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 hosted on Cloudflare Pages), 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).

**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) — these are the **only executable code** in the repo
- Planning outputs: `.planning/` (not product code)
## 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 `<script>` Tailwind config, minimal inline JS for markup behavior)
- Markdown — design docs (`DESIGN.md`, `IDEAS.md`, `stitch_minimalist_route_navigator/telemetry_rams/DESIGN.md`)
- A backend language/runtime for the Telegram bot (not yet chosen in any doc; nothing in the repo constrains it)
## Runtime
- None installed. No `package.json`, no `requirements.txt`, no lockfile, no `.nvmrc`, no CI config, no test config anywhere in the repo.
- 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 test framework, no test files.
- Not detected. No bundler, no formatter, no linter config. Mockups are standalone static files.
- 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 are hosted/lifted from Google-hosted sample assets (`lh3.googleusercontent.com/aida/...` URLs appear in some screens' `<img>`/`src` attributes) — placeholders from the Stitch tooling, not project data
- Telegram Bot API — frontend transport (`IDEAS.md`: "Telegram-first")
- Neon Postgres + PostGIS — event/user storage (`IDEAS.md`)
- OSRM — routing engine with dynamic traffic weighting (`IDEAS.md`, restated in `DESIGN.md`: `/navigate origin → destination → OSRM route`)
- Maptiler — map tile provider for grayscale snapshots (`IDEAS.md`, `DESIGN.md`)
- Cloudflare Pages — optional PWA hosting (`IDEAS.md`); 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
- No `.env*` files, no config files exist. Nothing to document; note that a first backend phase will need to introduce one (e.g., Telegram bot token, Neon connection string, Maptiler key) — treat secret handling from day one since none exists yet.
- 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 mockups; any text editor. No Node/Python runtime is required by current code.
- Telegram bot process (runtime/tooling TBC), Neon Postgres (with PostGIS extension enabled), OSRM instance or hosted API, Maptiler API key, Cloudflare Pages + R2, RabbitMQ broker, Prometheus/Grafana stack, Resend account.
## 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:** no application code, no `src/`, no import graph.
- **Error handling, logging, validation:** no code exists to define patterns for these.
- **Git hygiene:** the workspace directory is not yet a git repository; when initialized,
- **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`), dispatch confirm | `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"`) or **remote hosted URLs** (`lh3.googleusercontent.com/aida/...` logo images) — no local image assets besides `screen.png` captures.
- Interactivity is **vanilla JS via inline `onclick` handlers** only (demo stubs — e.g., `alert('Reroute broadcast loaded.')`). No state management, no routing, no data layer.
## 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 + optional PWA hosted on Cloudflare Pages
- Transport: Telegram API (bot commands, inline queries, location sharing)
- Services: OSRM routing with dynamic traffic weighting; RabbitMQ for event queueing; Resend for email
- Data: Neon (Postgres + PostGIS) for event/route storage; Cloudflare R2 for map snapshot storage; Maptiler for basemap tiles
- 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 screen is one directory holding exactly `code.html` (the mockup) and `screen.png` (a visual capture)
- 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` (`confirmDispatch('CONGESTION')`, `confirmDispatch('CRASH / BLOCK')`, `confirmDispatch('POLICE RADAR')`)
## 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:** `*:Zone.Identifier` metadata files are scattered throughout and should be excluded from any future build/lint tooling.
## 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 -->