@falai/agent 2.0.0 → 2.1.0

package/docs/README.md

@@ -1,6 +1,15 @@
+---
+title: "Documentation"
+description: "Typed conversations where code stays in charge. Docs for @falai/agent."
+type: overview
+order: 0
+---
+
 # Documentation
 
-Documentation for `@falai/agent`. The AI understands; the code is in control.
+**Typed conversations where code stays in charge.**
+
+Define flows, steps, and tools in TypeScript; the framework calls the LLM only for the parts that need language — routing, extraction, and generation.
 
 ## New here?
 
@@ -12,7 +21,7 @@ Walk through a five-step tutorial that builds a working agent end to end, from i
 
 Eight task-shaped recipes covering conditions, branching, flow control, instructions, persistence, streaming, errors, and compaction.
 
-[Browse the guides](./guides/)
+[Browse the guides](./guides/conditions.md)
 
 ## Want the why?
 
@@ -24,7 +33,7 @@ Three concept pages that build the mental model: the seven primitives, the per-t
 
 One page per public type. Signatures, field tables, errors, and short runnable examples for `createAgent`, `Flow`, `Step`, `Tool`, `Instruction`, `Directive`, signals, providers, adapters, and more.
 
-[Open the reference](./reference/)
+[Open the reference](./reference/create-agent.md)
 
 ---
 

package/docs/concepts/architecture.md

@@ -1,6 +1,6 @@
 ---
 title: "Architecture"
-description: "The seven primitives of @falai/agent and how they fit together to keep language on the AI's side and decisions on the code's side."
+description: "The six primitives of @falai/agent and how they fit together to keep language on the AI's side and decisions on the code's side."
 type: concept
 order: 1
 ---
@@ -9,11 +9,11 @@ order: 1
 
 > the AI understands, the code is in control
 
-Seven types do all the work. Five are about declaration — what the agent looks like in source. Two are about control — what tools and hooks return at runtime to redirect a turn. This page maps the ownership and reference relationships between them, explains the schema-first principle that makes pre-extraction work, and draws the line between what the AI does and what the code does.
+Six types do all the work. Five are about declaration — what the agent looks like in source. One is about control — what tools and hooks return at runtime to redirect a turn. This page maps the ownership and reference relationships between them, explains the schema-first principle that makes pre-extraction work, and draws the line between what the AI does and what the code does.
 
 LLMs are good at language and unreliable at control flow. They paraphrase well; they do not maintain invariants. They infer intent well; they do not enforce completion gates. The framework's job is to keep the AI on the side of language — understanding intent, extracting structured data, generating prose — while keeping the code on the side of decisions: which flow runs, when a flow completes, what a tool actually does, what state survives a turn.
 
-This page explains the shape of that seam. It names the seven primitives, says what each one is for, and shows how they reference each other. It does not teach syntax. Once the mental model is in place, the [reference](../reference/create-agent.md) pages document the contracts and the [tutorial](../start/01-install.md) walks through the code line by line.
+This page explains the shape of that seam. It names the six primitives, says what each one is for, and shows how they reference each other. It does not teach syntax. Once the mental model is in place, the [reference](../reference/create-agent.md) pages document the contracts and the [tutorial](../start/01-install.md) walks through the code line by line.
 
 ## Core vocabulary
 
@@ -32,9 +32,9 @@ Eight terms cover everything below. Every other term in the docs defines itself
 
 These are the words the rest of the docs use without footnotes. They are also the words the type system uses — every name in the table maps directly to an exported symbol or a generic parameter.
 
-## The seven primitives
+## The six primitives
 
-Seven types do all the work. The first five are about declaration — what the agent looks like in source. The last two are about control — what tools and hooks return at runtime to act on a turn. None of them is novel on its own. The shape of the framework is in how few there are and how cleanly they compose.
+Six types do all the work. The first five are about declaration — what the agent looks like in source. The last one is about control — what tools and hooks return at runtime to act on a turn. None of them is novel on its own. The shape of the framework is in how few there are and how cleanly they compose.
 
 A small illustrative sketch first, just to show the silhouette:
 
