@synergenius/flow-weaver 0.33.2 → 0.44.0

package/docs/reference/cli-reference.md

@@ -1,7 +1,7 @@
 ---
 name: CLI Reference
 description: Complete reference for all Flow Weaver CLI commands, flags, and options
-keywords: [cli, commands, compile, validate, strip, run, watch, dev, serve, export, diagram, diff, doctor, init, migrate, marketplace, plugin, grammar, openapi, pattern, create, templates, context, modify, implement, status]
+keywords: [cli, commands, compile, validate, strip, run, watch, dev, serve, export, diagram, diff, doctor, init, migrate, marketplace, grammar, openapi, agents, create, templates, context, modify, implement, status]
 ---
 
 # CLI Reference
@@ -12,37 +12,39 @@ Complete reference for all `fw` CLI commands.
 
 ## Quick Reference
 
+<!-- AUTO:START cli_quick_reference -->
 | Command | Description |
 |---------|-------------|
 | `compile` | Compile workflow files to TypeScript |
-| `validate` | Validate without compiling |
-| `strip` | Remove generated code from compiled files |
-| `describe` | Output workflow structure (JSON/text/mermaid) |
-| `run` | Execute a workflow directly |
-| `watch` | Recompile on file changes |
-| `dev` | Watch + compile + run in one command |
-| `serve` | HTTP server exposing workflows as endpoints |
-| `diagram` | Generate SVG diagram |
-| `diff` | Semantic diff between two workflows |
-| `doctor` | Check project environment |
-| `init` | Create a new project |
-| `create` | Create workflows/nodes from templates |
+| `strip` | Remove generated code from compiled workflow files |
+| `describe` | Output workflow structure in LLM-friendly formats (JSON, text, mermaid) |
+| `diagram` | Draw a workflow: its spine as an SVG, or text for a terminal |
+| `artifact` | Hand a workflow to a person: the brief as a page or a PDF, or the spine as an SVG |
+| `diff` | Compare two workflow files semantically |
+| `validate` | Validate workflow files without compiling |
+| `doctor` | Check project environment and configuration for flow-weaver compatibility |
+| `agents` | The agent profiles that answer agent gates in this project, and whether each is ready |
+| `init` | Create a new flow-weaver project |
+| `watch` | Watch workflow files and recompile on changes |
+| `dev` | Watch, compile, and run workflow on changes |
+| `mcp-server` | Start MCP server for Claude Code integration |
+| `mcp-setup` | Configure MCP server for AI coding tools (Claude, Cursor, VS Code, Windsurf, Codex, OpenClaw) |
+| `create` | Create workflows or nodes from templates |
+| `modify` | Modify workflow structure |
 | `templates` | List available templates |
-| `pattern` | Work with reusable patterns |
-| `export` | Export as serverless function |
-| `openapi` | Generate OpenAPI specification |
-| `migrate` | Migrate to current syntax |
-| `grammar` | Output annotation grammar |
-| `market` | Marketplace packages |
-| `plugin` | External plugins |
-| `modify` | Add/remove/rename nodes, connections, positions, and labels |
-| `implement` | Replace stub node with function skeleton |
-| `status` | Report implementation progress |
-| `context` | Generate LLM context bundle |
+| `grammar` | Output JSDoc annotation grammar (@input, @output, @connect, @node, @scope) as HTML railroad diagrams or EBNF text |
+| `run` | Execute a workflow file directly |
+| `serve` | Serve the workflows as HTTP endpoints. Gated runs pause, resume and stream over the same API |
+| `console` | Open the local operator console: workflows as processes, issues, code, live runs and gates |
+| `export` | Export a workflow to a target provided by an installed pack |
+| `openapi` | Generate OpenAPI specification from workflows |
+| `migrate` | Migrate workflow files to current syntax via parse → regenerate round-trip |
+| `status` | Report implementation progress for stub workflows |
+| `implement` | Replace a stub node with a real function skeleton |
 | `docs` | Browse reference documentation |
-| `ui` | Send commands to the editor |
-| `listen` | Stream editor events |
-| `mcp-server` | Start MCP server |
+| `context` | Generate LLM context bundle from documentation and grammar |
+| `market` | Discover, install, and publish marketplace packages |
+<!-- AUTO:END cli_quick_reference -->
 
 ---
 
@@ -63,28 +65,20 @@ fw compile <input> [options]
 | `-s, --source-map` | Generate source maps | `false` |
 | `--verbose` | Verbose output | `false` |
 | `--dry-run` | Preview without writing | `false` |
