@vimhead.dev/norn-cli 0.1.0-tip.35242809332.1 → 0.1.0-tip.35347037721.1

package/assets/README.md

@@ -63,7 +63,7 @@ Inside the interactive session:
 
 Model-free workflows need no provider authentication. For other credential
 methods, custom providers, and Norn's configuration directory, see
-[providers and authentication](setup/providers.md).
+[providers and authentication](docs/providers.md).
 
 ### 3. Optionally connect your harness
 
@@ -104,11 +104,6 @@ NORN_EXECUTABLE=/absolute/path/to/norn cursor .
 Need an adapter for another harness? [Open an issue](https://github.com/vimhead/norn/issues/new)
 with the harness name.
 
-## Setting up a Norn project
-
-[Projects and loading](docs/projects.md) covers initialization, registration,
-reusable configuration, dependencies, source reload, and discovery diagnostics.
-
 ## Build workflows with the Norn SDK
 
 Install SDK types and helpers for TypeScript/editor support:
@@ -121,22 +116,6 @@ Use the SDK version reported by `norn version` for an exact runtime match. Runti
 execution also supplies [virtual SDK imports](docs/projects.md#import-and-reload),
 so standalone examples need no local SDK installation.
 
-[Workflow authoring](docs/workflows.md) covers declarations, implementations,
-commands, and run outcomes. Focused companion references:
-
-- [Norn agents](docs/agents.md)
-- [State, artifacts, and workspaces](docs/persistence.md)
-- [Composition and reuse](docs/composition.md)
-- [Recovery and gates](docs/recovery.md)
-
-The larger [worktree development loop](examples/worktree-development-loop/README.md)
-is an optional composition example, not a required workflow architecture.
-
-## Run workflows with Norn
-
-[CLI and client](docs/cli.md) covers live contract discovery, JSON invocation,
-launch/wait semantics, results, and use from other harnesses.
-
 ## Development
 
 ```bash
@@ -153,5 +132,4 @@ published dependency. No separate core build is needed.
 
 Checks cover package builds, TypeScript (including examples, adapters, scripts,
 and tests), runtime regressions, isolated npm installations, and standalone binaries.
-`pack:dry` creates local tarballs without publishing. See
-[release setup](setup/releases.md) for bootstrap and trusted publishing.
+`pack:dry` creates local tarballs without publishing.

package/assets/docs/README.md

@@ -7,12 +7,14 @@ Norn capabilities are ordinary TypeScript plugins: an agent can write one during
 | Task | Documentation | Runnable example |
 |---|---|---|
 | Build, register, or diagnose workflows with the Norn SDK | [Projects and loading](projects.md), [Workflow authoring](workflows.md) | [Create → run → change](../examples/minimal-workflow/README.md) |
+| Define TypeBox schemas, constraints, or codecs | [TypeBox schemas](schemas.md) | — |
 | Discover contracts or invoke Norn from another harness | [CLI and client](cli.md) | [Create → run → change](../examples/minimal-workflow/README.md) |
+| Configure providers, models, and authentication for Norn agents | [Providers and authentication](providers.md) | — |
 | Delegate work with explicit inputs and structured results | [Norn agents](agents.md) | [Norn agent → saved artifact → analysis](../examples/agent-then-analysis/README.md) |
 | Initialize shared resources, attach state tools, or coordinate file mutations | [Resources and locking](resources.md) | [Explicit shared state](../examples/shared-state/README.md) |
 | Implement a custom resource and adapter to coordinate concurrent agents | [Resource contracts](resources.md) | [Example-local work queue](../examples/coordinating-multiple-agents/README.md) |
 | Retain evidence or choose a filesystem boundary | [State, artifacts, and workspaces](persistence.md) | [Norn agent → saved artifact → analysis](../examples/agent-then-analysis/README.md) |
-| Reuse a workflow with a caller-selected continuation | [Composition](composition.md) | [Worktree development loop](../examples/worktree-development-loop/README.md) — larger, optional |
+| Reuse a workflow with a caller-selected continuation | [Composition](composition.md) | [Caller-selected continuation](../examples/caller-selected-continuation/README.md) |
 | Repair a failed run without repeating earlier work | [Recovery and gates](recovery.md) | [Analysis-only repair](../examples/agent-then-analysis/README.md#repair-only-the-analysis-step) |
 
 [Public types](../packages/sdk/src/api.ts) define the Norn SDK's authoring interface. CLI discovery exposes the currently loaded project, not a documentation-time workflow catalogue. See [installation](../README.md#installation) for runtime setup.

package/assets/docs/agents.md

@@ -6,7 +6,7 @@ The [Norn agent → saved artifact → analysis example](../examples/agent-then-
 
 ## One prompt or a retained session
 
-`run.agents.prompt({ label, prompt, response, ...sessionOptions })` creates a Pi session, prompts it, validates its response, and disposes it in `finally`. It returns the parsed response itself, not `{ response, raw }`.
+`run.agents.prompt({ label, prompt, response, ...sessionOptions })` creates a Pi session for one prompt and returns the value described by the response schema, including any codec transformations—not `{ response, raw }`. You do not need to dispose this one-prompt session. See [schema input/output types](schemas.md#codecs-and-inputoutput-types).
 
 For follow-up turns in the same conversation:
 
@@ -34,7 +34,7 @@ try {
 }
 ```
 
-`task` and both Zod schemas are capability-specific inputs in this fragment. [Provider setup](../setup/providers.md) is a prerequisite for Norn agents; detached execution cannot conduct an interactive login.
+`task` and both TypeBox schemas are capability-specific inputs in this fragment. [Provider setup](providers.md) is a prerequisite for Norn agents; detached execution cannot conduct an interactive login.
 
 ## Response contract and evidence
 
@@ -52,7 +52,7 @@ Successful results and raw attempts are written under `current/logs/agents/`; Pi
 
 The default tool allowlist is `read`, `bash`, `edit`, `write`, plus the response tool. An explicit `tools: []` requests no built-in task tools, but still includes the response tool and any explicitly attached [resource-adapter tools](resources.md#explicit-agent-attachment). `resourceAdapters` is accepted by both session creation and one-shot prompting; omitting it attaches no workflow state.
 
-Each session constructs Pi runtime services at its `cwd`, using the engine's explicit `agentDir`, then `NORN_AGENT_DIR`, then `~/.norn/agent`. An inherited `PI_CODING_AGENT_DIR` does not select the Norn agent's global configuration. Installed provider extensions register before default-model selection. Model selection uses the session's explicit `model`, then the engine's model, then Pi's model configuration. `thinkingLevel` similarly falls through from session to engine to Pi configuration. Discoverable settings, skills, context files, and extensions can therefore affect it. It does **not** inherit the outer conversation or its in-memory tool registrations. Loaded extensions may change active tools; the requested tool list alone is not an adversarial restriction.
+Each session loads resources for its `cwd` and [Norn configuration](providers.md#norn-configuration). Installed provider extensions register before default-model selection. Both `run.agents.createSession` and `run.agents.prompt` accept per-session `model` and `thinkingLevel` overrides; omitted values use Pi's configured selection and defaults. Discoverable settings, skills, context files, and extensions can therefore affect it. It does **not** inherit the outer conversation or its in-memory tool registrations. Loaded extensions may change active tools; the requested tool list alone is not an adversarial restriction.
 
 `systemPrompt` replaces the base prompt; `appendSystemPrompt` adds to resource-loader append content. Pi's default self-documentation block is absent with a custom base prompt. Context files and applicable skill advertisements can still be appended by Pi. Norn currently does not automatically inject a Norn authoring bootstrap.
 

package/assets/docs/cli.md

@@ -45,7 +45,7 @@ npm/source installations resolve their built `assets/` tree directly from the CL
 package, not the current directory or another executable on PATH. A version mismatch
 fails rather than advertising another build's documentation. Compiled binaries embed the docs,
 examples, and source references, preserving relative links. The first
-inspection publishes a complete extracted tree into a build/content-specific
+inspection makes a complete copy available in a build/content-specific
 cache; later calls verify and reuse it without rewriting files. Different asset
 contents or build commits use separate entries. `version` and help do not extract
 anything. No prompt augmentation or agent-context delivery is performed.
@@ -57,9 +57,9 @@ Cache roots:
 - Windows: `%LOCALAPPDATA%/norn/docs/`, or `~/AppData/Local/norn/docs/`
 - Explicit override: `NORN_DOCS_CACHE_DIR`
 
-Extraction uses staging directories and atomic publication. Existing cache entries
-are checked for exact file bytes, missing/extra files, and symlinks. Corrupt entries
-are not silently overwritten; the error names the entry to remove before retrying.
+Existing cache entries must match the bundled files exactly, with no missing or
+extra files or symlinks. Corrupt entries are not silently overwritten; the error
+names the entry to remove before retrying.
 This is accidental-corruption detection, not a sandbox against another process
 with access to the same user's cache. Old build entries are not automatically
 removed. The extracted tree is a documentation snapshot, not a separate runtime
@@ -82,7 +82,7 @@ norn docs intro
 Returns `{ "intro": "..." }`: a compact authoring introduction with runtime
 version/commit, invocation, and pointers to the documentation index and examples.
 Topic routing remains in the index; the command does not copy manuals or enumerate
-workflows. It uses the same asset resolver/cache as `docs inspect`
+workflows. It returns locations for the same installed documentation as `docs inspect`
 and works without a valid project.
 
 The invocation is a JSON argument array, not a shell command string. Its first
@@ -113,7 +113,7 @@ Default workflow listing shows entrypoints; `--all` includes internal steps. Wor
 Help is text; ordinary results are JSON. `runs logs` emits JSONL events.
 `norn pi [arguments...]` is a passthrough to bundled Pi, preserving Pi's native
 output and exit status rather than wrapping them in Norn JSON. Use `norn pi --help`
-for Pi's options and [provider setup](../setup/providers.md) for operator instructions.
+for Pi's options and [provider setup](providers.md) for operator instructions.
 Commands and schemas from the invoked executable are authoritative when a checkout and installation differ.
 
 ## Start, wait, inspect
@@ -178,6 +178,6 @@ console.log(finished.outcome?.metadata);
 
 The client defaults to its own package's `bin/norn.mjs`. Its optional `executablePath` is a script launched through `process.execPath`, not an arbitrary standalone binary or shell command. Other languages can invoke the CLI directly with cwd, JSON stdin, and parsed stdout.
 
-`workflows.list()` and `inspect()` use fresh CLI discovery. `workflows.entries()` and `client.state` use a cached in-process project load; that state is registration memory, not a chosen run's persisted state. A new client is needed to refresh that in-process catalogue after source edits.
+`workflows.list()` and `inspect()` use fresh CLI discovery. `workflows.entries()` and `client.state` use a cached in-process project load; [persistence](persistence.md#choose-what-survives) defines the `client.state` lifetime. A new client is needed to refresh that in-process catalogue after source edits.
 
 Sources: [CLI declarations and handlers](../packages/cli/src/cli.ts), [client API](../packages/cli/src/client.ts).

package/assets/docs/composition.md

@@ -3,45 +3,42 @@
 ## Transfer, not a returning call
 
 ```ts
-return run.next(manifest.workflows.analyze, { draftArtifact });
+return manifest.workflows.analyze({ draftArtifact });
 ```
 
-`run.next` constructs a control result. Returning it lets the scheduler persist the transition and execute the target in the **same run**, with that target's isolation mode. It does not suspend the caller and later return a value. Awaiting `run.next` cannot turn it into a subroutine.
+Return a workflow call to select the next step in the same run. Supply its complete input; TypeScript checks it against the declaration's params schema. The target must be registered in the loaded project.
 
-The caller and target share run state and artifacts, not local variables or agent conversations. All targets must be registered in the loaded project. Params are validated at the target; a returned `complete` completes the entire run.
+This transfers control rather than calling a subroutine: awaiting the declaration does not execute the target or return its eventual result. Steps share run state and artifacts, not local variables or agent conversations. `run.complete` completes the whole run.
 
-## Caller-selected continuation
+For a dynamically selected string ID, use `return run.next(workflowId, params)`. The selected target checks its input at runtime. `run.next` accepts IDs, not declarations or reference functions.
 
-A reusable capability can accept a continuation whose schema describes the values it contributes. The caller owns the remaining params:
+## Caller-selected workflow reference
+
+The [caller-selected continuation example](../examples/caller-selected-continuation/README.md)
+runs a producer with either of two caller-selected consumers, forwarding caller
+context alongside the producer's results. It needs no model or credentials.
+
+A reusable capability can accept a workflow reference whose schema describes the values it contributes. The caller supplies the target and captures the remaining params:
 
 ```ts
 import { artifactRefSchema, workflowRefSchema } from "@vimhead.dev/norn";
-import { z } from "zod";
-
-const paramsSchema = z.object({
-  task: z.string(),
-  next: workflowRefSchema({
-    params: z.object({
-      resultArtifact: artifactRefSchema,
-      summary: z.string(),
+import { Type } from "typebox";
+
+const paramsSchema = Type.Object({
+  task: Type.String(),
+  next: Type.Union([
+    workflowRefSchema({
+      params: Type.Object({
+        resultArtifact: artifactRefSchema,
+        summary: Type.String(),
+      }),
     }),
-  }).nullable(),
+    Type.Null(),
+  ]),
 });
 ```
 
-After producing `resultArtifact` and `summary`, the reusable implementation returns:
-
-```ts
-return params.next
-  ? run.next(params.next.workflow, {
-      ...params.next.forwardParams,
-      resultArtifact,
-      summary,
-    })
-  : run.complete({ summary, artifacts: { result: resultArtifact } });
-```
-
-A caller supplies a registered target and its own context:
+A caller supplies the target and its own parameters:
 
 ```json
 {
@@ -55,22 +52,55 @@ A caller supplies a registered target and its own context:
 }
 ```
 
-`importer.deliver` must accept `batchId`, `resultArtifact`, and `summary`. Code can supply a workflow declaration instead of the ID string. A bare ID or `{ id }` reference normalizes to empty `forwardParams`.
+Code uses a declaration's `.id` in the reference payload, not the declaration itself. A bare ID string is shorthand for an object reference with empty `forwardParams`.
+
+Inside the workflow, `params.next` is a function. Supply only the result fields declared above:
+
+```ts
+return params.next
+  ? params.next({ resultArtifact, summary })
+  : run.complete({ summary, artifacts: { result: resultArtifact } });
+```
+
+`importer.deliver` receives `batchId` from the caller plus `resultArtifact` and `summary` from the producer. Its params schema must accept all three. Produced fields replace caller fields with the same name; nested objects are replaced, not deep-merged.
+
+Contributions must be JSON objects matching the declared input type. Object-valued records, unions, intersections and codecs are supported. With codecs, supply `StaticEncode` values, just as for a direct workflow call—not transformed `StaticDecode` values.
+
+`workflows inspect` shows the contribution contract under `x-norn-workflow-ref.contributedParamsSchema`. Use it alongside the target's params schema to check that the combined input fits.
+
+When passing a reference as input to another workflow, supply its JSON form shown above, not the function received in `params.next`.
+
+## Multiple outcomes and direct targets
+
+References can be nested under ordinary author-selected names with independent contribution schemas:
+
+```ts
+const next = Type.Object({
+  success: workflowRefSchema({
+    params: Type.Object({ resultArtifact: artifactRefSchema }),
+  }),
+  failure: workflowRefSchema({
+    params: Type.Object({ reason: Type.String() }),
+  }),
+});
+```
+
+An implementation can return `params.next.success({ resultArtifact })`, `params.next.failure({ reason })`, or select its own known target with `manualReviewWorkflow({ task, reason })`. A dynamic target still uses `run.next(selectedId, input)`.
 
-`workflows inspect` exposes `x-norn-workflow-ref.contributedParamsSchema` at the reference's JSON Schema node. This is the producer's contribution contract, not extra fields required in the caller's reference payload. It does not automatically merge params, verify the target exists, or prove the target accepts the combination.
+These are alternative transitions, not fan-out. `success` and `failure` are not reserved names, and a failure reference does not catch unhandled exceptions automatically.
 
 | Decision | GOOD | BAD |
 |---|---|---|
-| IF a caller selects the next step, THEN forward its opaque params and add the declared contribution explicitly. ELSE transition to a known declaration with explicit params. | Spread `forwardParams`, then add the producer-owned result fields. | Hardcode a task-specific next workflow into a supposedly reusable producer. |
-| IF resuming the caller requires additional work, THEN represent that work as the supplied continuation. ELSE let the producer complete. | `assess → caller.deliver`. | Expect execution to return to the line following `run.next`. |
-| IF a target schema changes, THEN inspect and exercise the combined params contract. ELSE preserve its existing input contract. | Verify the target accepts both batch context and result ref. | Treat the contributed schema annotation as automatic end-to-end compatibility checking. |
+| IF the caller selects the next step, THEN invoke its reference with the declared contribution. ELSE call a known declaration or use a dynamic ID. | `params.next({ resultArtifact })` | Manually reconstruct captured forwarding input. |
+| IF additional caller work follows the result, THEN represent it as the supplied reference. ELSE complete the run. | `assess → caller.deliver` | Expect execution to return to the line following a workflow call. |
+| IF a target schema changes, THEN exercise the assembled input contract. ELSE preserve its existing input contract. | Verify the target accepts captured context and contributed results. | Treat contribution metadata as end-to-end compatibility proof. |
 
-The [worktree development loop](../examples/worktree-development-loop/README.md) is a larger continuation-based example, not a required planner/reviewer architecture.
+The [worktree development loop](../examples/worktree-development-loop/README.md) is a larger multi-step example using known workflow declarations, not a required planner/reviewer architecture.
 
 ## Another project or harness
 
 Reuse source by explicitly registering it, directly or through [included config](projects.md). There is no required package layout. Plugin IDs must remain unique within a project; run state and artifacts belong to the invoking project/run, not the plugin source directory.
 
-An external shell, Python program, or agent harness can call the [CLI](cli.md) from the target project directory. The JavaScript client offers the same lifecycle without inventing another orchestration layer. Separate CLI starts create separate runs; connecting their artifact content is a caller responsibility, unlike same-run continuation refs.
+An external shell, Python program, or agent harness can call the [CLI](cli.md) from the target project directory. The JavaScript client offers the same lifecycle without inventing another orchestration layer. Separate CLI starts create separate runs; connecting their artifact content is a caller responsibility, unlike same-run references.
 
 Sources: [reference schemas and controls](../packages/sdk/src/api.ts), [scheduler](../packages/cli/src/internal/engine.ts), [reference contract tests](../tests/workflow-ref.test.ts).

package/assets/docs/persistence.md

@@ -4,13 +4,15 @@
 
 | Value | Lifetime and access |
 |---|---|
-| Local variables / plugin factory memory | Current executor only; not a resume contract. Factory context state is in-memory registration state. |
+| Local variables / plugin factory memory | Current invocation or executor only; not a resume contract. |
+| Factory context `state` / `client.state` | In-memory registration state for the loaded project, not a selected run's persisted state. |
 | `run.state` | Per-run, schema-validated JSON shared across steps. `get` requires a value; `getOptional` permits absence; `set` persists it. |
+| `run.resources` data | Per-run data included in checkpoint recovery. Resume reopens handles; closures do not survive. |
 | `run.artifacts` | Text files addressed by `{ path }` relative to this run's artifacts directory. Write content, pass the ref, read and validate at the consumer. |
 | Outcome metadata | Caller-facing summary, artifact/log refs and small data, exposed by run inspection. |
 | Workflow params | Explicit input to the current/next step, persisted for recovery. |
 
-Workflow state is the automatically initialized built-in [run resource](resources.md). State declarations live in the manifest. The [agent example](../examples/agent-then-analysis/plugin.ts) saves the draft ref in run state and also passes it explicitly to analysis. The state value is a retained run record; the params are the consumer's input contract.
+Workflow state is a built-in [run resource](resources.md), available without an explicit `ensure` call. State declarations live in the manifest; declaring a field, including a schema default, does not set its value. The [agent example](../examples/agent-then-analysis/plugin.ts) saves the draft ref in run state and also passes it explicitly to analysis. The state value is a retained run record; the params are the consumer's input contract.
 
 Artifact refs are paths, not content hashes, and a write to the same path replaces its content. State writes are serialized and atomic; an artifact write plus a state update is not a single transaction. An artifact read returns text, so a JSON consumer still needs parsing and schema validation.
 

package/assets/docs/projects.md

@@ -32,24 +32,15 @@ Reusable config files, conventionally `norn.json`, can declare `plugins`, `inclu
 }
 ```
 
-Plugin and include paths resolve relative to the file declaring them. `*` matches one directory segment. There is no automatic plugin tree scan, nor automatic inclusion of a sibling `norn.json`. Project config overrides included values; conflicting reusable values and duplicate plugin IDs are rejected. `version` and `seerMode` belong only in the project file.
-
-Projects using Seer can additionally declare writable project-relative roots:
-
-```json
-"seerMode": { "writableRoots": ["./workflow-sources"] }
-```
-
-This is a project-file field, not an OS sandbox. The current helper contract is in
-[Seer exports](../packages/sdk/src/seer/index.ts) and [config resolution](../packages/sdk/src/seer/config.ts).
+Plugin and include paths resolve relative to the file declaring them. `*` matches one directory segment. There is no automatic plugin tree scan, nor automatic inclusion of a sibling `norn.json`. Project config overrides included values; conflicting reusable values and duplicate plugin IDs are rejected. `version` belongs only in the project file.
 
 ## Import and reload
 
-Each registered module default-exports `definePlugin(manifest, implementation)`. Norn loads TypeScript through jiti without a local build, supplying runtime imports for `@vimhead.dev/norn`, its `/files`, `/schema`, and `/seer` subpaths, `zod`, and `typebox`. Other dependencies need normal package resolution from the plugin's location.
+Each registered module default-exports `definePlugin(manifest, implementation)`. Norn loads TypeScript through jiti without a local build, supplying runtime imports for `@vimhead.dev/norn`, its `/files` and `/schema` subpaths, `typebox`, `typebox/value`, `typebox/compile`, and `typebox/schema`. Other dependencies need normal package resolution from the plugin's location.
 
 Runtime virtual imports do not configure TypeScript or an editor. A matching `@vimhead.dev/norn` installation provides the SDK types; the source checkout's examples are checked by its `tsconfig.json`. A successful runtime import alone is not a type check.
 
-New CLI discovery/start/resume invocations load current source; an already executing workflow retains its loaded implementation. Module evaluation and implementation factories run even during discovery. Factory context state is in-memory registration state, **not** durable run state; see [persistence](persistence.md).
+New CLI discovery/start/resume invocations load current source; an already executing workflow retains its loaded implementation. Module evaluation and implementation factories run even during discovery. [Persistence](persistence.md#choose-what-survives) defines the lifetime of factory context state.
 
 | Decision | GOOD | BAD |
 |---|---|---|

package/assets/{setup → docs}/providers.md

@@ -27,8 +27,9 @@ It is independent of the outer Pi harness's global configuration:
 - `models.json` — custom endpoints, models, and authentication configuration
 
 `NORN_AGENT_DIR` selects another directory. Set it consistently for both
-`norn pi` and workflow execution. A programmatic runtime caller supplying `agentDir`
-must point the setup command at that same directory. Norn does not use an inherited
+`norn pi` and workflow execution. A programmatic runtime caller's explicit
+`agentDir` takes precedence over `NORN_AGENT_DIR`; the setup command still needs
+to target that same directory. Norn does not use an inherited
 `PI_CODING_AGENT_DIR` to select its global configuration. Existing Pi packages and
 credentials are not imported or linked: install providers and authenticate through
 `norn pi`, even when Pi is the outer harness.
@@ -59,7 +60,7 @@ norn pi
 
 This installs into Norn's global configuration. Select the new provider using
 `/model`. Agent resource discovery and model precedence are covered in
-[Norn agents](../docs/agents.md#prompts-tools-and-resource-loading).
+[Norn agents](agents.md#prompts-tools-and-resource-loading).
 Use `norn pi list` to inspect installations and `norn pi remove <source>` to remove
 one. Upgrade bundled Pi by upgrading Norn, not by using Pi's self-update command.
 `norn pi update --extensions` updates unpinned extension packages.

package/assets/docs/resources.md

@@ -2,18 +2,18 @@
 
 ## Initialization is separate from attachment
 
-Every run initializes or reopens `run.resources` before workflow execution and automatically ensures workflow state through that manager. The state handle is exposed as `run.state`, with `get`, `getOptional` and `set`. Creating storage does not populate declared fields, including schemas with defaults. Factory registration state remains in-memory and separate.
+`run.resources` provides shared resource handles, including [workflow state](persistence.md#choose-what-survives).
 
-`run.resources.ensure(definition)` returns a shared handle within that manager. A definition contains `name`, `kind`, JSON `configuration`, and `initialize({directory, files, mode})`. Names are single alphanumeric/underscore/hyphen identifiers starting with an alphanumeric character. Identity/configuration conflicts fail; `configuration` owns format/version compatibility.
+`run.resources.ensure(definition)` returns a shared handle for that resource across workflow contexts in the current executor. A definition contains `name`, `kind`, JSON `configuration`, and `initialize({directory, files, mode})`. Names are single alphanumeric/underscore/hyphen identifiers starting with an alphanumeric character. Identity/configuration conflicts fail; `configuration` owns format/version compatibility.
 
-The manager persists identity before calling the initializer and marks successful initialization afterward. `mode: "create"` also covers retry of an interrupted initialization; `mode: "open"` means an earlier initialization succeeded. Initializers own their data schema and must reject missing/incompatible data when reopening. Failed initialization remains visible and retryable, not a successful empty resource. Definitions have no filesystem effects until ensured.
+`mode: "create"` also covers retry of an interrupted initialization; `mode: "open"` means an earlier initialization succeeded. Initializers own their data schema and must reject missing/incompatible data when reopening. Failed initialization remains visible and retryable, not a successful empty resource. Definitions have no filesystem effects until ensured.
 
 | Decision | GOOD | BAD |
 |---|---|---|
 | IF implementing an initializer, THEN make create retries preserve existing data and open validate existing storage. ELSE do not register the definition. | Validate a file left by an interrupted create before reusing it. | Truncate the file each time `ensure` calls the initializer. |
 | IF a resource format changes incompatibly, THEN change its declared configuration and provide an explicit migration. ELSE reopen the same format. | A mismatching `format` fails. | Reinterpret old bytes under an unchanged format declaration. |
 
-Resources are run-scoped and persisted under `current/resources/`; built-in workflow values retain their existing `current/state.json` location. All workflow contexts in one executor share the manager. A resumed executor reopens handles, not closures. Resource data participates in normal [checkpoint recovery](recovery.md). Cross-run storage, queues, ledgers, and scheduler/agent activation are not supplied by this API.
+[Persistence](persistence.md) covers resource lifetimes, storage locations, and recovery. Cross-run storage, queues, ledgers, and scheduler/agent activation are not supplied by this API.
 
 ## Explicit agent attachment
 
@@ -33,7 +33,7 @@ resourceAdapters: [StateAdapter({
 
 List/get output is serialized JSON in bounded text pages. Requests specify UTF-16 `offset` and `limit` (1–10000); responses include `text`, `nextOffset` and a content `revision`. Pages are not a pinned snapshot. Set operations persist complete field values; get followed by set is not a transaction.
 
-Custom adapters implement `NornAgentResourceAdapter`: a unique name and `bind({runId, label})` returning a `NornAgentResourceBinding` with tools and async `dispose()`. An adapter can expose one or several resource handles; initializing storage does not construct or attach tools. Session creation and one-shot prompting accept adapters through `resourceAdapters`, not through the resource manager or state handle directly. The runner knows only the adapter contract, not individual resource kinds. Attached tools are activated with the normal response tool. Duplicate adapter names and collisions with built-ins, the response tool, other adapters or already-loaded extension tools fail. Successful bindings are cleaned up in reverse order on session disposal or later creation failure. An initializer/binder that throws before returning its handle owns cleanup of its partial allocations.
+Custom adapters implement `NornAgentResourceAdapter`: a unique name and `bind({runId, label})` returning a `NornAgentResourceBinding` with tools and async `dispose()`. An adapter can expose one or several resource handles; initializing storage does not construct or attach tools. Session creation and one-shot prompting accept adapters through `resourceAdapters`, not through the resource manager or state handle directly. Attached tools are activated with the normal response tool. Duplicate adapter names and collisions with built-ins, the response tool, other adapters or already-loaded extension tools fail. Successful bindings are cleaned up in reverse order on session disposal or later creation failure. An initializer/binder that throws before returning its handle owns cleanup of its partial allocations.
 
 | Decision | GOOD | BAD |
 |---|---|---|
@@ -47,9 +47,9 @@ The attachment never exposes internal scheduler/checkpoint control state. It is
 
 `run.resources.files` supplies `readText`, `writeText`, and `withExclusiveLock(path, async lockedPath => ...)`. Standalone callers can construct `NornFileCoordinator({lockRoot, waitTimeoutMs})` from `@vimhead.dev/norn`. Coordinating callers must use the same lock namespace. Target parents must exist before a raw `withExclusiveLock` call; `writeText` creates them. Existing symbolic links resolve to their canonical target; dangling links fail.
 
-The lock spans the complete callback, including read/validate/modify/persist. Atomic replacement remains underneath managed writes. A live owner is never expired by a TTL; confirmed dead local owners can be reclaimed. Invalid or foreign-host ownership fails closed, and contention has a bounded wait. PID reuse can delay reclamation rather than permit two owners. This is a local-filesystem, same-host protocol, not a distributed lock.
+The lock spans the complete callback, including read/validate/modify/persist. `writeText` replaces complete file contents atomically. A live owner is never expired by a TTL; confirmed dead local owners can be reclaimed. Invalid or foreign-host ownership fails closed, and contention has a bounded wait. PID reuse can delay reclamation rather than permit two owners. Locks support local filesystems on one host, not distributed storage.
 
-Workflow state, event manifests, scheduler-state writes, replaceable artifacts and whole-value logs use this coordination. Scheduler state remains executor-owned. Dedicated command-output streams retain their single-writer protocol; observability reads may see partial live streams. Immutable snapshot objects and run execution leases retain their own protocols. File locks do not make multi-file snapshots or external side effects transactional.
+Reads of live command-output logs may return partial streams. File locks do not make multi-file snapshots or external side effects transactional.
 
 | Decision | GOOD | BAD |
 |---|---|---|

package/assets/docs/schemas.md

@@ -0,0 +1,130 @@
+# TypeBox schemas
+
+The [Norn SDK](../packages/sdk/src/api.ts) accepts native `typebox` 1.x schemas for workflow params, config, state and agent responses. This reference is checked against 1.3.33. [Project loading](projects.md#import-and-reload) describes runtime-provided imports and editor dependency resolution.
+
+## TypeScript → TypeBox
+
+```ts
+import { Type, type Static } from "typebox";
+
+const Person = Type.Object({ name: Type.String() });
+type Person = Static<typeof Person>;
+```
+
+Schemas are runtime values; `Static` derives the TypeScript type. In the table, `S`, `A` and `B` are schemas, with corresponding inferred types `T`, `TA` and `TB`.
+
+| TypeScript type | TypeBox schema |
+|---|---|
+| `string` | `Type.String()` |
+| `number` | `Type.Number()` |
+| `boolean` | `Type.Boolean()` |
+| `null` | `Type.Null()` |
+| `undefined` | `Type.Undefined()` |
+| `unknown` | `Type.Unknown()` |
+| `any` | `Type.Any()` |
+| `never` | `Type.Never()` |
+| `"ready"` | `Type.Literal("ready")` |
+| `string[]` | `Type.Array(Type.String())` |
+| `[string, number]` | `Type.Tuple([Type.String(), Type.Number()])` |
+| `{ name: string }` | `Type.Object({ name: Type.String() })` |
+| `{ name?: string }` | `Type.Object({ name: Type.Optional(Type.String()) })` |
+| `{ readonly name: string }` | `Type.Object({ name: Type.Readonly(Type.String()) })` |
+| `string \| null` | `Type.Union([Type.String(), Type.Null()])` |
+| `TA \| TB` | `Type.Union([A, B])` |
+| `TA & TB` | `Type.Intersect([A, B])` |
+| `Record<string, number>` | `Type.Record(Type.String(), Type.Number())` |
+| `Partial<T>` | `Type.Partial(S)` |
+| `Required<T>` | `Type.Required(S)` |
+| `Pick<T, "name">` | `Type.Pick(S, ["name"])` |
+| `Omit<T, "name">` | `Type.Omit(S, ["name"])` |
+
+`Type.Integer()` also infers `number`; integrality is a runtime constraint. Optional properties may be absent; accepting `null` is a separate union. `Type.Readonly` affects static typing, not runtime freezing. `Type.Unknown` and `Type.Any` accept any value at runtime but infer different TypeScript types; neither guarantees JSON serializability. JavaScript-only values such as `undefined`, `bigint`, functions and symbols are not JSON data contracts.
+
+## Constraints and validation
+
+```ts
+import { Type } from "typebox";
+import { Value } from "typebox/value";
+import { Compile } from "typebox/compile";
+
+const Task = Type.Object({
+  title: Type.String({ minLength: 1 }),
+  attempts: Type.Integer({ minimum: 1, maximum: 10 }),
+}, { additionalProperties: false });
+
+const valid = Value.Check(Task, { title: "Build", attempts: 3 });
+const invalid = Value.Check(Task, { title: "Build", attempts: "3" });
+const issues = Value.Errors(Task, { title: "", attempts: 0 });
+const validator = Compile(Task);
+const compiledValid = validator.Check({ title: "Build", attempts: 3 });
+```
+
+`valid` and `compiledValid` are `true`; `invalid` is `false`. `Value.Check` tests without repairing the input. `Value.Assert` throws on failure. `Value.Parse` returns validated input with the default `correctiveParse: false` setting; enabling that setting adds repair operations. `Value.Errors` returns issues with fields including `keyword`, `instancePath`, `schemaPath` and `message`. `Compile` creates a reusable validator.
+
+Objects permit additional properties by default. `additionalProperties: false` rejects extras during validation; it does not strip them. A `default` annotation neither makes a property optional nor fills it during `Value.Check`. `Value.Default` is a separate operation; `Value.Convert` and `Value.Clean` likewise explicitly convert and clean values rather than merely validate them.
+
+## Tagged unions and refinements
+
+```ts
+import { Type, type Static } from "typebox";
+import { Value } from "typebox/value";
+
+const Outcome = Type.Union([
+  Type.Object({ kind: Type.Literal("done"), summary: Type.String() }),
+  Type.Object({ kind: Type.Literal("retry"), reason: Type.String() }),
+]);
+type Outcome = Static<typeof Outcome>;
+
+const UniqueNames = Type.Refine(
+  Type.Array(Type.String()),
+  names => new Set(names).size === names.length,
+  () => "Names must be unique",
+);
+const distinct = Value.Check(UniqueNames, ["build", "review"]);
+const repeated = Value.Check(UniqueNames, ["build", "build"]);
+```
+
+The literal `kind` supports TypeScript narrowing and distinguishes runtime branches. `Type.Refine` adds a predicate to an existing schema: `distinct` is `true`, `repeated` is `false`. The predicate executes in TypeBox; serializing the schema as JSON does not carry that function into another validator.
+
+## Recursive data
+
+```ts
+import { Type, type Static } from "typebox";
+import { Value } from "typebox/value";
+
+const Tree = Type.Cyclic({
+  Node: Type.Object({
+    name: Type.String(),
+    children: Type.Array(Type.Ref("Node")),
+  }),
+}, "Node");
+type Tree = Static<typeof Tree>;
+
+const tree: Tree = { name: "root", children: [{ name: "leaf", children: [] }] };
+const validTree = Value.Check(Tree, tree);
+```
+
+`Type.Cyclic` supplies definitions and selects the root; `Type.Ref` resolves a definition within that context. This describes recursive data shapes, not circular JavaScript object identities.
+
+## Codecs and input/output types
+
+```ts
+import { Type, type StaticEncode, type StaticDecode } from "typebox";
+import { Value } from "typebox/value";
+
+const CountText = Type.Codec(Type.String({ pattern: "^[0-9]+$" }))
+  .Decode(text => Number(text))
+  .Encode(count => String(count));
+
+type CountInput = StaticEncode<typeof CountText>;
+type CountOutput = StaticDecode<typeof CountText>;
+
+const count = Value.Decode(CountText, "42");
+const text = Value.Encode(CountText, 42);
+```
+
+`CountInput` is `string`, `CountOutput` is `number`; the values are `42` and `"42"`. `Static` uses the encoded/input direction. `Type.Decode(schema, callback)` defines a decode-only codec instead of a bidirectional one.
+
+`Value.Decode` is not a validation-only operation: in this version it clones, applies defaults, converts, cleans, validates, then runs decode callbacks. `Value.Check` and `Value.Assert` do not run codec callbacks. Callback behavior remains executable TypeBox code, not portable JSON Schema validation.
+
+Further API reference: [TypeBox documentation](https://sinclairzx81.github.io/typebox/).

package/assets/docs/workflows.md

@@ -6,15 +6,16 @@ Start with the complete [minimal plugin](../examples/minimal-workflow/plugin.ts)
 
 ## Declaration and implementation
 
-`definePluginManifest` qualifies workflow keys as `pluginId.workflowKey`, binds Zod params, optional plugin config, and optional state declarations. `definePlugin` binds every declared key to an implementation. Entrypoints need nonempty caller-facing `instructions`; internal steps may omit them. `isEntrypoint` controls default catalogue visibility, not an authorization boundary: the CLI can start a known internal workflow ID directly.
+`definePluginManifest` qualifies workflow keys as `pluginId.workflowKey`, binds TypeBox params, optional plugin config, and optional state declarations. `definePlugin` binds every declared key to an implementation. Entrypoints need nonempty caller-facing `instructions`; internal steps may omit them. `isEntrypoint` controls default catalogue visibility, not an authorization boundary: the CLI can start a known internal workflow ID directly.
 
-`instructions` describe selection, inputs, effects, and outputs. They are neither a Norn agent system prompt nor a gate decision. Params and plugin config are parsed before execution. Public contracts must support JSON Schema inspection; JSON params must survive persistence and later parsing.
+`instructions` describe selection, inputs, effects, and outputs. They are neither a Norn agent system prompt nor a gate decision. Declare params and config with [TypeBox schemas](schemas.md). Workflow inputs must be JSON data; `execute` receives the values after schema defaults and conversions. Public schemas must support `workflows inspect`.
 
 The implementation's `execute(run, params, config)` returns one control result:
 
 | Control | Meaning |
 |---|---|
-| `run.next(target, params)` | Transfer to another registered workflow in the same run. See [composition](composition.md). |
+| `target(params)` / `params.next(contribution)` | Select a known workflow or a caller-supplied next step. See [composition](composition.md). |
+| `run.next(workflowId, params)` | Select a workflow by string ID; its input is checked at execution. |
 | `run.complete(metadata)` | Complete the whole run, optionally exposing `summary`, `artifacts`, `logs`, and `data`. |
 | `run.fail({ summary, ...metadata })` | Record failure with an actionable explanation and optional evidence. |
 

package/assets/examples/agent-then-analysis/README.md

@@ -17,7 +17,7 @@ small application, not a prescribed development pipeline.
 
 [Select the matching runtime](../../docs/cli.md#select-the-runtime), copy this
 directory to a writable task directory, and `cd` into the copy. Configure
-[Norn agent authentication and a default model](../../setup/providers.md)
+[Norn agent authentication and a default model](../../docs/providers.md)
 beforehand; this example makes live model calls and the detached executor cannot
 prompt for login.