From 842b56670064c692eb0bdb3e0115f0c1b093d612 Mon Sep 17 00:00:00 2001
From: darepo-doc-bot <bot@lightning.engineering>
Date: Sun, 28 Jun 2026 07:52:28 +0000
Subject: [PATCH] docs: nightly doc-gardening sweep 2026-06-28

Automated sweep via .claude/skills/doc-gardening.
Updates per-package CLAUDE.md/AGENTS.md, docs/index.md
entries, and ARCHITECTURE.md as needed.

New packages documented (from wasm-wallet-bindings PR #803):
- cmd/walletdk-wasm: browser WASM entry point over mobile facade
- sdk/walletdk/mobile: gomobile-safe JSON facade over sdk/walletdk

New packages documented (pre-existing, missing docs):
- chainfees: chainfee.Estimator implementations and combinators
- coinselect: coin-type-agnostic largest-first selector
- internal/sqlbase: WASM-only SQL walletdb backend for lwwallet

Updated stale packages:
- sdk/walletdk: add GetExitPlan, SweepWallet RPC methods; new
  Entry DTOs (EntryPhase, EntryProgress, EntryRequest,
  EntryFailureCode, FailureCode field); error reconstruction
  mechanism via errmap.go
- oor: add ErrOutputPolicyViolation, ErrUserBalanceExceeded
  typed submit errors (PR #807)

Infra:
- db: sync AGENTS.md to CLAUDE.md (pre-existing drift)
- ARCHITECTURE.md: add five new packages to layer tables
- docs/index.md: add walletdk_mobile.md entry
---
 ARCHITECTURE.md               |  5 ++
 chainfees/AGENTS.md           | 48 ++++++++++++++++++
 chainfees/CLAUDE.md           | 48 ++++++++++++++++++
 cmd/walletdk-wasm/AGENTS.md   | 52 +++++++++++++++++++
 cmd/walletdk-wasm/CLAUDE.md   | 52 +++++++++++++++++++
 coinselect/AGENTS.md          | 49 ++++++++++++++++++
 coinselect/CLAUDE.md          | 49 ++++++++++++++++++
 db/AGENTS.md                  | 16 +++---
 docs/index.md                 |  1 +
 internal/sqlbase/AGENTS.md    | 39 +++++++++++++++
 internal/sqlbase/CLAUDE.md    | 39 +++++++++++++++
 oor/AGENTS.md                 | 16 ++++++
 oor/CLAUDE.md                 | 16 ++++++
 sdk/walletdk/AGENTS.md        | 58 ++++++++++++++++++---
 sdk/walletdk/CLAUDE.md        | 40 ++++++++++++++-
 sdk/walletdk/mobile/AGENTS.md | 94 +++++++++++++++++++++++++++++++++++
 sdk/walletdk/mobile/CLAUDE.md | 94 +++++++++++++++++++++++++++++++++++
 17 files changed, 699 insertions(+), 17 deletions(-)
 create mode 100644 chainfees/AGENTS.md
 create mode 100644 chainfees/CLAUDE.md
 create mode 100644 cmd/walletdk-wasm/AGENTS.md
 create mode 100644 cmd/walletdk-wasm/CLAUDE.md
 create mode 100644 coinselect/AGENTS.md
 create mode 100644 coinselect/CLAUDE.md
 create mode 100644 internal/sqlbase/AGENTS.md
 create mode 100644 internal/sqlbase/CLAUDE.md
 create mode 100644 sdk/walletdk/mobile/AGENTS.md
 create mode 100644 sdk/walletdk/mobile/CLAUDE.md

diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
index ad59aaf2b..5ae4bb5fe 100644
--- a/ARCHITECTURE.md
+++ b/ARCHITECTURE.md
@@ -28,6 +28,7 @@ package may import from a higher layer.
 | [`lib/recovery`](lib/recovery/) | Immutable recovery proof graph, session state machine, TLV codec for unilateral exit |
 | [`unrollplan`](unrollplan/) | Pure dependency-resolution planner driving unilateral-exit broadcast/sweep ordering |
 | [`vhtlcrecovery`](vhtlcrecovery/) | Durable control-plane types for vHTLC on-chain recovery jobs (action, state, script parameters, swap linkage) |
+| [`coinselect`](coinselect/) | Coin-type-agnostic coin-selection algorithm (largest-first) shared by vtxo and swapwallet; no wallet or RPC dependencies |
 
 ### Layer 2: Infrastructure (Chain, Storage, Messaging)
 
@@ -43,6 +44,8 @@ package may import from a higher layer.
 | [`lwwallet`](lwwallet/) | Lightweight in-process wallet (btcwallet + Esplora, no external LND) |
 | [`btcwbackend`](btcwbackend/) | Neutrino-backed wallet backend (btcwallet + compact block filters) |
 | [`walletcore`](walletcore/) | Shared wallet abstractions and boarding logic used by lwwallet and btcwbackend |
+| [`chainfees`](chainfees/) | `chainfee.Estimator` implementations and combinators (WalletKit, mempool.space, MinEstimator) |
+| [`internal/sqlbase`](internal/sqlbase/) | WASM-only SQL walletdb backend for lwwallet (js/wasm build tag); maps btcwallet nested-bucket semantics to SQL |
 | [`proofkeys`](proofkeys/) | Interface for wallet-managed key derivation and indexer proof signing |
 | [`fraud`](fraud/) | Fraud detection actor: watches OOR ancestor outpoints on-chain and triggers unilateral exit when an ancestor is spent |
 | [`vhtlcrecovery/coordinator`](vhtlcrecovery/coordinator/) | Runtime coordinator for durable vHTLC recovery jobs: arms, escalates into unroll, cancels, and reconciles after restart |
@@ -61,10 +64,12 @@ package may import from a higher layer.
 | [`sdk/ark`](sdk/ark/) | Consumer-facing Go SDK facade: remote or embedded daemon access with typed models |
 | [`sdk/swaps`](sdk/swaps/) | Lightning-to-Ark / Ark-to-Lightning atomic swap SDK with durable FSM flows |
 | [`sdk/walletdk`](sdk/walletdk/) | Wallet-shaped SDK facade for host apps: embeds the daemon in-process, dials it over a private bufconn transport, exposes typed methods for the seven core wallet verbs (create, unlock, send, recv, list, balance, exit). The highest-level layer in the stack; wraps `walletdkrpc.WalletService`. Wallet RPC methods gated behind `walletdkrpc` (which transitively requires `swapruntime`) |
+| [`sdk/walletdk/mobile`](sdk/walletdk/mobile/) | Gomobile-safe JSON-bytes-in/out facade over sdk/walletdk for iOS/Android/WASM targets; singleton lifecycle, pull-based Subscribe |
 | [`swapwallet`](swapwallet/) | Optional daemon-side `walletdkrpc.WalletService` implementation (build tags `walletdkrpc swapruntime`): composes the swap subsystem, cooperative leave, boarding, ledger, and unilateral-exit registry behind one flat, swap-vocabulary-free wallet API |
 | [`swapclientserver`](swapclientserver/) | Optional daemon-side swap subserver (build tag `swapruntime`): translates `swapclientrpc` RPCs into `sdk/swaps` operations and manages the daemon-local worker registry |
 | [`cmd/darepod`](cmd/darepod/) | Daemon entry point |
 | [`cmd/darepocli`](cmd/darepocli/) | CLI client |
+| [`cmd/walletdk-wasm`](cmd/walletdk-wasm/) | Browser/WASM entry point: installs `walletdkCall` JS bridge over sdk/walletdk/mobile (js/wasm only) |
 | [`timeout`](timeout/) | Generic timeout scheduling actor |
 | [`indexer`](indexer/) | Server indexing client for receive script registration |
 | [`arkrpc`](arkrpc/) | Server-side gRPC service definitions (ArkService, IndexerService) |
diff --git a/chainfees/AGENTS.md b/chainfees/AGENTS.md
new file mode 100644
index 000000000..3a910c1c1
--- /dev/null
+++ b/chainfees/AGENTS.md
@@ -0,0 +1,48 @@
+# chainfees
+
+## Purpose
+
+Provides reusable `chainfee.Estimator` implementations and combinators for
+wallet and daemon chain backends. Bundles three concrete estimators —
+`WalletKitEstimator` (queries lnd WalletKit), `MempoolSpaceEstimator` (queries
+mempool.space API), and `MinEstimator` (selects the lowest successful estimate
+across a set of child estimators) — so backends can compose fee estimation
+strategies without re-implementing the interface.
+
+## Key Types
+
+- `WalletKitEstimator` — proxies fee estimates to an lndclient WalletKitClient
+  with configurable timeout and optional degraded-mode fallback on error.
+- `WalletKitEstimatorConfig` — config for `WalletKitEstimator`: client,
+  logger, timeout, fallback flag.
+- `MempoolSpaceEstimator` — queries the mempool.space recommended-fee endpoint
+  with configurable URL, cache TTL, and chain params. Caches the last
+  successful response to avoid hammering the API on every block.
+- `MempoolSpaceConfig` — config for `MempoolSpaceEstimator`.
+- `MinEstimator` — queries multiple child estimators and returns the minimum
+  successful relay fee per KW.
+- `NamedEstimator` — wraps a child estimator with a stable name for logging.
+
+## Relationships
+
+- **Depends on**: `lnd/lnwallet/chainfee` (Estimator interface),
+  `lndclient` (WalletKitClient), `btcd/btcutil`, `btclog`.
+- **Depended on by**: `darepod` (daemon fee estimation),
+  `chainbackends` (lnd-backed fee estimation adapter).
+- **Sends**: nothing.
+- **Receives**: nothing.
+
+## Invariants
+
+- All three exported estimator types implement
+  `github.com/lightningnetwork/lnd/lnwallet/chainfee.Estimator`.
+- `MempoolSpaceEstimator` caches the last successful response at the
+  configured TTL; concurrent callers share the cached estimate without
+  issuing duplicate HTTP requests.
+- `WalletKitEstimator` with the fallback flag returns a static relay fee
+  rather than propagating errors, so fee estimation can degrade gracefully
+  when lnd is temporarily unreachable.
+
+## Deep Docs
+
+- [ARCHITECTURE.md](../ARCHITECTURE.md) — System-wide package map.
diff --git a/chainfees/CLAUDE.md b/chainfees/CLAUDE.md
new file mode 100644
index 000000000..3a910c1c1
--- /dev/null
+++ b/chainfees/CLAUDE.md
@@ -0,0 +1,48 @@
+# chainfees
+
+## Purpose
+
+Provides reusable `chainfee.Estimator` implementations and combinators for
+wallet and daemon chain backends. Bundles three concrete estimators —
+`WalletKitEstimator` (queries lnd WalletKit), `MempoolSpaceEstimator` (queries
+mempool.space API), and `MinEstimator` (selects the lowest successful estimate
+across a set of child estimators) — so backends can compose fee estimation
+strategies without re-implementing the interface.
+
+## Key Types
+
+- `WalletKitEstimator` — proxies fee estimates to an lndclient WalletKitClient
+  with configurable timeout and optional degraded-mode fallback on error.
+- `WalletKitEstimatorConfig` — config for `WalletKitEstimator`: client,
+  logger, timeout, fallback flag.
+- `MempoolSpaceEstimator` — queries the mempool.space recommended-fee endpoint
+  with configurable URL, cache TTL, and chain params. Caches the last
+  successful response to avoid hammering the API on every block.
+- `MempoolSpaceConfig` — config for `MempoolSpaceEstimator`.
+- `MinEstimator` — queries multiple child estimators and returns the minimum
+  successful relay fee per KW.
+- `NamedEstimator` — wraps a child estimator with a stable name for logging.
+
+## Relationships
+
+- **Depends on**: `lnd/lnwallet/chainfee` (Estimator interface),
+  `lndclient` (WalletKitClient), `btcd/btcutil`, `btclog`.
+- **Depended on by**: `darepod` (daemon fee estimation),
+  `chainbackends` (lnd-backed fee estimation adapter).
+- **Sends**: nothing.
+- **Receives**: nothing.
+
+## Invariants
+
+- All three exported estimator types implement
+  `github.com/lightningnetwork/lnd/lnwallet/chainfee.Estimator`.
+- `MempoolSpaceEstimator` caches the last successful response at the
+  configured TTL; concurrent callers share the cached estimate without
+  issuing duplicate HTTP requests.
+- `WalletKitEstimator` with the fallback flag returns a static relay fee
+  rather than propagating errors, so fee estimation can degrade gracefully
+  when lnd is temporarily unreachable.
+
+## Deep Docs
+
+- [ARCHITECTURE.md](../ARCHITECTURE.md) — System-wide package map.
diff --git a/cmd/walletdk-wasm/AGENTS.md b/cmd/walletdk-wasm/AGENTS.md
new file mode 100644
index 000000000..2ee514bc8
--- /dev/null
+++ b/cmd/walletdk-wasm/AGENTS.md
@@ -0,0 +1,52 @@
+# cmd/walletdk-wasm
+
+## Purpose
+
+Browser/WASM entry point for the embedded walletdk runtime. Installs a global
+`walletdkCall(method, request)` JavaScript function via `syscall/js` and
+dispatches each call to the corresponding `sdk/walletdk/mobile` verb, returning
+a JS Promise. The daemon, swap, and OOR machinery all run in-process inside the
+browser VM with no separate gateway. The bridge never reaches `walletdk.Client`
+directly — it always goes through the mobile facade so WASM behavior stays in
+sync with the gomobile bindings.
+
+Only compiles with `GOOS=js GOARCH=wasm -tags "mobile walletdkrpc swapruntime"`.
+`stub.go` provides an empty build so `go build ./...` succeeds on other targets.
+
+## Key Types
+
+- `main` — installs `walletdkCall` on `js.Global()`, dispatches a
+  `walletdk-ready` custom event, then parks the Go runtime so exported
+  callbacks remain live for the page lifetime.
+- `walletCall` — the single JS entry point; dispatches the method name to the
+  corresponding `mobile.*` verb and wraps the result in a Promise.
+- `subscriptionHandle` — wraps `*mobile.Subscription` as a JS object with
+  `next()` (Promise → next entry JSON or null at EOF) and `close()` methods.
+
+## Relationships
+
+- **Depends on**: `sdk/walletdk/mobile` (all wallet operations proxied through
+  the mobile facade).
+- **Depended on by**: browser host applications, React Native WASM bridges.
+- **Sends**: nothing (invokes mobile facade functions in goroutines).
+- **Receives** ← JS host: `walletdkCall(method, request)` invocations.
+
+## Invariants
+
+- `walletCall` is the only JS-exported function; all verb dispatch happens
+  inside its switch. Additional `js.Func` values outside `promise()` must be
+  released manually — `promise()` already releases its own executor immediately
+  after the Promise constructor returns to prevent per-call handle leaks.
+- The browser data dir defaults to `/darepo` (injected by `startConfig`).
+  Without this override, `os.UserHomeDir` fails under `wasm_exec.js` with
+  `"$HOME is not defined"` and aborts start before the wallet boots. Callers
+  may override via `data_dir` in the start request.
+- This package must not import `sdk/walletdk` directly; all access goes through
+  the `mobile` facade to keep the WASM bridge and gomobile bindings in sync.
+
+## Deep Docs
+
+- [sdk/walletdk/mobile/CLAUDE.md](../../sdk/walletdk/mobile/CLAUDE.md) —
+  The gomobile facade this package wraps.
+- [sdk/walletdk/CLAUDE.md](../../sdk/walletdk/CLAUDE.md) — Underlying Go SDK.
+- [ARCHITECTURE.md](../../ARCHITECTURE.md) — System-wide package map.
diff --git a/cmd/walletdk-wasm/CLAUDE.md b/cmd/walletdk-wasm/CLAUDE.md
new file mode 100644
index 000000000..2ee514bc8
--- /dev/null
+++ b/cmd/walletdk-wasm/CLAUDE.md
@@ -0,0 +1,52 @@
+# cmd/walletdk-wasm
+
+## Purpose
+
+Browser/WASM entry point for the embedded walletdk runtime. Installs a global
+`walletdkCall(method, request)` JavaScript function via `syscall/js` and
+dispatches each call to the corresponding `sdk/walletdk/mobile` verb, returning
+a JS Promise. The daemon, swap, and OOR machinery all run in-process inside the
+browser VM with no separate gateway. The bridge never reaches `walletdk.Client`
+directly — it always goes through the mobile facade so WASM behavior stays in
+sync with the gomobile bindings.
+
+Only compiles with `GOOS=js GOARCH=wasm -tags "mobile walletdkrpc swapruntime"`.
+`stub.go` provides an empty build so `go build ./...` succeeds on other targets.
+
+## Key Types
+
+- `main` — installs `walletdkCall` on `js.Global()`, dispatches a
+  `walletdk-ready` custom event, then parks the Go runtime so exported
+  callbacks remain live for the page lifetime.
+- `walletCall` — the single JS entry point; dispatches the method name to the
+  corresponding `mobile.*` verb and wraps the result in a Promise.
+- `subscriptionHandle` — wraps `*mobile.Subscription` as a JS object with
+  `next()` (Promise → next entry JSON or null at EOF) and `close()` methods.
+
+## Relationships
+
+- **Depends on**: `sdk/walletdk/mobile` (all wallet operations proxied through
+  the mobile facade).
+- **Depended on by**: browser host applications, React Native WASM bridges.
+- **Sends**: nothing (invokes mobile facade functions in goroutines).
+- **Receives** ← JS host: `walletdkCall(method, request)` invocations.
+
+## Invariants
+
+- `walletCall` is the only JS-exported function; all verb dispatch happens
+  inside its switch. Additional `js.Func` values outside `promise()` must be
+  released manually — `promise()` already releases its own executor immediately
+  after the Promise constructor returns to prevent per-call handle leaks.
+- The browser data dir defaults to `/darepo` (injected by `startConfig`).
+  Without this override, `os.UserHomeDir` fails under `wasm_exec.js` with
+  `"$HOME is not defined"` and aborts start before the wallet boots. Callers
+  may override via `data_dir` in the start request.
+- This package must not import `sdk/walletdk` directly; all access goes through
+  the `mobile` facade to keep the WASM bridge and gomobile bindings in sync.
+
+## Deep Docs
+
+- [sdk/walletdk/mobile/CLAUDE.md](../../sdk/walletdk/mobile/CLAUDE.md) —
+  The gomobile facade this package wraps.
+- [sdk/walletdk/CLAUDE.md](../../sdk/walletdk/CLAUDE.md) — Underlying Go SDK.
+- [ARCHITECTURE.md](../../ARCHITECTURE.md) — System-wide package map.
diff --git a/coinselect/AGENTS.md b/coinselect/AGENTS.md
new file mode 100644
index 000000000..ebe042389
--- /dev/null
+++ b/coinselect/AGENTS.md
@@ -0,0 +1,49 @@
+# coinselect
+
+## Purpose
+
+Provides a single, coin-type-agnostic coin-selection algorithm shared across
+the client. The package holds no wallet, actor, or RPC dependencies so every
+layer that needs a covering subset — the VTXO manager's reservation path and
+the swap wallet's send preview alike — selects through the same generic code
+rather than growing parallel implementations.
+
+## Key Types
+
+- `Request` — selection parameters: `Target` amount, `MinChange` floor,
+  `SweepAll` flag. `SweepAll` takes precedence and ignores `Target` and
+  `MinChange`.
+- `Result[T]` — selection outcome: `Selected` subset, `Total`, `Change`.
+- `AmountFunc[T]` — callback to extract a `btcutil.Amount` from a candidate
+  of type `T`.
+
+## Selection Errors
+
+- `ErrSelectionShortfall` — candidate set cannot cover target; `Result.Total`
+  carries the full candidate sum so callers can render a precise message.
+- `ErrChangeBelowMin` — covering selection exists but change is below the
+  requested minimum and no exact-fit set was found.
+- `ErrNoCandidates` — empty candidate set passed to the selector.
+- `ErrInvalidTarget` — non-positive target in a bounded selection.
+
+## Relationships
+
+- **Depends on**: `btcd/btcutil` (amount type).
+- **Depended on by**: `vtxo` (VTXO manager reservation path),
+  `swapwallet` (send-preview coin selection).
+- **Sends**: nothing.
+- **Receives**: nothing.
+
+## Invariants
+
+- `SweepAll` takes precedence: when set, `Target` and `MinChange` are ignored
+  and every candidate is selected.
+- The selector is policy-free: it reports why a pass failed via typed errors
+  and leaves layer-specific diagnostics (e.g. locked liquidity vs. true
+  shortfall) to callers.
+- Error values carry no total on `ErrNoCandidates` and `ErrInvalidTarget`;
+  only `ErrSelectionShortfall` and `ErrChangeBelowMin` populate `Result.Total`.
+
+## Deep Docs
+
+- [ARCHITECTURE.md](../ARCHITECTURE.md) — System-wide package map.
diff --git a/coinselect/CLAUDE.md b/coinselect/CLAUDE.md
new file mode 100644
index 000000000..ebe042389
--- /dev/null
+++ b/coinselect/CLAUDE.md
@@ -0,0 +1,49 @@
+# coinselect
+
+## Purpose
+
+Provides a single, coin-type-agnostic coin-selection algorithm shared across
+the client. The package holds no wallet, actor, or RPC dependencies so every
+layer that needs a covering subset — the VTXO manager's reservation path and
+the swap wallet's send preview alike — selects through the same generic code
+rather than growing parallel implementations.
+
+## Key Types
+
+- `Request` — selection parameters: `Target` amount, `MinChange` floor,
+  `SweepAll` flag. `SweepAll` takes precedence and ignores `Target` and
+  `MinChange`.
+- `Result[T]` — selection outcome: `Selected` subset, `Total`, `Change`.
+- `AmountFunc[T]` — callback to extract a `btcutil.Amount` from a candidate
+  of type `T`.
+
+## Selection Errors
+
+- `ErrSelectionShortfall` — candidate set cannot cover target; `Result.Total`
+  carries the full candidate sum so callers can render a precise message.
+- `ErrChangeBelowMin` — covering selection exists but change is below the
+  requested minimum and no exact-fit set was found.
+- `ErrNoCandidates` — empty candidate set passed to the selector.
+- `ErrInvalidTarget` — non-positive target in a bounded selection.
+
+## Relationships
+
+- **Depends on**: `btcd/btcutil` (amount type).
+- **Depended on by**: `vtxo` (VTXO manager reservation path),
+  `swapwallet` (send-preview coin selection).
+- **Sends**: nothing.
+- **Receives**: nothing.
+
+## Invariants
+
+- `SweepAll` takes precedence: when set, `Target` and `MinChange` are ignored
+  and every candidate is selected.
+- The selector is policy-free: it reports why a pass failed via typed errors
+  and leaves layer-specific diagnostics (e.g. locked liquidity vs. true
+  shortfall) to callers.
+- Error values carry no total on `ErrNoCandidates` and `ErrInvalidTarget`;
+  only `ErrSelectionShortfall` and `ErrChangeBelowMin` populate `Result.Total`.
+
+## Deep Docs
+
+- [ARCHITECTURE.md](../ARCHITECTURE.md) — System-wide package map.
diff --git a/db/AGENTS.md b/db/AGENTS.md
index 00ce565e9..535be0224 100644
--- a/db/AGENTS.md
+++ b/db/AGENTS.md
@@ -147,6 +147,14 @@ For field-level detail, use `go doc github.com/lightninglabs/darepo-client/db.<S
   collapsing on `(round_id, event_type, debit_account, credit_account)`.
   Renumbered from 000019 to land after `000019_oor_session_registry`,
   which merged to main while this work was in review.
+- `000021_vhtlc_recovery_job_generations` — rebuilds `vhtlc_recovery_jobs`
+  to widen the uniqueness key from `(swap_id, action)` to
+  `(swap_id, action, vtxo_txid, vtxo_vout)`, so a refreshed vHTLC (new
+  outpoint) arms a new recovery "generation" instead of colliding with the
+  prior job. SQLite cannot widen a UNIQUE constraint in place, so the table
+  is recreated, rows are copied, and the state / swap-action / unroll-target
+  indexes are rebuilt. The down migration collapses each `(swap_id, action)`
+  to its newest row before restoring the narrower constraint.
 - `000018_pending_intents` — generalizes the Board-only
   `pending_board_requests` outbox into a supertype/subtype set:
   `pending_intent_kinds` (enum table), `pending_intents` (header: 32-byte
@@ -156,14 +164,6 @@ For field-level detail, use `go doc github.com/lightninglabs/darepo-client/db.<S
   anchored outpoint, PK on the outpoint so a newer intent rebinds, FK to the
   header). Drops `pending_board_requests` outright (alpha; rows only exist
   in the narrow crash window between admission and round seal).
-- `000021_vhtlc_recovery_job_generations` — rebuilds `vhtlc_recovery_jobs`
-  to widen the uniqueness key from `(swap_id, action)` to
-  `(swap_id, action, vtxo_txid, vtxo_vout)`, so a refreshed vHTLC (new
-  outpoint) arms a new recovery "generation" instead of colliding with the
-  prior job. SQLite cannot widen a UNIQUE constraint in place, so the table
-  is recreated, rows are copied, and the state / swap-action / unroll-target
-  indexes are rebuilt. The down migration collapses each `(swap_id, action)`
-  to its newest row before restoring the narrower constraint.
 - `000017_spending_reservations` — adds `spending_reservations` table with
   `(outpoint_hash, outpoint_index)` PK, `owner_kind`, `owner_id`, and
   `created_at`. A row exists IFF the owning spend session was durably
diff --git a/docs/index.md b/docs/index.md
index 836141d0f..d5ffad9f5 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -18,6 +18,7 @@ into specific topics below.
 | [sdk_layered_architecture.md](sdk_layered_architecture.md) | SDK layering rationale: `sdk/ark` facade, remote vs. embedded modes, `sdk/swaps` future direction |
 | [swap_system.md](swap_system.md) | End-to-end swap walkthrough: vHTLC tree (collaborative vs. unilateral-exit leaves), receive (out-swap) and pay (in-swap) flows, the off-chain-first cancellation/timeout recovery ladder, same-Ark p2p detection, swap-server RPCs, and proof-gated indexer authorization, with mermaid diagrams |
 | [walletdk_integration.md](walletdk_integration.md) | Basic `walletdk` integration flow, startup/config examples, swap accounting, and wrapper guidance |
+| [walletdk_mobile.md](walletdk_mobile.md) | How to embed the walletdk daemon in a mobile app via the gomobile facade (`sdk/walletdk/mobile`): build tags, Start/Stop lifecycle, JSON verb convention, Subscription pull handle |
 | [walletdkrpc_build.md](walletdkrpc_build.md) | How to build and install the daemon and CLI with the wallet RPC subserver enabled (`walletdkrpc` + `swapruntime` tags) |
 | [seed_restore_recovery.md](seed_restore_recovery.md) | Restore a self-managed seed and recover Ark state from chain/indexer data |
 | [swap_background_execution.md](swap_background_execution.md) | Optional build-tagged daemon executor for background swap progress and daemon-backed CLI control |
diff --git a/internal/sqlbase/AGENTS.md b/internal/sqlbase/AGENTS.md
new file mode 100644
index 000000000..dcd27ea39
--- /dev/null
+++ b/internal/sqlbase/AGENTS.md
@@ -0,0 +1,39 @@
+# internal/sqlbase
+
+## Purpose
+
+SQL database abstraction layer that implements the `btcwallet` `walletdb.DB`
+interface over SQLite/Postgres for WASM environments. Maps the nested bucket
+semantics used by btcwallet's embedded KV store to parent-child SQL rows,
+allowing `lwwallet` to use a browser-safe SQLite backend instead of bbolt.
+Only compiles under `//go:build js && wasm`.
+
+## Key Types
+
+- `Config` — database configuration: `DriverName`, `Dsn`, `Timeout`,
+  `Schema`, `TableNamePrefix`, `SQLiteCmdReplacements`,
+  `WithTxLevelLock` flag.
+- `db` (unexported) — implements `walletdb.DB`; created by `NewSqlBackend`.
+
+## Relationships
+
+- **Depends on**: `btcwallet/walletdb` (interface to satisfy), `lnd/sqldb`
+  (connection helpers), `database/sql`.
+- **Depended on by**: `lwwallet` (WASM wallet backend, `walletdb_wasm.go`).
+- **Sends**: nothing.
+- **Receives**: nothing (called by lwwallet at wallet open time).
+
+## Invariants
+
+- Build constraint `//go:build js && wasm` gates the entire package; no
+  other build target sees it. Non-WASM lwwallet paths use a different
+  walletdb backend.
+- Nested buckets are modeled with a `parent_id` foreign key and a unique
+  index on `(parent_id, key)`. Schema changes require a migration.
+- `Init(maxConnections int)` must be called once before `NewSqlBackend` to
+  initialize the global connection pool; calling `NewSqlBackend` without
+  `Init` panics.
+
+## Deep Docs
+
+- [ARCHITECTURE.md](../../ARCHITECTURE.md) — System-wide package map.
diff --git a/internal/sqlbase/CLAUDE.md b/internal/sqlbase/CLAUDE.md
new file mode 100644
index 000000000..dcd27ea39
--- /dev/null
+++ b/internal/sqlbase/CLAUDE.md
@@ -0,0 +1,39 @@
+# internal/sqlbase
+
+## Purpose
+
+SQL database abstraction layer that implements the `btcwallet` `walletdb.DB`
+interface over SQLite/Postgres for WASM environments. Maps the nested bucket
+semantics used by btcwallet's embedded KV store to parent-child SQL rows,
+allowing `lwwallet` to use a browser-safe SQLite backend instead of bbolt.
+Only compiles under `//go:build js && wasm`.
+
+## Key Types
+
+- `Config` — database configuration: `DriverName`, `Dsn`, `Timeout`,
+  `Schema`, `TableNamePrefix`, `SQLiteCmdReplacements`,
+  `WithTxLevelLock` flag.
+- `db` (unexported) — implements `walletdb.DB`; created by `NewSqlBackend`.
+
+## Relationships
+
+- **Depends on**: `btcwallet/walletdb` (interface to satisfy), `lnd/sqldb`
+  (connection helpers), `database/sql`.
+- **Depended on by**: `lwwallet` (WASM wallet backend, `walletdb_wasm.go`).
+- **Sends**: nothing.
+- **Receives**: nothing (called by lwwallet at wallet open time).
+
+## Invariants
+
+- Build constraint `//go:build js && wasm` gates the entire package; no
+  other build target sees it. Non-WASM lwwallet paths use a different
+  walletdb backend.
+- Nested buckets are modeled with a `parent_id` foreign key and a unique
+  index on `(parent_id, key)`. Schema changes require a migration.
+- `Init(maxConnections int)` must be called once before `NewSqlBackend` to
+  initialize the global connection pool; calling `NewSqlBackend` without
+  `Init` panics.
+
+## Deep Docs
+
+- [ARCHITECTURE.md](../../ARCHITECTURE.md) — System-wide package map.
diff --git a/oor/AGENTS.md b/oor/AGENTS.md
index 0bd1ecfbd..937b58248 100644
--- a/oor/AGENTS.md
+++ b/oor/AGENTS.md
@@ -241,6 +241,22 @@ per-session durable actor's turn.
   `ClassifySubmitError` maps it to `*ErrLineageTooLarge` so wallet
   callers can switch on the cause without depending on the proto type.
 
+## Client-Facing Submit Errors
+
+`ClassifySubmitError` converts a generic submit-pipeline error into one of
+three typed, `errors.Is`-able sentinels. Callers receive the sentinel directly
+and can `errors.As` for detail fields without importing oorpb.
+
+- `*ErrLineageTooLarge` — operator rejected because the VTXO ancestry chain
+  exceeds the maximum allowed depth. Terminal for the same VTXO set.
+- `*ErrOutputPolicyViolation` — operator rejected because the output violates
+  its policy (e.g. per-VTXO amount cap). Terminal for the same output shape;
+  the caller must restructure the transfer.
+- `*ErrUserBalanceExceeded` — operator rejected because the recipient's total
+  balance would exceed `MaxUserBalance`. **Not terminal**: the caller can retry
+  after the recipient spends down its balance. Both `*ErrOutputPolicyViolation`
+  and `*ErrUserBalanceExceeded` carry a `Reason string` for diagnostics.
+
 ## Invariants
 
 - Checkpoint output collab path is 2-of-2
diff --git a/oor/CLAUDE.md b/oor/CLAUDE.md
index 0bd1ecfbd..937b58248 100644
--- a/oor/CLAUDE.md
+++ b/oor/CLAUDE.md
@@ -241,6 +241,22 @@ per-session durable actor's turn.
   `ClassifySubmitError` maps it to `*ErrLineageTooLarge` so wallet
   callers can switch on the cause without depending on the proto type.
 
+## Client-Facing Submit Errors
+
+`ClassifySubmitError` converts a generic submit-pipeline error into one of
+three typed, `errors.Is`-able sentinels. Callers receive the sentinel directly
+and can `errors.As` for detail fields without importing oorpb.
+
+- `*ErrLineageTooLarge` — operator rejected because the VTXO ancestry chain
+  exceeds the maximum allowed depth. Terminal for the same VTXO set.
+- `*ErrOutputPolicyViolation` — operator rejected because the output violates
+  its policy (e.g. per-VTXO amount cap). Terminal for the same output shape;
+  the caller must restructure the transfer.
+- `*ErrUserBalanceExceeded` — operator rejected because the recipient's total
+  balance would exceed `MaxUserBalance`. **Not terminal**: the caller can retry
+  after the recipient spends down its balance. Both `*ErrOutputPolicyViolation`
+  and `*ErrUserBalanceExceeded` carry a `Reason string` for diagnostics.
+
 ## Invariants
 
 - Checkpoint output collab path is 2-of-2
diff --git a/sdk/walletdk/AGENTS.md b/sdk/walletdk/AGENTS.md
index 73da35ef1..b32b4b309 100644
--- a/sdk/walletdk/AGENTS.md
+++ b/sdk/walletdk/AGENTS.md
@@ -49,8 +49,32 @@ For field-level detail, use `go doc github.com/lightninglabs/darepo-client/sdk/w
   bounded send and the swept total for sweep-all), `DepositRequest`/`Result` (boarding
   address + initial `Entry`), `ListRequest`, `ListResult` (tagged union
   on `View`, populates one of `Activity`/`VTXOs`/`Onchain`),
-  `ActivityList`, `VTXOInventory`, `OnchainHistory`, `Entry`,
-  `WalletVTXO`, `OnchainTx`.
+  `ActivityList`, `VTXOInventory`, `OnchainHistory`, `Entry`
+  (optional `Progress *EntryProgress` and `Request *EntryRequest`
+  sub-objects, both nil when absent; `Request` is a `Type`-tagged union
+  over lightning/onchain/ark; `FailureCode EntryFailureCode` classifies
+  terminal failure, empty on non-failed entries), `WalletVTXO`,
+  `OnchainTx`.
+- `EntryPhase` — wrapper-owned lifecycle phase string for an `Entry`
+  (`request_created`, `waiting_for_payment`, `payment_detected`,
+  `settling`, `confirmed`, `refunding`, `refunded`, `failed`,
+  `waiting_for_confirmation`, `unspecified`). Decoupled from proto enum
+  numbering.
+- `EntryProgress` — optional lifecycle metadata carried on `Entry.Progress`:
+  `Phase EntryPhase`, `PhaseLabel string`, `PaymentHash string`,
+  `Txid string`, `ConfirmationHeight int64`, `VTXOOutpoint string`.
+- `EntryRequest` — optional persisted request shape on `Entry.Request`;
+  discriminated by `Type` (`lightning`/`onchain`/`ark`).
+- `EntryFailureCode` — machine-readable failure classification on
+  `Entry.FailureCode` (`timed_out`, `expired`, `refunded`,
+  `needs_intervention`, `failed`, empty when not failed).
+- `GetExitPlanRequest` / `ExitPlanEntry` / `GetExitPlanResult` — exit-plan
+  preview DTOs. `GetExitPlan` returns a per-VTXO backing-wallet funding
+  plan: required sweepable amount, estimated on-chain fee, and whether the
+  backing wallet already holds sufficient funds.
+- `SweepWalletRequest` / `WalletSweepInput` / `SweepWalletResult` — sweep
+  DTOs. `SweepWallet` previews or broadcasts a backing-wallet sweep;
+  `SweepWalletRequest.Broadcast` controls whether the tx is actually sent.
 - `ExitRequest` / `ExitResult` / `ExitStatusRequest` /
   `ExitStatusResult` / `ExitJobStatus` — exit DTOs. `ExitRequest`
   carries the target outpoint plus an optional on-chain `Destination`
@@ -87,12 +111,24 @@ For field-level detail, use `go doc github.com/lightninglabs/darepo-client/sdk/w
 | `List` | Unified history view (Activity / VTXOs / Onchain) as a tagged-union `ListResult`. |
 | `Exit` | Trigger cooperative leave or unilateral unroll for a VTXO. |
 | `ExitStatus` | Query the phase of an exit job. |
+| `GetExitPlan` | Preview unilateral-exit readiness; returns per-VTXO backing-wallet funding plan. |
+| `SweepWallet` | Preview or broadcast a backing-wallet sweep. |
 | `Status` | Wallet readiness, balance, pending-entry count. |
 | `Subscribe` | Stream wallet activity (`Entry`) updates. |
 | `Stop` / `Close` | Shut down the embedded daemon, release the private transport. |
 | `Wait` | Single shared channel yielding the daemon's terminal run error. |
 | `GRPCConn` / `ArkRPC` / `SwapRPC` / `WalletRPC` | Escape hatches to the underlying private gRPC conn and raw clients. |
 
+## Error Reconstruction
+
+`errmap.go` installs a unary gRPC client interceptor (`errorReconstructInterceptor`)
+on both the embedded and remote client connections. The interceptor rewrites
+daemon rejection reasons (carried as gRPC status details of type
+`walletdkrpc.RejectionReason`) into `errors.Is`-able Go sentinels, so callers
+can match specific wallet failures without importing proto types. The
+interceptor is transparent on success and on errors that carry no rejection
+detail.
+
 ## Relationships
 
 - **Depends on**: `darepod` (embedded daemon runtime), `daemonrpc`
@@ -142,15 +178,23 @@ For field-level detail, use `go doc github.com/lightninglabs/darepo-client/sdk/w
   the wrapper boundary on builds without the `walletdkrpc` tag, before
   any RPC is attempted. `ErrSwapRuntimeUnavailable` is an alias for
   source-level compatibility with older swap-only callers.
-- `Entry.Kind`/`Entry.Status` / `ListResult.View` /
-  `WalletVTXO.Status` / `OnchainTx.Kind` / `ExitJobStatus` are
-  wrapper-owned lowercase strings (not proto enums). Projection lives
-  in `convert.go`, intentionally decoupled from proto enum
-  renumbering.
+- `Entry.Kind`/`Entry.Status` / `Entry.Progress.Phase` /
+  `Entry.Request.Type` / `ListResult.View` / `WalletVTXO.Status` /
+  `OnchainTx.Kind` / `ExitJobStatus` are wrapper-owned lowercase
+  strings (not proto enums). Projection lives in `convert.go`,
+  intentionally decoupled from proto enum renumbering.
 - `ListResult` is a discriminated union: read the variant named by
   `View` and treat the others as `nil`. Exhaustiveness is not
   enforced at compile time — switch on `View` rather than chaining
   nil checks.
+- `Entry.Progress` and `Entry.Request` are optional pointers: both are
+  `nil` when the daemon supplied no progress hint / persisted no
+  request, so nil-check before dereferencing. `Entry.Request` is a
+  discriminated union — read the variant named by `Type`
+  (`lightning`/`onchain`/`ark`) and treat the other fields as zero,
+  the same idiom as `ListResult.View`.
+- `Entry.FailureCode` is the zero `EntryFailureCode` (empty string) for
+  non-failed entries. Only condition on it when `Entry.Status == "failed"`.
 - `Wait()` is single-reader: same shared channel on every call. The
   channel delivers the daemon's terminal run error then closes; a
   closed channel reads as the zero error indefinitely.
diff --git a/sdk/walletdk/CLAUDE.md b/sdk/walletdk/CLAUDE.md
index c435f39ae..b32b4b309 100644
--- a/sdk/walletdk/CLAUDE.md
+++ b/sdk/walletdk/CLAUDE.md
@@ -51,8 +51,30 @@ For field-level detail, use `go doc github.com/lightninglabs/darepo-client/sdk/w
   on `View`, populates one of `Activity`/`VTXOs`/`Onchain`),
   `ActivityList`, `VTXOInventory`, `OnchainHistory`, `Entry`
   (optional `Progress *EntryProgress` and `Request *EntryRequest`
-  sub-objects, both nil when absent; `Request` is a `Type`-tagged
-  union over lightning/onchain/ark), `WalletVTXO`, `OnchainTx`.
+  sub-objects, both nil when absent; `Request` is a `Type`-tagged union
+  over lightning/onchain/ark; `FailureCode EntryFailureCode` classifies
+  terminal failure, empty on non-failed entries), `WalletVTXO`,
+  `OnchainTx`.
+- `EntryPhase` — wrapper-owned lifecycle phase string for an `Entry`
+  (`request_created`, `waiting_for_payment`, `payment_detected`,
+  `settling`, `confirmed`, `refunding`, `refunded`, `failed`,
+  `waiting_for_confirmation`, `unspecified`). Decoupled from proto enum
+  numbering.
+- `EntryProgress` — optional lifecycle metadata carried on `Entry.Progress`:
+  `Phase EntryPhase`, `PhaseLabel string`, `PaymentHash string`,
+  `Txid string`, `ConfirmationHeight int64`, `VTXOOutpoint string`.
+- `EntryRequest` — optional persisted request shape on `Entry.Request`;
+  discriminated by `Type` (`lightning`/`onchain`/`ark`).
+- `EntryFailureCode` — machine-readable failure classification on
+  `Entry.FailureCode` (`timed_out`, `expired`, `refunded`,
+  `needs_intervention`, `failed`, empty when not failed).
+- `GetExitPlanRequest` / `ExitPlanEntry` / `GetExitPlanResult` — exit-plan
+  preview DTOs. `GetExitPlan` returns a per-VTXO backing-wallet funding
+  plan: required sweepable amount, estimated on-chain fee, and whether the
+  backing wallet already holds sufficient funds.
+- `SweepWalletRequest` / `WalletSweepInput` / `SweepWalletResult` — sweep
+  DTOs. `SweepWallet` previews or broadcasts a backing-wallet sweep;
+  `SweepWalletRequest.Broadcast` controls whether the tx is actually sent.
 - `ExitRequest` / `ExitResult` / `ExitStatusRequest` /
   `ExitStatusResult` / `ExitJobStatus` — exit DTOs. `ExitRequest`
   carries the target outpoint plus an optional on-chain `Destination`