@@ -62,7 +62,7 @@ const agent = createAgent({
 });
 ```
 
-Five of the seven primitives appear by name in that block. The remaining two — `Directive` and `PreDirective` — surface only when control flow is on the line, returned from a tool or hook to redirect the conversation.
+Five of the six primitives appear by name in that block. The remaining one — `Directive` — surfaces only when control flow is on the line, returned from a tool or hook to redirect the conversation.
 
 ### Agent
 
@@ -96,19 +96,15 @@ An instruction owns its rendered position in the prompt. The composer renders ea
 
 ### Directive
 
-A `Directive<TContext, TData>` is a flat object literal — not a class, not a builder, not a discriminated union — that any tool, hook, or branch returns to act on the turn. Every field is optional. A directive carries up to four orthogonal payloads: at most **one position field** (`goTo`, `goToStep`, `complete`, `abort`, or `reset`), zero or one **verbatim reply**, optional **state writes** (`dataUpdate` / `contextUpdate`), and optional `reason` strings inside object forms for traceability. The flatness is intentional — earlier drafts modeled directives as a discriminated union, but a flat object composes more naturally when a single decision point needs to write state, change position, and speak verbatim in one return value.
+A `Directive<TContext, TData>` is a flat object literal — not a class, not a builder, not a discriminated union — that any tool, hook, or branch returns to act on the turn. Every field is optional. A directive carries up to four orthogonal payloads: at most **one position field** (`goTo`, `goToStep`, `complete`, `abort`, or `reset`), zero or one **verbatim reply**, optional **state writes** (`dataUpdate` / `contextUpdate`), and optional **pre-LLM augmentation** (`appendPrompt`, `injectTools`, `halt`) plus optional `reason` strings inside object forms for traceability. The flatness is intentional — earlier drafts modeled directives as a discriminated union, but a flat object composes more naturally when a single decision point needs to write state, change position, and speak verbatim in one return value.
 
-The directive is the single language the framework speaks for control flow. A tool that decides "this user is ineligible" returns `{ goTo: "denial", reply: "Sorry — you don't qualify." }`. A finalize hook that finishes a booking returns `{ complete: true, dataUpdate: { bookingId } }`. A signal that detects an off-topic user returns a pre-phase directive with `halt + reply`. All of these merge through one algorithm — position fields by precedence, state writes shallow-merged, `reply` last-wins — implemented as `flow.merge(a, b)` and applied uniformly across the turn pipeline. Multiple emissions in the same turn (a tool dispatching mid-handler, then a finalize hook returning) collapse into a single applied directive at the phase boundary.
+The directive is the single language the framework speaks for control flow. A tool that decides "this user is ineligible" returns `{ goTo: "denial", reply: "Sorry — you don't qualify." }`. A finalize hook that finishes a booking returns `{ complete: true, dataUpdate: { bookingId } }`. A prepare hook that detects a VIP returns `{ appendPrompt: ["This caller is VIP — confirm preferences first."] }`. All of these merge through one algorithm — position fields by precedence, state writes shallow-merged, `reply` last-wins — implemented as `flow.merge(a, b)` and applied uniformly across the turn pipeline.
 
-### PreDirective
-
-A `PreDirective<TContext, TData>` extends `Directive` with three fields that only make sense before the turn's LLM call: `appendPrompt` (sentences added to this turn's system prompt), `injectTools` (tools added to this turn's available list), and `halt` (skip the LLM call entirely). It is the return type of `onEnter` and `prepare` hooks. Lifetime is one turn; PreDirective fields never persist into `session.pendingDirective`.
-
-A pre-directive owns the per-turn shaping slots in the prompt composer and the tool manager. `appendPrompt` flows into a transient appendage slot — never cached, never persisted, recomputed every turn. `injectTools` flows into a transient tool layer that stacks on top of step → flow → agent scopes. `halt` is the kill switch: when set, the engine skips the model, and if `reply` is also set the verbatim string becomes the assistant message. PreDirective is also the parent of the v2.x `SignalDirective` — the signals primitive adds two further fields on top of this exact shape, so signal handlers participate in the same merge algorithm as everything else.
+The three pre-LLM fields (`appendPrompt`, `injectTools`, `halt`) have a one-turn lifetime: they only take effect in pre-LLM hooks (`onEnter`, `prepare`). When emitted from post-LLM hooks or persisted to `session.pendingDirective`, they are ignored with a WARN log. This keeps one type for all emitters while the engine enforces the phase boundary at runtime.
 
 ## Supporting concepts
 
-The seven primitives carry the weight. Four supporting pieces make them ergonomic.
+The six primitives carry the weight. Four supporting pieces make them ergonomic.
 
 ### `flow` namespace
 
@@ -164,7 +160,7 @@ Branches are also the place where the AI/code split is most visible at the call
 
 ## How the primitives reference each other
 
-The diagram below maps the ownership and reference relationships between the seven primitives and the two state surfaces. Solid arrows are ownership. Dashed lines are scoping or extension. The two state nodes (`Schema` and `Context`) are not primitives — they are the typed surfaces the primitives operate on, drawn at the bottom because everything else references them.
+The diagram below maps the ownership and reference relationships between the six primitives and the two state surfaces. Solid arrows are ownership. Dashed lines are scoping or extension. The two state nodes (`Schema` and `Context`) are not primitives — they are the typed surfaces the primitives operate on, drawn at the bottom because everything else references them.
 
 ```mermaid
 graph TB
