diff --git a/README.md b/README.md
index c2a5a1f..3df08ba 100644
--- a/README.md
+++ b/README.md
@@ -11,7 +11,7 @@ _Understanding, made observable._
 
 Noēsis is a cognitive runtime for agent workflows. It turns each run into an auditable episode with a causal event chain, governed side effects, and resumable execution.
 
-Each run produces a structured artifact pack (`events.jsonl`, `summary.json`, `state.json`, `manifest.json`) that can be inspected, audited, and verified.
+Each run produces a structured artifact pack (`events.jsonl`, `summary.json`, `state.json`, `manifest.json`) that can be inspected, audited, and verified. Terminal runs also write `final.json`. Paused runs stay unsealed until continuation.
 
 Bring your own graphs, loops, tools, and prompts. Noēsis adds runtime evidence, verification, and governance boundaries without replacing your orchestrator or agent framework.
 
@@ -42,7 +42,7 @@ Noēsis gives you a third option: keep your orchestrator, but run it inside a ru
 
 ## What Noēsis does
 
-- **structured episodes**: every run emits `events.jsonl`, `summary.json`, `state.json`, `final.json`, and `manifest.json`
+- **structured episodes**: every run emits `events.jsonl`, `summary.json`, and `state.json`. Terminal runs also seal `final.json` and `manifest.json`.
 - **governed side effects**: review, audit, veto, or pause actions before they execute
 - **resumable execution**: interrupt, checkpoint, and continue the same run
 - **verification**: capture workspace evidence and assert expected changes
@@ -58,34 +58,15 @@ episode_id = ns.run("Draft a weekly engineering update", intuition=True)
 summary = ns.summary.read(episode_id)
 timeline = list(ns.events.read(episode_id))
 
-ns.set(
-    governance_mode="enforce",
-    governance_pause_on_veto=True,
-    governance_failure_policy="fail_closed",
-    prompt_provenance_enabled=True,
-    prompt_provenance_mode="full",
-)
-
-# Start the run
-episode_id = ns.solve(
-    task="Apply canary rollout config to production",
-    using=lambda: my_agent(),
-    workspace="./repo",
-    verify=(
-        ns.file_exists("canary-rollout.json"),
-        ns.only_modified(["canary-rollout.json"]),
-    ),
-)
-
-# Governance vetoes the risky write →
-# run automatically emits interrupt + checkpoint
-# UI shows: run is paused, waiting on you
+print(summary["metrics"]["success"])
+print(timeline[0]["phase"], timeline[0].get("payload"))
+```
 
 ## How it works
 
 Noēsis models each run as explicit cognition phases:
 
-**Observe -> Interpret -> Plan -> Govern -> Act -> Reflect -> Learn**
+**Observe -> Interpret -> Plan -> Direction -> Governance -> Act -> Reflect -> Learn -> Insight**
 
 Each phase emits typed events with `caused_by` linkage, so the artifact trail preserves how the run moved from observation to action and reflection.
 
@@ -106,24 +87,32 @@ flowchart LR
 
 ## Artifact layout
 
-By default, Noēsis writes artifacts under `.noesis/episodes/`:
+By default, Noēsis writes artifacts under `.noesis/episodes/<episode_id>/`. Episode IDs are `ep_<ULID>`. Directories are flat: there is no per-label nesting. Group related runs with `process=` / `--process` instead of `ns.set(label=...)` (`label` is not a config key).
 
 ```text
 .noesis/
   episodes/
-    ep_.../
+    ep_01JH6Z2V9Q2K6Y6N0QZ7K2QW8C/
       events.jsonl
       summary.json
       state.json
-      final.json
-      manifest.json
+      final.json      # terminal runs only
+      manifest.json   # terminal runs only
       learn.jsonl     # optional
-      prompts.jsonl   # optional
-      snapshots/
+      prompts.jsonl   # optional, prompt provenance
+      snapshots/      # when verify=... is set
         pre.json
         post.json
+      checkpoints/    # paused / interrupted runs
+  processes/
+    index.json
+    <process_id>.json
+  index/
+    episodes.jsonl    # best-effort EpisodeIndex (TTL 30 days)
 ```
 
+Paused runs (for example enforce-mode veto with `governance_pause_on_veto=True`) write a checkpoint and **do not** seal `final.json` / `manifest.json` until continuation finishes.
+
 ## Governed side effects
 
 ```python
@@ -158,9 +147,16 @@ except NoesisVeto as veto:
 
 ## Workspace verification
 
-## Artifact contract
+Pass `verify=` to `ns.run` / `ns.solve` with helpers from `noesis.verification` (also re-exported on `ns`):
 
-Every episode writes a sealed artifact pack:
+```python
+import noesis as ns
+
+verify = (
+    ns.file_exists("canary-rollout.json"),
+    ns.file_contains("canary-rollout.json", "canary: true"),
+    ns.only_modified(["canary-rollout.json"]),
+)
 
 episode_id = ns.solve(
     "Update config",
@@ -170,46 +166,56 @@ episode_id = ns.solve(
 )
 ```
 
+`file_contains` is literal-only in v0.1: passing a compiled `re.Pattern` without `literal=True` raises `ValueError`. The CLI also rejects combining `--verify-no-modifications` with `--verify-only-modified`.
+
+Verification writes `snapshots/pre.json` and `snapshots/post.json` and records the result on the episode summary.
+
 ## Pause, checkpoint, and continue
 
+Do not call `interrupt` / `checkpoint` after a completed run. Terminal runs write `final.json` and reject later lifecycle mutations with `RunSealedError`.
+
+Canonical approval path: pause during the run, then continue the **same** episode ID.
+
 ```python
 import noesis as ns
 
-episode_id = ns.solve(
-    task="Update rollout config",
-    using=lambda: my_agent(),
-    workspace="./repo",
-    verify=(
-        ns.file_exists("canary-rollout.json"),
-        ns.file_contains("canary-rollout.json", "canary: true"),
-        ns.only_modified(["canary-rollout.json"]),
-    ),
+ns.set(
+    governance_mode="enforce",
+    governance_pause_on_veto=True,
 )
-```
-
-Verification produces `snapshots/pre.json` and `snapshots/post.json` and records verification state in the episode artifacts.
 
----
-
-interrupt_id = ns.interrupt(episode_id, reason="awaiting approval")
-checkpoint = ns.checkpoint(episode_id, caused_by=interrupt_id)
+episode_id = ns.solve(
+    task="Danger operation: delete production database",
+    using=my_graph,
+)
 
-ns.resume(episode_id, checkpoint_id=checkpoint["checkpoint_id"])
+checkpoint_event = next(
+    event
+    for event in ns.events.read(episode_id)
+    if event.get("phase") == "runtime" and event.get("event_type") == "run.checkpoint"
+)
+checkpoint_id = checkpoint_event["payload"]["checkpoint_id"]
 
+# After human approval, continue the same run
 episode_id = ns.resume_run(
     episode_id,
-    checkpoint_id=checkpoint["checkpoint_id"],
+    checkpoint_id=checkpoint_id,
     using=my_graph,
 )
+```
 
-episode_id = session.solve(task="...", using=lambda: my_agent())
-restore()
+You can also pause an **unsealed** run yourself:
+
+```python
+interrupt_id = ns.interrupt(episode_id, reason="awaiting approval")
+checkpoint = ns.checkpoint(episode_id, caused_by=interrupt_id)
+ns.resume_run(episode_id, checkpoint_id=checkpoint["checkpoint_id"], using=my_graph)
 ```
 
 Rule of thumb:
 
-- `resume()` emits lifecycle evidence only
-- `resume_run()` emits `run.resume` and continues execution
+- `resume()` emits lifecycle evidence only (`run.resume`)
+- `resume_run()` emits `run.resume` and continues execution on the same run ID
 
 ## Install
 
@@ -228,6 +234,8 @@ Run the demo:
 uv run python examples/demo.py
 ```
 
+The demo sets `runs_dir="./.noesis/episodes/demo"`, so its artifacts live under that custom root rather than the default `.noesis/episodes/` directory.
+
 ## Who it's for
 
 **Builders / platform teams**: wrap LangGraph, CrewAI, or custom graphs with observable cognition and governed execution without rewriting your orchestrator.
