@synergenius/flow-weaver 0.33.1 → 0.44.0

package/docs/reference/mcp-tools.md

@@ -0,0 +1,102 @@
+---
+name: MCP Tools
+description: Every tool the Flow Weaver MCP server exposes, what each is for, which to prefer, and how large their results are
+keywords: [mcp, tools, fw_run, fw_resume, fw_runs, fw_docs, fw_validate, fw_describe, fw_query, fw_diagram, fw_compile, fw_modify, fw_scaffold, fw_debug_workflow, fw_market_search, fw_context, mcp-server, mcp-setup, Claude Code, Cursor, assistant, tokens]
+---
+
+# MCP Tools
+
+`fw mcp-server --stdio` exposes 30 tools and one prompt. Every tool definition is sent to the assistant on every turn — about 27 KB, or roughly 6,700 tokens, before any work happens — so this page also says which tools to reach for and which results are large.
+
+- Register with an editor: `fw mcp-setup` (Claude Code, Cursor, VS Code, Windsurf, Codex, OpenClaw)
+- Every result is JSON: `{ success: true, data }` or `{ success: false, error: { code, message } }`. The one exception is `fw_context`, whose result is the bundle itself as markdown
+- Paths are resolved from the server's working directory; pass absolute paths when in doubt
+- Sizes below are measured on a 3-node workflow; they scale with the workflow
+
+## Choosing a tool
+
+| Need | Use | Not |
+|------|-----|-----|
+| Is this file valid? | `fw_validate` (~100 B) | `fw_describe` |
+| What nodes and connections are there? | `fw_query` with one query type (~300 B) | `fw_describe` (~2.3 KB) |
+| Show the graph in chat | `fw_diagram` with `format: "ascii-compact"` (~240 B) | The default `svg` (markup, not readable) |
+| Look something up | `fw_docs` with `action: "search"`, then `read` with `compact: true` | The `authoring`, `ops` and `full` presets of `fw_context` (75–195 KB) |
+| Run a workflow | `fw_run`, then `fw_resume` if it pauses | `fw_debug_workflow`, unless you need to step |
+| Change structure | `fw_modify_batch` for several edits, `fw_modify` for one | Rewriting the annotations by hand |
+| Create a workflow | Write the file (node type functions + workflow stub), then `fw_validate` | A generator; there is none |
+
+## Running workflows
+
+| Tool | Arguments | Returns | Notes |
+|------|-----------|---------|-------|
+| `fw_run` | `filePath`, `workflowName?`, `params?` | `completed` + `result`, or `waiting` + `runId` + `gate` | Gate inputs are named by port. ~300–400 B |
+| `fw_resume` | `runId`, one of `answer` / `reject` | Same shape | Control ports are filled in for you |
+| `fw_runs` | `runId?`, `filePath?`, `status?`, `limit?` | One run, or a list newest first | Re-read a pause without resuming. `status` is one of `waiting`, `completed`, `failed`, `cancelled` (`waiting` is the one that needs you); `limit` is how many to list, 1 to 200, default 20. When more exist the result says how many older runs were left out |
+
+See [Durable Gates](durable-gates.md) for what a gate is and the `answer` rules. A coordinator of your own does not go through MCP: it calls `createLocalCoordinator` (see [Library](library.md)).
+
+## Inspecting a workflow
+
+| Tool | Arguments | Returns | Notes |
+|------|-----------|---------|-------|
+| `fw_validate` | `filePath`, `workflowName?`, `draft?` | `{ valid, errors, warnings }` | Cheapest check. Each item is `{ message, severity, code, nodeId? }` plus one of `hint` (a tool call to make next) or `fix`. `draft` suppresses `STUB_NODE` errors for unimplemented nodes |
+| `fw_query` | `filePath`, `query`, `nodeId?`, `workflowName?` | Depends on `query` | `nodes`, `connections`, `deps`, `dependents`, `data-deps`, `execution-order`, `isolated`, `dead-ends`, `disconnected-outputs`, `node-types`. Ask one question, get one answer |
+| `fw_describe` | `filePath`, `format?`, `node?`, `workflowName?` | Full structure + validation | `json` (default), `text`, `mermaid`, `paths`, `ascii`, `ascii-compact`. Everything at once; ~2 KB+ |
+| `fw_diagram` | `filePath` or `source`, `format?`, `theme?`, `outputPath?` | Diagram | `svg` (default; the spine the console shows, as a vector image — write it with `outputPath`), `ascii` (~2 KB), `ascii-compact` (~240 B), `text`. Use `ascii-compact` in chat |
+| `fw_diff` | `file1`, `file2`, `format?`, `workflowName?` | Semantic diff | `text` (default, ~3 KB box drawing) or `json` |
+| `fw_find_workflows` | `directory`, `pattern?` | Files with `@flowWeaver workflow` and their metadata | Glob, default `**/*.ts`; ~500 ms per directory tree |
+
+## Creating and editing
+
+| Tool | Arguments | Returns | Notes |
+|------|-----------|---------|-------|
+| `fw_modify` | `filePath`, `operation`, `params`, `workflowName?`, `preview?` | Updated file + validation | `addNode`, `removeNode`, `renameNode`, `addConnection`, `removeConnection`, `setNodeLabel`. Rewrites the JSDoc annotations only; a file that was already compiled in place is recompiled so its body stays consistent |
+| `fw_modify_batch` | `filePath`, `operations`, `workflowName?`, `preview?` | Same | One parse/write/validate cycle for many operations. An `addConnection` that already exists is skipped with a warning, not an error |
+| `fw_scaffold` | `template`, `filePath`, `name?`, `config?`, `preview?` | New workflow or node from a template | Templates are listed in [Scaffold](scaffold.md). When `filePath` exists the code is appended to it |
+| `fw_list_templates` | `type?` | Template catalogue (~4 KB) | Same content as the Scaffold topic |
+| `fw_migrate` | `glob`, `dryRun?` | Files rewritten to current syntax | Parse → regenerate round-trip; use `dryRun` first |
+| `fw_compile` | `filePath`, `write?`, `production?`, `workflowName?`, `draft?` | Compiled output path and the validation warnings | Only marker sections are regenerated. `draft` lets a workflow with stub nodes compile |
+| `fw_export` | `filePath`, `target`, `outputDir?`, `production?`, `includeDocs?`, `preview?`, … | Deployment files | Targets come from installed packs; with none installed every target is `INVALID_TARGET`. `production` and `includeDocs` are off unless given, as on the CLI |
+
+## Debugging
+
+Six tools share one in-memory session; the session ends with the server process and cannot resume a gate.
+
+| Tool | Arguments | Notes |
+|------|-----------|-------|
+| `fw_debug_workflow` | `filePath`, `params?`, `breakpoints?`, `workflowName?` | Starts a session paused before the first node; returns `debugId` |
+| `fw_debug_step` | `debugId` | Execute one node |
+| `fw_debug_continue` | `debugId`, `toBreakpoint?` | Run to completion or next breakpoint |
+| `fw_debug_inspect` | `debugId`, `nodeId?` | Variables without advancing |
+| `fw_debug_set_variable` | `debugId`, `nodeId`, `portName`, `value`, `executionIndex?` | Override a value for downstream nodes |
+| `fw_debug_breakpoint` | `debugId`, `action`, `nodeId?` | `add`, `remove`, `list` |
+| `fw_list_debug_sessions` | — | Active sessions |
+
+See [Debugging](debugging.md).
+
+## Documentation and environment
+
+| Tool | Arguments | Returns | Notes |
+|------|-----------|---------|-------|
+| `fw_docs` | `action` (`list` / `read` / `search`), `topic?`, `query?`, `compact?`, `limit?` | Topics, one topic, or matching sections | `list` returns slug, name and description (~4 KB for 20 topics). `search` returns the 8 best sections by default (`limit` up to 20, `total` says how many matched), each with an excerpt of at most 300 characters; `read` with `compact: true` drops prose and keeps headings, tables, lists, and code. Topics declared by installed packs are included |
+| `fw_context` | `preset?`, `profile?`, `topics?`, `addTopics?`, `includeGrammar?` | The orientation bundle as markdown, ending with every other topic and its size | `core` (default) is the `orientation` topic plus the on-demand topic list, ~6 KB — the intended session start. `authoring` ≈ 75 KB, `ops` ≈ 100 KB, `full` ≈ 195 KB bundle whole references; prefer reading single topics with `fw_docs`. `includeGrammar` appends the generated EBNF (~3 KB), which `jsdoc-grammar` already covers |
+| `fw_list_resources` | `type?` | Icons, colors, tags (~3.7 KB) | Same content as the Available Colors / Icons sections of [Advanced Annotations](advanced-annotations.md) |
+| `fw_doctor` | `directory?` | Environment checks | Which install is running (version and path), Node version, config, dependencies; warns when the directory is a different Flow Weaver checkout than the running server |
+| `fw_market_search` | `query`, `limit?`, `registryUrl?` | npm packages tagged as Flow Weaver packs | |
+| `fw_market_install` | `package` | Installs via npm | Pack tools register on the next server start |
+| `fw_market_list` | — | Installed packs and what they contribute | |
+
+## The no-code prompt
+
+The server also publishes one prompt, `flow-weaver-nocode`. It instructs the assistant to build workflows from plain-language descriptions by writing the workflow file itself, then `fw_validate` → `fw_diagram`, showing step summaries and ASCII diagrams instead of code unless asked.
+
+## Error codes
+
+A failed result's `error.code` is one of three kinds. `INVALID_INPUT` means an argument was wrong: missing, malformed, or not one of the allowed values; fix the call and send it again. `<TOOL>_ERROR` means the tool itself failed on good input, named after the tool (`COMPILE_ERROR`, `VALIDATE_ERROR`, `MODIFY_ERROR`, `MARKET_SEARCH_ERROR`); the message says why. The rest name a state worth branching on and keep their names: `PARSE_ERROR`, `FILE_NOT_FOUND`, `INVALID_TARGET`, `CYCLE_DETECTED`, `EXECUTION_ERROR`, `SESSION_NOT_FOUND` and `NOT_PAUSED` for the debugger, and for runs `RUN_NOT_FOUND`, `RUN_NOT_WAITING`, `RUN_BUSY`, `BUNDLE_CHANGED`, `AMBIGUOUS_WORKFLOW`, `MISSING_OUTPUTS` and `AMBIGUOUS_EFFECT`.
+
+## Related Topics
+
+- [Durable Gates](durable-gates.md) — Running and resuming gated workflows
+- [CLI Reference](cli-reference.md) — `mcp-server` and `mcp-setup`; most tools mirror a CLI command
+- [Debugging](debugging.md) — The debug session tools in context
+- [Scaffold](scaffold.md) — Template catalogue behind `fw_scaffold`