-| `-w, --workflow-name <name>` | Specific workflow name | all |
+| `-w, --workflow <name>` | Specific workflow name | all |
 | `-f, --format <format>` | Module format: `esm`, `cjs`, `auto` | `auto` |
 | `--strict` | Type coercion warnings become errors | `false` |
 | `--clean` | Omit redundant @param/@returns | `false` |
-| `--target <target>` | `typescript` or `inngest` | `typescript` |
-| `--cron <schedule>` | Cron schedule (Inngest only) | — |
-| `--serve` | Generate serve() handler | `false` |
-| `--framework <name>` | `next`, `express`, `hono`, `fastify`, `remix` | — |
-| `--typed-events` | Generate Zod event schemas | `false` |
-| `--retries <n>` | Retries per function (Inngest only) | — |
-| `--timeout <duration>` | Function timeout (e.g. `"30m"`) | — |
 
 **Examples:**
 ```bash
 fw compile my-workflow.ts
 fw compile '**/*.ts' -o .output
 fw compile my-workflow.ts --format cjs
-fw compile workflow.ts --target inngest --serve --framework next
 fw compile workflow.ts --production --clean
 ```
 
-> See also: [Compilation](compilation) for details on targets and Inngest integration.
+> See also: [Compilation](compilation.md) for what the compiler installs and how markers work. Exporting to another platform is `fw export`, through a target an installed pack provides.
 
 ---
 
@@ -101,7 +95,7 @@ fw validate <input> [options]
 | `--verbose` | Verbose output | `false` |
 | `-q, --quiet` | Suppress warnings | `false` |
 | `--json` | Output as JSON | `false` |
-| `-w, --workflow-name <name>` | Specific workflow name | all |
+| `-w, --workflow <name>` | Specific workflow name | all |
 | `--strict` | Type coercion warnings become errors | `false` |
 
 **Examples:**
@@ -111,6 +105,59 @@ fw validate '**/*.ts' --verbose
 fw validate workflow.ts --json --strict
 ```
 
+#### JSON output contract
+
+With `--json`, the command prints a single JSON object to stdout and sets a
+non-zero exit code when any file has errors. This is the stable machine-readable
+contract for editor integrations and other tooling.
+
+```jsonc
+{
+  "valid": false,           // true when totalErrors === 0
+  "totalFiles": 1,
+  "validFiles": 0,
+  "totalErrors": 2,
+  "totalWarnings": 1,
+  "results": [
+    {
+      "file": "/abs/path/to/workflow.ts",  // absolute path
+      "valid": false,
+      "errors": [
+        {
+          "message": "Node \"Add\" has unconnected required input port \"x\".",
+          "severity": "error",
+          "code": "MISSING_REQUIRED_INPUT",   // optional, stable rule id
+          "nodeId": "Add",                     // optional, offending node
+          "location": {                        // optional, see below
+            "file": "/abs/path/to/workflow.ts",
+            "line": 33,                        // 1-based
+            "column": 0                        // 0-based
+          },
+          "docUrl": "https://..."              // optional, when available
+        }
+      ],
+      "warnings": [ /* same item shape, severity: "warning" */ ]
+    }
+  ]
+}
+```
+
+Notes for consumers:
+
+- **`location` is optional.** It is present when the validator can resolve the
+  offending annotation to a source position, and **omitted entirely** (never
+  `null`) otherwise. Test for it with an `in` check or a truthiness guard, e.g.
+  `if (finding.location) { ... }`.
+- **`line` is 1-based, `column` is 0-based.** Editors expecting 0-based lines
+  (such as the Language Server Protocol) must subtract one from `line`.
+- **Paths are absolute.** Both the top-level `results[].file` and
+  `location.file` are absolute; resolve against the workspace root as needed.
+- **`code` is a stable rule identifier** (e.g. `MISSING_REQUIRED_INPUT`) suitable
+  for filtering or suppression. `message` is human-facing and may change wording.
+
+Parse-level failures (malformed source that never reaches AST construction)
+appear as findings without `location` or `code`.
+
 ---
 
 ### strip
@@ -146,10 +193,10 @@ fw describe <input> [options]
 
 | Flag | Description | Default |
 |------|-------------|---------|
-| `-f, --format <format>` | `json`, `text`, `mermaid`, `paths` | `json` |
+| `-f, --format <format>` | `json`, `text`, `mermaid`, `paths`, `ascii`, `ascii-compact` | `json` |
 | `-n, --node <id>` | Focus on a specific node | — |
 | `--compile` | Also update runtime markers | `false` |
-| `-w, --workflow-name <name>` | Specific workflow name | all |
+| `-w, --workflow <name>` | Specific workflow name | all |
 
 **Examples:**
 ```bash
