feat(docs): builder docs rebuild — mechanics and spine (Phases 1-2)

.claude/context/contracts.md

@@ -433,5 +433,5 @@ Read these docs pages when you need deployment context or protocol details:
 
 - Deployment runbook: `packages/contracts/deployments/README.md`
 - System architecture and contract relationships: `docs/docs/builders/architecture.mdx`
-- Cross-protocol entity matrix: `docs/docs/builders/integrations/entity-matrix.mdx`
+- Cross-protocol entity matrix: `docs/docs/builders/architecture/entity-matrix.mdx`
 - EAS integration reference: `docs/docs/builders/integrations/eas.mdx`

.claude/context/ontology.md

@@ -83,7 +83,7 @@ Never merge or cross-map these vocabularies because they share only an identifie
 `bun run ontology:generate` owns all five outputs:
 
 - `docs/docs/reference/ontology.generated.mdx`
-- `docs/docs/builders/integrations/entity-matrix.mdx`
+- `docs/docs/builders/architecture/entity-matrix.mdx`
 - `docs/docs/reference/glossary.generated.mdx`
 - `docs/docs/community/green-goods-claims.generated.mdx`
 - `packages/shared/src/ontology/agent-manifest.generated.json`

.claude/context/product.md

@@ -37,7 +37,7 @@ Green Goods is the verified impact operations layer for community-led regenerati
 - Steward copy: may reference on-chain verification as a trust mechanism, but not Solidity internals
 - Evaluator copy: may use research/assessment terminology freely
 - Funder copy: may reference attestation integrity; never use "guaranteed returns"
-- For full persona profiles with behavioral scenarios: `docs/docs/reference/design-research.md#user-personas`
+- For full persona profiles with behavioral scenarios: `docs/docs/builders/architecture/design.mdx`
 - For vocabulary constraints (Use/Avoid lists): see Messaging Constraints below
 
 ## UX Quality Bars
@@ -279,4 +279,4 @@ These are already part of the core product baseline and should be treated as liv
 - Organizational mission and values → `docs/docs/community/why-we-build.mdx`
 - Impact model (CIDS) and action domains → `docs/docs/community/how-it-works.mdx`
 - Public capability boundaries → `docs/docs/community/green-goods-claims.generated.mdx`
-- Real communities and localization → `docs/docs/reference/design-research.md`
+- Real communities and localization → `docs/docs/builders/architecture/design.mdx`

.claude/context/shared.md

@@ -454,5 +454,5 @@ Read these docs pages when you need domain context beyond code patterns:
 
 - System architecture with Mermaid diagrams: `docs/docs/builders/architecture.mdx`
 - Domain authority: `packages/shared/src/ontology/green-goods-ontology.json`; public projection: `docs/docs/reference/glossary.generated.mdx`
-- Impact model & Eight Forms of Capital: `docs/docs/reference/design-research.md`
-- Cross-protocol entity matrix (draft/vocab aid): `docs/docs/builders/integrations/entity-matrix.mdx`
+- Impact model & Eight Forms of Capital: `docs/docs/builders/architecture/design.mdx`
+- Cross-protocol entity matrix (draft/vocab aid): `docs/docs/builders/architecture/entity-matrix.mdx`

.claude/context/testing.md

@@ -36,7 +36,7 @@ Alias → `packages/shared/src/__tests__/test-utils/`. Import test helpers from
 
 Enforced global thresholds live in each `vitest.config.ts` (branches/functions/lines/statements): **shared** 52/59/62/61 · **client** 56/62/64/63 · **admin** 47/44/53/51. Pull request Test jobs run plain `bun run test`; `.github/workflows/coverage-nightly.yml` enforces these floors nightly and after every push to `main`. Local coverage commands still generate `coverage/index.html`; CI omits HTML.
 
