diff --git a/openapi.yaml b/openapi.yaml
index c561cfb..7a6b54e 100644
--- a/openapi.yaml
+++ b/openapi.yaml
@@ -27,6 +27,7 @@ paths:
         '200': { description: Replay of an earlier request with the same key and body }
         '400': { $ref: '#/components/responses/Error' }
         '401': { $ref: '#/components/responses/Error' }
+        '413': { $ref: '#/components/responses/Error' }
         '422': { description: Idempotency-Key reused with a different body }
   /v1/orders/{id}:
     get:
@@ -36,6 +37,7 @@ paths:
         - { name: id, in: path, required: true, schema: { type: string } }
       responses:
         '200': { description: The order, content: { application/json: { schema: { $ref: '#/components/schemas/Order' } } } }
+        '401': { $ref: '#/components/responses/Error' }
         '404': { $ref: '#/components/responses/Error' }
   /v1/orders/{id}/cancel:
     post:
@@ -44,7 +46,8 @@ paths:
       parameters:
         - { name: id, in: path, required: true, schema: { type: string } }
       responses:
-        '200': { description: The cancelled order }
+        '200': { description: The cancelled order, content: { application/json: { schema: { $ref: '#/components/schemas/Order' } } } }
+        '404': { $ref: '#/components/responses/Error' }
         '409': { description: The order can no longer be cancelled }
 components:
   securitySchemes:
diff --git a/web/src/content/docs/docs/connect/android-forwarder.md b/web/src/content/docs/docs/connect/android-forwarder.md
index bb78563..b58e555 100644
--- a/web/src/content/docs/docs/connect/android-forwarder.md
+++ b/web/src/content/docs/docs/connect/android-forwarder.md
@@ -1,12 +1,35 @@
 ---
 title: Android forwarder
-description: Pass bank SMS and app alerts to Kaasu.
+description: Pass bank SMS and app alerts from an Android phone to Kaasu.
 sidebar:
   order: 1
 ---
 
-The forwarder is a small Android app on a phone that receives your bank alerts. It signs each alert with a key unique to that phone and sends it to Kaasu.
+> **Status:** the server side (pairing and signed ingest) is done and tested. The Android app itself is not built yet; this page describes what it will do and how its protocol works, so you can build against it.
 
-- Pair it once with a code from the admin screen.
-- You can revoke a phone at any time.
-- Alerts older than 60 seconds or repeated are refused.
+## What it will do
+
+A small app on the phone that receives your bank's SMS and notifications. It forwards only messages from the bank sender ids you allow, signs each with a key that never leaves the phone, and sends them to Kaasu. It keeps a short list of what it forwarded so you can see it working, and a "send test" button.
+
+## Pairing
+
+1. Kaasu shows a one-time pairing code as a QR (valid ten minutes, usable once). It contains your ingest address.
+2. The phone creates an Ed25519 key pair in the Android Keystore and sends the public key with the code.
+3. Kaasu stores the public key against a device id. The private key never leaves the phone.
+
+## Sending alerts
+
+Each alert is a JSON body (`source`, `sender`, `text`, `received_at`) with four headers: device id, timestamp, a 16 to 64 character nonce, and the signature over all of it. Details in [API: device ingest](/docs/reference/api/).
+
+- An alert whose timestamp is more than 60 seconds off is refused.
+- A nonce can be used once, so a captured request cannot be replayed (the second try gets `409`).
+- Every other failure is the same `401` with no detail.
+- A revoked phone is refused at once.
+
+## Battery savers
+
+Phones kill background apps to save power. The app will include per-brand steps (Xiaomi, Oppo, Vivo, Samsung and others) and a foreground notification, because a phone that silently stops forwarding is the main way a shop loses confirmations. The dashboard shows **Phone offline** when it has not heard from the phone for 15 minutes.
+
+## Until it ships
+
+Use [bank email](/docs/connect/bank-email/) as a source, or build a forwarder to the protocol above.
diff --git a/web/src/content/docs/docs/connect/bank-email.md b/web/src/content/docs/docs/connect/bank-email.md
index 63f2365..bef7a4a 100644
--- a/web/src/content/docs/docs/connect/bank-email.md
+++ b/web/src/content/docs/docs/connect/bank-email.md
@@ -1,6 +1,24 @@
 ---
 title: Bank email
-description: Use bank email alerts as a second source.
+description: Use bank email alerts as a second, independent source.
 ---
 
-Forward bank emails to Kaasu. Each message is checked for a valid sender signature and must come from a bank domain on your allow list. Anything else is ignored.
+> **Status:** the email checker is built and tested. It is not started by the server yet, and there is no setting screen for the mailbox, so it does not run in a normal install today.
+
+## How it works
+
+Kaasu reads an inbox that receives your bank's alert emails over IMAP with TLS, using an app password. For every unread message it:
+
+1. Checks the **DKIM signature** on the raw message.
+2. Requires the signing domain to be on the bank allow list (for example `hdfcbank.net`, `icicibank.com`, `axisbank.com`, `sbi.co.in`, `kotak.com`) **and** to match the From address.
+3. Reads the body, decoding base64 and quoted-printable and looking inside nested parts, with a size limit.
+4. Parses the credit with the bank's parser. Unknown formats are kept as evidence and never confirm anything.
+5. Marks the message read so it is not fetched again.
+
+A message that fails any step is logged as rejected with a reason (`no_dkim`, `bad_dkim`, `domain_not_allowed`, `from_not_aligned`) and ignored. A copy that arrives by SMS and by email is recognised as the **same payment**, which adds a second source and raises confidence.
+
+## Tips
+
+- Use a dedicated mailbox and an app password, never your main password.
+- Forward only bank alerts to it.
+- Email alone cannot be hurried by an attacker: a forged email fails DKIM, and an old one fails the time window.
diff --git a/web/src/content/docs/docs/connect/mac-messages.md b/web/src/content/docs/docs/connect/mac-messages.md
index 67ea348..72f94e5 100644
--- a/web/src/content/docs/docs/connect/mac-messages.md
+++ b/web/src/content/docs/docs/connect/mac-messages.md
@@ -1,6 +1,19 @@
 ---
 title: Messages on Mac and iPhone
-description: Use the Apple apps as an alert source.
+description: Use an iPhone relayed to a Mac as an alert source (experimental).
 ---
 
-The Apple apps can pass bank messages to Kaasu in the same signed way as the Android forwarder. Pair the device from the admin screen, then confirm it appears in the device list.
+> **Status:** planned and experimental. The server side (signed ingest) is ready; the Mac agent is not built yet.
+
+## Idea
+
+An iPhone cannot let apps read its SMS. The workaround is to turn on **Text Message Forwarding** to a Mac you own. The Mac's Messages database then holds the bank SMS, and a small Kaasu agent on the Mac reads it and sends each allowed message to Kaasu.
+
+## What it will need
+
+- Full Disk Access for the agent, granted by you.
+- Only messages from the bank sender ids you allow are read.
+- The agent signs requests with a key held in the macOS Keychain, in exactly the same way as the [Android forwarder](/docs/connect/android-forwarder/).
+- It is labelled experimental in the app, and warns you when it stops working, because it depends on how Apple stores messages.
+
+Prefer [bank email](/docs/connect/bank-email/) or an Android phone when you can.
diff --git a/web/src/content/docs/docs/connect/supported-banks.md b/web/src/content/docs/docs/connect/supported-banks.md
new file mode 100644
index 0000000..1e09116
--- /dev/null
+++ b/web/src/content/docs/docs/connect/supported-banks.md
@@ -0,0 +1,28 @@
+---
+title: Supported banks
+description: Which bank alerts Kaasu understands, and how new ones are added.
+---
+
+Kaasu reads **credits** (money received) from these banks. Debits, offers and anything unfamiliar are never treated as a payment.
+
+| Bank | SMS sender ids | Email domain |
+|---|---|---|
+| HDFC Bank | `HDFCBK` | `hdfcbank.net` |
+| State Bank of India | `SBIUPI`, `SBIINB`, `SBIPSG` | `sbi.co.in` |
+| ICICI Bank | `ICICIB` | `icicibank.com` |
+| Axis Bank | `AXISBK` | `axisbank.com` |
+| Kotak Mahindra Bank | `KOTAKB` | `kotak.com` |
+
+Sender ids are matched with their usual operator prefix and suffix, so `VM-HDFCBK-S` counts as `HDFCBK`. A look-alike such as `HDFCBK.evil` does not match.
+
+## What gets read
+
+The amount (in paise, parsed from the digits, never as a decimal number), the 12-digit UTR, the date, a masked payer and the last digits of your account. A reference that is not exactly 12 digits is rejected, so a longer number cannot be truncated into a valid-looking one.
+
+## Not understood?
+
+If a message is not recognised, Kaasu keeps it as evidence and never confirms from it. The optional [AI helper](/docs/use/ai-features/) can propose a reading, which always goes to you for approval.
+
+## Add a bank
+
+Parsers are small and have golden test files. See [Contribute](/docs/reference/contribute/): add a pattern, a **redacted** sample message (no real names, numbers or UTRs) and the expected result.
diff --git a/web/src/content/docs/docs/index.md b/web/src/content/docs/docs/index.md
index 6943ced..e55af7e 100644
--- a/web/src/content/docs/docs/index.md
+++ b/web/src/content/docs/docs/index.md
@@ -7,10 +7,22 @@ Kaasu confirms UPI payments for small shops. Customers pay your bank directly, a
 
 ## Start here
 