@@ -176,13 +223,12 @@ fw run <input> [options]
 | `--params-file <path>` | Path to JSON file with parameters | — |
 | `-p, --production` | No trace events | `false` |
 | `-t, --trace` | Include execution trace events | `false` |
+| `-s, --stream` | Stream trace events in real time | `false` |
 | `--json` | Output result as JSON | `false` |
 | `--timeout <ms>` | Execution timeout in milliseconds | — |
-| `--mocks <json>` | Mock config for built-in nodes as JSON | — |
+| `--mocks <json>` | Mock config as JSON: `gates` (answers by node id), `events`, `agents`, `invocations`, `fast` | — |
 | `--mocks-file <path>` | Path to JSON file with mock config | — |
 | `-d, --debug` | Start in step-through debug mode | `false` |
-| `--checkpoint` | Enable checkpointing to disk after each node | `false` |
-| `--resume [file]` | Resume from a checkpoint file (auto-detects latest if no file given) | — |
 | `-b, --breakpoint <nodeIds...>` | Set initial breakpoints (repeatable) | — |
 
 **Examples:**
@@ -192,12 +238,19 @@ fw run workflow.ts --params-file input.json --trace
 fw run workflow.ts --mocks '{"fast": true, "events": {"app/approved": {"status": "ok"}}}'
 fw run workflow.ts --timeout 30000 --json
 fw run workflow.ts --debug
-fw run workflow.ts --checkpoint
-fw run workflow.ts --resume
 fw run workflow.ts --debug --breakpoint processData --breakpoint validate
 ```
 
-> See also: [Built-in Nodes](built-in-nodes) for mock configuration details, [Debugging](debugging) for debug REPL commands and checkpoint details.
+> See also: [Built-in Nodes](built-in-nodes.md) for mock configuration details and [Debugging](debugging.md) for live debug REPL commands.
+
+**Gated workflows are refused.** A workflow containing `waitForEvent`, `waitForAgent`, or any `@durableGate` node yields a continuation instead of finishing, and `fw run` is not a coordinator that can persist one:
+
+```
+✗ Workflow execution failed: a workflow graph with durable gates requires
+  coordinator-verified whole-bundle identity before execution
+```
+
+Drive such a workflow with the `fw_run` / `fw_resume` MCP tools (see [mcp-server](#mcp-server)) or from code via `createLocalCoordinator` (or `executeWorkflow`) from `@synergenius/flow-weaver/coordinator`. `--mocks` does not resolve a gate. See [Durable Gates](durable-gates.md).
 
 ---
 
@@ -217,7 +270,7 @@ fw watch <input> [options]
 | `-p, --production` | No debug events | `false` |
 | `-s, --source-map` | Generate source maps | `false` |
 | `--verbose` | Verbose output | `false` |
-| `-w, --workflow-name <name>` | Specific workflow name | all |
+| `-w, --workflow <name>` | Specific workflow name | all |
 | `-f, --format <format>` | `esm`, `cjs`, `auto` | `auto` |
 
 **Examples:**
@@ -246,22 +299,21 @@ fw dev <input> [options]
 | `--clean` | Omit redundant annotations | `false` |
 | `--once` | Run once then exit | `false` |
 | `--json` | Output result as JSON | `false` |
-| `--target <target>` | `typescript` or `inngest` | `typescript` |
-| `--framework <framework>` | Framework for serve handler (Inngest only) | `express` |
-| `--port <port>` | Port for dev server (Inngest only) | `3000` |
+| `--mocks <json>` | Mock config as JSON: `gates` (answers by node id), `events`, `agents`, `invocations`, `fast` | — |
+| `--mocks-file <path>` | Path to JSON file with mock config for built-in nodes | — |
 
 **Examples:**
 ```bash
 fw dev workflow.ts --params '{"input": "hello"}'
 fw dev workflow.ts --once --json
-fw dev workflow.ts --target inngest --port 8080
+fw dev workflow.ts --mocks '{"fast": true}'
 ```
 
 ---
 
 ### serve
 
-Start an HTTP server exposing workflows as REST endpoints. Supports hot reload, CORS, and Swagger UI.
+Serve the workflows as HTTP endpoints: the routes they declare with `@http`, a run resource for every workflow, and the run endpoints. Gated runs pause, resume and stream over the same API. Supports hot reload, CORS, and Swagger UI.
 
 ```bash
 fw serve [directory] [options]
