kingmadoc 0.2.0__tar.gz

kingmadoc-0.2.0/.featuredoc.yml

@@ -0,0 +1,84 @@
+# KingmaDoc configuration. All keys are optional; shown values are the defaults.
+
+# Where generated feature docs are written (relative to the project root).
+output_dir: docs/features
+
+# Plan template: a bundled name, or an explicit path such as ./my_plan.md.j2
+# (relative to the project root). Templates always run sandboxed.
+template: plan_default.md.j2
+
+# Number of clarifying questions asked in `plan` mode (0-5).
+max_questions: 5
+
+project:
+  # Defaults to the project directory name.
+  name: null
+  description: ""
+
+analyzer:
+  max_files: 5000  # maximum
+  tree_depth: 3
+  # Lines read per source file when scanning imports (imports sit at the top).
+  max_lines_per_file: 2000
+  exclude_dirs:
+    - ".git"
+    - ".hg"
+    - ".svn"
+    - ".venv"
+    - "venv"
+    - "env"
+    - "node_modules"
+    - "__pycache__"
+    - ".mypy_cache"
+    - ".pytest_cache"
+    - ".ruff_cache"
+    - ".tox"
+    - "dist"
+    - "build"
+    - "*.egg-info"
+    - "evals"  # fixture projects for the skill evaluations
+
+# Diagrams included in the plan doc.
+diagrams:
+  - c4_context
+  - c4_container
+
+# Diagram language: mermaid, plantuml (C4-PlantUML) or d2.
+diagram_format: mermaid
+
+# Optional extra documents written by `plan` next to the plan doc. `template` is a
+# bundled name or an explicit path (e.g. ./my_design.md.j2); templates run sandboxed.
+# `models` selects the design models (sections) of a document; default: all of them.
+extra_designs:
+  functional_design:
+    # <slug>-functional-design.md: user flows, edge cases, business rules,
+    # permissions and roles.
+    enabled: false
+    template: functional_design.md.j2
+    models: []
+  technical_design:
+    # <slug>-technical-design.md: database schema, API contracts, error handling,
+    # performance and security considerations.
+    enabled: false
+    template: technical_design.md.j2
+    models: [dependency_graph]
+  domain_design:
+    # <slug>-domain-design.md: domain model and event storming.
+    enabled: false
+    template: domain_design.md.j2
+    models: [domain_model, event_storming]
+  security_design:
+    # <slug>-security-design.md: threat model (STRIDE) and who may do what.
+    enabled: false
+    template: security_design.md.j2
+    models: [threat_model, permissions]
+
+# Architecture Decision Records: `kingmadoc adr "<title>"` writes docs/adr/<NNNN>-<slug>.md.
+adr:
+  enabled: false
+  template: adr.md.j2
+
+# Explainers written by the explaining-code agent skill ("explain this project").
+# format: arc42 (the 12 arc42 sections, default) or c4 (compact zoom-in).
+explain:
+  format: arc42

kingmadoc-0.2.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,33 @@
+---
+name: Bug report
+about: Something in KingmaDoc does not work as documented
+title: ""
+labels: bug
+assignees: ""
+---
+
+## What happened
+
+<!-- A clear description of the bug. Include the full error message, if any. -->
+
+## Steps to reproduce
+
+1. <!-- e.g. `kingmadoc plan "Add login." --no-input` in a project with ... -->
+2.
+3.
+
+## Expected behavior
+
+<!-- What you expected to happen instead. -->
+
+## Environment
+
+- KingmaDoc version (`kingmadoc --version`, or "skill"):
+- How you use it: CLI / Claude Code skill / Cursor / Codex / GitHub Copilot
+- Python version (CLI only):
+- Operating system:
+- `diagram_format` and other non-default settings in `.featuredoc.yml`:
+
+## Additional context
+
+<!-- Generated docs (or the relevant part), screenshots, logs. Remove anything private. -->

