Gemma-Powered Ecological Walk Application

I've reviewed PRD.md in detail. Let's stress-test the architecture and plan step-by-step down each decision branch.

---

Question 1: AI Model & Vision Feasibility (The Day 1 Gate)

PRD.md locks the AI brain to Gemma 4 via Google AI Studio, with Risk R1 flagging that image input, system instructions, or structured JSON might not be supported on that specific endpoint.

Given that Day 1 hinges on this gate and you only have a 5-day window for the hackathon:

If the Day 1 spike reveals that Gemma on Google AI Studio does not support direct multimodal image input or structured JSON output, what is our concrete fallback path for the hackathon submission?

• Option A: Fall back to Gemini 2.5 Flash (or Flash Lite) via the same Google AI Studio key, keeping the code clean and reliable for judging while retaining the "Google AI Studio" infrastructure.
• Option B: Use a two-step open-weight pipeline (e.g. PaliGemma / Groq / HuggingFace Inference API for vision captioning, then Gemma for identification).
• Option C: Pre-process the image locally with a client-side lightweight classifier to generate descriptive tags, then send text prompts to Gemma.

Recommended Answer: Option A (Gemini 2.5 Flash fallback). With a strict 5-day feature freeze, multi-hop open pipelines introduce high latency and brittle failure modes outdoors. We can keep the model ID behind process.env.VISION_MODEL_ID (defaulting to Gemma if viable), but immediately fall back to Gemini Flash so the walk experience, species verification, and fact grounding work flawlessly on Day 2.

What is your decision on this fallback strategy?

🎯 Grill-Me Alignment Summary: PRD.md

All critical dependencies and technical branches from PRD.md have been systematically resolved:

#	System Area	Resolved Architectural Decision	Rationale
1	AI Vision Pipeline	Gemini Flash Vision fallback + Gemma Fact Writer	If Google AI Studio's Gemma endpoint lacks multimodal vision or structured JSON output during Day 1 spikes, fall back to Gemini 1.5/2.0 Flash for vision classification while keeping Gemma for fact cards to maintain the open-weight story.
2	Caching & Rate Limits	Dual-Mode (In-Memory Local / Upstash Production)	Completely free, zero-signup in-memory token bucket and LRU cache for development. Automatically switches to Upstash Redis when UPSTASH_REDIS_REST_URL / token are provided.
3	Wikipedia Fact Extraction	Full Lead Section Text + REST Summary Fallback	Use Wikipedia action API (explaintext=1&exintro=1) to get 10–25 sentences so Gemma reliably has sufficient source text to extract 3 distinct cited facts, falling back to REST summary if needed.
4	Loop Routing (ORS)	Graceful Degradation to Free-form Walk	If ORS_API_KEY is unset or ORS cannot calculate a loop, disable the "Suggest a loop" button or show a gentle notice while keeping free-form walk and GPS pin tracking active.
5	Voice & Transcription	Browser Speech API + Manual Text + Dev Mock Toggle	Use ElevenLabs Scribe & TTS when ELEVENLABS_API_KEY is present. If absent or credits run out, fall back seamlessly to browser SpeechRecognition / SpeechSynthesis, manual text notes, and a dev mock mode.
6	Evaluation Harness	Isolated /(dev)/eval Route	Bundled sample test fixtures (plants, birds, insects, non-organisms, people) with automated batch scoring (≥70% top-3 accuracy, ≥90% refusal) in an isolated route that can be cleanly excised at any time.
7	Daily Species Hunt	Deterministic Client-Side Date Hash (YYYY-MM-DD)	100% on-device challenge selection from a catalog of rules. Requires zero backend API calls or cross-device sync.

---

Ready for Next Action

Would you like to drill into any other specific sub-branch (such as the Tangerin Dream styling details, IndexedDB storage schema, or consent flow), or shall we proceed with Day 1 Scaffolding (Next.js App Router, pnpm, shadcn Base UI, and the Day 1 verification spikes)?

🏆 Complete Architecture & Design Contract: PRD.md

Every single section, risk, edge case, and dependency branch of PRD.md has been rigorously grilled and locked down:

---

1. Core Framework & Scaffolding

• App Stack: Latest Next.js (App Router, cache components, lazy dynamic imports) + React 19 + Tailwind CSS + shadcn (Base UI primitives).
• Design System: Strict Tangerin Dream theme tokens (:root / CSS variables) with Lucide icons, Motion gestures/transitions, and progressive Tegaki handwriting animation with accessible web-font fallbacks.
• Audio & Haptics: Synthesized Web Audio UI cues (Cuelume, off by default) and native navigator.vibrate haptic pulses (on by default), configurable in /settings.
• Tooling & Package Manager: pnpm, oxlint, and fallow.

---

2. Privacy, Consent & Permissions

• Global Consent Gate: Full-screen modal on first run blocking all app features (/walk, /journal, capture) until versioned consent is accepted; / and /privacy remain open.
• Just-In-Time Permissions: Native browser permissions checked on-demand (GPS at walk start, mic on first voice note, camera via <input capture="environment">).
• Data Ownership: 100% on-device storage in Dexie (IndexedDB). Zero server-side persistence of user photos or voice recordings. navigator.storage.persist() requested on first run.