@@ -270,35 +322,78 @@ fw serve [directory] [options]
 | Flag | Description | Default |
 |------|-------------|---------|
 | `-p, --port <port>` | Server port | `3000` |
-| `-H, --host <host>` | Server host | `0.0.0.0` |
-| `--no-watch` | Disable file watching | watch enabled |
-| `--production` | No trace events | `false` |
-| `--precompile` | Precompile all workflows on startup | `false` |
-| `--cors <origin>` | CORS origin | `*` |
+| `-H, --host <host>` | Server host. Beyond loopback needs `--token` or `--insecure` | `127.0.0.1` |
+| `--token <token>` | Bearer token every request must carry (also `FW_SERVE_TOKEN`) | — |
+| `--no-agents` | Do not answer agent gates from `.flowweaver/agents.yaml` | agents on |
+| `--trace` | Keep a step trace for every run and stream it on `/runs/:id/events` | `false` |
+| `--dev` | Error stacks in responses, and mocks accepted when starting a run | `false` |
+| `--insecure` | Listen beyond loopback without a token | `false` |
+| `--no-watch` | Disable file watching for hot reload | watch enabled |
+| `--cors <origin>` | Send CORS headers for this origin | off |
 | `--swagger` | Enable Swagger UI at `/docs` | `false` |
+| `--production` | Deprecated: the same as leaving `--trace` off | `false` |
 
 **Examples:**
 ```bash
 fw serve ./workflows
 fw serve ./workflows --port 8080 --swagger
-fw serve --production --precompile --no-watch
+fw serve --host 0.0.0.0 --token "$FW_SERVE_TOKEN"
+fw serve --trace --dev --no-watch
 ```
 
-> See also: [Deployment](deployment) for production serving and export.
+> See also: [Deployment](deployment.md) for the routes, the run resource, callbacks and embedding the API.
 
 ---
 
-### listen
+### console
 
-Connect to the editor and stream integration events as JSON lines.
+Open the local operator console: every workflow in the project as a process, its validation issues on the steps that carry them, the code behind each step, and runs live — including answering a durable gate from the page.
 
 ```bash
-fw listen [options]
+fw console [directory] [options]
 ```
 
 | Flag | Description | Default |
 |------|-------------|---------|
-| `-s, --server <url>` | Editor URL | `http://localhost:9000` |
+| `-p, --port <port>` | Port | `4311` |
+| `-H, --host <host>` | Host to bind. A host beyond loopback is refused without `--insecure` | `127.0.0.1` |
+| `--insecure` | Listen beyond loopback. The console has no authentication, so anyone who reaches the port can run your workflows | `false` |
+| `--open` | Open the browser once listening | `false` |
+| `--no-watch` | Do not reload when project files change | watch enabled |
+
+**Examples:**
+```bash
+fw console
+fw console ./workflows --open
+```
+
+Runs started here stream real execution events, so the process lights up step by step and a paused gate offers a form built from the port's TypeScript type. Runs live in the same store as `fw_run` and `fw_resume` (the project's `.fw/runs`, or `FW_RUNS_DIR`): a gate reached in the console can be answered by an assistant over MCP and the other way round, a run waiting at a gate survives a restart of the console, and effects get receipts. The step trace is kept beside the record, so a run opened later still shows what each step did; a segment resumed over MCP keeps no trace, and the console says so rather than guessing. The console binds to localhost and re-reads a file as you save it.
+
+> See also: [Durable Gates](durable-gates.md) for what pauses a run and how it resumes.
+
+---
+
+### agents
+
+The agent profiles that answer agent gates in this project, and whether each is ready. A profile is ready when its provider is configured and the environment variable naming its key is set; the listing says which of those is missing rather than failing at the gate.
+
+```bash
+fw agents [directory] [options]
+```
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--init` | Write the starter `.flowweaver/agents.yaml` | `false` |
+| `--force` | With `--init`: replace an existing file | `false` |
+| `--json` | Output as JSON | `false` |
+
+**Examples:**
+```bash
+fw agents
+fw agents --init
+```
+
+> See also: [Durable Gates](durable-gates.md) for the `agents.yaml` format and how a profile is matched to a gate.
 
 ---
 
@@ -306,7 +401,7 @@ fw listen [options]
 
 ### diagram
 
-Generate SVG diagram of a workflow.
+Draw a workflow. `svg` is the spine the console shows — steps in run order, the control flow as lanes beside them (failure arms, loop bodies, steps read on demand) — as a vector image for a slide or a document. The text formats are for a terminal or a chat.
 
 ```bash
 fw diagram <input> [options]
