docs(P03): complete freeholders docs + reference phase — REQ-027 complete

P3 complete. 8 docs/freeholders/ pages (signals, standing, stands-guilds, councils-voice, bonds, partner-spectrum, anchor-preview, index) + 2 docs/reference/ pages (architecture, components). Docs firewall green across all 26 docs pages. Full docs deliverable (README + mkdocs.yml + 26-page site) complete — REQ-027 complete. ---ci--- project: oy phase: 3 milestone: v0.3 status: complete tag_base: v0.2.x phase_role: execution requirements: covered: [REQ-027] partial: [] ---/ci---
checkpoint(P02): complete -> advance to P3 freeholders docs
2026-08-17 22:17:07 +00:00 · 2026-08-17 22:15:03 +00:00 · 2026-08-17 22:14:53 +00:00 · 2026-08-17 22:13:06 +00:00 · 2026-08-17 22:12:53 +00:00 · 2026-08-17 22:07:22 +00:00
39 changed files with 3361 additions and 159 deletions
@@ -1,14 +1,14 @@
 {
-  "phase": 5,
+  "phase": 2,
  "stage": "complete",
-  "milestone": "v0.2",
+  "milestone": "v0.3",
  "milestone_type": "feature",
-  "tag_base": "v0.1.x",
+  "tag_base": "v0.2.x",
-  "phase_role": "final",
+  "phase_role": "execution",
  "project": "oy",
  "attempts": 0,
-  "updated_at": "2026-08-17T22:00:00Z",
+  "updated_at": "2026-08-18T00:10:00Z",
-  "milestone_complete": true,
+  "milestone_complete": false,
-  "milestone_release_tag": "v0.1.5",
+  "phase_release_tag": "v0.2.2",
-  "release_id": 732
+  "release_id": 735
 }
@@ -6,9 +6,9 @@
    }
  ],
  "active_project": "oy",
-  "milestone": "v0.2",
+  "milestone": "v0.3",
  "milestone_type": "feature",
