norn-cli 2.9.8 → 3.1.0

package/CLAUDE.md

@@ -0,0 +1,68 @@
+# Norn Extension — Claude Code instructions
+
+## Read these first
+
+1. **[`NOW.md`](NOW.md)** — the tool-agnostic active-work board shared by every agent and by
+   Peter. Whatever sits under **Active now** is the current priority. This board, not any
+   assistant's memory, is the source of truth for what we are working on.
+2. **[`AGENTS.md`](AGENTS.md)** — the full repo instructions (CLI parity requirement, how to
+   run the local CLI, code style, testing). Everything in that file applies here.
+
+## Skills: consult `.github/skills/` — always
+
+This repo keeps its accumulated implementation knowledge in **[`.github/skills/`](.github/skills/)**,
+maintained by every agent that works here. Treat it as required reading, not an optional
+reference.
+
+**Before touching any area of the codebase, check `.github/skills/` for a skill covering it
+and read that skill.** Do this even for changes that look small — the skills exist precisely
+because these areas have non-obvious rules that are easy to break.
+
+Current skills and what they cover:
+
+| Skill | Read it when working on |
+|-------|------------------------|
+| `norn-syntax-highlighting` | TextMate grammars in `syntaxes/`, token scopes, highlighting bugs |
+| `norn-agent-workbench` | `.nornagent` sidecars, agent `run` steps, providers, contracts, record/replay, agent graph |
+| `norn-intellisense-preferences` | Completion providers, IntelliSense behaviour |
+| `norn-value-resolution` | Variables, interpolation, `.nornenv`, value precedence |
+| `add-norn-keyword` | Adding a keyword to the `.norn` language |
+| `add-assertion-operator` | Adding an assertion operator |
+| `add-sequence-step-type` | Adding a new sequence step type |
+| `add-imported-sidecar-language` | Adding a new imported sidecar file type |
+| `norn-cli-integration` | `src/cli.ts` and CLI parity |
+| `norn-debugger-integration` | DAP / debugger work |
+| `norn-response-panel` | The response webview panel |
+| `norn-test-explorer` | VS Code Test Explorer integration |
+| `norn-sequence-tags` | Sequence tags and filtering |
+| `norn-api-coverage` | `.nornapi` coverage features |
+| `norn-mcp-tools` | MCP client and tool wiring |
+| `norn-k8s` | Kubernetes features |
+| `norn-terminal` | Norn Terminal / PTY work |
+| `norn-env-templates` | `.nornenv` templates |
+| `norn-publishing` | Packaging and publishing the extension |
+| `norn-starter-catalog` | Starter templates catalog |
+| `norn-title-cards` | Title cards |
+| `demo-task-helper` | Building demos |
+| `readme-sync` | Keeping README/docs in sync with features |
+
+The table can go stale — list the directory when the work doesn't obviously map to a row.
+
+### Maintaining skills
+
+Per `AGENTS.md`, skills are living documents:
+
+- If a skill is **wrong or outdated**, fix it as part of the change.
+- If a skill is **missing** for an area you just learned, write one in Agent Skills format.
+- After creating or editing any skill, run `npm run validate:skills`.
+
+Capture the lesson that was hard to learn, not a restatement of the code.
+
+## Verification
+
+Never use `npx norn` — that runs the published package, not local changes:
+
+```bash
+npm run compile
+node ./dist/cli.js tests/file.norn --env prelive
+```

package/NOW.md

@@ -25,34 +25,183 @@
 
 ## Active now
 
