How do I document an entity?

Before writing a word of the chapter, ask the user which domain-knowledge document(s) — from the Knowledge index, usually a hub note under doc/knowledge/domain/, sometimes an external notebook file outside the repository — the chapter's conceptual section should be sourced from and summarised. Do not guess or invent domain framing from general knowledge — the chapter's authority comes from the project's own knowledge graph. Read the hub note and follow its own * See also links to the individual notes it points to; read each one before deciding what belongs in the chapter and what is out of scope (a hub note is frequently broader than what a single entity's shipped fields warrant — see step 2 below on scoping).

Cross-check whatever the domain notes describe against the entity's actual shipped fields (its ores.<component>.<entity>.org codegen model and, for Qt UI accuracy, its *_field_group.org or detail-fields table). Domain notes are written ahead of implementation and often describe fields that were modelled and then dropped, or that are still future work — never document as current, shipped behaviour anything the entity's own model doesn't actually carry. When in doubt, name the gap explicitly in the chapter's domain section rather than silently omitting or silently including it (see the Currency Pairs chapter's "A word of scope is due before moving on" paragraph on deliverability for the pattern).

Create the chapter under doc/manual/user_guide as chapter_<plural>.org (e.g. chapter_countries.org) — no chapter number in the filename. Ordering lives entirely in user_manual.org's #+include sequence, not the filename, so inserting a new chapter between two existing ones never requires renaming or renumbering anything else:

./compass.sh add manual \
  --slug chapter_<plural> \
  --parent-dir doc/manual/user_guide \
  --title "<Plural>" \
  --description "<Entity> management in ORE Studio: the standard, the Qt UI, history and revert, shell and CLI commands."

The frontmatter follows the exemplars: #+type: manual, #+level: cross, #+filetags: :knowledge:manual:<plural>:refdata:user_guide:, and #+startup: inlineimages so the screenshots render in Emacs.

Every entity chapter is an argument, laid out in the same order. The sections, top to bottom:

1. Abstract — the unlabelled opening paragraph, set with the lettrine drop-cap macro. One paragraph stating what the chapter examines and the ground it covers. It is not headed ** Abstract; it is simply the text before the first heading. Follow it with #+latex: \bigskip to restore the heading gap the lettrine suppresses.

   @@latex:\lettrine[lines=2,nindent=0em]{T}{his} \textsc{chapter} @@@@html:This chapter @@examines the /country/ as a
   reference-data entity in ORE Studio. ...
   
   # Restore the heading gap that the lettrine paragraph suppresses.
   #+latex: \bigskip
   

2. ** Overview — a map of the chapter. It states the argument as a series of steps and walks each section in document order via intra-doc links [[*Section heading][Section heading]], ending by pointing to the Conclusion. Write it as flowing prose, not bullets — "It begins by… From there it… It then… Finally…". This is the one section authors most often get wrong: it is a chapter map, not a summary of the domain.
3. A domain-concepts section (e.g. "Money, currency, and cash", "Currency pairs and market conventions") — the conceptual grounding sourced in step 0, positioned between the Overview and the standard/identity section. Its register is deliberately different from the rest of the chapter: PhD thesis prose, connected paragraphs building an argument, not a definition list. Avoid bullet-heavy structure here even when the source notebook or knowledge doc is itself bulleted — translate bullets into sentences that state a claim, ground it, and move to the next. A single #+BEGIN_EXAMPLE diagram (e.g. a nesting relationship) is acceptable where prose alone cannot carry the structure, but it should be the exception, not the default. This is a standing tone requirement across the whole chapter, not just this section — the body sections below (field tables aside) should also read as prose paragraphs rather than nested bullet lists wherever the content allows it.

4. Body sections — the entity's standard lifecycle, in this order:

   • the standard / identity section (e.g. "ISO 3166-1 and its limitations") — what identifies the entity and the gaps ORE Studio's extensions fill;
   • The <Plural> window — the list view, paging, reloading;
   • <Entity> Details — the detail dialog, one *** subsection per tab (General, Provenance, …);
   • Editing a <entity>, Deleting a <entity>, <Entity> history — change-under-audit, culminating in revert;
   • Shell commands and CLI commands — the programmatic equivalents, if they exist yet for this entity; if they don't, say so explicitly in the Conclusion rather than fabricating commands or silently dropping the sections (see the Currency Pairs chapter's Conclusion for the pattern).

   Segue every section into the next. Do not let the chapter jump from domain concepts straight to identity straight to screens with no bridge. End each section (or open the next) with one transition sentence or short paragraph that names what the reader is leaving behind and what they are moving into — e.g. "With the underlying model in place, … the rest of the chapter turns from what a currency record contains to where you go to work with one." A chapter with strong individual sections but no segues between them is not done; add the missing bridges before moving on to screenshots.

