# Changelog

All notable changes to this documentation repository, grouped into numbered revisions (`v1`, `v2`, …)
of the repository as a whole. There is no semantic version here — this repository has no manifest and
ships documents, so it uses the same `v#` scheme as the documents themselves.

Individual guideline documents carry their own `Document Version` header, and the skills carry
`metadata.version`; both are independent of the revisions below.

## v10 — 2026-10-13

### Changed
- **Python tooling moved from Poetry to uv** — `Python/DESIGN_DOCUMENT_PYTHON.md` v11 → v12 and
  `Python/DESIGN_DOCUMENT_PYTHON_MODULE.md` v4 → v5. Section 11 is now "uv": `uv sync`, `uv add`,
  `uv add --dev`, `uv remove`, `uv run`, and for libraries `uv build` / `uv publish`. The lock file is
  `uv.lock`, with the same rule as before — committed for applications, ignored for libraries
- uv also manages the interpreter — section 11 gained `uv python install <version>` and states that
  the interpreter is a uv-managed Python, no pyenv and no system Python
- The application document's new text is taken from the copy already migrated by hand in Curator, so
  that copy and the master are one and the same v12
- Library `pyproject.toml` example uses the `uv_build` backend in place of `poetry-core`. The
  `[tool.poetry] packages` table is gone — `uv_build` finds `src/<name>/` by itself — and the ban on
  entry points now names `[project.scripts]`
- `Python/TEMPLATE.md`, `Python/.gitignore` and the README conventions line follow: `uv.lock` in place
  of `poetry.lock`
- `Zscaler/ZSCALER_CERTIFICATE.md` — uv does not read `REQUESTS_CA_BUNDLE`, so it moved to the
  `SSL_CERT_FILE` row; the verification command is `uv run`

---

## v9 — 2026-10-07

