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---

.ciagent/CHECKPOINT.json

@@ -1,14 +1,12 @@
 {
-  "phase": 0,
-  "stage": "complete",
+  "phase": 1,
+  "stage": "verify",
   "milestone": "v0.3",
   "milestone_type": "feature",
   "tag_base": "v0.2.x",
-  "phase_role": "pre_execution",
+  "phase_role": "execution",
   "project": "oy",
   "attempts": 0,
-  "updated_at": "2026-08-17T23:40:00Z",
-  "milestone_complete": false,
-  "phase_release_tag": "v0.2.0",
-  "release_id": 733
+  "updated_at": "2026-08-17T23:50:00Z",
+  "milestone_complete": false
 }

README.md

@@ -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.

docs/index.md

@@ -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.

docs/shared/bread-scale.md

@@ -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.

docs/shared/index.md

@@ -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.

docs/shared/lexicon.md

@@ -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).

docs/shared/six-principles.md

@@ -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.

docs/shared/storage-pools.md

@@ -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.

docs/shared/vision.md

@@ -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.

docs/shared/watchers-mirror.md

@@ -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.

lexicon_meta_docs/lexicon_meta_docs_test.go

@@ -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)
+	}
+}

mkdocs.yml

@@ -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