-The first ratchet review is 2026-09-22. Once coverage supports it, raise every configured metric by two percentage points and update the matching arrays in `scripts/quality/workflow-performance-parity.test.mjs` in the same change. Policy targets remain critical paths ≥80% and auth/crypto 100%. Contracts use Foundry, not Vitest — see `.claude/context/contracts.md` and `docs/docs/builders/testing/forge.mdx`.
+The first ratchet review is 2026-09-22. Once coverage supports it, raise every configured metric by two percentage points and update the matching arrays in `scripts/quality/workflow-performance-parity.test.mjs` in the same change. Policy targets remain critical paths ≥80% and auth/crypto 100%. Contracts use Foundry, not Vitest — see `.claude/context/contracts.md` and `docs/docs/builders/testing/index.mdx`.
 
 ## Critical paths (deepest coverage in `packages/shared/src/`)
 
@@ -63,7 +63,7 @@ shrink when a violation is fixed, while every new or stale entry fails the check
 - Mutation hooks: assert the error path at both hook level (`isError` + handler/`logger.error` called) and component level (error toast surfaced). Errors are never swallowed.
 - Hook cleanup: verify timers cleared, listeners removed, `isMounted` guards on unmount — i.e. `.claude/rules/react-patterns.md` Rules 1-3.
 - Offline: `fake-indexeddb/auto` + `simulateNetworkConditions` / `navigator.onLine` spy; assert job-queue jobs transition pending → completed.
-- E2E (Playwright): critical journeys only, client PWA + admin with platform-specific auth (passkey / wallet-injection / mock-auth). Scope, helpers, runner: `tests/README.md`. Config + fixtures: `docs/docs/builders/testing/playwright.mdx`.
+- E2E (Playwright): critical journeys only, client PWA + admin with platform-specific auth (passkey / wallet-injection / mock-auth). Scope, helpers, runner: `tests/README.md`. Config + fixtures: `docs/docs/builders/testing/index.mdx`.
 
 ## Risk-triggered state and invariant matrix
 

.claude/launch.json

@@ -38,6 +38,12 @@
         "packages/shared/storybook-static"
       ],
       "port": 4620
+    },
+    {
+      "name": "docs",
+      "runtimeExecutable": "bun",
+      "runtimeArgs": ["run", "--cwd", "docs", "serve", "--port", "3013", "--no-open"],
+      "port": 3013
     }
   ]
 }

.claude/skills/audit/README.md

