@orkestrel/toolbox 0.0.12 → 0.0.14

package/dist/src/core/index.d.cts

@@ -1,55 +1,56 @@
-import { AgentInterface } from '@orkestrel/agent';
-import { AgentRegistryInterface } from '@orkestrel/agent';
+import type { AgentInterface } from '@orkestrel/agent';
+import type { AgentRegistryInterface } from '@orkestrel/agent';
 import { ArrayShape } from '@orkestrel/contract';
 import { BooleanShape } from '@orkestrel/contract';
-import { Condition } from '@orkestrel/database';
-import { ConditionConnector } from '@orkestrel/database';
-import { ContractInterface } from '@orkestrel/contract';
-import { ContractShape } from '@orkestrel/contract';
-import { ConversationStoreInterface } from '@orkestrel/agent';
-import { DatabaseErrorCode } from '@orkestrel/database';
-import { DatabaseInterface } from '@orkestrel/database';
-import { DriverInterface } from '@orkestrel/database';
-import { Include } from '@orkestrel/relation';
-import { IndexMap } from '@orkestrel/database';
+import type { Condition } from '@orkestrel/database';
+import type { ConditionConnector } from '@orkestrel/database';
+import type { ContractInterface } from '@orkestrel/contract';
+import type { ContractShape } from '@orkestrel/contract';
+import type { ConversationStoreInterface } from '@orkestrel/agent';
+import type { DatabaseErrorCode } from '@orkestrel/database';
+import type { DatabaseInterface } from '@orkestrel/database';
+import type { DriverInterface } from '@orkestrel/database';
+import type { Include } from '@orkestrel/relation';
+import type { IndexMap } from '@orkestrel/database';
 import { JSONShape } from '@orkestrel/contract';
-import { KeyFunction } from '@orkestrel/database';
-import { LifecycleStatus } from '@orkestrel/workflow';
+import type { KeyFunction } from '@orkestrel/database';
+import type { LifecycleStatus } from '@orkestrel/workflow';
 import { LiteralShape } from '@orkestrel/contract';
-import { ModelInterface } from '@orkestrel/relation';
+import type { ModelInterface } from '@orkestrel/relation';
 import { NumberShape } from '@orkestrel/contract';
 import { ObjectShape } from '@orkestrel/contract';
 import { OptionalShape } from '@orkestrel/contract';
-import { OrderDirection } from '@orkestrel/database';
-import { PrimaryMap } from '@orkestrel/database';
-import { QueryInput } from '@orkestrel/database';
-import { RelationErrorCode } from '@orkestrel/relation';
-import { RelationManagerInterface } from '@orkestrel/relation';
+import type { OrderDirection } from '@orkestrel/database';
+import type { PrimaryMap } from '@orkestrel/database';
+import type { QueryInput } from '@orkestrel/database';
+import type { RelationErrorCode } from '@orkestrel/relation';
+import type { RelationManagerInterface } from '@orkestrel/relation';
 import { StringShape } from '@orkestrel/contract';
-import { TableInterface } from '@orkestrel/database';
-import { TableMap } from '@orkestrel/database';
-import { TerminalManagerInterface } from '@orkestrel/terminal';
-import { ToolInterface } from '@orkestrel/tool';
-import { ToolManagerInterface } from '@orkestrel/tool';
+import type { TableInterface } from '@orkestrel/database';
+import type { TableMap } from '@orkestrel/database';
+import type { TerminalManagerInterface } from '@orkestrel/terminal';
+import type { ToolContext } from '@orkestrel/tool';
+import type { ToolInterface } from '@orkestrel/tool';
+import type { ToolManagerInterface } from '@orkestrel/tool';
 import { UnionShape } from '@orkestrel/contract';
-import { WorkflowDefinition } from '@orkestrel/workflow';
-import { WorkflowFault } from '@orkestrel/workflow';
-import { WorkflowFunction } from '@orkestrel/workflow';
-import { WorkflowRegistry } from '@orkestrel/workflow';
-import { WorkflowResult } from '@orkestrel/workflow';
-import { WorkflowRunnerInterface } from '@orkestrel/workflow';
-import { WorkflowStoreInterface } from '@orkestrel/workflow';
-import { WorkspaceManagerInterface } from '@orkestrel/workspace';
-import { WorkspaceStoreInterface } from '@orkestrel/workspace';
+import type { WorkflowDefinition } from '@orkestrel/workflow';
+import type { WorkflowFault } from '@orkestrel/workflow';
+import type { WorkflowFunction } from '@orkestrel/workflow';
+import type { WorkflowRegistry } from '@orkestrel/workflow';
+import type { WorkflowResult } from '@orkestrel/workflow';
+import type { WorkflowRunnerInterface } from '@orkestrel/workflow';
+import type { WorkflowStoreInterface } from '@orkestrel/workflow';
+import type { WorkspaceManagerInterface } from '@orkestrel/workspace';
+import type { WorkspaceStoreInterface } from '@orkestrel/workspace';
 
 /**
  * Holds the maximum nesting depth a delegation chain (agent tool → sub-agent → agent tool → …) may
- * reach — the bound {@link import('./factories.js').createAgentTool}'s depth/cycle guard
+ * reach, `8` — the bound {@link import('./factories.js').createAgentTool}'s depth/cycle guard
  * enforces.
  *
  * @remarks
- * Deliberately a SEPARATE constant from {@link MAX_WORKFLOW_CHAIN} (rather than the two guards
- * sharing one reference): the two guards bound DIFFERENT chains (workflow nesting vs. agent
+ * Deliberately a separate constant from {@link MAX_WORKFLOW_CHAIN} (rather than the guards
+ * sharing one reference): they bound different chains (workflow nesting against agent
  * delegation) that happen to share a value today, and keeping this bound decoupled means a
  * future change to one never silently shifts the other. Same numeric value by convention, not
  * by shared reference.
@@ -63,17 +64,21 @@ export declare const AGENT_TOOL_DEPTH = 8;
 export declare const AGENT_TOOL_DESCRIPTION: string;
 
 /**
- * Holds the name {@link import('./factories.js').createAgentTool} advertises by default — the key a
- * model calls and the `ToolManagerInterface` (`@orkestrel/tool`) registers under.
+ * Holds the name {@link import('./factories.js').createAgentTool} advertises by default, `'agent'`
+ * — the key a model calls and the `ToolManagerInterface` (`@orkestrel/tool`) registers under.
  */
 export declare const AGENT_TOOL_NAME = "agent";
 
 /**
- * Holds the lean {@link import('@orkestrel/tool').ToolInterface.summary} {@link import('./factories.js').createAgentTool}
- * advertises in place of {@link AGENT_TOOL_DESCRIPTION} — a `ToolManagerInterface.definitions()`
- * (`@orkestrel/tool`) advertises `summary ?? description`, so this one-sentence text stands in
- * for the full teaching description; the full text stays retrievable through
- * {@link import('./factories.js').createDescribeTool}.
+ * Holds the lean {@link import('@orkestrel/tool').ToolInterface.summary}
+ * {@link import('./factories.js').createAgentTool} advertises in place of
+ * {@link AGENT_TOOL_DESCRIPTION} — one sentence offering sub-agent delegation and pointing at
+ * `describe` for the optional overrides.
+ *
+ * @remarks
+ * A `ToolManagerInterface.definitions()` call (`@orkestrel/tool`) advertises
+ * `summary ?? description`, so this one-sentence text stands in for the full teaching description;
+ * the full text stays retrievable through {@link import('./factories.js').createDescribeTool}.
  */
 export declare const AGENT_TOOL_SUMMARY = "Delegate a task to a sub-agent and return its result; each call runs one sub-agent turn to completion. Call describe('agent') for the optional provider/tools/system overrides.";
 
