arah2/AGENTS.md

<!-- GSD:project-start source:PROJECT.md -->
## Project

**araharah**

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 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; 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
to.

### Constraints

- **Platform**: Telegram bot + Telegram Mini App (WebApp API) — the webview flow
  is the product; no independent mobile app in v1
- **Hosting**: Cloudflare Workers with static assets (research finding: Cloudflare now directs all new projects to Workers, not Pages) — one wrangler project serves Mini App statics + `/telegram/webhook` + `/api/*`
- **Free-first infra**: every service must be open-source or genuinely free-tier (verified stack: grammY, MapLibre GL, OpenFreeMap, Valhalla, Photon — all $0); no paid APIs. Only infrastructure cost candidate is a small VPS for Valhalla + Photon; Oracle Cloud Always Free is the zero-cost option with a reliability asterisk
- **Privacy**: no location history / profiles stored without explicit opt-in;
  opt-in only telemetry
- **Region**: KL metro tuning for v1 (geocoding, POI search)
- **Design**: must match Telemetry Rams design system; Rams values are
  non-negotiable per DESIGN.md
- **Ops appetite (implied)**: IDEAS.md lists RabbitMQ, Prometheus/Grafana, Neon,
  Resend — treat as future/aspirational; v1 should prefer the minimal set of
  services that the core value actually needs (final choice deferred to research)
<!-- GSD:project-end -->

<!-- GSD:stack-start source:codebase/STACK.md -->
## Technology Stack

## 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) — 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 mockup screens under `stitch_minimalist_route_navigator/*/code.html` are legacy reference; the active UI entry points are `web/` and `theme/gallery.html`
- TypeScript — the bot Worker (`bot/src/`) and the Vite Mini App (`web/src/`)
- Markdown — design docs (`DESIGN.md`, `IDEAS.md`, `stitch_minimalist_route_navigator/telemetry_rams/DESIGN.md`)
## Runtime
- Installed: root `package.json` with npm workspaces `theme`, `bot`, `web`, plus `package-lock.json`. Test config lives in custom harnesses (`bot/test/runner.mjs`, `web/test/runner.mjs`, `theme/scripts/audit.test.mjs`). No `.nvmrc` and no CI config yet.
- Mockups run by opening `code.html` directly in a browser (CDN-based dependencies, no local dev server required).
## Frameworks
- Tailwind CSS via Play CDN (`https://cdn.tailwindcss.com`) — loaded as a `<script>` tag with an inline `tailwind.config` block defining the full "Telemetry Rams" theme (colors like `signal-orange`, `matte-black`, `soft-beige`; fonts; spacing/border-radius tokens). Present in all four mockup screens.
- Google Fonts CDN — `Geist` (body) and `Space Grotesk` (headings/telemetry), plus Material Symbols Outlined for icons (`https://fonts.googleapis.com/css2?...`). Present in all four mockup screens.
- Not detected. No third-party test framework; tests use custom `node:test`-style harnesses in `bot/test/` and `web/test/` (`runner.mjs` + `*.test.mjs` suites) plus `theme/scripts/audit.test.mjs`.
- Bundler: Vite (`web/vite.config.ts`). Theme has a token audit tool (`npm run audit -w theme`). No formatter or linter config.
- The Play CDN is explicitly a prototyping tool — a first implementation phase should migrate mockup designs to a committed Tailwind setup (build pipeline or v4 binary) before production use.
## Key Dependencies
- `cdn.tailwindcss.com` — theming engine for all screens
- `fonts.googleapis.com` / `fonts.gstatic.com` — Geist, Space Grotesk, Material Symbols
- Mockup images were originally hosted/lifted from Google-hosted sample assets (`lh3.googleusercontent.com/aida/...` placeholders in the Stitch output). The logo placeholder has been replaced with the local project logo (`assets/MASTER_FILE-arah2_logo.svg`); any remaining remote URLs are non-logo placeholders.
- Telegram Bot API — frontend transport (`IDEAS.md`: "Telegram-first")
- Neon Postgres + PostGIS — event/user storage (`IDEAS.md`)
- Routing engine: Valhalla + Photon are the validated stack per the project constraints; the OSRM references in older docs (`IDEAS.md`, `DESIGN.md`) are superseded
- Maptiler — map tile provider for grayscale snapshots (`IDEAS.md`, `DESIGN.md`)
- Cloudflare Workers with static assets — hosts the Mini App (`bot/wrangler.jsonc` binds `../web/dist`); Cloudflare Pages is superseded. Cloudflare R2 — image/snapshot storage (`IDEAS.md`)
- RabbitMQ — event queue for broadcast-nearby flows (`IDEAS.md`)
- Prometheus + Grafana — monitoring (`IDEAS.md`)
- Resend — email (`IDEAS.md`)
## Configuration
- `bot/.dev.vars.example` is the template (the real `bot/.dev.vars` is gitignored local secrets), plus `bot/wrangler.jsonc` and `bot/src/config.ts` (the typed `Env` contract). See `docs/CONFIGURATION.md` for the full variable list.
- No build config files. Tailwind config lives inline per-mockup in `<script id="tailwind-config">`; the canonical design-token source of truth is `stitch_minimalist_route_navigator/telemetry_rams/DESIGN.md` (YAML frontmatter with `colors`, `typography`, `spacing` blocks).
## Platform Requirements
- Any modern browser to view the UI; any text editor. Node/npm are required (workspaces, Vite, wrangler); `python3` only for the theme gallery preview server (`npm run gallery` → `python3 -m http.server 8123`).
- Settled runtime: TypeScript + grammY on Cloudflare Workers with KV (`chat_sessions`). Neon Postgres, OSRM, RabbitMQ, and Resend are future/aspirational and are not deployed.
## Design-System Constraints (binding for future code)
- Palette: Signal Orange `#EB8008`, Functional Red `#ED3F1C`, Olive Green `#736B1E`, Soft Beige `#D9D2C6`, Matte Black `#1A1A1A` (as defined in `DESIGN.md` and in the inline Tailwind config of every mockup)
- Typography: Space Grotesk for headings/telemetry numbers, Geist for body/labels; uppercase + expanded letter-spacing for labels
- Geometry: 8px baseline grid, **zero border-radius**, no shadows/blur/glass (per `telemetry_rams/DESIGN.md` "Elevation & Depth", "Shapes")
- Interfaces are mobile-first (mockups are `shell-type: mobile_tab` / `mobile_stack`), designed for Telegram-embedded panels and a possible PWA
<!-- GSD:stack-end -->

