From c2b714f28574399f3c340a1b0522240787029554 Mon Sep 17 00:00:00 2001 From: araharah-executor Date: Sun, 25 Oct 2026 13:10:52 +0800 Subject: [PATCH] docs: README logo 560px + quickstart/future sections; new CORE-CONCEPTS doc; wiki synced --- .planning/tmp/arah2.wiki | 2 +- README.md | 80 +++++++++++++++++++++++++++++++++++++++- docs/CORE-CONCEPTS.md | 65 ++++++++++++++++++++++++++++++++ 3 files changed, 145 insertions(+), 2 deletions(-) create mode 100644 docs/CORE-CONCEPTS.md diff --git a/.planning/tmp/arah2.wiki b/.planning/tmp/arah2.wiki index 848a140..d8011e3 160000 --- a/.planning/tmp/arah2.wiki +++ b/.planning/tmp/arah2.wiki @@ -1 +1 @@ -Subproject commit 848a140b328e60c4e6ac7c863b63aaff928480af +Subproject commit d8011e3d732aac677128421ce19b6a81d584d6b8 diff --git a/README.md b/README.md index 4117d8b..0f3258d 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@

- arah² logo + arah² logo

# 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 +cd arah2 && npm install +cp bot/.dev.vars.example bot/.dev.vars +``` + +**3. Fill `bot/.dev.vars`** (gitignored — never commit): + +``` +BOT_TOKEN= +WEBHOOK_SECRET= +WEBHOOK_URL=https://.workers.dev +MINI_APP_URL=https://.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 diff --git a/docs/CORE-CONCEPTS.md b/docs/CORE-CONCEPTS.md new file mode 100644 index 0000000..84c698a --- /dev/null +++ b/docs/CORE-CONCEPTS.md @@ -0,0 +1,65 @@ + + +# Core Concepts + +The seven ideas that explain everything arah² does. Read this before any other doc — the rest of `docs/` assumes these. + +--- + +## 1. The privacy law: nothing persists + +**arah² stores nothing that identifies you beyond what you explicitly send it.** The concrete rules, enforced by tooling rather than promises: + +| Surface | Law | Enforcement | +|---|---|---| +| KV storage | **TTL-only** — every write carries an expiry; three families: sessions 900s · location pins 300s · guidance envelopes 7200s | `kv-ttl` gate + live `--live` probe (lists keys, asserts expiry) | +| Coordinates | Live in the Mini App's **memory only**; a route snapshot lives only inside its 7200s TTL envelope, gone at expiry or trip end | `storage-api` gate (repo-wide grep) + the no-storage test suites | +| Logs | **Category-only** — log lines name a surface and a rejection class, never coordinates, ids, tokens, or payload | `log-vocabulary` gate (schema-scans every `console.log`) | +| Telemetry | **Zero** — no analytics, no beacons, nothing to opt into; the only runtime fetches are OpenFreeMap tiles, the Telegram API, and the app's own endpoints | `bundle-telemetry` + `runtime-hosts` gates (printed host inventories) | + +The identity floor: you authenticate with Telegram's own **`initData`** — HMAC-validated server-side against the bot token, 900-second freshness, exchanged once for an opaque random session token held in the Mini App's memory. No profile is ever built. + +--- + +## 2. Backend ladders: interfaces, not products + +Every "engine" is an **interface with a documented escalation ladder** — so no capability ever wedges to a single implementation: + +- **`SearchSource`** — gazetteer #1 (curated KL, in-Worker) → WASM geocoder #2 (OSS track) → Photon #3 (documented). +- **`RoutingSource`** — fixtures #1 (golden KL pairs) → **engine A #2** (live: CSR road graph in R2, typed-array A\* in the Worker) → fully client-side router #3 (the static-hosted endgame) → Valhalla #4 (documented). + +Each rung answers the same contract; failures resolve **honestly** (`null` → a designed "router pending" surface — never a blank map, never a fake route). + +--- + +## 3. The $0 law + +Every service is on a free tier, enforced by measurement: `npm run budget-audit` compares real numbers (Worker CPU, KV ops/day, bundle bytes, subrequests) against the free ceilings, and **prints violations honestly**. The known negotiated class: short KL reroutes run 2–8ms in-budget; cross-metro routes degrade to the router-pending state until the ALT-landmarks rung lands. The cron is tuned inside the KV list-op ceiling (2-minute ticks ⇒ 720/day < 1,000). + +--- + +## 4. The bot is the transport; the Mini App is the product + +Search happens **in chat** (`/cari KLCC` → a native venue card with alternates). Choosing opens the Mini App **preloaded** (`?dest=` / `start_param` — the two carriers). Inside: location chain (Telegram LocationManager → WebView geolocation → chat-pin fallback), Rams-styled map, route, then turn-by-turn guidance. When minimized, the **cron pushes schematic turn-cards** to chat (glyph + street + ETA — best-effort projection, zero KV writes per tick). Re-opening resumes at the progressed position. + +--- + +## 5. Honest failure as the design language + +Every dead end is a **designed surface**: denied location (with a settings deep-link), signal lost, router pending, destination unavailable, abandon-route confirm, "trip ended, data deleted". No blank screens — the FM1–FM7 matrix pins all seven failure classes with captures. + +--- + +## 6. Design system binding + +`theme/` is the single source of truth (Telemetry Rams: zero radius, 8px grid, Space Grotesk/Geist, the 60/30/10 color law where **signal-orange is the route accent**). The Mini App consumes tokens as a build-time dependency; the map stays **Rams-constant** while the shell re-slots to Telegram's light/dark theme. `npm run audit` greps for invented values. + +--- + +## 7. Forkability is the license + +GPL-3.0 (code) + ODbL (data). One command deploys to *your* Cloudflare with *your* bot; the audit tools are yours too — run `npm run privacy-audit` before your first driver. Secrets live only in gitignored `.dev.vars`; no hard-coded identity anywhere. + +--- + +*Concepts verified against the live codebase (2025-10-25); see docs/ARCHITECTURE.md for the module map and docs/API.md for the endpoint laws.*