@vimhead.dev/norn-cli 0.1.0-tip.35359392805.1 → 0.1.0-tip.35436871363.1

package/assets/README.md

@@ -9,39 +9,34 @@ through the CLI from any harness. Agents run on the bundled
 
 1. [Install Norn](#installation), including agent authentication.
 
-2. **Combine an agent with code.** The agent writes a summary; code saves it as an artifact.
+2. **Combine an agent with code.** The agent writes a summary; code saves it as a file.
 
    ```ts
-   import { definePlugin, definePluginManifest } from "@vimhead.dev/norn";
+   import { writeFile } from "node:fs/promises";
+   import { join } from "node:path";
+   import { workflow } from "@vimhead.dev/norn";
    import { Type } from "typebox";
 
-   const manifest = definePluginManifest({
-     id: "summary",
-     workflows: {
-       write: {
-         isEntrypoint: true,
-         instructions: "Summarize supplied text and save the result.",
-         params: Type.Object({ text: Type.String() }),
-       },
+   const summarize = workflow({
+     id: "summary.write",
+     isEntrypoint: true,
+     instructions: "Summarize supplied text and save the result.",
+     args: Type.Object({ text: Type.String() }),
+     async execute({ args, paths, run }) {
+       const summary = await run.agents.prompt({
+         label: "summarize",
+         cwd: paths.workspace,
+         tools: [],
+         prompt: `Summarize this text in one sentence:\n${args.text}`,
+         response: Type.Object({ text: Type.String() }),
+       });
+       const summaryPath = "summary.txt";
+       await writeFile(join(paths.workspace, summaryPath), summary.text);
+       return run.complete({ data: { summaryPath } });
      },
    });
 
-   export default definePlugin(manifest, {
-     workflows: {
-       write: {
-         async execute(run, { text }) {
-           const summary = await run.agents.prompt({
-             label: "summarize",
-             tools: [],
-             prompt: `Summarize this text in one sentence:\n${text}`,
-             response: Type.Object({ text: Type.String() }),
-           });
-           const artifact = await run.artifacts.write("summary.txt", summary.text);
-           return run.complete({ artifacts: { summary: artifact } });
-         },
-       },
-     },
-   });
+   export default [summarize];
    ```
 
    [Full example and project configuration](examples/getting-started/README.md)
@@ -49,7 +44,7 @@ through the CLI from any harness. Agents run on the bundled
 3. **Run it** from the example directory:
 
    ```sh
-   printf '%s\n' '{"params":{"text":"Norn workflows combine agents and code. They run from any harness through the CLI."}}' \
+   printf '%s\n' '{"args":{"text":"Norn workflows combine agents and code. They run from any harness through the CLI."}}' \
      | norn runs start summary.write
 
    norn runs wait <run-id>

package/assets/docs/README.md

@@ -1,6 +1,6 @@
 # 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.
+Norn capabilities are ordinary TypeScript workflows: 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
 
@@ -10,10 +10,10 @@ Norn capabilities are ordinary TypeScript plugins: an agent can write one during
 | 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) |
+| Delegate work with explicit inputs and structured results | [Norn agents](agents.md) | [Norn agent → saved file → analysis](../examples/agent-then-analysis/README.md) |
+| Supply tools or tool wrappers to agents | [Custom tools](agents.md#custom-tools) | [Explicit shared state](../examples/shared-state/README.md) |
+| Persist application state or coordinate concurrent mutations | [Workflow-owned storage](persistence.md#workflow-owned-storage) | [Explicit shared state](../examples/shared-state/README.md), [Example-local work queue](../examples/coordinating-multiple-agents/README.md) |
+| Retain evidence or choose a filesystem boundary | [Persistence, files, and workspaces](persistence.md) | [Norn agent → saved file → analysis](../examples/agent-then-analysis/README.md) |
 | 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) |
 

package/assets/docs/agents.md

@@ -2,18 +2,32 @@
 
 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.
+The [Norn agent → saved file → 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.
+
+## Authoring types
+
+Import Pi types used by Norn directly from the SDK:
+
+```ts
+import type { CreateAgentSessionOptions, EventBus, PromptOptions, ToolDefinition } from "@vimhead.dev/norn";
+```
+
+These are Pi's original types, not Norn-specific copies. Installing the SDK
+installs its Pi dependency automatically; no separate Pi installation is needed.
 
 ## One prompt or a retained session
 
-`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).
+`run.agents.prompt({ label, cwd, 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:
+Both session creation and one-prompt calls require an absolute `cwd`; choose from the workflow's [paths](persistence.md#filesystem-boundaries) or supply another prepared directory. For follow-up turns in the same conversation:
 
 ```ts
