kingmadoc 0.3.0.dev14__tar.gz → 0.3.0.dev16__tar.gz

{kingmadoc-0.3.0.dev14 → kingmadoc-0.3.0.dev16}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: kingmadoc
-Version: 0.3.0.dev14
+Version: 0.3.0.dev16
 Summary: Feature docs for AI coding agents: a plan with C4 diagrams before the code, a verification doc after.
 Project-URL: Homepage, https://github.com/ATkingma/KingmaDoc
 Project-URL: Issues, https://github.com/ATkingma/KingmaDoc/issues

{kingmadoc-0.3.0.dev14 → kingmadoc-0.3.0.dev16}/skill/SKILL.md

@@ -145,7 +145,8 @@ the diagrams, but never beyond what the user said or the code shows.
   vague REQ or invented ones. Under each: `Verified by: <test, test case or command>`
   (or `_TODO_`).
 - **Planned changes**: per `files_expected` path what changes and why (the "how" of
-  answer 4), one to three lines, no code blocks. Risks and assumptions may add code
+  answer 4), one to three lines, no code blocks; where a code snippet would help
+  (a new method, a changed signature), draw a small `classDiagram` with just those members. Risks and assumptions may add code
   findings marked _(inferred)_.
 - **Generated**: the real system time (`date -Iminutes`).
 - External systems: those from answer 3, plus systems the code demonstrably uses

{kingmadoc-0.3.0.dev14 → kingmadoc-0.3.0.dev16}/skill/codex.md

@@ -145,7 +145,8 @@ the diagrams, but never beyond what the user said or the code shows.
   vague REQ or invented ones. Under each: `Verified by: <test, test case or command>`
   (or `_TODO_`).
 - **Planned changes**: per `files_expected` path what changes and why (the "how" of
-  answer 4), one to three lines, no code blocks. Risks and assumptions may add code
+  answer 4), one to three lines, no code blocks; where a code snippet would help
+  (a new method, a changed signature), draw a small `classDiagram` with just those members. Risks and assumptions may add code
   findings marked _(inferred)_.
 - **Generated**: the real system time (`date -Iminutes`).
 - External systems: those from answer 3, plus systems the code demonstrably uses
