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

[Soushi888]

SoushAI analysis. Drafted by Soushi's AI assistant, reviewed and posted by @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. Two commits: the original /CodeDocs Sync pass, and a re-sync against NDO Layer 1 that issue #135 deliberately sequenced behind PR #132.

Changes

Commit 1 — harmonization pass

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.

Commit 2 — re-sync against NDO Layer 1 (#132)

Issue #135 sequenced this pass behind #132 because Layer 1 changes what these documents describe. Every claim below was checked against the merged source.

False status claims corrected.

Document	Said	Code says
IMPLEMENTATION_STATUS.md	Governance-as-operator "specified, not implemented"; six named types and functions absent	GovernanceTransitionRequest / TransitionContext / GovernanceTransitionResult are in crates/shared/src/io/governance.rs; evaluate_state_transition is live in zome_gouvernance/src/transition.rs. Only request_resource_transition and evaluate_governance_transition are still absent, which is why the path is parallel and advisory rather than the mandatory funnel
IMPLEMENTATION_STATUS.md	"GovernanceRule semantics are not evaluated"	crates/shared/src/constraints.rs enforces classification predicates Hard at integrity and Soft as advisory. The row is split: classification constraints enforced, per-rule runtime conditions not
ndo_prima_materia.md (4 sites)	Layer 1 activation not in code	NdoToSpecification is in LinkTypes and is created on every create_resource_specification
ndo_prima_materia.md REQ-NDO-L1-02	Layer 1 may activate "at or after Ideation"	The integrity gate rejects Ideation and accepts Specification through Active, matching §5.2's own activation table

Struct listings regenerated from source in resources.md, zomes/resource_zome.md, zomes/governance_zome.md, API_REFERENCE.md and specifications/specifications.md. ResourceSpecification gained scope, ndo_identity_hash, ndo_state_hash. GovernanceRule replaced the rule_type/rule_data string pair with the typed RuleData enum plus three denormalized classification fields. EconomicEvent, Commitment, LogEconomicEventInput and ProposeCommitmentInput all gained ndo_identity_hash. created_by and created_at were documented on entries that never carried them, and the API reference's ResourceSpecificationInput / GovernanceRuleInput blocks described a schema with no counterpart in code at all.

Status banners on specifications/governance/cross-zome-api.md and governance-operator-architecture.md. They keep their target architecture, but a reader can no longer mistake request_resource_transition for a callable function. The same correction lands in pai/cursor-rules/20-architecture.md, which is always-loaded agent context and taught the wrong call chain.

SUMMARY.md now lists every document in the tree. The Source-NDO set, the Phase B design record, ADR-010-013, the hREA release plan and two Applications pages were unreachable from the mdBook TOC.

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.
Rewrite the three governance design docs to match code	They specify the target architecture, which is still the plan. A status banner naming which half exists is honest without discarding the design.
Rewrite the archived P2PMODELS_COMPARISON_REPORT.md versions	It is a dated archive document; its stale versions are accurate as of its own date.
Rebase-resolve conflicts by taking one side wholesale	Five files conflicted against the new dev. Each hunk was resolved against code: dev's newer prose where it was richer, this branch's corrections where dev was stale (Vite 7, client ^0.20.0, five roles not four, the 13 link paths dev reintroduced).

How to test

# Link integrity across all 105 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
grep -n "pub struct ResourceSpecification" -A 25 \
  dnas/nondominium/zomes/integrity/zome_resource/src/lib.rs        # 9 fields incl. the Layer 0 pair

Every document in the tree is reachable from SUMMARY.md:

python3 - <<'EOF'
import pathlib, re
linked = set(re.findall(r'\]\(([^)]+\.md)\)', pathlib.Path('documentation/SUMMARY.md').read_text()))
missing = [str(p.relative_to('documentation')) for p in sorted(pathlib.Path('documentation').rglob('*.md'))
           if str(p.relative_to('documentation')) not in linked | {'SUMMARY.md'}]
print(missing or 'none')
EOF

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

Documentation

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

Related

Closes #135

Follows PR #132, which this branch is rebased onto. Two items the first commit deliberately deferred are closed by #132 rather than here:

• PropertyRegime 6-vs-4 split — resolved. crates/shared/src/types.rs and packages/shared-types/src/resource.types.ts now both carry seven variants (Private, Commons, Collective, Pool, CommonPool, Public, Nondominium), and every doc that states a count states seven.
• complete-resource-specification.md was 0 bytes — resolved. It is now the 54KB Phase B design record for feat(resource)!: NDO Layer 1 typed governance rules, classification constraints, and OperationalState #132, and is linked from both DOCUMENTATION_INDEX.md and SUMMARY.md.

Still open, deliberately out of scope:

• documentation/specifications/protocol-bridge-specifications.md cites a user story that does not exist. The original link targeted user-story-resource-transaction.md. It was retargeted to user-story-ERP-bridge.md, which contains the participants that sentence describes, but whether the intended document was renamed or never written is a question for its author.
• The three governance design documents still specify request_resource_transition. They now carry a status banner, but reconciling the design with what feat(resource)!: NDO Layer 1 typed governance rules, classification constraints, and OperationalState #132 actually built is a design decision, not doc drift. Filed as design: decide whether write paths funnel through evaluate_state_transition or stay parallel #145: the funnel-versus-parallel question from complete-resource-specification.md §5 has to be answered before those banners can come off.