Here is a complete, detailed setup and run guide for Treads.

🌿 Treads — Setup & Run Guide

Treads is a local-first naturalist companion built with Next.js 16 (App Router), React 19, Tailwind CSS v4, Dexie (IndexedDB), and MapLibre GL.

1. Prerequisites

Make sure the following tools are installed on your machine:

Node.js: v20.x or v22+ recommended
Package Manager: pnpm (preferred)
Modern Web Browser: Chrome, Edge, Firefox, or Safari (supporting IndexedDB, Web Audio API, and Geolocation)

2. Clone & Install Dependencies

Navigate to the project root:
Install all dependencies using pnpm:

3. Environment Configuration

Create a local environment configuration file:

Add the following keys to your .env.local:

[!NOTE] In local development, the app can function with mock/fallback behavior if some API keys are not supplied immediately, but full AI identification, loop routing, and speech require their respective keys.

4. Running the Development Server

Start the local Next.js dev server with Turbopack:

Open your browser and navigate to: http://localhost:3000

5. First-Time Walkthrough & Browser Permissions

When opening the app for the first time:

Privacy Gate & Storage Consent: Grant permission for local-first persistent storage (navigator.storage.persist()) when prompted.
Location Permission: Allow browser Geolocation access so MapLibre GL can plot your outdoor tracks and create pedestrian loops.
Microphone Permission: Allow microphone access when recording audio notes on observations.

6. Running Scripts & Test Suites

The project comes with test scripts and evaluation runners:

Run the AI Headless Evaluation Benchmark

Validates the 30-fixture taxonomic identification accuracy (≥70%) and refusal detection (≥90%):

Export Engine Verification

Verify that the Obsidian vault zip exporter works with IndexedDB:

Code Quality & Linting

(Or use fallow for dead code and dependency analysis).

7. Production Build & Execution

To test a production-optimized build:

8. Key Project Architecture Reference

Directory / File	Description
`app/`	Next.js App Router pages and `/api` endpoints (`identify`, `facts`, `route`, `speak`, `transcribe`, `eval`)
`components/`	UI components (Tegaki handwriting animations, MapLibre map, capture dialog, recorder)
`lib/db.ts`	Dexie IndexedDB models (`walks`, `observations`, `photos`, `breadcrumbs`)
`lib/audio/cuelume.ts`	Web Audio API dual-oscillator synthesizer soundscapes and chimes
`scripts/run-eval-suite.ts`	Headless evaluation benchmark
`FIELD-VERIFICATION.md`	8-step outdoor field testing and verification checklist