@@ -186,26 +182,23 @@ graph TB
   Step -.scoped.- Tool
   Step -.scoped.- Instruction
   Step -->|branches| Step
-  Step -->|onEnter / prepare| PreDirective
+  Step -->|onEnter / prepare| Directive
   Step -->|finalize| Directive
 
   Tool -->|ctx.dispatch| Directive
   Tool -->|ToolResult.directive| Directive
 
-  PreDirective -.extends.-> Directive
-
   Directive -.merged via.-> FlowNS[flow.merge]
-  PreDirective -.validated via.-> FlowNS
 
   classDef primitive fill:#1e293b,stroke:#0ea5e9,color:#fff;
   classDef state fill:#0f172a,stroke:#64748b,color:#cbd5e1;
-  class Agent,Flow,Step,Tool,Instruction,Directive,PreDirective primitive;
+  class Agent,Flow,Step,Tool,Instruction,Directive primitive;
   class Schema,Context state;
 ```
 
-Read it top-down. The agent owns flows, tools, and instructions, and binds them to a single schema and a single context type. A flow owns steps and may scope its own instructions and tools. A step references the schema through `collect` and `requires`, may carry its own scoped instructions and tools, and may fork via `branches` into another step. Hooks and tools emit directives — pre-LLM hooks emit `PreDirective` (the extension), post-LLM hooks and tools emit plain `Directive`. The `flow` namespace validates and merges them.
+Read it top-down. The agent owns flows, tools, and instructions, and binds them to a single schema and a single context type. A flow owns steps and may scope its own instructions and tools. A step references the schema through `collect` and `requires`, may carry its own scoped instructions and tools, and may fork via `branches` into another step. Hooks and tools emit directives — pre-LLM hooks use the pre-LLM fields (`appendPrompt`, `injectTools`, `halt`), post-LLM hooks use position/state/reply fields. The `flow` namespace validates and merges them.
 
-The two state types — `Schema` for `TData`, `Context` for `TContext` — sit at the bottom because everything else points at them. They are not primitives in the same sense as the seven types; they are the typed surfaces those primitives operate on, and they are owned by the agent.
+The two state types — `Schema` for `TData`, `Context` for `TContext` — sit at the bottom because everything else points at them. They are not primitives in the same sense as the six types; they are the typed surfaces those primitives operate on, and they are owned by the agent.
 
 Two things are deliberately absent from this diagram. There is no separate "router" primitive — flow selection is an internal pipeline phase, not a user-facing type. There is no separate "session" primitive in the declaration model — sessions are runtime state, indexed by `sessionId`, persisted by adapters, but not something application code constructs as a building block. Both of those concerns live in the [turn pipeline](./pipeline.md), where they are explained as steps in the per-turn sequence rather than parts of the static structure.
 
@@ -241,9 +234,9 @@ There is no implicit messaging. The framework never emits a message of its own.
 
 There is no glossary. Eight terms are defined in the callout at the top of this page, and every other term in the docs defines itself at first use on the page that introduces it. The framework's surface is small enough that a glossary would duplicate prose without adding clarity.
 
-## Why seven primitives
+## Why six primitives
 
-The set of seven is the result of a few specific cuts. Each one collapsed a category of duplication into a single shape, and each one is worth naming for its own sake — not for migration purposes (the [migration guide](../migration/v1-to-v2.md) covers that), but because the surface visible today is the result of those choices.
+The set of six is the result of a few specific cuts. Each one collapsed a category of duplication into a single shape, and each one is worth naming for its own sake — not for migration purposes (the [migration guide](../migration/v1-to-v2.md) covers that), but because the surface visible today is the result of those choices.
 
 **One word per concept.** The verb form `route()` is still the act of selecting a flow, and "routing" is still the gerund — but the noun for "a single conversational goal" is **Flow**. The system that selects one is the **FlowRouter**. There is no overlap between the noun and the verb, which keeps the surface readable when the two appear in the same sentence.
 
@@ -251,7 +244,7 @@ The set of seven is the result of a few specific cuts. Each one collapsed a cate
 
 **One Tool with optional metadata.** A `Tool` is a single interface. The simple case is `{ id, handler }`. The production case adds `validateInput`, `checkPermissions`, `isReadOnly`, `isConcurrencySafe`, `isDestructive`, and `maxResultSizeChars` — every one optional. There is no upgrade boundary mid-codebase: a tool that starts as a plain function adds metadata fields when it needs them, without changing type or import. The executor reads each field defensively (undefined falls back to safe defaults), so the same tool runs identically with two metadata fields or zero.
 
-The remaining four primitives — Agent, Step, Directive, PreDirective — were always single-shape concepts. The seven-primitive count is what survives those three consolidations plus the four that stood on their own.
+The remaining four primitives — Agent, Step, Flow, Directive — were always single-shape concepts. The six-primitive count is what survives those three consolidations plus the three that stood on their own.
 
 ## Construction shape
 
@@ -274,7 +267,7 @@ The construction shape encodes the ownership tree: an agent owns flows, tools, a
 
 ## What's next
 
-The next page walks through what happens when `agent.respond(message)` is called: the per-turn pipeline, resolution precedence (`pendingDirective` first, then signals + routing in parallel, then auto-step chains, then branches, then linear succession), the directive bus, and how `flow.merge` collapses simultaneous emissions into a single applied directive. After that, the [Directives](./directives.md) page goes deeper into the directive shape itself — why it is flat, how the inheritance chain `Directive → PreDirective → SignalDirective` works, and what each field does.
+The next page walks through what happens when `agent.respond(message)` is called: the per-turn pipeline, resolution precedence (`pendingDirective` first, then signals + routing in parallel, then auto-step chains, then branches, then linear succession), the directive bus, and how `flow.merge` collapses simultaneous emissions into a single applied directive. After that, the [Directives](./directives.md) page goes deeper into the directive shape itself — why it is flat, how `SignalDirective` extends it for signals, and what each field does.
 
 If the goal right now is to write code, the [tutorial](../start/01-install.md) starts from a one-line install and arrives at a working agent in five short pages. If the goal is to look up an exact contract, every primitive on this page has a [reference](../reference/create-agent.md) page with the full TypeScript declaration, a fields table, two short examples, and the typed errors it can throw.
 

package/docs/concepts/directives.md

@@ -20,10 +20,8 @@ emitters, one shape.
 
 This page explains why the shape is flat, what each field does, how
 they merge when more than one handler emits during the same turn, and
-how `Directive`, `PreDirective`, and `SignalDirective` form the
-inheritance chain that lets pre-LLM hooks and signals add capability
-without adding a parallel type system. The page is conceptual — the
-[directive reference](../reference/directive.md) carries the
+how `Directive` and `SignalDirective` relate. The page is conceptual —
+the [directive reference](../reference/directive.md) carries the
 field-by-field contract.
 
 ## Why a flat shape
@@ -70,9 +68,9 @@ algorithm answers once.
 **Composable.** A directive carries up to four orthogonal payloads
 without forcing them into a hierarchy: at most one position field,
 optional state writes (`dataUpdate` / `contextUpdate`), an optional
-verbatim `reply`, and on `PreDirective` an optional set of pre-LLM
-augmentations. `dataUpdate` works alongside `goTo`. `reply` works
-alongside `complete`. A booking tool's success result writes the
+verbatim `reply`, and optional pre-LLM augmentations (`appendPrompt`,
+`injectTools`, `halt`). `dataUpdate` works alongside `goTo`. `reply`
+works alongside `complete`. A booking tool's success result writes the
 booking id and finishes the flow in one return value:
 `{ complete: true, dataUpdate: { bookingId } }`. A bridge utterance
 at a flow boundary writes nothing and only speaks: `{ reply: "Let me
@@ -186,26 +184,24 @@ LLM for the conversation.
 
 `reply` co-validates with two other fields. With **`abort`**, it is
 rejected at validation — an aborted conversation cannot deliver a
-reply. With **`halt: true`** (a `PreDirective` field, see below), it
-is the assistant message and the turn ends with
-`stoppedReason: 'reply'`; if `halt` is set without `reply`, the turn
-ends with `stoppedReason: 'halt'` and an empty body. Across multiple
-emitters in the same turn, `reply` is **last-wins** — the most
-recent emission overrides earlier ones, with a debug log so the
-override is visible in the trace.
-
-`reply` is the same shape on `Directive` and on `PreDirective` —
-there is no separate "speak before the LLM" vs "speak after the
-LLM" type. The phase the directive runs in determines whether the
-reply replaces a message that would have been generated (pre-LLM) or
-replaces one that just was (post-LLM). The field stays the same.
-
-## PreDirective fields
-
-`PreDirective` is the `Directive` variant that pre-LLM hooks return.
-It inherits every base field — position writes, state writes,
-`reply` — and adds three more that only make sense before this turn's
-LLM call: `appendPrompt`, `injectTools`, and `halt`.
+reply. With **`halt: true`**, it is the assistant message and the
+turn ends with `stoppedReason: 'reply'`; if `halt` is set without
+`reply`, the turn ends with `stoppedReason: 'halt'` and an empty
+body. Across multiple emitters in the same turn, `reply` is
+**last-wins** — the most recent emission overrides earlier ones,
+with a debug log so the override is visible in the trace.
+
+`reply` works the same regardless of which phase emits it. The phase
+determines whether the reply replaces a message that would have been
+generated (pre-LLM) or replaces one that just was (post-LLM).
+
+## Pre-LLM-only fields
+
+Three fields on `Directive` only take effect in pre-LLM hooks
+(`onEnter`, `prepare`). When emitted from post-LLM hooks (`finalize`,
+`onComplete`) or persisted to `session.pendingDirective`, they are
+**ignored with a WARN log** — a visible signal in your logs that
+says "hey, this did nothing here."
 
 **`appendPrompt: string[]`** is the prompt nudge slot. Each string is
 a sentence the prompt composer appends to the system prompt for this
@@ -236,15 +232,13 @@ halt the turn. The field is the framework's circuit breaker: a hook
 that detects an unresolvable state can stop the turn outright
 without competing with other emitters.
 
-The three `PreDirective`-only fields are stripped from
-`session.pendingDirective` before persistence — `pendingDirective`
-holds a plain `Directive`, and the augmentation fields cannot survive
-across turns by design. If a post-LLM hook returns a `PreDirective`
-with these fields set, they are dropped with a debug warning: an
-`appendPrompt` after the fact has no prompt to append to, an
-`injectTools` after the fact has no LLM call to inject into, and a
-`halt` after the fact has no LLM call to halt. The remaining base
-`Directive` portion is honored.
+These fields are stripped from `session.pendingDirective` before
+persistence — they cannot survive across turns by design. If a
+post-LLM hook returns a directive with these fields set, they are
+dropped with a WARN log: an `appendPrompt` after the fact has no
+prompt to append to, an `injectTools` after the fact has no LLM call
+to inject into, and a `halt` after the fact has no LLM call to halt.
+The remaining fields are honored normally.
 
 `appendPrompt` is concatenated across emitters in emission order
 without deduplication — duplicate sentences from different sources
@@ -252,22 +246,18 @@ are preserved (a flow-level "be polite" plus a step-level "be polite"
 is acceptable redundancy). `injectTools` is concatenated and then
 deduped by `Tool.id`, with the later definition winning — typically a
 step-level injection overriding a flow-level default. `halt` is
-logical-OR. The merge rules for the inherited base fields stay
-identical: position fields by precedence, `reply` last-wins, state
-writes shallow-merged.
+logical-OR. The merge rules for the base fields stay identical:
+position fields by precedence, `reply` last-wins, state writes
+shallow-merged.
 
-## The inheritance chain
+## SignalDirective
 
-`Directive` is the base. `PreDirective` extends it with the three
-pre-LLM-only fields. `SignalDirective` extends `PreDirective` further
-with two signal-specific fields. The chain is one direction —
-capabilities accumulate as you go down — and each level is the return
-type of a specific class of emitter:
+`SignalDirective` extends `Directive` with two signal-pipeline-specific
+fields: `stopOtherSignals` and `replyWith`.
 
 ```mermaid
 classDiagram
-    Directive <|-- PreDirective
-    PreDirective <|-- SignalDirective
+    Directive <|-- SignalDirective
 
     class Directive {
         +goTo? string | object
@@ -278,9 +268,6 @@ classDiagram
         +reply? string
         +dataUpdate? Partial~TData~
         +contextUpdate? Partial~TContext~
-    }
-
-    class PreDirective {
         +appendPrompt? string[]
         +injectTools? Tool[]
         +halt? boolean
@@ -291,41 +278,25 @@ classDiagram
         +replyWith? string | function
     }
 
-    note for Directive "Returned by tools, finalize hooks, branches.\nPersistable as session.pendingDirective."
-    note for PreDirective "Returned by prepare hooks, onEnter hooks.\nTransient — one-turn lifetime."
-    note for SignalDirective "Returned by signals (pre / post / both phases)."
+    note for Directive "One type for all hooks, tools, and branches.\nPre-LLM fields ignored with WARN log outside pre-LLM hooks."
+    note for SignalDirective "Returned by signal handlers (pre / post / both phases)."
 ```
 
-`Directive` is what tools (return value or `ctx.dispatch`), `finalize`
-hooks, `flow.hooks.onComplete`, and branch `then` targets return. It
-is plain JSON-serializable data — the same shape that sits on the
-session as `pendingDirective` and crosses the persistence boundary.
-
-`PreDirective` is what `flow.hooks.onEnter`, `step.hooks.onEnter`,
-and `step.hooks.prepare` return. The three augmentation fields and a
-live `Tool[]` reference make it non-serializable; the type system
-encodes the one-turn lifetime by being a structurally separate type
-that the engine strips before persistence.
-
 `SignalDirective` is what signal handlers return — pre-phase
 handlers, post-phase handlers, and `both`-phase handlers all use the
-same type. The two added fields are signal-pipeline-specific:
-`stopOtherSignals` skips remaining handlers in the same phase (it is
-consumed inside the signal pipeline, not the directive bus), and
+same type. `stopOtherSignals` skips remaining handlers in the same
+phase (consumed inside the signal pipeline, not the directive bus).
 `replyWith` is a late-binding `reply` that accepts a function form
 evaluated at emit time. Phase semantics still apply: when a
-`SignalDirective` runs in the post-phase, the inherited `appendPrompt`
-/ `injectTools` / `halt` fields are dropped (they have no meaning
-after the LLM call) and inherited position fields set
-`pendingDirective` for the *next* turn rather than redirecting this
-one.
-
-The three types share one merge algorithm and one validation pass.
-A pre-phase signal can dispatch a `SignalDirective`, a `prepare` hook
-can return a `PreDirective`, and the engine merges them through the
-same `flow.merge` that handles tool directives — the inheritance
-chain exists to widen the type at the call site without splitting the
-runtime.
+`SignalDirective` runs in the post-phase, `appendPrompt` /
+`injectTools` / `halt` are dropped (they have no meaning after the
+LLM call) and position fields set `pendingDirective` for the *next*
+turn rather than redirecting this one.
+
+Both types share one merge algorithm and one validation pass. A
+pre-phase signal can dispatch a `SignalDirective`, a `prepare` hook
+can return a `Directive`, and the engine merges them through the same
+`flow.merge`.
 
 ## The `flow` namespace
 
@@ -358,9 +329,8 @@ within the same tier), `reply` is last-wins, `dataUpdate` and
 `contextUpdate` shallow-merge in emission order, `appendPrompt`
 concatenates without deduplication, `injectTools` concatenates and
 then dedupes by `Tool.id` (later definition wins), and `halt` is
