docs: README logo 560px + quickstart/future sections; new CORE-CONCEPTS doc; wiki synced

README.md

@@ -1,7 +1,7 @@
 <!-- generated-by: gsd-doc-writer -->
 
 <p align="center">
-  <img src="assets/MASTER_FILE-arah2_logo.svg" alt="arah² logo" width="280">
+  <img src="assets/MASTER_FILE-arah2_logo.svg" alt="arah² logo" width="560">
 </p>
 
 # arah²
@@ -109,6 +109,84 @@ cp bot/.dev.vars.example bot/.dev.vars
 
 ---
 
+## Quickstart: clone → production (your own bot, your own Cloudflare)
+
+The concise path. Full detail lives in [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md); local development in [docs/GETTING-STARTED.md](docs/GETTING-STARTED.md).
+
+**1. Create the bot** — in Telegram, open [@BotFather](https://t.me/BotFather):
+- `/newbot` → pick a name + username → copy the **bot token**
+- `/setuserpic` → upload `assets/logo_arah2.png` (the bot's avatar)
+- Bot Settings → **Main Mini App** → set your future production URL (you'll fill the real one in step 4; BotFather's app *name* is what Telegram shows in the mini-app header)
+
+**2. Clone + install**
+
+```bash
+git clone <your fork>
+cd arah2 && npm install
+cp bot/.dev.vars.example bot/.dev.vars
+```
+
+**3. Fill `bot/.dev.vars`** (gitignored — never commit):
+
+```
+BOT_TOKEN=<token from step 1>
+WEBHOOK_SECRET=<any long random string — you choose it>
+WEBHOOK_URL=https://<your-worker>.workers.dev
+MINI_APP_URL=https://<your-worker>.workers.dev
+```
+
+**4. Deploy to YOUR Cloudflare** (free plan — `$0`):
+
+```bash
+npx wrangler login          # browser auth, once
+npm run build               # theme tokens → web/dist
+npm run deploy              # theme → web → worker + assets + webhook + commands
+```
+
+**5. Provision the road graph** (engine A's routing data — R2, also free):
+
+```bash
+npx wrangler r2 bucket create araharah-graphs
+node routing/scripts/upload-road-graph.mjs   # builds + uploads the KL graph, round-trip verifies
+```
+
+**6. Register the bot surfaces** (usually already done by `npm run deploy`, re-run to be sure):
+
+```bash
+node bot/scripts/set-webhook.mjs          # arms the webhook (+ /telegram/webhook path)
+node bot/scripts/register-commands.mjs    # /help /privacy /cari in every command scope
+node bot/scripts/set-menu-button.mjs      # the menu button opens the app ("arah²")
+```
+
+**7. Verify** — the canaries (read-backs, nothing trusted blindly):
+
+```bash
+npm run privacy-audit -- --live && npm run budget-audit -- --live
+```
+Then in Telegram: restart the client → open the bot → `/cari KLCC` → venue card → **OPEN** → the map routes. Done: your own private navigator, $0/month.
+
+> **Permission notes:** the Cloudflare token (optional, only for the audit `--live` probes) needs Account → Workers KV Storage → **Read** only. The bot itself needs no special Telegram permissions; `/setprivacy` default (off) is correct — the bot never reads non-command messages.
+
+---
+
+## Future enhancements & milestones
+
+**v1.x (next milestone):**
+- **ALT landmark preprocessing** — routing backend v2: fixes the cross-metro CPU class while staying $0 (measured decision: short KL reroutes are in-budget today)
+- **WASM-router track** — fully client-side routing in the webview (origin+destination never touch a server; static-hosted; the fork-perfect endgame)
+- **Battery measurement** — the <10%/hr guidance-drain record (deferred from launch)
+- **Bitmap map snapshots** in minimized chat turn-cards (needs a rasterizer in the $0 stack)
+- **Voice guidance** · **live trip share** (`sendLocation(live_period)`) · **toll toggle** · **speed-limit display** — the REQUIREMENTS deferred table
+
+**v2 (post user-validation):**
+- Incident reports + community layer, gamification, traffic-weighted ETAs — per the original vision doc ([IDEAS.md](IDEAS.md))
+
+**Core concepts** (the privacy law, backend ladders, session flow) are documented in [docs/CORE-CONCEPTS.md](docs/CORE-CONCEPTS.md).
+
+---
+
+---
+
 ## Usage
 
 ### Talking to the bot