docs: switch to history router (#289)

jahvon · web-flow · commit c23f63d255ef · 2025-08-08T19:24:29.000-04:00
diff --git a/README.md b/README.md
@@ -8,8 +8,8 @@
 </p>
 
 <p align="center">
-    <b>flow</b> is your personal workflow hub - organize automation across all your projects with built-in secrets, templates, and cross-project composition.
-    Define workflows in YAML, discover them visually, and run them anywhere.
+    <b>flow</b> is your local-first developer platform - organize automation across all your projects with built-in secrets, templates, and cross-project workflows.
+    Define workflows in YAML, browse auto-generated documentation, and run them anywhere.
 </p>
 
 ---
@@ -83,14 +83,14 @@ flow browse
 
 **Complete documentation at [flowexec.io](https://flowexec.io)**
 
-- [Installation](https://flowexec.io/#/installation) - Multiple installation methods
-- [Quick Start](https://flowexec.io/#/quickstart) - Get up and running in 5 minutes
-- [Core Concepts](https://flowexec.io/#/guide/concepts) - Understand workspaces, executables, and vaults
-- [User Guides](https://flowexec.io/#/guide/README) - Comprehensive guides for all features
+- [Installation](https://flowexec.io/installation) - Multiple installation methods
+- [Quick Start](https://flowexec.io/quickstart) - Get up and running in 5 minutes
+- [Core Concepts](https://flowexec.io/guide/concepts) - Understand workspaces, executables, and vaults
+- [User Guides](https://flowexec.io/guide/README) - Comprehensive guides for all features
 
 ## Community
 
 - [Discord Community](https://discord.gg/CtByNKNMxM) - Get help and share workflows
 - [Issue Tracker](https://github.com/flowexec/flow/issues) - Report bugs and request features
 - [Examples Repository](https://github.com/flowexec/examples) - Real-world workflow patterns
-- [Contributing Guide](https://flowexec.io/#/development) - Help make flow better
+- [Contributing Guide](https://flowexec.io/development) - Help make flow better
diff --git a/desktop/src-tauri/src/types/generated/template.rs b/desktop/src-tauri/src/types/generated/template.rs
@@ -57,7 +57,7 @@ pub mod error {
 #[doc = "      \"type\": \"string\""]
 #[doc = "    },"]
 #[doc = "    \"if\": {"]
-#[doc = "      \"description\": \"An expression that determines whether the the artifact should be copied, using the Expr language syntax. \\nThe expression is evaluated at runtime and must resolve to a boolean value. If the condition is not met, \\nthe artifact will not be copied.\\n\\nThe expression has access to OS/architecture information (os, arch), environment variables (env), form input \\n(form), and context information (name, workspace, directory, etc.).\\n\\nSee the [flow documentation](https://flowexec.io/#/guide/templating) for more information.\\n\","]
+#[doc = "      \"description\": \"An expression that determines whether the the artifact should be copied, using the Expr language syntax. \\nThe expression is evaluated at runtime and must resolve to a boolean value. If the condition is not met, \\nthe artifact will not be copied.\\n\\nThe expression has access to OS/architecture information (os, arch), environment variables (env), form input \\n(form), and context information (name, workspace, directory, etc.).\\n\\nSee the [flow documentation](https://flowexec.io/guide/templating) for more information.\\n\","]
 #[doc = "      \"default\": \"\","]
 #[doc = "      \"type\": \"string\""]
 #[doc = "    },"]
@@ -85,7 +85,7 @@ pub struct Artifact {
     #[doc = "The name of the file to copy to. If not set, the file will be copied with the same name."]
     #[serde(rename = "dstName", default)]
     pub dst_name: ::std::string::String,
-    #[doc = "An expression that determines whether the the artifact should be copied, using the Expr language syntax. \nThe expression is evaluated at runtime and must resolve to a boolean value. If the condition is not met, \nthe artifact will not be copied.\n\nThe expression has access to OS/architecture information (os, arch), environment variables (env), form input \n(form), and context information (name, workspace, directory, etc.).\n\nSee the [flow documentation](https://flowexec.io/#/guide/templating) for more information.\n"]
+    #[doc = "An expression that determines whether the the artifact should be copied, using the Expr language syntax. \nThe expression is evaluated at runtime and must resolve to a boolean value. If the condition is not met, \nthe artifact will not be copied.\n\nThe expression has access to OS/architecture information (os, arch), environment variables (env), form input \n(form), and context information (name, workspace, directory, etc.).\n\nSee the [flow documentation](https://flowexec.io/guide/templating) for more information.\n"]
     #[serde(rename = "if", default)]
     pub if_: ::std::string::String,
     #[doc = "The directory to copy the file from. \nIf not set, the file will be copied from the directory of the template file.\n"]
@@ -460,7 +460,7 @@ impl Template {
 #[doc = "      \"type\": \"string\""]
 #[doc = "    },"]
 #[doc = "    \"if\": {"]
-#[doc = "      \"description\": \"An expression that determines whether the executable should be run, using the Expr language syntax. \\nThe expression is evaluated at runtime and must resolve to a boolean value. If the condition is not met, \\nthe executable will be skipped.\\n\\nThe expression has access to OS/architecture information (os, arch), environment variables (env), form input \\n(form), and context information (name, workspace, directory, etc.).\\n\\nSee the [flow documentation](https://flowexec.io/#/guide/templating) for more information.\\n\","]
+#[doc = "      \"description\": \"An expression that determines whether the executable should be run, using the Expr language syntax. \\nThe expression is evaluated at runtime and must resolve to a boolean value. If the condition is not met, \\nthe executable will be skipped.\\n\\nThe expression has access to OS/architecture information (os, arch), environment variables (env), form input \\n(form), and context information (name, workspace, directory, etc.).\\n\\nSee the [flow documentation](https://flowexec.io/guide/templating) for more information.\\n\","]
 #[doc = "      \"default\": \"\","]
 #[doc = "      \"type\": \"string\""]
 #[doc = "    },"]
@@ -481,7 +481,7 @@ pub struct TemplateRefConfig {
     #[doc = "The command to execute.\nOne of `cmd` or `ref` must be set.\n"]
     #[serde(default)]
     pub cmd: ::std::string::String,
-    #[doc = "An expression that determines whether the executable should be run, using the Expr language syntax. \nThe expression is evaluated at runtime and must resolve to a boolean value. If the condition is not met, \nthe executable will be skipped.\n\nThe expression has access to OS/architecture information (os, arch), environment variables (env), form input \n(form), and context information (name, workspace, directory, etc.).\n\nSee the [flow documentation](https://flowexec.io/#/guide/templating) for more information.\n"]
+    #[doc = "An expression that determines whether the executable should be run, using the Expr language syntax. \nThe expression is evaluated at runtime and must resolve to a boolean value. If the condition is not met, \nthe executable will be skipped.\n\nThe expression has access to OS/architecture information (os, arch), environment variables (env), form input \n(form), and context information (name, workspace, directory, etc.).\n\nSee the [flow documentation](https://flowexec.io/guide/templating) for more information.\n"]
     #[serde(rename = "if", default)]
     pub if_: ::std::string::String,
     #[doc = "A reference to another executable to run in serial.\nOne of `cmd` or `ref` must be set.\n"]
diff --git a/desktop/src/types/generated/template.ts b/desktop/src/types/generated/template.ts
@@ -62,7 +62,7 @@ export interface Artifact {
    * The expression has access to OS/architecture information (os, arch), environment variables (env), form input
    * (form), and context information (name, workspace, directory, etc.).
    *
-   * See the [flow documentation](https://flowexec.io/#/guide/templating) for more information.
+   * See the [flow documentation](https://flowexec.io/guide/templating) for more information.
    *
    */
   if?: string;
@@ -138,7 +138,7 @@ export interface TemplateRefConfig {
    * The expression has access to OS/architecture information (os, arch), environment variables (env), form input
    * (form), and context information (name, workspace, directory, etc.).
    *
-   * See the [flow documentation](https://flowexec.io/#/guide/templating) for more information.
+   * See the [flow documentation](https://flowexec.io/guide/templating) for more information.
    *
    */
   if?: string;
diff --git a/docs/README.md b/docs/README.md
@@ -7,8 +7,8 @@
   <a href="https://github.com/flowexec/flow"><img alt="GitHub Repo stars" src="https://img.shields.io/github/stars/flowexec/flow"></a>
 </p>
 
-flow is your personal **workflow hub** - organize automation across all your projects with built-in secrets, templates, 
-and cross-project composition. Go beyond task running to workflow management that scales with your development ecosystem.
+flow is a local-first developer platform - organize automation across all your projects with built-in secrets, templates, and cross-project workflows. 
+Go beyond task running to workflow management that scales with your development ecosystem.
 
 #### _Why flow?_ <!-- {docsify-ignore} -->
 
diff --git a/docs/_coverpage.md b/docs/_coverpage.md
@@ -2,7 +2,7 @@
 
 # flow
 
-> _Interactive CLI automation that flows with you._
+> _Local developer platform that flows with you._
 
 - Define your _executables_ in YAML
 - Browse and execute with ease
diff --git a/docs/cli/flow_browse.md b/docs/cli/flow_browse.md
@@ -10,7 +10,7 @@ Browse executables across workspaces.
   flow browse --list         # Simple list view of executables
   flow browse VERB [ID]      # Detailed view of specific executable
 
-See https://flowexec.io/#/types/flowfile#executableverb for more information on executable verbs and https://flowexec.io/#/types/flowfile#executableref for more information on executable references.
+See https://flowexec.io/types/flowfile?id=executableverb for more information on executable verbs and https://flowexec.io/types/flowfile?id=executableref for more information on executable references.
 
 ```
 flow browse [EXECUTABLE-REFERENCE] [flags]
diff --git a/docs/cli/flow_exec.md b/docs/cli/flow_exec.md
@@ -12,7 +12,7 @@ If the target executable accept arguments, they can be passed in the form of fla
 Flag arguments are specified with the format 'flag=value' and positional arguments are specified as values without any prefix.
 
 
-See https://flowexec.io/#/types/flowfile#executableverb for more information on executable verbs and https://flowexec.io/#/types/flowfile#executableref for more information on executable IDs.
+See https://flowexec.io/types/flowfile?id=executableverb for more information on executable verbs and https://flowexec.io/types/flowfile?id=executableref for more information on executable IDs.
 
 
 #### Examples
diff --git a/docs/guide/README.md b/docs/guide/README.md
@@ -24,7 +24,7 @@ Take your automation to the next level:
 - **[Templates & Code Generation](templating.md)** - Generate workflows and project scaffolding
 - **[Advanced Workflows](advanced.md)** - Complex automation with conditionals, state, and composition
 - **[Interactive UI](interactive.md)** - Customize and use the terminal interface
-- **[Integrations](integrations.md)** - Run flow in CI/CD and containerized environments
+- **[Integrations](integrations.md)** - Run flow in MCP clients, GitHub Actions, and containerized environments
 
 ## Other Resources
 
diff --git a/docs/guide/advanced.md b/docs/guide/advanced.md
@@ -371,20 +371,24 @@ executables:
       cmd: ./deploy.sh
 ```
 
+> [!NOTE]
+> In serial and parallel executables, `params` and `args` that are defined at the parent level will apply to all 
+> child executables. Argument from the parent -> child executable should use matching `EnvKey` to ensure proper resolution.
+
 **Resolution example:**
 ```shell
 # Shell environment
-export ENVIRONMENT=development
 export API_KEY=shell-key
 export VERBOSE=true
+export ENVIRONMENT=development
 
 # Command execution
 flow deploy app verbose=false --param ENVIRONMENT=production
 
 # Final environment variables:
-# ENVIRONMENT=production    (--param override wins)
 # API_KEY=<secret-value>    (params wins over shell)
-# VERBOSE=false             (args wins over shell)
+# VERBOSE=false             (args wins over shell and params)
+# ENVIRONMENT=production    (--param override wins over all)
 ```
 
 ### Environment Variable Expansion <!-- {docsify-ignore} -->
diff --git a/docs/index.html b/docs/index.html
@@ -40,12 +40,14 @@
       subMaxLevel: 3,
       coverpage: true,
       onlyCover: false,
-      nameLink: '#/README',
+      nameLink: 'README',
       auto2top: true,
+      routerMode: 'history',
       alias: {
         '/releases/(.*)': 'https://github.com/flowexec/flow/releases/$1',
         '/schemas/(.*)': 'https://github.com/flowexec/flow/tree/main/schemas/$1',
         '/issues/(.*)': 'https://github.com/flowexec/flow/issues/$1',
+        '/(.*)/_sidebar.md': '$1/_sidebar.md',
       },
       copyCode: {
         buttonText: 'Copy',
diff --git a/docs/schemas/template_schema.json b/docs/schemas/template_schema.json
@@ -31,7 +31,7 @@
           "default": ""
         },
         "if": {
-          "description": "An expression that determines whether the the artifact should be copied, using the Expr language syntax. \nThe expression is evaluated at runtime and must resolve to a boolean value. If the condition is not met, \nthe artifact will not be copied.\n\nThe expression has access to OS/architecture information (os, arch), environment variables (env), form input \n(form), and context information (name, workspace, directory, etc.).\n\nSee the [flow documentation](https://flowexec.io/#/guide/templating) for more information.\n",
+          "description": "An expression that determines whether the the artifact should be copied, using the Expr language syntax. \nThe expression is evaluated at runtime and must resolve to a boolean value. If the condition is not met, \nthe artifact will not be copied.\n\nThe expression has access to OS/architecture information (os, arch), environment variables (env), form input \n(form), and context information (name, workspace, directory, etc.).\n\nSee the [flow documentation](https://flowexec.io/guide/templating) for more information.\n",
           "type": "string",
           "default": ""
         },
@@ -122,7 +122,7 @@
           "default": ""
         },
         "if": {
-          "description": "An expression that determines whether the executable should be run, using the Expr language syntax. \nThe expression is evaluated at runtime and must resolve to a boolean value. If the condition is not met, \nthe executable will be skipped.\n\nThe expression has access to OS/architecture information (os, arch), environment variables (env), form input \n(form), and context information (name, workspace, directory, etc.).\n\nSee the [flow documentation](https://flowexec.io/#/guide/templating) for more information.\n",
+          "description": "An expression that determines whether the executable should be run, using the Expr language syntax. \nThe expression is evaluated at runtime and must resolve to a boolean value. If the condition is not met, \nthe executable will be skipped.\n\nThe expression has access to OS/architecture information (os, arch), environment variables (env), form input \n(form), and context information (name, workspace, directory, etc.).\n\nSee the [flow documentation](https://flowexec.io/guide/templating) for more information.\n",
           "type": "string",
           "default": ""
         },
diff --git a/docs/types/template.md b/docs/types/template.md
@@ -39,7 +39,7 @@ Go templating from form data is supported in all fields.
 | `asTemplate` | If true, the artifact will be copied as a template file. The file will be rendered using Go templating from  the form data. [Sprig functions](https://masterminds.github.io/sprig/) are available for use in the template.  | `boolean` | false |  |
 | `dstDir` | The directory to copy the file to. If not set, the file will be copied to the root of the flow file directory. The directory will be created if it does not exist.  | `string` |  |  |
 | `dstName` | The name of the file to copy to. If not set, the file will be copied with the same name. | `string` |  |  |
-| `if` | An expression that determines whether the the artifact should be copied, using the Expr language syntax.  The expression is evaluated at runtime and must resolve to a boolean value. If the condition is not met,  the artifact will not be copied.  The expression has access to OS/architecture information (os, arch), environment variables (env), form input  (form), and context information (name, workspace, directory, etc.).  See the [flow documentation](https://flowexec.io/#/guide/templating) for more information.  | `string` |  |  |
+| `if` | An expression that determines whether the the artifact should be copied, using the Expr language syntax.  The expression is evaluated at runtime and must resolve to a boolean value. If the condition is not met,  the artifact will not be copied.  The expression has access to OS/architecture information (os, arch), environment variables (env), form input  (form), and context information (name, workspace, directory, etc.).  See the [flow documentation](https://flowexec.io/guide/templating) for more information.  | `string` |  |  |
 | `srcDir` | The directory to copy the file from.  If not set, the file will be copied from the directory of the template file.  | `string` |  |  |
 | `srcName` | The name of the file to copy. | `string` | <no value> |  |
 
@@ -94,7 +94,7 @@ Configuration for a template 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` | An expression that determines whether the executable should be run, using the Expr language syntax.  The expression is evaluated at runtime and must resolve to a boolean value. If the condition is not met,  the executable will be skipped.  The expression has access to OS/architecture information (os, arch), environment variables (env), form input  (form), and context information (name, workspace, directory, etc.).  See the [flow documentation](https://flowexec.io/#/guide/templating) for more information.  | `string` |  |  |
+| `if` | An expression that determines whether the executable should be run, using the Expr language syntax.  The expression is evaluated at runtime and must resolve to a boolean value. If the condition is not met,  the executable will be skipped.  The expression has access to OS/architecture information (os, arch), environment variables (env), form input  (form), and context information (name, workspace, directory, etc.).  See the [flow documentation](https://flowexec.io/guide/templating) for more information.  | `string` |  |  |
 | `ref` | A reference to another executable to run in serial. One of `cmd` or `ref` must be set.  | [ExecutableRef](#ExecutableRef) |  |  |
 
 
diff --git a/internal/io/output.go b/internal/io/output.go
@@ -5,11 +5,9 @@ import (
 	"strings"
 )
 
-func TypesDocsURL(docID, anchor string) string {
-	if anchor != "" {
-		anchor = "#" + anchor
-	} else {
-		anchor = "?id=" + strings.ToLower(anchor)
+func TypesDocsURL(docType, docId string) string {
+	if docId != "" {
+		docId = "?id=" + strings.ToLower(docId)
 	}
-	return fmt.Sprintf("https://flowexec.io/#/types/%s%s", docID, anchor)
+	return fmt.Sprintf("https://flowexec.io/types/%s%s", docType, docId)
 }
diff --git a/internal/mcp/prompts.go b/internal/mcp/prompts.go
@@ -338,7 +338,7 @@ Please provide a clear explanation that:
 
 Make the explanation conversational and practical, focusing on helping me understand not just what something is, 
 but why it's useful and how to use it effectively. You should fetch any additional information you need directly
-from the Flow documentation at https://flowexec.io/#/README
+from the Flow documentation at https://flowexec.io/README
 
 Do not add confusion by mentioning other tools or platforms unless directly relevant to the explanation. Clearly state
 when you do not have enough information to provide a complete answer, and suggest where I can find more details.`
diff --git a/internal/mcp/resources/template_schema.json b/internal/mcp/resources/template_schema.json
diff --git a/types/executable/template.gen.go b/types/executable/template.gen.go
diff --git a/types/executable/template_schema.yaml b/types/executable/template_schema.yaml

Original file line number	Diff line number	Diff line change
`@@ -62,7 +62,7 @@ export interface Artifact {`
`62`	`62`	`* The expression has access to OS/architecture information (os, arch), environment variables (env), form input`
`63`	`63`	`* (form), and context information (name, workspace, directory, etc.).`
`64`	`64`	`*`
`65`		`- * See the [flow documentation](https://flowexec.io/#/guide/templating) for more information.`
	`65`	`+ * See the [flow documentation](https://flowexec.io/guide/templating) for more information.`
`66`	`66`	`*`
`67`	`67`	`*/`
`68`	`68`	`if?: string;`
`@@ -138,7 +138,7 @@ export interface TemplateRefConfig {`
`138`	`138`	`* The expression has access to OS/architecture information (os, arch), environment variables (env), form input`
`139`	`139`	`* (form), and context information (name, workspace, directory, etc.).`
`140`	`140`	`*`
`141`		`- * See the [flow documentation](https://flowexec.io/#/guide/templating) for more information.`
	`141`	`+ * See the [flow documentation](https://flowexec.io/guide/templating) for more information.`
`142`	`142`	`*`
`143`	`143`	`*/`
`144`	`144`	`if?: string;`