-logical-OR. The function is generic in the shared subtype: merging
-two `PreDirective`s yields a `PreDirective`, merging two plain
-`Directive`s yields a `Directive`.
+logical-OR. The function is generic: merging two `Directive`s yields
+a `Directive`.
 
 `flow.validate(d)` enforces three structural invariants and throws
 `FlowConfigurationError` when any fails: at most one position field
@@ -384,8 +354,7 @@ small.
 The directive's mental model is in this page; the field-by-field
 contract — every position field's shorthand and object form, every
 state-write rule, every typed error the validator can throw — is in
-the [Directive reference](../reference/directive.md). The pre-LLM
-extras have their own [PreDirective reference](../reference/pre-directive.md).
+the [Directive reference](../reference/directive.md).
 The signal-specific additions live in [Signals](../reference/signals.md).
 
 When the goal is to *use* directives in handlers, the

package/docs/concepts/pipeline.md

@@ -174,7 +174,7 @@ Sources, in fixed order:
 4. `step.hooks.prepare`
 5. Any `ctx.dispatch` calls made inside the above hooks
 
-These return `PreDirective` — the same shape as `Directive` plus the
+These return `Directive` — with the pre-LLM fields
 three pre-LLM-only fields (`appendPrompt`, `injectTools`, `halt`). The
 merged result feeds the prompt composer and tool manager before the
 LLM call:
