eric1311 · eric1311 · Jun 11, 2026 · Jun 11, 2026 · Jun 11, 2026 · Jun 11, 2026
diff --git a/README.md b/README.md
@@ -36,19 +36,21 @@ Invart is currently a CLI-first **0.9 pre-release**. It is suitable for local ev
 - Run built-in benchmarks and demos, including real-world-risk-shaped and containerized risk flows.
 - Keep old `kappaski` imports and CLI as compatibility aliases while the public project name moves to `Invart`.
 
-## What To Inspect First
+## Start Here
 
-For a first pass, the most useful public-facing surfaces are:
+README is the landing page. The docs are organized as a user journey:
 
-| Surface | Why it matters |
+| If you want to... | Start with |
 | --- | --- |
-| [`docs/product.md`](docs/product.md) | One-page product overview for the before / during / after control loop. |
-| [`docs/quickstart.md`](docs/quickstart.md) | Minimal local session that writes a ledger and verifies proof. |
-| [`docs/runtime-effect-demo.md`](docs/runtime-effect-demo.md) | Shows the demo's before / during / after stages and L1-L5 control effects. |
-| [`docs/evaluation.md`](docs/evaluation.md) | Explains what the built-in benchmarks measure and what they do not claim. |
-| [`examples/`](examples/) | Small runnable examples before running the larger demos. |
+| Understand what Invart is and why it exists | [`docs/product.md`](docs/product.md) |
+| Run one local managed session | [`docs/quickstart.md`](docs/quickstart.md) |
+| Operate the five runtime layers on a ledger | [`docs/five-layer-operator-guide.md`](docs/five-layer-operator-guide.md) |
+| See the before / during / after demo artifacts | [`docs/runtime-effect-demo.md`](docs/runtime-effect-demo.md) |
+| Integrate with CLI, artifacts, or Python helpers | [`docs/cli-reference.md`](docs/cli-reference.md) and [`docs/api-sdk.md`](docs/api-sdk.md) |
+| Evaluate claims and benchmarks | [`docs/evaluation.md`](docs/evaluation.md) |
+| Browse the full documentation map | [`docs/index.md`](docs/index.md) or [`docs/html/index.html`](docs/html/index.html) |
 
-The main demo command below produces a local HTML entrypoint plus audit, replay, path graph, coverage, proof, and ledger artifacts. Those artifacts are the best way to see Invart intervening in and explaining an agent-like run.
+The recommended first path is: **Quickstart -> Five-layer operator guide -> Runtime effect demo -> Evaluation**. That path shows the whole loop from a local ledger to proof, replay, path graph, coverage, audit, and evidence review.
 
 ## Install For Local Development
 
@@ -141,20 +143,17 @@ Heavy external validation such as full SWE-Bench runs is intentionally separate
 
 ## Documentation
 
-Open the local docs:
+Open the docs home for the structured journey:
 
-- [Docs README](docs/README.md)
 - [Markdown docs home](docs/index.md)
 - [HTML docs home](docs/html/index.html)
-- [Product page](docs/product.md)
-- [Quickstart](docs/quickstart.md)
+
+Reference pages:
+
+- [Docs README](docs/README.md)
 - [Concepts](docs/concepts.md)
-- [CLI reference](docs/cli-reference.md)
-- [API and SDK](docs/api-sdk.md)
 - [Architecture](docs/architecture.md)
 - [Examples](docs/examples.md)
-- [Runtime effect demo](docs/runtime-effect-demo.md)
-- [Evaluation](docs/evaluation.md)
 - [Open-source boundary](docs/open-source-boundary.md)
 - [Brand assets](assets/brand/README.md)
 

diff --git a/docs/README.md b/docs/README.md
@@ -16,6 +16,7 @@ Public pages:
 | --- | --- | --- |
 | Product overview | [`product.md`](product.md) | [`html/product.html`](html/product.html) |
 | Quickstart | [`quickstart.md`](quickstart.md) | [`html/quickstart.html`](html/quickstart.html) |
+| Five-layer operator guide | [`five-layer-operator-guide.md`](five-layer-operator-guide.md) | [`html/five-layer-operator-guide.html`](html/five-layer-operator-guide.html) |
 | Concepts | [`concepts.md`](concepts.md) | [`html/concepts.html`](html/concepts.html) |
 | CLI reference | [`cli-reference.md`](cli-reference.md) | [`html/cli-reference.html`](html/cli-reference.html) |
 | API and SDK | [`api-sdk.md`](api-sdk.md) | [`html/api-sdk.html`](html/api-sdk.html) |

