Release v1.3.1

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -28,7 +28,7 @@ body:
     attributes:
       label: DocSprout version
       description: Output of `docsprout --version`.
-      placeholder: docsprout 1.3.0
+      placeholder: docsprout 1.3.1
     validations:
       required: true
   - type: input

.github/workflows/publish-docs.yml

@@ -32,7 +32,7 @@ jobs:
       - uses: actions/setup-python@v7
         with:
           python-version: '3.11'
-      - run: python -m pip install "git+https://github.com/ikelaiah/docsprout.git@v1.3.0"
+      - run: python -m pip install "git+https://github.com/ikelaiah/docsprout.git@v1.3.1"
       - run: docsprout check
       - if: inputs.versioned
         run: docsprout check-release

CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 1.3.1
+
+A diagnostics and release-validation patch. No configuration, route,
+machine-format, public CSS token or dependency change is required. Update
+package and workflow pins to `v1.3.1`, then rebuild.
+
+### Fixed
+
+- `audit` now reports a missing local non-Markdown asset, such as a linked ZIP
+  or PDF, as DK004, matching the documented rule and `check`'s build
+  behaviour. Previously `audit` could report "Ready to publish" while `build`
+  failed.
+- `check-release` and `build-all` report an actionable "Git is required" error
+  when Git is not installed, instead of an unhandled traceback.
+- `versions.json` rejects release names reserved for generated site output
+  (`versions.json`, `index.html`) and release names that differ only by case,
+  which previously crashed `build-all` on case-insensitive filesystems.
+
 ## 1.3.0
 
 A visual-theme modernisation minor. No configuration, route, machine-format,

README.md

@@ -1,6 +1,6 @@
 # 🌱 DocSprout
 
