From 91ad0c9d9325c2120438bd91cf2c084c55329303 Mon Sep 17 00:00:00 2001 From: araharah-executor Date: Fri, 23 Oct 2026 20:56:40 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20generate=20+=20verify=20project=20docum?= =?UTF-8?q?entation=20=E2=80=94=20canonical=20docs,=20per-package=20README?= =?UTF-8?q?s,=20verified=20fix=20pass?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - New: docs/ARCHITECTURE.md, docs/GETTING-STARTED.md, docs/DEVELOPMENT.md, docs/TESTING.md, docs/CONFIGURATION.md (colored mermaid diagrams, quoted labels) - Regenerated README.md (arah² / arah2bot naming, canonical clone URL) - New per-package READMEs: theme/, bot/, web/ - Verified 13 docs against the live codebase (2 fix iterations + 2 residual corrections); corrected 56 stale claims across AGENTS/DESIGN/IDEAS/GSD_FIX --- .planning/ROADMAP.md | 42 +++++++++++++++++++++++++------- AGENTS.md | 53 ++++++++++++++++++++++------------------- DESIGN.md | 14 +++++------ GSD_FIX.md | 13 +++++----- IDEAS.md | 22 ++++++++--------- README.md | 2 +- bot/README.md | 4 ++-- docs/ARCHITECTURE.md | 10 ++++---- docs/CONFIGURATION.md | 4 ++-- docs/GETTING-STARTED.md | 2 +- docs/TESTING.md | 4 ++-- web/README.md | 3 ++- 12 files changed, 103 insertions(+), 70 deletions(-) diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md index df01aa1..2f104fc 100644 --- a/.planning/ROADMAP.md +++ b/.planning/ROADMAP.md @@ -23,7 +23,7 @@ Decimal phases appear between their surrounding integers in numeric order. - [ ] **Phase 1: Design Tokens + Rams Foundation** - Distill the Telemetry Rams system into a single token package and Rams-styled map basemap, with a mockup-vs-implementation approval artifact — before any screen is built - [ ] **Phase 2: Bot Skeleton + initData Security** - grammY bot on one Cloudflare Worker: /start, command menu, /privacy, and HMAC-validated identity with TTL-only KV storage -- [ ] **Phase 3: Mini App Shell + Geolocation** - Telegram WebApp shell that boots, authenticates, and reads a reliable live location across the Android/iOS/Desktop client matrix +- [x] **Phase 3: Mini App Shell + Geolocation** - Telegram WebApp shell that boots, authenticates, and reads a reliable live location across the Android/iOS/Desktop client matrix (completed 2026-10-23) - [ ] **Phase 4: Destination Search + KL Gazetteer** - Free-text KL search that resolves landmarks despite Malay abbreviations and typos, venue cards, and Mini App launch with destination preloaded - [ ] **Phase 5: Routing + Route Display** - Valhalla-backed route calculation shown as a Rams route line with quiet alternative cards; the full search→route→render loop lands - [ ] **Phase 6: Turn-by-Turn Guidance (Live Driving)** - Client guidance state machine: maneuver banner, missed-turn auto-recalculation, honest ETA, haptics, seamless resume, and backgrounded chat turn-cards @@ -43,10 +43,10 @@ Decimal phases appear between their surrounding integers in numeric order. **Plans**: 4 plans Plans: -- [ ] 01-01-PLAN.md — Repo hygiene + Tailwind v4 token package (`theme/`) + self-hosted fonts + DESIGN.md supersession (D-01/02/04/05/06/07/16) -- [ ] 01-02-PLAN.md — Component sheet: `theme/src/components.css` + `sheet.html` consuming tokens only (D-03/D-11) -- [ ] 01-03-PLAN.md — Rams basemap: token-derived OpenFreeMap liberty fork + KL preview (D-08/09/10) -- [ ] 01-04-PLAN.md — Off-token audit (D-13) + Playwright captures (D-14) + DSGN-02 approval gallery (D-12), blocking user checkpoint +- [x] 01-01-PLAN.md — Repo hygiene + Tailwind v4 token package (`theme/`) + self-hosted fonts + DESIGN.md supersession (D-01/02/04/05/06/07/16) +- [x] 01-02-PLAN.md — Component sheet: `theme/src/components.css` + `sheet.html` consuming tokens only (D-03/D-11) +- [x] 01-03-PLAN.md — Rams basemap: token-derived OpenFreeMap liberty fork + KL preview (D-08/09/10) +- [x] 01-04-PLAN.md — Off-token audit (D-13) + Playwright captures (D-14) + DSGN-02 approval gallery (D-12), blocking user checkpoint Notes: - Repo hygiene lands here first: scrub `*:Zone.Identifier` artifacts, `.gitignore` for OS junk/`node_modules`/secrets (pre-dates any credential handling). @@ -63,7 +63,12 @@ Notes: 2. /privacy gives an honest, visible statement of what araharah stores and does not store (PRIV-01) — the in-app "trip ended, data deleted" messaging half completes with guidance in Phase 6, riding this requirement's message design 3. Tampered, stale, and replayed initData payloads are rejected with CI test vectors and known-good HMAC cases passing; only validated identities receive a one-time session token (security gate — the phase's exit criterion) 4. A storage spot-check shows KV with TTL-only namespaces and zero persistent coordinates or user profiles — privacy by construction holds from the first line of backend code (PRIV-02; re-audited in Phase 7) -**Plans**: TBD +**Plans**: 3 plans + +Plans: +- [x] 02-01-PLAN.md — bot workspace scaffold + Wave-0 test harness (RED initdata suite) +- [x] 02-02-PLAN.md — initData HMAC validator (rejection classes) + TTL-only KV sessions (GREEN) +- [x] 02-03-PLAN.md — command surface (en/ms, aliases) + Worker wiring (/telegram/webhook, /api/session) + deploy checkpoint Notes: - One Cloudflare Worker deployable (static assets + webhook + `/api/*`); KV `chat_sessions` (minutes TTL) is the first namespace; the `guidance_sessions` (~2h TTL) envelope is only designed with its consumer in Phase 5. @@ -80,11 +85,32 @@ Notes: 3. Location denial shows a deliberate denied state (never a blank map), and the app renders correctly under Telegram light and dark themes while the map keeps Rams cartography constant (PX-02, platform themes) 4. No coordinate written anywhere persists: storage remains TTL-ephemeral only, spot-checkable at phase exit (GEO-03) 5. Device-matrix exit pass: Android + iOS + Desktop + plain browser each demonstrate boot → session → position, exercising the full fallback chain (pitfall research device-matrix criterion) -**Plans**: TBD +**Plans**: 4 plans + +Plans: + +**Wave 1** (baseline): +- [x] 03-01-PLAN.md — `web/` workspace + Wave-0 test runner; TTL-only location-pin KV, GEO-02 chat keyboard handler, and the `GET /api/location` relay route + +**Wave 2** *(blocked on Wave 1 completion)*: +- [x] 03-02-PLAN.md — Location chain: three source adapters normalizing to one `Fix`, the D-04 state machine with freshness as a separate axis, memory-only session store, Telegram platform wrappers, Mock-Telegram harness, and the GEO-01/02/03 + PX-02 gates + +**Wave 3** *(blocked on Wave 2 completion)*: +- [x] 03-03-PLAN.md — Rams shell: UI-SPEC copy module, token-only stylesheet, MapLibre v6 bootstrap with the WebGL2 gate, marker/follow/recenter, status strip and state cards, and the map-first boot choreography + +**Wave 4** *(blocked on Wave 3 completion)*: +- [x] 03-04-PLAN.md — Worker `[assets]` binding + one-command deploy + D-14 build-artifact gate; Playwright capture harness with the GEO-03 runtime probe; blocking device-matrix exit gate + +Cross-cutting constraints (truths appearing in 2+ plans, binding at every wave): +- denied/blank is forbidden — every dependency-failure state renders a deliberate Rams surface (03-02, 03-03, 03-04) +- zero coordinate persistence — TTL-ephemeral KV only; grep gate + runtime probe (03-01, 03-02, 03-03, 03-04) +- Rams token-only styling — Telemetry Rams tokens binding over skill defaults (03-02, 03-03, 03-04) Notes: - Highest platform-integration uncertainty in the project — research recommends `/gsd-research-phase` (Android LocationManager stale-fix workaround, `getLiveData()` wrapper, WebView permission bridges, browser testing harness). - BackButton wiring and safe-area groundwork are built here as shell infrastructure; the observable PX-01/PX-03 behaviors are claimed by Phase 6 where the full state graph exists. +- Research findings that shaped the plan: `getLiveData()` does not exist (D-05's gated streaming is our own `Fix`-shaped abstraction with a pluggable cadence — Phase 6 picks poll vs `watchPosition`); the Android stale-fix inverts the naive D-04 chain reading, so freshness is a separate axis from availability; Desktop Telegram has no geolocation at all (issue #77), making the chat-keyboard path the only Desktop origin; `GET /api/location` is required scope; MapLibre v6 is ESM-only and WebGL2-only (the map-less shell state is a deliberate `--color-surface-dim` field, not a crash); Bot API 10.2's origin restriction is enforced as of 2026-07-20. +- 03-04 task 3 is a **blocking human checkpoint**: real Android, iOS, and Telegram Desktop are listed in RESEARCH as required with no fallback. If no device is available, Success Criterion 5 is recorded UNVERIFIED and the phase is held open rather than silently closed. **UI hint**: yes ### Phase 4: Destination Search + KL Gazetteer @@ -178,7 +204,7 @@ Phases execute in numeric order: 1 → 2 → 3 → 4 → 5 → 6 → 7 |-------|----------------|--------|-----------| | 1. Design Tokens + Rams Foundation | 0/TBD | Not started | - | | 2. Bot Skeleton + initData Security | 0/TBD | Not started | - | -| 3. Mini App Shell + Geolocation | 0/TBD | Not started | - | +| 3. Mini App Shell + Geolocation | 0/4 | Ready to execute | - | | 4. Destination Search + KL Gazetteer | 0/TBD | Not started | - | | 5. Routing + Route Display | 0/TBD | Not started | - | | 6. Turn-by-Turn Guidance (Live Driving) | 0/TBD | Not started | - | diff --git a/AGENTS.md b/AGENTS.md index f2913dc..693d1c4 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -7,12 +7,14 @@ A privacy-respecting GPS navigation app delivered through Telegram: a waze-like route navigator, but Telegram-first instead of an app store install, built on OpenStreetMap data, and designed to Dieter Rams' principle of "less, but better". Users search a destination (e.g. "KLCC") with the bot, tap into a Telegram Mini -App (webview hosted on Cloudflare Pages), and receive live route guidance while +App (webview served as Cloudflare Workers static assets (Workers superseded Pages — see bot/wrangler.jsonc)), and receive live route guidance while driving. First users are in the Kuala Lumpur metro area. Reference design docs: `DESIGN.md` (design philosophy), `IDEAS.md` (vision + stack), `stitch_minimalist_route_navigator/` (4 UI mockup screens), and -`.planning/codebase/` (codebase map; current state is design-only, no app code). +`.planning/codebase/` (codebase map; the repo has substantial app code: `bot/` +(grammY TypeScript worker), `web/` (Vite MapLibre Mini App), `theme/` (Tailwind v4 +token package)). **Core Value:** A user finds a local destination via Telegram and gets there with reliable turn-by-turn guidance — tracked by nothing beyond what they explicitly opted in @@ -40,20 +42,20 @@ to. ## Project Maturity - Concept and design-system documents: `DESIGN.md`, `IDEAS.md` - A design-system extension: `stitch_minimalist_route_navigator/telemetry_rams/DESIGN.md` (frontmatter-structured design tokens for colors, typography, spacing) -- Static HTML UI mockup screens (one `code.html` + `screen.png` per screen) — these are the **only executable code** in the repo -- Planning outputs: `.planning/` (not product code) +- Static HTML UI mockup screens (one `code.html` + `screen.png` per screen) — legacy design reference; the executable code is the `bot/`, `web/`, and `theme/` workspaces +- Planning outputs: `.planning/` — not product code; it holds phase plans for the code that now exists ## Languages -- HTML 5 — the four mockup screens: `stitch_minimalist_route_navigator/active_route_guidance/code.html`, `stitch_minimalist_route_navigator/navigate_map_overview/code.html`, `stitch_minimalist_route_navigator/community_incident_reporter/code.html`, `stitch_minimalist_route_navigator/telegram_live_traffic_feed/code.html` (each self-contained, inline `