docs: align README-linked docs with current framing

cli/README.md

@@ -1,8 +1,13 @@
-# ao - AgentOps Software Factory CLI
+# ao - AgentOps CLI
 
-`ao` is the explicit operator surface for AgentOps when you want the repo to
-behave like a software factory instead of a loose collection of agent
-primitives.
+`ao` is the automation and control-plane surface for AgentOps. Use it when you
+want the operational layer to run headlessly: stage briefings, inspect
+bookkeeping, drive repeatable flows, or run overnight compounding without
+staying inside an interactive skill.
+
+One important lane inside the CLI is the software-factory surface. That lane
+makes the work order, delivery flow, and closeout explicit instead of leaving
+them implicit in chat state.
 
 The short version:
 
@@ -10,17 +15,19 @@ The short version:
 ao quick-start
 ao factory start --goal "fix auth startup"
 ao rpi phased "fix auth startup"
-ao codex stop
+ao overnight report
 ```
 
 That lane keeps four concerns explicit:
 
 1. `ao factory start` surfaces a bounded work order by compiling a goal-time
    briefing when the corpus supports it, then running Codex startup.
-2. `ao rpi phased` runs the delivery line with fresh context per phase.
-3. `ao rpi status` lets the operator inspect long-running factory work.
-4. `ao codex stop` closes the flywheel so the session leaves behind learnings,
-   citations, and handoff state.
+2. `ao rpi phased` runs the delivery flow with fresh context per phase, and
+   `ao rpi status` lets the operator inspect long-running work.
+3. `ao overnight start` and `ao overnight report` run the private Dream flow
+   against the real local corpus and return a morning packet.
+4. `ao codex stop` and `ao flywheel close-loop` close the bookkeeping loop so
+   the session leaves behind learnings, citations, and handoff state.
 
 ## Install
 
@@ -37,15 +44,21 @@ ao quick-start
 # Start a goal with briefing-first runtime context
 ao factory start --goal "fix auth startup"
 
-# Run the delivery lane
+# Run the delivery flow
 ao rpi phased "fix auth startup"
+
+# Optional: set up and run a private overnight Dream
+ao overnight setup
+ao overnight start --goal "tighten auth startup"
+ao overnight report
 ```
 
 If you prefer the skill-first path, use `/rpi "fix auth startup"` after
 `ao factory start`.
 
 That's it. In Claude Code, `CLAUDE.md` remains the startup surface. The
-installed hooks stay silent and only prepare runtime state for the factory lane.
+installed hooks stay silent and only prepare runtime state for the higher-level
+flows.
 
 ## Operator Surfaces
 
@@ -64,11 +77,14 @@ can be captured as silent factory intake and staged for later explicit use.
 | `ao codex start` | Lower-level hookless Codex startup |
 | `ao rpi phased "<goal>"` | CLI-first Discovery -> Implementation -> Validation lane |
 | `ao rpi status` | Monitor long-running phased work |
+| `ao overnight setup` | Detect host/runtime constraints and persist Dream config |
+| `ao overnight start --goal "<goal>"` | Run the local overnight compounding flow |
+| `ao overnight report` | Render the latest Dream summary and council state |
 | `ao codex stop` | Close the loop explicitly at session end |
 
-## Lower-Level Substrate
+## Underlying Primitives
 
-These commands remain important, but they sit below the factory lane:
+These commands remain important, but they sit below the higher-level flows:
 
 - `ao knowledge` for belief/playbook/briefing refresh and gap reporting
 - `ao context assemble` for a five-section task briefing
@@ -78,5 +94,7 @@ These commands remain important, but they sit below the factory lane:
 ## Reference
 
 - [Software Factory Surface](../docs/software-factory.md)
+- [Dream Run Contract](../docs/contracts/dream-run-contract.md)
+- [Dream Report Contract](../docs/contracts/dream-report.md)
 - [Session Lifecycle](../docs/workflows/session-lifecycle.md)
 - [CLI Reference](docs/COMMANDS.md)

cli/embedded/skills/standards/references/behavioral-discipline.md

@@ -72,6 +72,69 @@ Turn requests into verifiable outcomes.
 - "Improve this skill" becomes "update the contract, validate skill integrity, then check the shipped runtime copy."
 - "Clean up the hook" becomes "preserve the contract, edit only the required files, then run the hook/doc parity gate."
 
