docs: add more details to schema and cli

cmd/internal/store.go

@@ -16,8 +16,11 @@ import (
 func RegisterStoreCmd(ctx *context.Context, rootCmd *cobra.Command) {
 	subCmd := &cobra.Command{
 		Use:   "store",
-		Short: "Manage the data store.",
-		Args:  cobra.NoArgs,
+		Short: "Manage the data store for persisting key-value data.",
+		Long: "Manage the flow data store - a key-value store that persists data within and across executable runs. " +
+			"Values set outside executables persist globally, while values set within executables persist only for " +
+			"that execution scope.",
+		Args: cobra.NoArgs,
 	}
 	registerStoreSetCmd(ctx, subCmd)
 	registerStoreGetCmd(ctx, subCmd)
@@ -28,7 +31,7 @@ func RegisterStoreCmd(ctx *context.Context, rootCmd *cobra.Command) {
 func registerStoreSetCmd(ctx *context.Context, rootCmd *cobra.Command) {
 	subCmd := &cobra.Command{
 		Use:   "set KEY [VALUE]",
-		Short: "Set a key-value pair in the data store.",
+		Short: "Set a key-value pair in the store.",
 		Long:  dataStoreDescription + "This will overwrite any existing value for the key.",
 		Args:  cobra.MinimumNArgs(1),
 		Run: func(cmd *cobra.Command, args []string) {
@@ -89,7 +92,7 @@ func registerStoreGetCmd(ctx *context.Context, rootCmd *cobra.Command) {
 	subCmd := &cobra.Command{
 		Use:     "get KEY",
 		Aliases: []string{"view"},
-		Short:   "Get a value from the data store.",
+		Short:   "Get a value from the store by its key.",
 		Long:    dataStoreDescription + "This will retrieve the value for the given key.",
 		Args:    cobra.ExactArgs(1),
 		Run: func(cmd *cobra.Command, args []string) {
@@ -125,7 +128,7 @@ func registerStoreClearCmd(ctx *context.Context, rootCmd *cobra.Command) {
 	subCmd := &cobra.Command{
 		Use:     "clear",
 		Aliases: []string{"reset"},
-		Short:   "Clear the data store.",
+		Short:   "Clear data from the store. Use --full to remove all stored data.",
 		Long:    dataStoreDescription + "This will remove all keys and values from the data store.",
 		Args:    cobra.NoArgs,
 		Run: func(cmd *cobra.Command, args []string) {

docs/_sidebar.md

@@ -10,6 +10,7 @@
     - [Executables](guide/executable.md "Managing executables")
     - [Templating](guide/templating.md "Using flowfile templates")
     - [Managing state](guide/state.md "Managing executable state")
+    - [Conditional execution](guide/conditional.md "Conditional execution")
 
 - Reference
 

docs/cli/README.md

@@ -24,7 +24,7 @@ See github.com/jahvon/flow for more information.
 * [flow library](flow_library.md)	 - View and manage your library of workspaces and executables.
 * [flow logs](flow_logs.md)	 - List and view logs for previous flow executions.
 * [flow secret](flow_secret.md)	 - Manage flow secrets.
-* [flow store](flow_store.md)	 - Manage the data store.
+* [flow store](flow_store.md)	 - Manage the data store for persisting key-value data.
 * [flow sync](flow_sync.md)	 - Scan workspaces and update flow cache.
 * [flow template](flow_template.md)	 - Manage flowfile templates.
 * [flow workspace](flow_workspace.md)	 - Manage flow workspaces.

docs/cli/flow_store.md

@@ -1,6 +1,10 @@
 ## flow store
 
-Manage the data store.
+Manage the data store for persisting key-value data.
+
+### Synopsis
+
+Manage the flow data store - a key-value store that persists data within and across executable runs. Values set outside executables persist globally, while values set within executables persist only for that execution scope.
 
 ### Options
 
@@ -19,7 +23,7 @@ Manage the data store.
 ### SEE ALSO
 
 * [flow](flow.md)	 - flow is a command line interface designed to make managing and running development workflows easier.
-* [flow store clear](flow_store_clear.md)	 - Clear the data store.
-* [flow store get](flow_store_get.md)	 - Get a value from the data store.
-* [flow store set](flow_store_set.md)	 - Set a key-value pair in the data store.
+* [flow store clear](flow_store_clear.md)	 - Clear data from the store. Use --full to remove all stored data.
+* [flow store get](flow_store_get.md)	 - Get a value from the store by its key.
+* [flow store set](flow_store_set.md)	 - Set a key-value pair in the store.
 

docs/cli/flow_store_clear.md

@@ -1,6 +1,6 @@
 ## flow store clear
 
-Clear the data store.
+Clear data from the store. Use --full to remove all stored data.
 
 ### Synopsis
 
@@ -29,5 +29,5 @@ flow store clear [flags]
 
 ### SEE ALSO
 
-* [flow store](flow_store.md)	 - Manage the data store.
+* [flow store](flow_store.md)	 - Manage the data store for persisting key-value data.
 

docs/cli/flow_store_get.md

@@ -1,6 +1,6 @@
 ## flow store get
 
-Get a value from the data store.
+Get a value from the store by its key.
 
 ### Synopsis
 
@@ -28,5 +28,5 @@ flow store get KEY [flags]
 
 ### SEE ALSO
 
-* [flow store](flow_store.md)	 - Manage the data store.
+* [flow store](flow_store.md)	 - Manage the data store for persisting key-value data.
 

docs/cli/flow_store_set.md

@@ -1,6 +1,6 @@
 ## flow store set
 
-Set a key-value pair in the data store.
+Set a key-value pair in the store.
 
 ### Synopsis
 
@@ -28,5 +28,5 @@ flow store set KEY [VALUE] [flags]
 
 ### SEE ALSO
 
-* [flow store](flow_store.md)	 - Manage the data store.
+* [flow store](flow_store.md)	 - Manage the data store for persisting key-value data.
 

docs/guide/_sidebar.md

@@ -8,3 +8,6 @@
     - [Workspaces](workspace.md "Managing workspaces")
     - [Executables](executable.md "Managing executables")
     - [Templating](templating.md "Using flowfile templates")
+    - [Managing state](guide/state.md "Managing executable state")
+    - [Conditional execution](guide/conditional.md "Conditional execution")
+

docs/schemas/flowfile_schema.json

@@ -248,7 +248,7 @@
           "default": ""
         },
         "if": {
-          "description": "A condition to determine if the executable should be run.",
+          "description": "An expression that determines whether the executable should run, using the Expr language syntax. \nThe expression is evaluated at runtime and must resolve to a boolean value. \n\nThe expression has access to OS/architecture information (os, arch), environment variables (env), stored data \n(store), and context information (ctx) like workspace and paths. \n\nFor example, `os == \"darwin\"` will only run on macOS, `len(store[\"feature\"]) \u003e 0` will run if a value exists \nin the store, and `env[\"CI\"] == \"true\"` will run in CI environments. \nSee the [Expr documentation](https://expr-lang.org/docs/language-definition) for more information.\n",
           "type": "string",
           "default": ""
         },
@@ -481,7 +481,7 @@
           "default": ""
         },
         "if": {
-          "description": "A condition to determine if the executable should be run.",
+          "description": "An expression that determines whether the executable should run, using the Expr language syntax. \nThe expression is evaluated at runtime and must resolve to a boolean value. \n\nThe expression has access to OS/architecture information (os, arch), environment variables (env), stored data \n(store), and context information (ctx) like workspace and paths. \n\nFor example, `os == \"darwin\"` will only run on macOS, `len(store[\"feature\"]) \u003e 0` will run if a value exists \nin the store, and `env[\"CI\"] == \"true\"` will run in CI environments. \nSee the [Expr documentation](https://expr-lang.org/docs/language-definition) for more information.\n",
           "type": "string",
           "default": ""
         },

docs/types/flowfile.md

@@ -206,7 +206,7 @@ Configuration for a parallel executable.
 | ----- | ----------- | ---- | ------- | :--------: |
 | `args` | Arguments to pass to the executable. | `array` (`string`) | [] |  |
 | `cmd` | The command to execute. One of `cmd` or `ref` must be set.  | `string` |  |  |
-| `if` | A condition to determine if the executable should be run. | `string` |  |  |
+| `if` | An expression that determines whether the executable should run, using the Expr language syntax.  The expression is evaluated at runtime and must resolve to a boolean value.   The expression has access to OS/architecture information (os, arch), environment variables (env), stored data  (store), and context information (ctx) like workspace and paths.   For example, `os == "darwin"` will only run on macOS, `len(store["feature"]) > 0` will run if a value exists  in the store, and `env["CI"] == "true"` will run in CI environments.  See the [Expr documentation](https://expr-lang.org/docs/language-definition) for more information.  | `string` |  |  |
 | `ref` | A reference to another executable to run in serial. One of `cmd` or `ref` must be set.  | [ExecutableRef](#ExecutableRef) |  |  |
 | `retries` | The number of times to retry the executable if it fails. | `integer` | 0 |  |
 
@@ -353,7 +353,7 @@ Configuration for a serial executable.
 | ----- | ----------- | ---- | ------- | :--------: |
 | `args` | Arguments to pass to the executable. | `array` (`string`) | [] |  |
 | `cmd` | The command to execute. One of `cmd` or `ref` must be set.  | `string` |  |  |
-| `if` | A condition to determine if the executable should be run. | `string` |  |  |
+| `if` | An expression that determines whether the executable should run, using the Expr language syntax.  The expression is evaluated at runtime and must resolve to a boolean value.   The expression has access to OS/architecture information (os, arch), environment variables (env), stored data  (store), and context information (ctx) like workspace and paths.   For example, `os == "darwin"` will only run on macOS, `len(store["feature"]) > 0` will run if a value exists  in the store, and `env["CI"] == "true"` will run in CI environments.  See the [Expr documentation](https://expr-lang.org/docs/language-definition) for more information.  | `string` |  |  |
 | `ref` | A reference to another executable to run in serial. One of `cmd` or `ref` must be set.  | [ExecutableRef](#ExecutableRef) |  |  |
 | `retries` | The number of times to retry the executable if it fails. | `integer` | 0 |  |
 | `reviewRequired` | If set to true, the user will be prompted to review the output of the executable before continuing. | `boolean` | false |  |

types/executable/executable_schema.yaml

@@ -345,7 +345,16 @@ definitions:
         default: ""
       if:
         type: string
-        description: A condition to determine if the executable should be run.
+        description: |
+          An expression that determines whether the executable should run, using the Expr language syntax. 
+          The expression is evaluated at runtime and must resolve to a boolean value. 
+          
+          The expression has access to OS/architecture information (os, arch), environment variables (env), stored data 
+          (store), and context information (ctx) like workspace and paths. 
+          
+          For example, `os == "darwin"` will only run on macOS, `len(store["feature"]) > 0` will run if a value exists 
+          in the store, and `env["CI"] == "true"` will run in CI environments. 
+          See the [Expr documentation](https://expr-lang.org/docs/language-definition) for more information.
         default: ""
       args:
         type: array
@@ -501,7 +510,16 @@ definitions:
         default: ""
       if:
         type: string
-        description: A condition to determine if the executable should be run.
+        description: |
+          An expression that determines whether the executable should run, using the Expr language syntax. 
+          The expression is evaluated at runtime and must resolve to a boolean value. 
+
+          The expression has access to OS/architecture information (os, arch), environment variables (env), stored data 
+          (store), and context information (ctx) like workspace and paths. 
+
+          For example, `os == "darwin"` will only run on macOS, `len(store["feature"]) > 0` will run if a value exists 
+          in the store, and `env["CI"] == "true"` will run in CI environments. 
+          See the [Expr documentation](https://expr-lang.org/docs/language-definition) for more information.
         default: ""
       args:
         type: array