Alpha stage commit

codex/BACKLOG.csv

@@ -0,0 +1,13 @@
+id,epic,story,priority,acceptance
+BP-001,Planning,As a rider I can create a trip request with bike/load and daily constraints,P0,Form submits typed request and persists trip shell
+BP-002,Routing,As a rider I can get a bikepacking route from a mock provider,P0,Route geometry score warnings returned deterministically
+BP-003,Scoring,As a rider I can see why a route is risky or suitable,P0,Score includes surface grade access water and food warnings
+BP-004,Staging,As a rider I can split a route into daily stages,P0,Stages respect daily distance range and attach sleep options
+BP-005,POI Corridor,As a rider I can see water food sleep and repair near my route,P0,POIs sorted by meters from start and detour distance
+BP-006,Gaps,As a rider I can see long water food repair and bailout gaps,P0,Warnings produced when thresholds exceeded
+BP-007,Export,As a rider I can export GPX,P0,GPX validates and includes stage waypoints
+BP-008,Offline,As a rider I can generate an offline pack manifest,P0,Manifest includes route stages POIs rules and exports
+BP-009,Rules,As a rider I can see local rule cards,P1,Rule card has source date confidence and advisory status
+BP-010,Reports,As a rider I can submit structured local reports,P1,Report stores type location observed_at trust and expiry
+BP-011,Weather,As a rider I can see weather warnings along stages,P2,Forecast endpoint returns route/stage risk summaries
+BP-012,Devices,As a rider I can export TCX/FIT or sync devices,P2,Device export provider interface and first implementation exist

codex/CODEX_MASTER_PROMPT.md

@@ -0,0 +1,52 @@
+# Codex Master Prompt
+
+Use this prompt with Codex or another coding agent.
+
+```text
+You are building pikebacker, a specialized bikepacking planner and riding companion.
+
+Read the repository docs before coding, especially:
+- README.md
+- AGENTS.md
+- docs/01_product_requirements.md
+- docs/02_mvp_scope.md
+- docs/03_system_architecture.md
+- docs/05_routing_and_scoring.md
+- docs/06_offline_strategy.md
+- docs/08_data_model.md
+- schemas/openapi.yaml
+- schemas/database.sql
+- codex/IMPLEMENTATION_TASKS.md
+
+Build the MVP as a monorepo with:
+- apps/web: TypeScript web planner with map placeholder or MapLibre integration.
+- apps/mobile: placeholder/mobile offline architecture if full mobile implementation is too large.
+- services/api: backend API implementing the MVP endpoints.
+- packages/shared: shared TypeScript domain types and scoring logic.
+- services/data-pipeline: import/normalization scripts and docs.
+
+First implement deterministic mock-provider functionality from examples/ fixtures. Do not block on external API keys.
+
+Core MVP behavior:
+1. Create a trip request.
+2. Plan or load a route from fixture/mock routing provider.
+3. Score route segments for bikepacking suitability.
+4. Split route into daily stages.
+5. Find route-corridor POIs from fixture/database.
+6. Generate critical gap warnings.
+7. Render route and stage cards in the web planner.
+8. Export GPX.
+9. Create offline-pack manifest.
+10. Submit local reports and queue offline reports.
+
+Engineering rules:
+- Keep provider interfaces abstract and testable.
+- Do not hardcode API keys.
+- Use environment variables for providers.
+- Add unit tests for scoring, staging, POI corridor, and GPX export.
+- Preserve attribution hooks for OSM-derived data.
+- Expose uncertainty and warning severity in API responses.
+- Make the app useful with mock data before adding real providers.
+
+After each task, update README or docs if setup/behavior changes.
+```

codex/IMPLEMENTATION_TASKS.md

@@ -0,0 +1,157 @@
+# Implementation Tasks for Codex
+
+## Task 1 — Create monorepo scaffold
+
+Create:
+
+```text
+apps/web
+apps/mobile
+services/api
+services/data-pipeline
+packages/shared
+```
+
+Acceptance criteria:
+
+- root package/workspace or equivalent created;
+- lint/test scripts documented;
+- shared domain types imported by web/API where applicable;
+- `.env.example` files created;
+- no API keys committed.
+
+## Task 2 — Implement shared domain types and scoring
+
+Implement TypeScript types from `schemas/domain_types.ts`.
+
+Add pure functions:
+
+- `scoreSegment(segment, profile)`;
+- `scoreRoute(route, profile)`;
+- `detectCriticalGaps(route, pois, thresholds)`;
+- `estimateHikeABikeRisk(segment, profile)`.
+
+Acceptance criteria:
+
+- unit tests pass;
+- sample scoring fixture returns expected warnings;
+- profile thresholds are configurable.
+
+## Task 3 — Backend API mock MVP
+
+Implement endpoints from `schemas/openapi.yaml` with mock data:
+
+- `POST /v1/routes/plan`,
+- `POST /v1/stages/plan`,
+- `GET /v1/routes/{id}/pois`,
+- `GET /v1/routes/{id}/gaps`,
+- `POST /v1/offline-packs`,
+- `GET /v1/routes/{id}/export?format=gpx`,
+- `POST /v1/reports`.
+
+Acceptance criteria:
+
+- returns deterministic responses from `examples/`;
+- API validation is implemented;
+- tests cover success and error cases.
+
+## Task 4 — Stage planner
+
+Implement stage splitting:
+
+- respect min/max daily distance;
+- prefer endpoints near sleep options;
+- avoid long water/food gaps at stage end;
+- include Plan A/B endpoints;
+- generate warnings.
+
+Acceptance criteria:
+
+- 3-day and 5-day fixture routes produce plausible stages;
+- no stage exceeds hard constraints unless warning returned;
+- sleep candidates attached to each stage.
+
+## Task 5 — Web planner UI
+
+Build a web UI:
+
+- trip request form;
+- map panel;
+- stage timeline;
+- POI filter toggles;
+- warnings panel;
+- export/offline buttons.
+
+Acceptance criteria:
+
+- user can submit sample trip and see route/stages;
+- route-corridor POIs shown/listed;
+- critical warnings visible;
+- GPX export downloads.
+
+## Task 6 — GPX export
+
+Generate valid GPX with:
+
+- route geometry;
+- waypoints for stage endpoints;
+- optional POIs/course points;
+- metadata and attribution.
+
+Acceptance criteria:
+
+- validates as XML;
+- imports into common route viewers;
+- includes stage waypoints.
+
+## Task 7 — Offline pack manifest
+
+Implement offline manifest generation.
+
+Acceptance criteria:
+
+- includes route, stages, POIs, rules, exports, data versions;
+- marks unavailable layers clearly;
+- supports future tile pack file references.
+
+## Task 8 — Data pipeline skeleton
+
+Implement scripts/docs for:
+
+- reading OSM PBF extract;
+- extracting POI categories;
+- normalizing tags;
+- inserting into PostGIS;
+- importing protected areas/rule cards later.
+
+Acceptance criteria:
+
+- one small sample extract/fixture works;
+- schema migrations documented;
+- source attribution stored.
+
+## Task 9 — Provider adapters
+
+Add adapters:
+
+- mock routing provider;
+- openrouteservice provider placeholder;
+- GraphHopper/Valhalla adapter interfaces;
+- OSM POI provider.
+
+Acceptance criteria:
+
+- provider selected via environment/config;
+- mock provider is default;
+- external provider failures return actionable errors.
+
+## Task 10 — Community reports
+
+Implement structured report model and UI submission.
+
+Acceptance criteria:
+
+- reports typed and dated;
+- offline queue represented;
+- reports can attach to route meters/location;
+- moderation status supported.