@@ -199,7 +199,7 @@ Sources, in fixed order:
 5. The `then` branch of any matched `step.branches` entry whose `then`
    was a full `Directive` (not just a step id)
 
-These return plain `Directive`. PreDirective-only fields here are
+These return `Directive`. Pre-LLM-only fields here are
 dropped with a debug warning — `halt` after the fact has no meaning,
 and `appendPrompt` / `injectTools` could not influence a call that
 has already happened.
@@ -222,7 +222,7 @@ the persistence boundary.
 ## Algorithm 4 — merge rules
 
 When the bus has more than one directive in a phase, the pipeline
-folds them into a single `Directive` (or `PreDirective` in the pre-LLM
+folds them into a single `Directive` (with pre-LLM fields honored in the pre-LLM
 phase) using the following rules. Same rules in both phases; the
 pre-LLM phase additionally folds the three augmentation fields.
 
@@ -392,7 +392,7 @@ elides:
 The pipeline is the *what happens*. The directive is the *how
 handlers ask for things to happen*. The next concept page covers the
 flat shape, the position field rules, the inheritance chain
-`Directive → PreDirective → SignalDirective`, and the `flow`
+`Directive → SignalDirective`, and the `flow`
 namespace helpers (`flow.isDirective`, `flow.merge`, `flow.validate`)
 that make the bus introspectable from user code.
 

package/docs/guides/flow-control.md

@@ -237,18 +237,19 @@ payloads — `reply`, `dataUpdate`, and the position field don't
 compete for the same slot.
 
 To skip the LLM **before** it runs (rather than from a finalize hook
-*after*), use a [`PreDirective`](../reference/pre-directive.md) from
-a prepare hook with `halt: true` — see below.
+*after*), return a `Directive` from a prepare hook with `halt: true`
+— see below.
 
