diff --git a/AGENTS.md b/AGENTS.md
index 7f0d014b..615e4ebd 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,5 +1,188 @@
-# Agent Configuration
+# Agent Configuration — Canton dApp Booster
 
-This project's agent configuration lives in [`CLAUDE.md`](./CLAUDE.md).
+This file is the canonical monorepo-wide agent configuration. `CLAUDE.md`
+files are compatibility shims that point here or to a sibling `AGENTS.md`.
+Each subproject can layer its own `AGENTS.md` for stack-specific deltas:
 
-Claude Code reads `CLAUDE.md` natively. If your agent reads `AGENTS.md` (Cursor, Windsurf, etc.), load rules from `CLAUDE.md` -- it is the single source of truth for this project's conventions, stack, and working rules.
+- [`carpincho-wallet/AGENTS.md`](carpincho-wallet/AGENTS.md) — CIP-0103 wallet (Vite + React + Biome)
+- [`canton-connect-kit/AGENTS.md`](canton-connect-kit/AGENTS.md) — wagmi-style React hooks for Canton dApps
+- [`canton-barebones/wallet-service/AGENTS.md`](canton-barebones/wallet-service/AGENTS.md) — wallet-service bridge rules
+- [`dapp/e2e/AGENTS.md`](dapp/e2e/AGENTS.md) — Playwright black-box integration test rules
+- `canton-barebones/`, `dapp/daml/`, `dapp/frontend/` — see each subproject's `README.md`
+
+For the system shape (data flow, components, ports), see [`architecture.md`](architecture.md).
+
+---
+
+## Documentation Distribution
+
+Use one reader per doc type, layered by scope:
+
+| File | Reader / question | Distribution rule |
+|------|-------------------|-------------------|
+| `README.md` | Human: what is this and how do I run it? | Every independently buildable, runnable, publishable, or testable unit gets one. Subproject READMEs cover only that unit and link to the root README for shared setup. |
+| `AGENTS.md` | Agent: what local rules change how I edit 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. |
+| `CLAUDE.md` | Claude compatibility loader | Three-line shim beside every `AGENTS.md`, pointing to the sibling `AGENTS.md`. It is never canonical. |
+| `architecture.md` | Human or agent: what are the structural seams and internal subsystems? | Root always for cross-component seams. Subproject only when internals outgrow the README: three or more interacting subsystems, non-trivial control flow, or named abstractions. |
+
+Current distribution:
+
+| Scope | README | AGENTS | CLAUDE | architecture | Decision |
+|-------|--------|--------|--------|--------------|----------|
+| root | yes | yes | shim | yes | Canonical repo rules and cross-component seams. |
+| `carpincho-wallet/` | yes | yes | shim | yes | Complex wallet internals: vault, provider, extension, WalletConnect, theme, session. |
+| `canton-connect-kit/` | yes | yes | shim | yes | Public hook API, connector abstractions, provider event wiring. |
+| `canton-barebones/wallet-service/` | yes | yes | shim | no | Local bridge rules are useful; README API boundary is enough architecture for now. |
+| `dapp/e2e/` | yes | yes | shim | no | Independent Playwright package with strict black-box testing conventions. |
+| `dapp/frontend/` | yes | no | no | no | Small dApp UI; root rules and README are enough. |
+| `dapp/daml/` | yes | no | no | no | Single DAML package. |
+| `canton-barebones/` | yes | no | no | no | Docker/Bash local participant wrapper. |
+
+Subproject docs must not restate root rules. They should describe only their local delta and link upward.
+
+## Stack & Conventions (monorepo)
+
+| Category | Technology | Notes |
+|----------|-----------|-------|
+| Languages | TypeScript, DAML, Bash | TypeScript across the JS subprojects; DAML in `dapp/daml/`; Bash for canton-barebones scripts |
+| Package manager | npm | One `package-lock.json` per Node subproject; root `package.json` orchestrates via `npm --prefix <dir>` |
+| Node | 24 | Pinned via root `.nvmrc`; inherits to every Node subproject |
+| Container runtime | Docker | Used by `canton-barebones/` for the local participant + Postgres |
+| Commit linting | commitlint + husky | Enforced via root `.husky/commit-msg` |
+| Lint / format | Biome | One root `biome.json` and a single root `@biomejs/biome`; per-project specifics live in `overrides`. No per-subproject Biome install or config |
+| Pre-commit | lint-staged | Root `.lintstagedrc.mjs` runs root Biome (`biome check --write`) across `carpincho-wallet/`, `canton-connect-kit/`, `dapp/frontend/`, and `dapp/e2e/` |
+| Pre-push | tsc | Root `.husky/pre-push` runs `tsc --noEmit` per Node subproject |
+
+## Subprojects
+
+| Path | Purpose | Stack | Port |
+|------|---------|-------|------|
+| [`canton-barebones/`](canton-barebones/) | Local Canton participant + Postgres via docker-compose; deploy + health + token scripts | Docker, Bash, Node scripts | 3013/3014/3015/3016/3017/3018 |
+| [`dapp/daml/`](dapp/daml/) | `quickstart-counter` DAML model | DAML | n/a (DAR artifact) |
+| [`canton-barebones/wallet-service/`](canton-barebones/wallet-service/) | JSON-RPC bridge between the wallet and the Canton participant. Started by `npm run canton:up`. Self-mints its Canton JWT. | Node + Express + TypeScript | 3010 |
+| [`carpincho-wallet/`](carpincho-wallet/) | CIP-0103 wallet — vault, signing, WalletConnect, Chrome extension | Vite 6 + React 18 + Tailwind v4 + Biome | 3011 |
+| [`dapp/frontend/`](dapp/frontend/) | dApp UI | Vite + React + Biome | 3012 |
+| [`dapp/e2e/`](dapp/e2e/) | dApp integration tests | Playwright + TypeScript | n/a |
+| [`canton-connect-kit/`](canton-connect-kit/) | wagmi-style React hooks for connecting Canton dApps to CIP-0103 wallets | TypeScript + React 18 + Biome | n/a (library) |
+
+## Code Style
+
+- All source code in English regardless of conversation language.
+- TypeScript preferred over JavaScript across Node subprojects.
+- **No semicolons** in TypeScript / JavaScript across the repo.
+- **Comments are terse and explain *why*, not *what*.** Prefer one line. Do not restate what the code already says, narrate steps, or write multi-line prose where a short clause suffices. If the code needs a paragraph to be understood, simplify the code instead.
+- Lint and formatting are centralized in the root `biome.json`. Add project-specific rules under `overrides` keyed by path; do not create per-subproject Biome configs.
+
+## Working Rules
+
+- Use **npm** only (never pnpm or yarn).
+- Install / run inside a subproject either by `cd <subproject>` or by using `npm --prefix <subproject> run <script>`. The root `package.json` exposes orchestration shortcuts:
+  - `npm run canton:up` / `canton:down` / `canton:health` / `canton:token`
+  - `npm run build-dar -- <daml-project>` / `npm run deploy-dar -- <dar>`
+  - `npm run carpincho:build:extension`
+  - `npm run app:dev`
+- For local-stack convenience, [`scripts/dev-stack.sh`](scripts/dev-stack.sh) wraps the shortcuts above behind an interactive menu (run with no args) or direct subcommands (`docker-up`, `up`, `down`, `docker-down`, `mock-up`, `mock-down`, `extension`, `status`). The `npm` scripts remain canonical; the helper just orchestrates them. See [`README.md`](README.md).
+- Local ports are intentionally assigned in the `3010+` range (see table above). Do not change them without updating every subproject's defaults.
+- Treat `package-lock.json` files as authoritative. Do not delete or regenerate them as part of unrelated changes.
+- Do not commit `.env.local`, `node_modules`, `dist/`, `dist-extension/`, or `.claude/settings.local.json` (covered by root `.gitignore`).
+
+## Architecture
+
+See [`architecture.md`](architecture.md) for the system shape, subproject layout, data flow between components, and the port allocation table.
+
+## Testing
+
+- Each subproject owns its own test runner. Run from the subproject directory or via `npm --prefix`:
+  - `carpincho-wallet`: `npm test` (Node `node:test` + `tsx` + happy-dom)
+  - `dapp/frontend`: `npm test` (Node `node:test` with `--experimental-strip-types`)
+  - `dapp/e2e`: `npm test` (Playwright against the running local stack)
+  - `canton-barebones`: `npm test` (Node `node:test` against the scripts)
+- Cover the paths that matter — business logic, API integrations, component behaviour. Skip styling, third-party library internals, trivial getters/setters.
+
+## Commit Standards
+
+Use [Conventional Commits](https://www.conventionalcommits.org/).
+
+**Format:** `type(scope): subject`
+
+- **Scope** is optional: `feat: add login` and `feat(auth): add login` are both valid.
+- **Subject** uses imperative mood, lowercase after the colon, no trailing period.
+- **Body** (optional) is separated by a blank line and explains *what* and *why*.
+
+**Allowed prefixes** (enforced by [`commitlint.config.js`](commitlint.config.js)):
+
+| Prefix | Purpose |
+|--------|---------|
+| `feat` | New feature |
+| `fix` | Bug fix |
+| `chore` | Maintenance, dependencies, config |
+| `docs` | Documentation only |
+| `refactor` | Code change that neither fixes a bug nor adds a feature |
+| `test` | Adding or updating tests |
+| `style` | Formatting, whitespace, semicolons |
+| `ci` | CI/CD pipeline changes |
+| `perf` | Performance improvement |
+| `build` | Build system or external dependencies |
+| `revert` | Reverts a previous commit |
+| `wip` | Work in progress (avoid on main) |
+| `release` | Release-related changes |
+| `hotfix` | Emergency fix bypassing normal flow |
+
+## PR Workflow
+
+- Every PR must reference an issue (`Closes #N`).
+
+  > No related issue? Use `No related issue.` as the first line of the Summary section.
+
+- Mirror the issue's acceptance criteria in the PR.
+- Self-review your diff before requesting peer review.
+- Keep PRs small and focused — one issue, one PR.
+- PR titles use the same Conventional Commit format (`feat: add user dashboard`).
+- The `create-pr` skill at `.claude/skills/create-pr/` reads [`.github/PULL_REQUEST_TEMPLATE.md`](.github/PULL_REQUEST_TEMPLATE.md) and fills every section automatically.
+
+## Label Conventions
+
+GitHub form dropdowns (like the Priority field in issue templates) only work through the web UI. When issues are created via `gh` CLI or REST API, dropdown values become unstructured body text — not queryable, not consistent. **Labels are the API-reliable mechanism for structured metadata.**
+
+**Priority** (bugs, features, and epics):
+
+| Label | Description |
+|-------|-------------|
+| `priority: critical` | Blocking work, system down, or security issue |
+| `priority: high` | Must be addressed in current sprint |
+| `priority: medium` | Should be addressed soon |
+| `priority: low` | Nice to have, can wait |
+
+Labels are queryable: `gh issue list --label "priority: high"`.
+
+The `issue` skill at `.claude/skills/issue/` applies these labels automatically when creating issues via CLI.
+
+## Guardrails
+
+- Do not commit secrets, API keys, or credentials. `.env.local` files are gitignored — keep it that way.
+- Do not modify CI/CD pipelines without team review.
+- Do not skip tests or linting to make a build pass.
+- Do not bypass the husky hooks (`--no-verify`) unless the user explicitly asks.
+- When in doubt, ask — don't assume.
+
+## Change Strategy
+
+- Prefer small, focused diffs over broad refactors.
+- Preserve existing UX unless the task explicitly changes it.
+- Avoid introducing new patterns when a project pattern already exists.
+- Update docs only when behaviour or workflow changes.
+
+## Validation Checklist
+
+Before declaring monorepo-touching work done:
+
+- Subproject-level: `npm run lint` and `npm test` inside any subproject you touched.
+- Root-level: `git push --dry-run` exercises the pre-push tsc sweep across all Node subprojects.
+- For the full end-to-end loop (Canton up → DAR built → DAR deployed → wallet-service → wallet → dApp), follow [`README.md`](README.md) §1–6.
+
+## References
+
+- [Conventional Commits](https://www.conventionalcommits.org/)
+- [WalletConnect Sign Client](https://docs.walletconnect.com/api/sign/overview)
+- [CIP-0103 Canton wallet provider spec](https://github.com/digital-asset/canton/tree/main/community/app/src/pack/examples/04-canton-wallet)
+- [Reown (WalletConnect cloud)](https://cloud.reown.com)
diff --git a/CLAUDE.md b/CLAUDE.md
index d16ace33..59ab8b09 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,158 +1,3 @@
-# Agent Configuration — Canton dApp Booster
-
-This file defines monorepo-wide rules for agents working in this repository. Each subproject can layer its own `CLAUDE.md` for stack-specific details:
-
-- [`carpincho-wallet/CLAUDE.md`](carpincho-wallet/CLAUDE.md) — CIP-0103 wallet (Vite + React + Biome)
-- [`canton-connect-kit/README.md`](canton-connect-kit/README.md) — wagmi-style React hooks for Canton dApps
-- `canton-barebones/`, `dapp/daml/`, `dapp/frontend/`, `dapp/e2e/` — see each subproject's `README.md`
-
-For the system shape (data flow, components, ports), see [`architecture.md`](architecture.md).
-
----
-
-## Stack & Conventions (monorepo)
-
-| Category | Technology | Notes |
-|----------|-----------|-------|
-| Languages | TypeScript, DAML, Bash | TypeScript across the JS subprojects; DAML in `dapp/daml/`; Bash for canton-barebones scripts |
-| Package manager | npm | One `package-lock.json` per Node subproject; root `package.json` orchestrates via `npm --prefix <dir>` |
-| Node | 24 | Pinned via root `.nvmrc`; inherits to every Node subproject |
-| Container runtime | Docker | Used by `canton-barebones/` for the local participant + Postgres |
-| Commit linting | commitlint + husky | Enforced via root `.husky/commit-msg` |
-| Lint / format | Biome | One root `biome.json` and a single root `@biomejs/biome`; per-project specifics live in `overrides`. No per-subproject Biome install or config |
-| Pre-commit | lint-staged | Root `.lintstagedrc.mjs` runs root Biome (`biome check --write`) across `carpincho-wallet/`, `canton-connect-kit/`, `dapp/frontend/`, and `dapp/e2e/` |
-| Pre-push | tsc | Root `.husky/pre-push` runs `tsc --noEmit` per Node subproject |
-
-## Subprojects
-
-| Path | Purpose | Stack | Port |
-|------|---------|-------|------|
-| [`canton-barebones/`](canton-barebones/) | Local Canton participant + Postgres via docker-compose; deploy + health + token scripts | Docker, Bash, Node scripts | 3013/3014/3015/3016/3017/3018 |
-| [`dapp/daml/`](dapp/daml/) | `quickstart-counter` DAML model | DAML | n/a (DAR artifact) |
-| [`canton-barebones/wallet-service/`](canton-barebones/wallet-service/) | JSON-RPC bridge between the wallet and the Canton participant. Started by `npm run canton:up`. Self-mints its Canton JWT. | Node + Express + TypeScript | 3010 |
-| [`carpincho-wallet/`](carpincho-wallet/) | CIP-0103 wallet — vault, signing, WalletConnect, Chrome extension | Vite 6 + React 18 + Tailwind v4 + Biome | 3011 |
-| [`dapp/frontend/`](dapp/frontend/) | dApp UI | Vite + React + Biome | 3012 |
-| [`dapp/e2e/`](dapp/e2e/) | dApp integration tests | Playwright + TypeScript | n/a |
-| [`canton-connect-kit/`](canton-connect-kit/) | wagmi-style React hooks for connecting Canton dApps to CIP-0103 wallets | TypeScript + React 18 + Biome | n/a (library) |
-
-## Code Style
-
-- All source code in English regardless of conversation language.
-- TypeScript preferred over JavaScript across Node subprojects.
-- **No semicolons** in TypeScript / JavaScript across the repo.
-- Lint and formatting are centralized in the root `biome.json`. Add project-specific rules under `overrides` keyed by path; do not create per-subproject Biome configs.
-
-## Working Rules
-
-- Use **npm** only (never pnpm or yarn).
-- Install / run inside a subproject either by `cd <subproject>` or by using `npm --prefix <subproject> run <script>`. The root `package.json` exposes orchestration shortcuts:
-  - `npm run canton:up` / `canton:down` / `canton:health` / `canton:token`
-  - `npm run build-dar -- <daml-project>` / `npm run deploy-dar -- <dar>`
-  - `npm run carpincho:build:extension`
-  - `npm run app:dev`
-- For local-stack convenience, [`scripts/dev-stack.sh`](scripts/dev-stack.sh) wraps the shortcuts above behind an interactive menu (run with no args) or direct subcommands (`docker-up`, `up`, `down`, `docker-down`, `mock-up`, `mock-down`, `extension`, `status`). The `npm` scripts remain canonical; the helper just orchestrates them. See [`README.md`](README.md).
-- Local ports are intentionally assigned in the `3010+` range (see table above). Do not change them without updating every subproject's defaults.
-- Treat `package-lock.json` files as authoritative. Do not delete or regenerate them as part of unrelated changes.
-- Do not commit `.env.local`, `node_modules`, `dist/`, `dist-extension/`, or `.claude/settings.local.json` (covered by root `.gitignore`).
-
-## Architecture
-
-See [`architecture.md`](architecture.md) for the system shape, subproject layout, data flow between components, and the port allocation table.
-
-## Testing
-
-- Each subproject owns its own test runner. Run from the subproject directory or via `npm --prefix`:
-  - `carpincho-wallet`: `npm test` (Node `node:test` + `tsx` + happy-dom)
-  - `dapp/frontend`: `npm test` (Node `node:test` with `--experimental-strip-types`)
-  - `dapp/e2e`: `npm test` (Playwright against the running local stack)
-  - `canton-barebones`: `npm test` (Node `node:test` against the scripts)
-- Cover the paths that matter — business logic, API integrations, component behaviour. Skip styling, third-party library internals, trivial getters/setters.
-
-## Commit Standards
-
-Use [Conventional Commits](https://www.conventionalcommits.org/).
-
-**Format:** `type(scope): subject`
-
-- **Scope** is optional: `feat: add login` and `feat(auth): add login` are both valid.
-- **Subject** uses imperative mood, lowercase after the colon, no trailing period.
-- **Body** (optional) is separated by a blank line and explains *what* and *why*.
-
-**Allowed prefixes** (enforced by [`commitlint.config.js`](commitlint.config.js)):
-
-| Prefix | Purpose |
-|--------|---------|
-| `feat` | New feature |
-| `fix` | Bug fix |
-| `chore` | Maintenance, dependencies, config |
-| `docs` | Documentation only |
-| `refactor` | Code change that neither fixes a bug nor adds a feature |
-| `test` | Adding or updating tests |
-| `style` | Formatting, whitespace, semicolons |
-| `ci` | CI/CD pipeline changes |
-| `perf` | Performance improvement |
-| `build` | Build system or external dependencies |
-| `revert` | Reverts a previous commit |
-| `wip` | Work in progress (avoid on main) |
-| `release` | Release-related changes |
-| `hotfix` | Emergency fix bypassing normal flow |
-
-## PR Workflow
-
-- Every PR must reference an issue (`Closes #N`).
-
-  > No related issue? Use `No related issue.` as the first line of the Summary section.
-
-- Mirror the issue's acceptance criteria in the PR.
-- Self-review your diff before requesting peer review.
-- Keep PRs small and focused — one issue, one PR.
-- PR titles use the same Conventional Commit format (`feat: add user dashboard`).
-- The `create-pr` skill at `.claude/skills/create-pr/` reads [`.github/PULL_REQUEST_TEMPLATE.md`](.github/PULL_REQUEST_TEMPLATE.md) and fills every section automatically.
-
-## Label Conventions
-
-GitHub form dropdowns (like the Priority field in issue templates) only work through the web UI. When issues are created via `gh` CLI or REST API, dropdown values become unstructured body text — not queryable, not consistent. **Labels are the API-reliable mechanism for structured metadata.**
-
-**Priority** (bugs, features, and epics):
-
-| Label | Description |
-|-------|-------------|
-| `priority: critical` | Blocking work, system down, or security issue |
-| `priority: high` | Must be addressed in current sprint |
-| `priority: medium` | Should be addressed soon |
-| `priority: low` | Nice to have, can wait |
-
-Labels are queryable: `gh issue list --label "priority: high"`.
-
-The `issue` skill at `.claude/skills/issue/` applies these labels automatically when creating issues via CLI.
-
-## Guardrails
-
-- Do not commit secrets, API keys, or credentials. `.env.local` files are gitignored — keep it that way.
-- Do not modify CI/CD pipelines without team review.
-- Do not skip tests or linting to make a build pass.
-- Do not bypass the husky hooks (`--no-verify`) unless the user explicitly asks.
-- When in doubt, ask — don't assume.
-
-## Change Strategy
-
-- Prefer small, focused diffs over broad refactors.
-- Preserve existing UX unless the task explicitly changes it.
-- Avoid introducing new patterns when a project pattern already exists.
-- Update docs only when behaviour or workflow changes.
-
-## Validation Checklist
-
-Before declaring monorepo-touching work done:
-
-- Subproject-level: `npm run lint` and `npm test` inside any subproject you touched.
-- Root-level: `git push --dry-run` exercises the pre-push tsc sweep across all Node subprojects.
-- For the full end-to-end loop (Canton up → DAR built → DAR deployed → wallet-service → wallet → dApp), follow [`README.md`](README.md) §1–6.
-
-## References
-
-- [BootNode SDLC framework](https://github.com/BootNodeDev/bootnode-sdlc)
-- [Conventional Commits](https://www.conventionalcommits.org/)
-- [WalletConnect Sign Client](https://docs.walletconnect.com/api/sign/overview)
-- [CIP-0103 Canton wallet provider spec](https://github.com/digital-asset/canton/tree/main/community/app/src/pack/examples/04-canton-wallet)
-- [Reown (WalletConnect cloud)](https://cloud.reown.com)
+# Agent Configuration
+This project's canonical agent configuration lives in [`AGENTS.md`](./AGENTS.md).
+Claude Code reads `CLAUDE.md` natively; load `AGENTS.md` as the single source of truth.
diff --git a/architecture.md b/architecture.md
index 802d93b6..f140c581 100644
--- a/architecture.md
+++ b/architecture.md
@@ -22,19 +22,20 @@
 .
 ├── .claude/
 │   ├── settings.local.json        (gitignored)
-│   └── skills/{create-pr,issue}   SDLC agent skills (used by /sdlc:* slash commands)
+│   └── skills/{create-pr,issue}   Agent helper skills
 ├── .github/
 │   ├── ISSUE_TEMPLATE/            bug / feature / epic / spike templates
 │   └── PULL_REQUEST_TEMPLATE.md
 ├── .husky/                        commit-msg, pre-commit, pre-push hooks
-├── canton-barebones/                   Local Canton participant + Postgres + wallet-service
+├── canton-barebones/              Local Canton participant + Postgres + wallet-service
+├── canton-connect-kit/            React hooks for CIP-0103 wallet connections
 ├── carpincho-wallet/              CIP-0103 wallet (web + Chrome extension)
 ├── dapp/
 │   ├── daml/                      quickstart-counter DAML model
 │   ├── frontend/                  dApp UI
 │   └── e2e/                       Black-box integration tests
-├── CLAUDE.md                      Agent rules — monorepo-wide
-├── AGENTS.md                      Pointer to CLAUDE.md for non-Claude agents
+├── AGENTS.md                      Agent rules — monorepo-wide
+├── CLAUDE.md                      Compatibility shim pointing to AGENTS.md
 ├── architecture.md                THIS FILE
 ├── README.md                      Bring-up runbook for the local stack
 ├── commitlint.config.js           Conventional Commit enforcement
@@ -114,10 +115,10 @@ For the full bring-up sequence, follow [`README.md`](README.md).
 
 ## Further Reading
 
-- [`carpincho-wallet/architecture.md`](carpincho-wallet/architecture.md) — wallet-internal architecture: Vault crypto, CIP-0103 dispatcher, WalletConnect handlers, Chrome extension bridge, theming, auth/session
+- [`carpincho-wallet/architecture.md`](carpincho-wallet/architecture.md) — wallet-internal architecture: Vault crypto, CIP-0103 dispatcher, WalletConnect integration, Chrome extension bridge, theming, auth/session
+- [`canton-connect-kit/architecture.md`](canton-connect-kit/architecture.md) — connect-kit internals: provider context, connectors, hooks, event bridge
 - [`canton-barebones/README.md`](canton-barebones/README.md) — local participant setup
 - [`dapp/daml/README.md`](dapp/daml/README.md) — DAML model
 - [`canton-barebones/wallet-service/README.md`](canton-barebones/wallet-service/README.md) — JSON-RPC bridge
 - [`dapp/frontend/README.md`](dapp/frontend/README.md) — dApp UI
 - [`dapp/e2e/README.md`](dapp/e2e/README.md) — black-box integration tests
-- [BootNode SDLC framework](https://github.com/BootNodeDev/bootnode-sdlc) — the methodology these `CLAUDE.md` / `architecture.md` / `.github/` / `.claude/skills/` files derive from
diff --git a/canton-barebones/wallet-service/AGENTS.md b/canton-barebones/wallet-service/AGENTS.md
new file mode 100644
index 00000000..435a6bf7
--- /dev/null
+++ b/canton-barebones/wallet-service/AGENTS.md
@@ -0,0 +1,28 @@
+# Agent Configuration — wallet-service
+
+This file applies only to `canton-barebones/wallet-service/`. For monorepo-wide rules, see [`../../AGENTS.md`](../../AGENTS.md).
+
+## Scope
+
+The wallet-service is an app-agnostic Express JSON-RPC bridge between Carpincho and the local Canton participant. It holds the Canton bearer token boundary, prepares and executes transactions, proxies participant reads, and handles wallet-internal party onboarding.
+
+## Working Rules
+
+- Keep this service app-agnostic. Do not add dApp-specific routes, template IDs, or Counter-specific command logic.
+- Keep the public dApp-facing API in Carpincho. This service exposes only the HTTP bridge Carpincho needs.
+- Keep wallet-internal party onboarding under `/admin/party/*`, not on the `/rpc` dApp surface.
+- Keep `ledgerApi` as a participant-native pass-through. Do not silently translate request bodies or wrap participant responses.
+- Keep mock mode shape-compatible with the real RPC and party APIs so `server.ts` can swap implementations without adapting HTTP wiring.
+- Keep token handling inside this service boundary. Do not expose `CANTON_BACKEND_TOKEN` to the dApp or wallet UI.
+
+## Testing
+
+- Run tests with `npm test` from this package, or `npm --prefix canton-barebones/wallet-service test` from the repo root.
+- Use `node:test` with `--experimental-strip-types`, matching `package.json`.
+- Cover RPC method shape, mock mode, pending approvals, token minting, party onboarding, and HTTP status behavior.
+
+## Validation Checklist
+
+- `npm run lint`
+- `npm test`
+- `npm run build`
diff --git a/canton-barebones/wallet-service/CLAUDE.md b/canton-barebones/wallet-service/CLAUDE.md
new file mode 100644
index 00000000..59ab8b09
--- /dev/null
+++ b/canton-barebones/wallet-service/CLAUDE.md
@@ -0,0 +1,3 @@
+# Agent Configuration
+This project's canonical agent configuration lives in [`AGENTS.md`](./AGENTS.md).
+Claude Code reads `CLAUDE.md` natively; load `AGENTS.md` as the single source of truth.
diff --git a/canton-connect-kit/AGENTS.md b/canton-connect-kit/AGENTS.md
new file mode 100644
index 00000000..48488fd2
--- /dev/null
+++ b/canton-connect-kit/AGENTS.md
@@ -0,0 +1,33 @@
+# Agent Configuration — canton-connect-kit
+
+This file applies only to `canton-connect-kit/`. For monorepo-wide rules, see [`../AGENTS.md`](../AGENTS.md).
+
+## Scope
+
+`canton-connect-kit` is a React hook library for Canton dApps. It exposes a stable wagmi-style hook surface while hiding connector details for the injected CIP-0103 provider and the optional WalletConnect fallback.
+
+## Working Rules
+
+- Keep this package app-agnostic. Do not import from `dapp/`, `carpincho-wallet/`, or `canton-barebones/`.
+- Treat `src/index.ts` as the public API. New exports should be deliberate and documented in `README.md`.
+- Keep connectors narrow: `detect`, `connect`, and provider/session wiring only.
+- Keep hooks thin. Hooks should read from `ConnectKitProvider` context and expose lifecycle state; shared state transitions belong in `ConnectKitProvider.tsx`.
+- Keep WalletConnect code lazy-loaded so extension-only dApps do not pay the fallback bundle cost.
+- Use relative imports with explicit `.ts` / `.tsx` extensions, matching the current package style.
+
+## Architecture
+
+See [`architecture.md`](architecture.md) for the provider, connector, hook, and event-flow structure.
+
+## Testing
+
+- Run tests with `npm test` from this package, or `npm --prefix canton-connect-kit test` from the repo root.
+- Use the configured `node:test` + `tsx` setup.
+- Prefer connector factories and test doubles over importing wallet or dApp source.
+- Cover context state transitions, connector selection, event subscriptions, and hook return values.
+
+## Validation Checklist
+
+- `npm run lint`
+- `npm test`
+- `npm run typecheck`
diff --git a/canton-connect-kit/CLAUDE.md b/canton-connect-kit/CLAUDE.md
new file mode 100644
index 00000000..59ab8b09
--- /dev/null
+++ b/canton-connect-kit/CLAUDE.md
@@ -0,0 +1,3 @@
+# Agent Configuration
+This project's canonical agent configuration lives in [`AGENTS.md`](./AGENTS.md).
+Claude Code reads `CLAUDE.md` natively; load `AGENTS.md` as the single source of truth.
diff --git a/canton-connect-kit/README.md b/canton-connect-kit/README.md
index 50348be7..eccbf69c 100644
--- a/canton-connect-kit/README.md
+++ b/canton-connect-kit/README.md
@@ -26,6 +26,9 @@ artifact. The hook signatures are stable enough to depend on; the
 implementation underneath may swap to delegate to `@partylayer/sdk` if that
 ecosystem matures.
 
+For the full local stack that consumes this package, follow the root
+[quick start](../README.md#quick-start).
+
 ## Hook surface
 
 ```tsx
@@ -76,17 +79,7 @@ function Counter() {
 
 ## Architecture
 
-- `ConnectKitProvider` — React context holding the active `DappClient`,
-  the current party, the connection status, and the wallet-lock flag. All
-  hooks read from this context.
-- `connectors/extension.ts` — uses `@canton-network/dapp-sdk`'s
-  `ExtensionAdapter`. Detects providers announced via
-  `canton:requestProvider` / `canton:announceProvider`.
-- `connectors/walletconnect.ts` — WalletConnect Sign Client (opt-in
-  fallback). Returns the same `DappClient` shape.
-- Hooks subscribe to wallet-pushed events
-  (`accountsChanged`, `txChanged`, `connected`, `statusChanged`) and expose
-  them as React state.
+See [`architecture.md`](architecture.md) for provider, connector, hook, and event-flow structure.
 
 ## Relationship to PartyLayer
 
diff --git a/canton-connect-kit/architecture.md b/canton-connect-kit/architecture.md
new file mode 100644
index 00000000..e57d9683
--- /dev/null
+++ b/canton-connect-kit/architecture.md
@@ -0,0 +1,92 @@
+# Architecture Overview — canton-connect-kit
+
+`canton-connect-kit` is the React adapter layer between Canton dApps and CIP-0103 wallets. It gives consumers wagmi-style hooks while normalizing two wallet transports: the injected browser extension provider and optional WalletConnect.
+
+## Project Structure
+
+```
+src/
+  ConnectKitProvider.tsx       React context, connection lifecycle, event wiring
+  connectors/
+    extension.ts               Injected CIP-0103 provider detection and event bridge
+    walletconnect.ts           WalletConnect Sign Client fallback provider
+  hooks/
+    useConnect.ts              Connect/disconnect lifecycle
+    useExecute.ts              prepareExecuteAndWait wrapper and tx state
+    useLedger.ts               ledgerApi pass-through
+    useParty.ts                active party state
+    useSignMessage.ts          signMessage request state
+    useWalletStatus.ts         lock/connect status state
+  lib/
+    walletAccount.ts           Wallet account normalization and primary selection
+  types.ts                     Public config, connector, party, and status types
+  index.ts                     Public package exports
+```
+
+## Data Flow
+
+```mermaid
+flowchart TD
+  app["Consumer dApp"]
+  hooks["Hooks<br/>useConnect / useParty / useExecute / useLedger"]
+  provider["ConnectKitProvider"]
+  extension["Extension connector<br/>CIP-0103 injected provider"]
+  wc["WalletConnect connector<br/>optional fallback"]
+  client["@canton-network/dapp-sdk<br/>DappClient"]
+  wallet["CIP-0103 wallet"]
+
+  app --> hooks
+  hooks --> provider
+  provider --> extension
+  provider --> wc
+  extension --> client
+  wc --> client
+  client --> wallet
+  wallet -->|"accountsChanged / txChanged / connected / statusChanged"| client
+  client --> provider
+```
+
+## Key Abstractions
+
+### `ConnectKitProvider`
+
+`ConnectKitProvider.tsx` owns all shared state: active `DappClient`, party, connection status, lock status, WalletConnect pairing URI, last transaction snapshot, and connection errors. Hooks should stay as readers over this context.
+
+Connection modes:
+
+- `extension`: require the injected browser provider.
+- `walletconnect`: require `walletConnectProjectId` and pair through WalletConnect.
+- `preferred`: try the extension first, then fall back to WalletConnect.
+
+The provider wires wallet-pushed events once per connected client and tears them down on disconnect or unmount.
+
+### Extension Connector
+
+`connectors/extension.ts` uses `@canton-network/dapp-sdk`'s `ExtensionAdapter` to detect Carpincho through `canton:requestProvider` / `canton:announceProvider`.
+
+Carpincho also emits `SPLICE_WALLET_EVENT` messages so wallet-pushed events can reach the canonical provider's `emit` path. The connector translates those page messages into provider events for `accountsChanged`, `txChanged`, `connected`, and `statusChanged`.
+
+### WalletConnect Connector
+
+`connectors/walletconnect.ts` implements a `Provider` around `@walletconnect/sign-client`. The Sign Client is dynamically imported so extension-only consumers do not load WalletConnect code.
+
+The connector maps canonical CIP-0103 requests onto `canton_*` WalletConnect methods and forwards `session_event` messages to provider listeners.
+
+### Hooks
+
+Each hook exposes one consumer-facing concern:
+
+| Hook | Responsibility |
+|------|----------------|
+| `useConnect` | Start/stop the active wallet connection and expose pairing / error state. |
+| `useParty` | Return the current primary party and connection status. |
+| `useWalletStatus` | Return lock/connect status derived from wallet events. |
+| `useSignMessage` | Wrap `signMessage` as a promise lifecycle. |
+| `useExecute` | Wrap `prepareExecuteAndWait` and expose transaction status updates. |
+| `useLedger` | Expose raw `ledgerApi` for reads not covered by higher-level hooks. |
+
+## Boundaries
+
+This package must not depend on the scaffold's dApp, wallet, or wallet-service internals. Its stable boundary is the CIP-0103 provider surface plus `@canton-network/dapp-sdk`.
+
+For the full local stack around this package, see the root [`architecture.md`](../architecture.md).
diff --git a/carpincho-wallet/AGENTS.md b/carpincho-wallet/AGENTS.md
index 7f0d014b..0863064e 100644
--- a/carpincho-wallet/AGENTS.md
+++ b/carpincho-wallet/AGENTS.md
@@ -1,5 +1,62 @@
-# Agent Configuration
+# Agent Configuration — carpincho-wallet
 
-This project's agent configuration lives in [`CLAUDE.md`](./CLAUDE.md).
+This file applies only to `carpincho-wallet/`. For monorepo-wide rules (commit standards, PR workflow, label conventions, guardrails, change strategy), see [`../AGENTS.md`](../AGENTS.md).
 
-Claude Code reads `CLAUDE.md` natively. If your agent reads `AGENTS.md` (Cursor, Windsurf, etc.), load rules from `CLAUDE.md` -- it is the single source of truth for this project's conventions, stack, and working rules.
+---
+
+## Stack & Conventions
+
+| Category | Technology | Notes |
+|----------|-----------|-------|
+| Language | TypeScript (strict mode) | |
+| Framework | Vite 6 + React 18 | SPA; also builds as a Chrome extension |
+| Styling | Tailwind CSS v4 | `@tailwindcss/vite` plugin; utility classes inline in JSX; `src/index.css` declares semantic CSS variables on `:root` / `[data-theme='dark']`, rebinds the `dark:` variant via `@custom-variant`, exposes tokens to Tailwind through `@theme inline`, and holds `@layer base` resets plus named keyframes (`fade-in`, `slide-down-and-fade`, `slide-up-and-fade`, `sheet-up`, `sheet-slide-right`, `slide-in-right`, `slide-in-left`, `soft-pulse`, `drift`). A brand-tinted radial top-glow (`--bg-radial`) sits behind the page; there is no paper-grain overlay |
+| Theming | Light / Dark / System selector in the drawer menu (dappbooster brand palette) | `src/theme/ThemeProvider.tsx` owns a persisted `mode` (`light` \| `dark` \| `system`, default `system`), exposes `{ mode, setMode }` via `useTheme()`, resolves `system` against `prefers-color-scheme` (and re-resolves on media changes while in `system`), and writes the resolved `data-theme` on `<html>` after mount. The selector lives in the drawer at Settings → Theme (`src/components/menu/ThemeMenu.tsx`); there is no header toggle. Use semantic colour utilities (`bg-surface`, `text-foreground`, `border-border`, `bg-primary-soft`, `bg-scrim`, etc.) so styles flip automatically. The dark theme is cool navy (`#14152b`) matching `dappbooster-canton-landing`; the light theme is neutral grey (`#f7f7f7`, primary `#692581`) matching the `dAppBooster` boilerplate. A shared purple→pink brand accent — `--bg-gradient-brand` (`linear-gradient(135deg, #c670e5, #e71d73)`) plus `--shadow-glow` — reveals on primary-button hover and tints the hero wordmark. `--color-success` is green (used for the connected-state indicator); `--color-scrim` is the theme-aware overlay tint used by modal/sheet backdrops |
+| Fonts | Self-hosted via `@fontsource-variable/manrope`, `@fontsource-variable/jetbrains-mono` | Imported once in `src/main.tsx`; works offline in the extension popup. Manrope is the entire UI: `font-display` for hero wordmarks, view-level headings, section markers (heavier weight for hierarchy) and `font-sans` for UI chrome / body / labels / buttons. `font-mono` (JetBrains Mono) is for party IDs, hashes, RPC URLs, JSON payloads, status eyebrows |
+| UI primitives | Radix UI | `@radix-ui/react-dialog`, `@radix-ui/react-tabs`, `@radix-ui/react-toast`, `@radix-ui/react-tooltip` for modals (incl. bottom sheets), tabs, toasts, and tooltips (auto-positioning with collision detection; `TooltipProvider` mounted once in `App.tsx`); styled with Tailwind via `data-[state=...]` and `data-[highlighted]` variants and animated through the `animate-*` tokens above. **When adding a new interactive component, check the [Radix UI primitives catalogue](https://www.radix-ui.com/primitives) first — prefer a Radix primitive over a hand-rolled implementation.** Local primitives in `src/components/ui/` (Button family, TextInput, PasswordInput, Alert (info / error / warning / success variants), Card, AccountAvatar, PendingActionCard, Sheet, Tabs, OptionList, Stepper, DangerConfirm, MenuRow, ToastProvider, Tooltip) compose Tailwind utilities + Radix where applicable; reuse them before writing one-off styling. `TextInput` and `PasswordInput` accept an `error?: boolean` prop that applies a danger border + persistent focus ring (`--shadow-focus-danger`) and sets `aria-invalid`; use this for field-level error state instead of wrapping in an `Alert`. Icon SVG literals live in [`src/components/ui/icons.tsx`](src/components/ui/icons.tsx) (`X_ICON`, `BACK_ICON`, `MENU_ICON`, `CHECK_ICON`, `COPY_ICON`, `COG_ICON`, `EYE_ICON`, `EYE_OFF_ICON`, `INFO_ICON`, `ALERT_TRIANGLE_ICON`, `ALERT_CIRCLE_ICON`, `SPINNER_ICON`, `SEARCH_ICON`, `DISCONNECT_ICON`, `CHEVRON_DOWN_ICON`, `CHEVRON_RIGHT_ICON`, `RECEIPT_ICON`, `TRASH_ICON`, `WALLET_CONNECT_ICON`); add new icons there instead of inlining `<svg>`. Custom width/height tokens (`w-popup`, `w-drawer`, `max-h-sheet`) are declared as `@utility` in `src/index.css`. `Sheet` wraps Radix Dialog with the shared overlay, title, and close-button chrome and takes `side: 'bottom' | 'right' | 'center'` (default `'bottom'`); the bottom variant uses `animate-sheet-up`, the right variant uses `animate-sheet-slide-right` (caps at 400px wide clamped by `100vw`, full-height, top-aligned content), and the center variant renders a centered modal dialog (used for account management, approval prompts, and danger confirmations) -- always use `Sheet` for sheet-style flows. `Button.tsx` also exports `GHOST_BUTTON_CLASS` and `ICON_BUTTON_CLASS` for places that need the interactive base without the button element. Larger shared building blocks live one level up in `src/components/` (`WelcomeHero` for the Setup/Unlock hero; `AccountCard`, `HomeTabs`, `ConnectionFooter` compose the Home view. The Home view is a fixed-height (`h-screen`) flex shell: the account selector and footer (no longer `fixed` — it lives in the column flow, bled full-width with `-mx-3`) stay pinned while only the active tab body scrolls. `HomeTabs` (the `Tabs` underline bar acts as the view title — no heading) holds `ActivityList` (executed transactions as MetaMask-style rows grouped by day, each opening a centered detail `Sheet`) and `AssetsPanel` (a mocked empty placeholder). WalletConnect URI pairing lives in the drawer via `WalletConnectMenu`, the first root menu screen, web-only; `PasswordStrengthIndicator` renders the live strength meter; `NewPasswordFields` owns the "new password + confirm + strength meter + validity callback" trio used by both the Setup form and the change-password form -- callers control the visible-vs-aria label mode and receive validity via `onValidityChange`). ConnectionSettings renders as a bottom `Sheet` from `HomeView`; account management (add / remove / switch) lives in `AccountsDialog`, a centered `Sheet` opened from `AccountCard`. Neither is a full-view replacement. `MenuSheet` (the burger-button drawer, right-anchored, 400px wide capped at `100vw`) drives multi-screen flows by toggling an internal `Screen` state inside one `Sheet`; every new sub-section in the drawer must be added as another `Screen` entry (drill-down with title + back + close + `animate-slide-in-*` transitions) — no accordion-style expansion |
+| Feedback | Toast vs inline Alert vs error prop | Transient system feedback (action results, async errors, network failures, copy confirmations) renders via `toast.*` from [`@/components/ui/toast.ts`](src/components/ui/toast.ts) — never as inline `Alert`. Mount the `ToastProvider` once in `App.tsx`. Field-level error state (mismatched passwords, wrong current password on a verify step, invalid input) uses the `error` prop on `TextInput` / `PasswordInput` (danger border + `aria-invalid`); pair it with `aria-errormessage` pointing at a sibling caption `<p>` when there is a human-readable reason to render. Inline `Alert` is reserved for form-level errors that cannot be attributed to a single field and for persistent contextual hints inside cards. All callers (React components, WalletConnect handlers in `src/wc/`, vault errors, extension bridge) use the imperative `toast` import directly. Variant durations: non-critical variants (`info` / `success` / `warning`) auto-dismiss after 3 s; only `error` (must-read) persists until dismissed. Identical messages collapse — emitting a string message that matches a visible toast of the same variant replaces it with a fresh entry (so rapid repeats like copy clicks collapse to a single toast and restart its timer); distinct messages of the same variant (a copy confirmation vs an RPC test result) stack separately. Toasts render as elevated `bg-surface` cards (border + `shadow-popover`) with a variant-tinted icon badge and a left accent rail, sized to the app content width (`w-popup`). Max 3 visible, top-center, newest on top |
+| Package manager | npm | lockfile: `package-lock.json` |
+| Linting | Biome (root config) | Single root `biome.json` + root `@biomejs/biome`; this project's rules (`@/` alias enforcement, Tailwind CSS parsing) live in a path `override`. Enforced via the root pre-commit hook; run `npm run lint` manually |
+| Node | 24 | inherited from `../.nvmrc` |
+| Naming | camelCase vars/functions, PascalCase components/types, kebab-case files | |
+
+## Code Style
+
+- **Semicolons:** no
+- **Quotes:** single
+- **Indent:** 2 spaces
+- **Imports:** every import that resolves inside `src/` must use the `@/*` alias (e.g. `import { Foo } from '@/components/Foo'`); relative `./` and `../` paths are banned by Biome's `style/noRestrictedImports`. Do **not** add the `.ts` / `.tsx` extension on import paths — `moduleResolution: bundler` (Vite + the tsx test loader) resolves extensionless. Because resolution is extensionless, two modules in the same directory must not differ only by case and extension (e.g. `Toast.tsx` vs `toast.ts`), or the import becomes ambiguous on a case-insensitive filesystem. The alias is declared in `tsconfig.app.json`, `test/tsconfig.json`, and `vite.config.ts`
+- **Functional style:** prefer `const` with expression-returning forms (ternaries, IIFEs, helper functions, lookup objects, destructured ternaries) over `let` + reassignment. Reach for `let` only when no clean expression form exists.
+
+## Working Rules
+
+- Use **npm** only (never pnpm or yarn)
+- Use the `@/*` alias for every import that resolves inside `src/`. Relative `./` / `../` paths are linter errors
+- Build outputs: `dist/` for the web build and `dist-extension/` for the Chrome extension (`npm run build:extension` locally, or `npm run carpincho:build:extension` from the repo root)
+- Dev server: `http://localhost:3011`
+
+## Architecture
+
+See [`architecture.md`](architecture.md) for project structure, data flow, and key abstractions inside the wallet. For how the wallet plugs into the rest of the monorepo (dApp, wallet-service, canton-barebones), see [`../architecture.md`](../architecture.md).
+
+## Testing
+
+- **Framework:** Node built-in `node:test` with `tsx` as the loader (transforms TS + TSX, automatic React JSX runtime)
+- **DOM environment:** `@happy-dom/global-registrator` bootstrapped in [`test/setup-dom.ts`](test/setup-dom.ts) for React Testing Library interaction tests
+- **Test config:** [`test/tsconfig.json`](test/tsconfig.json) sets `jsx: react-jsx`; `TSX_TSCONFIG_PATH` in the test script points tsx at it
+- **Run tests:** `npm test`
+- **What to test:** Business logic, API integrations, component behavior
+- **What not to test:** Styling, third-party library internals, trivial getters/setters
+- **Coverage:** Aim for meaningful coverage, not a number. Cover the paths that matter.
+
+## Validation Checklist
+
+- `npm run lint`
+- `npm test`
+- `npm run build` (when feasible for runtime-impacting changes)
+
+## References
+
+- [WalletConnect Sign Client](https://docs.walletconnect.com/api/sign/overview)
+- [CIP-0103 Canton wallet provider spec](https://github.com/digital-asset/canton/tree/main/community/app/src/pack/examples/04-canton-wallet)
+- [Reown (WalletConnect cloud)](https://cloud.reown.com)
diff --git a/carpincho-wallet/CLAUDE.md b/carpincho-wallet/CLAUDE.md
index ac775e99..59ab8b09 100644
--- a/carpincho-wallet/CLAUDE.md
+++ b/carpincho-wallet/CLAUDE.md
@@ -1,62 +1,3 @@
-# Agent Configuration — carpincho-wallet
-
-This file applies only to `carpincho-wallet/`. For monorepo-wide rules (commit standards, PR workflow, label conventions, guardrails, change strategy), see [`../CLAUDE.md`](../CLAUDE.md).
-
----
-
-## Stack & Conventions
-
-| Category | Technology | Notes |
-|----------|-----------|-------|
-| Language | TypeScript (strict mode) | |
-| Framework | Vite 6 + React 18 | SPA; also builds as a Chrome extension |
-| Styling | Tailwind CSS v4 | `@tailwindcss/vite` plugin; utility classes inline in JSX; `src/index.css` declares semantic CSS variables on `:root` / `[data-theme='dark']`, rebinds the `dark:` variant via `@custom-variant`, exposes tokens to Tailwind through `@theme inline`, and holds `@layer base` resets plus named keyframes (`fade-in`, `slide-down-and-fade`, `slide-up-and-fade`, `sheet-up`, `sheet-slide-right`, `slide-in-right`, `slide-in-left`, `soft-pulse`, `drift`). A brand-tinted radial top-glow (`--bg-radial`) sits behind the page; there is no paper-grain overlay |
-| Theming | Light / Dark / System selector in the drawer menu (dappbooster brand palette) | `src/theme/ThemeProvider.tsx` owns a persisted `mode` (`light` \| `dark` \| `system`, default `system`), exposes `{ mode, setMode }` via `useTheme()`, resolves `system` against `prefers-color-scheme` (and re-resolves on media changes while in `system`), and writes the resolved `data-theme` on `<html>` after mount. The selector lives in the drawer at Settings → Theme (`src/components/menu/ThemeMenu.tsx`); there is no header toggle. Use semantic colour utilities (`bg-surface`, `text-foreground`, `border-border`, `bg-primary-soft`, `bg-scrim`, etc.) so styles flip automatically. The dark theme is cool navy (`#14152b`) matching `dappbooster-canton-landing`; the light theme is neutral grey (`#f7f7f7`, primary `#692581`) matching the `dAppBooster` boilerplate. A shared purple→pink brand accent — `--bg-gradient-brand` (`linear-gradient(135deg, #c670e5, #e71d73)`) plus `--shadow-glow` — reveals on primary-button hover and tints the hero wordmark. `--color-success` is green (used for the connected-state indicator); `--color-scrim` is the theme-aware overlay tint used by modal/sheet backdrops |
-| Fonts | Self-hosted via `@fontsource-variable/manrope`, `@fontsource-variable/jetbrains-mono` | Imported once in `src/main.tsx`; works offline in the extension popup. Manrope is the entire UI: `font-display` for hero wordmarks, view-level headings, section markers (heavier weight for hierarchy) and `font-sans` for UI chrome / body / labels / buttons. `font-mono` (JetBrains Mono) is for party IDs, hashes, RPC URLs, JSON payloads, status eyebrows |
-| UI primitives | Radix UI | `@radix-ui/react-dialog`, `@radix-ui/react-tabs`, `@radix-ui/react-toast`, `@radix-ui/react-tooltip` for modals (incl. bottom sheets), tabs, toasts, and tooltips (auto-positioning with collision detection; `TooltipProvider` mounted once in `App.tsx`); styled with Tailwind via `data-[state=...]` and `data-[highlighted]` variants and animated through the `animate-*` tokens above. **When adding a new interactive component, check the [Radix UI primitives catalogue](https://www.radix-ui.com/primitives) first — prefer a Radix primitive over a hand-rolled implementation.** Local primitives in `src/components/ui/` (Button family, TextInput, PasswordInput, Alert (info / error / warning / success variants), Card, AccountAvatar, PendingActionCard, Sheet, Tabs, OptionList, Stepper, DangerConfirm, MenuRow, ToastProvider, Tooltip) compose Tailwind utilities + Radix where applicable; reuse them before writing one-off styling. `TextInput` and `PasswordInput` accept an `error?: boolean` prop that applies a danger border + persistent focus ring (`--shadow-focus-danger`) and sets `aria-invalid`; use this for field-level error state instead of wrapping in an `Alert`. Icon SVG literals live in [`src/components/ui/icons.tsx`](src/components/ui/icons.tsx) (`X_ICON`, `BACK_ICON`, `MENU_ICON`, `CHECK_ICON`, `COPY_ICON`, `EYE_ICON`, `EYE_OFF_ICON`, `SPINNER_ICON`); add new icons there instead of inlining `<svg>`. Custom width/height tokens (`w-popup`, `w-drawer`, `max-h-sheet`) are declared as `@utility` in `src/index.css`. `Sheet` wraps Radix Dialog with the shared overlay, title, and close-button chrome and takes `side: 'bottom' | 'right'` (default `'bottom'`); the bottom variant uses `animate-sheet-up`, the right variant uses `animate-sheet-slide-right`, caps at 400px wide (clamped by `100vw`), full-height, top-aligned content -- always use `Sheet` for sheet-style flows. `Button.tsx` also exports `GHOST_BUTTON_CLASS` and `ICON_BUTTON_CLASS` for places that need the interactive base without the button element. Larger shared building blocks live one level up in `src/components/` (`WelcomeHero` for the Setup/Unlock hero; `AccountCard`, `HomeTabs`, `ConnectionFooter` compose the Home view. The Home view is a fixed-height (`h-screen`) flex shell: the account selector and footer (no longer `fixed` — it lives in the column flow, bled full-width with `-mx-3`) stay pinned while only the active tab body scrolls. `HomeTabs` (the `Tabs` underline bar acts as the view title — no heading) holds `ActivityList` (executed transactions as MetaMask-style rows grouped by day, each opening a centered detail `Sheet`) and `AssetsPanel` (a mocked empty placeholder). WalletConnect URI pairing lives in the drawer via `WalletConnectMenu`, the first root menu screen, web-only; `PasswordStrengthIndicator` renders the live strength meter; `NewPasswordFields` owns the "new password + confirm + strength meter + validity callback" trio used by both the Setup form and the change-password form -- callers control the visible-vs-aria label mode and receive validity via `onValidityChange`). AddAccount and ConnectionSettings render as bottom `Sheet` instances from `HomeView`, not as full-view replacements. `MenuSheet` (the burger-button drawer, right-anchored, 400px wide capped at `100vw`) drives multi-screen flows by toggling an internal `Screen` state inside one `Sheet`; every new sub-section in the drawer must be added as another `Screen` entry (drill-down with title + back + close + `animate-slide-in-*` transitions) — no accordion-style expansion |
-| Feedback | Toast vs inline Alert vs error prop | Transient system feedback (action results, async errors, network failures, copy confirmations) renders via `toast.*` from [`@/components/ui/toast.ts`](src/components/ui/toast.ts) — never as inline `Alert`. Mount the `ToastProvider` once in `App.tsx`. Field-level error state (mismatched passwords, wrong current password on a verify step, invalid input) uses the `error` prop on `TextInput` / `PasswordInput` (danger border + `aria-invalid`); pair it with `aria-errormessage` pointing at a sibling caption `<p>` when there is a human-readable reason to render. Inline `Alert` is reserved for form-level errors that cannot be attributed to a single field and for persistent contextual hints inside cards. All callers (React components, WalletConnect handlers in `src/wc/`, vault errors, extension bridge) use the imperative `toast` import directly. Variant durations: non-critical variants (`info` / `success` / `warning`) auto-dismiss after 3 s; only `error` (must-read) persists until dismissed. Identical messages collapse — emitting a string message that matches a visible toast of the same variant replaces it with a fresh entry (so rapid repeats like copy clicks collapse to a single toast and restart its timer); distinct messages of the same variant (a copy confirmation vs an RPC test result) stack separately. Toasts render as elevated `bg-surface` cards (border + `shadow-popover`) with a variant-tinted icon badge and a left accent rail, sized to the app content width (`w-popup`). Max 3 visible, top-center, newest on top |
-| Package manager | npm | lockfile: `package-lock.json` |
-| Linting | Biome (root config) | Single root `biome.json` + root `@biomejs/biome`; this project's rules (`@/` alias enforcement, Tailwind CSS parsing) live in a path `override`. Enforced via the root pre-commit hook; run `npm run lint` manually |
-| Node | 24 | inherited from `../.nvmrc` |
-| Naming | camelCase vars/functions, PascalCase components/types, kebab-case files | |
-
-## Code Style
-
-- **Semicolons:** no
-- **Quotes:** single
-- **Indent:** 2 spaces
-- **Imports:** every import that resolves inside `src/` must use the `@/*` alias (e.g. `import { Foo } from '@/components/Foo'`); relative `./` and `../` paths are banned by Biome's `style/noRestrictedImports`. Do **not** add the `.ts` / `.tsx` extension on import paths — `moduleResolution: bundler` (Vite + the tsx test loader) resolves extensionless. Because resolution is extensionless, two modules in the same directory must not differ only by case and extension (e.g. `Toast.tsx` vs `toast.ts`), or the import becomes ambiguous on a case-insensitive filesystem. The alias is declared in `tsconfig.app.json`, `test/tsconfig.json`, and `vite.config.ts`
-- **Functional style:** prefer `const` with expression-returning forms (ternaries, IIFEs, helper functions, lookup objects, destructured ternaries) over `let` + reassignment. Reach for `let` only when no clean expression form exists.
-
-## Working Rules
-
-- Use **npm** only (never pnpm or yarn)
-- Use the `@/*` alias for every import that resolves inside `src/`. Relative `./` / `../` paths are linter errors
-- Build outputs: `dist/` for the web build and `dist-extension/` for the Chrome extension (`npm run build:extension` locally, or `npm run carpincho:build:extension` from the repo root)
-- Dev server: `http://localhost:3011`
-
-## Architecture
-
-See [`architecture.md`](architecture.md) for project structure, data flow, and key abstractions inside the wallet. For how the wallet plugs into the rest of the monorepo (dApp, wallet-service, canton-barebones), see [`../architecture.md`](../architecture.md).
-
-## Testing
-
-- **Framework:** Node built-in `node:test` with `tsx` as the loader (transforms TS + TSX, automatic React JSX runtime)
-- **DOM environment:** `@happy-dom/global-registrator` bootstrapped in [`test/setup-dom.ts`](test/setup-dom.ts) for React Testing Library interaction tests
-- **Test config:** [`test/tsconfig.json`](test/tsconfig.json) sets `jsx: react-jsx`; `TSX_TSCONFIG_PATH` in the test script points tsx at it
-- **Run tests:** `npm test`
-- **What to test:** Business logic, API integrations, component behavior
-- **What not to test:** Styling, third-party library internals, trivial getters/setters
-- **Coverage:** Aim for meaningful coverage, not a number. Cover the paths that matter.
-
-## Validation Checklist
-
-- `npm run lint`
-- `npm test`
-- `npm run build` (when feasible for runtime-impacting changes)
-
-## References
-
-- [WalletConnect Sign Client](https://docs.walletconnect.com/api/sign/overview)
-- [CIP-0103 Canton wallet provider spec](https://github.com/digital-asset/canton/tree/main/community/app/src/pack/examples/04-canton-wallet)
-- [Reown (WalletConnect cloud)](https://cloud.reown.com)
+# Agent Configuration
+This project's canonical agent configuration lives in [`AGENTS.md`](./AGENTS.md).
+Claude Code reads `CLAUDE.md` natively; load `AGENTS.md` as the single source of truth.
diff --git a/carpincho-wallet/architecture.md b/carpincho-wallet/architecture.md
index ecb433db..467708a9 100644
--- a/carpincho-wallet/architecture.md
+++ b/carpincho-wallet/architecture.md
@@ -3,7 +3,7 @@
 <!-- Keep this document up to date as the system evolves. It captures structural
      knowledge that helps both humans onboarding and agents building context at
      session start. Focus on the "shape" of the system — not usage instructions
-     (that's CLAUDE.md) or API docs (that's code comments). -->
+     (that's AGENTS.md) or API docs (that's code comments). -->
 
 ## Tech Stack
 
@@ -13,7 +13,7 @@
 | Language | TypeScript 5.9 (strict) | |
 | Wallet protocol | Injected CIP-0103 provider + optional WalletConnect Sign Client 2.x | Browser extension provider events by default; Reown relay only for WalletConnect fallback |
 | Cryptography | @noble/ed25519 3.x, @noble/hashes 1.x | Ed25519 signing; PBKDF2 + AES-GCM vault |
-| UI primitives | React 18 + Radix UI | `@radix-ui/react-{dialog,tabs,toast,tooltip}` for modals/tabs/toasts/tooltips; local wrappers (Button family, TextInput, PasswordInput, Alert, Card, AccountAvatar, PendingActionCard, Sheet, Tabs, OptionList, Stepper, DangerConfirm, MenuRow, ToastProvider, Tooltip) for static visuals and Radix re-skins; shared icon SVG literals live in `src/components/ui/icons.tsx`; `Sheet` is the shared Radix Dialog scaffold for sheet-style flows (overlay, title, close button) and takes `side: 'bottom' | 'right'` (default `'bottom'`; right opens as a 400px-wide top-aligned drawer clamped by `100vw`); `ToastProvider` and `TooltipProvider` are both mounted once in `App.tsx`; `TextInput` and `PasswordInput` accept `error?: boolean` which applies a danger border, a persistent focus ring, and `aria-invalid`; `Button.tsx` exports `GHOST_BUTTON_CLASS` / `ICON_BUTTON_CLASS` for ad-hoc buttons (e.g. `PasswordInput`'s show/hide button) |
+| UI primitives | React 18 + Radix UI | `@radix-ui/react-{dialog,tabs,toast,tooltip}` for modals/tabs/toasts/tooltips; local wrappers (Button family, TextInput, PasswordInput, Alert, Card, AccountAvatar, PendingActionCard, Sheet, Tabs, OptionList, Stepper, DangerConfirm, MenuRow, ToastProvider, Tooltip) for static visuals and Radix re-skins; shared icon SVG literals live in `src/components/ui/icons.tsx`; `Sheet` is the shared Radix Dialog scaffold for sheet-style flows (overlay, title, close button) and takes `side: 'bottom' | 'right' | 'center'` (default `'bottom'`; right opens as a 400px-wide top-aligned drawer clamped by `100vw`; center renders a centered modal dialog); `ToastProvider` and `TooltipProvider` are both mounted once in `App.tsx`; `TextInput` and `PasswordInput` accept `error?: boolean` which applies a danger border, a persistent focus ring, and `aria-invalid`; `Button.tsx` exports `GHOST_BUTTON_CLASS` / `ICON_BUTTON_CLASS` for ad-hoc buttons (e.g. `PasswordInput`'s show/hide button) |
 | Styling | Tailwind CSS v4 (`@tailwindcss/vite`) | Utility classes inline in JSX; `src/index.css` declares CSS-variable tokens on `:root` / `[data-theme="dark"]` and exposes them to Tailwind through `@theme inline`; `@layer base` holds global resets; Radix `data-[state=...]` and `data-[highlighted]` attrs drive interactive variants |
 | Fonts | `@fontsource-variable/manrope`, `@fontsource-variable/jetbrains-mono` | Self-hosted variable fonts so the extension popup works offline. Manrope is the whole UI: `font-sans` (UI chrome, body, labels, buttons) and `font-display` (hero wordmarks, view headings, section markers — heavier weight for hierarchy). JetBrains Mono is `font-mono` (party IDs, hashes, RPC URLs, JSON payloads) |
 | Theming | Light / dark / system selector in the drawer menu | `src/theme/ThemeProvider.tsx` owns a persisted `mode` (`light` \| `dark` \| `system`, default `system`), resolves `system` against `prefers-color-scheme` (re-resolving on media changes while in `system`), and writes the resolved `data-theme` on `<html>` after mount; the selector lives at Settings → Theme (`src/components/menu/ThemeMenu.tsx`) with no header toggle; the Tailwind `dark:` variant is rebound to `[data-theme='dark']` via `@custom-variant` |
@@ -25,7 +25,7 @@
 ```
 src/
   api/              JSON-RPC client for the external wallet-service backend
-  assets/           SVG assets (hero illustration)
+  assets/           SVG brand assets (carpincho-logo.svg)
   components/       Shared UI components (Logo, Header, WelcomeHero, AccountCard,
                     AccountRow, AccountListRow, AccountsDialog, CopyPartyIdButton,
                     ActivityList, HomeTabs, AssetsPanel, ConnectionFooter,
@@ -42,14 +42,18 @@ src/
   extension/        Chrome extension scripts: background, content script, provider injection
   provider/         CIP-0103 wallet provider — request dispatcher and method handlers
   vault/            Encrypted local vault: PBKDF2 key derivation, AES-GCM storage, React context
-  views/            Top-level UI views (onboarding/* two-step wizard, Unlock, Home, ConnectionSettings)
-  wc/               WalletConnect sign client setup and session event handlers
+  utils/            Pure helpers (account formatting, clipboard, classnames cn, JSON pretty-print)
+  views/            Top-level UI views (onboarding/* two-step wizard, Unlock, Home,
+                    ConnectionSettings) plus home/* — the extracted HomeView logic
+                    (pending-actions state, extension/provider request handling,
+                    WalletConnect lifecycle, transaction summarising)
+  wc/               WalletConnect sign client setup and session lifecycle API
   App.tsx           Root component — selects the active view based on vault state
   main.tsx          Entry point — detects chrome-extension:// vs web runtime
 public/
   manifest.json     Chrome extension manifest (consumed during extension build)
   icons/            Extension icons (16, 32, 48, 128 px)
-test/               Node test runner suite (11 test files)
+test/               Node test runner suite (mirrors src/ layout)
 ```
 
 ## Key Abstractions
@@ -86,9 +90,9 @@ Implements the Canton wallet provider standard. Any dApp request (from WalletCon
 
 Manages the WalletConnect sign client lifecycle and session event handling.
 
-- **`client.ts`** — Creates the Reown `Core` and `SignClient` instances. Declares the supported CIP-0103 methods and events used during session proposals.
-- **`handlers.ts`** — Subscribes to `session_proposal` and `session_request` events. Forwards approved requests to `src/provider/dispatch.ts` and responds with the result or rejection.
+- **`client.ts`** — Creates the Reown `Core` and `SignClient` instances, declares the supported CIP-0103 methods and events, and exposes the session lifecycle API: the `subscribeToProposals` / `subscribeToRequests` / `subscribeToSessionChanges` subscribers, the `approveProposal` / `rejectProposal` / `respondWithResult` / `respondWithError` responders, and `pairWithUri` for URI pairing. The subscriptions are wired up in `src/views/home/useWalletConnectLifecycle.ts`, which forwards approved requests to `src/provider/dispatch.ts` and responds with the result or rejection.
 - **`accounts.ts`** — Formats internal `AccountPublic` records into the `eip155`-style account strings WalletConnect expects.
+- **`storage.ts`** — `wipeWalletConnectStorage` deletes the WalletConnect IndexedDB database (`WALLET_CONNECT_V2_INDEXED_DB`, where `@walletconnect/keyvaluestorage` persists sessions, pairings, and the keychain) on vault reset, since the `carpincho` localStorage-prefix wipe never reaches it.
 
 ### Chrome Extension Bridge (`src/extension/`)
 
@@ -99,7 +103,7 @@ Connects the extension popup UI to web pages and the extension background.
 - **`directProvider.ts`** — Handles direct injected-provider requests inside the background worker when the cached wallet snapshot can answer without opening the popup; approval-required methods are queued for the popup.
 - **`messages.ts`** — Shared message-type constants and type guards used by all three extension scripts.
 - **`runtimeClient.ts`** — Popup-side client for sending requests to the background and receiving responses.
-- **`directConnections.ts`** — Persists the set of direct injected-provider dApp origins that have completed a connect (and removes them on disconnect) in `chrome.storage.session`, with an in-memory fallback when not running as an extension, so the popup footer can show connection state for non-WalletConnect dApps.
+- **`directConnections.ts`** — Persists the set of direct injected-provider dApp origins that have completed a connect (and removes them on disconnect) in `chrome.storage.session`, with an in-memory fallback when not running as an extension, so the popup footer can show connection state for non-WalletConnect dApps; `clearDirectConnectedOrigins` drops all remembered origins (used on vault reset).
 - **`directConnectionState.ts`** — Pure helper that normalizes page URLs to stable http(s) origins and derives a remember/forget/none update from a provider request/response pair: remembers on a successful `connect` whose result reports `isConnected: true`, forgets on `disconnect`.
 - **`walletSnapshot.ts`** — Serialises the current wallet state (accounts, network, lock status) into a plain object the background caches so the popup can render without unlocking the vault.
 
@@ -113,14 +117,14 @@ The app communicates with two external systems:
 | Injected extension provider | `src/extension/contentScript.ts` | Announces Carpincho to dApps through `canton:requestProvider` / `canton:announceProvider` and relays provider requests through the extension runtime |
 | WalletConnect relay | `src/wc/client.ts` | Optional fallback sign client connected to Reown relay using `VITE_WC_PROJECT_ID` |
 
-Components must never call these systems directly. All wallet-service calls go through `src/provider/walletService.ts`; injected-provider requests are bridged by `src/extension/contentScript.ts` / `src/extension/background.ts`, and WalletConnect events are handled in `src/wc/handlers.ts`. Both paths forward to the provider dispatcher.
+Components must never call these systems directly. All wallet-service calls go through `src/provider/walletService.ts`; injected-provider requests are bridged by `src/extension/contentScript.ts` / `src/extension/background.ts`, and WalletConnect events are handled by the `src/wc/client.ts` subscriptions wired in `src/views/home/useWalletConnectLifecycle.ts`. Both paths forward to the provider dispatcher.
 
 ## Data Flow
 
 ```mermaid
 flowchart TD
   dapp["dApp (browser page)"]
-  wc["src/wc/handlers.ts"]
+  wc["src/wc/client.ts subscriptions"]
   direct["src/extension/directProvider.ts"]
   dispatch["src/provider/dispatch.ts"]
   api["src/api/walletService.ts"]
@@ -200,6 +204,7 @@ Authentication is local-only; there is no remote auth service.
 - **Unlock** — `VaultContext.unlock(password)` re-derives the key, decrypts the vault, and stores the plaintext in a module-scope closure. The password is cached in `sessionStorage` via `sessionUnlock.ts` so hot-reloads do not require re-entry.
 - **Auto-lock** — Configurable from the Menu drawer (`Never` / `1 min` / `5 min` / `1 hour`, default `Never`, persisted to `localStorage.carpincho.autoLockOption`). Any timed option installs a `setTimeout`-based idle reset on window activity and also writes `Date.now() + idleMs` to `sessionStorage` as `carpincho.session.lockAt`. On mount, the session-restore effect refuses to auto-unlock if the persisted `lockAt` has elapsed, so the timeout is enforced across reloads, not just within a single tab session. On `pagehide` the in-memory vault is wiped when the active option is not `Never`.
 - **Lock** — `VaultContext.lock()` clears the module-scope closure, the cached session password, and the `lockAt` deadline.
+- **Reset** — `VaultContext.destroyVault()` (triggered from the Unlock screen's "Reset vault" confirmation) wipes every persistence surface that survives a reload: the in-memory keys and session token, every `carpincho`-prefixed `localStorage` key via `wipeAllPersistedData()` in `storage.ts`, the cached wallet snapshot, the WalletConnect IndexedDB (`wipeWalletConnectStorage`), and the direct-connected dApp origins in `chrome.storage.session` (`clearDirectConnectedOrigins`), then reloads the page so every provider re-inits from empty storage.
 
 No JWT, cookie, or server-side session is involved.
 
diff --git a/carpincho-wallet/src/components/ui/DangerConfirm.tsx b/carpincho-wallet/src/components/ui/DangerConfirm.tsx
index b9db7046..ac9d3004 100644
--- a/carpincho-wallet/src/components/ui/DangerConfirm.tsx
+++ b/carpincho-wallet/src/components/ui/DangerConfirm.tsx
@@ -2,7 +2,8 @@ import type { ReactNode } from 'react'
 import { DangerButton } from '@/components/ui/Button'
 
 interface DangerConfirmProps {
-  identifier: string
+  // A mono identifier box (party id, origin, …). Omit for confirms with nothing to echo back.
+  identifier?: string
   message: ReactNode
   note?: ReactNode
   confirmLabel: string
@@ -26,11 +27,13 @@ export const DangerConfirm = ({
     data-testid={testId}
     className="flex flex-col gap-4"
   >
-    <div className="rounded-md border border-border bg-muted/50 px-3 py-2.5">
-      <span className="block break-all font-mono text-[0.8rem] leading-relaxed text-foreground">
-        {identifier}
-      </span>
-    </div>
+    {identifier !== undefined && (
+      <div className="rounded-md border border-border bg-muted/50 px-3 py-2.5">
+        <span className="block break-all font-mono text-[0.8rem] leading-relaxed text-foreground">
+          {identifier}
+        </span>
+      </div>
+    )}
     <p className="text-soft text-[0.95rem] leading-relaxed">{message}</p>
     {note !== undefined && <p className="font-semibold text-foreground">{note}</p>}
     <DangerButton
diff --git a/carpincho-wallet/src/extension/directConnections.ts b/carpincho-wallet/src/extension/directConnections.ts
index 36bde211..a9aa8c94 100644
--- a/carpincho-wallet/src/extension/directConnections.ts
+++ b/carpincho-wallet/src/extension/directConnections.ts
@@ -5,6 +5,7 @@ export const DIRECT_CONNECTED_ORIGINS_KEY = 'carpincho.direct.connectedOrigins'
 type ChromeSessionStorage = {
   set: (items: Record<string, unknown>) => Promise<void> | void
   get: (key: string) => Promise<Record<string, unknown>> | Record<string, unknown>
+  remove: (key: string) => Promise<void> | void
 }
 
 const fallbackOrigins = new Set<string>()
@@ -79,6 +80,19 @@ export const rememberDirectConnectedOrigin = async (origin: string): Promise<str
   )
 }
 
+// Drops every remembered direct connection. Called on vault reset so the next wallet does not
+// inherit the previous one's connected dApp origins from chrome.storage.session.
+export const clearDirectConnectedOrigins = async (): Promise<void> => {
+  await withWriteLock(async () => {
+    fallbackOrigins.clear()
+    const storage = chromeSessionStorage()
+    if (storage === undefined) {
+      return
+    }
+    await storage.remove(DIRECT_CONNECTED_ORIGINS_KEY)
+  })
+}
+
 // Removes one direct dApp origin after an injected-provider disconnect response.
 export const forgetDirectConnectedOrigin = async (origin: string): Promise<string[]> => {
   const normalized = normalizeDirectConnectionOrigin(origin)
diff --git a/carpincho-wallet/src/vault/VaultContext.tsx b/carpincho-wallet/src/vault/VaultContext.tsx
index 0b809933..9162576a 100644
--- a/carpincho-wallet/src/vault/VaultContext.tsx
+++ b/carpincho-wallet/src/vault/VaultContext.tsx
@@ -10,6 +10,7 @@ import {
   useRef,
   useState,
 } from 'react'
+import { clearDirectConnectedOrigins } from '@/extension/directConnections'
 import { broadcastWalletEvent } from '@/extension/eventBroadcast'
 import { persistWalletSnapshot } from '@/extension/walletSnapshot'
 import { accountToCip103Wallet } from '@/provider/accounts'
@@ -30,11 +31,12 @@ import {
   loadAutoLockOption,
   loadVault,
   rotateVault,
-  wipeVault,
+  wipeAllPersistedData,
   writeAutoLockOption,
   writeFreshVault,
 } from '@/vault/storage'
 import type { AccountPublic, AccountSecret, TransactionRecord, VaultPlaintext } from '@/vault/types'
+import { wipeWalletConnectStorage } from '@/wc/storage'
 
 const AUTO_LOCK_MS: Record<AutoLockOption, number | null> = {
   never: null,
@@ -89,7 +91,7 @@ export interface VaultContextValue {
   setup: (password: string) => Promise<void>
   unlock: (password: string) => Promise<void>
   lock: () => void
-  destroyVault: () => void
+  destroyVault: () => Promise<void>
   accounts: AccountPublic[]
   primary: AccountPublic | null
   transactions: TransactionRecord[]
@@ -211,13 +213,22 @@ export const VaultProvider = ({ children }: PropsWithChildren): JSX.Element => {
     [bump, broadcastConnectionState],
   )
 
-  const destroyVault = useCallback((): void => {
-    void wipeMemory().catch(() => undefined)
-    wipeVault()
+  const destroyVault = useCallback(async (): Promise<void> => {
+    // Await every persistence surface that survives a reload: in-memory keys + session token,
+    // the snapshot, WalletConnect's IndexedDB sessions, and the direct connected origins in
+    // chrome.storage.session. The carpincho localStorage prefix wipe only covers localStorage.
+    await wipeMemory().catch(() => undefined)
+    await persistWalletSnapshot(null).catch(() => undefined)
+    await wipeWalletConnectStorage().catch(() => undefined)
+    await clearDirectConnectedOrigins().catch(() => undefined)
+    wipeAllPersistedData()
+    // Reload re-inits every provider from empty storage and is the primary reset mechanism,
+    // but reset the React state too so the UI is consistent if a reload is ever a no-op.
     setVaultExists(false)
     setIsLocked(true)
     bump()
     broadcastConnectionState(false)
+    window.location.reload()
   }, [bump, broadcastConnectionState])
 
   // dapp-api AccountsChangedEvent payload (Wallet[]); [] when locked.
diff --git a/carpincho-wallet/src/vault/storage.ts b/carpincho-wallet/src/vault/storage.ts
index 72017cae..ae277585 100644
--- a/carpincho-wallet/src/vault/storage.ts
+++ b/carpincho-wallet/src/vault/storage.ts
@@ -43,9 +43,27 @@ export const rotateVault = (blob: EncryptedVault): void => {
   localStorage.removeItem(KEY_VAULT_NEXT)
 }
 
-export const wipeVault = (): void => {
-  localStorage.removeItem(KEY_VAULT)
-  localStorage.removeItem(KEY_VAULT_NEXT)
+// Reset wipes every `carpincho`-namespaced key (vault + all prefs) by prefix, so
+// preferences added later are cleared without touching this.
+const STORAGE_PREFIX = 'carpincho'
+
+export const wipeAllPersistedData = (): void => {
+  const stale: string[] = []
+  for (let i = 0; i < localStorage.length; i += 1) {
+    const key = localStorage.key(i)
+    if (key?.startsWith(STORAGE_PREFIX)) {
+      stale.push(key)
+    }
+  }
+  for (const key of stale) {
+    // Remove defensively: one failing key (e.g. storage disabled mid-wipe) must not
+    // strand the rest, since destroyVault reloads regardless of what survives here.
+    try {
+      localStorage.removeItem(key)
+    } catch {
+      // Best effort; a key that cannot be removed is left for the reload to surface.
+    }
+  }
 }
 
 const KEY_AUTO_LOCK = 'carpincho.autoLockOption'
diff --git a/carpincho-wallet/src/views/UnlockView.tsx b/carpincho-wallet/src/views/UnlockView.tsx
index 8ba8da62..7a61bf5d 100644
--- a/carpincho-wallet/src/views/UnlockView.tsx
+++ b/carpincho-wallet/src/views/UnlockView.tsx
@@ -2,7 +2,9 @@ import { useState } from 'react'
 import { Alert } from '@/components/ui/Alert'
 import { PrimaryButton } from '@/components/ui/Button'
 import { Card } from '@/components/ui/Card'
+import { DangerConfirm } from '@/components/ui/DangerConfirm'
 import { PasswordInput } from '@/components/ui/PasswordInput'
+import { Sheet } from '@/components/ui/Sheet'
 import { toast } from '@/components/ui/toast'
 import { WelcomeHero } from '@/components/WelcomeHero'
 import { useVault } from '@/vault/useVault'
@@ -12,6 +14,7 @@ export const UnlockView = (): JSX.Element => {
   const [password, setPassword] = useState('')
   const [busy, setBusy] = useState(false)
   const [error, setError] = useState<string | undefined>(undefined)
+  const [resetOpen, setResetOpen] = useState(false)
 
   const onSubmit = async (e: React.FormEvent): Promise<void> => {
     e.preventDefault()
@@ -31,15 +34,6 @@ export const UnlockView = (): JSX.Element => {
     }
   }
 
-  const onReset = (): void => {
-    const ok = window.confirm(
-      'This wipes the vault from this browser. If you have not exported your private keys, your accounts will be unrecoverable. Continue?',
-    )
-    if (ok) {
-      v.destroyVault()
-    }
-  }
-
   return (
     <div>
       <WelcomeHero
@@ -76,12 +70,35 @@ export const UnlockView = (): JSX.Element => {
         </form>
         <button
           type="button"
+          data-testid="reset-vault-trigger"
           className="block w-full mt-5 py-2 px-2 text-[0.85rem] bg-transparent border-0 text-muted-foreground font-semibold tracking-wide hover:text-danger transition-colors"
-          onClick={onReset}
+          onClick={() => setResetOpen(true)}
         >
           Forgot password? Reset vault
         </button>
       </Card>
+      <Sheet
+        open={resetOpen}
+        onOpenChange={setResetOpen}
+        side="center"
+        title="Reset vault"
+        description="Wipe this vault from the browser."
+      >
+        <DangerConfirm
+          testId="reset-vault"
+          message={
+            <>
+              This wipes the vault from this browser. If you have not exported your private keys,
+              your accounts will be{' '}
+              <span className="font-semibold text-foreground">unrecoverable</span>.
+            </>
+          }
+          note="This cannot be undone."
+          confirmLabel="Reset vault"
+          confirmTestId="confirm-reset-vault"
+          onConfirm={() => v.destroyVault()}
+        />
+      </Sheet>
     </div>
   )
 }
diff --git a/carpincho-wallet/src/wc/storage.ts b/carpincho-wallet/src/wc/storage.ts
new file mode 100644
index 00000000..a9e698f7
--- /dev/null
+++ b/carpincho-wallet/src/wc/storage.ts
@@ -0,0 +1,25 @@
+// WalletConnect's browser KeyValueStorage (@walletconnect/keyvaluestorage) persists sessions,
+// pairings, and the keychain in this IndexedDB database. The `carpincho` localStorage prefix wipe
+// never reaches it, so a vault reset must drop the database to stop dApp session history from
+// surviving into the next wallet.
+export const WALLET_CONNECT_DB = 'WALLET_CONNECT_V2_INDEXED_DB'
+
+export const wipeWalletConnectStorage = async (): Promise<void> => {
+  const idb = (globalThis as { indexedDB?: IDBFactory }).indexedDB
+  if (idb === undefined) {
+    return
+  }
+  await new Promise<void>((resolve) => {
+    try {
+      const request = idb.deleteDatabase(WALLET_CONNECT_DB)
+      request.onsuccess = () => resolve()
+      request.onerror = () => resolve()
+      // An open WC connection blocks deletion; the reload that follows a reset closes it and
+      // the queued delete completes, so treat blocked as done rather than hanging the reset.
+      // (onblocked may later be followed by onsuccess, but resolving an already-settled promise is a no-op.)
+      request.onblocked = () => resolve()
+    } catch {
+      resolve()
+    }
+  })
+}
diff --git a/carpincho-wallet/test/extension/clearDirectConnectedOrigins.test.ts b/carpincho-wallet/test/extension/clearDirectConnectedOrigins.test.ts
new file mode 100644
index 00000000..503ebf90
--- /dev/null
+++ b/carpincho-wallet/test/extension/clearDirectConnectedOrigins.test.ts
@@ -0,0 +1,57 @@
+import { strict as assert } from 'node:assert'
+import { afterEach, describe, it } from 'node:test'
+import {
+  clearDirectConnectedOrigins,
+  DIRECT_CONNECTED_ORIGINS_KEY,
+  readDirectConnectedOrigins,
+} from '@/extension/directConnections'
+
+const originalChrome = (globalThis as { chrome?: unknown }).chrome
+
+const installChromeSession = (
+  initial: Record<string, unknown>,
+): { store: Record<string, unknown>; removed: string[] } => {
+  const store: Record<string, unknown> = { ...initial }
+  const removed: string[] = []
+  Object.defineProperty(globalThis, 'chrome', {
+    configurable: true,
+    value: {
+      storage: {
+        session: {
+          get: async (key: string) => ({ [key]: store[key] }),
+          set: async (items: Record<string, unknown>) => {
+            Object.assign(store, items)
+          },
+          remove: async (key: string) => {
+            removed.push(key)
+            delete store[key]
+          },
+        },
+      },
+    },
+  })
+  return { store, removed }
+}
+
+describe('clearDirectConnectedOrigins', () => {
+  afterEach(() => {
+    Object.defineProperty(globalThis, 'chrome', { configurable: true, value: originalChrome })
+  })
+
+  it('removes the connected-origins key from chrome session storage', async () => {
+    const { store, removed } = installChromeSession({
+      [DIRECT_CONNECTED_ORIGINS_KEY]: ['http://localhost:3012'],
+    })
+
+    await clearDirectConnectedOrigins()
+
+    assert.deepEqual(removed, [DIRECT_CONNECTED_ORIGINS_KEY])
+    assert.equal(store[DIRECT_CONNECTED_ORIGINS_KEY], undefined)
+    assert.deepEqual(await readDirectConnectedOrigins(), [])
+  })
+
+  it('resolves without error when chrome session storage is unavailable', async () => {
+    Object.defineProperty(globalThis, 'chrome', { configurable: true, value: undefined })
+    await clearDirectConnectedOrigins()
+  })
+})
diff --git a/carpincho-wallet/test/vault/destroyVault.test.tsx b/carpincho-wallet/test/vault/destroyVault.test.tsx
new file mode 100644
index 00000000..e2e0ed06
--- /dev/null
+++ b/carpincho-wallet/test/vault/destroyVault.test.tsx
@@ -0,0 +1,108 @@
+import { strict as assert } from 'node:assert'
+import { afterEach, beforeEach, describe, it } from 'node:test'
+import { act, cleanup, render } from '@testing-library/react'
+import { DIRECT_CONNECTED_ORIGINS_KEY } from '@/extension/directConnections'
+import { useVault } from '@/vault/useVault'
+import { type VaultContextValue, VaultProvider } from '@/vault/VaultContext'
+import { WALLET_CONNECT_DB } from '@/wc/storage'
+
+const originalChrome = (globalThis as { chrome?: unknown }).chrome
+
+const captureVault = (): { ref: { current: VaultContextValue | null } } => {
+  const ref: { current: VaultContextValue | null } = { current: null }
+  const Probe = (): null => {
+    ref.current = useVault()
+    return null
+  }
+  render(
+    <VaultProvider>
+      <Probe />
+    </VaultProvider>,
+  )
+  return { ref }
+}
+
+describe('VaultContext.destroyVault full wipe', () => {
+  let reloads = 0
+  let deletedDbs: string[]
+  let sessionStore: Record<string, unknown>
+  let realReload: typeof window.location.reload
+
+  beforeEach(() => {
+    localStorage.clear()
+    reloads = 0
+    deletedDbs = []
+    sessionStore = { [DIRECT_CONNECTED_ORIGINS_KEY]: ['http://localhost:3012'] }
+
+    realReload = window.location.reload
+    Object.defineProperty(window.location, 'reload', {
+      configurable: true,
+      value: () => {
+        reloads += 1
+      },
+    })
+
+    const request: { onsuccess?: () => void } = {}
+    Object.defineProperty(globalThis, 'indexedDB', {
+      configurable: true,
+      value: {
+        deleteDatabase: (name: string) => {
+          deletedDbs.push(name)
+          queueMicrotask(() => request.onsuccess?.())
+          return request
+        },
+      },
+    })
+
+    Object.defineProperty(globalThis, 'chrome', {
+      configurable: true,
+      value: {
+        storage: {
+          session: {
+            get: async (key: string) => ({ [key]: sessionStore[key] }),
+            set: async (items: Record<string, unknown>) => {
+              Object.assign(sessionStore, items)
+            },
+            remove: async (key: string) => {
+              delete sessionStore[key]
+            },
+          },
+        },
+      },
+    })
+  })
+
+  afterEach(() => {
+    cleanup()
+    localStorage.clear()
+    Object.defineProperty(window.location, 'reload', { configurable: true, value: realReload })
+    Object.defineProperty(globalThis, 'indexedDB', { configurable: true, value: undefined })
+    Object.defineProperty(globalThis, 'chrome', { configurable: true, value: originalChrome })
+  })
+
+  it('wipes localStorage, WalletConnect IndexedDB, direct origins, and resets state', async () => {
+    localStorage.setItem('other-app.token', 'keep-me')
+    const { ref } = captureVault()
+    await act(async () => {
+      await ref.current?.setup('correct-horse-battery')
+    })
+    assert.equal(ref.current?.hasVault, true)
+    assert.notEqual(localStorage.getItem('carpincho.vault'), null)
+
+    await act(async () => {
+      await ref.current?.destroyVault()
+    })
+
+    // localStorage: every carpincho key gone, foreign key kept.
+    assert.equal(localStorage.getItem('carpincho.vault'), null)
+    assert.equal(localStorage.getItem('other-app.token'), 'keep-me')
+    // WalletConnect IndexedDB dropped.
+    assert.deepEqual(deletedDbs, [WALLET_CONNECT_DB])
+    // Direct connected origins cleared from chrome session storage.
+    assert.equal(sessionStore[DIRECT_CONNECTED_ORIGINS_KEY], undefined)
+    // State reset stands even though reload is the primary mechanism.
+    assert.equal(reloads, 1)
+    assert.equal(ref.current?.hasVault, false)
+    assert.equal(ref.current?.isLocked, true)
+  })
+})
diff --git a/carpincho-wallet/test/vault/wipeAllPersistedData.test.ts b/carpincho-wallet/test/vault/wipeAllPersistedData.test.ts
new file mode 100644
index 00000000..59f9168a
--- /dev/null
+++ b/carpincho-wallet/test/vault/wipeAllPersistedData.test.ts
@@ -0,0 +1,75 @@
+import { strict as assert } from 'node:assert'
+import { afterEach, beforeEach, describe, it } from 'node:test'
+import { wipeAllPersistedData } from '@/vault/storage'
+
+describe('wipeAllPersistedData', () => {
+  beforeEach(() => {
+    localStorage.clear()
+  })
+
+  afterEach(() => {
+    localStorage.clear()
+  })
+
+  it('removes every carpincho-namespaced key (vault and all preferences)', () => {
+    localStorage.setItem('carpincho.vault', 'blob')
+    localStorage.setItem('carpincho.vault.next', 'blob')
+    localStorage.setItem('carpincho.autoLockOption', '5m')
+    localStorage.setItem('carpincho-theme', 'dark')
+    localStorage.setItem('carpincho.runtime-config.v1', '{}')
+
+    wipeAllPersistedData()
+
+    assert.equal(localStorage.length, 0)
+  })
+
+  it('leaves keys owned by other apps untouched', () => {
+    localStorage.setItem('carpincho-theme', 'dark')
+    localStorage.setItem('other-app.token', 'keep-me')
+
+    wipeAllPersistedData()
+
+    assert.equal(localStorage.getItem('carpincho-theme'), null)
+    assert.equal(localStorage.getItem('other-app.token'), 'keep-me')
+  })
+
+  it('is a no-op when nothing is persisted', () => {
+    wipeAllPersistedData()
+    assert.equal(localStorage.length, 0)
+  })
+
+  it('keeps wiping the remaining keys when one removal throws', () => {
+    // happy-dom's Storage ignores method monkeypatching, so swap the whole global for a
+    // fake whose removeItem throws on one key to prove the wipe does not abort midway.
+    const map = new Map<string, string>([
+      ['carpincho.vault', 'blob'],
+      ['carpincho.autoLockOption', '5m'],
+    ])
+    const fake = {
+      get length(): number {
+        return map.size
+      },
+      key: (index: number): string | null => [...map.keys()][index] ?? null,
+      getItem: (key: string): string | null => map.get(key) ?? null,
+      setItem: (key: string, value: string): void => {
+        map.set(key, value)
+      },
+      removeItem: (key: string): void => {
+        if (key === 'carpincho.vault') {
+          throw new Error('storage disabled')
+        }
+        map.delete(key)
+      },
+    }
+    const real = globalThis.localStorage
+    Object.defineProperty(globalThis, 'localStorage', { configurable: true, value: fake })
+
+    try {
+      wipeAllPersistedData()
+    } finally {
+      Object.defineProperty(globalThis, 'localStorage', { configurable: true, value: real })
+    }
+
+    assert.equal(map.get('carpincho.autoLockOption'), undefined)
+  })
+})
diff --git a/carpincho-wallet/test/views/UnlockView.test.tsx b/carpincho-wallet/test/views/UnlockView.test.tsx
new file mode 100644
index 00000000..abf9b9f8
--- /dev/null
+++ b/carpincho-wallet/test/views/UnlockView.test.tsx
@@ -0,0 +1,69 @@
+import { strict as assert } from 'node:assert'
+import { afterEach, describe, it } from 'node:test'
+import { cleanup, render, screen, waitFor } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { TooltipProvider } from '@/components/ui/Tooltip'
+import { VaultContext, type VaultContextValue } from '@/vault/VaultContext'
+import { UnlockView } from '@/views/UnlockView'
+
+const renderUnlock = (overrides: Partial<VaultContextValue> = {}): void => {
+  render(
+    <TooltipProvider>
+      <VaultContext.Provider
+        value={{ unlock: async () => undefined, ...overrides } as VaultContextValue}
+      >
+        <UnlockView />
+      </VaultContext.Provider>
+    </TooltipProvider>,
+  )
+}
+
+describe('UnlockView reset vault', () => {
+  afterEach(() => {
+    cleanup()
+  })
+
+  it('shows no dialog until the reset trigger is clicked', () => {
+    renderUnlock()
+    assert.equal(screen.queryByRole('dialog'), null)
+  })
+
+  it('opens a Radix confirm dialog instead of a native prompt', async () => {
+    const user = userEvent.setup()
+    renderUnlock()
+    await user.click(screen.getByTestId('reset-vault-trigger'))
+    const dialog = await screen.findByRole('dialog')
+    assert.ok((dialog.textContent ?? '').toLowerCase().includes('reset vault'))
+    assert.ok(screen.getByTestId('confirm-reset-vault'))
+  })
+
+  it('calls destroyVault when the reset is confirmed', async () => {
+    const user = userEvent.setup()
+    const calls: number[] = []
+    renderUnlock({
+      destroyVault: async () => {
+        calls.push(1)
+      },
+    })
+    await user.click(screen.getByTestId('reset-vault-trigger'))
+    await user.click(await screen.findByTestId('confirm-reset-vault'))
+    assert.equal(calls.length, 1)
+  })
+
+  it('does not destroy the vault when the dialog is dismissed with Escape', async () => {
+    const user = userEvent.setup()
+    const calls: number[] = []
+    renderUnlock({
+      destroyVault: async () => {
+        calls.push(1)
+      },
+    })
+    await user.click(screen.getByTestId('reset-vault-trigger'))
+    await screen.findByRole('dialog')
+    await user.keyboard('{Escape}')
+    await waitFor(() => {
+      assert.equal(screen.queryByRole('dialog'), null)
+    })
+    assert.equal(calls.length, 0)
+  })
+})
diff --git a/carpincho-wallet/test/wc/wipeWalletConnectStorage.test.ts b/carpincho-wallet/test/wc/wipeWalletConnectStorage.test.ts
new file mode 100644
index 00000000..2b2b2305
--- /dev/null
+++ b/carpincho-wallet/test/wc/wipeWalletConnectStorage.test.ts
@@ -0,0 +1,53 @@
+import { strict as assert } from 'node:assert'
+import { afterEach, describe, it } from 'node:test'
+import { WALLET_CONNECT_DB, wipeWalletConnectStorage } from '@/wc/storage'
+
+const restoreIndexedDb = (): void => {
+  // happy-dom does not provide indexedDB, so the registered default is undefined.
+  Object.defineProperty(globalThis, 'indexedDB', { configurable: true, value: undefined })
+}
+
+describe('wipeWalletConnectStorage', () => {
+  afterEach(() => {
+    restoreIndexedDb()
+  })
+
+  it('deletes the WalletConnect IndexedDB database', async () => {
+    const deleted: string[] = []
+    const request: { onsuccess?: () => void; onerror?: () => void; onblocked?: () => void } = {}
+    Object.defineProperty(globalThis, 'indexedDB', {
+      configurable: true,
+      value: {
+        deleteDatabase: (name: string) => {
+          deleted.push(name)
+          queueMicrotask(() => request.onsuccess?.())
+          return request
+        },
+      },
+    })
+
+    await wipeWalletConnectStorage()
+
+    assert.deepEqual(deleted, [WALLET_CONNECT_DB])
+  })
+
+  it('resolves when an open connection blocks the delete', async () => {
+    const request: { onsuccess?: () => void; onerror?: () => void; onblocked?: () => void } = {}
+    Object.defineProperty(globalThis, 'indexedDB', {
+      configurable: true,
+      value: {
+        deleteDatabase: () => {
+          queueMicrotask(() => request.onblocked?.())
+          return request
+        },
+      },
+    })
+
+    // Must not hang: a blocked delete completes once the post-reset reload closes the connection.
+    await wipeWalletConnectStorage()
+  })
+
+  it('resolves without throwing when IndexedDB is unavailable', async () => {
+    await wipeWalletConnectStorage()
+  })
+})
diff --git a/dapp/README.md b/dapp/README.md
index b005dbc3..1b0455fe 100644
--- a/dapp/README.md
+++ b/dapp/README.md
@@ -7,3 +7,5 @@ Minimal dApp split into:
 - `e2e`: Playwright tests for the dApp integration flow.
 
 The Canton barebones lives in `../canton-barebones`.
+
+For the shared local loop, follow the root [quick start](../README.md#quick-start).
diff --git a/dapp/daml/README.md b/dapp/daml/README.md
index 99f25a3f..cf3664da 100644
--- a/dapp/daml/README.md
+++ b/dapp/daml/README.md
@@ -12,10 +12,6 @@ The compiled DAR is written to:
 .daml/dist/quickstart-counter-0.0.1.dar
 ```
 
-Deploy it to the local Canton barebones:
-
-```bash
-../../canton-barebones/scripts/deploy-dar.sh .daml/dist/quickstart-counter-0.0.1.dar
-```
+For local deployment, follow the root [DAR deployment step](../../README.md#deploy-dars).
 
 This folder owns the app Daml code. The base Canton folder should not keep app DARs checked in.
diff --git a/dapp/e2e/AGENTS.md b/dapp/e2e/AGENTS.md
new file mode 100644
index 00000000..8098b1aa
--- /dev/null
+++ b/dapp/e2e/AGENTS.md
@@ -0,0 +1,27 @@
+# Agent Configuration — dapp/e2e
+
+This file applies only to `dapp/e2e/`. For monorepo-wide rules, see [`../../AGENTS.md`](../../AGENTS.md).
+
+## Scope
+
+`dapp/e2e` is a black-box Playwright package. It tests cross-package wiring through stable surfaces: wallet-service HTTP, the loaded Carpincho extension, the dApp UI, and browser-visible provider events.
+
+## Working Rules
+
+- Do not import source from `carpincho-wallet/`, `canton-barebones/`, `canton-connect-kit/`, or `dapp/frontend/`.
+- Do not make e2e own stack lifecycle unless the README and Playwright config are explicitly changed together.
+- Use env overrides (`WALLET_SERVICE_URL`, `DAPP_URL`, `EXTENSION_PATH`) instead of hard-coding alternate targets.
+- Prefer `data-testid` selectors and stable `data-*` attributes. Avoid CSS position selectors and broad text-only locators.
+- Avoid heuristic sleeps. Use Playwright waits, `expect.poll`, or assertions that wait on observable state.
+- Keep tests runnable independently. Do not rely on test order or shared browser state.
+
+## Testing
+
+- Run tests with `npm test` from this package, or `npm --prefix dapp/e2e test` from the repo root.
+- Use headed or UI mode only for debugging: `npm run test:headed` or `npm run test:ui`.
+- Keep each spec focused on one integration concern.
+
+## Validation Checklist
+
+- `npm run lint`
+- `npm test` when the full local stack is running
diff --git a/dapp/e2e/CLAUDE.md b/dapp/e2e/CLAUDE.md
new file mode 100644
index 00000000..59ab8b09
--- /dev/null
+++ b/dapp/e2e/CLAUDE.md
@@ -0,0 +1,3 @@
+# Agent Configuration
+This project's canonical agent configuration lives in [`AGENTS.md`](./AGENTS.md).
+Claude Code reads `CLAUDE.md` natively; load `AGENTS.md` as the single source of truth.
diff --git a/dapp/e2e/README.md b/dapp/e2e/README.md
index 6051616f..e25fc5ea 100644
--- a/dapp/e2e/README.md
+++ b/dapp/e2e/README.md
@@ -22,7 +22,6 @@ This package depends on **nothing in this repo** at the TypeScript level. Every
 | Door | Default | Override |
 |---|---|---|
 | wallet-service HTTP | `http://localhost:3010` | `WALLET_SERVICE_URL` |
-| Carpincho web | `http://localhost:3011` | `CARPINCHO_URL` |
 | dApp | `http://localhost:3012` | `DAPP_URL` |
 | Carpincho extension bundle | `../../carpincho-wallet/dist-extension` | `EXTENSION_PATH` |
 
@@ -35,22 +34,9 @@ When the four packages publish independently and the dev kit becomes a monorepo
 
 ### Prerequisites
 
-The full local stack must be running. From the repo root:
-
-```bash
-# Start the canton stack (postgres + canton + wallet-service)
-npm run canton:up && npm run canton:health
-
-# Deploy the Counter DAR
-./canton-barebones/scripts/deploy-dar.sh dapp/daml/.daml/dist/quickstart-counter-0.0.1.dar
-
-# Build the Carpincho extension
-npm --prefix carpincho-wallet run build:extension
-
-# In separate terminals:
-npm run wallet:dev              # terminal 1 — Carpincho web UI on :3011
-npm run app:dev                 # terminal 2 — dApp on :3012
-```
+The full local stack must be running. Follow the root
+[quick start](../../README.md#quick-start), including the dApp startup and
+Carpincho extension build/load setup steps.
 
 ### First-time setup
 
diff --git a/dapp/e2e/fixtures/stack.ts b/dapp/e2e/fixtures/stack.ts
index 2e45dd38..bcb0ff6d 100644
--- a/dapp/e2e/fixtures/stack.ts
+++ b/dapp/e2e/fixtures/stack.ts
@@ -3,8 +3,7 @@
 // CONSUMPTION CONTRACT — read before editing:
 // This package treats the other four parts of the system as published artifacts.
 // It does NOT import from their source. The only ways it consumes them:
-//   * HTTP: wallet-service (`WALLET_SERVICE_URL`), Carpincho web (`CARPINCHO_URL`),
-//     dApp (`DAPP_URL`).
+//   * HTTP: wallet-service (`WALLET_SERVICE_URL`), dApp (`DAPP_URL`).
 //   * Filesystem: Carpincho's built extension bundle at `EXTENSION_PATH`.
 //
 // All of these are env-overridable so a future monorepo migration can point the
@@ -20,7 +19,6 @@ import { type BrowserContext, test as base, chromium, type Worker } from '@playw
 const moduleDir = path.dirname(fileURLToPath(import.meta.url))
 
 export const WALLET_SERVICE_URL = process.env.WALLET_SERVICE_URL ?? 'http://localhost:3010'
-export const CARPINCHO_URL = process.env.CARPINCHO_URL ?? 'http://localhost:3011'
 export const DAPP_URL = process.env.DAPP_URL ?? 'http://localhost:3012'
 
 // Default: the in-tree dev extension. Override via EXTENSION_PATH for published builds.
diff --git a/dapp/e2e/package.json b/dapp/e2e/package.json
index 9434dd4f..4c9d7c58 100644
--- a/dapp/e2e/package.json
+++ b/dapp/e2e/package.json
@@ -3,7 +3,7 @@
   "version": "0.1.0",
   "private": true,
   "type": "module",
-  "description": "Integration tests across the canton-barebones, wallet-service, carpincho-wallet, and dapp/frontend packages. Black-box: consumes each package via its stable surface (HTTP endpoints, dist artifacts, UI). No direct source imports.",
+  "description": "Integration tests across the canton-barebones, wallet-service, carpincho-wallet, and dapp/frontend packages. Black-box: consumes each package via its stable surface (HTTP endpoints, extension artifact, dApp UI). No direct source imports.",
   "engines": {
     "node": ">=22"
   },
diff --git a/dapp/e2e/playwright.config.ts b/dapp/e2e/playwright.config.ts
index 390714a5..b52da457 100644
--- a/dapp/e2e/playwright.config.ts
+++ b/dapp/e2e/playwright.config.ts
@@ -3,7 +3,6 @@ import { defineConfig } from '@playwright/test'
 // All endpoints and artifact paths are env-driven so the suite can target either
 // the in-tree dev stack (default) or a published-package monorepo build later.
 const WALLET_SERVICE_URL = process.env.WALLET_SERVICE_URL ?? 'http://localhost:3010'
-const CARPINCHO_URL = process.env.CARPINCHO_URL ?? 'http://localhost:3011'
 const DAPP_URL = process.env.DAPP_URL ?? 'http://localhost:3012'
 
 export default defineConfig({
@@ -32,7 +31,6 @@ export default defineConfig({
       },
       metadata: {
         walletServiceUrl: WALLET_SERVICE_URL,
-        carpinchoUrl: CARPINCHO_URL,
         dappUrl: DAPP_URL,
       },
     },
diff --git a/dapp/frontend/README.md b/dapp/frontend/README.md
index 83963ade..acae7f68 100644
--- a/dapp/frontend/README.md
+++ b/dapp/frontend/README.md
@@ -17,6 +17,9 @@ meant to be deleted once you start building your own app.
 
 ## Run
 
+For the full local stack, follow the root [quick start](../../README.md#quick-start).
+This package can also run by itself against the configured wallet URL:
+
 ```bash
 npm install
 npm run dev