package/docs/reference/node-conversion.md

@@ -15,7 +15,7 @@ Does it need to return error data alongside the failure signal?
   NO  -> expression mode (@expression)
 ```
 
-**Default to expression mode.** Expression nodes handle success/failure branching via throw. Only use normal mode when you need to return data on the failure path, or for void side-effects.
+**Default to expression mode.** A throw in an expression node marks it failed and propagates the error out of the workflow call. Use normal mode when a failure must be routed to another node or to `Exit.onFailure`, must carry data, or the function returns void.
 
 ---
 
@@ -32,39 +32,55 @@ Does it need to return error data alongside the failure signal?
 
 Expression nodes are pure functions. The runtime auto-manages `execute`, `onSuccess`, and `onFailure`. The function signature and body are NOT modified -- only a JSDoc block is added.
 
-## Rules
+## The minimal form
 
-- Add a JSDoc block directly above the function
-- First line: `@flowWeaver nodeType`
-- Second line: `@expression`
-- Add `@input <name>` for each function parameter
-- Add `@output` based on the return type:
-  - **Primitive or array return** -> single `@output result`
-  - **Object return** `{ a: T, b: U }` -> one `@output` per property (`@output a`, `@output b`)
-  - **void return** -> no `@output` tags (only onSuccess/onFailure, which are automatic)
-- Add `@label` with a human-readable name (PascalCase -> spaced words)
-- Do NOT add `execute` parameter to the function
-- Do NOT change the return type
-- Do NOT modify the function body
-
-## Example -- single output (primitive return)
+**Ports are inferred from the signature.** For a fully-typed function, `@flowWeaver nodeType @expression` is the whole annotation. Each parameter becomes an input port; each returned object property becomes an output port (a primitive or array return is one port, `result`). You do not restate them.
 
 ```typescript
