# Catalog Index — every donor we mine, every census we keep

**Audience: AI coding agents first.** A directory, not a census. Optimize reads for activation.
**Status:** Living index. **This is the single source of truth for the donor roster (name → repo root).** SHA pins live *inside each census artifact* at the grain that artifact needs — never copied here (copying = drift).
**Purpose:** answer *"which donor repos do we mine, and where is each thing we already catalogued?"* in one place, so we **never re-explore what is already catalogued**. Before spawning any exploration agent, check here first.

> **Catalog vs registry — two indexes, opposite sides.** This index is the **input** side (donor *sources* we mine). `docs/registry.json` (+ `docs/specs/2026-06-12-module-registry.md`) is the **output** side (the `@platform-modules/*` *structure* we built). A census records what a donor *contains*; the registry records what becomes a module. They never duplicate; they cross-link.

---

## 1. Donor roster (identity — the SoT)

Stable identity only (name → repo root → role). For a donor's pinned SHA at a given grain, open the census artifact in §2 that covers it.

| Donor | Repo root | One-line identity |
|---|---|---|
| `multideal` | `/home/user/Projects/multideal` | richest product donor — commerce, money-path, AI, affiliate; Astro/React + CF Worker/DO + Drizzle/Neon + Stripe |
| `zync.is` | `/home/user/Projects/zync.is` | best package-hygiene donor — clean seams, tested; Vite React + Astro + Hono CF APIs + Workers + Drizzle |
| `ForumZone` | `/home/user/Projects/ForumZone` | realtime + community + provider-adapter donor; Astro/React + CF + `packages/{auth,db,providers,shared,ui}` |
| `trance-shop-israel` | `/home/user/Projects/trance-shop-israel` | commerce + ticketing donor (US-exclusive tax); Astro/React + Workers + Hono + Drizzle/Neon/PG |
| `fewtok` | `/home/user/Projects/fewtok` | tooling/leaf donor — Bun CLI, dict/macro/sigil, learn/simulate (some Bun-locked) |
| `vibeflare` | `/home/user/Projects/vibeflare` | AI-gateway + api-keys donor; Astro/React UI + Hono Worker + CLI + shared package |
| `Press.zone` | `/home/user/Projects/Press.zone/community-press-zone/community-press-zone-backend` | legacy/content donor — mostly non-portable; Vite React frontend (**untracked**) + Express backend + legacy CMS plugins |

**Dead / excluded (do not re-add):** `CommentPressZone` — DEAD (repo is a 4-byte `test.txt`, no source). `ticketing` capability — EXCLUDED (proprietary core product of `trance-shop-israel`, not generic substrate; `registry.json → excluded.ticketing`).

---

## 2. Census artifacts (the content — each owns its own pins)

| Artifact | Grain | Covers | Pin style (inside the artifact) |
|---|---|---|---|
| `docs/specs/2026-06-16-donor-capability-inventory.md` | **backend capability** (module-grain: who has `auth`/`billing`/`ledger`/…) | all 7 donors | **repo-level** SHA (whole-repo census) |
| `docs/catalog/2026-06-16-ui-donor-census.md` | **UI/design-system** (engine · token-layer · variants · taxonomy · design-system page) | all 7 donors | **path-scoped** SHA (last commit touching the UI subtree) |
| `docs/specs/2026-06-17-wasp-like-template-capability-map.md` | **DERIVED map** (Wasp/OpenSaaS-class full-stack-template gap: backend crosswalk · `ui-*`+`-react` sibling backlog · R5 harvest altitude) | n/a — lens over the 2 censuses + `registry.json` | **none of its own** — inherits source pins; stale iff a source above is stale |
| `docs/catalog/2026-06-17-screen-flow-donor-census.md` | **screen/flow** (page-grain: best donor + path + maturity per template flow — auth · account · subscription-tiers · team-org · admin-dashboard · content · notifications · onboarding · marketing · moderation · search · system) | 5 local donors (multideal · zync.is · ForumZone · trance · vibeflare); fewtok=no UI; Press.zone=untracked snapshot; CommentPressZone=dead | **path-scoped** SHA per donor (inside artifact §1) |
| `docs/catalog/2026-06-17-invoicing-census.md` | **invoicing / AR** (zync provider-agnostic AR core seam + tables; multideal IL `VendorInvoiceProvider` dispatch) | zync.is · multideal | **path-scoped** SHA per donor (inside artifact PART A/B) |
| `docs/catalog/2026-06-17-multideal-editorial-census.md` | **editorial primitives** (component-grain: rich-text editor signature · NO block model · publish/schedule picker · image-upload R2-lock · form/field primitives) — grounds the mod-cms editorial port wave; yields KILL `content/blocks`, build-eligible generic Tiptap editor, consumer-gated `content-react`, seam-gated `uploads-react` | multideal | **path-scoped** SHA `ff1c8ac32` (`apps/web/src/features`) |

New census added later → append a row here (the standing rule, §4). A **derived** map (lens over existing censuses, no new donor scan) is also appended here, marked "DERIVED" with no own pins — it never re-explores; it inherits its sources' freshness.

---

## 3. Freshness & lazy-refresh protocol

**Use the catalog if fresh; refresh only the stale part — never the whole catalog.**

1. **Before using a census,** check the artifact's pin against the donor's current state at that grain:
   - **Path-scoped (UI census):** `git -C <repo-root> log -1 --format=%h -- <ui-path>`. Fresh iff it equals the artifact's pinned SHA for that donor.
   - **Repo-level (capability inventory):** `git -C <repo-root> rev-parse --short HEAD`. (Coarser — over-invalidates; the path-scoped form is preferred for any new artifact.)
   - **Untracked donor** (`Press.zone` frontend): no SHA signal exists. Treat as a dated snapshot; re-census on demand, never assume fresh.
2. **Fresh** → use the catalogued facts directly. **Do not** spawn an exploration agent.
3. **Stale** → re-census **only the changed donor at the changed grain** (not the other 6, not the other grain), then update *that row's* pin + facts and bump the artifact date. Lazy by construction.

**Read-only census = non-opus subagent.** A freshness re-check / cheap single-donor refresh → `Explore` `model:'haiku'`; a build-feeding content re-census → non-opus Sonnet-class (cursor). **Read-only exploration is NEVER opus** — opus is judgment-only (`model-dispatch-cursor-census` memory; `platform-orchestrator` skill).

---

## 4. The standing rule (mirrors `CLAUDE.md §6 → Catalog discipline`)

When you census something in this project that was not catalogued before:
1. **Persist it** as a census artifact (a dated doc under `docs/catalog/` or `docs/specs/`) — never leave it only in chat.
2. **Register it here** — add the donor to §1 if new, add the artifact to §2.
3. **SHA-pin it** at the finest grain that matters (path-scoped where possible), inside the artifact.
4. **Check freshness before reuse** (§3); **refresh only stale parts.**

The point: do the exploration **once**, then query the catalog forever.