docs: consolidate product thesis into single vision.md

.gitignore

@@ -16,6 +16,7 @@ Thumbs.db
 # IDE
 .idea/
 .vscode/
+.codex/
 *.swp
 *.swo
 

CONTRIBUTING.md

@@ -1,6 +1,6 @@
 # Contributing to OpenPasture
 
-Thanks for helping improve OpenPasture! This project focuses on the Morning Farm Brief experience and adaptive grazing intelligence.
+Thanks for helping improve OpenPasture! See [docs/vision.md](docs/vision.md) for the product thesis before diving in.
 
 ## Table of Contents
 
@@ -42,13 +42,13 @@ npm install
 
 ### 2. Configure Environment
 
-Copy the example environment file:
+Copy the app example environment file:
 
 ```bash
-cp .env.example .env.local
+cp app/.env.example app/.env.local
 ```
 
-Edit `.env.local` with your values:
+Edit `app/.env.local` with your values:
 
 ```bash
 # Convex - Get from your Convex dashboard
@@ -62,6 +62,14 @@ VITE_CLERK_PUBLISHABLE_KEY=pk_test_your_key_here
 VITE_DEV_AUTH=true
 ```
 
+If you work on ingestion/pipeline code, also copy:
+
+```bash
+cp src/ingestion/.env.example src/ingestion/.env.local
+```
+
+For the complete env matrix (including Convex Dashboard server-side vars like `ANTHROPIC_API_KEY`), see [docs/environment.md](docs/environment.md).
+
 ### 3. Set Up Convex
 
 If you haven't already, create a Convex project:

README.md

@@ -1,26 +1,6 @@
 # OpenPasture
 
-An open-source intelligence and orchestration layer for adaptive grazing. This system translates satellite-derived land signals into clear daily grazing decisions.
-
-## Overview
-
-Grass is dynamic. Fences are static. Modern sensing allows us to understand land conditions daily - what's been missing is software that turns those signals into actionable guidance.
-
-This project provides the **decision-making brain** that tells farmers:
-
-> "Here is the current state of your land, and here is the best grazing action for today."
-
-## The Morning Farm Brief
-
-The core experience is a daily ritual:
-
-1. **Open the app** each morning
-2. **Receive a status report** on your farm's pasture conditions
-3. **Review the recommended grazing plan** for today
-4. **Approve or adjust** using natural language feedback
-5. **Get execution instructions** ready for your virtual fencing system or manual workflow
-
-This is decision support - you stay in control.
+An open-source intelligence layer for adaptive grazing. See [docs/vision.md](docs/vision.md) for the thesis and product philosophy.
 
 ## Features
 
@@ -57,8 +37,6 @@ We use publicly available satellite imagery (primarily Sentinel-2) to compute ve
 - Frequent revisits (daily to every few days)
 - Historical archive for trend analysis
 
-Satellite cadence aligns with biological reality - grazing decisions are daily or multi-day decisions, not minute-by-minute.
-
 ### Vegetation Indices
 
 | Index | Purpose |
@@ -77,17 +55,6 @@ Satellite cadence aligns with biological reality - grazing decisions are daily o
 6. Score pasture readiness using transparent rules
 7. Generate recommendation with confidence level
 
-## What This Is Not
-
-To maintain focus, this demo does not include:
-
-- Real-time livestock tracking
-- Custom hardware or collars
-- Automated fence actuation
-- Drone-based sensing
-
-These are future integration points, not current scope.
-
 ## Getting Started
 
 The web app lives in `app/`. Prerequisites: Node.js 18+ and npm.
@@ -107,11 +74,22 @@ Common scripts:
 
 ### Environment Variables
 
-The following environment variables are required for full functionality:
+Environment setup is documented in [docs/environment.md](docs/environment.md).
+
+Quick start:
+
+```bash
+cp app/.env.example app/.env.local
+cp src/ingestion/.env.example src/ingestion/.env.local
+```
 
