From f4cf9a9a83bf475a4b1d06105371c05e5c26692c Mon Sep 17 00:00:00 2001
From: nicosampler <nf.dominguez.87@gmail.com>
Date: Wed, 3 Jun 2026 17:45:00 -0300
Subject: [PATCH 1/7] docs: standardize documentation distribution

---
 AGENTS.md                                 | 187 +++++++++++++++++++++-
 CLAUDE.md                                 | 160 +-----------------
 architecture.md                           |  11 +-
 canton-barebones/wallet-service/AGENTS.md |  28 ++++
 canton-barebones/wallet-service/CLAUDE.md |   3 +
 canton-connect-kit/AGENTS.md              |  33 ++++
 canton-connect-kit/CLAUDE.md              |   3 +
 canton-connect-kit/README.md              |  15 +-
 canton-connect-kit/architecture.md        |  92 +++++++++++
 carpincho-wallet/AGENTS.md                |  58 ++++++-
 carpincho-wallet/CLAUDE.md                |  65 +-------
 carpincho-wallet/architecture.md          |   2 +-
 dapp/README.md                            |   2 +
 dapp/daml/README.md                       |   6 +-
 dapp/e2e/AGENTS.md                        |  27 ++++
 dapp/e2e/CLAUDE.md                        |   3 +
 dapp/e2e/README.md                        |  19 +--
 dapp/frontend/README.md                   |   3 +
 18 files changed, 454 insertions(+), 263 deletions(-)
 create mode 100644 canton-barebones/wallet-service/AGENTS.md
 create mode 100644 canton-barebones/wallet-service/CLAUDE.md
 create mode 100644 canton-connect-kit/AGENTS.md
 create mode 100644 canton-connect-kit/CLAUDE.md
 create mode 100644 canton-connect-kit/architecture.md
 create mode 100644 dapp/e2e/AGENTS.md
 create mode 100644 dapp/e2e/CLAUDE.md

