kingmadoc 0.2.0__tar.gz → 0.3.0.dev8__tar.gz

{kingmadoc-0.2.0 → kingmadoc-0.3.0.dev8}/.github/workflows/release.yml

@@ -1,10 +1,17 @@
 name: Release
 
-# Push a tag like v0.2.0: build, publish to PyPI (trusted publishing, no API token) and
-# create the GitHub release with the built files. One-time setup: see RELEASING.md.
+# Two channels, both with PyPI trusted publishing (no API token; setup: docs/releasing.md):
+# - Release: push a tag like v0.2.0. Publishes 0.2.0 and creates the GitHub release.
+# - Beta: every commit on main whose CI passed. Publishes its development version
+#   (e.g. 0.3.0.dev12, from hatch-vcs). pip installs it only when asked for pre-releases
+#   (pipx install --pip-args=--pre kingmadoc), so ordinary installs keep the release.
 on:
   push:
     tags: ["v*"]
+  workflow_run:
+    workflows: [CI]
+    types: [completed]
+    branches: [main]
 
 permissions:
   contents: read
@@ -12,12 +19,20 @@ permissions:
 jobs:
   build:
     name: Build and test the distribution
+    # Beta: only a push to this repository's main whose CI passed (not a pull request).
+    if: >-
+      github.event_name == 'push' || (
+        github.event.workflow_run.conclusion == 'success' &&
+        github.event.workflow_run.event == 'push' &&
+        github.event.workflow_run.head_repository.full_name == github.repository
+      )
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
-          fetch-depth: 0  # the version comes from the tag (hatch-vcs)
-      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97  # v7.0.0
+          fetch-depth: 0 # the version comes from the tag (hatch-vcs)
+          ref: ${{ github.event.workflow_run.head_sha || github.ref }}
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:
           python-version: "3.11"
       - name: Build