+import { writeFile } from "node:fs/promises";
+import { join } from "node:path";
+
 const agentSession = await run.agents.createSession({
   label: "implementation",
-  cwd: run.cwd,
+  cwd: paths.workspace,
   tools: ["read", "bash", "edit", "write"],
 });
 try {
@@ -27,8 +41,9 @@ try {
     response: verificationSchema,
     maxAttempts: 2,
   });
-  const verificationArtifact = await run.artifacts.write("verification.json", JSON.stringify(verification));
-  return run.complete({ artifacts: { verification: verificationArtifact } });
+  const verificationPath = join(paths.workspace, "verification.json");
+  await writeFile(verificationPath, JSON.stringify(verification));
+  return run.complete({ data: { verificationPath } });
 } finally {
   await agentSession.dispose();
 }
@@ -46,11 +61,35 @@ Successful results and raw attempts are written under `current/logs/agents/`; Pi
 |---|---|---|
 | 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. |
+| 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 file, then pass its path to analysis. | Expect the next workflow to recover a local variable or an undisposed session object. |
 
-## Prompts, tools, and resource loading
+## Custom tools
+
+Both session creation and one-shot prompting accept Pi `ToolDefinition` objects through `customTools`. Each definition supplies a name, description, parameter schema, and execution function. Tools can close over files, services, or author-owned storage handles. The [state tools](../examples/shared-state/state-tools.ts) and [queue tools](../examples/coordinating-multiple-agents/queue-tools.ts) are complete example-owned factories.
+
+`customTools` registers definitions; an explicit `tools` array selects enabled names across built-in, custom, and loaded extension tools. The response tool is always included. `tools: []` requests only that response tool, even when custom definitions are supplied. Omitting `tools` uses Pi's configured default tools (`read`, `bash`, `edit`, `write` when unconfigured), plus custom and extension tools.
 
-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.
+```ts
+const result = await run.agents.prompt({
+  label: "lookup",
+  cwd: paths.workspace,
+  customTools: [lookupTool],
+  tools: ["read", lookupTool.name],
+  prompt: "Look up the requested information and summarize it.",
+  response: Type.Object({ summary: Type.String() }),
+});
+return run.complete({ summary: result.summary });
+```
+
+`lookupTool` is an author-provided `ToolDefinition` in this fragment. Custom tool names must be unique and must not collide with built-ins, the response tool, or already-loaded extension tools. Authors own tool dependencies and their cleanup, including when session creation fails; closing an agent does not close a database or delete stored data captured by its tools.
+
+| Decision | GOOD | BAD |
+|---|---|---|
+| IF supplying an explicit `tools` list, THEN include each custom or extension tool name the agent needs. ELSE Pi's default selection applies. | Register `lookupTool` and select `lookupTool.name`. | Expect `customTools: [lookupTool]` to bypass `tools: []`. |
+| IF tool closures contain per-agent state, THEN create fresh definitions for each agent. ELSE shared definitions can use a shared dependency. | Create queue tools separately for each claim owner. | Reuse one owner's closures across competing workers. |
+| IF tool dependencies need cleanup, THEN retain ownership with `try/finally` around session creation and use. ELSE no cleanup wrapper is necessary. | Close an author-opened connection after the agent finishes or fails. | Expect a tool definition to provide automatic connection disposal. |
+
+## Prompts, tools, and resource loading
 
 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.
 

package/assets/docs/cli.md

@@ -108,7 +108,7 @@ 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.
+Default workflow listing shows entrypoints; `--all` includes internal steps. Workflow inspection returns instructions, args JSON Schema, gate metadata, workflow/scope configuration schemas and keys, and registration 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
@@ -121,7 +121,7 @@ Commands and schemas from the invoked executable are authoritative when a checko
 From inside the target project:
 
 ```bash
-printf '%s\n' '{"params":{"name":"Ada"}}' | norn runs start greeting.write
+printf '%s\n' '{"args":{"name":"Ada"}}' | norn runs start greeting.write
 norn runs wait <run>
 norn runs inspect <run>
 norn runs metrics <run>
@@ -129,13 +129,13 @@ 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.
+Run results expose `run.paths.project` and `run.paths.workspace` as absolute directories. `run.path` identifies the complete run storage directory, not the workspace. A completed capability's outputs are in `run.outcome.metadata`; file paths in `data` follow that workflow's declared convention. The [minimal example](../examples/minimal-workflow/README.md) returns a `greetingPath` relative to `run.paths.workspace`.
 
-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.
+Start stdin accepts `args` and optional `config`, with config overrides keyed independently by workflow ID or scope ID. Args 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 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 file 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:
@@ -167,7 +167,7 @@ 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" },
+  args: { name: "Ada" },
 });
 const finished = await client.runs.wait(started.id);
 if (finished.status !== "completed" || finished.health !== "healthy") {
@@ -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; [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.
+`workflows.list()` and `inspect()` use fresh discovery. `workflows.entries()` retains its loaded catalogue; create a new client to refresh those entries 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,14 +3,14 @@
 ## Transfer, not a returning call
 
 ```ts
