formulation/docs/agent-handoff.md

Agent handoff

Repository state

Development happens on dev; master is the deployable integration branch. Use Node.js 22 or newer and install dependencies with npm ci.

SQLite is the canonical writable store. YAML in culinary/ is portable seed and interchange data, not the live editing surface. Application and automated edits should use validated domain functions and transactions rather than unrestricted SQL or direct YAML changes.

Database Management

SQLite (var/recipe-book.sqlite) is the canonical writable store. Application and automated edits must use validated domain functions and transactions rather than direct YAML changes or unrestricted SQL.

Starting the Application

npm ci
npm run dev:app

Backups and Transfers

The runtime database lives under var/, which is intentionally ignored by Git.

To backup or hand off the current live state:

# Export full JSON backup
npm run db:backup -- var/recipe-book-backup.json

# Restore database from backup on receiving machine
npm run db:restore -- var/recipe-book-backup.json

Place the transferred file at var/recipe-book.sqlite on the receiving machine. The backup command uses SQLite's online backup API, includes committed WAL data, and refuses to overwrite an existing destination.

Validate a change

scripts/validate-content
npm run check:app
npm test
npm run build:app
git diff --check

The application supports a read-only deployment with FORMULATION_READ_ONLY=true. Ingredient bulk parsing additionally accepts FORMULATION_OLLAMA_URL and FORMULATION_INGREDIENT_PARSER_MODEL; USDA imports read USDA_FDC_API_KEY from the environment.