Task: Write country documentation (manual chapter, NATS reference)
Table of Contents
This page documents a task in the Commission: country story. It captures the goal, current status, acceptance, and any notes or results.
Goal
Write the country documentation: a manual chapter mirroring chapter 5 (currencies) — entity description, Qt windows, shell and CLI commands — wired into user_manual.org, and the refdata NATS message reference extended with the country subjects and the country_changed event.
Status
| Field | Value |
|---|---|
| State | DONE |
| Parent story | Commission: country |
| Now | Nothing. |
| Waiting on | Nothing. |
| Next | Nothing. |
| Last touched | 2026-06-06 |
Acceptance
- Manual chapter exists, covers the entity end to end, and is wired into user_manual.org; the PDF builds.
- NATS message reference documents country request/response subjects and the country_changed event.
- Shell and CLI recipe coverage is referenced, not duplicated.
Plan
(Transient implementation strategy. Written when work starts;
distilled into the parent story's * Decisions and cleared when the
task closes. Plans do not outlive their task.)
Notes
PRs
| PR | Title |
|---|---|
| #1372 | [doc] Country manual chapter, thesis chapters, entity-doc recipe |
Review
Round 1 (PR #1372, claude-review)
| # | Comment summary | File | Decision | Notes |
|---|---|---|---|---|
| 1 | CLI –tenant inconsistency (countries has it, currencies doesn't) | chapter_5_currencies.org | Accepted | Fixed 4f4a816a0; –tenant is a global refdata option, added to currencies examples to match |
| 2 | #+updated: not bumped on restructured chapters | chapter_1..5, accounts, shell, tenants | Accepted | Fixed e1125a9e4; stamped 2026-06-29 |
| 3 | Recipe screenshot-naming rule ambiguous (primary vs secondary list shot) | how_do_i_document_an_entity.org | Accepted | Fixed 2e54313f8; rule made explicit |
| 4 | Missing change-reason screenshot in "Editing a country" | chapter_6_countries.org | Accepted | Fixed 2e54313f8; id cross-ref to Currencies' shared dialog |
| 5 | Missing General-tab screenshot for country | chapter_6_countries.org | Accepted | Fixed c05c920a2; captured country_details_general.png and wired into the General subsection |
| 6 | system.new_record in shell example may mislead | chapter_6_countries.org | Declined | Verified: shell/CLI accept system.* codes (existence-only check, no category enforcement); UI-only restriction; consistent with currencies template |
Result
Wrote doc/manual/user_guide/chapter_6_countries.org mirroring the currency
chapter: Overview, ISO 3166-1 and its limitations (alpha-2/alpha-3/numeric/name
plus the official-name and flag extensions, code reuse and territory caveats),
the Countries window, Country Details (General + Provenance), editing, deleting,
history and revert, and the shell (countries get/add/delete/history) and CLI
(ores.cli refdata countries …) commands. Wired into user_manual.org under a
new * Countries heading after Currencies.
Recorded screenshots standardised to the currency naming convention (plural for the main list window, singular for detail/history/sub-dialog shots) and committed: countries_main_dialog, country_details_provenance, country_history_dialog, country_history_revert_{confirmation,save}, country_details_delete_confirmation, country_main_window_reload_button.
The refdata NATS message reference was already complete — events/channels.org
already lists ores.refdata.country_changed. Last open task in the story; its
closure cascades Commission: country to DONE.