-_Accepted 2026-07-03. Two workstreams: build the paid direction, and market it._
-
-### 1. 🔨 Contract & Drift — BUILD (anchor)
-Turn Norn's existing `matchesSchema` into the job the market will pay for: **catch
-breaking API changes on the PR.** Do **Stage 1 → Stage 2 first** (cheap, pure reuse);
-Stage 3 (drift-as-PR-verdict) is the sellable milestone; Stage 4 is fenced off until a
-Stage-3 buyer pays.
-→ Plan: [`Docs/contract_drift_build_plan.md`](Docs/contract_drift_build_plan.md) · Evidence: `Docs/market_signals.md` Signal 004
-**Next step:** build a thin Stage 1 slice, then Peter QA-dogfoods it.
-
-### 2. 📣 Marketing & positioning — Voiden playbook (message + distribution together)
-Sharpen the pitch **and** get it into dev-native rooms — one workstream. Channel
-correction after the LinkedIn flop: copy Voiden's **distribution, not their business
-model**. Phased do → prove → gate: sharpen the drift hook → publish migration essays on
-**dev.to / Reddit / Show HN** (does content travel?) → comparison pages + directories →
-launch on the Stage-3 drift demo → community/open-core (earned, last).
-→ Plan: [`Docs/marketing_plan.md`](Docs/marketing_plan.md) · Evidence: `Docs/market_signals.md` Signal 004 · [[norn-reddit-disclosed-selling]] · spine stays locked ([[norn-messaging-locked]])
-**Next step:** Phase 0 — write the one-paragraph "why Norn, now" hook (the field-rename-caught-on-the-PR story) + 3 headline angles.
+_Nothing accepted right now._ The MCP-servers item finished 2026-08-12 — see **Recently done**.
+Slice 5f is the standing follow-on in the backlog below; it now has a spec and is ready for a
+fresh session the moment Peter accepts it here.
 
 ---
 
 ## Backlog / accepted-but-not-started
 
-_(empty)_
+### 🧪 Agent Workbench — Slice 5f: eval fixtures, docs, positioning
+**Postponed 2026-08-11; the MCP work it was waiting on finished 2026-08-12, and it now has a
+spec.** Slice 5 is otherwise complete and reported across every surface (5a, 5c, 5e built; 5b and
+5d closed). 5f is smaller than its name suggests: the **website already documents `judge` well**,
+and a deterministic judge server already exists as a test fixture — so what is left is promoting
+that fixture to a demo anyone can run with **no API key** (one clearly-good case, one clearly-bad
+one), a README section that catches up with the website, and the explanation of what evals are
+for. **No `src/` change.** The spec leads with the constraint that matters: Norn's positioning is
+locked, so "positioning" here means explaining evals *from* the spine, never a new pitch.
+→ **5f spec: [`Docs/to-be-built/agent-workbench-slice-5f.md`](Docs/to-be-built/agent-workbench-slice-5f.md)**
+→ Slice 5 spec: [`Docs/to-be-built/agent-workbench-slice-5.md`](Docs/to-be-built/agent-workbench-slice-5.md)
+→ Built: [`5a`](Docs/to-be-built/agent-workbench-slice-5a.md) ·
+[`5c`](Docs/to-be-built/agent-workbench-slice-5c.md) ·
+[`5e`](Docs/to-be-built/agent-workbench-slice-5e.md)
+
+## Parked
+
+### Contract & Drift + Voiden-playbook marketing
+The previous direction, parked 2026-08-07 — untested, not failed. Stages 1+2 are built and
+shipped in 2.9.8; the QA dogfood and the "why Norn, now" hook never happened. Full
+narrative and how to resume:
+[`Docs/random/parked_contract_drift_and_marketing.md`](Docs/random/parked_contract_drift_and_marketing.md)
 
 ## Recently done
 