+## Before/After Examples
+
+### Example 1: Hidden Assumptions
+
+**Request:** "Make search faster"
+
+**Before**
+
+- picks one meaning of "faster" without clarifying
+- adds caching, async work, and new knobs all at once
+- verifies only that the code still runs
+
+**After**
+
+- asks whether "faster" means latency, throughput, or perceived speed
+- picks the smallest change that matches the answer
+- verifies against the metric that actually mattered
+
+### Example 2: Overbuilt Solution
+
+**Request:** "Add a discount helper"
+
+**Before**
+
+- introduces strategies, factories, and extension points for a one-off need
+- adds flexibility nobody asked for
+
+**After**
+
+- starts with a small helper that solves the current requirement
+- defers abstraction until a real second use case exists
+
+### Example 3: Drive-By Editing
+
+**Request:** "Fix empty emails crashing the validator"
+
+**Before**
+
+- rewrites adjacent validation logic
+- edits comments and formatting unrelated to the bug
+- leaves a large diff for a narrow request
+
+**After**
+
+- adds a reproducer for the empty-email case
+- fixes only the email path plus cleanup caused by that fix
+- records unrelated cleanup separately instead of bundling it into the patch
+
+### Example 4: Weak Proof
+
+**Request:** "Improve this AgentOps skill"
+
+**Before**
+
+- edits the skill doc and stops
+- forgets the mirrored Codex artifact or validation step
+
+**After**
+
+- updates the shared contract and the checked-in Codex copy
+- regenerates affected artifact metadata when needed
+- runs the relevant validation commands before claiming completion
+
 ## Review Questions
 
 Use these four questions when validating a plan, patch, or PR:

docs/ARCHITECTURE.md

@@ -1,10 +1,14 @@
 # AgentOps Architecture
 
-> Context quality is the primary lever for agent output quality. Orchestrate what enters each window, compound what comes out.
+> AgentOps is the operational layer for coding agents. Publicly it sells bookkeeping, validation, primitives, and flows; technically it compiles raw session signal into better next context.
 
 ## Overview
 
-AgentOps is a skills plugin that orchestrates context across agent windows and compounds results through a knowledge flywheel — each session is smarter than the last.
+AgentOps is a repo-native operating layer that combines interactive skills, the
+`ao` control plane, hooks, and `.agents/` artifacts. The public product story is
+bookkeeping, validation, primitives, and flows. The technical mechanism is a
+context compiler plus knowledge flywheel: capture what happened, validate it,
+store it with provenance, and surface it back when the next task needs it.
 
 The architecture rests on five pillars. Each one is independent — you can use any skill standalone — but together they form a recursive system that gets smarter with every cycle.
 
@@ -33,7 +37,11 @@ Three principles drive every architectural decision:
 
 **Least-privilege context loading.** Each agent receives only the context necessary for its task. Research gets prior knowledge. Plan gets a 500-token research summary. Crank workers get fresh context per wave with zero bleed-through. Vibe gets recent changes only. Phase summaries compress output between phases to prevent signal-to-noise collapse. The context window is treated as a security boundary — nothing enters without scoping.
 
-**The cycle is the product.** No single skill is the value. The compounding loop — discovery, implementation, validation, learn, repeat — makes each successive context window smarter than the last. Post-mortem doesn't just extract learnings; it proposes the next cycle's work. The system feeds itself.
+**The cycle is the product.** No single skill is the value. Bookkeeping,
+validation, primitives, and flows only matter when they turn into a repeatable
+loop: discovery, implementation, validation, learn, repeat. Post-mortem
+doesn't just extract learnings; it proposes the next cycle's work. The system
+feeds itself.
 
 ---
 
@@ -172,7 +180,8 @@ Deep dive: [how-it-works.md](how-it-works.md) — Ralph Wiggum Pattern, agent ba
 
 ## Pillar 4: Knowledge Flywheel
 
