fernandomg · Nov 2, 2026 · Nov 2, 2026 · Nov 2, 2026 · Nov 2, 2026 · Nov 2, 2026
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -25,7 +25,7 @@ Use one reader per doc type, layered by scope:
 
 | File | Reader / question | Distribution rule |
 |------|-------------------|-------------------|
-| `README.md` | Human: what is this and how does someone run it? | Every unit that builds, runs, publishes or tests on its own gets one. A subproject's README covers only that unit and links to the root README for shared setup. |
+| `README.md` | Human: what is this, how do I start, and where do I go next? | Every unit that builds, runs, publishes or tests on its own gets one. A subproject's README covers only that unit and links to the root README for shared setup. |
 | `CLAUDE.md` | Agent: what local rules change how an agent edits here? | Root always. Subproject only when local conventions differ from root enough that an agent editing only that directory would get it wrong. Deltas only; link upward for repo-wide rules. |
 | `CONTRIBUTING.md` | Human: how does someone work on this repo? | Root only. Setup, the local development command and the checks to run before a PR. A user creating a project reads the README instead. |
 | `AGENTS.md` | Agent compatibility loader | Three-line shim beside every `CLAUDE.md`, pointing to the sibling `CLAUDE.md`. It is never canonical. |
@@ -47,16 +47,32 @@ Current distribution:
 
 Subproject docs must not restate root rules. They should describe only their local delta and link upward.
 
-**Reference material never goes in a README.** A README answers "what is this and how does someone run it".
-Enumerations belong elsewhere however short they are: token lists, prop tables, exported-symbol
-indexes, config keys.
+**A README is the page a reader meets first, and most try the unit before reading anything else.**
+It introduces the unit, gets the reader running, and says where to go next. It may repeat what
+another document holds whenever that serves those three jobs: an install line, a usage example, a
+gotcha, a short table. The authoritative version stays where the rules below put it, the README
+links to it, and the same-commit sync rule covers both copies.
 
 - When the code *is* the list (a token file, a type, a barrel), the code is the doc. Group it with
   category comments; a prose copy drifts within two PRs.
 - A rule constraining how to author the code goes in the nearest `CLAUDE.md`.
 - A seam between units goes in `architecture.md`.
 
-A README may state that a contract exists and link to it. It may not restate it.
+A caveat a reader could miss in running text goes in a GitHub alert, one fact per block. GitHub and
+TypeDoc render the five kinds; npm shows the tag as text, which is accepted.
+
+Every pointer out of a README names what the reader finds there: the generated reference for the
+API, `architecture.md` for the why, `CLAUDE.md` for the authoring rules, `CONTRIBUTING.md` for
+working on the repo.
+
+**Never count what the repo can grow.** "The examples", not "the two examples"; "its DARs", not
+"both DARs". The number drifts the day a folder is added, and nothing flags the sentence. A count
+stays only where it is the point: a pair the sentence contrasts, or a figure fixed in history.
+
+**No document is an orphan.** Every `.md` in the repo is linked or named by path from at least one
+other, and every one is reachable from the root `README.md` by following those links and names. The
+number of hops does not matter; a page nothing points at does. Nothing enforces this yet, so it is a
+review check.
 
 ## Stack and conventions (monorepo)
 

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -53,13 +53,28 @@ token in `example-dapps/amulet-vesting/.env`.
 
 ```bash
 pnpm dev:token-vesting        # interactive menu
-pnpm dev:token-vesting up     # LocalNet, both DARs, token registry, Wallet Gateway and dApp
+pnpm dev:token-vesting up     # LocalNet, its DARs, token registry, Wallet Gateway and dApp
 pnpm dev:token-vesting down   # stop everything and keep the ledger
 ```
 
 The dApp runs on http://localhost:3012, its token registry on http://localhost:3013 and Wallet
-Gateway on http://localhost:3030. Both examples share the LocalNet, so stop one before you start the
-other.
+Gateway on http://localhost:3030. The examples share the LocalNet, so stop one before you start
+another.
+
+### Installer
+
+```bash
+pnpm -C canton-create try         # pack the installer and every example into canton-create/.try
+pnpm -C canton-create try:clean   # stop the stack, reset the LocalNet and remove .try
+```
+
+`try` then prints the commands that run them there, as a user would.
+
+## Where to read next
+
+- [`architecture.md`](architecture.md) maps the stack: data flow, services and ports, auth, orchestration and packaging;
+- each package's `README.md` says what it is and how to use it, and its `architecture.md` how it works: [`canton-connect`](canton-connect/architecture.md), [`canton-dappbooster`](canton-dappbooster/architecture.md), [`canton-create`](canton-create/architecture.md), [`amulet-vesting`](example-dapps/amulet-vesting/architecture.md) and [`token-vesting`](example-dapps/token-vesting/architecture.md). `canton-theme` has none: the split between components and theme is in canton-dappbooster's;
+- the `CLAUDE.md` files hold the rules for writing code here. They are addressed to agents and bind humans too: [`CLAUDE.md`](CLAUDE.md) for the repo, and one in each package for its deltas.
 
 ## Before opening a pull request
 