diff --git a/docs/api-sdk.md b/docs/api-sdk.md
@@ -5,7 +5,7 @@
 
 Invart 0.9 is CLI-first. The stable integration surface is the CLI plus verifiable artifacts. Python helpers are available for local tooling, but only a small set should be treated as provisional SDK entry points before 1.0.
 
-[Docs Home](index.md) · [Quickstart](quickstart.md) · [CLI](cli-reference.md) · [Architecture](architecture.md) · [Examples](examples.md)
+[Docs Home](index.md) · [Quickstart](quickstart.md) · [Operate L1-L5](five-layer-operator-guide.md) · [CLI](cli-reference.md) · [Architecture](architecture.md) · [Examples](examples.md)
 
 ## Public Surface
 
@@ -77,6 +77,8 @@ These helpers are suitable for local adapters, experiments, and internal automat
 | Paper tables JSON/CSV/HTML | invart experiment paper-tables | Research reports, appendix tables, product validation review | Derived summaries. Each row should link back to ledger/proof/replay/path graph/evidence artifacts. |
 | Research readiness report | invart release-candidate verify --paper | Pre-release research review | Separate from product RC. It checks evidence completeness without claiming external benchmark completion. |
 
+For the operational meaning of proof, replay, path graph, coverage, audit, and evidence workspace, use the [five-layer operator guide](five-layer-operator-guide.md). It explains which artifact answers each L1-L5 review question.
+
 ## Compatibility Names
 
 New integrations should import invart and use the canonical subpackages such as invart.core, invart.control, and invart.assurance. The older flat invart.ledger style imports and the former kappaski import path remain compatibility aliases during the rename period, but new documentation and examples use the organized Invart layout.

diff --git a/docs/architecture.md b/docs/architecture.md
@@ -3,10 +3,16 @@
 [HTML version](html/architecture.html)
 
 
-Invart is not a plugin-only wrapper. Plugin and hook integration can improve coverage, but the durable product boundary is the runtime control plane.
+Invart is not a plugin-only wrapper. Plugin and hook integration can improve coverage, but the durable product boundary is the runtime control plane. For operational usage of the same model, read the [five-layer operator guide](five-layer-operator-guide.md).
 
 ## Lifecycle
 
+| Stage | Architecture role |
+| --- | --- |
+| Before runtime | Inventory surfaces, bind identity, resolve profile and grants, and establish the claim boundary. |
+| During runtime | Normalize actions into ledger facts, evaluate policy, mediate covered surfaces, and record outcomes. |
+| After runtime | Derive proof, replay, path graph, coverage, audit, evidence bundles, and gates from the ledger. |
+
 ## Layer Model
 
 | Layer | Responsibility | Example modules |
@@ -19,7 +25,7 @@ Invart is not a plugin-only wrapper. Plugin and hook integration can improve cov
 
 ## Demo Verification
 
-The [runtime effect demo](runtime-effect-demo.md) is the concrete verification surface for this model. It renders a stage × layer matrix in the final demo entrypoint and an action timeline in each container risk case audit page. The timeline connects agent intent/action, Invart observation, policy or mediation decision, outcome, and the artifact that proves the step.
+The [runtime effect demo](runtime-effect-demo.md) is the concrete verification surface for this model. It renders a stage × layer matrix in the final demo entrypoint and an action timeline in each container risk case audit page. The [five-layer operator guide](five-layer-operator-guide.md) is the command-level usage surface for the same layers.
 
 Coverage terms remain strict: observed, mediated, and enforced are not interchangeable. Unmanaged direct execution is shown as a coverage gap unless it enters a managed launcher, wrapper, hook, broker, or shim.
 

diff --git a/docs/cli-reference.md b/docs/cli-reference.md
@@ -3,7 +3,20 @@
 [HTML version](html/cli-reference.html)
 
 