-The learning model. Automated extraction → quality gates → tiered storage → retrieval → injection → compounding.
+The bookkeeping and compounding model. Automated extraction -> quality gates ->
+tiered storage -> retrieval -> injection -> compounding.
 
 ```
   Sessions → Transcripts → Forge → Pool → Promote → Knowledge
@@ -236,7 +245,12 @@ The flywheel is curation, not just storage.
 └── tooling/       # Tooling documentation
 ```
 
-Knowledge artifacts are the system's long-term memory. Future `/research` commands discover them via file pattern matching, semantic search (`ao forge`), or Smart Connections MCP (if available). Freshness decay ensures stale artifacts lose priority over time — the system forgets what's no longer relevant. Quality gates prevent low-confidence or context-specific learnings from polluting the shared knowledge base.
+Knowledge artifacts are the system's long-term bookkeeping substrate. Future
+`/research` commands discover them via file pattern matching, semantic search
+(`ao forge`), or Smart Connections MCP (if available). Freshness decay ensures
+stale artifacts lose priority over time, and quality gates prevent
+low-confidence or context-specific learnings from polluting the shared
+knowledge base.
 
 Deep dive: [knowledge-flywheel.md](knowledge-flywheel.md) — flywheel mechanics. [the-science.md](the-science.md) — formal model, decay rates, limits to growth, and the scale-aware condition `ρ·σ(K,t) > δ + φ·K - I(t)/K`.
 
@@ -349,12 +363,12 @@ Skills span six tiers. Each level composes the ones below it.
 
 | Tier | Skills | Purpose |
 |------|--------|---------|
-| **Orchestration** | `/rpi`, `/council`, `/crank`, `/swarm`, `/codex-team`, `/evolve` | Multi-phase workflows |
+| **Orchestration** | `/rpi`, `/council`, `/crank`, `/swarm`, `/codex-team`, `/evolve` | Multi-phase flows |
 | **Team** | `/implement` | Single issue, full lifecycle |
 | **Solo** | `/research`, `/plan`, `/vibe`, `/pre-mortem`, `/post-mortem`, `/retro`, etc. | Standalone use |
 | **Library** | `beads`, `standards`, `shared` | Reference docs loaded by other skills |
 | **Background** | `inject`, `extract`, `forge`, `provenance`, `ratchet`, `flywheel` | Hook-triggered, invisible |
-| **Meta** | `using-agentops` | Workflow guide, auto-injected |
+| **Meta** | `using-agentops` | Flow guide, auto-injected |
 
 ### Subagents
 
@@ -395,7 +409,8 @@ The custom agents fill the gap:
 
 ### ao CLI Integration
 
-For full workflow orchestration, skills integrate with the ao CLI:
+For full flow orchestration and headless automation, skills integrate with the
+`ao` CLI:
 
 | Skill | ao Command |
 |-------|------------|
@@ -405,6 +420,9 @@ For full workflow orchestration, skills integrate with the ao CLI:
 | `/implement` | `ao context assemble`, `ao lookup`, `ao ratchet record` |
 | `/crank` | `ao rpi phased`, `ao ratchet`, `ao flywheel status` |
 
+Dream is binary-first today: `ao overnight setup|start|report` expose the
+overnight flow even before a dedicated `/dream` skill exists.
+
 ---
 
 ## Session Hooks

docs/FAQ.md

@@ -2,15 +2,20 @@
 
 ## Why not just use my coding agent directly?
 
-Without AgentOps, every session starts from scratch. Your agent doesn't remember what failed last time, doesn't validate its plan before coding, doesn't check its code with a second opinion, and doesn't capture what it learned. You fill those gaps manually — re-explaining context, reviewing code, tracking what changed. With AgentOps, the system handles context, validation, and memory. You manage the roadmap.
+Without AgentOps, every session starts from scratch. Your agent doesn't remember
+what failed last time, doesn't validate its plan before coding, doesn't check
+its code with a second opinion, and doesn't capture what it learned. You fill
+those gaps manually — re-explaining context, reviewing code, tracking what
+changed. With AgentOps, the system handles bookkeeping, validation, and
+repeatable flows. You manage the roadmap.
 
 ## How does this compare to other approaches?
 
 | Approach | What it does well | What AgentOps adds |
 |----------|------------------|--------------------|