diff --git a/README.md b/README.md
@@ -20,3 +20,7 @@ pnpm create canton-dappbooster
 ```
 
 More details are available in the [documentation](https://docs.dappbooster.cc/).
+
+## Contributing
+
+To work on this repository, see [CONTRIBUTING.md](https://github.com/BootNodeDev/canton-dappbooster/blob/main/CONTRIBUTING.md).
diff --git a/architecture.md b/architecture.md
@@ -7,11 +7,11 @@
 | LocalNet (external: [`BootNodeDev/canton-barebones`](https://github.com/BootNodeDev/canton-barebones)) | Node command-line tool over Docker Compose + the official Splice LocalNet bundle | Starts `sv + app-user`. A pinned dev dependency; `pnpm dev:amulet-vesting` scaffolds its config into the gitignored `.canton-localnet/` |
 | Wallet Gateway (external: [`canton-network/wallet`](https://github.com/canton-network/wallet)) | Node + Express + SQLite | The CIP-0103 wallet the dApp connects to: it holds the session, signs through the participant, and serves its own user UI. A root dev dependency, which `pnpm dev:amulet-vesting` runs on the host from `canton-create/scaffold/localnet/wallet-gateway.config.json` |
 | `scripts/` | Node + Bash + JSON | The root tooling: the doc, anatomy and version checks, the release bump, the `typedoc` configs and the gitleaks installer. See [`CLAUDE.md`](CLAUDE.md) |
-| `example-dapps/amulet-vesting/` | Vite + React + Ark UI + Tailwind v4 + `zustand` + react-router + Daml | Canton Coin **vesting** dApp, published as an example. Every read and write goes through the connected CIP-0103 wallet via `canton-connect`. Its `daml/` holds the `amulet-vesting` DAR: the vesting factory, proposal, contract and residual-claim templates. They hold real Canton Coin in escrow as a Splice `LockedAmulet`, and come vendored from [`BootNodeDev/cc-vesting-contracts`](https://github.com/BootNodeDev/cc-vesting-contracts). The build fetches its Splice data-dependencies rather than committing them. `scripts/bootstrap-vesting.mjs` creates the operator and its factory |
-| `example-dapps/token-vesting/` | Vite + React + Ark UI + Tailwind v4 + `zustand` + react-router | The same **vesting** dApp over a `DBT` instrument from [`BootNodeDev/canton-token-forge`](https://github.com/BootNodeDev/canton-token-forge), published as an example. Its `vesting` and `canton-token-forge` DARs ship as binaries in `vendor/`, so it builds no contract. `scripts/bootstrap-vesting.mjs` uploads them and creates the operator, its factory and the instrument; `scripts/registry.sh` runs the canton-token-forge registry the dApp reads the instrument from |
+| `example-dapps/amulet-vesting/` | Vite + React + Ark UI + Tailwind v4 + `zustand` + react-router + Daml | Canton Coin **vesting** dApp, published as an example. Every read and write goes through the connected CIP-0103 wallet via `canton-connect`. Its `daml/` holds the `amulet-vesting` DAR: the vesting factory, proposal, contract and residual-claim templates. They hold real Canton Coin in escrow as a Splice `LockedAmulet`, and come vendored from [`BootNodeDev/cc-vesting-contracts`](https://github.com/BootNodeDev/cc-vesting-contracts). The build fetches its Splice data-dependencies rather than committing them. `scripts/bootstrap-vesting.mjs` creates the operator and its factory. See [`example-dapps/amulet-vesting/architecture.md`](example-dapps/amulet-vesting/architecture.md) |
+| `example-dapps/token-vesting/` | Vite + React + Ark UI + Tailwind v4 + `zustand` + react-router | The same **vesting** dApp over a `DBT` instrument from [`BootNodeDev/canton-token-forge`](https://github.com/BootNodeDev/canton-token-forge), published as an example. Its `vesting` and `canton-token-forge` DARs ship as binaries in `vendor/`, so it builds no contract. `scripts/bootstrap-vesting.mjs` uploads them and creates the operator, its factory and the instrument; `scripts/registry.sh` runs the canton-token-forge registry the dApp reads the instrument from. See [`example-dapps/token-vesting/architecture.md`](example-dapps/token-vesting/architecture.md) |
 | `canton-create/` | TypeScript + Ink + React 19 + `tsdown` | The `create-canton-dappbooster` installer. Its `scaffold/daml-tooling/` and `scaffold/localnet/` scripts are also the local loop: the Splice dependency fetch, the DAR build and upload, the token mint and `dev-stack.sh`. See [`canton-create/architecture.md`](canton-create/architecture.md) |
-| `canton-connect/` | TypeScript + React 19 | wagmi-style hooks wrapping the `dapp-sdk` facade |
-| `canton-dappbooster/` | TypeScript + React 19 + `tsdown` | L2 headless UI components, zero styling, plus the theme runtime and the pure utilities under the components, exact-decimal amounts included |
+| `canton-connect/` | TypeScript + React 19 | wagmi-style hooks wrapping the `dapp-sdk` facade. See [`canton-connect/architecture.md`](canton-connect/architecture.md) |
+| `canton-dappbooster/` | TypeScript + React 19 + `tsdown` | L2 headless UI components, zero styling, plus the theme runtime and the pure utilities under the components, exact-decimal amounts included. See [`canton-dappbooster/architecture.md`](canton-dappbooster/architecture.md) |
 | `canton-theme/` | CSS | L3 plain-CSS theme: `--cnc-*` tokens + styled defaults |
 
 Each subproject's `architecture.md` is the index of its own seams. A subsystem that needs more than