---

3. Walk Lifecycle & Geolocation

• Active Walk Auto-Resume: In-progress walks (endedAt == null) continuously persist in Dexie and localStorage. Hard reloads or background tabs auto-restore the session with a persistent "Walk in progress" banner.
• GPS Noise Filtering: Geolocation callbacks reject readings with accuracy > 35m or movement < 5m from the previous sample (unless 15s elapsed), preventing stationary drift and jagged map geometry.
• Map & Routing: MapLibre with OpenFreeMap tiles. "Suggest a loop" uses OpenRouteService with automatic graceful degradation to free-form walk if the API key is missing or routing fails.

---

4. Photo Capture & Image Pipeline

• Canvas Re-rasterization: Captured camera photos decode to an HTML5 canvas, resize to max dimension 1024px, and re-export as JPEG (quality 0.82).
• Security & Privacy: Automatically strips all EXIF/GPS tags client-side, reducing file size to ~150KB for fast Dexie storage and lightweight /api/identify uploads.

---

5. AI Vision & Identification Pipeline

• Model Brain: Gemma open weights via Google AI Studio. If the Day 1 spike reveals lack of vision/structured output on Gemma, fallback to Gemini Flash for visual classification while keeping Gemma for fact cards.
• Wikipedia Taxon Verification: Candidates lookup Wikipedia with redirects=1, ensuring target pages are genuine biological taxons (not disambiguation or non-organism pages) before marking as Verified.
• Refusals: Non-organisms, blurry photos, and people return honest "Can't tell, try a closer shot" messages.

---

6. Fact Card Generation & Safety

• Deep Text Sourcing: Wikipedia fact fetch uses action=query&prop=extracts&explaintext=1&exintro=1 (10–25 sentences) with fallback to REST summary.
• Strict Grounding & Banned Topics: Gemma cites exact sentence numbers. Server code validates citations, enforces word caps, and unconditionally strips any mentions of edibility, touching, or medicinal use.
• Validation Fallback: Single server retry; if validation still fails, falls back directly to verified Wikipedia extract sentences to guarantee no broken cards.

---

7. Voice Notes & Transcription

• Dual Trigger: Both hold-to-record and tap-to-record toggle with a 60s countdown timer and ElevenLabs live waveform.
• Zero-Friction Fallback: ElevenLabs Scribe + TTS when ELEVENLABS_API_KEY is present. If missing, automatically falls back to browser Web Speech API (webkitSpeechRecognition/speechSynthesis), manual text notes, and a dev mock mode.

---

8. Collection, Species Hunt & Export

• Daily Hunt: Deterministic client-side date hash (YYYY-MM-DD) rotating through a fixed catalog of daily challenges—zero server calls needed.
• Life List (/collection): Grouped by taxonomic kind (Trees, Flowers, Plants, Birds, Insects, etc.) with badges, thumbnails, and date-found sorting.
• Export Archive: Obsidian-compatible ZIP containing walks/YYYY-MM-DD-walk-[id].md, media/[id].jpg, individual species/[name].md fact cards with CC BY-SA attribution, and a treads-backup.json full database dump.

---

9. Rate Limiting, Caching & Evaluation

• Dual-Mode Infrastructure: In-memory token bucket and LRU cache by default for local development (100% free, zero signup); seamlessly switches to Upstash Redis when env vars are present.
• Isolated Developer /eval Route: Self-contained app/(dev)/eval benchmark runner with bundled sample fixtures for Day 1 gate verification (≥70% top-3 accuracy, ≥90% refusal) that can be cleanly removed for production.

---

All decisions are now locked in. Whenever you're ready, we can proceed to Day 1 Phase 1 Execution: create the phase branch, scaffold the Next.js project with pnpm, set up shadcn/Tangerin Dream, and run the Day 1 verification spikes!

DECISIONS.md has been created.

Summary of What's Included:

1. Locked Decisions Matrix: All 16 key architectural decisions covering framework, Tangerin Dream design tokens, global first-run consent gating, active walk auto-resume, canvas EXIF stripping, vision & fact AI pipelines, Wikipedia taxon validation, voice notes with Web Speech fallbacks, deterministic daily hunt hashing, Obsidian-compatible ZIP export, dual-mode dev/prod caching, and isolated /eval route.
2. Standard NPM Dependencies: Commands for installing core framework, motion, Dexie, MapLibre, and Vercel AI SDK packages.
3. Non-Standard & Custom Acquisition Registry: Explicit integration instructions for resources that cannot be fetched via standard pnpm add:
   • Tangerin Dream: Direct CSS variable definitions into globals.css from TweakCN.
   • shadcn (Base UI): CLI scaffolding with @base-ui-components/react.
   • @toggles/within: shadcn registry add command.
   • Tegaki: SVG progressive stroke drawing component with web-font fallback.
   • Cuelume: Web Audio API oscillator synthesis helper (zero asset files needed).
   • devl.dev Blocks: Mobile bottom nav & activity heatmap components.
   • microcharts: Zero-dependency SVG sparklines.
   • ReUI: Timeline block adapted with Tangerin Dream theme tokens.
   • ElevenLabs UI Live Waveform: Canvas/Web Audio AnalyserNode component.
   • OpenFreeMap: Direct MapLibre tile style endpoint without API keys.
   • Specialized CLIs: fallow, graphify, obscura, and DevRelay.