@@ -25,10 +40,14 @@ jobs:
           python -m pip install build twine
           python -m build
           twine check --strict dist/*
-      - name: The version is the tag
+      - name: The version is the tag (release) or a development version (beta)
         run: |
-          version="${GITHUB_REF_NAME#v}"
-          ls dist/kingmadoc-"$version".tar.gz dist/kingmadoc-"$version"-py3-none-any.whl
+          if [ "$GITHUB_EVENT_NAME" = push ]; then
+            version="${GITHUB_REF_NAME#v}"
+            ls dist/kingmadoc-"$version".tar.gz dist/kingmadoc-"$version"-py3-none-any.whl
+          else
+            ls dist/kingmadoc-*.dev*-py3-none-any.whl
+          fi
       - name: The wheel works on its own (skills and templates included)
         run: |
           python -m venv "$RUNNER_TEMP/venv"
@@ -36,9 +55,9 @@ jobs:
           cd "$RUNNER_TEMP"
           "$RUNNER_TEMP/venv/bin/kingmadoc" --version
           "$RUNNER_TEMP/venv/bin/kingmadoc" plan "Release check." --no-input --stdout > /dev/null
-          "$RUNNER_TEMP/venv/bin/kingmadoc" skills install
+          "$RUNNER_TEMP/venv/bin/kingmadoc" skills install --no-vscode
           test -f .claude/skills/explaining-code/SKILL.md
-      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7.0.1
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: dist
           path: dist/
@@ -52,23 +71,27 @@ jobs:
       name: pypi
       url: https://pypi.org/p/kingmadoc
     permissions:
-      id-token: write  # trusted publishing
+      id-token: write # trusted publishing
     steps:
-      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c  # v8.0.1
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
         with:
           name: dist
           path: dist/
-      - uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33  # v1.14.2
+      - uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
+        with:
+          # A re-run of the same commit builds the same version: not an error.
+          skip-existing: true
 
   github-release:
     name: GitHub release
     needs: pypi
+    if: github.event_name == 'push'
     runs-on: ubuntu-latest
     permissions:
       contents: write
     steps:
-      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
-      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c  # v8.0.1
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
         with:
           name: dist
           path: dist/

{kingmadoc-0.2.0 → kingmadoc-0.3.0.dev8}/CHANGELOG.md

@@ -7,6 +7,50 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Changed
+
+- Tidier diagrams: `kingmadoc render` lays figures out with ELK (straight,
+  right-angled arrows with fewer crossings; a diagram that sets its own
+  `layout-engine` keeps it) and warns about more than 12 arrows or two arrows between
+  the same shapes. `explaining-code` 5.7: one flow direction, one arrow per pair, at
+  most 12 arrows, labels of at most six words; C4 boundary labels sit top-left in a
+  small font so arrows do not cross them. At hand-over the agent asks whether VS Code
+  should open explainers as a preview (the pictures only show there) and sets it up on
+  yes.
+- Beta channel: every commit on `main` that passes CI is published to PyPI as a
+  development version (`0.3.0.devN`); follow it with
+  `pipx install --pip-args=--pre kingmadoc` and `pipx upgrade kingmadoc`.
+- Fewer tokens for agents: `kingmadoc render` prints one line per document
+  (`--verbose` lists every image), `kingmadoc explain facts --only routes,data` prints
+  only the sections asked for, and `explaining-code` 5.6 works quietly, loads reference
+  sections on demand (each long reference starts with its contents), lets a subagent
+  read a big codebase and return a compact summary, fixes a figure by editing its
+  `.d2`, and hands over in at most five lines. The `kingmadoc` skill does not paste the
+  plan into the chat either.
+- `kingmadoc skills install` asks in a terminal whether VS Code should open explainers
+  as a rendered preview (default yes); `--vscode` / `--no-vscode` answer up front, and
+  agents or pipes only get a tip. `kingmadoc render` says how to see the pictures
+  (Ctrl+Shift+V) while that setting is missing.
+
+### Added
+
+- `kingmadoc explain facts` lists private modules from the dominator tree of the module
+  graph (Python and JavaScript/TypeScript): what only one module leads to belongs to
+  it, which shows the real component boundaries. A single entry point is left out.
+- `explaining-code` model "Algorithm": a flowchart, at most 15 lines of pseudocode, the
+  formula as `$$ … $$` (GitHub and VS Code render it), the invariant, the complexity and
+  a trace table on a small input.
+
+### Fixed
+
+- Dark mode: the C4 style of `explaining-code` (5.5) set black title text and white
+  boundaries and nodes, which were unreadable or glaring in dark mode. Titles and
+  labels now follow the theme and boundaries are transparent; `kingmadoc render` warns
+  about such styles in existing diagrams (fixed text colour without a fill, white
+  fills, a `sequence_diagram` whose container key shows as a heading).
+- `kingmadoc render`: images get normal file permissions (0644) instead of D2's private
+  0600.
+
 ## [0.2.0] - 2026-09-27
 
 Explain existing code with pictures, machine-readable plans, and a `verify` that

{kingmadoc-0.2.0 → kingmadoc-0.3.0.dev8}/CLAUDE.md

@@ -36,7 +36,7 @@ Flow for `plan "<description>"` (`cli.py`): `config.load_config` → `plan.analy
 - `render.py` (`kingmadoc render <doc>`): renders each ```` ```d2 ```` block to `img/<doc>-<n>.svg` (D2 via `d2_binary.ensure_d2`), moves its source to `img/<doc>-<n>.d2`, and leaves only `<!-- kingmadoc:diagram img/<doc>-<n>.d2 -->` + the image in the document (the comment is invisible in previews; re-rendering reads the `.d2` files, so edit those). Converts the older `<details>` format. Renders everything to a temp dir first, so a failing diagram changes nothing.
 - `d2_binary.py`: `ensure_d2` finds D2 (`KINGMADOC_D2`, PATH, cache) or downloads the pinned release once into the user cache; the SHA-256 per platform is pinned in `D2_ASSETS` (update version + all hashes together, cross-checked with the release's SHA256SUMS). `skills.py` + `kingmadoc skills install`: the skills in `skill/` ship as package data (hatch force-include) and are copied into the agent's skills dir; a `.kingmadoc-skill.json` manifest per skill folder records the installed hashes, so a reinstall updates unchanged files and only blocks local edits (`PREVIOUS_RELEASES` is the frozen hash list for installs from before the manifest).
 - `skill/explaining-code/`: second product skill; explains existing code (feature, branch, project, part) with D2 pictures, one folder per subject `docs/explain/<NNNN>-<slug>/README.md` (`explain.py` + `kingmadoc explain new`: next ID, never reused, same subject reuses its folder; regenerates the index `docs/explain/README.md`, also after `render` of such a file; `explain status` → `freshness`: `git diff --relative --name-only <Based on commit>` over the paths the explainer names in code spans (else the whole project), excluding `docs/explain`; `render` names a README's images `figure-<n>`). `SKILL.md` = workflow and D2 examples; the formats are `reference/arc42.md` (default) and `reference/c4.md`, chosen by `explain.format`; `reference/split.md` for `explain.documents: split` (cover + `functional.md` + `technical.md`); `reference/c4-model.md` (Simon Brown's C4: abstractions, 7 diagrams, notation, D2 style block, checklist) and `reference/models.md` (decision table + rules + one example per other model). `tests/test_skill_explaining_code.py` checks its format and compiles every D2 example with the real `d2` when available (`D2_BIN`); `tests/test_skill_models.py` checks every example obeys its model's rules. D2 pitfalls: quote labels with `[`/`:`; `source-arrowhead` only works on `<->`.
-- `facts/` (`kingmadoc explain facts`): pure parsers `projects.project_references` (.csproj) and `data_model.data_model` (EF Core via `DbSet<T>`, Prisma, Django, SQLAlchemy, TypeORM; regex, test files skipped) → frozen `Entity`/`Field`/`Relation`; `routes.routes` (ASP.NET controllers + minimal APIs, Next.js app/pages, Django urls + decorators, FastAPI, Flask, Express; `access` = what the code states), `services.services` (.NET DI), `js_modules.js_dependencies` (relative + tsconfig `paths` imports, `plan.dependencies.collapse` above 25 modules); `branch.branch_changes` (git I/O via `git.run_git`, merge base → working tree); `collect.collect_facts` reads files from the `CodebaseReport` and renders Markdown/JSON.
+- `facts/` (`kingmadoc explain facts`): pure parsers `projects.project_references` (.csproj) and `data_model.data_model` (EF Core via `DbSet<T>`, Prisma, Django, SQLAlchemy, TypeORM; regex, test files skipped) → frozen `Entity`/`Field`/`Relation`; `routes.routes` (ASP.NET controllers + minimal APIs, Next.js app/pages, Django urls + decorators, FastAPI, Flask, Express; `access` = what the code states), `services.services` (.NET DI), `js_modules.js_dependencies` (relative + tsconfig `paths` imports, `plan.dependencies.collapse` above 25 modules, `max_nodes=None` for the raw graph), `dominators.private_modules` (Cooper–Harvey–Kennedy on the raw Python + JS graphs; virtual root above the modules nothing imports; a single entry point is left out); `branch.branch_changes` (git I/O via `git.run_git`, merge base → working tree); `collect.collect_facts` reads files from the `CodebaseReport` and renders Markdown/JSON.
 - `plandoc.py` (not a mode; pure): the plan frontmatter (B2) and `REQ-n` requirements (B1): `check_plan` (every problem as a message), `parse_plan` → `PlanMeta`, `set_status` (frontmatter + header table). `kingmadoc check <slug>` / `approve <slug>` in `cli.py` use `verify.locate.find_plan`. The template renders the frontmatter from `PlanContext.slug/requirements/files_expected` (`generator.requirements_from_answers`: acceptance answer split on `;`/newlines; `files_from_answers`: existing paths only).
 - `verify/` (`kingmadoc verify <slug> [--run-checks]`): `locate.find_plan` (bad slug / missing plan → `VerificationError`) → `changes.detect_changes` (git; base = parent of the commit that added the plan, else last commit before **Generated** + 59 s; working tree incl. untracked; the plan's folder ignored) → `deviations.find_deviations` (pure: draft plan with code = process, `files_expected` untouched / changes outside, `REQ-n` not mentioned in tests or commit messages, containers vs `planned_containers` from the plan text; the CLI passes `infer_containers` names since verify may not import plan) → `commands.detect_commands` (config `verify:` > Makefile > npm > cargo > go > dotnet > pytest/ruff) and `run_check` (no shell; only with `--run-checks`, never enabled by the repo's config) → `report.render_verify` + `verify_status`; the plan's status becomes `implemented`/`partial` unless draft or not verified (written together, `write_documents`). Modes may not import each other (E5, auto-checked), so shared I/O lives in `documents.py`.
 - `diagrams/`: backend pattern, selected by `diagram_format` (`mermaid` default, `plantuml`, `d2`) via `diagrams.get_backend`. `base.py` has the `DiagramBackend` Protocol (`render_context/container/component/sequence/class`) and the shared pure model: `build_*` validate input, assign unique aliases and resolve relationships into frozen `Diagram`/`Node`/`Edge`. Backend modules (`mermaid.py`, `plantuml.py`, `d2.py`) only format that model and return a fenced block (templates must not add fences). Escaping differs per backend and is verified against the real tools: Mermaid `"`→`#quot;` (C4 titles drop `#`/`;`), PlantUML `"`→`<U+0022>`, D2 escapes `\`, `"`, `$`. Adding a backend: a module, an entry in `diagrams.BACKENDS` and `config.DIAGRAM_FORMATS`, snapshots via `KINGMADOC_UPDATE_SNAPSHOTS=1 pytest tests/test_diagram_backends.py`. Extra-doc templates pick their ER/flowchart placeholder by `diagram_format`. No knowledge of analysis: `generator.build_plan_context` maps analysis → C4 elements.

{kingmadoc-0.2.0 → kingmadoc-0.3.0.dev8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: kingmadoc
-Version: 0.2.0
+Version: 0.3.0.dev8
 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
@@ -75,16 +75,25 @@ for Claude Code, Cursor, Codex or GitHub Copilot.
 Requires Python 3.11+.
 
 ```bash
-pipx install git+https://github.com/ATkingma/KingmaDoc
+pipx install kingmadoc      # from PyPI
+pipx upgrade kingmadoc      # later: update to the newest release
 ```
 
-Once KingmaDoc is published on PyPI, this becomes `pipx install kingmadoc`, and
-`pipx upgrade kingmadoc` updates it.
+**Beta:** every commit on `main` that passes CI is published as a development version
+(e.g. `0.3.0.dev12`). Plain installs ignore it; to follow the beta:
 
-To update a git install to the latest commit, run `pipx reinstall kingmadoc`;
-`kingmadoc --version` then shows the new version and commit (every commit has a higher
-version, e.g. `0.2.0.dev43 (git 1a2b3c4)`). (`pipx install --force` fails on recent pipx
-versions with "Failed to create virtual environment" and keeps the old version.)
+```bash
+pipx install --pip-args=--pre kingmadoc   # once (pipx remembers --pre)
+pipx upgrade kingmadoc                    # later: the newest beta
+```
+
+For the latest commit instead of a release, install from GitHub with
+`pipx install git+https://github.com/ATkingma/KingmaDoc` and update it with
+`pipx reinstall kingmadoc`; `kingmadoc --version` then shows the commit
+(`0.2.1.dev3 (git 1a2b3c4)`). (`pipx install --force` fails on recent pipx versions with
+"Failed to create virtual environment" and keeps the old version.) An install from
+before 0.2.0 came from GitHub: `pipx uninstall kingmadoc && pipx install kingmadoc`
+switches it to the releases.
 
 Then, in your project, install the agent skills; that's all:
 
@@ -98,15 +107,17 @@ them are updated; files you edited are kept (`--force` replaces them too).
 
 Nothing else to install: the first `kingmadoc render` downloads the D2 diagram renderer by
 itself (pinned version, checksum-verified; `KINGMADOC_D2_DOWNLOAD=0` turns that off).
-`kingmadoc skills install --vscode` also makes VS Code open explainers (`docs/explain/`)
-as a rendered preview, so you see the pictures right away (it adds one setting to
-`.vscode/settings.json`, only when you pass `--vscode`; Visual Studio shows a preview by
-default).
+VS Code opens a `.md` file as text, which shows no pictures. `kingmadoc skills install`
+asks whether VS Code should open explainers (`docs/explain/`) as a rendered preview
+instead, so you see the pictures right away (one setting in `.vscode/settings.json`;
+`--vscode` / `--no-vscode` answer up front). Without it, press Ctrl+Shift+V in an
+explainer. Visual Studio shows a preview by default. The pictures follow VS Code's light
+or dark theme.
 
 ### pip
 
 ```bash
-pip install git+https://github.com/ATkingma/KingmaDoc   # into the current environment
+pip install kingmadoc   # into the current environment
 ```
 
 ### Markdown-only (no Python)

{kingmadoc-0.2.0 → kingmadoc-0.3.0.dev8}/README.md

@@ -21,16 +21,25 @@ for Claude Code, Cursor, Codex or GitHub Copilot.
 Requires Python 3.11+.
 
 ```bash
-pipx install git+https://github.com/ATkingma/KingmaDoc
+pipx install kingmadoc      # from PyPI
+pipx upgrade kingmadoc      # later: update to the newest release
 ```
 
-Once KingmaDoc is published on PyPI, this becomes `pipx install kingmadoc`, and
-`pipx upgrade kingmadoc` updates it.
+**Beta:** every commit on `main` that passes CI is published as a development version
+(e.g. `0.3.0.dev12`). Plain installs ignore it; to follow the beta:
 
-To update a git install to the latest commit, run `pipx reinstall kingmadoc`;
-`kingmadoc --version` then shows the new version and commit (every commit has a higher
-version, e.g. `0.2.0.dev43 (git 1a2b3c4)`). (`pipx install --force` fails on recent pipx
-versions with "Failed to create virtual environment" and keeps the old version.)
+```bash
+pipx install --pip-args=--pre kingmadoc   # once (pipx remembers --pre)
+pipx upgrade kingmadoc                    # later: the newest beta
+```
+
+For the latest commit instead of a release, install from GitHub with
+`pipx install git+https://github.com/ATkingma/KingmaDoc` and update it with
+`pipx reinstall kingmadoc`; `kingmadoc --version` then shows the commit
+(`0.2.1.dev3 (git 1a2b3c4)`). (`pipx install --force` fails on recent pipx versions with
+"Failed to create virtual environment" and keeps the old version.) An install from
+before 0.2.0 came from GitHub: `pipx uninstall kingmadoc && pipx install kingmadoc`
+switches it to the releases.
 
 Then, in your project, install the agent skills; that's all:
 
@@ -44,15 +53,17 @@ them are updated; files you edited are kept (`--force` replaces them too).
 
 Nothing else to install: the first `kingmadoc render` downloads the D2 diagram renderer by
 itself (pinned version, checksum-verified; `KINGMADOC_D2_DOWNLOAD=0` turns that off).
-`kingmadoc skills install --vscode` also makes VS Code open explainers (`docs/explain/`)
-as a rendered preview, so you see the pictures right away (it adds one setting to
-`.vscode/settings.json`, only when you pass `--vscode`; Visual Studio shows a preview by
-default).
+VS Code opens a `.md` file as text, which shows no pictures. `kingmadoc skills install`
+asks whether VS Code should open explainers (`docs/explain/`) as a rendered preview
+instead, so you see the pictures right away (one setting in `.vscode/settings.json`;
+`--vscode` / `--no-vscode` answer up front). Without it, press Ctrl+Shift+V in an
+explainer. Visual Studio shows a preview by default. The pictures follow VS Code's light
+or dark theme.
 
 ### pip
 
 ```bash
-pip install git+https://github.com/ATkingma/KingmaDoc   # into the current environment
+pip install kingmadoc   # into the current environment
 ```
 
 ### Markdown-only (no Python)

{kingmadoc-0.2.0 → kingmadoc-0.3.0.dev8}/docs/releasing.md

@@ -20,6 +20,15 @@ git has a higher version than the one before. Never set the version by hand.
    is the tag, installs the wheel and runs it (plan, skills install), publishes to PyPI,
    and creates the GitHub release with the changelog section and the built files.
 
+## Beta channel
+
+`release.yml` also runs after every successful CI run on `main` and publishes that
+commit's development version (`0.3.0.devN`) to PyPI with the same trusted publisher;
+it creates no GitHub release. pip installs development versions only with `--pre`, so
+`pipx install kingmadoc` keeps getting releases, and
+`pipx install --pip-args=--pre kingmadoc` follows the beta. A re-run of the same commit
+skips the upload (`skip-existing`). Pull requests never publish.
+
 ## Supply chain
 
 - `uv.lock` pins the development dependencies; CI fails when it is out of date

{kingmadoc-0.2.0 → kingmadoc-0.3.0.dev8}/docs/test-plan.md

@@ -23,9 +23,9 @@ every problem in the [results table](#results) at the end.
 - [ ] Install the CLI (Python 3.11+) and check the version:
 
   ```bash
-  pipx install git+https://github.com/ATkingma/KingmaDoc   # first time
-  pipx reinstall kingmadoc                                 # update to the latest commit
-  kingmadoc --version                                      # shows the installed commit
+  pipx install kingmadoc      # first time (a release from PyPI)
+  pipx upgrade kingmadoc      # update to the newest release
+  kingmadoc --version         # shows the version (and the commit for a git install)
   ```
 
   Do not update with `pipx install --force`: recent pipx versions (uv backend) fail with

kingmadoc-0.3.0.dev8/evals/results/2026-09-27T162715Z.json

@@ -0,0 +1,95 @@
+{
+  "agent": "claude -p {request} --output-format json --max-turns 80 --allowedTools 'Read,Write,Edit,Glob,Grep,Skill,Bash(kingmadoc:*),Bash(git log:*),Bash(git diff:*),Bash(git status:*),Bash(git show:*),Bash(git branch:*),Bash(git rev-parse:*),Bash(ls:*)'",
+  "results": [
+    {
+      "scenario": "explain-feature",
+      "variant": "with skill",
+      "agent": {
+        "exit_code": 0,
+        "seconds": 94,
+        "total_cost_usd": 0.6629856000000001,
+        "num_turns": 12,
+        "reply": "aren't caught.\n5. Paying is a separate call, `POST /orders/<id>/pay/`. It only changes the status from `new` to `paid` and doesn't contact any payment provider. It only finds the customer's own orders, and paying an order that isn't `new` returns 409.\n6. The `shipped` status exists, but no code ever sets it.\n\n**Couldn't work out:** how users log in. There's no login route, and `settings.py` sets no `MIDDLEWARE`, so it's unclear where `request.user` comes from. If you tell me the intended setup, I'll add it to the explainer.\n\nTo see the diagrams in VS Code, open the file and press Ctrl+Shift+V."
+      },
+      "checks": [
+        {
+          "check": "exists docs/explain/0001-*/README.md",
+          "ok": true,
+          "detail": "docs/explain/0001-placing-an-order/README.md"
+        },
+        {
+          "check": "exists docs/explain/README.md",
+          "ok": true,
+          "detail": "docs/explain/README.md"
+        },
+        {
+          "check": "contains docs/explain/0001-*/README.md",
+          "ok": true,
+          "detail": "all present"
+        },
+        {
+          "check": "pictures_only docs/explain/0001-*/*.md",
+          "ok": true,
+          "detail": "6 images"
+        },
+        {
+          "check": "max_questions docs/explain/0001-*/README.md",
+          "ok": true,
+          "detail": "1 question(s)"
+        },
+        {
+          "check": "unchanged_outside [docs/, .claude/]",
+          "ok": true,
+          "detail": "14 change(s), all allowed"
+        }
+      ],
+      "passed": 6,
+      "total": 6
+    },
+    {
+      "scenario": "explain-feature",
+      "variant": "with skill",
+      "agent": {
+        "exit_code": 0,
+        "seconds": 93,
+        "total_cost_usd": 0.6364946500000002,
+        "num_turns": 12,
+        "reply": " the status from `new` to `paid`. If the order isn't `new`, the caller gets 409. No payment provider is involved.\n\nStock is taken off when the order is placed, not when it's paid.\n\n**Things the code doesn't explain** (listed at the end of the explainer; tell me the answers and I'll add them):\n- **How do users log in?** `@login_required` needs session and authentication middleware, but `shop/settings.py` sets no `MIDDLEWARE` and there's no login route.\n- **What sets `shipped`, and what creates `Customer` rows?** No code does either.\n\nIn VS Code, Ctrl+Shift+V opens the preview with the pictures."
+      },
+      "checks": [
+        {
+          "check": "exists docs/explain/0001-*/README.md",
+          "ok": true,
+          "detail": "docs/explain/0001-placing-an-order/README.md"
+        },
+        {
+          "check": "exists docs/explain/README.md",
+          "ok": true,
+          "detail": "docs/explain/README.md"
+        },
+        {
+          "check": "contains docs/explain/0001-*/README.md",
+          "ok": true,
+          "detail": "all present"
+        },
+        {
+          "check": "pictures_only docs/explain/0001-*/*.md",
+          "ok": true,
+          "detail": "6 images"
+        },
+        {
+          "check": "max_questions docs/explain/0001-*/README.md",
+          "ok": true,
+          "detail": "2 question(s)"
+        },
+        {
+          "check": "unchanged_outside [docs/, .claude/]",
+          "ok": true,
+          "detail": "14 change(s), all allowed"
+        }
+      ],
+      "passed": 6,
+      "total": 6
+    }
+  ]
+}