@@ -315,17 +410,43 @@ fw diagram <input> [options]
 | Flag | Description | Default |
 |------|-------------|---------|
 | `-t, --theme <theme>` | `dark` or `light` | `dark` |
-| `-w, --width <pixels>` | SVG width in pixels | auto |
-| `-p, --padding <pixels>` | Canvas padding in pixels | auto |
-| `--no-port-labels` | Hide data type labels on ports | shown |
-| `--workflow-name <name>` | Specific workflow | all |
-| `-o, --output <file>` | Write SVG to file | stdout |
+| `-w, --workflow <name>` | Specific workflow | first |
+| `-f, --format <format>` | `svg` (the spine as a vector image), `ascii`, `ascii-compact`, `text` | `svg` |
+| `-o, --output <file>` | Write output to file | stdout |
 
 **Examples:**
 ```bash
 fw diagram workflow.ts
 fw diagram workflow.ts --theme light -o diagram.svg
-fw diagram workflow.ts --no-port-labels --width 1200
+fw diagram workflow.ts --format ascii-compact
+```
+
+---
+
+### artifact
+
+Hand a workflow to a person who will not open the code.
+
+```bash
+fw artifact <input> [options]
+```
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `-k, --kind <kind>` | `brief` — the brief as a page: the graph first, large, each step clickable for what it does, what it reads and where its failure goes, then what goes in, what comes out and where a person or an agent is needed; `pdf` — a one-page overview (the graph beside what goes in, what comes out, the pauses and the failure arms) followed by every step in detail; `svg` — the spine as a vector image | `brief` |
+| `-t, --theme <theme>` | `light` or `dark` | `light` |
+| `-w, --workflow <name>` | Specific workflow | first |
+| `--subtitle <text>` | Shown under the title | the folder name |
+| `--browser <path>` | Browser to print the PDF with | the one found, or `FW_BROWSER` |
+| `-o, --output <file>` | Write to a file; the brief and the SVG go to stdout otherwise | a PDF is written beside the workflow |
+
+The PDF is printed by a Chromium-family browser already on the machine — Chrome, Chromium, Edge or Brave, found where the platform installs them, or named with `FW_BROWSER`. Without one the command says so; the HTML brief prints to PDF from any browser's print dialog. `fw console`'s Share menu produces the same three files.
+
+**Examples:**
+```bash
+fw artifact workflow.ts -o workflow.brief.html
+fw artifact workflow.ts --kind pdf
+fw artifact workflow.ts --kind svg --theme dark -o workflow.svg
 ```
 
 ---
@@ -365,7 +486,7 @@ fw diff <file1> <file2> [options]
 | Flag | Description | Default |
 |------|-------------|---------|
 | `-f, --format <format>` | `text`, `json`, `compact` | `text` |
-| `-w, --workflow-name <name>` | Specific workflow | all |
+| `-w, --workflow <name>` | Specific workflow | all |
 | `--exit-zero` | Exit 0 even with differences | `false` |
 
 **Examples:**
@@ -381,6 +502,8 @@ fw diff old.ts new.ts --exit-zero  # for CI pipelines
 
 Check project environment and configuration for Flow Weaver compatibility.
 
+Also reports **Running services**: the `fw` processes alive on this machine (`mcp-server`, `serve`, `console`), each with its install, its client and its last activity, from the records they keep in `~/.fw/services/`. An MCP server running from a different install than the one checked is a warning. `fw_doctor` returns the same under `services`.
+
 ```bash
 fw doctor [options]
 ```
@@ -404,9 +527,14 @@ fw init [directory] [options]
 | Flag | Description | Default |
 |------|-------------|---------|
 | `-n, --name <name>` | Project name | directory name |
-| `-t, --template <template>` | Workflow template | `simple` |
+| `-t, --template <template>` | Workflow template | `sequential` |
 | `-f, --format <format>` | `esm` or `cjs` | `esm` |
 | `-y, --yes` | Skip prompts, use defaults | `false` |
+| `--preset <persona>` | User preset: `nocode`, `vibecoder`, `lowcode`, `expert` | — |
+| `--use-case <category>` | Use case: `data`, `ai`, `api`, `automation`, `minimal` | — |
+| `--mcp` | Auto-configure MCP for AI editors after scaffolding | — |
+| `--no-mcp` | Skip the MCP setup prompt | — |
+| `--no-agent` | Skip the post-init agent launch prompt | — |
 | `--install` | Run npm install | — |
 | `--no-install` | Skip npm install | — |
 | `--git` | Initialize git repo | — |
