HuntStand

Build a personal, offline-first hunting scouting map as a PWA. No accounts, no server, no telemetry. All data stays on the device.

Stack, no substitutions:
- Vite + React + TypeScript
- MapLibre GL JS for the map
- Dexie (IndexedDB) for all storage
- vite-plugin-pwa for installability and tile caching
- Tailwind for styling, keep it plain and thumb-friendly

Map:
- Base layers switchable: satellite and topo from MapTiler using VITE_MAPTILER_KEY from .env, plus an OpenStreetMap raster fallback that needs no key
- "Download this area" button: prefetch tiles for the current viewport at zoom 12 to 16 into the service worker cache, show progress and cache size, allow clearing

Data model in Dexie: properties (name, GeoJSON polygon, acres computed), markers (type: stand, blind, camera, plot, trail cam, gate, sign, custom; lat, lng, notes, photo blob), tracks (recorded GPS line, timestamps), sits (marker id, start, end, wind dir and speed, temp, moon phase, sightings list with species, count, sex, time, free notes).

Features:
- Tap map to add a marker, choose type from an icon grid, attach a photo from the camera input
- Draw or import property polygons: file import for GeoJSON, KML and GPX, since county GIS portals hand those out. Show acreage.
- Record a walk: watchPosition into a track, works with screen on, stop and save
- Wind overlay: fetch current and hourly wind direction and speed from Open-Meteo for the map center, draw an arrow and a compass rose, and shade a simple downwind cone from any selected stand so it is obvious which stands are burned today
- Sunrise, sunset and moon phase computed locally with suncalc, no API
- Sit log: start a sit from a stand marker, it snapshots wind, temp and moon, then log sightings as you go
- Export and import everything as one JSON file, plus GeoJSON export of markers and tracks

Explicitly out of scope: parcel boundaries or landowner names (no legal source to pull from, the user imports their own), multi-user sharing, sync, push notifications, deer movement predictions.

Seed with two example markers and a sample property polygon so the UI is not empty. Write a README that states plainly what it does not do.

# AGENTS.md — Build guide for HuntStand

## Project scope
An offline-capable PWA map where you drop stands, cameras, food plots and trails, draw your own property polygon, log sits with wind and moon data, and export everything as GeoJSON.

Catalogue verdict: no. Drawing pins on a map and logging what you saw at dawn is a trivial build, and an agent will hand you a working offline map in an afternoon. The part people actually pay for is the data underneath: nationwide parcel boundaries with owner names, recent high resolution aerial and topo imagery, and radar and wind layers stitched into one mobile app that works with no signal. That parcel layer is licensed, not scraped, and the imagery bill is real. Add the club side of it, where four people share the same map and see each other's stand check-ins live, and your local-only build stops covering the use case. Build the personal scouting notebook, keep paying if you need to know who owns the ridge behind you.
Use the implementation prompt below to define the deliverable. Complete each phase's acceptance checks before extending the scope.

## Working agreement
- Inspect the repository and its existing instructions before choosing paths, dependencies or commands. Keep one coherent stack and explain changes to the proposed architecture.
- Plan a vertical slice that accepts a real input and produces the useful output described below. Persist only the state the prompt calls for; respect memory-only and upstream-managed workflows. Use fixtures only when they are clearly labelled.
- After scaffolding, document the actual install, development, check and build commands in README and keep them synchronized with the package or project manifest. Do not report commands as successful unless they ran.
- Work in small steps. At handoff, list implemented flows, checks actually performed, remaining blockers, and any credentials or provider setup the owner must supply.
- Do not publish, spend money, contact customers, delete source data or run irreversible migrations without the project owner's authorization.

## Prerequisites
- A MapTiler or Mapbox key for satellite and topo tiles, or plain OpenStreetMap tiles if you accept no imagery
- County or state GIS parcel exports downloaded by hand for the properties you care about
- Open-Meteo for forecast and wind, no key needed
- A phone that will actually install a PWA and cache tiles

## Stack and architecture
- Vite + React + TypeScript.
- Model local triggers, rules, permissions, action history, and settings; keep stable source IDs and timestamps.
- Interface for this hunting land mapping and scouting workflow: a local web page with input, progress, review, and export views.

## Security and data integrity
- Base layers switchable: satellite and topo from MapTiler using VITE_MAPTILER_KEY from .env, plus an OpenStreetMap raster fallback that needs no key.
- Validate imported records and file paths; keep user data within the storage location named in the prompt.
- State the practical limit: Nationwide parcel boundaries and landowner names, which are licensed data you cannot regenerate.

## Agent implementation rules
- Project rule, data: Model local triggers, rules, permissions, action history, and settings; keep stable source IDs and timestamps.
- Project rule, behavior: Base layers switchable: satellite and topo from MapTiler using VITE_MAPTILER_KEY from .env, plus an OpenStreetMap raster fallback that needs no key.
- Project rule, recovery: Base layers switchable: satellite and topo from MapTiler using VITE_MAPTILER_KEY from .env, plus an OpenStreetMap raster fallback that needs no key.

## Optional agent skills and references
No installable skill is listed for this guide; use the project rules and the stack documentation.

