FarmAgent · FruitScout
Internal · Engineering
Project Context

The knowledge base that gets agents & new engineers productive fast.

A small set of curated, plain-Markdown docs that answer the questions you actually hit while working — what a service does, where data lives, how to deploy, which secret to use, who owns what. Built to be read by AI coding agents and humans, on demand.

Lives at FarmAgent2-Workspace/context/ · plain .md · the first thing every session reads.

1
Read the README first — then load only what your task needs.

The index tells you which doc answers which question. Don't pull all of them into context up front; open the one that matches what you're doing right now.

The doc map

Fourteen docs, each with a "load when…"

Every doc earns its place by answering a recurring question. The README carries this same table — here it is, grouped by what you're trying to do.

Start here
README.mdAlways first. What the project is, the doc index, the 3 GCP projects, and the Hard Wall rule.
stage.mdRead second at session start — sets the current lifecycle stage so work matches where the product actually is.
Architecture & data
components.mdYou need to know how a component works, where its repo is, or how it deploys.
data-model.mdAny DB, schema, or ETL work — read it before writing a single query. Now includes the Cloud-SQL-proxy connect recipe.
models.mdThe CV/ML models (Agave Inventory, Visual Scale) — architecture + the data each was trained on.
Build & ship
deploy.mdYou're deploying anything — the per-component cheat sheet + VM details.
workflows.mdYou need step-by-step guidance for a common task (deploy, accept a field, release mobile…).
monitoring.mdYou need to check if a service is healthy or investigate errors.
incident.mdSomething is broken in production. The runbook.
Resources & access
gcs-buckets.mdYou need to read from or write to GCS — which bucket, who reads/writes.
secrets.mdYou need a secret name, or to understand who has access to what.
Domain & people
glossary.mdA stakeholder used an agave/farm term you don't recognise (piña, quiote, cuadrilla…).
terminology.mdYou're building customer-specific UI copy, reports, or queries (Herradura "Fraction" vs Sauza "Plot").
team.mdYou need to know who owns a component or who to ask.
Health & rules of thumb
tech-debt.mdYou hit a bug that seems systemic, or want to know what's already known-broken.
habits.mdYou want a quick rules-of-thumb refresh, or something feels off.
How it stays useful

Five conventions that keep it trustworthy

Load on demand

The README is the router. Open the one doc your task needs — don't front-load all fourteen. Keeps context lean and answers precise.

Trust code over prose

Docs can lag reality. When a doc and the code disagree, the code wins — e.g. derive DB truth from connection.py/config.py, not a README sentence. Docs flag their own stale spots.

Project vs. personal

Machine-specific details (local proxy ports, your boxes) live in a separate personal ~/context/local-systems.md — so the project docs stay portable and shareable.

The Hard Wall

The one rule everything else respects: FarmAgent services connect only to the digital_twin DB. Pipeline tools are the producers. data-model.md has the diagram.

A living system

It's maintained as the product moves. Recent additions: models.md (the CV/ML models + training data) and the DB connect-recipe in data-model.md. When you learn something the hard way, write it down here.

Written for two readers

Every doc is pitched so an AI agent and a new engineer both get unblocked — concrete, specific, with the "why," not just the "what."

How an agent (or new hire) actually uses it

01

Orient

Session starts → read README.md, then stage.md. Now you know the shape of the system and where it is in its lifecycle.

02

Route to the task

About to touch the DB? Open data-model.md. Deploying? deploy.md. Hit a farm term? glossary.md. The index points you.

03

Act with the "why"

Each doc gives constraints + rationale, so the work fits the real system the first time — fewer wrong turns, fewer prod surprises.

AGENTS.md makes the first two steps mandatory at session start — the context system is wired into how every agent boots.

Quick reference

The three GCP projects

prod
fruit-scout-production

FarmAgent2 VM, the Digital Twin DB, Task API, Visual Scale.

pipeline
glass-hydra-267318

Anno Tool, drone ML pipeline, CVAT, legacy Composer.

ds-sandbox
datascience-8675309

DS analysis, prod→DS sync, Visual Scale sandbox.