-Run invart --help for the complete parser. These are the entry points most people should start with.
+Run `invart --help` for the complete parser. These are the entry points most people should start with. For a guided L1-L5 workflow, use the [five-layer operator guide](five-layer-operator-guide.md).
+
+## User intent to command
+
+| I want to... | Start with |
+| --- | --- |
+| Scan before an agent runs | `invart pre-runtime --target . --save` |
+| Run one managed session | `invart run --target . --agent codex --goal "..." -- <command>` |
+| Inspect L1-L5 for a ledger | `invart runtime layers --ledger ledger.jsonl --out-dir .invart/layers` |
+| Explain a risky path | `invart policy check-path --ledger ledger.jsonl --out path-policy.json` |
+| Inspect mediation state | `invart mediation inspect --ledger ledger.jsonl` |
+| Export reviewable evidence | `invart evidence export --ledger ledger.jsonl --out-dir .invart/evidence` |
+| Validate real-agent integration | `invart real-agent check --agent claude-code --out-dir .invart/real-agent` |
+| Run product benchmarks | `invart eval benchmark --suite full-product-readiness` |
 
 ### Pre-runtime
 
@@ -43,6 +56,19 @@ invart replay export --ledger ledger.jsonl --out replay.html
 invart audit report --ledger ledger.jsonl --out-dir .invart/audit
 ```
 
+### Evidence workspace
+
+```bash
+invart evidence export --ledger ledger.jsonl --out-dir .invart/evidence
+invart evidence verify --bundle .invart/evidence/manifest.json
+invart evidence inspect \
+  --manifest .invart/evidence/manifest.json \
+  --out-dir .invart/evidence-workspace \
+  --require-layer-workflow
+```
+
+`evidence inspect` treats the bundle as an L5 review workspace. It verifies artifact hashes, checks required bundle contents, and reports whether the run can answer who, what, why, policy, approval, outcome, and coverage. Optional requirements such as `--require-layer-workflow` and `--require-adapter-package` turn missing links into gate failures.
+
 ### Real agent conformance
 
 ```bash
@@ -78,5 +104,6 @@ invart eval benchmark --suite v0.9.3-agent-adapter-contract
 invart eval benchmark --suite v0.9.4-claude-reference-adapter
 invart eval benchmark --suite v0.9.5-priority-agent-tracks
 invart eval benchmark --suite v0.9.6-layer-runtime-workflow
+invart eval benchmark --suite v0.9.7-evidence-workspace-gate
 invart roadmap status --require-full
 ```
diff --git a/docs/concepts.md b/docs/concepts.md
@@ -1,17 +1,18 @@
-# The nouns that matter.
+# Core concepts reference
 
 [HTML version](html/concepts.html)
 
+This page is a glossary-style compatibility reference. If you are learning Invart for the first time, start with [Product Overview](product.md), then use the [five-layer operator guide](five-layer-operator-guide.md) for command-level usage.
 
-Invart is easier to understand when you separate facts, decisions, mediation, and portable evidence.
+| Concept | Meaning | Where to use it |
+| --- | --- | --- |
+| Session | A bounded agent run with target, goal, agent identity, principal, and ledger. | [Quickstart](quickstart.md) |
+| Invocation | A normalized runtime action such as shell, file, network, MCP, skill, or content activity. | [Five-layer operator guide](five-layer-operator-guide.md) |
+| Ledger | The append-only fact source. Proof, replay, graph, audit, and gates derive from it. | [Product Overview](product.md) |
+| Proof | A portable summary of the run. It should answer who, what, why, policy, approval, outcome, and coverage. | [API & SDK](api-sdk.md) |
+| Mediation | The decision contract for allow, audit, require approval, deny, enforced block, and fail-open alert. | [Five-layer operator guide](five-layer-operator-guide.md) |
+| Coverage | The strength of observation or control: declared, observed, mediated, enforced, or fail-open. | [Evaluation](evaluation.md) |
+| Path graph | A ledger-derived graph connecting identity, grant, invocation, resource, taint, decision, approval, outcome, and artifact. | [Runtime effect demo](runtime-effect-demo.md) |
+| Evidence bundle | A verifiable package containing manifest hashes, proof, replay, graph, coverage, audit JSON/HTML, and policy summary. | [API & SDK](api-sdk.md) |
 
-| Concept | Meaning |
-| --- | --- |
-| Session | A bounded agent run with target, goal, agent identity, principal, and ledger. |
-| Invocation | A normalized runtime action such as shell, file, network, MCP, skill, or content activity. |
-| Ledger | The append-only fact source. Proof, replay, graph, audit, and gates derive from it. |
-| Proof | A portable summary of the run. It should answer who, what, why, policy, approval, outcome, and coverage. |
-| Mediation | The decision contract for allow, audit, require approval, deny, enforced block, and fail-open alert. |
-| Coverage | The strength of observation or control: declared, observed, mediated, enforced, or fail-open. |
-| Path graph | A ledger-derived graph connecting identity, grant, invocation, resource, taint, decision, approval, outcome, and artifact. |
-| Evidence bundle | A verifiable package containing manifest hashes, proof, replay, graph, coverage, audit JSON/HTML, and policy summary. |
+For internal module boundaries, use [Architecture](architecture.md).
diff --git a/docs/evaluation.md b/docs/evaluation.md
@@ -5,6 +5,8 @@
 
 Invart separates local product checks from optional heavy external benchmark evidence.
 
+[Operate L1-L5](five-layer-operator-guide.md) · [Runtime Effect Demo](runtime-effect-demo.md) · [CLI](cli-reference.md)
+
 ## Default Local Checks
 
 ```bash