-_(empty)_
+- **3.1.0 — MCP authoring parity, and the changelog is gone** (2026-08-13) — **done.**
+  Three fixes that all came out of one painful hour authoring a real server by hand. **`header`
+  now reads like HTTP**: `header Name: value` is accepted alongside the original no-colon form,
+  because the colon form is what a `.norn` request writes and what everyone arrives with —
+  rejecting it silently produced a header *named* `Authorization:` and the only complaint came
+  from `Headers.append` at dial time, three layers from the line at fault. The name is now
+  validated against the RFC 9110 token set at parse time, so an unsendable one is red in the
+  editor. The header name and value carry `.norn`'s own `entity.name.tag.http` /
+  `string.unquoted.http` scopes, so the identical header is the identical colour in both files,
+  and the quoted-string pattern is gone from that rule — it advertised an escape that does not
+  exist, and quotes really do end up inside the token. IntelliSense offers the shared
+  `commonHeaders` list after `header `, inserting the colon form and chaining into the
+  `Bearer {{$env.…}}` value completion.
+  **`run mcp` completions now see sidecar-declared servers.** The precedence rule lived in three
+  copies and the completion copy was left on config-only, so a project that declared every server
+  in its sidecar offered no aliases at all while running perfectly. It is now one shared module,
+  `src/mcpAliasScope.ts`, and the alias carries its origin — which matters because the tools cache
+  is written beside whatever *declared* the server, so tool-name completions and signature help
+  were reading the wrong `.norn-cache` even once an alias resolved. **Config `mcp.servers` stays**:
+  supporting both is one function and one line per caller, so retiring it would have been strictly
+  more work than keeping it.
+  **`CHANGELOG.md` deleted** at Peter's call — the release record is git history plus this board,
+  and a changelog was a third place saying the same thing and the likeliest to drift.
+  Also fixed: `@vscode/test-electron` 2.5.2 could not launch VS Code 1.133 (the binary was renamed
+  from `Electron` to `Code`), which had left the Extension Host suite dark.
+- **Agent Workbench — declared MCP servers** (2026-08-12) — **done, all five items.**
+  Agents can now *do* things. A `.nornagent` sidecar declares the servers it uses beside the
+  models it uses — `mcp <Alias> … end mcp`, stdio and http, credentials as `.nornenv`
+  references — and each agent is granted a whole server with `mcp <Alias>` or named tools with
+  `tools <Alias>.<tool>`. The two stay visibly different statements on purpose: a granted tool
+  executes when the model asks, so the authored grant *is* the permission boundary and dropping
+  four characters must not widen it from one tool to twenty. `session run | agent | call` makes
+  shared server state a decision rather than a surprise; `run` stays the default because five
+  agents testing one website are one testing session, and `session agent` is how an agent asks
+  not to inherit a login it never earned. Config `mcp.servers` keeps working with the sidecar
+  winning, `run mcp` steps reach declared servers so a server is provable with no model and no
+  cost, and a granted server is a real node on the canvas — **declared servers only**, per
+  Peter: the graph draws the program the file describes.
+  Four corrections the build forced on the spec, all recorded in it: grant expansion **cannot**
+  live above the runner (pure replay never runs that preflight, and a derived root definition
+  never reaches sub-agents), so it is an injected hook with a live and a replay implementation;
+  drift between record and replay is only knowable where a live listing happens, so the
+  acceptance criterion demanding both was impossible as written; preflight needed a session
+  boundary of its own, or `session agent` was already broken by the check that proves an agent's
+  tools exist; and the spec's own demo sketch used an input expression the language does not
+  have. Fixed along the way: a templated URL resolving differently mid-run silently reused the
+  old session, and a refused connection reported the SDK's "fetch failed" instead of naming what
+  it dialled. 60 focused tests across five items; 256 pass across every runnable suite, plus
+  type-check, lint, bundles, skill validation, and regression at 198/200 (two live-SQL-Server
+  sequences needing a database).
+  → Spec: [`Docs/to-be-built/agent-workbench-mcp-servers.md`](Docs/to-be-built/agent-workbench-mcp-servers.md)
+  · Demo: [`demos/mcp-ticket-testing`](demos/mcp-ticket-testing)
+- **Agent Workbench Slice 5e — reporting** (2026-08-10) — **done.**
+  A verdict is now visible in the response panel, the canvas, the debugger, and JUnit, derived
+  once through `agentHopPresentation` so the surfaces cannot disagree. The load-bearing move was
+  putting the verdict on `AgentHopResult` rather than the step: a recording persists the trace
+  and never step results, so a step-only verdict vanished the moment a past run was reopened —
+  the round-trip is now a test. Two bugs the build surfaced: a judged hop has `success === true`
+  even when the verdict failed, so the canvas drew a **green node for a failed run** until the
+  verdict was counted explicitly; and the runner emits its `completed` event before the verdict
+  exists, so the deep-cloned event log needed patching or replay playback showed no verdict.
+  Also: judge statements now draw a sequence handoff edge from whatever produced the value they
+  judge, live progress is emitted as `stepType: 'judge'`, and JUnit gets one testcase per
+  statement with `ExpectationsUnmet` and `JudgeError` kept distinct. 13 new focused tests; 159
+  pass across every runnable suite, plus type-check, lint, bundles, regression, skill validation,
+  and a real CLI run producing JUnit.
+  → [`Docs/to-be-built/agent-workbench-slice-5e.md`](Docs/to-be-built/agent-workbench-slice-5e.md)
+- **Agent Workbench Slice 5c — judge execution and the result contract** (2026-08-10) — **done,
+  one deliverable deferred.** A `judge` statement now runs its judge and produces a verdict.
+  The design that carries it: **the model is never asked for an overall result** — it rules on
+  each expectation and quotes evidence, and Norn computes `passed`, checks one ruling per
+  expectation with indexes in range, and verifies each quote occurs in the judged text. A judge
+  is an ordinary agent invocation; everything judge-specific lives in a derived definition, so
+  there is no judge runtime and no `if (isJudge)` in the runner. `builtInContracts` generalises
+  "a contract that lives in code" and rides the existing generation/validation path.
+  A provider or contract failure sets an error and no verdict, so "the judge said no" never
+  reads like "the judge never answered". **A failed judge stops the sequence**, the same as a
+  failed `assert` — it is the concluding check on an orchestration, so later steps must not run
+  on a disproved premise; the run is still recorded and replayable. A malformed reply *shape* is
+  corrected up to `contract_retries` via the opt-in `retryReturnsContract` (off for `run
+  <Agent>`); the verdict itself is never re-rolled. Evidence that cannot be found in the judged
+  text is flagged and still passes — strictness is intended to become per-expectation, not
+  global. **Deferred:** the automatic replay drift check —
+  `expectationsHash` is recorded and diffable, but pure replay never re-reads the `.norn`, so
+  the comparison needs `runLineNumber` plumbing and lands with 5d, which owns the policy.
+  Fixed along the way: judge hops reported false prompt drift on every replay. 18 new focused
+  tests; 141 pass across every runnable suite, plus type-check, lint, bundles, regression, skill
+  validation, and a real CLI run against a deterministic judge server.
+  → [`Docs/to-be-built/agent-workbench-slice-5c.md`](Docs/to-be-built/agent-workbench-slice-5c.md)
+- **Agent Workbench Slice 5a — eval authoring** (2026-08-10) — **done.**
+  `judge <subject> with <Agent> expects "…"` in `.norn` sequences — **one line, like `assert`**,
+  with `expects file <path>` for a list. Built as a `judge … end judge` block first and reworked
+  on Peter's correction: the sequence is the orchestrator, so it stays a flat list of steps
+  rather than nesting a mini-language. Expectations are ordinary Norn strings, file lists resolve
+  at parse time with per-expectation origins, plus eleven `judge-*` diagnostics, grammar,
+  completions, hover, and CLI/JSON step output. Driven by Peter's answer that the first eval is a
+  checklist — all expectations must be met, exceeding them is not a failure. Reuse held:
+  expectation strings go through `agentPromptBlock.ts`'s existing escaping rather than a second
+  stack, one shared module serves runner/diagnostics/completions/hover, and statements validate
+  in the existing agent preflight so a malformed eval cannot spend a model call. A judge step
+  reports as explicitly *not judged* until 5c rather than silently passing. 15 new focused tests;
+  123 pass across every runnable suite, plus type-check, lint, bundles, regression, and skill
+  validation.
+  → [`Docs/to-be-built/agent-workbench-slice-5a.md`](Docs/to-be-built/agent-workbench-slice-5a.md)
+- **Agent Workbench Slice 4** (2026-08-09) — **done and reviewed.**
+  Default-on, secret-safe recordings under `.norn-cache/runs`; fixed 20-run retention;
+  byte-identical offline replay with zero provider/MCP side effects; strict CLI replay with JSON,
+  environment restoration, graph-drift failure, and live `--from`; agent frames/scopes,
+  breakpoints, stepping, and contract-failure navigation in the existing DAP; paused-hop canvas
+  highlighting and validated node-to-invocation navigation. Review: replay is a clean
+  `AgentProviderAdapter` with no runtime special-casing; the debugger is the existing DAP session
+  extended, not a second one; secrets are stable placeholders re-substituted from `.nornenv` at
+  replay time behind a preflight that fails naming the missing variables; and the debugger became
+  the third surface consuming the shared `agentHopPresentation` helper. 55 focused tests pass
+  across all agent suites, plus type-check, lint, and bundle build.
+  → [`Docs/to-be-built/agent-workbench-slice-4.md`](Docs/to-be-built/agent-workbench-slice-4.md)
+- **Agent Workbench Slice 3** (2026-08-09) — **done and reviewed.**
+  Read-only VS Code agent canvas with parser-first static graphs, redacted live/completed trace
+  overlays, deterministic cycle-safe layout, first-class contract states, hover/copy payloads,
+  source navigation, command and CodeLens entry points, and shared response-panel presentation.
+  Recovery resolves successful correction invocations rather than trusting a flag. Review: the
+  shared `agentHopPresentation` helper is consumed by both the canvas and the response panel so
+  they cannot drift; the trace is redacted before anything reads it; CSP is `default-src 'none'`
+  with nonce'd scripts and no external hosts; no graph library was added; the panel never writes.
+  43 focused tests pass across all agent suites, plus type-check, lint, and bundle build.
+  → [`Docs/to-be-built/agent-workbench-slice-3.md`](Docs/to-be-built/agent-workbench-slice-3.md)
+- **Agent Workbench Slice 2** (2026-08-08) — **done and reviewed.**
+  Model-directed agent-as-tool delegation, two-way boundary correction, subtree conversations,
+  configurable spend guards, recursive CLI/JSON/response-panel traces, language tooling, docs,
+  and a deterministic violate → correct → pass demo. Review: sub-agents go through the same tool
+  path as MCP tools, config precedence is agent → provider → global → built-in, parallel tool use
+  is disabled on both adapters, and the runner was extracted to `src/agents/agentRunner.ts` rather
+  than growing `sequenceRunner`. 32 focused tests pass; the language suite needs the VS Code host.
+  `max_tokens` default stays 16000 — a real OpenAI model rejected 32000 and reported a 16384
+  cap, so the generous default was walked back; raise it per-provider where a model allows it.
+  → [`Docs/to-be-built/agent-workbench-slice-2.md`](Docs/to-be-built/agent-workbench-slice-2.md)
+- **Agent Workbench Slice 1** (2026-08-08) — **done and verified running by Peter.**
+  `.nornagent` definitions, linear agent `run` handoffs, OpenAI/local/Anthropic/Google adapters,
+  MCP tools, automatic boundary contracts, live CLI + JSON traces, language tooling, focused
+  tests, and a runnable demo. Reviewed: reuse held (contracts go through `matchesSchema` and the
+  existing Contract View path), provider interface held (Google landed later as a pure new file).
+  → [`Docs/to-be-built/agent-workbench-slice-1.md`](Docs/to-be-built/agent-workbench-slice-1.md)
+- **Website k8s de-promotion** (2026-08-07) — promo surfaces stripped and deployed; docs
+  and functionality untouched. Was Phase 0 of the marketing plan.
 
 ---