-| **Direct agent use** (Claude Code, Cursor, Copilot) | Full autonomy, simple to start | Multi-model councils, fresh-context waves, and knowledge that compounds across sessions. A bare agent starts fresh each session; ours extracts learnings and applies them next time. |
-| **Custom prompts** (.cursorrules, CLAUDE.md) | Flexible, version-controlled | Static instructions don't compound. The flywheel auto-extracts learnings and injects them back. `/post-mortem` proposes changes to the tools themselves. |
-| **Agent orchestrators** (CrewAI, AutoGen, LangGraph) | Multi-language task scheduling | Those choreograph sequential tasks; we compose parallel waves with validation at every stage. No external state backend — all learnings are git-tracked. |
+| **Direct agent use** (Claude Code, Cursor, Copilot) | Full autonomy, simple to start | Bookkeeping, validation, and flows that compound across sessions. A bare agent starts fresh each session; AgentOps extracts learnings and reuses them next time. |
+| **Custom prompts** (.cursorrules, CLAUDE.md) | Flexible, version-controlled | Static instructions don't compound. AgentOps turns sessions into curated bookkeeping and injects the useful parts back at the right time. |
+| **Agent orchestrators** (CrewAI, AutoGen, LangGraph) | Multi-language task scheduling | Those choreograph sequential tasks; we add repo-native bookkeeping, validation gates, and fresh-context waves without requiring a hosted state backend. |
 | **CI/CD gates** (GitHub Actions, pre-commit) | Automated, industry standard | Gates run after code is written. Ours run before coding (`/pre-mortem`) and before push (`/vibe`). Failures retry with context, not human escalation. |
 
 ## What data leaves my machine?
@@ -30,7 +35,7 @@ Run `/product` to generate a `PRODUCT.md` describing your mission, personas, and
 - **Single primary author so far.** The system works but hasn't been stress-tested across diverse codebases and team sizes. Looking for early adopters willing to break things.
 - **Quality pool can over-promote.** Context-specific patterns sometimes get promoted as general knowledge. Freshness decay helps but doesn't fully solve stale injection.
 - **Retry loops cap at 3.** If a council or crank wave fails three times, the system surfaces the failure to you rather than looping forever. This is intentional but means some edge cases need human judgment.
-- **Knowledge curation is imperfect.** Freshness decay prevents the worst staleness, but the scoring heuristics (specificity, actionability, novelty) are tuned for one author's workflow. Your mileage may vary.
+- **Knowledge curation is imperfect.** Freshness decay prevents the worst staleness, but the scoring heuristics (specificity, actionability, novelty) are tuned for one operator's corpus and working style. Your mileage may vary.
 
 ## How does AgentOps handle subagent nesting?
 

docs/INDEX.md

@@ -17,7 +17,7 @@
 ## Architecture
 
 - [How It Works](how-it-works.md) — Brownian Ratchet, Ralph Wiggum Pattern, agent backends, hooks, context windowing
-- [Software Factory Surface](software-factory.md) — Explicit operator surface connecting briefings, RPI lanes, and loop closure
+- [Software Factory Surface](software-factory.md) — Explicit automation surface for briefings, RPI flows, and operator-controlled closeout
 - [Architecture](ARCHITECTURE.md) — System design and component overview
 - [Architecture Folder Index](architecture/README.md) — Architecture subdocs overview
 - [Codex Hookless Lifecycle](architecture/codex-hookless-lifecycle.md) — Runtime-aware lifecycle fallback for Codex when hooks are unavailable
@@ -59,7 +59,7 @@
 ## Concepts
 
 - [Philosophy](philosophy.md) — Five validated principles for building with coding agents, with evidence from five months of production use
-- [Context Lifecycle Contract](context-lifecycle.md) — The three-gap contract for judgment validation, durable learning, and loop closure
+- [Context Lifecycle Contract](context-lifecycle.md) — Internal proof contract behind the public bookkeeping, validation, primitives, and flows story
 - [Knowledge Flywheel](knowledge-flywheel.md) — How every session makes the next one smarter
 - [The Science](the-science.md) — Research behind knowledge decay and compounding
 - [Brownian Ratchet](brownian-ratchet.md) — AI-native development philosophy
@@ -104,7 +104,7 @@
 
 ### L2 — Persistence
 