-- `BRAINTRUST_API_KEY` - API key for Braintrust observability platform. Required for agent behavior tracking and debugging. Get your API key from [Braintrust](https://www.braintrust.dev). Set this in your Convex dashboard environment variables for production, or in `.env.local` for local development.
+Set server-side keys (for Convex backend actions) in Convex Dashboard environment variables:
 
-  Without this key, agent logging will be disabled but the application will continue to function.
+- `ANTHROPIC_API_KEY` (required for AI recommendations)
+- `BRAINTRUST_API_KEY` (optional observability)
+- `BRAINTRUST_PROJECT_NAME` (optional, defaults to `grazing-agent`)
+- `GITHUB_TOKEN` (optional, enables GitHub issue creation from reports)
+- `CONVEX_DEBUG` (optional backend debug logging)
 
 ## Tech Stack
 
@@ -132,6 +110,7 @@ The following environment variables are required for full functionality:
 │   ├── src/
 │   └── ...
 ├── docs/
+│   ├── vision.md          # Thesis and product philosophy
 │   ├── architecture.md    # Technical architecture details
 │   ├── domain.md          # Remote sensing domain knowledge
 │   └── phasing.md         # Development phases
@@ -140,9 +119,11 @@ The following environment variables are required for full functionality:
 
 ## Documentation
 
-- [Development Phasing](docs/phasing.md) - How we build this incrementally
+- [Vision](docs/vision.md) - Thesis and product philosophy
 - [Technical Architecture](docs/architecture.md) - System design and data flow
 - [Domain Knowledge](docs/domain.md) - Remote sensing and vegetation science primer
+- [Development Phasing](docs/phasing.md) - How we build this incrementally
+- [Environment Setup](docs/environment.md) - Required and optional variables by runtime
 
 ## Contributing
 
@@ -156,6 +137,3 @@ If you discover a vulnerability, see [SECURITY.md](SECURITY.md).
 
 Licensed under the Apache License, Version 2.0. See [LICENSE](LICENSE) and [NOTICE](NOTICE).
 
----
-
-*OpenPasture - Building the intelligence layer for regenerative grazing.*

agents.md

@@ -3,23 +3,7 @@
 > This file is the primary reference for AI agents working on this codebase.
 > Read this first before making any changes.
 
-## What This Project Is
-
-A **daily decision intelligence system for adaptive grazing**, powered by satellite data and human-in-the-loop AI. The core product is called the **Morning Farm Brief** - a daily ritual where farmers receive land status and recommended grazing actions.
-
-**Core thesis:** Grass is dynamic, fences are static. Satellite sensing lets us understand land conditions daily. We build the software brain that translates land signals into clear daily grazing decisions.
-
-## What This Project Is NOT
-
-Do not build or propose:
-- Livestock collar integration or firmware
-- Real-time livestock tracking/movement
-- Custom hardware
-- Automated actuation systems
-- Drone-based sensing
-- Real-time autonomous herding
-
-This is a **decision support system**, not an automation or control system.
+For the product thesis and philosophy, read [docs/vision.md](docs/vision.md) first.
 
 ## Core User Flow
 
@@ -118,14 +102,6 @@ These rules are intentionally simple and explainable for farmer trust.
 - **Format:** Cloud-Optimized GeoTIFFs (COGs)
 - **API:** STAC (SpatioTemporal Asset Catalog)
 
-## Design Principles
-
-1. **Plain language over charts** - Briefs should read like a farmer talking to a farmer
-2. **Transparency over magic** - Show assumptions and confidence, not black box scores
-3. **Daily cadence is sufficient** - Satellite refresh aligns with biological reality
-4. **Cloud cover is manageable** - Use rolling composites and multiple sources
-5. **Collar-agnostic output** - Generate geometry and copy-ready instructions, no direct integration
-
 ## File Structure Convention
 
 ```
@@ -144,13 +120,6 @@ These rules are intentionally simple and explainable for farmer trust.
 └── ...
 ```
 
-## Success Metrics
-
-The demo succeeds when:
-- A farmer says: "This matches how I think about my land."
-- An investor says: "This has a clear wedge and expansion path."
-- A collar company says: "This would make our product more valuable."
-
 ## Questions to Ask Before Building
 
 1. Does this feature support the Morning Farm Brief flow?

app/.env.example

@@ -1,17 +1,14 @@
 # =============================================================================
-# Convex Configuration
+# App Runtime (Vite, read from app/.env.local)
 # =============================================================================
-# Get your Convex URL from the Convex dashboard after setting up your project
+# REQUIRED
+# Where used: app/src/main.tsx
+# Acquire: Convex Dashboard -> Deployments -> Settings -> URL and Deploy Key
 VITE_CONVEX_URL=https://your-project.convex.cloud
 
-# Convex deploy key (for server-side API calls)
-# Generate from Convex dashboard → Settings → Deploy Keys
-CONVEX_DEPLOY_KEY=prod:your_deploy_key_here
-
-# =============================================================================
-# Clerk Authentication
-# =============================================================================
-# Get from Clerk dashboard → API Keys
+# OPTIONAL when using development auth bypass.
+# Where used: app/src/lib/auth/index.tsx
+# Acquire: Clerk Dashboard -> API Keys -> Publishable key (pk_test_* or pk_live_*)
 VITE_CLERK_PUBLISHABLE_KEY=pk_test_your_key_here
 
 # Clerk JWT template required by ConvexProviderWithClerk.
@@ -28,14 +25,14 @@ CLERK_WEBHOOK_SECRET=whsec_your_webhook_secret_here
 # Example with custom Clerk domain: https://clerk.themodernstrategy.com
 CLERK_JWT_ISSUER_DOMAIN=
 
-# =============================================================================
-# Development Mode
-# =============================================================================
-# Set to "true" to bypass Clerk auth during local development
+# OPTIONAL, defaults to false.
+# Where used: app/src/lib/auth/index.tsx and demo onboarding routes
+# true = bypass Clerk auth locally
 VITE_DEV_AUTH=false
 
-# Set to "true" to disable the subscription paywall (useful for dev)
-# Paywall is enabled by default in production
+# OPTIONAL, defaults to false.
+# Where used: app/src/routes/app.tsx and app/src/routes/subscribe.tsx
+# true = disable subscription paywall checks
 VITE_PAYWALL_DISABLED=false
 
 # =============================================================================
@@ -48,9 +45,29 @@ VITE_POSTHOG_KEY=phc_your_project_api_key
 VITE_POSTHOG_HOST=https://us.i.posthog.com
 
 # =============================================================================
-# Braintrust Observability (Optional)
+# Convex Server Runtime (set in Convex Dashboard env vars, not Vite-exposed)
 # =============================================================================
-# For agent tracing and observability
-# Get from Braintrust dashboard → Settings → API Keys
+# REQUIRED for AI recommendations in Convex actions.
+# Where used: app/convex/grazingAgentDirect.ts via Anthropic SDK
+# Acquire: Anthropic Console -> API Keys
+ANTHROPIC_API_KEY=sk-ant-api03-your-key-here
+
+# OPTIONAL observability.
+# Where used: app/lib/braintrust.ts
+# Acquire: Braintrust Settings -> Organization -> API keys
 BRAINTRUST_API_KEY=your_braintrust_api_key
+
+# OPTIONAL, defaults to "grazing-agent" if omitted.
+# Where used: app/lib/braintrust.ts
 BRAINTRUST_PROJECT_NAME=grazing-agent
+
+# OPTIONAL, enables automatic GitHub issue creation from bug/feature reports.
+# Where used: app/convex/bugReportsAction.ts and app/convex/featureRequestsAction.ts
+# Acquire: GitHub -> Settings -> Developer settings -> Personal access tokens
+# Recommended: fine-grained token with Issues: Read and write on this repository.
+GITHUB_TOKEN=github_pat_your_token_here
+
+# OPTIONAL, defaults to false.
+# Where used: app/convex/lib/logger.ts
+# true = enable debug/info logging in Convex backend logger
+CONVEX_DEBUG=false

app/CLAUDE.md

@@ -4,7 +4,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Project Overview
 
-OpenPasture - an open-source AI-powered decision support system that translates satellite-derived vegetation data into daily grazing recommendations. The core experience is a "Morning Farm Brief" that recommends which pasture to graze today.
+OpenPasture - an open-source adaptive grazing intelligence platform. See [docs/vision.md](../docs/vision.md) for the product thesis.
 
 ## Commands
 

app/README.md

@@ -13,13 +13,20 @@ npm run dev
 
 ## Environment
 
-Required env vars (set in `app/.env.local`):
+Copy and fill the app env template:
 
-- `VITE_CONVEX_URL` - Convex deployment URL
-- `VITE_DEV_AUTH=true` - bypass Clerk sign-in locally
-- `VITE_CLERK_PUBLISHABLE_KEY` - required when `VITE_DEV_AUTH` is not set
-- `CLERK_JWT_ISSUER_DOMAIN` (or `CLERK_FRONTEND_API_URL`) - Clerk issuer domain used by `convex/auth.config.ts`
-- Clerk JWT template named `convex` with audience `convex` - required for `ConvexProviderWithClerk`
+```bash
+cp .env.example .env.local
+```
+
+Primary app variables:
+
+- `VITE_CONVEX_URL` - required
+- `VITE_DEV_AUTH=true` - optional local auth bypass
+- `VITE_CLERK_PUBLISHABLE_KEY` - required when `VITE_DEV_AUTH=false`
+- `VITE_PAYWALL_DISABLED=true` - optional local paywall bypass
+
+Server-side Convex variables (`ANTHROPIC_API_KEY`, `BRAINTRUST_API_KEY`, etc.) are documented in [docs/environment.md](../docs/environment.md) and should be set in Convex Dashboard env vars.
 
 ## Scripts
 

app/index.html

@@ -4,39 +4,35 @@
     <meta charset="UTF-8" />
     <link rel="icon" type="image/svg+xml" href="/vite.svg" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <meta name="description" content="Get daily land status reports and grazing recommendations powered by Sentinel-2 satellite imagery. Decision support for adaptive grazing." />
+    <meta name="description" content="AI grazing recommendations that predict what a trained farmer would do. Daily movement plans from satellite imagery and grazing science. Open source." />
     <meta name="keywords" content="openpasture, adaptive grazing, satellite imagery, NDVI, farm management, grazing recommendations, Morning Farm Brief" />
 
     <!-- Open Graph / Facebook -->
     <meta property="og:type" content="website" />
-    <meta property="og:title" content="OpenPasture | AI-Powered Adaptive Grazing" />
-    <meta property="og:description" content="Get daily land status reports and grazing recommendations powered by Sentinel-2 satellite imagery. Decision support for adaptive grazing." />
+    <meta property="og:title" content="OpenPasture | Predict What a Trained Farmer Would Do" />
+    <meta property="og:description" content="AI grazing recommendations that predict what a trained farmer would do. Daily movement plans from satellite imagery and grazing science. Open source." />
 
     <!-- Twitter -->
     <meta name="twitter:card" content="summary_large_image" />
-    <meta name="twitter:title" content="OpenPasture | AI-Powered Adaptive Grazing" />
-    <meta name="twitter:description" content="Daily grazing decisions powered by satellite intelligence. Get your Morning Farm Brief." />
+    <meta name="twitter:title" content="OpenPasture | Predict What a Trained Farmer Would Do" />
+    <meta name="twitter:description" content="Daily movement recommendations from satellite imagery and grazing science. Predict what a trained farmer would do -- every morning, every paddock." />
+
+    <title>OpenPasture | Predict What a Trained Farmer Would Do</title>
 
-    <title>OpenPasture | AI-Powered Adaptive Grazing</title>
-
     <!-- Structured Data -->
     <script type="application/ld+json">
     {
       "@context": "https://schema.org",
       "@type": "SoftwareApplication",
-      "name": "Morning Farm Brief",
+      "name": "OpenPasture",
       "applicationCategory": "FarmManagementApplication",
-      "description": "Daily grazing decisions powered by satellite intelligence. Get land status reports and grazing recommendations for adaptive grazing.",
-      "offers": {
-        "@type": "Offer",
-        "price": "0",
-        "priceCurrency": "USD"
-      },
+      "description": "AI grazing recommendations that predict what a trained farmer would do. Daily movement plans from satellite imagery and grazing science.",
       "featureList": [
-        "Daily land status reports",
-        "AI-powered grazing recommendations",
-        "Satellite-derived vegetation health metrics",
-        "Digital farm mapping",
+        "Daily movement recommendations with full reasoning",
+        "NDVI satellite vegetation health by paddock",
+        "Targeted field observation requests",
+        "Farmer feedback learning loop",
+        "Pasture recovery and rest period tracking",
         "Exportable grazing plans"
       ]
     }

app/src/components/marketing/Footer.tsx

@@ -14,7 +14,7 @@ export function Footer() {
                   to="/technology"
                   className="hover:text-cream transition-colors"
                 >
-                  Technology
+                  How It Works
                 </Link>
               </li>
               <li>

app/src/components/marketing/MarketingHeader.tsx

@@ -17,7 +17,7 @@ export function MarketingHeader() {
             to="/technology"
             className="hover:opacity-70 transition-opacity text-muted-foreground"
           >
-            technology
+            how-it-works
           </Link>
           <Link
             to="/investors"