{kingmadoc-0.2.0 → kingmadoc-0.3.0.dev8}/scripts/run_evals.py

@@ -195,8 +195,8 @@ def prepare_workspace(scenario: dict[str, Any], target: Path, with_skills: bool)
         _git(target, "commit", "-qm", f"Work on {branch['name']}")
     if with_skills:
         subprocess.run(
-            [_kingmadoc(), "skills", "install", "--root", str(target)],
-            check=True, capture_output=True,
+            [_kingmadoc(), "skills", "install", "--root", str(target), "--no-vscode"],
+            check=True, capture_output=True, stdin=subprocess.DEVNULL,
         )
         # The skills are part of the setup, not a change by the agent.
         _git(target, "add", ".")

{kingmadoc-0.2.0 → kingmadoc-0.3.0.dev8}/skill/SKILL.md

@@ -130,7 +130,8 @@ the diagrams, but never beyond what the user said or the code shows.
    `<slug>-technical-design.md`
    ([format](reference/formats.md#technical-design-doc-docsfeaturesslug-technical-designmd)), in that
    order. Fill in only what the answers and code support; leave the rest as TODOs.
-2. Show the paths and a three-line summary (scope, biggest risk, open questions count).
+2. Show the paths and a three-line summary (scope, biggest risk, open questions count);
+   do not paste the plan into the chat, and do not narrate while you work.
 3. Ask the user to reply **yes** (approve), **edit <changes>**, or **stop**. On
    **edit**, update the doc and ask again. On **yes**, run `kingmadoc approve <slug>`
    (with the CLI; otherwise set `status: approved` in the frontmatter and **Status** to

{kingmadoc-0.2.0 → kingmadoc-0.3.0.dev8}/skill/codex.md

@@ -130,7 +130,8 @@ the diagrams, but never beyond what the user said or the code shows.
    `<slug>-technical-design.md`
    ([format](#technical-design-doc-docsfeaturesslug-technical-designmd)), in that
    order. Fill in only what the answers and code support; leave the rest as TODOs.
-2. Show the paths and a three-line summary (scope, biggest risk, open questions count).
+2. Show the paths and a three-line summary (scope, biggest risk, open questions count);
+   do not paste the plan into the chat, and do not narrate while you work.
 3. Ask the user to reply **yes** (approve), **edit <changes>**, or **stop**. On
    **edit**, update the doc and ask again. On **yes**, run `kingmadoc approve <slug>`
    (with the CLI; otherwise set `status: approved` in the frontmatter and **Status** to

{kingmadoc-0.2.0 → kingmadoc-0.3.0.dev8}/skill/copilot.md

@@ -130,7 +130,8 @@ the diagrams, but never beyond what the user said or the code shows.
    `<slug>-technical-design.md`
    ([format](#technical-design-doc-docsfeaturesslug-technical-designmd)), in that
    order. Fill in only what the answers and code support; leave the rest as TODOs.
-2. Show the paths and a three-line summary (scope, biggest risk, open questions count).
+2. Show the paths and a three-line summary (scope, biggest risk, open questions count);
+   do not paste the plan into the chat, and do not narrate while you work.
 3. Ask the user to reply **yes** (approve), **edit <changes>**, or **stop**. On
    **edit**, update the doc and ask again. On **yes**, run `kingmadoc approve <slug>`
    (with the CLI; otherwise set `status: approved` in the frontmatter and **Status** to

{kingmadoc-0.2.0 → kingmadoc-0.3.0.dev8}/skill/cursor.md

@@ -131,7 +131,8 @@ the diagrams, but never beyond what the user said or the code shows.
    `<slug>-technical-design.md`
    ([format](#technical-design-doc-docsfeaturesslug-technical-designmd)), in that
    order. Fill in only what the answers and code support; leave the rest as TODOs.
-2. Show the paths and a three-line summary (scope, biggest risk, open questions count).
+2. Show the paths and a three-line summary (scope, biggest risk, open questions count);
+   do not paste the plan into the chat, and do not narrate while you work.
 3. Ask the user to reply **yes** (approve), **edit <changes>**, or **stop**. On
    **edit**, update the doc and ask again. On **yes**, run `kingmadoc approve <slug>`
    (with the CLI; otherwise set `status: approved` in the frontmatter and **Status** to

{kingmadoc-0.2.0 → kingmadoc-0.3.0.dev8}/skill/explaining-code/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: explaining-code
 description: "Explains existing code with rendered diagrams (C4 in Simon Brown's notation; UML sequence, state, class, activity, use case; ER; data flow) and short tables, as an arc42 or compact C4 document, one file or split into functional and technical. Fixes code blindness, e.g. after an agent wrote the code. Scope: a feature, a branch or PR, a whole project, or a folder, service or module. Use when the user asks to explain, describe, document, map, diagram, draw, visualise or give an overview of existing code or architecture; asks how something works, what it does, how the parts fit together, where something happens, or what a branch, PR, commit or task changed; wants onboarding, a walkthrough, a codebase tour, an architecture or design document, arc42, C4, UML, sequence, ER or deployment diagrams of existing code; or no longer understands the code. The request may be in any language. Not for features that are not built yet."
-version: 5.4.0
+version: 5.7.0
 allowed-tools: [Read, Write, Glob, Grep, Bash]
 ---
 
@@ -54,6 +54,27 @@ Rules:
 - Never invent. If something essential cannot be worked out, ask at most three
   questions (Step 6).
 
+## Working efficiently
+
+The context window is shared with the user's work; keep what you load and say small.
+
+- **Work quietly.** No running commentary, no file contents, D2 sources or draft text in
+  the chat. Speak only to ask (Step 1, at most three questions in Step 6) or to hand
+  over (Step 6).
+- **Load on demand.** Read the format file you write, and in
+  [reference/c4-model.md](reference/c4-model.md) and
+  [reference/models.md](reference/models.md) only the sections of the models you draw:
+  each reference starts with a table of contents.
+- **Facts before files.** `kingmadoc explain facts --only <sections>` (e.g.
+  `routes,data`) gives just the part you need; read source files only for what the facts
+  cannot show.
+- **Big codebase** (several services, or more than about 100 source files): let a
+  subagent read the code if your agent can run one (in Claude Code: the Explore agent),
+  and have it return a compact list of containers, components, flows and data with
+  their paths (about 1,500 tokens), not the files themselves.
+- **Fix, don't rewrite.** When a diagram fails to render or needs a change, edit its
+  `img/*.d2` file and render again; do not re-read or rewrite the whole document.
+
 ## Step 1. Pin down the scope, the format and the documents
 
 Decide the scope (table above). If it is unclear what is meant, search first and ask one
@@ -92,7 +113,8 @@ kingmadoc explain facts --base main     # a branch: plus its commits and changed
 ```
 
 Draw from them and never contradict them: the project references and module
-dependencies are the arrows between containers and components, the routes and access
+dependencies are the arrows between containers and components, the private modules
+(dominator tree: everything only one module leads to) are its components' boundaries, the routes and access
 table is the source for routes and permissions, the DI services name the components,
 the data model is the ER diagram's source, the changed files are what a branch explains. (No `explain` command: update KingmaDoc, see Step 5.)
 
@@ -138,6 +160,15 @@ Write every diagram in **D2** (Step 5 turns them into images).
    says: e.g. arc42 section 6 for flows and lifecycles, section 8 for data and domain.
 4. **Readable in dark mode:** the images follow the viewer's light or dark theme. Give
    every shape you fill (`fill:`) a `font-color` too, and black dots a grey `stroke`.
+   Never set a `font-color` without a fill (titles, labels: the theme picks the colour),
+   and never fill white: boundaries and nodes are `fill: transparent`. Put
+   `shape: sequence_diagram` at the top level, or give its container the label `""`.
+5. **Tidy arrows:** set `direction: down` (people on top, data stores at the bottom;
+   `right` only for timelines and swimlanes), draw one arrow per pair of shapes with a
+   combined label, keep at most 12 arrows per figure (split it otherwise, e.g. one
+   figure per container), label each arrow in at most six words plus `[protocol]`, and
+   point arrows at the shapes inside a boundary, not at the boundary. `kingmadoc render`
+   lays figures out with straight, right-angled arrows (ELK) and warns about crowded ones.
 
 For a **branch**, mark changes by border, so the C4 colours stay meaningful, and add
 both to the legend:
@@ -149,6 +180,7 @@ classes: {
   changed: {style: {stroke: "#ef6c00"; stroke-width: 4}}
 }
 title: "[Container] Webshop - branch feature/invoices" {shape: text; near: top-center; style: {font-size: 24; bold: true}}
+direction: down
 vars: {
   d2-legend: {
     n: New in this branch {class: [container; new]}
@@ -197,7 +229,7 @@ on the PATH: `kingmadoc render` does not need it.
 
 - A diagram D2 rejects: fix it and run again.
 - `kingmadoc` has no `render` command: it is outdated; ask the user to update it with
-  `pipx reinstall kingmadoc` (or `pip install -U kingmadoc`), then render.
+  `pipx upgrade kingmadoc` (installed from GitHub: `pipx reinstall kingmadoc`), then render.
 - `kingmadoc` is not installed at all: render with `d2` if it happens to be available
   (save each diagram as `img/figure-<n>.d2` in the subject's folder, run
   `d2 --pad 20 <that>.d2 <that>.svg`, and replace the block with
@@ -208,7 +240,13 @@ on the PATH: `kingmadoc render` does not need it.
 
 Go through the checklist of each figure's model (end of
 [reference/c4-model.md](reference/c4-model.md) and [reference/models.md](reference/models.md))
-and fix what fails. Then show the path, the one-paragraph summary and the figures (check the document embeds the
-images). Ask the "Couldn't work out" questions, at most three, and update the explainer
-with the answers. In VS Code, mention that `kingmadoc skills install --vscode` makes
-explainers open as a rendered preview; do not run it without the user's consent.
+and fix what fails; check that the document embeds every image. Then hand over in at most five lines:
+the path, one or two sentences on what the system is, the number of figures, and the
+"Couldn't work out" questions (at most three), which you then answer into the explainer.
+Do not paste the explainer or its figures into the chat.
+
+VS Code shows the pictures only in its Markdown preview. If `.vscode/settings.json` does
+not yet open `docs/explain/` as a preview, Ask once: "Should VS Code open explainers
+directly as a preview, with the pictures?" and, on yes, run
+`kingmadoc skills install --vscode` (it adds one setting). Never run it without that yes;
+without it, mention that Ctrl+Shift+V shows the pictures.

{kingmadoc-0.2.0 → kingmadoc-0.3.0.dev8}/skill/explaining-code/reference/arc42.md

@@ -1,5 +1,11 @@
 # Format: arc42 (default)
 
+Contents: Output format · What changed (branch only) · 1. Introduction and goals · 2.
+Constraints · 3. Context and scope · 4. Solution strategy · 5. Building block view · 6.
+Runtime view · 7. Deployment view · 8. Cross-cutting concepts · 9. Architecture
+decisions · 10. Quality requirements · 11. Risks and technical debt · 12. Glossary ·
+Appendix: where to find what · Couldn't work out (optional, at most three).
+
 The default explainer format (`explain: {format: arc42}` in `.featuredoc.yml`): the
 twelve sections of the arc42 architecture template, each a figure or a table with a short
 explanation. Follow the rules in `../SKILL.md` (numbered figures, tables that decode
@@ -57,7 +63,7 @@ Text in `<angle brackets>` is filled in; leave out subsections marked optional.
 | **Scope**        | <feature / branch `<branch>` vs `<base>` / project / part `<path>`>                 |
 | **Stack**        | <languages, frameworks, data stores>                                                |
 | **Entry points** | <`path`, …>                                                                         |
-| **Based on**     | <commit hash (branch)> · <ISO date> · KingmaDoc skill explaining-code 5.4.0 (arc42) |
+| **Based on**     | <commit hash (branch)> · <ISO date> · KingmaDoc skill explaining-code 5.7.0 (arc42) |
 
 ## What changed (branch only)