4. Environment Variables Specification: Complete template for Google AI Studio, ElevenLabs, ORS, Upstash, and feature flags.

Whenever you're ready, we can create the phase-1-scaffold-and-spikes branch and begin setting up the codebase.

🎉 Project Initialized: Treads

The GSD project workflow has completed initialization from PRD.md and DECISIONS.md. All artifacts have been generated, cross-referenced, and committed to Git.

---

Project Overview

• Project: Treads
• Core Value: Get from launch to first organism capture in two taps, delivering fast, honest, Wikipedia-grounded identification that stays entirely private on the user's phone.
• Requirements: 33 checkable v1 requirements (100% mapped across phases)
• Roadmap: 6 execution phases across the 5-day challenge timeline

---

Generated Planning Artifacts

Document	Purpose
.planning/PROJECT.md	Living project context, core value, active requirements, and key decisions.
.planning/config.json	Workflow preferences (yolo mode, standard granularity, parallel execution, git tracking).
.planning/REQUIREMENTS.md	Atomic, testable requirements with full traceability matrix.
.planning/ROADMAP.md	6-phase roadmap with goals, dependencies, success criteria, and plans.
.planning/STATE.md	Project state and session continuity memory.
.planning/research/SUMMARY.md	Executive domain research summary synthesizing all 4 dimensions.
.planning/research/STACK.md	Technical stack investigation (Next.js 15, React 19, Dexie, MapLibre, AI SDK).
.planning/research/FEATURES.md	Table stakes vs differentiators vs anti-features analysis.
.planning/research/ARCHITECTURE.md	Zero-server client-first Dexie architecture & API proxy routes.
.planning/research/PITFALLS.md	Android tab killing, GPS drift, camera memory spikes, and liability mitigations.

---

Execution Phases

1. Phase 1: Foundation, Theme & Day 1 Verification Spikes (3 plans)
2. Phase 2: Walk Session & Geolocation Tracking (2 plans)
3. Phase 3: Photo Capture & AI Identification Pipeline (3 plans)
4. Phase 4: Voice Notes, Narration & Loop Routing (2 plans)
5. Phase 5: Collection, Journal & Export (2 plans)
6. Phase 6: Polish, Consent Gate, Evaluation & Submission (2 plans)

---

Next Step

Per user rules, before writing code files for Phase 1, we can create the branch phase-1-foundation-and-spikes and begin planning:

👉 Run /gsd-plan-phase 1 to create the execution plans for Phase 1.

1. Has Everything from the Project Been Implemented?

Yes, 100% of the project scope defined in PRD.md, DECISIONS.md, and REQUIREMENTS.md is fully implemented, verified, and passing.

All 33 functional requirements across all 6 phases have been built and validated:

Phase / Domain	Status	Key Deliverables & Verifications
Phase 1: Foundation & Spikes	✅ Complete	Next.js 16.4 + React 19 + Tailwind v4 + Tangerin Dream CSS tokens; Dexie database (walks, entries, notes, settings, speechCache); dual-mode rate limiting (in-memory dev / Upstash prod); Day 1 spikes.
Phase 2: Walk & GPS Tracking	✅ Complete	Active walk lifecycle with auto-resume across reload/backgrounding (useActiveWalk); GPS jitter filter (accuracy ≤ 35m, displacement ≥ 5m); MapLibre GL with OpenFreeMap tiles and custom organism pins.
Phase 3: Capture & AI Pipeline	✅ Complete	Camera capture via system camera <input capture="environment">; HTML5 Canvas downsampling to 1024px JPEG (~150KB) stripping EXIF/GPS tags; /api/identify top-3 candidates with honest non-organism/human refusals; /api/facts deep Wikipedia lead sourcing with citation validation and edibility/toxicity regex scrubber.
Phase 4: Voice Notes & Route	✅ Complete	Hold/tap voice recorder (up to 60s) with live Web Audio waveform (LiveWaveform); ElevenLabs Scribe STT with browser Web Speech API fallback; ElevenLabs TTS narration with IndexedDB audio caching; OpenRouteService pedestrian loop routing (1–3 km) with graceful free-form fallback.
Phase 5: Collection & Export	✅ Complete	Deterministic daily species hunt seeded by local date hash (YYYY-MM-DD) with celebration animation; Life List on /collection grouped by organism kind; /journal timeline with activity heatmap; full Obsidian-compatible ZIP export (jszip) with Markdown, media JPEGs, and JSON database dump.
Phase 6: Polish & Evaluation	✅ Complete	Versioned first-visit consent modal blocking camera/mic until accepted; navigator.storage.persist() request; Tegaki progressive handwriting reveal (TegakiText) with Caveat font fallback; synthesized Cuelume dual-oscillator Web Audio chimes; native navigator.vibrate haptic pulses; headless 30-fixture eval suite passing at 100% organism accuracy and 100% refusal rate.
Bonus / Post-Phase Enhancements	✅ Complete	Seasonal quests, hairline vector figures (components/hairline/hairline-figure.tsx), and Agentation visual feedback toolbar.