-// BEFORE
+/** @flowWeaver nodeType @expression */
 function add(a: number, b: number): number {
   return a + b;
 }
+```
 
-// AFTER
+That is a complete node type: two inputs `a` and `b`, one output `result`. Write this first. Reach for the tags below only when you want something inference cannot give you.
+
+## When to add tags
+
+`@input`, `@output` and `@label` are **optional overrides**, not a transcription step. Add one only for a specific reason:
+
+- `@input name - Description` / `@output name - Description` — to document a port. The description is the only thing here inference cannot produce.
+- `@input [name]` / `@input [name=default]` — to mark an input optional or give it a default.
+- `@input name [order:N]` / `@output name [order:N]` — to fix the visual order of ports in the editor.
+- `@label Display Name` — to set the node's display name in diagrams (defaults to the function name).
+- `@color`, `@icon`, `@tag` — visual customization.
+
+Rules for the function itself, always:
+
+- Do NOT add an `execute` parameter.
+- Do NOT change the return type.
+- Do NOT modify the body.
+
+A function used as a node with **no** `@flowWeaver nodeType` annotation at all still works (ports are inferred) but raises `INFERRED_NODE_TYPE`, because the parser cannot tell it was meant to be a node. Adding the one-line annotation silences that; adding port tags is not what it asks for.
+
+## Example -- ports inferred, description added
+
+```typescript
+// Minimal: ports inferred
+/** @flowWeaver nodeType @expression */
+function add(a: number, b: number): number {
+  return a + b;
+}
+
+// With descriptions, when they earn their place
 /**
  * @flowWeaver nodeType
  * @expression
- * @label Add
- * @input a
- * @input b
- * @output result
+ * @input a - First addend
+ * @input b - Second addend
+ * @output result - The sum
  */