-- [L2 README](levels/L2-persistence/README.md) — Cross-session memory with .agents/
+- [L2 README](levels/L2-persistence/README.md) — Cross-session bookkeeping with `.agents/`
 - [Research](levels/L2-persistence/research.md) — Explore codebase and save findings
 - [Retro](levels/L2-persistence/retro.md) — Extract session learnings
 - [Demo: Research Session](levels/L2-persistence/demo/research-session.md) — Example persistent research

docs/SKILLS.md

@@ -2,11 +2,16 @@
 
 Complete reference for all 66 AgentOps skills (57 user-facing + 9 internal).
 
+Skills are the primitive layer of AgentOps. Higher-level entry points like
+`/implement`, `/validation`, `/rpi`, and `/evolve` compose those primitives
+into repeatable flows.
+
 **Behavioral Contracts:** Most skills include `scripts/validate.sh` behavioral checks to verify key features remain documented. Run `skills/<name>/scripts/validate.sh` when present, or the GOALS.yaml `behavioral-skill-contracts` goal to validate the full covered set.
 
 ## Skill Router (Start Here)
 
-Use this when you're not sure which skill to run. For a full workflow overview, run `/using-agentops`.
+Use this when you're not sure which skill to run. For a full flow overview, run
+`/using-agentops`.
 
 ```text
 What are you trying to do?
@@ -66,7 +71,7 @@ What are you trying to do?
 └─ "First time here" ────────────► /quickstart
 ```
 
-## Core Workflow Skills
+## Core Flow Skills
 
 ### /research
 

docs/context-lifecycle.md

@@ -1,12 +1,13 @@
 # Context Lifecycle Contract
 
 > Publicly, AgentOps sells bookkeeping, validation, primitives, and flows.
-> This page explains the internal lifecycle contract that proves those claims:
-> judgment validation, durable learning, and loop closure.
+> This page explains the internal proof gaps those promises have to close:
+> validation risk, bookkeeping decay, and loop closure.
 
 ## Internal Proof Contract
 
-Most coding-agent tooling is strong at prompt construction and agent routing. The failure mode comes after that:
+Most coding-agent tooling is strong at prompt construction and agent routing.
+The failure mode comes after that:
 
 1. **Validation** is missing. Internally, this gap is tracked as
    **judgment validation**: the agent chooses an approach without loading the
@@ -14,11 +15,13 @@ Most coding-agent tooling is strong at prompt construction and agent routing. Th
 2. **Bookkeeping** is missing. Internally, this gap is tracked as
    **durable learning**: solved problems come back as if they were never
    solved.
-3. **Closure** is missing. Internally, this gap is tracked as
-   **loop closure**: completed work does not reliably produce better next
-   work, better rules, or better future context.
+3. **Flows** are present, but they do not compound. Internally, this gap is
+   tracked as **loop closure**: completed work does not reliably produce better
+   next work, better rules, or better future context.
 
-AgentOps treats those three gaps as a lifecycle contract, not as separate features.
+AgentOps treats those three gaps as one lifecycle contract. Skills and CLI
+primitives are the operator surface; the proof obligation is that each cycle
+actually closes these gaps.
 
 ## Gap 1: Validation
 
@@ -72,7 +75,7 @@ AgentOps treats those three gaps as a lifecycle contract, not as separate featur
 
 - session amnesia between independent runs
 - stale or contradictory learnings swamping retrieval
-- "memory" systems that store notes without curation or reinforcement
+- bookkeeping systems that store notes without curation or reinforcement
 
 ## Gap 3: Closure
 
@@ -114,14 +117,14 @@ AgentOps treats those three gaps as a lifecycle contract, not as separate featur
 | Bookkeeping | Compile | `GOALS.md`, Compile checks | Daily maintenance of learning quality |
 | Closure | `/post-mortem` + finding compiler | `skills/post-mortem/SKILL.md`, `docs/contracts/finding-registry.md`, `docs/contracts/finding-compiler.md` | Learnings + next work harvested from completed work; reusable findings re-enter planning/review and compile into preventive artifacts |
 | Closure | task-validation compiled enforcement | `hooks/task-validation-gate.sh`, `.agents/constraints/index.json` | Task-validation executes active compiled constraints before completion is accepted |