@@ -0,0 +1,8 @@
+# audit
+
+The repo-health check. Audit sweeps Green Goods for drift and decay: dead code, dependency health, stale guidance and plans, invariant drift, and concrete broken or brittle spots. It reads everything and changes nothing; accepted findings route to a fix pass, a cleanup run, or Linear.
+
+**How to invoke:** Type `/audit` (or `/audit drift` for the quick drift classifier).
+
+[`SKILL.md`](./SKILL.md) in this folder is the executable contract; this README is the human
+summary the [Skills Catalog](https://docs.greengoods.app/builders/agentic/skills) projects.

.claude/skills/clean/README.md

@@ -0,0 +1,8 @@
+# clean
+
+Scope-locked cleanup at scale. Clean runs eight focused assessment lanes over the codebase (deduplication, type consolidation, dead code, circular dependencies, type strengthening, defensive-code removal, legacy cleanup, and AI-slop removal) and only changes what a human locked into scope first.
+
+**How to invoke:** Type `/clean` after audit findings are accepted; `--dry-run` and `--scope` bound it.
+
+[`SKILL.md`](./SKILL.md) in this folder is the executable contract; this README is the human
+summary the [Skills Catalog](https://docs.greengoods.app/builders/agentic/skills) projects.

.claude/skills/debug/README.md

@@ -0,0 +1,8 @@
+# debug
+
+The bug entry point. Describe a bug, paste a stack trace, or report a failing build and this workflow fires on its own, then routes the work: reports from real users get reproduced first, urgent incidents take the hotfix lane, red tests get test-driven fixes, and QA slices get pulled from Linear.
+
+**How to invoke:** No command needed; describing the problem activates it.
+
+[`SKILL.md`](./SKILL.md) in this folder is the executable contract; this README is the human
+summary the [Skills Catalog](https://docs.greengoods.app/builders/agentic/skills) projects.

.claude/skills/design/README.md

@@ -0,0 +1,8 @@
+# design
+
+The keeper of the Warm Earth design language. Design holds the direction for shape, motion, color, and material tokens, the split between the admin cockpit and client PWA identities, and the review lenses for UI work. Reach for it before new views, polish passes, or prompts for AI design tools.
+
+**How to invoke:** Loads by context for design-direction questions and UI work.
+
+[`SKILL.md`](./SKILL.md) in this folder is the executable contract; this README is the human
+summary the [Skills Catalog](https://docs.greengoods.app/builders/agentic/skills) projects.

.claude/skills/design/SKILL.md

@@ -84,7 +84,7 @@ Three principles woven throughout — not a checklist, a lens:
 
 ### Regenerative Design
 
-Does this design regenerate or extract? Make value flows visible, match complexity to community maturity, enrich stakeholder boundaries, make failure recoverable, reject manufactured engagement, build community capability, and keep the visual language grounded rather than financialized. The executable PR checks live in [review-checklist.md § Lens 1](./review-checklist.md#lens-1-regenerative-design); public rationale and sources live in `docs/docs/reference/design-research.md`.
+Does this design regenerate or extract? Make value flows visible, match complexity to community maturity, enrich stakeholder boundaries, make failure recoverable, reject manufactured engagement, build community capability, and keep the visual language grounded rather than financialized. The executable PR checks live in [review-checklist.md § Lens 1](./review-checklist.md#lens-1-regenerative-design); public rationale and sources live in `docs/docs/builders/architecture/design.mdx`.
 
 ### User Ecosystem Thinking
 

.claude/skills/design/review-checklist.md

@@ -196,8 +196,8 @@ A checklist agents run once per PR catches what we remember. Automated checks ca
 
 ## Related
 
-- Regenerative rationale and sources: `docs/docs/reference/design-research.md`
+- Regenerative rationale and sources: `docs/docs/builders/architecture/design.mdx`
 - Spatial patterns: [surfaces.md](./surfaces.md)
 - Ecosystem archetypes: [ecosystem.md](./ecosystem.md)
 - Implementation details: [implementation.md](./implementation.md)
-- Green Goods personas: `docs/docs/reference/design-research.md`
+- Green Goods personas: `docs/docs/builders/architecture/design.mdx`

.claude/skills/design/system-alignment-review.md

@@ -159,5 +159,5 @@ If nothing in Section 1 meets all constraints, say so. "Design system is aligned
 - `packages/shared/src/styles/theme.css`, `design-md.generated.css`, `design-md.generated.json` — runtime projections
 - `scripts/design/check-tokens.sh`, `scripts/design/check-vocab.sh`, `scripts/design/md-generate.mjs` — validators and generator
 - `packages/shared/.storybook/**`, `packages/shared/src/components/Tokens/**` — Storybook surface for the design system
-- `docs/docs/builders/packages/admin.mdx`, `docs/docs/builders/testing/storybook.mdx` — live UI and Storybook contracts
+- `docs/docs/builders/packages/admin.mdx`, `docs/docs/builders/testing/index.mdx` — live UI and Storybook contracts
 - `CLAUDE.md`, `AGENTS.md`, `packages/*/AGENTS.md` — Design-System / Design-Language sections agents load by default

.claude/skills/doc-feedback/README.md

@@ -0,0 +1,8 @@
+# doc-feedback
+
+Turns a reviewed Google Doc into tracked work. Point it at a .docx export carrying comments and tracked changes and it parses the feedback into a triage-able record, then walks each item to resolution with a scope-lock gate between phases.
+
+**How to invoke:** Type `/doc-feedback` once the team has finished reviewing a doc.
+
+[`SKILL.md`](./SKILL.md) in this folder is the executable contract; this README is the human
+summary the [Skills Catalog](https://docs.greengoods.app/builders/agentic/skills) projects.

.claude/skills/module-seams-review/README.md

@@ -0,0 +1,8 @@
+# module-seams-review
+
+A deep, read-only review of module boundaries: public exports, dependency direction, composition roots, direct-test seams, and mock fidelity. Use it for import-boundary migrations and testability-architecture reviews, not for ordinary small diffs.
+
+**How to invoke:** Describe a modules-and-seams review intent to activate it.
+
+[`SKILL.md`](./SKILL.md) in this folder is the executable contract; this README is the human
+summary the [Skills Catalog](https://docs.greengoods.app/builders/agentic/skills) projects.

.claude/skills/plan/README.md

@@ -0,0 +1,8 @@
+# plan
+
+Planning and execution for Green Goods. Plan creates structured implementation plans in `.plans` feature hubs, tracks lane state and proof, mirrors visibility to Linear, and coordinates agent teams when they are explicitly requested.
+
+**How to invoke:** No slash command; planning intent ("plan this", "break down X") activates it.
+
+[`SKILL.md`](./SKILL.md) in this folder is the executable contract; this README is the human
+summary the [Skills Catalog](https://docs.greengoods.app/builders/agentic/skills) projects.

.claude/skills/qa-session/README.md

@@ -0,0 +1,8 @@
+# qa-session
+
+Live product QA with fixes in the loop. Run it during a walk of the product (paired, live, or from a transcript) and it captures stable records, triages bounded fix-now work, revalidates in the serving checkout, and hands deferred findings to qa-triage with exact test IDs.
+
+**How to invoke:** Type `/qa-session` or announce a QA walk.
+
+[`SKILL.md`](./SKILL.md) in this folder is the executable contract; this README is the human
+summary the [Skills Catalog](https://docs.greengoods.app/builders/agentic/skills) projects.

.claude/skills/qa-triage/README.md

@@ -0,0 +1,8 @@
+# qa-triage
+
+Turns QA notes into tracked records. After a Build Sync or a qa-session handoff, it enriches findings against PostHog and existing Linear records, then files scope-locked issues and private QA-sheet rows, and it writes only after confirmation.
+
+**How to invoke:** Type `/qa-triage` after a QA call or handoff.
+
+[`SKILL.md`](./SKILL.md) in this folder is the executable contract; this README is the human
+summary the [Skills Catalog](https://docs.greengoods.app/builders/agentic/skills) projects.

.claude/skills/research/README.md

@@ -0,0 +1,8 @@
+# research
+
+Evidence-first answers before decisions. Research reconciles repository and primary-source evidence for a bounded question, labels every conclusion by how established it is, and returns a brief that drives the next decision. It is read-only by default.
+
+**How to invoke:** Describe the bounded question; research intent activates it.
+
+[`SKILL.md`](./SKILL.md) in this folder is the executable contract; this README is the human
+summary the [Skills Catalog](https://docs.greengoods.app/builders/agentic/skills) projects.

.claude/skills/resolve-pr-comments/README.md

@@ -0,0 +1,8 @@
+# resolve-pr-comments
+
+Works a pull request's review feedback to done. It validates each unresolved thread, sweeps for related instances, fixes with targeted proof, and pushes through the gate. GitHub replies and thread resolution happen only with explicit authorization.
+
+**How to invoke:** Ask to address or resolve a PR's review comments.
+
+[`SKILL.md`](./SKILL.md) in this folder is the executable contract; this README is the human
+summary the [Skills Catalog](https://docs.greengoods.app/builders/agentic/skills) projects.

.claude/skills/review/README.md

@@ -0,0 +1,8 @@
+# review
+
+The full change review. Review hunts regressions, remaining gaps, and production quality in one pass over a PR, branch, or working copy, and returns severity-ordered findings with validation evidence and a verdict.
+
+**How to invoke:** Type `/review [package|PR|path]`.
+
+[`SKILL.md`](./SKILL.md) in this folder is the executable contract; this README is the human
+summary the [Skills Catalog](https://docs.greengoods.app/builders/agentic/skills) projects.

.claude/skills/ship/README.md

@@ -0,0 +1,8 @@
+# ship
+
+Publication without ceremony. Ship proves the changed behavior locally, runs the budgeted push gate, and lets GitHub CI own broad regression coverage; the complete local gate is reserved for releases, critical surfaces, and explicit full-local requests.
+
+**How to invoke:** Commit, push, or PR intent activates it.
+
+[`SKILL.md`](./SKILL.md) in this folder is the executable contract; this README is the human
+summary the [Skills Catalog](https://docs.greengoods.app/builders/agentic/skills) projects.

.husky/pre-push

@@ -18,9 +18,19 @@ fi
 
 echo "🔍 Running the focused ready-for-CI gate..."
 
+# git exports GIT_DIR/GIT_WORK_TREE/GIT_INDEX_FILE to hooks. Any test fixture
+# that spawns git in a temp directory would inherit them and operate on THIS
+# repository instead (observed 2026-09-02: fixture commits and core.bare=true
+# written into the real repo from the push gate). Hooks must not leak them.
+unset GIT_DIR GIT_WORK_TREE GIT_INDEX_FILE
+
 # Bun is the repository's required package manager.
 if ! command -v bun >/dev/null 2>&1; then
   echo "Error: Bun is required. Install bun: https://bun.sh"
   exit 1
 fi
-node scripts/dev/ci-local.js --intent push --reuse-passing-receipts
+# GG_PUSH_GATE_ARGS forwards ci-local's own sanctioned flags (e.g. --check <id>,
+# --test-path <surface>:<path>) for plans that require explicit focus; the gate
+# itself still runs and still decides.
+# shellcheck disable=SC2086
+node scripts/dev/ci-local.js --intent push --reuse-passing-receipts ${GG_PUSH_GATE_ARGS:-}

.plans/active/builder-docs-rebuild/brief.md

@@ -0,0 +1,42 @@
+# Builder Docs Rebuild — Brief
+
+**Feature Slug**: `builder-docs-rebuild`
+**Status**: ACTIVE
+**Created**: 2026-09-02
+**Owner**: Afo (decisions) / Claude (execution)
+
+## Problem
+
+The builder track at docs.greengoods.app (45 pages) was authored in the repository's
+agent-contract register: 29 pages under 220 words, ~5,900 hand-written words total, zero external
+links at research time, entry pages that defer to repo files instead of teaching, and seven of ten
+sidebar categories fronted by empty auto-generated index pages (which also breaks the teal accent).
+A 2026-09-01 review meeting rated the track "context-poor, not human-friendly, no flow, no links."
+
+## Outcome
+
+A clear, human-friendly technical guide for developers who want to understand, explore, test, or
+contribute to Green Goods: ~38 fuller pages in 8 sections, every category fronted by a real landing
+page, hand-written prose in the community track's register, generated projections kept and
+digest-gated, external links everywhere they teach, and the whole site agent-readable
+(`llms.txt` + `.md` twins).
+
+## Blueprint
+
+The full research brief and page-by-page dispositions live in the review artifact
+("Builder Docs Rebuild", rev 2 — private link, decisions D1–D10 locked with Afo on 2026-09-02):
+https://claude.ai/code/artifact/3f55d286-fca3-4d50-b032-d8e61001268a
+
+`spec.md` in this hub carries the durable subset: target IA, locked decisions, page templates,
+and tone contract. Research basis: reference-site evidence packs (GainForest, EAS, Hats, Octant),
+Diátaxis, Google developer style highlights, Write the Docs, and a full local inventory.
+
+## Constraints
+
+- Keep the docs trust machinery: generators, digest gates (`check:docs-generated`),
+  `source_of_truth` frontmatter, `docs:audit:ci`.
+- The `feature/qa-report` stream owns the QA pages (rewritten 2026-09-01/02, merged in #793);
+  this effort only aligns links and placement around them.
+- No big-bang: each phase is an independently shippable PR to `develop`; the site is never worse
+  mid-migration. Moved or deleted slugs always get redirects.
+- Root-scripts consolidation (240 scripts) is explicitly out of scope (D6, separate follow-up).