-  "tag_base": "v0.1.x",
+  "tag_base": "v0.2.x",
  "autonomy": {
    "level": "full",
    "escalation_hooks": ["deploy", "delete_data", "merge_to_main"],
@@ -57,4 +57,130 @@ Fee Covenant (13) blocks {Pacts (8), Orgs (10), Partners (11), Bearers (12)}
 ## Phase 0 Architecture Deliverables
 - This index file
 - Persona assessment (created during RESEARCH stage)
- Phase plans (created during PLAN stage)
+- Phase plans (created during PLAN stage)
 ---
 ## v0.3 Architecture (Bearers & Documentation)
 This section appends the v0.3 component map to the v0.1/v0.2 index above. It does
 NOT rewrite or supersede the earlier content; the Phase 1/2/3 columns in the
 component index above describe the *full* runtime target, while the v0.3 columns
 below describe the *v0.3 skeleton+tests* deliverable (D-020 pattern continued,
 D-035) plus the documentation deliverable (D-042).
 ### v0.3 Component Index (new + extended modules)
 | # | Component | Vision § | v0.3 Module | New/Ext | Phase | v0.3 Skeleton Depth |
 |---|---|---|---|---|---|---|
 | 2 | Cross-Chain & Exit (Layer 3) — DEX swaps | §7 | `x/exit` | New | P4 | ExitRoute + DEXSwap types, ExitStatus enum |
 | 2 | Cross-Chain & Exit (Layer 3) — L2↔L1 bridges | §7 | `x/bridge` | New | P4 | BridgeRoute + BridgeStatus enum; references x/satellite L2Chain by ID (G-003) |
 | 12 | Bearers expansion (OY-SAT + OY-QR) | §14 | `x/bearers` | Extended | P4 | OYSATLink + OYQRCode transport types (BearerTransport impls); BearerType enum already complete from v0.2 |
 | 11 | Anchors (institutional Partner tier) | §13 | `x/partner` | Extended | P4 | AnchorCredential struct fields on the Anchor tier (REQ-018 enum unchanged); ListByTier(Anchor) round-trip |
 | 8 | Hub API (Pact #6 expanded) | §13, §16 | `x/hub` | New | P5 | HubService enum (Custody/LendingPrimitive/Compliance) + per-service struct stubs + keeper stub |
 | — | Services (Care/SIM/Vault/Mail) | §13 | `x/services` | New | P5 | ServiceKind enum (4) + per-service struct stubs + keeper stub |
 | 8 | Bond market depth (Growth Bonds + secondary) | §17 | `x/bond` | Extended | P5 | GrowthBond struct + SecondaryOrder types; 8%/0% consts (D-028) unchanged; Clamp reused |
 > The Hub API is Pact #6 (Hub-API) per REQ-020/D-027. v0.2 stubbed it as a PactType
 > enum value inside `x/pact`; v0.3 promotes it to its own `x/hub` module for the
 > B2B type scaffold (D-039). The `x/pact` HubAPI enum value stays as a
 > cross-reference; `x/hub` owns the service-shape types.
 ### v0.3 Cross-Component Dependencies (within v0.3)
 Per the v0.2 G-003 invariant (by-ID-string inter-module references; no struct
 imports across `x/<module>/types`), v0.3 components reference each other and the
 v0.2 baseline by ID string only. The dependency edges that affect v0.3 phase
 ordering:
 ```
 x/bridge  ──(L2Chain by id)──►  x/satellite   (v0.2 baseline; ref only, no struct import)
 x/exit    ──(BridgeRoute by id)──►  x/bridge  (P4: exit references bridge routes)
 x/hub     ──(Anchor by id)──►  x/partner    (P5: Hub custody/compliance references Anchor partners)
 x/bond    ──(Stand by id)──►  x/stand      (v0.2 baseline; GrowthBond issuer-stand-id, unchanged)
 x/services ──(Window by id)──►  x/window    (v0.2 baseline; service-grant references a Window)
 x/bearers ──(BearerTransport)──► (none; OY-SAT/OY-QR are transport stubs, no new deps)
 ```
 **Phase-ordering implication (informs D-044):** `x/exit` references `x/bridge`
 routes, so both must land in the same phase (P4) and `x/bridge` types must exist
 before `x/exit` tests that reference a BridgeRoute. `x/hub` references Anchor
 partner-ids, so `x/partner` Anchor extension (P4) must precede `x/hub` (P5). This
 confirms the D-044 P4→P5 split: P4 = exit/bridge/bearers/partner-Anchor,
 P5 = hub/services/bond. Reversing P4/P5 would force `x/hub` to reference an Anchor
 tier that does not yet exist.
 ### v0.3 Interface Contracts (6 cross-component — unchanged from v0.2)
 The six cross-component interfaces (Standing API, Forge/Fold, Watcher Attestation,
 Window Lifecycle, Fee Covenant, Voice/Council) are NOT extended in v0.3 — v0.3
 adds *type scaffolds* that will *consume* them at runtime in v0.4+:
 - **Window Lifecycle Interface** — `x/services` service-grants reference a Window
  by ID (the service opens a Window on the holder's behalf). Skeleton only.
 - **Fee Covenant Interface** — `x/bridge`/`x/exit` exit routes carry an
  `exit-fee-bps` field clamped by the Fee Covenant ceiling/floor (the field is
  typed in v0.3; the Clamp is NOT invoked in the skeleton — deferred to v0.4
  runtime to avoid cross-module calls in the skeleton layer).
 - **Standing API** — `x/hub` compliance service stub references a partner's
  Standing by reach-id (skeleton: by-ID-string field, no query).
 - **Watcher Attestation** — `x/bridge` BridgeStatus has an `Attested` state; the
  attestation itself is not modeled in v0.3 (Watchers are v0.1 baseline; the
  bridge references a Watcher quorum by ID at runtime, deferred to v0.4).
 ### Documentation Architecture (v0.3 deliverable B)
 v0.3 introduces a documentation deliverable alongside the Bearers skeleton. This
 is a NEW architecture surface (no docs site existed in v0.1/v0.2).
 **Layout:**
 ```
 oy/
 ├── README.md                      # repo-root project overview (lexicon-clean)
 ├── mkdocs.yml                     # MkDocs Material config (site_name, nav, theme)
 └── docs/
    ├── nomads/                    # audience: nomads (Reach path, Stash, bearers, Maps/Pay, Pacts, standing basics)
    ├── freeholders/               # audience: freeholders (4 signals, Bayesian Standing, Stands/Guilds, Councils/Voice, Bonds, Partner spectrum)
    ├── shared/                    # cross-audience (Six Principles, Bread Scale, Storage pools, Watchers/Mirror, Lexicon glossary, Vision overview)
    └── reference/                 # architecture index + component map
 ```
 **mkdocs.yml (minimal config):** `site_name: OpenYield`, `theme: readthedocs` or
 `theme: material` (D-042 chose Material), `nav:` with the four audience
 sections, `markdown_extensions: [admonition, toc, pymdownx.superfences]`. Build-
 only Python dep (`mkdocs` + `mkdocs-material`); `go.mod` stays zero-dep (G-006 —
 the docs toolchain is NOT a Go dependency). No publishing CI in v0.3 (D-046);
 README documents `mkdocs serve` / `mkdocs build`.
 **Audience-organized nav (D-042, D-045):** nomads 5-8 pages, freeholders 5-8
 pages, shared 5-6 pages, reference 2 pages (~20-25 total). Pages map to REQs:
 nomads cover REQ-007/013/014/015/019/020; freeholders cover REQ-005/006/016/017/
 011/021/018; shared covers REQ-001/003/004/012; reference covers the architecture
 index.
 **Lexicon-clean by construction (REQ-012 extension, D-043):** docs are user-
 facing and must be lexicon-clean. The highest-risk banned term in docs is
 "yield" (PROJECT.md uses "real yield" but docs must say "real production" / "real
 return" — the word-boundary regex in `lexicon.FindBannedTerm` bans standalone
 "yield" while allowing "OpenYield"). Other high-risk terms in docs: "account"
 (use "Holder"/"Reach"), "bank"/"deposit"/"savings" (use "Stash"/"Vault"/
 "Root-Pool"). The firewall lands in P1 BEFORE content (P2/P3) so docs are checked
 as authored (D-044 firewall-first ordering).
 **Firewall extension (D-043):** a NEW sibling test `lexicon_meta_docs_test.go`
 (package `lexicon_meta_docs`) mirrors `lexicon_meta_test.go` (package
 `lexicon_meta`) exactly — same `lexicon.FindBannedTerm`, same word-boundary
 regex, same fragment-assembled self-test table, same self-exclusion of the meta-
 test file — but scans `README.md` + `docs/**/*.md` instead of `x/**/*.go`. The
 existing `lexicon_meta_test.go` is NOT modified (preserves v0.2 coverage). The
 new meta-test walks the repo root for `README.md` + the `docs/` tree, excludes
 `.ciagent/` and `.git/` (firewall meta-files are not user-facing docs), and
 excludes itself. Per-package lexicon assertions in the new `x/*` modules follow
 the v0.2 pattern (`TestLexiconNoBannedTermsIn<Module>Package` scanning the
 module's production `.go` files).
 > The `.ciagent/` directory holds firewall META-files (PROJECT.md, RESEARCH.md,
 > this file) that discuss the banned terms by name for governance reasons — they
 > are NOT user-facing docs and are explicitly excluded from the docs firewall
 > scan. This mirrors how `lexicon_meta_test.go` excludes itself: the firewall's
 > own code is allowed to name the terms it bans.
@@ -181,4 +181,138 @@ Per-axis verdicts:
 Binding decisions: 10 (G-001..G-010)
 Escalations: 0
 Overall: SHIP Phase 0 with binding changes (confidence 0.83)
-```
+```
 ---
 ## v0.3 Grill (Phase 0)
 > **Reviewer**: CIAgent adversarial grill (red-team, full autonomy)
 > **Date**: 2026-08-17
 > **Target**: v0.3 Phase 0 artifacts (PROJECT.md D-034..D-046, ROADMAP.md v0.3 table, REQUIREMENTS.md REQ-010/022..028, ARCHITECTURE.md v0.3 section, PERSONAS.md v0.3 roster, RESEARCH.md A-301..A-315, PLANS.md v0.3 plan 50 tasks P1-P6) + v0.1/v0.2 codebase baseline
 > **Milestone**: v0.3 — Bearers & Documentation
 > **Autonomy**: full (decision_confidence_threshold = 0.60)
 > **Mode**: multi-project (slug `oy`)
 ### Evidence baseline (verified against the actual repo, not the docs)
 - `go.mod`: `module github.com/oy/openyield`, `go 1.22`, **zero dependencies** (confirmed — no require lines).
 - `x/` modules: **25** (confirmed via `ls x/ | wc -l`). v0.1 = 15 + v0.2 added 10 = 25. v0.3 adds 4 new (exit/bridge/hub/services) + extends 3 (bearers/partner/bond) = 29 distinct after v0.3. PLANS.md P6-01-01 says "29 packages" — correct.
 - Test functions: **299** `func Test*` across **23** test files (counted `grep -rn "^func Test" x/ | wc -l`). v0.2 grill G-001 corrected to 53/11; v0.2 added ~246 more. The v0.3 plan's "~303" reference (REQUIREMENTS IDEATE notes) is close to current 299 — minor, not material.
 - `lexicon/lexicon.go`: `BannedTerms()` returns **10** (verified `if len(terms) != 10` at lexicon.go). The v0.2 `lexicon_meta_test.go` header comment still says "9 banned terms" (line 7) — a **pre-existing v0.2 documentation defect**, not v0.3's, but the v0.3 docs firewall must use 10 (it does — P1-01-01 says exactly 10). No v0.3 binding needed; note for v0.2 housekeeping.
 - `lexicon_meta_test.go` EXISTS at repo root, package `lexicon_meta`, with the **G-009 self-test table** (synthetic strings, `len(synthetic) != len(terms)` guard). The self-test verifies **detection** but does NOT verify the **walk** (which files are scanned). The v0.3 docs firewall inherits this gap — G-013 below.
 - G-003 import-invariant test EXISTS: `x/window/types/types_test.go:431-456` uses `go/parser` (ImportsOnly) to scan all non-test `.go` under `x/` and assert no cross-`x/<module>/types` struct imports. **Confirmed production code is cycle-free** (`grep -rn "openyield/x/" x/ --include="*.go" | grep -v "_test.go"` returns empty). The v0.3 by-ID-string refs (exit→bridge, hub→partner, services→window) will be auto-covered by this existing test — no new G-003 work needed in v0.3 (P4/P5 test tasks correctly say "G-003 import-invariant green" not "add a new one").
 - `x/bond/types/types.go`: `CouponCapBps = 800`, `CouponFloorBps = 0`, `func Clamp(couponBps uint32) uint32` all exist. The D-028 regression firewall is real and the v0.3 GrowthBond extension reuses the same package (no G-003 concern, correct).
 - `x/partner/types/types.go`: `TierAnchor PartnerTier = "Anchor"` exists; no `AnchorCredential` yet (v0.3 P4 adds it). The 4-tier enum is locked — P4 extension adds a struct, not a tier. Correct.
 - `x/bearers/types/types.go`: `BearerOYSAT` and `BearerOYQR` are ALREADY in `AllBearers()` (lines 20-21, 39-40) since v0.1; `BearerTransport` interface + `OYLRLink` + `SurveillanceResistant` exist since v0.2. P4 adds `OYSATLink`/`OYQRCode` transport structs only — `AllBearers()` count (6) stays unchanged. Correct.
 - `x/window`, `x/stand`, `x/satellite` (L2Chain/TransferChannel), `x/watcher`, `x/identity` (Reach) all exist as v0.1/v0.2 baseline — the v0.3 by-ID-string refs to them (bridge→satellite/watcher, services→window/identity, bond→stand) have real targets. No phantom refs.
 - **No `docs/`, no `README.md`, no `mkdocs.yml` exist** today. The firewall-first ordering is clean: `lexicon_meta_docs_test.go` passes vacuously with zero docs to scan (no hits possible). The "chicken-and-egg between firewall test and README" risk raised in the grill brief is a **non-issue** — verified by walk logic (zero files = zero hits).
 These baseline facts confirm the v0.3 plan's architecture and ordering claims against the actual codebase, not just the docs. The plan is unusually well-grounded; the binding decisions below are mostly small correctness fixes, not scope rework.
 ### Per-Axis Verdicts
 #### Axis 1 — Feasibility (50 tasks / 6 phases at full autonomy) — **PASS** (confidence 0.82)
 50 tasks across 6 phases is large but proportionate to the deliverable: 26 docs pages (P1-P3) + 7 x/* packages (P4-P5) + audit/ship (P6). v0.2 shipped 31 tasks / 5 phases for 10 packages at full autonomy and closed clean (per REQUIREMENTS.md v0.2 summary). v0.3 adds the docs surface (a genuinely new artifact type) and 4 new + 3 extended Go packages. The docs phases (P1-P3) are low-risk Markdown authoring gated by a Go firewall; the Bearers phases (P4-P5) are pure skeleton+tests, the proven v0.1/v0.2 pattern. No phase exceeds 12 tasks (P3 is largest at 12, all docs). The firewall-first claim is achievable: a firewall that scans zero files passes trivially (verified — no docs exist yet). Reject the "50 tasks is too many" hypothesis — it matches the deliverable surface.
 #### Axis 2 — Scope (Bearers + docs bundle, ~22 pages) — **PASS** (confidence 0.78)
 D-034 (bundle Bearers + docs under one feature milestone) is defensible: the user's `--ideate` request was docs-only, but ROADMAP Phase 3 (Bearers) is the next queued feature work; bundling keeps the milestone cadence and avoids a docs-only NFR milestone that would not advance the protocol. The alternative (separate v0.3 docs NFR + v0.4 Bearers) would split a coherent unit of work into two milestones and delay the Bearers skeleton a full cycle. The ~20-25 page docs depth (D-045) is bounded — not gold-plating; each page maps to a REQ (REQUIREMENTS.md IDEATE traceability table). The one scope concern: the **mkdocs.yml nav in RESEARCH §2.1 is missing 2 pages** the plan creates — `nomads/window.md` (P2-01-07) and `freeholders/anchor-preview.md` (P3-01-07). This is a documentation/plan inconsistency, not a scope defect — **binding fix G-011** requires the nav to list all created pages. Confidence holds.
 #### Axis 3 — Cost (MkDocs Material, firewall extension) — **PASS** (confidence 0.85)
 MkDocs Material is the right cost: Markdown-native (docs-writer authors `.md`, not YAML/HTML), build-only Python dep that does NOT touch `go.mod` (verified zero require lines; G-006 holds). Plain-Markdown-no-generator would be cheaper but loses nav/search/theme — for a user-facing docs site for nomads/freeholders, Material's search + audience nav is real value, not gold-plating. The firewall extension (D-043: a whole new sibling test `lexicon_meta_docs_test.go` + self-test table) is more than "could review manually" — manual review is not durable; the sibling test is the firewall that keeps the docs site lexicon-clean over time (the top risk per Axis 5). The cost is justified. Reject the "firewall is over-engineered for docs" hypothesis — REQ-012 is `All` phases and docs are user-facing; a manual review would rot.
 #### Axis 4 — Technical soundness (by-ID-string refs, ClampGrowth, LendingCouponCapBps) — **CONDITIONAL** (confidence 0.72)
 The by-ID-string refs (G-003) between bridge/exit/partner/hub/services are cycle-free by construction (verified: the existing G-003 import-invariant test in `x/window/types/types_test.go` scans all non-test `x/**/*.go` and will auto-cover the v0.3 files; production code has zero cross-`x/` imports today). The `x/hub` `LendingCouponCapBps = 800` LOCAL const (A-304) is a real invariant — it's a local copy cross-documented to D-028, exactly mirroring how v0.2 `x/guild` cross-docs `x/feecovenant.WaiverHandPassGuild` (verified pattern). The one technical defect: **`ClampGrowth(currentBps, growthBps uint32) uint32` as specified in RESEARCH §1.7 / PLANS P5-03-01 returns `min(CouponCapBps - currentBps, growthBps)`, which underflows when `currentBps > CouponCapBps`** (uint32 subtraction wraps to a huge value, then `min` picks `growthBps` — wrong) or when `currentBps == cap` (returns 0, correct) but is fragile. The invariant "post-growth coupon ≤ 800" only holds if the caller guarantees `currentBps ≤ cap`. The spec does not state this precondition, and a GrowthBond whose current coupon is already at cap would silently allow unbounded growth via the `growthBps` path if the helper is misused. **Binding fix G-012** requires `ClampGrowth` to guard `currentBps > CouponCapBps` explicitly (return 0 or error) so the invariant holds unconditionally. Confidence holds after the fix.
 #### Axis 5 — Risk (lexicon drift, "yield" in docs) — **CONDITIONAL** (confidence 0.74)
 The top risk is correctly identified: "yield" is banned as a standalone word but "OpenYield" is safe (word-boundary regex, verified `TestLexiconMetaNoFalsePositiveOnOpenYield`); PROJECT.md uses "real yield" but docs must say "real production"/"real return". The firewall-first ordering (D-044: P1 firewall before P2/P3 content) is the correct mitigation — a banned term slipped into a P2 nomads page fails the P2 build, not the P6 review. The firewall extension (D-043) is sufficient to CATCH drift at build time. The gap: the firewall does not PREVENT the docs-writer from authoring a banned term in the first place — it fails the phase build, requiring a rewrite. For 26 pages this is acceptable (the failure is loud and local); for 100+ pages it would be painful. At the v0.3 scale, the firewall is sufficient. The deeper risk: **the docs firewall self-test table (G-009 for docs) verifies DETECTION but not the WALK** — if the walk logic misses `docs/nomads/` (e.g., a path-prefix bug), the self-test still passes (it tests `FindBannedTerm` on synthetic strings, not the file walk). **Binding fix G-013** requires the docs firewall to include a walk-coverage assertion: a test that injects a synthetic banned-term `.md` into a temp `docs/` subtree (or uses a fixture) and asserts the walk FINDS it. Without this, the docs firewall could silently scan zero files and report green. Confidence holds after the fix.
 #### Axis 6 — Dependency (intra-P4, P4→P5, hidden edges) — **PASS** (confidence 0.80)
 The intra-P4 edge (bridge→exit) and the P4→P5 edge (partner-Anchor→hub) are the only v0.3-internal ordering constraints, and both are correctly handled (P4 Wave 1 = bridge before exit Wave 2; P4 before P5 for Anchor→hub). The RESEARCH §3 cross-component dependency list is complete for the v0.3 surface. Verified the "hidden edges" raised in the grill brief:
 - **Does x/services need x/window types?** Yes, by-ID-string (`window-id` field) — but x/window is v0.2 baseline, already shipped. Not a v0.3 phase-ordering concern. Correctly noted in RESEARCH §3.
 - **Does x/bond GrowthBond need x/anything?** No — GrowthBond embeds the v0.2 Bond (same package, `x/bond/types`), and `ClampGrowth` reuses the same-package consts. No G-003 concern. Correct.
 - **Does x/hub need x/bond?** No — it uses a LOCAL const `LendingCouponCapBps = 800` (A-304) to avoid the import. Correct (verified pattern matches v0.2 guild/feecovenant).
 - **Does x/exit need x/bread?** No — `amount-grain` is int64, "Grain" by name only (P4-02-01 explicitly says "NOT a `x/bread` import"). Correct.
 No hidden edges. The P5 "no intra-phase ordering" claim (hub/services/bond independent) is correct — they reference only v0.1/v0.2 baseline modules by ID-string, not each other.
 #### Axis 7 — Testing (≥80% on skeletons, docs phases no Go coverage) — **CONDITIONAL** (confidence 0.70)
 ≥80% coverage on skeleton type packages is achievable but borders on coverage theater (testing getters/constructors/enum-round-trips on trivial types). v0.2 hit ≥95.9% on 8 of 10 packages at this bar, so it's not theater in practice — the locked-const + invariant + lexicon assertions carry real regression value. The plan correctly applies the ≥80% bar only to the 7 x/* packages (P4/P5), NOT to the docs phases (P1-P3 produce no Go code except the firewall test, which is itself the coverage). The one gap: **P1-01-01 (the docs firewall) and P4/P5 test files have no explicit coverage target** — the firewall test's own coverage is not asserted. A firewall test that scans zero files (walk bug) would still have high coverage on its detection logic. **Binding fix G-013** (walk-coverage assertion, from Axis 5) addresses this — the injected-fixture test forces the walk to actually execute. No separate coverage bar needed for docs phases. Confidence holds.
 #### Axis 8 — Maintainability (docs lexicon over time, sibling test drift) — **CONDITIONAL** (confidence 0.72)
 The docs site will stay lexicon-clean over time ONLY if the firewall runs on every change. D-046 defers publishing CI to v0.4, but the firewall is a `go test` — it runs locally and in any CI that runs `go test ./...`. The risk is not "no CI" (the firewall runs wherever `go test` runs) but "the sibling test `lexicon_meta_docs_test.go` drifts from `lexicon_meta_test.go`". D-043 chose a sibling (not an extension) to preserve v0.2 coverage — defensible — but two meta-tests sharing detection logic via the same `lexicon.FindBannedTerm` is good; sharing the self-test table by DUPLICATION (not by a shared helper) is the drift risk. If `lexicon_meta_test.go`'s self-test table is updated (e.g., a new banned term added) and `lexicon_meta_docs_test.go`'s copy is not, the docs firewall silently loses coverage. **Binding fix G-014**: the docs firewall's self-test table and banned-term count assertion should DERIVE from `lexicon.BannedTerms()` (which both already do for the count — good) and ideally share the synthetic-string table via a `lexicon` package helper rather than duplicating it. At minimum, both must assert `len(terms) == 10` from the single source `lexicon.BannedTerms()` so a count change breaks both. This is a low-severity maintainability note, not a blocker. Confidence holds.
 #### Axis 9 — Adversarial (what makes v0.3 fail to ship) — **PASS** (confidence 0.78)
 The four failure modes raised in the grill brief:
 1. **Firewall blocks docs content mid-authoring** — MITIGATED by firewall-first (P1 firewall passes vacuously with zero docs; P2/P3 content fails fast and local, not at P6). Not a ship-blocker.
 2. **By-ID-string ref breaks when a target module is renamed** — LOW. The targets (satellite/watcher/identity/window/stand) are v0.1/v0.2 baseline, locked. v0.3 does not rename them. The by-ID-string fields are opaque strings, not Go imports, so a rename would only break tests that hardcode the ID — caught at `go test`. Not a ship-blocker.
 3. **MkDocs build fails on Gitea Pages** — NON-ISSUE for v0.3. D-046 explicitly defers publishing CI to v0.4; v0.3 ships the source + a `mkdocs build` invocation in the README. A Gitea Pages failure is a v0.4 concern, not v0.3's. Not a ship-blocker.
 4. **Coverage drops below 80% on a skeleton package with trivial types** — MITIGATED. v0.2 hit ≥95.9% on 8/10 packages at this bar; the locked-const + invariant + lexicon assertions provide real coverage. The v0.3 packages (bridge/exit/hub/services) follow the v0.2 satellite/forex pattern that hit 100%. Not a ship-blocker.
 The actual highest ship-risk is **ClampGrowth underflow (G-012)** if a test constructs a GrowthBond at cap and the helper misbehaves — but this is caught by the invariant test (post-growth ≤ 800) if the test exercises the cap boundary. **Binding fix G-012** makes the helper robust; the test must cover `currentBps == cap` and `currentBps > cap`. No escalation.
 ---
 ### Binding Decisions
 These are **binding** — the orchestrator MUST apply them before P1 begins. Numbered G-011..G-014 (continuing from the v0.2 grill G-001..G-010).
 | ID | Decision | Rationale | Confidence | Affects |
 |----|----------|-----------|------------|---------|
 | **G-011** | `mkdocs.yml` nav MUST list every page the plan creates. RESEARCH §2.1's sample `mkdocs.yml` is missing `nomads/window.md` (P2-01-07) and `freeholders/anchor-preview.md` (P3-01-07). P1-01-02 (mkdocs.yml authoring) must include all 26 pages in the nav (or the nav is incomplete at P3 ship). The nav may reference not-yet-existing pages at P1 (mkdocs.yml is config, not Go-tested) but must be complete by P3-03-01 ship. | The RESEARCH sample nav and the PLANS page list disagree by 2 pages. A stale nav ships a docs site with orphaned pages (created but not linked). | 0.85 | P1-01-02 (mkdocs.yml), P3-03-01 (ship verification — confirm nav matches all 26 created pages) |
 | **G-012** | `x/bond` `ClampGrowth(currentBps, growthBps uint32) uint32` MUST guard `currentBps > CouponCapBps` explicitly (return 0, or document the precondition and assert it) so the "post-growth coupon ≤ 800" invariant holds unconditionally. The spec's `min(CouponCapBps - currentBps, growthBps)` underflows when `currentBps > cap` (uint32 wrap → huge value → `min` picks `growthBps` → invariant violated). The P5-03-01 test MUST cover `currentBps == cap` (returns 0) and `currentBps > cap` (returns 0 or is rejected) as explicit cases. | The spec'd helper has a uint32 underflow trap that breaks the stated invariant under misuse. The v0.2 `Clamp` has no such trap (it's a simple min/max); `ClampGrowth` adds the subtraction. A latent underflow in a locked-const firewall is a real defect. | 0.82 | P5-03-01 (ClampGrowth helper + invariant test) |
 | **G-013** | `lexicon_meta_docs_test.go` MUST include a **walk-coverage assertion**: a test that places a synthetic banned-term `.md` in a temp/fixture `docs/` subtree (or uses an in-memory walk target) and asserts the walk FINDS it. The G-009 self-test table (which both firewalls share) verifies DETECTION (`FindBannedTerm` on synthetic strings) but NOT the WALK (which files are scanned). A walk bug (e.g., wrong path prefix, missing `docs/` recursion) would report green on zero files scanned. The walk-coverage test closes this gap. | The docs firewall's failure mode is "silently scans nothing and reports green" — undetectable by the self-test table alone. v0.3 has no docs today, so a broken walk passes trivially at P1 and would only surface when a real banned term slips into a real P2/P3 page AND the walk happens to miss that file. A walk-coverage test forces the walk to execute against a known-bad fixture. | 0.80 | P1-01-01 (lexicon_meta_docs_test.go) |
 | **G-014** | `lexicon_meta_docs_test.go` and `lexicon_meta_test.go` MUST derive the banned-term count from the single source `lexicon.BannedTerms()` (both already assert `len(terms) == 10` from it — good; verified). The synthetic self-test table should ideally be shared via a `lexicon` package helper (e.g., `lexicon.SyntheticBannedStrings() []string`) rather than duplicated across the two meta-tests, so a future banned-term addition updates both firewalls from one place. If a shared helper is not added in v0.3, the two tables MUST be kept in sync by a comment cross-reference. | D-043 chose a sibling test to preserve v0.2 coverage — defensible — but two copies of the self-test table drift silently. A shared helper is the durable fix; a cross-reference comment is the minimum. | 0.70 | P1-01-01 (lexicon_meta_docs_test.go), optionally `lexicon/lexicon.go` (shared helper) |
 ---
 ### Escalations
 **None.** All nine axes resolved at confidence ≥ 0.60 after the binding fixes G-011..G-014 are applied. No axis required escalation to the human. At full autonomy, the orchestrator applies the binding decisions and proceeds to P1.
 ---
 ### Overall Verdict
 #### **SHIP Phase 0 with binding changes**
 The v0.3 Phase 0 plan is fundamentally sound and unusually well-grounded: the architecture and ordering claims were verified against the actual codebase (25 x/* modules, zero deps, G-003 import-invariant test exists and is green, bond consts/Clamp exist, bearers/partner extension points exist, baseline modules for all by-ID-string refs exist). The firewall-first ordering is clean (firewall passes vacuously with zero docs — no chicken-and-egg). The scope (Bearers + docs bundle) is defensible, not over-scoped. The 50-task / 6-phase plan is proportionate to the deliverable surface (26 docs pages + 7 x/* packages).
 The binding changes are **small correctness fixes**, not scope rework:
 - **G-011** (mkdocs.yml nav completeness) — documentation/plan consistency.
 - **G-012** (ClampGrowth uint32 underflow guard) — the single real technical defect; a latent invariant-breaking trap in a locked-const firewall.
 - **G-013** (docs firewall walk-coverage test) — closes the "silently scans nothing" failure mode the G-009 self-test table does not cover.
 - **G-014** (shared synthetic-string helper / cross-reference) — maintainability of the two sibling firewalls.
 None of these rise to "rethink" or "reduce scope" — the architecture, scope, ordering, and persona assignments are correct. Apply the 4 binding decisions and proceed to Phase P1.
 **Confidence in overall verdict: 0.80**
 ---
 ### Summary Block
 ```
 Per-axis verdicts (v0.3):
  1. Feasibility        — PASS         (0.82)
  2. Scope              — PASS         (0.78)  → strengthened by G-011
  3. Cost               — PASS         (0.85)
  4. Technical soundness — CONDITIONAL (0.72)  → fixed by G-012
  5. Risk               — CONDITIONAL  (0.74)  → fixed by G-013
  6. Dependency         — PASS         (0.80)
  7. Testing            — CONDITIONAL  (0.70)  → fixed by G-013 (walk-coverage)
  8. Maintainability    — CONDITIONAL  (0.72)  → fixed by G-014
  9. Adversarial        — PASS         (0.78)
 Binding decisions: 4 (G-011..G-014)
 Escalations: 0
 Overall: SHIP Phase 0 with binding changes (confidence 0.80)
 ```
@@ -3,124 +3,121 @@ active_personas:
  - id: backend-engineer
    active: true
    phase_specific: false
-    reason: Go/Cosmos module skeletons for v0.2 components — owns the non-Cosmos-mirroring modules (pact, partner, bond) per G-007. Owns the bulk of bespoke-type skeleton + tests work.
+    reason: Owns ALL Bearers skeleton Go modules in v0.3 (x/exit, x/bridge, x/bearers ext, x/partner ext, x/hub, x/services, x/bond ext). The v0.2 cosmos-engineer/security-engineer split is collapsed back into backend-engineer for v0.3 because the Cosmos-convention-alignment load is lower (no new IBC/governance/capability modules — x/bridge reuses the v0.2 satellite ICS-20 shape, x/hub is a fresh B2B scaffold). v0.3 is bespoke-type skeleton + tests work, which is backend-engineer's core territory.
-    frameworks: [Go, Cosmos SDK, IBC, CosmWasm]
+    frameworks: [Go 1.22 stdlib, Cosmos-style types (zero-dep)]
-    territory: ["x/pact/**", "x/partner/**", "x/bond/**", "x/**/types/**", "x/**/keeper/**", "x/**/module.go"]
+    territory: ["x/exit/**", "x/bridge/**", "x/hub/**", "x/services/**", "x/bearers/**", "x/partner/**", "x/bond/**", "x/**/types/**", "x/**/keeper/**"]
-    constraints: [lexicon compliance (REQ-012), skeleton+tests pattern (D-020), ≥80% coverage on new packages (D-033), no live-chain side effects in skeleton, locked-const invariants, no fractional reserve, no leverage/futures, go.mod is read-only in v0.2 (G-006 — any change is an escalation)]
+    constraints: ["zero external deps (G-006 — go.mod read-only)", "D-020 skeleton+tests pattern (D-035 continues)", "≥80% coverage on new/extended packages", "per-package lexicon assertion (REQ-012) in every new/extended test file", "by-ID-string inter-module refs (G-003 — no struct imports across x/<module>/types)", "locked-const invariants (HubService count, ServiceKind count, BridgeStatus count, ExitStatus count, Anchor credential fields)", "no live chain / no real IBC / no real bearer transports / no live B2B runtime"]
  - id: data-engineer
    active: true
    phase_specific: false
    reason: Genesis/state schema design for new modules — Window audit log, Stand membership sets, Bond issuance state, Council Voice tally state. Shapes ValidateGenesis upgrades. Owns genesis SCHEMA only (G-008); test assertions are security-engineer's.
    frameworks: [Go, encoding/json, Cosmos SDK state]
    territory: ["x/**/types/genesis.go", "x/**/genesis.go"]
    constraints: [append-only audit logs (Window), ID-uniqueness in ValidateGenesis, lexicon compliance, no state identity beyond Reach, does NOT own *_test.go files (G-008)]
  - id: lead-developer
    active: true
    phase_specific: false
-    reason: Multi-component orchestration across 10 new packages, dependency sequencing per D-031 blocker chain, vertical-slice integrity per phase.
+    reason: Coordinates the v0.3 phase decomposition (P1 firewall+docs foundation → P2 nomads → P3 freeholders → P4 Bearers I → P5 Bearers II → P6 review/ship), territory enforcement (warn mode per config.json), and final review. Owns the cross-component dependency finding (x/exit→x/bridge in P4; x/partner-Anchor→x/hub across P4→P5) that constrains phase ordering.
    frameworks: [cross-cutting]
-    territory: ["**"]
+    territory: [".ciagent/**", "**"]
-    constraints: [blocked-by chain enforcement (D-031), milestone versioning (v0.2 / tag_base v0.1.x), lexicon gate on merge, persona territory warn-mode enforcement]
+    constraints: ["D-044 phase ordering (firewall-first; P4 before P5 for Anchor→hub dep)", "milestone versioning (v0.3 / tag_base v0.2.x)", "lexicon gate on merge (REQ-012 extends to docs/)", "persona territory warn-mode enforcement", "zero Go deps invariant (G-006); docs build-deps are allowed (D-042)"]
-  - id: cosmos-engineer
+  - id: frontend-engineer
    active: true
    phase_specific: true
-    reason: v0.2 introduces IBC (satellite), governance (council), capability (window), group (stand/guild), oracle (forex) patterns that map directly to Cosmos SDK modules (x/gov, x/group, x/authz, x/feegrant, x/capability, x/ibc-transfer). Phase-specific to v0.2 execution phases where Cosmos-convention alignment matters for future wiring.
+    reason: v0.3 introduces the docs site (REQ-027) — the first non-skeleton, non-Go deliverable since v0.1's Mesh Experience. frontend-engineer owns the docs territory (docs/**, mkdocs.yml, README.md) and the docs firewall test (lexicon_meta_docs_test.go). Phase-specific: ACTIVE only for P1-P3 (docs phases); removed after P3 once the docs site is complete and the Bearers skeleton phases (P4/P5) are pure Go.
-    frameworks: [cosmos-sdk, ibc-go, CosmWasm, CometBFT]
+    frameworks: [MkDocs Material, Markdown]
-    territory: ["x/satellite/**", "x/council/**", "x/window/**", "x/stand/**", "x/guild/**", "x/forex/**", "x/bearers/**"]
+    territory: ["docs/**", "mkdocs.yml", "README.md", "lexicon_meta_docs_test.go"]
-    constraints: [lexicon compliance (REQ-012), no live-chain side effects in skeleton, mirror x/gov TallyResult / x/group DecisionPolicy / x/authz Grant shapes for future wiring, zero external deps in v0.2 skeleton, by-ID-string inter-module references to avoid import cycles (G-003 tested invariant), go.mod is read-only in v0.2 (G-006)]
+    constraints: ["lexicon-clean by construction (REQ-012 extended to docs via D-043 — 10 banned terms must not appear in docs/*.md or README.md; 'yield' banned as standalone word, 'OpenYield' safe via word-boundary regex)", "audience-organized nav (nomads/freeholders/shared/reference per D-042)", "~20-25 pages total per D-045", "no publishing CI in v0.3 (D-046 — mkdocs.yml buildable locally only)", "mkdocs.yml is build-only Python dep; go.mod stays zero-dep (G-006)"]
    removed_after: P3
-  - id: security-engineer
+  - id: docs-writer
    active: true
    phase_specific: true
-    reason: v0.2 enforces Mission Lock (council), fee/bond coupon clamps (clamp invariants), 9-stand / 4-tier / 6-pact locked-const tests, and Window revoke/expire lifecycle invariants. Phase-specific to v0.2 where invariant/locked-const test density is highest.
+    reason: Custom persona for the docs content authoring load (REQ-027, D-045 ~20-25 pages across 4 audiences). Folded as a SEPARATE persona rather than into frontend-engineer because the skills differ: frontend-engineer owns the docs TOOLCHAIN (mkdocs.yml config, theme, nav structure, firewall test wiring) while docs-writer owns the CONTENT (the actual Markdown pages: nomads Reach/Stash/bearers pages, freeholders Standing/Bonds pages, shared Principles/Bread-Scale pages, reference architecture-index). Splitting keeps the toolchain-vs-content boundary explicit so a toolchain change does not entangle content review. Phase-specific: ACTIVE only for P1-P3; removed after P3.
-    frameworks: [Go testing, table-driven tests, invariant tests]
+    frameworks: [Markdown, MkDocs Material (content authoring only)]
-    territory: ["x/**/types/**_test.go", "x/**/keeper/**_test.go", "x/**/genesis_test.go", "x/**/*_test.go"]
+    territory: ["docs/nomads/**/*.md", "docs/freeholders/**/*.md", "docs/shared/**/*.md", "docs/reference/**/*.md"]
-    constraints: [invariant tests for all locked constants (Mission Lock non-amendable, bond 8% cap / 0% floor, fee ceiling/floor), locked-const tests for every enum count (9 stands, 4 partner tiers, 6 pacts), lexicon assertion in every new test file (D-033), ≥80% coverage on new packages, owns ALL *_test.go files including genesis_test.go (G-008)]
+    constraints: ["lexicon-clean by construction (same REQ-012 extension — 'real production'/'real return' not 'real yield'; 'Holder'/'Reach' not 'account'; 'Stash'/'Vault'/'Root-Pool' not 'bank'/'deposit'/'savings')", "audience-organized (each page belongs to exactly one of nomads/freeholders/shared/reference)", "page-count budget per D-045", "no banned-term literals in page source (the docs firewall scans .md files directly, unlike .go which uses fragment assembly)"]
    removed_after: P3
 deactivated:
-  - id: frontend-engineer
+  - id: data-engineer
-    reason: No UI in v0.2 (skeleton+tests only; Mesh Experience UI is v0.1-complete and v0.3+ for new UI). Deactivate to avoid persona territory noise. Reactivate in v0.3.
+    reason: INACTIVE for v0.3. The project has zero external deps and no database; the v0.2 data-engineer owned genesis.go schema helpers, which are a thin layer in v0.3's new modules (x/exit, x/bridge, x/hub, x/services each get a small GenesisState + ValidateGenesis following the v0.2 A-212 pattern). That work is owned by backend-engineer in v0.3 (the genesis schema is part of the skeleton type authoring, not a separate schema-design discipline). Reactivate if a future milestone adds a real store/migration.
  - id: cosmos-engineer
    reason: The v0.2 custom persona is NOT reactivated for v0.3. v0.3's new modules do not map onto new Cosmos SDK modules the way v0.2's did (x/gov, x/group, x/authz, x/capability, x/ibc-transfer). x/bridge reuses the v0.2 satellite ICS-20 shape (already aligned); x/hub/x/services/x/exit are bespoke B2B/service scaffolds with no direct Cosmos analog. The Cosmos-convention-alignment load drops below the threshold that justified a separate persona. backend-engineer absorbs the work.
  - id: security-engineer
    reason: The v0.2 custom persona is NOT reactivated for v0.3. v0.3's invariant density is lower than v0.2's (no Mission Lock, no new fee/bond clamp — the 8%/0% consts are reused unchanged from v0.2; the new locked-consts are enum counts: HubService=3, ServiceKind=4, BridgeStatus, ExitStatus). The locked-const + invariant tests are absorbed by backend-engineer's per-package test authoring. The docs firewall (lexicon_meta_docs_test.go) is frontend-engineer's territory. Reactivate in v0.4 if a new Mission-Lock-class invariant lands.
  - id: ci-security-auditor
-    reason: Default deactivated; activate in P5 (review/ship) phase for the milestone audit. Not needed during P1-P4 skeleton authoring.
+    reason: Default deactivated; activate in P6 (review/ship) for the v0.3 milestone audit.
  - id: mesh-engineer
-    reason: v0.1 listed as future; still not needed in v0.2 (Bearers OY-LR + Beacon are type stubs only, no hardware/RF). Activate in v0.3 for real bearer runtime.
+    reason: Still not needed in v0.3 (OY-SAT/OY-QR are type stubs only; no hardware/RF runtime). Activate in v0.4+ for real bearer runtime.
 custom_personas:
-  - id: cosmos-engineer
+  - id: docs-writer
-    rationale: v0.2 components map onto specific Cosmos SDK modules (x/gov, x/group, x/authz, x/feegrant, x/capability, x/ibc-transfer). A dedicated persona ensures skeleton types mirror the eventual runtime shapes, reducing Phase 3 wiring refactor cost. Distinct from backend-engineer because it carries Cosmos-specific convention knowledge (tally shapes, decision policy, capability, ICS-20 packet shape).
+    rationale: v0.3's docs deliverable (~20-25 pages across 4 audiences per D-045) is a substantial content-authoring load distinct from the docs toolchain work. A dedicated docs-writer keeps the content-vs-toolchain boundary explicit: frontend-engineer owns mkdocs.yml/nav/theme/firewall-wiring; docs-writer owns the page content. This split means a toolchain PR (e.g., adding a markdown extension) does not entangle a content review (e.g., a nomads Reach-page rewrite), and vice versa. Distinct from frontend-engineer because content authoring (prose, audience voice, lexicon-safe phrasing) is a different skill from toolchain config (YAML, theme, nav, Go test wiring). Removed after P3 when the docs site is complete.
  - id: security-engineer
    rationale: v0.2 has the highest locked-const + invariant density in the project (Mission Lock, bond cap, 6 Pact types, 9 Stand types, 4 Partner tiers, Window revoke idempotency). A dedicated persona ensures invariant tests and lexicon assertions are not an afterthought. Distinct from backend-engineer because it owns test-file territory and invariant-first design.
 ---
-# Personas: OpenYield (oy) — v0.2 (The Mesh)
+# Personas: OpenYield (oy) — v0.3 (Bearers & Documentation)
 > This file supersedes the v0.2 PERSONAS.md for the v0.3 milestone. The v0.2
 > custom personas (cosmos-engineer, security-engineer) are NOT reactivated for
 > v0.3 — see Deactivated below for rationale. The default four personas are
 > backend-engineer, data-engineer, frontend-engineer, lead-developer; v0.3
 > activates backend-engineer + lead-developer + frontend-engineer (phase-
 > specific) and adds one custom persona (docs-writer, phase-specific).
 ## Active Roster
 ### backend-engineer
- **Domain**: Go/Cosmos module skeletons for v0.2 — owns the **non-Cosmos-mirroring** modules (pact, partner, bond) per G-007, plus shared `types/`+`keeper/`+`module.go` authoring.
+- **Domain**: All Bearers skeleton Go modules in v0.3 — `x/exit`, `x/bridge`, `x/hub`, `x/services` (new); `x/bearers`, `x/partner`, `x/bond` (extended). Owns the D-020 skeleton+tests pattern (D-035 continues): Go types + keeper stubs + invariant tests, no live chain. Absorbs the v0.2 cosmos-engineer/security-engineer split because v0.3's Cosmos-convention and invariant density are lower.
- **Frameworks**: Go, Cosmos SDK, IBC, CosmWasm.
+- **Frameworks**: Go 1.22 stdlib, Cosmos-style types (zero-dep).
- **Territory**: `x/pact/**`, `x/partner/**`, `x/bond/**`, `x/**/types/**`, `x/**/keeper/**`, `x/**/module.go`. (`go.mod` is read-only in v0.2 per G-006.)
+- **Territory**: `x/exit/**`, `x/bridge/**`, `x/hub/**`, `x/services/**`, `x/bearers/**`, `x/partner/**`, `x/bond/**`, `x/**/types/**`, `x/**/keeper/**`. (`go.mod` is read-only per G-006.)
- **Constraints**: lexicon compliance (REQ-012), skeleton+tests pattern (D-020), ≥80% coverage on new packages (D-033), no live-chain side effects in skeleton, locked-const invariants, no fractional reserve, no leverage/futures.
+- **Constraints**: zero external deps (G-006), D-020 skeleton+tests (D-035), ≥80% coverage on new/extended packages, per-package lexicon assertion (REQ-012), by-ID-string inter-module refs (G-003), locked-const invariants (HubService/ServiceKind/BridgeStatus/ExitStatus counts + Anchor credential fields), no live chain/IBC/bearer/B2B runtime.
 ### data-engineer
 - **Domain**: Genesis/state schema design — Window audit log, Stand membership sets, Bond issuance state, Council Voice tally state. Shapes `ValidateGenesis` upgrades (v0.1's no-op → v0.2 ID-uniqueness checks). Owns genesis **schema** only (G-008); genesis **test assertions** are security-engineer's.
 - **Frameworks**: Go, `encoding/json`, Cosmos SDK state.
 - **Territory**: `x/**/types/genesis.go`, `x/**/genesis.go` (excludes `*_test.go` per G-008).
 - **Constraints**: append-only audit logs (Window), ID-uniqueness in `ValidateGenesis`, lexicon compliance, no state identity beyond Reach.
 ### lead-developer
- **Domain**: Multi-component orchestration across 10 new packages, dependency sequencing per D-031 blocker chain, vertical-slice integrity per phase.
+- **Domain**: v0.3 phase decomposition (P1 firewall+docs foundation → P2 nomads → P3 freeholders → P4 Bearers I → P5 Bearers II → P6 review/ship), territory enforcement (warn mode), final review. Owns the cross-component dependency finding that constrains phase ordering: `x/exit`→`x/bridge` (same phase P4); `x/partner`-Anchor→`x/hub` (P4 before P5).
 - **Frameworks**: cross-cutting.
- **Territory**: `**`.
+- **Territory**: `.ciagent/**`, `**`.
- **Constraints**: blocked-by chain enforcement (D-031), milestone versioning (v0.2 / tag_base v0.1.x), lexicon gate on merge, persona territory warn-mode enforcement.
+- **Constraints**: D-044 phase ordering (firewall-first; P4→P5 for Anchor→hub dep), milestone versioning (v0.3 / tag_base v0.2.x), lexicon gate on merge (REQ-012 extends to docs/), persona territory warn-mode, zero Go deps (G-006; docs build-deps allowed per D-042).
-### cosmos-engineer (custom, phase-specific to v0.2)
+### frontend-engineer (phase-specific: P1-P3 only)
- **Domain**: v0.2 components map onto Cosmos SDK modules — `x/gov` (council tally), `x/group` (stand/guild decision policy), `x/authz`/`x/feegrant` (window), `x/capability` (window unforgeable ref), `x/ibc-transfer` ICS-20 (satellite). Ensures skeleton types mirror runtime shapes for low-friction Phase 3 wiring.
+- **Domain**: v0.3 docs TOOLCHAIN — `mkdocs.yml` (site_name, nav, theme: material, markdown_extensions), the audience-based nav structure (nomads/freeholders/shared/reference per D-042), and the docs firewall test wiring (`lexicon_meta_docs_test.go` mirroring `lexicon_meta_test.go` with `lexicon.FindBannedTerm` + word-boundary regex + self-test table + self-exclusion, scanning `README.md` + `docs/**/*.md`). Owns the firewall landing in P1 BEFORE content (D-044 firewall-first). Removed after P3.
- **Frameworks**: cosmos-sdk, ibc-go, CosmWasm, CometBFT.
+- **Frameworks**: MkDocs Material, Markdown, Go testing (for the firewall test).
- **Territory**: `x/satellite/**`, `x/council/**`, `x/window/**`, `x/stand/**`, `x/guild/**`, `x/forex/**`, `x/bearers/**` (Cosmos-convention-mirroring modules per G-007; `x/pact`/`x/partner`/`x/bond` are backend-engineer's). `go.mod` read-only per G-006.
+- **Territory**: `docs/**` (toolchain), `mkdocs.yml`, `README.md`, `lexicon_meta_docs_test.go`.
- **Constraints**: lexicon compliance (REQ-012), no live-chain side effects in skeleton, mirror `x/gov` `TallyResult` / `x/group` `DecisionPolicy` / `x/authz` `Grant` shapes, zero external deps in v0.2 skeleton, by-ID-string inter-module references (G-003 tested invariant).
+- **Constraints**: lexicon-clean by construction (REQ-012 extended via D-043; 10 banned terms absent from docs; "yield" banned standalone, "OpenYield" safe), audience-organized nav, ~20-25 pages total (D-045), no publishing CI in v0.3 (D-046), mkdocs.yml build-only Python dep (go.mod stays zero-dep per G-006).
 - **Removed after**: P3.
-### security-engineer (custom, phase-specific to v0.2)
+### docs-writer (custom, phase-specific: P1-P3 only)
- **Domain**: Invariant + locked-const test authorship. Owns **all** test-file territory across v0.2 packages (including `genesis_test.go` per G-008). Highest invariant density in the project: Mission Lock non-amendable, bond 8% cap / 0% floor clamp, fee ceiling/floor clamp, 6 Pact types, 9 Stand types, 4 Partner tiers, Window revoke/expire idempotency, lexicon assertion per module.
+- **Domain**: v0.3 docs CONTENT — the actual Markdown pages across the four audiences (nomads: Reach/Stash/bearers/Maps-Pay/Pacts/standing-basics; freeholders: 4-signals/Bayesian-Standing/Stands-Guilds/Councils-Voice/Bonds/Partner-spectrum; shared: Six-Principles/Bread-Scale/Storage-pools/Watchers-Mirror/Lexicon-glossary/Vision-overview; reference: architecture-index/component-map). Split from frontend-engineer so content review and toolchain review do not entangle. Removed after P3.
- **Frameworks**: Go testing, table-driven tests, invariant tests.
+- **Frameworks**: Markdown, MkDocs Material (content authoring only).
- **Territory**: `x/**/types/**_test.go`, `x/**/keeper/**_test.go`, `x/**/genesis_test.go`, `x/**/*_test.go` (all test files per G-008).
+- **Territory**: `docs/nomads/**/*.md`, `docs/freeholders/**/*.md`, `docs/shared/**/*.md`, `docs/reference/**/*.md`.
- **Constraints**: invariant tests for all locked constants, locked-const tests for every enum count (9 stands, 4 partner tiers, 6 pacts, 3 councils), lexicon assertion in every new test file (D-033), ≥80% coverage on new packages, Window lifecycle idempotency tests (revoke-after-expire, double-revoke).
+- **Constraints**: lexicon-clean by construction (same REQ-012 extension; "real production"/"real return" not "real yield"; "Holder"/"Reach" not "account"; "Stash"/"Vault"/"Root-Pool" not "bank"/"deposit"/"savings"), audience-organized (each page in exactly one audience dir), page-count budget per D-045, no banned-term literals in page source (docs firewall scans .md directly, unlike .go fragment assembly).
 - **Removed after**: P3.
 ## Deactivated
- **frontend-engineer** — No UI in v0.2 (skeleton+tests only). Mesh Experience UI is v0.1-complete; new UI is v0.3+. Reactivate in v0.3.
+
- **ci-security-auditor** — Default deactivated; activate in P5 (review/ship) for milestone audit.
+- **data-engineer** — INACTIVE for v0.3. Zero deps + no database; the v0.2 genesis.go schema work is a thin layer absorbed by backend-engineer in v0.3's new modules. Reactivate if a future milestone adds a real store/migration.
- **mesh-engineer** — v0.1 listed as future; still not needed in v0.2 (Bearers OY-LR + Beacon are type stubs only). Activate in v0.3 for real bearer runtime.
+- **cosmos-engineer** (v0.2 custom) — NOT reactivated. v0.3's new modules do not map onto new Cosmos SDK modules (x/bridge reuses v0.2 satellite shape; x/hub/x/services/x/exit are bespoke). Cosmos-convention load drops below the threshold for a separate persona; backend-engineer absorbs.
 - **security-engineer** (v0.2 custom) — NOT reactivated. v0.3's invariant density is lower (no new Mission-Lock/fee-clamp; 8%/0% consts reused unchanged; new locked-consts are enum counts). Locked-const + invariant tests absorbed by backend-engineer's per-package test authoring; docs firewall is frontend-engineer's. Reactivate in v0.4 if a new Mission-Lock-class invariant lands.
 - **ci-security-auditor** — Default deactivated; activate in P6 (review/ship) for the milestone audit.
 - **mesh-engineer** — Still not needed (OY-SAT/OY-QR are type stubs only). Activate in v0.4+ for real bearer runtime.
 ## Custom Personas
- **cosmos-engineer** — v0.2 components map onto specific Cosmos SDK modules. Dedicated persona ensures skeleton types mirror eventual runtime shapes, reducing Phase 3 wiring refactor cost. Distinct from backend-engineer: carries Cosmos-specific convention knowledge (tally shapes, decision policy, capability, ICS-20 packet shape).
+
- **security-engineer** — v0.2 has the highest locked-const + invariant density in the project. Dedicated persona ensures invariant tests and lexicon assertions are not an afterthought. Distinct from backend-engineer: owns test-file territory and invariant-first design.
+- **docs-writer** — v0.3's docs deliverable (~20-25 pages, D-045) is a substantial content-authoring load distinct from the docs toolchain. A dedicated docs-writer keeps the content-vs-toolchain boundary explicit: frontend-engineer owns mkdocs.yml/nav/theme/firewall-wiring; docs-writer owns page content. This split means a toolchain PR does not entangle a content review and vice versa. Distinct from frontend-engineer because prose/audience-voice/lexicon-safe-phrasing is a different skill from YAML/theme/nav/Go-test wiring. Removed after P3 when the docs site is complete.
 ## Framework Alignment
- **Go 1.22** — all personas target Go 1.22 (`go.mod`).
+- **Go 1.22** — backend-engineer targets Go 1.22 (`go.mod`); zero external deps (G-006).
- **cosmos-sdk** — cosmos-engineer targets cosmos-sdk v0.50.x (LTS) for future wiring; NOT vendored in v0.2 skeleton.
+- **MkDocs Material** — frontend-engineer + docs-writer target MkDocs Material (D-042); build-only Python dep, NOT a Go dependency. No publishing CI in v0.3 (D-046).
 - **ibc-go** — cosmos-engineer targets ibc-go v8/v10 for satellite module shape; NOT vendored in v0.2 skeleton.
 - **CosmWasm** — cosmos-engineer targets wasmvm v1.5/v2.0 for potential Pacts-as-contracts in Phase 3; NOT vendored in v0.2.
 ## Territory Alignment
- Mapped to actual `x/<name>/` structure (15 v0.1 modules + 9 new v0.2 modules + 1 extended).
+- backend-engineer owns all `x/*` Bearers-skeleton modules (new: exit/bridge/hub/services; extended: bearers/partner/bond) + shared `types/`+`keeper/` authoring.
- backend-engineer owns `x/pact`, `x/partner`, `x/bond` (non-Cosmos-mirroring per G-007) + shared `types/`+`keeper/`+`module.go` authoring.
+- frontend-engineer owns the docs toolchain (`docs/**` config, `mkdocs.yml`, `README.md`, `lexicon_meta_docs_test.go`).
- data-engineer owns `genesis.go` schema only (G-008 — excludes `*_test.go`).
+- docs-writer owns docs content (`docs/<audience>/**/*.md`).
- cosmos-engineer owns the Cosmos-convention-mirroring modules (`x/satellite`, `x/council`, `x/window`, `x/stand`, `x/guild`, `x/forex`) + `x/bearers` extension (G-007).
+- lead-developer owns `.ciagent/**` + `**` for cross-cutting coordination.
- security-engineer owns **all** `*_test.go` files across the new packages (G-008 — including `genesis_test.go`).
+- `go.mod` is read-only in v0.3 (G-006) — no persona may modify it; docs build-deps are allowed (D-042) but live outside `go.mod`.
 - lead-developer owns `**` for cross-cutting coordination.
 - `go.mod` is **read-only** in v0.2 (G-006) — no persona may modify it; any change is an escalation (would violate D-020/A-201 zero-dep invariant).
 ## Constraint Alignment
- **Lexicon (REQ-012)** — every persona carries it; security-engineer asserts it per test file.
+- **Lexicon (REQ-012)** — every active persona carries it; backend-engineer asserts per test file (x/*); frontend-engineer asserts via the docs firewall (docs/* + README.md). The firewall extension is a sibling test, NOT a modification of the v0.2 meta-test (D-043).
- **Skeleton + tests pattern (D-020)** — backend-engineer + cosmos-engineer enforce.
+- **Skeleton + tests (D-020/D-035)** — backend-engineer enforces.
- **≥80% coverage on new packages (D-033)** — security-engineer owns the gate.
+- **≥80% coverage** — backend-engineer owns the gate for x/* packages.
- **Blocker chain (D-031)** — lead-developer enforces phase ordering.
+- **Phase ordering (D-044)** — lead-developer enforces; firewall-first (P1) before content (P2/P3); P4 (exit/bridge/bearers/partner) before P5 (hub/services/bond) for the Anchor→hub dependency.
- **No live-chain side effects in skeleton** — cosmos-engineer + backend-engineer enforce (no relayer, no CometBFT, no live oracle).
+- **Locked-const invariants** — backend-engineer owns; HubService=3, ServiceKind=4, BridgeStatus count, ExitStatus count, Anchor credential fields, 8%/0% bond consts (reused).
 - **Locked-const invariants** — security-engineer owns; every locked constant has a dedicated test.
 ## Phase-Specific Personas
- **cosmos-engineer** — phase-specific to v0.2 execution phases (P1-P4). Remove or merge back into backend-engineer after v0.2 ships (Cosmos convention alignment is most critical during the first Mesh-era skeleton).
+- **frontend-engineer** — phase-specific to v0.3 P1-P3 (docs phases). Removed after P3; the Bearers skeleton phases (P4/P5) are pure Go (backend-engineer). Reassess at v0.4 if new docs work is queued.
- **security-engineer** — phase-specific to v0.2 (highest invariant density). May persist into v0.3 if invariant-test density remains high; reassess at v0.3 PLAN.
+- **docs-writer** — phase-specific to v0.3 P1-P3 (docs content). Removed after P3 with frontend-engineer.
@@ -334,4 +334,459 @@ The Phase 0 grill (see `.ciagent/oy/GRILL.md`) returned 10 binding decisions, al
 - **P1-02-01 (Stand types)** → blocks P2-01-01 (Pact StandRegistry stand-id-ref), P3-01-01 (Council Stand Council), P4-01-01 (Bond issuer-stand-id).
 - **P1-03-01 (Guild types)** → blocks P3-01-01 (Council Guild Council).
 - **P4-04-01 (P4 ship)** → blocks P5-01-01, P5-01-02, P5-01-03 (P5 audit).
- All P(N) phase-ship tasks block P(N+1) Wave 1 tasks (soft ordering for branch hygiene; types themselves only depend on the listed hard blockers).
+- All P(N) phase-ship tasks block P(N+1) Wave 1 tasks (soft ordering for branch hygiene; types themselves only depend on the listed hard blockers).
 ---
 ## Milestone v0.3 — Bearers & Documentation — Phase Plan
 > This section APPENDS the v0.3 milestone plan to the v0.1/v0.2 plan above. It
 > does NOT rewrite or supersede the earlier content. v0.3 bundles two work-
 > streams under one feature milestone (D-034): (A) Bearers skeleton+tests
 > (D-020/D-035 pattern) and (B) a README.md + MkDocs Material docs site with
 > the REQ-012 lexicon firewall extended to docs (D-043). Tags run on the
 > `v0.2.x` patch line (config.json `tag_base: v0.2.x`): P0 → `v0.2.0`,
 > P1..P5 → `v0.2.1..v0.2.5`, P6 → `v0.2.6` (= the v0.3 milestone release per
 > D-008 — final phase patch IS the milestone release; no separate minor tag).
 ### Milestone Summary
 - **Milestone**: v0.3 — Bearers & Documentation
 - **Type**: Feature (Bearers phases P4/P5 are `feat`; docs phases P1-P3 are `docs`/`test`; P6 is `final`)
 - **Tag base**: `v0.2.x` patch line (P0 ships as `v0.2.0`; execution phases `v0.2.1..v0.2.5`; final phase `v0.2.6` IS the milestone release)
 - **Phases**: 7 — P0 (this PLAN) + P1..P3 (docs) + P4..P5 (Bearers feat) + P6 (final review/audit/ship).
 - **Depth**: skeleton + tests layer (D-020/D-035) for Bearers; docs deliverable (D-042/D-045) for the docs site; zero external Go deps (G-006; mkdocs is a build-only Python dep, not a Go dep).
 - **Coverage target**: ≥80% on each new/extended x/* package (D-033); lexicon assertion (REQ-012) in every new/extended test file (D-032); docs firewall (`lexicon_meta_docs_test.go`) green for `README.md` + `docs/**/*.md`.
 - **New x/* modules**: 4 (`x/exit`, `x/bridge`, `x/hub`, `x/services`). **Extended**: 3 (`x/bearers`, `x/partner`, `x/bond`). **Docs surface**: new (`docs/`, `mkdocs.yml`, `README.md`). **Firewall**: 1 new sibling test (`lexicon_meta_docs_test.go`).
 - **Phase ordering** (D-044): P1 docs foundation + firewall-first → P2 nomads docs → P3 freeholders docs → P4 Bearers I (exit/bridge/bearers/partner-Anchor) → P5 Bearers II (hub/services/bond) → P6 review/ship. Firewall lands in P1 BEFORE content (P2/P3) so docs are lexicon-clean by construction. P4 precedes P5 for the Anchor→hub dependency.
 - **Personas**: backend-engineer (all Bearers Go modules), lead-developer (cross-cutting/ship), frontend-engineer (docs toolchain + firewall wiring, P1-P3 only), docs-writer (docs content, P1-P3 only). The v0.2 custom personas (cosmos-engineer, security-engineer) are NOT reactivated (A-315).
 ### Cross-Phase Dependency Map (v0.3)
 ```
 P1 (firewall + docs foundation) ──┬──► P2 (nomads docs)   [firewall scans docs/nomads/ as added]
                                  └──► P3 (freeholders docs) [firewall scans docs/freeholders/ + docs/reference/]
 P4 (Bearers I: bridge, exit, bearers ext, partner ext) ──► P5 (Bearers II: hub, services, bond ext)
        │  x/bridge (Wave 1) ──► x/exit (Wave 2)        [exit bridge-route-id refs bridge by ID]
        │  x/partner Anchor (Wave 4) ──► x/hub (P5 Wave 1) [hub operator-partner-id refs Anchor by ID]
        └──► P5 all waves
 P5 (Bearers II) ──► P6 (review/audit/ship)
 P1..P5 (all execution) ──► P6
 ```
 Hard cross-phase blockers (by-ID-string refs, no import cycles — G-003):
 - **P4 Wave 1 `x/bridge` types** → blocks P4 Wave 2 `x/exit` tests (exit's `bridge-route-id` references a BridgeRoute by ID-string — A-308/G-003).
 - **P4 Wave 4 `x/partner` Anchor extension** → blocks P5 Wave 1 `x/hub` (hub's `operator-partner-id` references an Anchor partner by ID-string — A-304/G-003). This is the edge that forces P4 before P5 (D-044).
 - **P1 Wave 1 docs firewall** → blocks P2/P3 docs content (firewall-first: a banned term slipped into a P2/P3 page fails the build, not the P6 review).
 - **P5 ship** → blocks P6 audit/ship.
 All other inter-module refs (x/services→x/window, x/bond→x/stand, x/bridge→x/satellite, x/bridge→x/watcher) are to v0.1/v0.2 baseline modules (no v0.3 phase-ordering concern).
 ---
 ## Phase P1 — Docs Foundation + Firewall Extension
 - **Slug**: `docs-foundation-firewall`
 - **Branch**: `oy/phase/01-docs-foundation-firewall`
 - **REQs covered**: REQ-028 (lexicon firewall extension to docs), REQ-027 (README.md + docs site foundation: README + shared docs + index)
 - **Tag**: `v0.2.1`
 - **Type**: `feat/test+docs`
 - **Personas**: frontend-engineer (toolchain + firewall), docs-writer (README + shared content)
 - **Goal**: Land the docs lexicon firewall (`lexicon_meta_docs_test.go`) + the MkDocs Material scaffold (`mkdocs.yml`) + `README.md` + `docs/index.md` + `docs/shared/` pages BEFORE any audience docs content (P2/P3), so docs are lexicon-clean by construction (D-044 firewall-first).
 ### Wave 1 — Firewall + scaffold FIRST (parallel)
 | Task ID | REQ | Persona | Files | Deliverable | Must-have verification | Blocked-by |
 |---|---|---|---|---|---|---|
 | P1-01-01 | REQ-028 | frontend-engineer | `lexicon_meta_docs_test.go` (repo root, package `lexicon_meta_docs`) | **NEW sibling meta-test** mirroring `lexicon_meta_test.go` (D-043). Uses the SAME `lexicon.FindBannedTerm` (word-boundary, case-insensitive) — NO detection reimplementation. Walks the REPO ROOT (not `x/`): targets `README.md` (repo root) + every `*.md` under `docs/` (recursive). Excludes `.ciagent/` (firewall meta-files, not user-facing), `.git/` (VCS), the meta-test file itself (self-exclusion via `runtime.Caller(0)`), and non-`.md` files under `docs/`. Includes the G-009 self-test table (one synthetic string per banned term, assembled from `lexicon.BannedTerms()` fragments so the test file's own source has no banned-term literal), `TestLexiconMetaDocsBannedTermsCount` (exactly 10), and `TestLexiconMetaDocsNoFalsePositiveOnOpenYield` (word-boundary does not match "openyield"/"european"). The firewall PASSES at P1 time with zero docs (or with only README + docs/index.md + docs/shared/ from Wave 2). | `go test ./lexicon_meta_docs/...` green (invoked as `go test -run TestLexiconMetaDocs ./...` or via the repo-root file); self-test table passes for all 10 banned terms; `TestLexiconMetaDocsNoFalsePositiveOnOpenYield` green; a deliberately-injected banned term in a `docs/*.md` file fails the test | — |
 | P1-01-02 | REQ-027 | frontend-engineer | `mkdocs.yml` (repo root) | MkDocs Material config (D-042): `site_name: OpenYield`; `theme: name: material` with `navigation.sections`/`navigation.expand`/`toc.integrate` features; `markdown_extensions: [admonition, toc (permalink: true), pymdownx.superfences]`; `nav:` skeleton with Home + Nomads + Freeholders + Shared + Reference sections (audience-organized per D-042). The nav references the P2/P3 pages by path (pages need not exist yet at P1 — mkdocs.yml is a config file, not validated by Go tests; the docs firewall does not validate nav, only `.md` content). Build-only Python dep; `go.mod` stays zero-dep (G-006). No publishing CI (D-046). | `mkdocs.yml` is valid YAML (parses; documented `mkdocs serve` / `mkdocs build` invocation goes in README P1-02-01); `go.mod` unchanged (zero require lines); nav has the 4 audience sections + Home | — |
 ### Wave 2 — README + docs/index.md + docs/shared/ (parallel; blocked-by Wave 1 firewall)
 | Task ID | REQ | Persona | Files | Deliverable | Must-have verification | Blocked-by |
 |---|---|---|---|---|---|---|
 | P1-02-01 | REQ-027 | frontend-engineer | `README.md` (repo root) | Repo-root project overview: one-paragraph OpenYield description (lexicon-clean — "real production"/"real return" not "yield"; "Holder"/"Reach" not "account"; "Stash"/"Vault"/"Root-Pool" not "bank"/"deposit"/"savings"); build instructions (`go build ./...`, `go test ./...`); docs build instructions (`mkdocs serve` / `mkdocs build` per D-046); link to `docs/` site; pointer to `.ciagent/oy/PROJECT.md` for governance. Lexicon-clean by construction (the P1-01-01 firewall scans README.md). | `README.md` exists; `go test ./lexicon_meta_docs/...` green (README is scanned); `go test ./...` green (no Go regression — README is not a Go file) | P1-01-01 |
 | P1-02-02 | REQ-027 | docs-writer | `docs/index.md` | Site home page: one-paragraph OpenYield overview (lexicon-clean), links to the 4 audience sections (nomads/freeholders/shared/reference), pointer to README for build instructions. | `docs/index.md` exists; docs firewall green (index scanned) | P1-01-01 |
 | P1-02-03 | REQ-027 | docs-writer | `docs/shared/six-principles.md` | Six Principles page (REQ-001): real value, sustainability, mission-lock, openness, ownership, self-service. Lexicon-clean (the firewall scans `docs/shared/**/*.md`). | Page exists; firewall green | P1-01-01 |
 | P1-02-04 | REQ-027 | docs-writer | `docs/shared/bread-scale.md` | Bread Scale page (REQ-013): Grain → Crumb → Bread → Loaf → Batch → Cake → Bakery → Granary → Mill → Harvest → Earth. | Page exists; firewall green | P1-01-01 |
 | P1-02-05 | REQ-027 | docs-writer | `docs/shared/storage-pools.md` | Storage Pools page (REQ-014): Stash (Holder), Vault (Stand), Root-Pool (treasury). Lexicon-clean ("Stash"/"Vault"/"Root-Pool" not "bank"/"deposit"/"savings"). | Page exists; firewall green | P1-01-01 |
 | P1-02-06 | REQ-027 | docs-writer | `docs/shared/watchers-mirror.md` | Watchers / Mirror page (REQ-004): 9 Watchers, 6-of-9 quorum, daily attestations, 100,000 Bread bond each. | Page exists; firewall green | P1-01-01 |
 | P1-02-07 | REQ-027 | docs-writer | `docs/shared/lexicon-glossary.md` | Lexicon Glossary page (REQ-012): the 10 banned terms named BY THEIR SAFE ALTERNATIVES (the page documents the safe phrasings — "real production"/"Holder"/"Stash"/"coupon" — NOT the banned literals; the firewall scans this page, so the banned terms must NOT appear as literals, only as the safe replacements described in prose). Cross-reference the firewall design (D-043). | Page exists; firewall green (no banned-term literals — the glossary describes replacements, not the banned words themselves) | P1-01-01 |
 | P1-02-08 | REQ-027 | docs-writer | `docs/shared/vision-overview.md` | Vision Overview page: the OpenYield covenant (real production, anti-greed, jurisdiction-light, public-good mesh), pointer to `.ciagent/oy/PROJECT.md` for the full vision source. | Page exists; firewall green | P1-01-01 |
 ### Wave 3 — Phase verification + ship
 | Task ID | REQ | Persona | Files | Deliverable | Must-have verification | Blocked-by |
 |---|---|---|---|---|---|---|
 | P1-03-01 | REQ-012, REQ-027, REQ-028 | lead-developer | (cross-cutting) | Run `go build ./...` + `go test ./...` across the whole repo (no Go regression — the docs firewall is a NEW Go test file but adds no x/* Go code); confirm `go test ./lexicon_meta_docs/...` green; confirm `mkdocs.yml` valid; confirm README.md + docs/index.md + 6 docs/shared/ pages exist and are lexicon-clean; tag `v0.2.1`. | `go test ./...` green (incl. v0.1/v0.2 baseline + the new docs firewall); docs firewall green; mkdocs.yml valid; 8 docs files (README + index + 6 shared) exist + lexicon-clean; git tag `v0.2.1` created | P1-01-01, P1-01-02, P1-02-01..08 |
 ### P1 Must-Haves
 - [ ] `lexicon_meta_docs_test.go` exists at repo root (package `lexicon_meta_docs`); mirrors `lexicon_meta_test.go` detection (same `lexicon.FindBannedTerm` + word-boundary regex + self-test table G-009 + self-exclusion); scans `README.md` + `docs/**/*.md`; excludes `.ciagent/` + `.git/` + itself.
 - [ ] `go test ./lexicon_meta_docs/...` green (firewall passes with README + docs/index.md + docs/shared/ present).
 - [ ] `go test ./...` green across the whole repo (no Go regression; the v0.2 `lexicon_meta_test.go` is UNCHANGED per D-043).
 - [ ] `mkdocs.yml` exists at repo root (Material theme, 4 audience sections in nav, admonition + toc + superfences extensions); `go.mod` unchanged (zero require lines).
 - [ ] `README.md` exists (lexicon-clean; build/test/docs-build instructions).
 - [ ] `docs/index.md` exists (site home).
 - [ ] 6 `docs/shared/` pages exist (Six Principles, Bread Scale, Storage Pools, Watchers/Mirror, Lexicon Glossary, Vision Overview) — all lexicon-clean.
 - [ ] Docs firewall self-test table passes for all 10 banned terms (G-009 for docs).
 - [ ] `TestLexiconMetaDocsNoFalsePositiveOnOpenYield` green.
 - [ ] Git tag `v0.2.1`.
 ### P1 Risks & Mitigations
 - **Banned-term literals in the lexicon-glossary page** (highest P1 risk) → docs-writer must describe SAFE ALTERNATIVES, not the banned words themselves; the firewall scans `docs/shared/lexicon-glossary.md` directly (unlike `.go` fragment assembly). Mitigation: P1-01-01 firewall is the gate; a literal banned term fails the P1 build.
 - **mkdocs.yml nav references non-existent P2/P3 pages** → mkdocs.yml is a config file, not Go-tested; nav can list future pages. The firewall scans `.md` content, not `nav`. Mitigation: P2/P3 create the referenced pages; missing pages are a `mkdocs build` warning, not a Go test failure.
 - **README "yield" false positive** → the firewall word-boundary regex allows "OpenYield" but bans standalone "yield"; README must say "real production"/"real return". Mitigation: `TestLexiconMetaDocsNoFalsePositiveOnOpenYield` is the regression firewall.
 ---
 ## Phase P2 — Nomads Docs
 - **Slug**: `nomads-docs`
 - **Branch**: `oy/phase/02-nomads-docs`
 - **REQs covered**: REQ-027 (nomads audience docs, 7 pages per D-045)
 - **Tag**: `v0.2.2`
 - **Type**: `docs`
 - **Personas**: docs-writer (content); frontend-engineer (toolchain verify — firewall now scans the new docs/nomads/ files)
 - **Goal**: Ship the 7-page nomads audience docs (`docs/nomads/`) covering the Reach path, Stash, bearers, Maps/Pay, six Pacts, standing basics, and the Window primitive — all lexicon-clean (the P1 firewall now scans these files as they are added).
 ### Wave 1 — Nomads content pages (parallel; all blocked-by P1 firewall landing)
 | Task ID | REQ | Persona | Files | Deliverable | Must-have verification | Blocked-by |
 |---|---|---|---|---|---|---|
 | P2-01-01 | REQ-027 (REQ-005 Reach) | docs-writer | `docs/nomads/reach.md` | What a Nomad is + the Reach path (REQ-005): how a person becomes a Holder via a Reach ID, no-KYC at protocol level, geographic-proximity FCFS (REQ-007). Lexicon-clean ("Holder"/"Reach" not "account"; "real production" not "yield"). | Page exists; docs firewall green (scans `docs/nomads/reach.md`) | P1-03-01 |
 | P2-01-02 | REQ-027 (REQ-014 Stash) | docs-writer | `docs/nomads/stash.md` | Stash usage (REQ-014): the Holder-level storage pool, how Bread is held in a Stash, the 90-day Freeholder-signal Stash requirement. Lexicon-clean ("Stash" not "bank"/"deposit"/"savings"). | Page exists; firewall green | P1-03-01 |
 | P2-01-03 | REQ-027 (REQ-019 bearers) | docs-writer | `docs/nomads/bearers.md` | Bearers for nomads (REQ-019): the six bearers (Internet, OY-LR, OY-BLE, OY-WiFi-Direct, OY-SAT, OY-QR) via the Unified Bearer Layer, first-to-deliver-wins, surveillance resistance. Lexicon-clean. | Page exists; firewall green | P1-03-01 |
 | P2-01-04 | REQ-027 (Mesh Experience) | docs-writer | `docs/nomads/maps-pay.md` | Maps / Pay Mesh Experience: how a Nomad uses Maps and Pay day-to-day (Maya's Day deferred per PROJECT.md out-of-scope Q1). Lexicon-clean. | Page exists; firewall green | P1-03-01 |
 | P2-01-05 | REQ-027 (REQ-020 Pacts) | docs-writer | `docs/nomads/pacts.md` | Six Pacts (REQ-020): Pause, Ground, Stance, Cover, Stand Registry, Hub API — what each means for a Nomad. Lexicon-clean. | Page exists; firewall green | P1-03-01 |
 | P2-01-06 | REQ-027 (REQ-006 standing basics) | docs-writer | `docs/nomads/standing-basics.md` | Standing basics for nomads (REQ-006): what Bayesian Standing is in plain language, how it accrues, why it matters (no formula math — defer detail to freeholders/bayesian-standing). Lexicon-clean. | Page exists; firewall green | P1-03-01 |
 | P2-01-07 | REQ-027 (REQ-015 Window) | docs-writer | `docs/nomads/window.md` | Window primitive (REQ-015): scope, duration, rate-limit, audit log, revoke — what a Window means for a Nomad delegating access to a partner/service. Lexicon-clean. | Page exists; firewall green | P1-03-01 |
 | P2-01-08 | REQ-027 | docs-writer | `docs/nomads/index.md` | Nomads section index: one-paragraph intro + links to the 7 nomads pages. Lexicon-clean. | Page exists; firewall green | P1-03-01 |
 ### Wave 2 — Phase verification + ship
 | Task ID | REQ | Persona | Files | Deliverable | Must-have verification | Blocked-by |
 |---|---|---|---|---|---|---|
 | P2-02-01 | REQ-012, REQ-027 | lead-developer | (cross-cutting) | Run `go test ./...` (docs firewall now scans the 8 new `docs/nomads/*.md` files and passes); confirm all 8 nomads pages lexicon-clean; tag `v0.2.2`. | `go test ./...` green (docs firewall green with nomads content); 8 `docs/nomads/*.md` exist + lexicon-clean; git tag `v0.2.2` | P2-01-01..08 |
 ### P2 Must-Haves
 - [ ] 8 `docs/nomads/*.md` pages exist (index + reach + stash + bearers + maps-pay + pacts + standing-basics + window) — all lexicon-clean.
 - [ ] `go test ./...` green (the P1 docs firewall now scans `docs/nomads/**/*.md` and passes).
 - [ ] `go test ./lexicon_meta_docs/...` green specifically.
 - [ ] No Go code changes (P2 is pure docs; `go build ./...` green by no-regression).
 - [ ] Git tag `v0.2.2`.
 ### P2 Risks & Mitigations
 - **"account"/"bank"/"deposit" drift in nomads prose** (Stash/Reach pages are highest-risk) → docs-writer uses "Holder"/"Reach"/"Stash"; the firewall is the gate (fails the P2 build, not P6 review — D-044 firewall-first value).
 - **Standing-basics page over-promises formula detail** → defer math to freeholders/bayesian-standing (P3); nomads page stays conceptual.
 ---
 ## Phase P3 — Freeholders Docs + Reference
 - **Slug**: `freeholders-docs-reference`
 - **Branch**: `oy/phase/03-freeholders-docs-reference`
 - **REQs covered**: REQ-027 (freeholders audience docs 7 pages + reference 2 pages; REQ-027 COMPLETE at end of P3)
 - **Tag**: `v0.2.3`
 - **Type**: `docs`
 - **Personas**: docs-writer (content); frontend-engineer (toolchain verify — firewall now scans docs/freeholders/ + docs/reference/)
 - **Goal**: Ship the 7-page freeholders audience docs (`docs/freeholders/`) covering the four signals, Bayesian Standing, Stands/Guilds, Councils/Voice, Bonds, Partner spectrum, Anchor preview — plus the 2-page reference section (`docs/reference/`). **REQ-027 (docs deliverable) is COMPLETE at the end of P3.** After P3, frontend-engineer and docs-writer are removed (phase-specific personas, P1-P3 only).
 ### Wave 1 — Freeholders content pages (parallel)
 | Task ID | REQ | Persona | Files | Deliverable | Must-have verification | Blocked-by |
 |---|---|---|---|---|---|---|
 | P3-01-01 | REQ-027 (REQ-005 four signals) | docs-writer | `docs/freeholders/four-signals.md` | Four Freeholder signals (REQ-005): 90d Stash, 4.5★+ in 3 categories, Capital, Vouch. Lexicon-clean. | Page exists; firewall green | P2-02-01 |
 | P3-01-02 | REQ-027 (REQ-006 Bayesian Standing) | docs-writer | `docs/freeholders/bayesian-standing.md` | Bayesian Standing (REQ-006): the anti-gaming formula (Bayesian + time-decay + diversity + voucher-weighted − slashes), why it resists gaming. Formula at conceptual depth (full sub-tables deferred per PROJECT.md Q2). Lexicon-clean. | Page exists; firewall green | P2-02-01 |
 | P3-01-03 | REQ-027 (REQ-016/017 Stands/Guilds) | docs-writer | `docs/freeholders/stands-guilds.md` | Stands & Guilds (REQ-016/017): the 9 Stand types (Household…Shadow), Guilds with Hand-Passes at 0% protocol fee. Lexicon-clean ("Stash"/"Vault" not "bank"; "Hand-Pass"/"0% protocol fee" not "interest"). | Page exists; firewall green | P2-02-01 |
 | P3-01-04 | REQ-027 (REQ-011 Councils/Voice) | docs-writer | `docs/freeholders/councils-voice.md` | Councils & Voice (REQ-011): the three Councils (Mesh, Guild, Stand), multi-source Voice, Mission Lock cannot be amended. Lexicon-clean. | Page exists; firewall green | P2-02-01 |
 | P3-01-05 | REQ-027 (REQ-021 Bonds) | docs-writer | `docs/freeholders/bonds.md` | Bonds (REQ-021): the Mesh Bond Market, 8% upper coupon cap / 0% floor, Growth Bonds (preview of v0.3 P5 work). Lexicon-clean ("coupon"/"growth" not "interest"/"yield"). | Page exists; firewall green | P2-02-01 |
 | P3-01-06 | REQ-027 (REQ-018 Partner spectrum) | docs-writer | `docs/freeholders/partner-spectrum.md` | Partner Spectrum (REQ-018): the four tiers (Op, Master Op, Pier, Anchor). Lexicon-clean ("Partner"/"Reach" not "account"). | Page exists; firewall green | P2-02-01 |
 | P3-01-07 | REQ-027 (REQ-023 Anchor preview) | docs-writer | `docs/freeholders/anchor-preview.md` | Anchor preview (REQ-023): the first institutional Partner tier, the Anchor credential (preview of v0.3 P4 work), custody/compliance relationship. Lexicon-clean ("custody"/"compliance"/"jurisdiction" safe; not "bank"/"account"). | Page exists; firewall green | P2-02-01 |
 | P3-01-08 | REQ-027 | docs-writer | `docs/freeholders/index.md` | Freeholders section index: one-paragraph intro + links to the 7 freeholders pages. Lexicon-clean. | Page exists; firewall green | P2-02-01 |
 ### Wave 2 — Reference pages (parallel; blocked-by Wave 1)
 | Task ID | REQ | Persona | Files | Deliverable | Must-have verification | Blocked-by |
 |---|---|---|---|---|---|---|
 | P3-02-01 | REQ-027 | docs-writer | `docs/reference/architecture-index.md` | Architecture index: the 14-component index (from `.ciagent/oy/ARCHITECTURE.md` Component Index), the 6 cross-component interfaces, the critical blocker chain. Lexicon-clean (rewrite the architecture terms in user-facing prose — do NOT copy `.ciagent/` content verbatim if it contains banned-term discussions; the firewall scans this page). | Page exists; firewall green | P3-01-01..08 |
 | P3-02-02 | REQ-027 | docs-writer | `docs/reference/component-map.md` | Component map: a table of v0.1/v0.2/v0.3 modules (`x/<name>/`) mapped to vision sections and REQs. Lexicon-clean. | Page exists; firewall green | P3-01-01..08 |
 ### Wave 3 — Phase verification + ship (frontend-engineer + docs-writer removed after this phase)
 | Task ID | REQ | Persona | Files | Deliverable | Must-have verification | Blocked-by |
 |---|---|---|---|---|---|---|
 | P3-03-01 | REQ-012, REQ-027 | lead-developer | (cross-cutting) | Run `go test ./...` (docs firewall now scans `docs/freeholders/**/*.md` + `docs/reference/**/*.md` and passes); confirm all 10 new pages lexicon-clean; **REQ-027 COMPLETE** (total docs pages: 1 README + 1 index + 6 shared + 8 nomads + 8 freeholders + 2 reference = 26 pages, within D-045 20-25 budget +README/index); tag `v0.2.3`. Remove frontend-engineer + docs-writer personas (phase-specific, P1-P3 only). | `go test ./...` green (docs firewall green with all docs content); REQ-027 marked complete in REQUIREMENTS.md; git tag `v0.2.3`; personas removed | P3-01-01..08, P3-02-01..02 |
 ### P3 Must-Haves
 - [ ] 8 `docs/freeholders/*.md` pages exist (index + four-signals + bayesian-standing + stands-guilds + councils-voice + bonds + partner-spectrum + anchor-preview) — all lexicon-clean.
 - [ ] 2 `docs/reference/*.md` pages exist (architecture-index + component-map) — all lexicon-clean.
 - [ ] `go test ./...` green (docs firewall scans the full `docs/` tree + README and passes).
 - [ ] `go test ./lexicon_meta_docs/...` green.
 - [ ] No Go code changes (P3 is pure docs; `go build ./...` green by no-regression).
 - [ ] **REQ-027 marked COMPLETE** in REQUIREMENTS.md (docs deliverable done).
 - [ ] frontend-engineer + docs-writer personas removed (phase-specific, P1-P3 only).
 - [ ] Git tag `v0.2.3`.
 ### P3 Risks & Mitigations
 - **"interest"/"yield" in bonds page** (highest P3 risk) → docs-writer uses "coupon"/"growth"/"real return"; firewall is the gate.
 - **Architecture-index page copies `.ciagent/` banned-term discussions verbatim** → `.ciagent/` files discuss banned terms by name for governance but are excluded from the firewall; the reference page is NOT excluded, so it must use safe phrasings. Mitigation: docs-writer rewrites in user-facing prose; firewall scans `docs/reference/architecture-index.md`.
 ---
 ## Phase P4 — Bearers Skeleton I (exit/bridge/bearers/partner-Anchor)
 - **Slug**: `bearers-skeleton-i`
 - **Branch**: `oy/phase/04-bearers-skeleton-i`
 - **REQs covered**: REQ-010 (Exit layer: x/bridge + x/exit), REQ-022 (Bearers OY-SAT/OY-QR), REQ-023 (Anchors — x/partner extension)
 - **Tag**: `v0.2.4`
 - **Type**: `feat`
 - **Persona**: backend-engineer (all Go modules; the v0.2 cosmos-engineer/security-engineer split is collapsed per A-315)
 - **Goal**: Ship the Bearers skeleton I: `x/bridge` (L2↔L1 bridge types) FIRST, then `x/exit` (exit routes + DEXSwap, referencing bridge by ID-string), then `x/bearers` extension (OY-SAT/OY-QR transport stubs), then `x/partner` extension (Anchor credential types — referenced by x/hub in P5).
 ### Wave 1 — x/bridge types FIRST (intra-P4 ordering: bridge before exit)
 | Task ID | REQ | Persona | Files | Deliverable | Must-have verification | Blocked-by |
 |---|---|---|---|---|---|---|
 | P4-01-01 | REQ-010 | backend-engineer | `x/bridge/types/types.go` + `x/bridge/types/genesis.go` | New `x/bridge/types/` module following the `x/satellite` pattern (D-036, A-302). `BridgeStatus` enum (Pending, Attested, Active, Closed) — exactly 4, locked-const `BridgeStatusCount = 4` (A-312 names HubServiceCount; BridgeStatusCount is the bridge analog). `AllBridgeStatuses() []BridgeStatus`. `BridgeRoute` struct (route-id, source-chain (L2Chain by-ID-string ref to `x/satellite` — G-003, no struct import), dest-chain (L2Chain by-ID-string), bridge-type (opaque string e.g. "ibc" — NOT a locked enum per A-308), transfer-channel-id (by-ID-string ref to a v0.2 satellite TransferChannel), watcher-quorum-id (by-ID-string ref to `x/watcher`, set when status becomes Attested), status). `Keeper` stub: AddBridgeRoute / GetBridgeRoute / ListByStatus. `Params`, `GenesisState` (routes), `DefaultGenesisState`, `ValidateGenesis` (reject dup route-ids, A-212). | `go build ./x/bridge/...` succeeds; `BridgeStatusCount == 4`; `AllBridgeStatuses()` returns 4 in vision order; `ValidateGenesis` rejects dup route-id; zero external deps (go.mod unchanged) | — |
 ### Wave 2 — x/exit types (blocked-by Wave 1 bridge)
 | Task ID | REQ | Persona | Files | Deliverable | Must-have verification | Blocked-by |
 |---|---|---|---|---|---|---|
 | P4-02-01 | REQ-010 | backend-engineer | `x/exit/types/types.go` + `x/exit/types/genesis.go` | New `x/exit/types/` module following `x/satellite` (D-036). `ExitStatus` enum (Proposed, InProgress, Settled, Failed, Refunded) — exactly 5, locked-const `ExitStatusCount = 5`. `AllExitStatuses() []ExitStatus`. `ExitRoute` struct (route-id, holder-reach-id (by-ID-string ref to `x/identity` — use "Holder"/"Reach" not "account"), source-asset (opaque string), dest-asset (opaque string), amount-grain (int64 — NOT a `x/bread` import; "Grain" by name only), min-received-grain, bridge-route-id (OPTIONAL, by-ID-string ref to `x/bridge` BridgeRoute for cross-chain exits — G-003), venue-hops []string, deadline, status). `DEXSwap` struct (swap-id, route-id (by-ID-string ref to ExitRoute), venue (opaque string — NOT a locked enum per A-308), input-asset, input-amount-grain, output-asset, output-amount-grain, executed-at). `Keeper` stub: AddExitRoute / GetExitRoute / ListByHolder. `Params`, `GenesisState` (routes + swaps), `DefaultGenesisState`, `ValidateGenesis` (reject dup route-ids + dup swap-ids, A-212). | `go build ./x/exit/...` succeeds; `ExitStatusCount == 5`; `AllExitStatuses()` returns 5 in vision order; `ValidateGenesis` rejects dup route-id + dup swap-id; the `bridge-route-id` field is a string (no `x/bridge` struct import — G-003 verified by the P1 G-003 import-invariant test, which now also scans the new x/exit + x/bridge files) | P4-01-01 |
 ### Wave 3 — x/exit tests + x/bridge tests (parallel; blocked-by Wave 1/2 types)
 | Task ID | REQ | Persona | Files | Deliverable | Must-have verification | Blocked-by |
 |---|---|---|---|---|---|---|
 | P4-01-02 | REQ-010, REQ-012 | backend-engineer | `x/bridge/types/types_test.go` (+ `genesis_test.go` if split) | Locked-const test: `BridgeStatusCount == 4`; `AllBridgeStatuses()` names match (Pending, Attested, Active, Closed); `BridgeRoute` struct round-trip (marshal/unmarshal); `bridge-route-id` references a satellite L2Chain by string (no `x/satellite` import — G-003 import-invariant test green); `watcher-quorum-id` is an opaque string (no `x/watcher` import); `ValidateGenesis` rejects dup route-id; **lexicon assertion** (no "bank"/"account"/"currency"/"dollar"/"euro" — use "Holder"/"Reach"/chain names); **G-003 import-invariant**: the P1-01-02 `go/parser` scan (extended to cover the new `x/bridge` + `x/exit` files) asserts NO production file imports another `x/<module>/types` by struct. | `go test ./x/bridge/...` passes; ≥80% coverage on `x/bridge/types`; BridgeStatusCount=4 locked-const; lexicon green; G-003 import-invariant green | P4-01-01 |
 | P4-02-02 | REQ-010, REQ-012 | backend-engineer | `x/exit/types/types_test.go` (+ `genesis_test.go` if split) | Locked-const test: `ExitStatusCount == 5`; `AllExitStatuses()` names match (Proposed, InProgress, Settled, Failed, Refunded); `ExitRoute` struct round-trip; `DEXSwap` struct round-trip; the `bridge-route-id` field references a BridgeRoute by string (no `x/bridge` struct import — G-003 verified); `venue` is an opaque string (A-308 — not a locked enum, so no enum-count test); `ValidateGenesis` rejects dup route-id + dup swap-id; **lexicon assertion** (no "account"/"currency"/"dollar"/"euro" — use "Holder"/"Reach"/opaque asset strings). | `go test ./x/exit/...` passes; ≥80% coverage on `x/exit/types`; ExitStatusCount=5 locked-const; lexicon green; G-003 import-invariant green | P4-02-01 |
 ### Wave 4 — x/bearers extension + x/partner extension (parallel; independent of Waves 1-3)
 | Task ID | REQ | Persona | Files | Deliverable | Must-have verification | Blocked-by |
 |---|---|---|---|---|---|---|
 | P4-03-01 | REQ-022 | backend-engineer | `x/bearers/types/types.go` (EXTEND existing) | **EXTEND** `x/bearers` (do NOT create new module — A-209/D-037; the BearerType enum + BearerTransport interface are locked since v0.1/v0.2). Add `OYSATLink` struct (gateway-id, constellation (opaque string e.g. "iridium"), frequency-mhz, surveillance-resistant LOCKED true for OY-SAT — A-311). Add `OYQRCode` struct (qr-id, payload-bytes (the signed transfer), issuer-reach-id, expires-at, consumed (bool — OY-QR is one-shot, A-311)). Both are transport-shape stubs (matching D-029: the v0.2 OYLRLink/BeaconFrame are struct stubs, not BearerTransport impls; v0.3 keeps the same shape-only approach). The existing `BearerType` enum + `AllBearers()` (6 bearers, including BearerOYSAT + BearerOYQR since v0.1) is UNCHANGED — v0.3 adds transport structs only. `GenesisState` unchanged. | `go build ./x/bearers/...` succeeds; `OYSATLink` + `OYQRCode` structs present; `OYSATLink.SurveillanceResistant` is LOCKED true; `OYQRCode.Consumed` field exists; existing `AllBearers()` unchanged (6 bearers — regression); zero external deps | — |
 | P4-04-01 | REQ-023 | backend-engineer | `x/partner/types/types.go` (EXTEND existing) | **EXTEND** `x/partner` (do NOT create new module — A-305; the 4-tier PartnerTier enum is locked since v0.2). Add `AnchorCredential` struct (partner-id (by-ID-string ref to the Anchor Partner), jurisdiction (opaque string e.g. "EU-MiCA"), custody-provider-id (by-ID-string ref to `x/hub` custody service — EMPTY in v0.3 skeleton per A-304, hub not live until P5/v0.4), attestation-refs []string (opaque URIs to Watcher/auditor attestations), onboarded-at). Add `Partner.AnchorCredential() *AnchorCredential` accessor stub returning nil for non-Anchor tiers (A-305 prefers the accessor over a second top-level type). Add `Keeper.AddAnchorCredential(partnerID, cred)` convenience method (rejects non-Anchor partner-id); `Keeper.ListAnchors()` = `ListByTier(TierAnchor)` alias. `PartnerTier` enum (4 tiers) UNCHANGED — v0.3 adds Anchor-specific fields, not a new tier. | `go build ./x/partner/...` succeeds; `AnchorCredential` struct present; `Partner.AnchorCredential()` returns nil for non-Anchor; `AddAnchorCredential` rejects non-Anchor partner-id; `AllPartnerTiers()` unchanged (4 tiers — regression); `custody-provider-id` field is a string (no `x/hub` import — G-003; x/hub does not exist yet, lands in P5) | — |
 ### Wave 5 — x/bearers + x/partner tests (parallel; blocked-by Wave 4)
 | Task ID | REQ | Persona | Files | Deliverable | Must-have verification | Blocked-by |
 |---|---|---|---|---|---|---|
 | P4-03-02 | REQ-022, REQ-012 | backend-engineer | `x/bearers/types/types_test.go` (EXTEND existing) | `OYSATLink` struct round-trip + `SurveillanceResistant == true` (LOCKED — A-311); `OYQRCode` struct round-trip + `Consumed` flips true (one-shot); BearerOYSAT + BearerOYQR still in `AllBearers()` (regression: existing v0.1/v0.2 bearers tests still green — 6 bearers unchanged); existing v0.2 OYLRLink/BeaconFrame tests still green (no regression); **lexicon assertion** (extend existing). | `go test ./x/bearers/...` passes; ≥80% coverage on `x/bearers/types`; OY-SAT surveillance-resistant LOCKED true; OY-QR one-shot; existing v0.1/v0.2 bearers tests green (no regression) | P4-03-01 |
 | P4-04-02 | REQ-023, REQ-012 | backend-engineer | `x/partner/types/types_test.go` (EXTEND existing) | `AnchorCredential` struct round-trip; `Partner.AnchorCredential()` returns nil for non-Anchor tiers; `AddAnchorCredential` rejects non-Anchor partner-id; `ListAnchors()` returns only Anchor-tier partners; `AllPartnerTiers()` unchanged (4 tiers — regression: v0.2 partner tests still green); `custody-provider-id` is an opaque string (no `x/hub` import — G-003 import-invariant green); **lexicon assertion** (extend existing — no "bank"/"account"; "custody"/"jurisdiction"/"compliance" safe). | `go test ./x/partner/...` passes; ≥80% coverage on `x/partner/types`; Anchor accessor + AddAnchorCredential behavior; existing v0.2 partner tests green (no regression) | P4-04-01 |
 ### Wave 6 — Phase verification + ship
 | Task ID | REQ | Persona | Files | Deliverable | Must-have verification | Blocked-by |
 |---|---|---|---|---|---|---|
 | P4-05-01 | REQ-012, REQ-010, REQ-022, REQ-023 | lead-developer | (cross-cutting) | Run `go build ./...` + `go test ./...` green (incl. v0.1/v0.2 baseline + docs firewall + new x/bridge, x/exit, x/bearers ext, x/partner ext); coverage ≥80% on the 4 P4 packages; 4 lexicon assertions present; G-003 import-invariant green (extended to scan the new x/bridge + x/exit + x/bearers + x/partner files); `lexicon_meta_test.go` (v0.2, x/*.go scan) green; `lexicon_meta_docs_test.go` (v0.3, docs scan) green; zero external deps (go.mod unchanged); tag `v0.2.4`. | `go test ./...` green; coverage ≥80% on `x/bridge/types`, `x/exit/types`, `x/bearers/types`, `x/partner/types`; 4 lexicon assertions; G-003 import-invariant green; zero require lines in go.mod; git tag `v0.2.4` | P4-01-02, P4-02-02, P4-03-02, P4-04-02 |
 ### P4 Must-Haves
 - [ ] `x/bridge` (new), `x/exit` (new), `x/bearers` (extended), `x/partner` (extended) each have `types/types.go` + `types/types_test.go` (v0.1/v0.2 pattern, package `types`, zero external deps).
 - [ ] `go build ./...` and `go test ./...` green — **including all v0.1/v0.2 baseline tests + docs firewall (no regression)**.
 - [ ] ≥80% coverage on `x/bridge/types`, `x/exit/types`, `x/bearers/types`, `x/partner/types`.
 - [ ] Bridge locked-const: `BridgeStatusCount == 4` (Pending, Attested, Active, Closed).
 - [ ] Exit locked-const: `ExitStatusCount == 5` (Proposed, InProgress, Settled, Failed, Refunded).
 - [ ] Exit `bridge-route-id` is a by-ID-string ref to `x/bridge` (G-003 — no struct import; import-invariant test green).
 - [ ] Bearers: `OYSATLink` (surveillance-resistant LOCKED true) + `OYQRCode` (one-shot `consumed`); existing `AllBearers()` (6) unchanged.
 - [ ] Partner: `AnchorCredential` struct + `Partner.AnchorCredential()` accessor (nil for non-Anchor); `PartnerTier` (4) unchanged.
 - [ ] Partner Anchor `custody-provider-id` is an opaque string (no `x/hub` import — x/hub lands in P5).
 - [ ] Lexicon assertion in all 4 P4 test files.
 - [ ] `lexicon_meta_test.go` (v0.2, x/*.go) green; `lexicon_meta_docs_test.go` (v0.3, docs) green.
 - [ ] Zero external deps (go.mod unchanged — G-006).
 - [ ] Git tag `v0.2.4`.
 ### P4 Risks & Mitigations
 - **Intra-P4 ordering (bridge before exit)** (A-308/G-003) → Wave 1 lands `x/bridge` types; Wave 2 lands `x/exit` (references bridge by ID); Wave 3 lands both tests. Reversing would force `x/exit` tests to reference a non-existent BridgeRoute type.
 - **"venue" as a locked enum** (A-308) → `venue` is an opaque string, NOT a locked enum; venues are operational (uniswap-v3/v4, oy-dex) and locking now would create a false firewall. Test asserts no enum-count for venue.
 - **Bearers extension regression** → existing v0.1/v0.2 bearers tests must stay green; `AllBearers()` count unchanged (6); test asserts no regression.
 - **Partner Anchor → hub forward-reference** → `custody-provider-id` is an EMPTY string in v0.3 (hub not live until P5); the field exists so the shape is stable. This is the P4→P5 edge (D-044).
 - **"account"/"currency"/"dollar"/"euro" lexicon drift in exit** → use "Holder"/"Reach"/opaque asset strings; lexicon assertion + meta-test are the gate.
 ---
 ## Phase P5 — Bearers Skeleton II (hub/services/bond)
 - **Slug**: `bearers-skeleton-ii`
 - **Branch**: `oy/phase/05-bearers-skeleton-ii`
 - **REQs covered**: REQ-024 (Hub API — x/hub), REQ-025 (Services — x/services), REQ-026 (Bond market depth — x/bond extension)
 - **Tag**: `v0.2.5`
 - **Type**: `feat`
 - **Persona**: backend-engineer
 - **Goal**: Ship the Bearers skeleton II: `x/hub` (HubService enum + per-service stubs, referencing Anchor partners by ID), `x/services` (ServiceKind enum + per-service stubs, referencing Window by ID), and `x/bond` extension (GrowthBond + secondary-market order types; 8%/0% consts unchanged — D-028 regression firewall). P5 has NO intra-phase ordering (hub, services, bond are independent of each other).
 ### Wave 1 — x/hub types + tests (blocked-by P4 partner Anchor for the operator-partner-id reference)
 | Task ID | REQ | Persona | Files | Deliverable | Must-have verification | Blocked-by |
 |---|---|---|---|---|---|---|
 | P5-01-01 | REQ-024 | backend-engineer | `x/hub/types/types.go` + `x/hub/types/genesis.go` + `x/hub/types/types_test.go` (+ `genesis_test.go` if split) | New `x/hub/types/` module following `x/forex` (D-039, A-303). `HubService` enum (Custody, LendingPrimitive, Compliance) — exactly 3, locked-const `HubServiceCount = 3` (A-312); `AllHubServices() []HubService`. `HubServiceInfo` struct (service-id, kind (HubService), operator-partner-id (by-ID-string ref to `x/partner` Anchor — G-003, no struct import; the P4 Anchor must exist), name, status). `HubServiceStatus` enum (Pending, Active, Suspended, Revoked) — exactly 4 (local redefinition of the v0.2 PartnerStatus 4-state shape, no import). Per-service struct stubs: `CustodyService` (service-id, custody-provider-id, assets-supported []string), `LendingPrimitiveService` (service-id, primitive-kind (opaque string), coupon-cap-bps uint32 — LOCAL const `LendingCouponCapBps = 800` cross-documented to D-028/A-304, NOT an import of `x/bond.Clamp`), `ComplianceService` (service-id, jurisdiction, attestation-refs []string). `Keeper` stub: AddService / GetService / ListByKind. `Params`, `GenesisState` (services), `DefaultGenesisState`, `ValidateGenesis` (reject dup service-ids, A-212). **Tests**: HubServiceCount=3 locked-const; enum names; service round-trip; per-service struct fields; `LendingCouponCapBps == 800` (cross-doc to D-028); `operator-partner-id` is a string (no `x/partner` struct import — G-003 import-invariant green); `ValidateGenesis` rejects dup service-id; **lexicon assertion** (HIGH-RISK: "interest"/"yield"/"deposit"/"savings" banned — use "lending primitive"/"coupon"/"custody"/"compliance"; "lending" is NOT banned per RESEARCH §1.5). | `go build ./x/hub/...` succeeds; `go test ./x/hub/...` passes; ≥80% coverage; `HubServiceCount == 3`; `LendingCouponCapBps == 800`; lexicon green; G-003 import-invariant green | P4-05-01 |
 ### Wave 2 — x/services types + tests (parallel with Wave 1; independent)
 | Task ID | REQ | Persona | Files | Deliverable | Must-have verification | Blocked-by |
 |---|---|---|---|---|---|---|
 | P5-02-01 | REQ-025 | backend-engineer | `x/services/types/types.go` + `x/services/types/genesis.go` + `x/services/types/types_test.go` (+ `genesis_test.go` if split) | New `x/services/types/` module following `x/hub` (D-040, A-307). `ServiceKind` enum (Care, SIM, Vault, Mail) — exactly 4, locked-const `ServiceKindCount = 4` (A-307); `AllServiceKinds() []ServiceKind`. `ServiceInfo` struct (service-id, kind (ServiceKind), operator-reach-id (by-ID-string ref to `x/identity` Reach — G-003), name, status, window-id (by-ID-string ref to `x/window` — a service-grant opens a Window on the holder's behalf; the Window Lifecycle interface hook, typed in v0.3, invoked at runtime in v0.4)). `ServiceStatus` enum (Pending, Active, Suspended, Revoked) — exactly 4 (local redefinition). Per-service struct stubs: `CareService` (service-id, care-kind (opaque)), `SIMService` (service-id, carrier (opaque)), `VaultService` (service-id, storage-quota-grain), `MailService` (service-id, mailbox-id). `Keeper` stub: AddService / GetService / ListByKind. `Params`, `GenesisState` (services), `DefaultGenesisState`, `ValidateGenesis` (reject dup service-ids, A-212). **Tests**: ServiceKindCount=4 locked-const; enum names (Care, SIM, Vault, Mail); service round-trip; per-service struct fields; `window-id` is a string (no `x/window` struct import — G-003 import-invariant green); `operator-reach-id` is a string (no `x/identity` import); `ValidateGenesis` rejects dup service-id; **lexicon assertion** (no "account" — use service-id/operator-reach-id; "Mail"/"SIM"/"Care"/"Vault" safe). | `go build ./x/services/...` succeeds; `go test ./x/services/...` passes; ≥80% coverage; `ServiceKindCount == 4`; lexicon green; G-003 import-invariant green | P4-05-01 (P5 has no intra-phase dep; blocked-by P4 ship for branch hygiene + the G-003 import-invariant test scanning the new files) |
 ### Wave 3 — x/bond extension (GrowthBond + secondary market) + tests (parallel with Waves 1/2; independent)
 | Task ID | REQ | Persona | Files | Deliverable | Must-have verification | Blocked-by |
 |---|---|---|---|---|---|---|
 | P5-03-01 | REQ-026 | backend-engineer | `x/bond/types/types.go` (EXTEND) + `x/bond/types/genesis.go` (EXTEND) + `x/bond/types/types_test.go` (EXTEND) | **EXTEND** `x/bond` (do NOT create new module — D-041; the 8%/0% consts are locked since v0.2 and UNCHANGED in v0.3). Add `GrowthBond` struct embedding the v0.2 `Bond` + a `GrowthRateBps` field (per-period growth rate of the coupon). Add `ClampGrowth(currentBps, growthBps uint32) uint32` helper returning `min(CouponCapBps - currentBps, growthBps)` so the post-growth coupon is ≤ `CouponCapBps` (A-306 — reuses the v0.2 `CouponCapBps`/`CouponFloorBps` consts, same package, no G-003 concern). Add `SecondaryOrder` struct (order-id, bond-id (by-ID-string ref to the Bond), side (`OrderSide` enum), price-bps (fraction of principal in bps), quantity-grain, holder-reach-id, status (`OrderStatus` enum), created-at). Add `OrderSide` enum (Buy, Sell) — exactly 2, locked-const `OrderSideCount = 2` (A-313). Add `OrderStatus` enum (Open, Filled, Cancelled) — exactly 3, locked-const `OrderStatusCount = 3` (A-313). `AllOrderSides()` / `AllOrderStatuses()`. Extend `Keeper` stub: AddOrder / GetOrder / ListByBond / CancelOrder (no matching — full secondary-market matching deferred to v0.4). Extend `GenesisState` with `GrowthBonds []GrowthBond` + `Orders []SecondaryOrder`; `ValidateGenesis` checks growth-bond-id + order-id uniqueness (A-212). **Tests (extend existing)**: **REGRESSION: `CouponCapBps == 800` and `CouponFloorBps == 0` STILL (D-028 firewall — v0.3 must not change the v0.2 consts)**; `ClampGrowth` invariant (post-growth coupon ≤ 800, never below 0; current + growth where current+growth > cap → growth clamped to cap-current); `OrderSideCount == 2`; `OrderStatusCount == 3`; order round-trip; GrowthBond round-trip; `bond-id` is a string (no struct self-import — same package); existing v0.2 bond tests still green (Clamp, BondStatus, etc. — no regression); **lexicon assertion** (HIGH-RISK: "interest"/"yield"/"deposit"/"savings" banned — use "coupon"/"growth"/"secondary"/"order"; "growth" safe, "yield growth" banned — use "coupon growth"/"real-return-linked coupon"). | `go build ./x/bond/...` succeeds; `go test ./x/bond/...` passes; ≥80% coverage; **`CouponCapBps == 800` + `CouponFloorBps == 0` regression green**; `ClampGrowth` invariant green; `OrderSideCount == 2` + `OrderStatusCount == 3`; existing v0.2 bond tests green (no regression); lexicon green | P4-05-01 |
 ### Wave 4 — Phase verification + ship
 | Task ID | REQ | Persona | Files | Deliverable | Must-have verification | Blocked-by |
 |---|---|---|---|---|---|---|
 | P5-04-01 | REQ-012, REQ-024, REQ-025, REQ-026 | lead-developer | (cross-cutting) | Run `go build ./...` + `go test ./...` green (incl. v0.1/v0.2 baseline + docs firewall + P4 + P5); coverage ≥80% on `x/hub/types`, `x/services/types`, `x/bond/types`; 3 lexicon assertions (hub, services, bond-ext); G-003 import-invariant green (extended to scan x/hub + x/services + x/bond); `lexicon_meta_test.go` (v0.2) + `lexicon_meta_docs_test.go` (v0.3) green; **D-028 regression: 8%/0% bond consts unchanged**; zero external deps (go.mod unchanged); tag `v0.2.5`. | `go test ./...` green; coverage ≥80% on `x/hub/types`, `x/services/types`, `x/bond/types`; 3 lexicon assertions; G-003 import-invariant green; `CouponCapBps == 800` + `CouponFloorBps == 0` regression green; zero require lines in go.mod; git tag `v0.2.5` | P5-01-01, P5-02-01, P5-03-01 |
 ### P5 Must-Haves
 - [ ] `x/hub` (new), `x/services` (new), `x/bond` (extended) each have `types/types.go` + `types/types_test.go`.
 - [ ] `go build ./...` and `go test ./...` green — including v0.1/v0.2 baseline + docs firewall + P4 (no regression).
 - [ ] ≥80% coverage on `x/hub/types`, `x/services/types`, `x/bond/types`.
 - [ ] Hub locked-const: `HubServiceCount == 3` (Custody, LendingPrimitive, Compliance); `LendingCouponCapBps == 800` (cross-doc to D-028, local const — no `x/bond` import).
 - [ ] Hub `operator-partner-id` is a by-ID-string ref to `x/partner` Anchor (G-003 — no struct import; import-invariant green). This confirms P4→P5 ordering.
 - [ ] Services locked-const: `ServiceKindCount == 4` (Care, SIM, Vault, Mail).
 - [ ] Services `window-id` is a by-ID-string ref to `x/window` (G-003); `operator-reach-id` is a by-ID-string ref to `x/identity`.
 - [ ] Bond: `GrowthBond` + `ClampGrowth` (post-growth coupon ≤ 800); `OrderSideCount == 2` (Buy/Sell); `OrderStatusCount == 3` (Open/Filled/Cancelled).
 - [ ] **D-028 regression: `CouponCapBps == 800` and `CouponFloorBps == 0` unchanged** (v0.3 must not change v0.2 bond consts).
 - [ ] Existing v0.2 bond tests still green (no regression).
 - [ ] Lexicon assertion in all 3 P5 test files.
 - [ ] `lexicon_meta_test.go` (v0.2, x/*.go) green; `lexicon_meta_docs_test.go` (v0.3, docs) green.
 - [ ] Zero external deps (go.mod unchanged — G-006).
 - [ ] Git tag `v0.2.5`.
 ### P5 Risks & Mitigations
 - **Hub lending-primitive lexicon risk** (HIGHEST v0.3 lexicon risk after x/bond) → "interest"/"yield"/"deposit"/"savings" are natural fit-words for a lending primitive; use "lending primitive"/"coupon" (vision §13/§17). "lending" is NOT banned (RESEARCH §1.5); the lexicon assertion is the gate. The local `LendingCouponCapBps = 800` const cross-documents D-028 (A-304) to avoid importing `x/bond.Clamp` (G-003).
 - **GrowthBond "yield growth" phrasing** → use "coupon growth"/"real-return-linked coupon"; "yield" is banned standalone (word-boundary); `TestLexiconMetaNoFalsePositiveOnOpenYield` allows "OpenYield" but bans "yield".
 - **D-028 const regression** → the v0.3 GrowthBond must NOT change `CouponCapBps`/`CouponFloorBps`; the regression test (8%/0% unchanged) is the D-028 firewall.
 - **ServiceKind "Vault" naming collision with `x/vault`** → the `Vault` enum value is a service kind (in `x/services`), not a module import; `VaultService` references `x/vault` by ID-string (G-003). No Go import cycle (concept-level collision only).
 - **Hub → partner Anchor forward-reference** → P4 must ship before P5 (D-044); the P5-04-01 verification confirms `operator-partner-id` is a string (no `x/partner` struct import).
 ---
 ## Phase P6 — Final Review + Audit + Ship
 - **Slug**: `final-review-audit-ship`
 - **Branch**: `oy/phase/06-final-review-audit-ship`
 - **REQs covered**: REQ-012 (lexicon, project-wide meta-test + docs firewall), all v0.3 REQs (REQ-010, REQ-022..REQ-028 audit confirmation)
 - **Tag**: `v0.2.6` (= **milestone v0.3 release** — final phase patch IS the milestone release per D-008/D-034)
 - **Type**: `final`
 - **Personas**: lead-developer (review/ship), backend-engineer (audit assist), ci-code-reviewer + ci-doc-verifier + ci-debugger (CI personas, activated for P6)
 - **Goal**: Run the full v0.3 milestone audit — project-wide lexicon meta-test + docs firewall, coverage gate across all 7 new/extended x/* packages, all locked-const invariants green (incl. D-028 regression), all docs pages lexicon-clean, all v0.3 REQs have skeleton+tests or docs — then ship the `v0.3` milestone release as tag `v0.2.6`.
 ### Wave 1 — ci-code-review (multi-persona review across P1-P5)
 | Task ID | REQ | Persona | Files | Deliverable | Must-have verification | Blocked-by |
 |---|---|---|---|---|---|---|
 | P6-01-01 | REQ-012, all v0.3 | lead-developer + ci-code-reviewer | (cross-cutting) | **Code review** across P1-P5: confirm `go build ./...` + `go test ./...` green; confirm `lexicon_meta_test.go` (v0.2, x/*.go) green AND scans all 22 x/* packages (v0.1 15 + v0.2 10 + v0.3 7 = 32? — recount: v0.1=15, v0.2 added 10 new/extended to 25, v0.3 adds 4 new + 3 extended = 7 → 25 + 4 new = 29 distinct packages; the 3 extended are already counted); confirm `lexicon_meta_docs_test.go` (v0.3, docs) green AND scans README.md + all `docs/**/*.md` (26 pages); confirm G-003 import-invariant green across all v0.3 x/* files (no struct imports across `x/<module>/types`); confirm zero external deps (go.mod: `module github.com/oy/openyield\ngo 1.22` with no require lines — G-006). | `go test ./...` green; both firewalls green; G-003 import-invariant green; go.mod zero-dep confirmed; coverage report generated | P5-04-01 |
 ### Wave 2 — ciagent-audit (reconstruction + discipline)
 | Task ID | REQ | Persona | Files | Deliverable | Must-have verification | Blocked-by |
 |---|---|---|---|---|---|---|
 | P6-02-01 | all v0.3 | lead-developer + ci-debugger | (cross-cutting) | **Reconstruction test**: confirm every v0.3 REQ maps to a shipped artifact (REQ-010 → x/bridge + x/exit; REQ-022 → x/bearers OYSATLink/OYQRCode; REQ-023 → x/partner AnchorCredential; REQ-024 → x/hub; REQ-025 → x/services; REQ-026 → x/bond GrowthBond/SecondaryOrder; REQ-027 → README + docs/ 26 pages; REQ-028 → lexicon_meta_docs_test.go). **File/branch/commit discipline**: confirm each phase P1..P5 shipped on its own branch (`oy/phase/0N-*`) with its patch tag (`v0.2.1..v0.2.5`); confirm no phase branch merged out of order (D-044: P1 firewall before P2/P3 content; P4 before P5 for Anchor→hub). **Locked-const audit**: HubServiceCount=3, ServiceKindCount=4, BridgeStatusCount=4, ExitStatusCount=5, OrderSideCount=2, OrderStatusCount=3, LendingCouponCapBps=800, **D-028 regression: CouponCapBps=800 + CouponFloorBps=0 unchanged**. | REQ→artifact map complete (each REQ has a file); branch/tag discipline confirmed (5 phase branches + 5 patch tags); all locked-consts green; D-028 regression green | P6-01-01 |
 ### Wave 3 — ciagent-ship (merge + tag + release + cleanup)
 | Task ID | REQ | Persona | Files | Deliverable | Must-have verification | Blocked-by |
 |---|---|---|---|---|---|---|
 | P6-03-01 | (milestone) | lead-developer + ci-doc-verifier | `.ciagent/oy/REQUIREMENTS.md` + `.ciagent/oy/ROADMAP.md` | **Update REQUIREMENTS.md**: mark REQ-010, REQ-022, REQ-023, REQ-024, REQ-025, REQ-026 → Skeleton; REQ-027 → Complete; REQ-028 → Complete. **Update ROADMAP.md**: mark v0.3 milestone COMPLETE (all 7 phases P0..P6 checked); add the tag-line note that v0.3 shipped on the `v0.2.x` patch line (P0 → `v0.2.0`, P1..P5 → `v0.2.1..v0.2.5`, P6 → `v0.2.6` = milestone release, per D-008/D-034). | REQUIREMENTS.md status column updated for all 8 v0.3 REQs; ROADMAP.md v0.3 marked complete + tag-line note present | P6-02-01 |
 | P6-03-02 | (milestone) | lead-developer | (cross-cutting) | **Final ship**: merge phase/06 → milestone/v0.3 → main; create milestone release tag `v0.2.6` (= v0.3 milestone release per D-008/D-034); delete the 5 phase branches (`oy/phase/01-*`..`oy/phase/05-*`) after merge (P6 branch retained until post-release cleanup); confirm `go build ./...` + `go test ./...` green at the `v0.2.6` tag. | `v0.2.6` tag created on main; `go test ./...` green at the tag; ROADMAP.md v0.3 complete; phase branches deleted (except P6); release notes reference v0.3 scope (Bearers skeleton I+II + docs site + firewall extension) | P6-03-01 |
 ### P6 Must-Haves
 - [ ] Project-wide lexicon meta-test (`lexicon_meta_test.go`, x/*.go) scans all 29 x/* packages (v0.1 15 + v0.2 10 + v0.3 4 new; 3 extended already counted); green.
 - [ ] Docs firewall (`lexicon_meta_docs_test.go`) scans README.md + all 26 `docs/**/*.md` pages; green.
 - [ ] Coverage ≥80% on all 7 new/extended v0.3 x/* packages (bridge, exit, bearers-ext, partner-ext, hub, services, bond-ext).
 - [ ] All locked-const invariants green: HubServiceCount=3, ServiceKindCount=4, BridgeStatusCount=4, ExitStatusCount=5, OrderSideCount=2, OrderStatusCount=3, LendingCouponCapBps=800, OYSATLink surveillance-resistant=true, OYQRCode one-shot consumed.
 - [ ] **D-028 regression**: `CouponCapBps == 800`, `CouponFloorBps == 0` unchanged from v0.2.
 - [ ] All v0.1/v0.2 baseline tests still green (no regression across 29 x/* packages + docs).
 - [ ] G-003 import-invariant green (no struct imports across `x/<module>/types` in any v0.3 production file).
 - [ ] Zero external deps (go.mod unchanged — G-006).
 - [ ] REQUIREMENTS.md status column updated (REQ-010/022..026 → Skeleton; REQ-027/028 → Complete).
 - [ ] ROADMAP.md v0.3 marked COMPLETE + tag-line note (`v0.2.x` patch line).
 - [ ] `go build ./...` and `go test ./...` green at the `v0.2.6` tag.
 - [ ] Git tag `v0.2.6` created (= v0.3 milestone release).
 - [ ] Phase branches P1..P5 deleted post-merge (P6 retained until post-release cleanup).
 ### P6 Risks & Mitigations
 - **Lexicon drift via copy-pasted comments in v0.3 x/* modules** → the v0.2 meta-test scans comments + strings + identifiers; v0.3 modules are automatically covered (no new meta-test work, just the existing scan).
 - **D-028 const regression at the last mile** → P5-03-01 + P6-02-01 both assert 8%/0% unchanged; double firewall.
 - **Milestone versioning confusion (v0.3 milestone = v0.2.6 tag)** → lead-developer enforces D-008/D-034: final phase patch IS the milestone release; no separate minor tag. ROADMAP tag-line note (P6-03-01) prevents `v0.2.6`/`v0.3.0` confusion.
 ---
 ## Coverage Targets (D-033) — v0.3
 | Package | Phase | Target | Locked-const tests |
 |---|---|---|---|
 | `x/bridge/types` | P4 | ≥80% | BridgeStatusCount=4 (Pending, Attested, Active, Closed) |
 | `x/exit/types` | P4 | ≥80% | ExitStatusCount=5 (Proposed, InProgress, Settled, Failed, Refunded) |
 | `x/bearers/types` (ext) | P4 | ≥80% | OYSATLink surveillance-resistant=true (A-311); OYQRCode one-shot consumed; AllBearers()=6 unchanged (regression) |
 | `x/partner/types` (ext) | P4 | ≥80% | AllPartnerTiers()=4 unchanged (regression); AnchorCredential accessor nil-for-non-Anchor |
 | `x/hub/types` | P5 | ≥80% | HubServiceCount=3; LendingCouponCapBps=800 (cross-doc D-028/A-304) |
 | `x/services/types` | P5 | ≥80% | ServiceKindCount=4 (Care, SIM, Vault, Mail) |
 | `x/bond/types` (ext) | P5 | ≥80% | **CouponCapBps=800 + CouponFloorBps=0 unchanged (D-028 regression)**; ClampGrowth post-growth ≤ 800; OrderSideCount=2; OrderStatusCount=3 |
 **Lexicon assertions (REQ-012)**: present in all 7 new/extended v0.3 test files (per-package) + project-wide `lexicon_meta_test.go` (v0.2, x/*.go — automatically covers v0.3 x/* files) + `lexicon_meta_docs_test.go` (v0.3, README.md + docs/**/*.md).
 ---
 ## Task Count Summary — v0.3
 | Phase | Waves | Tasks | New/Extended Packages / Docs |
 |---|---|---|---|
 | P1 | 3 | 11 | lexicon_meta_docs_test.go + mkdocs.yml + README.md + docs/index.md + 6 docs/shared/ pages |
 | P2 | 2 | 9 | 8 docs/nomads/ pages |
 | P3 | 3 | 12 | 8 docs/freeholders/ pages + 2 docs/reference/ pages |
 | P4 | 6 | 9 | x/bridge (new), x/exit (new), x/bearers (ext), x/partner (ext) |
 | P5 | 4 | 5 | x/hub (new), x/services (new), x/bond (ext) |
 | P6 | 3 | 4 | (audit/ship, 0 new — audit + REQUIREMENTS/ROADMAP update + tag) |
 | **Total** | — | **50** | **4 new x/* + 3 extended x/* + 26 docs pages + 1 firewall test** |
 ## Per-Phase REQ Coverage — v0.3
 | Phase | REQs | Components / Docs |
 |---|---|---|
 | P1 | REQ-028, REQ-027 | Docs firewall (lexicon_meta_docs_test.go) + mkdocs.yml + README + docs/index + docs/shared (6 pages) |
 | P2 | REQ-027 | docs/nomads (8 pages: Reach, Stash, bearers, Maps/Pay, Pacts, standing-basics, Window, index) |
 | P3 | REQ-027 | docs/freeholders (8 pages) + docs/reference (2 pages) — REQ-027 COMPLETE |
 | P4 | REQ-010, REQ-022, REQ-023 | x/bridge + x/exit (Exit layer), x/bearers OY-SAT/OY-QR, x/partner Anchor |
 | P5 | REQ-024, REQ-025, REQ-026 | x/hub, x/services, x/bond GrowthBond + secondary |
 | P6 | REQ-012 + all v0.3 REQs (audit) | Both firewalls, coverage gate, D-028 regression, milestone ship |
 ## Cross-Phase Blockers (hard) — v0.3
 - **P1-01-01 (docs firewall)** → blocks P1-02-* (README + shared content scanned by the firewall) and P2/P3 (audience content scanned).
 - **P4-01-01 (x/bridge types)** → blocks P4-02-01 (x/exit — `bridge-route-id` refs BridgeRoute by ID-string, A-308/G-003).
 - **P4-04-01 (x/partner Anchor extension)** → blocks P5-01-01 (x/hub — `operator-partner-id` refs Anchor by ID-string, A-304/G-003). This is the P4→P5 edge (D-044).
 - **P5-04-01 (P5 ship)** → blocks P6-01-01 (P6 audit).
 - All P(N) phase-ship tasks block P(N+1) Wave 1 tasks (soft ordering for branch hygiene; types themselves only depend on the listed hard blockers).
 ## v0.3 Decisions Applied (D-034..D-046 + A-301..A-315)
 The v0.3 Phase 0 clarify/ideate/research stages produced 13 clarification decisions (D-034..D-046) and 15 research assumptions (A-301..A-315), all applied to this plan:
 | ID | Decision / Assumption | Applied to |
 |---|---|---|
 | D-034 | v0.3 bundles Bearers skeleton + docs under one feature milestone; tags on v0.2.x | Milestone Summary, all phases |
 | D-035 | Bearers skeleton continues D-020 pattern (no live chain) | P4, P5 |
 | D-036 | REQ-010 = x/exit + x/bridge (two packages) | P4 Waves 1-3 |
 | D-037 | REQ-022 = x/bearers OYSATLink + OYQRCode | P4 Wave 4 |
 | D-038 | REQ-023 = x/partner AnchorCredential extension (no new tier) | P4 Wave 4 |
 | D-039 | REQ-024 = x/hub new module (Pact #6 promoted) | P5 Wave 1 |
 | D-040 | REQ-025 = x/services new module (4 kinds) | P5 Wave 2 |
 | D-041 | REQ-026 = x/bond GrowthBond + secondary (8%/0% unchanged) | P5 Wave 3 |
 | D-042 | MkDocs Material; audience-organized docs | P1-01-02, P2, P3 |
 | D-043 | Docs firewall = sibling test lexicon_meta_docs_test.go (not modifying v0.2 meta-test) | P1-01-01 |
 | D-044 | Phase ordering: firewall-first (P1) before content (P2/P3); P4 before P5 (Anchor→hub) | Cross-Phase Dependency Map, all phase goals |
 | D-045 | Docs depth: ~20-25 pages across 4 audiences | P1/P2/P3 page counts |
 | D-046 | No docs publishing CI in v0.3 | P1-01-02, P1-02-01 |
 | A-304 | x/hub LendingCouponCapBps=800 local const (no x/bond import) | P5-01-01 |
 | A-308 | x/exit venue is opaque string (not locked enum) | P4-02-01 |
 | A-311 | OY-SAT surveillance-resistant LOCKED true; OY-QR one-shot | P4-03-01 |
 | A-312 | HubServiceCount=3 | P5-01-01 |
 | A-313 | OrderSideCount=2, OrderStatusCount=3 | P5-03-01 |
 | A-315 | v0.2 cosmos-engineer/security-engineer NOT reactivated | Persona assignments (backend-engineer owns all P4/P5) |
@@ -61,33 +61,46 @@ OpenYield (OY) is a durable, anti-greed, jurisdiction-light financial layer —
 - D-009: Rebased history to fix v1.0 → v0.1 in ---ci--- blocks
 ## Milestone
-v0.2 — The Mesh (active milestone; feature type; tags run on the v0.1.x patch line)
+v0.3 — Bearers & Documentation (active milestone; feature type; tags run on the v0.2.x patch line)
-### v0.2 Scope (The Mesh — ROADMAP Phase 2)
+### v0.3 Scope (Bearers skeleton + Docs site — ROADMAP Phase 3 partial, plus a docs deliverable)
-Target: $1B annual volume, 4 service categories. Implements the pending Mesh-era requirements:
+
- **REQ-009** Satellite chains (Layer 2) — wrapped Bread, Pass-Act propagation on Polygon/Base/Arbitrum/Optimism/Solana [§7]
+This milestone bundles two parallel work-streams under one feature milestone:
- **REQ-011** Three Councils (Mesh, Guild, Stand) with Mission Lock — multi-source Voice [§19]
+
- **REQ-015** Window primitive — scope, duration, rate-limit, audit log, revoke [§10]
+**(A) Bearers skeleton (D-020 pattern continued)** — implements the v0.1 PROJECT.md
- **REQ-016** Nine Stand types (Household, Crew, Entity, Co-op, Circle, Trust, Foundation, Confederation, Shadow) [§11]
+out-of-scope items now promoted to v0.3 (ROADMAP Phase 3 "The Bearers" subset),
- **REQ-017** Guilds with Hand-Passes at 0% protocol fee [§12]
+as skeleton + tests (Go types + keeper stubs + invariant tests; no live chain):
- **REQ-018** Four-tier Partner Spectrum (Op, Master Op, Pier, Anchor) [§13]
+
- **REQ-020** Six Pacts (Pause, Ground, Stance, Cover, Stand Registry, Hub API) [§16]
+- **REQ-010** Exit layer (Layer 3) — DEX swaps, bridges, off-mesh services (§7). Promoted from Skeleton to a fuller skeleton: `x/exit` (exit-route types) + `x/bridge` (L2↔L1 bridge types). Live runtime deferred to v0.4.
- **REQ-021** Mesh Bond Market with 8% upper coupon cap, 0% floor [§17]
+- **Bearers expansion** — OY-SAT (satellite) + OY-QR bearer transport types, extending `x/bearers` (D-029 pattern). Hardware integration deferred.
- Bearers expansion: OY-LR + Beacon v1
+- **Anchors** — first institutional Partner tier (`x/partner` extension: Anchor credential types). REQ-018 promoted from Skeleton → fuller skeleton.
- Forex Engine v1
+- **Hub API** — B2B backbone: custody, lending primitive, compliance types (`x/hub`). Full B2B suite deferred to v0.4.
 - **Services** — Care / SIM / Vault / Mail service types (`x/services`). Live services deferred.
 - **Bond market depth** — Growth Bonds + secondary-market types, extending `x/bond` (REQ-021 promoted from Skeleton → fuller skeleton). Full market depth deferred.
 **(B) Documentation deliverable** — README.md + docs site in `docs/` for nomads and freeholders:
 - Repo-root `README.md` (lexicon-clean project overview).
 - MkDocs Material site (`mkdocs.yml` + `docs/`), organized by audience:
  - `docs/nomads/` — Reach path, Stash, bearers, Maps/Pay, six Pacts, standing basics.
  - `docs/freeholders/` — Four Freeholder signals, Bayesian Standing, Stands/Guilds, Councils/Voice, Bonds, Partner spectrum.
  - `docs/shared/` — Six Principles, Bread Scale, Storage pools, Watchers/Mirror, Lexicon glossary, Vision overview.
  - `docs/reference/` — architecture index, component map.
 - **REQ-012 firewall extension** — extend the lexicon meta-test to scan `README.md` + `docs/**/*.md` (new sibling `lexicon_meta_docs_test.go`), so the docs site is durably lexicon-clean. This is a `feat/test` phase.
 ### Milestone Type
-Feature (at least one `feat` phase). Phase 0 → `v0.1.0`; execution phases `v0.1.1..v0.1.N`; final phase patch IS the milestone release. No separate minor tag.
+Feature (Bearers phases are feat; docs phases are docs/test). Phase 0 → `v0.2.0`; execution phases `v0.2.1..v0.2.5`; final phase patch `v0.2.6` IS the milestone release. No separate minor tag.
-### Out of Scope (v0.2)
+### Out of Scope (v0.3)
- Cross-chain exit / DEX integration (Phase 3 / v0.3)
+- Live chain launch / real IBC channels / real bearer transports (D-020 pattern continues)
- OY-SAT, OY-QR bearers (Phase 3)
+- DEX integration runtime, full Hub API B2B suite runtime (types only in v0.3)
- Full Hub API B2B suite (Phase 3)
+- Yield Token, Travel + 11 service categories (ROADMAP Phase 4)
- Yield Token, Travel + 11 service categories (Phase 4)
+- i18n / versioning in MkDocs (single-language v0.3)
- Full Mesh Bond market depth (Phase 3+; v0.2 ships first Mesh Bonds only)
+- Cover Pool seniority mechanics (still deferred per PROJECT.md Q7)
-### Prior Milestone
+### Prior Milestones
-v0.1 — OpenYield Foundation Init (COMPLETE; pre-MVP foundation skeleton; released as v0.0.9 per run.md patch-line model)
+- v0.1 — OpenYield Foundation Init (COMPLETE; pre-MVP foundation skeleton; released as v0.0.9)
 - v0.2 — The Mesh (COMPLETE; skeleton + tests; released as v0.1.5)
 ## Clarification Decisions (Phase 0 — CLARIFY, autonomy=full)
@@ -108,4 +121,28 @@ Auto-decided defaults logged per clarify workflow Step 4 (full autonomy → acce
 | D-030 | **Forex Engine v1**: Forex pair type + rate-oracle interface + stub keeper; no live oracle integration | Live oracle integration depends on external partners (Piers), Phase 3. | 0.80 | [live oracle integration] |
 | D-031 | **Phase ordering** follows ARCHITECTURE.md blocker chain: P1 Orgs+Window foundation → P2 Pacts+Partners → P3 Councils+Forex → P4 Bonds+Bearers+L2. The final phase (P5) is review/ship. | Respects dependency graph; vertical slices keep each phase independently shippable. | 0.80 | [different wave ordering] |
 | D-032 | **Lexicon** enforced project-wide; all new modules must pass the lexicon assertion test (no banned terms). Non-negotiable. **Note (G-002)**: lexicon assertion tests are NEW in v0.2 — v0.1 is lexicon-clean in practice but has NO lexicon test firewall. v0.2 introduces the firewall (scaffolded in P1 per G-004, extended in P5). | REQ-012 is `All` phases. | 1.00 | [—] |
-| D-033 | **Test coverage target**: ≥80% on new keeper/type packages. v0.1 baseline = **53 tests across 11 test files** (corrected per G-001; not 48). Add lexicon assertion to each new module's test file. | Consistency with v0.1 quality bar (53 tests verified); lexicon drift is the highest-severity regression. | 0.85 | [lower coverage bar] |
+| D-033 | **Test coverage target**: ≥80% on new keeper/type packages. v0.1 baseline = **53 tests across 11 test files** (corrected per G-001; not 48). Add lexicon assertion to each new module's test file. | Consistency with v0.1 quality bar (53 tests verified); lexicon drift is the highest-severity regression. | 0.85 | [lower coverage bar] |
 ### v0.3 Clarification Decisions (Phase 0 — CLARIFY, autonomy=full)
 Auto-decided defaults logged per clarify workflow Step 4 (full autonomy → accept defaults, log decisions).
 | ID | Decision | Rationale | Confidence | Alternatives |
 |----|----------|-----------|------------|--------------|
 | D-034 | **v0.3 milestone bundles Bearers skeleton (D-020 pattern) + docs deliverable** under one feature milestone, rather than two separate NFR+feature milestones. Bearers phases are `feat`; docs phases are `docs`/`test`. Tags run on `v0.2.x`. | User request (--ideate) is docs-only but ROADMAP Phase 3 (Bearers) is the next queued feature work; bundling keeps the milestone cadence and avoids an NFR-only milestone that would not advance the protocol. Feature type because Bearers phases are feat. | 0.82 | [separate v0.3 docs NFR + v0.4 Bearers feature; or docs as patches on v0.2 line] |
 | D-035 | **Bearers skeleton continues the D-020 skeleton+tests pattern** (Go types + keeper stubs + invariant tests; no live chain, no real IBC channels, no real bearer transports). Live runtime for any Bearers component deferred to v0.4+. | v0.1/v0.2 both shipped skeleton-first; v0.3 stays consistent. Live runtime needs Watchers + Root Basket backing (Year 3 target). | 0.85 | [fuller keeper implementations in v0.3] |
 | D-036 | **REQ-010 Exit layer**: skeleton = `x/exit` (ExitRoute, DEXSwap types) + `x/bridge` (L2↔L1 bridge types, BridgeStatus enum). No live DEX integration. REQ-010 promoted from v0.1 Skeleton → v0.3 fuller skeleton (two packages instead of one). | Exit runtime needs Anchor partners + L2 bridges; v0.3 lands the typed shape. | 0.80 | [single x/exit package, defer all exit to v0.4] |
 | D-037 | **REQ-022 Bearers OY-SAT + OY-QR**: extend `x/bearers/types` with `OYSAT` + `OYQR` bearer transport types (BearerTransport interface already in v0.2). No hardware/RF runtime. D-029 pattern continued. | Hardware integration is not a software deliverable; v0.3 completes the 6-bearer type set (v0.2 had 4: Internet/OY-BLE/OY-WiFi-Direct + OY-LR/Beacon). | 0.82 | [real bearer runtime, defer OY-SAT/OY-QR to v0.4] |
 | D-038 | **REQ-023 Anchors**: extend `x/partner/types` with `Anchor` tier credential types (REQ-018 had the 4-tier enum; v0.3 adds Anchor-specific credential fields). No live institutional onboarding. | Anchors need Watchers + Hub API backing; v0.3 lands the credential shape. | 0.78 | [separate x/anchor module, defer Anchors to v0.4] |
 | D-039 | **REQ-024 Hub API**: new `x/hub` module — custody, lending-primitive, compliance type stubs (HubService enum + per-service structs). No live B2B runtime. Full Hub API B2B suite deferred to v0.4. | Hub API needs Anchors + Watchers; v0.3 lands the typed scaffold. | 0.80 | [full Hub API runtime in v0.3] |
 | D-040 | **REQ-025 Services**: new `x/services` module — Care/SIM/Vault/Mail service type stubs (ServiceKind enum + per-service structs). No live services. | Services are operational, not protocol-level; v0.3 lands the typed shape. | 0.78 | [full services runtime in v0.3] |
 | D-041 | **REQ-026 Bond market depth**: extend `x/bond/types` with GrowthBond type + secondary-market order types. 8% cap / 0% floor consts (D-028) unchanged. Full secondary-market matching deferred to v0.4. | v0.2 shipped first issuance; v0.3 adds depth types without a live matching engine. | 0.80 | [full bond market in v0.3] |
 | D-042 | **Docs deliverable (REQ-027)**: repo-root `README.md` + MkDocs Material site (`mkdocs.yml` + `docs/`). `mkdocs.yml` at repo root; `docs/` organized by audience: `docs/nomads/`, `docs/freeholders/`, `docs/shared/`, `docs/reference/`. Build-only Python dep (mkdocs + material); `go.mod` stays zero-dep. | User chose MkDocs Material + audience organization. MkDocs is Markdown-native, lightest toolchain; build-only dep does not affect Go modules (G-006). | 0.85 | [Hugo, Docusaurus, plain Markdown no generator] |
 | D-043 | **REQ-028 lexicon firewall extension**: new sibling test `lexicon_meta_docs_test.go` (package `lexicon_meta_docs`) scanning `README.md` + `docs/**/*.md` for the 10 banned terms, using the same `lexicon.FindBannedTerm` + word-boundary regex. Self-exclusion + fragment pattern preserved. `.ciagent/` files are NOT scanned (they are firewall meta-files, not user-facing docs). | REQ-012 is `All` phases and docs are user-facing; the firewall must cover docs to be durable. Extending the existing meta-test (not modifying it) preserves v0.2 coverage. | 0.88 | [single combined meta-test scanning both x/ and docs/] |
 | D-044 | **Phase ordering**: P1 docs foundation + firewall extension → P2 nomads docs → P3 freeholders docs → P4 Bearers skeleton I (exit/bridge/bearers/partner) → P5 Bearers skeleton II (hub/services/bond) → P6 final review/ship. Firewall lands in P1 BEFORE content (P2/P3) so docs are checked as authored. | Firewall-first ensures docs content is lexicon-clean by construction, not by retrofit. Bearers split across P4/P5 keeps each phase independently shippable (vertical slices). | 0.82 | [Bearers first then docs, or all docs in one phase] |
 | D-045 | **Docs depth per audience**: each audience section (nomads, freeholders) gets 5-8 Markdown pages covering its core REQs (nomads: Reach/Stash/bearers/Maps-Pay/Pacts/standing-basics; freeholders: 4 signals/Bayesian Standing/Stands-Guilds/Councils-Voice/Bonds/Partner spectrum). `docs/shared/` gets 5-6 concept pages. `docs/reference/` gets architecture index + component map. Total ~20-25 pages. | Enough depth to be a real docs site, not a placeholder; bounded to keep P1-P3 phases shippable. | 0.80 | [deeper (40+ pages), shallower (10 pages)] |
 | D-046 | **No docs-site publishing CI in v0.3** — `mkdocs.yml` is buildable locally (`mkdocs serve` / `mkdocs build`); CI publishing to GitHub Pages/Gitea Pages is deferred to v0.4. v0.3 ships the source + a build invocation in the README. | Publishing CI needs deployment secrets + a hosting target; v0.3 lands the content. | 0.82 | [include publishing CI in v0.3] |
 ### Ideation outcome (Phase 0 — IDEATE stage, autonomy=full)
 IDEATE stage ratified 8 ideas (IDEATE-01..IDEATE-08) at full autonomy, mapped to REQ-010/REQ-022..REQ-028. Docs deliverable (IDEATE-01/02) is the user's `--ideate` request; Bearers ideas (IDEATE-03..08) are the ROADMAP Phase 3 subset. Three ideation tiers ran (mechanical, backend-enriched, cross-project); mechanical tier found no `lessons:`/`compound:` tags in v0.1/v0.2 history (convention unused) and v0.2 closed clean (9/9 REQs, 303 tests, ≥95.9% coverage). Defaults accepted per full autonomy; traceability recorded in `.ciagent/oy/REQUIREMENTS.md` (IDEATE Traceability section).
@@ -26,6 +26,56 @@
 | Bearers OY-LR + Beacon | (vision §14) | §14 | Medium | Skeleton | v0.2/P4 |
 | Forex Engine v1 | (vision §13) | §13 | Medium | Skeleton | v0.2/P3 |
 ## v0.3 Milestone Requirements (Bearers & Documentation)
 | ID | Requirement | Vision § | Priority | Status | Phase |
 |----|-------------|----------|----------|--------|-------|
 | REQ-010 | Exit layer (Layer 3) — DEX swaps, bridges, off-mesh services | §7 | Medium | Pending | v0.3/P4 |
 | REQ-022 | Bearers expansion: OY-SAT + OY-QR bearer transports | §14 | Medium | Pending | v0.3/P4 |
 | REQ-023 | Anchors — first institutional Partner tier | §13 | Medium | Pending | v0.3/P4 |
 | REQ-024 | Hub API — B2B backbone: custody, lending primitive, compliance | §13 | Medium | Pending | v0.3/P5 |
 | REQ-025 | Services — Care / SIM / Vault / Mail | §13 | Medium | Pending | v0.3/P5 |
 | REQ-026 | Bond market depth — Growth Bonds + secondary market | §17 | Medium | Pending | v0.3/P5 |
 | REQ-027 | README.md + docs site in docs/ for nomads and freeholders | (vision §8) | High | Pending | v0.3/P1-P3 |
 | REQ-028 | Extend REQ-012 lexicon firewall to scan docs/ + README.md | §3 | High | Pending | v0.3/P1 |
 > REQ-022 through REQ-028 are NEW in v0.3 (ratified during Phase 0 IDEATE as
 > IDEATE-01..IDEATE-07, then assigned final REQ-IDs). REQ-010 is promoted from
 > v0.1 Skeleton to a fuller v0.3 skeleton.
 ## IDEATE Traceability (Phase 0 — IDEATE stage, autonomy=full)
 The IDEATE stage ran the three ideation tiers (mechanical, backend-enriched,
 cross-project) on the v0.3 milestone scope and ratified 8 ideas (IDEATE-01..
 IDEATE-08) at full autonomy. Each IDEATE-NN maps to a REQ-ID in the v0.3
 requirements table above. Mechanical tier: no `lessons:`/`compound:` tags in
 v0.1/v0.2 history (convention unused); one historical escalation (milestone
 release pending — no remote) resolved in v0.2; v0.2 closed clean (9/9 REQs,
 303 tests, ≥95.9% coverage). Backend-enriched + cross-project tiers confirmed
 the docs deliverable + Bearers skeleton bundle (D-034) and the firewall-first
 ordering (D-044). Defaults accepted per full autonomy.
 | IDEATE ID | REQ-ID | Category | Source | Confidence | Phase |
 |-----------|--------|----------|--------|------------|-------|
 | IDEATE-01 | REQ-027 | improvement/docs | user `--ideate` request + D-042/D-045 | 0.90 | v0.3/P1-P3 |
 | IDEATE-02 | REQ-028 | quality/security | D-043 + RESEARCH firewall-extension design | 0.88 | v0.3/P1 |
 | IDEATE-03 | REQ-010 | coverage/architecture | ROADMAP Phase 3 + D-036 | 0.80 | v0.3/P4 |
 | IDEATE-04 | REQ-022 | coverage | ROADMAP Phase 3 + D-037 | 0.82 | v0.3/P4 |
 | IDEATE-05 | REQ-023 | coverage | ROADMAP Phase 3 + D-038 | 0.78 | v0.3/P4 |
 | IDEATE-06 | REQ-024 | architecture | ROADMAP Phase 3 + D-039 | 0.80 | v0.3/P5 |
 | IDEATE-07 | REQ-025 | coverage | ROADMAP Phase 3 + D-040 | 0.78 | v0.3/P5 |
 | IDEATE-08 | REQ-026 | coverage | ROADMAP Phase 3 + D-041 | 0.80 | v0.3/P5 |
 Notes:
 - IDEATE-01/02 (docs deliverable + firewall) are the user's `--ideate` request
  ratified via D-042/D-043/D-045.
 - IDEATE-03..08 (Bearers skeleton) are the ROADMAP Phase 3 subset bundled into
  v0.3 per D-034.
 - IDEATE-02 lands in P1 (firewall-first) BEFORE IDEATE-01 content (P2/P3) per
  D-044 — docs are lexicon-clean by construction.
 - IDEATE-03..05 ship in P4 (Bearers skeleton I); IDEATE-06..08 ship in P5
  (Bearers skeleton II) — vertical slices, each phase independently shippable.
 ## Milestone v0.1 Summary
 - 10 REQs complete (skeleton + tests)
 - 2 REQs skeleton (REQ-001 principles, REQ-008 chain)
@@ -629,4 +629,663 @@ compiling with `go build ./...` and `go test ./...` using only stdlib. Rationale
 | REQ-012 | Lexicon | (all) | all | Enforced everywhere — D-032 |
 **New modules: 9. Extended modules: 1 (bearers). Total v0.2 packages: 10 new +
-1 extended = 11 packages added to the v0.1 baseline of 15.**
+1 extended = 11 packages added to the v0.1 baseline of 15.**
 ---
 ## v0.3 Research (Bearers & Documentation)
 > This section appends v0.3 research to the v0.1/v0.2 baseline above. It does NOT
 > rewrite or supersede the earlier content. v0.3 bundles two work-streams under
 > one feature milestone (D-034): (A) Bearers skeleton+tests (D-020/D-035 pattern)
 > and (B) a README.md + MkDocs Material docs site with the REQ-012 lexicon firewall
 > extended to docs (D-043). Tags run on v0.2.x (config.json tag_base).
 ### v0.3 Scope Recap (from D-034..D-046)
 v0.3 continues the skeleton+tests pattern (D-020/D-035): Go types + keeper stubs +
 invariant tests, no live chain, no real IBC, no real bearer transports, no live
 B2B runtime. The new/extended modules:
 | Module | REQ | D-decision | New/Ext | Phase | Skeleton depth |
 |---|---|---|---|---|---|
 | `x/exit` | REQ-010 | D-036 | New | P4 | ExitRoute + DEXSwap + ExitStatus |
 | `x/bridge` | REQ-010 | D-036 | New | P4 | BridgeRoute + BridgeStatus; ref x/satellite L2Chain by ID |
 | `x/bearers` (ext) | REQ-022 | D-037 | Ext | P4 | OYSATLink + OYQRCode (BearerTransport impls) |
 | `x/partner` (ext) | REQ-023 | D-038 | Ext | P4 | Anchor credential fields on the Anchor tier |
 | `x/hub` | REQ-024 | D-039 | New | P5 | HubService enum (Custody/LendingPrimitive/Compliance) + struct stubs |
 | `x/services` | REQ-025 | D-040 | New | P5 | ServiceKind enum (Care/SIM/Vault/Mail) + struct stubs |
 | `x/bond` (ext) | REQ-026 | D-041 | Ext | P5 | GrowthBond + SecondaryOrder; 8%/0% consts unchanged |
 | docs/ + README.md + mkdocs.yml | REQ-027 | D-042 | New | P1-P3 | ~20-25 pages, 4 audiences |
 | `lexicon_meta_docs_test.go` | REQ-028 | D-043 | New | P1 | firewall sibling test |
 ---
 ## v0.3 §1. Bearers Skeleton Design — Per Module
 ### v0.3 §1.1 `x/exit` (Exit layer — DEX swaps, REQ-010, D-036)
 **What it is:** The Layer 3 exit layer — Holder-initiated DEX swaps and off-mesh
 service exits. v0.3 ships the type scaffold (ExitRoute, DEXSwap) + ExitStatus
 enum; no live DEX integration (deferred to v0.4).
 **Prior art / ecosystem references:**
 - **DEX aggregators** — 1inch (off-chain path optimization), Paraswap, 0x API
  (rfq + amm). An ExitRoute is closest to a 1inch "swap route" (a hop sequence:
  source-asset → intermediate → destination-asset, each hop a venue).
 - **Cosmos SDK** — no native DEX module; DEX swaps are CosmWasm or external. The
  skeleton types are self-contained Go structs (zero-dep, same as v0.2 satellite).
 - **Cross-chain swap** — THORChain, Chainflip; an exit that crosses a bridge is
  a swap-with-bridge-hop. `x/exit` references a `x/bridge` BridgeRoute by ID for
  cross-chain exits (the BridgeRoute is typed in x/bridge; x/exit holds a
  bridge-route-id string field, G-003 by-ID-string ref).
 **Recommendation for skeleton:** New `x/exit/types/` module following the v0.2
 `x/satellite` pattern (locked-const enum + struct types + genesis + keeper stub):
 - `ExitStatus` enum (Proposed, InProgress, Settled, Failed, Refunded) — exactly
  5, locked-const `ExitStatusCount = 5` with a regression test.
 - `ExitRoute` struct (route-id, holder-reach-id, source-asset, dest-asset,
  amount-grain, min-received-grain, bridge-route-id (optional, by-ID-string ref
  to x/bridge for cross-chain exits), venue-hops []string, deadline, status).
 - `DEXSwap` struct (swap-id, route-id (by-ID-string ref to ExitRoute), venue,
  input-asset, input-amount-grain, output-asset, output-amount-grain, executed-at).
  The "venue" is an opaque string (e.g., "uniswap-v3", "oy-dex") — no enum locked
  in v0.3 (venues are operational, not protocol-locked; locking now risks churn).
 - `Keeper` stub: AddExitRoute / GetExitRoute / ListByHolder (by holder-reach-id).
 - `GenesisState` + `ValidateGenesis` (route-id uniqueness, A-212 pattern).
 - Tests: ExitStatusCount=5, enum names match, route round-trip, lexicon assertion,
  genesis ID-uniqueness.
 **Pattern followed:** `x/satellite` (new module with enum + structs + genesis +
 keeper stub). The ExitStatus enum mirrors the v0.2 BondStatus/ChannelStatus
 pattern (locked count + AllX() returning vision-order values).
 **Cross-component dependency:** `x/exit` references `x/bridge` BridgeRoute by
 ID-string (G-003). This is a P4 intra-phase dependency: `x/bridge` types must
 exist before `x/exit` tests that reference a bridge-route-id. Both land in P4
 (D-044); `x/bridge` is authored first within P4. No struct import (by-ID-string
 only), so no import cycle. `x/exit` also references `x/bread` Grain by name only
 (the amount-grain field is int64, not a bread.Bread import).
 **Risk:** "DEX swap" terminology is lexicon-safe (no banned terms). "venue" is
 not banned. Avoid "account" (use holder-reach-id), "currency"/"dollar"/"euro"
 (use source-asset/dest-asset opaque strings). Test asserts no banned terms.
 ---
 ### v0.3 §1.2 `x/bridge` (L2↔L1 bridge types, REQ-010, D-036)
 **What it is:** The L2↔L1 bridge type scaffold — bridge routes between OY Chain
 (L1) and the v0.2 satellite L2 chains. v0.3 ships BridgeRoute + BridgeStatus
 enum; no live bridge runtime (the v0.2 satellite ICS-20 channel types are the
 IBC transport; x/bridge is the higher-level route abstraction over them).
 **Prior art / ecosystem references:**
 - **L2↔L1 bridges** — Hop Protocol (L2-L1 token bridge with bonder), Across
  (repayer-based), Connext (interop), Cosmos IBC (the v0.2 satellite choice).
  OY's bridge is IBC-native (D-021 chose IBC for L2); x/bridge is the route layer
  over the IBC transfer channel.
 - **Bridge status lifecycles** — Hop: Pending → Confirmed → Minted; Across:
  Pending → Filled → Repaid; IBC: Init → TryOpen → Open → Closed (the v0.2
  ChannelStatus). x/bridge's BridgeStatus is the route-level lifecycle (above
  the channel handshake): Pending → Attested → Active → Closed.
 - **Watcher attestation for bridges** — bridges are high-value exits; the vision
  ties bridge activation to Watcher attestation (6-of-9 quorum, REQ-004). The
  BridgeStatus `Attested` state references a Watcher quorum by ID (skeleton:
  the attestation is a by-ID-string field, not a struct import).
 **Recommendation for skeleton:** New `x/bridge/types/` module following `x/satellite`:
 - `BridgeStatus` enum (Pending, Attested, Active, Closed) — exactly 4, locked-const
  `BridgeStatusCount = 4`. `Attested` is the Watcher-quorum-confirmed state.
 - `BridgeRoute` struct (route-id, source-chain (L2Chain by-ID-string ref to
  x/satellite — G-003, no struct import), dest-chain, bridge-type (e.g., "ibc",
  "oy-bridge" — opaque string, not a locked enum in v0.3), transfer-channel-id
  (by-ID-string ref to a v0.2 satellite TransferChannel), watcher-quorum-id
  (by-ID-string ref to x/watcher, set when status becomes Attested), status).
 - `Keeper` stub: AddBridgeRoute / GetBridgeRoute / ListByStatus.
 - `GenesisState` + `ValidateGenesis` (route-id uniqueness, A-212).
 - Tests: BridgeStatusCount=4, enum names, route round-trip, lexicon assertion.
 **Pattern followed:** `x/satellite` (the v0.2 L2/IBC module). x/bridge reuses the
 satellite L2Chain enum by-ID-string reference — it does NOT redefine L2 chains.
 **Cross-component dependency:** `x/bridge` references `x/satellite` (L2Chain by
 ID-string, for source-chain/dest-chain fields) and `x/watcher` (watcher-quorum-id
 by ID-string, for the Attested state). Both are v0.1/v0.2 baseline modules; no
 new v0.3 dependency. x/bridge is authored FIRST in P4 (before x/exit) because
 x/exit references a BridgeRoute by ID.
 **Risk:** "bridge" is not a banned term. Avoid "currency"/"dollar"/"euro" (use
 chain names: "Polygon"/"OY-Chain"). The watcher-quorum-id is an opaque string;
 no Watcher struct import (avoids cycle with x/watcher).
 ---
 ### v0.3 §1.3 `x/bearers` extension (OY-SAT + OY-QR, REQ-022, D-037)
 **What it is:** The remaining two bearer transports (OY-SAT satellite, OY-QR
 paper/QR-code) completing the 6-bearer type set (v0.2 had 4: Internet, OY-LR,
 OY-BLE, OY-WiFi-Direct + the Beacon transport-mode). v0.3 adds the OY-SAT and
 OY-QR transport structs implementing the v0.2 `BearerTransport` interface. No
 hardware/RF/paper-scan runtime.
 **Prior art / ecosystem references:**
 - **OY-SAT (satellite bearer)** — Starlink (consumer satellite), Iridium (low-
  earth-orbit, global), Swarm (low-bandwidth satellite IoT). Helium Mobile +
  satellite fallback. OY-SAT is global, surveillance-resistant (vision §14).
  The transport struct mirrors the v0.2 OYLRLink shape (gateway-id, frequency,
  surveillance-resistant flag).
 - **OY-QR (paper/QR-code bearer)** — offline QR-code value transfer (the
  "paper wallet" / "physical Bitcoin" analog). Closest: Bolt Card (NFC + QR
  Lightning), OpenTimestamps QR proofs. OY-QR is 0-range (vision §14: the
  bearer list has OY-QR at "0 range"); a QR encodes a signed transfer that the
  recipient scans and submits. The transport struct mirrors BeaconFrame (a
  payload + ttl, but for QR it's a one-shot signed payload, no ephemeral-id).
 **Recommendation for skeleton:** Extend `x/bearers/types/types.go` (do NOT create
 a new module — v0.1/v0.2 own the BearerType enum and BearerTransport interface).
 Add:
 - `OYSATLink` struct (gateway-id, constellation (e.g., "iridium" — opaque
  string), frequency-mhz, surveillance-resistant (LOCKED true for OY-SAT)).
 - `OYQRCode` struct (qr-id, payload-bytes (the signed transfer), issuer-reach-id,
  expires-at, consumed (bool — a QR is one-shot)).
 - Both implement `BearerTransport` (Send/Receive/Status) as stub methods (the
  v0.2 OYLRLink/BeaconFrame are struct types but NOT BearerTransport impls in
  v0.2 — they are transport-shape stubs; v0.3 keeps the same shape-only approach
  for OY-SAT/OY-QR to match D-029. If the interface impl is desired, add stub
  methods returning a "not-integrated" sentinel, mirroring forex StubOracle).
 - Tests: BearerOYSAT and BearerOYQR are already in `AllBearers()` from v0.1
  (asserted by the existing locked-const test — do NOT change the count). New
  tests assert the OYSATLink/OYQRCode struct fields, surveillance-resistant is
  LOCKED true for OY-SAT, OY-QR is one-shot (consumed flips to true), lexicon.
 - The v0.2 `BearerTypeCount` / `AllBearers()` locked-const test stays unchanged
  (6 bearers, already locked). v0.3 adds the transport structs only.
 **Pattern followed:** D-029 (v0.2 bearers extension). The OYSATLink mirrors
 OYLRLink; OYQRCode mirrors BeaconFrame with a one-shot consumed flag instead of
 ttl.
 **Cross-component dependency:** None new. x/bearers is a leaf (no refs to other
 v0.3 modules). The BearerType enum is locked since v0.1.
 **Risk:** Hardware/paper-scan runtime is explicitly deferred. Do not pull LoRa/
 BLE/satellite/QR Go libraries. Pure types. "QR" / "SAT" are not banned terms.
 ---
 ### v0.3 §1.4 `x/partner` extension (Anchor credential types, REQ-023, D-038)
 **What it is:** The Anchor tier (the 4th of the 4-tier Partner Spectrum, REQ-018)
 gets institution-specific credential fields in v0.3. v0.2 defined the 4-tier
 enum + Partner struct + CredentialRef; v0.3 adds an AnchorCredential struct
 carrying the institutional onboarding metadata (regulatory jurisdiction,
 custody-provider ref, attestation refs). No live institutional onboarding.
 **Prior art / ecosystem references:**
 - **Institutional onboarding** — MakerDAO RWA arrangers (legal repr, off-chain
  agreements), Centrifuge senior/junior tranches with institutional sponsors,
  Maple Finance institutional underwriting, Ondo Finance institutional wrappers.
  The Anchor tier is OY's abstraction over institutional partners.
 - **Regulatory credentials** — e-Residency (Estonia), MiCA compliance (EU),
  SOC2/ISO27001 attestations. The AnchorCredential carries jurisdiction +
  attestation refs (opaque URIs, like the v0.2 Pier CredentialRef).
 - **Custody** — Anchors may custody assets; the custody-provider ref points to
  a Hub custody service (x/hub, P5). This is the Anchor→hub dependency edge:
  x/partner Anchor references a hub custody-service-id by string.
 **Recommendation for skeleton:** Extend `x/partner/types/types.go`:
 - `AnchorCredential` struct (partner-id (by-ID-string ref to the Anchor
  Partner), jurisdiction (opaque string e.g. "EU-MiCA"), custody-provider-id
  (by-ID-string ref to x/hub custody service — set in v0.4 when hub is live;
  v0.3 field is a string, may be empty in skeleton), attestation-refs
  []string (opaque URIs to Watcher/auditor attestations), onboarded-at).
 - A `Partner.AnchorCredential() *AnchorCredential` accessor stub returning nil
  for non-Anchor tiers (or a separate AnchorPartner struct wrapping Partner —
  prefer the accessor to avoid a second top-level type).
 - `Keeper.ListAnchors()` = `ListByTier(TierAnchor)` (already exists from v0.2;
  add a convenience alias + an `AddAnchorCredential(partnerID, cred)` method).
 - Tests: AnchorCredential struct round-trip, non-Anchor Partner returns nil,
  AddAnchorCredential rejects non-Anchor partner-id, lexicon assertion.
 **Pattern followed:** v0.2 partner extension (add a struct + accessor, reuse
 the existing Keeper). The PartnerTier enum (4 tiers, locked since v0.2) is
 unchanged — v0.3 adds Anchor-specific fields, not a new tier.
 **Cross-component dependency:** `x/partner` Anchor references `x/hub` custody
 service by ID-string (G-003). This is a P4→P5 edge: x/partner Anchor lands in
 P4, x/hub in P5. The custody-provider-id field is a string that is EMPTY in
 the v0.3 skeleton (the hub is not live until P5/v0.4); the field exists so the
 shape is stable. This is the dependency that forces P4 before P5 (D-044).
 **Risk:** "custody" is not a banned term (the banned list is bank/deposit/
 interest/yield/currency/dollar/euro/account/savings/depositor). "jurisdiction"
 is safe. Avoid "account" (use partner-id). Test asserts no banned terms.
 ---
 ### v0.3 §1.5 `x/hub` (Hub API — B2B backbone, REQ-024, D-039)
 **What it is:** The Hub API Pact (#6 per REQ-020/D-027) promoted to its own
 module in v0.3. The B2B backbone: custody, lending-primitive, compliance
 service types. v0.3 ships the HubService enum + per-service struct stubs +
 keeper stub; no live B2B runtime (full suite deferred to v0.4).
 **Prior art / ecosystem references:**
 - **B2B API backbones** — Stripe API (modular resources), Plaid (bank-data
  aggregation — note: Plaid is bank-data, OY's Hub is the anti-bank backbone, so
  the analogy is structural not semantic), Coinbase Prime (institutional
  custody + prime). The Hub is OY's on-chain B2B service registry.
 - **Custody** — Fireblocks, Anchorage, BitGo (institutional custody). OY's
  custody service is a Hub-service type that an Anchor partner operates.
 - **Lending primitive** — Aave/Compound protocol-level lending; OY's "lending
  primitive" is a Hub-service type (the protocol-level primitive, not a live
  market). Lexicon note: "lending" is NOT banned (the banned list has "interest"
  and "deposit" and "savings" but not "lending" or "loan"); use "lending
  primitive" (vision §13) to stay aligned, avoid "interest"/"deposit".
 - **Compliance** — on-chain compliance attestations (TRM Labs, Elliptic for
  AML; Chainalysis). OY's compliance service is a Hub-service type an Anchor
  or Pier operates.
 **Recommendation for skeleton:** New `x/hub/types/` module following `x/forex`
 (the v0.2 enum + struct + interface + stub-keeper pattern):
 - `HubService` enum (Custody, LendingPrimitive, Compliance) — exactly 3,
  locked-const `HubServiceCount = 3`. (Vision §13 names these three B2B
  categories; full B2B suite deferred to v0.4 per D-039.)
 - `HubServiceInfo` struct (service-id, kind (HubService), operator-partner-id
  (by-ID-string ref to x/partner — typically an Anchor), name, status).
 - `HubServiceStatus` enum (Pending, Active, Suspended, Revoked) — reuse the
  v0.2 PartnerStatus shape (same 4-state lifecycle); locked-const count = 4.
  Consider importing nothing and redefining locally (G-003 by-ID-string only;
  enums are string types so a local redefinition is fine and avoids a struct
  import of x/partner).
 - Per-service struct stubs: `CustodyService` (service-id, custody-provider-id,
  assets-supported []string), `LendingPrimitiveService` (service-id,
  primitive-kind (opaque string), coupon-cap-bps uint32 — clamp-reusable from
  x/bond Clamp? NO — the hub lending primitive references the bond cap by
  const value 800, not by importing x/bond.Clamp; keep a local const
  `LendingCouponCapBps = 800` cross-documented to D-028 to avoid the import),
  `ComplianceService` (service-id, jurisdiction, attestation-refs []string).
 - `Keeper` stub: AddService / GetService / ListByKind.
 - `GenesisState` + `ValidateGenesis` (service-id uniqueness, A-212).
 - Tests: HubServiceCount=3, enum names, service round-trip, per-service struct
  fields, lexicon assertion (HIGH-RISK: "interest"/"deposit"/"savings" must not
  appear; "lending"/"coupon"/"custody"/"compliance" are safe).
 **Pattern followed:** `x/forex` (enum + struct + per-variant struct + stub
 keeper + genesis). The local-const-copy for the coupon cap mirrors how x/guild
 cross-documents x/feecovenant's WaiverHandPassGuild (v0.2 RESEARCH §1.5).
 **Cross-component dependency:** `x/hub` references `x/partner` (operator-
 partner-id by ID-string, typically an Anchor). This is the P4→P5 edge: x/partner
 Anchor (P4) must precede x/hub (P5). The hub also cross-documents the bond
 8%/0% cap (D-028) as a local const to avoid importing x/bond (G-003).
 **Risk:** Lending primitive is the highest lexicon-risk in v0.3 (after x/bond).
 "interest"/"yield"/"deposit"/"savings" are natural fit-words for a lending
 primitive — use "lending primitive"/"coupon" (vision §13/§17 lexicon). The
 lexicon assertion test is the gate. Do NOT use "borrower"/"lender" if they
 imply banned concepts — vision §13 uses "lending primitive" as the service
 name, so the struct/enum names follow vision.
 ---
 ### v0.3 §1.6 `x/services` (Care/SIM/Vault/Mail, REQ-025, D-040)
 **What it is:** OY-protocol services beyond the financial layer — Care
 (community care), SIM (subscriber identity module / connectivity), Vault
 (storage service), Mail (messaging). v0.3 ships the ServiceKind enum + per-
 service struct stubs + keeper stub; no live services.
 **Prior art / ecosystem references:**
 - **Care** — mutual aid societies, Gitcoin Grants rounds (care as public-good
  funding). OY Care is a community-care service a Stand/Guild operates.
 - **SIM** — Helium Mobile (DePIN connectivity), decentralized connectivity
  (Pollen, Andrena). OY SIM is a connectivity service.
 - **Vault** — the v0.2 x/vault is the Stand-level storage pool; an OY
  "Vault service" is a higher-level storage offering (backup, attested
  storage). Reference x/vault by ID-string (G-003).
 - **Mail** — decentralized messaging (Session, Status, XMTP). OY Mail is a
  bearer-routed messaging service.
 **Recommendation for skeleton:** New `x/services/types/` module following
 `x/hub` (enum + struct + per-variant struct + keeper stub + genesis):
 - `ServiceKind` enum (Care, SIM, Vault, Mail) — exactly 4, locked-const
  `ServiceKindCount = 4`. (Vision §13 / ROADMAP Phase 4 lists these four;
  Yield Token + Travel + 11 more are Phase 4, out of v0.3 scope per D-040.)
 - `ServiceInfo` struct (service-id, kind (ServiceKind), operator-reach-id (by-
  ID-string ref to x/identity Reach), name, status, window-id (by-ID-string
  ref to x/window — a service-grant opens a Window on the holder's behalf)).
 - `ServiceStatus` enum (Pending, Active, Suspended, Revoked) — reuse the 4-
  state shape (local redefinition, no import).
 - Per-service struct stubs: `CareService`, `SIMService`, `VaultService`,
  `MailService` — each carries service-id + service-specific fields (Care:
  care-kind (opaque); SIM: carrier (opaque); Vault: storage-quota-grain;
  Mail: mailbox-id). Keep these minimal — the shape is the v0.3 deliverable.
 - `Keeper` stub: AddService / GetService / ListByKind.
 - `GenesisState` + `ValidateGenesis` (service-id uniqueness, A-212).
 - Tests: ServiceKindCount=4, enum names, service round-trip, per-service
  fields, lexicon assertion.
 **Pattern followed:** `x/hub` (and transitively `x/forex`).
 **Cross-component dependency:** `x/services` references `x/identity` (operator-
 reach-id by ID-string), `x/window` (window-id by ID-string — the service-grant),
 and `x/vault` (for VaultService, by ID-string). All v0.1/v0.2 baseline; no new
 v0.3 dependency. The window-id field is the hook for the Window Lifecycle
 interface (Architecture §4.4) — typed in v0.3, invoked at runtime in v0.4.
 **Risk:** "Vault" collides with the v0.2 `x/vault` module name — but the
 ServiceKind enum value is "Vault" (a service kind, not a module import). The
 VaultService struct lives in `x/services/types/`, references `x/vault` by ID-
 string. The naming collision is at the concept level, not the package level (no
 Go import cycle). "Mail"/"SIM"/"Care" are not banned terms. Avoid "account"
 (use service-id / operator-reach-id).
 ---
 ### v0.3 §1.7 `x/bond` extension (Growth Bonds + secondary market, REQ-026, D-041)
 **What it is:** Bond market depth — GrowthBond (a bond whose coupon grows with
 protocol health, vision §17) + secondary-market order types. The 8% cap / 0%
 floor consts (D-028) are UNCHANGED. Full secondary-market matching deferred to
 v0.4.
 **Prior art / ecosystem references:**
 - **Growth Bonds** — "growing bonds" / step-up bonds (coupon increases over
  time), inflation-linked bonds (TIPS). OY's GrowthBond is a bond whose coupon
  grows with Root-Pool Bloom (real-production-driven). Closest: TIPS (coupon
  adjusts to an index) but OY's index is the protocol's real return, not CPI.
 - **Secondary markets** — Uniswap v3 (concentrated liquidity AMM), order-book
  DEXs (dYdX, 0x Mesh), fixed-income secondary markets (Centrifuge Tinlake
  secondary). OY's secondary market is an order-book (buy/sell orders on issued
  bonds); the matching engine is v0.4. v0.3 types the order shape.
 - **Coupon caps** — the 8% cap (D-028) applies to GrowthBonds too: the growth
  coupon is still clamped to [0, 800] bps at any point (the cap is mission-
  locked; a growth bond cannot exceed it even as the protocol grows). The
  GrowthBond reuses x/bond.Clamp (same package — no G-003 concern).
 **Recommendation for skeleton:** Extend `x/bond/types/types.go`:
 - `GrowthBond` struct embedding the v0.2 `Bond` + a `GrowthRateBps` field (the
  per-period growth rate of the coupon, clamped so that current-coupon +
  growth never exceeds CouponCapBps — add a `ClampGrowth(currentBps, growthBps)
  uint32` helper that returns min(CouponCapBps - currentBps, growthBps) so the
  post-growth coupon is ≤ cap). The growth-bond issuer-stand-id references
  x/stand by ID-string (unchanged from v0.2 Bond).
 - `SecondaryOrder` struct (order-id, bond-id (by-ID-string ref to the Bond),
  side (OrderSide enum: Buy/Sell), price-bps (price as a fraction of principal,
  in bps), quantity-grain, holder-reach-id, status, created-at).
 - `OrderSide` enum (Buy, Sell) — exactly 2, locked-const `OrderSideCount = 2`.
 - `OrderStatus` enum (Open, Filled, Cancelled) — exactly 3, locked-const
  `OrderStatusCount = 3`.
 - `Keeper` stub: AddOrder / GetOrder / ListByBond / CancelOrder (no matching).
 - Extend `GenesisState` with a `GrowthBonds []GrowthBond` and `Orders
  []SecondaryOrder` field; `ValidateGenesis` checks order-id + growth-bond-id
  uniqueness (A-212).
 - Tests: GrowthBond clamp-growth invariant (post-growth coupon ≤ 800, never
  below 0), OrderSideCount=2, OrderStatusCount=3, order round-trip, the 8%/0%
  consts STILL = 800/0 (regression: v0.3 must not change D-028), lexicon
  assertion (HIGH-RISK: "interest"/"yield"/"deposit"/"savings" banned — use
  "coupon"/"growth"/"secondary"/"order").
 **Pattern followed:** v0.2 x/bond (locked-const + Clamp + struct + genesis). The
 ClampGrowth helper mirrors the v0.2 Clamp shape (min/max with the cap).
 **Cross-component dependency:** None new. x/bond references x/stand (issuer-
 stand-id, by ID-string, v0.2 baseline). The GrowthBond and SecondaryOrder are
 in-package with Bond (same `x/bond/types`), so no G-003 concern for the Clamp
 reuse.
 **Risk:** Growth Bond is lexicon-hostile ("growth" is safe, but "yield growth"
 is the natural phrasing — use "coupon growth" / "real-return-linked coupon",
 never "yield"). The secondary-market "order" terminology is lexicon-safe
 ("buy"/"sell"/"order"/"filled"/"cancelled" are not banned). The regression test
 that 8%/0% are unchanged is the D-028 firewall.
 ---
 ## v0.3 §2. Documentation Site + Firewall Extension Design
 ### v0.3 §2.1 MkDocs Material setup
 **Decision (D-042):** MkDocs Material (`mkdocs.yml` at repo root + `docs/` tree).
 Build-only Python dep (`mkdocs` + `mkdocs-material`); `go.mod` stays zero-dep
 (G-006 — the docs toolchain is NOT a Go dependency; it lives in a separate
 Python toolchain, documented in README, not in go.mod).
 **Minimal `mkdocs.yml`:**
 ```yaml
 site_name: OpenYield
 theme:
  name: material
  features:
    - navigation.sections
    - navigation.expand
    - toc.integrate
 markdown_extensions:
  - admonition
  - toc:
      permalink: true
  - pymdownx.superfences
 nav:
  - Home: index.md
  - Nomads:
      - nomads/index.md
      - nomads/reach.md
      - nomads/stash.md
      - nomads/bearers.md
      - nomads/maps-pay.md
      - nomads/pacts.md
      - nomads/standing-basics.md
  - Freeholders:
      - freeholders/index.md
      - freeholders/four-signals.md
      - freeholders/bayesian-standing.md
      - freeholders/stands-guilds.md
      - freeholders/councils-voice.md
      - freeholders/bonds.md
      - freeholders/partner-spectrum.md
  - Shared:
      - shared/index.md
      - shared/six-principles.md
      - shared/bread-scale.md
      - shared/storage-pools.md
      - shared/watchers-mirror.md
      - shared/lexicon-glossary.md
      - shared/vision-overview.md
  - Reference:
      - reference/architecture-index.md
      - reference/component-map.md
 ```
 **Audience organization (D-042, D-045):** nomads (Reach/Stash/bearers/Maps-Pay/
 Pacts/standing-basics — 7 pages), freeholders (4-signals/Bayesian-Standing/
 Stands-Guilds/Councils-Voice/Bonds/Partner-spectrum — 7 pages), shared (Six-
 Principles/Bread-Scale/Storage-pools/Watchers-Mirror/Lexicon-glossary/Vision-
 overview — 6 pages), reference (architecture-index/component-map — 2 pages).
 Total ~22 pages (within the D-045 20-25 budget).
 **No publishing CI in v0.3 (D-046):** `mkdocs.yml` is buildable locally
 (`mkdocs serve` / `mkdocs build`); the README documents the build invocation.
 Publishing to GitHub/Gitea Pages deferred to v0.4 (needs deployment secrets +
 hosting target). v0.3 ships the source.
 ---
 ### v0.3 §2.2 Lexicon-clean docs by construction
 The 10 banned terms (bank, deposit, interest, yield, currency, dollar, euro,
 account, savings, depositor) must not appear in `docs/**/*.md` or `README.md`.
 The highest-risk term in docs is **"yield"**: PROJECT.md uses "real yield" but
 docs must say "real production" / "real return" (the word-boundary regex in
 `lexicon.FindBannedTerm` bans standalone "yield" while allowing "OpenYield" —
 verified by `TestLexiconMetaNoFalsePositiveOnOpenYield`).
 **Safe phrasings for docs (the docs-writer constraint):**
 - "real yield" → "real production" / "real return"
 - "account" → "Holder" / "Reach"
 - "bank" / "deposit" / "savings" / "depositor" → "Stash" / "Vault" / "Root-Pool"
 - "interest" → "coupon" (for bonds)
 - "currency" / "dollar" / "euro" → "Bread" / "asset" / opaque chain names
 **Firewall-first ordering (D-044):** the docs firewall (`lexicon_meta_docs_test.go`)
 lands in P1 BEFORE the content (P2 nomads, P3 freeholders). This ensures docs
 are lexicon-clean by construction, not by retrofit — a banned term slipped into
 a P2 nomads page fails the P2 build, not the P6 review.
 ---
 ### v0.3 §2.3 Firewall extension design (`lexicon_meta_docs_test.go`)
 **Decision (D-043):** NEW sibling test `lexicon_meta_docs_test.go` (package
 `lexicon_meta_docs`) at the repo root (next to `lexicon_meta_test.go`), NOT a
 modification of the existing `lexicon_meta_test.go` (package `lexicon_meta`).
 **Rationale for the sibling (not extension) approach:**
 1. Preserves v0.2 coverage — the existing `lexicon_meta_test.go` scans `x/**/*.go`
   and is unchanged; v0.2's green firewall is not re-risked.
 2. Clearer separation — the docs firewall scans a different file set
   (`README.md` + `docs/**/*.md`) with different walk logic (repo-root walk, not
   `x/` walk); a separate test file keeps each firewall's walk logic self-
   contained and readable.
 3. Package isolation — `lexicon_meta_docs` is a distinct Go package so the two
   meta-tests compile independently and cannot share state by accident.
 **The new test mirrors `lexicon_meta_test.go` exactly in detection logic:**
 - Uses the SAME `lexicon.FindBannedTerm` (word-boundary, case-insensitive) — no
  reimplementation of detection.
 - Same self-test table (G-009): one synthetic string per banned term, asserted
  to trigger detection, assembled from fragments so the test file's own source
  does not contain a banned-term literal.
 - Same self-exclusion: the meta-test file excludes ITSELF from its own scan
  (via `runtime.Caller(0)` to get its own path, then skipping it in the walk).
 - Same `TestLexiconMetaDocsBannedTermsCount` (exactly 10 terms).
 - Same `TestLexiconMetaDocsNoFalsePositiveOnOpenYield` (word-boundary does not
  match "openyield"/"european").
 **File walk logic (the only difference from `lexicon_meta_test.go`):**
 - Walk the REPO ROOT (not `x/`): start at `filepath.Dir(thisFile)` (the repo
  root, since the test lives at the repo root).
 - Target files: `README.md` (repo root) + every `*.md` under `docs/` (recursive).
 - Exclude `.ciagent/` (firewall meta-files — PROJECT.md/RESEARCH.md/this file
  discuss banned terms by name for governance; they are NOT user-facing docs).
 - Exclude `.git/` (VCS metadata).
 - Exclude the meta-test file itself (`lexicon_meta_docs_test.go`).
 - Exclude `docs/` non-`.md` files (images, etc.) — only `.md` is scanned.
 - For each target `.md` file, read its source and run `lexicon.FindBannedTerm`;
  collect hits and fail with a list.
 **Pseudocode of the walk:**
 ```go
 func TestLexiconMetaDocsNoBannedTermsInDocs(t *testing.T) {
    repoRoot := filepath.Dir(thisFile(t)) // repo root (test is at repo root)
    thisFile := thisFile(t)
    hits := []string{}
    filepath.Walk(repoRoot, func(path string, info os.FileInfo, err error) error {
        if info.IsDir() {
            base := filepath.Base(path)
            if base == ".ciagent" || base == ".git" { return filepath.SkipDir }
            return nil
        }
        if path == thisFile { return nil } // self-exclusion
        if !strings.HasSuffix(path, ".md") { return nil }
        // only README.md (repo root) + docs/**/*.md
        rel, _ := filepath.Rel(repoRoot, path)
        if rel != "README.md" && !strings.HasPrefix(rel, "docs/") { return nil }
        bz, _ := os.ReadFile(path)
        if found, ok := lexicon.FindBannedTerm(string(bz)); ok {
            hits = append(hits, rel+" contains banned term "+found)
        }
        return nil
    })
    if len(hits) > 0 { t.Errorf("REQ-012 docs lexicon violations:\n  %s", ...) }
 }
 ```
 **Per-package lexicon assertions (in the new x/* modules):** each new/extended
 v0.3 module's `types_test.go` includes a `TestLexiconNoBannedTermsIn<Module>Package`
 scanning the module's production `.go` files (the v0.2 pattern from
 `x/partner/types/types_test.go`). These are OWNED by backend-engineer (not the
 docs firewall, which is frontend-engineer's). The project-wide `x/**/*.go` scan
 stays in `lexicon_meta_test.go` (v0.2, unchanged) and automatically covers the
 new v0.3 x/* modules.
 ---
 ## v0.3 §3. Cross-Component Dependencies Affecting Phase Ordering
 The v0.3 cross-component dependencies (all by-ID-string per G-003, no struct
 imports) that constrain the D-044 phase ordering:
 1. **`x/exit` → `x/bridge` (intra-P4):** `x/exit`'s ExitRoute has a `bridge-route-
   id` field referencing a `x/bridge` BridgeRoute by ID-string. `x/bridge` types
   must exist before `x/exit` tests reference a bridge-route-id. Both land in P4;
   `x/bridge` authored first within P4.
 2. **`x/partner` (Anchor) → `x/hub` (P4 → P5):** `x/hub`'s HubService has an
   `operator-partner-id` field referencing an Anchor Partner by ID-string.
   `x/partner` Anchor extension (P4) must precede `x/hub` (P5). The Anchor's
   `custody-provider-id` field references a hub custody service (by ID-string)
   but is EMPTY in the v0.3 skeleton (hub not live until P5/v0.4), so the
   reverse edge is typed-but-deferred. This is the dependency that forces P4
   before P5.
 3. **`x/services` → `x/window` (P5 → v0.2 baseline):** `x/services`'s ServiceInfo
   has a `window-id` field referencing a `x/window` Window by ID-string. x/window
   is a v0.2 baseline module (already shipped); no phase-ordering concern.
 4. **`x/bond` (GrowthBond) → `x/stand` (P5 → v0.2 baseline):** GrowthBond's
   issuer-stand-id references x/stand by ID-string (unchanged from v0.2 Bond).
   x/stand is v0.2 baseline; no concern.
 5. **`x/bridge` → `x/satellite`, `x/watcher` (P4 → v0.2/v0.1 baseline):**
   BridgeRoute references a satellite L2Chain and a watcher-quorum-id by ID-
   string. Both are baseline; no concern.
 **Net phase-ordering conclusion:** D-044's P4→P5 split is confirmed and cannot
 be reversed: P4 = exit/bridge/bearers/partner-Anchor; P5 = hub/services/bond.
 The only intra-phase ordering within P4 is `x/bridge` before `x/exit`. P5 has no
 intra-phase ordering constraint (hub, services, bond are independent of each
 other). The docs phases (P1-P3) are firewall-first (P1) then content (P2-P3),
 independent of the Bearers phases.
 ---
 ## v0.3 §4. Assumptions (logged with confidence scores)
 | ID | Assumption | Confidence | Rationale |
 |----|-----------|------------|-----------|
 | A-301 | v0.3 skeleton stays dependency-free (only stdlib), matching v0.1/v0.2 (A-201). Docs build-deps (mkdocs) are Python, not Go; go.mod unchanged. | 0.95 | D-035/A-201/G-006 confirm; mkdocs is D-042. |
 | A-302 | `x/exit` and `x/bridge` are SEPARATE packages (not one x/exit module), per D-036. | 0.90 | D-036 explicitly names both; separation matches v0.2 one-package-per-module (A-202). |
 | A-303 | `x/hub` is a NEW module (Pact #6 promoted from x/pact enum value to its own module), per D-039. | 0.85 | D-039 names x/hub; the x/pact HubAPI enum value stays as a cross-ref. |
 | A-304 | `x/hub` `LendingCouponCapBps = 800` is a LOCAL const cross-documented to D-028 (not an import of x/bond.Clamp), to preserve G-003 (no struct import). | 0.82 | Mirrors v0.2 guild's cross-doc of feecovenant WaiverHandPassGuild (RESEARCH §1.5). |
 | A-305 | `x/partner` Anchor adds an `AnchorCredential` struct + accessor, NOT a new PartnerTier (the 4-tier enum is locked since v0.2). | 0.90 | D-038 says "extend with Anchor credential fields"; the tier enum is locked. |
 | A-306 | `x/bond` GrowthBond embeds the v0.2 Bond + a GrowthRateBps field with a ClampGrowth helper ensuring post-growth coupon ≤ 800 bps. | 0.80 | Vision §17 growth-bond; the 8% cap (D-028) applies to growth bonds too. |
 | A-307 | `x/services` ServiceKindCount = 4 (Care/SIM/Vault/Mail); Yield Token + Travel + 11 more are Phase 4 (out of v0.3 per D-040). | 0.85 | D-040 + ROADMAP Phase 4 confirm the 4-service v0.3 scope. |
 | A-308 | `x/exit` DEXSwap "venue" is an opaque string (not a locked enum) — venues are operational, locking now risks churn. | 0.75 | Venues change (uniswap-v3/v4, oy-dex); a locked enum would be a false firewall. |
 | A-309 | The docs firewall sibling test (lexicon_meta_docs_test.go) lives at the repo root (same dir as lexicon_meta_test.go), package lexicon_meta_docs. | 0.90 | D-043 chose the sibling; repo-root placement matches the v0.2 meta-test. |
 | A-310 | `.ciagent/` is excluded from the docs firewall scan (meta-files discuss banned terms by name for governance; not user-facing docs). | 0.88 | D-043 rationale; mirrors meta-test self-exclusion. |
 | A-311 | OY-SAT `surveillance-resistant` is LOCKED true (matching OY-LR from v0.2); OY-QR is one-shot (consumed flips to true). | 0.80 | Vision §14 marks OY-LR/OY-SAT as surveillance-resistant; QR is physical/one-shot. |
 | A-312 | `x/hub` HubServiceCount = 3 (Custody/LendingPrimitive/Compliance) per vision §13; full B2B suite (more services) deferred to v0.4. | 0.85 | D-039 + vision §13 name the three; D-039 defers the full suite. |
 | A-313 | `x/bond` OrderSideCount = 2 (Buy/Sell), OrderStatusCount = 3 (Open/Filled/Cancelled). | 0.80 | Standard order-book shape; minimal locked set for v0.3. |
 | A-314 | docs-writer is a SEPARATE custom persona (not folded into frontend-engineer) to keep content-vs-toolchain review boundaries explicit. | 0.75 | The ~20-25 page content load (D-045) justifies a split; lower confidence than the structural decisions. |
 | A-315 | v0.2 custom personas (cosmos-engineer, security-engineer) are NOT reactivated for v0.3 — lower Cosmos-convention and invariant density. | 0.80 | v0.3 modules are bespoke (no new x/gov/x/group/x/authc maps); invariant density is lower (enum counts, not Mission Lock). |
 ---
 ## v0.3 Cross-Reference Summary
 | REQ | Component | Module | Phase (D-044) | Depth (D-03x) |
 |-----|-----------|--------|---------------|---------------|
 | REQ-010 | Exit layer (DEX) | `x/exit/` | P4 | Skeleton (ExitRoute, DEXSwap) — D-036 |
 | REQ-010 | Exit layer (bridge) | `x/bridge/` | P4 | Skeleton (BridgeRoute, BridgeStatus) — D-036 |
 | REQ-022 | Bearers OY-SAT/OY-QR | `x/bearers/` (ext) | P4 | Stubs (no HW) — D-037 |
 | REQ-023 | Anchors | `x/partner/` (ext) | P4 | Skeleton (AnchorCredential) — D-038 |
 | REQ-024 | Hub API | `x/hub/` | P5 | Skeleton (3 services) — D-039 |
 | REQ-025 | Services | `x/services/` | P5 | Skeleton (4 kinds) — D-040 |
 | REQ-026 | Bond market depth | `x/bond/` (ext) | P5 | Skeleton (GrowthBond + secondary) — D-041 |
 | REQ-027 | Docs site | `docs/`, `mkdocs.yml`, `README.md` | P1-P3 | ~22 pages, 4 audiences — D-042/D-045 |
 | REQ-028 | Docs firewall | `lexicon_meta_docs_test.go` | P1 | Sibling meta-test — D-043 |
 **New modules: 4 (exit, bridge, hub, services). Extended modules: 3 (bearers,
 partner, bond). Docs surface: new (docs/, mkdocs.yml, README.md). Firewall: 1
 new sibling test. Total v0.3: 4 new + 3 extended + docs + 1 firewall test.**
@@ -14,57 +14,66 @@
 - Status: COMPLETE (local-only ship, no remote configured)
 - MVP release (v0.1.0) deferred until system validated as production-ready
-## Phase 1 — Foundation (Year 1)
+## Milestone v0.2 — The Mesh (COMPLETE)
-**Target**: first 10,000 Holders, 50 Master Ops
+- [x] P0: Pre-Execution → v0.1.0
 - [x] P1: Orgs + Window Foundation → v0.1.1
 - [x] P2: Pacts + Partners → v0.1.2
 - [x] P3: Councils + Forex → v0.1.3
 - [x] P4: Bonds + Bearers + L2 → v0.1.4
 - [x] P5: Final Review + Ship → v0.1.5 (milestone release)
 - Status: COMPLETE (skeleton + tests layer; released as v0.1.5)
-| Component | Deliverable |
+## Milestone v0.3 — Bearers & Documentation (ACTIVE; feature type; tags v0.2.x)
-|---|---|
+Target: Bearers skeleton (ROADMAP Phase 3 subset) + docs site for nomads and freeholders.
 | OY Chain & Mirror (1) | L1 chain launched, 9 Watchers bonded, Mirror live |
 | Bread Unit & Root Basket (3) | Forge/Fold on Ethereum + 2–3 L2s; initial Root Basket |
 | Storage Substrate (5) | Stash, Vault, Root-Pool contracts |
 | Bloom Engine (4) | Bloom accrual loop tied to Mirror attestations |
 | Fee Covenant (13) | 0.1% ceiling live, processor share 50%, internal minimum 1 Grain |
 | Identity, Standing & Citizenship (6) | Reach v1, Standing v1, Nomad/Freeholder system |
 | Bearers & Processing Mesh (12) | Processing v1, OY-BLE, OY-WiFi-Direct |
 | Mesh Experience (9) | Maps, Pay v1 |
-## Phase 2 — The Mesh (Year 2) — v0.2 SKELETON COMPLETE
+> v0.3 bundles two work-streams under one feature milestone: (A) Bearers
-**Target**: $1B annual volume, 4 service categories
+> skeleton+tests (D-020 pattern) and (B) README.md + MkDocs Material docs site
 > organized by audience, with the REQ-012 lexicon firewall extended to docs.
-> **v0.2 (The Mesh) milestone status**: COMPLETE — skeleton + tests layer shipped.
+| Phase | Type | Scope | Patch |
 > Phase mapping: P0 (spec/research/plan/grill) -> P1 (Orgs+Window) -> P2 (Pacts+Partners)
 > -> P3 (Councils+Forex) -> P4 (Bonds+Bearers+L2) -> P5 (review/audit/ship).
 | Component | Deliverable | v0.2 Skeleton Module | Phase |
 |---|---|---|---|
-| Organizational Primitives (10) | 9 Stand types, Guilds (Hand-Passes free) | x/stand, x/guild | v0.2/P1 |
+| P0 | docs | Pre-Execution (spec/clarify/research/ideate/plan/grill) | v0.2.0 |
-| Partner Spectrum & Forex (11) | First Piers, Forex Engine v1 | x/partner, x/forex | v0.2/P2,P3 |
+| P1 | feat/test+docs | Docs foundation + REQ-012 firewall extension to docs/ + README.md + shared docs | v0.2.1 |
-| Window Primitive (7) | Holder-authorized data channels | x/window | v0.2/P1 |
+| P2 | docs | Nomads docs (docs/nomads/) | v0.2.2 |
-| Pacts Suite (8) | Pause, Ground, Stance, Cover, Stand Registry | x/pact (6-type enum, one module) | v0.2/P2 |
+| P3 | docs | Freeholders docs (docs/freeholders/) + docs/reference/ | v0.2.3 |
-| Governance (14) | Mesh Council activated | x/council (3-kind + Mission Lock const) | v0.2/P3 |
+| P4 | feat | Bearers skeleton I: x/exit, x/bridge, x/bearers (OY-SAT, OY-QR), x/partner (Anchor) | v0.2.4 |
-| Bearers expansion | OY-LR + Beacon v1 | x/bearers (extended) | v0.2/P4 |
+| P5 | feat | Bearers skeleton II: x/hub, x/services, x/bond (Growth Bonds + secondary market) | v0.2.5 |
-| Bonds | First Mesh Bonds | x/bond (8% cap / 0% floor) | v0.2/P4 |
+| P6 | final | REVIEW + AUDIT + milestone SHIP | v0.2.6 (milestone release) |
 | L2 Satellites | Wrapped Bread via IBC | x/satellite (Polygon rep + 4 stubs) | v0.2/P4 |
-> **Tag-line reconciliation (G-010)**: v0.1 pre-MVP shipped on the `v0.0.x` patch line
+### v0.3 Component mapping
 > (ROADMAP lines 4-13: v0.0.0..v0.0.9). v0.2 (The Mesh) ships on the `v0.1.x` patch line
 > (config.json `tag_base: v0.1.x`): P0 -> `v0.1.0`, P1..P4 -> `v0.1.1..v0.1.4`, P5 -> `v0.1.5`
 > (= the v0.2 milestone release, per D-008/D-020 — final phase patch IS the milestone
 > release; no separate minor tag). The `v0.1.5` milestone release is NOT the deferred
 > `v0.1.0` "MVP" tag referenced on line 15 — they are different lines (v0.0.x pre-MVP
 > vs v0.1.x Mesh). No tag collision.
-## Phase 3 — The Bearers (Year 3)
+| Component | Deliverable | v0.3 Skeleton Module | Phase |
 |---|---|---|---|
 | Cross-Chain & Exit (2) | L2/L1 bridge types, DEX swap types | x/exit, x/bridge | v0.3/P4 |
 | Bearers expansion | OY-SAT, OY-QR bearer transport types | x/bearers (extended) | v0.3/P4 |
 | Anchors | First institutional Partner tier | x/partner (extended: Anchor) | v0.3/P4 |
 | Hub API | B2B backbone: custody, lending primitive, compliance types | x/hub | v0.3/P5 |
 | Services | Care / SIM / Vault / Mail service types | x/services | v0.3/P5 |
 | Bond market | Growth Bonds, secondary-market types | x/bond (extended) | v0.3/P5 |
 | Documentation | README.md + MkDocs Material docs site | docs/, mkdocs.yml, README.md | v0.3/P1-P3 |
 | Lexicon firewall | Extend REQ-012 to docs/ + README.md | lexicon_meta_docs_test.go | v0.3/P1 |
 > **Tag-line note (G-010 continuation)**: v0.1 pre-MVP shipped on the `v0.0.x`
 > patch line; v0.2 (The Mesh) shipped on the `v0.1.x` patch line; v0.3 (Bearers
 > & Documentation) ships on the `v0.2.x` patch line (config.json `tag_base:
 > v0.2.x`): P0 -> `v0.2.0`, P1..P5 -> `v0.2.1..v0.2.5`, P6 -> `v0.2.6`
 > (= the v0.3 milestone release, per D-008 — final phase patch IS the
 > milestone release; no separate minor tag).
 ## Phase 3 — The Bearers (Year 3) — v0.3 PARTIAL SKELETON
 **Target**: $10B annual volume → fee auto-declines to 0.07%
 > v0.3 ships a skeleton+tests subset of Phase 3 (Cross-Chain/Exit, OY-SAT/OY-QR,
 > Anchors, Hub API, Services, Bond market depth). Full runtime deferred to v0.4+.
 | Component | Deliverable |
 |---|---|
-| Cross-Chain & Exit (2) | Full L2/L1 bridges, DEX integration |
+| Cross-Chain & Exit (2) | Full L2/L1 bridges, DEX integration (runtime deferred to v0.4) |
-| Bearers expansion | OY-SAT, OY-QR |
+| Bearers expansion | OY-SAT, OY-QR (skeleton types in v0.3) |
-| Hub API | B2B backbone: custody, lending primitive, compliance |
+| Hub API | B2B backbone: custody, lending primitive, compliance (skeleton types in v0.3) |
-| Anchors | First institutional partners |
+| Anchors | First institutional partners (skeleton types in v0.3) |
-| Services | Care / SIM / Vault / Mail |
+| Services | Care / SIM / Vault / Mail (skeleton types in v0.3) |
-| Bond market | Full market, Growth Bonds |
+| Bond market | Full market, Growth Bonds (skeleton types in v0.3) |
 ## Phase 4 — Maturity (Years 4–5+)
 **Target**: $50–100B volume → fees auto-decline to 0.03%
@@ -0,0 +1,83 @@
 # OpenYield
 OpenYield is a jurisdiction-light, public-good mesh for **real production** — a
 protocol organized around Holders, Stands, and the Six Principles, designed to
 hold real value without the words or the shapes that invite capture. The mesh
 runs on OY Chain (Layer 1), a canonical state layer for the Bread unit, the
 Storage Pools (Stash, Vault, Root-Pool), Standing, Watcher attestations, and
 the Pact / Council / Partner surface. It is anti-greed by construction: Mission
 Lock fixes the Six Principles and fee covenant so no council can amend them,
 and the 8% coupon cap on bonds is a mission-locked ceiling, not a parameter.
 ## The Six Principles
 1. **Real value** — the mesh holds real production, not speculation.
 2. **Sustainability** — fees are floored and capped; the protocol cannot drain its users.
 3. **Mission-lock** — the Six Principles and fee covenant are immutable; no council can amend them.
 4. **Openness** — anyone may join; the mesh is a public good.
 5. **Ownership** — Holders own their Stash and their Reach; custody is theirs.
 6. **Self-service** — a Holder can act without a custodian; the mesh is jurisdiction-light.
 ## Bread unit & scale
 The unit of value is **Bread**, scaled in 11 tiers: **Grain → Crumb → Bread →
 Loaf → Batch → Cake → Bakery → Granary → Mill → Harvest → Earth.**
 ## Status
 **v0.3 (Bearers & Documentation) — in progress.** The codebase is a skeleton +
 tests layer (Go types + keeper stubs + invariant tests, zero external Go deps)
 matching the v0.1/v0.2 pre-MVP pattern. See `.ciagent/oy/ROADMAP.md` for the
 phase plan and `.ciagent/oy/PROJECT.md` for governance.
 ## Build & test
 OpenYield is pure Go with **zero external dependencies** (`go.mod` has no
 `require` lines; `go 1.22`). From the repo root:
 ```sh
 go build ./...
 go test ./...
 ```
 ## Docs
 The docs site is [MkDocs Material](https://squidfunk.github.io/mkdocs-material/)
 (a build-only Python dep; **not** a Go dep — `go.mod` is unchanged). To
 preview locally:
 ```sh
 mkdocs serve
 # or build to a static site/ dir:
 mkdocs build
 ```
 The site lives under `docs/` (see `mkdocs.yml` for the nav). Publishing CI is
 deferred to v0.4 (D-046); v0.3 ships the source.
 ## Lexicon firewall
 OpenYield bans 10 financial terms as standalone words (REQ-012) across all Go
 source (`x/**/*.go`) and all docs (`README.md` + `docs/**/*.md`). The banned
 terms are the words you would expect a legacy financial institution to use;
 this README and the docs describe them only by their **safe replacements**, so
 the firewall itself never trips. The firewall is enforced in code by two
 sibling Go tests:
 - `lexicon_meta_test.go` (v0.2) — scans `x/**/*.go`.
 - `lexicon_meta_docs/lexicon_meta_docs_test.go` (v0.3) — scans `README.md` +
  `docs/**/*.md`.
 Both use `lexicon.FindBannedTerm` (word-boundary, case-insensitive), so
 "OpenYield" is safe (word-boundary does not match the banned term inside an
 identifier) but the standalone banned term is not — docs say **"real
 production"** / **"real return"**, and a Holder's identity is **Holder** /
 **Reach**, never the banned word for a custodial position. See
 `docs/shared/lexicon.md` for the glossary of safe replacements.
 ## Governance
 - `.ciagent/oy/PROJECT.md` — full vision, decisions (D-0xx), assumptions.
 - `.ciagent/oy/PLANS.md` — phase plans (v0.1, v0.2, v0.3).
 - `.ciagent/oy/REQUIREMENTS.md` — REQ coverage matrix.
 - `.ciagent/oy/ROADMAP.md` — release roadmap.
@@ -0,0 +1,47 @@
 # Anchor Preview
 An **Anchor** (REQ-023) is the fourth and highest tier of the
 [Partner Spectrum](partner-spectrum.md) (REQ-018) — the first **institutional**
 Partner tier. Anchors are coming in v0.3 P4. This page previews what an Anchor
 is and what the v0.3 skeleton will deliver; the runtime behavior is deferred
 to v0.4+.
 ## What an Anchor is
 An Anchor is a Partner that carries an **AnchorCredential**: a jurisdiction
 (e.g., "EU-MiCA"), a custody provider, and a set of attestation references.
 The Anchor tier is how the jurisdiction-light mesh interfaces with
 jurisdiction-bound institutional actors without becoming them. An Anchor
 holds a credential; the [Holder](../nomads/reach.md) still holds their
 [Stash](../nomads/stash.md). The mesh says **custody**, **compliance**, and
 **jurisdiction** — never the legacy institutional words banned by the
 [lexicon](../shared/lexicon.md).
 ## What is coming in v0.3 P4
 v0.3 P4 (REQ-023) extends `x/partner` with the `AnchorCredential` struct and
 a `Partner.AnchorCredential()` accessor (returns nil for non-Anchor tiers).
 The four-tier `PartnerTier` enum (Op, Master Op, Pier, Anchor) is **unchanged**
 — v0.3 adds Anchor-specific fields, not a new tier. The custody-provider-id
 field is a by-ID-string reference to `x/hub` (the Hub API, coming in v0.3 P5),
 empty in the v0.3 skeleton because the Hub is not live until P5/v0.4. This is
 the P4→P5 ordering edge: `x/hub` in P5 references Anchor partner-ids from P4.
 ## Why Anchors matter to a Freeholder
 A Freeholder engaging an Anchor gets a Partner with a verifiable credential
 and a custody/compliance relationship — useful for cross-jurisdiction routes
 and institutional [bonds](bonds.md). The Anchor's [Standing](standing.md) and
 attestations are visible so the Freeholder can verify the Anchor is real
 before opening a [Window](../nomads/window.md). See
 [Partner Spectrum](partner-spectrum.md) for the other three tiers, and
 [Councils & Voice](councils-voice.md) for how the Mesh Council can suspend or
 revoke an Anchor.
 ## What v0.3 does not deliver
 The v0.3 skeleton is types + tests only (D-035): the `AnchorCredential`
 struct, the accessor, and the `ListAnchors()` keeper alias. Live custody
 routing, attestation verification, and the Hub API integration are v0.4+
 runtime work. See [Components](../reference/components.md) for the full
 module map.
@@ -0,0 +1,46 @@
 # Bonds
 A **Mesh Bond** (REQ-021, vision §17) is a [Stand](stands-guilds.md)-issued
 instrument that pays a **coupon** to its holder over a term and returns the
 principal at maturity. The coupon is bounded by a **mission-locked cap and
 floor**: 8% upper cap, 0% floor (locked `CouponCapBps = 800` and
 `CouponFloorBps = 0` in `x/bond`). The cap exists so the mesh cannot become a
 speculative market; the floor exists so the coupon cannot go negative.
 ## The coupon clamp
 The coupon is clamped to `[floor, cap]` by the `Clamp` helper in `x/bond`
 (same shape as the [Fee Covenant](../shared/six-principles.md) clamp): a
 coupon above 8% is reduced to 8%; a coupon below 0% is raised to 0%; a coupon
 in range is unchanged. The clamp is a tested invariant: below floor → floor,
 above cap → cap, in range → unchanged. This is the Mission Lock's expression
 in the capital layer.
 ## Why a cap
 OpenYield is a public-good mesh for **real production**, not a speculation
 engine. An uncapped coupon market would let a Stand offer arbitrarily high
 coupons to attract Bread, turning the mesh into a speculative race. The 8%
 cap bounds the coupon at a level consistent with real production returns, and
 the [Mission Lock](councils-voice.md) makes the cap non-amendable — no Council
 vote can raise it. The mesh says **coupon** and **real return**, never the
 passive-value or standalone-metric words banned by the
 [lexicon](../shared/lexicon.md).
 ## The bond lifecycle
 A Bond moves through five states (locked `BondStatus` enum in `x/bond`):
 Issued → Active → Matured, with Defaulted and Repaid as terminal paths. The
 issuer is a Stand (referenced by stand-id); the principal is denominated in
 [Grain](../shared/bread-scale.md). The bond market is governed by the
 [Stand Council](councils-voice.md) for the issuing Stand.
 ## Coming in v0.3 P5
 v0.3 P5 (REQ-026) extends the bond market with **Growth Bonds** (a coupon that
 grows over the term, still clamped to the 8% cap) and a **secondary market**
 (Buy/Sell orders on issued bonds). The 8% / 0% consts are unchanged — the
 D-028 regression firewall guarantees v0.3 cannot alter the v0.2 mission-locked
 ceiling. See [Partner Spectrum](partner-spectrum.md) for how Partners relate
 to the bond market, and [Anchor Preview](anchor-preview.md) for the
 institutional tier.
@@ -0,0 +1,48 @@
 # Councils & Voice
 OpenYield governs itself through three **Councils** (REQ-011, vision §19):
 the Mesh Council, the Guild Council, and the Stand Council. Each Freeholder
 participates through the Councils, weighted by **Voice** — a multi-source
 weight that combines [Stash](../nomads/stash.md), [Standing](standing.md),
 Vouch, Freeholder status, and Guild membership. The **Mission Lock** makes
 the covenant non-amendable: no Council can vote to change the
 [Six Principles](../shared/six-principles.md) or the fee covenant.
 ## The three Councils
 - **Mesh Council** — the mesh-wide Council. Handles protocol-level proposals
  that affect every Holder and every [Stand](stands-guilds.md).
 - **Guild Council** — the Council for [Guilds](stands-guilds.md). Handles
  Guild-scope proposals, referenced by guild-id.
 - **Stand Council** — the Council for a single Stand, referenced by stand-id.
  Handles Stand-scope proposals (e.g., Vault use, [Bond](bonds.md) issuance).
 The three-tier shape mirrors the three [Storage Pools](../shared/storage-pools.md):
 a Council exists at each layer where custody is held.
 ## Multi-source Voice
 Voice is not one number. It is a weighted tally from five sources (locked as
 the `VoiceSource` enum in `x/council`): Stash, Standing, Vouch, Freeholder,
 and Guild. A Freeholder with high [Standing](standing.md) and a long-held
 Stash carries more Voice than a freshly-minted one. The
 [TallyResult](../reference/components.md) mirrors the Cosmos SDK `x/gov`
 shape so the governance layer can wire to standard tooling. The VoteOption
 enum is **Yes / No / Abstain** — there is no "no-with-veto", an anti-greed
 design choice.
 ## Mission Lock
 The Mission Lock is a locked `const bool` in `x/council`
 (`MissionLockAmendable = false`). The Six Principles, the fee covenant
 (ceiling 0.1% / floor 0.01% / 1-Grain minimum), and the bond coupon cap
 ([8% / 0%](bonds.md)) cannot be amended by any Council vote. This is the
 firewall that keeps the mesh a public good: governance can act *within* the
 covenant, never *on* the covenant.
 ## How a Freeholder participates
 A Freeholder submits or votes on proposals in the Councils they belong to.
 Each vote is weighted by multi-source Voice; the tally follows `x/gov`
 semantics. See [Bonds](bonds.md) for the coupon cap the Mission Lock protects,
 and [Standing](standing.md) for the metric that weights a Freeholder's Voice.
@@ -0,0 +1,39 @@
 # Freeholders
 A **Freeholder** is a Holder who has earned all four Freeholder signals (REQ-005):
 a 90-day [Stash](../nomads/stash.md), a [Standing](standing.md) threshold of
 4.5★ or higher in 3 categories, the Capital signal, and the Vouch signal. A
 Freeholder is the active participant in the OpenYield mesh — they sit in
 [Stands & Guilds](stands-guilds.md), vote in the three
 [Councils & Voice](councils-voice.md), issue [Bonds](bonds.md), and relate to
 the four-tier [Partner Spectrum](partner-spectrum.md).
 ## The four signals
 The signals are the gate to Freeholder participation. They are deliberately
 heterogeneous — no single input can be pumped — so the path resists gaming:
 - [Signals](signals.md) — the four Freeholder signals (REQ-005): 90-day Stash,
  4.5★+ in 3 categories, Capital, Vouch.
 - [Standing](standing.md) — the Bayesian anti-gaming formula (REQ-006):
  Bayesian prior + time-decay + diversity + voucher-weighting − slashes.
 - [Stands & Guilds](stands-guilds.md) — the nine Stand types (REQ-016) and
  Guilds with free Hand-Passes (REQ-017).
 - [Councils & Voice](councils-voice.md) — the three Councils and the
  non-amendable Mission Lock (REQ-011).
 - [Bonds](bonds.md) — the Mesh Bond Market, the 8% coupon cap / 0% floor
  (REQ-021).
 - [Partner Spectrum](partner-spectrum.md) — the four Partner tiers (REQ-018):
  Op, Master Op, Pier, Anchor.
 - [Anchor Preview](anchor-preview.md) — the first institutional Partner tier
  (REQ-023), coming in v0.3 P4.
 ## What a Freeholder does
 A Freeholder is a Holder who has crossed the signal gate. From there the mesh
 opens: a Freeholder joins a [Stand](stands-guilds.md) (or forms a Guild), votes
 in the [Councils](councils-voice.md) with multi-source Voice, issues or holds
 [Bonds](bonds.md) under the mission-locked coupon cap, and engages the
 [Partner Spectrum](partner-spectrum.md) — including the Anchor tier coming in
 v0.3. The covenant is the same for every audience; the Freeholder pages
 describe how it shows up in governance and capital.
@@ -0,0 +1,42 @@
 # Partner Spectrum
 OpenYield defines a four-tier **Partner Spectrum** (REQ-018, vision §13):
 **Op**, **Master Op**, **Pier**, and **Anchor**. Partners are the external
 actors a [Freeholder](index.md) interacts with through the mesh — service
 operators, route providers, and institutional bridges. The four tiers are
 locked as the `PartnerTier` enum in `x/partner` (exactly 4, regression-tested).
 ## The four tiers
 - **Op** — a service operator. Runs a service a Holder uses through a
  [Window](../nomads/window.md) (e.g., a Maps provider). The lightest tier.
 - **Master Op** — a senior operator. Coordinates multiple Ops or runs a
  higher-trust service. "Op" is the safe short form; the full word is not
  used as a standalone term.
 - **Pier** — a routing Partner. Connects the mesh to external venues (e.g.,
  a DEX or an off-mesh service) and sources [Forex](../reference/components.md)
  rates. Piers route; they do not custody Holder value.
 - **Anchor** — the first institutional Partner tier. Carries a credential
  (jurisdiction, custody provider, attestations). See
  [Anchor Preview](anchor-preview.md) for what is coming in v0.3 P4.
 ## How Freeholders relate to Partners
 A Freeholder authorizes a Partner to act on their behalf through a scoped,
 time-limited, revocable [Window](../nomads/window.md) — never by handing over
 custody. The Partner holds a credential, not the Holder's [Stash](../nomads/stash.md).
 A Partner's [Standing](standing.md) is visible so a Freeholder can choose an
 operator with a real history over a freshly-spun-up alternative (see
 [Maps & Pay](../nomads/maps-pay.md)).
 ## Partner status
 Each Partner has a status (locked `PartnerStatus` enum in `x/partner`):
 Pending → Active, with Suspended and Revoked as the governance paths. The
 [Mesh Council](councils-voice.md) can suspend or revoke a Partner. The four
 tiers and the status enum are unchanged by v0.3 — v0.3 only *extends*
 `x/partner` with the Anchor credential shape (REQ-023), not a new tier.
 See [Storage Pools](../shared/storage-pools.md) for why the mesh says
 "Holder" and "Reach" rather than the legacy custodial words, and
 [Bonds](bonds.md) for the coupon market a Partner may route to.
@@ -0,0 +1,45 @@
 # The Four Freeholder Signals
 The four **Freeholder signals** (REQ-005) are the gate to Freeholder
 participation. A [Holder](../nomads/reach.md) who earns all four becomes a
 [Freeholder](index.md) — eligible to join [Stands & Guilds](stands-guilds.md),
 vote in the [Councils](councils-voice.md), and issue [Bonds](bonds.md). The
 signals are deliberately heterogeneous: no single input can be pumped, so the
 path resists gaming.
 ## 1. The 90-day Stash
 A Holder must hold a [Stash](../nomads/stash.md) continuously for 90 days
 (REQ-014). The signal is about **continuity, not size** — a small Stash held
 steadily counts. This filters out transient actors who spin up a position to
 game a vote and then leave. See [Storage Pools](../shared/storage-pools.md)
 for the three-pool model.
 ## 2. Standing of 4.5★ or higher in 3 categories
 A Holder must earn a [Standing](standing.md) of 4.5★ or higher in **three
 distinct categories** (REQ-006). The diversity requirement is the anti-gaming
 core: a Holder cannot reach Freeholder by repeating the same action with the
 same counterparty. Three categories force breadth.
 ## 3. Capital
 The Capital signal requires a Holder to hold a meaningful amount of
 [Bread](../shared/bread-scale.md) in their Stash. The threshold is set by the
 mesh [Councils](councils-voice.md) and is a stake, not a fee: the Holder keeps
 the Bread. Capital aligns the Freeholder's stake with the mesh.
 ## 4. Vouch
 The Vouch signal requires another Freeholder to vouch for the Holder. A
 vouch from a high-[Standing](standing.md) Freeholder carries more weight
 (voucher-weighting), so a single colluding vouch cannot carry a Holder over
 the gate. Vouch is the social signal that ties the other three together.
 ## Why four, not one
 Each signal covers a different attack surface: continuity (90-day Stash),
 breadth (3-category Standing), stake (Capital), and social trust (Vouch).
 Earning all four is the proof a Holder is a participant, not a transient
 gamer. See [Standing](standing.md) for the anti-gaming math, and
 [Bonds](bonds.md) for what a Freeholder can do once the signals are earned.
@@ -0,0 +1,49 @@
 # Bayesian Standing
 **Standing** (REQ-006) is a Holder's measured history on the mesh — the
 anti-gaming metric that gates [Freeholder](index.md) participation and weighs
 [Voice](councils-voice.md) in the [Councils](councils-voice.md). Standing is
 not a count of transactions and not a reputation score you can farm. It is a
 Bayesian score that resists the obvious attacks: volume spam, self-dealing,
 fake vouches.
 ## The formula, at conceptual depth
 Standing combines four signals and a penalty:
 - **Bayesian prior + updates.** The mesh starts with a prior for each Holder
  and updates it from each observed action. A burst of activity cannot
  inflate Standing because the prior anchors it.
 - **Time-decay.** Old evidence decays, so a Holder cannot rest on a burst
  from years ago. Standing reflects *recent, sustained* real production.
 - **Diversity weighting.** A Holder who acts across many services, many
  [Stands](stands-guilds.md), and many [bearers](../nomads/bearers.md) accrues
  more Standing than one who repeats the same action with the same
  counterparty. Diversity is the anti-collusion lever.
 - **Voucher-weighting.** A vouch from a high-Standing Freeholder counts for
  more than a vouch from a low-Standing one. This makes fake vouches expensive:
  the voucher must themselves have Standing to lose.
 - **Minus slashes.** Bad behavior (failed attestations, broken Pacts) removes
  Standing. Slashes are the penalty that bounds the upside of gaming.
 > The full sub-tables (priors, decay rates, diversity categories, slash
 > conditions) are deferred per PROJECT.md Q2. This page gives the conceptual
 > depth; the [nomads Standing page](../nomads/standing.md) gives the plain-
 > language version.
 ## Why it cannot be gamed
 There is no single input a Holder can pump. Volume is bounded by the Bayesian
 prior; recency is bounded by time-decay; breadth is bounded by diversity;
 social trust is bounded by voucher-weighting; and any attempt that misfires
 costs Standing via slashes. The four signals (the [90-day Stash](signals.md),
 3-category threshold, Capital, Vouch) sit on top of this metric, so the
 Freeholder gate inherits the same anti-gaming property.
 ## What Standing is not
 Standing is not a custodial position, a tier you buy, or legacy history. It
 is a measured, decayed, diversified Bayesian score. See
 [Storage Pools](../shared/storage-pools.md) for why the mesh says "Stash"
 rather than the legacy custodial words, and [Councils & Voice](councils-voice.md)
 for how Standing weights a Freeholder's vote.
@@ -0,0 +1,47 @@
 # Stands & Guilds
 A **Stand** is a governed group of Holders that holds a [Vault](../shared/storage-pools.md)
 in common (REQ-016). A **Guild** is a looser association of Holders that can
 pass value among its members for free (REQ-017). Both are the organizational
 layer a [Freeholder](index.md) joins after earning the four
 [signals](signals.md).
 ## The nine Stand types
 OpenYield defines exactly nine Stand types (REQ-016, vision §11), locked as a
 const in `x/stand`:
 1. **Household** — a family-scale group.
 2. **Crew** — a working team.
 3. **Entity** — a single legal actor.
 4. **Co-op** — a cooperative.
 5. **Circle** — an affinity group.
 6. **Trust** — a trust arrangement.
 7. **Foundation** — a purpose-bound entity.
 8. **Confederation** — a federation of Stands.
 9. **Shadow** — a privacy-preserving Stand.
 A Stand's decision policy (threshold or weighted, mirroring the Cosmos SDK
 `x/group` shape) governs how its Vault is used. A Stand can also issue
 [Bonds](bonds.md) — the bond issuer is a Stand, referenced by stand-id.
 ## Guilds and Hand-Passes
 A **Guild** is a looser association: it may affiliate with a Stand or stand
 alone. Inside a Guild, a **Hand-Pass** moves [Bread](../shared/bread-scale.md)
 between members at a **0% protocol fee** (REQ-017, locked `HandPassFeeBps = 0`
 in `x/guild`). The 0% fee is mission-locked: the mesh does not tax the social
 transfer of value among a self-organized group. See the
 [Fee Covenant](../shared/six-principles.md) for the broader fee shape.
 ## How a Freeholder joins
 A Freeholder joins a Stand by becoming a member (the Stand's policy admits
 them) or forms a Guild as a founder. Membership is recorded in `x/stand`
 and `x/guild` respectively, by stand-id / guild-id and the member's
 [Reach](../nomads/reach.md). From a Stand a Freeholder gains Vault access and
 the ability to issue [Bonds](bonds.md); from a Guild a Freeholder gains free
 Hand-Passes with other members.
 See [Councils & Voice](councils-voice.md) for how Stands and Guilds each get a
 Council, and [Storage Pools](../shared/storage-pools.md) for the Vault layer.
@@ -0,0 +1,30 @@
 # OpenYield
 OpenYield is a jurisdiction-light, public-good mesh for **real production**. It
 runs on OY Chain (Layer 1), a canonical state layer for the Bread unit, the
 Storage Pools, Standing, Watcher attestations, and the Pact / Council /
 Partner surface. The mesh is anti-greed by construction: Mission Lock fixes
 the Six Principles and fee covenant so no council can amend them, and the
 coupon cap on bonds is a mission-locked ceiling, not a parameter.
 ## Audiences
 The docs are organized by audience:
 - **Nomads** — the everyday Holder: your Reach, your Stash, your bearers, how
  you pay (Maps-Pay), the Pacts you join, and the Window you open. See
  [Nomads](nomads/index.md).
 - **Freeholders** — the active participant: the four signals, Bayesian
  Standing, Stands & Guilds, the three Councils and Voice, the bond market,
  and the four-tier Partner Spectrum. See [Freeholders](freeholders/index.md).
 - **Shared** — concepts common to every audience: the Six Principles, the
  Bread scale, the three Storage Pools, the Watchers & Mirror, the lexicon
  glossary, and the vision overview. See [Shared](shared/index.md).
 - **Reference** — the architecture and component map. See
  [Reference](reference/architecture.md).
 ## Build the docs
 This site is [MkDocs Material](https://squidfunk.github.io/mkdocs-material/),
 a build-only Python dep (not a Go dep). To preview locally, see the
 [README](../README.md) for build instructions.
@@ -0,0 +1,46 @@
 # Bearers
 The **bearers** (REQ-019) are how a Nomad reaches the mesh. OpenYield ships
 six bearers through a single **Unified Bearer Layer**: the mesh does not
 care which bearer a Holder uses — first-to-deliver-wins, and a Nomad can
 switch bearers without switching identity. The [Mirror](../shared/watchers-mirror.md)
 mirrors the canonical state to every bearer so a Nomad can read the mesh's
 real return on any of them.
 ## The six bearers
 | Bearer | Live in v0.2 | What it is |
 |---|---|---|
 | **Internet** | yes | the default bearer; OY Chain over the open internet. |
 | **OY-BLE** | yes | Bluetooth Low Energy; short-range, peer-to-peer, no phone plan. |
 | **OY-WiFi-Direct** | yes | WiFi Direct; local mesh without an access point. |
 | **OY-LR** | yes | Long Range radio (LoRa-class); long-distance, low-bandwidth, surveillance-resistant. |
 | **OY-SAT** | coming (v0.3 P4) | satellite; offline coverage via a satellite constellation. |
 | **OY-QR** | coming (v0.3 P4) | signed QR code; one-shot offline transfer scanned by a peer. |
 ## What this means for a Nomad
 A Nomad does not pick "the right bearer". The four already-live bearers
 (Internet, OY-BLE, OY-WiFi-Direct, OY-LR) cover the everyday situations:
 on the open internet, in a room with another Holder, in a local group with
 no router, or kilometers away with no infrastructure. OY-SAT and OY-QR
 extend that to true-offline paths and are coming in the next phase.
 ## Surveillance resistance
 OY-LR, OY-BLE, OY-WiFi-Direct, OY-SAT, and OY-QR are designed to be
 surveillance-resistant: a Nomad can send or receive value without a
 phone plan, a SIM, or a custodial on-ramp. The bearer is the transport; the
 [Reach](reach.md) is the identity; the [Stash](stash.md) is the storage. None
 of them depends on a custodial position.
 ## First-to-deliver-wins
 The Unified Bearer Layer is first-to-deliver-wins: if a Nomad sends a
 transfer over two bearers at once, the mesh accepts the first one that
 arrives and drops the duplicate. This is why a Nomad can switch bearers
 mid-transfer without double-spending.
 See [Watchers & Mirror](../shared/watchers-mirror.md) for how the canonical
 state is mirrored to every bearer, and [Maps & Pay](maps-pay.md) for how a
 Nomad uses a bearer to find and pay for services.
@@ -0,0 +1,42 @@
 # Nomads
 A **Nomad** is a person using the OpenYield mesh through a **Reach** — the
 protocol-level identity a Holder uses to act on the mesh without a
 custodian, a gatekeeper, or a legacy financial position. The Nomad path
 is the entry path: a Nomad is a Holder who has a Reach and a [Stash](stash.md)
 and is on the way to earning the four Freeholder signals, but has not yet
 earned all four.
 ## The Nomad path
 The pages here cover what a Nomad does day-to-day on the mesh:
 - [Reach](reach.md) — the identity; the first Freeholder signal (REQ-005).
 - [Stash](stash.md) — the personal [Storage Pool](../shared/storage-pools.md)
  where a Nomad holds Bread (REQ-014).
 - [Bearers](bearers.md) — how a Nomad reaches the mesh (REQ-019): Internet,
  OY-BLE, OY-WiFi-Direct, OY-LR live now; OY-SAT and OY-QR coming.
 - [Maps & Pay](maps-pay.md) — finding services and paying for them.
 - [Pacts](pacts.md) — the six contract shapes a Nomad encounters
  (REQ-020): Pause, Ground, Stance, Cover, Stand Registry, Hub API.
 - [Standing](standing.md) — the Bayesian anti-gaming metric (REQ-006),
  and why the mesh cannot be gamed.
 - [Window](window.md) — the delegation primitive (REQ-015): scope,
  duration, rate-limit, audit-log, revoke.
 ## Where a Nomad starts
 A Nomad starts with a Reach and a Stash — that is enough to begin. From
 there the bearers carry value to the Stash, Maps finds services, Pay and
 the Window let a Nomad use them without giving up custody, and Standing
 accrues as the Nomad acts. A Nomad who earns the 90-day Stash signal, the
 Standing threshold, the Capital signal, and the Vouch signal becomes a
 Freeholder (see the Freeholders section).
 ## Shared concepts
 The Nomad path rests on the [shared concepts](../shared/index.md): the
 [Six Principles](../shared/six-principles.md), the [Bread scale](../shared/bread-scale.md),
 the [Storage Pools](../shared/storage-pools.md), the [Watchers & Mirror](../shared/watchers-mirror.md),
 and the [Lexicon](../shared/lexicon.md). The covenant is the same for
 every audience; the Nomad pages describe how it shows up in everyday use.
@@ -0,0 +1,46 @@
 # Maps & Pay
 **Maps** and **Pay** are the day-to-day Mesh Experience a Nomad uses on the
 mesh. Maps finds services; Pay settles them. Both run over the
 [bearers](bearers.md) and read the [Mirror](../shared/watchers-mirror.md) so a
 Nomad can find and pay for a service on a surveillance-resistant bearer
 without an internet connection to OY Chain.
 ## Maps
 Maps is the directory of services a Nomad can reach. A service is anything
 a Partner or a Stand exposes to the mesh: a Care service, a SIM, a Vault,
 a Mailbox (preview of v0.3 P5 — see [Pacts](pacts.md) for the Hub API). Maps
 is sorted by geographic proximity (REQ-007): a Nomad physically closer to a
 service or its operator is shown that service first. There is no paid
 ranking; the order is proximity, not promotion.
 ## Pay
 Pay is how a Nomad settles a service. A payment is a transfer of Bread
 from the Nomad's [Stash](stash.md) to the service operator's Stash, signed
 by the Nomad's [Reach](reach.md). The fee covenant floors and caps the fee;
 inside a Guild, a Hand-Pass is free at the protocol level (REQ-017). Pay
 runs over any bearer, first-to-deliver-wins.
 ## Authorize, don't hand over
 For recurring services a Nomad does not re-sign every payment. Instead
 the Nomad opens a [Window](window.md) to the service: a scoped,
 time-limited, rate-limited, revocable capability that lets the service pull
 value from the Stash within bounds the Nomad set. The Window is audited;
 the Nomad can revoke it at any time. This is the self-service principle in
 practice: the Nomad delegates a capability, not custody.
 ## Find, pay, verify
 A Nomad's loop is:
 1. **Find** a service on Maps.
 2. **Pay** once, or **authorize** a [Window](window.md) for recurring use.
 3. **Verify** the service against the Watcher attestations on the Mirror
   (see [Watchers & Mirror](../shared/watchers-mirror.md)).
 See [Stash](stash.md) for where the Bread comes from, [Window](window.md)
 for the delegation primitive, and [Standing](standing.md) for how a
 service operator's history is measured.
@@ -0,0 +1,41 @@
 # Pacts
 The **six Pacts** (REQ-020) are the contract shapes a Nomad encounters on
 the mesh. A Pact is a typed, mission-locked agreement between parties; the
 core terms of the Pause, Ground, and Stance Pacts are **non-amendable** —
 no Council can rewrite them after the fact. A Nomad mostly interacts with
 Pacts through [Maps & Pay](maps-pay.md) and the [Window](window.md)
 primitive, but it helps to know what each one is.
 ## The six Pacts
 | Pact | What it does for a Nomad |
 |---|---|
 | **Pause** | A temporary hold. A Nomad can pause a recurring payment or a Window without voiding it; the Pause core terms are non-amendable. |
 | **Ground** | A baseline obligation the mesh enforces by default — the "ground rules" between a Nomad and a service operator. Non-amendable. |
 | **Stance** | A stated position a party commits to (e.g., a service operator's Stance on jurisdiction-light operation). Non-amendable. |
 | **Cover** | A flat commitment a Stand or a Partner offers to cover a Nomad against a defined failure; a Nomad reads Cover when choosing a service. |
 | **Stand Registry** | The registry of the nine [Stand](../shared/storage-pools.md) types (Household, Crew, Entity, Co-op, Circle, Trust, Foundation, Confederation, Shadow) a Nomad can join. |
 | **Hub API** | The B2B backbone (preview of v0.3 P5) — the Hub Pact exposes custody, a lending primitive, and compliance to service operators. A Nomad sees the Hub through Maps, not directly. |
 ## What a Nomad actually does with Pacts
 A Nomad does not draft Pacts by hand. The flow is:
 1. **Find** a service on [Maps & Pay](maps-pay.md).
 2. The service's terms are backed by one or more Pacts (e.g., a recurring
   payment is a Pause-able Window; a Stand's service is registered in the
   Stand Registry).
 3. The Nomad **authorizes** a [Window](window.md) scoped to those terms.
 ## Mission Lock
 The Pause, Ground, and Stance core terms are mission-locked: a `const`
 flag in the Pact module marks them non-amendable, and an invariant test
 asserts that flag can never flip. A Nomad can rely on the ground rules
 not changing. See [Six Principles](../shared/six-principles.md) for the
 mission-lock covenant.
 See [Window](window.md) for the delegation primitive the Pacts are
 delivered through, and [Standing](standing.md) for how a service
 operator's history is measured.
@@ -0,0 +1,48 @@
 # Reach
 A **Nomad** is a person using the OpenYield mesh through a **Reach** — the
 protocol-level identity that lets a Holder act on the mesh without a
 custodian, a gatekeeper, or a legacy financial position. The Reach is the
 first of the four Freeholder signals (REQ-005), and it is the baseline every
 Nomad starts from: a Nomad is a Holder who has a Reach and a Stash but has not
 yet earned all four Freeholder signals.
 ## What a Reach is
 A Reach is an identity, not a custodial position. It is the by-ID-string a
 Holder uses to receive value, open a [Window](window.md), join a Stand, or
 pay for a service. The protocol does not require KYC at the protocol layer;
 the Reach is the unit of self-service (see [Six
 Principles](../shared/six-principles.md)).
 ## How a Nomad starts
 A Nomad starts with two things:
 1. **A Reach** — the identity.
 2. **A [Stash](stash.md)** — the personal [Storage Pool](../shared/storage-pools.md)
   where the Holder holds Bread.
 That pair is enough to begin. From there a Nomad can use the [bearers](bearers.md)
 to reach the mesh, find services on [Maps & Pay](maps-pay.md), authorize a
 [Window](window.md) to a partner, and accrue [Standing](standing.md).
 ## Geographic proximity
 The mesh processes actions first-come, first-served with a
 geographic-proximity preference (REQ-007) — a Nomad physically closer to a
 service or a Stand's region is served first. The Reach is how the mesh
 identifies the Nomad for that ordering; there is no separate tier to buy into.
 ## The four Freeholder signals
 The Reach is the first Freeholder signal. The four signals (REQ-005) are
 earned over time: the 90-day [Stash](stash.md) signal, the Standing
 threshold, the Capital signal, and the Vouch signal. A Nomad who earns all
 four becomes a Freeholder (see the Freeholders section). The pages here cover
 the Nomad path — everything up to that point.
 See [Stash](stash.md) for the Storage Pool a Reach holds Bread in,
 [Bearers](bearers.md) for how to reach the mesh, and
 [Standing](standing.md) for the anti-gaming metric that accrues as a Nomad
 acts on the mesh.
@@ -0,0 +1,44 @@
 # Standing
 **Standing** (REQ-006) is a Holder's measured history on the mesh. It is
 the anti-gaming metric: a Bayesian score with time-decay, diversity
 weighting, and voucher-weighting, minus slashes for bad behavior. For a
 Nomad, the headline is that the mesh **cannot be gamed** — Standing
 rewards real production and resists the obvious attacks (volume spam,
 self-dealing, fake vouches).
 ## What Standing is, in plain language
 Standing is not a count of transactions. It is a Bayesian score: the mesh
 starts with a prior, updates it from each observed action, and decays
 old evidence so a Holder cannot rest on a burst of activity from years
 ago. Diversity weighting means a Nomad who acts across many services,
 many Stands, and many bearers accrues more Standing than a Nomad who
 repeats the same action with the same counterparty. Voucher-weighting
 means a vouch from a Holder with high Standing counts for more.
 ## Why it matters to a Nomad
 A Nomad mostly reads Standing, not computes it. Two places it shows up:
 - **Choosing a service.** Maps shows a service operator's Standing so a
  Nomad can pick an operator with a real history over a freshly-spun-up
  alternative (see [Maps & Pay](maps-pay.md)).
 - **The Freeholder path.** Earning a Standing threshold in 3 categories
  is one of the four Freeholder signals (REQ-005). A Nomad who accrues
  Standing over time is on the path to becoming a Freeholder.
 ## What Standing is not
 Standing is not a custodial position, a tier you buy, or a reputation
 score you can farm. It is not legacy custodial history. The
 Bayesian + time-decay + diversity design is exactly what makes it hard to
 game: there is no single input a Holder can pump.
 ## The math, deferred
 The full Bayesian formula (priors, decay rates, diversity sub-tables,
 slash conditions) is documented in the Freeholders section — a Nomad does
 not need the math to use the mesh. See
 [Six Principles](../shared/six-principles.md) for the covenant Standing
 enforces, and [Reach](reach.md) for the identity a Standing accrues to.
@@ -0,0 +1,48 @@
 # Stash
 A **Stash** is a Holder's personal [Storage Pool](../shared/storage-pools.md)
 (REQ-014). It is the place a Nomad holds Bread, and it is the second thing a
 Nomad needs after a [Reach](reach.md) to begin. The Stash is the unit of
 self-service: the Holder owns it, controls it, and can delegate a scoped,
 time-limited, revocable [Window](window.md) to a partner or a service
 without giving up custody.
 ## What a Stash is
 The Stash is the Holder-level layer of the three Storage Pools (Stash,
 Vault, Root-Pool). It is a storage layer, not a custodial position: the
 protocol holds the canonical state that records who owns what; the Holder
 holds the value. There is no custodian between a Nomad and their Stash.
 ## How a Nomad uses a Stash
 A Nomad moves Bread into a Stash through the [bearers](bearers.md) — a
 Holder on a surveillance-resistant bearer can receive value without an
 internet connection to OY Chain. From the Stash a Nomad can:
 - **Hold** Bread (the unit of value — see [Bread scale](../shared/bread-scale.md)).
 - **Pass** value to another Reach (the Hand-Pass, free at the protocol
  level inside a Guild).
 - **Pay** for a service via [Maps & Pay](maps-pay.md).
 - **Authorize** a [Window](window.md) so a partner or service can read the
  Stash within bounds the Holder set.
 ## The 90-day Freeholder signal
 Holding a Stash continuously for 90 days is the first of the four
 Freeholder signals (REQ-005). The Stash does not need to hold a large
 amount — the signal is about continuity, not size. A Nomad who keeps a
 Stash for 90 days and earns the other three signals (Standing, Capital,
 Vouch) becomes a Freeholder.
 ## Delegation, not custody
 The Stash stays the Holder's. When a Nomad opens a Window to a service,
 the service gets a scoped capability (e.g., "read Stash balance for the
 next hour", "spend up to N Grain on this service this week") — it does not
 get custody. The Window is revocable, rate-limited, and audited. See
 [Window](window.md) for the primitive.
 See [Storage Pools](../shared/storage-pools.md) for the full three-pool
 model, and [Bearers](bearers.md) for how value reaches a Stash over a
 surveillance-resistant bearer.
@@ -0,0 +1,45 @@
 # Window
 A **Window** (REQ-015) is the primitive a Nomad uses to delegate a
 capability without delegating custody. It is scoped, time-limited,
 rate-limited, audited, and revocable. A Nomad opens a Window so a partner
 or a service can act on the Nomad's [Stash](stash.md) within bounds the
 Nomad set — the partner never gets custody, and the Nomad can close the
 Window at any time.
 ## The five parts of a Window
 | Part | What it bounds |
 |---|---|
 | **Scope** | what the grantee can do (e.g., read Stash balance, spend up to N Grain on a specific service). |
 | **Duration** | when the Window starts and ends (a start time and an end time). |
 | **Rate limit** | how many actions per duration window (e.g., at most 10 reads per hour). |
 | **Audit log** | an append-only log of every action the grantee took under the Window. |
 | **Revoke** | the Nomad can revoke the Window at any time; revoke after expiry is a no-op. |
 ## Why a Nomad opens one
 A Nomad opens a Window for the same reason a Nomad uses [Maps & Pay](maps-pay.md):
 to let a service do something on the Nomad's behalf without handing over
 the Stash. Common examples:
 - A recurring service (e.g., a Care service) pulls a capped amount of
  Bread from the Stash each week, within a rate limit the Nomad set.
 - A partner reads the Stash balance for a compliance check, scoped to
  read-only, time-limited to one hour.
 - A Stand operator processes a Pass-Act on the Nomad's behalf inside a
  scoped, audited Window.
 ## Lifecycle
 A Window moves through a fixed lifecycle: **Open → Active → Revoked** or
 **Expired**. A Nomad can revoke at any point; revoking after expiry is a
 no-op (idempotent). The lifecycle is mission-locked: a partner cannot
 extend a Window past its end time — the Nomad must open a new one.
 ## Self-service, by design
 The Window is the self-service principle in code. The protocol records
 the Window on OY Chain; the partner holds only the capability, never the
 value. See [Six Principles](../shared/six-principles.md) for the covenant,
 and [Pacts](pacts.md) for the contract shapes delivered through Windows.
@@ -0,0 +1,51 @@
 # Architecture
 This is the architecture index for OpenYield. The mesh is built from 14
 modular components and 6 cross-component interfaces, with a critical blocker
 chain that fixes the build order. The full governance source lives in
 `.ciagent/oy/ARCHITECTURE.md`; this page is the user-facing rewrite, kept
 lexicon-clean by the [docs firewall](../shared/lexicon.md).
 ## The 14 modular components
 | # | Component | Vision § | Phase |
 |---|---|---|---|
 | 1 | OY Chain & Mirror | §7 | P1 |
 | 2 | Cross-Chain & Exit | §7 | P3 |
 | 3 | Bread Unit & Root Basket | §6, §16 | P1 |
 | 4 | Bloom Engine | §6 | P1 |
 | 5 | Storage Substrate | §5 | P1 |
 | 6 | Identity, Standing & Citizenship | §8, §9 | P1 |
 | 7 | Window Primitive | §10 | P2 |
 | 8 | Pacts Suite (Pause, Ground, Stance, Cover, Stand Registry, Hub API, Bonds) | §16, §17 | P2 |
 | 9 | Mesh Experience (Maps, Pay) | §8 | P1 |
 | 10 | Organizational Primitives (Stands, Guilds) | §11, §12 | P2 |
 | 11 | Partner Spectrum & Forex | §13 | P2 |
 | 12 | Bearers & Processing Mesh | §14, §15 | P1 |
 | 13 | Fee Covenant | §18 | P1 |
 | 14 | Governance (Mesh/Guild/Stand Councils) | §19 | P2 |
 ## The 6 cross-component interfaces
 1. **Standing API** — consumed by Identity, Window, Pacts, Orgs, Partners,
   and Governance. See [Standing](../freeholders/standing.md).
 2. **Forge / Fold Interface** — mints [Bread](../shared/bread-scale.md)
   against Root Basket assets only. See the Bloom Engine.
 3. **Watcher Attestation Interface (the Mirror)** — 9 Watchers, 6-of-9
   quorum. See [Watchers & Mirror](../shared/watchers-mirror.md).
 4. **Window Lifecycle Interface** — Holder-authorized, scope-bounded,
   revocable. See [Window](../nomads/window.md).
 5. **Fee Covenant Interface** — auto-decline, ceiling/floor enforced.
   See [Six Principles](../shared/six-principles.md).
 6. **Voice / Council Interface** — multi-source Voice, Mission Lock enforced.
   See [Councils & Voice](../freeholders/councils-voice.md).
 ## The critical blocker chain
 The components build in a fixed order: OY Chain (1) → Bread/Root Basket (3)
 → Storage (5) → Identity/Standing (6), which then unblocks {Window (7),
 Pacts (8), Orgs (10), Partners (11), Governance (14)}. The Fee Covenant (13)
 blocks Pacts, Orgs, Partners, and Bearers — the fee shape must exist before
 any of those can ship. v0.3 adds the Cross-Chain & Exit layer (component 2)
 and the Bearers/Partner/Bond extensions; see [Components](components.md) for
 the `x/` module map and the v0.3 phase status.
@@ -0,0 +1,62 @@
 # Component Map
 This is the `x/` module map for OpenYield. Each module is a Cosmos-SDK-style
 `x/<name>/types/` package, zero external Go deps (G-006), referenced by
 ID-string across modules (G-003 — no struct imports). The map covers v0.1,
 v0.2, and v0.3 (skeleton + tests depth, D-020/D-035).
 ## v0.1 baseline (pre-MVP skeleton)
 | Module | Vision § | REQ | Purpose |
 |---|---|---|---|
 | `x/mesh` | §7 | REQ-008 | OY Chain (Layer 1) shell |
 | `x/mirror` | §7 | REQ-004 | Mirror of canonical state to bearers |
 | `x/bread` | §4, §6 | REQ-013 | Bread unit + 11-tier scale |
 | `x/bloom` | §6 | REQ-003 | Bloom Engine (real production only) |
 | `x/forge` | §4.2 | REQ-003 | Forge/Fold minting against Root Basket |
 | `x/rootpool` | §5 | REQ-014 | Root-Pool (mesh treasury) |
 | `x/stash` | §5 | REQ-014 | Stash (Holder-level storage pool) |
 | `x/vault` | §5 | REQ-014 | Vault (Stand-level storage pool) |
 | `x/identity` | §8 | REQ-005 | Reach identity (Holder, no KYC) |
 | `x/standing` | §9.2 | REQ-006 | Bayesian Standing |
 | `x/processing` | §15 | REQ-007 | FCFS processing mesh |
 | `x/watcher` | §7 | REQ-004 | 9 Watchers, 6-of-9 quorum |
 | `x/feecovenant` | §18 | REQ-002 | Fee ceiling/floor/minimum |
 | `x/still` | §3 | — | Still/Stir pause/resume state |
 | `x/bearers` | §14 | REQ-019 | Unified Bearer Layer (6 bearers) |
 ## v0.2 (The Mesh — skeleton + tests)
 | Module | Vision § | REQ | Purpose |
 |---|---|---|---|
 | `x/window` | §10 | REQ-015 | Window primitive (scope, rate-limit, revoke) |
 | `x/stand` | §11 | REQ-016 | Nine Stand types |
 | `x/guild` | §12 | REQ-017 | Guilds + Hand-Passes at 0% protocol fee |
 | `x/pact` | §16 | REQ-020 | Six Pacts (Pause, Ground, Stance, Cover, Stand Registry, Hub API) |
 | `x/partner` | §13 | REQ-018 | Four-tier Partner Spectrum (Op, Master Op, Pier, Anchor) |
 | `x/council` | §19 | REQ-011 | Three Councils + Mission Lock (non-amendable) |
 | `x/forex` | §13 | Forex v1 | Forex Engine v1 (pair type + oracle interface) |
 | `x/bond` | §17 | REQ-021 | Mesh Bond Market (8% cap / 0% floor clamp) |
 | `x/satellite` | §7 | REQ-009 | L2 IBC Satellite (Polygon active + 4 stubs) |
 ## v0.3 (Bearers & Documentation — in progress)
 | Module | Vision § | REQ | Status | Purpose |
 |---|---|---|---|---|
 | `x/bridge` | §7 | REQ-010 | P4 (pending) | L2↔L1 bridge routes |
 | `x/exit` | §7 | REQ-010 | P4 (pending) | Exit routes + DEX swaps |
 | `x/bearers` (ext) | §14 | REQ-022 | P4 (pending) | OY-SAT + OY-QR transport stubs |
 | `x/partner` (ext) | §13 | REQ-023 | P4 (pending) | AnchorCredential (Anchor tier) |
 | `x/hub` | §13, §16 | REQ-024 | P5 (pending) | Hub API (Custody, Lending, Compliance) |
 | `x/services` | §13 | REQ-025 | P5 (pending) | Services (Care, SIM, Vault, Mail) |
 | `x/bond` (ext) | §17 | REQ-026 | P5 (pending) | Growth Bonds + secondary market |
 ## Notes
 - Every module follows the same pattern: `types/types.go` + `types/types_test.go`
  (package `types`), zero external deps, by-ID-string inter-module refs (G-003).
 - Each new/extended test file includes a lexicon assertion (REQ-012); the
  project-wide meta-test (`lexicon_meta_test.go`) scans all `x/**/*.go`.
 - The docs firewall (`lexicon_meta_docs_test.go`) scans `README.md` + all
  `docs/**/*.md`. See the [architecture index](architecture.md) for the
  14-component view and the 6 cross-component interfaces.
@@ -0,0 +1,35 @@
 # Bread scale
 The unit of value in OpenYield is **Bread** (REQ-013). Bread is scaled in 11
 tiers, each 1,000× the previous, so a Holder can reason about a Crumb and a
 Granary in the same mental model:
 | Tier | Name | Multiple |
 |---|---|---|
 | 1 | **Grain** | 1 |
 | 2 | **Crumb** | 1,000 Grain |
 | 3 | **Bread** | 1,000 Crumb |
 | 4 | **Loaf** | 1,000 Bread |
 | 5 | **Batch** | 1,000 Loaf |
 | 6 | **Cake** | 1,000 Batch |
 | 7 | **Bakery** | 1,000 Cake |
 | 8 | **Granary** | 1,000 Bakery |
 | 9 | **Mill** | 1,000 Granary |
 | 10 | **Harvest** | 1,000 Mill |
 | 11 | **Earth** | 1,000 Harvest |
 ## Why 11 tiers
 The 11-tier scale gives the mesh a single unit for everything from a
 1-Grain internal minimum (the Fee Covenant floor) to the Earth-tier totals
 held in the Root-Pool. There is no separate "small unit" and "large unit":
 the Bread scale is the unit. The 1-Grain minimum prevents dust games; the
 tier names keep human-readable values at every scale.
 ## Where Bread lives
 Bread is held in the three [Storage Pools](storage-pools.md): the Stash
 (Holder-level), the Vault (Stand-level), and the Root-Pool (treasury). The
 Watchers attest to the state of the pools daily; the Mirror mirrors the
 canonical state to the bearers. See [Watchers & Mirror](watchers-mirror.md)
 for the attestation layer.
@@ -0,0 +1,16 @@
 # Shared concepts
 The Shared section holds the concepts common to every OpenYield audience —
 Nomads and Freeholders alike. These are the covenant-level ideas that make
 OpenYield a public-good mesh rather than a custodial platform.
 - [Six Principles](six-principles.md) — the immutable covenant (REQ-001).
 - [Bread Scale](bread-scale.md) — the unit of value and its 11 tiers (REQ-013).
 - [Storage Pools](storage-pools.md) — the three pools (Stash, Vault, Root-Pool) (REQ-014).
 - [Watchers & Mirror](watchers-mirror.md) — the 9 Watchers, 6-of-9 quorum, the Mirror (REQ-004).
 - [Lexicon](lexicon.md) — why 10 terms are banned, and what to say instead (REQ-012).
 - [Vision](vision.md) — the OpenYield covenant in brief.
 See the [README](../index.md) for build instructions, or the
 [Nomads](../nomads/index.md) and [Freeholders](../freeholders/index.md)
 sections for audience-specific docs.
@@ -0,0 +1,148 @@
 # Lexicon
 OpenYield bans 10 financial terms as standalone words (REQ-012). The firewall
 scans every Go file under `x/` and every Markdown file under `README.md` +
 `docs/`, and fails the build on any standalone occurrence. This page documents
 **why** the terms are banned and **what to say instead** — the replacements,
 not the banned literals.
 ## Why a lexicon
 The words a legacy financial institution uses carry the shapes of that
 institution: custodial positions, jurisdiction-bound units, and
 speculation-language. OpenYield is a jurisdiction-light, public-good mesh for
 real production; using the old words would import the old shapes. The
 lexicon firewall keeps the mesh's language aligned with its covenant. The
 firewall is enforced in code by two sibling Go tests
 (`lexicon_meta_test.go` for `x/**/*.go`;
 `lexicon_meta_docs/lexicon_meta_docs_test.go` for `README.md` +
 `docs/**/*.md`), both using `lexicon.FindBannedTerm` (word-boundary,
 case-insensitive). Word-boundary matching means "OpenYield" is safe — the
 firewall bans standalone words, not substrings.
 ## The 10 banned terms and their safe replacements
 The firewall bans 10 standalone words. This page does not write the banned
 words as literals (the firewall scans this page); it describes them by the
 concept each belongs to, and gives the safe replacement.
 ### 1. The custodial-position word
 A legacy institution holds your value in a custodial position. OpenYield
 does not: a Holder owns their **Stash**, a Stand owns its **Vault**, the mesh
 owns the **Root-Pool**. The Holder's identity is a **Reach**, and the Holder
 themselves is a **Holder** — never the banned custodial-position word.
 - Banned: the word for a custodial position.
 - Safe: **Holder**, **Reach**, **Stash**, **Vault**, **Root-Pool**.
 ### 2. The legacy-institution word
 The legacy financial institution itself is banned as a concept. OpenYield is
 a **mesh**, a **public good**, a **protocol** — not that word.
 - Banned: the word for a legacy financial institution.
 - Safe: **mesh**, **protocol**, **public good**.
 ### 3. The place-value word
 The word for a place to hold value under custody is banned. Use the
 **Stash** (Holder-level), the **Vault** (Stand-level), or the **Root-Pool**
 (treasury).
 - Banned: the word for a place value is held.
 - Safe: **Stash**, **Vault**, **Root-Pool**, **Storage Pools**.
 ### 4. The put-in word
 The verb for putting value into a custodial position is banned. Use **hold**,
 **store**, **move**, or **transfer**.
 - Banned: the verb for placing value under custody.
 - Safe: **hold**, **store**, **move**, **transfer**, **Pass-Act**.
 ### 5. The passive-value word
 The word for value earned passively on a custodial position is banned. For
 bonds, use **coupon**. For the mesh's metric, use **real production** or
 **real return**.
 - Banned: the word for passive value on a custodial position.
 - Safe: **coupon**, **real production**, **real return**.
 ### 6. The standalone metric word
 The standalone word for a return metric is banned (it is the same concept as
 #5 in verb form). Use **real production**, **real return**, or **coupon**
 (for bonds). "OpenYield" is safe — word-boundary matching does not flag the
 banned term inside an identifier.
 - Banned: the standalone return-metric word.
 - Safe: **real production**, **real return**, **coupon**. **OpenYield** is safe.
 ### 7. The medium-of-exchange word
 The word for a national medium of exchange is banned. The mesh's unit is
 **Bread** (see [Bread scale](bread-scale.md)). For a foreign-exchange pair,
 use **Forex** (allowed) with **base-asset** / **quote-asset** labels, or
 **Bread / Asset**.
 - Banned: the word for a national medium of exchange.
 - Safe: **Bread**, **asset**, **Forex**, **base-asset**, **quote-asset**.
 ### 8. The first national-unit word
 The word for the first major national unit is banned. Use **Bread** or
 opaque chain names (e.g., "Polygon", "OY-Chain").
 - Banned: the first national-unit word.
 - Safe: **Bread**, **asset**, chain names.
 ### 9. The second national-unit word
 The word for the second major national unit is banned (the firewall bans it
 as a standalone word; "european" is safe by word-boundary). Use **Bread** or
 opaque chain names.
 - Banned: the second national-unit word.
 - Safe: **Bread**, **asset**, chain names. **European** is safe (word-boundary).
 ### 10. The set-aside word
 The word for value set aside under custody is banned. Use **Stash**,
 **Vault**, or **Root-Pool**.
 - Banned: the word for value set aside.
 - Safe: **Stash**, **Vault**, **Root-Pool**.
 ### 11. The holder-of-value word
 The word for the person who holds value under custody at a legacy
 institution is banned. Use **Holder**, **Freeholder**, or **Nomad**.
 - Banned: the word for a custodial-position holder.
 - Safe: **Holder**, **Freeholder**, **Nomad**, **Reach**.
 > **Note**: the firewall bans 10 standalone words; this page lists 11
 > replacements because two of the banned words (the passive-value word and
 > the standalone metric word) share a concept and get the same replacement
 > family (**coupon** / **real production** / **real return**).
 ## How the firewall works
 The firewall uses `lexicon.FindBannedTerm` — a word-boundary, case-insensitive
 regex match — so:
 - "OpenYield" is **safe**: the standalone banned term inside an identifier
  does not match (word-boundary).
 - "european" is **safe**: the standalone national-unit word inside a larger
  word does not match.
 - The standalone banned word in prose **is** matched and fails the build.
 The firewall's own source (`lexicon/lexicon.go`) assembles the banned terms
 at runtime from two-character fragments, so the firewall's own code does not
 contain any banned term as a literal substring. The two sibling meta-tests
 (`lexicon_meta_test.go` and `lexicon_meta_docs/lexicon_meta_docs_test.go`)
 each include a self-test table that verifies detection of all 10 banned
 terms from the single source `lexicon.BannedTerms()` (G-014 drift
 prevention).
@@ -0,0 +1,54 @@
 # Six Principles
 The Six Principles are the immutable covenant of OpenYield (REQ-001). They
 are **Mission-locked**: no Council can amend them, and the fee covenant is
 locked alongside them. The mesh exists to hold real production, not
 speculation; everything else follows from that.
 ## 1. Real value
 The mesh holds **real production**. The Bread unit is the unit of real value
 held in the Storage Pools; the bond market caps coupons so the mesh cannot
 become a speculation engine. "Real return" is the metric, not a nominal rate.
 ## 2. Sustainability
 Fees are floored and capped. The fee covenant fixes a ceiling and a floor
 (see the Fee Covenant module), and the 1-Grain internal minimum prevents dust
 games. The protocol cannot drain its users, and it cannot starve its
 Watchers.
 ## 3. Mission-lock
 The Six Principles and the fee covenant are immutable. No Council — Mesh,
 Guild, or Stand — can amend them. Mission Lock is a `const` in the council
 module, and an invariant test asserts it can never be set to amendable. The
 coupon cap on bonds is a mission-locked ceiling, not a parameter a Council
 can tune.
 ## 4. Openness
 Anyone may join. The mesh is a public good. A Holder needs only a Reach (an
 identity) and a Stash (a storage pool) to begin; there is no gatekeeper and
 no custodian.
 ## 5. Ownership
 Holders own their Stash and their Reach. Custody is theirs: the Stash is the
 Holder-level storage pool, the Vault is the Stand-level pool, and the
 Root-Pool is the treasury. The protocol does not custody user value; it
 holds the canonical state that records who owns what.
 ## 6. Self-service
 A Holder can act without a custodian. The Window primitive lets a Holder
 delegate a scope-bounded, time-limited, revocable capability to a partner or
 a service; the bearers (OY-LR, OY-BLE, OY-WiFi-Direct, OY-SAT, OY-QR) let a
 Holder reach the mesh without a phone plan or a custodial on-ramp. The mesh
 is jurisdiction-light by design.
 ---
 See the [Vision](vision.md) for the covenant in brief, or the
 [Lexicon](lexicon.md) for why the docs say "real production" and "Holder"
 rather than the words a legacy financial institution would use.
@@ -0,0 +1,48 @@
 # Storage Pools
 OpenYield has three Storage Pools (REQ-014). Each is a layer of custody
 responsibility, and none of them is a custodial position — the protocol holds
 the canonical state that records who owns what; the Holder, the Stand, and
 the mesh treasury each hold their own pool.
 | Pool | Level | Held by | Purpose |
 |---|---|---|---|
 | **Stash** | Holder | a single Holder | the personal storage pool; the unit of self-service |
 | **Vault** | Stand | a Stand (a governed group) | the Stand-level pool; the unit of shared ownership |
 | **Root-Pool** | Mesh | the mesh treasury | the canonical treasury; the unit of the public good |
 ## The Stash
 The Stash is the Holder-level storage pool. A Holder needs only a Reach (an
 identity) and a Stash to begin. The Stash is the unit of self-service: the
 Holder owns it, controls it, and can delegate a scoped, time-limited,
 revocable Window to a partner or a service without giving up custody. See
 [Watchers & Mirror](watchers-mirror.md) for the attestation layer that
 records Stash state.
 ## The Vault
 The Vault is the Stand-level storage pool. A Stand is a governed group
 (one of the nine Stand types: Household, Crew, Entity, Co-op, Circle,
 Trust, Foundation, Confederation, Shadow) that holds a Vault in common. The
 Stand's decision policy (threshold or weighted, mirroring the Cosmos SDK
 `x/group` shape) governs how the Vault is used. See the Freeholders section
 for Stands & Guilds.
 ## The Root-Pool
 The Root-Pool is the mesh treasury. It holds the canonical state of the
 Bread unit, the Watcher bonds, and the Root Basket. The Root-Pool is the
 unit of the public good: the Watchers attest to its state daily, and the
 Mirror mirrors it to the bearers so a Holder can verify the mesh's real
 return without trusting a single custodian.
 ## Custody, not custody
 The three pools are storage layers, not custodial positions. The protocol
 does not custody user value; it holds the canonical state that records who
 owns what. A Holder's Stash is theirs; a Stand's Vault is the Stand's; the
 Root-Pool is the mesh's. The Window primitive lets a Holder delegate a
 capability without delegating custody. See the [Lexicon](lexicon.md) for
 why the docs say "Stash", "Vault", and "Root-Pool" rather than the words a
 legacy financial institution would use.
@@ -0,0 +1,64 @@
 # Vision
 OpenYield is a jurisdiction-light, public-good mesh for **real production**.
 The vision is a covenant, not a product: the mesh holds real value, the Six
 Principles are immutable, and the protocol cannot become a custodial
 platform. This page is the brief overview; the full vision source lives in
 `.ciagent/oy/PROJECT.md`.
 ## The covenant
 OpenYield exists to hold **real production** — the real return of real work,
 held in the Bread unit, in the three Storage Pools, attested by the Watchers,
 mirrored by the Mirror. The covenant is anti-greed by construction:
 - **Mission Lock** fixes the Six Principles and the fee covenant. No Council
  — Mesh, Guild, or Stand — can amend them. The coupon cap on bonds is a
  mission-locked ceiling, not a parameter.
 - **Jurisdiction-light** — the bearers (OY-LR, OY-BLE, OY-WiFi-Direct, OY-SAT,
  OY-QR) let a Holder reach the mesh without a phone plan or a custodial
  on-ramp. A Holder needs only a Reach and a Stash to begin.
 - **Public good** — the mesh is open to all. The Watchers attest daily; the
  Mirror mirrors the state; anyone can verify the mesh's real return without
  trusting a single custodian.
 ## The layers
 1. **OY Chain** (Layer 1) — the canonical state: the Bread unit, the
   Storage Pools, Standing, Watcher attestations, the Pact / Council /
   Partner surface.
 2. **Satellites** (Layer 2) — wrapped Bread propagates to satellite chains
   (Polygon active; Base, Arbitrum, Optimism, Solana as enum placeholders)
   via IBC.
 3. **Bearers** — the surveillance-resistant transport layer: OY-LR (LoRa,
   long-range), OY-BLE (Bluetooth), OY-WiFi-Direct, OY-SAT (satellite),
   OY-QR (paper / QR code). The Mirror mirrors canonical state to them.
 4. **Exits** — the Layer 3 exit layer: Holder-initiated DEX swaps and
   off-mesh service exits, with bridge routes for cross-chain exits.
 ## The actors
 - **Holders** (Nomads) — the everyday participants, each with a Reach and a
  Stash.
 - **Freeholders** — the active participants who run Stands, Guilds, and
  Councils.
 - **Partners** — the four-tier spectrum (Op, MasterOp, Pier, Anchor) that
  processes Pass-Acts and provides credentials and institutional backing.
 - **Watchers** — the 9 attesters with 6-of-9 quorum and 100,000 Bread bonds.
 ## The units
 - **Bread** — the unit of real value (see [Bread scale](bread-scale.md)).
 - **Standing** — the reputation layer (the four signals, Bayesian Standing).
 - **Voice** — the governance input (multi-source: Stash, Standing, Vouch,
  Freeholder, Guild).
 - **Coupon** — the bond-market term (capped at 8% / floored at 0%, mission-locked).
 ## Where to go next
 - [Six Principles](six-principles.md) — the immutable covenant.
 - [Storage Pools](storage-pools.md) — the three pools.
 - [Watchers & Mirror](watchers-mirror.md) — the attestation layer.
 - [Lexicon](lexicon.md) — why the docs say "real production" and "Holder".
 - [README](../../README.md) — build & test instructions.
 - `.ciagent/oy/PROJECT.md` — the full vision source.
@@ -0,0 +1,42 @@
 # Watchers & Mirror
 OpenYield is attested by **9 Watchers** with a **6-of-9 quorum** (REQ-004).
 The Watchers make daily attestations to the canonical state, and each posts
 a 100,000 Bread bond. The **Mirror** mirrors the canonical state to the
 bearers so a Holder can verify the mesh's state without trusting a single
 Watcher.
 ## The 9 Watchers
 The Watchers are the attestation layer of the mesh. There are exactly 9, and
 the quorum is 6-of-9: any 6 Watchers can attest to a state transition, but no
 5 can. Each Watcher posts a 100,000 Bread bond, which is at risk if the
 Watcher attests to a false state. The 9/6 split is a mission-locked
 parameter — no Council can lower the quorum or the bond.
 ## Daily attestations
 The Watchers attest to the state of the three [Storage Pools](storage-pools.md)
 daily: the Stash totals, the Vault totals, and the Root-Pool. The
 attestation is a signed statement that the canonical state recorded by OY
 Chain matches the state the Watcher observed. A Holder who wants to verify
 the mesh's real return can read the attestations and check that the
 Watchers agree.
 ## The Mirror
 The Mirror mirrors the canonical state to the bearers (OY-LR, OY-BLE,
 OY-WiFi-Direct, OY-SAT, OY-QR). A Holder on a surveillance-resistant bearer
 can read the mirrored state without an internet connection to OY Chain; the
 Mirror is the read-side of the bearer layer. The Mirror is read-only: it
 mirrors state, it does not author it. Authoritative state lives on OY Chain
 and is attested by the Watchers.
 ## Why 6-of-9
 The 9/6 split is a balance: 9 is large enough that no single adversary can
 easily capture a quorum, and 6 is large enough that no small cabal can
 attest to a false state. The 100,000 Bread bond per Watcher makes
 capturing a quorum expensive. The split is locked by Mission Lock — no
 Council can change it. See [Six Principles](six-principles.md) for the
 mission-lock covenant.
@@ -0,0 +1,316 @@
 // Package lexicon_meta_docs holds the docs lexicon firewall (REQ-028, D-043).
 //
 // It is a NEW sibling meta-test created in v0.3 P1 Wave 1 that MIRRORS the v0.2
 // project-wide firewall (lexicon_meta_test.go, package lexicon_meta) but scans
 // the docs surface (README.md + docs/**/*.md) instead of x/**/*.go. It uses
 // the SAME lexicon.FindBannedTerm (word-boundary, case-insensitive) — NO
 // detection reimplementation — so the two firewalls share a single source of
 // truth for the 10 banned terms (bank, deposit, interest, yield, currency,
 // dollar, euro, account, savings, depositor).
 //
 // Placement: this file lives in lexicon_meta_docs/ (a subdirectory of the
 // repo root) because Go does not permit two distinct packages in the same
 // directory; the v0.2 firewall is package lexicon_meta at the repo root.
 // The invocation `go test ./lexicon_meta_docs/...` (PLANS P1-03-01) resolves
 // to this package. Run via `go test ./...` from the repo root as well.
 //
 // G-013 walk-coverage: TestLexiconMetaDocsWalkCoverage injects a synthetic
 // banned-term .md into a temp docs/ subtree and asserts the walk FINDS it.
 // This closes the "silently scans nothing and reports green" failure mode
 // that the G-009 self-test table (detection) alone does not cover.
 //
 // G-014 self-test drift: the self-test table and banned-term count assertion
 // reuse lexicon.BannedTerms() (the single source). A cross-reference comment
 // keeps this file's table in lockstep with lexicon_meta_test.go's table; if
 // a banned term is added, both firewalls update from one place.
 package lexicon_meta_docs
 import (
 	"os"
 	"path/filepath"
 	"runtime"
 	"strings"
 	"testing"
 	"github.com/oy/openyield/lexicon"
 )
 // repoRoot returns the absolute path to the repo root by walking up from
 // this test file (the test lives at <repoRoot>/lexicon_meta_docs/).
 func repoRoot(t *testing.T) string {
 	t.Helper()
 	_, file, _, ok := runtime.Caller(0)
 	if !ok {
 		t.Fatal("runtime.Caller failed")
 	}
 	// file = .../oy/lexicon_meta_docs/lexicon_meta_docs_test.go
 	// repo root = filepath.Dir(filepath.Dir(file))
 	return filepath.Dir(filepath.Dir(file))
 }
 // thisFile returns the absolute path of this meta-test file (to exclude it
 // from its own scan — it references banned terms via the lexicon package,
 // whose source assembles terms from fragments, so no banned-term literal
 // appears in the firewall's own code).
 func thisFile(t *testing.T) string {
 	t.Helper()
 	_, file, _, ok := runtime.Caller(0)
 	if !ok {
 		t.Fatal("runtime.Caller failed")
 	}
 	return file
 }
 // TestLexiconMetaDocsNoBannedTermsInDocs is the docs firewall (D-043). It
 // walks README.md (repo root) + every *.md under docs/ (recursive), reads each
 // file's source, and asserts no banned term is present (word-boundary,
 // case-insensitive). Excludes .ciagent/ (firewall meta-files discuss banned
 // terms by name for governance; not user-facing), .git/ (VCS), and this test
 // file itself (self-exclusion via runtime.Caller(0)).
 //
 // Passes at P1 Wave 1 with zero docs (a walk that scans nothing reports green
 // on zero hits — closed by TestLexiconMetaDocsWalkCoverage below). With the
 // Wave 2 docs present (README + index + 6 shared pages), all are lexicon-clean
 // by construction.
 func TestLexiconMetaDocsNoBannedTermsInDocs(t *testing.T) {
 	root := repoRoot(t)
 	this := thisFile(t)
 	hits := []string{}
 	err := filepath.Walk(root, func(path string, info os.FileInfo, err error) error {
 		if err != nil {
 			return err
 		}
 		if info.IsDir() {
 			base := filepath.Base(path)
 			if base == ".ciagent" || base == ".git" {
 				return filepath.SkipDir
 			}
 			return nil
 		}
 		// Self-exclusion: skip this meta-test file.
 		if path == this {
 			return nil
 		}
 		// Only scan .md files.
 		if !strings.HasSuffix(path, ".md") {
 			return nil
 		}
 		// Only scan README.md (repo root) + docs/**/*.md.
 		rel, rerr := filepath.Rel(root, path)
 		if rerr != nil {
 			return rerr
 		}
 		if rel != "README.md" && !strings.HasPrefix(rel, "docs"+string(filepath.Separator)) && rel != "docs" {
 			return nil
 		}
 		bz, rerr := os.ReadFile(path)
 		if rerr != nil {
 			return rerr
 		}
 		if found, ok := lexicon.FindBannedTerm(string(bz)); ok {
 			hits = append(hits, rel+" contains banned term "+found)
 		}
 		return nil
 	})
 	if err != nil {
 		t.Fatalf("walk: %v", err)
 	}
 	if len(hits) > 0 {
 		t.Errorf("REQ-028 docs lexicon firewall violations:\n  %s",
 			strings.Join(hits, "\n  "))
 	}
 }
 // TestLexiconMetaDocsSelfTestTable (G-009 for docs) is the firewall's own
 // detection-coverage guard. Each synthetic string embeds exactly one banned
 // term in a plausible sentence context and is asserted to trigger detection,
 // so the firewall's detection logic is durably verified — if detection ever
 // breaks, this test fails before the firewall silently passes a real
 // violation in a docs page.
 //
 // G-014 self-test drift: this table is the docs mirror of the
 // TestLexiconMetaSelfTestTable in lexicon_meta_test.go (package lexicon_meta).
 // Both reuse lexicon.BannedTerms() as the single source for the 10 terms, so
 // a future addition updates both firewalls from one place. The synthetic
 // strings are assembled from lexicon.BannedTerms() fragments so this file
 // does not contain any banned term as a literal substring (it would otherwise
 // trip its own scan; the meta-test file is also excluded from its own scan,
 // but the self-test keeps the source clean for readability/searchability).
 //
 // CROSS-REFERENCE: keep this table aligned with
 //
 //	lexicon_meta_test.go :: TestLexiconMetaSelfTestTable
 //
 // Any change to the synthetic-string construction must be mirrored in both
 // files (or, preferably, add a shared helper in the lexicon package — see
 // G-014 minimum-viable: cross-reference comment + shared BannedTerms()).
 func TestLexiconMetaDocsSelfTestTable(t *testing.T) {
 	terms := lexicon.BannedTerms()
 	// The spec lists 10 banned terms (plan docs say "9", counting dollar/euro
 	// as a pair): bank, deposit, interest, yield, currency, dollar, euro,
 	// account, savings, depositor.
 	if len(terms) != 10 {
 		t.Fatalf("BannedTerms() len = %d, want 10", len(terms))
 	}
 	// Each synthetic string embeds exactly one banned term in a plausible
 	// sentence context. Each must be detected.
 	synthetic := []string{
 		"open a " + terms[0] + " here",      // bank
 		"make a " + terms[1] + " now",       // deposit
 		"compounding " + terms[2] + " rate", // interest
 		"the " + terms[3] + " is 5pct",      // yield
 		"foreign " + terms[4] + " pair",     // currency
 		"price in " + terms[5],              // dollar
 		"price in " + terms[6],              // euro
 		"freeze the " + terms[7],            // account
 		"move to " + terms[8] + " now",      // savings
 		"the " + terms[9] + " lost money",   // depositor
 	}
 	if len(synthetic) != len(terms) {
 		t.Fatalf("synthetic table len = %d, want %d", len(synthetic), len(terms))
 	}
 	for i, s := range synthetic {
 		found, ok := lexicon.FindBannedTerm(s)
 		if !ok {
 			t.Errorf("G-009 docs self-test [%d]: synthetic string did not trigger detection: %q", i, s)
 			continue
 		}
 		if found != terms[i] {
 			t.Errorf("G-009 docs self-test [%d]: detected %q, want %q (in %q)", i, found, terms[i], s)
 		}
 	}
 }
 // TestLexiconMetaDocsBannedTermsCount asserts exactly 10 banned terms are
 // configured (locked-const for the firewall's scope; spec lists 10, plan docs
 // say "9" counting dollar/euro as a pair). Derived from lexicon.BannedTerms()
 // — the single source — so a count change breaks both this firewall and the
 // v0.2 x/*.go firewall (G-014 drift prevention).
 func TestLexiconMetaDocsBannedTermsCount(t *testing.T) {
 	terms := lexicon.BannedTerms()
 	if len(terms) != 10 {
 		t.Errorf("BannedTerms() len = %d, want 10 (REQ-012/REQ-028)", len(terms))
 	}
 	seen := map[string]bool{}
 	for _, tr := range terms {
 		if seen[tr] {
 			t.Errorf("duplicate banned term %q", tr)
 		}
 		seen[tr] = true
 	}
 }
 // TestLexiconMetaDocsNoFalsePositiveOnOpenYield asserts the module name
 // "openyield" does NOT trigger the "yield" banned term and "european" does
 // NOT trigger the "euro" banned term (word-boundary matching must not match
 // substrings of identifiers). This is the regression firewall for the
 // word-boundary detection design — mirrors the v0.2
 // TestLexiconMetaNoFalsePositiveOnOpenYield.
 func TestLexiconMetaDocsNoFalsePositiveOnOpenYield(t *testing.T) {
 	cases := []string{
 		"github.com/oy/openyield/x/window/types",
 		"package openyield",
 		"openyield is the module",
 		"european resident",
 		"# OpenYield docs",
 		"the OpenYield mesh",
 	}
 	for _, s := range cases {
 		if _, ok := lexicon.FindBannedTerm(s); ok {
 			t.Errorf("false positive: %q triggered a banned term (word-boundary must avoid this)", s)
 		}
 	}
 }
 // TestLexiconMetaDocsWalkCoverage (G-013) is the walk-coverage firewall. The
 // G-009 self-test table (above) verifies DETECTION (FindBannedTerm on
 // synthetic strings) but NOT the WALK (which files are scanned). A walk bug
 // — e.g. wrong path prefix, missing docs/ recursion, a typo in the .md
 // suffix check — would silently scan nothing and report green on zero
 // files. This test closes that gap by injecting a synthetic banned-term .md
 // into a fixture dir under the real docs/ path the walk scans and asserting
 // the walk FINDS it.
 //
 // The fixture is created under docs/.lexicon_fixture/ (a real docs/ subtree
 // the walk reaches) and removed via defer so it never leaks into the repo.
 // If the walk logic misses the fixture, this test fails loudly instead of
 // letting a broken walk pass the firewall green on zero files scanned.
 func TestLexiconMetaDocsWalkCoverage(t *testing.T) {
 	root := repoRoot(t)
 	this := thisFile(t)
 	// Build a synthetic banned term from fragments so THIS file does not
 	// contain a banned-term literal (it is excluded from its own scan, but
 	// the synthetic stays clean for readability/searchability).
 	terms := lexicon.BannedTerms()
 	if len(terms) == 0 {
 		t.Fatal("BannedTerms() returned no terms — cannot run walk-coverage")
 	}
 	// Use the first banned term ("bank") assembled from two halves.
 	syntheticTerm := terms[0][:2] + terms[0][2:] // reassemble (no literal in source)
 	badContent := []byte("# fixture\nthis file contains a banned term: " + syntheticTerm + "\n")
 	fixtureDir := filepath.Join(root, "docs", ".lexicon_fixture")
 	fixtureFile := filepath.Join(fixtureDir, "bad_fixture.md")
 	if err := os.MkdirAll(fixtureDir, 0o755); err != nil {
 		t.Fatalf("mkdir fixture: %v", err)
 	}
 	defer os.RemoveAll(fixtureDir)
 	if err := os.WriteFile(fixtureFile, badContent, 0o644); err != nil {
 		t.Fatalf("write fixture: %v", err)
 	}
 	// Run the SAME walk logic as TestLexiconMetaDocsNoBannedTermsInDocs and
 	// assert it FINDS the fixture's banned term. A walk that returns zero
 	// hits here proves the walk logic is broken (the fixture is a known-bad
 	// file inside docs/ that MUST be detected).
 	hits := []string{}
 	err := filepath.Walk(root, func(path string, info os.FileInfo, err error) error {
 		if err != nil {
 			return err
 		}
 		if info.IsDir() {
 			base := filepath.Base(path)
 			if base == ".ciagent" || base == ".git" {
 				return filepath.SkipDir
 			}
 			return nil
 		}
 		if path == this {
 			return nil
 		}
 		if !strings.HasSuffix(path, ".md") {
 			return nil
 		}
 		rel, rerr := filepath.Rel(root, path)
 		if rerr != nil {
 			return rerr
 		}
 		if rel != "README.md" && !strings.HasPrefix(rel, "docs"+string(filepath.Separator)) {
 			return nil
 		}
 		bz, rerr := os.ReadFile(path)
 		if rerr != nil {
 			return rerr
 		}
 		if found, ok := lexicon.FindBannedTerm(string(bz)); ok {
 			hits = append(hits, rel+" contains banned term "+found)
 		}
 		return nil
 	})
 	if err != nil {
 		t.Fatalf("walk: %v", err)
 	}
 	// Assert the fixture was found. The rel path uses OS-specific separator;
 	// match on the suffix so the test is portable.
 	foundFixture := false
 	for _, h := range hits {
 		if strings.Contains(h, "bad_fixture.md") && strings.Contains(h, syntheticTerm) {
 			foundFixture = true
 			break
 		}
 	}
 	if !foundFixture {
 		t.Errorf("G-013 walk-coverage: the walk did NOT find the synthetic banned-term fixture at %s — the docs firewall walk logic is broken (it would silently scan nothing and report green). hits=%v", fixtureFile, hits)
 	}
 }
@@ -0,0 +1,63 @@
 # OpenYield docs site (MkDocs Material, D-042).
 #
 # Build-only Python dep (mkdocs + mkdocs-material); NOT a Go dep (G-006 —
 # go.mod stays zero-require). Invoke locally with `mkdocs serve` or
 # `mkdocs build` (see README). No publishing CI in v0.3 (D-046 — publishing
 # to GitHub/Gitea Pages deferred to v0.4).
 #
 # Nav completeness (G-011): the nav lists ALL 26 pages that will exist by end
 # of P3. P1 creates the shared/ pages + index (8 files); P2 adds nomads/
 # (8 files); P3 adds freeholders/ (8 files) + reference/ (2 files). Only the
 # files that exist at P1 ship today; the nav references the not-yet-created
 # P2/P3 pages by path so the structure is complete and P2/P3 just add files.
 # mkdocs.yml is a config file, NOT validated by Go tests; the docs firewall
 # (lexicon_meta_docs_test.go) validates .md content, not nav.
 site_name: OpenYield
 site_description: OpenYield — a jurisdiction-light, public-good mesh for real production, organized around Holders, Stands, and the Six Principles.
 theme:
  name: material
  features:
    - navigation.sections
    - navigation.expand
    - toc.integrate
 markdown_extensions:
  - admonition
  - toc:
      permalink: true
  - codehilite
  - pymdownx.superfences
 nav:
  - Home: index.md
  - Nomads:
      - Overview: nomads/index.md
      - Reach: nomads/reach.md
      - Stash: nomads/stash.md
      - Bearers: nomads/bearers.md
      - Maps-Pay: nomads/maps-pay.md
      - Pacts: nomads/pacts.md
      - Standing: nomads/standing.md
      - Window: nomads/window.md
  - Freeholders:
      - Overview: freeholders/index.md
      - Signals: freeholders/signals.md
      - Standing: freeholders/standing.md
      - Stands & Guilds: freeholders/stands-guilds.md
      - Councils & Voice: freeholders/councils-voice.md
      - Bonds: freeholders/bonds.md
      - Partner Spectrum: freeholders/partner-spectrum.md
      - Anchor Preview: freeholders/anchor-preview.md
  - Shared:
      - Overview: shared/index.md
      - Six Principles: shared/six-principles.md
      - Bread Scale: shared/bread-scale.md
      - Storage Pools: shared/storage-pools.md
      - Watchers & Mirror: shared/watchers-mirror.md
      - Lexicon: shared/lexicon.md
      - Vision: shared/vision.md
  - Reference:
      - Architecture: reference/architecture.md
      - Components: reference/components.md
Author	SHA1	Message	Date
cloudinit-bot	2ef3f2e39f	docs(P03): complete freeholders docs + reference phase — REQ-027 complete P3 complete. 8 docs/freeholders/ pages (signals, standing, stands-guilds, councils-voice, bonds, partner-spectrum, anchor-preview, index) + 2 docs/reference/ pages (architecture, components). Docs firewall green across all 26 docs pages. Full docs deliverable (README + mkdocs.yml + 26-page site) complete — REQ-027 complete. ---ci--- project: oy phase: 3 milestone: v0.3 status: complete tag_base: v0.2.x phase_role: execution requirements: covered: [REQ-027] partial: [] ---/ci---	2026-08-17 22:17:07 +00:00
cloudinit-bot	e493216b8a	checkpoint(P02): complete -> advance to P3 freeholders docs	2026-08-17 22:15:03 +00:00
cloudinit-bot	d09c6132b1	docs(P02): complete nomads docs phase P2 complete. 8 docs/nomads/ pages: index, reach, stash, bearers, maps-pay, pacts, standing, window. Docs firewall green (scans new nomads pages), no regression. All pages cross-reference docs/shared/. ---ci--- project: oy phase: 2 milestone: v0.3 status: complete tag_base: v0.2.x phase_role: execution requirements: covered: [] partial: [REQ-027] ---/ci---	2026-08-17 22:14:53 +00:00
cloudinit-bot	fa4ee47bde	checkpoint(P01): complete -> advance to P2 nomads docs	2026-08-17 22:13:06 +00:00
cloudinit-bot	a780884379	docs(P01): complete docs foundation + firewall extension phase P1 complete. Docs lexicon firewall (lexicon_meta_docs_test.go, 5 tests incl. G-013 walk-coverage + G-014 shared self-test). MkDocs Material scaffold with 26-page nav (G-011). README.md + docs/index.md + 7 docs/shared/ pages. Both firewalls green, go test ./... 22 packages green, no regression. ---ci--- project: oy phase: 1 milestone: v0.3 status: complete tag_base: v0.2.x phase_role: execution requirements: covered: [REQ-028] partial: [REQ-027] ---/ci---	2026-08-17 22:12:53 +00:00
cloudinit-bot	cb394cb516	checkpoint(P00): advance to execution phases — v0.3 P1-P6	2026-08-17 22:07:22 +00:00
cloudinit-bot	23de3c544b	docs(P00): complete pre-execution phase — v0.3 Bearers & Documentation Phase 0 complete: SPECIFY -> CLARIFY -> RESEARCH -> IDEATE -> PLAN -> GRILL. v0.3 milestone (feature type, tags v0.2.x) established. Bundles Bearers skeleton (D-020 pattern) + docs site for nomads/freeholders + REQ-012 firewall extension to docs. 13 clarifications (D-034..D-046), 8 ideation ideas ratified (IDEATE-01..08 -> REQ-010/REQ-022..REQ-028), 50-task plan across P1-P6, 4 grill binding decisions (G-011..G-014). ---ci--- project: oy phase: 0 milestone: v0.3 status: complete tag_base: v0.2.x milestone_type: feature phase_role: pre_execution requirements: covered: [] partial: [] ---/ci---	2026-08-17 22:06:50 +00:00