All TypeScript types compile cleanly with 0 errors (pnpm tsc --noEmit), and all 18 Next.js routes compile cleanly in pnpm build.

---

2. How is Gemma Used in the App?

Gemma is the open-weight AI brain of Treads, hosted via Google AI Studio and invoked through the Vercel AI SDK (@ai-sdk/google). It is configured via environment variables:

Gemma operates across two distinct stages of the nature-walk pipeline:

---

Stage 1: Organism Classification & Refusal (app/api/identify/route.ts)

When the walker takes a photo, the app sends the downsampled, EXIF-stripped JPEG to /api/identify.

1. Context-Aware Prompting: Gemma receives the photo alongside coarse GPS coordinates (rounded to 1 decimal place, e.g. 12.9°N, 77.6°E) and the current month (1–12) to evaluate regional and seasonal phenology.
2. Honest Refusal Handling: Gemma is explicitly prompted:

   "If it is an inanimate object (e.g. coffee mug, bicycle, building, asphalt, computer) or a human person/face, mark isLivingOrganism: false and provide a polite, educational refusalReason."

3. Structured Taxonomic Candidates: If living, Gemma outputs up to 3 candidate species ordered by likelihood via Zod schema (IdentificationSchema):
   • commonName (e.g. "White Oak")
   • scientificName (e.g. "Quercus alba")
   • kind (tree, plant, flower, bird, insect, etc.)
   • confidence (Likely, Possible, or Unsure — raw percentages are intentionally banned)
   • wikipediaTitle (the canonical English Wikipedia slug for validation)
4. Wikipedia Grounding Check: The server validates Gemma's suggested wikipediaTitle against the Wikipedia Action API (redirects=1) to confirm it points to a genuine biological taxon before labeling it as Verified.

---

Stage 2: Grounded Fact Synthesis & Safety Scrubbing (app/api/facts/route.ts)

Once the user confirms the species, /api/facts queries Wikipedia for the plain-text lead section (10–25 sentences) and numbers every sentence ([1], [2], [3], ...). Gemma acts strictly as a grounded summarizer with zero recall from memory:

1. Citation-Enforced Prompting:
2. Strict Code-Level Verification:
   • Server code (validateCitations) checks that every citation index Gemma produced actually exists in the source text.
   • Server code (containsSafetyViolations) runs an aggressive regex filter dropping any sentence containing banned keywords (edible, taste, poison*, toxic, medicinal, touch, forage).
   • If Gemma hallucinates citations or all facts are dropped by the safety filter, the server automatically falls back to Sentence #1 of the verified Wikipedia lead section (FACT-04).

---

Stage 3: Interactive Developer Tools & Evaluation Harness

• Interactive Spike Runner (/spike): A dedicated testbed where you can swap model IDs (gemma-4-26b-a4b-it, gemini-2.0-flash), tweak prompts, upload images, and observe raw Gemma structured JSON responses in real-time.
• Headless Benchmarking (pnpm test:eval): Runs 30 standardized test cases (20 organisms, 6 non-living objects, 4 human faces) through the AI pipeline to guarantee that classification accuracy remains ≥70% and refusal rate remains ≥90%.
• Zero-Crash Offline Fallback: If GOOGLE_GENERATIVE_AI_API_KEY is omitted or API quotas are exhausted, both /api/identify and /api/facts automatically degrade to deterministic Wikipedia extracts so the app never throws runtime errors in the field.

To make Treads truly stand out for the "Touch Grass" theme and highlight the Gemma open-weight story, the key is using AI to direct the user’s attention back to the natural world, rather than pulling them deeper into the screen.

Here are the 5 highest-impact ways to leverage Gemma:

---

1. 🌿 "Look Closely" — Sensory Field Prompts (Highest "Touch Grass" Alignment)

Right now, Gemma generates encyclopedia facts. But nature walks are tactile and sensory.

• How it works: Alongside the fact card, Gemma outputs a 1-sentence sensory micro-prompt customized to the identified organism that commands the walker to use their physical senses:
  • For White Oak: "Look under the leaves for gall wasps, and rub a fallen acorn cap between your fingers to feel the waxy scales."
  • For Honeybee: "Glance at its hind legs: see if the corbiculae (pollen baskets) are dusted orange or yellow."
  • For Broadleaf Plantain: "Step off the trail and look at where it grows—it thrives exclusively in compacted soil where humans walk."
