How do I create a new doc?

projects/ores.codegen/generate_doc.sh \
  --type task --slug fix_broken_link \
  --parent-dir doc/agile/versions/v0/sprint_17/audit_tooling \
  --title "Fix broken id-links surfaced by audit" \
  --description "Audit reports two unresolved id-links; fix them." \
  --tags "audit,bug_fix"

Parent story info is auto-detected from doc/agile/versions/v0/sprint_17/audit_tooling/story.org.

Add --predecessor-id and --predecessor-title. The script renders #+predecessor: in the frontmatter and a Continued from: line in the body:

projects/ores.codegen/generate_doc.sh \
  --type story --slug currencies_temporal_continued \
  --parent-dir doc/agile/versions/v0/sprint_17 \
  --title "Currencies temporal (continued)" \
  --description "Pick up where sprint 02 left off." \
  --tags "currencies,temporal,reference_data" \
  --predecessor-id ed5bc735-fb54-4ce0-9a08-6dab88c242d0 \
  --predecessor-title "Currencies temporal and export"

After the script runs, manually update the predecessor story: add #+successor: <new-uuid> to its frontmatter and a Continued in: [[id:<new-uuid>][...]] note in its * Decisions section.

Component overview files are always named component_overview.org. Use --slug component_overview (not the component name):

./projects/ores.compass/compass.sh add component \
  --slug component_overview \
  --parent-dir projects/ores.example/modeling \
  --title "ores.example" \
  --description "One-line summary of what the component does." \
  --tags "example,component"

Output: projects/ores.example/modeling/component_overview.org. See How do I create a component overview? for how to fill in each section.

Use the how_do_i_<thing> slug convention. The output is <parent-dir>/how_do_i_<thing>.org:

./projects/ores.compass/compass.sh add recipe \
  --slug how_do_i_clear_the_cache \
  --parent-dir doc/recipes/cmake \
  --title "How do I clear the cache?" \
  --description "Remove the CMake binary cache to force a clean re-configure." \
  --tags "cmake,build,recipe"

Scaffold with content — the body sections can be supplied as arguments (verbatim org markup; multi-line via $(printf ...) or shell $'...' quoting) so the recipe is born complete instead of with placeholder text:

• --intro — lead paragraph before * Question;
• --question — the * Question body;
• --answer — the * Answer body (include the #+begin_src block);
• --script — the * Script body;
• --tested-by — the * Tested by body;
• --see-also — one * See also bullet (repeatable).

Sections not supplied fall back to the fill-in placeholders.

When the recipe's * Answer involves a shell command, write it in an #+begin_src sh :results verbatim block so the recipe is executable in emacs (C-c C-c) — see How do I list available presets? for an example that also captures a #+RESULTS: snapshot.

Use compass add manual. The slug should follow the chapter_<N>_<topic> convention. --parent-dir defaults to doc/manual/user_guide and can be omitted. Headings inside the chapter start at ** (level 2); they become \section in the PDF. After creating, add a #+include line in user_manual.org and an entry in user_manual_site.org.

./projects/ores.compass/compass.sh add manual \
  --slug chapter_4_reference_data \
  --title "Reference Data" \
  --description "Reference data management in ORE Studio: currencies, countries, and other slowly-changing financial master data." \
  --tags "manual,reference_data,user_guide"

Use compass add skill. The slug must be snake_case; it becomes the folder name and the name: field in the skill's markdown frontmatter. --parent-dir defaults to doc/llm/skills and can be omitted:

./projects/ores.compass/compass.sh add skill \
  --slug my_new_skill \
  --title "My New Skill" \
  --description "When and how to use the new skill."

Output: doc/llm/skills/my_new_skill/SKILL.org.

After filling in the skill body, rebuild the shipped bundle so Claude Code picks up the change — see How do I deploy the skills?:

./compass.sh build --direct skills

There is one product identity document per product (product_identity.org under doc/identity/). The codegen scaffolds a fresh one — useful mostly when bootstrapping a new product or migrating an existing identity from scratch.

projects/ores.codegen/generate_doc.sh \
  --type product_identity --slug product_identity \
  --parent-dir doc/identity \
  --title "ORE Studio product identity" \
  --description "The durable statement of what ORE Studio is and is not." \
  --tags "identity,vision"

Investigation reports live in doc/investigations/. They are formal records of technical research or debugging sessions.

projects/ores.codegen/generate_doc.sh \
  --type investigation --slug msvc_c1202_rfl_complexity \
  --parent-dir doc/investigations \
  --title "MSVC C1202 and rfl complexity" \
  --description "Root cause analysis of recursive template depth limits in reflect-cpp." \
  --tags "msvc,cpp,reflect_cpp,investigation"

Captures live in doc/agile/product_backlog/ across four buckets: inbox/ (untriaged), next/ (upcoming candidate), deferred/ (long-horizon), discarded/ (explicitly rejected).

The preferred way to file a new capture is compass capture, which lands the file in inbox/ automatically:

projects/ores.compass/compass.sh capture --note "Add an uptime screen"

To create directly in a specific bucket via codegen:

projects/ores.codegen/generate_doc.sh \
  --type capture --slug add_uptime_screen \
  --parent-dir doc/agile/product_backlog/next \
  --title "Add an uptime screen" \
  --description "Surface live service health in the Qt UI." \
  --tags "ui,observability"

The bucket name is derived from --parent-dir basename and appears in the generated blurb automatically.

Memories live under doc/llm/memory/. Pass --memory-subtype to pick the kind of memory (feedback / user / project / reference — default feedback). The memory filetag is auto-injected so the catalogue is greppable.

projects/ores.codegen/generate_doc.sh \
  --type memory --slug do_not_re_export_env_vars \
  --parent-dir doc/llm/memory \
  --title "Do not re-export ORES_* env vars in Bash tool calls" \
  --description "The user already exports them; prepending is noise." \
  --memory-subtype feedback

For the LLM-side decision flow (when to write vs push back), see the doc-add-memory skill; for the standalone recipe with body conventions, see How do I create a memory?.

When creating multiple documents that will link to each other (e.g. a knowledge doc and several component overviews that reference it), the correct order is:

1. Generate all skeleton files first. Each call mints a fresh UUID. Do not pre-assign or guess UUIDs before running the script — they will not match.

   projects/ores.codegen/generate_doc.sh --type knowledge ...
   projects/ores.codegen/generate_doc.sh --type component --slug component_overview ...
   projects/ores.codegen/generate_doc.sh --type component --slug component_overview ...
   

2. Collect the generated IDs.

   grep "^:ID:" projects/ores.foo/modeling/component_overview.org \
                doc/knowledge/topic/my_knowledge.org
   

3. Fill in the content of each file, using the actual IDs in [[id:UUID][label]] links.

The --id flag is for migration only — preserving an existing UUID when reformatting a document that already has one. Never use it to pre-assign an ID to a brand-new document.