### Added
- `Claude/skills/doubynet/` — new personal skill, reconciles the DoubyNet home-network
  documentation (a separate Syncthing-synced tree, not part of this repository) against
  the live state of its hosts, reports discrepancies, and updates the affected `.md`
  files. Versioned `v1`, following the established `metadata.version` convention. Was
  already in use directly from `~/.claude/skills/doubynet/` without a master copy here;
  brought in after a session surfaced several gaps (stale hardcoded path, unclear
  historical-vs-live document handling, no mention of CHANGELOG.md, no guidance for
  facts that can't be verified from a machine at all) that were fixed in the same pass
- `check_versions.py` now also checks the master skills in `Claude/skills/<name>/SKILL.md`
  against their installed copies in `~/.claude/skills/<name>/SKILL.md` — a fixed location,
  independent of `--root`. Reads `metadata.version` from the YAML frontmatter instead of
  the `**Document Version:**` marker used by guideline documents. A skill missing from
  `~/.claude/skills/` entirely is reported as a new status, `MISSING`, and is safe to
  `--sync` like `BEHIND`. Prompted by running the tool for the first time since `doubynet`
  was added: it found four of the five pre-existing skills installed without any version
  header at all, and `documentation_context` missing from `~/.claude/skills/` entirely

### Changed
- `--sync`/report wording generalised from "document(s)" to "item(s)" now that the same
  machinery covers both guideline documents and skills

---

## v8 — 2026-09-29

### Fixed
- `WEB/DESIGN_DOCUMENT_WEBAPP.md` registered in `check_versions.py`. v7 added the document but left it
  out of `MASTERS`, so its copies in projects were never compared against the master and `--sync`
  never propagated it

---

## v7 — 2026-09-24

### Added
- **`API/DESIGN_DOCUMENT_API.md` v2** — guidelines for any project that exposes an HTTP API,
  carried in addition to the language design document. It settles what was previously left to
  precedent: the URL version (`/v0`) and the product version are separate axes, the first naming a
  frozen consumer contract that moves only on a breaking change, the second following semantic
  versioning per release. Also fixes path naming
  (`/v<n>/<CONSUMER>/<resource-in-kebab-case>`, resources spelled out and never PascalCase),
  parameter and handler naming, the response envelope and its reserved paging keys, when an
  endpoint may be a delta and when it must stay a full snapshot, status-code meanings (an empty
  collection is `200`, not `404`), and the endpoint-level testing floor.
- `API/DESIGN_DOCUMENT_API.md` registered in `check_versions.py` and in the project-type table, so
  `--sync` propagates it like every other guideline document.
- Section 2.1 was rewritten before release (v1 → v2). The v1 draft filed `/subscribe` under
  endpoints that are "not part of any consumer contract" and declared the whole group free to
  change with the product version. It is the opposite: the token endpoints are the widest
  contract in the API, every delta consumer holds a token they issued, and the unversioned
  legacy feeds are contracts too. The section now splits operational endpoints from unversioned
  consumer endpoints and subjects the second group to section 1.1 — having no version to bump
  is not permission to break.
- **`WEB/DESIGN_DOCUMENT_WEBAPP.md` v1** — guidelines for a server-rendered web interface driven
  over a websocket (NiceGUI on FastAPI), carried in addition to `DESIGN_DOCUMENT_PYTHON.md`. Covers
  layers, one connection and one lock per service, page and dialog structure, where the language
  belongs, tables as the main idiom (including the slot trap), hand-written canvases, theming,
  performance, errors and notifications, authentication, testing, and a checklist for a new screen.

### Changed
- **`AGENTS.md` v8 → v9** — the table mapping project types to design documents is gone. Every
  `DESIGN_DOCUMENT*.md` in the project root now applies, with the suffix saying what it covers (a
  language, application vs. library, or a part of the system such as `_WEBAPP`), so the list can no
  longer go stale. Where two design documents disagree, the more specific one wins for what it covers.
- The `MASTERS` comment in `check_versions.py` no longer claims a design document is always named
  after a language — it is named after what it scopes, which may be a cross-cutting concern.

---

## v6 — 2026-08-18

### Added
- `--sync` in `check_versions.py` — offers to overwrite the outdated copies with the master, after
  listing them and asking for confirmation (`--yes` skips the prompt, `--dry-run` writes nothing).
  Each file keeps the line endings it already used, so a version bump stays a one-line diff on
  Windows and Linux alike, and the write goes through a backup that is restored if it fails.
  A `MODIFIED` copy is never overwritten — it holds a local edit that copying would discard
- `.gitignore` at the repository root for `__pycache__/`

### Changed
- **The design documents are renamed so the language is part of the file name**:
  `DESIGN_DOCUMENT.md` → `DESIGN_DOCUMENT_PYTHON.md` / `DESIGN_DOCUMENT_RUST.md`,
  `DESIGN_DOCUMENT_MODULE.md` → `DESIGN_DOCUMENT_PYTHON_MODULE.md`,
  `DESIGN_DOCUMENT_LIB.md` → `DESIGN_DOCUMENT_RUST_LIB.md`. Python and Rust applications used to
  share one file name, which only worked because the folder here disambiguated them — and the folder
  does not travel with the copy that lands in a project root. A project can now carry one design
  document per language, and `check_versions.py` no longer has to guess the language from
  `Cargo.toml`. Bumped: `DESIGN_DOCUMENT_PYTHON.md` v10 → v11, `DESIGN_DOCUMENT_PYTHON_MODULE.md`
  v3 → v4, `DESIGN_DOCUMENT_RUST.md` v3 → v4, `DESIGN_DOCUMENT_RUST_LIB.md` v3 → v4,
  `AGENTS.md` v7 → v8, `CLAUDE.md` v2 → v3
- `check_versions.py` recognises the pre-rename file names, reports them as `OLD NAME`, and renames
  them during `--sync`. The `Cargo.toml` check survives only to disambiguate legacy
  `DESIGN_DOCUMENT.md` copies and can be deleted once every project is migrated. A project holding
  both the old and the new name is reported as `DUPLICATE` and never touched

## v5 — 2026-08-18

### Added
- `check_versions.py` — walks the sibling project directories, compares every `CLAUDE.md`,
  `AGENTS.md` and `DESIGN_DOCUMENT*.md` copy against its master here, and reports the ones that are
  behind or were edited in place. Standard library only; exits non-zero when anything needs
  attention
- "Guideline copies in projects" section in `README.md` — the copies in project roots are now
  **committed** with each project, with the rationale and the three rules that keep them from
  drifting (never edit a copy, deviations go to `PROJECT.md`, sync commits stand alone)

### Changed
- `README.md` step 3 of "Starting a new project": the guideline copies are committed with the
  project instead of being kept out of version control, and `Claude/CLAUDE.md` is named alongside
  `AGENTS.md` and the design document
- `AGENTS.md` v6 → v7: the Git section said the opposite of the new policy — "Never commit shared
  documentation" is replaced by the rule that every core document is committed, must never be edited
  inside a project, and is synchronised in its own commit that stays out of the project `CHANGELOG.md`
- `CLAUDE.md` added to the list of core root documents in `AGENTS.md` and in all five design
  documents, which had omitted it: `DESIGN_DOCUMENT.md` v9 → v10, `DESIGN_DOCUMENT_MODULE.md` v2 → v3,
  `Rust/DESIGN_DOCUMENT.md` v2 → v3, `Rust/DESIGN_DOCUMENT_LIB.md` v2 → v3,
  `DESIGN_DOCUMENT_GODOT.md` v2 → v3
- `Python/TEMPLATE.md`: the note that the shared documents are "never committed" now matches the new
  policy — they stay out of the template, but the copies in a project are committed and never edited
- `Project template/CHANGELOG.md` gained a "Versioning" section: semantic versioning stays mandatory
  for software projects, while documentation and other manifest-less repositories may use
  single-number revisions (`v1`, `v2`, …). This repository's own changelog was converted to that
  scheme and its revisions renumbered `0.1.0`–`0.4.0` → `v1`–`v4`

## v4 — 2026-08-18

### Added
- Skill versioning: every `SKILL.md` now carries `metadata.version` — `changelog` v2, `check` v1,
  `commit` v2, `documentation` v1, `documentation_context` v2. The skill format has no top-level
  `version` field; `metadata` is one of the six Agent Skills spec fields, so the frontmatter still
  packages and uploads cleanly
- "Skills" section in `README.md` describing the versioning convention, the install location
  (`~/.claude/skills/`) and the rule that the folder name — not `name:` — is the command
- The five skills listed individually in the `README.md` structure tree
- `AGENTS.md` v5 → v6: new "Commit messages" subsection under Git — commits and pull requests must
  never carry AI authorship (`Co-Authored-By`, "Generated with …", tool signatures or emoji footers).
  The subsection also states the single-line verbal English style, so assistants without the `commit`
  skill get the same rules; the AI-authorship rule was added to the skill as well
- `CHANGELOG.md` for this repository, with history backfilled from the git log
- Explicit line length for Rust: 100 characters (rustfmt default `max_width`) in both Rust design documents
- `README.md`, `docs/`, `prebuild.py` and the PyInstaller `.spec` to the template structure in `Python/TEMPLATE.md`
- Note in `Python/TEMPLATE.md` that `AGENTS.md` and `DESIGN_DOCUMENT.md` are not part of the template
- `README.md` to the session read list in `Claude/CLAUDE.md`, plus a missing top-level heading
- `Document Version` marker in `Claude/CLAUDE.md`, starting at v2 — it is copied into projects like
  `AGENTS.md` and the design documents, so it can go stale there the same way

### Changed
- Document versions bumped for the structural changes released on 2026-08-18:
  `DESIGN_DOCUMENT.md` v8 → v9, `DESIGN_DOCUMENT_MODULE.md` v1 → v2,
  `Rust/DESIGN_DOCUMENT.md` v1 → v2, `Rust/DESIGN_DOCUMENT_LIB.md` v1 → v2,
  `DESIGN_DOCUMENT_GODOT.md` v1 → v2
- `Project template/CHANGELOG.md` now names the project manifest generically
  (`pyproject.toml`, `Cargo.toml`, `project.godot`) instead of `pyproject.toml` only
- Godot debug constant renamed `Constants.DEBUG` → `Constants.DEFAULT_DEBUG`, matching the Python reference module
- `README.md` step 1 of "Starting a new project" now also requires writing a `README.md`
- `Python/TEMPLATE.md` entry point is named by purpose or tool name instead of `main.py`
- `prebuild.py` loads `.env` before importing `src.constants` instead of relying on the import side effect

### Fixed
- Skill folder `Claude/skills/context/` renamed to `documentation_context/`, with the frontmatter
  `name` matched to it. The folder name is what Claude Code turns into the command, so the old
  mismatch meant installing from this repository would have changed `/documentation_context`
  into `/context`
- Removed the misplaced lock-file rule from the Testing sections of `DESIGN_DOCUMENT_MODULE.md` (§9)
  and `Rust/DESIGN_DOCUMENT_LIB.md` (§8) — it already belongs to the Poetry / Distribution sections

## v3 — 2026-08-18

### Added
- `Zscaler/ZSCALER_CERTIFICATE.md` — full certificate setup for Node, Python, git and cargo
- Language-specific `.gitignore` files for Python, Rust and Godot, plus a shared core in `Project template/`
- `poetry.lock` and `prebuild.py` sections in `Python/DESIGN_DOCUMENT.md`

### Changed
- Unified task notation across all languages on the Todo Tree tags `TODO`, `FIXME`, `BUG`, `HACK`, `NOTE`
- `AGENTS.md` v4 → v5: rewritten as strictly language-agnostic, naming no concrete tool
- Python line length 150 → 120 characters
- Rust edition 2021 → 2024 (requires Rust 1.85 or newer)
- Godot project version key corrected to `application/config/version`
- Every design document now lists `README.md` among the core root documents

### Removed
- `Zscaler/NODE_EXTRA_CA_CERTS.md`, superseded by `ZSCALER_CERTIFICATE.md`

## v2 — 2026-06-24

### Added
- `Godot/DESIGN_DOCUMENT_GODOT.md` — Godot development guidelines (v1)

## v1 — 2026-05-25

### Added
- `Rust/DESIGN_DOCUMENT.md` and `Rust/DESIGN_DOCUMENT_LIB.md` — Rust guidelines for applications and libraries (v1)
- `Claude/` — `CLAUDE.md`, `AGENTS.md` (v4) and the custom skills `changelog`, `check`, `commit`, `context`, `documentation`
- `Python/` — `DESIGN_DOCUMENT.md` (v8), `DESIGN_DOCUMENT_MODULE.md` (v1), `TEMPLATE.md`, and the reference `constants.py` module with tests
- `Project template/` — `PROJECT.md` and `CHANGELOG.md` templates

### Changed
- Documentation organised into topic folders: `Claude/`, `Python/`, `Zscaler/`, `Project template/`
- `README.md` rewritten to describe the repository itself instead of a single project