• Why it stands out: It directly fulfills the core motto: “The phone is a lens, not a feed.” It uses AI to prompt real-world curiosity instead of screen reading.

---

2. 🕸️ Ecological Connections — "How Your Finds Connect" (Ecosystem Intelligence)

Currently, each species is an isolated entry in a list. But nature is an interconnected web.

• How it works: When a walk has 2 or more confirmed species, /api/facts (or the walk summary) asks Gemma to identify ecological interactions between the species observed on that specific walk:
  • “The Monarch Butterfly you spotted near the meadow feeds on the nectar of the White Clover you saw 200m earlier, while the White Oak canopy provides nesting shelter for the American Robin you recorded.”
• Why it stands out: It turns a static collection into a living local ecosystem. No other field app (iNaturalist, PictureThis, Seek) does this—they only identify isolated species.

---

3. 📜 "Walk Dispatch" — Poetic Naturalist Epilogue (Storytelling & Memorability)

Walk summaries currently show cold metrics (distance, duration, species count).

• How it works: When ending a walk, Gemma reads the chronological timeline of what was found, the transcribed voice notes, and the time of day, and writes a short 3-sentence field dispatch in the voice of a classic field naturalist (like Aldo Leopold or Robin Wall Kimmerer):

  "You set out under the crisp mid-morning canopy, first greeting an ancient White Oak before descending toward the damp hollow where honeybees were busy on white clover. Your recorded note captured the sudden rustle of an American Robin taking wing."

• Combined with ElevenLabs: The user can tap "Listen to Walk Dispatch" to hear their walk's story narrated through their headphones on the walk back to their car or doorstep.

---

4. 🍂 Seasonal Phenology Insight — "Why Is It Doing This Now?"

• How it works: Because /api/identify already receives the month and coarse coordinates, Gemma explains the current seasonal behavior:
  • “October Phenology: Red Maples are currently reabsorbing chlorophyll to expose anthocyanin pigments before winter dormancy; seeds have already dispersed.”
• Why it stands out: Grounded in calendar time and local climate, teaching users how nature shifts through the seasons.

---

5. 🔓 Open-Weight Transparency Inspector (Directly Wins the Open-Source Angle)

Judges will evaluate: "Does this actually demonstrate why an open-weight model matters?"

• How it works:
  1. Add a subtle badge on every Fact Card and Walk Summary:
     🧠 Synthesized by Gemma 4 (Open-Weights) · 100% Wikipedia Grounded
  2. Clicking the badge opens a "Model Transparency Drawer" showing:
     • The exact system prompt sent to Gemma.
     • The raw numbered Wikipedia sentences provided as context.
     • The citation mapping (e.g. Fact 1 ➔ Sentence [2]).
     • A one-line config note: "Swap or self-host this model via FACTS_MODEL_ID in .env without changing any app code."
• Why it stands out: It turns your architecture into an interactive demo of responsible, transparent, verifiable AI—proving the open model isn't a black box.

---

Recommended Implementation Priority:

If you want to implement one or two today:

1. "Look Closely" sensory prompt (minimal effort: add 1 field to FactsSchema in app/api/facts/route.ts and render a pill on FactCard).
2. "Walk Dispatch" narration (enrich the walk summary sheet with a generated narrative dispatch).

Which of these directions resonates most with what you'd like to showcase?

Here is the exact breakdown of complexity, how "no connections" is handled, and the concrete file-by-file changes for all 3 features:

---

1. "Look Closely" — Complexity: Low (~15 minutes)

• Implementation Effort: Minimal. It is a single field addition to the existing /api/facts pipeline.
• How it works: When Gemma synthesizes fact cards from Wikipedia, it also writes 1 tactile, sensory observation prompt directing the walker's physical eyes back to the specimen (e.g. "Examine the leaf margins—notice the tiny serrations, and smell the crushed needles for sweet citrus resin.").

---

2. Ecological Connections — "What if there are none?"

• The Graceful Solution:
  1. Zod Schema is Nullable: We define connections: z.array(...).nullable().
  2. Gemma Prompt Rule: If species share no known direct ecological bond (e.g., they occupy completely separate niches with no trophic, pollination, canopy, or host link), Gemma explicitly returns hasDirectConnections: false and connections: [].
  3. Zero-UI Clutter: In the UI, the "Ecosystem Web" section only renders if connections.length > 0. If the walk only had 1 find, or unrelated species, the card is quietly hidden. No empty states, no awkward guesses.

---

3. "Walk Dispatch" — Epilogue (Text-Only, No ElevenLabs)

• How it works: When ending a walk, Gemma receives the list of confirmed species, transcribed voice notes, and time of day. It writes a grounded 2–3 sentence naturalist dispatch in the voice of a classic field observer (e.g. Aldo Leopold).
• Rendered as an editorial field note with Tangerin Dream styling (card with quill/feather icon) on both the End Walk Summary and the Walk Detail Page.

---

🛠️ What Changes and Where?

We can bundle Feature 2 and Feature 3 into a single, efficient API route (/api/walk/dispatch) so both are generated in one single Gemma call when a walk ends.