-function add(a: number, b: number): number {
+function addDocumented(a: number, b: number): number {
   return a + b;
 }
 ```
@@ -82,10 +98,6 @@ function splitName(fullName: string): { first: string; last: string } {
 /**
  * @flowWeaver nodeType
  * @expression
- * @label Split Name
- * @input fullName
- * @output first
- * @output last
  */
 function splitName(fullName: string): { first: string; last: string } {
   const [first, ...rest] = fullName.split(' ');
@@ -93,44 +105,55 @@ function splitName(fullName: string): { first: string; last: string } {
 }
 ```
 
-## Example -- async expression (returns a value)
+Inputs: `fullName`. Outputs: `first`, `last`, one per returned property.
+
+## Choosing scalar ports or one object port
+
+Every returned property becomes its own port, so the shape you give the return type is the shape of the graph.
+
+- **The rule: scalar ports for what the node reads or transforms; one object port for context that flows through unchanged.** Getting this backwards is the main cause of over-wired workflows.
+- `splitName` above is right to return two scalars, because both are values it computes. The mistake is carrying values through a node that never touches them:
 
 ```typescript
-// BEFORE
-async function fetchData(url: string): Promise<Data> {
-  const res = await fetch(url);
-  return await res.json();
+// SPRAWL -- surface, tenant and locale are re-declared on every node
+// in the chain purely to reach the one at the end that needs them.
+/** @flowWeaver nodeType @expression */
+function score(record: Record, surface: string, tenant: string, locale: string) {
+  return { score: rate(record), surface, tenant, locale };
 }
 
-// AFTER
-/**
- * @flowWeaver nodeType
- * @expression
- * @label Fetch Data
- * @input url
- * @output result
- */
+// BETTER -- the unchanging context travels as one object port
+/** @flowWeaver nodeType @expression */
+function score(record: Record, brief: Brief) {
+  return { score: rate(record), brief };
+}
+```
+
+- **An `@input x` plus `@output x` that only passes a value through is a relay pair**, and a sign the value belongs in the shared object instead.
+- **Keep the port name identical along the chain** (`brief` in and `brief` out at every step) so `@path` wires it with no `@connect`.
+- **The cost: type-checking is per-object, not per-field.** A consumer declaring a narrower shape than the producer emits gets an `OBJECT_TYPE_MISMATCH` warning and still runs. Keep the one or two values the node actually transforms as typed scalars so the checker still guards them.
+- Full treatment, including how durable gates read fields off the object with `[expr:]`, is in `export-interface`.
+
+## Example -- async expression (returns a value)
+
+An `async` function is an expression node like any other; its resolved value maps to the outputs.
+
+```typescript
+/** @flowWeaver nodeType @expression */
 async function fetchData(url: string): Promise<Data> {
   const res = await fetch(url);
   return await res.json();
 }
 ```
 
+Input: `url`. Output: `result` (the single non-object return).
+
 ## Example -- void return (side-effect expression)
 
-```typescript
-// BEFORE
-function logMessage(message: string): void {
-  console.log(message);
-}
+A void return has no data outputs, only the automatic `onSuccess`/`onFailure`.
 
-// AFTER
-/**
- * @flowWeaver nodeType
- * @expression
- * @label Log Message
- * @input message
- */
+```typescript
+/** @flowWeaver nodeType @expression */
 function logMessage(message: string): void {
   console.log(message);
 }
@@ -172,7 +195,7 @@ function double(x: number): number {
 function double(
   execute: boolean,
   x: number
-): { onSuccess: boolean; onFailure: boolean; result: number | null } {
+): { onSuccess: boolean, onFailure: boolean, result: number | null } {
   if (!execute) return { onSuccess: false, onFailure: false, result: null };
   try {
     const result = x * 2;
@@ -201,7 +224,7 @@ async function fetchUser(id: string): Promise<User> {
 async function fetchUser(
   execute: boolean,
   id: string
-): Promise<{ onSuccess: boolean; onFailure: boolean; user: User | null }> {
+): Promise<{ onSuccess: boolean, onFailure: boolean, user: User | null }> {
   if (!execute) return { onSuccess: false, onFailure: false, user: null };
   try {
     const user = await db.users.findById(id);
@@ -231,7 +254,7 @@ function analyze(text: string): { wordCount: number; charCount: number } {
 function analyze(
   execute: boolean,
   text: string
-): { onSuccess: boolean; onFailure: boolean; wordCount: number | null; charCount: number | null } {
+): { onSuccess: boolean, onFailure: boolean, wordCount: number | null, charCount: number | null } {
   if (!execute) return { onSuccess: false, onFailure: false, wordCount: null, charCount: null };
   try {
     const wordCount = text.split(' ').length;
@@ -277,7 +300,7 @@ When no `--mode` is specified:
 - **Expression** (default): function returns a value (non-void), whether sync or async
 - **Normal**: void return, or user explicitly requests normal mode
 
-**Default to expression mode.** Expression nodes support failure branching via throw. Only switch to normal mode for error-with-data patterns or void side-effects.
+**Default to expression mode.** A throw in an expression node marks it failed and propagates the error out of the workflow call. Switch to normal mode when a failure must be routed to another node or to `Exit.onFailure`, must carry data, or the function returns void.
 
 The compiler fully supports async expression nodes -- `await`, async detection, try/catch wrapping, and onSuccess/onFailure are all handled automatically.
 
@@ -285,11 +308,13 @@ The compiler fully supports async expression nodes -- `await`, async detection,
 
 # Output Mapping Rules
 
+This is what the compiler infers from the return type; you do not write these `@output` tags unless you are overriding.
+
 ## Expression mode
 
-- Primitive/array return -> single `@output result`
-- Object return `{ a, b }` -> one `@output` per property
-- void -> no `@output` tags
+- Primitive/array return -> single output `result`
+- Object return `{ a, b }` -> one output per property
+- void -> no data outputs
 
 ## Normal mode
 

package/docs/reference/orientation.md

@@ -0,0 +1,68 @@
+---
+name: Orientation
+description: The Flow Weaver model on one page, the tool loop, and which topic to read for which task — start here and load the rest on demand
+keywords: [orientation, start, overview, mental model, getting started, map, which topic, first, basics, workflow, nodeType, annotations, tools, loop]
+---
+
+# Orientation
+
+Flow Weaver compiles workflows you describe with JSDoc annotations into plain TypeScript functions. This page is the map: what the pieces are, how to work on them with the tools, and which reference topic to open next. Read it once; load other topics only when a task needs them.
+
+## The model
+
+- A **node type** is a plain function annotated `@flowWeaver nodeType @expression`, and that one line is the whole annotation. Ports are inferred from the signature: each parameter is an input port, each field of the returned object an output port (a primitive return is one port, `result`). Add `@input`/`@output`/`@label` only to override the inference — a description, a rename, an order, a display label — never to restate it. Throwing marks the node failed and propagates the error out of the workflow call. Normal mode, with an `execute: boolean` first parameter and `onSuccess`/`onFailure` in the return, exists for the cases that need it: routing a failure to another node or to `Exit.onFailure`, returning data alongside a failure, a boolean branch, a scope owner, a durable gate or effect.
+- A **workflow** is an exported function annotated `@flowWeaver workflow` with the signature `(execute, params)`. `@param` declares the `Start` ports, `@returns` the `Exit` ports.
+- Inside a workflow, `@node <id> <nodeType>` declares an instance and `@path Start -> a -> b -> Exit` wires the route: control flow between the steps, and every data port to the nearest earlier step with an output of the same name, `Exit` included. `@connect a.port -> b.port` wires one port explicitly, for the cases where names differ; an explicit connection always wins.
+- The workflow's function body is a stub. The compiler generates it from the annotations and only ever rewrites the marker sections, so hand-written code around them survives.
+- Built-in node types need no import: `delay`, `invokeWorkflow`, `waitForEvent`, `waitForAgent`. The last two are **durable gates** — the run pauses, hands back a continuation, and resumes later. In a workflow with a gate, an `@expression` node is pure automatically; only a normal-mode pure node needs `@durablePure`, and gates and effects need `@durableGate`/`@durableEffect`.
+- The compiled file imports nothing from Flow Weaver. The code that calls it hands it a runtime built with `createWorkflowRuntime`, which the compiled file itself exports (see `library`).
+- Nodes take direct parameters; workflows take a `params` object. That is the mistake made most often.
+
+## The loop
+
+| To | Use | Note |
+|----|-----|------|
+| Check a file | `fw_validate` | Cheapest call; run it after every change |
+| Answer one question about structure | `fw_query` with one `query` type | ~300 B |
+| See everything about a file | `fw_describe` | Larger; prefer `fw_query` |
+| Show the graph in chat | `fw_diagram` with `format: "ascii-compact"` | The default `svg` is not readable |
+| Show a person the workflow | `fw_diagram` with `format: "svg"` and an `outputPath` | The spine: steps in run order, pauses, failure arms, as a vector image |
+| Create a workflow | Write the file: one `@flowWeaver nodeType` function per step, then the `@flowWeaver workflow` stub | `tutorial` walks through it; `fw_scaffold` starts from a template |
+| Change structure | `fw_modify_batch` (several edits) or `fw_modify` (one) | Rewrites annotations only; re-validate afterwards |
+| Run a workflow | `fw_run`, then `fw_resume` if it pauses at a gate | `fw run` on the CLI refuses gated workflows |
+| Look something up | `fw_docs` `search`, then `read` with `compact: true` | Search first; a topic can be large |
+
+## What to read next
+
+| When you need to | Read |
+|------------------|------|
+| Write or fix an annotation | `jsdoc-grammar` |
+| Understand a validation error | `error-codes` — search it; never read it whole |
+| Use expressions, pull execution, merge strategies, fan-out, colours and icons | `advanced-annotations` |
+| Use `delay`, `invokeWorkflow`, or mocks | `built-in-nodes` |
+| Pause a workflow for approval, input, or an AI agent | `durable-gates` |
+| Know every MCP tool, its arguments and result sizes | `mcp-tools` |
+| Find a CLI flag | `cli-reference` |
+| Compile to something other than TypeScript | `compilation` |
+| Export, serve over HTTP, or generate OpenAPI | `deployment` |
+| Install, write, or extend a pack | `marketplace` |
+| Decide which values are scalar ports and which travel as one object | `export-interface` |
+| Loop over items with scoped ports | `export-interface` |
+| Turn an existing function into a node | `node-conversion` |
+| Start from a template | `scaffold` |
+| Step through execution | `debugging` |
+| Cancel a run | `cancellation` |
+| Walk from an empty file to a running workflow | `tutorial` |
+| Call a compiled workflow from your own code, or drive one that pauses from a service | `library` |
+| Read the long-form reference behind this page | `concepts` |
+
+## Rules of thumb
+
+- Read topics with `compact: true`; it keeps headings, tables, lists and code and drops the prose
+- Never load the `full` context preset, and never read `error-codes` whole
+- Use absolute file paths in tool calls
+- Node ids and workflow function names are camelCase
+- After `fw_modify` or a hand edit, run `fw_validate` before anything else
+- `fw_modify` never compiles a file that was not already compiled in place; `fw_compile` and `fw_run` do that
+- Hand a gate only what its resolver needs; a later node reads larger values across the gate from the node that produced them (see `durable-gates`)
+- In a worktree or a second checkout, `fw_doctor` says which install the MCP server runs from; rebuilding anywhere else changes nothing it does

package/docs/reference/scaffold.md

@@ -1,12 +1,12 @@
 ---
 name: Flow Weaver Scaffold
 description: Scaffold workflows and nodes from templates using CLI commands
-keywords: [scaffold, templates, create, generate, workflow, node, sequential, foreach, ai-agent]
+keywords: [scaffold, templates, create, generate, workflow, node, sequential, foreach, approval, gate, ai-agent]
 ---
 
 # Quick Start
 
-Use the `fw create` command to scaffold workflows and nodes from templates, or `fw init` to create a new project.
+Use the `fw create` command to scaffold workflows and nodes from templates, or `fw init` to create a new project. The same templates are behind `fw_scaffold` for an assistant and `fw templates` lists them. `approval` is the gated one: it pauses for a person and resumes with their answer.
 
 ## Create a Project
 
@@ -18,7 +18,7 @@ Creates a new Flow Weaver project with recommended structure, dependencies, and
 
 Options:
 - `--name <name>` / `-n` - Project name (defaults to directory name)
-- `--template <template>` / `-t` - Workflow template (default: `simple`)
+- `--template <template>` / `-t` - Workflow template (default: `sequential`)
 - `--format <format>` / `-f` - Module format: `esm` or `cjs` (default: `esm`)
 - `--yes` / `-y` - Skip prompts, use defaults
 - `--install` / `--no-install` - Run or skip npm install
@@ -62,7 +62,7 @@ fw create node <name> <file> [--template T] [--line N] [--preview]
 
 Options:
 <!-- AUTO:START default_node_template -->
-- `--template T` / `-t T` - Use specific template (default: processor)
+- `--template T` / `-t T` - Use specific template (default: transformer)
 <!-- AUTO:END default_node_template -->
 - `--line N` / `-l N` - Insert at specific line
 - `--preview` / `-p` - Preview generated code without writing
@@ -85,6 +85,7 @@ fw templates [--json]
 | `sequential` | Linear pipeline: validate -> transform -> output |
 | `foreach` | Batch processing with iteration over arrays |
 | `conditional` | Route data based on conditions with branching paths |
+| `approval` | Prepare a request, pause for a person to approve it, then carry it out |
 | `ai-agent` | Stateful LLM agent with explicit reasoning loop and tool execution |
 | `ai-react` | Reasoning + Acting agent with explicit thought process |
 | `ai-rag` | Retrieval-Augmented Generation for knowledge-based Q&A |