-## PreDirective extras (pre-LLM only)
+## Pre-LLM fields (pre-LLM hooks only)
 
 Pre-LLM hooks (`flow.hooks.onEnter`, `step.hooks.onEnter`,
-`step.hooks.prepare`) return a [`PreDirective`](../reference/pre-directive.md) —
-the `Directive` variant with three extra fields that only make sense
-before this turn's LLM call.
+`step.hooks.prepare`) return a `Directive` — the same type as
+post-LLM hooks, but with three fields that only take effect before
+this turn's LLM call.
 
 ```typescript
-interface PreDirective extends Directive {
+interface Directive {
+  // ...all position/state/reply fields...
   appendPrompt?: string[];
   injectTools?: Tool[];
   halt?: boolean;
@@ -257,8 +258,8 @@ interface PreDirective extends Directive {
 
 Lifetime is one turn. None of the three fields persist on
 `session.pendingDirective` — they're stripped before the write.
-Returning a PreDirective from a post-LLM hook drops these fields with
-a debug log.
+Returning a Directive with these fields from a post-LLM hook ignores
+them with a WARN log.
 
 ### `appendPrompt` — nudge the system prompt
 
@@ -349,7 +350,7 @@ await agent.dispatch({ goTo: "Billing", reply: "Transferring you now." }, sessio
 
 The call validates the directive (`flow.validate`), confirms any
 `goTo`-named flow exists (throws `FlowConfigurationError` if not),
-strips PreDirective-only fields, writes `pendingDirective` onto the
+strips pre-LLM-only fields, writes `pendingDirective` onto the
 session, and persists if an adapter is configured.
 
 `pendingDirective` is **single-shot** — consumed exactly once and
@@ -375,7 +376,7 @@ Where to emit:
 |----------------|------|-----|
 | Tool handler, mid-flight | `Directive` | `ctx.dispatch(d)` |
 | Tool handler, on return | `Directive` | `return { data, directive: d }` |
-| `prepare` / `onEnter` hook | `PreDirective` | `return d` |
+| `prepare` / `onEnter` hook | `Directive` | `return d` (pre-LLM fields honored) |
 | `finalize` / `onComplete` hook | `Directive` | `return d` |
 | Branch `then` target | `Directive` | `then: d` (see [Branching](./branching.md)) |
 | Outside a turn (webhook, job) | `Directive` | `await agent.dispatch(d, session)` |
@@ -397,8 +398,6 @@ Code or model speaking:
 
 - [Directive reference](../reference/directive.md) — every field,
   every shorthand, every validation rule.
-- [PreDirective reference](../reference/pre-directive.md) —
-  pre-LLM-only fields and merge rules.
 - [Directives concept](../concepts/directives.md) — the mental model
   and the inheritance chain.
 - [Branching](./branching.md) — when the redirect is source-local

package/docs/guides/streaming.md

@@ -85,7 +85,7 @@ for await (const chunk of agent.respondStream({ history })) {
 
 If you need finer-grained tool telemetry — which tool fired, with what arguments — read `chunk.toolCalls` on the terminal chunk. It mirrors the same field on the non-streaming `AgentResponse`. For per-tool progress UI, attach observability to the [tool's `handler`](../reference/tool.md) directly; the streaming chunk shape stays clean.
 
-When a step uses [verbatim `reply`](../reference/step.md) or a [`halt` directive](../reference/pre-directive.md), the engine skips the LLM entirely and yields a single chunk with `done: true` and the full text in `accumulated`. The renderer above handles that case without a special branch — there is just no spinner gap.
+When a step uses [verbatim `reply`](../reference/step.md) or a `halt` directive, the engine skips the LLM entirely and yields a single chunk with `done: true` and the full text in `accumulated`. The renderer above handles that case without a special branch — there is just no spinner gap.
 
 ## The terminal chunk
 

package/docs/migration/README.md

@@ -1,15 +1,14 @@
-# Migration
-
-Migration guides for upgrading `@falai/agent`.
+---
+title: "Migration"
+description: "Migration guides for upgrading @falai/agent from v1 to v2."
+type: overview
+order: 99
+---
 
-## v1 → v2
+# Migration
 
-Use this guide when upgrading from any `1.x` release to `2.0`. It covers every breaking change in v2, with rename tables and before/after code.
+Upgrading from `1.x`? The consolidated migration guide covers every breaking change in v2 — including the Route → Flow rename, the Instruction unification, the Tool merge, and the Directive collapse — with rename tables, per-adapter schema migrations, and before/after code for each section.
 
 [Read the v1 → v2 migration guide](./v1-to-v2.md)
 
-## Route → Flow rename
-
-Use this guide if you are landing the minor release that ships just before `2.0`, which renames the `Route` domain noun to `Flow` across symbols, config, and persistence.
-
-[Read the Route → Flow guide](./route-to-flow.md)
+Section 3 covers the Route → Flow rename in full, including per-adapter SQL/Mongo/Redis/OpenSearch migration snippets and ID-prefix guidance.