docs: build comprehensive audience-first documentation

Author: rand

README.md

@@ -158,10 +158,27 @@ rlm-core powers these projects:
 
 ## Documentation
 
-- [Unified Library Design](docs/unified-rlm-library-design.md) - Architecture overview
-- [Migration Spec: recurse](docs/migration-spec-recurse.md) - Go integration guide
-- [Migration Spec: rlm-claude-code](docs/migration-spec-rlm-claude-code.md) - Python integration guide
-- [Implementation Roadmap](docs/implementation-roadmap.md) - Development phases
+### Start Here
+- [Documentation Portal](docs/README.md) - Role-based index and workflow-oriented navigation.
+- [User Guide](docs/user-guide/README.md) - New user to power-user guidance.
+- [Developer Guide](docs/developer-guide/README.md) - Setup, gates, and contribution workflow.
+- [Internals](docs/internals/README.md) - Architecture, OODA flow, and module map.
+- [Troubleshooting](docs/troubleshooting/README.md) - Incident triage and diagnostics checklists.
+
+### Conceptual and Architecture
+- [Concepts](docs/concepts/README.md) - Mental model and system vocabulary.
+- [Unified Library Design](docs/unified-rlm-library-design.md) - Long-form architecture background.
+- [Lean Formal Verification Design](docs/lean-formal-verification-design.md) - Formal methods design rationale.
+- [ADR Index](docs/adr/) - Decision records and architectural tradeoffs.
+
+### Specifications and Planning
+- [Spec Contracts](docs/spec/) - Canonical feature-level specifications (SPEC-20 through SPEC-27).
+- [Execution Plan](docs/execution-plan/README.md) - Program execution, evidence, and governance operations.
+- [Implementation Roadmap](docs/implementation-roadmap.md) - Development phases.
+
+### Integration and Migration
+- [Migration Spec: recurse](docs/migration-spec-recurse.md) - Go integration plan.
+- [Migration Spec: rlm-claude-code](docs/migration-spec-rlm-claude-code.md) - Python/plugin integration plan.
 
 ## License
 

docs/README.md

@@ -0,0 +1,72 @@
+# Loop Documentation
+
+Welcome to the part of the project where we admit future-you exists.
+
+This documentation is organized by audience and workflow, not by who happened to write the last markdown file at 2:13 AM.
+
+## Choose Your Path
+
+| If you are... | Start here | Then go to |
+|---|---|---|
+| New to Loop | [User Guide](./user-guide/README.md) | [Workflow Recipes](./user-guide/workflow-recipes.md) |
+| Building features | [Developer Guide](./developer-guide/README.md) | [Quality Gates](./developer-guide/quality-gates.md) |
+| Debugging internals | [Internals](./internals/README.md) | [Troubleshooting](./troubleshooting/README.md) |
+| Looking for architecture rationale | [Concepts](./concepts/README.md) | [ADR Index](./adr/) |
+
+## Documentation Map
+
+### User-Facing
+- [User Guide](./user-guide/README.md): Start-to-finish guidance by skill level.
+- [Workflow Recipes](./user-guide/workflow-recipes.md): End-to-end task playbooks.
+- [Power User Playbook](./user-guide/power-user-playbook.md): Performance, scale, and control.
+
+### Developer-Facing
+- [Developer Guide](./developer-guide/README.md): Build and change Loop safely.
+- [Setup](./developer-guide/setup.md): Environment bootstrap.
+- [Quality Gates](./developer-guide/quality-gates.md): Tests, checks, governance.
+- [Contribution Workflow](./developer-guide/contribution-workflow.md): Branch-to-merge routine.
+
+### Architecture and Internals
+- [Concepts](./concepts/README.md): Mental models and design vocabulary.
+- [Internals](./internals/README.md): Runtime architecture and module boundaries.
+- [Architecture](./internals/architecture.md): System structure and data flow.
+- [OODA + Execution Flow](./internals/ooda-and-execution.md): Observe/Orient/Decide/Act mapping.
+- [Module Map](./internals/module-map.md): Where behavior actually lives.
+
+### Operational and Recovery
+- [Troubleshooting](./troubleshooting/README.md): Fast diagnosis and fix paths.
+- [Common Issues](./troubleshooting/common-issues.md): Known failure patterns.
+- [Diagnostics Checklist](./troubleshooting/diagnostics-checklist.md): Structured incident capture.
+
+### Reference and Specifications
+- [Specification Set](./spec/): Canonical feature contracts (SPEC-20 through SPEC-27).
+- [Execution Plan](./execution-plan/README.md): Program-level planning, evidence, and governance.
+- [Architecture Decisions](./adr/): Long-lived technical decisions and context.
+- [Glossary](./glossary.md): Shared terms and definitions.
+- [Writing Style](./writing-style.md): Documentation voice and formatting contract.
+
+## Documentation Principles
+
+1. Behavior over aspiration: document what exists and runs.
+2. Workflow over component: prefer "how to get outcome X" over "here is a list of modules".
+3. Reproducibility over vibes: include concrete commands and expected outputs.
+4. Honesty over smoothness: if something is sharp, say so plainly.
+5. Friendly precision: direct writing, with enough personality that reading it does not feel like filing taxes.
+
+## Suggested Reading Order
+
+1. [Concepts: Mental Model](./concepts/mental-model.md)
+2. [User Guide](./user-guide/README.md)
+3. [Developer Setup](./developer-guide/setup.md)
+4. [Internals Architecture](./internals/architecture.md)
+5. [Troubleshooting](./troubleshooting/README.md)
+
+## Scope Note
+
+The docs in this folder are the operational surface. Deep design history and migration rationale still live in long-form docs such as:
+- `docs/unified-rlm-library-design.md`
+- `docs/lean-formal-verification-design.md`
+- `docs/migration-spec-recurse.md`
+- `docs/migration-spec-rlm-claude-code.md`
+
+Those are excellent references; they are not where a newcomer should start unless they really enjoy scrolling.

