# Documentation changelog All notable changes to the **documentation tree** under `docs/` (and related doc-only policy files) are tracked here. This journal is separate from the repository root [`CHANGELOG.md`](../CHANGELOG.md), which focuses on product and API behavior (see [ADR 0013](adr/0013-changelog-and-release-notes.html)). The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). ## 2026-04-22 ### Added - **Portal profile [Kirill Neustroev](internal/portal/people/kirill-neustroev/index.html)** (DevOps): machine-readable `data-person-*` on ``, avatar `photo.png`, **Page history** baseline. Co-maintainer on [`docs/internal/api/errors.html`](internal/api/errors.html) via `data-maintainer-ids`. ### Changed - **[`docs/audit/README.html`](audit/README.html):** new section **How to create assessments** (file naming such as `YYYY-MM-DD-topic-assessment.html`, folder choice under `docs/audit/docs/` or `docs/audit/api/`, title alignment, asset paths, ADR 0024 cross-links). - **[`docs/audit/docs/README.html`](audit/docs/README.html):** assessment table lists the UI/UX report alongside earlier DX assessments. - **Shared docs assets:** incremental updates to [`docs/assets/docs.css`](assets/docs.css), [`docs-theme.css`](assets/docs-theme.css), [`docs-nav.js`](assets/docs-nav.js), [`internal-sidebar.js`](assets/internal-sidebar.js), and [`docs-internal-meta.js`](assets/docs-internal-meta.js); portal profile tweaks for Cursor and Ivan Boyarkin; [`README.md`](../README.md), [`docs/index.html`](index.html), and selected internal pages (conspectus, methodology, backlog) refreshed in the same pass. - **Generated artifacts:** [`docs/assets/docs-portal-data.js`](assets/docs-portal-data.js) and [`docs/assets/search-index.json`](assets/search-index.json) regenerated (`collect_docs_portal_data.py`, `build_docs_search_index.py`). ## 2026-04-21 ### Added - **Employee portal** under [`docs/internal/portal/`](internal/portal/README.html): hub and profile pages driven by `data-*` attributes; [`docs/assets/docs-portal-data.js`](assets/docs-portal-data.js) generated by [`scripts/collect_docs_portal_data.py`](../scripts/collect_docs_portal_data.py); client UI in [`docs/assets/docs-internal-meta.js`](assets/docs-internal-meta.js) (breadcrumbs for profile hubs, **Maintained pages** list with pagination, **Page editors**). Navigation entry in [`docs/assets/internal-sidebar.js`](assets/internal-sidebar.js); repository tree in root [`README.md`](../README.md) lists `docs/internal/portal/`. - **Page history** on hand-written documentation pages: section `id="page-history"` (or assessment `id="5-page-history"`) with columns **Date | Change | Author**; [`scripts/ensure_docs_page_history.py`](../scripts/ensure_docs_page_history.py) for bulk inserts; [`scripts/link_page_history_authors.py`](../scripts/link_page_history_authors.py) links author names to portal profiles where applicable. - **Default page editors** for hand-written HTML: [`scripts/apply_default_page_editor_to_docs.py`](../scripts/apply_default_page_editor_to_docs.py). Portal pages mount **in-page TOC** (`docs-inpage-toc-mount`) so `make docs-design-check` passes. ### Changed - [`scripts/validate_docs_design.py`](../scripts/validate_docs_design.py): requires a **Page history** block (or the assessment equivalent) and existing top-nav / card / TOC rules. - **Shared styling:** `.docs-page-meta` (avatars, editor list) and page-history author links in [`docs/assets/docs.css`](assets/docs.css); portal chrome and pager styles in [`docs/assets/internal-layout.css`](assets/internal-layout.css), including dark-theme background for the pager. - [`docs/internal/front/documentation-style-guide.html`](internal/front/documentation-style-guide.html): documents page history and author linking. - **`make docs-fix`:** new step runs `collect_docs_portal_data.py` before pdoc and search index ([`Makefile`](../Makefile)). - **Premium docs UI polish:** top-nav links and command palette interactions in [`docs/assets/docs-nav.js`](assets/docs-nav.js), [`docs/assets/docs-site-nav.css`](assets/docs-site-nav.css), and [`docs/assets/docs.css`](assets/docs.css) now include consistent hover/focus motion, quick actions launcher, grouped command palette actions, and inline filtering. - **Page editors UX:** [`docs/assets/docs-internal-meta.js`](assets/docs-internal-meta.js) now renders a compact avatar stack by default and exposes the full editor list behind a click-to-expand **Page editors** toggle. - **Portal people cards:** [`docs/assets/internal-layout.css`](assets/internal-layout.css) and [`docs/assets/docs-internal-meta.js`](assets/docs-internal-meta.js) now use consistent card sizing, alphabetical sort inside groups, small group count badges, profile subtitle metadata, and matched avatar hover effects on both portal hub and profile pages. - **Frontend contract documentation:** [`docs/internal/front/documentation-style-guide.html`](internal/front/documentation-style-guide.html) now includes a dedicated **Docs frontend contract** section that defines required mounts/attributes/scripts for shared docs UI features. - **Skeleton loading states (demo visibility):** portal widgets in [`docs/assets/docs-internal-meta.js`](assets/docs-internal-meta.js) and [`docs/assets/docs.css`](assets/docs.css) now show skeleton placeholders for people and maintained pages with a minimum visible window (`SKELETON_MIN_VISIBLE_MS = 600`) for visual verification. ## 2026-04-18 ### Added - **Unified audit template and layout:** [`docs/audit/AUDIT_TEMPLATE.html`](docs/audit/AUDIT_TEMPLATE.html) — Overview (`id="overview"`, no `lead`), Table 2 with **Justification** column, `pre.audit-scoring-formula`, `table.audit-gap-table` (TODO / IN PROGRESS / DONE). Assessments live under [`docs/audit/docs/`](docs/audit/docs/README.html) (documentation DX) and [`docs/audit/api/`](docs/audit/api/README.html) (REST API). Canonical DX and API reports: [`2026-04-14-documentation-experience-assessment.html`](docs/audit/docs/2026-04-14-documentation-experience-assessment.html), [`2026-04-14-rest-api-assessment.html`](docs/audit/api/2026-04-14-rest-api-assessment.html). CSS: gap workflow colours and formula blocks in [`docs/assets/docs.css`](assets/docs.css); dark theme in [`docs/assets/docs-theme.css`](assets/docs-theme.css). - **Dark theme** for hand-written documentation: [`docs/assets/docs-theme.css`](assets/docs-theme.css) (palette + overrides), loaded after [`docs/assets/docs.css`](assets/docs.css) on all pages that already linked `docs.css`. - **Theme control** in [`docs/assets/docs-nav.js`](assets/docs-nav.js): cycles **Auto** (follows `prefers-color-scheme`) → **Light** → **Dark** → Auto; preference stored in `localStorage` (`docs-theme-preference`). A short synchronous script in each page `` applies the stored choice before first paint to limit flash of the wrong theme. - [`scripts/inject_docs_theme_assets.py`](../scripts/inject_docs_theme_assets.py): inserts the `docs-theme.css` `` (after `docs.css`) and the early theme script into `docs/**/*.html` when adding or normalizing pages. - **Shared ADR/RFC lifecycle help** in [`docs/assets/docs-nav.js`](assets/docs-nav.js): `injectDocsLifecycleHelp()` fills `
` from one versioned source (`DOCS_LIFECYCLE_HELP_SNIPPET_VERSION`); relative links use `relHref` so `docs/adr/` and `docs/rfc/` stay correct. ADR pages use class `adr-weight-help`, RFC pages `rfc-weight-help`; the [ADR template](adr/0000-template.html) uses `adr-template` for the full milestone table. Injected nodes carry `data-docs-lifecycle-version` for traceability. ### Changed - **Assessments consolidated:** removed dated standalone files under `docs/audit/` root (`2026-04-14-*`, `2026-04-17-*`, `2026-04-18-*`); content merged into the `docs/` and `api/` trees above. [`docs/audit/README.html`](audit/README.html) and [ADR 0024](adr/0024-architecture-and-quality-assessment-documents.html) updated. Top nav label **Assessments** (was “API assessment reports”); breadcrumb hubs for `audit/docs` and `audit/api` in [`docs/assets/docs-nav.js`](assets/docs-nav.js). - Shared styling refactored around **CSS custom properties** in [`docs/assets/docs.css`](assets/docs.css), [`docs/assets/docs-site-nav.css`](assets/docs-site-nav.css), [`docs/assets/internal-layout.css`](assets/internal-layout.css), and [`docs/backlog/backlog.css`](backlog/backlog.css) so light and dark themes stay consistent (navigation, search, tables, ADR steppers, backlog pills, internal sidebar, diagrams). - **Top navigation:** removed the rotating conic **outline** treatment from the **⭐Backlog** pill so it matches other internal links; theme switcher sits in a dedicated top row (`.top-nav__theme-bar`) above the Internal / Code cards. - **Motion:** slowed the animated **sidebar “SHOW MENU”** control border in [`docs/assets/internal-layout.css`](assets/internal-layout.css) and the **ADR “Current status”** pill rim in [`docs/assets/docs.css`](assets/docs.css) for calmer motion. - **Responsive layout** in [`docs/assets/docs.css`](assets/docs.css): `img` / `svg` / `video` capped with `max-width: 100%`; narrower breakpoints (~520px / ~380px) adjust padding (including `env(safe-area-inset-*)`), headings, cards, and `pre`; **Back to top** uses safe-area insets; coarse-pointer media adds comfortable tap targets and `16px` search input text to reduce iOS zoom-on-focus. - **Hub index tables:** [`docs/adr/README.html`](adr/README.html), [`docs/howto/README.html`](howto/README.html), [`docs/runbooks/README.html`](runbooks/README.html), [`docs/audit/README.html`](audit/README.html), [`docs/rfc/README.html`](rfc/README.html), and [`docs/internal/developers.html`](internal/developers.html) — document titles in the first column are the links; redundant **Open** columns removed. [`docs/internal/system-design.html`](internal/system-design.html) aligned where applicable. - [ADR 0018](adr/0018-adr-lifecycle-ratification-and-badges.html): narrative references `renderLifecycleStatusBlocks` and notes RFC [`data-rfc-weight`](rfc/README.html) on `
`. - **Plain language:** [`docs/internal/front/documentation-style-guide.html`](internal/front/documentation-style-guide.html#plain-language) now defines readability rules (short sentences, simple vocabulary where possible, ESL-friendly). Entry pages updated for simpler English: repository root [`README.md`](../README.md) and [`CONTRIBUTING.md`](../CONTRIBUTING.md), [`docs/index.html`](index.html), [`docs/howto/README.html`](howto/README.html), [`docs/audit/README.html`](audit/README.html). Older ADRs and long internal pages can follow the same guide in follow-up edits. - **ADR plain-language pass:** [`docs/adr/`](adr/) — shorter, clearer wording across numbered ADRs (ratification blurbs, Context/Decision where edited), [`docs/assets/docs-nav.js`](assets/docs-nav.js) lifecycle help copy updated (`DOCS_LIFECYCLE_HELP_SNIPPET_VERSION` **2**). Very long ADRs (e.g. 0020, 0021 industry sections) can be tightened further in follow-up PRs. - **RFC plain-language pass:** [`docs/rfc/README.html`](rfc/README.html), [`docs/rfc/0001-docs-search-implementation.html`](rfc/0001-docs-search-implementation.html) (also fixes local validation `
    ` structure), [`docs/rfc/0002-docs-search-kpi-policy-and-slo.html`](rfc/0002-docs-search-kpi-policy-and-slo.html) — simpler English aligned with the documentation style guide. - **Runbooks plain-language pass:** [`docs/runbooks/README.html`](runbooks/README.html) and all numbered runbooks (`0000`–`0010`) — shorter sentences and simpler vocabulary; [`docs/runbooks/0008-observability-scrape-failing.html`](runbooks/0008-observability-scrape-failing.html) gains a **Follow-up** section aligned with other runbooks. - **Developer guides plain-language pass:** [`docs/developer/`](developer/) — simpler overviews and leads; clearer lists in requirements, schemas, business logic, and error-matrix guides; shorter Kibana/Elastic instructions in [`docs/developer/0007-local-development.html`](developer/0007-local-development.html); docs pipeline and Docker image pages tightened; **See also** links to the hub use anchor [`#developer-guides`](internal/developers.html#developer-guides) (fixes redirect target vs [`docs/internal/developers.html`](internal/developers.html) section id). - **Backlog plain-language pass:** [`docs/backlog/README.html`](backlog/README.html) — shorter intro (estimates vs ADR lifecycle), simpler legend and “how to update” steps, and tightened **Summary** / **Problem & value** text for backlog items. - **Audit plain-language pass (superseded by 2026-04-18 layout):** earlier edits targeted the pre-restructure paths; current canonical assessments are under [`docs/audit/docs/`](audit/docs/README.html) and [`docs/audit/api/`](audit/api/README.html). ## 2026-04-17 ### Added - Shared favicon asset [`docs/assets/favicon.svg`](assets/favicon.svg) and favicon links across all documentation HTML pages under `docs/`. ### Changed - Favicon handling is now automated for generated docs outputs: - [`scripts/render_docs_html.py`](../scripts/render_docs_html.py) injects favicon links for rendered markdown companion pages. - [`scripts/normalize_pdoc_output.py`](../scripts/normalize_pdoc_output.py) injects favicon links into pdoc-generated API reference pages under `docs/api/`. - [`scripts/inject_docs_favicon.py`](../scripts/inject_docs_favicon.py) provides a one-shot repo-wide backfill/normalization for docs HTML files missing a favicon tag. ## 2026-04-15 ### Removed - Legacy `docs/internal/user/index.html` (superseded by [`internal/api/user/index.html`](internal/api/user/index.html)); orphan assets `internal-doc-demo.css`, `internal-doc-nav.js`; unused `details.internal-doc-map` rules in [`docs/assets/docs.css`](assets/docs.css). ### Added - [`docs/howto/README.html`](howto/README.html) — index for how-to guides. - [`docs/howto/internal-service-docs-layout.html`](howto/internal-service-docs-layout.html) — directory layout for `docs/internal/`, shared chrome, and how to add or edit internal HTML pages (content moved from [`internal/STRUCTURE.md`](internal/STRUCTURE.md), which is now a short pointer). - [`docs/howto/0004-how-to-add-post-contract.html`](howto/0004-how-to-add-post-contract.html) — beginner guide for `POST /api/v1/contract` (moved from [`developer/0004-how-to-add-post-contract.html`](developer/0004-how-to-add-post-contract.html); old URL redirects). ### Changed - [`docs/internal/STRUCTURE.md`](internal/STRUCTURE.md) — now links to [`howto/internal-service-docs-layout.html`](howto/internal-service-docs-layout.html) instead of holding the full tree and steps inline. - [`docs/assets/docs-nav.js`](assets/docs-nav.js): top nav item **How-to guides** (`howto/README.html`) and `activeTarget` for `howto/*` paths. - `docs/internal/user-http-api.html` moved to [`docs/internal/api/user/user-http-api.html`](internal/api/user/user-http-api.html) (resource-scoped layout); sidebar and inbound links updated. - Full User internal specification merged into [`docs/internal/api/user/index.html`](internal/api/user/index.html) (single entry point). [`docs/internal/api/user/user-http-api.html`](internal/api/user/user-http-api.html) is a redirect stub to `index.html` with hash preserved; per-method pages link to `../index.html#…`. - [ADR 0025](adr/0025-external-and-internal-api-documentation.html): internal docs described as multi-page (`docs/internal/api/`, per-resource hub, [`STRUCTURE.md`](internal/STRUCTURE.md) / [how-to layout](howto/internal-service-docs-layout.html)). - [ADR 0026](adr/0026-internal-service-documentation-as-source-of-truth.html): expanded with repository layout table, navigation ownership (`INTERNAL_SIDEBAR_NAV` in [`docs/assets/internal-sidebar.js`](assets/internal-sidebar.js)), contributor workflow, and ratification note (2026-04-15). ## 2026-04-14 ### Added - [ADR 0025](adr/0025-external-and-internal-api-documentation.html): external vs internal documentation — OpenAPI (`docs/openapi/`) as the sole normative HTTP contract for integrators; internal engineering narrative under `docs/internal/`; relationship table vs changelog, pdoc, Swagger views. - [ADR 0026](adr/0026-internal-service-documentation-as-source-of-truth.html): internal service HTML as the authoritative engineering narrative for documented topics; scope (business rules, HTTP mapping via `operationId`, observability expectations, async boundaries); document history tables; index at [`docs/internal/README.html`](internal/README.html). - [`docs/internal/README.html`](internal/README.html) — entry point for internal service docs (project + service overview); [`docs/internal/service-overview.html`](internal/service-overview.html) — redirect stub to the same page for old links. - [`docs/internal/api/user/user-http-api.html`](internal/api/user/user-http-api.html) — internal specification for the User HTTP API (operations, idempotency, errors, logging, metrics, dependencies); lives under the User resource folder (see 2026-04-15 changelog). - [`docs/internal/api/user/index.html`](internal/api/user/index.html) — User resource **internal hub** (contract links, method index). Per-endpoint pages under [`docs/internal/api/user/operations/`](internal/api/user/operations/). How to extend `docs/internal/`: [`docs/howto/internal-service-docs-layout.html`](howto/internal-service-docs-layout.html) (see also [`internal/STRUCTURE.md`](internal/STRUCTURE.md)). Anchors on `user-http-api.html`: `#user-op-createUser`, `#user-op-getUserBySystemUserId`, `#user-op-updateUserBySystemUserId`, `#user-op-patchUserBySystemUserId`. - [`docs/assets/docs-nav.js`](assets/docs-nav.js): top nav item **Internal (service)** and `activeTarget` for `internal/*` paths. - Shared **assessment score** styling: `docs/assets/docs.css` defines `--audit-score-*` colours, `.audit-score-table` cell classes (`score-excellent`, `score-good`, `score-needs-attention`; `score-neutral` remains an alias), and `.audit-score-legend` / swatch layout. Canonical legend markup: [`docs/assets/audit-score-legend-fragment.html`](assets/audit-score-legend-fragment.html), injected by [`docs/assets/docs-nav.js`](assets/docs-nav.js) into `
    ` placeholders (see [ADR 0024](adr/0024-architecture-and-quality-assessment-documents.html#assessment-score-scale)). `SKIP_HTML_INDENT_NORMALIZE` in [`scripts/format_docs_html.py`](../scripts/format_docs_html.py) includes the fragment file. - [ADR 0024](adr/0024-architecture-and-quality-assessment-documents.html): architecture and quality **assessment** documents — `docs/audit/` location, `YYYY-MM-DD-topic-assessment.html` naming, canonical HTML sections (lead metadata, Table 1 reference practices, Table 2 mapping/scores, narrative findings, mitigation, checklist, document history), goals, process (when to refresh, ownership, `docs/CHANGELOG.md`), relationship to ADRs/runbooks, alternatives, links to existing assessments, and a note on `SKIP_HTML_INDENT_NORMALIZE` in [`scripts/format_docs_html.py`](../scripts/format_docs_html.py). - [`scripts/format_docs_html.py`](../scripts/format_docs_html.py): optional skip list `SKIP_HTML_INDENT_NORMALIZE` so the line-based indenter does not corrupt long HTML pages with multiline list items (ADR 0024 registered). - [Developer guide 0010](developer/0010-make-commands-and-workflows.html): Make commands and workflows — PlantUML sources under [`docs/uml/make/`](uml/make/) (rendered PNGs via `make docs-fix`), composite pipeline and run/observability figures, tables of atomic targets by theme, if-then onboarding scenarios; linked from [docs index](index.html), [developer README](developer/README.html), [CONTRIBUTING](../CONTRIBUTING.md), [ADR 0008](adr/0008-make-command-taxonomy-and-workflow-entrypoints.html), [developers docs](internal/developers.html), and [local development](developer/0007-local-development.html). ### Changed - [ADR 0024](adr/0024-architecture-and-quality-assessment-documents.html): rewritten around a single **published assessment backbone** (ordered list: lead/TOC, scope/methodology, Table 1, Table 2 + injected legend, scoring summary, gaps 5.1–5.3, mitigation, optional beyond-baseline, checklist, document history); merged former implementation/validation into **Rollout and validation**; shorter alternatives; anchor `#published-assessment-backbone` replaces the old canonical-sections template list. - [API assessment](audit/api/2026-04-14-rest-api-assessment.html): §8 actionable checklist, §9 document history, TOC entries for sections 7–9 (aligned with ADR 0024). - [DX assessment](audit/docs/2026-04-14-documentation-experience-assessment.html): same section order as the API assessment; Table 2 anchor `table-2-study-app-scores`; invalid nesting and duplicate blocks removed. - [ADR 0024](adr/0024-architecture-and-quality-assessment-documents.html): **Industry context and applicability** — how common large-org practices (RFC/launch/security/portal) relate to this repo’s lightweight rubric; **PET scale** and when low scores mean deferral, not failure; backbone now expects an industry/PET subsection under scope/methodology. - [API assessment](audit/api/2026-04-14-rest-api-assessment.html): §1.6 industry/PET; restored §8 checklist and §9 document history (TOC). - [DX assessment](audit/docs/2026-04-14-documentation-experience-assessment.html): §1.5 industry/PET; restored §7 checklist; Table 1 intro fixed; [audit index](audit/README.html) — “not a FAANG gate” card. ## <= 2026-04-12 ### Changed - [ADR 0019](adr/0019-python-dependency-security-pip-audit-and-pinning-policy.html): implementation marked **Done** (`data-adr-weight="7"`). [Backlog item-4](backlog/README.html#item-4) marked **Done**; `Makefile` **`verify-ci`** now includes **`deps-audit`** (engineering-practices table synced). - [ADR 0022](adr/0022-embedded-swagger-ui-openapi-sandbox.html) superseded: browser validation cancelled; `openapi/openapi-explorer.html` is OpenAPI (test), Swagger browse-only; task on hold. Removed `openapi-live.html` (use app `/docs` for Try it out). - All numbered ADRs (`0001`–`0017`): replaced legacy **Status** badge blocks with `data-adr-weight="7"` on `
    ` and a **Ratification** note for pre–ADR-0018 adoption; UI status comes from `docs/assets/docs-nav.js` per [ADR 0018](adr/0018-adr-lifecycle-ratification-and-badges.html). [ADR 0018](adr/0018-adr-lifecycle-ratification-and-badges.html) and [ADR 0019](adr/0019-python-dependency-security-pip-audit-and-pinning-policy.html) include the collapsible weight help from the [ADR template](adr/0000-template.html). - ADR template: weight instructions in a collapsible `
    ` (styles in `docs/assets/docs.css`); `data-adr-weight` default for new drafts is `-1` (not `9`, which clamped to `7`). - ADR **Status log**: one attribute on `
    ` — `data-adr-weight` (−1…7); **current status** and the linear 8-step log derive from that value. [ADR template](adr/0000-template.html), [ADR 0018](adr/0018-adr-lifecycle-ratification-and-badges.html), `docs/assets/docs-nav.js`, `docs/assets/docs.css`. - API reference generation: `scripts/normalize_pdoc_output.py` strips unstable `at 0x…` fragments from pdoc HTML so `make docs-check` stays reproducible; `make api-docs` runs with `PYTHONHASHSEED=0`. - PlantUML under `docs/uml/`: architecture and sequence `.puml` sources include the shared style; rendered SVGs in `docs/uml/rendered/` updated to match ([ADR 0020](adr/0020-c4-plantuml-diagram-style-and-conventions.html)). - Docs pipeline and contributor entrypoints: `scripts/regenerate_docs.py`, `scripts/sync_docs.py`, `Makefile`, `CONTRIBUTING.md`, and `.github/ISSUE_TEMPLATE/adr_discussion.md` aligned with ADR lifecycle, UML rendering, and synced HTML companions (`docs/internal/developers.html`, `docs/internal/system-design.html`, `docs/backlog/README.html`, `docs/runbooks/README.html`, `docs/developer/0008-docs-pipeline.html`). ### Added - [ADR 0021](adr/0021-continuous-delivery-github-actions-and-ghcr.html): continuous delivery via GitHub Actions — build Dockerfile, push to GHCR after CI, beginner-oriented context (CI vs CD), scope, and references; developer guide 0009 links to registry automation. - [ADR 0019](adr/0019-python-dependency-security-pip-audit-and-pinning-policy.html): Python dependency security—`requirements.txt` as exact pin, `pip-audit`, Make/CI expectations, severity handling, and exception process (implements backlog policy; `make deps-audit` / CI wiring tracked there). - Documentation changelog (`docs/CHANGELOG.md`) and ADR lifecycle policy ([ADR 0018](adr/0018-adr-lifecycle-ratification-and-badges.html)): Issue discussion with `[ADR]` title, ratification via Issue + PR, `data-adr-weight`, and `docs/CHANGELOG.md` update expectations. - [ADR 0020](adr/0020-c4-plantuml-diagram-style-and-conventions.html): C4 views, PlantUML layout and naming conventions, and a shared diagram style via `docs/uml/include/style.puml` (with `docs/uml/README.txt` for authors).