5. ** Conclusion — draws the argument together in prose, retracing the steps the Overview promised ("The chapter set out to show… and it has traced exactly that path."). Always named Conclusion, never "Summary".
6. ** See also — id-links to the standard, related external references, and the sibling/template chapter this one mirrors.

The ** Provenance subsection links to the shared Reference Data chapter's Provenance section by ID rather than re-describing the common audit fields.

At this stage no real screenshots exist; each one is a placeholder the next recipe (How do I capture screenshots for a manual chapter?) will replace. For every dialog, window, or UI state the chapter references, insert:

#+caption: [SCREENSHOT NEEDED] <what the image should show>.
# Capture: <precise instruction — what state to set up, what to click, what to capture>.
[[proj:assets/images/TODO_<descriptive_name>.png]]

The # Capture: comment is not decorative — it is the literal instruction the next recipe's test-scenario step will use verbatim, so write it as if briefing someone who has never seen the dialog: what data must already exist, what to click, what the frame should include. Name the placeholder file with the TODO_ prefix and the real target name after it (see naming convention below) so a repo-wide search for TODO_ finds every outstanding capture across every chapter.

Screenshots live in assets/images/ and are referenced from the chapter with [[proj:assets/images/<name>.png]]. The naming rule turns on plural vs singular:

• Plural (<plural>_…) names the one primary screenshot of the list / main window — the canonical shot of the whole collection: countries_main_dialog.png. Reserve the plural prefix for this single establishing image.
• Singular (<entity>_…) names everything else: every shot scoped to a single record (country_details_provenance.png, country_history_dialog.png, country_history_revert_confirmation.png, country_history_revert_save.png, country_details_delete_confirmation.png) and any secondary, feature-specific shot of the list window that illustrates one control rather than the collection as a whole (country_main_window_reload_button.png). In short: plural is the one establishing list shot; singular is everything else, whichever window it happens to show.

Each image is introduced with a #+caption[Short caption]: Long caption… on the line above the link; the short caption feeds the PDF list of figures, the long one describes what the reader is looking at.

Add the chapter to doc/manual/user_guide/user_manual.org in reading order, inside the correct \part, as a top-level heading with a :CUSTOM_ID: plus an #+include at :minlevel 2. Because filenames carry no chapter number, inserting a chapter between two existing ones (e.g. a companion entity documented right after the one it extends) is just a matter of placing its heading in the right reading-order position — nothing about any other chapter's filename, :CUSTOM_ID:, or include line ever needs to change:

* Countries
:PROPERTIES:
:CUSTOM_ID: chapter_countries
:END:

#+include: "chapter_countries.org" :minlevel 2

Also add a row to the separate site index, doc/manual/user_guide/user_manual_site.org's * Chapters table — this is easy to skip since it's a different file from user_manual.org and the PDF build won't catch a missing row. Link the chapter's own :ID:, not a #+include, and put it under the matching Part: divider row:

| [[id:849845B0-29BE-4BBB-96D1-05579F06EEED][6. Countries]] | Country management: ISO 3166-1, the Qt UI, history and revert, shell and CLI commands. |

./compass.sh build --direct manual
./compass.sh build --direct site

A clean manual build ("Manual PDF build succeeded.") confirms the lettrine, includes, images and links all resolve, and that every placeholder's [[proj:assets/images/TODO_*.png]] link at least points somewhere resolvable as a file reference (the build does not require the TODO_ files to exist as real images). The site build publishes the chapter's HTML regardless of whether it's linked from the site index — it will not fail if you forgot the step above, so never rely on eyeballing the built HTML to catch a missing row (this is exactly how chapter_parties.org=/=chapter_counterparties.org went undetected for a full sprint). Cross-check the two chapter lists programmatically instead — every #+include-d chapter filename in user_manual.org must have a matching row in user_manual_site.org:

comm -23 \
  <(grep -oP '(?<=#\+include: ")[^"]+(?=\.org")' doc/manual/user_guide/user_manual.org | sort) \
  <(grep -oP '(?<=\[\[id:)[A-F0-9-]+(?=\]\[)' doc/manual/user_guide/user_manual_site.org \
    | while read -r id; do grep -l ":ID: $id" doc/manual/user_guide/chapter_*.org 2>/dev/null; done \
    | xargs -n1 basename | sed 's/\.org$//' | sort)

Empty output means every chapter in user_manual.org has a matching row in the site index. Any filename it prints is missing from user_manual_site.org's * Chapters table — add it before moving on.

At the end of this recipe the chapter is content-complete — domain grounding sourced and written in the required prose tone, every section segued into the next, every field and workflow documented, and every screenshot placeholder inserted with its # Capture: instruction — but it is not yet ready to ship: it still needs its screenshots captured (see How do I capture screenshots for a manual chapter?) and a human review pass. Do not mark the underlying task DONE until both of those are done.