docs(readme): lead with the front doors consumers actually use

docs/README.md

@@ -4,7 +4,7 @@ The map of every doc. **Start here** if you're new; the deeper tracks follow.
 
 ## Start here
 
-1. [The README](../README.md) — what the package is, a runnable offline quickstart, and the primitives catalog.
+1. [The README](../README.md) — what the package is, a runnable offline quickstart, and the front-door table.
 2. [concepts.md](./concepts.md) — the mental model (chat turns, tasks, runs) in plain terms.
 3. [canonical-api.md](./canonical-api.md) — find the right primitive: "I want to ___ → use ___".
 4. [../examples/](../examples) — copy a runnable example near your task.
@@ -35,6 +35,8 @@ These are internal working documents: design theses, research narrative, and roa
 | [STABILITY.md](./STABILITY.md) | stability contract | What `@stable` / `@experimental` promise consumers, the graduation bar, and the demotion/removal policy. |
 | [concepts.md](./concepts.md) | mental model | The product-API layer cake (chat turns, tasks, runs) — the onramp before the loop/strategy docs. |
 | [glossary.md](./glossary.md) | canonical vocabulary | One definition per term, grounded to `file:line`; drifted synonyms flagged. |
+| [improve.md](./improve.md) | improvement reference | The `improve()` call, the optimizer object, official GEPA and SkillOpt installs, surfaces, redaction, and the proposal→review→activation path. |
+| [primeintellect.md](./primeintellect.md) | training/eval adapter | Package the same runtime program as a PrimeIntellect Verifiers environment and import its traces back. |
 | [execution-model.md](./execution-model.md) | the picture | The unified `Executor` port (router/bridge/cli/sandbox/BYO) + two engines, driver vs worker, spawn mechanics. |
 | [agent-bus-protocol.md](./agent-bus-protocol.md) | normative protocol | The multi-agent call bus — depth limits, headers, refusal contract. |
 | [durability-adapters.md](./durability-adapters.md) | subsystem | SQL-backed journal and restart behavior for conversations. Supervised-tree recovery is not implemented. |

docs/api/index.md

@@ -8903,7 +8903,8 @@ The spawn label, when the node's `spawned` event is in this journal tree.
 
 > `readonly` `optional` **name?**: `string`
 
-Stable identifier surfaced in trace events. Default `'driver'`.
+Trace label surfaced in trace events. No behavioral effect: it never
+selects a strategy or a decision path. Default `'driver'`.
 
 #### Methods
 