-| Closure | flywheel close hook | `hooks/ao-flywheel-close.sh` | Stop-time feedback loop closure |
+| Closure | flywheel close hook | `hooks/ao-flywheel-close.sh` | Stop-time closure of the feedback loop |
 | Closure | goals / evolve | `GOALS.md`, flywheel-proof gate | Proof that the system compounds across sessions |
 
 ## What AgentOps Does Not Claim
 
 - It does not claim that prompt engineering or routing are unimportant.
 - It does not claim that every loop-closing behavior must be fully autonomous.
-- It does not claim that raw memory alone is enough; the contract depends on validation, curation, and re-use.
+- It does not claim that raw recall alone is enough; the contract depends on validation, curation, and re-use.
 - It does not claim that new runtime machinery should be invented when an existing command, hook, or gate already covers the gap.
 
 ## The Knowledge Ledger — Session-to-Session Flow

docs/how-it-works.md

@@ -4,7 +4,10 @@
 
 Parallel agents produce noisy output; councils filter it; ratchets lock progress so it can never regress.
 
-Publicly, AgentOps sells bookkeeping, validation, primitives, and flows. This page explains the internal mechanics beneath that story: the three-gap proof contract, the Brownian Ratchet, and the flywheel that makes sessions compound.
+Publicly, AgentOps sells bookkeeping, validation, primitives, and flows. This
+page explains the internal mechanics beneath that story: the proof gaps those
+promises must close, the Brownian Ratchet, and the flywheel that makes sessions
+compound.
 
 Think of the mechanics below as the substrate under the operator surface:
 briefings and startup context prepare the work order, RPI phases run the
@@ -19,13 +22,24 @@ The same split now applies to Dream:
 
 That matters most for overnight work. GitHub nightly is the public proof harness. `ao overnight` is the private local compounding engine.
 
-## The Three Gaps
+## The Proof Gaps
 
-AgentOps exists because most agent tooling leaves three gaps open after prompt construction and routing are solved. The runtime mechanics described on this page are organized around proving they are actually closed:
+AgentOps exists because most agent tooling leaves three gaps open after prompt
+construction and routing are solved. The runtime mechanics described on this
+page are organized around proving they are actually closed:
 
-1. **Judgment validation** — agents ship without risk context. Hooks and skills that challenge plans and implementations before they land (pre-mortem gate, `/vibe`, `/council`, task-validation gate).
-2. **Durable learning** — solved problems recur. The knowledge flywheel extracts, scores, promotes, and retrieves learnings so the same lesson is never re-paid (session-end forging, `ao forge`, `ao lookup`, maturity controls).
-3. **Loop closure** — completed work does not produce better next work. Post-mortems, finding registries, compiled constraints, and the flywheel close hook ensure every session leaves the environment smarter than it found it.
+1. **Validation gap** (internal label: judgment validation) — agents ship
+   without risk context. Hooks and skills challenge plans and implementations
+   before they land (pre-mortem gate, `/vibe`, `/council`, task-validation
+   gate).
+2. **Bookkeeping gap** (internal label: durable learning) — solved problems
+   recur. The knowledge flywheel extracts, scores, promotes, and retrieves
+   learnings so the same lesson is never re-paid (session-end forging,
+   `ao forge`, `ao lookup`, maturity controls).
+3. **Closure gap** (internal label: loop closure) — completed work does not
+   produce better next work. Post-mortems, finding registries, compiled
+   constraints, and the flywheel close hook ensure every session leaves the
+   environment smarter than it found it.
 
 The canonical contract is in [Context Lifecycle Contract](context-lifecycle.md). The sections below show how each runtime mechanism maps to one or more of these gaps.
 

docs/philosophy.md

@@ -6,7 +6,8 @@
 
 ## The Core Thesis
 
-Treat coding agents as fast, stateless workers inside a disciplined operating system — not as magical coworkers with reliable memory and judgment.
+Treat coding agents as fast, stateless workers inside a disciplined operating
+system — not as magical coworkers with reliable bookkeeping or self-validation.
 
 Good agent work comes from **context, boundaries, validation, and reusable lessons** — not from hoping the agent "just gets it."
 
@@ -14,7 +15,10 @@ Good agent work comes from **context, boundaries, validation, and reusable lesso
 
 ## Five Principles (Validated by Evidence)
 