-1. [Install Kaasu](/docs/start/install/) and try it with demo data.
-2. [Take your first payment](/docs/start/first-payment/).
-3. [Connect a bank alert source](/docs/connect/android-forwarder/).
-4. [Connect your shop](/docs/connect/woocommerce/): WooCommerce works today, [Shopify](/docs/connect/shopify/) is planned.
+1. [How Kaasu works](/docs/start/how-it-works/): the flow and the rules it never breaks.
+2. [Install Kaasu](/docs/start/install/) and run the first-time setup.
+3. [Take your first payment](/docs/start/first-payment/).
+4. [Connect an alert source](/docs/connect/android-forwarder/) and [your shop](/docs/connect/woocommerce/).
+
+## Everyday use
+
+[Dashboard](/docs/use/dashboard/), [Orders and pay links](/docs/use/orders-and-links/), [Needs your OK](/docs/use/needs-your-ok/), [Refunds](/docs/use/refunds/), [Reconciliation](/docs/use/reconciliation/), [Languages and voice](/docs/use/languages-and-voice/), [AI help](/docs/use/ai-features/), [Backups and keys](/docs/use/backup-and-keys/).
+
+## Reference
+
+[API](/docs/reference/api/), [Webhooks](/docs/reference/webhooks/), [Command line](/docs/reference/cli/), [Configuration](/docs/reference/configuration/), [Orders, states and the ledger](/docs/reference/ledger-and-states/), [Operations](/docs/reference/operations/), [Security](/docs/reference/security/), [Troubleshooting](/docs/reference/troubleshooting/), [FAQ](/docs/reference/faq/).
+
+## What works today
+
+Kaasu is early software. The core is built and tested: orders, exact amounts, the matcher, signed alerts, webhooks, the ledger, the pay and receipt pages, the dashboard and the command line. Phone and Mac apps, the email watcher's mailbox setup, backups and several screens are still being connected, and each page says so where it matters. Test with small amounts first.
 
 ## How these docs are kept
 
diff --git a/web/src/content/docs/docs/reference/api.md b/web/src/content/docs/docs/reference/api.md
index 9594d2c..b6de89d 100644
--- a/web/src/content/docs/docs/reference/api.md
+++ b/web/src/content/docs/docs/reference/api.md
@@ -1,11 +1,118 @@
 ---
 title: API
-description: Kaasu REST API basics, including the base path, API keys, idempotency and paise amounts.
+description: "The Kaasu REST API: authentication, orders, idempotency, errors, limits, customer pages, webhooks and the device ingest API."
 ---
 
-- Base path `/v1`.
-- One API key per shop.
-- `Idempotency-Key` header is required when creating an order.
-- Money fields are integer paise, for example `49907` means ₹499.07.
+Kaasu has three HTTP listeners. This page covers the three you may call from code: the **public** order API, the **customer pages**, and the **ingest** API used by bank-alert devices. The admin listener is for people and is never exposed to the internet. The machine-readable spec is `openapi.yaml` in the repository.
 