@@ -8933,9 +8934,11 @@ readonly [`Iteration`](runtime.md#iteration-1)\<`Task`, `Output`\>[]
 > **decide**(`history`): `Decision` \| `Promise`\<`Decision`\>
 
 Inspect history and return the next state. The kernel terminates the
-loop when `decide` returns a value listed in `isTerminalDecision`
-(`'stop' | 'pick-winner' | 'fail' | 'done'`), when `maxIterations`
-is hit, or when the abort signal fires.
+loop when `decide` returns a `TerminalDecision`
+(`'stop' | 'pick-winner' | 'fail' | 'done'`, exported as
+`TERMINAL_DECISIONS` with the `isTerminalDecision` guard), when
+`maxIterations` is hit, or when the abort signal fires. Every other
+value is caller vocabulary and continues the loop.
 
 ###### Parameters
 

docs/api/primitive-catalog.md

@@ -525,7 +525,7 @@ Import from `@tangle-network/agent-runtime/intelligence` — 166 exports.
 
 ### Execution kernel — recursive atom, supervision, executors, round-synchronous loop
 
-Import from `@tangle-network/agent-runtime/kernel` — 767 exports.
+Import from `@tangle-network/agent-runtime/kernel` — 770 exports.
 
 | Symbol | Kind | Summary |
 |---|---|---|
@@ -624,6 +624,7 @@ Import from `@tangle-network/agent-runtime/kernel` — 767 exports.
 | `harvestSurfaceDiffs` | function | Re-read every mounted (and watched) surface and report the ones whose settled state differs from |
 | `inlineSandboxClient` | function | Adapt an `ExecutorFactory` into a `SandboxClient` for `runAgentRounds`. The factory is |
 | `inProcessSandboxClient` | function | Adapt a single `onPrompt(prompt, ctx)` callback into a `SandboxClient` for |
+| `isTerminalDecision` | function | True when the kernel stops the loop for this decision value. |
 | `isWaitOutcome` | function | Narrow a settlement's `out` to a wait outcome — a wait settles on the SAME cursor as workers, |
 | `jjWorkspace` | function | A jj-backed `Workspace` (Jujutsu, colocated with git for the durable remote). |
 | `kernelPromptRegistry` | function | The kernel's seeded registry: every surface the runtime's own builders derive from. A caller |
@@ -782,6 +783,7 @@ Import from `@tangle-network/agent-runtime/kernel` — 767 exports.
 | `strategyAuthorContract` | const | The compressed consumable a skill carries: everything an author needs to emit a loop. |
 | `strategyAuthorSystemPrompt` | const | Standing behavior callers put in the strategy-author AgentProfile. |
 | `supervisorPolicyPrompt` | const | THE supervisor policy — one stance, both front doors. The work-vs-delegate rule is conditional |
+| `TERMINAL_DECISIONS` | const | Decision values the kernel treats as terminal. Every other value returned by |
 | `VERIFY_TAIL_CHARS` | const | Tail of the verify output — the failing assertion lives at the END of a test log. |
 | `WORKER_TOOL_TRACE_SCHEMA_VERSION` | const | Schema version for content-addressed worker tool-trace artifacts. |
 | `workerTraceSeamKey` | const | Seam key the `Scope` seeds a {@link TraceContext} under on each child's `ExecutorContext.seams`. |
@@ -1130,6 +1132,7 @@ Import from `@tangle-network/agent-runtime/kernel` — 767 exports.
 | `SupervisorSpanAttributes` | type | OTLP span attribute values. Exported because `SupervisorSpanOptions.attributes` is public and |
 | `SurfaceReader` | type | The read seam: fetch the current bytes at a mounted path. Implemented by a sandbox box's |
 | `SurfaceReadOutcome` | type | Outcome of reading one surface back at settle. `missing: true` means the path no longer exists |
+| `TerminalDecision` | type | One of the kernel's terminal decision values. |
 | `ToolLoopCompactionOptions` | type | Public supervisor-facing compaction config: same knobs as the primitive, but `distill` is optional |
 | `ToolLoopMessageRecord` | type | Provider-neutral conversation record accepted by a tool-loop brain. |
 | `TrajectoryReportFn` | type | `trajectoryReport(...)` — the tree+cost reconstructor. Async (reads journal + optionally blobs). |

docs/api/runtime.md

@@ -19635,6 +19635,16 @@ A checkable task domain — implement these 5 hooks and the suite does the rest.
 
 ***
 
+### TerminalDecision
+
+> **TerminalDecision** = *typeof* [`TERMINAL_DECISIONS`](#terminal_decisions)\[`number`\]
+
+**`Stable`**
+
+One of the kernel's terminal decision values.
+
+***
+
 ### Deliverable
 
 > **Deliverable**\<`Out`\> = \{ `kind`: `"events"`; `fromEvents`: (`events`) => `Out`; \} \| \{ `kind`: `"artifact"`; `path`: `string`; `fromArtifact`: (`raw`, `events`) => `Out`; \}
@@ -21132,6 +21142,19 @@ The default registry `runPersonified` resolves a shape name against. Empty by co
 
 ***
 
+### TERMINAL\_DECISIONS
+
+> `const` **TERMINAL\_DECISIONS**: readonly \[`"stop"`, `"pick-winner"`, `"fail"`, `"done"`\]
+
+**`Stable`**
+
+Decision values the kernel treats as terminal. Every other value returned by
+`decide` continues the loop. Type a driver's `decide` return as
+`'your-word' | TerminalDecision` so caller vocabulary and kernel keywords
+stay visibly distinct.
+
+***
+
 ### strategyAuthorContract
 
 > `const` **strategyAuthorContract**: "\nYou author an OPTIMIZATION STRATEGY for an agentic loop system. A strategy decides how to\nspend a compute budget to beat a task's deployable check. You compose exactly two steps:\n\n  shot(spec?: \{ handle?, messages?, steer?, persona?, tools? \}): Promise\<ShotResult \| null\>\n    Runs ONE worker attempt (a bounded tool loop) over an artifact.\n    - omit handle  =\> the shot opens its OWN fresh artifact and closes it after (a sample).\n    - pass handle  =\> the shot CONTINUES that artifact (state accumulates across shots).\n    - messages     =\> the carried conversation (pass the previous ShotResult.messages to continue).\n    - steer        =\> a corrective instruction injected before the shot.\n    - persona      =\> \{ systemPrompt?, model? \} — give THIS shot its own role and/or model\n      (multi-agent strategies: a researcher shot then an engineer shot, a panel of k\n      personas over one budget). On a fresh shot the systemPrompt replaces the task's; on\n      a carried conversation it arrives as a hand-off message. Same conserved budget.\n    - tools        =\> string\[\] — restrict THIS shot to a subset of the task's tools by\n      name (focus an explore shot on read-only tools, an execute shot on write tools).\n      Restriction-only; unknown names make the shot fail. ALWAYS select from\n      await listTools(handle) — never hardcode. Omitted =\> the shot sees every tool.\n    ShotResult = \{ messages, score (0..1 on the task's check), passes, total, completions, toolErrors \}\n    Returns null if the attempt failed infra-wise.\n\n  critique(messages): Promise\<string \| null\>\n    A firewalled trace-analyst reads the attempt's trajectory and returns ONE corrective\n    instruction (or null when it judges the work complete). Costs ~1 completion.\n\n  consult(messages, instruction): Promise\<string \| null\>\n    The RAW analyst channel: the same firewalled critic answers YOUR instruction over the\n    trajectory verbatim (no reformatting) — use it when you need a specific reply format\n    (a decision, a prediction). Costs ~1 completion.\n\n  surface.open(task) / surface.close(handle)\n    Open a persistent artifact you manage yourself (remember to close in a finally).\n    close is idempotent — closing an already-closed handle is a safe no-op.\n\n  listTools(handle): Promise\<Array\<\{ name, description? \}\>\>\n    The tools THIS task actually offers. TOOL SETS VARY PER TASK — if you restrict a\n    shot with \`tools\`, you MUST pick names from await listTools(handle); hardcoding\n    names from an example kills your shots on every task whose tools differ.\n\nRules:\n- ALWAYS await every shot/critique/surface call — a floating promise that rejects\n  crashes the whole benchmark run.\n- Stay within ~budget total shots; every shot/critique spends from a conserved pool.\n- For a FRESH attempt OMIT \`messages\` entirely (never pass \`\[\]\` — an empty array is a\n  fresh conversation too, but be explicit). To CONTINUE, pass the previous\n  ShotResult.messages unchanged.\n- Return \{ score, resolved, completions, progression, shots \} — score = the BEST checkpoint\n  you reached (keep-best, never final-state), progression = score after each shot.\n- The module must be EXACTLY this shape (no other imports, no commentary outside code):\n\nimport \{ defineStrategy \} from '@tangle-network/agent-runtime/kernel'\nexport default defineStrategy('your-strategy-name', async (\{ surface, task, budget, shot, critique, listTools \}) =\> \{\n  // your composition (listTools comes from the destructured context — it is NOT a global)\n\})\n"
@@ -23270,6 +23293,26 @@ a forked copy).
 
 ***
 
+### isTerminalDecision()
+
+> **isTerminalDecision**(`decision`): decision is "stop" \| "done" \| "pick-winner" \| "fail"
+
+**`Stable`**
+
+True when the kernel stops the loop for this decision value.
+
+#### Parameters
+
+##### decision
+
+`unknown`
+
+#### Returns
+
+decision is "stop" \| "done" \| "pick-winner" \| "fail"
+
+***
+
 ### acquireSandbox()
 
 > **acquireSandbox**(`client`, `options`, `acquire?`): `Promise`\<`SandboxInstance`\>