Doc Sync Recipes

When the user asks you to refresh the recipes for a topic — CLI, HTTP, shell, SQL, cmake, etc. — because the source has drifted. Symptoms:

• The user added commands, routes, or scripts and the recipes do not yet describe them.
• An existing command/route/script has changed signature and the recipe is stale.
• A capability has been removed and the recipe still references it.

The procedure is the same across topics. Only the source-of-truth location changes.

1. Pick the topic and identify its source. Common topics in this repo:

   Topic	Source-of-truth	Recipe folder
   cli	projects/ores.cli/src/config/entity_parsers/	doc/recipes/cli/
   http	projects/ores.http.core/src/routes/ (and ores.http.api)	doc/recipes/http/
   shell	projects/ores.shell/src/app/commands/	doc/recipes/shell/
   sql	projects/ores.sql/schema/	doc/recipes/sql/
   cmake	CMakeLists.txt + presets in CMakePresets.json	doc/recipes/cmake/
   git	(none — convention-only)	doc/recipes/git/
   github	gh CLI capabilities + this repo's PR/CI conventions	doc/recipes/github/

   For any other topic, read the topic's doc/recipes/<topic>/<topic>.org inventory to see what is currently documented.

2. Enumerate what the source actually provides. Use whichever pattern fits — parser registries, route tables, command tables. Produce a flat list of things the recipe set should cover.

3. Enumerate the current recipes for the topic:

   ./projects/ores.compass/compass.sh list \
       --tag <topic> --type recipe --sort path
   

4. Diff. Bucket each item:
   • In source but not in recipes → missing, schedule new recipe.
   • In recipes but not in source → retired, schedule deletion.
   • In both, but with drift → stale, schedule update.
5. Apply changes, one at a time:
   • New recipe → scaffold via How do I create a new doc? §"New recipe", then write the body per How do I create a recipe?. The filename, #+title:, and * Question must all agree as the same NLP question.
   • Retired recipe → git rm the file, remove its row from the topic inventory.
   • Stale recipe → bump #+updated: when you fix the body; for non-trivial drift, also refresh the * Answer example output.
6. Sync the inventory. Open doc/recipes/<topic>/<topic>.org and make sure every recipe in the folder appears, grouped under a sensible sub-heading.

• How do I create a new doc? — scaffold a new recipe file.
• How do I create a recipe? — body conventions, question form, executable babel blocks.
• How do I find docs matching a pattern? — enumerate the recipes currently in a topic.
• How do I show a doc by UUID? — inspect a single recipe to see what it currently claims.

• Recipe (glossary) — the contract.
• Recipes — the top-level inventory listing every topic.
• Document types§=recipe= — required sections and conventions.