@@ -464,7 +592,7 @@ fw create node <name> <file> [options]
 | Flag | Description | Default |
 |------|-------------|---------|
 | `-l, --line <number>` | Insert at specific line | end of file |
-| `-t, --template <template>` | Node template | `processor` |
+| `-t, --template <template>` | Node template | `transformer` |
 | `-p, --preview` | Preview without writing | `false` |
 | `--strategy <strategy>` | Template strategy (e.g. `mock`, `callback`, `webhook`) | — |
 | `--config <json>` | Additional configuration | — |
@@ -480,7 +608,7 @@ fw create node checker my-workflow.ts --template validator
 
 ### modify
 
-Modify workflow structure programmatically. Parses the file, applies the operation, and regenerates the JSDoc annotations in place. Useful for scripting, CI pipelines, and the genesis self-evolution system.
+Modify workflow structure programmatically. Parses the file, applies the operation, and regenerates the JSDoc annotations in place. Useful for scripting and CI pipelines.
 
 #### modify addNode
 
@@ -488,7 +616,7 @@ Modify workflow structure programmatically. Parses the file, applies the operati
 fw modify addNode --file <path> --nodeId <id> --nodeType <type>
 ```
 
-Adds a new node instance to the workflow. Auto-positions to the right of the rightmost existing node. Warns if the node type isn't defined in the file.
+Adds a new node instance to the workflow. Warns if the node type isn't defined in the file.
 
 #### modify removeNode
 
@@ -522,14 +650,6 @@ fw modify renameNode --file <path> --oldId <id> --newId <id>
 
 Renames a node instance and updates all connections that reference it.
 
-#### modify setPosition
-
-```bash
-fw modify setPosition --file <path> --nodeId <id> --x <number> --y <number>
-```
-
-Sets the canvas position of a node instance.
-
 #### modify setLabel
 
 ```bash
@@ -546,7 +666,6 @@ fw modify addConnection --file workflow.ts --from Start.data --to validator.inpu
 fw modify removeNode --file workflow.ts --nodeId oldStep
 fw modify removeConnection --file workflow.ts --from a.output --to b.input
 fw modify renameNode --file workflow.ts --oldId step1 --newId validateStep
-fw modify setPosition --file workflow.ts --nodeId step1 --x 200 --y 100
 fw modify setLabel --file workflow.ts --nodeId step1 --label "Validate Input"
 ```
 
@@ -605,64 +724,7 @@ fw templates [options]
 |------|-------------|---------|
 | `--json` | Output as JSON | `false` |
 
-> See also: [Scaffold](scaffold) for template details.
-
----
-
-## Patterns
-
-### pattern list
-
-List patterns in a file or directory.
-
-```bash
-fw pattern list <path> [options]
-```
-
-| Flag | Description | Default |
-|------|-------------|---------|
-| `--json` | Output as JSON | `false` |
-
----
-
-### pattern apply
-
-Apply a reusable pattern to a workflow file.
-
-```bash
-fw pattern apply <pattern-file> <target-file> [options]
-```
-
-| Flag | Description | Default |
-|------|-------------|---------|
-| `-p, --preview` | Preview without writing | `false` |
-| `--prefix <prefix>` | Prefix for node IDs (conflict avoidance) | — |
-| `-n, --name <name>` | Specific pattern name | — |
-
----
-
-### pattern extract
-
-Extract a pattern from selected workflow nodes.
-
-```bash
-fw pattern extract <source-file> [options]
-```
-
-| Flag | Description | Default |
-|------|-------------|---------|
-| `--nodes <nodes>` | Comma-separated node IDs **(required)** | — |
-| `-o, --output <file>` | Output file **(required)** | — |
-| `-n, --name <name>` | Pattern name | — |
-| `-p, --preview` | Preview without writing | `false` |
-
-**Examples:**
-```bash
-fw pattern extract workflow.ts --nodes a,b -o extracted.ts
-fw pattern extract workflow.ts --nodes validator,transformer -o validate-transform.ts --name validateTransform
-```
-
-> See also: [Patterns](patterns) for the full pattern system guide.
+> See also: [Scaffold](scaffold.md) for template details.
 
 ---
 
@@ -670,7 +732,7 @@ fw pattern extract workflow.ts --nodes validator,transformer -o validate-transfo
 
 ### export
 
-Export workflow as a serverless function for cloud platforms.
+Export a workflow through a target provided by an installed pack. Flow Weaver core ships no export target; install one with `fw market search` / `fw market install`, then pass its name to `--target`.
 
 ```bash
 fw export <input> [options]