@@ -240,16 +248,20 @@ uv run python examples/demo.py
 
 ## Docs and links
 
-- Artifacts guide: `docs/artifacts/state.md`
-- Schema index: `docs/app/reference/schema-index.mdx`
-- CLI reference: `docs/app/reference/cli/page.mdx`
-- Quickstart guide: `docs/app/guides/quickstart/page.mdx`
+- Quickstart: `docs/quickstart.mdx`
+- Artifacts: `docs/explanation/artifacts.mdx`
+- Python API: `docs/reference/python-api.mdx`
+- CLI reference: `docs/reference/cli.mdx`
+- Events schema: `docs/reference/events.mdx`
+- Human-in-the-loop: `docs/guides/human-in-the-loop.mdx`
 - Examples: `examples/README.md`
 
+Published site: https://docs.noesis.systems
+
 ## Status
 
 - Package: `noesis` v1.0.0
-- Schema pack: summary/state/events/kpi v1.0.0
+- Schema pack: summary 1.3.0, events 1.3.0, final 2.0.0
 - Python: >= 3.11
 - CI: contracts, schema guard, and release preparation run in GitHub Actions
 
diff --git a/docs/docs.json b/docs/docs.json
index 955c7ba..e4ca4ad 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -48,10 +48,13 @@
           {
             "group": "Tutorials",
             "pages": [
+              "tutorials/first-episode",
               "tutorials/hello-episode",
+              "tutorials/first-policy",
               "tutorials/langgraph-episode",
               "tutorials/governed-side-effects",
-              "tutorials/trace-based-evals"
+              "tutorials/trace-based-evals",
+              "tutorials/incident-triage"
             ]
           },
           {
diff --git a/docs/explanation/artifacts.mdx b/docs/explanation/artifacts.mdx
index e27739f..e4dd5ce 100644
--- a/docs/explanation/artifacts.mdx
+++ b/docs/explanation/artifacts.mdx
@@ -8,21 +8,30 @@ Every Noēsis episode produces a set of structured artifacts that capture the co
 ## Artifact structure
 
 ```
-.noesis/episodes/
-  <label>/                     # e.g., "demo", "production"
-    <episode_id>/              # e.g., "ep_20251108_120000_abc123_def4_s0"
+.noesis/
+  episodes/
+    ep_01JH6Z2V9Q2K6Y6N0QZ7K2QW8C/   # episode id (ep_<ULID>)
       events.jsonl             # cognitive event timeline with lineage
       summary.json             # metrics and KPIs (insight.metrics)
       state.json               # plan, beliefs, memory, outcomes
-      manifest.json            # SHA-256 catalog + optional HMAC
+      final.json               # terminal seal marker (absent while paused)
+      manifest.json            # SHA-256 catalog (terminal runs)
       learn.jsonl              # learning signals (optional)
       prompts.jsonl            # prompt provenance (opt-in, ADR-005)
+      checkpoints/             # pause / interrupt pointers
+  processes/                   # process registry (grouping, not a directory nest)
+    index.json
+    <process_id>.json
+  index/                       # best-effort EpisodeIndex (not _episodes/)
+    episodes.jsonl
 ```
 
 <Info>
-**Episode IDs** use ULID format (monotonic, sortable, 48-bit timestamp + 80-bit entropy). **Directive and governance IDs** use deterministic UUIDv5 for reproducible lineage tracking.
+**Episode IDs** use `ep_<ULID>` (monotonic, sortable, 48-bit timestamp + 80-bit entropy). **Directive and governance IDs** use deterministic UUIDv5 for reproducible lineage tracking. Episode directories are **flat** under `episodes/`; there is no per-label subdirectory.
 </Info>
 
+Paused runs (interrupt / `governance_pause_on_veto=True`) keep `events.jsonl` and `state.json` append-only and **do not** write `final.json` or `manifest.json` until the run becomes terminal.
+
 ## summary.json
 
 The summary captures episode outcomes, metrics, and cross-references.
@@ -32,7 +41,7 @@ The summary captures episode outcomes, metrics, and cross-references.
 ```json
 {
   "schema_version": "1.3.0",
-  "episode_id": "ep_2024_abc123_s0",
+  "episode_id": "ep_01JH6Z2V9Q2K6Y6N0QZ7K2QW8C",
   "task": "Draft release notes for v1.2.0",
   "seed": 42,
   "started_at": "2024-01-15T10:30:00Z",
@@ -119,7 +128,7 @@ The state captures the cognitive context at the end of the episode.
   "version": "1.0",
   "state_schema_version": "1.0.0",
   "episode": {
-    "id": "ep_2024_abc123_s0",
+    "id": "ep_01JH6Z2V9Q2K6Y6N0QZ7K2QW8C",
     "seed": 0,
     "adapter": "baseline",
     "started_at": "2024-01-15T10:30:00Z",
@@ -343,7 +352,7 @@ The manifest provides integrity verification for all artifacts with SHA-256 hash
 ```json
 {
   "schema_version": "manifest/1.0",
-  "episode_id": "ep_2024_abc123_s0",
+  "episode_id": "ep_01JH6Z2V9Q2K6Y6N0QZ7K2QW8C",
   "created_at": "2024-01-15T10:30:05Z",
   "files": [
     {"name": "summary.json", "sha256": "sha256:abc123...", "size_bytes": 1234, "kind": "summary"},
@@ -439,25 +448,32 @@ if learn_path.exists():
 
 ## prompts.jsonl (opt-in)
 
-When prompt provenance is enabled (ADR-005, experimental), all prompts are recorded for debugging and auditing.
+When prompt provenance is enabled (ADR-005, experimental), prompts are recorded under `.noesis/episodes/<episode_id>/prompts.jsonl`. See [Prompt provenance](/explanation/prompt-provenance) for field-level mode behavior.
 
-### Schema
+### Schema (`prompt@1.1.0`)
 
 ```json
 {
-  "prompt_id": "pmt_abc123",
-  "timestamp": "2024-01-15T10:30:01Z",
-  "model": "gpt-4",
-  "template": "Generate release notes for:\n{changelog}",
-  "variables": {"changelog": "..."},
-  "response": "## Release Notes...",
-  "tokens": {"input": 150, "output": 200},
-  "latency_ms": 1250
+  "$schema_name": "prompt",
+  "$schema_version": "1.1.0",
+  "episode_id": "ep_01JH6Z2V9Q2K6Y6N0QZ7K2QW8C",
+  "phase": "plan",
+  "agent_id": "direction.planner",
+  "role": "system",
+  "template_id": "planner.v2",
+  "template": "Plan for: {{goal}}",
+  "rendered": "Plan for: ship the release",
+  "variables": {"goal": "ship the release"},
+  "fingerprint": "sha256:...",
+  "timestamp": "2025-11-21T12:34:56.789Z",
+  "model": "gpt-4.1",
+  "mode": "full",
+  "tags": {"env": "production"}
 }
 ```
 
 <Warning>
-**Experimental feature (ADR-005)**: Enable prompt logging carefully—prompts may contain sensitive data. Use `ns.set(log_prompts=True)` only when needed for debugging or compliance.
+**Experimental feature (ADR-005)**: Enable prompt logging carefully—prompts may contain sensitive data. Use `ns.set(prompt_provenance_enabled=True, prompt_provenance_mode="hash_only")`. There is no `log_prompts` config key.
 </Warning>
 
 ### Use cases
@@ -471,39 +487,46 @@ When prompt provenance is enabled (ADR-005, experimental), all prompts are recor
 
 ### Runs directory
 
+Default `runs_dir` is `.noesis/episodes`. Path resolution (`noesis/runtime/paths.py`):
+
+| `runs_dir` value | Episodes written to |
+| --- | --- |
+| `.noesis/episodes` (parent is `.noesis`) | that directory |
+| `.noesis` | `.noesis/episodes` |
+| any other path | `{runs_dir}/.noesis/episodes` (unless `{runs_dir}/episodes` already exists) |
+
 ```python
 import noesis as ns
 
-# Set custom runs directory
-ns.set(runs_dir="./my-runs")
-
-# Or via environment
-# NOESIS_RUNS_DIR=./my-runs
+ns.set(runs_dir=".noesis/episodes")
+# NOESIS_RUNS_DIR=.noesis/episodes
 ```
 
-### Labels
+Pitfall: `NOESIS_RUNS_DIR=/srv/noesis/episodes` does **not** treat that path as the episodes root, because the parent directory is not named `.noesis`. Prefer `/srv/noesis/.noesis/episodes`.
+
+### Process grouping (not labels)
 
-Organize episodes with labels:
+`ns.set(label=...)` is not a config key and raises `ValueError: unknown config keys`. Group related runs with `process=`:
 
 ```python
 import noesis as ns
 
-ns.set(label="production")
-# Artifacts go to .noesis/episodes/production/ep_.../
-
-ns.set(label="staging")
-# Artifacts go to .noesis/episodes/staging/ep_.../
+episode_id = ns.run("Apply canary", process="rollout")
+# CLI: noesis run "Apply canary" --process rollout
+# Inspect: noesis processes && noesis runs --process rollout
 ```
 
+Process identity is `sha256("{workspace}|{name}")[:12]` when a name is provided (`noesis.domain.process.derive_process_identity`). Registry files live under `.noesis/processes/`. Episode bundles stay flat: `.noesis/episodes/ep_<ULID>/`.
+
 ### Retention
 
-Control artifact retention:
+The runtime appends a best-effort index under `.noesis/index/` with `ttl_days=30`. `EpisodeIndex.vacuum()` rewrites `episodes.jsonl` to drop **expired index rows**; it does not delete episode directories.
 
 ```python
 from noesis.episode import EpisodeIndex
 
-store = EpisodeIndex("./.noesis/episodes/_episodes", ttl_days=14)
-store.vacuum()  # Remove episodes older than 14 days
+store = EpisodeIndex(".noesis/index", ttl_days=30)
+removed = store.vacuum()  # count of expired index records removed
 ```
 
 ## Best practices
diff --git a/docs/explanation/core-concepts.mdx b/docs/explanation/core-concepts.mdx
index 87b40e9..4deb449 100644
--- a/docs/explanation/core-concepts.mdx
+++ b/docs/explanation/core-concepts.mdx
@@ -13,44 +13,37 @@ An **episode** is the fundamental unit of execution in Noēsis. Every time you r
 import noesis as ns
 
 episode_id = ns.run("Draft release notes")
-# episode_id = "ep_2024_abc123_s0"
+# episode_id = "ep_01JH6Z2V9Q2K6Y6N0QZ7K2QW8C"
 ```
 
 ### Episode lifecycle
 
-Episodes progress through a defined lifecycle:
+A run either **seals** or **pauses**:
 
 ```
-queued → running → completed | errored | vetoed
+running → sealed (final.json + manifest.json)
+        → paused (checkpoint, unsealed until resume_run)
 ```
 
-| Status | Meaning |
+| Outcome | Meaning |
 | --- | --- |
-| `queued` | Episode created, waiting to start |
-| `running` | Cognitive loop in progress |
-| `completed` | All phases finished successfully |
-| `errored` | An exception occurred during execution |
-| `vetoed` | A policy blocked execution |
+| Sealed terminal | `final.json` exists. Lifecycle APIs raise `RunSealedError`. |
+| Paused / interrupted | Checkpoint written; no `final.json` yet. Continue with `ns.resume_run(...)`. |
+| Enforce veto (default) | Side effect is blocked and the run terminates (`governance_pause_on_veto=False`). |
+| Enforce veto (pause) | Side effect is blocked, then `run.interrupt` + `run.checkpoint` (`governance_pause_on_veto=True`). |
 
 ### Episode IDs
 
-Episode IDs follow the format `ep_<timestamp>_<hash>_s<seed>`:
+Episode IDs follow the format `ep_<ULID>` (26 Crockford base32 characters after the prefix). The ULID encodes a millisecond timestamp plus entropy so IDs sort chronologically.
 
-- `ep_` prefix identifies it as an episode
-- `<timestamp>` provides chronological ordering
-- `<hash>` ensures uniqueness
-- `s<seed>` enables reproducible runs with the same seed
+Reproducibility uses the **per-call** `seed=` argument. `seed` is not a `ns.set()` config key.
 
 ```python
 import noesis as ns
 
-# Reproducible runs with the same seed
-ns.set(seed=42)
-ep1 = ns.run("task")
-
-ns.set(seed=42)
-ep2 = ns.run("task")
-# ep1 and ep2 will have matching behavior
+ep1 = ns.run("task", seed=42)
+ep2 = ns.run("task", seed=42)
+# Matching seed + frozen inputs → matching behavior (external tools/LLMs may still vary)
 ```
 
 ## The cognitive loop
@@ -146,13 +139,13 @@ Every episode produces structured **artifacts** that capture the full cognitive
 
 ```
 .noesis/episodes/
-  demo/                    # label
-    ep_2024_abc123_s0/     # episode
-      summary.json         # metrics and outcomes
-      state.json           # cognitive state
-      events.jsonl         # timeline
-      manifest.json        # integrity checksums
-      learn.jsonl          # learning signals (optional)
+  ep_01JH6Z2V9Q2K6Y6N0QZ7K2QW8C/
+    summary.json         # metrics and outcomes
+    state.json           # cognitive state
+    events.jsonl         # timeline
+    final.json           # terminal seal
+    manifest.json        # integrity checksums
+    learn.jsonl          # learning signals (optional)
 ```
 
 ### summary.json
@@ -162,7 +155,7 @@ The summary captures episode outcomes, flags, metrics, and insight:
 ```json
 {
   "schema_version": "1.3.0",
-  "episode_id": "ep_2024_abc123_s0",
+  "episode_id": "ep_01JH6Z2V9Q2K6Y6N0QZ7K2QW8C",
   "task": "Draft release notes",
   "seed": 42,
   "started_at": "2024-01-15T10:30:00Z",
@@ -213,7 +206,7 @@ The state captures the cognitive context:
 {
   "version": "1.0",
   "episode": {
-    "id": "ep_2024_abc123_s0",
+    "id": "ep_01JH6Z2V9Q2K6Y6N0QZ7K2QW8C",
     "adapter": "baseline"
   },
   "goal": {
@@ -252,7 +245,7 @@ The manifest provides integrity verification:
 ```json
 {
   "schema_version": "manifest/1.0",
-  "episode_id": "ep_2024_abc123_s0",
+  "episode_id": "ep_01JH6Z2V9Q2K6Y6N0QZ7K2QW8C",
   "created_at": "2024-01-15T10:30:05Z",
   "files": [
     {"name": "summary.json", "sha256": "sha256:abc123...", "size_bytes": 1234, "kind": "summary"},
@@ -314,10 +307,12 @@ Noēsis is configured through multiple sources:
 
 Key configuration options:
 
-- `runs_dir`: Where artifacts are stored
+- `runs_dir`: Where artifacts are stored (default `.noesis/episodes`)
 - `planner_mode`: `meta` (full governance) or `minimal`
-- `seed`: For reproducible episodes
-- `label`: Subdirectory name for organizing runs
+- `governance_mode` / `governance_pause_on_veto`: pre-act audit and pause-on-veto
+- Per-call `seed=`, `tags=`, `process=`, `verify=` on `ns.run` / `ns.solve` (not `ns.set()` keys)
+
+There is no `label` config key. Group runs with `process="rollout"` / `--process rollout`. Process identity is `sha256(workspace|name)[:12]` and lives under `.noesis/processes/`, not as a nested episode folder.
 
 ## Mental model
 
diff --git a/docs/explanation/prompt-provenance.mdx b/docs/explanation/prompt-provenance.mdx
index 44b5ed5..7e39688 100644
--- a/docs/explanation/prompt-provenance.mdx
+++ b/docs/explanation/prompt-provenance.mdx
@@ -10,7 +10,7 @@ Prompt provenance captures how prompts were constructed and used during an episo
 | Property | Value |
 | --- | --- |
 | File | `prompts.jsonl` |
-| Location | `.noesis/episodes/<label>/<episode_id>/prompts.jsonl` |
+| Location | `.noesis/episodes/<episode_id>/prompts.jsonl` |
 | Schema | `$schema_name: "prompt"`, `$schema_version: "1.1.0"` |
 | Kind | `attachment` in `manifest.json` |
 | Opt-in | `prompt_provenance_enabled` (bool) |
diff --git a/docs/guides/configure-shared-storage.mdx b/docs/guides/configure-shared-storage.mdx
index 3e4a88c..a441929 100644
--- a/docs/guides/configure-shared-storage.mdx
+++ b/docs/guides/configure-shared-storage.mdx
@@ -24,14 +24,15 @@ ls /srv/noesis/episodes
 # (empty or existing runs)
 ```
 
-Configure your app/runtime to use it as the base runs directory, e.g.:
+Configure your app/runtime to use a path whose parent is `.noesis` so the resolver treats it as the episodes root:
 
 ```bash
-# pseudo-config
-NOESIS_RUNS_DIR=/srv/noesis/episodes
+NOESIS_RUNS_DIR=/srv/noesis/.noesis/episodes
 ```
 
-Result: `/srv/noesis/episodes/<service>/<episode-id>/` is shared across the team.
+Result: `/srv/noesis/.noesis/episodes/<episode-id>/` is shared across the team. There is no per-service subdirectory; group runs with `--process` / `process=`.
+
+Pitfall: `NOESIS_RUNS_DIR=/srv/noesis/episodes` (parent not named `.noesis`) resolves to `/srv/noesis/episodes/.noesis/episodes/`.
 
 ## B) Shared dev: local + S3 (or any object store)
 
@@ -39,13 +40,13 @@ Don’t write directly to S3; sync a local directory.
 
 ```bash
 # App writes episodes locally
-NOESIS_RUNS_DIR=/var/noesis/episodes
+NOESIS_RUNS_DIR=/var/noesis/.noesis/episodes
 
 # Periodic sync job (cron/CI)
-aws s3 sync /var/noesis/episodes s3://my-bucket/noesis-runs --delete
+aws s3 sync /var/noesis/.noesis s3://my-bucket/noesis-root --delete
 
 # Optionally pull shared episodes down
-aws s3 sync s3://my-bucket/noesis-runs /var/noesis/episodes
+aws s3 sync s3://my-bucket/noesis-root /var/noesis/.noesis
 ```
 
 Pattern: local path for fast replay/debugging, S3 as central archive.
@@ -53,15 +54,15 @@ Pattern: local path for fast replay/debugging, S3 as central archive.
 ## C) Docker: bind-mount the runs directory
 
 ```bash
-mkdir -p /srv/noesis/episodes
+mkdir -p /srv/noesis/.noesis/episodes
 
 docker run \
-  -v /srv/noesis/episodes:/app/.noesis/episodes \
+  -v /srv/noesis/.noesis:/app/.noesis \
   -e NOESIS_RUNS_DIR=/app/.noesis/episodes \
   my-noesis-service:latest
 ```
 
-Inside the container, Noēsis writes to `/app/.noesis/episodes/...`; on the host, you see `/srv/noesis/episodes/...`.
+Inside the container, Noēsis writes to `/app/.noesis/episodes/<episode-id>/`; on the host, you see `/srv/noesis/.noesis/episodes/<episode-id>/`. Mount the `.noesis` root so `processes/` and `index/` stay with the episodes.
 
 ## D) Kubernetes: PersistentVolumeClaim
 
@@ -88,17 +89,17 @@ spec:
           image: my-noesis-service:latest
           env:
             - name: NOESIS_RUNS_DIR
-              value: /var/noesis/episodes
+              value: /var/noesis/.noesis/episodes
           volumeMounts:
             - name: noesis-runs
-              mountPath: /var/noesis/episodes
+              mountPath: /var/noesis/.noesis
       volumes:
         - name: noesis-runs
           persistentVolumeClaim:
             claimName: noesis-runs-pvc
 ```
 
-Each pod writes episodes under `/var/noesis/episodes`, backed by the shared PVC.
+Each pod writes episodes under `/var/noesis/.noesis/episodes/<episode-id>/`, backed by the shared PVC.
 
 ---
 
diff --git a/docs/guides/human-in-the-loop.mdx b/docs/guides/human-in-the-loop.mdx
index 31a5bf4..4b07b8c 100644
--- a/docs/guides/human-in-the-loop.mdx
+++ b/docs/guides/human-in-the-loop.mdx
@@ -16,49 +16,69 @@ Add human approval when:
 
 ## Basic approval pattern
 
-The recommended pattern is pause -> checkpoint -> approve -> resume (same run):
+Pause **during** the run, then continue the same episode ID. Do not call `ns.interrupt(...)` after a completed `ns.solve(...)` / `ns.run(...)`: terminal runs write `final.json` and reject lifecycle mutations with `RunSealedError`. Starting a follow-up `ns.run(...)` after approval is a **new** episode, not a continuation.
+
+Canonical path: enforce-mode pause-on-veto.
 
 ```python
 import noesis as ns
+from pathlib import Path
+from noesis.io import paths
+
+
+def latest_checkpoint_id(episode_id: str) -> str | None:
+    for event in ns.events.read(episode_id):
+        if event.get("phase") == "runtime" and event.get("event_type") == "run.checkpoint":
+            checkpoint_id = (event.get("payload") or {}).get("checkpoint_id")
+            if isinstance(checkpoint_id, str) and checkpoint_id:
+                return checkpoint_id
+    return None
+
+
+def is_sealed(episode_id: str) -> bool:
+    return (Path(paths(episode_id)["dir"]) / "final.json").exists()
 
 
 def require_approval(episode_id: str, action: str) -> bool:
-    """
-    In production, replace with:
-    - Slack interactive message
-    - ServiceNow approval workflow
-    - Custom approval UI
-    """
-    print(f"\n⚠️  Approval required for episode {episode_id}")
+    """Replace with Slack, ServiceNow, or your approval UI."""
+    print(f"\nApproval required for episode {episode_id}")
     print(f"   Action: {action}")
-    response = input("   Approve? (y/n): ")
-    return response.lower() == "y"
+    return input("   Approve? (y/n): ").lower() == "y"
 
 
 def run_with_approval(task: str, using):
-    # Start run
+    ns.set(
+        governance_mode="enforce",
+        governance_pause_on_veto=True,
+    )
     episode_id = ns.solve(task, using=using, intuition=True)
 
-    # Pause and checkpoint before high-risk continuation
-    interrupt_id = ns.interrupt(episode_id, reason="High-risk action requires approval")
-    checkpoint = ns.checkpoint(episode_id, caused_by=interrupt_id)
+    if is_sealed(episode_id):
+        return episode_id  # no veto / no pause
+
+    checkpoint_id = latest_checkpoint_id(episode_id)
+    if checkpoint_id is None:
+        return episode_id
 
     if not require_approval(episode_id, task):
-        print("❌ Action rejected by human reviewer")
+        print("Action rejected by human reviewer")
         return None
 
-    # Continue same run ID from checkpoint (no rerun)
     return ns.resume_run(
         episode_id,
-        checkpoint_id=checkpoint["checkpoint_id"],
+        checkpoint_id=checkpoint_id,
         using=using,
     )
 ```
 
 <Tip>
-Prefer `resume_run(...)` over rerunning from scratch after approval. It preserves a continuous, append-only run history.
+Prefer `resume_run(...)` over rerunning from scratch after approval. It preserves a continuous, append-only run history. `resume()` emits `run.resume` evidence only and does not continue execution.
 </Tip>
 
+<Warning>
+Paused runs stay unsealed: `final.json` and `manifest.json` are absent until continuation finishes. Do not hand-edit `events.jsonl`, `state.json`, or checkpoint files while waiting on approval (`CheckpointConsistencyError` on resume).
+</Warning>
+
 ## Policy-driven approval
 
 Create a policy that flags operations for approval:
@@ -189,28 +209,32 @@ class SlackApproval:
         return approved
 
 
-# Usage
+# Usage — reuse latest_checkpoint_id from the basic pattern above
 slack = SlackApproval(channel="#approvals")
 
-def run_with_slack_approval(task: str):
-    episode_id = ns.run(task, intuition=ApprovalPolicy())
-    
-    # Check if approval needed
-    events = list(ns.events.read(episode_id))
-    approval_event = next(
-        (e for e in events if e.get("payload", {}).get("requires_approval")),
-        None,
+
+def run_with_slack_approval(task: str, using):
+    ns.set(governance_mode="enforce", governance_pause_on_veto=True)
+    episode_id = ns.solve(task, using=using, intuition=True)
+
+    checkpoint_id = latest_checkpoint_id(episode_id)
+    if checkpoint_id is None:
+        return {"status": "completed", "episode_id": episode_id}
+
+    slack.request_approval(
+        episode_id,
+        task,
+        {"reason": "governance veto", "checkpoint_id": checkpoint_id},
     )
-    
-    if approval_event:
-        slack.request_approval(
-            episode_id,
-            task,
-            {"reason": approval_event["payload"].get("risk_reason")},
-        )
-        return {"status": "pending_approval", "episode_id": episode_id}
-    
-    return {"status": "completed", "episode_id": episode_id}
+    return {
+        "status": "pending_approval",
+        "episode_id": episode_id,
+        "checkpoint_id": checkpoint_id,
+    }
+
+
+def on_slack_approved(episode_id: str, checkpoint_id: str, using):
+    return ns.resume_run(episode_id, checkpoint_id=checkpoint_id, using=using)
 ```
 
 ## Async approval workflow
@@ -292,126 +316,102 @@ class ApprovalQueue:
 queue = ApprovalQueue(timeout_seconds=300)
 
 
-async def run_async_approval(task: str):
-    episode_id = ns.run(task, intuition=ApprovalPolicy())
-    
-    events = list(ns.events.read(episode_id))
-    if any(e.get("payload", {}).get("requires_approval") for e in events):
-        request = await queue.request_approval(episode_id, task, {})
-        
-        if request.status == ApprovalStatus.APPROVED:
-            # Continue with approved action
-            return ns.run(f"{task} [APPROVED by {request.approver}]", intuition=True)
-        elif request.status == ApprovalStatus.EXPIRED:
-            print("Approval timed out")
-            return None
-        else:
-            print(f"Rejected by {request.approver}")
-            return None
-    
-    return episode_id
+async def run_async_approval(task: str, using):
+    ns.set(governance_mode="enforce", governance_pause_on_veto=True)
+    episode_id = ns.solve(task, using=using, intuition=True)
+    checkpoint_id = latest_checkpoint_id(episode_id)
+    if checkpoint_id is None:
+        return episode_id
+
+    request = await queue.request_approval(episode_id, task, {"checkpoint_id": checkpoint_id})
+
+    if request.status == ApprovalStatus.APPROVED:
+        return ns.resume_run(
+            episode_id,
+            checkpoint_id=checkpoint_id,
+            using=using,
+        )
+    if request.status == ApprovalStatus.EXPIRED:
+        print("Approval timed out")
+        return None
+    print(f"Rejected by {request.approver}")
+    return None
 ```
 
 ## Recording approval in events
 
-The approval decision should be captured in the event timeline:
-
-```python
-import noesis as ns
+Keep the decision on the **same** run. `resume_run` appends `run.resume` and continues execution. A follow-up `ns.run(...)` is a different episode and breaks the causal chain.
 
-
-def record_approval(episode_id: str, approved: bool, approver: str):
-    """Record approval decision in a new episode that references the original."""
-    
-    summary = ns.summary.read(episode_id)
-    original_task = summary.get("task", "")
-    
-    # Create a linked episode with the decision
-    approval_episode = ns.run(
-        f"Human review of: {original_task}",
-        intuition=False,
-        tags={
-            "type": "approval",
-            "original_episode": episode_id,
-            "approved": approved,
-            "approver": approver,
-        },
-    )
-    
-    return approval_episode
-```
+If you need an explicit audit note before continuation, emit it through your approval adapter or inspect the existing `run.interrupt` / `run.checkpoint` / `run.resume` events rather than opening a new episode.
 
 ## UI for approvals
 
-Build a simple approval UI with Gradio:
+Build a simple approval UI with Gradio. List **unsealed** runs that already have a checkpoint, then call `resume_run` (do not start a new episode):
 
 ```python
 import gradio as gr
 import noesis as ns
+from pathlib import Path
+from noesis.io import list_runs, paths
 
 
 def get_pending_approvals():
-    """Get episodes awaiting approval."""
-    episodes = ns.list_runs(limit=50)
     pending = []
-    
-    for ep in episodes:
-        events = list(ns.events.read(ep["episode_id"]))
-        if any(e.get("payload", {}).get("requires_approval") for e in events):
-            summary = ns.summary.read(ep["episode_id"])
-            if not summary.get("tags", {}).get("approved"):
-                pending.append({
-                    "episode_id": ep["episode_id"],
-                    "task": summary.get("task", ""),
-                    "timestamp": ep["timestamp"],
-                })
-    
+    for ep in list_runs(limit=50):
+        episode_id = ep["episode_id"]
+        if (Path(paths(episode_id)["dir"]) / "final.json").exists():
+            continue
+        checkpoint_id = latest_checkpoint_id(episode_id)
+        if checkpoint_id is None:
+            continue
+        pending.append({
+            "episode_id": episode_id,
+            "task": ep.get("task", ""),
+            "started_at": ep.get("started_at"),
+            "checkpoint_id": checkpoint_id,
+        })
     return pending
 
 
-def approve_episode(episode_id: str, approver: str):
-    """Approve an episode."""
-    ns.run(
-        f"[APPROVED] {ns.summary.read(episode_id).get('task', '')}",
-        tags={"approved": True, "approver": approver, "original": episode_id},
-    )
-    return f"✅ Approved by {approver}"
+def approve_episode(episode_id: str, using):
+    checkpoint_id = latest_checkpoint_id(episode_id)
+    if checkpoint_id is None:
+        return "No checkpoint on this episode (already sealed or not paused)"
+    ns.resume_run(episode_id, checkpoint_id=checkpoint_id, using=using)
+    return f"Resumed {episode_id}"
 
 
-def reject_episode(episode_id: str, approver: str, reason: str):
-    """Reject an episode."""
-    ns.run(
-        f"[REJECTED] {ns.summary.read(episode_id).get('task', '')}",
-        tags={"rejected": True, "approver": approver, "reason": reason, "original": episode_id},
+def reject_episode(episode_id: str, reason: str):
+    return (
+        f"Left {episode_id} paused. Rejection reason: {reason}. "
+        "Do not call resume_run; the run stays unsealed until you continue or abandon it."
     )
-    return f"❌ Rejected by {approver}: {reason}"
 
 
-# Build Gradio interface
 with gr.Blocks(title="Approval Queue") as app:
-    gr.Markdown("# 🔐 Approval Queue")
-    
-    with gr.Row():
-        refresh_btn = gr.Button("Refresh")
-        pending_list = gr.Dataframe(headers=["Episode ID", "Task", "Timestamp"])
-    
-    with gr.Row():
-        episode_input = gr.Textbox(label="Episode ID")
-        approver_input = gr.Textbox(label="Your name")
-        reason_input = gr.Textbox(label="Rejection reason (if rejecting)")
-    
-    with gr.Row():
-        approve_btn = gr.Button("✅ Approve", variant="primary")
-        reject_btn = gr.Button("❌ Reject", variant="stop")
-    
+    gr.Markdown("# Approval Queue")
+    using_input = gr.Textbox(label="Adapter import path (required for non-minimal runs)")
+    refresh_btn = gr.Button("Refresh")
+    pending_list = gr.Dataframe(headers=["Episode ID", "Task", "Started at", "Checkpoint"])
+    episode_input = gr.Textbox(label="Episode ID")
+    reason_input = gr.Textbox(label="Rejection reason (if rejecting)")
+    approve_btn = gr.Button("Approve", variant="primary")
+    reject_btn = gr.Button("Reject", variant="stop")
     result = gr.Textbox(label="Result")
-    
+
     refresh_btn.click(
-        lambda: [[p["episode_id"], p["task"], p["timestamp"]] for p in get_pending_approvals()],
+        lambda: [
+            [p["episode_id"], p["task"], p["started_at"], p["checkpoint_id"]]
+            for p in get_pending_approvals()
+        ],
         outputs=pending_list,
     )
-    approve_btn.click(approve_episode, inputs=[episode_input, approver_input], outputs=result)
-    reject_btn.click(reject_episode, inputs=[episode_input, approver_input, reason_input], outputs=result)
+    approve_btn.click(
+        lambda episode_id, using: approve_episode(episode_id, using),
+        inputs=[episode_input, using_input],
+        outputs=result,
+    )
+    reject_btn.click(reject_episode, inputs=[episode_input, reason_input], outputs=result)
 
 
 if __name__ == "__main__":
diff --git a/docs/index.mdx b/docs/index.mdx
index 32ea5be..67a98d4 100644
--- a/docs/index.mdx
+++ b/docs/index.mdx
@@ -85,19 +85,21 @@ print(summary["metrics"]["success"])
 print(timeline[0]["phase"], timeline[0].get("payload"))
 ```
 
-Every run produces a clean artifact structure:
+Every run produces a clean artifact structure. Directories are **flat** (`ep_<ULID>/` under `.noesis/episodes/`). Group related runs with `process=` / `--process`; `ns.set(label=...)` is not a config key.
 
 ```
 .noesis/episodes/
-  demo/                # label (configurable)
-    ep_.../            # episode id
-      summary.json     # metrics and outcomes
-      state.json       # current plan and episode state
-      events.jsonl     # timeline with causal IDs
-      manifest.json    # SHA-256 + size ledger for tamper evidence
-      learn.jsonl      # optional learning payloads
+  ep_01JH6Z2V9Q2K6Y6N0QZ7K2QW8C/
+    summary.json     # metrics and outcomes
+    state.json       # current plan and episode state
+    events.jsonl     # timeline with causal IDs
+    final.json       # terminal seal marker
+    manifest.json    # SHA-256 + size ledger for tamper evidence
+    learn.jsonl      # optional learning payloads
 ```
 
+Paused runs stay unsealed (no `final.json` / `manifest.json`) until continuation.
+
 ## Next steps
 
 <Steps>
diff --git a/docs/quickstart.mdx b/docs/quickstart.mdx
index b48ed36..438383b 100644
--- a/docs/quickstart.mdx
+++ b/docs/quickstart.mdx
@@ -106,13 +106,14 @@ Every episode creates a structured artifact directory (written under `.noesis/ep
     summary.json                  # metrics + rollups
     state.json                    # final state snapshot
     events.jsonl                  # append-only timeline
+    final.json                    # terminal seal marker
     manifest.json                 # SHA-256 + size ledger
     learn.jsonl                   # optional learning payloads
-  _episodes/                      # optional episode index (best-effort)
-    episodes.jsonl
+.noesis/index/
+    episodes.jsonl                # best-effort EpisodeIndex (may be missing)
 ```
 
-The `_episodes/` index is written on a best-effort basis at the end of runs and may be missing or empty (for example, if indexing fails due to permissions).
+The index under `.noesis/index/` is written on a best-effort basis at the end of **sealed** runs and may be missing (for example, if indexing fails due to permissions). There is no `_episodes/` directory under `episodes/`.
 
 <Tip>
 Use `jq` for pretty-printing JSON artifacts: `cat .noesis/episodes/ep_01JH6Z2V9Q2K6Y6N0QZ7K2QW8C/summary.json | jq .`
diff --git a/docs/reference/llms-txt.mdx b/docs/reference/llms-txt.mdx
new file mode 100644
index 0000000..00639d4
--- /dev/null
+++ b/docs/reference/llms-txt.mdx
@@ -0,0 +1,39 @@
+---
+title: "llms.txt and llms-full.txt"
+description: "How Noēsis docs expose LLM-friendly indexes and how to customize them."
+---
+
+Noēsis publishes a compact Markdown index so coding agents and other LLM tools can discover the public docs without scraping the site.
+
+## Files
+
+| File | Location | Purpose |
+| --- | --- | --- |
+| `llms.txt` | repository root | Curated list of public docs URLs with one-line summaries |
+| This page | `docs/reference/llms-txt.mdx` | Explains the index for humans |
+
+Mintlify also exposes the same content at [https://docs.noesis.systems/llms.txt](https://docs.noesis.systems/llms.txt) when the docs site is deployed.
+
+## What belongs in the index
+
+Only pages that exist under `docs/` **and** are intended for public consumption:
+
+- Get started, tutorials, how-to guides, explanation, and reference MDX
+- URLs must match Mintlify routes (for example `/tutorials/hello-episode`, not `/docs/app/...`)
+
+Do **not** list:
+
+- Deprecated stubs (for example `tutorials/guarded-langgraph-agent`)
+- Internal plans under `docs/internal/`
+- Pages that are not in the repo (the previous index listed `/guides/use-noesis-in-cursor` and `/guides/use-copilot`, which have no MDX files)
+
+## Maintainers
+
+When you add or rename a public docs page:
+
+1. Add or update the MDX file under `docs/`.
+2. Add the route to `docs/docs.json` navigation so the sidebar matches the index.
+3. Add a bullet to root `llms.txt` with the published `https://docs.noesis.systems/...` URL.
+4. From `docs/`, run `npx --yes mintlify@latest broken-links`.
+
+Keep descriptions to one sentence. Group entries the same way the sidebar is grouped.
diff --git a/docs/reference/python-api.mdx b/docs/reference/python-api.mdx
index 6f699ad..ca832f3 100644
--- a/docs/reference/python-api.mdx
+++ b/docs/reference/python-api.mdx
@@ -29,6 +29,7 @@ episode_id = ns.run(
     tags: dict[str, object] | None = None,
     context: Any | None = None,
     workspace: str | Path | None = None,
+    process: str | None = None,
     verify: VerifySpec | Sequence[VerifySpec] | None = None,
 ) -> str
 ```
@@ -57,6 +58,10 @@ Optional runtime context. If provided, execution bypasses the default session.
 Workspace root to snapshot for verification.
 </ParamField>
 
+<ParamField body="process" type="str | None" default="None">
+Human process label for grouping runs. Stored in the process registry under `.noesis/processes/`; does **not** nest episode directories. Identity is `sha256(workspace|name)[:12]`.
+</ParamField>
+
 <ParamField body="verify" type="VerifySpec | Sequence[VerifySpec] | None" default="None">
 Verification assertions to evaluate against the workspace.
 </ParamField>
@@ -70,6 +75,7 @@ import noesis as ns
 
 episode_id = ns.run("Draft release notes")
 episode_id = ns.run("Draft release notes", intuition=False, tags={"env": "staging"})
+episode_id = ns.run("Apply canary", process="rollout", seed=42)
 ```
 
 **Runtime context example**:
@@ -99,6 +105,7 @@ episode_id = ns.solve(
     tags: dict[str, object] | None = None,
     context: Any | None = None,
     workspace: str | Path | None = None,
+    process: str | None = None,
     verify: VerifySpec | Sequence[VerifySpec] | None = None,
 ) -> str
 ```
@@ -174,30 +181,42 @@ episode_id = ns.resume_run(
 ```python
 import noesis as ns
 
-# 1) Optional: enable pause-on-veto in enforce mode
+# 1) Enable pause-on-veto in enforce mode so a veto pauses instead of sealing
 ns.set(
     governance_mode="enforce",
     governance_pause_on_veto=True,
 )
 
-# 2) Start a run
+# 2) Start a run. If governance vetoes, solve returns an unsealed episode
+#    with run.interrupt + run.checkpoint already on the trace.
 episode_id = ns.solve("Danger operation: delete production database", using=my_graph)
 
-# 3) Manual pause (if your approval system decides to pause)
-interrupt_id = ns.interrupt(episode_id, reason="Awaiting human approval")
-checkpoint = ns.checkpoint(episode_id, caused_by=interrupt_id)
-
-# 4a) Emit resume evidence only (no execution continuation)
-resume_event_id = ns.resume(episode_id, checkpoint_id=checkpoint["checkpoint_id"])
-
-# 4b) Continue execution from checkpoint on the same run ID
-episode_id = ns.resume_run(
-    episode_id,
-    checkpoint_id=checkpoint["checkpoint_id"],
-    using=my_graph,  # required for non-minimal runs
+checkpoint_event = next(
+    (
+        event
+        for event in ns.events.read(episode_id)
+        if event.get("phase") == "runtime" and event.get("event_type") == "run.checkpoint"
+    ),
+    None,
 )
+
+if checkpoint_event is None:
+    # Run completed and sealed. ns.interrupt(...) would raise RunSealedError.
+    pass
+else:
+    checkpoint_id = checkpoint_event["payload"]["checkpoint_id"]
+    # 3a) Emit resume evidence only (no execution continuation)
+    resume_event_id = ns.resume(episode_id, checkpoint_id=checkpoint_id)
+    # 3b) Continue execution from checkpoint on the same run ID
+    episode_id = ns.resume_run(
+        episode_id,
+        checkpoint_id=checkpoint_id,
+        using=my_graph,  # required for non-minimal runs
+    )
 ```
 
+Manual `ns.interrupt` / `ns.checkpoint` is only valid on **unsealed** runs. After `final.json` exists, use a new run rather than mutating the sealed episode.
+
 Determinism scope:
 
 - Noēsis enforces immutable, append-only artifacts and replay discipline.
@@ -304,7 +323,7 @@ episodes = list_runs(
 ) -> list[dict]
 ```
 
-Each row includes `episode_id`, `task`, `started_at`, `flags`, `success`, `manifest`, and `manifest_status` (when `strict_manifest=True`).
+Each row includes `episode_id`, `task`, `started_at`, `flags`, `success`, `process`, `manifest`, and `manifest_status` (when `strict_manifest=True`). There is no `timestamp` field; use `started_at`.
 
 <Note>
 In v1.0.0, `ns.list_runs()` exists as a deprecated legacy alias. Prefer `noesis.io.list_runs()`.
@@ -592,18 +611,20 @@ Manage an on-disk episode manifest (and optional FAISS similarity index).
 from noesis.episode import EpisodeIndex
 
 store = EpisodeIndex(
-    root="./.noesis/episodes/_episodes",
-    ttl_days=14,
+    root=".noesis/index",
+    ttl_days=30,
     enable_faiss=False,  # set True if faiss + numpy installed and you provide embeddings
 )
 ```
 
+The runtime writes this index best-effort after sealing (`noesis/core.py`, `ttl_days=30`). `vacuum()` drops expired **index rows** only; it does not delete `.noesis/episodes/ep_*/` directories. There is no `_episodes/` folder under `episodes/`.
+
 **Core methods**:
 
 - `append(episode_id, summary_path, state_path, status, task, using, provenance=None, embedding=None)`
 - `iter(include_expired=False)` → iterator of `EpisodeRecord`
 - `search(embedding, k=5)` → similarity matches (empty if FAISS disabled)
-- `vacuum()` → prune expired records
+- `vacuum()` → rewrite `episodes.jsonl` excluding expired index rows (does not delete episode directories)
 
 ## Type definitions
 
diff --git a/examples/README.md b/examples/README.md
index 35c522b..74ffbe5 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -1,11 +1,13 @@
 # Examples & Learning Path
 
-Use these scenarios to introduce Noēsis concepts to engineers, operators, and stakeholders. Each folder keeps real code alongside the immutable artifacts stored in `.noesis/episodes/`.
+Use these scenarios to introduce Noēsis concepts to engineers, operators, and stakeholders. Each folder keeps real code alongside the immutable artifacts stored under `.noesis/`.
 
 ## Quickstart
 
 - `examples/demo.py` – one-file tour that runs two tasks (normal + vetoed) and prints summaries. Pair it with [`docs/explanation/artifacts.mdx`](../docs/explanation/artifacts.mdx) to explain the emitted artifacts.
-- `examples/artifacts/state_v1_example.json` – trimmed state snapshot used throughout the README and docs.
+- `examples/artifacts/state_v1_example.json` – trimmed state snapshot used throughout the docs.
+
+`examples/demo.py` sets `ns.set(runs_dir="./.noesis/episodes/demo")`. That is a **custom `runs_dir`**, not a label subdirectory of the default episodes root. Default runs still land in `.noesis/episodes/ep_<ULID>/`.
 
 ## Governance & operations
 
@@ -14,17 +16,13 @@ Use these scenarios to introduce Noēsis concepts to engineers, operators, and s
 
 ## Memory & insight
 
-- Start from the [`Runtime context & memory`](../README.md#runtime-context--memory) snippet, then register your own SQLite/FAISS provider with `context.create_runtime_context()`.
-- Inspect `state.json["memory"]` and `summary.json["insight"]["metrics"]` in any demo run to see durable recall and KPI rollups.
-
-## MCP & external tools
+Register a memory port with `context.create_runtime_context()` / `context.register("memory", ...)`. See [`docs/guides/add-memory-port.mdx`](../docs/guides/add-memory-port.mdx).
 
-- Follow the [MCP & external tooling](../README.md#mcp--external-tooling) section to hook existing Model Context Protocol servers into Noēsis.
-- Adapters report every tool invocation via `events.jsonl`, so you can share the same observability story whether the tool ran locally, remotely, or inside MCP.
+Inspect `state.json["memory"]` and `summary.json["insight"]["metrics"]` in any demo run to see durable recall and KPI rollups.
 
-### Suggested flow for new contributors
+## Suggested flow for new contributors
 
 1. Run `uv run python examples/demo.py`.
-2. Open the emitted `.noesis/episodes/demo/<episode>/summary.json` and `state.json`.
+2. Open the emitted episode under the demo `runs_dir` (look for `ep_*/summary.json` and `state.json`).
 3. Step up to `uv run python -m examples.incident_triage.gradio_app` to see governance + dashboards.
 4. Customize `context.register("memory", ...)` to plug in domain memories or insight evaluators.
diff --git a/llms.txt b/llms.txt
index df1f502..4bce4ea 100644
--- a/llms.txt
+++ b/llms.txt
@@ -6,11 +6,12 @@
 
 ## Tutorials
 - [Your first episode](https://docs.noesis.systems/tutorials/first-episode): Learn how to run, inspect, and understand Noēsis episodes step by step.
-- [Your first policy](https://docs.noesis.systems/tutorials/first-policy): Learn how to create intuition policies that guide and guard your agent episodes.
-- [Guarded LangGraph Agent: Vetoing Dangerous File Deletes](https://docs.noesis.systems/tutorials/guarded-langgraph-agent): Wrap a LangGraph agent with Noēsis so every tool call is observable and dangerous deletes get vetoed.
 - [Hello Episode: See Your Agent Think in 5 Minutes](https://docs.noesis.systems/tutorials/hello-episode): Run a tiny agent through Noēsis, open the artifacts, and read the timeline that shows every phase.
-- [Build an incident triage dashboard](https://docs.noesis.systems/tutorials/incident-triage): Create a production-ready incident response system with Noēsis, complete with guardrails and human approval loops.
+- [Your first policy](https://docs.noesis.systems/tutorials/first-policy): Learn how to create intuition policies that guide and guard your agent episodes.
+- [LangGraph Episode](https://docs.noesis.systems/tutorials/langgraph-episode): Trace the cognitive loop with `ns.solve(...)`.
+- [Governed Side Effects](https://docs.noesis.systems/tutorials/governed-side-effects): Enforce `action_candidate → governance → act` with `ns.governed_act(...)`.
 - [Trace-Based Evals: Safety & Success in 100 Lines](https://docs.noesis.systems/tutorials/trace-based-evals): Score your guarded agent over a dataset using Noēsis traces, not just final answers.
+- [Build an incident triage dashboard](https://docs.noesis.systems/tutorials/incident-triage): Create a production-ready incident response system with Noēsis, complete with guardrails and human approval loops.
 
 ## How-to guides
 - [Add a memory port](https://docs.noesis.systems/guides/add-memory-port): Plug long-term memory into Noēsis using SQLite, your DB, or a custom store.
@@ -21,8 +22,6 @@
 - [Human-in-the-loop](https://docs.noesis.systems/guides/human-in-the-loop): How to add human approval workflows to your Noēsis episodes.
 - [Integrate adapters](https://docs.noesis.systems/guides/integrate-adapters): How to connect Noēsis to LangGraph, CrewAI, or your own agent runtime.
 - [Write intuition policies](https://docs.noesis.systems/guides/write-policies): How to create, test, and deploy policies that guide and guard your agent episodes.
-- [Use Noēsis in Cursor](https://docs.noesis.systems/guides/use-noesis-in-cursor): Run episodes, add guardrails, and inspect traces without leaving your editor.
-- [Use GitHub Copilot with Noēsis](https://docs.noesis.systems/guides/use-copilot): Pasteable Noēsis cheat sheet for Copilot to guide users through the API and CLI without hallucinations.
 
 ## Explanation
 - [Core concepts](https://docs.noesis.systems/explanation/core-concepts): Understand the fundamental building blocks of Noēsis: episodes, faculties, and artifacts.
diff --git a/noesis-tui/README.md b/noesis-tui/README.md
index b271e87..f980e05 100644
--- a/noesis-tui/README.md
+++ b/noesis-tui/README.md
@@ -1,121 +1,116 @@
 # Noesis TUI
 
-A beautiful terminal user interface for the Noesis cognitive framework, built with [Bubbletea](https://github.com/charmbracelet/bubbletea), [Bubbles](https://github.com/charmbracelet/bubbles), and [Lipgloss](https://github.com/charmbracelet/lipgloss).
+A terminal user interface for the Noesis cognitive framework, built with [Bubbletea](https://github.com/charmbracelet/bubbletea), [Bubbles](https://github.com/charmbracelet/bubbles), and [Lipgloss](https://github.com/charmbracelet/lipgloss).
 
 ## Features
 
 - **Episode Browser**: List and filter recent episodes with status badges
 - **Dashboard View**: Execution map, verification results, KPIs, and timeline
 - **Events Viewer**: Scrollable event stream with phase filtering
+- **Proof / changes**: Inspection screens for run evidence
 - **Run Launcher**: Start new episodes directly from the TUI
 
 ## Prerequisites
 
 - Go 1.22 or later
-- Noesis Python CLI installed and in your PATH (`noesis` command available)
+- Noesis Python CLI installed and on your `PATH` (`noesis` command available)
 
 ## Installation
 
 ```bash
-# From the go-tui directory
+cd noesis-tui
 go install .
 
 # Or build locally
 make build
 ```
 
+The TUI auto-detects `.noesis/episodes` (or `NOESIS_RUNS_DIR`) by walking parent directories. Episode bundles are flat `ep_<ULID>/` directories.
+
 ## Usage
 
 ```bash
-# Run the TUI
+# From this directory after `make build`
 ./noesis-tui
 
 # Or if installed
 noesis-tui
 ```
 
-### Keyboard Shortcuts
+The Python CLI also exposes an in-process browser: `noesis browse`.
+
+### Keyboard shortcuts
+
+Help text on the home screen: `1/2: tabs  enter: view  b: browse  p: proof  e: events  n: run  r: refresh  /: filter  q: quit`.
+
+#### Home screen (episode list)
+
+- `enter` — View episode details
+- `e` — View episode events
+- `b` — Open browse
+- `p` — Open proof
+- `d` — Open changes
+- `n` — Launch new episode
+- `r` — Refresh list
+- `f` — Cycle status filter
+- `/` — Filter episodes
+- `tab` / `1` / `2` — Switch runs vs agents tabs
+- `q` — Quit
 
-#### Home Screen (Episode List)
-- `enter` - View episode details
-- `e` - View episode events
-- `n` - Launch new episode
-- `r` - Refresh list
-- `/` - Filter episodes
-- `q` - Quit
+#### Detail screen (dashboard)
 
-#### Detail Screen (Dashboard)
-- `e` - View events
-- `↑/↓` - Scroll
-- `esc` - Go back
+- `e` — View events
+- `p` — Open proof
+- `↑/↓` — Scroll (viewport)
+- `esc` — Go back
 
-#### Events Screen
-- `←/→` or `h/l` - Switch phase filter
-- `tab` - Cycle filters
-- `↑/↓` - Scroll
-- `esc` - Go back
+#### Events screen
 
-#### Run Screen
-- `enter` - Start run (input mode) / View details (after completion)
-- `n` - Start new run (after completion)
-- `esc` - Go back
+- `←/→` or `h/l` — Switch phase filter
+- `tab` — Cycle filters
+- `↑/↓` — Scroll
+- `esc` — Go back
+
+#### Run screen
+
+- `enter` — Start run (input mode) / View details (after completion)
+- `n` — Start new run (after completion)
+- `esc` — Go back
 
 ## Architecture
 
-The TUI consumes CLI contracts defined in ADR-011 and ADR-012:
+The TUI shells out to the Python CLI (`noesis-tui/internal/cli/client.go`):
 
-- `noesis ps --json` → Episode list (PsResult envelope)
-- `noesis view <id> --json` → Episode dashboard (ViewResult envelope)
-- `noesis events <id> --envelope` → Event stream (EventsResult envelope)
-- `noesis run "task" --json` → Run episode (RunResult envelope)
+- `noesis ps --json` → Episode list
+- `noesis view <id> --json` → Episode dashboard
+- `noesis events <id> --envelope` → Event stream
+- `noesis run "task" --json` → Run episode
 
-### Directory Structure
+### Directory structure
 
 ```
-go-tui/
-├── main.go                    # Entry point
-├── internal/
-│   ├── cli/                   # CLI client and types
-│   │   ├── client.go          # Shell-out to Python CLI
-│   │   ├── envelope.go        # CLI version block
-│   │   ├── ps.go              # PsResult types
-│   │   ├── view.go            # ViewResult + Dashboard types
-│   │   ├── events.go          # EventsResult types
-│   │   └── run.go             # RunResult types
-│   ├── model/                 # Bubbletea models
-│   │   ├── app.go             # Root model (screen router)
-│   │   ├── home.go            # Episode list screen
-│   │   ├── detail.go          # Dashboard detail screen
-│   │   ├── events.go          # Events viewer screen
-│   │   └── run.go             # Run launcher screen
-│   ├── style/                 # Lipgloss styling
-│   │   ├── theme.go           # Colors (matches Python CLI)
-│   │   ├── symbols.go         # Status/phase symbols
-│   │   └── layout.go          # Breakpoints, dimensions
-│   └── msg/                   # Bubbletea messages
-│       ├── navigation.go      # Screen transitions
-│       └── data.go            # Data fetch results
-└── Makefile
+noesis-tui/
+├── main.go
+├── Makefile
+└── internal/
+    ├── cli/          # Shell-out client and JSON envelopes
+    ├── model/        # Bubbletea screens (home, detail, events, run, browse, proof, changes)
+    ├── ui/           # Dashboard + proof rendering
+    ├── style/        # Lipgloss theme (aligned with Python CLI)
+    └── msg/          # Navigation and data messages
 ```
 
 ## Development
 
 ```bash
-# Install dependencies
+cd noesis-tui
 go mod tidy
-
-# Build
 make build
-
-# Run in development
 make dev
-
-# Clean
 make clean
 ```
 
 ## Related
 
-- [Noesis](https://github.com/noesis-ai/noesis) - The Python cognitive framework
-- [ADR-011](../internals/adr/ADR-011-cli-run-contract.md) - CLI Run Boundary Contract
-- [ADR-012](../internals/adr/ADR-012-cli-observe-contract.md) - CLI Observe Boundary Contract
+- [Noesis](https://github.com/saraeloop/noesis) — Python runtime
+- CLI contracts: `noesis ps`, `noesis view`, `noesis events --envelope`, `noesis run --json` (see `docs/reference/cli.mdx`)