Format Markdown sources

Normalize Markdown sources and exclude imported Copier documentation from lint.

Author: leynos

.markdownlint-cli2.jsonc

@@ -0,0 +1,25 @@
+{
+  "config": {
+    "MD004": { "style": "dash" },
+    "MD010": { "code_blocks": false },
+    "MD013": {
+      "line_length": 80,
+      "code_block_line_length": 120,
+      "tables": false,
+      "headings": false
+    },
+    "MD029": { "style": "ordered" }
+  },
+  "ignores": [
+    "**/.venv/**",
+    ".node_modules/**",
+    "**/node_modules/**",
+    "**/target/**",
+    ".terraform/**",
+    ".uv-cache/**",
+    ".uv-tools/**",
+    "docs/configuring-a-copier-template.md",
+    "docs/creating-a-copier-template.md",
+    "CRUSH.md"
+  ]
+}

Makefile

@@ -1,4 +1,4 @@
-.PHONY: help check-fmt lint spelling test typecheck
+.PHONY: help check-fmt fmt lint spelling test typecheck
 
 MAKEFLAGS += --no-print-directory
 
@@ -19,6 +19,10 @@ test: ## Run template tests
 check-fmt: ## Verify template test formatting
 	$(UV) ruff format --check tests/
 
+fmt: ## Format parent tests and Markdown sources
+	$(UV) ruff format tests/
+	mdformat-all
+
 lint: ## Run template test lint checks
 	$(UV) ruff check tests/
 	$(UV) --with interrogate interrogate --fail-under 100 tests/

README.md

