# 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

```sh
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:

```sh
# 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

```sh
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.