# Agent Instructions

This repository is a product and implementation blueprint for a bikepacking app. Treat the docs as the source of truth.

## Product constraints

- The app is for loaded bikepacking, not generic cycling.
- Optimize for multi-day trips, offline use, resupply, water, sleeping, repair, local rules, and bailout options.
- Routing quality should come from OSM/elevation/routing engines plus a proprietary bikepacking suitability layer.
- Never hardcode API keys or commercial credentials.
- Keep data-source adapters interchangeable.
- Treat legal access, protected areas, wild camping, and safety warnings as confidence-scored advisory information, not guaranteed legal advice.

## Engineering constraints

- Prefer a monorepo with `apps/web`, `apps/mobile`, `services/api`, `services/data-pipeline`, and `packages/shared`.
- Use TypeScript for user-facing apps and shared domain types.
- Use a backend service with geospatial database support. The recommended default is FastAPI + PostgreSQL/PostGIS, but an equivalent stack is acceptable if it preserves the API contract.
- Use MapLibre-compatible map rendering.
- Keep routing behind provider interfaces: `RoutingProvider`, `PoiProvider`, `ElevationProvider`, `WeatherProvider`, `RulesProvider`, `DeviceExportProvider`.
- Implement testable pure functions for scoring, staging, POI filtering, and warning generation.
- Add unit tests for scoring and staging before UI refinements.
- Add fixtures from `examples/` and keep sample outputs deterministic.

## Acceptance standard

A task is complete only when:

- code compiles,
- tests pass,
- API contracts are updated when behavior changes,
- environment variables are documented,
- user-facing errors are actionable,
- OSM and third-party attribution requirements are preserved in the UI and docs.