docs(sync): harmonize documentation and READMEs across the repo

[Soushi888]

Intent

The docs had drifted apart from each other and from the code. A reader landing on CLAUDE.md was told this is a "3-zome Holochain hApp" while README.md correctly described a five-role multi-DNA hApp. TEST_COMMANDS.md said Tryorama was "still the primary test suite" while every other doc said it was deprecated. Five files pinned Vite 6.2.5 when ui/package.json has been on Vite 7. Eleven files referenced an EncryptedProfile entry type that does not exist anywhere in the codebase.

This is a full documentation sync pass: every doc-to-doc contradiction found, arbitrated against code evidence, and resolved with one canonical home per claim. Ran via /CodeDocs Sync over 96 markdown files.

Changes

Contradictions resolved against code (7). Each was checked against the source, not against whichever doc looked newest.

Topic	Was	Now	Evidence
Vite version	Vite 6.2.5 in 5 files	Vite 7	ui/package.json:45 → ^7.0.4
Holochain client	0.19.0 in 5 files	^0.20.0 (UI), ^0.19.1 (root tooling)	ui/package.json:51, root package.json
hApp architecture	"3-zome Holochain hApp"	Multi-DNA, 5 roles; "3-zome" now always scoped to the Nondominium DNA	workdir/happ.yaml:5-60 — lobby, nondominium, hrea, group, ndo
Primary test suite	TEST_COMMANDS.md: Tryorama "still the primary test suite"	Sweettest primary, Tryorama deprecated	agrees with README, .rules, tests/DEPRECATED.md, IMPLEMENTATION_STATUS
Private-data entry	EncryptedProfile (11 files)	PrivatePersonData	zome_person/src/lib.rs:59 — no EncryptedProfile type exists
Sweettest binaries	"Four [[test]] binaries"	5 nondominium + 2 group + 1 lobby	the three tests/Cargo.toml manifests
Ontology doc paths	documentation/archives/{agent,resources,governance}.md	documentation/requirements/	those files are not in archives/

Superseded content refreshed. .rules development status was three months behind README.md and now points at it. tests/DEPRECATED.md claimed the resource and governance migrations were "Not started" when both Sweettest modules exist (137 and 307 lines); the table now reflects reality and lists the Sweettest coverage that has no Tryorama predecessor. tests/README.md had no deprecation banner at all despite sitting beside DEPRECATED.md; it has one now.

Duplication collapsed to canonical homes. The tech-stack block was repeated verbatim in five files, each carrying the same two stale versions. It now lives once in README.md § Technology Stack; the others link. Same for the Sweettest command block (five copies) which now lives in documentation/TEST_COMMANDS.md.

Structure.

• ui/README.md was still the untouched SvelteKit scaffold: titled # sv, instructing npx sv create and npm run dev. Replaced with a real README covering the multi-agent dev harness, per-agent origin isolation via VITE_DEV_AGENT, checks, E2E, and the lib/ layout.
• README.md setup was missing git submodule update --init --recursive, which is genuinely required — build:happ runs cd vendor/hrea && cargo build and packs vendor/hrea/dnas/hrea/workdir, so the build fails without it.
• README.md still listed "NPM Workspaces" and Tryorama as current stack, contradicting the bun-only convention stated 200 lines above it.
• Four competing documentation indexes now have declared roles: documentation/README.md is the hub, DOCUMENTATION_INDEX.md the annotated guide, SUMMARY.md the flat TOC, and the root README a short pointer. Each links to the others; previously the hub linked to neither of the other two.
• The Playwright E2E suite was documented in ui/tests/README.md but linked from nowhere. Now reachable from README, the hub, TEST_COMMANDS, and .rules.
• pai/cursor-rules/20-architecture.md gained a Multi-DNA Topology section; it is always-loaded agent context and described only the three zomes.

Links: 34 broken → 0. All were path moves after files were relocated (archives/{agent,resources,governance}.md → requirements/, post-mvp/lobby-dna.md → requirements/lobby-dna.md, versioning.md → ndo-versioning.md, and the lobby-architecture and valueflows-dsl pairs). Two dead anchors fixed against their real headings. One link pointed at user-story-resource-transaction.md, which exists nowhere; retargeted to user-story-ERP-bridge.md, the actual home of the Sarah/Sensorica and Marco/FabLab participants that sentence describes.

Decisions

Option	Rejected because
Edit CLAUDE.md / AGENTS.md / GEMINI.md directly	All three are symlinks to .rules. Edits go to .rules, which is tracked and is itself the source (only .cursor/rules is nix-materialized from pai/).
Delete the stale Tryorama sections from TEST_COMMANDS.md	Content moves, it does not vanish. They are demoted under an explicit deprecation banner and kept as archaeology.
Fix the PropertyRegime 6-vs-4 split	It is a code divergence, not doc drift. See Still open.
Rewrite the archived P2PMODELS_COMPARISON_REPORT.md versions	It is a dated archive document; its stale versions are accurate as of its own date.

How to test

# Link integrity across all 96 docs
bun ~/.claude/skills/CodeDocs/Tools/DocSync.ts links --repo .

Expect broken: 1. The single remaining hit is a false positive: ndo_prima_materia.md:19 targets #6-the-surface-of-attachment--capability-slots, and the heading contains an em-dash. GitHub strips the em-dash and leaves both surrounding spaces, producing two hyphens; the checker collapses them to one. The link resolves correctly on GitHub.

Spot-check the code-arbitrated claims:

grep -rn "EncryptedProfile" --include="*.md" . | grep -v vendor/   # expect none
grep -n '"vite"\|"@holochain/client"' ui/package.json              # ^7.0.4, ^0.20.0
grep -c "name = " dnas/*/tests/Cargo.toml                          # binary counts

No code changed, so no build or test run is required.

Documentation

This PR is documentation only. 24 files: README.md, .rules, REVIEW.md, ui/README.md, tests/README.md, tests/DEPRECATED.md, 3 files under pai/, and 15 under documentation/.

Related

Related issues:

• None

Still open, deliberately out of scope:

• PropertyRegime has 6 variants in Rust and 4 in TypeScript. crates/shared/src/types.rs:47 carries Private, Commons, Collective, Pool, CommonPool, Nondominium; packages/shared-types/src/resource.types.ts:176 carries four, with Collective and Pool documented as "removed after design review". The docs describe both sides accurately and resources.md §2.6 already asks for a reconciliation pass. Fixing it means either dropping two Rust variants (a breaking change to NondominiumIdentity validation) or restoring them in the UI. That is a code decision and wants its own issue.
• documentation/requirements/post-mvp/complete-resource-specification.md is 0 bytes. Dropped from the SUMMARY.md TOC rather than linking an empty page. The file is left in place pending a decision to write it or delete it.

Closes #135