@@ -84,9 +89,9 @@ export declare type AgentFunction = WorkflowFunction & {
 };
 
 /**
- * Represents the options for {@link import('./factories.js').createAgentFunction} — the OPT-IN adapter that
- * wraps a live `AgentInterface` (`@orkestrel/agent`) as an {@link AgentFunction} with immutable
- * lineage metadata and optional nested-workflow composition.
+ * Represents the options for {@link import('./factories.js').createAgentFunction} — the opt-in
+ * adapter that wraps a live `AgentInterface` (`@orkestrel/agent`) as an {@link AgentFunction} with
+ * immutable lineage metadata and optional nested-workflow composition.
  *
  * @remarks
  * All fields are optional. An empty lineage is resolved from the controller's root workflow when
@@ -109,14 +114,14 @@ export declare interface AgentFunctionOptions {
 }
 
 /**
- * Represents the FLAT args {@link import('./factories.js').createAgentTool} accepts — a delegated `task`
- * plus the minimal optional `AgentJobInput` (`@orkestrel/agent`) fields a caller may override
- * per-call.
+ * Represents the flat args {@link import('./factories.js').createAgentTool} accepts — a delegated
+ * `task` plus the minimal optional `AgentJobInput` (`@orkestrel/agent`) fields a caller may
+ * override per-call.
  *
  * @remarks
  * `task` becomes the seed user message in the sub-agent's rehydrated conversation
  * (`AgentJobInput.messages`). `provider` / `tools` / `system` shadow the tool's own
- * {@link AgentToolOptions} defaults for this ONE call when supplied.
+ * {@link AgentToolOptions} defaults for this one call when supplied.
  */
 export declare interface AgentToolArguments {
     readonly task: string;
@@ -132,12 +137,12 @@ export declare interface AgentToolArguments {
  * @remarks
  * - `name` / `description` — advertised tool overrides; default to
  *   {@link import('./constants.js').AGENT_TOOL_NAME} / {@link import('./constants.js').AGENT_TOOL_DESCRIPTION}.
- * - `provider` — the DEFAULT registry provider key used when a call omits `provider`; a call
- *   that supplies its own `provider` overrides this. One of `provider` (here or per-call) MUST
+ * - `provider` — the default registry provider key used when a call omits `provider`; a call
+ *   that supplies its own `provider` overrides this. One of `provider` (here or per-call) must
  *   resolve, or the handler throws a typed `TOOL` {@link import('./errors.js').ToolboxError}.
- * - `tools` — the DEFAULT registry tool-name list loaded into the delegated sub-agent; a
+ * - `tools` — the default registry tool-name list loaded into the delegated sub-agent; a
  *   per-call `tools` list overrides (never merges with) this default.
- * - `system` — the DEFAULT system prompt seeding the sub-agent's context; a per-call `system`
+ * - `system` — the default system prompt seeding the sub-agent's context; a per-call `system`
  *   overrides this.
  * - `depth` — this invocation's nesting depth (default `0`); a delegated sub-agent that itself
  *   calls this tool again runs at `depth + 1`, bounded by
@@ -145,17 +150,17 @@ export declare interface AgentToolArguments {
  * - `ancestry` — the sub-agent identifiers already in this delegation chain (default empty); a
  *   cycle (the resolved agent already present) is rejected with a typed `DEPTH`
  *   {@link import('./errors.js').ToolboxError}.
- * - `store` — this package's ADDITION: when supplied, the handler persists the delegated
+ * - `store` — this package's addition: when supplied, the handler persists the delegated
  *   sub-agent's active conversation snapshot (`store.set(agent.context.conversations.active.snapshot())`)
- *   once `agent.generate()` settles successfully, before returning — one snapshot per delegation
+ *   after `agent.generate()` settles successfully, before returning — one snapshot per delegation
  *   (each `registry.build` mints a fresh conversation id, so a shared store accumulates an
  *   audit log rather than colliding). Omitted ⇒ no persistence from this tool.
  *
- * Conversation persistence for a delegated sub-agent has TWO independent seams, composable
- * together: this `store` slot persists EACH delegation's conversation individually, and an
+ * Conversation persistence for a delegated sub-agent has independent seams, composable
+ * together: this `store` slot persists each delegation's conversation individually, and an
  * `AgentRegistryInterface` built with `AgentRegistryOptions.store` (`@orkestrel/agent`) backs
- * EVERY agent it builds — including ones built through this tool — with a store-backed
- * `ConversationManagerInterface` of its own. Neither is required; either or both may be used.
+ * every agent it builds — including ones built through this tool — with a store-backed
+ * `ConversationManagerInterface` of its own. Neither is required, and they compose.
  */
 export declare interface AgentToolOptions {
     readonly name?: string;
@@ -176,28 +181,36 @@ export declare interface AgentToolOptions {
  * `task` is the only required field (a non-empty string); `provider` / `tools` / `system`
  * are per-call overrides of the tool's own configured defaults.
  */
-export declare const agentToolShape: ObjectShape<{
-    task: StringShape;
-    provider: OptionalShape<StringShape>;
-    tools: OptionalShape<ArrayShape<StringShape>>;
-    system: OptionalShape<StringShape>;
+export declare const agentToolShape: ObjectShape<    {
+task: StringShape;
+provider: OptionalShape<StringShape>;
+tools: OptionalShape<ArrayShape<StringShape>>;
+system: OptionalShape<StringShape>;
 }, false>;
 
-/** Holds the pending/answer protocol {@link import('./factories.js').createAnswerTool} advertises. */
+/**
+ * Holds the protocol {@link import('./factories.js').createAnswerTool} advertises — the `pending`
+ * and `answer` operations and the `values` record an answer supplies, each with a worked example.
+ */
 export declare const ANSWER_TOOL_DESCRIPTION: string;
 
 /**
- * Holds the name {@link import('./factories.js').createAnswerTool} advertises by default — the key a
- * model calls and the `ToolManagerInterface` (`@orkestrel/tool`) registers under.
+ * Holds the name {@link import('./factories.js').createAnswerTool} advertises by default,
+ * `'answer'` — the key a model calls and the `ToolManagerInterface` (`@orkestrel/tool`) registers
+ * under.
  */
 export declare const ANSWER_TOOL_NAME = "answer";
 
 /**
- * Holds the lean {@link import('@orkestrel/tool').ToolInterface.summary} {@link import('./factories.js').createAnswerTool}
- * advertises in place of {@link ANSWER_TOOL_DESCRIPTION} — a `ToolManagerInterface.definitions()`
- * (`@orkestrel/tool`) advertises `summary ?? description`, so this one-sentence text stands in
- * for the full teaching description; the full text stays retrievable through
- * {@link import('./factories.js').createDescribeTool}.
+ * Holds the lean {@link import('@orkestrel/tool').ToolInterface.summary}
+ * {@link import('./factories.js').createAnswerTool} advertises in place of
+ * {@link ANSWER_TOOL_DESCRIPTION} — one sentence offering the pending listing and the answer call,
+ * and pointing at `describe` for the fields each takes.
+ *
+ * @remarks
+ * A `ToolManagerInterface.definitions()` call (`@orkestrel/tool`) advertises
+ * `summary ?? description`, so this one-sentence text stands in for the full teaching description;
+ * the full text stays retrievable through {@link import('./factories.js').createDescribeTool}.
  */
 export declare const ANSWER_TOOL_SUMMARY = "List forms addressed to this terminal, or answer one by id with a values record. Call describe('answer') for the required fields.";
 
@@ -211,7 +224,7 @@ export declare const ANSWER_TOOL_SUMMARY = "List forms addressed to this termina
  *   handler calls — `pending` lists the forms addressed to `to`, `answer` resolves
  *   one by `id`. A failed `answer` (`TerminalAnswerError`) re-surfaces as a typed
  *   `ANSWER` {@link import('./errors.js').ToolboxError}.
- * - `to` — the terminal identity this tool lists / answers prompts FOR.
+ * - `to` — the terminal identity this tool lists / answers prompts for.
  * - `name` / `description` — advertised tool overrides; default to
  *   {@link import('./constants.js').ANSWER_TOOL_NAME} / {@link import('./constants.js').ANSWER_TOOL_DESCRIPTION}.
  */
@@ -231,20 +244,21 @@ export declare interface AnswerToolOptions {
  * `values` is first bounded to exact JSON. The handler then narrows it with the originating Form
  * package's `isFormValues` guard before the terminal manager applies it to the parked live form.
  */
-export declare const answerToolShape: UnionShape<readonly [ ObjectShape<{
-    operation: LiteralShape<readonly ["pending"]>;
-}, false>, ObjectShape<{
-    operation: LiteralShape<readonly ["answer"]>;
-    id: StringShape;
-    values: JSONShape;
+export declare const answerToolShape: UnionShape<readonly [ObjectShape<    {
+operation: LiteralShape<readonly ["pending"]>;
+}, false>, ObjectShape<    {
+operation: LiteralShape<readonly ["answer"]>;
+id: StringShape;
+values: JSONShape;
 }, false>]>;
 
 /**
- * Represents the PROBE query and effective row limit {@link import('./helpers.js').clampQuery} returns.
+ * Represents the probe query and effective row limit {@link import('./helpers.js').clampQuery}
+ * returns.
  *
  * @remarks
  * `limit` is the effective ceiling — `min(query?.limit ?? cap, cap)`, floored at `0`. `query`
- * requests one row MORE than that, so a caller detects truncation from the returned row count
+ * requests one row more than that, so a caller detects truncation from the returned row count
  * without a separate `count` round trip.
  */
 export declare interface ClampedQuery {
@@ -253,14 +267,14 @@ export declare interface ClampedQuery {
 }
 
 /**
- * Clamps a `'records'` call's query to a row cap, and builds the PROBE query the caller reads
- * with — the pure leaf {@link import('./factories.js').createDatabaseTool}'s `'records'` operation
- * uses to detect truncation without a separate `count` round trip.
+ * Clamps a `'records'` call's query to a row cap, and builds the probe query the caller reads with
+ * — the pure leaf {@link import('./factories.js').createDatabaseTool}'s `'records'` operation uses
+ * to detect truncation without a separate `count` round trip.
  *
  * @remarks
  * {@link resolveLimit} picks the effective limit, so a caller can never exceed the configured cap
  * by supplying a larger `query.limit`, and can never drive it below `0`. The returned probe query
- * requests ONE MORE row than the effective limit (`limit: effective + 1`) — if storage returns
+ * requests one more row than the effective limit (`limit: effective + 1`) — if storage returns
  * that many, the caller knows the true result was truncated (`rows.length > effective`) and slices
  * back down to `effective` before returning.
  *
@@ -276,7 +290,7 @@ export declare interface ClampedQuery {
  *
  * @param query - The live query to clamp (or `undefined`)
  * @param cap - The row-count ceiling
- * @returns The PROBE query (`limit` bumped by one) and the effective `limit`
+ * @returns The probe query (`limit` bumped by one) and the effective `limit`
  */
 export declare function clampQuery(query: QueryInput | undefined, cap: number): ClampedQuery;
 
@@ -296,9 +310,9 @@ export declare type ColumnSpec = ColumnPrimitive | Readonly<{
 }>;
 
 /** Describes a {@link import('./types.js').ColumnSpec} — a bare {@link columnPrimitiveShape}, or `{ primitive, optional }`. */
-export declare const columnSpecShape: UnionShape<readonly [ LiteralShape<readonly ["string", "integer", "number", "boolean"]>, ObjectShape<{
-    primitive: LiteralShape<readonly ["string", "integer", "number", "boolean"]>;
-    optional: OptionalShape<BooleanShape>;
+export declare const columnSpecShape: UnionShape<readonly [LiteralShape<readonly ["string", "integer", "number", "boolean"]>, ObjectShape<    {
+primitive: LiteralShape<readonly ["string", "integer", "number", "boolean"]>;
+optional: OptionalShape<BooleanShape>;
 }, false>]>;
 
 /**
@@ -320,21 +334,21 @@ export declare function compileColumn(spec: ColumnSpec): ContractShape;
 export declare function compileColumnPrimitive(primitive: ColumnPrimitive): ContractShape;
 
 /**
- * Completes a {@link WorkflowDraft} into a strict {@link WorkflowDefinition} — synthesizes any
- * MISSING `id` deterministically + positionally, and defaults any MISSING `name` to its
- * (now-resolved) `id`.
+ * Completes a {@link WorkflowDraft} into a strict {@link WorkflowDefinition} — synthesizes a
+ * missing `id` deterministically and positionally, and defaults a missing `name` to its resolved
+ * `id`.
  *
  * @remarks
  * The positional id scheme is stable and human-legible: the workflow is `wf`, phase `i` is
  * `phase-<i>`, and task `j` of that phase is `<phaseId>-task-<j>` (so a provided phase id flows
- * into its tasks' synthesized ids). A PROVIDED `id` / `name` at any level is kept VERBATIM —
+ * into its tasks' synthesized ids). A provided `id` / `name` at any level is kept verbatim —
  * synthesis touches only the omitted ones. A missing `name` defaults to the resolved `id` (never
- * the other way round), so the result always has both. `behavior`, `description`, the per-phase
+ * the other way round), so the result always carries an `id` and a `name`. `behavior`, `description`, the per-phase
  * `concurrency` / `bail`, the per-task `retries` / `timeout`, and the workflow `bail` carry over
  * unchanged. The result is a complete {@link WorkflowDefinition}; the caller still validates it
- * against the STRICT contract.
+ * against the strict contract.
  *
- * @param draft - The draft workflow (id/name optional at all three levels)
+ * @param draft - The draft workflow (`id` and `name` optional at the workflow, phase, and task levels)
  * @returns A complete {@link WorkflowDefinition} with every id/name filled
  */
 export declare function completeDraft(draft: WorkflowDraft): WorkflowDefinition;
@@ -361,12 +375,15 @@ export declare function completePhaseDraft(phase: PhaseDraft, index: number): Wo
  */
 export declare function completeTaskDraft(task: TaskDraft, phaseId: string, index: number): WorkflowDefinition['phases'][number]['tasks'][number];
 
-/** Describes one SERIALIZED WHERE condition — `values` is ALWAYS an array, even for a single-value operator. */
-export declare const conditionShape: ObjectShape<{
-    column: StringShape;
-    operator: LiteralShape<readonly ["equals", "not", "above", "below", "from", "to", "between", "like", "glob", "starts", "ends", "any", "none", "absent", "present"]>;
-    values: ArrayShape<JSONShape>;
-    connector: OptionalShape<LiteralShape<readonly ["and", "or"]>>;
+/**
+ * Describes one serialized where condition — `values` is always an array, even for a single-value
+ * operator.
+ */
+export declare const conditionShape: ObjectShape<    {
+column: StringShape;
+operator: LiteralShape<readonly ["equals", "not", "above", "below", "from", "to", "between", "like", "glob", "starts", "ends", "any", "none", "absent", "present"]>;
+values: ArrayShape<JSONShape>;
+connector: OptionalShape<LiteralShape<readonly ["and", "or"]>>;
 }, false>;
 
 /**
@@ -408,8 +425,8 @@ export declare const conditionShape: ObjectShape<{
 export declare function createAgentFunction(agent: AgentInterface, options?: AgentFunctionOptions): AgentFunction;
 
 /**
- * Builds an LLM-callable sub-agent delegation tool — resolves a live, seeded `AgentInterface`
- * from `registry` and runs it to completion for ONE delegated `task`.
+ * Builds an LLM-callable sub-agent delegation tool — it resolves a live, seeded `AgentInterface`
+ * from `registry` and runs it to completion for one delegated `task`.
  *
  * @remarks
  * The universal tool-handler contract: validates the call args against
@@ -417,10 +434,10 @@ export declare function createAgentFunction(agent: AgentInterface, options?: Age
  * sub-agent's conversation as a single `user` message; `provider` / `tools` / `system` fall
  * back to the tool's own {@link import('./types.js').AgentToolOptions} defaults), rehydrates the sub-agent through
  * `registry.build`, runs it with `agent.generate()`, and returns the settled
- * `AgentResult.content` string (the sub-agent's final text). A missing / unresolvable `provider`, or a malformed call, THROWS a typed `TOOL`
+ * `AgentResult.content` string (the sub-agent's final text). A missing / unresolvable `provider`, or a malformed call, throws a typed `TOOL`
  * {@link import('./errors.js').ToolboxError}; a delegation that would exceed
  * {@link import('./constants.js').AGENT_TOOL_DEPTH}, or re-enter an already-delegated agent (a
- * cycle), THROWS a typed `DEPTH` {@link import('./errors.js').ToolboxError} — both isolated
+ * cycle), throws a typed `DEPTH` {@link import('./errors.js').ToolboxError}, each isolated
  * by the `ToolManagerInterface` into the canonical tool result's top-level `error`.
  *
  * `AgentInterface` (`@orkestrel/agent`) exposes no teardown method — a bound sub-agent's
@@ -449,9 +466,8 @@ export declare function createAgentFunction(agent: AgentInterface, options?: Age
 export declare function createAgentTool(registry: AgentRegistryInterface, options?: AgentToolOptions): ToolInterface;
 
 /**
- * Builds an LLM-callable answer tool — the ANSWER side of the terminal seam. Lists the forms
- * addressed to {@link import('./types.js').AnswerToolOptions.to}, or answers one of
- * them by id.
+ * Builds an LLM-callable answer tool — the answer side of the terminal seam. It lists the forms
+ * addressed to {@link import('./types.js').AnswerToolOptions.to}, or answers one of them by id.
  *
  * @remarks
  * The universal tool-handler contract: validates the call args against
@@ -461,10 +477,10 @@ export declare function createAgentTool(registry: AgentRegistryInterface, option
  * and applies it through
  * `TerminalManagerInterface.answer` — a rejected / unknown / unresolvable outcome
  * (`TerminalAnswerResult.error`) re-surfaces as a typed `ANSWER` `ToolboxError`; success returns
- * `{ answered: id }`. `to` is FIXED at construction
+ * `{ answered: id }`. `to` is fixed at construction
  * ({@link import('./types.js').AnswerToolOptions.to}) — never read from the model-supplied args —
  * so a model cannot spoof which terminal it is answering for. Concurrent answerers racing on one
- * endpoint are FIRST-WRITE-WINS — a late answer to an already-settled form returns a typed
+ * endpoint are first-write-wins — a late answer to an already-settled form returns a typed
  * `ANSWER` `ToolboxError` (surfaced as a 422 over HTTP).
  *
  * @param options - The live manager, the fixed `to` identity, and advertised overrides (see
@@ -511,7 +527,7 @@ export declare function createDatabaseDefinitionStore(driver?: DriverInterface):
  * @remarks
  * The universal tool-handler contract: validates the call args against
  * {@link import('./shapers.js').databaseToolShape}, dispatches to the matching operation, and
- * RETURNS a plain result on success. A database is resolved lazily and cached for the tool's
+ * returns a plain result on success. A database is resolved lazily and cached for the tool's
  * lifetime — `'create'` mints one from `tables` ({@link import('./compilers.js').expandTables}) and
  * a registered `driver` key ({@link import('./types.js').DatabaseToolOptions.drivers}, default
  * `{ memory: () => createMemoryDriver() }`); any other operation addressing an uncached id falls
@@ -536,7 +552,7 @@ export declare function createDatabaseDefinitionStore(driver?: DriverInterface):
  * ({@link import('./helpers.js').inferDatabaseCode}); an `ToolboxError` thrown by this tool's own
  * guards passes through unwrapped.
  *
- * A lazily re-minted database over the DEFAULT in-memory driver yields an EMPTY database — only
+ * A lazily re-minted database over the default in-memory driver yields an empty database — only
  * the {@link import('./types.js').DatabaseDefinition} schema persists in `store`, never rows;
  * durable rows need a persistent driver factory registered in
  * {@link import('./types.js').DatabaseToolOptions.drivers}. `'destroy'` closes whatever handle is
@@ -544,7 +560,7 @@ export declare function createDatabaseDefinitionStore(driver?: DriverInterface):
  * {@link import('./types.js').DatabaseToolOptions.databases} handle — the embedder relinquishes
  * that handle's lifecycle to this tool for any id it wires in. This tool assumes the
  * single-writer, non-reentrant model `@orkestrel/database` itself assumes — concurrent calls
- * against one id are NOT serialized by this tool. `'get'` is uncapped by
+ * against one id are not serialized by this tool. `'get'` is uncapped by
  * {@link import('./types.js').DatabaseToolOptions.limit} (bounded only by the caller's `key` array
  * size), unlike `'records'` / `'find'` / `'links'`.
  *
@@ -556,19 +572,21 @@ export declare function createDatabaseDefinitionStore(driver?: DriverInterface):
  * import { createDatabaseTool } from '@src/core'
  *
  * const tool = createDatabaseTool()
- * await tool.execute({
- * 	operation: 'create',
- * 	id: 'shop',
- * 	tables: { products: { columns: { name: 'string', price: 'number' } } },
- * })
+ * await tool.execute(
+ * 	{
+ * 		operation: 'create',
+ * 		id: 'shop',
+ * 		tables: { products: { columns: { name: 'string', price: 'number' } } },
+ * 	},
+ * 	{ signal: new AbortController().signal },
+ * )
  * ```
  */
 export declare function createDatabaseTool(options?: DatabaseToolOptions): ToolInterface;
 
 /**
- * Builds an LLM-callable tool that returns the FULL `description` of another registered tool by
- * name — the counterpart to the lean `summary` the other tools in this package advertise
- * (`AGENT_TOOL_SUMMARY` / `WORKFLOW_TOOL_SUMMARY` / `WORKSPACE_TOOL_SUMMARY`).
+ * Builds an LLM-callable tool that returns the full `description` of another registered tool by
+ * name — the counterpart to the lean `summary` the other tools in this package advertise.
  *
  * @remarks
  * `ToolManagerInterface.definitions()` (`@orkestrel/tool`) advertises `tool.summary ??
@@ -579,8 +597,8 @@ export declare function createDatabaseTool(options?: DatabaseToolOptions): ToolI
  * tool has no `description` of its own, then a placeholder when it has neither).
  *
  * The universal tool-handler contract: validates the call args against
- * {@link import('./shapers.js').describeToolShape}, RETURNS the plain description string on
- * success, THROWS a typed `TOOL` {@link import('./errors.js').ToolboxError} on a malformed call
+ * {@link import('./shapers.js').describeToolShape}, returns the plain description string on
+ * success, throws a typed `TOOL` {@link import('./errors.js').ToolboxError} on a malformed call
  * or an unknown tool name.
  *
  * @param tools - The `ToolManagerInterface` (`@orkestrel/tool`) whose registered tools this
@@ -602,36 +620,38 @@ export declare function createDatabaseTool(options?: DatabaseToolOptions): ToolI
 export declare function createDescribeTool(tools: ToolManagerInterface): ToolInterface;
 
 /**
- * Wraps one CONCRETE endpoint ({@link import('./types.js').EndpointDefinition}) as an LLM-callable
- * `ToolInterface` — the endpoint half of the "existing API/DB → MCP tool" bridge (the other half,
- * {@link createInferTool}, is a standalone inference utility).
+ * Wraps one concrete endpoint ({@link import('./types.js').EndpointDefinition}) as an LLM-callable
+ * `ToolInterface` — the endpoint half of the bridge from an existing API or database into an MCP
+ * tool (the other half, {@link createInferTool}, is a standalone inference utility).
  *
  * @remarks
- * `parameters` is inferred ONCE at construction from `definition.samples` through
+ * `parameters` is inferred once at construction from `definition.samples` through
  * `@orkestrel/contract`'s `samplesToSchema` (tuned by {@link import('./types.js').EndpointToolOptions}'s
  * `format` / `enum`), wrapping a non-object root as `{ value: <schema> }` through `schemaToObject` —
- * the SAME object-rooted schema is both the ADVERTISED `parameters` and, by default
- * ({@link import('./types.js').EndpointToolOptions.validate} `true`), the ENFORCED contract:
- * `@orkestrel/contract`'s `schemaToShape` compiles it ONCE (through `createContract`) into a
+ * the same object-rooted schema is both the advertised `parameters` and, by default
+ * ({@link import('./types.js').EndpointToolOptions.validate} `true`), the enforced contract:
+ * `@orkestrel/contract`'s `schemaToShape` compiles it once (through `createContract`) into a
  * `ContractInterface` whose `.parse` runs on every call's `args` before `definition.execute` — a
- * NORMALIZING parse, not a strict type check: a scalar is COERCED to its inferred type where the
+ * normalizing parse, not a strict type check: a scalar is coerced to its inferred type where the
  * house parsers coerce (a number to/from a numeric string, a boolean from `'1'`/`'0'`/`'true'`/
- * `'false'`/`1`/`0`), so `definition.execute` receives the COERCED value (for example `7` sent for a
+ * `'false'`/`1`/`0`), so `definition.execute` receives the coerced value (for example `7` sent for a
  * string slot arrives as `'7'`), not the raw call value. A call whose `args` fails to parse into
- * a record — a required key missing, or a value not coercible to its slot's type — THROWS a
+ * a record — a required key missing, or a value not coercible to its slot's type — throws a
  * typed `TOOL` {@link import('./errors.js').ToolboxError} carrying the compiled contract's
  * structured `explain` faults, and `definition.execute` is never called. `format` annotations are
- * NEVER asserted, and a key outside the closed inferred schema is SILENTLY DROPPED rather than
+ * never asserted, and a key outside the closed inferred schema is silently dropped rather than
  * rejected (see {@link import('./types.js').EndpointToolOptions.validate}). With
- * `validate: false`, the tool's `execute` PASSES THROUGH the model-supplied `args` to
- * `definition.execute` WITHOUT re-validation — the raw-passthrough opt-out. Either way, the
- * definition's return flows back as the tool call's plain result; a throw PROPAGATES uncaught,
+ * `validate: false`, the tool's `execute` passes through the model-supplied `args` to
+ * `definition.execute` without re-validation — the raw-passthrough opt-out. The execution context
+ * the tool's `execute` receives reaches `definition.execute` unchanged whichever way `args` are
+ * handled, so a handler that reads `context.signal` observes the caller's cancellation. Either way,
+ * the definition's return flows back as the tool call's plain result; a throw propagates uncaught,
  * isolated by the `ToolManagerInterface` (`@orkestrel/tool`) into the canonical error envelope
  * — never caught or re-wrapped here.
  *
  * @param definition - The endpoint's identity, non-empty samples, and local handler (see
  *   {@link import('./types.js').EndpointDefinition})
- * @param options - Construction-time inference tuning + the validate opt-out (see
+ * @param options - Construction-time inference tuning and the validate opt-out (see
  *   {@link import('./types.js').EndpointToolOptions})
  * @returns A `ToolInterface` named `definition.name`
  *
@@ -670,44 +690,44 @@ export declare function createDescribeTool(tools: ToolManagerInterface): ToolInt
 export declare function createEndpointTool(definition: EndpointDefinition, options?: EndpointToolOptions): ToolInterface;
 
 /**
- * Builds a standalone LLM-callable tool that infers a JSON Schema from example values — the
- * utility half of the "existing API/DB → MCP tool" bridge (the other half,
- * {@link createEndpointTool}, wraps one CONCRETE endpoint).
+ * Builds a standalone LLM-callable tool that infers a JSON Schema from example values — the utility
+ * half of the bridge from an existing API or database into an MCP tool (the other half,
+ * {@link createEndpointTool}, wraps one concrete endpoint).
  *
  * @remarks
  * The universal tool-handler contract: validates the call args against
  * {@link import('./shapers.js').inferToolShape} (`samples` non-empty, `format` / `enum` optional
  * booleans, `candidates` an optional array), infers a schema through `@orkestrel/contract`'s
  * `samplesToSchema`, wraps a non-object root as `{ value: <schema> }` through `schemaToObject` (mirrors
- * the tool-parameters convention every other `create*Tool` factory advertises), and RETURNS the
+ * the tool-parameters convention every other `create*Tool` factory advertises), and returns the
  * resulting parameters record. An empty `samples` array fails `inferToolShape`'s `min: 1` bound —
  * `contract.parse` returns `undefined` and the handler throws a typed `TOOL`
  * {@link import('./errors.js').ToolboxError}.
  *
- * When `candidates` is ABSENT, the return is the bare parameters record — unchanged from before
- * this array existed. When `candidates` is PRESENT (any array, including empty), the handler
- * compiles a SEPARATE per-call contract from the RAW inferred schema (through `@orkestrel/contract`'s
- * `schemaToShape`, NOT the `schemaToObject`-wrapped parameters — a bare-value sample checks a
+ * When `candidates` is absent, the return is the bare parameters record — unchanged from before
+ * this array existed. When `candidates` is present (any array, including empty), the handler
+ * compiles a separate per-call contract from the raw inferred schema (through `@orkestrel/contract`'s
+ * `schemaToShape`, not the `schemaToObject`-wrapped parameters — a bare-value sample checks a
  * bare-value candidate) and returns `{ parameters, checks }`, one check per candidate at the same
- * index. Every entry has a UNIFORM shape — `{ index, valid, coercible }`, with `faults` added ONLY
- * when `valid` is `false`: `valid` is the STRICT guard verdict (`checker.is(candidate)`), the
- * OPPOSITE of {@link createEndpointTool}'s enforcement, which coerces (`7` becomes `'7'` for a
- * string slot) — here a conformance report answers "does this value conform AS-IS": `7` against a
- * string slot is `valid: false`, full stop. `coercible` answers a SEPARATE question — "would the
- * NORMALIZING parse accept this value", that is would {@link createEndpointTool}'s default enforcement
+ * index. Every entry has a uniform shape — `{ index, valid, coercible }`, with `faults` added only
+ * when `valid` is `false`: `valid` is the strict guard verdict (`checker.is(candidate)`), the
+ * opposite of {@link createEndpointTool}'s enforcement, which coerces (`7` becomes `'7'` for a
+ * string slot) — here a conformance report answers "does this value conform as-is": `7` against a
+ * string slot is `valid: false`, full stop. `coercible` answers a separate question — "would the
+ * normalizing parse accept this value", that is would {@link createEndpointTool}'s default enforcement
  * admit it (`checker.parse(candidate) !== undefined`) — computed for every candidate regardless of
  * `valid`; by the house parse/guard round-trip, a `valid: true` entry is
- * ALWAYS also `coercible: true`. `@orkestrel/contract`'s `explain` mirrors the normalizing
+ * always also `coercible: true`. `@orkestrel/contract`'s `explain` mirrors the normalizing
  * `parse`'s leniency, not `is`'s strictness — so a strictly-invalid but coercible candidate (`7`
- * against a string slot) yields `{ valid: false, coercible: true, faults: [] }`: EMPTY faults, since
+ * against a string slot) yields `{ valid: false, coercible: true, faults: [] }`: empty faults, because
  * the mismatch the normalizing parse would silently fix is not one `explain` reports. `faults`
- * therefore only ever populates for a NON-coercible mismatch — a wrong type the parse can't coerce
+ * therefore only ever populates for a non-coercible mismatch — a wrong type the parse can't coerce
  * (a boolean in a string slot), a missing required key, or an out-of-enum value — where
  * `coercible: false`. `checker.is` / `.parse` / `.explain` are all total over JSON-safe input — a
- * JSON-safe hostile candidate (a `__proto__`-carrying object, deeply nested data) reaches all three
- * and yields a bounded, non-throwing per-candidate verdict; a NON-JSON-safe candidate (for example a
- * throwing-getter `Proxy`) never reaches the checker at all — it fails the OUTER `args` parse
- * against {@link import('./shapers.js').inferToolShape} and rejects the WHOLE call with the same
+ * JSON-safe hostile candidate (a `__proto__`-carrying object, deeply nested data) reaches each of them
+ * and yields a bounded, non-throwing per-candidate verdict; a non-JSON-safe candidate (for example a
+ * throwing-getter `Proxy`) never reaches the checker at all — it fails the outer `args` parse
+ * against {@link import('./shapers.js').inferToolShape} and rejects the whole call with the same
  * `TOOL` {@link import('./errors.js').ToolboxError} a malformed `samples`/`format`/`enum` throws,
  * with no per-candidate verdict produced.
  *
@@ -750,8 +770,8 @@ export declare function createInferTool(options?: InferToolOptions): ToolInterfa
 
 /**
  * Creates the in-memory {@link DefinitionStoreInterface} — a process-lifetime `Map` of database
- * definitions, the DEFAULT store the database and relation tools persist their
- * `DatabaseDefinition` configs through.
+ * definitions, the default store the database and relation tools persist their `DatabaseDefinition`
+ * configs through.
  *
  * @returns A {@link DefinitionStoreInterface}
  *
@@ -765,20 +785,23 @@ export declare function createInferTool(options?: InferToolOptions): ToolInterfa
 export declare function createMemoryDefinitionStore(): DefinitionStoreInterface;
 
 /**
- * Builds an LLM-callable form tool — the ASK side of the terminal seam. Asks
- * a multi-field form and BLOCKS until it answers, returning the resolved values record.
+ * Builds an LLM-callable form tool — the ask side of the terminal seam. It asks a multi-field form
+ * and blocks until the addressed terminal answers, returning the resolved values record.
  *
  * @remarks
  * The universal tool-handler contract: validates the call args against
  * {@link import('./shapers.js').promptToolShape}, parses the call's schema through
  * `@orkestrel/form`, constructs the live form, and passes it to `TerminalManagerInterface.ask`.
- * `from` is FIXED at construction
+ * `from` is fixed at construction
  * ({@link import('./types.js').PromptToolOptions.from}) — never read from the model-supplied
- * args — so a model cannot spoof which terminal is asking. A form CYCLE rejects with
+ * args — so a model cannot spoof which terminal is asking. A form cycle rejects with
  * `TerminalError('DEADLOCK')`, re-surfaced as a typed `DEADLOCK`
  * {@link import('./errors.js').ToolboxError}; an expired form re-surfaces as `EXPIRE`; an
  * unknown `to` (or any other `TerminalError`) re-surfaces as `TOOL`, naming the unknown terminal
- * and how many brokers the manager holds (`manager.count`).
+ * and how many brokers the manager holds (`manager.count`). A schema `parseForm` refuses — an
+ * unknown control, a duplicate field name, a `'select'` or `'checkbox'` field without usable
+ * `choices` — throws a typed `TOOL` error up front, so a malformed schema never parks as a form
+ * nobody can answer.
  *
  * @param options - The live manager, the fixed `from` identity, and advertised overrides (see
  *   {@link import('./types.js').PromptToolOptions})
@@ -809,14 +832,14 @@ export declare function createPromptTool(options: PromptToolOptions): ToolInterf
  * The universal tool-handler contract: validates the call args against
  * {@link import('./shapers.js').relationToolShape}, resolves the addressed
  * {@link import('@orkestrel/relation').RelationManagerInterface} — an explicit `manager` field
- * must match a key of {@link import('./types.js').RelationToolOptions.managers}, an OMITTED one
- * resolves to the SOLE registered manager, either miss throwing a typed `TOOL`
+ * must match a key of {@link import('./types.js').RelationToolOptions.managers}, an omitted one
+ * resolves to the sole registered manager, either miss throwing a typed `TOOL`
  * {@link import('./errors.js').ToolboxError}
  * ({@link import('./helpers.js').resolveRelationManager}) — then resolves `model` against it
  * ({@link import('./helpers.js').resolveRelationModel}, same typed-`TOOL`-on-miss shape), and
- * dispatches to the matched operation, RETURNING a plain result on success.
+ * dispatches to the matched operation, returning a plain result on success.
  *
- * `'load'` / `'find'` expand the call's FLAT dot-path `include` list into a live
+ * `'load'` / `'find'` expand the call's flat dot-path `include` list into a live
  * `@orkestrel/relation` `Include` tree through {@link import('./helpers.js').expandInclude}, capped
  * at {@link import('./types.js').RelationToolOptions.depth} (default
  * {@link import('./constants.js').RELATION_TOOL_DEPTH}) — a path exceeding the cap, or carrying an
@@ -826,7 +849,7 @@ export declare function createPromptTool(options: PromptToolOptions): ToolInterf
  * result to {@link import('./types.js').RelationToolOptions.limit} (default
  * {@link import('./constants.js').RELATION_TOOL_LIMIT}), taken through
  * {@link import('./helpers.js').resolveLimit} — `'find'` probes one row past the effective limit to
- * report `truncated`; `'links'` (which has no upstream pagination) fetches the FULL linked-key
+ * report `truncated`; `'links'` (which has no upstream pagination) fetches the full linked-key
  * list and slices/truncates it the same way. `'link'` / `'unlink'` write / remove one `through` junction
  * row.
  *
@@ -845,21 +868,26 @@ export declare function createPromptTool(options: PromptToolOptions): ToolInterf
  * import { createRelationTool } from '@src/core'
  *
  * const tool = createRelationTool({ managers: { shop: manager } })
- * await tool.execute({ operation: 'load', model: 'accounts', key: 'acc1', include: ['contacts'] })
+ * await tool.execute(
+ * 	{ operation: 'load', model: 'accounts', key: 'acc1', include: ['contacts'] },
+ * 	{ signal: new AbortController().signal },
+ * )
  * ```
  */
 export declare function createRelationTool(options: RelationToolOptions): ToolInterface;
 
 /**
- * Wraps a registered tool as a {@link WorkflowFunction} (`@orkestrel/workflow`) — the OPT-IN
- * adapter that lets a `function`-form task run a `@orkestrel/tool` tool BY NAME.
+ * Wraps a registered tool as a {@link WorkflowFunction} (`@orkestrel/workflow`) — the opt-in
+ * adapter that lets a `function`-form task run a `@orkestrel/tool` tool by name.
  *
  * @remarks
  * Composes into a caller's `WorkflowOptions.functions` registry like any other behavior
  * (`{ publish: createToolFunction(tools, 'publish') }`); the pure workflow runner has no
  * knowledge of tools itself. The returned function executes `name` against `tools` with the
  * task's `controller.input` as the call arguments. The adapter resolves the live tool, calls its
- * `execute` method directly, and deep-gates the returned unknown through `parseJSONValue`.
+ * `execute` method directly, and deep-gates the returned unknown through `parseJSONValue`. The
+ * execution context it passes carries the task's own `controller.signal`, so a handler that
+ * reads `context.signal` observes the caller's cancellation.
  * Genuine execution throws retain identity. An unregistered name or non-JSON return throws this
  * package's typed `TOOL` `ToolboxError`.
  *
@@ -882,7 +910,9 @@ export declare function createRelationTool(options: RelationToolOptions): ToolIn
 export declare function createToolFunction(tools: ToolManagerInterface, name: string): WorkflowFunction;
 
 /**
- * Compiles the lenient workflow draft contract used by {@link createWorkflowTool}.
+ * Compiles the lenient workflow draft contract {@link createWorkflowTool} parses an authored tree
+ * with — a `ContractInterface` over a {@link WorkflowDraft}, whose `id` and `name` are optional at
+ * the workflow, phase, and task levels.
  *
  * @returns The compiled {@link import('./types.js').WorkflowDraft} contract
  */
@@ -918,34 +948,33 @@ export declare function createWorkflowDraftContract(): ContractInterface<Workflo
 export declare function createWorkflowFunctions(runner: WorkflowRunnerInterface, options?: WorkflowToolOptions): WorkflowRegistry;
 
 /**
- * Wraps a {@link WorkflowDefinition} as an LLM-callable tool — it ADVERTISES the SIMPLE flat
- * authoring shape (`{ name?, steps: [{ name }] }`) as its `parameters` so even a small model can
- * author a complete tree, and its handler EXPANDS / COMPLETES the authored blob, validates it
- * against the STRICT contract, and runs it through `runner`, forwarding the caller's optional
- * named functions and native checkpoint store.
+ * Wraps a {@link WorkflowDefinition} as an LLM-callable tool — it advertises the flat authoring
+ * shape (`{ name?, steps: [{ name }] }`) as its `parameters`, and its handler completes the
+ * authored blob, validates it against the strict contract, and runs it through `runner`, forwarding
+ * the caller's optional named functions and native checkpoint store.
  *
  * @remarks
  * A plain `ToolManagerInterface`-compatible tool (`@orkestrel/tool`), reproducing
  * Toolbox's flat / draft / full authoring contract, strict soundness gate, and lineage guard.
- * It is ALSO the propagation carrier
+ * It is also the propagation carrier
  * {@link createAgentFunction} binds onto a wrapped agent's `context.tools`: because a tool
  * handler receives only the model-supplied `args`, the immutable lineage is closed over at bind
  * time. The authored target is appended and its zero-based depth derived from workflow tags.
  *
- * **Widened authoring surface (additive — the canonical contract + runner stay STRICT and
- * unchanged).** A 2B model reliably CALLS the tool but cannot reliably emit the full four-level
- * nested {@link WorkflowDefinition} (six required `id`/`name` strings, an all-or-nothing tree).
- * So the tool ACCEPTS three authoring forms and converges them on the SAME strict
+ * **Widened authoring surface (additive — the canonical contract and runner stay strict and
+ * unchanged).** A 2B model reliably calls the tool but cannot reliably emit the full nested
+ * {@link WorkflowDefinition}, whose every `id` and `name` is required across an all-or-nothing
+ * tree. So the tool accepts the authoring forms that follow and converges them on the same strict
  * `createWorkflowContract` gate before running (soundness preserved):
- * - the FLAT shape `{ name?, steps: [{ name }] }` — the ADVERTISED `parameters` (the simplest
+ * - the flat shape `{ name?, steps: [{ name }] }` — the advertised `parameters` (the simplest
  *   form, {@link import('./helpers.js').expandSteps}'d into one one-task phase per step);
- * - a nested DRAFT with any `id`/`name` OMITTED — {@link createWorkflowDraftContract}-parsed then
+ * - a nested draft with any `id`/`name` omitted — {@link createWorkflowDraftContract}-parsed then
  *   {@link import('./helpers.js').completeDraft}'d (missing ids synthesized positionally);
  * - the full nested {@link WorkflowDefinition} — the advanced escape-hatch, accepted as the draft
  *   super-set.
  *
  * The universal tool-handler contract: returns the plain run summary
- * (`{ status, count, durable?, fault? }`) on success, THROWS a typed `ToolboxError` on Toolbox
+ * (`{ status, count, durable?, fault? }`) on success, throws a typed `ToolboxError` on Toolbox
  * boundary failures — malformed authored args (`TOOL`), or an over-deep / cyclic nested run
  * (`DEPTH`) — and preserves genuine runner `WorkflowError`s. The `ToolManagerInterface` isolates every throw into the canonical tool result's
  * top-level `error`, so nothing escapes the run. `options.lineage` is the propagation carrier
@@ -959,6 +988,34 @@ export declare function createWorkflowFunctions(runner: WorkflowRunnerInterface,
  * @returns A `ToolInterface` (named {@link import('./constants.js').WORKFLOW_TOOL_NAME}) whose
  *   `parameters` advertise the flat authoring schema
  *
+ * @example Authoring and running a workflow through the tool with a real ToolManager
+ * ```ts
+ * import { createWorkflowTool } from '@orkestrel/toolbox'
+ * import { createToolManager } from '@orkestrel/tool'
+ * import { createWorkflowRunner } from '@orkestrel/workflow'
+ * import type { WorkflowDefinition } from '@orkestrel/workflow'
+ *
+ * const definition: WorkflowDefinition = { id: 'release', name: 'Release', phases: [] }
+ * const runner = createWorkflowRunner()
+ * const functions = {
+ * 	compile: () => 'compiled',
+ * 	publish: () => 'published',
+ * }
+ * const tool = createWorkflowTool(definition, runner, { functions })
+ *
+ * const tools = createToolManager()
+ * tools.add(tool)
+ *
+ * // A small model authors the simple flat shape — no ids/names required.
+ * const result = await tools.execute({
+ * 	id: 'call-1',
+ * 	name: 'workflow',
+ * 	arguments: { name: 'release', steps: [{ name: 'compile' }, { name: 'publish' }] },
+ * })
+ * if (!result.success) throw new Error(result.error)
+ * result.value // { status: 'completed', count: 2 } — the single-level envelope; no nested { id, name, value }
+ * ```
+ *
  * @example
  * ```ts
  * import { createWorkflowTool } from '@src/core'
@@ -975,42 +1032,35 @@ export declare function createWorkflowFunctions(runner: WorkflowRunnerInterface,
 export declare function createWorkflowTool(definition: WorkflowDefinition, runner: WorkflowRunnerInterface, options?: WorkflowToolOptions): ToolInterface;
 
 /**
- * Builds an LLM-callable workspace-editing tool — it ADVERTISES the `operation`-discriminated
- * union ({@link import('./shapers.js').workspaceToolShape}) as its `parameters`, and its
- * handler PARSES the model-supplied args against that contract and DISPATCHES the matched
- * operation against the manager's ACTIVE workspace (the registry ops drive the manager itself),
- * returning the plain result. A malformed operation throws this package's `ToolboxError`; a
- * genuine workspace-domain failure propagates `@orkestrel/workspace`'s typed `WorkspaceError`.
- * EITHER drives a caller-supplied {@link WorkspaceToolOptions.manager} directly, OR
- * constructs a fresh `WorkspaceManagerInterface` (`@orkestrel/workspace`) over
- * {@link import('./types.js').WorkspaceToolOptions.store} (through `@orkestrel/workspace`'s
- * `createWorkspaceManager`); neither given constructs a manager backed by
- * `@orkestrel/workspace`'s in-memory store default.
+ * Builds an LLM-callable workspace-editing tool — it advertises the `operation`-discriminated union
+ * ({@link import('./shapers.js').workspaceToolShape}) as its `parameters`, and its handler parses
+ * the model-supplied args against that contract and dispatches the matched operation against the
+ * manager's active workspace, returning the plain result.
  *
  * @remarks
- * MANAGER-DRIVEN: every edit / read op (read / list / has / search / replace / write / splice /
+ * Manager-driven: every edit / read op (read / list / has / search / replace / write / splice /
  * prepend / append / move / remove) targets `manager.active`, so the model edits whichever
  * workspace is active and a host can re-point it (`WorkspaceManagerInterface.switch`) between
- * turns. Two REGISTRY ops make the model self-sufficient: `workspaces` LISTS the registered
+ * turns. The registry ops make the model self-sufficient: `workspaces` lists the registered
  * workspaces (each `{ id, files, active }`) so it can discover an id, and `switch` re-points the
  * active workspace by id (lenient — an unknown id is a no-op reporting `switched: false`, never a
  * throw).
  *
- * NO-ACTIVE RULE (the ergonomic seam): a WRITING op (write / splice / prepend / append / move /
- * remove / replace) run when `manager.active` is `undefined` AUTO-CREATES + activates a default
- * workspace (`manager.add()`) so the model can start writing; a pure-READ op (read / list /
- * has / search) against no active workspace returns the EMPTY result (`undefined` / `[]` /
+ * No-active rule (the ergonomic seam): a writing op (write / splice / prepend / append / move /
+ * remove / replace) run when `manager.active` is `undefined` auto-creates and activates a default
+ * workspace (`manager.add()`) so the model can start writing; a pure-read op (read / list /
+ * has / search) against no active workspace returns the empty result (`undefined` / `[]` /
  * `false`), never creating one and never throwing.
  *
  * The handler conforms to the universal tool-handler contract: it `contract.parse`s
- * the args, THROWS a `TOOL` `ToolboxError` when no operation arm matched (a malformed / unknown
- * operation), else `switch`es on `op.operation` and RETURNS the plain result — letting a
+ * the args, throws a `TOOL` `ToolboxError` when no operation arm matched (a malformed / unknown
+ * operation), else `switch`es on `op.operation` and returns the plain result — letting a
  * `WorkspaceError` raised by the live workspace (`MISSING` / `MODALITY` / `PATTERN` / `RANGE`)
- * PROPAGATE uncaught. The range edit is the FLAT `'splice'` op: its four flat caret integers are
+ * propagate uncaught. The range edit is the flat `'splice'` op: its flat caret integers are
  * reassembled into a `Range` (`@orkestrel/workspace`) by `rangeOf` and fed to the workspace's
  * ranged `write`.
  *
- * @param options - `manager` (drive directly) OR `store` (build a manager over it); neither ⇒
+ * @param options - `manager` (drive directly) or `store` (build a manager over it); neither ⇒
  *   an in-memory-backed manager (see {@link import('./types.js').WorkspaceToolOptions})
  * @returns A `ToolInterface` (named {@link import('./constants.js').WORKSPACE_TOOL_NAME} by default)
  *
@@ -1028,44 +1078,54 @@ export declare function createWorkspaceTool(options?: WorkspaceToolOptions): Too
 
 /**
  * Holds the description {@link import('./factories.js').createDatabaseTool} advertises — a
- * multi-line guide that teaches a small model the operation list, the SERIALIZED query form, and
+ * multi-line guide that teaches a small model the operation list, the serialized query form, and
  * the {@link import('./types.js').TableSpec} column DSL.
  *
  * @remarks
- * The query form is deliberately SERIALIZED (never fluent) — every condition is a flat object
- * `{ column, operator, values, connector? }` where `values` is ALWAYS an array, even for a
+ * The query form is deliberately serialized (never fluent) — every condition is a flat object
+ * `{ column, operator, values, connector? }` where `values` is always an array, even for a
  * single-value operator (`{ column: 'age', operator: 'from', values: [18] }`), so a small model
  * never has to chain method calls or guess whether a value is scalar or a list.
  */
 export declare const DATABASE_TOOL_DESCRIPTION: string;
 
-/** Holds the default cap on rows a `records` call returns when the caller omits `query.limit` — the database tool's default row ceiling. */
+/**
+ * Holds the default cap on rows a `records` call returns when the caller omits `query.limit`,
+ * `1000` — the database tool's default row ceiling.
+ */
 export declare const DATABASE_TOOL_LIMIT = 1000;
 
 /** Lists the runtime-frozen database-tool mutation names disabled by `DatabaseToolOptions.readonly`. */
 export declare const DATABASE_TOOL_MUTATIONS: readonly string[];
 
 /**
- * Holds the name {@link import('./factories.js').createDatabaseTool} advertises by default — the key
- * a model calls and the `ToolManagerInterface` (`@orkestrel/tool`) registers under.
+ * Holds the name {@link import('./factories.js').createDatabaseTool} advertises by default,
+ * `'database'` — the key a model calls and the `ToolManagerInterface` (`@orkestrel/tool`) registers
+ * under.
  */
 export declare const DATABASE_TOOL_NAME = "database";
 
 /**
  * Holds the lean {@link import('@orkestrel/tool').ToolInterface.summary}
  * {@link import('./factories.js').createDatabaseTool} advertises in place of
- * {@link DATABASE_TOOL_DESCRIPTION}.
+ * {@link DATABASE_TOOL_DESCRIPTION} — one sentence offering the `operation`-keyed database call and
+ * pointing at `describe` for the operation list, the query form, and the column DSL.
+ *
+ * @remarks
+ * A `ToolManagerInterface.definitions()` call (`@orkestrel/tool`) advertises
+ * `summary ?? description`, so this one-sentence text stands in for the full teaching description;
+ * the full text stays retrievable through {@link import('./factories.js').createDescribeTool}.
  */
 export declare const DATABASE_TOOL_SUMMARY = "Create and query a database \u2014 one operation per call (create, tables, get, records, count, aggregate, add, set, update, remove, destroy), chosen by the 'operation' field. Call describe('database') for the full operation list, the query form, and the column DSL.";
 
 /**
- * Represents one database's CONFIG-ONLY definition — `id` + `driver` + {@link TableSpec}, with optional
- * `primary`, `indexes`, and `version` schema configuration.
+ * Represents one database's config-only definition — an `id`, a `driver`, and a {@link TableSpec},
+ * with optional `primary`, `indexes`, and `version` schema configuration.
  *
  * @remarks
- * A `DatabaseDefinition` is NEVER a live handle — it is the durable, serializable config a
+ * A `DatabaseDefinition` is never a live handle — it is the durable, serializable config a
  * {@link DefinitionStoreInterface} persists and a tool factory turns into a real
- * `@orkestrel/database` `DatabaseInterface` (through `createDatabase` + {@link import('./compilers.js').expandTables})
+ * `@orkestrel/database` `DatabaseInterface` (through `createDatabase` and {@link import('./compilers.js').expandTables})
  * on demand. `primary` maps table names to primary-key columns; `indexes` maps table names to
  * index column groups; `version` opts a capable driver into open-time schema reconciliation.
  */
@@ -1078,7 +1138,7 @@ export declare interface DatabaseDefinition {
     readonly version?: number;
 }
 
-/** Represents one opaque persisted row — the shape a `TableInterface<DatabaseDefinitionRow>`-backed store reads/writes; `definition` is narrowed with {@link import('./validators.js').isDatabaseDefinition} on read. */
+/** Represents one opaque persisted row — the shape a definition-row-backed `TableInterface` store reads/writes; `definition` is narrowed with {@link import('./validators.js').isDatabaseDefinition} on read. */
 export declare interface DatabaseDefinitionRow {
     readonly id: string;
     readonly definition: unknown;
@@ -1086,25 +1146,25 @@ export declare interface DatabaseDefinitionRow {
 
 /**
  * Represents a {@link DefinitionStoreInterface} backed by one table of the `@orkestrel/database` layer — a
- * database's durable CONFIG state IS a row, so persistence reduces to keyed point-access
+ * database's durable config state is a row, so persistence reduces to keyed point-access
  * (`get` / `set` / `delete`) over a {@link TableInterface}, the driver-pluggable twin of the
  * plain-`Map` {@link import('./MemoryDefinitionStore.js').MemoryDefinitionStore}.
  *
  * @remarks
  * The store is driver-agnostic: it holds a single {@link TableInterface} whose backend (memory,
  * JSON, SQLite, IndexedDB) is chosen by whoever builds it (the factories), so a JSON / SQLite /
- * IndexedDB backend swaps in WITHOUT touching a consumer — the same seam as
+ * IndexedDB backend swaps in without touching a consumer — the same seam as
  * {@link import('./MemoryDefinitionStore.js').MemoryDefinitionStore}. The driver defaults to
  * memory ({@link import('../factories.js').createDatabaseDefinitionStore} passes
- * `createMemoryDriver()`), so it ALSO works in memory out of the box; you opt into the durable
+ * `createMemoryDriver()`), so it also works in memory out of the box; you opt into the durable
  * plumbing by passing a JSON / SQLite / IndexedDB driver.
  *
- * The {@link DatabaseDefinition} is stored as ONE OPAQUE JSON COLUMN — the table is a row of
- * `{ id; definition }` ({@link DatabaseDefinitionRow}). The definition is already a COMPLETE,
- * self-contained, pure-JSON CONFIG payload (never a live handle), so storing it whole is lossless
- * AND keeps the row type flat (`definition` reads back as `unknown`).
+ * The {@link DatabaseDefinition} is stored as one opaque JSON column — the table is a row of
+ * `{ id; definition }` ({@link DatabaseDefinitionRow}). The definition is already a complete,
+ * self-contained, pure-JSON config payload (never a live handle), so storing it whole is lossless
+ * and keeps the row type flat (`definition` reads back as `unknown`).
  *
- * - **`set(definition)` upserts under the definition's OWN `id`** (no separate id param) — it
+ * - **`set(definition)` upserts under the definition's own `id`** (no separate id param) — it
  *   writes the row `{ id: definition.id, definition }`.
  * - **`get(id)` resolves the stored definition for an id**, narrowing the opaque JSON column back
  *   to a {@link DatabaseDefinition} ({@link import('../validators.js').isDatabaseDefinition} — the
@@ -1112,7 +1172,7 @@ export declare interface DatabaseDefinitionRow {
  *   or the stored blob is malformed.
  * - **`delete(id)` drops a definition by id**; an absent id is a no-op (no throw).
  *
- * The public surface is EXACTLY `get` / `set` / `delete` — no extra members (the method
+ * The public surface is exactly `get` / `set` / `delete` — no extra members (the method
  * bijection with {@link DefinitionStoreInterface}).
  *
  * @example
@@ -1144,30 +1204,29 @@ export declare class DatabaseDefinitionStore implements DefinitionStoreInterface
      */
     get(id: string): Promise<DatabaseDefinition | undefined>;
     /**
-     * Inserts or replaces a definition under its OWN `id` — the written row is `{ id, definition }`.
+     * Inserts or replaces a definition under its own `id` — the written row is `{ id, definition }`.
      *
      * @param definition - The config to persist; its own `id` is the row key (no separate id param)
-     * @returns A promise settling once the row is written
+     * @returns A promise settling after the row is written
      */
     set(definition: DatabaseDefinition): Promise<void>;
     /**
      * Drops the definition stored under `id`.
      *
      * @param id - The database id to drop; an absent id is a no-op, never a throw
-     * @returns A promise settling once no row is stored under `id`
+     * @returns A promise settling after no row is stored under `id`
      */
     delete(id: string): Promise<void>;
 }
 
 /**
- * Represents the SERIALIZED wire query a database-tool call carries — the parsed form of
- * {@link import('./shapers.js').queryShape}, which
- * {@link import('./helpers.js').normalizeQuery} normalizes into a live `@orkestrel/database`
- * {@link QueryInput}.
+ * Represents the serialized wire query a database-tool call carries — the parsed form of
+ * {@link import('./shapers.js').queryShape}, which {@link import('./helpers.js').normalizeQuery}
+ * normalizes into a live `@orkestrel/database` `QueryInput`.
  *
  * @remarks
- * Every condition is FLAT and its `values` is ALWAYS an array, even for a single-value operator.
- * `connector` is optional because the LAST condition joins nothing forward; `normalizeQuery` defaults an
+ * Every condition is flat and its `values` is always an array, even for a single-value operator.
+ * `connector` is optional because the last condition joins nothing forward; `normalizeQuery` defaults an
  * omitted one to `'and'`. `order` / `limit` / `offset` carry over to the live query unchanged.
  */
 export declare interface DatabaseQueryInput {
@@ -1186,7 +1245,8 @@ export declare interface DatabaseQueryInput {
 }
 
 /**
- * Resolves database definitions into cached live handles for database tools.
+ * Resolves a database definition into a cached live handle for a database tool, over the tool's
+ * live handles, its stored definitions, its driver registry, and an optional key generator.
  *
  * @example
  * ```ts
@@ -1237,7 +1297,8 @@ export declare class DatabaseResolver {
      */
     delete(id: string): void;
     /**
-     * Resolves a cached or stored database by id.
+     * Resolves a live database by id — the cached handle when one exists, otherwise a database
+     * constructed from its stored definition.
      *
      * @param id - Database definition id
      * @returns The cached or newly constructed live database
@@ -1254,7 +1315,7 @@ export declare class DatabaseResolver {
  *   caller-constructed database it manages alongside store-backed ones); keyed by the id a
  *   call's `id` field addresses.
  * - `store` — the {@link DefinitionStoreInterface} the `'create'` operation persists its
- *   {@link DatabaseDefinition} CONFIG through, and `'destroy'` deletes from; also the source
+ *   {@link DatabaseDefinition} config through, and `'destroy'` deletes from; also the source
  *   `'get'`/every other operation resolves an id from when it isn't already cached. Omitted means
  *   no persistence — a database created without a store lives only for the tool's lifetime.
  * - `drivers` — registry of driver-name to `() => DriverInterface` factories a `'create'` call's
@@ -1291,9 +1352,8 @@ export declare interface DatabaseToolOptions {
 
 /**
  * Describes the shape of {@link import('./factories.js').createDatabaseTool}'s call arguments —
- * discriminated by `operation` into the 11 database operations (`'create'` / `'tables'` /
- * `'get'` / `'records'` / `'count'` / `'aggregate'` / `'add'` / `'set'` / `'update'` /
- * `'remove'` / `'destroy'`).
+ * discriminated by `operation` into the database operations `'create'`, `'tables'`, `'get'`,
+ * `'records'`, `'count'`, `'aggregate'`, `'add'`, `'set'`, `'update'`, `'remove'`, and `'destroy'`.
  *
  * @remarks
  * Every arm carries `id` (the database id). `'create'` carries `tables` (the
@@ -1301,120 +1361,123 @@ export declare interface DatabaseToolOptions {
  * {@link import('./compilers.js').expandTables}); `'get'` / `'update'` / `'remove'` carry `key`
  * (one key or an array of keys, positional); `'add'` / `'set'` carry `row` (one row or an array of
  * rows); `'update'` also carries `changes` (a loose partial row); `'records'` / `'count'` /
- * `'aggregate'` carry an optional `query` (the SERIALIZED form — `values` is ALWAYS an array,
+ * `'aggregate'` carry an optional `query` (the serialized form — `values` is always an array,
  * even for a single-value operator, so a caller never chains method calls or guesses arity).
  */
-export declare const databaseToolShape: UnionShape<readonly [ ObjectShape<{
-    operation: LiteralShape<readonly ["create"]>;
-    id: StringShape;
-    tables: ObjectShape<Record<never, never>, ObjectShape<{
-        columns: ObjectShape<Record<never, never>, UnionShape<readonly [ LiteralShape<readonly ["string", "integer", "number", "boolean"]>, ObjectShape<{
-            primitive: LiteralShape<readonly ["string", "integer", "number", "boolean"]>;
-            optional: OptionalShape<BooleanShape>;
-        }, false>]>>;
-    }, false>>;
-    driver: OptionalShape<StringShape>;
-    primary: OptionalShape<ObjectShape<Record<never, never>, StringShape>>;
-    indexes: OptionalShape<ObjectShape<Record<never, never>, ArrayShape<ArrayShape<StringShape>>>>;
-    version: OptionalShape<NumberShape>;
-}, false>, ObjectShape<{
-    operation: LiteralShape<readonly ["tables"]>;
-    id: StringShape;
-}, false>, ObjectShape<{
-    operation: LiteralShape<readonly ["get"]>;
-    id: StringShape;
-    table: StringShape;
-    key: UnionShape<readonly [ ArrayShape<UnionShape<readonly [ StringShape, NumberShape]>>, StringShape, NumberShape]>;
-}, false>, ObjectShape<{
-    operation: LiteralShape<readonly ["records"]>;
-    id: StringShape;
-    table: StringShape;
-    query: OptionalShape<ObjectShape<{
-        conditions: OptionalShape<ArrayShape<ObjectShape<{
-            column: StringShape;
-            operator: LiteralShape<readonly ["equals", "not", "above", "below", "from", "to", "between", "like", "glob", "starts", "ends", "any", "none", "absent", "present"]>;
-            values: ArrayShape<JSONShape>;
-            connector: OptionalShape<LiteralShape<readonly ["and", "or"]>>;
-        }, false>>>;
-        order: OptionalShape<ArrayShape<ObjectShape<{
-            column: StringShape;
-            direction: LiteralShape<readonly ["ascending", "descending"]>;
-        }, false>>>;
-        limit: OptionalShape<NumberShape>;
-        offset: OptionalShape<NumberShape>;
-    }, false>>;
-}, false>, ObjectShape<{
-    operation: LiteralShape<readonly ["count"]>;
-    id: StringShape;
-    table: StringShape;
-    query: OptionalShape<ObjectShape<{
-        conditions: OptionalShape<ArrayShape<ObjectShape<{
-            column: StringShape;
-            operator: LiteralShape<readonly ["equals", "not", "above", "below", "from", "to", "between", "like", "glob", "starts", "ends", "any", "none", "absent", "present"]>;
-            values: ArrayShape<JSONShape>;
-            connector: OptionalShape<LiteralShape<readonly ["and", "or"]>>;
-        }, false>>>;
-        order: OptionalShape<ArrayShape<ObjectShape<{
-            column: StringShape;
-            direction: LiteralShape<readonly ["ascending", "descending"]>;
-        }, false>>>;
-        limit: OptionalShape<NumberShape>;
-        offset: OptionalShape<NumberShape>;
-    }, false>>;
-}, false>, ObjectShape<{
-    operation: LiteralShape<readonly ["aggregate"]>;
-    id: StringShape;
-    table: StringShape;
-    function: LiteralShape<readonly ["count", "sum", "average", "minimum", "maximum"]>;
-    column: StringShape;
-    query: OptionalShape<ObjectShape<{
-        conditions: OptionalShape<ArrayShape<ObjectShape<{
-            column: StringShape;
-            operator: LiteralShape<readonly ["equals", "not", "above", "below", "from", "to", "between", "like", "glob", "starts", "ends", "any", "none", "absent", "present"]>;
-            values: ArrayShape<JSONShape>;
-            connector: OptionalShape<LiteralShape<readonly ["and", "or"]>>;
-        }, false>>>;
-        order: OptionalShape<ArrayShape<ObjectShape<{
-            column: StringShape;
-            direction: LiteralShape<readonly ["ascending", "descending"]>;
-        }, false>>>;
-        limit: OptionalShape<NumberShape>;
-        offset: OptionalShape<NumberShape>;
-    }, false>>;
-}, false>, ObjectShape<{
-    operation: LiteralShape<readonly ["add"]>;
-    id: StringShape;
-    table: StringShape;
-    row: UnionShape<readonly [ ArrayShape<ObjectShape<Record<never, never>, JSONShape>>, ObjectShape<Record<never, never>, JSONShape>]>;
-}, false>, ObjectShape<{
-    operation: LiteralShape<readonly ["set"]>;
-    id: StringShape;
-    table: StringShape;
-    row: UnionShape<readonly [ ArrayShape<ObjectShape<Record<never, never>, JSONShape>>, ObjectShape<Record<never, never>, JSONShape>]>;
-}, false>, ObjectShape<{
-    operation: LiteralShape<readonly ["update"]>;
-    id: StringShape;
-    table: StringShape;
-    key: UnionShape<readonly [ ArrayShape<UnionShape<readonly [ StringShape, NumberShape]>>, StringShape, NumberShape]>;
-    changes: ObjectShape<Record<never, never>, JSONShape>;
-}, false>, ObjectShape<{
-    operation: LiteralShape<readonly ["remove"]>;
-    id: StringShape;
-    table: StringShape;
-    key: UnionShape<readonly [ ArrayShape<UnionShape<readonly [ StringShape, NumberShape]>>, StringShape, NumberShape]>;
-}, false>, ObjectShape<{
-    operation: LiteralShape<readonly ["destroy"]>;
-    id: StringShape;
+export declare const databaseToolShape: UnionShape<readonly [ObjectShape<    {
+operation: LiteralShape<readonly ["create"]>;
+id: StringShape;
+tables: ObjectShape<Record<never, never>, ObjectShape<    {
+columns: ObjectShape<Record<never, never>, UnionShape<readonly [LiteralShape<readonly ["string", "integer", "number", "boolean"]>, ObjectShape<    {
+primitive: LiteralShape<readonly ["string", "integer", "number", "boolean"]>;
+optional: OptionalShape<BooleanShape>;
+}, false>]>>;
+}, false>>;
+driver: OptionalShape<StringShape>;
+primary: OptionalShape<ObjectShape<Record<never, never>, StringShape>>;
+indexes: OptionalShape<ObjectShape<Record<never, never>, ArrayShape<ArrayShape<StringShape>>>>;
+version: OptionalShape<NumberShape>;
+}, false>, ObjectShape<    {
+operation: LiteralShape<readonly ["tables"]>;
+id: StringShape;
+}, false>, ObjectShape<    {
+operation: LiteralShape<readonly ["get"]>;
+id: StringShape;
+table: StringShape;
+key: UnionShape<readonly [ArrayShape<UnionShape<readonly [StringShape, NumberShape]>>, StringShape, NumberShape]>;
+}, false>, ObjectShape<    {
+operation: LiteralShape<readonly ["records"]>;
+id: StringShape;
+table: StringShape;
+query: OptionalShape<ObjectShape<    {
+conditions: OptionalShape<ArrayShape<ObjectShape<    {
+column: StringShape;
+operator: LiteralShape<readonly ["equals", "not", "above", "below", "from", "to", "between", "like", "glob", "starts", "ends", "any", "none", "absent", "present"]>;
+values: ArrayShape<JSONShape>;
+connector: OptionalShape<LiteralShape<readonly ["and", "or"]>>;
+}, false>>>;
+order: OptionalShape<ArrayShape<ObjectShape<    {
+column: StringShape;
+direction: LiteralShape<readonly ["ascending", "descending"]>;
+}, false>>>;
+limit: OptionalShape<NumberShape>;
+offset: OptionalShape<NumberShape>;
+}, false>>;
+}, false>, ObjectShape<    {
+operation: LiteralShape<readonly ["count"]>;
+id: StringShape;
+table: StringShape;
+query: OptionalShape<ObjectShape<    {
+conditions: OptionalShape<ArrayShape<ObjectShape<    {
+column: StringShape;
+operator: LiteralShape<readonly ["equals", "not", "above", "below", "from", "to", "between", "like", "glob", "starts", "ends", "any", "none", "absent", "present"]>;
+values: ArrayShape<JSONShape>;
+connector: OptionalShape<LiteralShape<readonly ["and", "or"]>>;
+}, false>>>;
+order: OptionalShape<ArrayShape<ObjectShape<    {
+column: StringShape;
+direction: LiteralShape<readonly ["ascending", "descending"]>;
+}, false>>>;
+limit: OptionalShape<NumberShape>;
+offset: OptionalShape<NumberShape>;
+}, false>>;
+}, false>, ObjectShape<    {
+operation: LiteralShape<readonly ["aggregate"]>;
+id: StringShape;
+table: StringShape;
+function: LiteralShape<readonly ["count", "sum", "average", "minimum", "maximum"]>;
+column: StringShape;
+query: OptionalShape<ObjectShape<    {
+conditions: OptionalShape<ArrayShape<ObjectShape<    {
+column: StringShape;
+operator: LiteralShape<readonly ["equals", "not", "above", "below", "from", "to", "between", "like", "glob", "starts", "ends", "any", "none", "absent", "present"]>;
+values: ArrayShape<JSONShape>;
+connector: OptionalShape<LiteralShape<readonly ["and", "or"]>>;
+}, false>>>;
+order: OptionalShape<ArrayShape<ObjectShape<    {
+column: StringShape;
+direction: LiteralShape<readonly ["ascending", "descending"]>;
+}, false>>>;
+limit: OptionalShape<NumberShape>;
+offset: OptionalShape<NumberShape>;
+}, false>>;
+}, false>, ObjectShape<    {
+operation: LiteralShape<readonly ["add"]>;
+id: StringShape;
+table: StringShape;
+row: UnionShape<readonly [ArrayShape<ObjectShape<Record<never, never>, JSONShape>>, ObjectShape<Record<never, never>, JSONShape>]>;
+}, false>, ObjectShape<    {
+operation: LiteralShape<readonly ["set"]>;
+id: StringShape;
+table: StringShape;
+row: UnionShape<readonly [ArrayShape<ObjectShape<Record<never, never>, JSONShape>>, ObjectShape<Record<never, never>, JSONShape>]>;
+}, false>, ObjectShape<    {
+operation: LiteralShape<readonly ["update"]>;
+id: StringShape;
+table: StringShape;
+key: UnionShape<readonly [ArrayShape<UnionShape<readonly [StringShape, NumberShape]>>, StringShape, NumberShape]>;
+changes: ObjectShape<Record<never, never>, JSONShape>;
+}, false>, ObjectShape<    {
+operation: LiteralShape<readonly ["remove"]>;
+id: StringShape;
+table: StringShape;
+key: UnionShape<readonly [ArrayShape<UnionShape<readonly [StringShape, NumberShape]>>, StringShape, NumberShape]>;
+}, false>, ObjectShape<    {
+operation: LiteralShape<readonly ["destroy"]>;
+id: StringShape;
 }, false>]>;
 
 /**
- * Represents the point-access persistence seam for {@link DatabaseDefinition} configs —
- * the twin of `@orkestrel/terminal`'s `TerminalStoreInterface`, storing a database's CONFIG-ONLY
- * blueprint (never a live handle). Every primitive is async; `delete` of an absent id is a no-op.
+ * Represents the point-access persistence seam for {@link DatabaseDefinition} configs — the twin of
+ * `@orkestrel/terminal`'s `TerminalStoreInterface`, storing a database's config-only blueprint
+ * rather than a live handle. Every primitive is async; `delete` of an absent id is a no-op.
  */
 export declare interface DefinitionStoreInterface {
+    /** Resolves the persisted definition for `id`, or `undefined` when none is stored. */
     get(id: string): Promise<DatabaseDefinition | undefined>;
+    /** Inserts or replaces a definition under its own `id`, taking no separate id argument. */
     set(definition: DatabaseDefinition): Promise<void>;
+    /** Drops the definition for `id`, treating an absent id as a no-op that never throws. */
     delete(id: string): Promise<void>;
 }
 
@@ -1427,7 +1490,8 @@ export declare interface DefinitionStoreInterface {
 export declare function deriveWorkflowDepth(lineage: WorkflowLineage): number;
 
 /**
- * Holds the DESCRIPTION {@link import('./factories.js').createDescribeTool} advertises.
+ * Holds the description {@link import('./factories.js').createDescribeTool} advertises — the
+ * registered tool `name` it requires, and the full description of that tool it returns.
  *
  * @remarks
  * Deliberately short — unlike the workflow / workspace / agent tools, this one has no authoring
@@ -1436,8 +1500,9 @@ export declare function deriveWorkflowDepth(lineage: WorkflowLineage): number;
 export declare const DESCRIBE_TOOL_DESCRIPTION = "Return the full description of a registered tool by its name. Required: name - the registered tool name (see another tool listing for available names).";
 
 /**
- * Holds the name {@link import('./factories.js').createDescribeTool} advertises by default — the key a
- * model calls and the `ToolManagerInterface` (`@orkestrel/tool`) registers under.
+ * Holds the name {@link import('./factories.js').createDescribeTool} advertises by default,
+ * `'describe'` — the key a model calls and the `ToolManagerInterface` (`@orkestrel/tool`) registers
+ * under.
  *
  * @remarks
  * Pairs with the lean {@link AGENT_TOOL_SUMMARY} / {@link WORKFLOW_TOOL_SUMMARY} /
@@ -1455,8 +1520,8 @@ export declare const DESCRIBE_TOOL_NAME = "describe";
 export declare const DESCRIBE_TOOL_SUMMARY = "Return the full description of a named registered tool.";
 
 /**
- * Represents the FLAT args {@link import('./factories.js').createDescribeTool} accepts — the registered
- * tool `name` whose full `description` a model wants back.
+ * Represents the flat args {@link import('./factories.js').createDescribeTool} accepts — the
+ * registered tool `name` whose full `description` a model wants back.
  *
  * @remarks
  * `name` must match a tool registered on the {@link import('@orkestrel/tool').ToolManagerInterface}
@@ -1473,8 +1538,8 @@ export declare interface DescribeToolArguments {
  * @remarks
  * `name` is the only field (a non-empty string) — the registered tool name to look up.
  */
-export declare const describeToolShape: ObjectShape<{
-    name: StringShape;
+export declare const describeToolShape: ObjectShape<    {
+name: StringShape;
 }, false>;
 
 /**
@@ -1483,17 +1548,17 @@ export declare const describeToolShape: ObjectShape<{
  * `parameters` are inferred from, and the local handler that runs a call.
  *
  * @remarks
- * `samples` MUST be non-empty — {@link import('./factories.js').createEndpointTool} throws a
- * typed `TOOL` {@link import('./errors.js').ToolboxError} at CONSTRUCTION when it is empty,
- * since an empty sample set cannot infer a schema. By DEFAULT ({@link EndpointToolOptions.validate}
- * `true`) `execute` receives the PARSED, NORMALIZED args record — a copy of the model-supplied
+ * `samples` must be non-empty — {@link import('./factories.js').createEndpointTool} throws a
+ * typed `TOOL` {@link import('./errors.js').ToolboxError} at construction when it is empty,
+ * because an empty sample set cannot infer a schema. By default ({@link EndpointToolOptions.validate}
+ * `true`) `execute` receives the parsed, normalized args record — a copy of the model-supplied
  * `args` with each scalar coerced to its inferred type (for example a number sent for a string slot
  * arrives coerced to a string), checked against the same schema advertised as `parameters` — and
  * a call with a missing required key or a non-coercible value never reaches `execute` at all (see
  * {@link EndpointToolOptions.validate}). With
- * `validate: false`, `execute` receives the model-supplied `args` VERBATIM (raw passthrough, never
+ * `validate: false`, `execute` receives the model-supplied `args` verbatim (raw passthrough, never
  * checked against the inferred schema). Either way `execute`'s return flows back as the tool
- * call's result; a throw PROPAGATES uncaught, isolated by the `ToolManagerInterface`
+ * call's result; a throw propagates uncaught, isolated by the `ToolManagerInterface`
  * (`@orkestrel/tool`) into the canonical error envelope. When `samples` are non-object values,
  * the advertised schema wraps them under a single required `value` property, so `execute` receives
  * an `args` record of the shape `{ value: ... }` — never the bare value.
@@ -1506,37 +1571,44 @@ export declare interface EndpointDefinition {
 }
 
 /**
- * Represents the handler {@link import('./types.js').EndpointDefinition.execute} implements — mirrors
- * `@orkestrel/tool`'s `ToolOptions.execute` signature EXACTLY (same `Readonly<Record<string,
- * unknown>>` argument, same `Promise<unknown> | unknown` return) so
- * `execute: (args) => definition.execute(args)` typechecks with zero assertions in
- * {@link import('./factories.js').createEndpointTool}.
+ * Represents the handler {@link EndpointDefinition.execute} implements — it mirrors
+ * `@orkestrel/tool`'s `ToolOptions.execute` signature exactly, so
+ * {@link import('./factories.js').createEndpointTool} forwards the execution context it receives
+ * to the handler unchanged and a handler that reads `context.signal` observes the caller's
+ * cancellation.
+ *
+ * @remarks
+ * The mirrored signature is the same `Readonly<Record<string, unknown>>` argument, the same
+ * `ToolContext` second parameter, and the same `Promise<unknown> | unknown` return. A handler that
+ * declares `args` alone still satisfies the type, the way a function declaring fewer parameters
+ * than its contract does, so an endpoint definition written against the argument alone keeps
+ * typechecking and reads no signal.
  */
-export declare type EndpointHandler = (args: Readonly<Record<string, unknown>>) => Promise<unknown> | unknown;
+export declare type EndpointHandler = (args: Readonly<Record<string, unknown>>, context: ToolContext) => Promise<unknown> | unknown;
 
 /**
- * Represents the construction-time tuning for {@link import('./factories.js').createEndpointTool} — the
- * inferred `parameters` schema's `format` / `enum` constraints, and whether that same schema is
- * ENFORCED at `execute` time.
+ * Represents the construction-time tuning for {@link import('./factories.js').createEndpointTool} —
+ * the inferred `parameters` schema's `format` and `enum` constraints, and whether that same schema
+ * is enforced at `execute` time.
  *
  * @remarks
  * `format` / `enum` default to `false`, matching `@orkestrel/contract`'s own
  * `ValueToSchemaOptions` defaults. `validate` defaults to `true`: the schema
- * `createEndpointTool` advertises as `parameters` (`samplesToSchema` + `schemaToObject`) is
- * compiled ONCE at construction (through `@orkestrel/contract`'s `schemaToShape`) into a
- * `ContractInterface` used to `parse` every call's `args` before `execute` runs — a NORMALIZING
- * parse: a scalar value is COERCED to its inferred type where the house parsers coerce (a number
+ * `createEndpointTool` advertises as `parameters` (`samplesToSchema` and `schemaToObject`) is
+ * compiled once at construction (through `@orkestrel/contract`'s `schemaToShape`) into a
+ * `ContractInterface` used to `parse` every call's `args` before `execute` runs — a normalizing
+ * parse: a scalar value is coerced to its inferred type where the house parsers coerce (a number
  * to/from a numeric string, a boolean from `'1'`/`'0'`/`'true'`/`'false'`/`1`/`0`), so `execute`
- * receives the COERCED values (for example `7` sent for a string slot arrives at `execute` as `'7'`), not
+ * receives the coerced values (for example `7` sent for a string slot arrives at `execute` as `'7'`), not
  * the raw call args. A call whose `args` fails to parse — a required key missing, or a value not
- * coercible to its slot's type — THROWS a typed `TOOL` {@link import('./errors.js').ToolboxError}
+ * coercible to its slot's type — throws a typed `TOOL` {@link import('./errors.js').ToolboxError}
  * carrying the structured `explain` faults, and `execute` is never called. Beyond that coercion,
- * enforcement is STRUCTURAL — required keys, `enum` membership, and numeric bounds — `format`
- * annotations (`email`, `date-time`, `uuid`, `uri`, ...) are NEVER asserted, mirroring
+ * enforcement is structural — required keys, `enum` membership, and numeric bounds — `format`
+ * annotations (`email`, `date-time`, `uuid`, `uri`, ...) are never asserted, mirroring
  * `@orkestrel/contract`'s own widening-only law for `schemaToShape`: a `format: true`-tuned
- * endpoint still ACCEPTS a non-conforming string in a format-tagged slot. A key NOT present in
- * the inferred (closed, `additionalProperties: false`) schema is NEVER a rejection either — it is
- * SILENTLY DROPPED before `execute` runs (the same leniency `@orkestrel/contract`'s own `parse`
+ * endpoint still accepts a non-conforming string in a format-tagged slot. A key not present in
+ * the inferred (closed, `additionalProperties: false`) schema is never a rejection either — it is
+ * silently dropped before `execute` runs (the same leniency `@orkestrel/contract`'s own `parse`
  * grants a closed object generally), so `execute` may see fewer keys than the caller sent. Set
  * `validate: false` when the endpoint's own handler validates its arguments, or when `samples`
  * under-describe the real contract and the normalizing coercion would corrupt a call: the tool's
@@ -1550,15 +1622,15 @@ export declare interface EndpointToolOptions {
 }
 
 /**
- * Expands the relation tool's FLAT dot-path `include` list into a live `@orkestrel/relation`
+ * Expands the relation tool's flat dot-path `include` list into a live `@orkestrel/relation`
  * {@link Include} tree — the pure leaf {@link import('./factories.js').createRelationTool} calls
  * before a `'load'` / `'find'` call.
  *
  * @remarks
  * Each path splits on `'.'` into a chain of relation names, deep-merged into one nested
- * `Include` object with a leaf `true`. A longer path SUBSUMES a shorter sibling's bare `true` —
+ * `Include` object with a leaf `true`. A longer path subsumes a shorter sibling's bare `true` —
  * `'contacts'` followed by `'contacts.account'` yields `{ contacts: { account: true } }`, never
- * overwriting the deeper chain. An EMPTY segment (`''`, from a leading/trailing/doubled `.`) or a
+ * overwriting the deeper chain. An empty segment (`''`, from a leading/trailing/doubled `.`) or a
  * path whose segment count exceeds `depth` throws a typed `TOOL` {@link ToolboxError}.
  *
  * @param paths - The flat dot-path `include` list (or `undefined` — yields `{}`)
@@ -1577,18 +1649,18 @@ export declare function expandInclude(paths: readonly string[] | undefined, dept
 
 /**
  * Expands a flat {@link WorkflowSteps} blob into a strict {@link WorkflowDefinition} — each step
- * becomes a one-task phase, IN ORDER.
+ * becomes a one-task phase, in order.
  *
  * @remarks
- * The expansion of the tool's ADVERTISED surface: the deliberately-reduced flat form. Each
+ * The expansion of the tool's advertised surface: the deliberately-reduced flat form. Each
  * {@link import('./types.js').WorkflowStep} maps to a phase holding exactly one task: the step's
  * `name` becomes the task's `behavior` (the behavior-registry key). Ids/names are auto-filled
  * positionally — it builds an ids-omitted {@link WorkflowDraft} and delegates to
- * {@link completeDraft}, so the two lenient surfaces share ONE synthesis path (step `i` → phase
+ * {@link completeDraft}, so the lenient surfaces share one synthesis path (step `i` → phase
  * `phase-<i>`, its task `phase-<i>-task-0`). The optional `name` becomes both the workflow's
  * deterministic id and its name, so named flat workflows retain distinct persistence keys;
  * omission keeps the shared draft fallback `wf`. The result is a complete definition the caller
- * validates against the STRICT contract before running.
+ * validates against the strict contract before running.
  *
  * @param flat - The flat steps blob (`{ name?, steps: [{ name }] }`)
  * @returns A complete {@link WorkflowDefinition} (one one-task phase per step)
@@ -1618,21 +1690,29 @@ export declare function extendLineage(lineage: WorkflowLineage, tag: string): Wo
 /** Describes the flat dot-path relation include list, expanded through {@link import('./helpers.js').expandInclude}. */
 export declare const includeShape: OptionalShape<ArrayShape<StringShape>>;
 
-/** Holds the schema-inference protocol {@link import('./factories.js').createInferTool} advertises. */
+/**
+ * Holds the schema-inference protocol {@link import('./factories.js').createInferTool} advertises —
+ * the required `samples`, the optional `format`, `enum`, and `candidates` arguments, and a worked
+ * example of the bare return and of the `candidates`-wrapped return.
+ */
 export declare const INFER_TOOL_DESCRIPTION: string;
 
 /**
- * Holds the name {@link import('./factories.js').createInferTool} advertises by default — the key a
- * model calls and the `ToolManagerInterface` (`@orkestrel/tool`) registers under.
+ * Holds the name {@link import('./factories.js').createInferTool} advertises by default, `'infer'`
+ * — the key a model calls and the `ToolManagerInterface` (`@orkestrel/tool`) registers under.
  */
 export declare const INFER_TOOL_NAME = "infer";
 
 /**
- * Holds the lean {@link import('@orkestrel/tool').ToolInterface.summary} {@link import('./factories.js').createInferTool}
- * advertises in place of {@link INFER_TOOL_DESCRIPTION} — a `ToolManagerInterface.definitions()`
- * (`@orkestrel/tool`) advertises `summary ?? description`, so this one-sentence text stands in
- * for the full teaching description; the full text stays retrievable through
- * {@link import('./factories.js').createDescribeTool}.
+ * Holds the lean {@link import('@orkestrel/tool').ToolInterface.summary}
+ * {@link import('./factories.js').createInferTool} advertises in place of
+ * {@link INFER_TOOL_DESCRIPTION} — one sentence offering schema inference from example values and
+ * pointing at `describe` for the fields it takes.
+ *
+ * @remarks
+ * A `ToolManagerInterface.definitions()` call (`@orkestrel/tool`) advertises
+ * `summary ?? description`, so this one-sentence text stands in for the full teaching description;
+ * the full text stays retrievable through {@link import('./factories.js').createDescribeTool}.
  */
 export declare const INFER_TOOL_SUMMARY = "Infer a JSON Schema (as advertised tool parameters) from one or more example values. Call describe('infer') for the required fields.";
 
@@ -1676,9 +1756,9 @@ export declare function inferRelationCode(error: unknown): RelationErrorCode | u
 export declare function inferTerminalCode(error: unknown): ToolboxErrorCode | undefined;
 
 /**
- * Represents the options for {@link import('./factories.js').createInferTool} — advertised name/description
- * overrides only; `format` / `enum` are RUNTIME call arguments (see
- * {@link import('./shapers.js').inferToolShape}), not construction-time options, since a model
+ * Represents the options for {@link import('./factories.js').createInferTool} — advertised name and
+ * description overrides only; `format` and `enum` are runtime call arguments (see
+ * {@link import('./shapers.js').inferToolShape}), not construction-time options, because a model
  * chooses them per call.
  */
 export declare interface InferToolOptions {
@@ -1695,15 +1775,15 @@ export declare interface InferToolOptions {
  * `samples` requires at least one element (`min: 1`) — an empty array parses to `undefined`,
  * surfaced by the handler as a typed `TOOL` {@link import('./errors.js').ToolboxError}. When
  * `candidates` is present (any array, including empty), the handler compiles a contract from the
- * freshly inferred schema and checks each candidate against it with a STRICT guard (`.is`, no
- * coercion) — the opposite of {@link import('./factories.js').createEndpointTool}'s NORMALIZING
+ * freshly inferred schema and checks each candidate against it with a strict guard (`.is`, no
+ * coercion) — the opposite of {@link import('./factories.js').createEndpointTool}'s normalizing
  * `.parse` enforcement.
  */
-export declare const inferToolShape: ObjectShape<{
-    samples: ArrayShape<JSONShape>;
-    format: OptionalShape<BooleanShape>;
-    enum: OptionalShape<BooleanShape>;
-    candidates: OptionalShape<ArrayShape<JSONShape>>;
+export declare const inferToolShape: ObjectShape<    {
+samples: ArrayShape<JSONShape>;
+format: OptionalShape<BooleanShape>;
+enum: OptionalShape<BooleanShape>;
+candidates: OptionalShape<ArrayShape<JSONShape>>;
 }, false>;
 
 /**
@@ -1731,7 +1811,7 @@ export declare function isColumnPrimitive(value: unknown): value is ColumnPrimit
 export declare function isColumnSpec(value: unknown): value is ColumnSpec;
 
 /**
- * Narrows an unknown value to a {@link DatabaseDefinition} — a non-empty `id` + `driver`, a
+ * Narrows an unknown value to a {@link DatabaseDefinition} — a non-empty `id` and `driver`, a
  * `tables` record whose every value is `{ columns: record of valid ColumnSpec }`, plus optional
  * `primary`, `indexes`, and finite `version` schema configuration. The boundary guard a
  * {@link import('./types.js').DefinitionStoreInterface} applies to an untrusted persisted blob
@@ -1743,7 +1823,7 @@ export declare function isColumnSpec(value: unknown): value is ColumnSpec;
 export declare function isDatabaseDefinition(value: unknown): value is DatabaseDefinition;
 
 /**
- * Narrows an unknown caught value to an {@link ToolboxError}.
+ * Narrows an unknown caught value to a {@link ToolboxError}.
  *
  * @param value - The value to test (typically a `catch` binding)
  * @returns True if `value` is an {@link ToolboxError}; false otherwise
@@ -1769,14 +1849,18 @@ export declare function isToolboxError(value: unknown): value is ToolboxError;
  */
 export declare function isWorkflowLineage(value: unknown): value is WorkflowLineage;
 
-/** Describes one key value for the database tool and the relation tool — a string or number; the array form (multiple keys, positional) resolves FIRST, so an array argument is read as many keys rather than one. */
-export declare const keyShape: UnionShape<readonly [ ArrayShape<UnionShape<readonly [ StringShape, NumberShape]>>, StringShape, NumberShape]>;
+/**
+ * Describes one key value for the database tool and the relation tool — a string or number; the
+ * array form (multiple keys, positional) resolves first, so an array argument is read as many keys
+ * rather than one.
+ */
+export declare const keyShape: UnionShape<readonly [ArrayShape<UnionShape<readonly [StringShape, NumberShape]>>, StringShape, NumberShape]>;
 
 /** Describes which registered relation manager to address — omitted resolves to the sole registered manager. */
 export declare const managerShape: OptionalShape<StringShape>;
 
 /**
- * Holds the maximum nesting depth a workflow → agent → workflow chain may reach — the bound
+ * Holds the maximum nesting depth a workflow → agent → workflow chain may reach, `8` — the bound
  * {@link import('./factories.js').createAgentFunction} and
  * {@link import('./factories.js').createWorkflowTool}'s depth/cycle guards enforce.
  *
@@ -1789,7 +1873,7 @@ export declare const MAX_WORKFLOW_CHAIN = 8;
 
 /**
  * Represents the in-memory {@link DefinitionStoreInterface} — a process-lifetime `Map` of
- * {@link DatabaseDefinition}s keyed by database id, the DEFAULT store
+ * {@link DatabaseDefinition}s keyed by database id, the default store
  * {@link import('../factories.js').createMemoryDefinitionStore} builds. It implements the same
  * {@link DefinitionStoreInterface} contract as
  * {@link import('./DatabaseDefinitionStore.js').DatabaseDefinitionStore}: this store copies on
@@ -1798,19 +1882,19 @@ export declare const MAX_WORKFLOW_CHAIN = 8;
  *
  * @remarks
  * A plain `Map<string, DatabaseDefinition>` (the definition is already pure,
- * self-contained CONFIG-only JSON, so no encoding is needed for the memory tier). Values are
- * structured-cloned on both write and read, keeping caller mutation outside the store. There is NO
- * idle-TTL and NO eviction: a persisted definition lives until an explicit `delete`. A durable
- * backend (JSON / SQLite / IndexedDB) swaps in through the SAME interface without touching a
+ * self-contained config-only JSON, so no encoding is needed for the memory tier). Values are
+ * structured-cloned on both write and read, keeping caller mutation outside the store. There is no
+ * idle-TTL and no eviction: a persisted definition lives until an explicit `delete`. A durable
+ * backend (JSON / SQLite / IndexedDB) swaps in through the same interface without touching a
  * consumer — its driver-pluggable twin is
  * {@link import('./DatabaseDefinitionStore.js').DatabaseDefinitionStore} (the definition as one
  * opaque JSON column).
  *
  * - **`get` resolves the persisted definition for an id**, or `undefined` if none is stored.
- * - **`set` inserts / replaces under the definition's OWN `id`** (no separate id param).
+ * - **`set` inserts / replaces under the definition's own `id`** (no separate id param).
  * - **`delete` drops a definition by id**; an absent id is a no-op (no throw).
  *
- * The public surface is EXACTLY `get` / `set` / `delete` — no extra members (the method
+ * The public surface is exactly `get` / `set` / `delete` — no extra members (the method
  * bijection with {@link DefinitionStoreInterface}).
  *
  * @example
@@ -1833,17 +1917,17 @@ export declare class MemoryDefinitionStore implements DefinitionStoreInterface {
      */
     get(id: string): Promise<DatabaseDefinition | undefined>;
     /**
-     * Inserts or replaces a definition under its OWN `id`, copied into the backing `Map`.
+     * Inserts or replaces a definition under its own `id`, copied into the backing `Map`.
      *
      * @param definition - The config to persist; its own `id` is the key (no separate id param)
-     * @returns A promise settling once the definition is stored
+     * @returns A promise settling after the definition is stored
      */
     set(definition: DatabaseDefinition): Promise<void>;
     /**
      * Drops the definition stored under `id`.
      *
      * @param id - The database id to drop; an absent id is a no-op, never a throw
-     * @returns A promise settling once no definition is stored under `id`
+     * @returns A promise settling after no definition is stored under `id`
      */
     delete(id: string): Promise<void>;
 }
@@ -1858,11 +1942,11 @@ export declare function normalizeLineage(lineage?: WorkflowLineage): WorkflowLin
 
 /**
  * Returns the canonical live `@orkestrel/database` {@link QueryInput} for the database tool's
- * parsed SERIALIZED query — each condition's OMITTED `connector` defaults to `'and'`.
+ * parsed serialized query — each condition's omitted `connector` defaults to `'and'`.
  *
  * @remarks
  * The wire form ({@link import('./shapers.js').databaseToolShape}) lets a caller drop `connector`
- * on the last condition (it has nothing to join FORWARD to); the compiled `Condition` a live
+ * on the last condition (it has nothing to join forward to); the compiled `Condition` a live
  * `@orkestrel/database` table call accepts always carries one, so this fills the gap. `order` /
  * `limit` / `offset` pass through unchanged. Pure and total.
  *
@@ -1871,13 +1955,16 @@ export declare function normalizeLineage(lineage?: WorkflowLineage): WorkflowLin
  */
 export declare function normalizeQuery(query: DatabaseQueryInput | undefined): QueryInput | undefined;
 
-/** Describes one sort term. */
-export declare const orderShape: ObjectShape<{
-    column: StringShape;
-    direction: LiteralShape<readonly ["ascending", "descending"]>;
+/** Describes one sort term — a `column` to sort by and the `direction` to sort it in. */
+export declare const orderShape: ObjectShape<    {
+column: StringShape;
+direction: LiteralShape<readonly ["ascending", "descending"]>;
 }, false>;
 
-/** Represents a draft phase — a `PhaseDefinition` (`@orkestrel/workflow`) with OPTIONAL `id` / `name` and {@link TaskDraft} tasks. */
+/**
+ * Represents a draft phase — a `PhaseDefinition` (`@orkestrel/workflow`) with optional `id` and
+ * `name` and {@link TaskDraft} tasks.
+ */
 export declare interface PhaseDraft {
     readonly id?: string;
     readonly name?: string;
@@ -1885,45 +1972,53 @@ export declare interface PhaseDraft {
     readonly tasks: readonly TaskDraft[];
     /** Caps the tasks in flight at once (a resource throttle); omitted ⇒ unbounded. */
     readonly concurrency?: number;
-    /** Holds the per-phase failure-policy OVERRIDE; omitted ⇒ inherits the workflow `bail`. */
+    /** Holds the per-phase failure-policy override; omitted ⇒ inherits the workflow `bail`. */
     readonly bail?: boolean;
 }
 
 /**
- * Describes the shape of a PHASE in a draft workflow — identical to a strict phase shape EXCEPT `id` and
- * `name` are OPTIONAL, and its tasks are {@link taskDraftShape}s.
- */
-export declare const phaseDraftShape: ObjectShape<{
-    id: OptionalShape<StringShape>;
-    name: OptionalShape<StringShape>;
-    description: OptionalShape<StringShape>;
-    tasks: ArrayShape<ObjectShape<{
-        id: OptionalShape<StringShape>;
-        name: OptionalShape<StringShape>;
-        description: OptionalShape<StringShape>;
-        behavior: OptionalShape<StringShape>;
-        retries: OptionalShape<NumberShape>;
-        timeout: OptionalShape<NumberShape>;
-    }, false>>;
-    concurrency: OptionalShape<NumberShape>;
-    bail: OptionalShape<LiteralShape<readonly [true, false]>>;
+ * Describes the shape of a phase in a draft workflow — identical to a strict phase shape except
+ * that `id` and `name` are optional and each task takes {@link taskDraftShape}.
+ */
+export declare const phaseDraftShape: ObjectShape<    {
+id: OptionalShape<StringShape>;
+name: OptionalShape<StringShape>;
+description: OptionalShape<StringShape>;
+tasks: ArrayShape<ObjectShape<    {
+id: OptionalShape<StringShape>;
+name: OptionalShape<StringShape>;
+description: OptionalShape<StringShape>;
+behavior: OptionalShape<StringShape>;
+retries: OptionalShape<NumberShape>;
+timeout: OptionalShape<NumberShape>;
+}, false>>;
+concurrency: OptionalShape<NumberShape>;
+bail: OptionalShape<LiteralShape<readonly [true, false]>>;
 }, false>;
 
-/** Holds the full form protocol {@link import('./factories.js').createPromptTool} advertises. */
+/**
+ * Holds the form protocol {@link import('./factories.js').createPromptTool} advertises — the
+ * required `to` and `schema`, how a field declares its control and its rules, and a worked
+ * example.
+ */
 export declare const PROMPT_TOOL_DESCRIPTION: string;
 
 /**
- * Holds the name {@link import('./factories.js').createPromptTool} advertises by default — the key a
- * model calls and the `ToolManagerInterface` (`@orkestrel/tool`) registers under.
+ * Holds the name {@link import('./factories.js').createPromptTool} advertises by default, `'ask'` —
+ * the key a model calls and the `ToolManagerInterface` (`@orkestrel/tool`) registers under.
  */
 export declare const PROMPT_TOOL_NAME = "ask";
 
 /**
- * Holds the lean {@link import('@orkestrel/tool').ToolInterface.summary} {@link import('./factories.js').createPromptTool}
- * advertises in place of {@link PROMPT_TOOL_DESCRIPTION} — a `ToolManagerInterface.definitions()`
- * (`@orkestrel/tool`) advertises `summary ?? description`, so this one-sentence text stands in
- * for the full teaching description; the full text stays retrievable through
- * {@link import('./factories.js').createDescribeTool}.
+ * Holds the lean {@link import('@orkestrel/tool').ToolInterface.summary}
+ * {@link import('./factories.js').createPromptTool} advertises in place of
+ * {@link PROMPT_TOOL_DESCRIPTION} — one sentence offering the blocking multi-field ask and pointing
+ * at `describe` for the schema.
+ *
+ * @remarks
+ * A `ToolManagerInterface.definitions()` call (`@orkestrel/tool`) advertises
+ * `summary ?? description`, so this one-sentence text stands in for the full teaching description;
+ * the full text stays retrievable through {@link import('./factories.js').createDescribeTool}.
  */
 export declare const PROMPT_TOOL_SUMMARY = "Ask another terminal a multi-field form and BLOCK until it answers; the call resolves with the values record. Call describe('ask') for the schema.";
 
@@ -1934,10 +2029,10 @@ export declare const PROMPT_TOOL_SUMMARY = "Ask another terminal a multi-field f
  *
  * @remarks
  * - `manager` — the terminal manager whose `ask(from, to, form)` the tool's handler calls with a
- *   live `@orkestrel/form` form; BLOCKS the calling agent turn until the addressed terminal answers (or the ask
+ *   live `@orkestrel/form` form; blocks the calling agent turn until the addressed terminal answers (or the ask
  *   rejects — a cycle throws `TerminalError('DEADLOCK')`, re-surfaced as a typed `DEADLOCK`
  *   {@link import('./errors.js').ToolboxError}; an expired prompt re-surfaces as `EXPIRE`).
- * - `from` — the terminal identity this tool asks AS; the model supplies the `to` target and the
+ * - `from` — the terminal identity this tool asks as; the model supplies the `to` target and the
  *   complete form schema per call.
  * - `name` / `description` — advertised tool overrides; default to
  *   {@link import('./constants.js').PROMPT_TOOL_NAME} / {@link import('./constants.js').PROMPT_TOOL_DESCRIPTION}.
@@ -1957,63 +2052,80 @@ export declare interface PromptToolOptions {
  * The contract first requires exact JSON. The handler then delegates schema parsing and semantic
  * validation to `@orkestrel/form`'s `parseForm`, so Toolbox does not duplicate the form schema.
  */
-export declare const promptToolShape: ObjectShape<{
-    to: StringShape;
-    schema: JSONShape;
+export declare const promptToolShape: ObjectShape<    {
+to: StringShape;
+schema: JSONShape;
 }, false>;
 
-/** Describes the SERIALIZED query form — conditions, order, and pagination. */
-export declare const queryShape: ObjectShape<{
-    conditions: OptionalShape<ArrayShape<ObjectShape<{
-        column: StringShape;
-        operator: LiteralShape<readonly ["equals", "not", "above", "below", "from", "to", "between", "like", "glob", "starts", "ends", "any", "none", "absent", "present"]>;
-        values: ArrayShape<JSONShape>;
-        connector: OptionalShape<LiteralShape<readonly ["and", "or"]>>;
-    }, false>>>;
-    order: OptionalShape<ArrayShape<ObjectShape<{
-        column: StringShape;
-        direction: LiteralShape<readonly ["ascending", "descending"]>;
-    }, false>>>;
-    limit: OptionalShape<NumberShape>;
-    offset: OptionalShape<NumberShape>;
+/** Describes the serialized query form — conditions, order, and pagination. */
+export declare const queryShape: ObjectShape<    {
+conditions: OptionalShape<ArrayShape<ObjectShape<    {
+column: StringShape;
+operator: LiteralShape<readonly ["equals", "not", "above", "below", "from", "to", "between", "like", "glob", "starts", "ends", "any", "none", "absent", "present"]>;
+values: ArrayShape<JSONShape>;
+connector: OptionalShape<LiteralShape<readonly ["and", "or"]>>;
+}, false>>>;
+order: OptionalShape<ArrayShape<ObjectShape<    {
+column: StringShape;
+direction: LiteralShape<readonly ["ascending", "descending"]>;
+}, false>>>;
+limit: OptionalShape<NumberShape>;
+offset: OptionalShape<NumberShape>;
 }, false>;
 
-/** Holds the default cap on how many `include` path segments deep a `load` / `find` call may traverse — the relation tool's default include-depth ceiling. */
+/**
+ * Holds the default cap on how many `include` path segments deep a `load` or `find` call may
+ * traverse, `3` — the relation tool's default include-depth ceiling.
+ */
 export declare const RELATION_TOOL_DEPTH = 3;
 
 /**
- * Holds the DESCRIPTION the relation tool advertises — a multi-line guide that teaches a small model
- * the operation list and the flat dot-path `include` syntax.
+ * Holds the description {@link import('./factories.js').createRelationTool} advertises — a
+ * multi-line guide that teaches a small model the operation list and the flat dot-path `include`
+ * syntax.
  *
  * @remarks
- * An include path is a FLAT dot-separated string (`'contacts.account'`), never a nested object —
+ * An include path is a flat dot-separated string (`'contacts.account'`), never a nested object —
  * the same small-model ergonomic lever the other tools in this package use for flat args.
  */
 export declare const RELATION_TOOL_DESCRIPTION: string;
 
-/** Holds the default cap on rows a `find` / `links` call returns when the caller omits `limit` — the relation tool's default row ceiling. */
+/**
+ * Holds the default cap on rows a `find` or `links` call returns when the caller omits `limit`,
+ * `1000` — the relation tool's default row ceiling.
+ */
 export declare const RELATION_TOOL_LIMIT = 1000;
 
 /**
- * Holds the name `createRelationTool` advertises by default — the key a model calls and the
- * `ToolManagerInterface` (`@orkestrel/tool`) registers under.
+ * Holds the name {@link import('./factories.js').createRelationTool} advertises by default,
+ * `'relation'` — the key a model calls and the `ToolManagerInterface` (`@orkestrel/tool`) registers
+ * under.
  */
 export declare const RELATION_TOOL_NAME = "relation";
 
 /**
- * Holds the lean {@link import('@orkestrel/tool').ToolInterface.summary} the relation tool advertises
- * in place of {@link RELATION_TOOL_DESCRIPTION}.
+ * Holds the lean {@link import('@orkestrel/tool').ToolInterface.summary}
+ * {@link import('./factories.js').createRelationTool} advertises in place of
+ * {@link RELATION_TOOL_DESCRIPTION} — one sentence offering the `operation`-keyed relationship
+ * traversal and pointing at `describe` for the include-path syntax.
+ *
+ * @remarks
+ * A `ToolManagerInterface.definitions()` call (`@orkestrel/tool`) advertises
+ * `summary ?? description`, so this one-sentence text stands in for the full teaching description;
+ * the full text stays retrievable through {@link import('./factories.js').createDescribeTool}.
  */
 export declare const RELATION_TOOL_SUMMARY = "Traverse and edit relationships between database rows \u2014 one operation per call (load, find, link, unlink, links), chosen by the 'operation' field. Call describe('relation') for the include-path syntax.";
 
 /**
- * Represents the options for {@link import('./factories.js').createRelationTool}.
+ * Represents the options for {@link import('./factories.js').createRelationTool} — the required
+ * live `RelationManagerInterface` registry a call addresses, the row cap, and the `include` depth
+ * cap.
  *
  * @remarks
  * - `managers` — the live `RelationManagerInterface` (`@orkestrel/relation`) registry a call's
- *   optional `manager` field addresses by name; REQUIRED (unlike the database tool's lazily
+ *   optional `manager` field addresses by name; required (unlike the database tool's lazily
  *   resolved handles, a relation manager's relations are declared up front and cannot be minted
- *   on demand from a tool call). A call that omits `manager` resolves to the SOLE registered
+ *   on demand from a tool call). A call that omits `manager` resolves to the sole registered
  *   manager when exactly one is registered, else throws a typed `TOOL`
  *   {@link import('./errors.js').ToolboxError} naming the registered manager keys.
  * - `limit` — the row cap `'find'` / `'links'` enforce when a call's `limit` is omitted or
@@ -2034,49 +2146,49 @@ export declare interface RelationToolOptions {
 
 /**
  * Describes the shape of {@link import('./factories.js').createRelationTool}'s call arguments —
- * discriminated by `operation` into the 5 relation operations (`'load'` / `'find'` / `'link'` /
- * `'unlink'` / `'links'`).
+ * discriminated by `operation` into the relation operations `'load'`, `'find'`, `'link'`,
+ * `'unlink'`, and `'links'`.
  *
  * @remarks
  * `'load'` fetches one or more rows (positional key/array) with `include` attached. `'find'`
  * fetches rows (pagination / sort only) with `include` attached. `'link'` / `'unlink'` write /
  * remove a `through` junction row; `'links'` lists a `through` relation's linked keys.
  */
-export declare const relationToolShape: UnionShape<readonly [ ObjectShape<{
-    operation: LiteralShape<readonly ["load"]>;
-    manager: OptionalShape<StringShape>;
-    model: StringShape;
-    key: UnionShape<readonly [ ArrayShape<UnionShape<readonly [ StringShape, NumberShape]>>, StringShape, NumberShape]>;
-    include: OptionalShape<ArrayShape<StringShape>>;
-}, false>, ObjectShape<{
-    operation: LiteralShape<readonly ["find"]>;
-    manager: OptionalShape<StringShape>;
-    model: StringShape;
-    include: OptionalShape<ArrayShape<StringShape>>;
-    limit: OptionalShape<NumberShape>;
-    offset: OptionalShape<NumberShape>;
-    sort: OptionalShape<StringShape>;
-    direction: OptionalShape<LiteralShape<readonly ["ascending", "descending"]>>;
-}, false>, ObjectShape<{
-    operation: LiteralShape<readonly ["link"]>;
-    manager: OptionalShape<StringShape>;
-    model: StringShape;
-    key: UnionShape<readonly [ StringShape, NumberShape]>;
-    relation: StringShape;
-    target: UnionShape<readonly [ StringShape, NumberShape]>;
-}, false>, ObjectShape<{
-    operation: LiteralShape<readonly ["unlink"]>;
-    manager: OptionalShape<StringShape>;
-    model: StringShape;
-    key: UnionShape<readonly [ StringShape, NumberShape]>;
-    relation: StringShape;
-    target: UnionShape<readonly [ StringShape, NumberShape]>;
-}, false>, ObjectShape<{
-    operation: LiteralShape<readonly ["links"]>;
-    manager: OptionalShape<StringShape>;
-    model: StringShape;
-    key: UnionShape<readonly [ StringShape, NumberShape]>;
-    relation: StringShape;
+export declare const relationToolShape: UnionShape<readonly [ObjectShape<    {
+operation: LiteralShape<readonly ["load"]>;
+manager: OptionalShape<StringShape>;
+model: StringShape;
+key: UnionShape<readonly [ArrayShape<UnionShape<readonly [StringShape, NumberShape]>>, StringShape, NumberShape]>;
+include: OptionalShape<ArrayShape<StringShape>>;
+}, false>, ObjectShape<    {
+operation: LiteralShape<readonly ["find"]>;
+manager: OptionalShape<StringShape>;
+model: StringShape;
+include: OptionalShape<ArrayShape<StringShape>>;
+limit: OptionalShape<NumberShape>;
+offset: OptionalShape<NumberShape>;
+sort: OptionalShape<StringShape>;
+direction: OptionalShape<LiteralShape<readonly ["ascending", "descending"]>>;
+}, false>, ObjectShape<    {
+operation: LiteralShape<readonly ["link"]>;
+manager: OptionalShape<StringShape>;
+model: StringShape;
+key: UnionShape<readonly [StringShape, NumberShape]>;
+relation: StringShape;
+target: UnionShape<readonly [StringShape, NumberShape]>;
+}, false>, ObjectShape<    {
+operation: LiteralShape<readonly ["unlink"]>;
+manager: OptionalShape<StringShape>;
+model: StringShape;
+key: UnionShape<readonly [StringShape, NumberShape]>;
+relation: StringShape;
+target: UnionShape<readonly [StringShape, NumberShape]>;
+}, false>, ObjectShape<    {
+operation: LiteralShape<readonly ["links"]>;
+manager: OptionalShape<StringShape>;
+model: StringShape;
+key: UnionShape<readonly [StringShape, NumberShape]>;
+relation: StringShape;
 }, false>]>;
 
 /**
@@ -2110,7 +2222,7 @@ export declare function resolveLimit(requested: number | undefined, cap: number)
  *
  * @remarks
  * An explicit `name` must match a key of `managers` (a miss throws a typed `TOOL`
- * {@link ToolboxError} naming the registered managers). An OMITTED `name` resolves to the sole
+ * {@link ToolboxError} naming the registered managers). An omitted `name` resolves to the sole
  * registered manager when exactly one is registered, else throws the same typed error.
  *
  * @param managers - The tool's registered `RelationManagerInterface` map
@@ -2130,33 +2242,37 @@ export declare function resolveRelationManager(managers: Readonly<Record<string,
  */
 export declare function resolveRelationModel(manager: RelationManagerInterface, name: string): ModelInterface;
 
-/** Describes a loose row — a flat object of column name to JSON value; the array form (multiple rows) resolves FIRST, so an array argument is read as many rows rather than one. */
+/** Describes a loose row — a flat object of column name to JSON value. */
 export declare const rowShape: ObjectShape<Record<never, never>, JSONShape>;
 
-/** Describes one or many loose rows — the array form resolves FIRST, so an array argument is read as many rows rather than one. */
-export declare const rowsShape: UnionShape<readonly [ ArrayShape<ObjectShape<Record<never, never>, JSONShape>>, ObjectShape<Record<never, never>, JSONShape>]>;
+/**
+ * Describes one or many loose rows — the array form resolves first, so an array argument is read as
+ * many rows rather than one.
+ */
+export declare const rowsShape: UnionShape<readonly [ArrayShape<ObjectShape<Record<never, never>, JSONShape>>, ObjectShape<Record<never, never>, JSONShape>]>;
 
 /** Describes a single row key (not an array) — used by `'link'` / `'unlink'` / `'links'`, which address exactly one owning row. */
-export declare const singleKeyShape: UnionShape<readonly [ StringShape, NumberShape]>;
+export declare const singleKeyShape: UnionShape<readonly [StringShape, NumberShape]>;
 
 /**
- * Describes the shape of ONE flat step — `{ name }` — the building block of {@link workflowStepsShape}.
+ * Describes the shape of one flat step — `{ name }` — the building block of
+ * {@link workflowStepsShape}.
  *
  * @remarks
- * `name` is the REGISTERED behavior name the step runs (it becomes the task's `behavior`). The tool
+ * `name` is the registered behavior name the step runs (it becomes the task's `behavior`). The tool
  * expands each step into a one-task phase, in order ({@link import('./helpers.js').expandSteps}).
  */
-export declare const stepShape: ObjectShape<{
-    name: StringShape;
+export declare const stepShape: ObjectShape<    {
+name: StringShape;
 }, false>;
 
 /**
- * Builds the plain success summary {@link import('./factories.js').createWorkflowTool} returns on
- * a completed run — the universal tool-handler contract: return a plain value on success,
- * appearing identically over BOTH the agent loop and MCP.
+ * Builds the plain success summary {@link import('./factories.js').createWorkflowTool} returns on a
+ * completed run — the universal tool-handler contract: return a plain value on success, appearing
+ * identically over both the agent loop and MCP.
  *
  * @remarks
- * The summary is LEAN: the workflow's terminal `status`, settled-task count, and exact optional
+ * The summary is lean: the workflow's terminal `status`, settled-task count, and exact optional
  * native persistence outcome. It carries no synthetic `id` / `name`: a tool handler has no call
  * id; the `ToolManagerInterface` (`@orkestrel/tool`) supplies the canonical envelope's identity.
  *
@@ -2175,11 +2291,11 @@ export declare type TableSpec = Readonly<Record<string, Readonly<{
 }>>>;
 
 /** Describes a {@link import('./types.js').TableSpec} — table name to `{ columns }`, each column a {@link columnSpecShape}. */
-export declare const tableSpecShape: ObjectShape<Record<never, never>, ObjectShape<{
-    columns: ObjectShape<Record<never, never>, UnionShape<readonly [ LiteralShape<readonly ["string", "integer", "number", "boolean"]>, ObjectShape<{
-        primitive: LiteralShape<readonly ["string", "integer", "number", "boolean"]>;
-        optional: OptionalShape<BooleanShape>;
-    }, false>]>>;
+export declare const tableSpecShape: ObjectShape<Record<never, never>, ObjectShape<    {
+columns: ObjectShape<Record<never, never>, UnionShape<readonly [LiteralShape<readonly ["string", "integer", "number", "boolean"]>, ObjectShape<    {
+primitive: LiteralShape<readonly ["string", "integer", "number", "boolean"]>;
+optional: OptionalShape<BooleanShape>;
+}, false>]>>;
 }, false>>;
 
 /**
@@ -2200,8 +2316,8 @@ export declare function tagAgent(name: string): string;
  * Returns the ancestry identifier of a workflow in a run chain — `workflow:<id>`.
  *
  * @remarks
- * Namespacing keeps a workflow id and a {@link tagAgent} agent name in ONE set without
- * collision, so re-entering a workflow OR an agent already in the chain is a single `includes`
+ * Namespacing keeps a workflow id and a {@link tagAgent} agent name in one set without
+ * collision, so re-entering a workflow or an agent already in the chain is a single `includes`
  * check.
  *
  * @param id - The workflow definition's `id`
@@ -2210,11 +2326,12 @@ export declare function tagAgent(name: string): string;
 export declare function tagWorkflow(id: string): string;
 
 /**
- * Represents a draft task — a `TaskDefinition` (`@orkestrel/workflow`) with OPTIONAL `id` / `name`.
+ * Represents a draft task — a `TaskDefinition` (`@orkestrel/workflow`) with optional `id` and
+ * `name`.
  *
  * @remarks
  * The tool synthesizes a missing `id` positionally and defaults a missing `name` to its `id`
- * ({@link import('./helpers.js').completeDraft}). A PROVIDED `id` / `name` is preserved verbatim
+ * ({@link import('./helpers.js').completeDraft}). A provided `id` / `name` is preserved verbatim
  * (and must be non-empty — the draft contract's `minLength: 1`).
  */
 export declare interface TaskDraft {
@@ -2230,16 +2347,16 @@ export declare interface TaskDraft {
 }
 
 /**
- * Describes the shape of a {@link import('./types.js').TaskDraft} — identical to a strict task shape
- * EXCEPT `id` and `name` are OPTIONAL.
+ * Describes the shape of a {@link import('./types.js').TaskDraft} — identical to a strict task
+ * shape except that `id` and `name` are optional.
  */
-export declare const taskDraftShape: ObjectShape<{
-    id: OptionalShape<StringShape>;
-    name: OptionalShape<StringShape>;
-    description: OptionalShape<StringShape>;
-    behavior: OptionalShape<StringShape>;
-    retries: OptionalShape<NumberShape>;
-    timeout: OptionalShape<NumberShape>;
+export declare const taskDraftShape: ObjectShape<    {
+id: OptionalShape<StringShape>;
+name: OptionalShape<StringShape>;
+description: OptionalShape<StringShape>;
+behavior: OptionalShape<StringShape>;
+retries: OptionalShape<NumberShape>;
+timeout: OptionalShape<NumberShape>;
 }, false>;
 
 /**
@@ -2250,7 +2367,7 @@ export declare const taskDraftShape: ObjectShape<{
  * @remarks
  * Carries a machine-readable `code` (see {@link import('./types.js').ToolboxErrorCode}) and
  * an optional `context` bag for structured diagnostics. They are readable through an in-process
- * catch, including around a direct `tool.execute(args)` call. The `ToolManagerInterface`
+ * catch, including around a direct `tool.execute(args, context)` call. The `ToolManagerInterface`
  * (`@orkestrel/tool`) instead flattens every throw to the canonical tool result's top-level
  * `error` message string under AGENTS' “narrow untrusted input with guards” rule.
  *
@@ -2302,48 +2419,52 @@ export declare type ToolboxErrorCode = 'TOOL' | 'DEPTH' | 'DEADLOCK' | 'EXPIRE'
 export declare const WORKFLOW_TOOL_DESCRIPTION: string;
 
 /**
- * Holds a complete FLAT authoring example — the PRIMARY way a small model authors a workflow through
- * {@link import('./factories.js').createWorkflowTool}: `{ name, steps: [{ name }] }`.
+ * Holds a complete flat authoring example — the primary way a small model authors a workflow
+ * through {@link import('./factories.js').createWorkflowTool}: `{ name, steps: [{ name }] }`.
  *
  * @remarks
  * Each step becomes a one-task phase, in
- * order; a step's `name` is a REGISTERED behavior name (not a label) — the registry key its
+ * order; a step's `name` is a registered behavior name (not a label) — the registry key its
  * task's `behavior` resolves against. The tool expands this
  * ({@link import('./helpers.js').expandSteps}) into a valid `WorkflowDefinition`
- * (`@orkestrel/workflow`). It is embedded VERBATIM in {@link WORKFLOW_TOOL_DESCRIPTION}.
+ * (`@orkestrel/workflow`). It is embedded verbatim in {@link WORKFLOW_TOOL_DESCRIPTION}.
  */
 export declare const WORKFLOW_TOOL_FLAT_EXAMPLE: WorkflowSteps;
 
 /**
- * Holds the name {@link import('./factories.js').createWorkflowTool} advertises by default — the key a
- * model calls and the `ToolManagerInterface` (`@orkestrel/tool`) registers under, and the name
- * {@link import('./factories.js').createAgentFunction} binds the depth/cycle-aware workflow tool
- * under onto a wrapped agent's `context.tools`.
+ * Holds the name {@link import('./factories.js').createWorkflowTool} advertises by default,
+ * `'workflow'` — the key a model calls and the `ToolManagerInterface` (`@orkestrel/tool`) registers
+ * under, and the name {@link import('./factories.js').createAgentFunction} binds the
+ * depth/cycle-aware workflow tool under onto a wrapped agent's `context.tools`.
  *
  * @remarks
  * The propagation seam's well-known key: when
  * `createAgentFunction`'s `runner` option is supplied, it adds a `createWorkflowTool`-built tool
- * under this name to the agent's `context.tools`, so it can author + run a NESTED workflow
+ * under this name to the agent's `context.tools`, so it can author and run a nested workflow
  * (bounded by {@link MAX_WORKFLOW_CHAIN}).
  */
 export declare const WORKFLOW_TOOL_NAME = "workflow";
 
 /**
- * Holds a minimal NESTED authoring example — the ADVANCED escape-hatch form a model may use instead of
- * the flat shape: a full `WorkflowDefinition` (`@orkestrel/workflow`).
+ * Holds a minimal nested authoring example — the advanced escape-hatch form a model can use instead
+ * of the flat shape: a full `WorkflowDefinition` (`@orkestrel/workflow`).
  *
  * @remarks
- * The full four-level form, documented in
- * {@link WORKFLOW_TOOL_DESCRIPTION} as the advanced alternative. It is embedded VERBATIM.
+ * The full nested form, documented in
+ * {@link WORKFLOW_TOOL_DESCRIPTION} as the advanced alternative. It is embedded verbatim.
  */
 export declare const WORKFLOW_TOOL_NESTED_EXAMPLE: WorkflowDefinition;
 
 /**
- * Holds the lean {@link import('@orkestrel/tool').ToolInterface.summary} {@link import('./factories.js').createWorkflowTool}
- * advertises in place of {@link WORKFLOW_TOOL_DESCRIPTION} — a `ToolManagerInterface.definitions()`
- * (`@orkestrel/tool`) advertises `summary ?? description`, so this one-sentence text stands in
- * for the full teaching description; the full text stays retrievable through
- * {@link import('./factories.js').createDescribeTool}.
+ * Holds the lean {@link import('@orkestrel/tool').ToolInterface.summary}
+ * {@link import('./factories.js').createWorkflowTool} advertises in place of
+ * {@link WORKFLOW_TOOL_DESCRIPTION} — one sentence offering multi-phase authoring and pointing at
+ * `describe` for the authoring schema and its examples.
+ *
+ * @remarks
+ * A `ToolManagerInterface.definitions()` call (`@orkestrel/tool`) advertises
+ * `summary ?? description`, so this one-sentence text stands in for the full teaching description;
+ * the full text stays retrievable through {@link import('./factories.js').createDescribeTool}.
  */
 export declare const WORKFLOW_TOOL_SUMMARY = "Author and run a multi-phase workflow in one call \u2014 phases run in sequence, tasks within a phase run concurrently. Call describe('workflow') for the full authoring schema and examples.";
 
@@ -2351,8 +2472,8 @@ export declare const WORKFLOW_TOOL_SUMMARY = "Author and run a multi-phase workf
 export declare type WorkflowAgents = Readonly<Record<string, AgentInterface>>;
 
 /**
- * Represents a draft workflow — a `WorkflowDefinition` (`@orkestrel/workflow`) with OPTIONAL `id` / `name`
- * at all three levels (workflow / phase / task).
+ * Represents a draft workflow — a `WorkflowDefinition` (`@orkestrel/workflow`) with optional `id`
+ * and `name` at the workflow, phase, and task levels.
  *
  * @remarks
  * The lenient authoring form {@link import('./factories.js').createWorkflowDraftContract}
@@ -2370,49 +2491,52 @@ export declare interface WorkflowDraft {
 }
 
 /**
- * Describes the shape of a DRAFT workflow — identical to a strict workflow shape EXCEPT `id` and `name`
- * are OPTIONAL at all three levels (workflow / phase / task), so a small model can omit the six
- * identity strings and let the tool synthesize them positionally.
+ * Describes the shape of a draft workflow — identical to a strict workflow shape except that `id`
+ * and `name` are optional at the workflow, phase, and task levels, so a small model can omit every
+ * identity string and let the tool synthesize them positionally.
  *
  * @remarks
  * The lenient counterpart {@link import('./factories.js').createWorkflowDraftContract} compiles.
  * `behavior` stays optional like the strict form; omission is the deliberate JSON `null` no-op. A
  * provided `id` / `name` still has `minLength: 1` (so
- * an explicitly-empty `id: ''` is REJECTED, not auto-filled). After
+ * an explicitly-empty `id: ''` is rejected, not auto-filled). After
  * {@link import('./helpers.js').completeDraft} fills the missing ids/names, the result is
- * validated against the STRICT `createWorkflowContract` (`@orkestrel/workflow`) gate before
+ * validated against the strict `createWorkflowContract` (`@orkestrel/workflow`) gate before
  * running.
  */
-export declare const workflowDraftShape: ObjectShape<{
-    id: OptionalShape<StringShape>;
-    name: OptionalShape<StringShape>;
-    description: OptionalShape<StringShape>;
-    phases: ArrayShape<ObjectShape<{
-        id: OptionalShape<StringShape>;
-        name: OptionalShape<StringShape>;
-        description: OptionalShape<StringShape>;
-        tasks: ArrayShape<ObjectShape<{
-            id: OptionalShape<StringShape>;
-            name: OptionalShape<StringShape>;
-            description: OptionalShape<StringShape>;
-            behavior: OptionalShape<StringShape>;
-            retries: OptionalShape<NumberShape>;
-            timeout: OptionalShape<NumberShape>;
-        }, false>>;
-        concurrency: OptionalShape<NumberShape>;
-        bail: OptionalShape<LiteralShape<readonly [true, false]>>;
-    }, false>>;
-    bail: OptionalShape<LiteralShape<readonly [true, false]>>;
+export declare const workflowDraftShape: ObjectShape<    {
+id: OptionalShape<StringShape>;
+name: OptionalShape<StringShape>;
+description: OptionalShape<StringShape>;
+phases: ArrayShape<ObjectShape<    {
+id: OptionalShape<StringShape>;
+name: OptionalShape<StringShape>;
+description: OptionalShape<StringShape>;
+tasks: ArrayShape<ObjectShape<    {
+id: OptionalShape<StringShape>;
+name: OptionalShape<StringShape>;
+description: OptionalShape<StringShape>;
+behavior: OptionalShape<StringShape>;
+retries: OptionalShape<NumberShape>;
+timeout: OptionalShape<NumberShape>;
+}, false>>;
+concurrency: OptionalShape<NumberShape>;
+bail: OptionalShape<LiteralShape<readonly [true, false]>>;
+}, false>>;
+bail: OptionalShape<LiteralShape<readonly [true, false]>>;
 }, false>;
 
-/** Represents one immutable workflow/agent call chain, beginning with a workflow tag. */
+/**
+ * Represents one immutable workflow/agent call chain — strictly alternating tags, each unique,
+ * beginning with a workflow tag.
+ */
 export declare type WorkflowLineage = readonly string[];
 
 /**
  * Represents one flat step — `{ name }` — the building block of a {@link WorkflowSteps} blob.
  *
  * @remarks
- * `name` is the REGISTERED behavior name the step runs (it becomes the task's `behavior`, NOT a
+ * `name` is the registered behavior name the step runs (it becomes the task's `behavior`, not a
  * human label) — resolved against a workflow-level functions registry at construction.
  */
 export declare interface WorkflowStep {
@@ -2421,13 +2545,13 @@ export declare interface WorkflowStep {
 }
 
 /**
- * Represents the FLAT authoring blob {@link import('./factories.js').createWorkflowTool} advertises —
- * `{ name?, steps }` — the simplest surface a small model can fill.
+ * Represents the flat authoring blob {@link import('./factories.js').createWorkflowTool} advertises
+ * — `{ name?, steps }` — the simplest surface a small model can fill.
  *
  * @remarks
  * Each {@link WorkflowStep} becomes a one-task phase, in order
  * ({@link import('./helpers.js').expandSteps}); `name` is the optional workflow name and
- * deterministic persistence id (both default to `wf` when omitted).
+ * deterministic persistence id (each defaults to `wf` when omitted).
  */
 export declare interface WorkflowSteps {
     readonly name?: string;
@@ -2435,23 +2559,24 @@ export declare interface WorkflowSteps {
 }
 
 /**
- * Describes the FLAT authoring shape {@link import('./factories.js').createWorkflowTool} advertises as its
- * `parameters` — the simplest surface a small model can fill: `{ name?, steps: [{ name }] }`.
+ * Describes the flat authoring shape {@link import('./factories.js').createWorkflowTool} advertises
+ * as its `parameters` — the simplest surface a small model can fill:
+ * `{ name?, steps: [{ name }] }`.
  *
  * @remarks
  * A deliberately-reduced surface: a flat ordered list of steps, each a `{ name }`. The tool
- * EXPANDS it ({@link import('./helpers.js').expandSteps}) into a full
+ * expands it ({@link import('./helpers.js').expandSteps}) into a full
  * {@link import('./types.js').WorkflowDefinition} — one one-task phase per step, in order —
- * then validates against the STRICT `createWorkflowContract` (`@orkestrel/workflow`) gate. The
- * full nested form is STILL accepted by the tool (it branches on the args' shape) and is
- * documented as the advanced escape-hatch in the tool's description — but THIS is what
+ * then validates against the strict `createWorkflowContract` (`@orkestrel/workflow`) gate. The
+ * full nested form is still accepted by the tool (it branches on the args' shape) and is
+ * documented as the advanced escape-hatch in the tool's description — but this is what
  * `parameters` advertises.
  */
-export declare const workflowStepsShape: ObjectShape<{
-    name: OptionalShape<StringShape>;
-    steps: ArrayShape<ObjectShape<{
-        name: StringShape;
-    }, false>>;
+export declare const workflowStepsShape: ObjectShape<    {
+name: OptionalShape<StringShape>;
+steps: ArrayShape<ObjectShape<    {
+name: StringShape;
+}, false>>;
 }, false>;
 
 /**
@@ -2496,8 +2621,8 @@ export declare interface WorkflowToolResult {
 export declare const WORKSPACE_TOOL_DESCRIPTION: string;
 
 /**
- * Holds a valid {@link import('./types.js').WorkspaceOperation} object — the canonical example embedded
- * VERBATIM in {@link WORKSPACE_TOOL_DESCRIPTION}.
+ * Holds a valid {@link import('./types.js').WorkspaceOperation} object — the canonical example
+ * embedded verbatim in {@link WORKSPACE_TOOL_DESCRIPTION}.
  *
  * @remarks
  * A `'write'` op (the most common authoring
@@ -2507,56 +2632,61 @@ export declare const WORKSPACE_TOOL_DESCRIPTION: string;
 export declare const WORKSPACE_TOOL_EXAMPLE: WorkspaceOperation;
 
 /**
- * Holds the name {@link import('./factories.js').createWorkspaceTool} advertises by default — the key a
- * model calls and the `ToolManagerInterface` (`@orkestrel/tool`) registers under.
+ * Holds the name {@link import('./factories.js').createWorkspaceTool} advertises by default,
+ * `'workspace'` — the key a model calls and the `ToolManagerInterface` (`@orkestrel/tool`)
+ * registers under.
  */
 export declare const WORKSPACE_TOOL_NAME = "workspace";
 
 /**
- * Holds the lean {@link import('@orkestrel/tool').ToolInterface.summary} {@link import('./factories.js').createWorkspaceTool}
- * advertises in place of {@link WORKSPACE_TOOL_DESCRIPTION} — a `ToolManagerInterface.definitions()`
- * (`@orkestrel/tool`) advertises `summary ?? description`, so this one-sentence text stands in
- * for the full teaching description; the full text stays retrievable through
- * {@link import('./factories.js').createDescribeTool}.
+ * Holds the lean {@link import('@orkestrel/tool').ToolInterface.summary}
+ * {@link import('./factories.js').createWorkspaceTool} advertises in place of
+ * {@link WORKSPACE_TOOL_DESCRIPTION} — one sentence offering the `operation`-keyed file editing and
+ * pointing at `describe` for the operation list and its fields.
+ *
+ * @remarks
+ * A `ToolManagerInterface.definitions()` call (`@orkestrel/tool`) advertises
+ * `summary ?? description`, so this one-sentence text stands in for the full teaching description;
+ * the full text stays retrievable through {@link import('./factories.js').createDescribeTool}.
  */
 export declare const WORKSPACE_TOOL_SUMMARY = "Read and edit files in a workspace \u2014 one operation per call (read, write, list, search, replace, splice, move, remove, plus workspace switching), chosen by the 'operation' field. Call describe('workspace') for the full operation list and fields.";
 
 /**
- * Represents one operation an agent invokes through {@link import('./factories.js').createWorkspaceTool} — a
- * FLAT, descriptive tagged union over the workspace edit, read, and navigation actions,
- * discriminated by the `operation` literal (a discriminant is named for its axis — the action
- * being performed — NEVER `kind`).
+ * Represents one operation an agent invokes through
+ * {@link import('./factories.js').createWorkspaceTool} — a flat, descriptive tagged union over the
+ * workspace edit, read, and navigation actions, discriminated by the `operation` literal (a
+ * discriminant is named for its axis — the action being performed — never `kind`).
  *
  * @remarks
- * This is the SOURCE OF TRUTH the tool contract is typed to
+ * This is the source of truth the tool contract is typed to
  * ({@link import('./shapers.js').workspaceToolShape} compiles to a structurally-identical guard /
- * parser / JSON Schema). Every field is FLAT (no nested objects) — the small-model ergonomic
- * lever: a range edit is the four flat integers of the `'splice'` arm (`fromLine` /
+ * parser / JSON Schema). Every field is flat (no nested objects) — the small-model ergonomic
+ * lever: a range edit is the flat integers of the `'splice'` arm (`fromLine` /
  * `fromColumn` / `toLine` / `toColumn`), reassembled into a 1-based `Range`
  * (`@orkestrel/workspace`)
- * by `rangeOf`, never a nested `{ start, end }`. Each EDIT / READ arm maps onto exactly one
- * `WorkspaceInterface` call against the manager's ACTIVE workspace; the two REGISTRY arms
+ * by `rangeOf`, never a nested `{ start, end }`. Each edit / read arm maps onto exactly one
+ * `WorkspaceInterface` call against the manager's active workspace; the registry arms
  * (`switch` / `workspaces`) drive the {@link WorkspaceManagerInterface} pointer instead —
- * `workspaces` LISTS the workspaces the model can move between, and `switch` re-points which one
+ * `workspaces` lists the workspaces the model can move between, and `switch` re-points which one
  * the edit / read arms target.
  */
 export declare type WorkspaceOperation = 
-/** Reads a whole text file's text by `path` from the ACTIVE workspace (a binary / absent path — or no active workspace — yields no content). */
+/** Reads a whole text file's text by `path` from the active workspace (a binary / absent path — or no active workspace — yields no content). */
     {
     readonly operation: 'read';
     readonly path: string;
 }
-/** Lists every file in the ACTIVE workspace (path / state / size / lines / kind summaries); `[]` when no workspace is active. */
+/** Lists every file in the active workspace (path / state / size / lines / kind summaries); `[]` when no workspace is active. */
 | {
     readonly operation: 'list';
 }
-/** Reports whether a file exists at `path` in the ACTIVE workspace (`false` when no workspace is active). */
+/** Reports whether a file exists at `path` in the active workspace (`false` when no workspace is active). */
 | {
     readonly operation: 'has';
     readonly path: string;
 }
 /**
-* Scans every text file for `query`, returning each hit (path + 1-based line / column + the line).
+* Scans every text file for `query`, returning each hit (the path, the 1-based line and column, and the line).
 *
 * @remarks
 * `regex` treats `query` as a regular-expression source (default `false` — a literal substring);
@@ -2592,10 +2722,10 @@ export declare type WorkspaceOperation =
 }
 /**
 * Splices `content` into an existing text file, replacing the 1-based range
-* `(fromLine, fromColumn)` (INCLUSIVE) → `(toLine, toColumn)` (EXCLUSIVE).
+* `(fromLine, fromColumn)` (inclusive) → `(toLine, toColumn)` (exclusive).
 *
 * @remarks
-* The FLAT range edit — the four positive-integer caret components reassemble into a `Range`
+* The flat range edit — the four positive-integer caret components reassemble into a `Range`
 * (`@orkestrel/workspace`) through `rangeOf`. An empty span (`from === to`) inserts; a span past
 * the end is clamped. An inverted / sub-1 range throws `RANGE`; a binary target throws
 * `MODALITY`; a missing target throws `MISSING`.
@@ -2636,25 +2766,25 @@ export declare type WorkspaceOperation =
 | {
     readonly operation: 'workspaces';
 }
-/** Re-points the manager's ACTIVE workspace to the one with `id` (an unknown `id` is a lenient no-op). The edit / read arms target the active workspace from then on. */
+/** Re-points the manager's active workspace to the one with `id` (an unknown `id` is a lenient no-op). The edit / read arms target the active workspace from then on. */
 | {
     readonly operation: 'switch';
     readonly id: string;
 };
 
 /**
- * Represents the options for {@link import('./factories.js').createWorkspaceTool} — EITHER a caller-built
- * {@link WorkspaceManagerInterface} to drive directly, OR a {@link WorkspaceStoreInterface} the
- * tool constructs a fresh manager over; neither given constructs a manager over
- * `@orkestrel/workspace`'s in-memory store.
+ * Represents the options for {@link import('./factories.js').createWorkspaceTool} — either a
+ * caller-built {@link WorkspaceManagerInterface} to drive directly, or a
+ * {@link WorkspaceStoreInterface} the tool constructs a fresh manager over; neither given
+ * constructs a manager over `@orkestrel/workspace`'s in-memory store.
  *
  * @remarks
- * - `manager` — drive THIS manager directly (its `active` workspace is what every edit / read
- *   operation targets). Takes priority over `store` when both are supplied.
+ * - `manager` — drive this manager directly (its `active` workspace is what every edit / read
+ *   operation targets). Takes priority over `store` when the caller supplies `manager` and `store`.
  * - `store` — construct a manager over this durable {@link WorkspaceStoreInterface} (through
  *   `@orkestrel/workspace`'s `createWorkspaceManager`) — used only when `manager` is omitted.
  *   The store only backs the manager's own `open` / `save` operations: the tool's edits are
- *   NOT auto-persisted — durability requires an explicit caller `save` on the manager
+ *   not auto-persisted — durability requires an explicit caller `save` on the manager
  *   (unlike the workflow tool's `store`, which is forwarded into native run-wide checkpoints).
  * - `name` / `description` — advertised tool overrides; default to
  *   {@link import('./constants.js').WORKSPACE_TOOL_NAME} / {@link import('./constants.js').WORKSPACE_TOOL_DESCRIPTION}.
@@ -2670,71 +2800,71 @@ export declare interface WorkspaceToolOptions {
  * Describes the shape of a {@link import('./types.js').WorkspaceOperation} — a descriptive tagged union
  * over the workspace edit, read, and navigation operations, discriminated by the `operation`
  * literal (never a bare `kind`). Each variant leads with its `operation`
- * discriminant then its FLAT fields, every field through `stringShape` / `optionalShape` /
+ * discriminant then its flat fields, every field through `stringShape` / `optionalShape` /
  * `integerShape({ min: 1 })` / `booleanShape`, each carrying a strong field-level `description`.
  *
  * @remarks
- * The union compiles to an `anyOf` JSON Schema + a `unionOf` guard + a first-match parser
+ * The union compiles to an `anyOf` JSON Schema, a `unionOf` guard, and a first-match parser
  * automatically ({@link import('./factories.js').createWorkspaceTool} types the result to the
- * hand-written {@link import('./types.js').WorkspaceOperation}). `limit` and the four `'splice'`
- * caret components are POSITIVE integers (`integerShape({ min: 1 })`); `regex` / `sensitive`
- * are `optionalShape(booleanShape(...))`. The two REGISTRY arms — `workspaces` (list the
+ * hand-written {@link import('./types.js').WorkspaceOperation}). `limit` and the `'splice'`
+ * caret components are positive integers (`integerShape({ min: 1 })`); `regex` / `sensitive`
+ * are `optionalShape(booleanShape(...))`. The registry arms — `workspaces` (list the
  * workspaces the model can move between) and `switch` (re-point the active one by `id`) — let a
- * model DISCOVER then CHOOSE which workspace the edit / read arms target.
- */
-export declare const workspaceToolShape: UnionShape<readonly [ ObjectShape<{
-    operation: LiteralShape<readonly ["read"]>;
-    path: StringShape;
-}, false>, ObjectShape<{
-    operation: LiteralShape<readonly ["list"]>;
-}, false>, ObjectShape<{
-    operation: LiteralShape<readonly ["has"]>;
-    path: StringShape;
-}, false>, ObjectShape<{
-    operation: LiteralShape<readonly ["search"]>;
-    query: StringShape;
-    regex: OptionalShape<BooleanShape>;
-    sensitive: OptionalShape<BooleanShape>;
-    limit: OptionalShape<NumberShape>;
-}, false>, ObjectShape<{
-    operation: LiteralShape<readonly ["replace"]>;
-    query: StringShape;
-    replacement: StringShape;
-    regex: OptionalShape<BooleanShape>;
-    sensitive: OptionalShape<BooleanShape>;
-    limit: OptionalShape<NumberShape>;
-}, false>, ObjectShape<{
-    operation: LiteralShape<readonly ["write"]>;
-    path: StringShape;
-    content: StringShape;
-}, false>, ObjectShape<{
-    operation: LiteralShape<readonly ["splice"]>;
-    path: StringShape;
-    content: StringShape;
-    fromLine: NumberShape;
-    fromColumn: NumberShape;
-    toLine: NumberShape;
-    toColumn: NumberShape;
-}, false>, ObjectShape<{
-    operation: LiteralShape<readonly ["prepend"]>;
-    path: StringShape;
-    content: StringShape;
-}, false>, ObjectShape<{
-    operation: LiteralShape<readonly ["append"]>;
-    path: StringShape;
-    content: StringShape;
-}, false>, ObjectShape<{
-    operation: LiteralShape<readonly ["move"]>;
-    from: StringShape;
-    to: StringShape;
-}, false>, ObjectShape<{
-    operation: LiteralShape<readonly ["remove"]>;
-    path: StringShape;
-}, false>, ObjectShape<{
-    operation: LiteralShape<readonly ["workspaces"]>;
-}, false>, ObjectShape<{
-    operation: LiteralShape<readonly ["switch"]>;
-    id: StringShape;
+ * model discover then choose which workspace the edit / read arms target.
+ */
+export declare const workspaceToolShape: UnionShape<readonly [ObjectShape<    {
+operation: LiteralShape<readonly ["read"]>;
+path: StringShape;
+}, false>, ObjectShape<    {
+operation: LiteralShape<readonly ["list"]>;
+}, false>, ObjectShape<    {
+operation: LiteralShape<readonly ["has"]>;
+path: StringShape;
+}, false>, ObjectShape<    {
+operation: LiteralShape<readonly ["search"]>;
+query: StringShape;
+regex: OptionalShape<BooleanShape>;
+sensitive: OptionalShape<BooleanShape>;
+limit: OptionalShape<NumberShape>;
+}, false>, ObjectShape<    {
+operation: LiteralShape<readonly ["replace"]>;
+query: StringShape;
+replacement: StringShape;
+regex: OptionalShape<BooleanShape>;
+sensitive: OptionalShape<BooleanShape>;
+limit: OptionalShape<NumberShape>;
+}, false>, ObjectShape<    {
+operation: LiteralShape<readonly ["write"]>;
+path: StringShape;
+content: StringShape;
+}, false>, ObjectShape<    {
+operation: LiteralShape<readonly ["splice"]>;
+path: StringShape;
+content: StringShape;
+fromLine: NumberShape;
+fromColumn: NumberShape;
+toLine: NumberShape;
+toColumn: NumberShape;
+}, false>, ObjectShape<    {
+operation: LiteralShape<readonly ["prepend"]>;
+path: StringShape;
+content: StringShape;
+}, false>, ObjectShape<    {
+operation: LiteralShape<readonly ["append"]>;
+path: StringShape;
+content: StringShape;
+}, false>, ObjectShape<    {
+operation: LiteralShape<readonly ["move"]>;
+from: StringShape;
+to: StringShape;
+}, false>, ObjectShape<    {
+operation: LiteralShape<readonly ["remove"]>;
+path: StringShape;
+}, false>, ObjectShape<    {
+operation: LiteralShape<readonly ["workspaces"]>;
+}, false>, ObjectShape<    {
+operation: LiteralShape<readonly ["switch"]>;
+id: StringShape;
 }, false>]>;
 
 export { }