kingmadoc-0.2.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,24 @@
+---
+name: Feature request
+about: Suggest an idea or improvement for KingmaDoc
+title: ""
+labels: enhancement
+assignees: ""
+---
+
+## Problem
+
+<!-- What are you trying to do, and what makes it hard today?
+     e.g. "After the agent finishes, I can't tell whether ... matches the plan." -->
+
+## Proposed solution
+
+<!-- What should KingmaDoc do? Which part: plan, verify, adr, diagrams, the skill, config? -->
+
+## Alternatives considered
+
+<!-- Other tools or workarounds you tried. -->
+
+## Additional context
+
+<!-- Example documents, diagrams, links. -->

kingmadoc-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,75 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    name: lint (ruff, mypy, conventions)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+        with:
+          fetch-depth: 0  # the version comes from the git tags (hatch-vcs)
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97  # v7.0.0
+        with:
+          python-version: "3.11"
+          cache: pip
+          cache-dependency-path: pyproject.toml
+      - name: Install
+        run: python -m pip install -e ".[dev]"
+      - name: Ruff
+        run: ruff check .
+      - name: mypy --strict
+        run: mypy
+      - name: Architecture contracts (import-linter)
+        run: lint-imports
+      - name: Skill variants up to date
+        run: python scripts/build_skill_variants.py --check
+      - name: Convention checker
+        run: python .claude/skills/checking-conventions/scripts/check_conventions.py
+      - name: Lock file up to date, no known vulnerabilities (pip-audit)
+        run: |
+          python -m pip install uv pip-audit
+          uv lock --check
+          uv export --frozen --all-extras --no-emit-project --format requirements-txt -o "$RUNNER_TEMP/requirements.txt"
+          pip-audit --strict -r "$RUNNER_TEMP/requirements.txt"
+
+  test:
+    name: pytest (${{ matrix.os }}, Python ${{ matrix.python-version }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+        with:
+          fetch-depth: 0  # the version comes from the git tags (hatch-vcs)
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97  # v7.0.0
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+          cache-dependency-path: pyproject.toml
+      - name: Install
+        run: python -m pip install -e ".[dev]"
+      - name: Test
+        if: ${{ !(matrix.os == 'ubuntu-latest' && matrix.python-version == '3.11') }}
+        run: python -m pytest
+      - name: Test with branch coverage (minimum in pyproject.toml)
+        if: ${{ matrix.os == 'ubuntu-latest' && matrix.python-version == '3.11' }}
+        run: python -m pytest --cov --cov-report=term
+      - name: CLI smoke test
+        shell: bash
+        run: |
+          kingmadoc --help
+          cd "$RUNNER_TEMP"
+          kingmadoc init
+          kingmadoc plan "Test feature." --no-input
+          test -f docs/features/test-feature-plan.md

kingmadoc-0.2.0/.github/workflows/release.yml

@@ -0,0 +1,86 @@
+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.
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build and test the distribution
+    runs-on: ubuntu-latest
+    steps:
+      - 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
+        with:
+          python-version: "3.11"
+      - name: Build
+        run: |
+          python -m pip install build twine
+          python -m build
+          twine check --strict dist/*
+      - name: The version is the tag
+        run: |
+          version="${GITHUB_REF_NAME#v}"
+          ls dist/kingmadoc-"$version".tar.gz dist/kingmadoc-"$version"-py3-none-any.whl
+      - name: The wheel works on its own (skills and templates included)
+        run: |
+          python -m venv "$RUNNER_TEMP/venv"
+          "$RUNNER_TEMP/venv/bin/pip" install dist/*.whl
+          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
+          test -f .claude/skills/explaining-code/SKILL.md
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7.0.1
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+
+  pypi:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/kingmadoc
+    permissions:
+      id-token: write  # trusted publishing
+    steps:
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c  # v8.0.1
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33  # v1.14.2
+
+  github-release:
+    name: GitHub release
+    needs: pypi
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c  # v8.0.1
+        with:
+          name: dist
+          path: dist/
+      - name: Create the release with the changelog section
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          version="${GITHUB_REF_NAME#v}"
+          awk -v v="$version" '
+            $0 ~ "^## \\[" v "\\]" { found = 1; next }
+            found && /^## \[/ { exit }
+            found { print }
+          ' CHANGELOG.md > "$RUNNER_TEMP/notes.md"
+          gh release create "$GITHUB_REF_NAME" dist/* --title "KingmaDoc $version" \
+            --notes-file "$RUNNER_TEMP/notes.md" --verify-tag

kingmadoc-0.2.0/.gitignore

@@ -0,0 +1,30 @@
+# Byte-compiled / cache
+__pycache__/
+*.py[cod]
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+
+# Packaging
+build/
+dist/
+*.egg-info/
+.eggs/
+
+# Environments
+.venv/
+venv/
+env/
+.env
+
+# Test / coverage
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+.nox/
+
+# Editors / OS
+.idea/
+.vscode/
+.DS_Store

kingmadoc-0.2.0/CHANGELOG.md

@@ -0,0 +1,214 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.2.0] - 2026-09-27
+
+Explain existing code with pictures, machine-readable plans, and a `verify` that
+compares the code with its plan. Upgrading from 0.1.1:
+
+- Update with `pipx reinstall kingmadoc` (or, once on PyPI, `pipx upgrade kingmadoc`),
+  then run `kingmadoc skills install` again; it updates the skills without `--force`.
+- Plans now start with YAML frontmatter and have a "Requirements" section. Plans from
+  0.1.x have neither: `kingmadoc check` says so, and `verify` reports them as
+  "Not verified". Regenerate the plan, or add the frontmatter by hand
+  (`skill/reference/formats.md`).
+- `kingmadoc verify` now compares the code with the plan and changes the plan's status
+  (`implemented` / `partial`); it runs project commands only with `--run-checks`.
+- `.vscode/settings.json` is only written with `skills install --vscode`.
+- Python API: `skills.install_skills` returns an `InstallResult`; `verify.stub` is
+  replaced by `verify.locate` (`find_plan`) and `verify.report` (`render_verify`).
+
+### Added
+
+**Explain existing code** (agent skill `explaining-code` 5.4, roadmap WP12)
+
+- Explains a feature, a branch (what it changed), a project or a part of one with
+  pictures: an arc42 document by default, or the compact C4 format
+  (`explain.format: c4`); one document, or functional and technical apart
+  (`explain.documents: split`). No audit or risk list; at most three questions.
+- Real C4 diagrams in Simon Brown's notation, plus the models the code calls for, picked
+  from a decision table: UML sequence, state machine, class and domain model, package,
+  activity with swimlanes, use case, ER, data flow with trust boundaries, event flow and
+  DDD context map. Tests check that every example follows its notation and compiles.
+- One folder per subject, `docs/explain/<NNNN>-<name>/`, with an ID that is never
+  reused: `kingmadoc explain new "<name>"` picks or reuses it and keeps the index
+  `docs/explain/README.md` up to date.
+- `kingmadoc explain facts [--base REF] [--json]`: what can be read from the code
+  without guessing, for the agent to draw from: the stack, project references (.NET),
+  Python and JavaScript/TypeScript module dependencies, routes with their access rules
+  (ASP.NET, Next.js, Django, FastAPI, Flask, Express), .NET services, the data model
+  (EF Core, Prisma, Django, SQLAlchemy, TypeORM) and, with `--base`, a branch's commits
+  and changed files.
+- `kingmadoc explain status [--check]`: which explainers the code changed under since
+  the commit they are based on.
+
+**Pictures**
+
+- `kingmadoc render <doc>`: turns the D2 diagrams in a Markdown document into SVG images
+  next to it; the document shows only the pictures, the sources go to `img/*.d2`. The
+  images follow the viewer's dark mode (`--light` for light only). D2 is downloaded on
+  first use (pinned, SHA-256-verified; `KINGMADOC_D2_DOWNLOAD=0` to opt out).
+
+**Plans and verification** (roadmap WP1, WP2)
+
+- Plans start with YAML frontmatter (`kingmadoc: 1`, `feature`, `status`,
+  `requirements`, `files_expected`) and have a "Requirements" section with `REQ-n` IDs
+  from the acceptance criteria. `kingmadoc check <slug>` validates a plan;
+  `kingmadoc approve <slug>` sets `status: approved`, the gate before code.
+- `kingmadoc verify <slug>` compares the code with its plan: the files changed since
+  the plan (git, including uncommitted work), expected files never touched, changes
+  outside the plan, `REQ-n` no test or commit mentions, containers added or gone, and
+  code written before approval. Build, test and lint (from `verify:` in the config, or
+  detected) run only with `--run-checks`. The plan's status becomes `implemented` or
+  `partial`.
+- Design documents: design models per document (`extra_designs.<document>.models`),
+  `domain_design` (domain model, event storming) and `security_design` (STRIDE threat
+  model, permissions matrix); `technical_design` gets a module dependency graph, and
+  `kingmadoc analyze` reports `module_dependencies`.
+
+**Installing and updating**
+
+- `kingmadoc skills install [--agent claude|cursor|codex|copilot]` installs both
+  skills into the project and updates them later without `--force` (only local edits
+  need it); `--vscode` makes VS Code open explainers as a rendered preview.
+- `kingmadoc --version` shows the installed git commit (`0.2.0 (git 1a2b3c4)`).
+
+**Development**
+
+- Skill evaluations (roadmap WP5): scenarios in `evals/`, run with
+  `python scripts/run_evals.py --compare --record`.
+
+### Changed
+
+- The version comes from the git tag (`hatch-vcs`): every commit after a release has a
+  higher development version, so updates of a git install are visible.
+- Release workflow: a `v*` tag builds, tests and publishes to PyPI (trusted
+  publishing) and creates the GitHub release (`docs/releasing.md`).
+- The `kingmadoc` skill (1.1) is split into `SKILL.md` and `reference/`
+  (formats, diagram rules); the Cursor, Codex and Copilot files still hold everything.
+- Quality: branch coverage with a 90 % minimum, property-based tests (Hypothesis),
+  `import-linter` contracts for the architecture rules, `uv.lock`, `pip-audit` and
+  Ruff's security rules in CI.
+- API: `skills.install_skills` returns an `InstallResult`; `verify.stub` is replaced by
+  `verify.locate` and `verify.report`.
+
+### Fixed
+
+- Analyzer: imports in test directories no longer add frameworks to the detected stack.
+- Analyzer: build output of Next.js (`.next/`), Nuxt and SvelteKit is no longer
+  analyzed as source.
+
+## [0.1.1] - 2026-09-26
+
+First public release, including all fixes from the pre-release review. Upgrading from
+the unpublished 0.1.0: move `extra_designs.adr` to a
+top-level `adr:` block, and use `kingmadoc analyze --json` instead of `plan --json`.
+
+### Security
+
+- Templates: `kingmadoc` no longer loads templates from the analyzed project's root,
+  so running it in an untrusted repository cannot execute code from that repository.
+  All templates render in Jinja's sandbox, and a project template is used only when
+  `template:` names an explicit path (`ConfigError` if it is missing or not a file).
+- Config: `output_dir` must resolve inside the project root (symlinks resolved first);
+  a repository's config can no longer make `plan` write outside the project.
+- Analyzer: import scanning no longer takes quadratic time on long runs of blank lines;
+  a crafted file could stall `plan` for minutes (50k blank lines: 75 s → 0.04 s).
+
+### Fixed
+
+- CLI: `plan --stdout` no longer crashes with `UnicodeEncodeError` when stdout is not
+  UTF-8 (piped output on Windows); stdout is written as UTF-8.
+- CLI: `verify` no longer crashes with an unhandled `ValueError` when `output_dir` is an
+  absolute path outside the project; it reports a config error instead.
+- Documents: writing several documents is now truly all-or-nothing; a failure part-way
+  restores replaced files and removes new ones.
+- Analyzer: a manifest with a wrongly typed table or list (e.g. `dependencies = 5`) no
+  longer crashes the analysis.
+- Analyzer: manifests saved with a UTF-8 byte-order mark are parsed instead of skipped.
+- Analyzer: Compose images with a registry port (`registry.local:5000/postgres:16`)
+  are recognized by their image name.
+- Summaries: the first sentence is no longer cut at `e.g.`, `i.e.`, `etc.`, `vs.`,
+  `cf.` or `approx.`, and only ends before a capital letter.
+- Slugs: accented letters are transliterated (`café` → `cafe`); descriptions without
+  Latin letters get a short hash instead of all sharing the slug `feature`.
+- Diagrams: test directories (`__tests__`, `spec`, `src/tests`, ...) are no longer
+  inferred as C4 containers, and loose `src/*.py` files no longer add a `src` container
+  next to `src/<pkg>`.
+- Diagrams: elements with the same name no longer produce wrong arrows
+  (`Rel(user, user)`); duplicate names are rejected, and generated names are unique.
+- ADRs: date-named files such as `docs/adr/2024-q3-review.md` no longer set the next
+  ADR number.
+
+### Changed
+
+- Config: `adr` is a top-level block, `adr: {enabled, template}`; `extra_designs.adr`
+  is rejected as an unknown key.
+- Config: each extra design (`extra_designs.<name>.template`) and `adr.template` can
+  select its own template.
+- CLI: `plan` always requires a description; its `--json` option moved to
+  `kingmadoc analyze --json`.
+- Diagrams: `render_context(relationships=None)` is replaced by the keyword
+  `default_relationships: bool = True`; explicit relationships are drawn in addition to
+  the default arrows.
+- API: `write_document` takes `(path, content)`, like `write_documents`.
+- Packaging: bundled templates live in `src/kingmadoc/templates/`; the sdist no longer
+  contains the repository's Claude Code dev tooling (`.claude/`).
+- Development: Ruff and `mypy --strict` are enforced in CI (new `lint` job), and
+  GitHub Actions are pinned to commit SHAs.
+
+### Added
+
+- CLI: `kingmadoc analyze [--json]` prints the codebase analysis.
+- Config: `analyzer.max_lines_per_file` (default 2000) limits how many lines per source
+  file are read when detecting frameworks; manifests are always read in full.
+- Analyzer: Cargo `[workspace.dependencies]` and `[target.*.dependencies]`, PEP 735
+  `[dependency-groups]`, Poetry `[tool.poetry.group.*.dependencies]` and npm
+  `optionalDependencies` are read.
+- Generator: importing it fails if `EXTRA_DESIGNS` and the `extra_designs` config
+  fields disagree, instead of failing during `plan`.
+- Tests for `init`, custom templates, Ctrl-C during questions, atomic writes, the skill
+  variant `--check`, Poetry dependencies and `verify --config`.
+
+## [0.1.0] - 2026-09-26
+
+Internal milestone; never published. Its contents first shipped in 0.1.1.
+
+### Added
+
+- `kingmadoc plan "<description>"`: analyzes the codebase, asks up to five clarifying
+  questions and writes `docs/features/<slug>-plan.md` with a one-sentence summary,
+  scope (in / out), assumptions, risks, C4 Context and C4 Container diagrams, open
+  questions and a codebase appendix. Options: `--no-input`, `--stdout`, `--output`,
+  `--force`, `--config`, `--root`.
+- `kingmadoc plan --json`: the codebase analysis as JSON (file count, language
+  breakdown, top-level directories, entry points, config files, test directories and
+  detected stack). The analysis reads `pyproject.toml`, `requirements.txt`,
+  `package.json`, `go.mod`, `Cargo.toml` and Docker Compose files, and stops at 5000 files.
+- `kingmadoc verify <slug>`: work-in-progress stub that writes a placeholder
+  `<slug>-verify.md` next to the plan (exit code 1 if the plan does not exist).
+- `kingmadoc adr "<title>"`: numbered Architecture Decision Records in
+  `docs/adr/<NNNN>-<slug>.md`, enabled with `extra_designs.adr.enabled`.
+- `kingmadoc init`: writes `.featuredoc.yml` with every default and a comment per key.
+- Optional extra documents next to the plan: `<slug>-functional-design.md` (user flows,
+  edge cases, business rules, permissions) and `<slug>-technical-design.md` (database
+  schema, API contracts, error handling, performance, security).
+- Diagram backends: Mermaid (default), PlantUML (C4-PlantUML) and D2, selected with
+  `diagram_format`, each with C4 Context/Container/Component, sequence and class diagrams.
+- Markdown-only agent skill `skill/SKILL.md` for Claude Code, with generated variants
+  for Cursor (`skill/cursor.md`), Codex (`skill/codex.md`) and GitHub Copilot
+  (`skill/copilot.md`). The skill performs plan and full verify without Python.
+- Documentation: README, CONTRIBUTING, conventions (`docs/conventions.md`) and an
+  example plan doc (`examples/verify-mode-plan.md`).
+- CI on Python 3.11–3.13 on Linux, macOS and Windows.
+
+[Unreleased]: https://github.com/ATkingma/KingmaDoc/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/ATkingma/KingmaDoc/compare/v0.1.1...v0.2.0
+[0.1.1]: https://github.com/ATkingma/KingmaDoc/compare/v0.1.0...v0.1.1
+[0.1.0]: https://github.com/ATkingma/KingmaDoc/releases/tag/v0.1.0

kingmadoc-0.2.0/CLAUDE.md

@@ -0,0 +1,53 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project
+
+KingmaDoc is a Python CLI (Click, Jinja2, PyYAML) that generates feature docs for AI coding agents, to prevent "code blindness": `plan` writes a Feature Design Doc before implementation (C4/sequence/class diagrams in Mermaid, PlantUML or D2); `verify` writes a Feature Verification Doc afterwards (deviations from the plan, and build/test/lint results with `--run-checks`). `plan` generates C4 Context + Container.
+
+## Commands
+
+```bash
+uv venv -p 3.11 .venv && uv pip install -p .venv -e '.[dev]'   # setup
+.venv/bin/pytest -q                                             # all tests
+.venv/bin/pytest tests/test_config.py::test_unknown_key_raises  # single test
+.venv/bin/kingmadoc plan "Add a feature." --no-input --stdout   # smoke test
+python3 .claude/skills/checking-conventions/scripts/check_conventions.py  # convention check (also runs ruff + mypy when in .venv)
+.venv/bin/ruff check . && .venv/bin/mypy                        # lint + mypy --strict
+.venv/bin/lint-imports && .venv/bin/pytest --cov              # architecture contracts; branch coverage (min 90 %)
+.venv/bin/python scripts/run_evals.py --compare --record     # skill evals (runs real agents; evals/README.md)
+```
+
+The version comes from git tags (`hatch-vcs`; never set it by hand, `kingmadoc.__version__` reads the installed metadata); releases: `docs/releasing.md`. After changing dependencies in `pyproject.toml`, run `uv lock` (CI checks `uv.lock` and runs `pip-audit`). Ruff includes the `S` (bandit) rules; justify a `# noqa: S…` in a comment. A new top-level module must be added to the E1 contract in `[tool.importlinter]` (a test checks it).
+
+A Stop hook (`.claude/settings.json`) runs the convention checker after every turn with uncommitted changes and feeds violations back. Fix them; for manual rules use the `checking-conventions` skill (repo dev tool, not the product skill).
+
+Regenerate `examples/verify-mode-plan.md` after changing the template or generator (it's output of running `plan` on this repo with `-o examples/verify-mode-plan.md --force`; keep its answers).
+
+## Architecture
+
+Flow for `plan "<description>"` (`cli.py`): `config.load_config` → `plan.analyzer.analyze` → `plan.generator.build_questions` (prompts on stderr so `--stdout` stays clean; `--no-input`/closed stdin leaves them unanswered → "Open questions") → `plan.generator.build_plan_context` (pure; CLI passes `now`) → `render_plan` (every `PlanContext` field is a template variable) → `documents.write_documents` (all-or-nothing) to `<output_dir>/<slug>-plan.md`, plus one file per enabled `extra_designs.<name>` (`<slug>-functional-design.md`, `<slug>-technical-design.md`) via `render_extra_design`, each with its own `template:` and `models:` (design-model sections rendered by `plan/models.py`; names per document in `config.DOCUMENT_MODELS`, checked against the registry at import time). To add an extra doc type: a field on `config.ExtraDesignsConfig` (its default sets the bundled template), an `ExtraDesign(name, suffix)` in `generator.EXTRA_DESIGNS` (checked against the config fields at import time), a template, and a format block in `skill/reference/formats.md` → prints one path per line.
+
+- `config.py`: frozen dataclasses with defaults; `parse_config` rejects unknown keys and wrong types. `default_config_yaml()` produces the `init` output and must stay equal to the dataclass defaults (enforced by a test).
+- `plan/analyzer.py`: pathlib walk with fnmatch excludes ("glob", hard cap `MAX_FILES_LIMIT` = 5000), manifest parsing (`pyproject.toml`, `requirements.txt`, `package.json`, `go.mod`, `Cargo.toml`, compose files → `DEPENDENCY_TECH`), regex import scanning ("grep"). Returns an immutable `CodebaseReport` (`kingmadoc analyze` prints it via `format_report`, `--json` via `report_to_dict`); `source_dirs` drives container inference (descends into `src/` layouts, skips tests/docs/examples).
+- `skill/SKILL.md`: the product skill (Markdown-only KingmaDoc for users without Python; not the repo's `checking-conventions` dev skill): the workflow, under 250 lines. Its document formats live in `skill/reference/formats.md` and must keep the same headings as `src/kingmadoc/templates/plan_default.md.j2`, the extra-design templates and `verify/report.py` — `tests/test_skill.py` fails otherwise, so change both together; the Mermaid rules in `skill/reference/diagram-rules.md`. SKILL.md keeps a `## Output format` / `## Diagram rules` stub that links each reference. `skill/cursor.md`, `codex.md`, `copilot.md` are single files generated by `scripts/build_skill_variants.py`, which inlines each reference in place of its stub — never edit them; rerun the script after changing SKILL.md or a reference (`tests/test_skill.py` fails on stale variants). `kingmadoc skills install` copies SKILL.md plus `reference/`.
+- `adr.py` (`kingmadoc adr "<title>"`, gated by the top-level `adr.enabled`; `adr.template` selects the template): `adr_path` → `next_number` (max existing + 1, never reused) + `adr_filename` → `render_adr` (`templates/adr.md.j2`, bundled) → `docs/adr/<NNNN>-<slug>.md`. Not a mode; shares `naming.slugify` and `templating.load_template` with plan.
+- `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.
+- `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.
+- Templates live in `src/kingmadoc/templates/` (shipped as package data). Security: `templating.load_template` loads bundled templates only from that package dir and never searches the analyzed project's root; a project template is used only when a `template:` setting gives an explicit path (`ConfigError` if missing or not a file). Every template renders in Jinja's `SandboxedEnvironment` (repos may be untrusted; see `tests/test_templating_security.py`). Jinja uses `StrictUndefined`, so every template variable must be passed.
+
+## Conventions
+
+All docs are indexed in `docs/index.md` (English only; add new `.md` files there). Rules: the **Rule summary** table at the top of `docs/conventions.md` (ID, status, auto/manual); open a rule's section only when needed. Key rules:
+
+- Classes only for frozen dataclasses (data) and `typing.Protocol` extension points (behavior); everything else plain functions. Composition, not inheritance.
+- Keep I/O in the shell (`cli.py`, file walking/writing); diagram builders, config parsing and detection stay pure.
+- Type hints and docstrings on all public functions; `pathlib.Path` for all paths.
+- No global state; config is passed explicitly, never imported as a module-level object.
+- Raise subclasses of `kingmadoc.exceptions.KingmaDocError`; the CLI converts them to `click.ClickException`.