Canonical version 2 culinary data lives in culinary/ and is defined by the vendor-neutral schemas in container/schemas/v2/. Two independent Astro applications consume the shared data and libraries; see the culinary data model for entity boundaries, density and unit semantics, and USDA provenance.

Knowledge Sync

The Gitea Actions workflow at .gitea/workflows/sync-knowledge.yml exports the recipes as clean Markdown and synchronizes them to the Gourmand Open WebUI knowledge base. It runs when recipe content, ingredient data, or the corpus exporter changes on master, and it can also be started manually.

Configure these Actions variables in this repository:

OPEN_WEBUI_URL
GOURMAND_KB_ID

Configure this Actions secret:

KNOWLEDGE_SYNC_OPEN_WEBUI_API_KEY

The existing knowledge-sync account and API key may be reused if the account has permission to manage files in the Gourmand knowledge base.

To inspect the generated corpus locally, run:

scripts/corpus-export

Validate canonical entities, schema conformance, and cross-references before building or committing changes:

python3 -m pip install --user -r requirements-dev.txt
scripts/validate-content

To review purchasing products extracted from the sibling ledger receipt archive, run scripts/receipt-products propose and open /tools/purchasing-review/. Export the decisions and apply them with:

scripts/receipt-products apply ~/Downloads/purchasing-decisions.json
scripts/validate-content

Build both applications:

npm ci
npm run db:reset # initial setup only; do not use over an edited database
npm run build

The frontend requires Node.js 22.12 or newer. The public cooking site is a fully static build in dist/site; the SQLite-backed management application is a Node server build in dist/app. They share components and culinary calculation code, but neither artifact contains the other application's routes. The site build generates a read-only projection from SQLite before Astro renders its pages.

Run them independently during development:

npm run dev:site  # http://localhost:4321
npm run dev:app   # http://localhost:4322/app/

The generated files are written to generated/open-webui/recipes/ and are not committed.

Search USDA FoodData Central and import a candidate mapping with:

USDA_FDC_API_KEY=... scripts/usda-fdc search "all-purpose flour"
USDA_FDC_API_KEY=... scripts/usda-fdc import flour_all_purpose 790018

Add --reviewed only after confirming that the USDA description matches the canonical ingredient. An official USDA JSON download can be supplied with --dataset instead. Never commit the API key.