-[![CI](https://github.com/ikelaiah/docsprout/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/ikelaiah/docsprout/actions/workflows/ci.yml?query=branch%3Amain) [![Docs](https://img.shields.io/website?url=https%3A%2F%2Fikelaiah.github.io%2Fdocsprout%2F1.3.0%2F&label=docs)](https://ikelaiah.github.io/docsprout/1.3.0/) [![Latest release](https://img.shields.io/github/v/release/ikelaiah/docsprout?display_name=tag&sort=semver)](https://github.com/ikelaiah/docsprout/releases/latest) [![Python 3.10–3.14](https://img.shields.io/badge/python-3.10%E2%80%933.14-3776AB?logo=python&logoColor=white)](https://github.com/ikelaiah/docsprout/blob/main/docs/qualification.md#supported-python-versions) [![License: MIT](https://img.shields.io/github/license/ikelaiah/docsprout)](https://github.com/ikelaiah/docsprout/blob/main/LICENSE)
+[![CI](https://github.com/ikelaiah/docsprout/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/ikelaiah/docsprout/actions/workflows/ci.yml?query=branch%3Amain) [![Docs](https://img.shields.io/website?url=https%3A%2F%2Fikelaiah.github.io%2Fdocsprout%2F1.3.1%2F&label=docs)](https://ikelaiah.github.io/docsprout/1.3.1/) [![Latest release](https://img.shields.io/github/v/release/ikelaiah/docsprout?display_name=tag&sort=semver)](https://github.com/ikelaiah/docsprout/releases/latest) [![Python 3.10–3.14](https://img.shields.io/badge/python-3.10%E2%80%933.14-3776AB?logo=python&logoColor=white)](https://github.com/ikelaiah/docsprout/blob/main/docs/qualification.md#supported-python-versions) [![License: MIT](https://img.shields.io/github/license/ikelaiah/docsprout)](https://github.com/ikelaiah/docsprout/blob/main/LICENSE)
 
 ![DocSprout banner — Build documentation people can use.](docs/assets/docsprout-banner.svg)
 
@@ -23,7 +23,7 @@ Open a terminal in your project's top-level folder—the folder that normally
 contains files such as `README.md`, `src/` or `.git/`—and run:
 
 ```bash
-python -m pip install "https://github.com/ikelaiah/docsprout/archive/refs/tags/v1.3.0.zip"
+python -m pip install "https://github.com/ikelaiah/docsprout/archive/refs/tags/v1.3.1.zip"
 docsprout init
 docsprout serve
 ```

docs/architecture.md

@@ -77,6 +77,6 @@ needs no custom CSS; the custom stylesheet mechanism is a deliberately bounded
 escape hatch whose inclusion mechanics DocSprout owns and whose accessibility
 the author owns.
 
-Downstream projects should pin released tags such as `v1.3.0`, never the main
+Downstream projects should pin released tags such as `v1.3.1`, never the main
 branch. The stable boundary and deprecation policy are in [Machine-readable
 contracts](machine-contracts.md).

docs/beginners-guide.md

@@ -26,7 +26,7 @@ that normally contains `README.md` or `src/`.
 Open a terminal in your project folder and run:
 
 ```bash
-python -m pip install "https://github.com/ikelaiah/docsprout/archive/refs/tags/v1.3.0.zip"
+python -m pip install "https://github.com/ikelaiah/docsprout/archive/refs/tags/v1.3.1.zip"
 ```
 
 Then check that the command is available:
@@ -254,7 +254,7 @@ appear in the navigation.
   in [How DocSprout renders Markdown](markdown-showcase.md).
 - Learn the three configuration files in [Configuration](configuration.md).
 - Copy a small working project from the
-  [minimal example](https://github.com/ikelaiah/docsprout/tree/v1.3.0/examples/minimal).
+  [minimal example](https://github.com/ikelaiah/docsprout/tree/v1.3.1/examples/minimal).
 - When you truly want a public site, choose the simpler or historical path in
   [GitHub Pages](github-pages.md).
 - Look up unfamiliar words in the [glossary](glossary.md).

docs/building.md

@@ -24,7 +24,7 @@ asset is local, and `index.html` opens directly in a browser.
 ## Ship a ZIP
 
 ```bash
-docsprout build --release 1.3.0 --offline-archive dist/docsprout-docs-1.3.0.zip
+docsprout build --release 1.3.1 --offline-archive dist/docsprout-docs-1.3.1.zip
 ```
 
 The release label used for an offline archive must start with a letter or

docs/ci-cd.md

@@ -40,7 +40,7 @@ jobs:
         with:
           python-version: "3.12"
       - name: Install DocSprout
-        run: python -m pip install "https://github.com/ikelaiah/docsprout/archive/refs/tags/v1.3.0.zip"
+        run: python -m pip install "https://github.com/ikelaiah/docsprout/archive/refs/tags/v1.3.1.zip"
       - name: Validate the site
         run: docsprout check
       - name: Audit publications
@@ -52,7 +52,7 @@ jobs:
           path: audit.json
 ```
 
-Pin a released tag (`v1.3.0` above), never a branch. `--format json` writes the
+Pin a released tag (`v1.3.1` above), never a branch. `--format json` writes the
 machine-readable report; the artifact keeps it after the job, including when
 the audit fails.
 
@@ -76,7 +76,7 @@ is yours. The same checks in GitLab CI:
 docs-checks:
   image: python:3.12
   script:
-    - python -m pip install "https://github.com/ikelaiah/docsprout/archive/refs/tags/v1.3.0.zip"
+    - python -m pip install "https://github.com/ikelaiah/docsprout/archive/refs/tags/v1.3.1.zip"
     - docsprout check
     - docsprout audit --strict
 ```

docs/customisation.md

@@ -70,8 +70,8 @@ identity asset:
 
 Fields that are not relevant here, such as `banner` and `homepage`, are
 omitted for brevity. You can inspect the complete maintained
-[`docs/docsprout.json`](https://github.com/ikelaiah/docsprout/blob/v1.3.0/docs/docsprout.json)
-and its [local SVG asset](https://github.com/ikelaiah/docsprout/blob/v1.3.0/docs/assets/docsprout-mark.svg).
+[`docs/docsprout.json`](https://github.com/ikelaiah/docsprout/blob/v1.3.1/docs/docsprout.json)
+and its [local SVG asset](https://github.com/ikelaiah/docsprout/blob/v1.3.1/docs/assets/docsprout-mark.svg).
 On generated DocSprout pages, purple is the accent and highlight colour; the
 potted sprout mark (green leaves, brown soil and a beige pot) appears immediately
 before the project name in the top header;

docs/existing-repository.md

@@ -18,7 +18,7 @@ Run both commands from the repository's top-level folder—the one that contains
 `README.md` or `.git/`:
 
 ```bash
-python -m pip install "https://github.com/ikelaiah/docsprout/archive/refs/tags/v1.3.0.zip"
+python -m pip install "https://github.com/ikelaiah/docsprout/archive/refs/tags/v1.3.1.zip"
 docsprout init
 ```
 

docs/github-pages.md

@@ -48,7 +48,7 @@ from feature branches do not deploy Pages.
 workflow are current, it makes no repository changes.
 
 The generated workflow carries a DocSprout ownership marker and pins the reusable
-workflow to the installed release, such as `@v1.3.0`. It never follows
+workflow to the installed release, such as `@v1.3.1`. It never follows
 `@main`. If a recognised managed workflow is older, ordinary setup reports the
 version and leaves it unchanged. Update only that workflow deliberately:
 
@@ -101,13 +101,13 @@ jobs:
       contents: read
       pages: write
       id-token: write
-    uses: ikelaiah/docsprout/.github/workflows/publish-docs.yml@v1.3.0
+    uses: ikelaiah/docsprout/.github/workflows/publish-docs.yml@v1.3.1
     with:
       versioned: false
       release: latest
 ```
 
-The maintained [single-version example](https://github.com/ikelaiah/docsprout/tree/v1.3.0/examples/single-version)
+The maintained [single-version example](https://github.com/ikelaiah/docsprout/tree/v1.3.1/examples/single-version)
 uses this form.
 
 ## Historical site for versioned projects
@@ -129,7 +129,7 @@ jobs:
       contents: read
       pages: write
       id-token: write
-    uses: ikelaiah/docsprout/.github/workflows/publish-docs.yml@v1.3.0
+    uses: ikelaiah/docsprout/.github/workflows/publish-docs.yml@v1.3.1
 ```
 
 Check a historical release locally after creating its tag and before pushing:
@@ -140,7 +140,7 @@ docsprout check-release
 docsprout build-all --output build/docs-site
 ```
 
-The maintained [historical example](https://github.com/ikelaiah/docsprout/tree/v1.3.0/examples/historical)
+The maintained [historical example](https://github.com/ikelaiah/docsprout/tree/v1.3.1/examples/historical)
 uses this form. Follow the [pre-publish checklist](pre-publish-checklist.md)
 for the exact release order.
 

docs/historical-docs.md

@@ -71,6 +71,6 @@ the release check and full build, then push the tag. Use the exact commands in t
 [pre-publish checklist](pre-publish-checklist.md).
 
 The maintained
-[historical example](https://github.com/ikelaiah/docsprout/tree/v1.3.0/examples/historical)
+[historical example](https://github.com/ikelaiah/docsprout/tree/v1.3.1/examples/historical)
 demonstrates two small releases. Its automated test builds the same Git history
 twice and compares every generated byte.

docs/homepage-recipes.md

@@ -18,7 +18,7 @@ which is a top-level setting, are `homepage` values.
 ## See it in DocSprout
 
 DocSprout uses the same configuration on this site. Its
-[`docs/docsprout.json`](https://github.com/ikelaiah/docsprout/blob/v1.3.0/docs/docsprout.json)
+[`docs/docsprout.json`](https://github.com/ikelaiah/docsprout/blob/v1.3.1/docs/docsprout.json)
 uses these exact values for its home-page banner and capability cards:
 
 ```json

docs/migration.md

@@ -3,7 +3,7 @@
 The 1.x upgrades are deliberately boring: v1.0.0 froze the qualified v0.18.1
 surface, and every later 1.x release adds no configuration schema change. Pin
 the released package and workflow, then run the same checks you already use.
-Current guidance targets `v1.3.0`; each section below remains authoritative for
+Current guidance targets `v1.3.1`; each section below remains authoritative for
 its own step.
 
 ## DocKit to DocSprout (1.x rebrand)
@@ -64,7 +64,7 @@ each published release manifest on immutable tags while upgrading.
 ## Upgrade directly from any supported 0.x release
 
 All released 0.x configurations use schema version 1. Upgrade the pinned package
-and workflow to the latest 1.x release (`v1.3.0`), then use this table before
+and workflow to the latest 1.x release (`v1.3.1`), then use this table before
 running `doctor`, `check`, and the appropriate publish build.
 
 | Starting release | Required compatibility work |
@@ -96,6 +96,18 @@ segments and option-like refs, requires the current source to match `HEAD`, and
 requires documentation changes to be committed. These checks make existing
 valid manifests more dependable; they do not change generated routes.
 
+## v1.3.0 to v1.3.1
+
+No configuration or content migration is required. Update package and workflow
+pins to `v1.3.1`, then rebuild. The patch tightens diagnostics and release
+validation without changing generated routes, configuration schemas, the
+audit JSON format or public CSS tokens: `audit` now reports a missing local
+non-Markdown asset as DK004 just as `check` fails the build, `check-release`
+and `build-all` report an actionable "Git is required" error instead of an
+unhandled traceback when Git is unavailable, and `versions.json` rejects
+release names reserved for generated output and names that differ only by
+case.
+
 ## v1.2.3 to v1.3.0
 
 No configuration or content migration is required. Update package and workflow
@@ -305,7 +317,7 @@ the contract qualified by v0.18.1:
 
 1. Pin the package archive or source installation to `v1.0.0` and pin the
    reusable Pages workflow to `@v1.0.0`; never use `main`. For a new upgrade
-   today, pin the latest 1.x release (`v1.3.0`) instead.
+   today, pin the latest 1.x release (`v1.3.1`) instead.
 2. Keep `"schema_version": 1` in `docsprout.json`, `layout.json` and
    `versions.json`. There is no schema rewrite or generated-route migration.
 3. If custom CSS still uses pre-v0.18 generic names such as `--bg`, `--text`
@@ -437,9 +449,9 @@ safe, readable plain code.
 
 Version 1.0 is the formal commitment point for the contracts that v0.18.1
 qualified, and later 1.x releases keep that contract. There is no schema change.
-Before adopting the latest 1.x release (`v1.3.0`):
+Before adopting the latest 1.x release (`v1.3.1`):
 
-1. Upgrade the pinned package and Pages workflow to `v1.3.0` following this
+1. Upgrade the pinned package and Pages workflow to `v1.3.1` following this
    guide's patterns (config-compatible, then rebuild).
 2. Remove references to any pre-v0.18 generic theme token names
    (`--bg`, `--text`, `--interactive`, …) in custom CSS; the `--dk-*` names

docs/pre-publish-checklist.md

@@ -62,18 +62,18 @@ This path updates the public site from a branch such as `main`.
 ## Historical site
 
 This path publishes an immutable site for every listed release. In the example
-below, replace `1.3.0` with your version.
+below, replace `1.3.1` with your version.
 
-1. Add release `1.3.0` and source ref `v1.3.0` to `docs/versions.json`. Set
-   `current` to `1.3.0`.
+1. Add release `1.3.1` and source ref `v1.3.1` to `docs/versions.json`. Set
+   `current` to `1.3.1`.
 2. Run `docsprout check`.
 3. Commit all release files, including package metadata, documentation,
    examples and workflows, on a branch named `release/vX.Y.Z`:
 
    ```bash
    git add pyproject.toml src/docsprout/__init__.py README.md CHANGELOG.md docs .github examples tests
    git diff --cached --check
-   git commit -m "Prepare v1.3.0 documentation"
+   git commit -m "Prepare v1.3.1 documentation"
    ```
 
 4. Push the qualified branch and open a PR against `main`. Wait for every
@@ -83,7 +83,7 @@ below, replace `1.3.0` with your version.
 5. Check out the merged `main` commit and create the tag on that exact commit:
 
    ```bash
-   git tag -a v1.3.0 -m "v1.3.0"
+   git tag -a v1.3.1 -m "v1.3.1"
    ```
 
 6. Run the release checks and historical build:
@@ -100,7 +100,7 @@ below, replace `1.3.0` with your version.
 8. Push the annotated tag (the merge commit is already on `main`):
 
    ```bash
-   git push origin v1.3.0
+   git push origin v1.3.1
    ```
 
 9. Create the GitHub Release from the tag. Confirm both CI and the Documentation
@@ -111,7 +111,7 @@ below, replace `1.3.0` with your version.
 ## If you find a mistake
 
 If the tag exists only on your computer, correct and commit the files, delete
-the local tag with `git tag -d v1.3.0`, then create it again on the corrected
+the local tag with `git tag -d v1.3.1`, then create it again on the corrected
 commit.
 
 If the tag has been pushed, do not move or replace it. Publish the correction

docs/qualification.md

@@ -1,7 +1,7 @@
-# Qualification evidence for DocSprout v1.3.0
+# Qualification evidence for DocSprout v1.3.1
 
-DocSprout v1.3.0 modernises every visual style while preserving JSON and
-Markdown layout compatibility and the v1.0.0 stable contract. The claims below are the contract that CI and the maintained fixtures
+DocSprout v1.3.1 is a diagnostics and release-validation patch that preserves
+JSON and Markdown layout compatibility and the v1.0.0 stable contract. The claims below are the contract that CI and the maintained fixtures
 exercise. Every row names how it is verified. "Supported" means the combination
 is run by automated qualification on every pull request and release, not merely
 believed to work.
@@ -286,6 +286,16 @@ site configuration; no schema, route or token value changes:
   distinguish page structure from home-page presentation, and the glossary
   covers the navigation, theme and command vocabulary.
 
+## v1.3.1 additions
+
+- Audit tests cover a missing local non-Markdown asset linked from prose
+  (DK004) and an existing asset that stays quiet, matching the documented
+  DK004 rule and `check`'s build behaviour.
+- Version tests cover an actionable "Git is required" error for `check-release`
+  and `_run_git` when Git is unavailable, plus manifest rejection of release
+  names reserved for generated output (`versions.json`, `index.html`) and
+  names that differ only by case on case-insensitive filesystems.
+
 ## v1.3.0 additions
 
 - Generated-page tests cover the glassmorphic hero glow, specular panel

docs/themes.md

@@ -46,7 +46,7 @@ footer—never underlines, signalling hover with a background tint or colour
 shift instead, and buttons never underline.
 
 The maintained
-[single-version example](https://github.com/ikelaiah/docsprout/tree/v1.3.0/examples/single-version)
+[single-version example](https://github.com/ikelaiah/docsprout/tree/v1.3.1/examples/single-version)
 starts in Paper (`"style": "paper"`), so its built opening page shows the
 warm reading surface before a visitor changes the control.
 
@@ -119,7 +119,7 @@ hexadecimal values:
 Test custom colours in both Light and Dark mode. Links, selected navigation and
 keyboard focus must remain easy to see. A preset is safer when you are unsure.
 The maintained
-[minimal example](https://github.com/ikelaiah/docsprout/tree/v1.3.0/examples/minimal)
+[minimal example](https://github.com/ikelaiah/docsprout/tree/v1.3.1/examples/minimal)
 uses the exact teal values shown above; its built links, selected navigation
 and focus state use that accent.
 

docs/versions.json

@@ -1,7 +1,8 @@
 {
   "schema_version": 1,
-  "current": "1.3.0",
+  "current": "1.3.1",
   "versions": [
+    {"release": "1.3.1", "source_ref": "v1.3.1"},
     {"release": "1.3.0", "source_ref": "v1.3.0"},
     {"release": "1.2.3", "source_ref": "v1.2.3"},
     {"release": "1.2.2", "source_ref": "v1.2.2"},

examples/github-pages/.github/workflows/docsprout-pages.yml

@@ -13,7 +13,7 @@ concurrency:
 jobs:
   documentation:
     if: github.ref == format('refs/heads/{0}', github.event.repository.default_branch)
-    uses: ikelaiah/docsprout/.github/workflows/publish-docs.yml@v1.3.0
+    uses: ikelaiah/docsprout/.github/workflows/publish-docs.yml@v1.3.1
     with:
       versioned: false
       release: latest

examples/historical/.github/workflows/documentation.yml

@@ -12,7 +12,7 @@ permissions:
 
 jobs:
   documentation:
-    uses: ikelaiah/docsprout/.github/workflows/publish-docs.yml@v1.3.0
+    uses: ikelaiah/docsprout/.github/workflows/publish-docs.yml@v1.3.1
     permissions:
       contents: read
       pages: write

examples/single-version/.github/workflows/documentation.yml

@@ -12,7 +12,7 @@ permissions:
 
 jobs:
   documentation:
-    uses: ikelaiah/docsprout/.github/workflows/publish-docs.yml@v1.3.0
+    uses: ikelaiah/docsprout/.github/workflows/publish-docs.yml@v1.3.1
     with:
       versioned: false
       release: latest