arah2/AGENTS.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)

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

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

Architecture

System Overview

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

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

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.