@vimhead.dev/norn-cli 0.1.0-tip.0

package/README.md

@@ -0,0 +1,13 @@
+# Norn CLI
+
+Harness-agnostic workflow runtime with Pi-powered agent sessions.
+
+```bash
+npm install -g @vimhead.dev/norn-cli@tip
+norn docs intro
+```
+
+The package includes its matching SDK, documentation, and runnable examples.
+Use `norn pi` to configure Norn's provider credentials and default model.
+
+[Installation, authentication, and optional adapters](./assets/README.md).

package/assets/README.md

@@ -0,0 +1,157 @@
+# Norn
+
+Norn is a harness-agnostic workflow framework and runtime built primarily for
+agents. Use the Norn SDK to write reusable agent-driven and code-driven TypeScript
+workflows, then discover, run, inspect, and recover them through the CLI.
+
+Norn is intended as a portable replacement for harness-specific subagents and
+workflow extensions. Use it from Claude Code, Pi, Codex, or any other harness
+that can invoke its CLI.
+
+Norn agents are powered by the bundled, open-source and extensible
+[Pi coding agent](https://pi.dev). Your outer harness does not need to be Pi,
+and code-only workflows do not require a model.
+
+- [Documentation index](docs/README.md) — focused references by capability
+- [Create → run → change a workflow](examples/minimal-workflow/README.md) — code-driven, no model required
+- [Norn agent → saved artifact → analysis](examples/agent-then-analysis/README.md) — agent-driven, with a recoverable transition
+- [Norn SDK types](packages/sdk/src/api.ts)
+
+## Installation
+
+Install the runtime, authenticate for workflows that use Norn agents, and
+optionally connect your harness with an adapter. Direct CLI use needs no adapter.
+
+### 1. Install the runtime
+
+Install the rolling npm `tip` release (Node `>=22.19.0`):
+
+```bash
+npm install -g @vimhead.dev/norn-cli@tip
+norn version
+```
+
+Releases are prereleases, not stable `latest` releases. For a standalone binary
+without Node, use the matching GitHub `tip` release:
+
+```bash
+curl -fsSL https://github.com/vimhead/norn/releases/download/tip/install.sh | sh
+```
+
+Set `NORN_INSTALL_DIR` to select a different binary installation directory.
+
+[Runtime selection](docs/cli.md#select-the-runtime) covers source checkout invocation
+and keeping examples/docs matched to the executable. Upgrade discovery:
+
+```bash
+norn upgrade --dry-run
+```
+
+### 2. Authenticate Norn agents
+
+Open the bundled Pi interface; no separate Pi installation is required:
+
+```bash
+norn pi
+```
+
+Inside the interactive session:
+
+1. Run `/login`, choose a provider, and complete its authentication flow.
+2. Run `/model`, highlight a model, and press **Ctrl+S** to save the startup default.
+3. Run `/quit`.
+
+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).
+
+### 3. Optionally connect your harness
+
+The shipped Pi and Cursor adapters deliver Norn documentation context to your
+harness. Installing Norn alone does not register an adapter. Claude Code, Codex,
+and other harnesses can [invoke the CLI directly](docs/cli.md#javascript-client-and-other-harnesses).
+
+#### Pi
+
+With Pi already installed and `norn` available on `PATH`, install the adapter
+and start a new session:
+
+```bash
+pi install npm:@vimhead.dev/pi-norn@tip
+pi
+```
+
+To select a CLI executable outside `PATH`:
+
+```bash
+pi --norn-executable /absolute/path/to/norn
+```
+
+#### Cursor
+
+1. Open **Customize** in Cursor and choose **From GitHub Repository**.
+2. Enter `https://github.com/vimhead/norn` to import the marketplace.
+3. Install the **norn** plugin, choosing user or project scope.
+4. Start a new agent conversation.
+
+By default the adapter runs `norn` from `PATH`. To select a CLI executable
+outside `PATH`, start Cursor with an executable path:
+
+```bash
+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:
+
+```bash
+npm install -D @vimhead.dev/norn@tip
+```
+
+Use the SDK version reported by `norn version` for an exact runtime match. Runtime
+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
+pnpm install --frozen-lockfile
+pnpm check
+pnpm test
+pnpm pack:dry
+```
+
+Use the pnpm version pinned in `package.json`. The private root coordinates three
+published workspaces: `packages/sdk`, `packages/cli`, and `packages/pi-norn`.
+`packages/core` is private source shared through consumer builds, not a fourth
+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.

package/assets/docs/README.md

@@ -0,0 +1,23 @@
+# Norn documentation
+
+Norn capabilities are ordinary TypeScript plugins: an agent can write one during a task, register it in that project, exercise it, change it, and retain it for another caller. No generated project hierarchy or separate compilation step is required.
+
+## Read by task
+
+| 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) |
+| Discover contracts or invoke Norn from another harness | [CLI and client](cli.md) | [Create → run → change](../examples/minimal-workflow/README.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 |
+| 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.
+
+| Decision | GOOD | BAD |
+|---|---|---|
+| IF a task needs persisted workflow control, independently prompted Norn agents, or a callable capability, THEN use the relevant pages and author only the missing capability. ELSE solve it directly. | A retryable delivery step consuming saved assessments. | Wrapping a literal text replacement in a workflow solely because Norn is installed. |
+| IF the executable differs from the installation containing these docs, THEN locate matching docs or invoke this installation explicitly using [CLI setup](cli.md#select-the-runtime). ELSE use its local examples and types. | A source checkout paired with its own `packages/cli/bin/norn.mjs`. | Reading a new checkout while invoking an older `PATH` binary. |

package/assets/docs/agents.md

@@ -0,0 +1,64 @@
+# Norn agents
+
+A Norn agent is a workflow-managed session powered by the bundled, open-source and extensible [Pi coding agent](https://pi.dev). Pi supplies the agent implementation regardless of which [outer harness invokes Norn](cli.md#javascript-client-and-other-harnesses). Extensions, skills, and custom providers can customize these sessions; their loading and boundaries are described below.
+
+The [Norn agent → saved artifact → analysis example](../examples/agent-then-analysis/README.md) is a complete two-session application. Agent outputs flow through a saved contract, not shared conversation history.
+
+## 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 }`.
+
+For follow-up turns in the same conversation:
+
+```ts
+const agentSession = await run.agents.createSession({
+  label: "implementation",
+  cwd: run.cwd,
+  tools: ["read", "bash", "edit", "write"],
+});
+try {
+  const implementation = await agentSession.prompt({
+    prompt: task,
+    response: implementationSchema,
+    maxAttempts: 2,
+  });
+  const verification = await agentSession.prompt({
+    prompt: JSON.stringify({ task: "Verify the saved changes", implementation }),
+    response: verificationSchema,
+    maxAttempts: 2,
+  });
+  const verificationArtifact = await run.artifacts.write("verification.json", JSON.stringify(verification));
+  return run.complete({ artifacts: { verification: verificationArtifact } });
+} finally {
+  await agentSession.dispose();
+}
+```
+
+`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.
+
+## Response contract and evidence
+
+Norn adds `pi_workflows_agent_response` to the requested tools and supplies the schema and response instructions. If a turn omits that tool call, Norn requests finalization with only that tool active. Invalid or missing structured responses can be retried in the same session (`maxAttempts`, default 3). This is response-contract recovery, not a domain retry policy or a retry of every provider exception.
+
+Successful results and raw attempts are written under `current/logs/agents/`; Pi session files live under `current/sessions/`. A schema-valid response establishes shape, not factual support, successful external effects, or task completion.
+
+| Decision | GOOD | BAD |
+|---|---|---|
+| IF later work needs independent judgment, THEN create a fresh session and pass only its input/evidence contract. ELSE retain a session for conversation-dependent follow-up. | Analysis receives saved source and draft, not the author's conversation. | Call an author again and describe its self-review as independent. |
+| IF a Norn agent claims a verifiable result, THEN verify the evidence before accepting it. ELSE preserve the uncertainty in the result. | Check quotations against source bytes and command outcomes against logs. | Treat a schema-valid `passed: true` as proof that tests ran. |
+| IF a result must survive a workflow transition, THEN save its content/ref using [persistence](persistence.md). ELSE keep it local to the active step. | Save a draft artifact, then pass its ref to analysis. | Expect the next workflow to recover a local variable or an undisposed session object. |
+
+## Prompts, tools, and resource loading
+
+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.
+
+`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.
+
+| Decision | GOOD | BAD |
+|---|---|---|
+| IF a custom-prompt Norn agent must author capabilities, THEN deliberately supply the matching documentation locations and authoring scope. ELSE keep authoring material out of a source-only assessor's supplied prompt. | Author gets installed Norn references; assessor gets source and result. | Inject the entire parent task and authoring manual into every agent. |
+| IF strict evidence/tool isolation is required, THEN control the Pi resource environment and inspect the effective session, using an OS boundary for filesystem restrictions. ELSE describe this as conversation separation only. | Verify loaded context and active tools in a controlled agent environment. | Call `tools: []` plus a fresh session a filesystem sandbox. |
+
+Sources: [session API](../packages/sdk/src/api.ts), [agent runner](../packages/cli/src/internal/agents.ts), [response tool](../packages/cli/src/internal/agent-response-tool.ts). Filesystem semantics: [workspaces](persistence.md#filesystem-boundaries).

package/assets/docs/cli.md

@@ -0,0 +1,183 @@
+# CLI and client
+
+## Select the runtime
+
+[Install Norn](../README.md#installation), then inspect the executable you will actually invoke:
+
+```bash
+command -v norn
+norn version
+norn help
+```
+
+For a source checkout, run `pnpm install --frozen-lockfile` and `pnpm build` first. A shell function keeps all examples bound to that checkout rather than another `PATH` installation:
+
+```bash
+NORN_ROOT=/absolute/path/to/norn
+norn() { node "$NORN_ROOT/packages/cli/bin/norn.mjs" "$@"; }
+norn version
+```
+
+Use Node satisfying the package's engine requirement (currently `>=22.19.0`). `NORN_ROOT` here is an example shell variable, not a runtime configuration option. Use `norn docs inspect` to locate this installation's documentation and examples;
+[local documentation assets](#local-documentation-assets) covers binary extraction.
+Source builds may not carry release revision metadata. Rebuild after changing source or documentation.
+
+Registry installations update through the package manager in their existing scope:
+`npm install -g @vimhead.dev/norn-cli@tip` for a global npm installation, or the
+corresponding local install command. `norn upgrade` does not guess that scope.
+Standalone binaries retain their checksum-verified `norn upgrade` command.
+
+Copied examples already contain a project file, so they skip initialization. npm
+omits `.gitignore` from the package; add `.norn/runs/` to the copy's `.gitignore`
+before committing example work. Source-checkout examples include that exclusion.
+
+## Local documentation assets
+
+```bash
+norn docs inspect
+```
+
+This explicit command works outside a Norn project and does not use the network.
+Its `documentation` result contains `storage`, `version`, `commit`, `assetDigest`,
+and absolute `paths` (`root`, `readme`, `index`, `docs`, `examples`).
+
+npm/source installations resolve their built `assets/` tree directly from the CLI
+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
+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.
+
+Cache roots:
+
+- macOS: `~/Library/Caches/norn/docs/`
+- Linux: `$XDG_CACHE_HOME/norn/docs/`, or `~/.cache/norn/docs/`
+- 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.
+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
+installation.
+
+| Decision | GOOD | BAD |
+|---|---|---|
+| IF an example will be edited or run, THEN copy it into the task workspace first. ELSE read the cached asset in place. | Copy `paths.examples/minimal-workflow` before starting a run. | Modify the verified cache or put `.norn/` state inside it. |
+| IF inspection reports a modified/incomplete cache, THEN preserve any wanted edits elsewhere, remove only the named cache entry, and retry. ELSE reuse the returned paths. | Remove the reported `v1-...` directory after preserving work. | Delete every build's cache or accept modified docs as matching the binary. |
+
+The same resolver is available from [`@vimhead.dev/norn-cli/documentation`](../packages/cli/src/documentation.ts),
+with explicit source, build metadata, and cache-root inputs.
+
+## Documentation introduction
+
+```bash
+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`
+and works without a valid project.
+
+The invocation is a JSON argument array, not a shell command string. Its first
+entry is the executable; remaining entries precede CLI arguments. Source/npm
+invocations include the Node executable and this installation's `bin/norn.mjs`;
+compiled invocations contain the binary path. Spaces and quotes remain part of
+each argument, without relying on another `norn` installation on PATH.
+
+`renderNornDocumentationIntro({ documentation, invocation })`, also exported from
+[`@vimhead.dev/norn-cli/documentation`](../packages/cli/src/documentation.ts), renders the same text from explicit
+inputs without filesystem or process access. Generating the introduction does not
+inject it into prompts or alter Norn agent sessions.
+
+## Discover live contracts
+
+```bash
+norn project inspect
+norn workflows list
+norn workflows list --all
+norn workflows inspect <workflow-id>
+norn commands list
+norn commands inspect runs.start
+norn help runs start
+```
+
+Default workflow listing shows entrypoints; `--all` includes internal steps. Workflow inspection returns instructions, params JSON Schema, isolation, gate metadata and plugin source locations. [Loading diagnostics](projects.md#diagnose-registration) are part of the discovery envelope.
+
+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.
+Commands and schemas from the invoked executable are authoritative when a checkout and installation differ.
+
+## Start, wait, inspect
+
+From inside the target project:
+
+```bash
+printf '%s\n' '{"params":{"name":"Ada"}}' | norn runs start greeting.write
+norn runs wait <run>
+norn runs inspect <run>
+norn runs metrics <run>
+```
+
+Start returns `{ "run": ... }` with `id`, `name`, and `path`, after launching a detached executor. This is acceptance of the launch, not success of the task. `runs wait` returns when the run is no longer running or inspection reports it unhealthy. Its successful process exit does not mean the workflow completed; callers check `run.status`, `run.health`, and outcome/failure information.
+
+A completed capability's outputs are in `run.outcome.metadata`. Artifact refs resolve beneath `<run.path>/current/artifacts/`. The [minimal example](../examples/minimal-workflow/README.md) gives concrete output expectations.
+
+Start stdin accepts `params` and optional `config`, with config overrides keyed by plugin ID. Params are JSON, not CLI flags or TOON. For display, a JSON viewer can format a finite result; keep machine artifacts and JSONL events in their native format.
+
+| Decision | GOOD | BAD |
+|---|---|---|
+| IF start returns a run ID, THEN retain it and inspect the terminal outcome. ELSE handle the launch error. | Wait, then verify `status === "completed"` and expected artifact content. | Report task success from `runs start` alone. |
+| IF a new capability is written or registered, THEN query the current catalogue and schema. ELSE use the inspected contract. | `workflows inspect greeting.write` after editing. | Rely on a cached session-start list that cannot contain the new workflow. |
+
+For live monitoring and explicit lifecycle control:
+
+```bash
+norn runs list
+norn runs logs <run>
+norn runs logs <run> --follow
+norn runs stop <run>
+norn runs kill <run>
+norn runs delete <run>
+```
+
+`stop` signals SIGTERM; `kill` signals SIGKILL. Delete removes an inactive run and its evidence. Neither stopping nor deleting undoes external effects. Resume and rollback are documented in [recovery](recovery.md).
+
+## JavaScript client and other harnesses
+
+Claude Code, Pi, Codex, and other CLI-capable harnesses can invoke Norn without an
+adapter. Workflows provide portable task delegation and workflow logic, not
+compatibility with a host's plugin format or UI extension APIs. The caller does
+not need Pi installed: [Norn agents](agents.md) use Norn's bundled Pi runtime.
+
+The JavaScript client invokes the runtime; the [Norn SDK](workflows.md) defines
+workflows. For example, start and inspect a run through `@vimhead.dev/norn-cli/client`:
+
+```ts
+import { createNornClient } from "@vimhead.dev/norn-cli/client";
+
+const client = createNornClient({ spawnCwd: "/absolute/path/to/project" });
+const started = await client.runs.start({
+  workflowId: "greeting.write",
+  params: { name: "Ada" },
+});
+const finished = await client.runs.wait(started.id);
+if (finished.status !== "completed" || finished.health !== "healthy") {
+  throw new Error(`Run ${finished.id}: ${finished.status} (${finished.health})`);
+}
+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.
+
+Sources: [CLI declarations and handlers](../packages/cli/src/cli.ts), [client API](../packages/cli/src/client.ts).

package/assets/docs/composition.md

@@ -0,0 +1,76 @@
+# Composition and reuse
+
+## Transfer, not a returning call
+
+```ts
+return run.next(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.
+
+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.
+
+## Caller-selected continuation
+
+A reusable capability can accept a continuation whose schema describes the values it contributes. The caller owns 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(),
+    }),
+  }).nullable(),
+});
+```
+
+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:
+
+```json
+{
+  "params": {
+    "task": "Assess this import",
+    "next": {
+      "workflow": "importer.deliver",
+      "forwardParams": { "batchId": "batch-17" }
+    }
+  }
+}
+```
+
+`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`.
+
+`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.
+
+| 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. |
+
+The [worktree development loop](../examples/worktree-development-loop/README.md) is a larger continuation-based example, 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.
+
+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

@@ -0,0 +1,56 @@
+# State, artifacts, and workspaces
+
+## Choose what survives
+
+| Value | Lifetime and access |
+|---|---|
+| Local variables / plugin factory memory | Current executor only; not a resume contract. Factory context state is in-memory registration state. |
+| `run.state` | Per-run, schema-validated JSON shared across steps. `get` requires a value; `getOptional` permits absence; `set` persists it. |
+| `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.
+
+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.
+
+| Decision | GOOD | BAD |
+|---|---|---|
+| IF earlier work must survive retry of a later step, THEN persist it before a transition and recover from that boundary. ELSE expect the active step to be repeated. | Save assessments, transition to delivery, retry delivery. | Keep assessments in a closure and restart the entire coordinator. |
+| IF evidence must remain distinguishable across attempts, THEN use distinct artifact paths or retain the relevant checkpoint. ELSE document intentional replacement. | `attempt-2/analysis.json`. | Overwrite `analysis.json` while promising both revisions remain in the current files. |
+| IF a ref crosses into another run or project, THEN transfer its content and establish a destination-owned ref. ELSE use the ref within its original run. | Read and copy the source run's artifact before invoking a separate consumer run. | Pass `{ "path": "draft.json" }` to an unrelated run and expect global resolution. |
+
+## Filesystem boundaries
+
+Each run is stored under `<project>/.norn/runs/<id>/`:
+
+```text
+current/
+  workspace/       working files
+  artifacts/       capability evidence and results
+  resources/       resource definitions and data
+  state.json       workflow state values
+  run-state.json   scheduler state
+  manifest.json    recorded events
+  logs/            command and agent output
+  sessions/        Pi conversations
+  checkpoints.json
+locks/             transient resource/file coordination; not snapshotted
+store/             snapshot manifests and content-addressed objects
+```
+
+| Workflow isolation | Default `run.cwd` / `run.path(...)` | Additional access |
+|---|---|---|
+| `runWorkspace` (default) | `current/workspace/` | An initially empty directory, not a checkout or copy of the project. |
+| `project` | Project root | Typed `run.projectRoot` and `run.projectPath(...)`. |
+
+`run.workspace` remains the per-run workspace in both modes. Command/agent cwd selection and path helpers reject lexical escapes from the selected root. These checks do not sandbox Node code, shell commands, tool file arguments, symlinks, network access, or loaded extensions.
+
+| Decision | GOOD | BAD |
+|---|---|---|
+| IF work needs existing project files, THEN declare project isolation or explicitly prepare a copy/worktree inside the run workspace. ELSE use the empty per-run workspace. | A project-mode verifier checks the actual project; an editing workflow prepares its own worktree. | Run `npm test` in an empty workspace and assume the repository is present. |
+| IF rollback must undo a change, THEN keep it in snapshotted run files or separately manage the external effect. ELSE do not promise rollback of that change. | Reconcile a project-root edit or remote delivery explicitly. | Assume snapshots restore project plugin source, remote APIs, or symlink targets. |
+
+Snapshots cover `current/`, preserve symlinks as links rather than copying targets, and do not include project-root source. [Recovery](recovery.md) defines when snapshots are taken and how to select a retry boundary.
+
+Sources: [state store](../packages/cli/src/internal/state-store.ts), [artifacts](../packages/cli/src/internal/artifacts.ts), [run paths](../packages/cli/src/internal/run.ts), [snapshot store](../packages/cli/src/internal/run-store.ts).

package/assets/docs/projects.md

@@ -0,0 +1,75 @@
+# Projects and loading
+
+## Create and register
+
+```bash
+norn project init
+```
+
+Initialization creates `norn.project.json`, `.norn/runs/`, and a run-state exclusion in `.gitignore`. Project discovery walks upward from the invocation directory to the nearest `norn.project.json`.
+
+A plugin can be a single file anywhere explicitly registered by the project:
+
+```json
+{
+  "version": 1,
+  "plugins": ["./workflows/plugin.ts"],
+  "config": {
+    "example": { "repositoryRoot": "." }
+  }
+}
+```
+
+`config` is keyed by plugin ID and validated against that plugin's manifest schema. Omit the entry for a plugin with no config schema. [The minimal example](../examples/minimal-workflow/README.md) needs only its project file and plugin.
+
+Reusable config files, conventionally `norn.json`, can declare `plugins`, `includes`, and `config`. The project includes them explicitly:
+
+```json
+{
+  "version": 1,
+  "plugins": ["./local-plugin.ts"],
+  "includes": ["./packages/*/norn.json"]
+}
+```
+
+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).
+
+## 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.
+
+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).
+
+| Decision | GOOD | BAD |
+|---|---|---|
+| IF source changes, THEN inspect it through a new invocation before starting or resuming. ELSE use the inspected declaration. | Edit `plugin.ts`, run `workflows inspect`, then resume. | Assume a running Norn agent or executor hot-reloads the edit. |
+| IF importing a plugin can mutate files or start work, THEN move those effects into workflow execution. ELSE keep import-time declarations and factory construction. | `execute` launches the command. | `workflows list` unexpectedly starts a delivery from top-level module code. |
+
+## Diagnose registration
+
+```bash
+norn project inspect
+norn workflows list --all
+norn workflows inspect example.plan
+```
+
+Discovery returns `isComplete` and `diagnostics`. Each diagnostic includes source paths, stage, message, and schema issues when available. A broken plugin is excluded as a whole; duplicate plugin IDs exclude all conflicting sources. `import` covers module evaluation as well as syntax/import errors.
+
+Discovery can exit successfully with an incomplete catalogue. Start, resume, and executable client entries require the entire project to load; otherwise they report `NORN_PROJECT_INVALID`. Malformed project/include configuration remains fatal rather than producing a partial catalogue.
+
+| Decision | GOOD | BAD |
+|---|---|---|
+| IF `isComplete` is false, THEN repair or explicitly remove the reported invalid registration and inspect again. ELSE select from the loaded contracts. | Fix the named config field or missing default export. | Treat a listed valid sibling as permission to launch an invalid project. |
+
+Sources: [loader](../packages/cli/src/plugin-loader.ts), [registry](../packages/cli/src/internal/workflow-registry.ts). Next: [write a workflow](workflows.md), [reuse across projects](composition.md).