Read the linked SKILL.md and its dependencies before adding a skill. Select only the skills matching this project's runtime and task; their documentation does not supply API access, credentials or approval to perform external actions. Pin the reviewed revision where the tool supports it. Follow the chosen agent's documented project-level installation mechanism.

## Distribution ideas
These are optional planning notes. Obtain the owner's approval before publishing or contacting anyone.
- Demonstrate this hunting land mapping and scouting operation with sample or user-owned data: Base layers switchable: satellite and topo from MapTiler using VITE_MAPTILER_KEY from .env, plus an OpenStreetMap raster fallback that needs no key.
- Show a concrete result or export: "Download this area" button: prefetch tiles for the current viewport at zoom 12 to 16 into the service worker cache, show progress and cache size, allow clearing.
- State the practical limit: Nationwide parcel boundaries and landowner names, which are licensed data you cannot regenerate.

## Engineering roadmap
1. Phase 1, architecture and data: Vite + React + TypeScript. Model local triggers, rules, permissions, action history, and settings; keep stable source IDs and timestamps.
2. Phase 2, implement: Base layers switchable: satellite and topo from MapTiler using VITE_MAPTILER_KEY from .env, plus an OpenStreetMap raster fallback that needs no key.
3. Phase 3, implement: Data model in Dexie: properties (name, GeoJSON polygon, acres computed), markers (type: stand, blind, camera, plot, trail cam, gate, sign, custom; lat, lng, notes, photo blob), tracks (recorded GPS line, timestamps), sits (marker id, start, end, wind dir and speed, temp, moon phase, sightings list with species, count, sex, time, free notes).
4. Phase 4, review and output: Draw or import property polygons: file import for GeoJSON, KML and GPX, since county GIS portals hand those out. Show acreage. "Download this area" button: prefetch tiles for the current viewport at zoom 12 to 16 into the service worker cache, show progress and cache size, allow clearing.
5. Phase 5, recovery and acceptance: Base layers switchable: satellite and topo from MapTiler using VITE_MAPTILER_KEY from .env, plus an OpenStreetMap raster fallback that needs no key. Verify this invariant with a saved fixture: A denied OS permission or unavailable target must leave user data unchanged and show what permission is missing. State the practical limit: Nationwide parcel boundaries and landowner names, which are licensed data you cannot regenerate.

## Paid-product capabilities outside this build
- Nationwide parcel boundaries and landowner names, which are licensed data you cannot regenerate
- Fresh leaf-off aerial imagery and multi-source topo layers across the whole country
- Live sharing with a hunting party: shared markers, check-ins, and who is sitting where right now
- Native app polish offline: reliable background GPS tracks, tile prefetch, battery behavior
- Weather radar, rut and deer movement forecasts, and the constant map data refreshes

## Implementation prompt
Build a personal, offline-first hunting scouting map as a PWA. No accounts, no server, no telemetry. All data stays on the device.

Stack, no substitutions:
- Vite + React + TypeScript
- MapLibre GL JS for the map
- Dexie (IndexedDB) for all storage
- vite-plugin-pwa for installability and tile caching
- Tailwind for styling, keep it plain and thumb-friendly

Map:
- Base layers switchable: satellite and topo from MapTiler using VITE_MAPTILER_KEY from .env, plus an OpenStreetMap raster fallback that needs no key
- "Download this area" button: prefetch tiles for the current viewport at zoom 12 to 16 into the service worker cache, show progress and cache size, allow clearing

Data model in Dexie: properties (name, GeoJSON polygon, acres computed), markers (type: stand, blind, camera, plot, trail cam, gate, sign, custom; lat, lng, notes, photo blob), tracks (recorded GPS line, timestamps), sits (marker id, start, end, wind dir and speed, temp, moon phase, sightings list with species, count, sex, time, free notes).

Features:
- Tap map to add a marker, choose type from an icon grid, attach a photo from the camera input
- Draw or import property polygons: file import for GeoJSON, KML and GPX, since county GIS portals hand those out. Show acreage.
- Record a walk: watchPosition into a track, works with screen on, stop and save
- Wind overlay: fetch current and hourly wind direction and speed from Open-Meteo for the map center, draw an arrow and a compass rose, and shade a simple downwind cone from any selected stand so it is obvious which stands are burned today
- Sunrise, sunset and moon phase computed locally with suncalc, no API
- Sit log: start a sit from a stand marker, it snapshots wind, temp and moon, then log sightings as you go
- Export and import everything as one JSON file, plus GeoJSON export of markers and tracks

Explicitly out of scope: parcel boundaries or landowner names (no legal source to pull from, the user imports their own), multi-user sharing, sync, push notifications, deer movement predictions.

Seed with two example markers and a sample property polygon so the UI is not empty. Write a README that states plainly what it does not do.

## Completion evidence
Demonstrate the prompt's acceptance scenarios against the scoped workflow. Include setup from a clean checkout and failure recovery. Check persistence across restart and export/restore only for the state the prompt says to store; for memory-only tools, confirm that temporary content is discarded as specified. Record actual results and remaining limitations. A detailed plan alone does not establish a working replacement.