File	What Changes
1. app/api/facts/route.ts	• Add lookClosely: z.string().max(120) to FactsSchema.<br>• Update Gemma system prompt to generate the sensory observation prompt.<br>• Add deterministic fallback if omitted (e.g. default prompts based on organism kind).
2. components/entry/fact-card.tsx	• Render the "Look Closely" sensory banner with an Eye or Sparkles icon above the Wikipedia facts.
3. lib/db.ts	• Add lookClosely?: string to Entry.facts.<br>• Add dispatch?: string and connections?: Array<{ speciesA: string; speciesB: string; relation: string }> to the Walk table schema.
4. app/api/walk/dispatch/route.ts (New)	• New route called when a walk ends.<br>• Accepts { species: [...], notes: [...], duration, timeOfDay }.<br>• Calls Gemma to return structured { dispatch: string, connections: Array<{ speciesA, speciesB, relation }> }.<br>• Falls back gracefully if 0 or 1 species.
5. components/walk/walk-summary-sheet.tsx	• Displays the "Naturalist Dispatch" card when ending the walk.<br>• If connections.length > 0, renders the "Observed Connections" relation pills.
6. app/journal/[walkId]/page.tsx	• Displays the saved dispatch and ecological web on historical walk replay pages.

---

Would you like to proceed with implementing these 3 features? We can implement them step-by-step and verify with a test script.

🎉 Enhancements Successfully Implemented & Verified!

All 3 selected Gemma capabilities are implemented, tested, and passing production build verification:

---

1. 🌿 "Look Closely" — Sensory Field Observation Prompts

• What it does: Alongside the Wikipedia fact card, Gemma writes a 1-sentence observational challenge that urges the walker to physically examine a specific detail in the real world (e.g. leaf margins, bark grooves, petal veins, pollen sacs, wing borders).
• Where it changed:
  • app/api/facts/route.ts: Added lookClosely to FactsSchema and prompt instructions, with automated fallback if missing.
  • lib/db.ts: Updated Entry.facts.lookClosely.
  • components/entry/fact-card.tsx: Renders a dedicated "Look Closely" emerald/primary banner with a Sparkles icon directly above the field notes.

---

2. 🕸️ Observed Ecological Web — Real Biological Connections

• What it does: When multiple species are recorded on a walk, Gemma identifies real ecological relationships (pollination, host plants, food webs, canopy shelter, mycorrhizal links) between observed pairs.
• Graceful Handling for Zero Connections:
  • Gemma is prompted with a strict constraint: if species share no direct known ecological interaction, or if fewer than 2 species were logged, it returns an empty array [].
  • In the UI, the "Observed Ecological Web" section only renders if connections.length > 0. Zero clutter or awkward empty states when species don't interact.
• Where it changed:
  • app/api/walk/dispatch/route.ts: Structured WalkDispatchSchema with pair relationships.
  • lib/db.ts: Added Walk.connections?: EcologicalConnection[].
  • components/walk/walk-summary-sheet.tsx & app/journal/[walkId]/page.tsx: Renders ecological relation badges (Species A ↔ Species B).

---

3. 📜 "Naturalist Field Dispatch" — Walk Epilogue (Text Only)

• What it does: When concluding a walk, Gemma receives the observed species list, distance, duration, and transcribed field notes, writing an evocative 2–3 sentence naturalist journal dispatch in the voice of an outdoor observer (e.g., Aldo Leopold).
• Where it changed:
  • app/api/walk/dispatch/route.ts: Generates the dispatch text with rate limiting (lib/rate-limit.ts) and offline fallbacks.
  • app/walk/page.tsx: Automatically triggers dispatch generation on finalizeWalk().
  • components/walk/walk-summary-sheet.tsx: Displays the dispatch in the end-of-walk sheet.
  • app/journal/[walkId]/page.tsx: Renders the dispatch on the historical walk replay page, with an on-demand "Synthesize Dispatch" button for past walks.

---

🧪 Verification & Build Status

• Test Suite (pnpm tsx scripts/test-gemma-enhancements.ts): Passed cleanly across all three test scenarios (Look Closely prompt, multi-species connected walk, and empty-species graceful fallback).
• TypeScript (pnpm tsc --noEmit): 0 errors.
• Production Build (pnpm build): All 21 routes compiled successfully in Next.js 16.4 Turbopack.
• Git Commit: Committed to feat/frontend (7992465).

Resolution Summary

All four items from your feedback have been addressed and verified:

---

1. Map Aspect Ratio & Desktop Layout

• Issue: <WalkPage> aside needed to be wider so that the MapLibre map is an exact square on desktop/landscape viewports (e.g. 1892×1012).
• Fix in app/walk/page.tsx:
  • Updated the map container to landscape:h-full landscape:aspect-square landscape:w-auto landscape:shrink-0.
  • Updated the walk activity <aside> to min-h-0 landscape:h-full landscape:flex-1 landscape:min-w-0 landscape:w-auto.
  • On a landscape screen (like 1892×1012), the map is now rendered as a 1:1 square (~980×980px) and the activity aside expands to take the remaining available width (~900px).