-The full specification lives in `openapi.yaml` in the repository.
+## Basics
+
+- Base path `/v1`, JSON in and out, `Content-Type: application/json`.
+- Money is an integer number of **paise**: `49907` means ₹499.07. Floats are rejected. Currency is always `INR`.
+- Send `Authorization: Bearer <api key>`. Create a key on your server with `kaasu apikey new <label>`; it is shown once and only a hash is stored.
+- Every response carries an `X-Request-Id`. Quote it when you report a problem.
+- Request bodies are limited to 64 KB, and each listener rate-limits per client address (public: 200 requests a second, burst 400). Over the limit you get `429` with `Retry-After`.
+
+## Create an order
+
+`POST /v1/orders` with an `Idempotency-Key` header (required).
+
+```json
+{ "amount_paise": 49907, "reference": "INV-1042", "note": "Order 1042", "expires_in_seconds": 900 }
+```
+
+| Field | Meaning |
+|---|---|
+| `amount_paise` | Required. ₹1 to ₹1,00,000 (`100` to `10000000`). |
+| `account_id` | Receiving account. Required only when the shop has more than one active account. |
+| `reference` | Your own id, shown to you and on the receipt. |
+| `note` | Shown in the customer's UPI app (first 50 characters). |
+| `expires_in_seconds` | 60 to 86400, default 900 (15 minutes). |
+
+The reply is `201` with the order. The `amount_paise` you get back is the exact amount the customer must pay: Kaasu adds a few paise (up to 99) so that every open order has a unique amount, and that is how a bank alert is matched to it. `base_amount_paise` is what you asked for.
+
+### Idempotency
+
+Repeat a request with the same key and the same body and you get the first order back with status `200` and the header `Idempotent-Replayed: true`. The same key with a different body is `422 idempotency_conflict`. Use one key per order attempt, for example your cart id.
+
+## Read and cancel
+
+- `GET /v1/orders/{id}` returns the order.
+- `POST /v1/orders/{id}/cancel` cancels an unpaid order. An order that is already paid, expired or cancelled returns `409 not_cancellable`.
+
+## The order object
+
+```json
+{
+  "id": "ord_x7k2m9q4w8r5t1y3u6p0",
+  "account_id": "acc_000001",
+  "state": "awaiting",
+  "base_amount_paise": 49900,
+  "amount_paise": 49907,
+  "currency": "INR",
+  "reference": "INV-1042",
+  "upi_link": "upi://pay?pa=shop%40okhdfcbank&pn=Sharma+Sweets&am=499.07&cu=INR&tn=Order+1042",
+  "expires_at": "2026-10-24T10:15:00Z",
+  "created_at": "2026-10-24T10:00:00Z",
+  "updated_at": "2026-10-24T10:00:00Z"
+}
+```
+
+`upi_link` is present only while the order is `awaiting`. A `queued` order (the amount pool for that price is full) has no link until a slot frees up, so never show a pay button for it.
+
+### States
+
+| State | Meaning |
+|---|---|
+| `awaiting` | Waiting for the customer to pay. |
+| `queued` | Waiting for a free exact amount. It moves to `awaiting` on its own. |
+| `confirmed` | A verified bank alert matched the order. Safe to fulfil. |
+| `review` | Kaasu is unsure (wrong amount, unknown sender, late). The owner decides. |
+| `late_paid` | Paid after the order expired and accepted by the owner. |
+| `rejected`, `cancelled`, `expired` | Closed without payment. |
+| `refunded`, `disputed` | Set by the owner after the fact. |
+
+Only `confirmed` and `late_paid` mean money arrived. Do not infer payment from anything the customer's browser tells you.
+
+## Errors
+
+Errors are `{"error": {"code": "...", "message": "..."}}`.
+
+| Status | `code` | When |
+|---|---|---|
+| 400 | `invalid_request` | Bad JSON, a float amount, an amount or expiry out of range, a missing key. |
+| 401 | `unauthorized` | Missing, invalid or revoked API key. |
+| 404 | `not_found` | No such order. |
+| 409 | `not_cancellable` | The order can no longer be cancelled. |
+| 413 | `too_large` | Body over 64 KB. |
+| 422 | `idempotency_conflict` | Same key, different body. |
+| 429 | `rate_limited` | Too many requests; wait `Retry-After` seconds. |
+| 500 | `internal` | Something went wrong. Details are in the server log under your `X-Request-Id`. |
+
+## Customer pages
+
+Send your customer to `/pay/{order id}` on your public address. These pages need no API key and load no third-party script.
+
+- `GET /pay/{id}` is the pay page: exact amount, one button that opens the UPI app, and live waiting steps.
+- `GET /pay/{id}/status` returns `{"state": "..."}` only. The page polls it every two seconds; you can too.
+- `GET /pay/{id}/done` shows success only for a confirmed or late-paid order, and redirects to the pay page otherwise.
+- `GET /pay/{id}/receipt` is a printable receipt (`?format=txt` for plain text) with the UTR and a six-character check code the shopkeeper can compare with their own app.
+- Reusable payment links and a counter QR for walk-in customers exist in the engine but have no web routes yet, so create orders through this API for now.
+
+## Webhooks
+
+Kaasu pushes order changes to your server so you never have to poll. See [Webhooks](/docs/reference/webhooks/) for events, signatures and retries. Ready-made integrations: [WooCommerce](/docs/connect/woocommerce/); [Shopify](/docs/connect/shopify/) is planned.
+
+## Device ingest API
+
+Phones and the Mac agent forward bank alerts to the ingest listener. You only need this to build your own forwarder.
+
+1. **Pair.** `POST /ingest/v1/pair` with the one-time pairing token from the QR code and the device's Ed25519 public key. The token works once and expires after ten minutes.
+2. **Send alerts.** `POST /ingest/v1/alerts` with the raw alert JSON (`source`, `sender`, `text`, `received_at`) and four headers: `X-Kaasu-Device`, `X-Kaasu-Timestamp` (unix seconds), `X-Kaasu-Nonce` (16 to 64 characters) and `X-Kaasu-Signature`, the base64 Ed25519 signature over the version, device id, timestamp, nonce and SHA-256 of the body.
+3. **Rules.** The timestamp must be within 60 seconds of the server's clock, and a nonce can be used once (a replay gets `409`). Any failed check is the same `401` with no detail. An alert from a sender Kaasu does not know is kept as evidence and never confirms anything.
+
+Alerts from devices are authentic only because they are signed; text that merely looks like a bank message is never trusted.
+
+## Try it without real money
+
+Run `make dev` for demo data and `kaasu sim --list` to see the simulator's scenarios. Dev mode blocks outbound network calls, so you can test your integration offline.
diff --git a/web/src/content/docs/docs/reference/cli.md b/web/src/content/docs/docs/reference/cli.md
new file mode 100644
index 0000000..f3f255b
--- /dev/null
+++ b/web/src/content/docs/docs/reference/cli.md
@@ -0,0 +1,35 @@
+---
+title: Command line
+description: Every kaasu command, what it does and what it prints.
+---
+
+Commands read the same settings as the server: `KAASU_DATABASE_PATH`, `KAASU_MASTER_KEY` and the rest in [Configuration](/docs/reference/configuration/). Run them as the user that owns the database.
+
+| Command | What it does |
+|---|---|
+| `kaasu serve` | Starts the three listeners and the background jobs. It takes no flags; configuration comes from the environment or `KAASU_CONFIG`. An unknown argument is refused. |
+| `kaasu migrate` | Applies database migrations and exits. The server does this at start too. |
+| `kaasu keygen` | Prints a fresh 32-byte master key. Does not touch the database. |
+| `kaasu rotate-key` | Re-wraps every secret under `KAASU_NEW_MASTER_KEY`, all or nothing. |
+| `kaasu account add --vpa <id> --bank <name> --name <display name> [--limit-rupees N]` | Adds a receiving UPI account. `--limit-rupees` is the auto-confirm ceiling; 0 means every payment waits for you. |
+| `kaasu apikey new <label>` | Creates an API key and prints it once. Only a hash is stored. |
+| `kaasu admin init --name <name> [--role owner\|staff]` | Creates a person and prints their authenticator link once. Default role is owner. |
+| `kaasu verify` | Walks the ledger hash chain and reports the first broken row. |
+| `kaasu doctor` | Checks config, master key, database, pending migrations and the ledger. It only reads. |
+| `kaasu healthcheck` | Exits 0 if the admin listener answers `/healthz` (used by the Docker image). |
+| `kaasu sim --list` | Lists the payment simulator scenarios. |
+| `kaasu version` | Prints the version. |
+| `kaasu backup`, `kaasu pair` | Placeholders; not implemented yet. |
+
+## Exit codes
+
+`0` success, `1` the command ran and failed, `2` the command was used wrongly (the usage line is printed).
+
+## Examples
+
+```bash
+kaasu account add --vpa sharma.sweets@okhdfcbank --bank HDFC --name "Sharma Sweets" --limit-rupees 5000
+kaasu apikey new website
+kaasu admin init --name priya --role owner
+kaasu doctor
+```
diff --git a/web/src/content/docs/docs/reference/configuration.md b/web/src/content/docs/docs/reference/configuration.md
new file mode 100644
index 0000000..7d790fe
--- /dev/null
+++ b/web/src/content/docs/docs/reference/configuration.md
@@ -0,0 +1,33 @@
+---
+title: Configuration
+description: Every setting, its default and where it comes from.
+---
+
+Settings come from three places, later ones winning: built-in defaults, a JSON file named by `KAASU_CONFIG`, then environment variables. An unknown key in the file is an error, so a typo cannot be silently ignored.
+
+| Environment variable | File key | Default | Meaning |
+|---|---|---|---|
+| `KAASU_PUBLIC_ADDR` | `public_addr` | `:8080` | Customer pages and the order API. |
+| `KAASU_INGEST_ADDR` | `ingest_addr` | `:8443` | Signed device alerts. |
+| `KAASU_ADMIN_ADDR` | `admin_addr` | `127.0.0.1:9000` | Dashboard and metrics. Loopback by default. |
+| `KAASU_PAIRING_HOST` | `pairing_host` | the ingest address | The host:port phones are told to reach for ingest (put your proxy address here). |
+| `KAASU_DATABASE_PATH` | `database_path` | `kaasu.db` | The SQLite file. |
+| `KAASU_LOG_LEVEL` | `log_level` | `info` | `debug`, `info`, `warn` or `error`. |
+| `KAASU_ADMIN_ALLOW_NON_LOOPBACK` | `admin_allow_non_loopback` | off | Allows the admin address to be non-loopback. Only on a private network. |
+| `KAASU_CONFIG` | | none | Path to the JSON config file. |
+
+## Secrets
+
+| Variable | Meaning |
+|---|---|
+| `KAASU_MASTER_KEY` | The 32-byte master key from `kaasu keygen`. On macOS it can also come from the login keychain; under systemd or Compose it can be a credential file. |
+| `KAASU_NEW_MASTER_KEY` | Used only by `kaasu rotate-key`. |
+| `KAASU_DISABLE_KEYCHAIN=1` | Never read the macOS keychain (containers, CI, tests). |
+
+## Ports and TLS
+
+Kaasu serves plain HTTP. Put a reverse proxy or your host's TLS in front of the public and ingest ports, and never expose the admin port. The default `:8080` stands in for the usual public `:443`; terminating TLS on 443 is left to the proxy.
+
+## Limits worth knowing
+
+Request bodies are limited to 64 KB, each request has a 15 second budget, and each listener rate-limits per client address (public 200 a second with a burst of 400, ingest 50 and 100, admin 10 and 30). The server shuts down gracefully, finishing in-flight requests, and exits non-zero if any listener fails.
diff --git a/web/src/content/docs/docs/reference/faq.md b/web/src/content/docs/docs/reference/faq.md
new file mode 100644
index 0000000..89bcea6
--- /dev/null
+++ b/web/src/content/docs/docs/reference/faq.md
@@ -0,0 +1,48 @@
+---
+title: FAQ
+description: Short answers to common questions.
+---
+
+## Does Kaasu hold my money?
+
+No. The customer's bank pays your bank directly. Kaasu is not a payment gateway and never has your funds.
+
+## Do I need a payment-aggregator licence?
+
+Kaasu does not process payments, so it is not an aggregator. You are still responsible for your own tax and compliance. See [Bank terms](/docs/reference/bank-terms/).
+
+## What if two customers pay the same amount?
+
+They cannot: every open order gets its own exact amount to the paisa. See [Orders and pay links](/docs/use/orders-and-links/).
+
+## What if the customer pays the wrong amount?
+
+The order is held as **Needs your OK**. You see what was expected and what the bank reported, and you approve or reject.
+
+## What if my phone is off or the SMS is late?
+
+The order waits. A second source such as bank email confirms it without the phone. The dashboard warns when you have fewer than two live sources.
+
+## Can someone fake a payment?
+
+A screenshot, a typed UTR or a pasted message cannot confirm anything. Only a signed device alert or a DKIM-verified bank email can, and the exact amount must match. See [Security](/docs/reference/security/).
+
+## Does it work for businesses with many UPI ids?
+
+Yes. Add several receiving accounts. When there is more than one, an API call must say which `account_id` it is for.
+
+## Is AI required?
+
+No. It is off by default and never confirms a payment. See [AI help](/docs/use/ai-features/).
+
+## Which languages?
+
+English and ten Indian languages, with native review still needed. See [Languages and voice](/docs/use/languages-and-voice/).
+
+## What does it cost, and what is the licence?
+
+It is free and open source under the AGPL-3.0. A separate commercial licence is available from OpenSawce for people who cannot meet the AGPL terms. See [Terms](/terms/).
+
+## Which shop platforms work?
+
+WooCommerce works today. [Shopify](/docs/connect/shopify/) is planned. Anything else can use the [API](/docs/reference/api/).
diff --git a/web/src/content/docs/docs/reference/ledger-and-states.md b/web/src/content/docs/docs/reference/ledger-and-states.md
new file mode 100644
index 0000000..5b7f891
--- /dev/null
+++ b/web/src/content/docs/docs/reference/ledger-and-states.md
@@ -0,0 +1,40 @@
+---
+title: Orders, states and the ledger
+description: The order state machine and the tamper-evident ledger behind it.
+---
+
+## States
+
+An order moves along fixed edges only. Nothing outside the state machine changes a state, and every move writes a ledger row in the same transaction.
+
+| From | Can go to |
+|---|---|
+| `created` | `awaiting`, `queued`, `cancelled` |
+| `queued` | `awaiting`, `cancelled`, `expired` |
+| `awaiting` | `matched`, `review`, `cancelled`, `expired` |
+| `matched` | `confirmed`, `review` |
+| `review` | `confirmed`, `late_paid`, `rejected`, `awaiting` (only before the order expires) |
+| `expired` | `review` |
+| `confirmed`, `late_paid` | `refunded`, `disputed` |
+| `disputed` | `confirmed`, `refunded` |
+| `rejected`, `cancelled`, `refunded` | none |
+
+An alert that arrives for an expired order puts it into `review`; Kaasu never confirms a late payment on its own.
+
+## Amount slots
+
+Each open order holds one exact amount on its account. The hold lasts until the order's expiry plus 10 minutes. A cancelled, rejected or expired order keeps its slot through that grace window, and only a refund frees it at once. See [Orders and pay links](/docs/use/orders-and-links/).
+
+## The ledger
+
+The ledger is an append-only table. Each row stores a SHA-256 hash of its own content and the previous row's hash, so the rows form a chain. Database triggers block `UPDATE` and `DELETE`.
+
+- The row records the kind (for example `order.confirmed`), the order, the actor (`api:<key>`, `matcher`, `admin:<name>`, `cli`) and a small payload.
+- It never stores raw alert text or full payer identifiers.
+- `kaasu verify` recomputes the chain. Editing, removing or re-ordering a row breaks it from that row on.
+
+The chain proves nothing was changed in the middle. Removing the newest rows is only detectable if you keep the latest hash somewhere else, which is why off-site backups matter.
+
+## Evidence
+
+The raw alert bytes are stored once, exactly as received, in an evidence store. The same payment arriving by two sources becomes one alert with two sources, which raises the match score. A payer address is masked everywhere except in this evidence store.
diff --git a/web/src/content/docs/docs/reference/operations.md b/web/src/content/docs/docs/reference/operations.md
new file mode 100644
index 0000000..a8ada10
--- /dev/null
+++ b/web/src/content/docs/docs/reference/operations.md
@@ -0,0 +1,35 @@
+---
+title: Operations
+description: Health checks, logs, metrics and the background jobs.
+---
+
+## Health
+
+- `GET /healthz` on each listener returns `{"status":"ok"}`. Docker uses `kaasu healthcheck`, which asks the admin listener.
+- `kaasu doctor` is the deeper check: configuration, master key, database, pending migrations and the ledger. It never changes anything.
+
+## Logs
+
+Logs are JSON lines on stderr. Every request has an `X-Request-Id` that appears in its log lines. Before a line is written, email addresses, UPI addresses, 12-digit UTRs and long account numbers are masked (for example `ra***@okicici`, `***5678`), including inside error text.
+
+## Metrics
+
+`/metrics` on the **admin** port serves Prometheus metrics. It is not on the public or ingest ports.
+
+## Background jobs
+
+A small persistent scheduler runs inside the server. Jobs survive restarts and a crashed job is retried.
+
+| Job | Every | Does |
+|---|---|---|
+| `orders.expire` | 5 s | Expires orders whose time is up. |
+| `pool.sweep` | 1 min | Gives freed amounts to queued orders. |
+| `webhooks.deliver` | 5 s | Sends pending webhooks. |
+| `nonces.purge` | 5 min | Forgets alert nonces older than ten minutes. |
+| `jobs.purge` | 1 h | Removes finished jobs older than a week. |
+
+Stopping the server waits for the scheduler to finish before closing the database.
+
+## Upgrading
+
+Download the new binary (or image), restart. Migrations run in order at start and are never edited after release. Back up the database first.
diff --git a/web/src/content/docs/docs/reference/security.md b/web/src/content/docs/docs/reference/security.md
index c7d550b..bd6f106 100644
--- a/web/src/content/docs/docs/reference/security.md
+++ b/web/src/content/docs/docs/reference/security.md
@@ -6,10 +6,50 @@ description: How Kaasu protects your shop with signed alerts, verified email, sa
 - **Three separate doors.** Customer pages, device alerts and the admin screen are served separately. Admin is reachable only from your own machine or VPN.
 - **Signed alerts.** Each device signs every alert. Replays and old messages are refused.
 - **Verified email.** Email alerts must pass sender verification and come from allowed bank domains.
