diff --git a/apps/web/docs/concepts-app-routing.md b/apps/web/docs/concepts-app-routing.md
new file mode 100644
index 0000000..bb753d2
--- /dev/null
+++ b/apps/web/docs/concepts-app-routing.md
@@ -0,0 +1,167 @@
+# App Routing & Conversation UI Architecture
+
+Source: [`src/app/`](../src/app/), in particular
+[`layout.tsx`](../src/app/layout.tsx), [`page.tsx`](../src/app/page.tsx),
+[`app/layout.tsx`](../src/app/app/layout.tsx) and
+[`app/conversations/[id]/page.tsx`](../src/app/app/conversations/%5Bid%5D/page.tsx).
+
+This describes the routing structure after the route-consolidation work (commit `f6a40ef`,
+"retire duplicate conversation route and legacy chat demo"): there is now a single conversation
+route, `/app/conversations/[id]`. For auth state see
+[`concepts-auth-device-lifecycle.md`](concepts-auth-device-lifecycle.md); for the message
+pipeline behind the conversation view see
+[`concepts-message-pipeline.md`](concepts-message-pipeline.md) and
+[`concepts-e2ee-architecture.md`](concepts-e2ee-architecture.md).
+
+## Next.js App Router in one paragraph
+
+The web app uses the App Router (`src/app/`). Each folder containing a `page.tsx` is a URL
+segment; a `layout.tsx` wraps every page beneath it and persists across navigation between those
+pages; a folder named `[id]` is a dynamic segment read with `useParams()`. Nearly every page here
+is a client component (`'use client'`) because it depends on wallet, auth token or socket state.
+
+## Route tree
+
+```
+src/app/
+├── layout.tsx                  Root layout (all routes)
+├── page.tsx                    /                          Landing page
+├── globals.css, favicon.ico
+├── providers.tsx               (not mounted — see "Leftovers")
+├── routes/conversations.js     (not a route — see "Leftovers")
+└── app/                        /app/*  Authenticated shell
+    ├── layout.tsx              Sidebar, wallet button, push prompt
+    ├── page.tsx                /app                       Demo messages view
+    ├── messages/page.tsx       /app/messages              Re-exports /app page
+    ├── conversations/[id]/page.tsx  /app/conversations/:id  Real conversation view
+    ├── devices/page.tsx        /app/devices
+    ├── profile/page.tsx        /app/profile
+    ├── proposals/page.tsx      /app/proposals
+    ├── search/page.tsx         /app/search
+    └── treasury/page.tsx       /app/treasury
+```
+
+### Root layout and landing page
+
+- [`app/layout.tsx`](../src/app/layout.tsx) sets metadata and fonts and nests the global
+  providers, outermost first: `WalletContext` → `AuthProvider` → `ToastProvider`. Every route,
+  including `/app/*`, can therefore call `useWallet()`, `useAuth()` and the toast API.
+- [`app/page.tsx`](../src/app/page.tsx) (`/`) is the marketing page, wrapped in
+  `<ProtectedRoute mode="unauthenticated">`: a visitor who already has a token is redirected to
+  `/app`.
+
+### The `/app` shell
+
+[`app/app/layout.tsx`](../src/app/app/layout.tsx) is the shell shared by every route below. It
+renders a fixed left sidebar (nav links for Messages, Treasury, Proposals and Devices, plus a
+Connect/Disconnect wallet button using `useWallet()`) and puts the active page in `<main>`. It
+also mounts `PushPermissionPrompt` and listens for `sw:sync` messages from the service worker
+(see [`concepts-service-worker.md`](concepts-service-worker.md)): a notification click navigates
+to `/app/conversations/:id`, or to `/app/messages` if no conversation id was sent.
+
+The shell does **not** wrap its children in `ProtectedRoute mode="authenticated"`. Pages that
+need a token handle a missing one themselves (for instance the conversation page shows "Sign in
+to view this conversation.").
+
+### Top-level routes under `app/app/`
+
+| Route | Purpose |
+|---|---|
+| `/app` | Default landing inside the shell; currently a **demo** chat view with hard-coded messages and a local search panel, not wired to the backend. The sidebar highlights "Messages" for this path. |
+| `/app/messages` | Alias of `/app` (`export { default } from '../page'`), and the sidebar's "Messages" target. |
+| `/app/conversations/[id]` | The real, end-to-end encrypted conversation view for one direct or group conversation. Detailed below. |
+| `/app/devices` | Lists the signed-in user's registered devices and lets them be managed/revoked, via `apiFetch` and modals. |
+| `/app/profile` | Shows and edits the signed-in user's profile and linked wallets, via `apiFetch`. |
+| `/app/proposals` | Community funding proposals list with voting UI; currently driven by local sample state. |
+| `/app/search` | Full-page local message search (`MessageSearch` over the on-device index) with an indexed-message count. |
+| `/app/treasury` | Group treasury view: fetches withdraw proposals, shows `ProposalCard`s, and opens `ProposeWithdrawalModal`; updates live through `useSocket`. See [`components-treasury-wallet.md`](components-treasury-wallet.md). |
+
+`/app/profile` is routed but has no sidebar entry; it is reached by direct link.
+
+## Conversation view (`/app/conversations/[id]`)
+
+`ConversationPage` is a single client component (~900 lines) that owns data loading, send
+handlers, and rendering. It does **not** delegate to the components in `components/messaging/`
+(`MessageThread`, `InboundMessageRow`) or `components/chat/` (`ConversationHeader`,
+`NewConversationModal`), nor to `ConversationListSidebar`; none of those is imported by any
+route. Orient yourself in the page file by these parts.
+
+### Hooks and libraries it pulls together
+
+| Concern | What it uses |
+|---|---|
+| Route param | `useParams<{ id }>()` gives the conversation id. |
+| Auth | `useAuth()` supplies `token` and `loading`; no token → error state. |
+| Realtime | `useSocket(token)`; on mount emits `join_room` via `emitSocketEnvelope`. |
+| Incoming messages | `useInboundPipeline({ socket, token, conversationId })` receives, decrypts and orders envelopes, returning `messages` with `decrypted` / `unavailable` status. |
+| Sending text | `sendEncryptedMessage` from `lib/crypto`, then `socket.emit('send_message')`. |
+| Sending files | `fetchConversationDevices`, `generateEncryptedThumbnail`, `sendEncryptedFile`, then `socket.emit('send_file_message')`; download via `downloadAndDecryptFile`. |
+| Key-change reset | `clearSessionKeys()` and `sessionStore.clear()` when a key-change socket event arrives. |
+| Presentation | `Avatar`, `EmptyState`, `TransferCard`, `EncryptedThumbnail`, `UnavailableMessagePlaceholder`. |
+
+### Data flow
+
+1. **Initial load.** An effect (waits for auth) fetches in parallel `GET /users/me`,
+   `GET /conversations/:id` and `GET /conversations/:id/messages` into `currentUser`,
+   `conversation` and `messages`.
+2. **Merge.** The `allMessages` memo overlays pipeline results on the REST history by message
+   id: a decrypted inbound entry supplies `content` (and a parsed `filePayload` for
+   `file`/`image`/`video` types), an `unavailable` one marks the row undecryptable, and inbound
+   messages not yet in REST history are appended. The result is sorted by `createdAt`.
+3. **Derive.** `contacts` (members other than the current user), `title` and
+   `hasChangedSafetyNumber` are computed from state.
+
+### Layout and the message list
+
+The component renders a flex row of two panes:
+
+- **Main column (`<section>`)**: a header (avatar, title, member count or primary wallet, and the
+  safety-numbers toggle button), an optional amber "Safety number changed" banner, the scrolling
+  **message list**, and the **input bar**.
+- **Safety panel (`<aside>`)**, shown only while `isSafetyOpen`.
+
+The message list maps `allMessages` and picks one body per message, in this order:
+`TransferCard` (token-transfer payload) → `UnavailableMessagePlaceholder` → image/video
+`EncryptedThumbnail` + download link → file download button → plain text bubble. System
+messages (e.g. membership/key events) render as labelled text. A `bottomRef` element is scrolled
+into view whenever the message count changes. An empty list shows `EmptyState`.
+
+### Input bar
+
+A hidden `<input type="file">` triggered by the paperclip button (`handleSendFile`, runs on file
+selection), a text input where Enter (without Shift) calls `handleSendEncrypted`, and a Send
+button. Both controls are disabled while `sending` is true. Failures are only logged with
+`console.error`; no toast is shown.
+
+### Safety-number UI
+
+- **Loading.** For each contact, `loadSafetyNumber(userId)` calls
+  `GET /users/:id/key-fingerprint` and stores `{ fingerprint, formatted }` in `safetyByUser`.
+- **Verification record.** "Mark verified" (`verifyContact`) saves `{ fingerprint, verifiedAt }`
+  to `localStorage` under `clicked.safetyVerification.<userId>`. This is per browser, not
+  synced.
+- **Change detection.** On load, a stored fingerprint that differs from the server's sets
+  `changed = true`, clears `verifiedAt` and opens the panel. The same happens live when the
+  socket emits `key_set_changed`, `key_changed`, `contact_key_changed`, `safety_number_changed`
+  or `system_event` for a contact in this conversation (via `isRelevantKeyChangeEvent`); that
+  handler also wipes cached session keys so the next send renegotiates.
+- **Display.** The header button turns amber and relabels itself when any contact has changed;
+  the panel lists each contact with the formatted number, a Verified/Mark verified button, and
+  loading/error states.
+
+## Leftovers
+
+Two files under `src/app/` are not part of the route tree: [`providers.tsx`](../src/app/providers.tsx)
+(an unused `AuthProvider` wrapper importing `../lib/auth`) and
+[`routes/conversations.js`](../src/app/routes/conversations.js) (an Express router that looks
+like a misplaced backend file; `routes/` has no `page.tsx`, so it serves nothing). Neither
+affects routing, and new code should not build on them.
+
+## Adding a route
+
+1. Create `src/app/app/<name>/page.tsx` with `'use client'` if it needs wallet, auth or socket.
+2. Add an entry to `navItems` in [`app/app/layout.tsx`](../src/app/app/layout.tsx) if it should
+   appear in the sidebar. The active-state check is an exact `pathname === href` match, so nested
+   paths do not highlight their parent.
+3. Handle the signed-out case in the page (or wrap it in `ProtectedRoute mode="authenticated"`),
+   since the shell does not guard children.
diff --git a/contracts/docs/concepts-cross-contract-interfaces.md b/contracts/docs/concepts-cross-contract-interfaces.md
new file mode 100644
index 0000000..445104c
--- /dev/null
+++ b/contracts/docs/concepts-cross-contract-interfaces.md
@@ -0,0 +1,184 @@
+# Cross-Contract Interfaces & the Two Withdrawal Paths
+
+Source:
+[`group_treasury/src/token_interface.rs`](../contracts/group_treasury/src/token_interface.rs),
+[`token_transfer/src/token_interface.rs`](../contracts/token_transfer/src/token_interface.rs),
+[`proposals/src/treasury_interface.rs`](../contracts/proposals/src/treasury_interface.rs),
+[`proposals/src/treasury_interface_client.rs`](../contracts/proposals/src/treasury_interface_client.rs),
+plus the callers in each contract's `lib.rs`.
+
+The three contracts call each other through small typed clients rather than by importing each
+other's crates. This page explains those clients, then resolves a source of confusion: there are
+**two independent ways to move treasury funds**, and neither triggers the other.
+
+Related: [`contracts-proposals-storage.md`](contracts-proposals-storage.md) (storage and the
+client call sequence in detail), [`concepts-treasury-multisig-model.md`](concepts-treasury-multisig-model.md),
+[`concepts-proposal-lifecycle.md`](concepts-proposal-lifecycle.md),
+[`concepts-token-transfer-flow.md`](concepts-token-transfer-flow.md).
+
+## The mechanism: `#[contractclient]`
+
+Soroban contracts call one another by contract address, function name and arguments. To avoid
+writing raw `invoke_contract` calls, each caller declares a trait describing only the callee
+functions it needs and annotates it with `#[contractclient(name = "...")]`. The SDK macro
+generates a client struct with one method per trait function:
+
+```rust
+let client = TokenClient::new(&env, &token_address);   // no I/O, no validation
+client.transfer(&from, &to, &amount);                   // invokes "transfer" on that contract
+```
+
+Properties common to all of the interfaces below:
+
+- **The trait is never implemented.** It exists only to generate the client.
+- **The address is data, not code.** It comes from storage or arguments. Nothing verifies at
+  compile time or at `new()` that the address is the contract you expect.
+- **Interfaces are hand-maintained subsets.** They are not derived from the real contract. If
+  the callee renames or re-types a function, the caller still compiles and fails at runtime.
+- **Calls are synchronous and atomic.** A panic in the callee aborts the whole transaction;
+  state changes made earlier in the caller revert too.
+- **Return values are typed by the trait.** The client converts the result into the declared
+  Rust type.
+
+## Interface inventory
+
+| Interface file | Client | Used by | Calls into | Functions declared |
+|---|---|---|---|---|
+| `group_treasury/src/token_interface.rs` | `TokenClient` | `group_treasury::deposit`, `withdraw` | An external SEP-41 token contract (address passed per call) | `transfer(from, to, amount)`, `balance(id) -> i128` |
+| `token_transfer/src/token_interface.rs` | `TokenClient` | `token_transfer::transfer`, `balance` | The SEP-41 token whose address is stored as `DataKey::TokenContract` | same two functions |
+| `proposals/src/treasury_interface.rs` | `TreasuryClient` | `proposals::execute_withdraw` | A `group_treasury` contract (address from `Proposal.treasury`) | `is_member(member) -> bool`, `balance(token) -> i128`, `withdraw(to, token, amount)` |
+| `proposals/src/treasury_interface_client.rs` | — | nothing | — | empty placeholder, see below |
+
+### The two `token_interface.rs` files
+
+They are byte-for-byte the same "minimal SEP-41" subset: `transfer` and `balance`. Each crate
+gets its own generated `TokenClient`, which is why the file is duplicated rather than shared.
+Note the difference in *where the token address comes from*:
+
+- `group_treasury` is multi-token. The token address is an argument to `deposit`, `withdraw` and
+  the balance accessors, and the treasury tracks per-token balances itself in
+  `DataKey::Balances`.
+- `token_transfer` is single-token. The address is fixed at `initialize` and changeable by
+  `set_token_contract`, stored in instance storage. It keeps no balances of its own;
+  `balance` reads straight from the token.
+
+In both, the token's `transfer(from, ...)` enforces `from`'s authorization. For `deposit` and
+`token_transfer::transfer` that is the user, who has signed. For the treasury's `withdraw`, `from`
+is the treasury contract itself (`env.current_contract_address()`), which the host authorizes
+automatically as the direct caller.
+
+### `treasury_interface.rs` and the empty `treasury_interface_client.rs`
+
+`treasury_interface.rs` is the real definition: it declares `TreasuryInterface` and generates
+`TreasuryClient`. `lib.rs` includes it with `mod treasury_interface;` and calls it as
+`crate::treasury_interface::TreasuryClient::new(&env, &proposal.treasury)`.
+
+`treasury_interface_client.rs` contains only the comment
+`// Intentionally left empty - this file was generated automatically.` It is not declared as a
+module, is not compiled, and nothing depends on it. Despite its name and the comment, the client
+is **not** hand-written in that file; it exists only as macro output of `treasury_interface.rs`.
+The file can be deleted without any effect. The caution is real, though: because the interface is
+a hand-maintained subset, `proposals` and `group_treasury` can drift without a compile error.
+
+## Two ways to move treasury funds
+
+`group_treasury` holds the funds. There are three distinct entry points in play, which form two
+mechanisms for deciding that a withdrawal should happen.
+
+### Path A — the treasury's own multisig (`propose_withdraw` / `approve_withdraw` / `reject_withdraw`)
+
+1. A **member** calls `propose_withdraw(proposer, to, token, amount, ttl_ledgers)`. The treasury
+   checks membership, `amount > 0` and sufficient balance, stores a `WithdrawProposal`, and counts
+   the proposer as the first approval.
+2. Members call `approve_withdraw` or `reject_withdraw` (one vote each).
+3. When `approvals >= threshold`, status becomes `Passed`. When `rejections` reaches the
+   blocking minority (`members - threshold + 1`), status becomes `Rejected`.
+
+**This path does not move funds.** There is no function that reads a `Passed` `WithdrawProposal`
+and transfers tokens. `Executed` exists in the treasury's `ProposalStatus` but nothing sets it,
+and `Expired` is likewise never assigned. A `Passed` proposal is currently a recorded decision only,
+which an off-chain actor or the admin can act on. Votes and decisions are on-chain
+and verifiable; actually releasing the money still requires `withdraw` (Path C).
+
+### Path B — the `proposals` contract (`execute_withdraw`)
+
+1. **Anyone** calls `proposals::create_proposal(... treasury, token, to, amount)`. This records
+   the intended withdrawal in the `proposals` contract's own storage. It is not registered with the
+   treasury, and the treasury has no knowledge of it.
+2. Authorized addresses vote in `proposals` (no membership check) until `expires_at`.
+3. `finalize_proposal` marks it `Passed` if `yes_votes > no_votes`.
+4. A caller who is a **treasury member** calls `proposals::execute_withdraw(caller, proposal_id)`.
+   `proposals` uses `TreasuryClient` to check `is_member(caller)` and `balance(token)`, then
+   calls `treasury.withdraw(to, token, amount)` and marks its own proposal `Executed`.
+
+### Path C — what Path B actually calls: the admin-gated `withdraw`
+
+`group_treasury::withdraw(to, token, amount)` is the only function that transfers funds out. It is
+**admin-gated**: it calls `require_admin`, which runs `admin.require_auth()` on the address stored
+at `DataKey::Admin`. It checks `amount > 0` and the recorded balance, calls the token's
+`transfer`, decrements `Balances`, and emits `withdraw`.
+
+Because `proposals` invokes it as a nested call, the **treasury admin's authorization must
+accompany the transaction** (a signed auth entry for that sub-invocation, or an admin that is a
+contract able to authorize it). `proposals` being the caller is not sufficient, and `proposals`
+is not automatically the admin. The `proposals` tests use
+`mock_all_auths_allowing_non_root_auth()` because of this.
+
+### How they relate
+
+```
+ Path A  (inside group_treasury)           Path B  (inside proposals)
+ propose_withdraw ─▶ approve/reject ─▶     create_proposal ─▶ vote ─▶ finalize_proposal
+ Passed / Rejected                         Passed / Rejected / Expired
+ (recorded decision, moves nothing)                │
+                                                   ▼  execute_withdraw (caller is a member)
+                                           TreasuryClient.is_member / balance
+                                                   │
+                                                   ▼
+                      Path C: group_treasury.withdraw  (needs treasury admin auth)
+                                         │
+                                         ▼
+                             TokenClient.transfer(treasury → to)
+```
+
+| | Path A: treasury multisig | Path B: `proposals` contract |
+|---|---|---|
+| Where state lives | `group_treasury` (`DataKey::Proposal(u32)`) | `proposals` (`DataKey::Proposal(u64)`) |
+| Who can propose | Treasury members | Any authorized address |
+| Who can vote | Treasury members (checked at vote time) | Any authorized address, once each |
+| Decision rule | `approvals >= threshold` (fixed at init) | `yes_votes > no_votes` after `expires_at` (no quorum) |
+| Early outcome | Passes/rejects as soon as the threshold is reached | Only after `expires_at` |
+| Moves funds? | No | Yes, via `withdraw` |
+| Needs admin auth? | No | Yes (nested `withdraw`) |
+| Cross-contract calls | None | `is_member`, `balance`, `withdraw` on the treasury |
+| Proposal ids | `u32`, in the treasury | `u64`, in `proposals` |
+
+The two systems are **parallel, not layered**:
+
+- `proposals` never calls `propose_withdraw`, `approve_withdraw` or `reject_withdraw`.
+- A `Passed` proposal in one system has no effect on the other. Passing Path A does not authorize
+  Path B, and an `Executed` proposal in `proposals` does not mark anything in the treasury.
+- Nothing prevents both from being used for the same withdrawal, or from disagreeing, because
+  neither consults the other. The balance the treasury enforces at `withdraw` is the only shared
+  safeguard.
+
+### Practical consequences
+
+- **The effective gate is the treasury admin, not either vote.** Both paths ultimately depend on
+  the admin address being willing to authorize `withdraw`. Today the on-chain votes are advisory
+  with respect to that final authorization. The deployment script or the admin's configuration
+  decides how binding they are.
+- **Path B's `proposals` vote is weaker than the treasury's.** It has no membership requirement
+  on voters, no quorum, and the `treasury` address is user-supplied. Path A is the stronger
+  control against outsiders; Path B is the only one that can complete a transfer without the
+  admin signing a separate transaction, and only if the admin's authorization is included.
+- **Failure is clean.** If `withdraw` panics (no admin auth, insufficient funds), the whole
+  `execute_withdraw` reverts and the proposal stays `Passed` so it can be retried.
+- **Choose one path per deployment** and document it for your members. If you want Path A's
+  threshold to actually bind, the admin must be a contract or process that releases funds only
+  for a `Passed` `WithdrawProposal`; this repository does not yet provide one.
+- **Drift risk.** Neither `TreasuryInterface` nor either `TokenInterface` is checked against the
+  real contract. When changing a function signature in `group_treasury` (`is_member`, `balance`,
+  `withdraw`) or the token calls, update the interface file and the cross-contract tests together.
+
+See [`security-checklist.md`](security-checklist.md) for review items that follow from this.
diff --git a/contracts/docs/contracts-proposals-storage.md b/contracts/docs/contracts-proposals-storage.md
new file mode 100644
index 0000000..e5a7232
--- /dev/null
+++ b/contracts/docs/contracts-proposals-storage.md
@@ -0,0 +1,268 @@
+# `proposals` Storage Layout & Treasury Client
+
+Source: [`contracts/contracts/proposals/src/storage.rs`](../contracts/proposals/src/storage.rs),
+[`contracts/contracts/proposals/src/treasury_interface.rs`](../contracts/proposals/src/treasury_interface.rs),
+[`contracts/contracts/proposals/src/treasury_interface_client.rs`](../contracts/proposals/src/treasury_interface_client.rs),
+[`contracts/contracts/proposals/src/lib.rs`](../contracts/proposals/src/lib.rs).
+
+For function signatures see [`api-proposals.md`](api-proposals.md); for the lifecycle narrative
+see [`concepts-proposal-lifecycle.md`](concepts-proposal-lifecycle.md). For how this contract's
+withdrawal path relates to the treasury's own multisig, see
+[`concepts-cross-contract-interfaces.md`](concepts-cross-contract-interfaces.md). The sibling
+document for the treasury is [`contracts-group-treasury-storage.md`](contracts-group-treasury-storage.md).
+
+## Storage tier: everything is instance storage
+
+Every read and write in `proposals` goes through `env.storage().instance()`. The contract never
+calls `.persistent()`, `.temporary()`, `.extend_ttl()` or `bump()` (verified across `lib.rs` and
+`storage.rs`).
+
+**TTL / bump behaviour:**
+
+- All keys below share the **single TTL of the contract's instance entry**. There is no per-key
+  TTL, no TTL constant, and nothing in this contract extends the TTL — not on `create_proposal`,
+  not on `vote`, not on any read.
+- Keeping the instance alive is therefore a platform/operator concern (an out-of-band
+  `extend` / restore of the contract instance). If the instance entry archives, **every** key
+  (admin, id counter, all proposals, all votes) archives together and calls fail until it is
+  restored. See [`concepts-state-archival.md`](concepts-state-archival.md).
+- Because votes and proposals live in instance storage, the instance entry grows with each
+  proposal and each vote. Large numbers of voters make the single entry bigger and every
+  invocation costlier; see [`concepts-resource-budget.md`](concepts-resource-budget.md).
+- `initialize` cannot be used to revive state: it panics (`"already initialized"`) if
+  `DataKey::Admin` is present.
+
+## `DataKey` — storage key inventory
+
+```rust
+#[contracttype]
+pub enum DataKey {
+    Admin,
+    NextProposalId,
+    Proposal(u64),
+    Vote(u64, Address), // (proposal_id, voter) -> bool (true = yes, false = no)
+}
+```
+
+| Key | Value type | Tier | Meaning | Lifecycle |
+|---|---|---|---|---|
+| `DataKey::Admin` | `Address` | instance | Reserved admin slot. No function currently reads it for authorization. | Set once by `initialize` (requires the admin's auth). Never updated. Its presence is the "already initialized" guard. |
+| `DataKey::NextProposalId` | `u64` | instance | Id that will be assigned to the next proposal; equals the count of proposals ever created. | Set to `0` by `initialize`. Read and incremented by `create_proposal` (ids are `0`-based, monotonically increasing, never reused). |
+| `DataKey::Proposal(u64)` | `Proposal` | instance | Full record for proposal `id`. | Created by `create_proposal`. Rewritten whole by `vote`, `finalize_proposal`, `finalize_expired_proposal`, `execute_proposal` and `execute_withdraw`. Read by every function through `load_proposal`, which panics with `"proposal not found"` for unknown ids. Never deleted. |
+| `DataKey::Vote(u64, Address)` | `bool` | instance | The vote `voter` cast on proposal `proposal_id`: `true` = yes, `false` = no. | Written once by `vote`. Its mere existence (`has`) is the duplicate-vote guard (`"voter has already voted"`). Never changed or cleared. |
+
+There is no index of voters per proposal and no list of proposals: the only way to enumerate is
+to walk ids `0..NextProposalId` and look up `Vote(id, address)` for a known address. Only the
+yes/no *tallies* are kept on the `Proposal` itself.
+
+## `Proposal`
+
+```rust
+#[contracttype]
+#[derive(Clone)]
+pub struct Proposal {
+    pub id: u64,
+    pub proposer: Address,
+    pub description: String,
+    pub created_at: u64,
+    pub expires_at: u64,
+    pub yes_votes: u32,
+    pub no_votes: u32,
+    pub status: ProposalStatus,
+
+    // Withdrawal execution parameters.
+    pub treasury: Address,
+    pub token: Address,
+    pub to: Address,
+    pub amount: i128,
+}
+```
+
+| Field | Type | Set by | Notes |
+|---|---|---|---|
+| `id` | `u64` | `create_proposal` | Copy of the `NextProposalId` value at creation. |
+| `proposer` | `Address` | `create_proposal` | Must authorize the creation call. Not checked against treasury membership. |
+| `description` | `String` | `create_proposal` | Free text; stored as given. |
+| `created_at` | `u64` | `create_proposal` | Ledger timestamp (unix seconds) at creation. |
+| `expires_at` | `u64` | `create_proposal` | Unix seconds; must be strictly greater than the creation time. Voting is allowed while `now < expires_at`. |
+| `yes_votes` | `u32` | `vote` | Incremented per `support = true` vote. |
+| `no_votes` | `u32` | `vote` | Incremented per `support = false` vote. |
+| `status` | `ProposalStatus` | all state-changing calls | See below. Starts as `Active`. |
+| `treasury` | `Address` | `create_proposal` | `group_treasury` contract to withdraw from on execution. |
+| `token` | `Address` | `create_proposal` | Token contract to withdraw. |
+| `to` | `Address` | `create_proposal` | Withdrawal recipient. |
+| `amount` | `i128` | `create_proposal` | Must be `> 0`. |
+
+The four withdrawal parameters are fixed at creation. They are never updated, and they are what
+`execute_withdraw` hands to the treasury client.
+
+## `ProposalStatus`
+
+```rust
+#[contracttype]
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub enum ProposalStatus {
+    Active,
+    Approved,
+    Passed,
+    Rejected,
+    Executed,
+    Expired,
+}
+```
+
+| Value | Meaning | Reached by |
+|---|---|---|
+| `Active` | Open for voting; the initial state. | `create_proposal` |
+| `Passed` | Voting closed with `yes_votes > no_votes`. The only state from which execution is allowed. | `finalize_proposal` |
+| `Rejected` | Voting closed with `yes_votes <= no_votes` (ties reject). Terminal. | `finalize_proposal` |
+| `Expired` | Voting window passed and the proposal was closed without a tally. Terminal. | `finalize_expired_proposal` |
+| `Executed` | Execution has run. Terminal. | `execute_proposal` or `execute_withdraw` |
+| `Approved` | **Declared but never assigned.** No function in `lib.rs` writes it. | — (see note) |
+
+> **Note on `Approved`.** The doc comment on `execute_withdraw` says the proposal "must be
+> Approved", but the code checks for `Passed`, and nothing ever sets `Approved`. Treat
+> `Approved` as a reserved, currently unreachable value. Clients should not wait for it.
+
+### Transitions
+
+```
+                    finalize_proposal                     execute_proposal
+                    (now >= expires_at,                   or execute_withdraw
+                     yes > no)                            (status == Passed)
+   create_proposal ┌────────────────────▶ Passed ──────────────────────────▶ Executed
+ ─────────────────▶ Active
+                    │ finalize_proposal (now >= expires_at, yes <= no)
+                    ├────────────────────▶ Rejected
+                    │ finalize_expired_proposal (now > expires_at)
+                    └────────────────────▶ Expired
+```
+
+| From | To | Function | Guard |
+|---|---|---|---|
+| (none) | `Active` | `create_proposal` | `expires_at > now`, `amount > 0`, proposer auth |
+| `Active` | `Passed` | `finalize_proposal` | `now >= expires_at` and `yes_votes > no_votes` |
+| `Active` | `Rejected` | `finalize_proposal` | `now >= expires_at` and `yes_votes <= no_votes` |
+| `Active` | `Expired` | `finalize_expired_proposal` | `now > expires_at` |
+| `Passed` | `Executed` | `execute_proposal` | executor auth; status must be `Passed` |
+| `Passed` | `Executed` | `execute_withdraw` | caller auth; treasury membership, balance, and successful treasury `withdraw` |
+
+Points worth knowing:
+
+- Both `finalize_proposal` and `finalize_expired_proposal` accept only `Active` proposals. For
+  any `now > expires_at` **both** are valid, and whichever is called first decides the outcome
+  (`Passed`/`Rejected` vs `Expired`). At exactly `now == expires_at` only `finalize_proposal`
+  works. Both are callable by anyone and require no auth.
+- `vote` is only valid while `status == Active` **and** `now < expires_at`.
+- `Rejected`, `Expired` and `Executed` have no outgoing transitions.
+- `execute_proposal` only flips the status and emits an event; it moves no funds. Only
+  `execute_withdraw` calls the treasury.
+- The status check in `execute_withdraw` panics `"proposal already executed"` for `Executed`
+  and `"proposal not approved"` for anything other than `Passed`. Because the status is only
+  written after the treasury call succeeds, and a panic reverts the whole invocation, a failed
+  withdrawal leaves the proposal `Passed` and retryable.
+
+## Vote tracking
+
+1. `vote(voter, proposal_id, support)` calls `voter.require_auth()` and loads the proposal.
+2. It requires `Active` status and `now < expires_at`.
+3. It builds `DataKey::Vote(proposal_id, voter)` and panics if that key already exists.
+4. It stores `support` (`bool`) under that key, bumps `yes_votes` or `no_votes` on the
+   `Proposal`, and writes the proposal back.
+5. It emits `vote_cast`.
+
+The `Vote` entry is the source of truth for "has this address voted" and for *how* it voted.
+The counters on `Proposal` are the source of truth for the tally used by `finalize_proposal`.
+Note that **`vote` does not check treasury membership** — any authorized address can vote, and
+each address counts once. Membership is only checked at execution time, for the `caller` of
+`execute_withdraw`.
+
+## Event payload structs
+
+Also defined in `storage.rs` (not stored, only published):
+
+| Struct | Fields | Published as | By |
+|---|---|---|---|
+| `ProposalCreatedEvent` | `id`, `proposer`, `expires_at`, `treasury`, `token`, `to`, `amount` | `proposal_created` | `create_proposal` |
+| `VoteCastEvent` | `id`, `voter`, `support` | `vote_cast` | `vote` |
+| `ProposalFinalizedEvent` | `id`, `status`, `yes_votes`, `no_votes` | `proposal_finalized` | `finalize_proposal` |
+| `ProposalExpiredEvent` | `id` | `proposal_expired` | `finalize_expired_proposal` |
+| `ProposalExecutedEvent` | `id`, `executor` | `executed` (`execute_proposal`) / `execut` (`execute_withdraw`) | execution |
+
+The two execution paths use different topic symbols (`executed` vs `execut`); see
+[`contracts-events.md`](contracts-events.md) for the full event catalogue.
+
+## Typed cross-contract client for `group_treasury`
+
+### What is in the source
+
+- [`treasury_interface.rs`](../contracts/proposals/src/treasury_interface.rs) is the real
+  mechanism. It declares a trait annotated with `#[contractclient(name = "TreasuryClient")]`:
+
+  ```rust
+  #[contractclient(name = "TreasuryClient")]
+  pub trait TreasuryInterface {
+      fn is_member(env: Env, member: Address) -> bool;
+      fn balance(env: Env, token: Address) -> i128;
+      fn withdraw(env: Env, to: Address, token: Address, amount: i128);
+  }
+  ```
+
+  The `soroban-sdk` macro generates a `TreasuryClient` struct from it. The trait is never
+  implemented; it exists only to describe the callee's function names and signatures.
+- [`treasury_interface_client.rs`](../contracts/proposals/src/treasury_interface_client.rs) is
+  **an empty placeholder** whose entire content is the comment
+  `// Intentionally left empty - this file was generated automatically.` It is not declared as a
+  module in `lib.rs` (`lib.rs` has `mod treasury_interface;` only), so it is not compiled and
+  nothing is imported from it. The client lives in the macro expansion of
+  `treasury_interface.rs`, not in this file.
+
+The interface is hand-maintained: it is a minimal subset of `group_treasury`'s public functions
+(`is_member`, `balance`, `withdraw`) and is **not** checked against the real contract at compile
+time. If `group_treasury` renames or re-types one of these functions, `proposals` still
+compiles and the mismatch only surfaces at runtime as a failed invocation.
+
+### How the contract ID is resolved and invoked
+
+There is no registry or lookup. The target contract is whatever `Address` is stored in
+`Proposal.treasury`, supplied by the proposer at `create_proposal`. In `execute_withdraw`:
+
+1. `proposal.treasury` is loaded from instance storage.
+2. `TreasuryClient::new(&env, &proposal.treasury)` wraps that address. Constructing a client
+   does no I/O and does not check that the address is a deployed treasury.
+3. Each method call (`is_member`, `balance`, `withdraw`) compiles to
+   `env.invoke_contract(&address, &Symbol::new("<fn name>"), args)`. The client converts the
+   Rust arguments to `Val`s, invokes the function by name on that contract, and converts the
+   return value back (e.g. to `bool` or `i128`). The call is synchronous and runs inside the
+   caller's transaction.
+4. If the callee panics, errors, or the address is not a contract exporting that function, the
+   panic propagates up the host stack and aborts the entire `execute_withdraw` invocation. All
+   state changes revert, including the status update, and no event is emitted.
+
+The call sequence in `execute_withdraw(caller, proposal_id)`:
+
+| Step | Call | Check |
+|---|---|---|
+| 1 | `caller.require_auth()` | Caller authorized the `proposals` call |
+| 2 | local | Status is `Passed` (`Executed` panics `"proposal already executed"`) |
+| 3 | `TreasuryClient::is_member(caller)` | else `"caller is not a treasury member"` |
+| 4 | `TreasuryClient::balance(token)` | `>= amount`, else `"insufficient funds"` |
+| 5 | `TreasuryClient::withdraw(to, token, amount)` | Treasury moves funds |
+| 6 | local | Status set to `Executed`, stored |
+| 7 | event | `execut` / `ProposalExecutedEvent` |
+
+### Authorization of the nested `withdraw` call
+
+`group_treasury::withdraw` is admin-gated: it calls `admin.require_auth()` on the treasury's
+stored admin. In step 5 that is a **non-root** invocation (the root is `proposals`'
+`execute_withdraw`). The treasury admin's authorization must therefore be present for that
+sub-invocation, for example by having the admin sign an authorization entry covering
+`treasury.withdraw(to, token, amount)`, or by making the admin a contract that authorizes the
+call. The tests use `env.mock_all_auths_allowing_non_root_auth()` for exactly this reason (see
+the comment in [`proposals/src/test.rs`](../contracts/proposals/src/test.rs)). Holding a `Passed`
+proposal is not by itself sufficient to move treasury funds.
+
+The `Proposal.treasury` address is also not validated against any allow-list, so a proposal can
+point at any contract. The membership and balance checks protect against a *real* treasury being
+drained, not against a malicious one; voters should verify the `treasury` field before voting.
+See [`security-checklist.md`](security-checklist.md).
diff --git a/docs/user-guide/getting-started.md b/docs/user-guide/getting-started.md
new file mode 100644
index 0000000..1c0ccea
--- /dev/null
+++ b/docs/user-guide/getting-started.md
@@ -0,0 +1,141 @@
+# Getting started with Clicked
+
+Clicked is a private messaging app where your Stellar wallet is your login. There is no
+password and no separate account to create. This guide takes you from nothing installed to
+sending your first message, file and tokens.
+
+You will need:
+
+- A desktop browser such as Chrome, Brave, Edge or Firefox.
+- A few minutes. You do not need to buy anything to get started.
+
+---
+
+## 1. Install Freighter
+
+Freighter is a free browser extension that holds your Stellar wallet. Clicked uses it to
+confirm that you are you.
+
+1. Go to the Freighter website, [freighter.app](https://www.freighter.app), and choose the
+   install button for your browser. You can also search for "Freighter" in your browser's
+   extension store.
+2. Add the extension, then pin it to your toolbar so it is easy to find (look for the puzzle
+   piece icon in your browser).
+3. Open Freighter and choose **Create new wallet**, or **Import wallet** if you already have one.
+4. Write down your **recovery phrase** (a list of 12 or 24 words) on paper and keep it
+   somewhere safe and private.
+
+> **Keep your recovery phrase secret.** Anyone who has it can take everything in your wallet.
+> Clicked and Freighter will never ask you to type it into a website or send it in a message.
+> If anyone asks for it, even someone claiming to be support, it is a scam.
+
+## 2. Connect your wallet
+
+1. Open Clicked in the same browser.
+2. Select **Connect Wallet**.
+3. Freighter opens a small window asking whether Clicked may see your wallet address.
+   Choose **Approve** (or **Connect**).
+
+Your wallet address is the long code beginning with `G`. It is public by design, a bit like
+a username, and sharing it lets people find you. Connecting does not move any money.
+
+## 3. Sign in
+
+After connecting, Clicked asks you to sign in. Freighter opens again with a request to
+**sign a message**.
+
+**What the request means.** Clicked has made up a one-time piece of text and is asking your
+wallet to put its signature on it. Only the owner of the wallet can produce that signature, so
+it proves that you control the address without a password ever being sent anywhere.
+
+**What it does not do:**
+
+- It does **not** spend any money. No fee is charged.
+- It does **not** give Clicked, or anyone else, permission to spend your funds, now or later.
+- It does **not** send anything to the Stellar network. It is just a signature on a note.
+
+Read the text in the Freighter window. If it looks like a payment or a transaction, with an
+amount, a destination or a fee, **do not approve it**. A sign-in request is plain text.
+
+Choose **Approve** or **Sign**. You are now signed in, and the first time on a new browser your
+device is set up for private messaging automatically. This takes a moment.
+
+> **Signing out.** Selecting your address at the bottom-left of the app disconnects your wallet.
+> You can sign in again at any time with the same steps.
+
+## 4. Start a conversation
+
+**A direct conversation (one other person)**
+
+1. Choose **New conversation**.
+2. Type the other person's username into **Search users**.
+3. Select their name (it says **Start DM**). The conversation opens and you can type straight away.
+
+**A group conversation**
+
+A group is a conversation with three or more people. Create one from **New conversation** by
+choosing several people instead of one, give it a name, and select **Create**. Everyone in the
+group can read new messages. People who join later cannot read what was sent before they joined.
+
+> Group creation and some screens are still being rolled out, so what you see may differ a
+> little from these steps. If you cannot find an option described here, check back after the
+> next update.
+
+### Check you're talking to the right person
+
+At the top of every conversation is a **Safety numbers** button. Compare the number shown
+there with the other person, ideally in person or by a phone call. If they match, select
+**Mark verified**. If the number ever changes later, Clicked shows an amber **Safety number
+changed** warning. This can be harmless (they got a new phone), but confirm with them another
+way before sharing anything sensitive.
+
+For more on this, see [Devices, safety numbers, and privacy](devices-and-privacy.md).
+
+## 5. Send a message
+
+Type in the box at the bottom of the conversation and press **Enter**, or select **Send**.
+Messages are scrambled on your device and can only be opened by the people in the conversation.
+Not even Clicked can read them.
+
+## 6. Send a file
+
+1. Select the **paperclip** icon next to the message box.
+2. Choose a file from your computer. Photos and videos show a small preview in the chat.
+3. The file is sent as soon as you choose it. Wait for the paperclip to become active again
+   before sending another.
+
+To open a file someone sent you, select its name or **Download**. It is unscrambled on your
+device as it downloads.
+
+## 7. Send tokens in a chat
+
+You can send tokens (such as XLM) to the person you are talking to, and the payment appears as
+a card in the conversation showing the amount, the token, and a **View on explorer** link where
+anyone in the chat can check it went through.
+
+1. In the conversation, choose the option to send tokens.
+2. Enter the amount.
+3. Freighter opens and shows the payment: who it goes to, how much, and the network fee.
+   **Check these carefully.** This is the one step that really does spend money.
+4. Choose **Approve** in Freighter.
+
+Unlike signing in, approving a payment is permanent: a sent payment cannot be taken back. Start
+with a small test amount for someone new. Make sure you have enough in your wallet to cover the
+amount plus the small network fee.
+
+---
+
+## Troubleshooting
+
+| What you see | What to try |
+|---|---|
+| Nothing happens when I choose **Connect Wallet** | Check that Freighter is installed, enabled for this site, and unlocked (enter your Freighter password). Then try again. |
+| Freighter's window didn't open | Click the Freighter icon in your toolbar. A request may be waiting there. |
+| "Unable to request sign-in challenge" or similar | Clicked could not be reached. Check your connection and try again in a minute. |
+| I rejected the sign-in request by mistake | Nothing was lost. Select **Connect Wallet** again and approve it this time. |
+| A message says it is unavailable or cannot be opened | It may have been sent before this device was set up. Ask the sender to send it again. |
+| I changed computers or browsers | Install Freighter and import your recovery phrase, then sign in again. Older messages may not appear on a new device. |
+
+More questions about privacy and your devices? Read
+[Devices, safety numbers, and privacy](devices-and-privacy.md) and, for shared group funds,
+[the treasury guide](treasury.md).