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

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aleksandr Zub
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/assets/README.md

@@ -1,21 +1,55 @@
 # 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)
+Norn is a portable runtime for reusable agent-driven and code-driven TypeScript
+workflows. Author them with the SDK, then discover, run, inspect, and recover them
+through the CLI from any harness. Agents run on the bundled
+[Pi coding agent](https://pi.dev); code-only workflows need no model.
+
+## Getting started
+
+1. [Install Norn](#installation), including agent authentication.
+
+2. **Combine an agent with code.** The agent writes a summary; code saves it as an artifact.
+
+   ```ts
+   import { workflow } from "@vimhead.dev/norn";
+   import { Type } from "typebox";
+
+   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, run }) {
+       const summary = await run.agents.prompt({
+         label: "summarize",
+         tools: [],
+         prompt: `Summarize this text in one sentence:\n${args.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)
+
+3. **Run it** from the example directory:
+
+   ```sh
+   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>
+   ```
+
+   Replace `<run-id>` with the ID returned by `start`.
+
+See the [documentation index](docs/README.md) for focused references and the
+[SDK types](packages/sdk/src/api.ts) for API details.
 
 ## Installation
 

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
 
@@ -11,9 +11,9 @@ Norn capabilities are ordinary TypeScript plugins: an agent can write one during
 | 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) |
+| Initialize resources, attach agent 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) |
+| Retain evidence or choose a filesystem boundary | [Persistence, 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) | [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

@@ -4,6 +4,17 @@ A Norn agent is a workflow-managed session powered by the bundled, open-source a
 
 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.
 
+## 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).
@@ -50,7 +61,7 @@ Successful results and raw attempts are written under `current/logs/agents/`; Pi
 
 ## 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.
+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 resource tools.
 
 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, isolation, 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>
@@ -131,7 +131,7 @@ Start returns `{ "run": ... }` with `id`, `name`, and `path`, after launching a
 
 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.
+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 |
 |---|---|---|
@@ -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({ draftArtifact });
 ```
 
-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 run resources and artifacts, 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,17 +18,17 @@ 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 { Type } from "typebox";
 
-const paramsSchema = Type.Object({
+const argsSchema = Type.Object({
   task: Type.String(),
   next: Type.Union([
     workflowRefSchema({
-      params: Type.Object({
+      args: Type.Object({
         resultArtifact: artifactRefSchema,
         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 })
+return args.next
+  ? args.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.
+`importer.deliver` receives `batchId` from the caller plus `resultArtifact` 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({ resultArtifact: artifactRefSchema }),
   }),
   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({ resultArtifact })`, `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({ 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. |
 
@@ -99,7 +99,7 @@ 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 artifacts belong to the invoking project/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.
 

package/assets/docs/persistence.md

@@ -1,20 +1,18 @@
-# State, artifacts, and workspaces
+# Persistence, artifacts, 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. |
+| Local variables / module memory | Current invocation or executor only; not a resume contract. |
 | `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 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, artifacts for retained outputs, and [resources](resources.md) for mutable storage. The [shared-state example](../examples/shared-state/README.md) provides a custom store; Norn has no dedicated application-state API. The [agent example](../examples/agent-then-analysis/plugin.ts) saves a draft artifact and passes its reference explicitly 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.
+Artifact refs are paths, not content hashes, and writing to the same path replaces its content. An artifact read returns text, so a JSON consumer still needs parsing and schema validation. Separate artifact and resource writes are not one transaction.
 
 | Decision | GOOD | BAD |
 |---|---|---|
@@ -31,7 +29,6 @@ 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
@@ -51,8 +48,8 @@ store/             snapshot manifests and content-addressed objects
 | 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 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: [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

@@ -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.
 

package/assets/docs/recovery.md

@@ -10,19 +10,19 @@ norn runs checkpoints <run>
 
 `<run>` is the ID or generated name returned by start. Inspection exposes status, health, current workflow, failure/interruption, and outcome metadata. Logs are newline-delimited events; agent and command evidence is retained in the run's current files. [CLI details](cli.md) explain launch/wait semantics.
 
-Checkpoints are taken at run start, successful transitions, gate interruptions, and completion. Failure/stopping does not create a new successful boundary. A transition snapshot contains the saved preceding work and the next step's params.
+Checkpoints are taken at run start, successful transitions, gate interruptions, and completion. Failure/stopping does not create a new successful boundary. A transition snapshot contains the saved preceding work and the next step's args.
 
 | Observed state | Action | GOOD | BAD |
 |---|---|---|---|
-| `failed` or `stopped` | IF execution must continue, THEN repair the cause, select an earlier active checkpoint, rollback, and resume without params. ELSE leave the run inactive. | Retry delivery from the transition after assessment. | Resume a failed run directly or restart all assessments. |
-| `interrupted` | IF the declared decision is available within authorization, THEN resume with the permitted param patch. ELSE retain the interruption and identify the missing input. | An authorized agent evaluates evidence and supplies the decision. | Assume every gate requires a human or edit protected evidence fields. |
-| `pendingResume` | IF retry is intended, THEN resume with no params. ELSE leave the restored boundary untouched. | `norn runs resume <run> </dev/null`. | Try to override arbitrary saved inputs through resume. |
+| `failed` or `stopped` | IF execution must continue, THEN repair the cause, select an earlier active checkpoint, rollback, and resume without args. ELSE leave the run inactive. | Retry delivery from the transition after assessment. | Resume a failed run directly or restart all assessments. |
+| `interrupted` | IF the declared decision is available within authorization, THEN resume with the permitted argument patch. ELSE retain the interruption and identify the missing input. | An authorized agent evaluates evidence and supplies the decision. | Assume every gate requires a human or edit protected evidence fields. |
+| `pendingResume` | IF retry is intended, THEN resume with no args. ELSE leave the restored boundary untouched. | `norn runs resume <run> </dev/null`. | Try to override arbitrary saved inputs through resume. |
 | `running` with unhealthy inspection | IF the executor is no longer healthy, THEN inspect ownership and reconcile effects before recovery. ELSE monitor active execution. | Check run health and command evidence before retry. | Start a competing executor or equate stale status with successful delivery. |
 
 ## Source repair and rollback
 
 ```bash
-# Edit the registered plugin source, then inspect its current contract.
+# Edit the registered workflow source, then inspect its current contract.
 norn workflows inspect <workflow-id>
 norn runs checkpoints <run>
 norn runs rollback <run> <checkpoint-id>
@@ -30,7 +30,7 @@ norn runs resume <run> </dev/null
 norn runs wait <run>
 ```
 
-Use the actual `cp_...` ID from checkpoint listing, not an index or invented name. Rollback restores the run's current files and active checkpoint history, then prepares the saved step for resume. A fresh CLI executor loads current plugin source. It does not restore the source version that created the checkpoint, and saved params/state must remain compatible with the repaired implementation.
+Use the actual `cp_...` ID from checkpoint listing, not an index or invented name. Rollback restores the run's current files and active checkpoint history, then prepares the saved step for resume. A fresh CLI executor loads current workflow source. It does not restore the source version that created the checkpoint, and saved args/state must remain compatible with the repaired implementation.
 
 Rollback restores only [snapshotted files](persistence.md). It does not undo project-root edits, remote deliveries, or other external effects. Re-execution is not an exactly-once guarantee.
 
@@ -41,6 +41,10 @@ Rollback restores only [snapshotted files](persistence.md). It does not undo pro
 
 The [agent example's repair exercise](../examples/agent-then-analysis/README.md#repair-only-the-analysis-step) demonstrates preserving a live Norn agent result through analysis failure and source repair.
 
+## Saved-run compatibility
+
+Runs created before the complete-workflow API migration cannot be resumed or rolled back by this alpha. Their saved status remains inspectable, and existing files are preserved. Use the original runtime to continue those runs, or start a new run.
+
 ## Declared gates
 
 A workflow can declare:
@@ -49,8 +53,8 @@ A workflow can declare:
 gate: { enabled: true, fields: ["decision", "notes"] }
 ```
 
-Its params schema must include those top-level fields. An optional implementation `gate.describe(run, params, config)` explains the decision. The CLI uses pause mode: a gate interrupts **before** execution, including direct starts of a gated workflow.
+Its args schema must include those top-level fields. An optional `gate.describe({ args, config, scope, run })` callback explains the decision, with the same inferred context as `execute`; standalone workflows have no `scope` property. The CLI uses pause mode: a gate interrupts **before** execution, including direct starts of a gated workflow.
 
-Resume stdin has the form `{"params":{"decision":"accept","notes":"Evidence checked"}}`. With declared `fields`, the patch merges into saved object params and rejects non-gate keys; without `fields`, resume supplies replacement params. The merged/replacement value is schema-validated. A gate is a persisted control boundary, not an automatic human approval mechanism or an authorization system.
+Resume stdin has the form `{"args":{"decision":"accept","notes":"Evidence checked"}}`. With declared `fields`, the patch merges into saved object args and rejects non-gate keys; without `fields`, resume supplies replacement args. The merged/replacement value is schema-validated. A gate is a persisted control boundary, not an automatic human approval mechanism or an authorization system.
 
-Sources: [scheduler and resume](../packages/cli/src/internal/engine.ts), [saved state and param merging](../packages/cli/src/internal/run-state.ts), [snapshot restoration](../packages/cli/src/internal/run-store.ts), [CLI lifecycle](../packages/cli/src/cli.ts).
+Sources: [scheduler and resume](../packages/cli/src/internal/engine.ts), [saved state and argument patches](../packages/cli/src/internal/run-state.ts), [snapshot restoration](../packages/cli/src/internal/run-store.ts), [CLI lifecycle](../packages/cli/src/cli.ts).

package/assets/docs/resources.md

@@ -2,7 +2,7 @@
 
 ## Initialization is separate from attachment
 
-`run.resources` provides shared resource handles, including [workflow state](persistence.md#choose-what-survives).
+`run.resources` provides shared resource handles. The [shared-state example](../examples/shared-state/README.md) demonstrates mutable storage as a custom resource.
 
 `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.
 
@@ -17,28 +17,13 @@
 
 ## Explicit agent attachment
 
-The [runnable shared-state example](../examples/shared-state/README.md) uses:
-
-```ts
-resourceAdapters: [StateAdapter({
-  state: run.state,
-  fields: [
-    { field: manifest.states.source, access: "read" },
-    { field: manifest.states.copiedText, access: "write" },
-  ],
-})]
-```
-
-`StateAdapter` is exported from `@vimhead.dev/norn` and accepts the public workflow-state interface, without a storage path. `read-write` is also supported. This adapter adds `norn_state_list`, `norn_state_get`, and `norn_state_set`, including when `tools: []` is requested. Discovery lists only selected fields and their schemas/permissions. Each operation checks its grant; setting validates against the declared field schema. Unset reads return `isSet:false`.
-
-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.
+The [shared-state example](../examples/shared-state/README.md) supplies its own resource and permission-selected adapter. The [queue example](../examples/coordinating-multiple-agents/README.md) supplies a different resource and tool contract. Neither adapter is a built-in SDK state facility.
 
 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 |
 |---|---|---|
-| IF a Norn agent needs state access, THEN explicitly select its fields and permissions. ELSE omit the attachment. | A reviewer reads a pinned candidate field. | Automatically expose all manifest fields to every session. |
-| IF combining pages, THEN compare their revisions and restart the read when they differ. ELSE use a single returned page as a fragment only. | Re-read a value changed between pages. | Concatenate pages from different revisions. |
+| IF a Norn agent needs resource access, THEN attach an adapter exposing the required operations. ELSE omit the attachment. | A reviewer receives read-only access to a candidate. | Automatically expose every resource to every session. |
 | IF disposing a binding, THEN release session-local handles only. ELSE retain the resource for later sessions. | Close a subscription. | Delete workflow state when its agent exits. |
 
 The attachment never exposes internal scheduler/checkpoint control state. It is a cooperative tool boundary, not a sandbox against unrestricted filesystem tools or trusted extensions. [Agent loading](agents.md#prompts-tools-and-resource-loading) owns those limitations.
@@ -58,4 +43,4 @@ Reads of live command-output logs may return partial streams. File locks do not
 | IF a callback holds a lock, THEN finish its short storage operation before prompting a model or taking another lock on the same file. ELSE release it first. | Persist a value and return. | Wait for a model turn while holding a file lock. |
 | IF restoring a checkpoint, THEN restore resource data but not lock ownership. ELSE follow the owning external resource's recovery contract. | Built-in locks live under the run's `locks/`, outside `current/`. | Restore an old owner's lock directory as live ownership. |
 
-Sources: [resource contracts](../packages/sdk/src/resources.ts), [resource manager](../packages/cli/src/resources.ts), [adapter contracts](../packages/sdk/src/agent-resource-adapter.ts), [StateAdapter](../packages/sdk/src/state-adapter.ts), [file coordinator](../packages/sdk/src/files.ts).
+Sources: [resource contracts](../packages/sdk/src/resources.ts), [resource manager](../packages/cli/src/resources.ts), [adapter contracts](../packages/sdk/src/agent-resource-adapter.ts), [file coordinator](../packages/sdk/src/files.ts).

package/assets/docs/schemas.md

@@ -1,6 +1,6 @@
 # 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.
+The [Norn SDK](../packages/sdk/src/api.ts) accepts native `typebox` 1.x schemas for workflow args, workflow/scope config, 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