@@ -233,8 +234,8 @@ Show the user the path, the number of deviations, and any failing check.
 - **Always Mermaid** (ignore `diagram_format`; PlantUML/D2 are CLI-only). Mermaid is
   the source of truth; every diagram is also rendered to a PNG and embedded in the
   Markdown (see [Rendering](#rendering)).
-- **Always fenced**: every diagram is a complete ` ```mermaid ` … ` ``` `
-  block, with nothing else inside it.
+- **Always complete**: every diagram is a complete Mermaid diagram (a ` ```mermaid `
+  block, or its `.mmd` file once rendered), with nothing else in it.
 - **Always labeled**:
   - C4 and `sequenceDiagram`: the first line after the diagram type is `title <text>`
     (`System Context: <project>`, `Containers: <project>`);
@@ -292,7 +293,7 @@ this line: _Disabled in `.featuredoc.yml` (`diagrams`)._
 
 `diagrams_png` in `.featuredoc.yml` [`embed`]: `embed` (below), `file` (the PNG goes to
 `<output_dir>/img/<slug>-<diagram>.png`, linked with `![<title>](img/<slug>-<diagram>.png)`)
-or `off` (no image, only the Mermaid block).
+or `off` (no image; the ` ```mermaid ` block stays in the document).
 
 - **Mode comes only from `.featuredoc.yml`.** No file or no `diagrams_png` key → `embed`.
   Never infer the mode from existing files (an `img/` folder, how an earlier doc did it).
@@ -300,26 +301,32 @@ or `off` (no image, only the Mermaid block).
   `![...](data:image/png;base64,`. A relative path such as `](img/` is an error: embed it and
   delete the loose PNG.
 - Embed the PNG with a script (read file → base64 → replace the line), never by hand.
+- **No Mermaid source in the document** once its PNG is there: no ` ```mermaid ` block
+  and no `<details>` with the source. The source lives in
+  `<output_dir>/diagrams/<slug>-<diagram>.mmd`.
 
-1. Write each ` ```mermaid ` block to a temporary `.mmd` file outside the repo and run:
-   `npx -y @mermaid-js/mermaid-cli -i <tmp>.mmd -o <tmp>.png -s 2 -b white -t default -p <puppeteer.json>`
+1. Write each diagram to `<output_dir>/diagrams/<slug>-<diagram>.mmd` (`<diagram>`:
+   `c4-context`, `c4-container`, `class`, `sequence-current`, `sequence-new`) and run:
+   `npx -y @mermaid-js/mermaid-cli -i <that>.mmd -o <tmp>.png -s 2 -b white -t default -p <puppeteer.json>`
    (`-t default`: Mermaid's normal theme; newer versions otherwise colour every shape).
 2. Set `PUPPETEER_SKIP_DOWNLOAD=true`, and let `puppeteer.json` point at an installed
    browser, so no Chromium is downloaded:
    `{"executablePath": "C:/Program Files (x86)/Microsoft/Edge/Application/msedge.exe"}`
    (or Chrome). Ask the user once before the first npm download: package
    `@mermaid-js/mermaid-cli`, from the npm registry, about 50 MB with dependencies.
-3. Directly below the block, after one empty line:
+3. In the document, in place of the block, two lines:
+   `<!-- kingmadoc:diagram diagrams/<slug>-<diagram>.mmd -->` and
    `![<diagram title>](data:image/png;base64,<base64 of the PNG>)`.
-   No separate image files go into the repo.
-4. The ` ```mermaid ` block always stays (GitHub shows no data URIs; the block is the
-   source for the next render). On a new render, replace only the image line below
-   the same block.
+   No separate image files go into the repo (`file` mode aside).
+4. To change a diagram, edit its `.mmd` file and render again; replace only the image
+   line below its comment. (GitHub shows no data-URI images; there the `.mmd` file is
+   the readable version.)
 5. Look at every PNG after rendering (Read): not empty, no labels cut off at the edge,
    no unexpected extra participants. If needed, fix the Mermaid (split or shorten a
    label) and render again.
-6. If rendering fails, write `_TODO: PNG not generated: <reason>._` below the block
-   (in `language`) and carry on; the document stays valid.
+6. If rendering fails, keep the ` ```mermaid ` block in the document, write
+   `_TODO: PNG not generated: <reason>._` below it (in `language`) and carry on; the
+   document stays valid.
 
 ## Output format
 
@@ -367,7 +374,8 @@ files_expected: [<existing files or folders the user said will change>]
 ## Planned changes
 
 - `<path from files_expected>`: <what changes and why, one to three lines, no code
-  blocks; the "how" from answer 4, or> _TODO: what changes here and why._
+  blocks (a small classDiagram with the changed members instead of a snippet); the "how"
+  from answer 4, or> _TODO: what changes here and why._
 
 ## Requirements
 
@@ -449,7 +457,7 @@ The classes this feature touches and their direct collaborators.
 
 Omit "**Answered while planning**" when nothing was answered.
 
-- Every diagram is a ` ```mermaid ` block with its PNG below it (see
+- Every diagram is its PNG, with the Mermaid source in a `.mmd` file (see
   [Rendering](diagram-rules.md#rendering)); a disabled diagram keeps its section with
   _Disabled in `.featuredoc.yml` (`diagrams`)._
 - **Generated** is the real system time (`date -Iminutes`), never a guess.

{kingmadoc-0.3.0.dev14 → kingmadoc-0.3.0.dev16}/skill/copilot.md

@@ -145,7 +145,8 @@ the diagrams, but never beyond what the user said or the code shows.
   vague REQ or invented ones. Under each: `Verified by: <test, test case or command>`
   (or `_TODO_`).
 - **Planned changes**: per `files_expected` path what changes and why (the "how" of
-  answer 4), one to three lines, no code blocks. Risks and assumptions may add code
+  answer 4), one to three lines, no code blocks; where a code snippet would help
+  (a new method, a changed signature), draw a small `classDiagram` with just those members. Risks and assumptions may add code
   findings marked _(inferred)_.
 - **Generated**: the real system time (`date -Iminutes`).
 - External systems: those from answer 3, plus systems the code demonstrably uses
@@ -233,8 +234,8 @@ Show the user the path, the number of deviations, and any failing check.
 - **Always Mermaid** (ignore `diagram_format`; PlantUML/D2 are CLI-only). Mermaid is
   the source of truth; every diagram is also rendered to a PNG and embedded in the
   Markdown (see [Rendering](#rendering)).
-- **Always fenced**: every diagram is a complete ` ```mermaid ` … ` ``` `
-  block, with nothing else inside it.
+- **Always complete**: every diagram is a complete Mermaid diagram (a ` ```mermaid `
+  block, or its `.mmd` file once rendered), with nothing else in it.
 - **Always labeled**:
   - C4 and `sequenceDiagram`: the first line after the diagram type is `title <text>`
     (`System Context: <project>`, `Containers: <project>`);
@@ -292,7 +293,7 @@ this line: _Disabled in `.featuredoc.yml` (`diagrams`)._
 
 `diagrams_png` in `.featuredoc.yml` [`embed`]: `embed` (below), `file` (the PNG goes to
 `<output_dir>/img/<slug>-<diagram>.png`, linked with `![<title>](img/<slug>-<diagram>.png)`)
-or `off` (no image, only the Mermaid block).
+or `off` (no image; the ` ```mermaid ` block stays in the document).
 
 - **Mode comes only from `.featuredoc.yml`.** No file or no `diagrams_png` key → `embed`.
   Never infer the mode from existing files (an `img/` folder, how an earlier doc did it).
@@ -300,26 +301,32 @@ or `off` (no image, only the Mermaid block).
   `![...](data:image/png;base64,`. A relative path such as `](img/` is an error: embed it and
   delete the loose PNG.
 - Embed the PNG with a script (read file → base64 → replace the line), never by hand.
+- **No Mermaid source in the document** once its PNG is there: no ` ```mermaid ` block
+  and no `<details>` with the source. The source lives in
+  `<output_dir>/diagrams/<slug>-<diagram>.mmd`.
 
-1. Write each ` ```mermaid ` block to a temporary `.mmd` file outside the repo and run:
-   `npx -y @mermaid-js/mermaid-cli -i <tmp>.mmd -o <tmp>.png -s 2 -b white -t default -p <puppeteer.json>`
+1. Write each diagram to `<output_dir>/diagrams/<slug>-<diagram>.mmd` (`<diagram>`:
+   `c4-context`, `c4-container`, `class`, `sequence-current`, `sequence-new`) and run:
+   `npx -y @mermaid-js/mermaid-cli -i <that>.mmd -o <tmp>.png -s 2 -b white -t default -p <puppeteer.json>`
    (`-t default`: Mermaid's normal theme; newer versions otherwise colour every shape).
 2. Set `PUPPETEER_SKIP_DOWNLOAD=true`, and let `puppeteer.json` point at an installed
    browser, so no Chromium is downloaded:
    `{"executablePath": "C:/Program Files (x86)/Microsoft/Edge/Application/msedge.exe"}`
    (or Chrome). Ask the user once before the first npm download: package
    `@mermaid-js/mermaid-cli`, from the npm registry, about 50 MB with dependencies.
-3. Directly below the block, after one empty line:
+3. In the document, in place of the block, two lines:
+   `<!-- kingmadoc:diagram diagrams/<slug>-<diagram>.mmd -->` and
    `![<diagram title>](data:image/png;base64,<base64 of the PNG>)`.
-   No separate image files go into the repo.
-4. The ` ```mermaid ` block always stays (GitHub shows no data URIs; the block is the
-   source for the next render). On a new render, replace only the image line below
-   the same block.
+   No separate image files go into the repo (`file` mode aside).
+4. To change a diagram, edit its `.mmd` file and render again; replace only the image
+   line below its comment. (GitHub shows no data-URI images; there the `.mmd` file is
+   the readable version.)
 5. Look at every PNG after rendering (Read): not empty, no labels cut off at the edge,
    no unexpected extra participants. If needed, fix the Mermaid (split or shorten a
    label) and render again.
-6. If rendering fails, write `_TODO: PNG not generated: <reason>._` below the block
-   (in `language`) and carry on; the document stays valid.
+6. If rendering fails, keep the ` ```mermaid ` block in the document, write
+   `_TODO: PNG not generated: <reason>._` below it (in `language`) and carry on; the
+   document stays valid.
 
 ## Output format
 
@@ -367,7 +374,8 @@ files_expected: [<existing files or folders the user said will change>]
 ## Planned changes
 
 - `<path from files_expected>`: <what changes and why, one to three lines, no code
-  blocks; the "how" from answer 4, or> _TODO: what changes here and why._
+  blocks (a small classDiagram with the changed members instead of a snippet); the "how"
+  from answer 4, or> _TODO: what changes here and why._
 
 ## Requirements
 
@@ -449,7 +457,7 @@ The classes this feature touches and their direct collaborators.
 
 Omit "**Answered while planning**" when nothing was answered.
 
-- Every diagram is a ` ```mermaid ` block with its PNG below it (see
+- Every diagram is its PNG, with the Mermaid source in a `.mmd` file (see
   [Rendering](diagram-rules.md#rendering)); a disabled diagram keeps its section with
   _Disabled in `.featuredoc.yml` (`diagrams`)._
 - **Generated** is the real system time (`date -Iminutes`), never a guess.

{kingmadoc-0.3.0.dev14 → kingmadoc-0.3.0.dev16}/skill/cursor.md

@@ -146,7 +146,8 @@ the diagrams, but never beyond what the user said or the code shows.
   vague REQ or invented ones. Under each: `Verified by: <test, test case or command>`
   (or `_TODO_`).
 - **Planned changes**: per `files_expected` path what changes and why (the "how" of
-  answer 4), one to three lines, no code blocks. Risks and assumptions may add code
+  answer 4), one to three lines, no code blocks; where a code snippet would help
+  (a new method, a changed signature), draw a small `classDiagram` with just those members. Risks and assumptions may add code
   findings marked _(inferred)_.
 - **Generated**: the real system time (`date -Iminutes`).
 - External systems: those from answer 3, plus systems the code demonstrably uses
@@ -234,8 +235,8 @@ Show the user the path, the number of deviations, and any failing check.
 - **Always Mermaid** (ignore `diagram_format`; PlantUML/D2 are CLI-only). Mermaid is
   the source of truth; every diagram is also rendered to a PNG and embedded in the
   Markdown (see [Rendering](#rendering)).
-- **Always fenced**: every diagram is a complete ` ```mermaid ` … ` ``` `
-  block, with nothing else inside it.
+- **Always complete**: every diagram is a complete Mermaid diagram (a ` ```mermaid `
+  block, or its `.mmd` file once rendered), with nothing else in it.
 - **Always labeled**:
   - C4 and `sequenceDiagram`: the first line after the diagram type is `title <text>`
     (`System Context: <project>`, `Containers: <project>`);
@@ -293,7 +294,7 @@ this line: _Disabled in `.featuredoc.yml` (`diagrams`)._
 
 `diagrams_png` in `.featuredoc.yml` [`embed`]: `embed` (below), `file` (the PNG goes to
 `<output_dir>/img/<slug>-<diagram>.png`, linked with `![<title>](img/<slug>-<diagram>.png)`)
-or `off` (no image, only the Mermaid block).
+or `off` (no image; the ` ```mermaid ` block stays in the document).
 
 - **Mode comes only from `.featuredoc.yml`.** No file or no `diagrams_png` key → `embed`.
   Never infer the mode from existing files (an `img/` folder, how an earlier doc did it).
@@ -301,26 +302,32 @@ or `off` (no image, only the Mermaid block).
   `![...](data:image/png;base64,`. A relative path such as `](img/` is an error: embed it and
   delete the loose PNG.
 - Embed the PNG with a script (read file → base64 → replace the line), never by hand.
+- **No Mermaid source in the document** once its PNG is there: no ` ```mermaid ` block
+  and no `<details>` with the source. The source lives in
+  `<output_dir>/diagrams/<slug>-<diagram>.mmd`.
 
-1. Write each ` ```mermaid ` block to a temporary `.mmd` file outside the repo and run:
-   `npx -y @mermaid-js/mermaid-cli -i <tmp>.mmd -o <tmp>.png -s 2 -b white -t default -p <puppeteer.json>`
+1. Write each diagram to `<output_dir>/diagrams/<slug>-<diagram>.mmd` (`<diagram>`:
+   `c4-context`, `c4-container`, `class`, `sequence-current`, `sequence-new`) and run:
+   `npx -y @mermaid-js/mermaid-cli -i <that>.mmd -o <tmp>.png -s 2 -b white -t default -p <puppeteer.json>`
    (`-t default`: Mermaid's normal theme; newer versions otherwise colour every shape).
 2. Set `PUPPETEER_SKIP_DOWNLOAD=true`, and let `puppeteer.json` point at an installed
    browser, so no Chromium is downloaded:
    `{"executablePath": "C:/Program Files (x86)/Microsoft/Edge/Application/msedge.exe"}`
    (or Chrome). Ask the user once before the first npm download: package
    `@mermaid-js/mermaid-cli`, from the npm registry, about 50 MB with dependencies.
-3. Directly below the block, after one empty line:
+3. In the document, in place of the block, two lines:
+   `<!-- kingmadoc:diagram diagrams/<slug>-<diagram>.mmd -->` and
    `![<diagram title>](data:image/png;base64,<base64 of the PNG>)`.
-   No separate image files go into the repo.
-4. The ` ```mermaid ` block always stays (GitHub shows no data URIs; the block is the
-   source for the next render). On a new render, replace only the image line below
-   the same block.
+   No separate image files go into the repo (`file` mode aside).
+4. To change a diagram, edit its `.mmd` file and render again; replace only the image
+   line below its comment. (GitHub shows no data-URI images; there the `.mmd` file is
+   the readable version.)
 5. Look at every PNG after rendering (Read): not empty, no labels cut off at the edge,
    no unexpected extra participants. If needed, fix the Mermaid (split or shorten a
    label) and render again.
-6. If rendering fails, write `_TODO: PNG not generated: <reason>._` below the block
-   (in `language`) and carry on; the document stays valid.
+6. If rendering fails, keep the ` ```mermaid ` block in the document, write
+   `_TODO: PNG not generated: <reason>._` below it (in `language`) and carry on; the
+   document stays valid.
 
 ## Output format
 
@@ -368,7 +375,8 @@ files_expected: [<existing files or folders the user said will change>]
 ## Planned changes
 
 - `<path from files_expected>`: <what changes and why, one to three lines, no code
-  blocks; the "how" from answer 4, or> _TODO: what changes here and why._
+  blocks (a small classDiagram with the changed members instead of a snippet); the "how"
+  from answer 4, or> _TODO: what changes here and why._
 
 ## Requirements
 
@@ -450,7 +458,7 @@ The classes this feature touches and their direct collaborators.
 
 Omit "**Answered while planning**" when nothing was answered.
 
-- Every diagram is a ` ```mermaid ` block with its PNG below it (see
+- Every diagram is its PNG, with the Mermaid source in a `.mmd` file (see
   [Rendering](diagram-rules.md#rendering)); a disabled diagram keeps its section with
   _Disabled in `.featuredoc.yml` (`diagrams`)._
 - **Generated** is the real system time (`date -Iminutes`), never a guess.

{kingmadoc-0.3.0.dev14 → kingmadoc-0.3.0.dev16}/skill/explaining-code/SKILL.md

@@ -41,7 +41,8 @@ Rules:
   stops it; never a proposal.
 - **Picture, caption, table. No stories.** Every figure has a numbered caption
   (`**Figure 3.** …`, no gaps) and at most three sentences; a table decodes it. Never
-  describe a diagram in prose, never paste code as an image, no filler.
+  describe a diagram in prose, never paste code as an image, no filler. Where a code
+  snippet would explain a class or signature, draw a small UML class diagram instead.
 - **Zoom in step by step,** one small diagram per level (at most about fifteen elements).
 - **Every figure follows its model's notation** ([reference/c4-model.md](reference/c4-model.md),
   [reference/models.md](reference/models.md)) and passes its checklist: a title, a

{kingmadoc-0.3.0.dev14 → kingmadoc-0.3.0.dev16}/skill/reference/diagram-rules.md

@@ -3,8 +3,8 @@
 - **Always Mermaid** (ignore `diagram_format`; PlantUML/D2 are CLI-only). Mermaid is
   the source of truth; every diagram is also rendered to a PNG and embedded in the
   Markdown (see [Rendering](#rendering)).
-- **Always fenced**: every diagram is a complete ` ```mermaid ` … ` ``` `
-  block, with nothing else inside it.
+- **Always complete**: every diagram is a complete Mermaid diagram (a ` ```mermaid `
+  block, or its `.mmd` file once rendered), with nothing else in it.
 - **Always labeled**:
   - C4 and `sequenceDiagram`: the first line after the diagram type is `title <text>`
     (`System Context: <project>`, `Containers: <project>`);
@@ -62,7 +62,7 @@ this line: _Disabled in `.featuredoc.yml` (`diagrams`)._
 
 `diagrams_png` in `.featuredoc.yml` [`embed`]: `embed` (below), `file` (the PNG goes to
 `<output_dir>/img/<slug>-<diagram>.png`, linked with `![<title>](img/<slug>-<diagram>.png)`)
-or `off` (no image, only the Mermaid block).
+or `off` (no image; the ` ```mermaid ` block stays in the document).
 
 - **Mode comes only from `.featuredoc.yml`.** No file or no `diagrams_png` key → `embed`.
   Never infer the mode from existing files (an `img/` folder, how an earlier doc did it).
@@ -70,23 +70,29 @@ or `off` (no image, only the Mermaid block).
   `![...](data:image/png;base64,`. A relative path such as `](img/` is an error: embed it and
   delete the loose PNG.
 - Embed the PNG with a script (read file → base64 → replace the line), never by hand.
+- **No Mermaid source in the document** once its PNG is there: no ` ```mermaid ` block
+  and no `<details>` with the source. The source lives in
+  `<output_dir>/diagrams/<slug>-<diagram>.mmd`.
 
-1. Write each ` ```mermaid ` block to a temporary `.mmd` file outside the repo and run:
-   `npx -y @mermaid-js/mermaid-cli -i <tmp>.mmd -o <tmp>.png -s 2 -b white -t default -p <puppeteer.json>`
+1. Write each diagram to `<output_dir>/diagrams/<slug>-<diagram>.mmd` (`<diagram>`:
+   `c4-context`, `c4-container`, `class`, `sequence-current`, `sequence-new`) and run:
+   `npx -y @mermaid-js/mermaid-cli -i <that>.mmd -o <tmp>.png -s 2 -b white -t default -p <puppeteer.json>`
    (`-t default`: Mermaid's normal theme; newer versions otherwise colour every shape).
 2. Set `PUPPETEER_SKIP_DOWNLOAD=true`, and let `puppeteer.json` point at an installed
    browser, so no Chromium is downloaded:
    `{"executablePath": "C:/Program Files (x86)/Microsoft/Edge/Application/msedge.exe"}`
    (or Chrome). Ask the user once before the first npm download: package
    `@mermaid-js/mermaid-cli`, from the npm registry, about 50 MB with dependencies.
-3. Directly below the block, after one empty line:
+3. In the document, in place of the block, two lines:
+   `<!-- kingmadoc:diagram diagrams/<slug>-<diagram>.mmd -->` and
    `![<diagram title>](data:image/png;base64,<base64 of the PNG>)`.
-   No separate image files go into the repo.
-4. The ` ```mermaid ` block always stays (GitHub shows no data URIs; the block is the
-   source for the next render). On a new render, replace only the image line below
-   the same block.
+   No separate image files go into the repo (`file` mode aside).
+4. To change a diagram, edit its `.mmd` file and render again; replace only the image
+   line below its comment. (GitHub shows no data-URI images; there the `.mmd` file is
+   the readable version.)
 5. Look at every PNG after rendering (Read): not empty, no labels cut off at the edge,
    no unexpected extra participants. If needed, fix the Mermaid (split or shorten a
    label) and render again.
-6. If rendering fails, write `_TODO: PNG not generated: <reason>._` below the block
-   (in `language`) and carry on; the document stays valid.
+6. If rendering fails, keep the ` ```mermaid ` block in the document, write
+   `_TODO: PNG not generated: <reason>._` below it (in `language`) and carry on; the
+   document stays valid.

{kingmadoc-0.3.0.dev14 → kingmadoc-0.3.0.dev16}/skill/reference/formats.md

@@ -44,7 +44,8 @@ files_expected: [<existing files or folders the user said will change>]
 ## Planned changes
 
 - `<path from files_expected>`: <what changes and why, one to three lines, no code
-  blocks; the "how" from answer 4, or> _TODO: what changes here and why._
+  blocks (a small classDiagram with the changed members instead of a snippet); the "how"
+  from answer 4, or> _TODO: what changes here and why._
 
 ## Requirements
 
@@ -126,7 +127,7 @@ The classes this feature touches and their direct collaborators.
 
 Omit "**Answered while planning**" when nothing was answered.
 
-- Every diagram is a ` ```mermaid ` block with its PNG below it (see
+- Every diagram is its PNG, with the Mermaid source in a `.mmd` file (see
   [Rendering](diagram-rules.md#rendering)); a disabled diagram keeps its section with
   _Disabled in `.featuredoc.yml` (`diagrams`)._
 - **Generated** is the real system time (`date -Iminutes`), never a guess.