-_Last updated: 2026-07-03_
+_Last updated: 2026-08-12_

package/README.md

@@ -27,6 +27,7 @@ That means you can:
 - `.nornenv` files for environments and secrets
 - `.nornapi` files for reusable endpoint definitions
 - `.nornsql` files for database queries and commands
+- `.nornagent` files for contract-checked AI agents and model-directed delegation
 - syntax highlighting, IntelliSense, and diagnostics
 - response inspection, JSON diffing, and click-to-generate assertions
 - tagged and parameterized test execution in VS Code and the CLI
@@ -106,7 +107,14 @@ Every `{{...}}` reference in any Norn file shows its resolved value as a gray in
 
 ## Deterministic MCP Tools
 
-Norn can call MCP tools from sequences without leaving the `.norn` runtime. MCP sessions are deterministic and shared across the full sequence run, so nested sequences reuse the same connection for the same resolved server alias.
+Norn can call MCP tools from sequences without leaving the `.norn` runtime. MCP sessions are deterministic and shared across the full sequence run by default, so nested sequences reuse the same connection for the same resolved server alias.
+
+A server can be declared in two places, and an alias resolves through them in this order:
+
+1. an `mcp <Alias> ... end mcp` block in a `.nornagent` sidecar the file imports — see
+   [Contract-Checked Agent Graphs](#contract-checked-agent-graphs), and prefer this when agents
+   use the server too, because the file then says what it connects to;
+2. `mcp.servers` in the nearest `norn.config.json`.
 
 Create a `norn.config.json` in the root of your project:
 
@@ -149,7 +157,223 @@ Behavior:
 - `run mcp list <alias>` returns the full tool list and drains paginated `nextCursor` responses automatically.
 - `run mcp call <alias> <tool>(...)` supports named arguments or positional arguments bound in tool-schema order, and returns a deterministic result envelope with `content`, `structuredContent`, `isError`, `text`, `server`, and `tool`.
 - Tool `structuredContent` is validated against the MCP tool's advertised `outputSchema` when present.
-- Sessions are closed automatically when the outermost sequence finishes or fails.
+- A run-scoped session is closed automatically when the outermost sequence finishes or fails. A
+  sidecar-declared server can narrow that with `session agent` or `session call`, which close at
+  their own boundary instead.
+- An imported `.norn` helper sequence resolves aliases through **its own** imports, not its
+  caller's — the same rule agent scopes follow.
+
+## Contract-Checked Agent Graphs
+
+Define agents in an imported `.nornagent` sidecar. An agent can grant another
+agent through `agents`; the callee then appears to the calling model as an
+ordinary tool. Its `accepts` schema constrains and validates the generated tool
+input, and its `returns` schema validates the result before it travels back up
+the graph.
+
+A `model` block declares the provider, the provider's model, and where the API key
+comes from. Nothing is implied by convention: `apiKey` points at a `.nornenv`
+variable, so the file says exactly which value it needs and the secret itself never
+leaves the environment.
+
+```nornagent
+model Workbench
+    provider openai          # openai, anthropic, google, or local
+    name gpt-4o
+    apiKey {{$env.OPENAI_API_KEY}}
+    # baseUrl {{$env.OPENAI_BASE_URL}}   # optional; required for local
+end model
+
+agent DomainExpert
+    model Workbench
+    describe "Call for domain questions and include the ticket context."
+    accepts contracts/domain-question.schema.json
+    returns contracts/domain-answer.schema.json
+    system "Answer only the supplied domain question."
+end agent
+
+agent TicketRouter
+    model Workbench
+    agents DomainExpert
+    system "Consult the domain expert when the ticket needs it."
+end agent
+```
+
+### Giving agents hands: declared MCP servers
+
+An agent reaches the outside world through MCP servers, and those are declared in the same
+file, the same way — every input the server needs written down, credentials as `.nornenv`
+references:
+
+```nornagent
+mcp Browser
+    transport stdio
+    command npx playwright-mcp --headless --isolated
+    session agent            # run (default) | agent | call
+end mcp
+
+mcp House
+    transport http
+    url {{$env.HOUSE_MCP_URL}}                          # the MCP endpoint, path included
+    header Authorization: Bearer {{$env.HOUSE_TOKEN}}
+    timeout 60000
+end mcp
+
+agent FrontendTester
+    model Workbench
+    mcp Browser                                    # every tool this server advertises
+    tools House.getFixtureUser, House.resetTenant  # only these, from this one
+    system file prompts/frontend-tester.md
+end agent
+```
+
+- **`transport stdio` spawns the server per run; `transport http` only dials one.** Norn never
+  starts an http server, so it must already be listening — a refused connection fails before
+  any model spend, naming the URL it tried.
+- **`mcp <Alias>` and `tools <Alias>.<tool>` are deliberately different statements.** A granted
+  tool executes when the model asks for it, so the authored grant *is* the permission boundary:
+  dropping four characters must not silently widen access from one tool to twenty.
+- **`header` writes an HTTP header the way you would write it anywhere else.** `header Name:
+  value`, and the value is the rest of the line taken verbatim — so `Bearer {{token}}` needs no
+  quotes, and quotes you add become part of the token. The colon is optional but recommended:
+  it is what the request side of Norn uses, and IntelliSense inserts it for you.
+- **`session` decides what state is shared.** The default, `run`, gives every agent in a
+  sequence one session — deliberate for an orchestration, and a trap when a backend agent
+  inherits a frontend agent's login and passes a test that should have failed. `session agent`
+  is how an agent asks for its own.
+- An alias with no block still resolves through `norn.config.json` `mcp.servers`, and a block
+  in the sidecar wins over a config entry of the same name.
+
+Deterministic `run mcp` steps resolve the same aliases, so a server can be proved reachable
+with no model and no cost:
+
+```norn
+import "./agents.nornagent"
+
+test sequence ServersUp
+    var tools = run mcp list House
+    assert tools.length > 0
+end sequence
+```
+
+The runnable [`demos/mcp-ticket-testing`](./demos/mcp-ticket-testing) example is the whole
+shape end to end: a browser agent, a backend agent narrowed on the same custom server, a
+reporter, and a `judge` over the expected test cases.
+
+A prompt that outgrows its sidecar can live in its own file instead. `describe`
+and `system` both accept `file <path>`, resolved relative to the `.nornagent`
+file just like an import:
+
+```nornagent
+agent TicketRouter
+    model Workbench
+    agents DomainExpert
+    system file prompts/ticket-router.md
+end agent
+```
+
+The file's text is the prompt verbatim — no escaping, so quotes and backslashes
+stay as written — and `{{...}}` references in it resolve exactly as they do
+inline. A missing or empty prompt file is a parse error on the directive line.
+
+Run the graph from an ordinary sequence; the same nested contract and retry
+trace appears in VS Code and the CLI:
+
+```norn
+import "./agents.nornagent"
+
+test sequence RouteTicket
+    var ticket = run readJson "./ticket.json"
+    var verdict = run TicketRouter ticket
+    assert verdict.text exists
+end sequence
+```
+
+Malformed handoffs are returned to the calling model as field-level tool errors
+so it can correct them. The default guardrails are depth 5, 25 total agent
+invocations, and a two-failed-attempt contract cap. Configure them globally,
+per provider, or on an individual agent (most specific wins):
+
+```json
+{
+    "version": 1,
+    "agents": {
+        "max_tokens": 16000,
+        "max_depth": 5,
+        "max_invocations": 25,
+        "contract_retries": 2,
+        "recording": { "enabled": true },
+        "providers": {
+            "local": { "max_tokens": 4096 }
+        }
+    }
+}
+```
+
+`max_tokens` is an output ceiling, not prepaid usage: raising it does not spend
+tokens by itself. Depth, invocation, and retry limits can permit additional
+model calls, so tighten those three when controlling run cost. See the runnable
+[`demos/agent-workbench`](./demos/agent-workbench) example for delegation and a
+visible contract correction.
+
+Every sequence run that reaches an agent is recorded under
+`.norn-cache/runs/` by default, with a rolling cap of 20 files. Recordings hold
+the resolved provider request, response, tool transcript, contracts,
+conversation state, and ordered hop events. Values declared as secrets in
+`.nornenv` are written as stable named placeholders and restored from the
+selected environment when replay starts; a missing value stops replay before a
+provider or tool can run. Set `agents.recording.enabled` to `false` to disable
+automatic recording.
+
+Replay a recording without model calls, MCP calls, or other sequence side
+effects using the local CLI:
+
+```bash
+node ./dist/cli.js replay .norn-cache/runs/<recording>.json
+node ./dist/cli.js replay .norn-cache/runs/<recording>.json --json
+node ./dist/cli.js replay .norn-cache/runs/<recording>.json --from CriteriaComparer
+```
+
+Pure replay reproduces the stored trace and exits non-zero for failed hops or
+contracts, so a deliberately copied recording can be used as a no-key CI
+fixture. `--from` accepts a unique agent name or canonical path such as
+`TicketRouter[1]/CriteriaComparer[1]`; the prefix stays replayed and that hop
+onward runs live against the current graph.
+
+**Norn: Show Agent Graph**, or the CodeLens on any agent block, draws the graph
+for a `.nornagent` file: who calls whom, the `accepts`/`returns` contract on each
+boundary, and how each one turned out. Hover an agent or a boundary for the full
+detail — models, timings, usage, prompts, payloads, contract issues.
+
+The graph's toolbar also lists the project's recorded runs, each labelled with the
+`.norn` file it came from. Pick one to see how it finished, or press **Play run**
+to watch it unfold hop by hop on the canvas. Playback replays the recording's own
+events, so nothing re-executes and no model is called; press **Stop** to jump to
+the end. A run from a file the open one took no part in is drawn from that
+recording alone — the toolbar says which file it came from, and **This file —
+current view** returns you to the open file, ready for its next live run.
+Recording is on by default and keeps the last 20 runs under `.norn-cache/runs/`.
+
+To step a recording in VS Code, use the existing `norn` debugger and add the
+artifact to a launch configuration:
+
+```json
+{
+    "type": "norn",
+    "request": "launch",
+    "name": "Replay RouteTicket",
+    "file": "${workspaceFolder}/route-ticket.norn",
+    "sequence": "RouteTicket",
+    "recording": "${workspaceFolder}/fixtures/route-ticket-run.json",
+    "stopOnEntry": true
+}
+```
+
+Agent calls appear as nested frames with Request, Response, Contracts, and
+Conversation scopes. Normal step controls navigate the recorded hop timeline;
+**Norn Debug: Run to Next Contract Failure** stops on retry violations as well
+as final contract failures. With Agent Graph open, the paused invocation is
+highlighted and selecting a node moves the replay cursor to that invocation.
 
 ## Good Fit For