@@ -1,8 +1,7 @@
 # Generic Copier Template
 
 This repository provides a [Copier](https://copier.readthedocs.io/) template
-for a Python package.
-It offers two flavours:
+for a Python package. It offers two flavours:
 
 1. **Python Only** – a pure Python implementation.
 2. **Python with Rust** – includes a PyO3 extension.
@@ -12,10 +11,10 @@ Run `copier copy` and answer the prompts to generate a project.
 ## Running Tests
 
 The test suite relies on the `pytest-copier` plugin and renders generated
-projects that run Ruff, Pylint via a PyPy-backed runner, `ty`, pytest, and, when
-the Rust extension is enabled, Clippy, Whitaker, and nextest-aware Rust tests.
-Generated Python linting also runs Interrogate as a 100% docstring-coverage
-gate.
+projects that run Ruff, Pylint via a PyPy-backed runner, `ty`, pytest, and,
+when the Rust extension is enabled, Clippy, Whitaker, and nextest-aware Rust
+tests. Generated Python linting also runs Interrogate as a 100%
+docstring-coverage gate.
 
 Run the parent template tests through the repository `Makefile`. Run
 `make help` to list the available parent Makefile targets. Parent gates include
@@ -29,8 +28,8 @@ make test
 
 Run `make test WITH_ACT=1` to include the act-backed workflow integration tests
 when `act` and Docker are available. Parent repository CI runs this mode in a
-separate act-validation workflow so rendered in-template GitHub workflows do not
-hold up the normal template test workflow.
+separate act-validation workflow so rendered in-template GitHub workflows do
+not hold up the normal template test workflow.
 
 Generated projects install and run their own tooling, including Ruff,
 Interrogate, Pylint via PyPy, `ty`, pytest, and, when Rust is enabled, Clippy,
@@ -43,8 +42,8 @@ dependencies into the current Python environment manually.
 
 Figure: The generated `make all` quality gate runs build, formatting, linting,
 typechecking, and testing. Rust-specific lint and test branches run only when
-the Rust extension is enabled. The `audit` target checks Python dependencies
-via `pip-audit` and, when Rust is enabled, Rust dependencies via `cargo audit`.
+the Rust extension is enabled. The `audit` target checks Python dependencies via
+`pip-audit` and, when Rust is enabled, Rust dependencies via `cargo audit`.
 
 ```mermaid
 flowchart LR

docs/adr-001-template-quality-gates.md

@@ -31,6 +31,6 @@ execution stay aligned.
 ## Consequences
 
 The generated Makefile remains the primary developer interface, but individual
-lint tiers can be run directly when narrowing failures. Rust-only tooling is not
-rendered for Python-only projects. The repository tests assert key generated
-file contracts instead of adding a snapshot framework to this branch.
+lint tiers can be run directly when narrowing failures. Rust-only tooling is
+not rendered for Python-only projects. The repository tests assert key
+generated file contracts instead of adding a snapshot framework to this branch.

docs/adr-002-adopt-cuprum-for-template-scripts.md

@@ -26,10 +26,9 @@ commands within `sh.scoped(...)`, and inspect `CommandResult.exit_code`,
 catalogues in a project module, while standalone scripts and tests should keep
 local catalogues scoped to the programs they need.
 
-The generated documentation should signpost
-`docs/scripting-standards.md` from contributor-facing instructions so script
-authors find the `cuprum`, `Cyclopts`, `pathlib`, and `cmd-mox` conventions
-before adding automation.
+The generated documentation should signpost `docs/scripting-standards.md` from
+contributor-facing instructions so script authors find the `cuprum`, `Cyclopts`,
+`pathlib`, and `cmd-mox` conventions before adding automation.
 
 ## Alternatives considered
 
@@ -45,9 +44,9 @@ allowlist without enforcing scoped command construction across the script.
 `plumbum` also makes observability a convention layered around command calls.
 Common logging, tracing, and command auditing would need bespoke wrappers, and
 those wrappers would be easy to bypass when a script author reaches directly for
-`local[...]` or an imported command object. That is acceptable for small private
-scripts, but it is a poor template default because generated projects inherit
-the convention without the local context that produced it.
+`local[...]` or an imported command object. That is acceptable for small
+private scripts, but it is a poor template default because generated projects
+inherit the convention without the local context that produced it.
 
 Finally, `plumbum` raises on non-zero exits by default. That can be convenient
 for short scripts, but it encourages exception-driven control flow for command
@@ -57,10 +56,10 @@ observable values that tests can assert directly with `cmd-mox`.
 ### Use subprocess directly
 
 The standard library `subprocess` module avoids a dependency, but it leaves
-command allowlisting, argument construction, result handling, observability, and
-test-double integration to each script. That would make the template guidance
-longer and less consistent while still failing to provide a central enforcement
-point for external program access.
+command allowlisting, argument construction, result handling, observability,
+and test-double integration to each script. That would make the template
+guidance longer and less consistent while still failing to provide a central
+enforcement point for external program access.
 
 ## Consequences
 
@@ -71,9 +70,8 @@ place to attach logging or auditing, and keeps command results testable as data.
 
 Scripts no longer rely on exception-driven handling of non-zero command exits;
 they must check `CommandResult.exit_code` directly. This is slightly more
-verbose than `plumbum` for trivial calls, but it makes success and failure paths
-clear in both production scripts and tests that mock external executables.
+verbose than `plumbum` for trivial calls, but it makes success and failure
+paths clear in both production scripts and tests that mock external executables.
 
-The template documentation now includes migration guidance for legacy
-`plumbum` usage, but the preferred path for new and updated scripts is
-`cuprum`.
+The template documentation now includes migration guidance for legacy `plumbum`
+usage, but the preferred path for new and updated scripts is `cuprum`.

docs/adr-003-shared-oxford-spelling-base.md

@@ -22,9 +22,10 @@ deterministic, tracked `typos.toml`.
 
 The refresh validates data before atomic replacement, keeps a valid cache when
 its authority is not newer, and supports explicit offline reuse. The generated
-Makefile pins `typos`, exposes `make spelling`, includes spelling in `make all`,
-and runs it through Continuous Integration (CI). The template repository uses
-the same mechanism for its own Markdown and rendered Markdown sources.
+Makefile pins `typos`, exposes `make spelling`, includes spelling in
+`make all`, and runs it through Continuous Integration (CI). The template
+repository uses the same mechanism for its own Markdown and rendered Markdown
+sources.
 
 ## Consequences
 

docs/adr-004-adopt-skylos-for-dead-code-detection.md

@@ -140,13 +140,13 @@ Allowlist entries follow these rules:
    `lint-python` in `template/Makefile.jinja`, and implement the guarded
    `skylos-allow` target.
 2. Extend the template contract tests to prove that rendered projects install
-   Skylos, run it through `make lint`, reject missing `NAME` or `REASON` values,
-   invoke `skylos whitelist "$(NAME)" --reason "$(REASON)"` once, persist the
-   documented entry under `[tool.skylos.whitelist]`, and expose the new target
-   through `make help`. Assert that the target does not scrape reports or
-   generate a baseline.
-3. Update `template/AGENTS.md.jinja` with the dead-code and allowlist policy, and
-   update `template/docs/developers-guide.md` with the contributor workflow.
+   Skylos, run it through `make lint`, reject missing `NAME` or `REASON`
+   values, invoke `skylos whitelist "$(NAME)" --reason "$(REASON)"` once,
+   persist the documented entry under `[tool.skylos.whitelist]`, and expose the
+   new target through `make help`. Assert that the target does not scrape
+   reports or generate a baseline.
+3. Update `template/AGENTS.md.jinja` with the dead-code and allowlist policy,
+   and update `template/docs/developers-guide.md` with the contributor workflow.
 4. Add or update the parent repository's `docs/users-guide.md` to explain the
    dead-code gate and the generated `make skylos-allow` interface to template
    users.
@@ -159,8 +159,8 @@ Allowlist entries follow these rules:
 - Dynamic Python code can still produce false positives or false negatives;
   contributors must verify findings before removing code.
 - A name-based allowlist can accidentally cover a later symbol with the same
-  name. Narrow entry-point rules and routine review reduce, but do not eliminate,
-  this risk.
+  name. Narrow entry-point rules and routine review reduce, but do not
+  eliminate, this risk.
 - Skylos has a broader and faster-moving feature surface than this template
   needs. The generated configuration and documentation must keep the adopted
   surface limited to local dead-code detection.

docs/adr-004-pin-ty-version.md

@@ -13,9 +13,9 @@ resolved the latest release.
 
 `ty` is pre-1.0 and its diagnostics change between releases. When ty 0.0.56
 landed, estate repositories with unpinned installations broke without any code
-change: the falcon-correlate and polythene main branches were red for days.
-An unpinned typechecker makes gate outcomes depend on release timing rather
-than on the code under review.
+change: the falcon-correlate and polythene main branches were red for days. An
+unpinned typechecker makes gate outcomes depend on release timing rather than
+on the code under review.
 
 ## Decision