docs: full re-audit of the agent doc graph and knowledge base

AGENTS.md

@@ -16,7 +16,7 @@ This file is a **map**, not a manual. Follow links for details.
 | `make fmt-changed-check` | Verify changed Go source files are formatted |
 | `make unit pkg=<pkg> case=<test>` | Run unit tests |
 | `make unit log="stdlog trace" pkg=<pkg> case=<test>` | Unit tests with debug logs |
-| `make itest icase=<test>` | Integration test |
+| `make systest` | System integration tests (use `db=postgres` for PostgreSQL) |
 | `make tidy-module-check` | Verify module files are tidy |
 | `make rpc` | Regenerate protobuf stubs |
 | `make sqlc` | Regenerate type-safe DB queries |
@@ -27,7 +27,7 @@ This file is a **map**, not a manual. Follow links for details.
 
 ## Code Style (Summary)
 
-- **8-space tabs** (see `.editorconfig`), 80-char line limit (best effort).
+- **8-space tabs**, 80-char line limit (best effort).
 - Every function/method gets a comment starting with its name.
 - Exported identifiers need GoDoc comments wrapped to 80 columns.
 - Organize code into logical stanzas with explanatory comments between them.
@@ -54,7 +54,7 @@ Body wrapped at 72 characters. Explain WHY, not just WHAT.
 ## Critical Rules
 
 1. **Never edit generated code** — regenerate via `make rpc` or `make sqlc`.
-2. **Never write raw SQL in Go** — add queries to `db/queries/`, use sqlc.
+2. **Never write raw SQL in Go** — add queries to `db/sqlc/queries/`, use sqlc.
 3. **Run `make fmt-changed` before every commit.**
    This applies `goimports` and `llformat` to changed handwritten Go files.
    Use `make fmt` instead when you intentionally need a full-tree format pass.
@@ -130,7 +130,7 @@ and navigate into the package relevant to your task.
 ## Code Generation Workflow
 
 1. **Protobuf**: edit `.proto` → `make rpc` → commit generated code separately.
-2. **Database**: edit `db/schema/` or `db/queries/` → `make sqlc` → commit separately.
+2. **Database**: edit `db/sqlc/migrations/` or `db/sqlc/queries/` → `make sqlc` → commit separately.
 3. **Never edit generated code manually.**
 
 ## Dependencies

ARCHITECTURE.md

@@ -28,6 +28,8 @@ 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) |
+| [`credit`](credit/) | Client-side credit subsystem: supervisor/per-operation-actor pair driving fault-tolerant sub-dust pay, credit-receive, and redeem flows against the authoritative server ledger |
+| [`coinselect`](coinselect/) | Single coin-type-agnostic coin-selection algorithm shared across wallet backends |
 
 ### Layer 2: Infrastructure (Chain, Storage, Messaging)
 
@@ -36,6 +38,8 @@ package may import from a higher layer.
 | [`baselib`](baselib/) | Actor framework (`baselib/actor`) and protofsm state machine engine (`baselib/protofsm`) |
 | [`chainsource`](chainsource/) | `ChainBackend` interface: fee estimation, block/conf/spend notifications |
 | [`chainbackends`](chainbackends/) | LND-backed `ChainBackend` implementation plus lndclient adapters (`TxBroadcaster`, `PackageSubmitter`) |
+| [`chainbackends/lndsubmitter`](chainbackends/lndsubmitter/) | `chainbackends.PackageSubmitter` over lnd's WalletKit; the default LND package-relay submitter |
+| [`chainfees`](chainfees/) | Reusable `chainfee.Estimator` implementations and combinators for pricing transactions |
 | [`chain`](chain/) | Bitcoind RPC utilities (package relay, `SubmitPackage`) |
 | [`txconfirm`](txconfirm/) | Generic "broadcast + CPFP fee-bump + notify on confirm" actor with per-parent fee-input reservations and BIP-125 Rule 3/4 enforcement |
 | [`unroll`](unroll/) | Durable per-target unilateral-exit actor + thin registry: owns proof assembly, materialization, CSV maturity, final sweep build, persist-before-broadcast, and control-plane record persistence |
