Task: Update user manual with the holding company description
Table of Contents
This page documents a task in the Holding company treasury functionality: FX/CRM visibility, Group Treasury book, consolidated reporting story. It captures the goal, current status, acceptance, and any notes or results.
Goal
Add a section to the user manual's Acme Corporation chapter describing the holding company's own treasury footprint – FX/CRM visibility, the Group Treasury book – and how it differs from the three operating offices' trading floors, so a reader understands why the holding party looks and behaves differently from Acme UK/US/HK.
Status
| Field | Value |
|---|---|
| State | DONE |
| Parent story | Holding company treasury functionality: FX/CRM visibility, Group Treasury book, consolidated reporting |
| Now | New chapter section written and wired in; site + PDF build verified. Screenshots pending – follow-up when back at a machine with X access. |
| Waiting on | Nothing. |
| Next | None – task closed. Screenshots are a separate, small follow-up, not a blocker. |
| Last touched | 2026-08-07 |
Acceptance
- A new section in
chapter_acme_corporation.orgdescribes the holding company's FX/CRM visibility (tenant-wide FX tick consumption, no feed_binding of its own) and the Group Treasury book/portfolio (one DIVISION unit, one virtual GBP portfolio, two Banking-classified books), contrasted explicitly with an operating company's trading floor. [DONE] - The chapter's Overview and Conclusion sections reference the new section so the chapter's narrative arc stays consistent. [DONE]
- The user_guide site (HTML) and the PDF manual both build cleanly with the new content included. [DONE – verified both.]
- Screenshots illustrating the new section (Cross-Rates Matrix,
Group Treasury Org Explorer tree) – deferred: no X11 access in
this session. A
#+begin_notecallout flags this explicitly in the chapter itself rather than silently shipping without them.
Plan
(Implementation strategy. Written when work starts; key decisions
are distilled into the parent story's * Decisions at close, but the
plan itself stays — it is the historical record of what we did.)
- Read the existing
chapter_acme_corporation.orgend to end to match its structure, tone, and heading conventions before adding anything – it already has an established narrative arc (Overview -> What is Acme Corporation -> organisational model -> the holding-group structure -> departments -> staff -> provisioning -> conclusion), and the new section needed to fit into that arc rather than being bolted on. - Added a new
** The holding company's own treasury footprintsection immediately after** The holding-group structureand before** Departments and segregation of duties– structurally the right place, since it belongs with "what the group centre itself is" rather than with the departmental/staffing detail that follows. Covers, in order: why Acme Corporation Plc is not a pure legal shell; how FX visibility works without the holding company needing its own feed_binding (tenant-wide FX tick consumption, per the earlier tasks in this story); the Group Treasury business unit/portfolio/books, explicitly contrasted with an operating company's Trading-classified desk books (Banking classification, the correct prudential treatment for financing/hedging rather than held-for-trading positions); and a forward pointer to the consolidated-group-risk-reporting investigation findings, without claiming that reporting is built. - Updated the chapter's
** Overview(added the new section to the guided tour) and** Conclusion(added a sentence on the holding company's own treasury activity) so the chapter's own internal cross-references stay consistent with the new structure. - Screenshots: planned two (Cross-Rates Matrix at the holding party;
Org Explorer's Group Treasury tree), matching the chapter's
existing captioned-screenshot convention. Attempted to capture
these live via X11 forwarding, but the user does not currently
have X access on this box – deferred rather than skipped
silently: added a
#+begin_notecallout (the chapter's existing admonition convention, matching e.g. chapter_tenants.org) directly in the new section flagging that the screenshots are pending a follow-up pass. - Verified the change builds cleanly in both manual output formats,
since a docs-only change can still break the site/PDF pipeline
(broken links, malformed org syntax, LaTeX export failures):
compass build site(the fulldeploy_siteCMake target, which re-indexes all ~4700.orgfiles' IDs and renders HTML): completed with "Build succeeded", and the renderedchapter_acme_corporation.htmlcontains the new section's text.- Noticed
deploy_site's bundled PDF publish step just copies the pre-existinguser_manual.pdfas a static attachment rather than regenerating it from source – its mtime was stale (pre-dated this edit). Found and ran the actual PDF-generation target,deploy_manual(driven byprojects/ores.lisp/src/ores-build-manual.el, per thedoc-update-manualskill), directly. It completed with "Manual PDF build succeeded" – 189 pages, correct file size, no fatal LaTeX errors (no!-prefixed error lines inuser_manual.log); the one warning ("There were multiply-defined labels") is a standard benign artefact of a 3-pass pdflatex build, not a content defect. Extracted the PDF's text (pdftotext) and confirmed the new section's content is present.
Notes
- Screenshots are the one deliberately incomplete part of this task:
#+begin_notein the chapter flags it, and the Acceptance criteria above record it explicitly rather than silently shipping a chapter section with promised images missing. Follow-up (not a new task in this story, since the story itself is now fully closed): captureacme_corporation_holding_company_cross_rates_matrix.png(Cross- Rates Matrix opened attenant_admin@acme_corporation, showing live GBP/USD/HKD rates) andacme_corporation_group_treasury_tree.png(Org Explorer expanded to Acme Corporation Plc -> Group Treasury -> Group Treasury Portfolio -> both books) underassets/images/, then wire them in with#+caption[...]=/https://github.com/OreStudio/OreStudio/blob/main/assets/images/...= blocks matching the chapter's existing screenshot convention, and remove the#+begin_notecallout.
Test Scenarios
Manual QA scenarios (scaffolded via compass add test_scenario, run
through the QA Validation Runner panel) that verify this task. Link
new ones here as they're created; the scenario doc itself links back
via its "Verifies task" field.
| Scenario | State | Notes |
|---|---|---|
PRs
| PR | Title |
|---|---|
| #1895 | [docs,agile] Document the holding company in the Acme Corporation manual |
Review
| Comment summary | File | Decision | Notes |
|---|---|---|---|
Result
The Acme Corporation user manual chapter now has a dedicated section
explaining the holding company's own treasury footprint – FX
visibility across its subsidiaries' currencies without a feed_binding
of its own, and the Group Treasury business unit/portfolio/two
Banking books – explicitly contrasted with an operating company's
trading floor, so a reader understands why Acme Corporation Plc looks
and behaves differently from Acme UK/US/HK. Both manual output
formats (site HTML and PDF) build cleanly with the new content.
Screenshots are the one deliberately incomplete part: no X11 access
in this session prevented capturing them, so a #+begin_note callout
in the chapter flags this openly rather than shipping silently
incomplete, and the follow-up capture/wiring steps are recorded in
this task's Notes for whenever X access is available again. This was
the last remaining task in the holding-company-treasury-functionality
story – the story itself is now fully closed alongside this task.