kingmadoc 0.3.0.dev13__tar.gz → 0.3.0.dev15__tar.gz

{kingmadoc-0.3.0.dev13 → kingmadoc-0.3.0.dev15}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: kingmadoc
-Version: 0.3.0.dev13
+Version: 0.3.0.dev15
 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.dev13 → kingmadoc-0.3.0.dev15}/skill/codex.md

@@ -233,8 +233,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>`);
@@ -252,6 +252,9 @@ Show the user the path, the number of deviations, and any failing check.
   `System_Boundary` alias ends in `_boundary` and is never used in `Rel`.
 - **Escaping**: inside quoted labels write `"` as `#quot;`. In titles, leave quotes as
   they are and drop `#` and `;` (they end a C4 title). Put everything on one line.
+- **Colour**: the normal Mermaid theme. No `style`, `classDef` or `%%{init}%%` colours in
+  UML (class, sequence) diagrams; colour only to make one thing stand out, such as the
+  changed containers below.
 - **Short labels**: about 50 characters at most; split a long message in two.
 - **Sequence aliases**: never `x`, `X`, `o` or `O` (they clash with the `-x` and `-o`
   arrows); use abbreviations of two or more letters (`ct`, `svc`).
@@ -289,7 +292,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).
@@ -297,25 +300,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.
-
-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 -p <puppeteer.json>`
+- **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 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
 
@@ -445,7 +455,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.dev13 → kingmadoc-0.3.0.dev15}/skill/copilot.md

@@ -233,8 +233,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>`);
@@ -252,6 +252,9 @@ Show the user the path, the number of deviations, and any failing check.
   `System_Boundary` alias ends in `_boundary` and is never used in `Rel`.
 - **Escaping**: inside quoted labels write `"` as `#quot;`. In titles, leave quotes as
   they are and drop `#` and `;` (they end a C4 title). Put everything on one line.
+- **Colour**: the normal Mermaid theme. No `style`, `classDef` or `%%{init}%%` colours in
+  UML (class, sequence) diagrams; colour only to make one thing stand out, such as the
+  changed containers below.
 - **Short labels**: about 50 characters at most; split a long message in two.
 - **Sequence aliases**: never `x`, `X`, `o` or `O` (they clash with the `-x` and `-o`
   arrows); use abbreviations of two or more letters (`ct`, `svc`).
@@ -289,7 +292,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).
@@ -297,25 +300,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.
-
-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 -p <puppeteer.json>`
+- **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 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
 
@@ -445,7 +455,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.dev13 → kingmadoc-0.3.0.dev15}/skill/cursor.md

@@ -234,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>`);
@@ -253,6 +253,9 @@ Show the user the path, the number of deviations, and any failing check.
   `System_Boundary` alias ends in `_boundary` and is never used in `Rel`.
 - **Escaping**: inside quoted labels write `"` as `#quot;`. In titles, leave quotes as
   they are and drop `#` and `;` (they end a C4 title). Put everything on one line.
+- **Colour**: the normal Mermaid theme. No `style`, `classDef` or `%%{init}%%` colours in
+  UML (class, sequence) diagrams; colour only to make one thing stand out, such as the
+  changed containers below.
 - **Short labels**: about 50 characters at most; split a long message in two.
 - **Sequence aliases**: never `x`, `X`, `o` or `O` (they clash with the `-x` and `-o`
   arrows); use abbreviations of two or more letters (`ct`, `svc`).
@@ -290,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).
@@ -298,25 +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.
-
-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 -p <puppeteer.json>`
+- **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 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
 
@@ -446,7 +456,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.dev13 → kingmadoc-0.3.0.dev15}/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>`);
@@ -22,6 +22,9 @@
   `System_Boundary` alias ends in `_boundary` and is never used in `Rel`.
 - **Escaping**: inside quoted labels write `"` as `#quot;`. In titles, leave quotes as
   they are and drop `#` and `;` (they end a C4 title). Put everything on one line.
+- **Colour**: the normal Mermaid theme. No `style`, `classDef` or `%%{init}%%` colours in
+  UML (class, sequence) diagrams; colour only to make one thing stand out, such as the
+  changed containers below.
 - **Short labels**: about 50 characters at most; split a long message in two.
 - **Sequence aliases**: never `x`, `X`, `o` or `O` (they clash with the `-x` and `-o`
   arrows); use abbreviations of two or more letters (`ct`, `svc`).
@@ -59,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).
@@ -67,22 +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 -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.dev13 → kingmadoc-0.3.0.dev15}/skill/reference/formats.md

@@ -126,7 +126,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.