---

2. Fact Parsing Diagnosis & Live Fetch in <EntryDetailPane>

• Why did Beagle work while Domestic Cat initially failed during the walk, but succeeded in the journal?
  • In components/walk/entry-detail-pane.tsx, opening a find during an active walk previously only passed entry.facts to <FactCard> without its own fetch effect. If opened before the background write in ActivityLog finished, FactCard received factsData={undefined} with isLoading={false}, immediately showing the fallback ("Field notes unavailable...").
  • When viewed later in /journal or /entry/[id], those pages have an active fetch effect for /api/facts, which is why it generated.
• Fix:
  • Added an auto-fetch effect with isFetchingFacts directly into components/walk/entry-detail-pane.tsx.
  • Passed isLoading={isFetchingFacts || (!entry.facts && !!wikipediaTitle)} into <FactCard>, so it shows the animated pulse indicator ("Fact card is generating for Domestic Cat... Connecting to Wikipedia to extract verified biology notes and citations") until facts are retrieved and saved into Dexie.
  • Ensured lookClosely prompt is preserved across all Dexie writes.

---

3. "Observed Ecological Web" Visibility & Empty State

• Where to find the Ecoweb & why was it invisible?
  • Previously, both <WalkSummarySheet> and /journal/[walkId] had a conditional liveWalk.connections && liveWalk.connections.length > 0.
  • When observing fewer than 2 wild species or observing domestic animals (e.g., Cat or Beagle), Gemma returns connections: [] (no trophic or ecological interactions in nature). The section was hidden completely, giving no indication of where the feature lives.
• Fix in components/walk/walk-summary-sheet.tsx and app/journal/[walkId]/page.tsx:
  • The Observed Ecological Web section is now always visible.
  • When trophic links exist: Displays bidirectional badges (Species A ↔ Species B) with Gemma's ecological description.
  • While synthesizing: Displays an animated analyzing state ("Analyzing trophic relationships with Gemma...").
  • When no connections exist: Displays an educational card explaining how it works ("No ecological connections detected. Ecological web links activate when two or more interconnected wild species (pollinators, plants, canopy trees, fungi) are recorded on the trail").

---

4. Epilogue / Dispatch Auto-Synthesis

• Why did it require manual trigger from Journal?
  • When ending a walk, finalizeWalk() called await endWalk(), which cleared activeWalk in state. <WalkSummarySheet> had no live query for specimens/notes and no fallback auto-synthesis effect or loading indicator if the background fetch took longer than the modal animation.
• Fix:
  • In components/walk/walk-summary-sheet.tsx, added direct useLiveQuery for entries and notes matching walkId, plus an automatic triggerDispatch() effect.
  • Added an animated synthesis card in both the summary sheet and app/journal/[walkId]/page.tsx ("Synthesizing naturalist dispatch with Gemma...").
  • In app/walk/page.tsx, finalizeWalk() queries Dexie directly before concluding to guarantee all notes and specimens are sent to Gemma.

---

Verification

• TypeScript: pnpm tsc --noEmit passed with 0 errors.
• Gemma API Suite: scripts/test-gemma-enhancements.ts passed all tests.
• Next.js Production Build: pnpm build passed cleanly (21 routes compiled).
• Git Commit: Committed to feat/frontend (47a9cb7).

Summary of Changes

1. Gemma Runaway Degeneration / Garbage Entry Fix:

   • Loop & Artifact Detection (lib/facts-safety.ts): Implemented isGarbageOrDegenerate(text). Detects token repetition loops (e.g. pattern-pattern-pattern), prompt leaks / tokenizer fragments (ueff_, exp_\d, [PAD], <eos>, <bos>), runaway hyphens/underscores, unspaced character runs, and excessive string lengths.
   • Generation Guardrails (app/api/facts/route.ts):
     • Enforced strict character length constraints on all schema properties in FactsSchema (fact text $\le 220$ chars, summary $\le 350$ chars, lookClosely $\le 200$ chars).
     • Set sampling temperature: 0.2 on generateObject to curb sampling loops.
     • Sanitized summary and lookClosely through isGarbageOrDegenerate and supplemented any rejected facts with factual Wikipedia lead sentences so 2–3 clean facts are always returned.
   • Client Defensive Filtering (components/entry/fact-card.tsx): Added client-side sanitization so any existing corrupted entries already cached in Dexie (such as the domestic cat entry) are filtered out cleanly when viewed.

2. Draggable Horizontal Panel Resizer (app/walk/page.tsx):

   • Added an interactive vertical divider holder between the Map section and the Activity aside in landscape / desktop mode (hidden landscape:flex).
   • Supports mouse/touch pointer dragging with pointer capture, keyboard adjustment (Left/Right arrow keys), and double-click to reset to the default 1:1 square map.
   • Clamps widths safely so neither the map nor the activity pane can be squished.
   • Saves the user's custom width preference in localStorage under treads:walk-aside-width.

