ARPAHLS · rosspeili · Aug 29, 2026 · Aug 29, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Changed
+
+- **Documentation sweep ([#14](https://github.com/ARPAHLS/aura/issues/14))** — `docs/INDEX.md` three-tier entry (Start / Build / Decide + Optional vision); demoted narrative, three-rings, aura-levels, field-services; refreshed architecture, concepts, stack-position, field-services shipped vs planned; fixed stale v0.2 voice in getting-started and concepts.
+
 ## [0.3.4] - 2026-08-26
 
 ### Added

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -159,7 +159,8 @@ Pure internal refactors with no user-visible effect may omit CHANGELOG; ask on t
 | Integration example (Ollama, API, framework) | `integrations/<stack>/`, `docs/integrations/README.md`, `.env.example`, CHANGELOG |
 | CLI commands or flags | `docs/getting-started.md`, `README.md` quick start line, `docs/outputs.md` (export/compare shapes), CHANGELOG |
 | New core example | Flat script in `examples/`, `examples/README.md`, optional link from `docs/getting-started.md` |
-| Architecture terminology | `docs/architecture.md`, `README.md` diagrams (keep in sync) |
+| Architecture terminology | `docs/architecture.md`, `docs/INDEX.md`, `README.md` diagrams (keep in sync) |
+| Public docs tree / INDEX tiers | `docs/INDEX.md`, cross-links from `getting-started.md`, `onboarding.md`, `ROADMAP.md` |
 | Release / PyPI behavior | `docs/PUBLISHING.md`, `.github/workflows/publish-pypi.yml`, CHANGELOG |
 | PR CI workflow | `.github/workflows/ci.yml`, `.github/workflows/reusable-test.yml`, `docs/TESTING.md`, `CONTRIBUTING.md` |
 | Issue template fields | `.github/labels.json` if new label needed; run label sync |

diff --git a/README.md b/README.md
@@ -122,6 +122,7 @@ CLI: `aura agent create`, `aura run`, `aura export`, `aura report show`, `aura c
 
 | Topic | Links |
 | :--- | :--- |
+| **Index** | [docs/INDEX.md](docs/INDEX.md) — full doc map (Start / Build / Decide) |
 | **Start** | [onboarding.md](docs/onboarding.md) · [getting-started.md](docs/getting-started.md) · [concepts.md](docs/concepts.md) · [using-aura.md](docs/using-aura.md) |
 | **Integration** | [reference-tool-host-capstone.md](docs/guides/reference-tool-host-capstone.md) · [guides/aura-on-skillware.md](docs/guides/aura-on-skillware.md) · [skillware-integration.md](docs/skillware-integration.md) · [sequencer.md](docs/sequencer.md) |
 | **Identity & audit** | [trust-paths.md](docs/trust-paths.md) · [outputs.md](docs/outputs.md) |

diff --git a/docs/INDEX.md b/docs/INDEX.md
@@ -1,57 +1,69 @@
 # AURA Harness — Documentation
 
+Single entry point for public docs. **Shipped behavior** lives in Tier 1–2; Tier 3 is positioning; **Optional** is vision and internal vocabulary — not required for onboarding.
+
 ---
 
-## Start here
+## Tier 1 — Start
 
 | Doc | Content |
 |---|---|
 | [onboarding.md](onboarding.md) | **Start here** — install → posture → agent → body → receipt |
-| [getting-started.md](getting-started.md) | Install, example, CLI |
-| [using-aura.md](using-aura.md) | Membrane, personas, SDK |
-| [contributing/ai_native_workflow.md](contributing/ai_native_workflow.md) | Agents and operators |
-| [TESTING.md](TESTING.md) | pytest, black, flake8, PR checklist |
-| [../CONTRIBUTING.md](../CONTRIBUTING.md) | Full contributor guide (humans and agents) |
+| [getting-started.md](getting-started.md) | Install, minimal example, CLI |
+| [using-aura.md](using-aura.md) | Membrane, postures, session export, SDK |
 | [concepts.md](concepts.md) | Agent, session, identity, audit |
-| [comparison.md](comparison.md) | vs orchestrators, eval harnesses, tracing |
-| [architecture.md](architecture.md) | v0.2 modules |
-| [ROADMAP.md](ROADMAP.md) | Shipped vs deferred |
-| [examples/](../examples/README.md) | Four runnable core demos plus Skillware / ToolHost demos |
-| [guides/reference-tool-host-capstone.md](guides/reference-tool-host-capstone.md) | ToolHost integration checklist (AURA-first) |
+| [examples/README.md](../examples/README.md) | Runnable core scripts + integration demos |
+| [integrations/README.md](integrations/README.md) | Pick your stack — Ollama, cloud APIs, Skillware |
+| [guides/reference-tool-host-capstone.md](guides/reference-tool-host-capstone.md) | ToolHost checklist (mock → live → Ollama) |
 
 ---
 
-## Integration
+## Tier 2 — Build
 
 | Doc | Content |
 |---|---|
-| [integrations/README.md](integrations/README.md) | Pick your stack — models, tools, frameworks |
-| [skillware-integration.md](skillware-integration.md) | Skillware reference adapter — see `integrations/skillware/` |
-| [sequencer.md](sequencer.md) | Prescriptive pipelines, gates, conformance |
+| [architecture.md](architecture.md) | Modules, data flow, extension surface |
+| [stack-position.md](stack-position.md) | Optional — harness-centric input layers vs full ARPA stack |
+| [sequencer.md](sequencer.md) | Prescriptive pipelines, gates, `when`, conformance |
+| [skillware-integration.md](skillware-integration.md) | Skillware reference adapter (optional host) |
+| [guides/aura-on-skillware.md](guides/aura-on-skillware.md) | Deep dive — Skillware as one ToolHost impl |
+| [trust-paths.md](trust-paths.md) | `agent_ref`, ULID, ids trailer — no central ID service |
+| [outputs.md](outputs.md) | JSONL, summary, audit report, hash chain, OTel |
+| [TESTING.md](TESTING.md) | pytest, black, flake8, PR checklist |
+| [../CONTRIBUTING.md](../CONTRIBUTING.md) | Contributor guide (humans and agents) |
+| [contributing/ai_native_workflow.md](contributing/ai_native_workflow.md) | Agent contribution workflow |
+
+Copy [`.env.example`](../.env.example) to `.env` for local Ollama or cloud API keys. Never commit `.env`.
+
+---
+
+## Tier 3 — Decide
 
-Copy [`.env.example`](../.env.example) to `.env` for local Ollama (`llama3.2:1b`) or cloud API keys. Never commit `.env`.
+| Doc | Content |
+|---|---|
+| [comparison.md](comparison.md) | vs orchestrators, eval harnesses, tracing |
+| [ROADMAP.md](ROADMAP.md) | Shipped vs deferred (sole deferrals file for public docs) |
+| [README.md](../README.md) | Project entry, quick start, badges |
 
 ---
 
-## Reference
+## Optional — vision & reference
+
+Not on the default onboarding path. Kept for ARPA stack context and long-form design language.
 
 | Doc | Content |
 |---|---|
-| [README.md](../README.md) | Project entry, stack diagram |
-| [narrative.md](narrative.md) | Long-form vision (coat, SCI) |
-| [stack-position.md](stack-position.md) | Optional ARPA stack context |
-| [trust-paths.md](trust-paths.md) | Lite ID — no identity service |
-| [outputs.md](outputs.md) | AuraEvent, exporters |
-| [aura-levels.md](aura-levels.md) | Autonomy tiers (roadmap enforcement) |
-| [field-services.md](field-services.md) | Observer presets (roadmap) |
+| [narrative.md](narrative.md) | Long-form vision (coat, SoulSig, cybernetics) |
 | [three-rings.md](three-rings.md) | Envelope · Field · Adapter model |
-| [glossary.md](glossary.md) | Terms |
+| [aura-levels.md](aura-levels.md) | Autonomy tiers (enforcement roadmap) |
+| [field-services.md](field-services.md) | Twelve parallel services — shipped vs planned |
+| [glossary.md](glossary.md) | Terminology reference |
 
 ---
 
 ## Specifications
 
-Schemas for manifest, events, plugins — **stable contracts** for adapters.
+Stable contracts for adapters and tooling.
 
 | File | Purpose |
 |---|---|

diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md
@@ -9,8 +9,9 @@ Shipped work stays in [CHANGELOG.md](../CHANGELOG.md). This file lists what is *
 | Version | Highlights |
 |---|---|
 | **v0.1** | Registry, sessions, constraints, JSONL export, SDK |
-| **v0.2** | Membrane, sequencer, Skillware host, observer presets (monitor, break) |
+| **v0.2** | Membrane, sequencer, Skillware host, observers |
 | **v0.3** | ULID + `agent_ref`, audit report, hash chain, OTel export (+ promoted attrs), compare CLI, ToolHost reference coat |
+| **v0.3.4** | Onboarding guide, `report show`, flat core examples, Monitor/Break presets, capstone + examples 05–08 |
 
 ---
 

diff --git a/docs/architecture.md b/docs/architecture.md
@@ -38,8 +38,12 @@ flowchart LR
 | `aura/observers/` | Parallel subscribers |
 | `aura/exporters/` | JSONL summary, OTel JSONL |
 
-## Extension surface (roadmap)
+## Extension surface
 
-Type plugins, packaged observer presets (monitor, break — see [reference-tool-host-capstone.md](guides/reference-tool-host-capstone.md)), HTTP fleet API — see [ROADMAP.md](ROADMAP.md).
+**Shipped:** ToolHost protocol, Monitor + Break observer presets, OTel export with promoted span attributes, sequencer `when` guards — see [reference-tool-host-capstone.md](guides/reference-tool-host-capstone.md).
+
+**Roadmap:** Limit preset, signed audit packs, HTTP fleet API, brain/memory/MCP type plugins — [ROADMAP.md](ROADMAP.md).
+
+Input-layer model (brain, memory, tools as adapters): [stack-position.md](stack-position.md).
 
 **Principle:** new capabilities emit or subscribe to the spine — core loop unchanged.
diff --git a/docs/aura-levels.md b/docs/aura-levels.md
@@ -1,5 +1,7 @@
 # AURA Levels
 
+> **Optional / roadmap** — autonomy tiers; enforcement UX tracked in [#27](https://github.com/ARPAHLS/aura/issues/27). Today use postures in [using-aura.md](using-aura.md) and sequencer gates.
+
 **Permissioned autonomy** — not binary on/off.
 
 From [narrative.md](narrative.md). Enforced by Spectrum + conformance engine + hook pipeline.

diff --git a/docs/comparison.md b/docs/comparison.md
@@ -155,7 +155,7 @@ OpenTelemetry and structured logging provide **telemetry primitives** — spans,
 ### Key differences
 
 * **Agent semantics**: AURA events carry **agent identity**, session mode, constitution violations, and conformance — not generic spans alone.
-* **Policy**: Logging does not enforce confirm-before-action or token budgets; AURA constraints do (v0.1 on explicit events; membrane intercept roadmap).
+* **Policy**: Logging does not enforce confirm-before-action or token budgets; AURA constraints do on wired egress paths (broader intercept planned).
 * **Complementary**: OTel exporter shipped (v0.3); audit trail maps to spans ([outputs.md](outputs.md), [ROADMAP](ROADMAP.md)).
 
 ---

diff --git a/docs/concepts.md b/docs/concepts.md
@@ -4,11 +4,18 @@ Plain-language model for AURA Harness.
 
 ## Agent
 
-A logical entity you run under AURA. Gets a permanent **`AURA-000n`** ID for audit. You can also give it a **name** (`agent1test`).
+A logical entity you run under AURA.
 
-Your own IDs (OpenAI assistant id, company id, etc.) live in the agent **`ids`** trailer — AURA does not replace them.
+| Field | Role |
+|---|---|
+| **`agent_ref`** | Stable slug for humans and CI, e.g. `acme/compliance-bot` |
+| **`aura_id`** | Internal ULID (default) or your supplied id |
+| **`name`** | Optional alias for lookup |
+| **`ids`** | Trailer for tenant, Skillware, and your external ids |
+
+Legacy profiles with `AURA-000n` ids still load. See [trust-paths.md](trust-paths.md).
 
-v0.2 fields: **`skills`**, **`sequencer`** spec, **`observers`** list.
+Profile fields also include **`skills`**, **`sequencer`** spec, **`observers`**, and **`rules`**.
 
 ## Session
 

diff --git a/docs/field-services.md b/docs/field-services.md
@@ -1,25 +1,27 @@
 # Field Services
 
+> **Optional reference** — not required for onboarding. See [INDEX.md](INDEX.md). For shipped observer behavior use [using-aura.md](using-aura.md) and [reference-tool-host-capstone.md](guides/reference-tool-host-capstone.md).
+
 The **twelve complementary services** that run **in parallel** with the agent loop — the coat, not bolt-ons.
 
-From [narrative.md](narrative.md). Implemented as **operation plugins** in `aura/ops/`, registered in [spec/capability.registry.json](../spec/capability.registry.json).
+Design language from [narrative.md](narrative.md). Operation ids live in [spec/capability.registry.json](../spec/capability.registry.json); packaged presets ship under `aura/observers/presets/`.
 
 ---
 
-| Service | What it does |
-|---|---|
-| **Monitor** | Loop state, tool calls, outputs, drift — continuously |
-| **Audit** | Record what, when, why, under which permissions — **always on (Job B)** |
-| **Track** | Task progress, resource use, retries, lineage across steps |
-| **Limit** | Budgets, rate caps, scope, AURA Level permissions |
-| **Safeguard** | Enforce guardrails from manifest, soul contract, memory layer, skill constitution, or elsewhere |
-| **Wake** | Restart stalled loops, re-queue work, resume |
-| **Break** | Stop infinite retries, circular reasoning, runaway tools |
-| **Conserve** | Reduce token waste — redundant calls, repeated failures |
-| **Recover** | Catch errors, retry logic, fallback paths |
-| **Remember** | Memory discipline — keep, compress, discard, persist |
-| **Learn** | Capture mistakes and outcomes for next iteration |
-| **Attach** | Modular extensions — skills, schedulers, observers |
+| Service | What it does | Status |
+|---|---|---|
+| **Monitor** | Loop state, tool calls, outputs, drift — continuously | **Shipped** — `preset: monitor` |
+| **Audit** | Record what, when, why, under which permissions — always on | **Shipped** — audit spine + export |
+| **Break** | Stop infinite retries, circular reasoning, runaway tools | **Shipped** — `preset: break` |
+| **Track** | Task progress, resource use, retries, lineage across steps | Planned |
+| **Limit** | Budgets, rate caps, scope, spectrum permissions | Planned |
+| **Safeguard** | Enforce guardrails from manifest and constitution | Partial — constraint engine + manifest merge |
+| **Wake** | Restart stalled loops, re-queue work, resume | Planned |
+| **Conserve** | Reduce token waste — redundant calls, repeated failures | Planned |
+| **Recover** | Catch errors, retry logic, fallback paths | Partial — sequencer retries |
+| **Remember** | Memory discipline — keep, compress, discard, persist | Planned (memory adapter) |
+| **Learn** | Capture mistakes and outcomes for next iteration | Planned |
+| **Attach** | Modular extensions — skills, schedulers, observers | **Shipped** — observers + Skillware host |
 
 ---
 
@@ -35,14 +37,14 @@ All three emit to the same **audit spine**.
 
 ---
 
-## Spectrum Toggle
+## Spectrum toggle (roadmap)
 
-Manifest `spectrum.services` selects which field services activate for a session. `audit` is non-optional in production profiles.
+Manifest `spectrum.services` will select which field services activate for a session. `audit` is non-optional in production profiles. Enforcement UX: [#27](https://github.com/ARPAHLS/aura/issues/27).
 
 ---
 
-## Attachments (Extensions)
+## Attachments (extensions)
 
 Beyond core twelve — observability modules, resource governors, temporal schedulers, event bridges, recovery playbooks. Registered as **op plugins** or **type plugins** — same extensibility model.
 
-See [architecture.md](architecture.md) · [outputs.md](outputs.md) · [spec/capability.registry.json](../spec/capability.registry.json)
+See [architecture.md](architecture.md) · [outputs.md](outputs.md) · [ROADMAP.md](ROADMAP.md)
diff --git a/docs/getting-started.md b/docs/getting-started.md
@@ -47,7 +47,7 @@ with ag.session() as run:
 print(run.exports)  # JSONL + summary paths
 ```
 
-## Sequencer example (v0.2)
+## Sequencer example
 
 ```python
 from aura import agent, configure
@@ -74,7 +74,7 @@ print(run.exports)
 
 Logs land in `~/.aura/sessions/` unless you configure project storage.
 
-## CLI
+## CLI (export & verify)
 
 ```bash
 aura agent create my-bot --purpose "research assistant"
@@ -127,5 +127,5 @@ See [examples/](../examples/README.md) — including [sequencer_pipeline.py](../
 - [skillware-integration.md](skillware-integration.md) — Skillware host
 - [concepts.md](concepts.md) — agent, session, sequencer
 - [comparison.md](comparison.md) — vs orchestrators and eval harnesses
-- [ROADMAP.md](ROADMAP.md) — what comes after v0.2
+- [ROADMAP.md](ROADMAP.md) — shipped vs deferred
 - [architecture.md](architecture.md) — modules and data flow
diff --git a/docs/glossary.md b/docs/glossary.md
@@ -1,5 +1,7 @@
 # Glossary
 
+> **Optional reference** — terminology including ARPA-internal names. Product path: [concepts.md](concepts.md) and [INDEX.md](INDEX.md).
+
 | Term | Meaning |
 |---|---|
 | **αύρα / AVRA / AURA** | Runtime coat / harness / field around the loop |

diff --git a/docs/guides/README.md b/docs/guides/README.md
@@ -6,6 +6,6 @@ Long-form integration and usage guides.
 |---|---|
 | [aura-on-skillware.md](aura-on-skillware.md) | Reference adapter deep dive (Skillware as one ToolHost impl) |
 | [reference-tool-host-capstone.md](reference-tool-host-capstone.md) | **360° tool-host checklist** — membrane before/at/after, spine events, runnable paths |
-| [skillware-follow-ups.md](skillware-follow-ups.md) | Post–#12 backlog (CI, flat examples, limit preset) |
+| [skillware-follow-ups.md](skillware-follow-ups.md) | Post–#12 backlog (CI, limit preset, docs sweep) |
 
 See also: [using-aura.md](../using-aura.md), [skillware-integration.md](../skillware-integration.md).
diff --git a/docs/guides/aura-on-skillware.md b/docs/guides/aura-on-skillware.md
@@ -273,6 +273,6 @@ See [skillware-follow-ups.md](skillware-follow-ups.md) for post–#12 backlog: f
 
 ## Related
 
-- [using-aura.md](../using-aura.md) — membrane and personas  
+- [using-aura.md](../using-aura.md) — membrane and postures  
 - [stack-position.md](../stack-position.md) — where AURA fits in the agent stack  
 - [Skillware repository](https://github.com/arpahls/skillware)
diff --git a/docs/guides/skillware-follow-ups.md b/docs/guides/skillware-follow-ups.md
@@ -25,7 +25,7 @@ Track these **after** closing the reference ToolHost epic ([#12](https://github.
 | **Flat examples restructure** ([#21](https://github.com/ARPAHLS/aura/issues/21)) | Align paths referenced in docs after examples layout change (remainder of [#41](https://github.com/ARPAHLS/aura/issues/41)) |
 | **Multi-provider comparison page** | One doc comparing Ollama vs GPT vs Claude vs Gemini with the same skill chain (extends capstone) |
 | **Skill catalog appendix** | Table of bundled Skillware skills: offline vs API, suggested AURA guardrails |
-| **Docs sweep** ([#13](https://github.com/ARPAHLS/aura/issues/13), [#14](https://github.com/ARPAHLS/aura/issues/14), [#19](https://github.com/ARPAHLS/aura/issues/19), [#20](https://github.com/ARPAHLS/aura/issues/20)) | Cross-link INDEX, ROADMAP, integration READMEs |
+| **Docs sweep** ([#14](https://github.com/ARPAHLS/aura/issues/14), [#19](https://github.com/ARPAHLS/aura/issues/19), [#20](https://github.com/ARPAHLS/aura/issues/20)) | Cross-link INDEX, ROADMAP, integration READMEs — onboarding ([#13](https://github.com/ARPAHLS/aura/issues/13)) shipped |
 
 ---
 

diff --git a/docs/narrative.md b/docs/narrative.md
@@ -1,5 +1,7 @@
 # AURA Harness
 
+> **Optional / vision** — long-form ARPA narrative. For product usage start at [onboarding.md](onboarding.md) and [INDEX.md](INDEX.md).
+
 **The runtime coat around your agent loops.**
 
 *By ARPA Hellenic Logical Systems — [arpacorp.net](https://arpacorp.net)*

diff --git a/docs/onboarding.md b/docs/onboarding.md
@@ -1,6 +1,6 @@
 # Onboarding — use AURA correctly
 
-Step-by-step path from install to a reviewable session receipt. For membrane detail see [using-aura.md](using-aura.md); for terms see [concepts.md](concepts.md).
+Step-by-step path from install to a reviewable session receipt. Full doc map: [INDEX.md](INDEX.md). For membrane detail see [using-aura.md](using-aura.md); for terms see [concepts.md](concepts.md).
 
 ---
 

diff --git a/docs/outputs.md b/docs/outputs.md
@@ -2,6 +2,8 @@
 
 What a session produces on close (v0.3).
 
+Identity fields on export: [trust-paths.md](trust-paths.md). Session-close workflow: [using-aura.md](using-aura.md).
+
 ---
 
 ## Per session

diff --git a/docs/skillware-integration.md b/docs/skillware-integration.md
@@ -237,7 +237,7 @@ Use session export `.summary.json` `conformance.passed` in CI to fail builds whe
 
 ## Related
 
-- [using-aura.md](using-aura.md) — membrane and personas
+- [using-aura.md](using-aura.md) — membrane and postures
 - [sequencer.md](sequencer.md) — step model and gates
 - [integrations/skillware/](../integrations/skillware/) — reference scripts and README
 - [Skillware repo](https://github.com/arpahls/skillware) — skill registry, manifests, CLI
-Original file line number
+Diff line change
@@ Expand Up / @@ -2,6 +2,8 @@ @@
     What a session produces on close (v0.3).
+    Identity fields on export: [trust-paths.md](trust-paths.md). Session-close workflow: [using-aura.md](using-aura.md).
     ---
     ## Per session
@@ Expand Down @@