@@ -89,12 +111,24 @@ For field-level detail, use `go doc github.com/lightninglabs/darepo-client/sdk/w
 | `List` | Unified history view (Activity / VTXOs / Onchain) as a tagged-union `ListResult`. |
 | `Exit` | Trigger cooperative leave or unilateral unroll for a VTXO. |
 | `ExitStatus` | Query the phase of an exit job. |
+| `GetExitPlan` | Preview unilateral-exit readiness; returns per-VTXO backing-wallet funding plan. |
+| `SweepWallet` | Preview or broadcast a backing-wallet sweep. |
 | `Status` | Wallet readiness, balance, pending-entry count. |
 | `Subscribe` | Stream wallet activity (`Entry`) updates. |
 | `Stop` / `Close` | Shut down the embedded daemon, release the private transport. |
 | `Wait` | Single shared channel yielding the daemon's terminal run error. |
 | `GRPCConn` / `ArkRPC` / `SwapRPC` / `WalletRPC` | Escape hatches to the underlying private gRPC conn and raw clients. |
 
+## Error Reconstruction
+
+`errmap.go` installs a unary gRPC client interceptor (`errorReconstructInterceptor`)
+on both the embedded and remote client connections. The interceptor rewrites
+daemon rejection reasons (carried as gRPC status details of type
+`walletdkrpc.RejectionReason`) into `errors.Is`-able Go sentinels, so callers
+can match specific wallet failures without importing proto types. The
+interceptor is transparent on success and on errors that carry no rejection
+detail.
+
 ## Relationships
 
 - **Depends on**: `darepod` (embedded daemon runtime), `daemonrpc`
@@ -159,6 +193,8 @@ For field-level detail, use `go doc github.com/lightninglabs/darepo-client/sdk/w
   discriminated union — read the variant named by `Type`
   (`lightning`/`onchain`/`ark`) and treat the other fields as zero,
   the same idiom as `ListResult.View`.
