@synergenius/flow-weaver 0.33.1 → 0.44.0

package/docs/reference/advanced-annotations.md

@@ -6,7 +6,7 @@ keywords: [pullExecution, executeWhen, mergeStrategy, autoConnect, strictTypes,
 
 # Advanced Annotations
 
-This guide covers annotations that go beyond the basics in [Concepts](concepts). Each feature is fully supported by the parser, validator, and compiler.
+This guide covers annotations that go beyond the basics in [Concepts](concepts.md). Each feature is fully supported by the parser, validator, and compiler.
 
 ## Pull Execution
 
@@ -65,7 +65,7 @@ Controls how a node evaluates incoming STEP signals before firing. This matters
 | `DISJUNCTION` | Execute when **ANY** signal arrives (OR) | Priority routing, first-response |
 | `CUSTOM` | Execution controlled by custom logic | Advanced patterns |
 
-### Node Type Level
+The strategy is set on the node type, and applies to every instance of it:
 
 ```typescript
 /**
@@ -80,15 +80,6 @@ function firstResponse(execute: boolean, data: string) {
 }
 ```
 
-### Instance Level
-
-```typescript
-/**
- * @flowWeaver workflow
- * @node fr firstResponse [executeWhen: DISJUNCTION]
- */
-```
-
 ---
 
 ## Merge Strategies
@@ -147,9 +138,24 @@ Enables automatic linear connection wiring. When `@autoConnect` is present and n
 Start -> first @node -> second @node -> ... -> last @node -> Exit
 ```
 
-Data ports are matched by name — if node A has an output named `result` and node B has an input named `result`, they are automatically connected.
+Data ports are matched by name between neighbours — if node A has an output named `record` and the next node B has an input named `record`, they are automatically connected.
 
 ```typescript
+/** @flowWeaver nodeType @expression */
+function validateRecord(data: Record<string, unknown>): { record: Record<string, unknown> } {
+  return { record: data };
+}
+
+/** @flowWeaver nodeType @expression */
+function enrichRecord(record: Record<string, unknown>): { enriched: Record<string, unknown> } {
+  return { enriched: { ...record, enrichedAt: Date.now() } };
+}
+
+/** @flowWeaver nodeType @expression */
+function scoreRecord(enriched: Record<string, unknown>): { result: Record<string, unknown> } {
+  return { result: { ...enriched, score: 1 } };
+}
+
 /**
  * @flowWeaver workflow
  * @autoConnect
@@ -159,18 +165,23 @@ Data ports are matched by name — if node A has an output named `result` and no
  * @param data - Input record
  * @returns result - Scored record
  */
-export function pipeline(params: { data: Record<string, unknown> }): { result: Record<string, unknown> } {
-  throw new Error('Not compiled');
+export function pipeline(
+  execute: boolean,
+  params: { data: Record<string, unknown> }
+): { onSuccess: boolean; onFailure: boolean; result: Record<string, unknown> } {
+  throw new Error('generated body was not installed');
 }
 ```
 
 This is equivalent to manually writing:
 ```
+@connect Start.execute -> v.execute
 @connect Start.data -> v.data
 @connect v.onSuccess -> e.execute
-@connect v.result -> e.data
+@connect v.record -> e.record
 @connect e.onSuccess -> s.execute
-@connect e.result -> s.data
+@connect e.enriched -> s.enriched
+@connect s.onSuccess -> Exit.onSuccess
 @connect s.result -> Exit.result
 ```
 
@@ -184,7 +195,24 @@ Fan macros reduce boilerplate when broadcasting a single output to many targets,
 
 ### `@fanOut` — One to Many
 
-Broadcasts a single output port to multiple targets:
+Broadcasts a single output port to multiple targets. The examples below use three node types that each take `data` and return `result`:
+
+```typescript
+/** @flowWeaver nodeType @expression */
+function processA(data: string): { result: string } {
+  return { result: `A: ${data}` };
+}
+
+/** @flowWeaver nodeType @expression */
+function processB(data: string): { result: string } {
+  return { result: `B: ${data}` };
+}
+
+/** @flowWeaver nodeType @expression */
+function processC(data: string): { result: string } {
+  return { result: `C: ${data}` };
+}
+```
 
 ```typescript
 /**
@@ -227,11 +255,14 @@ Merges multiple output ports into a single target:
  * @node c processC
  * @node agg aggregate
  *
+ * @fanOut Start.data -> a, b, c
  * @fanIn a.result, b.result, c.result -> agg.items
- * @connect agg.merged -> Exit.result
+ * @connect agg.combined -> Exit.result
  */
 ```
 
+(`aggregate` is the `[mergeStrategy:COLLECT]` node type from [Declaring Merge Strategy](#declaring-merge-strategy).)
+
 This expands to:
 ```
 @connect a.result -> agg.items
@@ -249,56 +280,141 @@ Both macros are preserved through parse-regenerate round-trips. The compiler sto
 
 ## Strict Types (`@strictTypes`)
 
-By default, type mismatches between connected ports produce warnings. With `@strictTypes`, they become errors.
+By default, type mismatches between connected ports produce warnings. With `@strictTypes`, they become `TYPE_INCOMPATIBLE` errors. This workflow is rejected because a `STRING` output reaches a `NUMBER` input:
 
+<!-- example: invalid TYPE_INCOMPATIBLE -->
 ```typescript
+/** @flowWeaver nodeType @expression */
+function readAmount(raw: string): { amount: string } {
+  return { amount: raw.trim() };
+}
+
+/** @flowWeaver nodeType @expression */
+function addTax(total: number): { withTax: number } {
+  return { withTax: total * 1.2 };
+}
+
 /**
  * @flowWeaver workflow
  * @strictTypes
- * @node n myNode
- * @connect Start.count -> n.text
+ * @param raw - Amount as typed by the user
+ * @returns withTax - Amount with tax
+ * @node read readAmount
+ * @node tax addTax
+ * @path Start -> read -> tax -> Exit
+ * @connect read.amount -> tax.total
  */
+export function strict(
+  execute: boolean,
+  params: { raw: string }
+): { onSuccess: boolean; onFailure: boolean; withTax: number } {
+  throw new Error('generated body was not installed');
+}
 ```
 
-Type compatibility levels:
-- **exact** — Same type (e.g. `STRING` → `STRING`)
-- **assignable** — Safe conversion (e.g. `NUMBER` → `ANY`)
-- **coercible** — Lossy conversion (e.g. `NUMBER` → `STRING`) — warning by default, error with `@strictTypes`
-- **incompatible** — No conversion possible — always an error
+How a connection between two node ports is judged:
+- **same type** (`STRING` → `STRING`), or `ANY` on either side: compatible
+- **safe coercion** (`NUMBER` → `STRING`, `BOOLEAN` → `STRING`): compatible, no warning
+- **lossy coercion** (`STRING` → `NUMBER`, `OBJECT` → `STRING`, ...), **unusual coercion** (`NUMBER` → `BOOLEAN`, `STRING` → `OBJECT`, ...) and any other mismatch: a warning (`LOSSY_TYPE_COERCION`, `UNUSUAL_TYPE_COERCION`, `TYPE_MISMATCH`) by default, a `TYPE_INCOMPATIBLE` error with `@strictTypes`
+- a `STEP` port connected to a data port: always an error (`STEP_PORT_TYPE_MISMATCH`)
+
+Connections from `Start` or into `Exit` are not type-checked.
 
 ---
 
 ## Path Sugar (`@path`)
 
-Syntactic sugar for declaring multi-step execution routes. A `@path` annotation expands to a chain of STEP connections (execute → onSuccess).
+Syntactic sugar for declaring multi-step execution routes. A `@path` annotation expands to a chain of STEP connections (execute → onSuccess) and wires the data ports along the way by name.
 
 ### Basic Syntax
 
 ```typescript
+/** @flowWeaver nodeType @expression */
+function validate(record: Record<string, unknown>): { record: Record<string, unknown> } {
+  return { record };
+}
+
+/** @flowWeaver nodeType @expression */
+function enrich(record: Record<string, unknown>): { record: Record<string, unknown> } {
+  return { record: { ...record, enrichedAt: Date.now() } };
+}
+
+/** @flowWeaver nodeType @expression */
+function score(record: Record<string, unknown>): { score: number } {
+  return { score: Object.keys(record).length };
+}
+
 /**
  * @flowWeaver workflow
+ * @param record - Raw record
+ * @returns score - Final score
  * @node v validate
  * @node e enrich
  * @node s score
  * @path Start -> v -> e -> s -> Exit
  */
+export function scorePipeline(
+  execute: boolean,
+  params: { record: Record<string, unknown> }
+): { onSuccess: boolean; onFailure: boolean; score: number } {
+  throw new Error('generated body was not installed');
+}
 ```
 
 This expands to:
 ```
 @connect Start.execute -> v.execute
+@connect Start.record -> v.record
 @connect v.onSuccess -> e.execute
+@connect v.record -> e.record
 @connect e.onSuccess -> s.execute
-@connect s.onSuccess -> Exit.execute
+@connect e.record -> s.record
+@connect s.onSuccess -> Exit.onSuccess
+@connect s.score -> Exit.score
 ```
 
+### Data Resolution
+
+For every step after the first, each data input resolves to the nearest earlier step in the path that has an output of the same name. `Start` params count as outputs, and `Exit` `@returns` ports count as inputs, so a linear pipeline with consistently named ports needs no `@connect` at all.
+
+Two rules keep this predictable:
+
+- **An explicit `@connect` wins.** If a port already has a connection, `@path` leaves it alone. Use this to take a value from an earlier step than the nearest one.
+- **A `Start` param never passes straight through to `Exit`.** Echoing an input as an output would hide a missing producer, so `Start.x -> Exit.x` is only ever an explicit `@connect`.
+
+A port with no same-name ancestor stays unconnected and is reported by validation as usual (`MISSING_REQUIRED_INPUT` for a node, `UNREACHABLE_EXIT_PORT` for Exit).
+
 ### Branching with `:ok` and `:fail`
 
-Use `:ok` or `:fail` suffixes to route through `onSuccess` or `onFailure`:
+Use `:ok` or `:fail` suffixes to route through `onSuccess` or `onFailure`. The router is a normal-mode node, because it branches:
 
 ```typescript
+/**
+ * Boolean branch: onSuccess for routine records, onFailure for urgent ones.
+ * @flowWeaver nodeType
+ */
+function routeUrgency(
+  execute: boolean,
+  record: Record<string, unknown>
+): { onSuccess: boolean; onFailure: boolean; record: Record<string, unknown> } {
+  if (!execute) return { onSuccess: false, onFailure: false, record };
+  const urgent = record.priority === 'high';
+  return { onSuccess: !urgent, onFailure: urgent, record };
+}
+
+/** @flowWeaver nodeType @expression */
+function handle(record: Record<string, unknown>): { handled: boolean } {
+  return { handled: record !== undefined };
+}
+
+/** @flowWeaver nodeType @expression */
+function escalate(record: Record<string, unknown>): { ticket: string } {
+  return { ticket: `ESC-${String(record.id)}` };
+}
+
 /**
  * @flowWeaver workflow
+ * @param record - Raw record
  * @node v validate
  * @node router routeUrgency
  * @node handler handle
@@ -316,8 +432,25 @@ Without a suffix, `:ok` (onSuccess) is the default. Duplicate connections from o
 Multiple paths can be declared in a single `@path` tag using commas. This is equivalent to separate `@path` tags:
 
 ```typescript
+/** @flowWeaver nodeType @expression */
+function enrichCompany(lead: { domain: string }): { company: string } {
+  return { company: lead.domain };
+}
+
+/** @flowWeaver nodeType @expression */
+function enrichContact(lead: { email: string }): { contact: string } {
+  return { contact: lead.email };
+}
+
+/** @flowWeaver nodeType @expression */
+function scoreLead(company: string, contact: string): { score: number } {
+  return { score: company.length + contact.length };
+}
+
 /**
- * @flowWeaver workflow @autoConnect
+ * @flowWeaver workflow
+ * @param lead - The lead to score
+ * @returns score - Lead score
  * @node enrichCompany enrichCompany
  * @node enrichContact enrichContact
  * @node scoreLead scoreLead
@@ -340,6 +473,11 @@ Syntactic sugar for forEach iteration patterns. A `@map` expands to a synthetic
 ### Basic Syntax
 
 ```typescript
+/** @flowWeaver nodeType @expression */
+function doubleIt(value: number): { doubled: number } {
+  return { doubled: value * 2 };
+}
+
 /**
  * @flowWeaver workflow
  * @node proc doubleIt
@@ -378,10 +516,64 @@ Node instances in workflows support attribute brackets `[...]` for configuration
 Set port values via JavaScript expressions instead of connections:
 
 ```typescript
-@node wait waitForEvent [expr: eventName="'app/expense.approved'", match="'data.expenseId'", timeout="'48h'"]
+@node wait delay [expr: duration="'30s'"]
+```
+
+Each assignment is `portName="expression"`. Multiple assignments are comma-separated. (`waitForEvent` and `waitForAgent` accept expressions the same way, but using either makes the workflow a gated one — see [Durable Gates](durable-gates.md).)
+
+#### Referencing upstream ports
+
+An expression may read values the workflow already has: `Start.<param>` for a workflow input, `<node>.<port>` for an output of an earlier node. Any property access after the port is ordinary JavaScript, so `Start.expense.id` reads the `id` field of the `expense` param.
+
+```typescript
+/** @flowWeaver nodeType @expression */
+function route(expense: { id: string; amount: number }): { risk: string } {
+  return { risk: expense.amount > 1000 ? 'high' : 'low' };
+}
+
+/**
+ * The body is never called: the gate's resolution is its return value.
+ * @flowWeaver nodeType
+ * @durableGate approval
+ * @input draft - The drafted decision to approve
+ * @output decision - The approved decision
+ */
+async function waitForApproval(
+  execute: boolean,
+  draft: object
+): Promise<{ onSuccess: boolean; onFailure: boolean; decision: object }> {
+  throw new Error('durable gate implementation must not execute');
+}
+
+/**
+ * @flowWeaver workflow
+ * @param expense - The expense
+ * @returns decision
+ * @node route route
+ * @node reviewer waitForAgent [expr:
+ *   agentId="'review'",
+ *   context="{ id: Start.expense.id, amount: Start.expense.amount, risk: route.risk }",
+ *   prompt="`Draft an approve/reject decision for expense ${Start.expense.id}`"]
+ * @node approval waitForApproval [expr: draft="reviewer.agentResult"]
+ * @path Start -> route -> reviewer -> approval -> Exit
+ */
 ```
 
-Each assignment is `portName="expression"`. Multiple assignments are comma-separated.
+This replaces the node that would otherwise exist only to shape those three values, and it replaces a `@connect` whose only purpose is a rename (`[expr: draft="reviewer.agentResult"]`).
+
+**Keep expressions short.** A reference or a small reshape (`shape.top`, `{ path: Start.path }`, `Start.count + 1`) reads well inline. A multi-line string, a template literal with its own quotes, or anything you would want to format across lines belongs in a node function body, not in a `[expr:]` string, where JSDoc forces it onto one line with escaped quotes. If the value is a prompt or a paragraph, write a one-line `@expression` node that builds it — the template literal lives in real code — and let `@path` wire it. The expression form is for wiring and reshaping, not for authoring prose.
+
+Each reference is a real data dependency. The parser records it as a connection marked as derived from the expression, so execution order, cycle detection, `fw_query` (`data-deps`, `execution-order`), the diagram and the durable continuation all see the edge. A derived connection is not written as `@connect` (the expression implies it), is exempt from the one-source-per-input rule (one expression may read several ports) and from type checks (the expression transforms the value), and cannot be removed on its own; edit the expression.
+
+What is recognised, exactly:
+
+- A property access on a bare identifier that is `Start` or a node id, where the property is a declared data port. The expression is parsed as TypeScript, so a name inside a string literal (`'Start.path'`) is text, a name inside a template substitution (`` `${Start.path}` ``) is a reference, and `Start["path"]`, `f().port` or `x[0].port` are never references.
+- A node id that is also a top-level binding of the file (an import, a `const`, a class) is ambiguous when the property is a port and plain JavaScript when it is not. Node type functions do not count: `@node route route` with `route.risk` reads the node.
+- References are between top-level nodes. A scoped child, or a reference to one, is refused; scoped ports keep their explicit `@connect node.port:scope` form.
+
+Errors are reported at parse time, prefixed with the instance and port, for example `[expr] reviewer.context: "route.rsk" is not an output of "route". Available: risk.`, and for a control port, a self-reference, a scope boundary or an ambiguous name. A reference cycle between two expressions is `CYCLE_DETECTED` like any other cycle.
+
+The decision record is [ADR 0002](../adr/0002-expression-port-references.md).
 
 ### Port Order (`[portOrder: ...]`)
 
@@ -409,7 +601,7 @@ Display the node in a collapsed/minimized state:
 
 ### Size (`[size: W H]`)
 
-Custom node dimensions in the visual editor:
+Custom node dimensions when the workflow is rendered as a diagram:
 
 ```typescript
 @node big BigNode [size: 400 300]
@@ -441,7 +633,7 @@ Visual tags/badges on the instance. Each tag has a label string and optional too
 
 ### Suppress Warnings (`[suppress: ...]`)
 
-Silences specific validator warnings on a per-instance basis. Useful when a warning is intentional, such as output ports that are deliberately left unconnected in CI/CD workflows where data is discarded by design.
+Silences specific validator warnings on a per-instance basis. Useful when a warning is intentional, such as an output port deliberately left unconnected because its value is discarded by design.
 
 ```typescript
 @node fetch fetchData [suppress: "UNUSED_OUTPUT_PORT"]
@@ -455,7 +647,7 @@ The suppression is scoped to the annotated instance only. Other instances of the
 Multiple attribute brackets can appear on the same `@node`:
 
 ```typescript
-@node wait waitForEvent [expr: eventName="'approval'", timeout="'24h'"] [minimized] [color: "#3b82f6"]
+@node wait delay [expr: duration="'24h'"] [minimized] [color: "#3b82f6"]
 ```
 
 ---
@@ -467,28 +659,44 @@ A single TypeScript file can contain multiple `@flowWeaver workflow` annotations
 ```typescript
 /**
  * @flowWeaver workflow
+ * @param record - Raw record
+ * @returns record - Validated record
  * @node v validate
  * @path Start -> v -> Exit
  */
-export function validatePipeline(params: { data: string }) { ... }
+export function validatePipeline(
+  execute: boolean,
+  params: { record: Record<string, unknown> }
+): { onSuccess: boolean; onFailure: boolean; record: Record<string, unknown> } {
+  throw new Error('generated body was not installed');
+}
 
 /**
  * @flowWeaver workflow
+ * @param record - Raw record
+ * @returns record - Enriched record
  * @node e enrich
  * @path Start -> e -> Exit
  */
-export function enrichPipeline(params: { data: string }) { ... }
+export function enrichPipeline(
+  execute: boolean,
+  params: { record: Record<string, unknown> }
+): { onSuccess: boolean; onFailure: boolean; record: Record<string, unknown> } {
+  throw new Error('generated body was not installed');
+}
 ```
 
+(`validate` and `enrich` are the node types from [Path Sugar](#path-sugar-path).)
+
 ### Targeting a Specific Workflow
 
-Most CLI commands accept `--workflow-name` or `-w` to target a specific workflow:
+Most CLI commands accept `--workflow` or `-w` to target a specific workflow:
 
 ```bash
-fw compile multi.ts --workflow-name validatePipeline
+fw compile multi.ts --workflow validatePipeline
 fw validate multi.ts -w enrichPipeline
-fw run multi.ts -w validatePipeline --params '{"data": "test"}'
-fw describe multi.ts --workflow-name enrichPipeline
+fw run multi.ts -w validatePipeline --params '{"record": {"id": 1}}'
+fw describe multi.ts --workflow enrichPipeline
 ```
 
 Without this flag, all workflows in the file are processed.
@@ -515,6 +723,14 @@ These annotations go on `@flowWeaver nodeType` blocks:
 | `@expression` | Expression mode (simplified signature) | `@expression` |
 | `@executeWhen` | Execution strategy | `@executeWhen DISJUNCTION` |
 | `@pullExecution` | Lazy evaluation | `@pullExecution execute` |
+| `@resilience` | Declare adapter-owned retry/fallback handling for static validation | `@resilience retries=3 fallback="backup-provider"` |
+| `@durablePure` | No side effects; safe to re-run after a resume | `@durablePure` |
+| `@durableGate` | Pause point: `approval`, `input`, or `agent` | `@durableGate approval` |
+| `@durableEffect` | Touches the outside world; runs through the effect adapter | `@durableEffect` |
+
+`@resilience` is an explicit static-analysis contract; it does not implement retries itself. Use it only when the node's shared adapter already performs the declared bounded retries or fallback. An unconnected `onFailure` port still remains an error because exhausted attempts must be handled.
+
+The three `@durable…` tags are a closed classification: once a workflow's reachable closure contains a gate, every node in it must carry exactly one of them, or compilation fails. An effect node also changes its signature — a trailing `operationKey: string` parameter and a `{ result, receipt }` return. See [Durable Gates](durable-gates.md).
 
 ---
 
@@ -522,42 +738,43 @@ These annotations go on `@flowWeaver nodeType` blocks:
 
 Named colors adapt to the diagram theme (dark/light). You can also pass any hex color directly (e.g. `@color "#ff6b35"`).
 
-`blue` · `purple` · `cyan` · `orange` · `pink` · `green` · `red` · `yellow` · `teal` (alias for cyan)
+`blue`, `purple`, `cyan`, `orange`, `pink`, `green`, `red`, `yellow`, `teal` (alias for cyan)
 
 ## Available Icons
 
-Icons render inside the node body in SVG diagrams. Names correspond to Material Symbols (outlined, weight 500).
+Any [Material Symbols](https://fonts.google.com/icons) name is valid, in the font's `snake_case` or in `camelCase` (`swap_horiz` and `swapHoriz` are the same icon). The console draws the icon from the font; the SVG artifacts draw the icons in the visual-reference table with a path and any other as a dot.
 
-**AI & ML:** `psychology` · `smartToy` · `autoAwesome` · `modelTraining` · `science` · `biotech`
+**AI & ML:** `psychology`, `smartToy`, `autoAwesome`, `modelTraining`, `science`, `biotech`
 
-**Data & storage:** `database` · `dataObject` · `tableChart` · `token` · `storage` · `memory`
+**Data & storage:** `database`, `dataObject`, `tableChart`, `token`, `storage`, `memory`
 
-**Cloud & network:** `api` · `webhook` · `cloudSync` · `cloudUpload` · `cloudDownload` · `dns` · `router` · `http` · `link`
+**Cloud & network:** `api`, `webhook`, `cloudSync`, `cloudUpload`, `cloudDownload`, `dns`, `router`, `http`, `link`
 
-**Security & auth:** `key` · `shield` · `vpnKey` · `verified` · `security` · `policy` · `adminPanelSettings`
+**Security & auth:** `key`, `shield`, `vpnKey`, `verified`, `security`, `policy`, `adminPanelSettings`
 
-**Logic & flow:** `altRoute` · `callSplit` · `callMerge` · `rule` · `filterAlt` · `repeat` · `sort`
+**Logic & flow:** `altRoute`, `callSplit`, `callMerge`, `rule`, `filterAlt`, `repeat`, `sort`
 
-**Actions & status:** `bolt` · `build` · `rocketLaunch` · `send` · `sync` · `refresh`
+**Actions & status:** `bolt`, `build`, `rocketLaunch`, `send`, `sync`, `refresh`
 
-**Communication:** `notifications` · `email` · `campaign`
+**Communication:** `notifications`, `email`, `campaign`
 
-**Scheduling:** `event` · `schedule` · `timer`
+**Scheduling:** `event`, `schedule`, `timer`
 
-**General tools:** `terminal` · `settings` · `tune` · `search` · `save` · `upload` · `download` · `edit` · `delete`
+**General tools:** `terminal`, `settings`, `tune`, `search`, `save`, `upload`, `download`, `edit`, `delete`
 
-**Status:** `checkCircle` · `error` · `warning` · `info` · `help` · `visibility`
+**Status:** `checkCircle`, `error`, `warning`, `info`, `help`, `visibility`
 
-**Files:** `folder` · `description` · `attachFile`
+**Files:** `folder`, `description`, `attachFile`
 
-**Structural:** `code` (default) · `flow` (workflow nodes) · `startNode` · `exitNode`
+**Structural:** `code` (default), `flow` (workflow nodes), `startNode`, `exitNode`
 
 ---
 
 ## Related Topics
 
-- [Concepts](concepts) — Core workflow fundamentals
-- [JSDoc Grammar](jsdoc-grammar) — Formal EBNF syntax for all annotations
-- [Compilation](compilation) — How annotations affect code generation
-- [Error Codes](error-codes) — Validation errors for annotation issues
-- [CLI Reference](cli-reference) — All command flags
+- [Concepts](concepts.md) — Core workflow fundamentals
+- [Durable Gates](durable-gates.md) — The `@durablePure` / `@durableGate` / `@durableEffect` classification
+- [JSDoc Grammar](jsdoc-grammar.md) — Formal EBNF syntax for all annotations
+- [Compilation](compilation.md) — How annotations affect code generation
+- [Error Codes](error-codes.md) — Validation errors for annotation issues
+- [CLI Reference](cli-reference.md) — All command flags