Process & Registry

How a sibling repo points back here

Every repo in the family carries a short "Part of the Amoleo family" section in its own CLAUDE.md naming this repo. Two failure modes showed up in that pointer on 3 Sept 2026, in the same conversation where a user noticed docs/stack.md and CLAUDE.md were making false claims about which repos had backlog tooling. Fixing that raised the obvious follow-up: if the docs in this repo had drifted from reality without anyone noticing, what was stopping the same thing happening to the pointer every other repo keeps back to this one?

The two failures

1. Four repos spelled out this machine's own absolute path. Website, Pets, Connections and Accounts all wrote something like:

../Amoleo-Family (a sibling of this folder, i.e. I:\Development\Docker\Amoleo-Family)

The relative path is fine and is what actually gets used. The parenthetical is the problem: it bakes a specific Windows drive letter and folder layout into a file that gets committed and pushed to GitHub. Every repo in the family happens to be private today, so nothing has actually leaked — but a repo's visibility is an editorial decision made elsewhere (see docs/cost-model.md's "free tier" framing — a public repo is also free), not something this pointer should depend on for safety. The other eleven repos already had it right, just saying "a sibling of this folder" with no drive letter — that's the pattern now, everywhere:

- **On disk:** `../Amoleo-Family` (a sibling of this folder)
- **On GitHub:** https://github.com/ValadAmoleo/Amoleo-Family (use this if
  the sibling folder isn't checked out)

2. Several repos hand-copied a list of "which family doc covers what." Website, Pets, Connections and Accounts each carry a small table mapping "here you might change…" to "the spec is…", covering four or five docs. Rissbrook and the ten design-only repos have the same thing in prose form — "brand, footer, cookie banner, screenshots, stack, identity." Both are a snapshot of the family docs index at the time that repo's CLAUDE.md was last touched. The index itself has since grown to seventeen documents (wordmark, header, auth box, OG image, SEO, accessibility, theme, CSS system, cost model, roadmap, mission statements, and more) — none of that growth is reflected in most of the reproduced lists, because nothing tells a repo to update its copy when the index changes. It's the exact same failure this repo caught in its own docs the same day, one level removed: a fact copied into a second file will eventually be wrong in one of them, and nobody notices which.

The fix: point at the index, don't copy it

A repo may still name the two or three docs it touches most (that's useful, local color — Pets' note that it's "the reference for the transactional stack" earns its place). What it must not do is imply that list is complete. Every repo's CLAUDE.md now carries one more sentence after its doc pointers, worded to fit that repo's own style, but making the same claim:

Amoleo-Family/CLAUDE.md's own "Cross-repo specifications" table is the current, authoritative index — read that table directly rather than assuming [this repo's own list] is exhaustive.

That sentence is the thing that actually solves "we don't need to worry about the files going stale in the individual repos": nothing in a sibling repo needs to change when this repo adds a new doc, because the sibling never claimed to enumerate the docs in the first place — it just says where the real list lives, on disk and on GitHub, and trusts that.

What's checked, and what isn't

node tools/check-docs-pointer.mjs reads every repo in tools/repos.json and fails a repo whose CLAUDE.md:

• contains an absolute drive-letter path landing on Amoleo-Family (the leak in failure 1 above, regex-matched so it doesn't matter which drive letter or folder name a future machine uses)
• is missing the relative path ../Amoleo-Family
• is missing the GitHub fallback URL
• has no sentence pointing at the live "authoritative index" (matched loosely, on that phrase — see failure 2 above)

It cannot and does not check that a repo's own hand-picked doc list is accurate — only that the repo has also pointed at the place where accuracy actually lives. A repo is free to say something wrong in its own three-line summary; the checker's job is only to make sure nobody has to trust that summary once they've read the sentence after it.

Applying this to a new repo

tools/register-repo.mjs should be extended to write this section automatically for a brand-new repo, the same way it already writes the repos.json/stack.json/CLAUDE.md triple — not done yet, tracked here rather than silently assumed. Until then, copy the block above by hand into a new repo's CLAUDE.md and run node tools/check-docs-pointer.mjs to confirm it passes.

Generated from docs/family-docs-pointer.md. Edit there and re-run npm run build in docs-site-src/ — never hand-edit a page.