diff --git a/AGENTS.md b/AGENTS.md
index 7f0d014b..e496e30a 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,5 +1,186 @@
-# 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.
+- 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`
+- 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 f24dac70..59ab8b09 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,157 +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`
-- 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..39e44cc6 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
@@ -115,9 +116,9 @@ 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
+- [`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..659dc161 100644
--- a/carpincho-wallet/AGENTS.md
+++ b/carpincho-wallet/AGENTS.md
@@ -1,5 +1,57 @@
-# 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 | Manual light/dark toggle (dappbooster brand palette) | `src/theme/ThemeProvider.tsx` owns the theme state, persists to `localStorage`, defaults to `prefers-color-scheme`, and writes `data-theme` on `<html>` after mount. 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-dropdown-menu`, `@radix-ui/react-dialog`, `@radix-ui/react-select`, `@radix-ui/react-toast`, `@radix-ui/react-tooltip` for menus, modals (incl. bottom sheets), selects, 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, SectionTitle, AccountAvatar, PendingActionCard, WarningBadge, JsonPreview, Select, Sheet, 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`, `ActivityList`, `ConnectionFooter`, `PairOrConnectedCard` compose the Home view; `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: `info` / `success` 5 s, `warning` 8 s, `error` never auto-dismisses. Max 3 visible, top-center, newest on top |
+| Naming | camelCase vars/functions, PascalCase components/types, kebab-case files | |
+
+## Code Style
+
+- **Quotes:** single
+- **Indent:** 2 spaces
+- **Imports:** every import that resolves inside `src/` must use the `@/*` alias (e.g. `import { Foo } from '@/components/Foo.tsx'`); relative `./` and `../` paths are banned by Biome's `style/noRestrictedImports`. Keep the explicit `.ts` / `.tsx` extension on the alias path so the tsx test loader resolves correctly. 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 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 c4c72456..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 | Manual light/dark toggle (dappbooster brand palette) | `src/theme/ThemeProvider.tsx` owns the theme state, persists to `localStorage`, defaults to `prefers-color-scheme`, and writes `data-theme` on `<html>` after mount. 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-dropdown-menu`, `@radix-ui/react-dialog`, `@radix-ui/react-select`, `@radix-ui/react-toast`, `@radix-ui/react-tooltip` for menus, modals (incl. bottom sheets), selects, 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, SectionTitle, AccountAvatar, PendingActionCard, WarningBadge, JsonPreview, Select, Sheet, 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`, `ActivityList`, `ConnectionFooter`, `PairOrConnectedCard` compose the Home view; `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: `info` / `success` 5 s, `warning` 8 s, `error` never auto-dismisses. 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, import extensions, 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.tsx'`); relative `./` and `../` paths are banned by Biome's `style/noRestrictedImports`. Keep the explicit `.ts` / `.tsx` extension on the alias path so the tsx test loader resolves correctly. 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 c0c5d7ab..3530fd65 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
 
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..e1444cb9
--- /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, Carpincho web or extension UI, 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`, `CARPINCHO_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..03180759 100644
--- a/dapp/e2e/README.md
+++ b/dapp/e2e/README.md
@@ -35,22 +35,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 wallet, dApp, and
+extension setup steps.
 
 ### First-time setup
 
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

From ce9c67f4d3c738145a566fd13b8eb8b9bf4df682 Mon Sep 17 00:00:00 2001
From: Gabito Esmiapodo <4015436+gabitoesmiapodo@users.noreply.github.com>
Date: Wed, 3 Jun 2026 22:49:56 -0300
Subject: [PATCH 2/7] docs(wallet): sync architecture and AGENTS after
 home/menu refactor

Drop references to the deleted src/wc/handlers.ts (WalletConnect events
are now wired via wc/client.ts subscriptions in views/home/useWalletConnectLifecycle.ts),
add the new views/home and utils modules to the structure tree, record the
Sheet center variant, fix the AddAccount-to-AccountsDialog relocation, and
complete the icons.tsx inventory.
---
 architecture.md                  |  2 +-
 carpincho-wallet/AGENTS.md       |  2 +-
 carpincho-wallet/architecture.md | 21 ++++++++++++---------
 3 files changed, 14 insertions(+), 11 deletions(-)

diff --git a/architecture.md b/architecture.md
index 39e44cc6..f140c581 100644
--- a/architecture.md
+++ b/architecture.md
@@ -115,7 +115,7 @@ 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
diff --git a/carpincho-wallet/AGENTS.md b/carpincho-wallet/AGENTS.md
index 807292ff..0863064e 100644
--- a/carpincho-wallet/AGENTS.md
+++ b/carpincho-wallet/AGENTS.md
@@ -13,7 +13,7 @@ This file applies only to `carpincho-wallet/`. For monorepo-wide rules (commit s
 | 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 |
+| 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 |
diff --git a/carpincho-wallet/architecture.md b/carpincho-wallet/architecture.md
index a5a04d23..e6f21632 100644
--- a/carpincho-wallet/architecture.md
+++ b/carpincho-wallet/architecture.md
@@ -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,8 +90,7 @@ 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.
 
 ### Chrome Extension Bridge (`src/extension/`)
@@ -113,14 +116,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"]

From f662374fec98eb7ed9b4dcdf4b0c847112bac9df Mon Sep 17 00:00:00 2001
From: nicosampler <nf.dominguez.87@gmail.com>
Date: Thu, 4 Jun 2026 11:56:51 -0300
Subject: [PATCH 3/7] docs: clarify e2e extension usage

---
 dapp/e2e/AGENTS.md            | 4 ++--
 dapp/e2e/README.md            | 5 ++---
 dapp/e2e/fixtures/stack.ts    | 4 +---
 dapp/e2e/package.json         | 2 +-
 dapp/e2e/playwright.config.ts | 2 --
 5 files changed, 6 insertions(+), 11 deletions(-)

diff --git a/dapp/e2e/AGENTS.md b/dapp/e2e/AGENTS.md
index e1444cb9..8098b1aa 100644
--- a/dapp/e2e/AGENTS.md
+++ b/dapp/e2e/AGENTS.md
@@ -4,13 +4,13 @@ This file applies only to `dapp/e2e/`. For monorepo-wide rules, see [`../../AGEN
 
 ## Scope
 
-`dapp/e2e` is a black-box Playwright package. It tests cross-package wiring through stable surfaces: wallet-service HTTP, Carpincho web or extension UI, the dApp UI, and browser-visible provider events.
+`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`, `CARPINCHO_URL`, `DAPP_URL`, `EXTENSION_PATH`) instead of hard-coding alternate targets.
+- 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.
diff --git a/dapp/e2e/README.md b/dapp/e2e/README.md
index 03180759..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` |
 
@@ -36,8 +35,8 @@ When the four packages publish independently and the dev kit becomes a monorepo
 ### Prerequisites
 
 The full local stack must be running. Follow the root
-[quick start](../../README.md#quick-start), including the wallet, dApp, and
-extension setup steps.
+[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,
       },
     },

From 53215573ccd59e1594971a503cf6ca453020b874 Mon Sep 17 00:00:00 2001
From: Gabito Esmiapodo <4015436+gabitoesmiapodo@users.noreply.github.com>
Date: Thu, 4 Jun 2026 12:55:45 -0300
Subject: [PATCH 4/7] fix(wallet): radix reset-vault confirm and full
 preference wipe

Replace the native window.confirm on the unlock screen with a centered
Radix Sheet + DangerConfirm, matching the rest of the app. Reset now
wipes every carpincho-namespaced storage key (theme, auto-lock, runtime
config) and reloads so all providers re-init from a clean slate, instead
of only clearing the vault blob.
---
 AGENTS.md                                     |  1 +
 .../src/components/ui/DangerConfirm.tsx       | 15 +++---
 carpincho-wallet/src/vault/VaultContext.tsx   | 19 ++++----
 carpincho-wallet/src/vault/storage.ts         | 17 +++++++
 carpincho-wallet/src/views/UnlockView.tsx     | 37 ++++++++++----
 .../test/vault/wipeAllPersistedData.test.ts   | 40 ++++++++++++++++
 .../test/views/UnlockView.test.tsx            | 48 +++++++++++++++++++
 7 files changed, 153 insertions(+), 24 deletions(-)
 create mode 100644 carpincho-wallet/test/vault/wipeAllPersistedData.test.ts
 create mode 100644 carpincho-wallet/test/views/UnlockView.test.tsx

diff --git a/AGENTS.md b/AGENTS.md
index effe61e1..615e4ebd 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -70,6 +70,7 @@ Subproject docs must not restate root rules. They should describe only their loc
 - 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
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/vault/VaultContext.tsx b/carpincho-wallet/src/vault/VaultContext.tsx
index 0b809933..5f9fca24 100644
--- a/carpincho-wallet/src/vault/VaultContext.tsx
+++ b/carpincho-wallet/src/vault/VaultContext.tsx
@@ -30,7 +30,7 @@ import {
   loadAutoLockOption,
   loadVault,
   rotateVault,
-  wipeVault,
+  wipeAllPersistedData,
   writeAutoLockOption,
   writeFreshVault,
 } from '@/vault/storage'
@@ -212,13 +212,16 @@ export const VaultProvider = ({ children }: PropsWithChildren): JSX.Element => {
   )
 
   const destroyVault = useCallback((): void => {
-    void wipeMemory().catch(() => undefined)
-    wipeVault()
-    setVaultExists(false)
-    setIsLocked(true)
-    bump()
-    broadcastConnectionState(false)
-  }, [bump, broadcastConnectionState])
+    void (async () => {
+      // Await the async session/snapshot wipes (they survive a reload) before clearing
+      // localStorage, then reload so every provider re-inits from empty storage.
+      await wipeMemory().catch(() => undefined)
+      await persistWalletSnapshot(null).catch(() => undefined)
+      wipeAllPersistedData()
+      broadcastConnectionState(false)
+      window.location.reload()
+    })()
+  }, [broadcastConnectionState])
 
   // dapp-api AccountsChangedEvent payload (Wallet[]); [] when locked.
   const accountsChangedPayload = useCallback((): unknown[] => {
diff --git a/carpincho-wallet/src/vault/storage.ts b/carpincho-wallet/src/vault/storage.ts
index 72017cae..5508e454 100644
--- a/carpincho-wallet/src/vault/storage.ts
+++ b/carpincho-wallet/src/vault/storage.ts
@@ -48,6 +48,23 @@ export const wipeVault = (): void => {
   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) === true) {
+      stale.push(key)
+    }
+  }
+  for (const key of stale) {
+    localStorage.removeItem(key)
+  }
+}
+
 const KEY_AUTO_LOCK = 'carpincho.autoLockOption'
 
 export const AUTO_LOCK_OPTIONS = ['never', '1m', '5m', '1h'] as const
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/test/vault/wipeAllPersistedData.test.ts b/carpincho-wallet/test/vault/wipeAllPersistedData.test.ts
new file mode 100644
index 00000000..e057385f
--- /dev/null
+++ b/carpincho-wallet/test/vault/wipeAllPersistedData.test.ts
@@ -0,0 +1,40 @@
+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)
+  })
+})
diff --git a/carpincho-wallet/test/views/UnlockView.test.tsx b/carpincho-wallet/test/views/UnlockView.test.tsx
new file mode 100644
index 00000000..6f32c432
--- /dev/null
+++ b/carpincho-wallet/test/views/UnlockView.test.tsx
@@ -0,0 +1,48 @@
+import { strict as assert } from 'node:assert'
+import { afterEach, describe, it } from 'node:test'
+import { cleanup, render, screen } 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: () => 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)
+  })
+})

From 0d9d0f12b86aa300054a99f81536aeb48abe463c Mon Sep 17 00:00:00 2001
From: Gabito Esmiapodo <4015436+gabitoesmiapodo@users.noreply.github.com>
Date: Thu, 4 Jun 2026 13:34:34 -0300
Subject: [PATCH 5/7] fix(wallet): wipe WalletConnect and direct-connection
 data on vault reset

Vault reset only cleared the carpincho localStorage prefix, leaving two
persistence surfaces behind: WalletConnect sessions/pairings/keychain in
its IndexedDB database, and the remembered direct-connected dApp origins
in chrome.storage.session. Both now cleared so no stale state or dApp
connection history survives into the next wallet.

- wipeWalletConnectStorage deletes the WalletConnect IndexedDB database
- clearDirectConnectedOrigins removes the connected-origins session key
- destroyVault orchestrates all wipes and restores React state as a
  fallback in case the reload is a no-op
- wipeAllPersistedData removes keys defensively so one failure cannot
  strand the rest
---
 .../src/extension/directConnections.ts        |  14 +++
 carpincho-wallet/src/vault/VaultContext.tsx   |  32 ++++--
 carpincho-wallet/src/vault/storage.ts         |  10 +-
 carpincho-wallet/src/wc/storage.ts            |  31 +++++
 .../clearDirectConnectedOrigins.test.ts       |  57 +++++++++
 .../test/vault/destroyVault.test.tsx          | 108 ++++++++++++++++++
 .../test/vault/wipeAllPersistedData.test.ts   |  35 ++++++
 .../test/views/UnlockView.test.tsx            |  25 +++-
 .../test/wc/wipeWalletConnectStorage.test.ts  |  53 +++++++++
 9 files changed, 349 insertions(+), 16 deletions(-)
 create mode 100644 carpincho-wallet/src/wc/storage.ts
 create mode 100644 carpincho-wallet/test/extension/clearDirectConnectedOrigins.test.ts
 create mode 100644 carpincho-wallet/test/vault/destroyVault.test.tsx
 create mode 100644 carpincho-wallet/test/wc/wipeWalletConnectStorage.test.ts

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 5f9fca24..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'
@@ -35,6 +36,7 @@ import {
   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,17 +213,23 @@ export const VaultProvider = ({ children }: PropsWithChildren): JSX.Element => {
     [bump, broadcastConnectionState],
   )
 
-  const destroyVault = useCallback((): void => {
-    void (async () => {
-      // Await the async session/snapshot wipes (they survive a reload) before clearing
-      // localStorage, then reload so every provider re-inits from empty storage.
-      await wipeMemory().catch(() => undefined)
-      await persistWalletSnapshot(null).catch(() => undefined)
-      wipeAllPersistedData()
-      broadcastConnectionState(false)
-      window.location.reload()
-    })()
-  }, [broadcastConnectionState])
+  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.
   const accountsChangedPayload = useCallback((): unknown[] => {
diff --git a/carpincho-wallet/src/vault/storage.ts b/carpincho-wallet/src/vault/storage.ts
index 5508e454..6bfb9549 100644
--- a/carpincho-wallet/src/vault/storage.ts
+++ b/carpincho-wallet/src/vault/storage.ts
@@ -56,12 +56,18 @@ 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) === true) {
+    if (key?.startsWith(STORAGE_PREFIX)) {
       stale.push(key)
     }
   }
   for (const key of stale) {
-    localStorage.removeItem(key)
+    // 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.
+    }
   }
 }
 
diff --git a/carpincho-wallet/src/wc/storage.ts b/carpincho-wallet/src/wc/storage.ts
new file mode 100644
index 00000000..811c85d2
--- /dev/null
+++ b/carpincho-wallet/src/wc/storage.ts
@@ -0,0 +1,31 @@
+// 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) => {
+    let settled = false
+    const finish = (): void => {
+      if (!settled) {
+        settled = true
+        resolve()
+      }
+    }
+    try {
+      const request = idb.deleteDatabase(WALLET_CONNECT_DB)
+      request.onsuccess = finish
+      request.onerror = finish
+      // 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.
+      request.onblocked = finish
+    } catch {
+      finish()
+    }
+  })
+}
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
index e057385f..59f9168a 100644
--- a/carpincho-wallet/test/vault/wipeAllPersistedData.test.ts
+++ b/carpincho-wallet/test/vault/wipeAllPersistedData.test.ts
@@ -37,4 +37,39 @@ describe('wipeAllPersistedData', () => {
     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
index 6f32c432..abf9b9f8 100644
--- a/carpincho-wallet/test/views/UnlockView.test.tsx
+++ b/carpincho-wallet/test/views/UnlockView.test.tsx
@@ -1,6 +1,6 @@
 import { strict as assert } from 'node:assert'
 import { afterEach, describe, it } from 'node:test'
-import { cleanup, render, screen } from '@testing-library/react'
+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'
@@ -40,9 +40,30 @@ describe('UnlockView reset vault', () => {
   it('calls destroyVault when the reset is confirmed', async () => {
     const user = userEvent.setup()
     const calls: number[] = []
-    renderUnlock({ destroyVault: () => calls.push(1) })
+    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()
+  })
+})

From ec73a68f8e41ad47b148cd90a8e096fd80dc26ca Mon Sep 17 00:00:00 2001
From: Gabito Esmiapodo <4015436+gabitoesmiapodo@users.noreply.github.com>
Date: Thu, 4 Jun 2026 13:44:39 -0300
Subject: [PATCH 6/7] refactor(wallet): drop dead wipeVault and simplify WC
 delete resolution

---
 carpincho-wallet/src/vault/storage.ts |  5 -----
 carpincho-wallet/src/wc/storage.ts    | 16 +++++-----------
 2 files changed, 5 insertions(+), 16 deletions(-)

diff --git a/carpincho-wallet/src/vault/storage.ts b/carpincho-wallet/src/vault/storage.ts
index 6bfb9549..ae277585 100644
--- a/carpincho-wallet/src/vault/storage.ts
+++ b/carpincho-wallet/src/vault/storage.ts
@@ -43,11 +43,6 @@ 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'
diff --git a/carpincho-wallet/src/wc/storage.ts b/carpincho-wallet/src/wc/storage.ts
index 811c85d2..a9e698f7 100644
--- a/carpincho-wallet/src/wc/storage.ts
+++ b/carpincho-wallet/src/wc/storage.ts
@@ -10,22 +10,16 @@ export const wipeWalletConnectStorage = async (): Promise<void> => {
     return
   }
   await new Promise<void>((resolve) => {
-    let settled = false
-    const finish = (): void => {
-      if (!settled) {
-        settled = true
-        resolve()
-      }
-    }
     try {
       const request = idb.deleteDatabase(WALLET_CONNECT_DB)
-      request.onsuccess = finish
-      request.onerror = finish
+      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.
-      request.onblocked = finish
+      // (onblocked may later be followed by onsuccess, but resolving an already-settled promise is a no-op.)
+      request.onblocked = () => resolve()
     } catch {
-      finish()
+      resolve()
     }
   })
 }

From 7bd80d00c7064bad2325ba5632c41e469b3315c0 Mon Sep 17 00:00:00 2001
From: Gabito Esmiapodo <4015436+gabitoesmiapodo@users.noreply.github.com>
Date: Thu, 4 Jun 2026 14:06:38 -0300
Subject: [PATCH 7/7] docs(wallet): document vault reset full-wipe flow and
 wc/storage

---
 carpincho-wallet/architecture.md | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/carpincho-wallet/architecture.md b/carpincho-wallet/architecture.md
index e6f21632..467708a9 100644
--- a/carpincho-wallet/architecture.md
+++ b/carpincho-wallet/architecture.md
@@ -92,6 +92,7 @@ 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, 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/`)
 
@@ -102,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.
 
@@ -203,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.