+- `Entry.FailureCode` is the zero `EntryFailureCode` (empty string) for
+  non-failed entries. Only condition on it when `Entry.Status == "failed"`.
 - `Wait()` is single-reader: same shared channel on every call. The
   channel delivers the daemon's terminal run error then closes; a
   closed channel reads as the zero error indefinitely.
diff --git a/sdk/walletdk/mobile/AGENTS.md b/sdk/walletdk/mobile/AGENTS.md
new file mode 100644
index 000000000..bbf7b9f32
--- /dev/null
+++ b/sdk/walletdk/mobile/AGENTS.md
@@ -0,0 +1,94 @@
+# sdk/walletdk/mobile
+
+## Purpose
+
+Gomobile-safe facade over `sdk/walletdk` that provides a flat,
+host-language-compatible API. Wraps the wallet SDK in types that respect
+gomobile's type restrictions: no `context.Context`, no channels, no maps, no
+slices other than `[]byte`, and no unsigned integers at the language boundary.
+RPC verbs use a JSON bytes-in / bytes-out convention so host apps decode with
+kotlinx.serialization or Swift Codable without needing a protobuf runtime.
+`Start` is synchronous (must be called off the UI thread); the one streaming
+verb returns a pull-based `Subscription` handle instead of a callback because
+Go channels cannot cross the gomobile boundary.
+
+Only compiles with `-tags "mobile walletdkrpc swapruntime"`. `stub.go`
+provides an empty build so `go build ./...` succeeds without the tags.
+
+## Key Types
+
+- `Subscription` — pull-based streaming handle returned by `Subscribe`.
+  `Next() ([]byte, error)` blocks until the next entry JSON is available or
+  the stream ends (`io.EOF`). `Close() error` cancels the underlying stream.
+
+## Lifecycle
+
+The package manages a package-level singleton guarded by a mutex; at most one
+Start/Stop cycle can be active simultaneously.
+
+- `Start(cfgJSON string) error` — boots the embedded walletdk daemon;
+  blocks until gRPC is ready or start fails.
+- `Stop() error` — shuts down the daemon; idempotent.
+- `IsRunning() bool` — true while the daemon is up.
+
+## JSON RPC Verbs
+
+All verbs take a JSON request body (`[]byte`, nil treated as zero request) and
+return a JSON response body. Host apps marshal/unmarshal with their native JSON
+library.
+
+| Verb | Description |
+|------|-------------|
+| `GetInfo() ([]byte, error)` | Daemon readiness snapshot. |
+| `Balance() ([]byte, error)` | Flat balance summary. |
+| `Status() ([]byte, error)` | Wallet readiness, balance, pending-entry count. |
+| `CreateWallet([]byte) ([]byte, error)` | Create or import wallet. |
+| `UnlockWallet([]byte) ([]byte, error)` | Unlock existing wallet. |
+| `Deposit([]byte) ([]byte, error)` | Allocate boarding address. |
+| `Receive([]byte) ([]byte, error)` | Open Lightning receive. |
+| `PrepareSend([]byte) ([]byte, error)` | Quote outbound payment; returns single-use intent ID. |
+| `SendPrepared([]byte) ([]byte, error)` | Dispatch prepared send. |
+| `List([]byte) ([]byte, error)` | Unified history view. |
+| `Exit([]byte) ([]byte, error)` | Trigger cooperative or unilateral exit. |
+| `ExitStatus([]byte) ([]byte, error)` | Query exit job phase. |
+| `GetExitPlan([]byte) ([]byte, error)` | Preview unilateral-exit readiness. |
+| `SweepWallet([]byte) ([]byte, error)` | Preview or broadcast backing-wallet sweep. |
+| `Subscribe([]byte) (*Subscription, error)` | Stream wallet activity updates. |
+
+## Scalar Convenience Methods
+
+Hot UI paths that must avoid JSON decode overhead:
+
+- `ConfirmedBalanceSat() (int64, error)`
+- `PendingInboundSat() (int64, error)`
+- `WalletReady() (bool, error)`
+
+## Relationships
+
+- **Depends on**: `sdk/walletdk` (all wallet operations delegate to the
+  embedded `walletdk.Client`).
+- **Depended on by**: `cmd/walletdk-wasm` (WASM bridge), iOS/Android gomobile
+  targets, `cmd/walletdk-tui`.
+- **Sends**: nothing (all calls delegate to `walletdk.Client`).
+- **Receives** ← host application (gomobile or syscall/js): lifecycle and
+  verb calls.
+
+## Invariants
+
+- Singleton lifecycle: concurrent `Start` calls while the daemon is already
+  starting or running return an error; `Stop` during stopping is a no-op.
+- All RPC verbs call `activeClient()` and return an error if the daemon is
+  not running, so hosts never need to guard calls with `IsRunning`.
+- Verb implementations use `callCtx` so a `Stop` cancels in-flight calls
+  cleanly before tearing down the daemon.
+- The `gen` counter guards against a racing Stop/Start: a goroutine that
+  started under `gen N` detects the new `gen N+1` and exits rather than
+  touching the fresh client.
+
+## Deep Docs
+
+- [sdk/walletdk/CLAUDE.md](../CLAUDE.md) — The underlying Go SDK this
+  facade wraps.
+- [cmd/walletdk-wasm/CLAUDE.md](../../../cmd/walletdk-wasm/CLAUDE.md) —
+  WASM bridge that wraps this facade for browsers.
+- [ARCHITECTURE.md](../../../ARCHITECTURE.md) — System-wide package map.
diff --git a/sdk/walletdk/mobile/CLAUDE.md b/sdk/walletdk/mobile/CLAUDE.md
new file mode 100644
index 000000000..bbf7b9f32
--- /dev/null
+++ b/sdk/walletdk/mobile/CLAUDE.md
@@ -0,0 +1,94 @@
+# sdk/walletdk/mobile
+
+## Purpose
+
+Gomobile-safe facade over `sdk/walletdk` that provides a flat,
+host-language-compatible API. Wraps the wallet SDK in types that respect
+gomobile's type restrictions: no `context.Context`, no channels, no maps, no
+slices other than `[]byte`, and no unsigned integers at the language boundary.
+RPC verbs use a JSON bytes-in / bytes-out convention so host apps decode with
+kotlinx.serialization or Swift Codable without needing a protobuf runtime.
+`Start` is synchronous (must be called off the UI thread); the one streaming
+verb returns a pull-based `Subscription` handle instead of a callback because
+Go channels cannot cross the gomobile boundary.
+
+Only compiles with `-tags "mobile walletdkrpc swapruntime"`. `stub.go`
+provides an empty build so `go build ./...` succeeds without the tags.
+
+## Key Types
+
+- `Subscription` — pull-based streaming handle returned by `Subscribe`.
+  `Next() ([]byte, error)` blocks until the next entry JSON is available or
+  the stream ends (`io.EOF`). `Close() error` cancels the underlying stream.
+
+## Lifecycle
+
+The package manages a package-level singleton guarded by a mutex; at most one
+Start/Stop cycle can be active simultaneously.
+
+- `Start(cfgJSON string) error` — boots the embedded walletdk daemon;
+  blocks until gRPC is ready or start fails.
+- `Stop() error` — shuts down the daemon; idempotent.
+- `IsRunning() bool` — true while the daemon is up.
+
+## JSON RPC Verbs
+
+All verbs take a JSON request body (`[]byte`, nil treated as zero request) and
+return a JSON response body. Host apps marshal/unmarshal with their native JSON
+library.
+
+| Verb | Description |
+|------|-------------|
+| `GetInfo() ([]byte, error)` | Daemon readiness snapshot. |
+| `Balance() ([]byte, error)` | Flat balance summary. |
+| `Status() ([]byte, error)` | Wallet readiness, balance, pending-entry count. |
+| `CreateWallet([]byte) ([]byte, error)` | Create or import wallet. |
+| `UnlockWallet([]byte) ([]byte, error)` | Unlock existing wallet. |
+| `Deposit([]byte) ([]byte, error)` | Allocate boarding address. |
+| `Receive([]byte) ([]byte, error)` | Open Lightning receive. |
+| `PrepareSend([]byte) ([]byte, error)` | Quote outbound payment; returns single-use intent ID. |
+| `SendPrepared([]byte) ([]byte, error)` | Dispatch prepared send. |
+| `List([]byte) ([]byte, error)` | Unified history view. |
+| `Exit([]byte) ([]byte, error)` | Trigger cooperative or unilateral exit. |
+| `ExitStatus([]byte) ([]byte, error)` | Query exit job phase. |
+| `GetExitPlan([]byte) ([]byte, error)` | Preview unilateral-exit readiness. |
+| `SweepWallet([]byte) ([]byte, error)` | Preview or broadcast backing-wallet sweep. |
+| `Subscribe([]byte) (*Subscription, error)` | Stream wallet activity updates. |
+
+## Scalar Convenience Methods
+
+Hot UI paths that must avoid JSON decode overhead:
+
+- `ConfirmedBalanceSat() (int64, error)`
+- `PendingInboundSat() (int64, error)`
+- `WalletReady() (bool, error)`
+
+## Relationships
+
+- **Depends on**: `sdk/walletdk` (all wallet operations delegate to the
+  embedded `walletdk.Client`).
+- **Depended on by**: `cmd/walletdk-wasm` (WASM bridge), iOS/Android gomobile
+  targets, `cmd/walletdk-tui`.
+- **Sends**: nothing (all calls delegate to `walletdk.Client`).
+- **Receives** ← host application (gomobile or syscall/js): lifecycle and
+  verb calls.
+
+## Invariants
+
+- Singleton lifecycle: concurrent `Start` calls while the daemon is already
+  starting or running return an error; `Stop` during stopping is a no-op.
+- All RPC verbs call `activeClient()` and return an error if the daemon is
+  not running, so hosts never need to guard calls with `IsRunning`.
+- Verb implementations use `callCtx` so a `Stop` cancels in-flight calls
+  cleanly before tearing down the daemon.
+- The `gen` counter guards against a racing Stop/Start: a goroutine that
+  started under `gen N` detects the new `gen N+1` and exits rather than
+  touching the fresh client.
+
+## Deep Docs
+
+- [sdk/walletdk/CLAUDE.md](../CLAUDE.md) — The underlying Go SDK this
+  facade wraps.
+- [cmd/walletdk-wasm/CLAUDE.md](../../../cmd/walletdk-wasm/CLAUDE.md) —
+  WASM bridge that wraps this facade for browsers.
+- [ARCHITECTURE.md](../../../ARCHITECTURE.md) — System-wide package map.