@@ -51,6 +55,8 @@ package may import from a higher layer.
 | [`mailbox`](mailbox/) | Mailbox protocol primitives across three sub-packages (pb, rpc, conn) |
 | [`serverconn`](serverconn/) | Unified server connector: durable egress, ingress polling, unary RPC facade |
 | [`serverconn/mailboxpull`](serverconn/mailboxpull/) | Shared exponential-backoff retry primitives for mailbox pull loops (used by serverconn ingress and SDK swap consumers) |
+| [`rpcauth`](rpcauth/) | Shared macaroon and TLS helpers securing gRPC/REST connections |
+| [`internal/sqlbase`](internal/sqlbase/) | `walletdb`-compatible key/value backend over `database/sql` (js/wasm walletdb storage for `lwwallet` browser builds) |
 
 ### Layer 3: Application & Orchestration
 
@@ -61,10 +67,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 facade over `sdk/walletdk` for Android/iOS host apps: drives an embedded in-process wallet over the private bufconn transport |
 | [`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/) | Command compiling the embedded walletdk runtime to a browser WASM binary |
 | [`timeout`](timeout/) | Generic timeout scheduling actor |
 | [`indexer`](indexer/) | Server indexing client for receive script registration |
 | [`arkrpc`](arkrpc/) | Server-side gRPC service definitions (ArkService, IndexerService) |
@@ -73,6 +81,7 @@ package may import from a higher layer.
 | [`rpc/walletdkrpc`](rpc/walletdkrpc/) | Highest-level gRPC surface: `WalletService` with the seven core wallet verbs. Composes `daemonrpc` and `rpc/swapclientrpc` server-side via `swapwallet` |
 | [`rpc/restclient`](rpc/restclient/) | HTTP/protoJSON transport adapter: `Client`, `StreamClient[T]`, and per-service factory functions implementing the same gRPC stub interfaces over REST |
 | [`daemonrpc`](daemonrpc/) | Daemon gRPC API definitions |
+| [`swaprpc`](swaprpc/) | Generated gRPC/REST/mailbox-RPC stubs for the external `SwapService` |
 
 ### Layer 4: Testing & Tooling
 

CLAUDE.md

@@ -16,7 +16,7 @@ This file is a **map**, not a manual. Follow links for details.
 | `make fmt-changed-check` | Verify changed Go source files are formatted |
 | `make unit pkg=<pkg> case=<test>` | Run unit tests |
 | `make unit log="stdlog trace" pkg=<pkg> case=<test>` | Unit tests with debug logs |
-| `make itest icase=<test>` | Integration test |
+| `make systest` | System integration tests (use `db=postgres` for PostgreSQL) |
 | `make tidy-module-check` | Verify module files are tidy |
 | `make rpc` | Regenerate protobuf stubs |
 | `make sqlc` | Regenerate type-safe DB queries |
@@ -27,7 +27,7 @@ This file is a **map**, not a manual. Follow links for details.
 
 ## Code Style (Summary)
 
-- **8-space tabs** (see `.editorconfig`), 80-char line limit (best effort).
+- **8-space tabs**, 80-char line limit (best effort).
 - Every function/method gets a comment starting with its name.
 - Exported identifiers need GoDoc comments wrapped to 80 columns.
 - Organize code into logical stanzas with explanatory comments between them.
@@ -54,7 +54,7 @@ Body wrapped at 72 characters. Explain WHY, not just WHAT.
 ## Critical Rules
 
 1. **Never edit generated code** — regenerate via `make rpc` or `make sqlc`.
-2. **Never write raw SQL in Go** — add queries to `db/queries/`, use sqlc.
+2. **Never write raw SQL in Go** — add queries to `db/sqlc/queries/`, use sqlc.
 3. **Run `make fmt-changed` before every commit.**
    This applies `goimports` and `llformat` to changed handwritten Go files.
    Use `make fmt` instead when you intentionally need a full-tree format pass.
@@ -130,7 +130,7 @@ and navigate into the package relevant to your task.
 ## Code Generation Workflow
 
 1. **Protobuf**: edit `.proto` → `make rpc` → commit generated code separately.
-2. **Database**: edit `db/schema/` or `db/queries/` → `make sqlc` → commit separately.
+2. **Database**: edit `db/sqlc/migrations/` or `db/sqlc/queries/` → `make sqlc` → commit separately.
 3. **Never edit generated code manually.**
 
 ## Dependencies

baselib/AGENTS.md

@@ -22,9 +22,16 @@ build on.
 - `StateTransition[InternalEvent, OutboxEvent, Env]` — Next state + emitted events from a transition.
 - `EmittedEvent[InternalEvent, OutboxEvent]` — Internal events (recursive) + outbox events (external).
 
+### baselib/example
+- Runnable reference wiring a `protofsm` state machine to `actor` services;
+  not used by production code. See `baselib/example/CLAUDE.md`.
+
 ## Relationships
 
-- **Depends on**: nothing (pure abstraction layer).
+- **Depends on**: `lnd/tlv`, `lnd/fn/v2`, `lnd/clock` (external, no
+  darepo-client-specific logic); `darepo-client/build` (context-scoped logger
+  helper only) is the one root-module import, otherwise this is a pure
+  abstraction layer.
 - **Depended on by**: every domain package (`round`, `vtxo`, `oor`, `wallet`), `chainsource`, `serverconn`, `db`, `darepod`.
 
 ## Invariants

baselib/CLAUDE.md

@@ -22,9 +22,16 @@ build on.
 - `StateTransition[InternalEvent, OutboxEvent, Env]` — Next state + emitted events from a transition.
 - `EmittedEvent[InternalEvent, OutboxEvent]` — Internal events (recursive) + outbox events (external).
 
+### baselib/example
+- Runnable reference wiring a `protofsm` state machine to `actor` services;
+  not used by production code. See `baselib/example/CLAUDE.md`.
+
 ## Relationships
 
-- **Depends on**: nothing (pure abstraction layer).
+- **Depends on**: `lnd/tlv`, `lnd/fn/v2`, `lnd/clock` (external, no
+  darepo-client-specific logic); `darepo-client/build` (context-scoped logger
+  helper only) is the one root-module import, otherwise this is a pure
+  abstraction layer.
 - **Depended on by**: every domain package (`round`, `vtxo`, `oor`, `wallet`), `chainsource`, `serverconn`, `db`, `darepod`.
 
 ## Invariants

baselib/actor/AGENTS.md

@@ -75,8 +75,8 @@ crash-safe at-least-once delivery with exactly-once deduplication.
 
 ## Relationships
 
-- **Depends on**: `lnd/tlv` (message serialization).
-- **Depended on by**: All domain actors (`round`, `vtxo`, `oor`, `wallet`, `serverconn`, `timeout`, `indexer`), `baselib/protofsm` (FSM-to-actor bridge), `db/actordelivery` (persistence implementation).
+- **Depends on**: `lnd/tlv` (message serialization), `lnd/fn/v2` (Result/Option/Either types), `lnd/clock` (testable time), `build` (logger-from-context helper).
+- **Depended on by**: All domain actors (`round`, `vtxo`, `oor`, `wallet`, `serverconn`, `timeout`), `baselib/protofsm` (FSM-to-actor bridge), `db/actordelivery` (persistence implementation).
 
 ## Invariants
 

baselib/actor/CLAUDE.md

@@ -75,8 +75,8 @@ crash-safe at-least-once delivery with exactly-once deduplication.
 
 ## Relationships
 
-- **Depends on**: `lnd/tlv` (message serialization).
-- **Depended on by**: All domain actors (`round`, `vtxo`, `oor`, `wallet`, `serverconn`, `timeout`, `indexer`), `baselib/protofsm` (FSM-to-actor bridge), `db/actordelivery` (persistence implementation).
+- **Depends on**: `lnd/tlv` (message serialization), `lnd/fn/v2` (Result/Option/Either types), `lnd/clock` (testable time), `build` (logger-from-context helper).
+- **Depended on by**: All domain actors (`round`, `vtxo`, `oor`, `wallet`, `serverconn`, `timeout`), `baselib/protofsm` (FSM-to-actor bridge), `db/actordelivery` (persistence implementation).
 
 ## Invariants
 

baselib/example/AGENTS.md

@@ -18,9 +18,9 @@ reference and learning aid; not used by production code.
   `StateApproved`, `StateRejected`.
 - `DocEnvironment` — Immutable FSM context holding an actor reference;
   implements `protofsm.TellRefEnv[DocEvent]`.
-- `ReviewService` / `ReviewServiceBehavior` — Actor that performs async review
-  and sends the result event back to the FSM.
-- `NotificationService` / `NotificationServiceBehavior` — Actor that delivers
+- `ReviewServiceBehavior` — `ActorBehavior` that performs async document
+  review and sends the result event back to the FSM.
+- `NotificationServiceBehavior` — `ActorBehavior` that delivers
   approval/rejection notifications.
 
 ## Relationships

baselib/example/CLAUDE.md

@@ -18,9 +18,9 @@ reference and learning aid; not used by production code.
   `StateApproved`, `StateRejected`.
 - `DocEnvironment` — Immutable FSM context holding an actor reference;
   implements `protofsm.TellRefEnv[DocEvent]`.
-- `ReviewService` / `ReviewServiceBehavior` — Actor that performs async review
-  and sends the result event back to the FSM.
-- `NotificationService` / `NotificationServiceBehavior` — Actor that delivers
+- `ReviewServiceBehavior` — `ActorBehavior` that performs async document
+  review and sends the result event back to the FSM.
+- `NotificationServiceBehavior` — `ActorBehavior` that delivers
   approval/rejection notifications.
 
 ## Relationships

baselib/protofsm/AGENTS.md

@@ -4,17 +4,21 @@
 
 Protocol-style finite state machine engine that separates pure state transitions
 from side effects. Business logic lives in `(State, Event) → (State, []OutboxEvent)`
-transition functions; the runtime dispatches outbox messages after state is
-durably persisted.
+transition functions; the runtime commits the new state, then dispatches the
+transition's outbox events.
 
 ## Key Types
 
-- `State[E, O, Env]` — Interface for FSM states: `ProcessEvent` returns the next state and outbox events.
+- `State[E, O, Env]` — Interface for FSM states: `ProcessEvent` returns a
+  `StateTransition`, iterated until a terminal state or no further internal
+  events are emitted.
 - `StateMachine[E, O, Env]` — Non-actor FSM runner (for testing or embedded use).
 - `StateMachineCfg[E, O, Env]` — Configuration for state machines (initial state, environment, transition table).
 - `ActorStateMachine[E, O, Env]` — FSM wrapped as an actor behavior for use with `baselib/actor`.
-- `EmittedEvent[E, O]` — Pair of (next state, outbox events) returned by transitions.
-- `StateTransition[E, O, Env]` — Single transition result (new state + emitted events).
+- `EmittedEvent[E, O]` — Internal events (recursive, routed back into the
+  FSM) plus outbox events (dispatched externally), emitted by a transition.
+- `StateTransition[E, O, Env]` — Single transition result: next state plus an
+  optional `EmittedEvent`.
 - `TransitionTable[S, E, M]` — Declarative transition table mapping (State, Event) → handler.
 - `TransitionEntry[S, E, M]` — Single entry in a transition table.
 - `RoutedOutboxEvent[M, R]` — Outbox event that targets a specific actor via `ServiceKey` (Tell or Ask delivery).
@@ -31,12 +35,18 @@ durably persisted.
 ## Invariants
 
 - Transition functions must be pure: no I/O, no network calls, no database writes. All side effects are expressed as outbox events.
-- Outbox events are dispatched only after the new state is durably persisted (prevents message-before-state bugs).
-- `TransitionTable` enforces exhaustive (State, Event) coverage at compile time via type constraints.
+- `ActorStateMachine.Receive` commits `currentState` in memory before
+  dispatching any outbox events for that turn (prevents dispatching a side
+  effect for a transition the FSM hasn't "moved into" yet). Protofsm itself
+  has no persistence layer; durability, if any, comes from the surrounding
+  `DurableActor`/`baselib/actor` wiring, not from this package.
+- `TransitionTable` is a declarative, introspectable description of valid
+  (State, Event) transitions used for documentation/rendering
+  (`RenderMarkdown`) and test validation; it is not compiler-enforced and
+  does not by itself guarantee exhaustive coverage.
 - `RoutedOutboxEvent` captures the target `ServiceKey` so the runtime can dispatch to the correct actor without the FSM knowing about actor references.
 
 ## Deep Docs
 
 - [baselib/CLAUDE.md](../CLAUDE.md) — Parent baselib package overview.
-- [docs/durable_actor_architecture.md](../../docs/durable_actor_architecture.md) — Durable actor internals.
 - [ARCHITECTURE.md](../../ARCHITECTURE.md) — System-wide package map.

baselib/protofsm/CLAUDE.md

@@ -4,17 +4,21 @@
 
 Protocol-style finite state machine engine that separates pure state transitions
 from side effects. Business logic lives in `(State, Event) → (State, []OutboxEvent)`
-transition functions; the runtime dispatches outbox messages after state is
-durably persisted.
+transition functions; the runtime commits the new state, then dispatches the
+transition's outbox events.
 
 ## Key Types
 
-- `State[E, O, Env]` — Interface for FSM states: `ProcessEvent` returns the next state and outbox events.
+- `State[E, O, Env]` — Interface for FSM states: `ProcessEvent` returns a
+  `StateTransition`, iterated until a terminal state or no further internal
+  events are emitted.
 - `StateMachine[E, O, Env]` — Non-actor FSM runner (for testing or embedded use).
 - `StateMachineCfg[E, O, Env]` — Configuration for state machines (initial state, environment, transition table).
 - `ActorStateMachine[E, O, Env]` — FSM wrapped as an actor behavior for use with `baselib/actor`.
-- `EmittedEvent[E, O]` — Pair of (next state, outbox events) returned by transitions.
-- `StateTransition[E, O, Env]` — Single transition result (new state + emitted events).
+- `EmittedEvent[E, O]` — Internal events (recursive, routed back into the
+  FSM) plus outbox events (dispatched externally), emitted by a transition.
+- `StateTransition[E, O, Env]` — Single transition result: next state plus an
+  optional `EmittedEvent`.
 - `TransitionTable[S, E, M]` — Declarative transition table mapping (State, Event) → handler.
 - `TransitionEntry[S, E, M]` — Single entry in a transition table.
 - `RoutedOutboxEvent[M, R]` — Outbox event that targets a specific actor via `ServiceKey` (Tell or Ask delivery).
@@ -31,12 +35,18 @@ durably persisted.
 ## Invariants
 
 - Transition functions must be pure: no I/O, no network calls, no database writes. All side effects are expressed as outbox events.
-- Outbox events are dispatched only after the new state is durably persisted (prevents message-before-state bugs).
-- `TransitionTable` enforces exhaustive (State, Event) coverage at compile time via type constraints.
+- `ActorStateMachine.Receive` commits `currentState` in memory before
+  dispatching any outbox events for that turn (prevents dispatching a side
+  effect for a transition the FSM hasn't "moved into" yet). Protofsm itself
+  has no persistence layer; durability, if any, comes from the surrounding
+  `DurableActor`/`baselib/actor` wiring, not from this package.
+- `TransitionTable` is a declarative, introspectable description of valid
+  (State, Event) transitions used for documentation/rendering
+  (`RenderMarkdown`) and test validation; it is not compiler-enforced and
+  does not by itself guarantee exhaustive coverage.
 - `RoutedOutboxEvent` captures the target `ServiceKey` so the runtime can dispatch to the correct actor without the FSM knowing about actor references.
 
 ## Deep Docs
 
 - [baselib/CLAUDE.md](../CLAUDE.md) — Parent baselib package overview.
-- [docs/durable_actor_architecture.md](../../docs/durable_actor_architecture.md) — Durable actor internals.
 - [ARCHITECTURE.md](../../ARCHITECTURE.md) — System-wide package map.