Integration with Every.Farm

Crop Picker is a spinoff project that will fold into the wider Every.Farm ecosystem. This document describes the current state of the relationship and the integration points.

Updated 2026-10-01. The integration model changed. Crop Picker will not hold farm records. It is a cited crop catalog that Every.Farm agents query with a farm's conditions, through /api/v1/recommend, and get back ranked crops with per-criterion evidence. Farm context — fields, soils, topography, equipment, labor — stays canonical on Every.Farm. The phased plan below is kept for history; Phase 2 is built in this form, and Phase 1 (shared auth) is no longer a prerequisite for it.

#Why a spinoff

Crop Picker was built as a focused, public-facing catalog. Shipping it independently:

• Avoids coupling public marketing/SEO content to internal Every.Farm schemas during early iteration
• Lets us move fast on the catalog UX without scheduling around core Every.Farm release cycles
• Gives ag researchers, buyers, and prospective users a low-friction way to explore crop fit without signing up for anything

The long-term goal is to integrate Crop Picker data and UX into Every.Farm's authenticated app — so a logged-in farmer sees crop recommendations scored against their farm's soil/drainage/equipment rather than a generic regional profile.

#Current boundaries

Today these are two independent systems that share a brand and one contract: Every.Farm describes a farm, Crop Picker ranks crops for it.

#What connects them today

• A Crop Picker entry (marked Experimental) in Every.Farm's Plugins drawer opens crops.every.farm in a new tab. Nothing about the farm is sent.
• The Every.Farm API manifest (GET https://api.every.farm/v1) lists every Crop Picker endpoint under relatedApis.cropPicker, with a link to each one's documentation.
• GET https://api.every.farm/v1/docs?api=crops serves this API's documentation by endpoint, and GET https://api.every.farm/v1/crop-picker/openapi.json serves an OpenAPI description of it.
• The Every.Farm MCP server includes Crop Picker tools, which work without a token.
• The prompt copied by Every.Farm's Connect AI agent button points agents at this API.

#The contract: /api/v1/recommend

This is the intended agent workflow. Step 1 is not automated yet: Every.Farm does not hold soil-survey or climate values per field today, so the agent (or the grower) supplies them.

An Every.Farm agent assembling a diversification proposal for a farm:

1. Reads the farm's fields on Every.Farm — soil series (texture, drainage class, slope, aspect from Web Soil Survey), PRISM-derived GDD and frost-free days per field, pH from soil tests, irrigation and cold storage on hand, labor and capital the grower can commit, and what is already planted.
2. Calls /api/v1/recommend once per field (or once per distinct condition set), passing those values and exclude_crops for what is already grown.
3. Receives, per crop, a fit tier, a score over evaluable criteria only, coverage (how much was evaluable and how much of it is cited), gaps (which crop attributes the catalog lacks), and a criteria table with the farm value, the crop value, the verdict and the reason.
4. Reasons over that — across fields, against the grower's goals — and cites evidence_url for anything it recommends, so the grower can read the extension source behind each claim.

Nothing about the farm is stored on Crop Picker. The catalog stays public and read-only; the farm stays private on Every.Farm.

For guilds and alley systems, the engine already uses crop_interactions (companion, nurse, allelopathic, shared-pest relations) and the structural crop attributes (shade_tolerance, canopy_height_ft, root_depth_in) added 2026-10-01 — see Data Model & Schema.

#The farm_* scaffold (superseded)

Crop Picker's database has four user-owned tables that are not exposed anywhere in the UI, are empty, and are no longer the direction — farm context lives on Every.Farm. They may be dropped:

• farm_profiles — per-farm record
• farm_fields — field geometries, soil, drainage
• farm_equipment — owned equipment
• farm_crop_scores — per-farm × per-crop suitability

All four have RLS enabled with zero policies — locked down entirely.

#Original phased plan (historical)

#Phase 1: shared authentication

• Swap Crop Picker's Supabase project to use Every.Farm's auth provider.
• Add authenticated-role SELECT policies to the farm_* tables gated by auth.uid().
• Log-in persists via standard Supabase session; the existing useSupabase() composable picks it up automatically via the Supabase client.

#Phase 2: per-farm scoring — built, as /api/v1/recommend

• Originally: compute the snowflake against a farm profile stored in Crop Picker.
• As built: the farm's conditions are passed as request parameters and crop attributes are evaluated directly against them, with per-criterion verdicts and evidence status. No farm data stored, no auth required. The regional snowflake remains the default for the public UI until it moves to /recommend with region presets.

#Phase 3: buyer matching

• The existing nearby_buyers RPC gets a companion nearby_buyers_for_farm that uses the farm's own geography instead of a picker-provided lat/lng.

#Phase 4: data contract

• A public internal API at api.every.farm/crop-picker/* that proxies Crop Picker data with auth-aware scoring.
• Shared TypeScript types between the two apps so schema changes propagate cleanly.

#Design principles that survive the merger

• Public read-only by default. Even after auth lands, unauthenticated visitors continue to see the regional snowflake and generic catalog. Logged-in users get personalization layered on top; they're not gated behind a wall.
• Audit log stays the provenance system of record. Every data point continues to cite a source, regardless of whose farm is consuming the data.
• SEO-friendly crop pages. The public /crops/:slug pages remain server-rendered and indexable forever; auth is additive.