-return manifest.workflows.analyze({ draftArtifact });
+return analyze({ draftPath });
 ```
 
-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.
+Return a workflow call to select the next step in the same run. Supply its complete input; TypeScript checks it against the declaration's args schema. The target must be registered in the loaded project.
 
-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.
+This transfers control rather than calling a subroutine: awaiting the declaration does not execute the target or return its eventual result. Steps share workspace files, not local variables or agent conversations. `run.complete` completes the whole run.
 
-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.
+For a dynamically selected string ID, use `return run.next(workflowId, args)`. The selected target checks its input at runtime. `run.next` accepts IDs, not declarations or reference functions.
 
 ## Caller-selected workflow reference
 
@@ -18,18 +18,18 @@ The [caller-selected continuation example](../examples/caller-selected-continuat
 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:
+A reusable capability can accept a workflow reference whose schema describes the values it contributes. The caller supplies the target and captures the remaining args:
 
 ```ts
-import { artifactRefSchema, workflowRefSchema } from "@vimhead.dev/norn";
+import { workflowRefSchema } from "@vimhead.dev/norn";
 import { Type } from "typebox";
 
-const paramsSchema = Type.Object({
+const argsSchema = Type.Object({
   task: Type.String(),
   next: Type.Union([
     workflowRefSchema({
-      params: Type.Object({
-        resultArtifact: artifactRefSchema,
+      args: Type.Object({
+        resultPath: Type.String(),
         summary: Type.String(),
       }),
     }),
@@ -42,33 +42,33 @@ A caller supplies the target and its own parameters:
 
 ```json
 {
-  "params": {
+  "args": {
     "task": "Assess this import",
     "next": {
       "workflow": "importer.deliver",
-      "forwardParams": { "batchId": "batch-17" }
+      "forwardArgs": { "batchId": "batch-17" }
     }
   }
 }
 ```
 
-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`.
+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 `forwardArgs`.
 
-Inside the workflow, `params.next` is a function. Supply only the result fields declared above:
+Inside the workflow, `args.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 } });
+return args.next
+  ? args.next({ resultPath, summary })
+  : run.complete({ summary, data: { resultPath } });
 ```
 
-`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.
+`importer.deliver` receives `batchId` from the caller plus `resultPath` and `summary` from the producer. Its args 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.
+`workflows inspect` shows the contribution contract under `x-norn-workflow-ref.contributedArgsSchema`. Use it alongside the target's args 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`.
+When passing a reference as input to another workflow, supply its JSON form shown above, not the function received in `args.next`.
 
 ## Multiple outcomes and direct targets
 
@@ -77,21 +77,21 @@ References can be nested under ordinary author-selected names with independent c
 ```ts
 const next = Type.Object({
   success: workflowRefSchema({
-    params: Type.Object({ resultArtifact: artifactRefSchema }),
+    args: Type.Object({ resultPath: Type.String() }),
   }),
   failure: workflowRefSchema({
-    params: Type.Object({ reason: Type.String() }),
+    args: 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)`.
+An implementation can return `args.next.success({ resultPath })`, `args.next.failure({ reason })`, or select its own known target with `manualReviewWorkflow({ task, reason })`. A dynamic target still uses `run.next(selectedId, input)`.
 
 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 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 the caller selects the next step, THEN invoke its reference with the declared contribution. ELSE call a known declaration or use a dynamic ID. | `args.next({ resultPath })` | 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. |
 
@@ -99,8 +99,8 @@ The [worktree development loop](../examples/worktree-development-loop/README.md)
 
 ## 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.
+Reuse source by explicitly registering it, directly or through [included config](projects.md). There is no required package layout. Workflow IDs must remain unique within a project; shared scopes follow the [scope declaration contract](workflows.md#shared-scopes-and-configuration). Resources and workspace files belong to the invoking run, not the workflow 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 references.
+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 files is a caller responsibility. Relative paths must use the base declared by the producing workflow; see [file persistence](persistence.md).
 
 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

@@ -1,26 +1,34 @@
-# State, artifacts, and workspaces
+# Persistence, files, and workspaces
 
 ## Choose what survives
 
 | Value | Lifetime and access |
 |---|---|
-| 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. |
+| Local variables / module memory | Current invocation or executor only; not a resume contract. |
+| Workspace files | Ordinary files under `paths.workspace`, saved in checkpoints and restored on rollback. |
+| Outcome metadata | Caller-facing summary, log refs and workflow-defined `data`, exposed by run inspection. |
+| Workflow args | Explicit input to the current/next step, persisted for recovery. |
 
-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.
+Use arguments for step inputs and workspace files for retained content. The [shared-state example](../examples/shared-state/README.md) owns a SQLite store in its workspace. The [agent example](../examples/agent-then-analysis/plugin.ts) writes a JSON file with ordinary filesystem APIs and passes its path to analysis.
 
-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.
+File names, formats, and path conventions belong to the workflow. Return relevant paths in outcome `data`; declare whether they are absolute or relative and, for relative paths, their base. Norn does not interpret arbitrary strings in args or outcomes as paths. 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. |
+| IF evidence must remain distinguishable across attempts, THEN use distinct file 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 consumer receives a relative file path, THEN resolve it against the base declared by the workflow. ELSE use the absolute path directly. | Resolve a workspace-relative `draftPath` against `run.paths.workspace` from inspection. | Resolve it against the caller's cwd or the run storage root. |
+
+## Workflow-owned storage
+
+Workflows can use ordinary filesystem APIs or a storage library. Storage formats, initialization, validation, and concurrency belong to that application code. The [shared-state](../examples/shared-state/README.md) and [work-queue](../examples/coordinating-multiple-agents/README.md) examples use SQLite through `node:sqlite`, without a separate dependency installation.
+
+Finish writers and close database connections before returning a transition. Checkpoints preserve files, not live connections or closures; later steps reopen storage from `paths.workspace`. Stop all users of a store before rollback. An external database is not restored by a workspace checkpoint.
+
+| Decision | GOOD | BAD |
+|---|---|---|
+| IF agents mutate shared data concurrently, THEN use storage transactions or serialize the complete mutation. ELSE ordinary independent file writes can suffice. | Claim and acknowledge queue work transactionally. | Read the same JSON file in two agents and overwrite each other's changes. |
+| IF returning a transition after database work, THEN commit writes and close owned handles before returning. ELSE the workspace may not contain a consistent recoverable database. | Close the SQLite store in `finally`. | Leave writers running while the next step begins. |
 
 ## Filesystem boundaries
 
@@ -29,30 +37,33 @@ 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
+locks/             runtime locks; not snapshotted
 store/             snapshot manifests and content-addressed objects
 ```
 
-| Workflow isolation | Default `run.cwd` / `run.path(...)` | Additional access |
+Every workflow and gate description receives `paths`:
+
+| Path | Directory | Checkpoint and rollback behavior |
 |---|---|---|
-| `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(...)`. |
+| `paths.project` | Absolute root of the loaded project | Project edits are excluded. |
+| `paths.workspace` | Absolute, initially empty run workspace | Workspace files are saved in checkpoints and restored on rollback. |
+
+Run start, list, inspect, and wait results expose these same directories under `run.paths`. The separate `run.path` is the storage root, not the workspace. These locations remain discoverable for interrupted and failed runs as well as completed ones.
+
+Use ordinary path utilities to address files or subdirectories. The workspace is not a checkout or copy of the project. Commands and agents require an explicit absolute `cwd`, such as `paths.project`, `paths.workspace`, or a prepared subdirectory.
 
-`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.
+The dedicated run worker uses an empty, read-only cwd to guard against accidental relative writes to the project. This is not a security sandbox: enforcement depends on filesystem permissions and process privileges. Explicit project paths and other external locations remain accessible.
 
 | 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. |
+| IF work needs existing project files, THEN use `paths.project` or explicitly prepare a copy/worktree inside `paths.workspace`. ELSE use the empty run workspace. | A verifier chooses `cwd: paths.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 workflow 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).
+Sources: [public path and outcome types](../packages/sdk/src/api.ts), [snapshot store](../packages/cli/src/internal/run-store.ts).

package/assets/docs/projects.md

@@ -8,44 +8,54 @@ 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:
+Register workflow modules explicitly:
 
 ```json
 {
   "version": 1,
-  "plugins": ["./workflows/plugin.ts"],
-  "config": {
-    "example": { "repositoryRoot": "." }
-  }
+  "workflows": ["./workflows/index.ts"]
 }
 ```
 
-`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.
+Each module default-exports an array of complete [workflow definitions](workflows.md):
 
-Reusable config files, conventionally `norn.json`, can declare `plugins`, `includes`, and `config`. The project includes them explicitly:
+```ts
+import { summarize } from "./summarize.ts";
+import { save } from "./save.ts";
+
+export default [summarize, save];
+```
+
+Arrays may contain standalone workflows and workflows from multiple scopes. Only array entries are registered; importing or calling a target does not register it. Include internal transition targets as well as entrypoints. The [minimal example](../examples/minimal-workflow/README.md) needs only its project file and workflow module.
+
+The optional `config` object contains independently keyed [workflow and scope configuration](workflows.md#shared-scopes-and-configuration). Omit entries for owners without a config schema.
+
+Reusable config files, conventionally `norn.json`, can declare `workflows`, `includes`, and `config`:
 
 ```json
 {
   "version": 1,
-  "plugins": ["./local-plugin.ts"],
+  "workflows": ["./local-workflows.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` belongs only in the project file.
+Workflow and include paths resolve relative to the file declaring them. `*` matches one directory segment. There is no automatic workflow tree scan or inclusion of a sibling `norn.json`. Project config overrides included values; conflicting reusable values are rejected. `version` belongs only in the project file.
+
+Workflow IDs must be unique. Workflows can share a scope across modules by importing one scope definition; independent declarations of the same scope ID conflict.
 
 ## 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` and `/schema` subpaths, `typebox`, `typebox/value`, `typebox/compile`, and `typebox/schema`. Other dependencies need normal package resolution from the plugin's location.
+TypeScript modules need no local build. Runtime imports are supplied 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 workflow module'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.
+Runtime imports do not configure TypeScript or an editor. A matching `@vimhead.dev/norn` installation provides 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. [Persistence](persistence.md#choose-what-survives) defines the lifetime of factory context state.
+New CLI discovery/start/resume invocations load current source; an already executing workflow retains its loaded definition. Discovery does not invoke workflow execution or gate descriptions. Module-level code still executes during import.
 
 | 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. |
+| IF source changes, THEN inspect it through a new invocation before starting or resuming. ELSE use the inspected definition. | Edit a workflow, inspect it, then resume. | Assume a running executor hot-reloads edits. |
+| IF importing a module can mutate files or start work, THEN move those effects into workflow execution. ELSE keep import-time definitions. | `execute` launches the command. | `workflows list` starts a delivery from top-level code. |
 
 ## Diagnose registration
 
@@ -55,12 +65,14 @@ 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 returns `isComplete` and `diagnostics`, with source paths, stage, message, and schema issues when available. An invalid registration module is excluded as a whole; conflicting workflow IDs or scope declarations exclude the conflicting modules. `import` covers module evaluation as well as syntax/import errors.
+
+Workflow inspection exposes argument and configuration schemas, separate workflow/scope config keys, and the registration module and declaring configuration file. The registration module is not necessarily the file containing the implementation.
 
-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.
+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 is 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. |
+| IF `isComplete` is false, THEN repair or explicitly remove the invalid registration and inspect again. ELSE select from the loaded contracts. | Fix the named config field or default export. | Launch a valid sibling from an incomplete 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).
+Next: [write a workflow](workflows.md), [reuse across projects](composition.md).

package/assets/docs/providers.md

@@ -46,7 +46,7 @@ Finding a configured key or listing a model is not proof that a provider accepts
 
 ## Third-party provider packages
 
-Pi provider extensions are separate from Norn workflow plugins and outer-harness
+Pi provider extensions are separate from Norn workflow modules and outer-harness
 adapters. They register providers through Pi's APIs; do not put them in
 `norn.project.json` or install them only in Cursor's plugin marketplace.
 
@@ -83,8 +83,8 @@ with `/model`. A newly started session reloads the provider; its model listing c
 contain fallback models even without working credentials.
 
 Keep the provider's **local runtime and Pi tool bridge enabled** for Norn agents.
-Norn requires its structured-response tool, and attached resources also expose Pi
-tools. The provider's cloud mode does not expose that local bridge. Cursor-native
+Norn requires its structured-response tool, and workflow-supplied custom tools use
+the same bridge. The provider's cloud mode does not expose that local bridge. Cursor-native
 tools are a separate surface: restricting Norn's `tools` list does not disable
 Cursor's own tools or ambient configuration. See the package's documentation for
 its runtime and isolation controls.