docs/concepts/README.md

@@ -0,0 +1,20 @@
+# Concepts
+
+This section explains how to think about Loop before you care about where any specific function lives.
+
+## Start Here
+
+- [Mental Model](./mental-model.md)
+
+## Conceptual Layers
+
+1. **Intent Layer**: User goals and jobs-to-be-done.
+2. **Orchestration Layer**: Complexity classification, decomposition, and execution strategy.
+3. **Evidence Layer**: Memory, traces, and verification artifacts.
+4. **Assurance Layer**: Tests, policy gates, compatibility checks, and release controls.
+
+## Why This Matters
+
+If you skip conceptual grounding and start from implementation details, everything feels random.
+
+If you start here, the codebase reads like a system instead of a haunted attic.

docs/concepts/mental-model.md

@@ -0,0 +1,48 @@
+# Loop Mental Model
+
+Loop is a runtime for turning "this problem is too big" into "this is a sequence of tractable decisions with receipts".
+
+## The Core Loop
+
+1. **Observe**
+- Collect user intent, context state, and relevant file/tool signals.
+
+2. **Orient**
+- Classify complexity and decide whether recursive orchestration is warranted.
+- Externalize context into a structure that modules can reason over.
+
+3. **Decide**
+- Choose model, budget posture, decomposition strategy, and validation depth.
+
+4. **Act**
+- Execute module flows, produce outputs, persist traces/evidence, and report outcomes.
+
+The cycle repeats until quality and completion criteria are met.
+
+## Design Tensions
+
+### Speed vs Certainty
+- Fast path gives quick iteration.
+- Deep path increases cost but catches mistakes earlier.
+- Loop makes this tradeoff explicit via mode selection and policy gates.
+
+### Flexibility vs Reproducibility
+- Dynamic runtime behaviors are useful.
+- Production workflows need deterministic checks.
+- Loop uses typed signatures, structured events, and governance gates to keep both.
+
+### Automation vs Human Control
+- Automation scales throughput.
+- Humans still own risk decisions.
+- Loop supports policy-based enforcement and evidence-first handoff.
+
+## What "Good" Looks Like
+
+A healthy Loop workflow has:
+- Clear intent capture.
+- Explicit strategy selection.
+- Traceable execution decisions.
+- Evidence for claims.
+- Reproducible quality checks.
+
+Or, put differently: fewer mysteries and fewer surprises during push.

docs/developer-guide/README.md

@@ -0,0 +1,23 @@
+# Developer Guide
+
+This guide is for contributors changing code in Loop itself.
+
+## Start Here
+
+1. [Setup](./setup.md)
+2. [Quality Gates](./quality-gates.md)
+3. [Contribution Workflow](./contribution-workflow.md)
+
+## Development Contract
+
+1. Build and tests must pass locally.
+2. Governance gates must pass.
+3. Behavior changes must be documented.
+4. Evidence must exist for critical claims.
+5. Push-ready means actually pushed, not emotionally prepared.
+
+## Scope Notes
+
+- Runtime planning and multi-session execution rules: `docs/execution-plan/`
+- Feature contracts: `docs/spec/`
+- Architecture rationale: `docs/adr/`

docs/developer-guide/contribution-workflow.md