@@ -678,25 +740,26 @@ fw export <input> [options]
 
 | Flag | Description | Default |
 |------|-------------|---------|
-| `-t, --target <target>` | Target from installed packs (e.g. `lambda`, `vercel`, `cloudflare`, `inngest`, `github-actions`, `gitlab-ci`) **(required)** | — |
+| `-t, --target <target>` | Target name registered by an installed pack **(required)** | — |
 | `-o, --output <path>` | Output directory **(required)** | — |
 | `-w, --workflow <name>` | Specific workflow | — |
-| `-p, --production` | Production mode | `true` |
+| `-p, --production` | Production mode (no debug events) | `false` |
+| `--bundle` | Bundle node types into the output | `false` |
 | `--dry-run` | Preview without writing | `false` |
 | `--multi` | Export all workflows as single service | `false` |
 | `--workflows <names>` | Comma-separated workflow subset (with `--multi`) | all |
 | `--docs` | Include API documentation routes | `false` |
-| `--durable-steps` | Per-node Inngest steps (Inngest only) | `false` |
+| `--durable-steps` | Per-node durable steps; handed to the target as an option | `false` |
 
 **Examples:**
 ```bash
-fw export workflow.ts --target vercel --output api/
-fw export workflows.ts --target lambda --output dist/ --multi --docs
-fw export workflow.ts --target inngest --output dist/ --durable-steps
-fw export workflow.ts --target cloudflare --output worker/
+fw export workflow.ts --target <name> --output dist/
+fw export workflows.ts --target <name> --output api/ --multi --docs
+fw export workflow.ts --target <name> --output dist/ --durable-steps
+fw export workflow.ts --target <name> --output dist/ --dry-run
 ```
 
-> Available targets depend on installed `flow-weaver-pack-*` packages (the package names stay as-is). See [Deployment](deployment) for installation instructions and target-specific details.
+> Available targets depend on the installed packs (any package with a `flowweaver.manifest.json`; the package names stay as-is). See [Deployment](deployment.md) for installation instructions and target-specific details.
 
 ---
 
@@ -716,11 +779,14 @@ fw openapi <directory> [options]
 | `--description <desc>` | API description | — |
 | `-f, --format <format>` | `json` or `yaml` | `json` |
 | `--server <url>` | Server URL | — |
+| `--no-auth` | Leave out the bearer scheme, for a server without a token | auth included |
+| `--no-legacy` | Leave out `POST /workflows/<name>`, and declare `@http` routes only | legacy included |
 
 **Examples:**
 ```bash
 fw openapi ./workflows --output api-spec.json
 fw openapi ./workflows --format yaml --server https://api.example.com
+fw openapi ./workflows --no-auth --no-legacy
 ```
 
 ---
@@ -841,32 +907,7 @@ fw market list [options]
 |------|-------------|---------|
 | `--json` | Output as JSON | `false` |
 
-> See also: [Marketplace](marketplace) for the full package lifecycle guide.
-
----
-
-## Plugins
-
-### plugin init
-
-Scaffold a new external plugin with component area and optional system module.
-
-```bash
-fw plugin init <name> [options]
-```
-
-| Flag | Description | Default |
-|------|-------------|---------|
-| `-a, --area <area>` | `sidebar`, `main`, `toolbar`, `modal`, `panel` | `panel` |
-| `--no-system` | Skip generating a system module | system included |
-| `-p, --preview` | Preview without writing | `false` |
-| `--force` | Overwrite existing files | `false` |
-
-**Examples:**
-```bash
-fw plugin init my-plugin
-fw plugin init my-plugin --area sidebar --no-system
-```
+> See also: [Marketplace](marketplace.md) for the full package lifecycle guide.
 
 ---
 
@@ -887,12 +928,12 @@ fw docs [list] [options]
 
 ---
 
-### docs read
+### docs topic
 
-Read a documentation topic.
+Read a documentation topic by passing its slug directly.
 
 ```bash
-fw docs read <topic> [options]
+fw docs <topic> [options]
 ```
 
 | Flag | Description | Default |
@@ -917,8 +958,8 @@ fw docs search <query> [options]
 **Examples:**
 ```bash
 fw docs
-fw docs read error-codes
-fw docs read scaffold --compact
+fw docs error-codes
+fw docs scaffold --compact
 fw docs search "missing workflow"
 ```
 
@@ -941,7 +982,7 @@ fw context [preset] [options]
 | `-o, --output <path>` | Write to file instead of stdout | stdout |
 | `--list` | List available presets and exit | — |
 
