# v0.6.0 Documentation Pass — Design

**Date:** 2026-03-04
**Branch:** feat/gateway
**Release Target:** v0.6.0

---

## Goal

Refresh all public-facing documentation to accurately reflect the v0.6.0 release — including the Gateway feature, Composable Kernel Architecture, and Structured Plan Engine — with beautiful, example-rich pages that help users understand every major system.

---

## Section 1: Accuracy Fixes

### README.md
- Test count: `1001 tests` → `1,340 tests`
- File count: `139 files` → `173 files`
- Package count: `18 packages` → `19 packages`
- Update version references to v0.6.0
- Add Gateway and Composable Kernel to capability highlights

### CLAUDE.md
- File count: `173 files` → `171 files` (verify via `bun test --reporter=verbose | wc -l` or equivalent)
- Update project status header to v0.6.0 with summary of this release's major features

### Landing Page (`apps/docs/src/content/docs/index.mdx`)
- Stats bar: `1000+ Tests` → `1,340 Tests`
- Stats bar: `17 packages` (if stale) → `19 packages`
- Add Gateway and Composable Kernel to feature cards
- Update comparison cards if any numbers are stale

### CHANGELOG.md
- Move `[Unreleased]` → `[0.6.0] - 2026-03-04`
- Ensure both Composable Kernel Architecture and Structured Plan Engine entries are present
- Add summary line at top of section

---

## Section 2: New Feature Pages

### `apps/docs/src/content/docs/concepts/composable-kernel.md` (NEW)
The Composable Kernel Architecture is a major internal architecture shift that also surfaces as a user-facing extensibility API. This page covers:
- What a ThoughtKernel is — the single-step reasoning algorithm contract
- KernelState — immutable state container (context, steps, metadata)
- KernelRunner — universal execution loop with embedded tool call guard and KernelHooks
- KernelHooks — centralized EventBus wiring (ToolCallCompleted, ReasoningStepCompleted)
- How all 5 built-in strategies use `runKernel(reactKernel)`
- **Custom kernel example** — implement and register a custom ThoughtKernel via StrategyRegistry
- Why it matters: `reactive.ts` 905 → 128 lines; duplication eliminated

### `apps/docs/src/content/docs/features/eval.md` (NEW)
The `@reactive-agents/eval` package has no documentation. This page covers:
- What LLM-as-judge evaluation is and when to use it
- EvalStore — persisted evaluation results
- Quick start: running evaluations on agent outputs
- Custom evaluators — implementing a scoring function
- Integration with `ReactiveAgentBuilder`
- Reading evaluation reports

### Expand `apps/docs/src/content/docs/guides/reasoning.md`
Add a new **Structured Plan Engine** section covering:
- How plan-execute strategy generates structured JSON plans (not text-parsed)
- The 4-layer output pipeline: prompt → repair → validate → retry
- PlanStoreService — SQLite-backed plan persistence
- Cross-step references with `{{from_step:sN}}` syntax
- Graduated retry → patch → replan error recovery
- Example: a multi-step research task with a visible plan trace

---

## Section 3: AGENTS.md Hierarchy Map

Add a new **Architecture Quick Reference** section near the top of `AGENTS.md` containing:

1. **Layer dependency tree** — ASCII diagram showing the 19 packages ordered by dependency, grouped into: Foundation → LLM → Memory/Reasoning/Tools → Optional → Gateway/Runtime
2. **Per-layer quick reference table** — package name, one-line purpose, key files to read first, key exports
3. **Service wiring map** — brief description of how `createRuntime()` and `ReactiveAgentBuilder` compose optional layers via Effect-TS Layers
4. **Common debugging entry points** — "if X is broken, start reading Y"

This section is scannable in under 60 seconds and does not replace the existing AGENTS.md content.

---

## Out of Scope (Deferred)

- Provider-agnostic skills directory
- `architecture-reference` skill expansion
- `features/testing-utilities.md` (eval comes first)
- Kill switch / behavioral contracts dedicated pages
- ADRs, performance tuning, troubleshooting guides

---

## Success Criteria

- [ ] All stale numbers corrected across README, CLAUDE.md, landing page
- [ ] CHANGELOG finalized with v0.6.0 date
- [ ] `concepts/composable-kernel.md` published with working code examples
- [ ] `features/eval.md` published covering all major eval APIs
- [ ] `guides/reasoning.md` expanded with Structured Plan Engine section
- [ ] `AGENTS.md` has scannable hierarchy map at top
- [ ] Docs site builds without errors (`astro build`)
