Standardize documentation distribution across the monorepo and subprojects

[gabitoesmiapodo]

User story / Problem statement

Currently the repo's docs are distributed unevenly with no written rationale. Root has the full set (CLAUDE.md, architecture.md, README.md, AGENTS.md), carpincho-wallet has the full set, and every other subproject (canton-base, counter/daml, counter/wallet-service, counter/frontend, canton-connect-kit) has only a README. There is no documented rule for when a subproject should gain a CLAUDE.md or architecture.md, so the decision is ad hoc and the docs risk drifting or duplicating root content. Contributors and agents lack a single statement of which doc answers which question, for which reader, at which tier.

Expected outcome

A documented, repo-wide convention for how the four doc types are distributed across the monorepo and subprojects, with the existing docs brought into line and new delta docs created only where warranted. When done:

• The distribution rule is written into a canonical location so future doc decisions are mechanical, not ad hoc.
• Subproject docs contain only their delta from root and link upward; no subproject doc restates repo-wide rules.
• New CLAUDE.md/architecture.md files exist only where a subproject's complexity or divergent conventions warrant them.

Acceptance criteria

• Research confirms or revises the proposed distribution model against the actual state of each subproject and any team conventions.
• The doc-distribution convention is written into a canonical location (root CLAUDE.md or architecture.md): the one-reader-per-doc principle, the per-file tier rules, and the "deltas only, link upward" rule.
• Each existing subproject doc is audited; content that restates root rules is removed and replaced with an upward link.
• AGENTS.md is co-located with every CLAUDE.md and nowhere else.
• New delta docs are created where warranted (candidates: counter/wallet-service CLAUDE.md, counter/frontend CLAUDE.md, canton-connect-kit CLAUDE.md + architecture.md), or each candidate is explicitly recorded as "not warranted yet" with a reason.
• No subproject README restates root setup; each links to the root README for the shared local loop.
• Root architecture.md stays seam-focused; no subproject internals are duplicated into it.

Alternatives considered

• Single root architecture.md covering all subproject internals — rejected: becomes a god-doc that drifts on every subproject commit, duplicates content that belongs next to the code, and loses the cross-component "what talks to what" clarity that is root's job.
• README-only everywhere (no nested CLAUDE.md/architecture.md) — rejected: nested CLAUDE.md is auto-loaded by cwd and changes agent behavior in that directory; complex subprojects (carpincho-wallet) need structural docs a README cannot carry.
• Pre-emptively giving every subproject the full four-file set — rejected: empty or restating docs are worse than none; they drift and dilute the root single-source-of-truth.

Technical notes

Proposed distribution model (one reader, one question, layered by scope; deltas only):

• README.md — human "what is this / how to run." Floor: every independently buildable/runnable/publishable unit gets one. Subproject READMEs cover only that unit and link to root for shared setup.
• CLAUDE.md — agent rules; auto-loaded by cwd, additive over root. Root always (commit standards, PR flow, npm-only, ports, no-semicolons, orchestration). Subproject only when local conventions differ from or add to root enough that an agent editing only that dir would get it wrong; deltas only, defer upward.
• architecture.md — shape/seams. Root always (canton-base <-> wallet-service <-> wallet <-> frontend seam map + ports). Subproject only when internal structure outgrows its README (~3+ interacting subsystems, non-trivial control flow, or named abstractions).
• AGENTS.md — static 3-line pointer to CLAUDE.md for non-Claude agents (Cursor, Windsurf). Co-locate with every CLAUDE.md, nowhere else.

Recommendation matrix (current -> recommended):

Subproject	README	CLAUDE	architecture	AGENTS	Note
root	yes	yes	yes	yes	correct as-is
carpincho-wallet	yes	yes	yes	yes	correct as-is (vault, provider, extension, wc)
counter/wallet-service	yes	candidate	only if bridge grows	mirror CLAUDE if added	borderline; CLAUDE is the likely add
counter/frontend	yes	candidate	no	mirror CLAUDE if added	borderline
canton-connect-kit	yes	candidate	candidate	mirror CLAUDE if added	strongest future candidate as its public hook API stabilizes
counter/daml	yes	no	no	no	README-only is right (single DAR artifact)
canton-base	yes	no	no	no	README-only is right (docker + bash)

Tooling interaction to keep in mind during implementation: doc-sync tooling in this repo auto-discovers root canonical docs and nested files named CLAUDE.md, but not nested architecture.md/AGENTS.md. Adding nested architecture.md files widens that blind spot; broadening the sync tool's discovery glob is a reasonable follow-up.

Additional context

Current doc inventory (verified on fix/direct-dapp-footer-status):

Scope	CLAUDE.md	architecture.md	README.md	AGENTS.md
root	yes	yes	yes	yes
carpincho-wallet	yes	yes	yes	yes
canton-base	—	—	yes	—
counter/daml	—	—	yes	—
counter/wallet-service	—	—	yes	—
counter/frontend	—	—	yes	—
canton-connect-kit	—	—	yes	—