-Built-in presets: `core` (concepts, grammar, tutorial), `authoring` (concepts, grammar, annotations, built-in nodes, scaffold, node-conversion, patterns), `ops` (CLI, compilation, deployment, export, debugging, error-codes), `full` (all 16 topics).
+Built-in presets: `core` (the `orientation` map alone, plus the list of every other topic to read on demand), `authoring` (orientation, concepts, grammar, annotations, built-in nodes, durable gates, scaffold, node-conversion), `ops` (orientation, library, CLI, MCP tools, compilation, deployment, export-interface, debugging, error-codes), `full` (20 topics: every reference topic except `console` and `visual-reference`). `fw docs list` names all 22 topics.
 
 **Examples:**
 ```bash
@@ -955,70 +996,47 @@ fw context --list
 
 ---
 
-## Editor Integration
-
-### ui focus-node
-
-Select and center a node in the editor.
-
-```bash
-fw ui focus-node <nodeId> [options]
-```
-
-### ui add-node
-
-Add a node type at viewport center.
-
-```bash
-fw ui add-node <nodeTypeName> [options]
-```
-
-### ui open-workflow
-
-Open a workflow file in the editor.
-
-```bash
-fw ui open-workflow <filePath> [options]
-```
+## System
 
-### ui get-state
+### mcp-server
 
-Return current workflow state from the editor.
+Start MCP server for Claude Code integration.
 
 ```bash
-fw ui get-state [options]
+fw mcp-server [options]
 ```
 
-### ui batch
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--stdio` | Run in MCP stdio mode | `false` |
 
-Execute a batch of commands with auto-snapshot rollback.
+**Running workflows over MCP.**
 
-```bash
-fw ui batch <json> [options]
-```
+| Tool | Notes |
+|------|-------|
+| `fw_run` | Runs to completion or pauses at a gate, returning `{ runId, gate }` with inputs named by port |
+| `fw_resume` | Continues a paused run with `answer` or `reject`; control ports are filled in |
+| `fw_runs` | Lists runs, or inspects one |
 
-All UI commands accept:
+Runs are stored under the workflow's project, in `.fw/runs/<runId>/` (`FW_RUNS_DIR` overrides). Results carry no trace events or continuation. See [Durable Gates](durable-gates.md). A coordinator of your own uses `createLocalCoordinator` from the library, not MCP.
 
-| Flag | Description | Default |
-|------|-------------|---------|
-| `-s, --server <url>` | Editor URL | `http://localhost:9000` |
+The full list of 30 tools, with which to prefer and how large their results are, is in [MCP Tools](mcp-tools.md).
 
 ---
 
-## System
-
-### mcp-server
+### mcp-setup
 
-Start MCP server for Claude Code integration.
+Configure Flow Weaver's MCP server for supported AI coding tools.
 
 ```bash
-fw mcp-server [options]
+fw mcp-setup [options]
 ```
 
 | Flag | Description | Default |
 |------|-------------|---------|
-| `-s, --server <url>` | Editor URL | `http://localhost:9000` |
-| `--stdio` | Run in MCP stdio mode | `false` |
+| `--tool <tools...>` | Configure specific tools: Claude, Cursor, VS Code, Windsurf, Codex, or OpenClaw | — |
+| `--all` | Configure all detected tools without prompting | `false` |
+| `--list` | List detected tools without configuring | `false` |
 
 ---
 
@@ -1032,10 +1050,10 @@ fw mcp-server [options]
 
 ## Related Topics
 
-- [Concepts](concepts) — Fundamental workflow concepts
-- [Compilation](compilation) — Compilation targets and Inngest integration
-- [Deployment](deployment) — Export, serve, and OpenAPI
-- [Built-in Nodes](built-in-nodes) — delay, waitForEvent, invokeWorkflow, and mocks
-- [Scaffold](scaffold) — Template details
-- [Marketplace](marketplace) — Package ecosystem
-- [Advanced Annotations](advanced-annotations) — Pull execution, merge strategies, and more
+- [Concepts](concepts.md) — Fundamental workflow concepts
+- [Compilation](compilation.md) — Compile targets and target options
+- [Deployment](deployment.md) — Export, serve, and OpenAPI
+- [Built-in Nodes](built-in-nodes.md) — delay, waitForEvent, invokeWorkflow, and mocks
+- [Scaffold](scaffold.md) — Template details
+- [Marketplace](marketplace.md) — Package ecosystem
+- [Advanced Annotations](advanced-annotations.md) — Pull execution, merge strategies, and more