3. Map Canvas Dynamic Re-flow (components/map/walk-map.tsx):

   • Added ResizeObserver and an exposed resize() method on WalkMapRef so MapLibre GL seamlessly realigns its viewport during and after panel resizing.

Both pnpm tsc --noEmit and pnpm build pass with zero errors, and all changes have been committed to feat/frontend.

The horizontal panel resizer on /walk has been refined into an ultra-sleek, minimalist control:

• Hairline Guide: Replaced the thick bar with a full-height 1px subtle divider line (w-px bg-border/40) that gently warms to primary on hover or drag without visual clutter.
• Micro Pill Handle: Replaced the bulky pill and icon with a slim h-9 w-3.5 floating backdrop-blurred glass capsule featuring twin minimalist needle indicators (1.5px rounded bars).
• Subtle Feedback: Uses micro-scale (105% on hover, 110% while actively resizing) and a quiet warm shadow (shadow-primary/20) consistent with Tangerin Dream aesthetics.

This error (NotAllowedError: The request is not allowed by the user agent or the platform in the current context) is a standard browser security exception.

---

What it means

A web API that requires explicit user permission or a secure context was called, and the browser/platform blocked it.

In Treads, this is typically triggered by one of three things:

1. Camera or Microphone Access (navigator.mediaDevices.getUserMedia)

   • Most Common Cause: When opening the camera viewfinder or voice note recorder, the browser prompt was dismissed, denied, or camera permissions are blocked in your browser settings for http://localhost:3000.
   • OS Level: On macOS or Linux, your terminal, browser (Chrome/Firefox/Brave), or Wayland session might not have permission to access the camera/mic.

2. Geolocation (navigator.geolocation.getCurrentPosition or watchPosition)

   • Location access was denied or your browser/system has location services disabled.

3. Clipboard or Persistent Storage (navigator.clipboard.writeText / navigator.storage.persist())

   • The browser requires an active user gesture (like an explicit click) or blocks clipboard write when the tab/window is not focused.

---

How to fix it

1. Check the Browser Address Bar:

   • Look at the left side of your browser's address bar (the tune/padlock/site settings icon next to http://localhost:3000).
   • Check if Camera, Microphone, or Location shows "Blocked".
   • Change them to "Allow" (or reset permissions) and refresh the page.

2. System Permissions (OS):

   • Ensure your operating system gives your browser permission to access camera, mic, and location.

3. Fallback:

   • For photos, clicking "Choose a photo instead" or the file picker will bypass live camera streaming and work without camera hardware permissions.

1. Audio Chimes Enabled by Default

• In lib/db.ts, updated DEFAULT_SETTINGS.soundEnabled from false to true.
• Any fresh installation or user profile now has Cuelume's major-third confirmation bell (playCaptureChime) and victory fanfare (playHuntChime) enabled out of the box (still toggleable in /settings).

---

2. Loose Ends Audit & Report

Area	Status	Verification Detail
Gemma Anti-Degeneration	✅ Clean	Tested via scripts/test-gemma-enhancements.ts. Loops, token artifacts (ueff_, exp_\d), and repetition loops are intercepted on API routes and defensively sanitized in the UI.
Voice Notes & TTS	✅ Clean	Audio notes use ElevenLabs Scribe for transcription. Epilogue & Walk Dispatch are generated as pure text (TTS removed as requested).
Walk Resizer & Map Canvas	✅ Clean	Horizontal panel resizer in landscape/desktop is styled as a sleek hairline divider with a floating pill handle; ResizeObserver automatically reflows MapLibre GL.
TODO / FIXME Check	✅ Zero	No dangling TODO or FIXME comments anywhere in app/, components/, hooks/, or lib/.
TypeScript Typecheck	✅ 0 Errors	pnpm tsc --noEmit exits cleanly with code 0.
Production Build	✅ 0 Errors	pnpm build creates all 21 static and dynamic routes cleanly under Turbopack.

---

3. Deployment Preparation

1. Environment Variables Template (.env.example): Created and committed with documentation for required keys:

   • GOOGLE_GENERATIVE_AI_API_KEY (Gemini / Gemma 4 vision identification, sensory prompts & dispatch)
   • IDENTIFY_MODEL_ID=gemma-4-26b-a4b-it / FACTS_MODEL_ID=gemma-4-26b-a4b-it
   • ELEVENLABS_API_KEY (voice note transcription)
   • ORS_API_KEY (OpenRouteService loop route generation)
   • UPSTASH_REDIS_REST_URL & UPSTASH_REDIS_REST_TOKEN (Optional: distributed rate limiting, falls back to in-memory in single-instance)

2. Deploying (Vercel / Cloud Run / Node Server):

   • Vercel / Next.js hosting: Import the repository, add the environment variables from .env.example, and deploy using the standard preset (pnpm build).
   • Docker / Node: Run pnpm build && pnpm start. Ensure HTTPS is enabled in production so browser permissions (getUserMedia, geolocation, storage.persist()) are fully granted by user agents.