-These are not opinions. Each principle was learned through failure, refined through iteration, and validated against five months of production use: 1,083 commits, 65 skills, 33 CI gates, and hundreds of agent sessions across multiple runtimes.
+These are not opinions. Each principle was learned through failure, refined
+through iteration, and validated against five months of production use: 1,083
+commits, 66 skills, 33 CI gates, and hundreds of agent sessions across multiple
+runtimes.
 
 ### 1. Context Timing Beats Context Volume
 
@@ -72,7 +76,7 @@ The formula:
 ```
 Capture what happened (post-mortem, forge, retro)
     → Extract what mattered (learnings, findings, patterns)
-    → Promote into beliefs and workflows (rules, playbooks, checks)
+    → Promote into beliefs, playbooks, and checks
     → Feed back into the next task (inject, session intelligence)
     → Repeat
 ```
@@ -85,7 +89,10 @@ This is not a feature. It is the architecture. Every skill, hook, and CLI comman
 
 An honest philosophy acknowledges its failure modes.
 
-AgentOps has 65 skills, 33 CI gates, and a 6-phase post-mortem. The operating system itself can become the bottleneck. Every validation gate that prevents a bug also adds latency. Every knowledge extraction step that feeds the flywheel also adds ceremony.
+AgentOps has 66 skills, 33 CI gates, and a 6-phase post-mortem. The operating
+system itself can become the bottleneck. Every validation gate that prevents a
+bug also adds latency. Every knowledge extraction step that feeds the flywheel
+also adds ceremony.
 
 The discipline is tuning, not adding:
 
@@ -104,4 +111,4 @@ When in doubt, remove. A system that does fewer things reliably compounds faster
 - [How It Works](how-it-works.md) — Brownian Ratchet, Ralph Wiggum Pattern, context windowing
 - [The Science](the-science.md) — Research foundations: MemRL, cache eviction, freshness decay
 - [Knowledge Flywheel](knowledge-flywheel.md) — The extraction and compounding pipeline
-- [Context Lifecycle](context-lifecycle.md) — The three-gap contract
+- [Context Lifecycle](context-lifecycle.md) — The internal proof contract behind bookkeeping, validation, primitives, and flows

docs/the-science.md

@@ -8,10 +8,10 @@
 
 This wasn't designed in a vacuum. It came from years of connecting dots across fields:
 
-1. **Knowledge OS** — The insight that git + files = institutional memory
+1. **Knowledge OS** — The insight that git + files can become a durable bookkeeping substrate
 2. **DevOps** — The Three Ways applied to knowledge, not just code
 3. **Cognitive Science** — Why 40% load is optimal (35 years of research)
-4. **MemRL** — Reinforcement learning for memory systems (2026)
+4. **MemRL** — Reinforcement learning for retrieval and utility-scoring systems (2026)
 5. **Thermodynamics** — The Brownian Ratchet as progress model
 
 Each piece validated the intuition. The math fell out naturally.
@@ -46,7 +46,9 @@ Week 4:  47%
 Week 8:  22%
 ```
 
-**Why this matters for AI:** Every Claude session starts at Week 0. There's no memory between sessions. You're always on the left side of the decay curve.
+**Why this matters for AI:** Every Claude session starts close to Week 0 unless
+the environment resurfaces prior work. Without bookkeeping plus retrieval,
+you're always on the left side of the decay curve.
 
 ### The Forgetting Curve
 
@@ -154,7 +156,7 @@ If your retrieval effectiveness times your citation rate exceeds 0.17 in self-su
 
 | Scenario | σ | ρ | σ × ρ | vs δ | Result |
 |----------|---|---|-------|------|--------|
-| No memory | 0 | 0 | 0 | < 0.17 | Decaying |
+| No bookkeeping or retrieval | 0 | 0 | 0 | < 0.17 | Decaying |
 | Store but don't retrieve | 0.1 | 0.1 | 0.01 | < 0.17 | Decaying |
 | Retrieve but don't use | 0.8 | 0.1 | 0.08 | < 0.17 | Decaying |
 | **AgentOps target** | 0.7 | 0.3 | 0.21 | > 0.17 | **Compounding** |