@@ -0,0 +1,52 @@
+# Contribution Workflow
+
+A disciplined path from idea to merged, reproducible change.
+
+## 1. Intake and Scope
+
+1. Understand the user/job outcome.
+2. Confirm existing issue context (`bd ready`, `bd show <id>`).
+3. Claim work (`bd update <id> --status in_progress`).
+
+## 2. Implement in Small Increments
+
+1. Make scoped changes.
+2. Add or update tests with behavior changes.
+3. Keep docs aligned in the same change set.
+
+## 3. Validate Continuously
+
+1. Run targeted tests during development.
+2. Run `make check` before commit.
+3. Run governance gates before push.
+
+## 4. Close Work Properly
+
+1. `bd close <id> --reason "implemented + verified"`
+2. `bd sync`
+3. `git add ...`
+4. `git commit -m "type: summary"`
+5. `git push`
+
+## 5. Verify Landing
+
+1. `git status` shows clean working tree.
+2. Branch is up to date with remote.
+3. Issue tracker reflects final status.
+
+## Documentation Requirements
+
+For notable changes, include:
+1. What changed.
+2. Why it changed.
+3. How it was validated.
+4. Where evidence lives.
+
+## Anti-Patterns to Avoid
+
+1. Large mixed-purpose commits.
+2. Undocumented behavior changes.
+3. Skipping gates because "it worked once locally".
+4. Leaving local-only commits at session end.
+
+In short: ship predictably, not poetically.

docs/developer-guide/quality-gates.md

@@ -0,0 +1,65 @@
+# Quality Gates
+
+Loop uses layered quality gates: local correctness, policy enforcement, and release-grade verification.
+
+## Gate Layers
+
+### Layer 1: Local correctness
+
+```bash
+make check
+```
+
+Runs:
+- Type checks
+- Tests
+
+### Layer 2: Governance review
+
+```bash
+./scripts/dp review --json
+./scripts/dp verify --json
+```
+
+Purpose:
+- Consistent, machine-readable status
+- Standardized workflow enforcement
+
+### Layer 3: Enforcement gates
+
+```bash
+./scripts/dp enforce pre-commit --policy dp-policy.json --json
+./scripts/dp enforce pre-push --policy dp-policy.json --json
+```
+
+Purpose:
+- Block policy violations before commit/push boundaries
+
+## Required Interpretation Rules
+
+1. Exit code is authoritative.
+2. JSON `ok` is authoritative.
+3. Warnings are not failures, but they are not decorative either.
+
+## Failure Protocol
+
+When a gate fails:
+1. Re-run same command to confirm.
+2. Isolate first failing step.
+3. Fix root cause.
+4. Re-run full gate chain.
+
+No partial-pass narratives.
+
+## Suggested Daily Rhythm
+
+1. During iteration: targeted tests.
+2. Before commit: `make check`.
+3. Before push: full `dp` enforcement chain.
+
+## Evidence Logging
+
+For major changes, capture outputs into:
+- `docs/execution-plan/evidence/<date>/<scope>/...`
+
+This makes reviews faster and postmortems less fictional.

docs/developer-guide/setup.md

@@ -0,0 +1,72 @@
+# Developer Setup
+
+## Toolchain
+
+Install and verify:
+
+```bash
+rustc --version
+python3 --version
+go version
+uv --version
+```
+
+Recommended minimums:
+- Rust 1.75+
+- Python 3.11+
+- Go 1.22+
+
+## Repository Bootstrap
+
+```bash
+git clone https://github.com/rand/loop.git
+cd loop
+```
+
+Build Rust core:
+
+```bash
+cd rlm-core
+cargo build --release
+```
+
+## Python Binding Setup
+
+```bash
+cd /Users/rand/src/loop/rlm-core/python
+uv sync
+uv run maturin develop --release
+```
+
+## Go Binding Setup
+
+```bash
+cd /Users/rand/src/loop/rlm-core
+test -f target/release/librlm_core.a || cargo build --release --lib
+
+cd /Users/rand/src/loop/rlm-core/go/rlmcore
+go test ./...
+```
+
+## Fast Sanity Check
+
+From repository root:
+
+```bash
+make check
+./scripts/dp review --json
+```
+
+If both pass, you have a working developer environment.
+
+## Environment Tips
+
+1. Run commands from repository root unless a doc says otherwise.
+2. Prefer offline-capable iterations where practical.
+3. Keep evidence files in `docs/execution-plan/evidence/...` for nontrivial validations.
+
+## When Setup Fails
+
+Go directly to:
+- [Common Issues](../troubleshooting/common-issues.md)
+- [Diagnostics Checklist](../troubleshooting/diagnostics-checklist.md)