-- **Safe sign-in.** Passkeys, with an authenticator code as backup.
+- **Safe sign-in.** An authenticator code (6 digits, each usable once), lockout after five wrong tries, hashed sessions with idle and absolute limits, form tokens against forged requests, and a fresh code for decisions that move money. Passkeys are planned.
 - **Protected secrets.** Keys are encrypted and kept apart from the database.
 - **A ledger you can check.** Append only and chained; `kaasu verify` proves it.
 
 Report a vulnerability through the private security advisory form on GitHub, not a public issue.
 
 The full design is in [architecture.md](https://github.com/opensawce/kaasu/blob/main/architecture.md).
+
+## The details
+
+### Who can confirm a payment
+
+Only the matcher, and only from a verified alert whose amount matches exactly, can confirm automatically. A test in the repository scans the code to make sure nothing else changes an order to confirmed. The one human exception is the owner approving a held payment, which needs the owner role, a valid form token and a code entered in the last five minutes, and writes their name to the ledger.
+
+### Alerts
+
+- Device alerts are signed with Ed25519 over a version tag, the device id, the timestamp, a nonce and the body's SHA-256. The window is 60 seconds and each nonce works once.
+- Failures return an identical `401` with no detail, so nothing can be learned by probing.
+- Bank email must pass DKIM on the raw message, from an allowed bank domain that matches the From address.
+- Alert text and UPI notes are untrusted data. They are stored and shown escaped, never executed, and never sent to an AI model unmasked.
+
+### Secrets
+
+Secrets are encrypted with per-secret keys wrapped by the master key. API keys are stored only as hashes. The master key never lives in the database.
+
+### Network
+
+- Customer pages, ingest and admin are three listeners on three ports. Admin routes are mounted only on the admin listener.
+- Every response carries a strict content security policy, no third-party script runs on customer pages, and all outbound webhook calls refuse private and loopback addresses and redirects.
+- Request bodies, request time and request rate are limited on every listener.
+
+### Supply chain
+
+Releases are built reproducibly and signed with Sigstore; the SBOM is listed in the signed `SHA256SUMS`. GitHub Actions are pinned to full commit SHAs, dependencies are scanned with `govulncheck` and CodeQL runs on every change.
+
+### Verifying a release
+
+```bash
+sha256sum --ignore-missing -c SHA256SUMS
+cosign verify-blob --certificate kaasu-linux-amd64.pem --signature kaasu-linux-amd64.sig \
+  --certificate-identity-regexp 'https://github.com/opensawce/kaasu/.github/workflows/release.yml@.*' \
+  --certificate-oidc-issuer https://token.actions.githubusercontent.com kaasu-linux-amd64
+```
+
+## Known limits
+
+The ledger detects edits but cannot detect the newest rows being removed unless you keep the latest hash elsewhere. The listeners speak plain HTTP and expect TLS from a proxy. An external security audit is planned before 1.0 ([issue #78](https://github.com/opensawce/kaasu/issues/78)).
diff --git a/web/src/content/docs/docs/reference/troubleshooting.md b/web/src/content/docs/docs/reference/troubleshooting.md
new file mode 100644
index 0000000..254d5d8
--- /dev/null
+++ b/web/src/content/docs/docs/reference/troubleshooting.md
@@ -0,0 +1,42 @@
+---
+title: Troubleshooting
+description: Common problems and what to check first.
+---
+
+Start with `kaasu doctor`: it names the failing check.
+
+## The server will not start
+
+| Message | Fix |
+|---|---|
+| `master key: ...` | Set `KAASU_MASTER_KEY` to a key from `kaasu keygen`. |
+| `listen public on :8080: address already in use` | Another program uses the port. Change `KAASU_PUBLIC_ADDR`. |
+| `config: ...` | A typo in `KAASU_CONFIG` or an invalid address. Unknown keys are errors. |
+| `serve: unexpected arguments` | `kaasu serve` takes no flags. Use environment variables. |
+
+## An order never confirms
+
+1. Is an alert source live? The dashboard shows a phone as offline after 15 minutes of silence.
+2. Did the customer pay the **exact** amount, to the right UPI id? Check the order's `amount_paise`.
+3. Did the order expire first? A late payment goes to [Needs your OK](/docs/use/needs-your-ok/).
+4. Is the sender allowed? A message from an unknown sender is kept as evidence and never confirms.
+5. Is the amount above the account's `--limit-rupees`? Then it waits for you.
+
+## API errors
+
+See the table in [API](/docs/reference/api/#errors). `401` means the key is wrong or revoked; `422` means you reused an `Idempotency-Key` with a different body; `429` means slow down and honour `Retry-After`.
+
+## Webhooks do not arrive
+
+- The address must be `https` and public. `localhost` and private addresses are refused by design.
+- Your endpoint must answer `2xx` within 10 seconds.
+- Check the signature against the raw body, not re-serialised JSON.
+- Events are retried eight times over about a day, then dead-lettered.
+
+## `kaasu verify` fails
+
+The chain shows the first row that does not match. Do not edit the database to fix it. Restore from a backup taken before that row, and report it if you did not change anything yourself.
+
+## Locked out of the dashboard
+
+Five wrong codes lock a person for five minutes. Check your phone's clock is correct, since codes depend on it. If you lost your authenticator, create a new person with `kaasu admin init` from the server.
diff --git a/web/src/content/docs/docs/reference/webhooks.md b/web/src/content/docs/docs/reference/webhooks.md
index 8899d75..8b0b7a0 100644
--- a/web/src/content/docs/docs/reference/webhooks.md
+++ b/web/src/content/docs/docs/reference/webhooks.md
@@ -1,14 +1,88 @@
 ---
 title: Webhooks
-description: Events Kaasu sends to your systems.
+description: Events Kaasu sends to your systems, how to verify them and how retries work.
 ---
 
-Kaasu sends a signed `POST` for each event. Delivery is at least once, so use `event_id` to ignore repeats.
+Kaasu sends a signed `POST` to your server whenever an order changes in a way that matters. Delivery is **at least once**, so the same event can arrive more than once: dedupe by `event_id`.
+
+Each event is written to an outbox **in the same database transaction** as the change that caused it, so a crash never loses an event or sends one for a change that was rolled back.
 
 ## Events
 
-`order.confirmed`, `order.review`, `order.rejected`, `order.expired`, `order.cancelled`, `order.refunded`, `order.disputed`
+| `type` | Sent when |
+|---|---|
+| `order.confirmed` | A verified alert matched the order (or the owner approved it). Safe to fulfil. |
+| `order.review` | The order is held for the owner. |
+| `order.rejected` | The owner rejected a held payment. |
+| `order.expired` | The order expired unpaid. |
+| `order.cancelled` | The order was cancelled. |
+| `order.refunded` | The full amount was refunded. |
+| `order.disputed` | Reconciliation or the owner marked it disputed. |
+
+Act only on final states. A payment that arrived after expiry and that the owner accepted is also sent as `order.confirmed`, with `state` set to `late_paid` in the payload, so check `state` if you treat late payments differently.
+
+## The request
+
+```http
+POST /your/webhook HTTP/1.1
+Content-Type: application/json
+X-Kaasu-Event-Id: evt_5a1c...
+X-Kaasu-Signature: t=1767261600,v1=3d73b6f9...
+
+{"event_id":"evt_5a1c...","type":"order.confirmed","created_at":"2026-10-24T10:02:11Z",
+ "data":{"order":{"id":"ord_...","state":"confirmed","amount_paise":49907,
+ "reference":"INV-1042","account_id":"acc_000001","confirmed_at":"2026-10-24T10:02:10Z"}}}
+```
+
+The payload carries ids, state, amount and your reference. It never carries payer names, UPI addresses or account numbers.
 
 ## Verify the signature
 
-The header looks like `X-Kaasu-Signature: t=<unix>,v1=<hmac>`. Compute HMAC-SHA256 of `t.body` with your webhook secret and compare it to `v1`. Reject old timestamps.
+`X-Kaasu-Signature` is `t=<unix seconds>,v1=<hex>`. Compute HMAC-SHA256 with your webhook secret over the string `t`, a dot, then the **raw request body** (exactly the bytes received, before any JSON parsing). Compare with `v1` in constant time, and reject timestamps more than five minutes from your clock.
+
+```python
+import hmac, hashlib, time
+
+def verify(secret: str, header: str, body: bytes, tolerance=300) -> bool:
+    parts = dict(p.split("=", 1) for p in header.split(","))
+    ts, v1 = int(parts["t"]), parts["v1"]
+    if abs(time.time() - ts) > tolerance:
+        return False
+    want = hmac.new(secret.encode(), f"{ts}.".encode() + body, hashlib.sha256).hexdigest()
+    return hmac.compare_digest(want, v1)
+```
+
+```js
+import { createHmac, timingSafeEqual } from 'node:crypto';
+
+export function verify(secret, header, body, tolerance = 300) {
+  const p = Object.fromEntries(header.split(',').map((x) => x.split('=')));
+  if (Math.abs(Date.now() / 1000 - Number(p.t)) > tolerance) return false;
+  const want = createHmac('sha256', secret).update(`${p.t}.`).update(body).digest('hex');
+  return want.length === p.v1.length && timingSafeEqual(Buffer.from(want), Buffer.from(p.v1));
+}
+```
+
+```php
+function kaasu_verify(string $secret, string $header, string $body, int $tol = 300): bool {
+    parse_str(str_replace(',', '&', $header), $p);
+    if (abs(time() - (int) $p['t']) > $tol) return false;
+    return hash_equals(hash_hmac('sha256', $p['t'] . '.' . $body, $secret), $p['v1']);
+}
+```
+
+The repository's `examples/webhooks/vectors.json` has a known secret, body and header. Every language example is tested against it, so use it to check your own code.
+
+## Respond and retry
+
+Answer with any `2xx` within 10 seconds. Anything else, or a timeout, is retried with growing waits: 10 seconds, 30 seconds, 2 minutes, 10 minutes, 1 hour, 6 hours and 12 hours, eight attempts in all. After the last one the event is **dead-lettered**: it is kept, shown to you as a problem, and can be sent again by hand.
+
+## Where Kaasu will send
+
+- The address must be `https`.
+- It must not be `localhost` or resolve to a private, loopback or link-local address. Kaasu checks the address it actually connects to, so a DNS trick cannot get past the check, and it never follows redirects.
+- The signing secret is stored encrypted.
+
+## Setting it up
+
+The webhook address is the `webhook.url` setting and the secret is stored under `webhook_secret`. A settings screen and a command for these are being connected; until then they are set directly in the database by an administrator. Shop plugins such as [WooCommerce](/docs/connect/woocommerce/) document their own fields.
diff --git a/web/src/content/docs/docs/start/first-payment.md b/web/src/content/docs/docs/start/first-payment.md
index 2e308bd..d873a1e 100644
--- a/web/src/content/docs/docs/start/first-payment.md
+++ b/web/src/content/docs/docs/start/first-payment.md
@@ -1,13 +1,53 @@
 ---
 title: Your first payment
-description: Create an order, share the link and watch it confirm.
+description: Create an order, open its pay page and see how a payment is confirmed.
 sidebar:
   order: 2
 ---
 
-1. Create an order with an amount and an optional note.
-2. Share the pay link or show the QR code.
-3. The customer pays from any UPI app.
-4. Your bank sends an alert. Kaasu checks it, matches it to the order and turns the order green.
+This walk-through uses a ₹1 order so you can test with real money safely.
 
-Every order shows an icon, a colour and a word: **Confirmed**, **Waiting**, **Needs your OK**, **Rejected** or **Expired**. Colour is never the only signal.
+## 1. Create the order
+
+```bash
+curl -s -X POST http://localhost:8080/v1/orders \
+  -H "Authorization: Bearer $KAASU_KEY" \
+  -H "Idempotency-Key: first-test-1" \
+  -H "Content-Type: application/json" \
+  -d '{"amount_paise": 100, "reference": "test-1"}'
+```
+
+The reply has the order `id`, its `state` (`awaiting`) and the **exact** `amount_paise` the customer must pay. It may be a few paise above what you asked for, for example `103`. That small difference is how Kaasu tells two customers apart.
+
+## 2. Open the pay page
+
+Send the customer to `http://localhost:8080/pay/<order id>` (use your public address in real life). The page shows the amount and one button that opens their UPI app with everything filled in. It also shows three waiting steps and never says "failed" while the result is unknown.
+
+## 3. Pay it
+
+Pay from any UPI app, exactly the amount shown.
+
+## 4. See it confirm
+
+Your bank sends an alert. A paired phone or the bank-email watcher forwards it, Kaasu checks the signature, reads the amount, finds the one order with that exact amount and marks it **confirmed**. The pay page switches to the success screen, and your webhook fires if you set one up.
+
+To read the order at any time:
+
+```bash
+curl -s -H "Authorization: Bearer $KAASU_KEY" http://localhost:8080/v1/orders/<order id>
+```
+
+## What each state means
+
+Every order shows an icon, a colour and a word. Colour is never the only signal.
+
+| Word | Meaning |
+|---|---|
+| **Waiting** | The customer has not paid yet. |
+| **Money received** | Confirmed from a verified alert. |
+| **Needs your OK** | Kaasu is unsure. [You decide](/docs/use/needs-your-ok/). |
+| **Expired** or **Rejected** | Closed without payment. |
+
+## Try it without real money
+
+`kaasu sim --list` shows the payment scenarios the simulator knows: an exact match, a one-paisa edit, a late alert, the same payment by SMS and email, a replayed request, a forged sender, an unknown format, a payment that never arrives, a full pool and a refund. Running a scenario against a live server is still being built; the same scenarios run in the automated tests today.
diff --git a/web/src/content/docs/docs/start/how-it-works.md b/web/src/content/docs/docs/start/how-it-works.md
new file mode 100644
index 0000000..c18ec82
--- /dev/null
+++ b/web/src/content/docs/docs/start/how-it-works.md
@@ -0,0 +1,33 @@
+---
+title: How Kaasu works
+description: The whole flow in one page, and what Kaasu will never do.
+sidebar:
+  order: 3
+---
+
+Money moves from your customer's bank straight to yours. Kaasu never touches it. It only **watches for the bank's own message** that the money arrived, and marks the order paid.
+
+## The flow
+
+1. Your shop creates an order through the [API](/docs/reference/api/) (or a plugin does).
+2. Kaasu gives it an **exact amount** in paise that no other open order has. This is the key to matching.
+3. The customer pays that amount with any UPI app.
+4. Your bank sends an alert. A signed device or a verified bank email hands it to Kaasu.
+5. The **matcher** compares the alert with open orders. One order with that exact amount, an authentic source, a plausible time and a UTR: it confirms. Anything less certain goes to you.
+6. Kaasu writes the result to the [ledger](/docs/reference/ledger-and-states/), updates the pay page and sends your [webhook](/docs/reference/webhooks/).
+
+## Rules that are never broken
+
+- Money is a whole number of paise. No floats, anywhere.
+- Only the matcher confirms a payment automatically, and only from a verified alert. Text typed by a customer, a screenshot or an AI answer never confirms anything.
+- An owner can confirm a held payment, with their name written to the ledger, after signing in with a fresh authenticator code.
+- Every state change writes a ledger row in the same database transaction.
+- Customer pages, device alerts and the admin screen are served on separate ports, so a mistake on one cannot open the others.
+
+## What it needs from you
+
+At least one **alert source**: a paired phone, or bank emails that pass verification. Two independent sources are better: the dashboard warns when only one is live. See the [Connect](/docs/connect/android-forwarder/) section.
+
+## Where it stores things
+
+One SQLite file (`kaasu.db`), encrypted secrets inside it, and nothing sent anywhere unless you turn on an optional feature such as [AI help](/docs/use/ai-features/).
diff --git a/web/src/content/docs/docs/start/install.md b/web/src/content/docs/docs/start/install.md
index b0c5e45..7b911bf 100644
--- a/web/src/content/docs/docs/start/install.md
+++ b/web/src/content/docs/docs/start/install.md
@@ -1,28 +1,66 @@
 ---
 title: Install
-description: Run Kaasu on your own machine in a few minutes.
+description: Run Kaasu on your own machine or server, step by step.
 sidebar:
   order: 1
 ---
 
-You need a computer that stays on during shop hours. A small cloud server, a Mac or a Windows PC all work.
+Kaasu is one program with one database file. You need something that stays on during shop hours: a small cloud server, a spare PC or a Mac. Nothing else has to be installed.
 
-## Try it with demo data
+## Choose how to run it
+
+| Way | Best for | Notes |
+|---|---|---|
+| **Installer script** | A Linux server with systemd | Downloads the release, checks its SHA-256, creates a locked-down service. |
+| **Docker or Compose** | Any machine with Docker | Runs as a non-root user with a persistent volume. |
+| **From source** | Trying it, or contributing | Needs Go. `make dev` runs the server. |
+| **Railway** | One-click hosting | Template configuration is in the repository; the public template is not published yet. |
+
+### Linux installer
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/opensawce/kaasu/main/install.sh -o install.sh
+sh install.sh --dry-run      # prints what it would do and changes nothing
+sudo sh install.sh
+```
+
+The script is safe to run again. It downloads the binary for your machine, verifies it against `SHA256SUMS`, creates a `kaasu` user, writes a master key to `/etc/kaasu/master.key` (readable by root only) and starts the `kaasu` service. Check the release signature too: see [Security](/docs/reference/security/).
+
+### Docker
 
 ```bash
-git clone https://github.com/opensawce/kaasu
-cd kaasu && make dev
+git clone https://github.com/opensawce/kaasu && cd kaasu
+mkdir secrets && go run ./cmd/kaasu keygen > secrets/master.key
+sudo chown 65532 secrets/master.key && sudo chmod 0400 secrets/master.key
+docker compose up -d
 ```
 
-Everything runs offline with sample orders. Open the address shown in the terminal.
+The container runs as user 65532, stores data in the `kaasu-data` volume at `/data`, and reads the master key from the Compose secret. The admin listener stays on `127.0.0.1` inside the container; see [Configuration](/docs/reference/configuration/) before exposing anything.
 
-## Send a pretend bank alert
+### From source
 
 ```bash
-kaasu sim exact-match
+git clone https://github.com/opensawce/kaasu && cd kaasu
+export KAASU_MASTER_KEY=$(go run ./cmd/kaasu keygen)
+make dev
 ```
 
-An order turns green. List more scenarios with `kaasu sim --list`.
+## First-time setup
+
+Run these once, as the same user and with the same `KAASU_MASTER_KEY` and `KAASU_DATABASE_PATH` the server uses.
+
+```bash
+kaasu account add --vpa shop@okhdfcbank --bank HDFC --name "Sharma Sweets" --limit-rupees 5000
+kaasu apikey new website          # prints a key once; store it in your shop software
+kaasu admin init --name priya     # prints an authenticator link once; scan it with your authenticator app
+kaasu doctor                      # every line should say OK
+```
+
+`--limit-rupees` is the most Kaasu may confirm on its own for this account. Anything above it, or anything it is unsure about, waits for you. See [Needs your OK](/docs/use/needs-your-ok/).
+
+## Keep the master key safe
+
+The master key encrypts every secret Kaasu stores (API key hashes, the TOTP secrets, the webhook secret). Lose it and those secrets cannot be read; leak it and they can. Keep a copy offline. Rotate it with `kaasu rotate-key`: see [Command line](/docs/reference/cli/).
 
 ## Check the ledger
 
@@ -30,4 +68,4 @@ An order turns green. List more scenarios with `kaasu sim --list`.
 kaasu verify
 ```
 
-A healthy result reads "Ledger intact". Any edit to history makes this check fail.
+A healthy result reads "ledger intact". Any edit to history makes it fail and names the first broken row.
diff --git a/web/src/content/docs/docs/use/ai-features.md b/web/src/content/docs/docs/use/ai-features.md
new file mode 100644
index 0000000..effe573
--- /dev/null
+++ b/web/src/content/docs/docs/use/ai-features.md
@@ -0,0 +1,28 @@
+---
+title: AI help (optional)
+description: What the optional AI features are, what they never do, and how they are limited.
+---
+
+AI is **off by default** and Kaasu works completely without it. Turning it on is your choice, with your own provider key.
+
+## What it can do
+
+| Feature | What it does | What it never does |
+|---|---|---|
+| Unknown alert formats | Reads a bank message no built-in parser knows and proposes the fields. | Confirm a payment. The result goes to review marked as AI-read. |
+| Statement mapping | Suggests which column is date, credit, debit and UTR in a statement. | Import anything. The suggestion is checked against every row first. |
+| Ask your shop | Picks one of four fixed read-only questions (totals, order counts, refunds, held payments) and shows the numbers it used. | Run free-form queries, or write anything. |
+| Hints and summaries | Writes plain-language hints and review summaries from facts Kaasu already computed. | Decide, approve or change an order. |
+
+## The guard rails
+
+- **No tools.** The model cannot call functions or touch your data. It receives masked text and returns one structured answer.
+- **Masked first.** Account numbers, UPI addresses, email addresses and UTRs are replaced before any text leaves your machine. If something still looks unmasked, the call is refused.
+- **Checked output.** The answer must match a strict schema, with no extra fields and no trailing text, or it is discarded.
+- **Never authentic.** An AI-read alert can never be the source of an automatic confirmation.
+- **Budget.** A monthly cap in rupees (on the India calendar month) stops calls when reached. A cap of 0 means no calls.
+- **Consent and record.** You must acknowledge the data notice before use, each feature has its own switch, and every answer is logged with provider and model, without the text.
+
+## Status
+
+The provider layer and each feature are implemented and tested with a stub provider. Choosing a real provider and entering a key from a settings screen is not available yet, so nothing is sent to any AI service today.
diff --git a/web/src/content/docs/docs/use/backup-and-keys.md b/web/src/content/docs/docs/use/backup-and-keys.md
new file mode 100644
index 0000000..8bfd88d
--- /dev/null
+++ b/web/src/content/docs/docs/use/backup-and-keys.md
@@ -0,0 +1,30 @@
+---
+title: Backups and keys
+description: What to back up, how to rotate the master key, and how to check history.
+---
+
+## What to back up
+
+Everything Kaasu knows is in one SQLite file (`kaasu.db`, set by `KAASU_DATABASE_PATH`) next to its `-wal` and `-shm` files, plus your **master key**. Without the key the secrets inside the file cannot be read.
+
+- Copy the database only while Kaasu is stopped, or use SQLite's own online backup (`sqlite3 kaasu.db ".backup backup.db"`).
+- Keep the master key somewhere else, offline. Never store it next to the backup.
+- Automatic encrypted backups with a weekly restore test are planned; `kaasu backup` is a placeholder today.
+
+## Rotating the master key
+
+```bash
+export KAASU_NEW_MASTER_KEY=$(kaasu keygen)
+kaasu rotate-key
+```
+
+Every stored secret is re-wrapped under the new key in one transaction: if any fails, nothing changes. After it succeeds, point `KAASU_MASTER_KEY` at the new key and restart.
+
+## Check the ledger
+
+`kaasu verify` walks the chained history and tells you the first row that does not match. Run it after a restore and now and then.
+
+## Revoking things
+
+- API keys are stored as hashes and cannot be shown again. Make a new one with `kaasu apikey new <label>` and stop using the old one.
+- A lost phone: device revocation is built (a revoked device's next request is refused immediately), but there is no command or screen for it yet. Until there is, stop the service and ask in the issue tracker for the manual steps rather than editing the database yourself.
diff --git a/web/src/content/docs/docs/use/dashboard.md b/web/src/content/docs/docs/use/dashboard.md
new file mode 100644
index 0000000..d65c12c
--- /dev/null
+++ b/web/src/content/docs/docs/use/dashboard.md
@@ -0,0 +1,31 @@
+---
+title: The dashboard
+description: Sign in, see today's money and check that your alert sources are alive.
+---
+
+The dashboard is served on the **admin** port, which listens on your own machine by default (`127.0.0.1:9000`). Reach it from a VPN or SSH tunnel; never put it on a public address.
+
+## Sign in
+
+You sign in with your name and a 6-digit code from an authenticator app. Create the account once with `kaasu admin init --name <name>` and scan the link it prints. The code works once, so a code someone saw cannot be replayed.
+
+- Five wrong codes lock the account for five minutes. An unknown name and a wrong code give the same reply.
+- A session lasts up to 12 hours and ends after 30 idle minutes. The session cookie is stored hashed on the server.
+- Decisions that move money (approving a held payment) ask for a fresh code if you signed in more than five minutes ago.
+- Two roles: **owner** can decide payments; **staff** can look but not change.
+
+## Today
+
+Shows money received today (India time), the number of payments, and a list of your alert sources with a health word. A phone not heard from in 15 minutes shows **Phone offline**. With fewer than two live sources the page warns you, because one source is a single point of failure. With none, it says nothing is being seen.
+
+## Orders
+
+The 50 most recent orders with their status word and the masked payer (for example `ra***@okicici`). A full payer address is never shown here.
+
+## Monitoring
+
+`/metrics` on the admin port serves Prometheus metrics. Logs are JSON lines with request ids, and account numbers, UTRs and payer addresses are masked before they are written. See [Operations](/docs/reference/operations/).
+
+## Coming to the dashboard
+
+A review-queue screen, device pairing and revocation, settings (webhook address, accounts) and a first-run setup wizard with the ₹1 test payment are built as parts of the engine and are being connected to screens. Until then use the command line: [Command line](/docs/reference/cli/).
diff --git a/web/src/content/docs/docs/use/languages-and-voice.md b/web/src/content/docs/docs/use/languages-and-voice.md
new file mode 100644
index 0000000..191ede6
--- /dev/null
+++ b/web/src/content/docs/docs/use/languages-and-voice.md
@@ -0,0 +1,22 @@
+---
+title: Languages and voice
+description: Eleven languages, Indian number formats and spoken confirmations.
+---
+
+## Languages
+
+Customer pages and merchant screens speak English and ten Indian languages: Hindi, Bengali, Gujarati, Kannada, Malayalam, Marathi, Odia, Punjabi, Tamil and Telugu.
+
+- The pay page picks a language from `?lang=`, then a saved choice, then the browser, then your shop's default.
+- Amounts use Indian grouping: ₹1,25,000.50. UPI ids, UTRs and order ids always stay in Latin letters.
+- Every string lives in one catalogue file per language. Hindi and Tamil are machine drafts; the rest still show English for many strings. **None has had a native-speaker review yet**, and `i18n/REVIEW.md` lists what needs one. If you read one of these languages, a review is the most useful help you can give.
+
+## Spoken confirmations
+
+The engine can read out "₹499 received" when a payment is confirmed, in your chosen voice language (separate from the screen language) using the device's own text-to-speech.
+
+- It speaks **only** for confirmed or late-paid payments, never for held or unconfirmed ones.
+- Each order is announced once, even after a reconnect.
+- Whole rupees are read as rupees; paise are added only when there are some.
+
+Voice is wired into the merchant apps as they are built.
diff --git a/web/src/content/docs/docs/use/needs-your-ok.md b/web/src/content/docs/docs/use/needs-your-ok.md
index 78f7dc1..05cce45 100644
--- a/web/src/content/docs/docs/use/needs-your-ok.md
+++ b/web/src/content/docs/docs/use/needs-your-ok.md
@@ -1,8 +1,47 @@
 ---
 title: Needs your OK
-description: What to do when Kaasu is not sure.
+description: Why Kaasu holds some payments for you, and how to decide them.
 ---
 
-When an alert nearly matches an order, Kaasu does not guess. The order moves to **Needs your OK** and shows the evidence: amount, time and masked payer.
+Kaasu confirms a payment on its own only when everything lines up. Otherwise it **holds the order and asks you**. A wrong "paid" would cost you goods, so it prefers to ask.
 
-Approve it if it is right, reject it if it is not. Either choice is written to the ledger.
+## How it decides
+
+Kaasu scores each alert against the order it matches. The points are fixed and public:
+
+| Signal | Points |
+|---|---|
+| The amount is exactly the order's amount | 40 |
+| The alert came from an authentic source (a signed device, or verified bank email) | 20 |
+| The alert carries a UTR (the bank's transaction number) | 10 |
+| The alert text echoes your order reference | 10 |
+| The time fits the order's window | 10 |
+| The payer has paid before | 5 |
+| Two independent sources reported it | 5 |
+
+It confirms automatically only if the amount is exact, the source is authentic, the score is at least 80 **and** the amount is under that account's auto-confirm limit. A limit of 0 means every payment waits for you.
+
+## Why an order is held
+
+| Reason | What happened |
+|---|---|
+| `amount_mismatch` | The customer paid a little more or less than asked. |
+| `late` | The money arrived after the order expired. |
+| `order_closed` | The order was cancelled or rejected before the money arrived. |
+| `ambiguous` | Two open orders could both fit the alert. |
+| `unauthentic` | The alert was not from a signed device or verified email. |
+| `low_score` | Not enough signals agreed. |
+| `over_limit` | The amount is above the account's auto-confirm limit. |
+
+## Deciding
+
+Held orders show **Needs your OK** with the evidence: the amount expected next to what the bank said, the score, the reason and the masked payer. The raw alert text is shown escaped, never as live HTML.
+
+- **Approve.** The order becomes confirmed, or late-paid if its window had passed.
+- **Reject.** Choose one reason: not received, wrong amount, duplicate, suspected fraud, or other.
+
+Only the **owner** can decide, and only with a fresh sign-in (an authenticator code within the last five minutes). Staff accounts are read-only. Every decision writes the owner's name to the ledger. Deciding twice, or an order with no held alert, is refused instead of changing anything.
+
+## Why this is safe
+
+A person approving a held payment is the one place a human, not the matcher, confirms. It needs the owner role, a valid form token and a fresh code, and it is recorded. See [Security](/docs/reference/security/).
diff --git a/web/src/content/docs/docs/use/orders-and-links.md b/web/src/content/docs/docs/use/orders-and-links.md
index b350b77..f0bacca 100644
--- a/web/src/content/docs/docs/use/orders-and-links.md
+++ b/web/src/content/docs/docs/use/orders-and-links.md
@@ -1,8 +1,37 @@
 ---
 title: Orders and pay links
-description: How orders get exact amounts and how links work.
+description: How orders get exact amounts, how long they last, and how customers pay.
 ---
 
-Each order is given a unique amount in paise so a payment can be matched to it. Amounts are always whole paise; Kaasu never uses decimals for money.
+## An order in one minute
 
-Pay links use the standard UPI fields only: payee address, name, amount, currency and note.
+An order has an amount, an optional reference and note, an expiry and a state. You create it through the [API](/docs/reference/api/) or a shop plugin. The customer pays from the **pay page** at `/pay/<order id>`.
+
+## Why the amount changes by a few paise
+
+Two customers may owe ₹499 at the same time. If both paid exactly ₹499, Kaasu could not tell whose money arrived. So each open order on an account gets its own amount: ₹499.00, ₹499.01, ₹499.02 and so on, up to 99 paise above the price.
+
+- A customer sees the exact amount and pays it. They may notice the extra paise; the pay page shows it clearly and the UPI link carries it.
+- When the customer pays a different amount, Kaasu does not guess. It goes to [Needs your OK](/docs/use/needs-your-ok/).
+- Amounts are whole paise everywhere. Decimals are never used for money.
+
+## Slots, expiry and the queue
+
+- An open order **holds its amount** until it expires plus a 10 minute grace period. A cancelled or expired order keeps its amount through that grace, so a late payment cannot be mistaken for someone else's.
+- By default an order lasts 15 minutes. You can set 1 minute up to 24 hours.
+- If all 100 amounts for a price are taken, a new order is **queued**. It has no pay link yet. When an amount frees up, the oldest queued order is promoted and its expiry window starts fresh from that moment.
+- Queued orders on other prices are not blocked by a full price.
+
+## Cancelling
+
+You can cancel an order that has not been paid. A paid, expired or already cancelled order cannot be cancelled.
+
+## Pay links
+
+The pay link is a standard UPI link that opens the customer's app with your UPI ID, your name, the exact amount, INR and your note. For personal UPI IDs it uses only those fields (`pa`, `pn`, `am`, `cu`, `tn`). It never includes merchant codes or signatures.
+
+Reusable **payment links** and a printable **counter QR** for walk-in customers are built in the engine and are being wired to web routes; until then, create orders through the API and show the pay page.
+
+## After payment
+
+The pay page polls its status every two seconds and switches to a success screen for a confirmed or late-paid order. The success screen shows the amount from the order (never from the address bar), the time, your reference, the UTR and a six-character check code. `/pay/<id>/receipt` gives a printable receipt.
diff --git a/web/src/content/docs/docs/use/reconciliation.md b/web/src/content/docs/docs/use/reconciliation.md
index 5e18044..c5d8406 100644
--- a/web/src/content/docs/docs/use/reconciliation.md
+++ b/web/src/content/docs/docs/use/reconciliation.md
@@ -1,6 +1,32 @@
 ---
 title: Reconciliation
-description: Compare Kaasu against your bank statement.
+description: Prove each confirmed payment against your bank statement.
 ---
 
-At the end of the day, compare confirmed orders with your bank statement. Differences are listed so you can fix them or mark them as reviewed.
+Reconciliation compares what Kaasu confirmed with what your bank says it received. It is read-only: it never changes an order by itself.
+
+> **Status:** the import and matching engine is built and tested; the screen and command to run it are still being connected.
+
+## Import a statement
+
+Export a CSV statement from your bank and import it for **one receiving account**. A statement belongs to an account and only checks that account's orders.
+
+- Known layouts exist for common banks, plus a generic layout (`date`, `description`, `credit`, `debit`, `utr`).
+- Files up to 10 MB and 100,000 rows. A row with missing columns is an error with its row number, never a crash.
+- Importing the same file twice stores it once.
+- Amounts are read as integer paise.
+
+## What you get
+
+Each confirmed order in the period lands in one bucket:
+
+- **Matched**: a statement credit with the same UTR (or, if the order has no UTR, the same exact amount) was found.
+- **Confirmed but missing**: Kaasu confirmed it but the bank shows no such credit. These deserve a look, and you can move them to **disputed**.
+- **Amount mismatch**: a credit with the order's UTR exists but for a different amount.
+- **Credited but unmatched**: the bank shows money Kaasu has no order for.
+
+Matching by UTR happens first, so an amount match can never steal a credit that belongs to another order's UTR. An order that has a UTR only falls back to a credit that carries no UTR.
+
+## With AI
+
+An optional helper can propose the column layout for a statement Kaasu does not know. Its answer is always checked against every row of the file before anything is imported. See [AI help](/docs/use/ai-features/).
diff --git a/web/src/content/docs/docs/use/refunds.md b/web/src/content/docs/docs/use/refunds.md
index 77aa81d..b8fe3f3 100644
--- a/web/src/content/docs/docs/use/refunds.md
+++ b/web/src/content/docs/docs/use/refunds.md
@@ -3,4 +3,18 @@ title: Refunds
 description: Record a refund against an order.
 ---
 
-Kaasu does not send money back. Refund from your bank app, then record it on the order so the ledger and your reports stay correct. The order moves to `order.refunded`.
+Kaasu does not send money back. Refund from your bank app, then record it so your books and the ledger stay right.
+
+> **Status:** the refund log is built and tested; recording one from a screen or command is still being connected.
+
+## Rules
+
+- A refund can be recorded only against a **confirmed** or **late-paid** order.
+- The total refunded can never be more than the amount paid. This is checked inside the same database transaction that writes the refund, so two people recording refunds at once cannot overshoot.
+- Each refund can carry the bank's UTR for the money you sent back. A UTR can be recorded once.
+- A **partial** refund leaves the order in its current state. The refund that brings the total to the full amount moves the order to **refunded**, which sends an `order.refunded` [webhook](/docs/reference/webhooks/).
+- Every refund is written to the ledger.
+
+## Shop plugins
+
+A refund in WooCommerce or Shopify does not move money and does not tell Kaasu. Do both: refund in the bank app, then record it in Kaasu.