<!-- GSD:conventions-start source:CONVENTIONS.md -->
## Conventions

## Established Document Conventions
- The design system lives in `stitch_minimalist_route_navigator/telemetry_rams/DESIGN.md`
- Core philosophy docs are plain prose at repository root: `DESIGN.md` (Rams principles,
- Colors, kebab-case: `signal-orange` (#EB8008), `functional-red` (#ED3F1C),
- Typography scale, kebab-case: `display-lg`, `headline-lg`, `headline-md`, `headline-sm`,
- Spacing, kebab-case: `gutter`, `gutter-desktop`, `margin`, `margin-desktop`,
## Naming Patterns
- `snake_case`, name = the screen/feature being mocked up:
- `code.html` — the generated mockup markup for that screen.
- `screen.png` — the rendered screenshot of the same screen. Never rename these;
- `DESIGN.md` (where present) — design-system doc for that screen group.
## HTML Mockup Style (observed in `code.html` files)
- One self-contained HTML file per screen; first `<head>` line is a dense set of
- Tailwind is loaded via CDN (`https://cdn.tailwindcss.com`) with an inline
- Body uses semantic structure: `<header>` (fixed, h-16), `<main>` (flex-1), with content
- Fine-grained comments use PascalCase-ish descriptive style:
- Zero border radius (`0px`) on all containers, buttons, cards, badges, inputs.
- No shadows-with-blur, no frosted glass, no faux 3D; hierarchy via `1px`/`2px` solid
- Uppercase labels with expanded tracking (`tracking-wider`/`tracking-widest` on
- Icons: Material Symbols or inline `<svg>` with uniform stroke weights (2px standard,
- Color semantics are strict: orange = navigation/primary action, red = hazards/errors only,
## JavaScript (inline in mockups only)
- Vanilla, no framework, small inline `<script>` block at end of body.
- Functions are `camelCase`, verb-first, one per interaction:
- Interaction is triggered via inline `onclick="…"` on buttons (mockups are
## Where Conventions Are NOT Yet Established
- **Languages/runtime:** no manifest declares TypeScript/JavaScript versions, Node, or
- **Formatting & linting:** no Prettier/ESLint/Biome/editorconfig. HTML mockups are
- **Module layout / imports:** three `src/` trees with a full import graph: `theme/src/`, `web/src/`, `bot/src/`.
- **Error handling, logging, validation:** patterns exist — `bot/src/webhook.ts` secret validation + error handling, `bot/src/security/initdata.ts` HMAC validation, `web/test/no-storage.test.mjs` storage guard.
- **Git hygiene:** the workspace is a git repository (branch `main`); see the `.gitignore` rules for generated output and local secrets.
- **Path casing:** any backend service (Telegram bot, OSRM, Neon/Postgres — the stack
## Prescriptive Guidance for New Code
<!-- GSD:conventions-end -->

<!-- GSD:architecture-start source:ARCHITECTURE.md -->
## Architecture

## System Overview
```text
```
## Component Responsibilities
| Component | Responsibility | File |
|-----------|----------------|------|
| `active_route_guidance/` | Turn-by-turn navigation HUD mockup: maneuver strip, incident telemetry band, map corridor viewport | `stitch_minimalist_route_navigator/active_route_guidance/code.html` |
| `navigate_map_overview/` | Full-map navigation screen mockup: route rendering, layer toggles, recenter control | `stitch_minimalist_route_navigator/navigate_map_overview/code.html` |
| `telegram_live_traffic_feed/` | Telegram-bot-styled traffic feed mockup: inline commands (`/traffic`, `/hazard`, `/status`, `/clear`) via `insertCommand` handlers only — the dispatch-confirm interaction lives in `navigate_map_overview/code.html` (`confirmDispatch`) | `stitch_minimalist_route_navigator/telegram_live_traffic_feed/code.html` |
| `community_incident_reporter/` | Incident-report flow mockup: hazard drawer, modal report, incident type selection | `stitch_minimalist_route_navigator/community_incident_reporter/code.html` |
| `telemetry_rams/DESIGN.md` | Formal design system spec (design tokens: colors, typography, spacing, breakpoints, component rules) | `stitch_minimalist_route_navigator/telemetry_rams/DESIGN.md` |
| `DESIGN.md` | High-level Rams design philosophy: palette, typography, iconography, interaction flows | `DESIGN.md` |
| `IDEAS.md` | Product vision, core principles, target stack outline, gamification and future ideas | `IDEAS.md` |
## Pattern Overview
- Each mockup screen is a **single self-contained HTML file** (`code.html`) with inline `<style>` and inline `<script>`. No shared CSS/JS modules, no bundler, no imports between screens.
- Styling is Tailwind via **CDN script** (`https://cdn.tailwindcss.com`) with a per-file inline `tailwind.config` object encoding the design tokens (colors, borderRadius, spacing). No Tailwind build step.
- Fonts and icons are loaded from CDNs: **Google Fonts** (Space Grotesk for headlines/telemetry, Geist for body) and **Material Symbols Outlined** for iconography.
- Imagery is either **inline SVG** (route vectors, directional glyphs drawn with `stroke-linecap="square"`), the local project logo (`assets/MASTER_FILE-arah2_logo.svg`), or legacy **remote hosted URLs** (`lh3.googleusercontent.com/aida/...` placeholders in the remaining mockups) — local image assets are limited to the logo and `screen.png` captures.
- The mockups remain inline-`onclick` demo stubs with no state management, but the real app interactivity lives in `web/` (Vite/TypeScript Mini App) and the `bot/` command handlers.
## Layers
- Presentation: `stitch_minimalist_route_navigator/*/code.html` — Tailwind markup + inline SVG + demo JS
- Design tokens: `stitch_minimalist_route_navigator/telemetry_rams/DESIGN.md` (YAML front matter: `colors`, `typography`, `spacing`) duplicated as inline `tailwind.config` in each mockup's `<head>`
- Specs/docs: `DESIGN.md`, `IDEAS.md` (root)
- Frontend: Telegram Bot interface + Mini App served by the Cloudflare Worker's static assets (Pages superseded); optional PWA remains future
- Transport: Telegram API (bot commands, inline queries, location sharing)
- Routing: not wired yet — Valhalla + Photon is the validated target stack (OSRM references superseded)
- Services: RabbitMQ for event queueing; Resend for email
- Data: Neon (Postgres + PostGIS) for event/route storage; Cloudflare R2 for map snapshot storage; Tiles: OpenFreeMap today (`theme/basemap/liberty-rams.json`); Maptiler was the original idea
- Observability: Prometheus + Grafana
## Data Flow
### Mockup Screen Flow (current)
### Implied Report Flow (target, per `DESIGN.md`)
### Implied Navigation Flow (target, per `DESIGN.md`)
- None today. Mockup JS is stateless demo handlers only. Nothing implies persistence patterns yet.
## Key Abstractions
- Purpose: Single source of truth for colors, typography, spacing, component rules
- Examples: `stitch_minimalist_route_navigator/telemetry_rams/DESIGN.md`, duplicated inline in each `code.html` `<head>` as `tailwind.config`
- Pattern: YAML-front-matter spec → inline Tailwind config (manual duplication — a known inconsistency risk)
- Each of the four mockup screen directories holds exactly `code.html` (the mockup) and `screen.png` (a visual capture); `telemetry_rams/` holds only its `DESIGN.md`
- Examples: all four screen directories under `stitch_minimalist_route_navigator/`
- Event types appear consistently across docs and mockups: CONGESTION (traffic/orange), ACCIDENT/CRASH-BLOCK (red), POLICE RADAR / SPEED_TRAP (green)
- Examples: `stitch_minimalist_route_navigator/telegram_live_traffic_feed/code.html` (its actual handlers are `insertCommand('/traffic ')` / `insertCommand('/hazard ')` / `insertCommand('/status ')` / `insertCommand('/clear ')` plus a single `alert('Reroute broadcast loaded.')`; no `confirmDispatch` exists)
## Entry Points
- Location: `stitch_minimalist_route_navigator/<screen>/code.html` for each of the four screens
- Triggers: opening the file directly in a browser (`file://` works — all dependencies are CDN-hosted)
- Responsibilities: render the screen for design review; demo-interactions via inline handlers
## Architectural Constraints
- **Runtime:** None required for mockups; plain browser. An internet connection is required (Tailwind CDN, Google Fonts, remote images).
- **Global state:** None. Each mockup is fully isolated; no shared modules exist.
- **Circular imports:** Not applicable (no modules).
- **Token duplication:** The palette/typography/spacing defined in `telemetry_rams/DESIGN.md` is hand-copied into every mockup's inline `tailwind.config`. Any token change must be replicated N times until a real build pipeline exists.
- **Windows Zone.Identifier files:** no `*:Zone.Identifier` files exist anymore; the `.gitignore` rule for them remains as hygiene.
## Anti-Patterns (recommendations for the target codebase)
### Per-file Tailwind config duplication
### Inline onclick demo handlers
## Error Handling
## Cross-Cutting Concerns
<!-- GSD:architecture-end -->

<!-- GSD:skills-start source:skills/ -->
## Project Skills

| skill | Description | Path |
|-------|-------------|------|
| design-taste-frontend | >- tasteskill v2, the anti-slop frontend skill. Art direction for websites, distilled from a study of 247 curated gallery sites (One Page Love, Awwwards Sites of the Day). Deals researched directions (idea, composition, type, palette, photographs, section blueprints) from a library, enforces a strict no-slop house style with a real-browser inspector, and runs a look-and-fix loop on screenshots. Use this whenever you build, design, redesign, restyle, polish or review a landing page, marketing site, portfolio, product page, one-pager, hero or any public-facing web page, in any stack (HTML/CSS, React, Next.js, Vue, Svelte, Astro, Tailwind) — also when the user says a page looks generic, templated, "AI-made", sloppy, or asks to make it look designed, premium, award-level or less like every other site. Also for app screens: dashboards, admin and analytics views, settings, inboxes and other screens people work in, with their own run and rules. | `.agents/skills/design-taste-frontend/SKILL.md` |
<!-- GSD:skills-end -->

<!-- GSD:workflow-start source:GSD defaults -->
## GSD Workflow Enforcement

Before using edit, write, or other file-changing tools, start work through a GSD command so planning artifacts and execution context stay in sync.

Use these entry points:
- `/gsd-quick` for small fixes, doc updates, and ad-hoc tasks
- `/gsd-debug` for investigation and bug fixing
- `/gsd-execute-phase` for planned phase work

Do not make direct repo edits outside a GSD workflow unless the user explicitly asks to bypass it.
<!-- GSD:workflow-end -->



<!-- GSD:profile-start -->
## Developer Profile

> Profile not yet configured. Run `/gsd-profile-user` to generate your developer profile.
> This section is managed by `generate-claude-profile` -- do not edit manually.
<!-- GSD:profile-end -->