@@ -24,6 +26,17 @@ PYTHONPATH=src python -m invart.cli roadmap status --require-full
 | Coverage truthfulness | Observed, mediated, enforced, and fail-open are not the same claim. |
 | Audit reconstruction | A reviewer should reconstruct the run from durable evidence. |
 
+## Product claim to benchmark
+
+| Product claim | Local check | Evidence to inspect |
+| --- | --- | --- |
+| Invart can preserve a closed before / during / after runtime loop. | `invart eval benchmark --suite pre-v1-control-plane` | ledger, proof, replay, path graph, coverage, audit report |
+| High-risk agent-like actions are blocked, paused, or escalated without silent pass-through. | `invart eval benchmark --suite real-world-agent-risk-demo` | risk demo HTML, case audit report, mediation decisions |
+| Coverage labels remain truthful across observed, mediated, enforced, fail-open, and bypassed paths. | `invart eval benchmark --suite v0.47-coverage-mediation-pilot` | coverage matrix JSON/HTML |
+| Auditors can reconstruct who, what, why, policy, approval, outcome, and coverage. | `invart eval benchmark --suite v0.48-audit-reconstruction-study` | audit reconstruction study and evidence bundle |
+| Plugin-only or vendor-native visibility is not reported as full runtime mediation. | `invart eval benchmark --suite v0.50-product-control-matrix` | product control matrix |
+| Pre-release evidence can be checked separately from external benchmark completion. | `invart eval benchmark --suite v0.51-pre-1.0-research-ready-gate` | research-ready gate report |
+
 ## Research-Ready Validation Loop
 
 The pre-1.0 research track validates an LLM/agent workflow end to end:

diff --git a/docs/examples.md b/docs/examples.md
@@ -1,24 +1,27 @@
-# Small examples before full demos.
+# Examples and safe fixtures
 
 [HTML version](html/examples.html)
 
+This page is a compatibility index for small examples. For a guided first run, use [Quickstart](quickstart.md). For layer-by-layer operation, use the [five-layer operator guide](five-layer-operator-guide.md).
 
-The examples/ directory contains short runnable or copyable examples for local evaluation.
+## Runnable examples
 
-### Basic managed session
+| Example | Use it for |
+| --- | --- |
+| [`../examples/basic-managed-session.sh`](../examples/basic-managed-session.sh) | Create one managed session, ledger, and proof for a low-risk command. |
+| [`../examples/policy-profile.toml`](../examples/policy-profile.toml) | Inspect a compact policy-as-code profile with path-aware rules. |
+| [`../examples/unsafe-action-event.json`](../examples/unsafe-action-event.json) | Analyze an unsafe shell event without executing it. |
 
-examples/basic-managed-session.sh creates a ledger and proof for one low-risk command.
-
-### Policy profile
-
-examples/policy-profile.toml shows a small TOML profile with path-aware risk rules.
-
-### Unsafe event
-
-examples/unsafe-action-event.json is a shell event you can analyze without executing it.
-
-## Analyze The Unsafe Event
+## Analyze the unsafe event
 
 ```bash
 invart runtime analyze-event --event "$(cat examples/unsafe-action-event.json)"
 ```
+
+This command analyzes a JSON event payload. It does not execute the unsafe command inside the fixture.
+
+## Next steps
+
+- Use [Quickstart](quickstart.md) to create a real local ledger.
+- Use [Five-layer Operator Guide](five-layer-operator-guide.md) to inspect L1-L5 on that ledger.
+- Use [Runtime Effect Demo](runtime-effect-demo.md) for generated demo artifacts and action timelines.