Improve themed documentation site and prepare 0.4.0

CHANGELOG.md

@@ -4,13 +4,22 @@ Notable changes to Agent Code Guard are recorded here.
 
 ## Unreleased
 
+## 0.4.0 - 2026-09-06
+
 ### Added
 
 - Explicit source-controlled Markdown document-size ratchets: create accepted
   physical-line allowances and update them only downward or by pruning. Accepted
   documents pass without repeated REVIEW; growth returns REVIEW, while section
   findings remain independent. Normal analysis never writes a baseline.
 
+### Changed
+
+- Give the documentation site a practical introduction, quick start, and agent
+  setup guidance, using the shared dark Primer theme. Add GitHub and documentation
+  navigation and link the project README directly to the published guides.
+- Bundle the updated Markdown ratchet instructions and policy with the skill.
+
 ## 0.3.1 - 2026-08-29
 
 ### Changed

README.md

@@ -7,9 +7,13 @@
 Deterministic maintainability guardrails for source code and Markdown changed by
 a human or coding agent.
 
+[Documentation](https://stef-k.github.io/agent-code-guard/) ·
+[Get started](https://stef-k.github.io/agent-code-guard/#get-started) ·
+[Releases](https://github.com/stef-k/agent-code-guard/releases)
+
 [![Production Analysis](https://github.com/stef-k/agent-code-guard/actions/workflows/analysis.yml/badge.svg)](https://github.com/stef-k/agent-code-guard/actions/workflows/analysis.yml)
 [![PyPI](https://img.shields.io/pypi/v/agent-code-guard?logo=pypi&logoColor=white)](https://pypi.org/project/agent-code-guard/)
-[![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/stef-k/agent-code-guard/blob/main/docs/platform-support.md)
+[![Python 3.10–3.14](https://img.shields.io/badge/Python-3.10%E2%80%933.14-3776AB?logo=python&logoColor=white)](https://stef-k.github.io/agent-code-guard/platform-support.html)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/stef-k/agent-code-guard/blob/main/LICENSE)
 
 Agent Code Guard measures file size, callable size, structural nesting,
@@ -61,7 +65,7 @@ code-guard doctor
 ```
 
 `--version` confirms the installed distribution identity. `doctor` checks the
-active installation's health. See the [usage guide](https://github.com/stef-k/agent-code-guard/blob/main/docs/usage.md) for virtual
+active installation's health. See the [usage guide](https://stef-k.github.io/agent-code-guard/usage.html) for virtual
 environment, uv, and developer alternatives.
 
 ### Ask your agent to adopt it
@@ -75,12 +79,12 @@ Copy this prompt to a coding agent:
 > activating or exporting its installed, version-matched skill for the current
 > agent environment. Verify `code-guard --version` and run `code-guard doctor`,
 > then locate the skill with `code-guard --skill-path`. Follow the
-> [skill activation guide](https://github.com/stef-k/agent-code-guard/blob/main/docs/skill-distribution.md):
+> [skill activation guide](https://stef-k.github.io/agent-code-guard/skill-distribution.html):
 > activate that installed path when the platform supports it, or export it with
 > `code-guard --export-skill <target-directory>` to the platform's documented
 > skill directory. Do not guess a target or overwrite an existing export; verify
 > that `.agent-code-guard-version` matches the installed distribution. Follow the
-> [agent workflow](https://github.com/stef-k/agent-code-guard/blob/main/docs/agent-workflow.md)
+> [agent workflow](https://stef-k.github.io/agent-code-guard/agent-workflow.html)
 > without creating an adoption baseline. After meaningful source or Markdown edits, run
 > `code-guard . --changed-only --json --json-mode compact`; outside Git, pass the
 > exact edited files. Inspect REVIEW and FAIL findings, make only genuine
@@ -104,7 +108,7 @@ No configuration is needed. A REVIEW asks for inspection and judgment, not an
 automatic refactor. Outside Git, pass the exact edited files instead, such as
 `code-guard src/app.py docs/guide.md`.
 
-See the [agent workflow guide](https://github.com/stef-k/agent-code-guard/blob/main/docs/agent-workflow.md) for repeated human and
+See the [agent workflow guide](https://stef-k.github.io/agent-code-guard/agent-workflow.html) for repeated human and
 agent use.
 
 ## Recommended workflow
@@ -126,7 +130,7 @@ report the result before completion
 Use `code-guard . --changed-only --json --json-mode compact` for a structured,
 low-noise manual agent check. Hooks are optional, platform-owned, and require
 user authorization; Code Guard does not install them. The
-[workflow guide](https://github.com/stef-k/agent-code-guard/blob/main/docs/agent-workflow.md) owns the complete manual and
+[workflow guide](https://stef-k.github.io/agent-code-guard/agent-workflow.html) owns the complete manual and
 hook-assisted process.
 
 ## Interpreting results
@@ -163,7 +167,7 @@ measurement. A REVIEW is not proof of a defect or a mandatory refactor.
 Comparisons are strictly greater-than, so equality passes. All guards except
 file LOC are REVIEW-only; only file LOC can FAIL. A new guard must provide
 distinct, deterministic value rather than duplicate conventional tooling. See
-[Guard admission](https://github.com/stef-k/agent-code-guard/blob/main/docs/guard-admission.md).
+[Guard admission](https://stef-k.github.io/agent-code-guard/guard-admission.html).
 
 ### Result and JSON reference
 
@@ -172,7 +176,7 @@ all-guard-excluded file counts. Bare `--json` is the compatible full output;
 `--json-mode debug` is byte-identical for the same completed invocation, while
 `--json-mode compact` removes only normalized `pass` findings and retains the
 result, scope, required policies, guards, ordering, and actionable findings.
-Named modes require `--json`. See [Usage](https://github.com/stef-k/agent-code-guard/blob/main/docs/usage.md) for the schema and
+Named modes require `--json`. See [Usage](https://stef-k.github.io/agent-code-guard/usage.html) for the schema and
 option contract.
 
 Known per-file syntax or provider failures instead produce `overall:
@@ -207,7 +211,7 @@ Generic `.h` files are not syntax-dispatched; `.markdown` is not enabled; Vue
 template and style regions are not executable syntax input; and unsupported
 artifacts are inapplicable. Malformed applicable syntax or a required provider
 failure is unavailable evidence, distinct from both an inapplicable file and a
-completed FAIL finding. See [Language support](https://github.com/stef-k/agent-code-guard/blob/main/docs/language-support.md).
+completed FAIL finding. See [Language support](https://stef-k.github.io/agent-code-guard/language-support.html).
 
 ### Skill integration
 
@@ -219,21 +223,21 @@ code-guard --export-skill <target-directory>
 ```
 
 Skill activation is platform-specific and is not performed by pipx or Code
-Guard. See [Skill distribution](https://github.com/stef-k/agent-code-guard/blob/main/docs/skill-distribution.md). The checkout
+Guard. See [Skill distribution](https://stef-k.github.io/agent-code-guard/skill-distribution.html). The checkout
 compatibility runner is for repository development, not normal installation.
 
 ### Configuration
 
 Built-in defaults require no configuration. Configure a project only for a
-concrete policy reason; see the [configuration guide](https://github.com/stef-k/agent-code-guard/blob/main/docs/configuration.md).
+concrete policy reason; see the [configuration guide](https://stef-k.github.io/agent-code-guard/configuration.html).
 The LOC baseline is an explicit adoption tool for established legacy
 repositories, not an ordinary-use requirement or a way to silence findings.
 Its default `ratchetAt: "fail"` policy freezes files above `failAt`; choose
 `ratchetAt: "review"` only when every established file above `warnAt` must be
 non-increasing while ordinary findings in that range remain REVIEW.
 
 Reviewed oversized Markdown documents have a separate, explicit
-[document-size ratchet](https://github.com/stef-k/agent-code-guard/blob/main/docs/usage.md#reviewed-markdown-document-ratchet).
+[document-size ratchet](https://stef-k.github.io/agent-code-guard/usage.html#reviewed-markdown-document-ratchet).
 `--create-markdown-baseline` records accepted physical-line counts;
 `--update-markdown-baseline` only lowers or prunes them. Documents within their
 allowance pass the document-size guard; growth produces REVIEW. Section
@@ -246,18 +250,18 @@ remain visible but non-blocking, while FAIL findings and tool errors block the
 workflow; the repository intentionally uses no adoption baseline.
 
 The maintained interpreter range is **CPython 3.10–3.14**. See
-[Platform support](https://github.com/stef-k/agent-code-guard/blob/main/docs/platform-support.md) for supported binary platforms and
+[Platform support](https://stef-k.github.io/agent-code-guard/platform-support.html) for supported binary platforms and
 source-build boundaries.
 
 ## Documentation
 
-- [Documentation index](https://github.com/stef-k/agent-code-guard/blob/main/docs/README.md)
-- [Agent workflow](https://github.com/stef-k/agent-code-guard/blob/main/docs/agent-workflow.md)
-- [Usage and CLI reference](https://github.com/stef-k/agent-code-guard/blob/main/docs/usage.md)
-- [Configuration](https://github.com/stef-k/agent-code-guard/blob/main/docs/configuration.md)
-- [Language support](https://github.com/stef-k/agent-code-guard/blob/main/docs/language-support.md)
-- [Platform support](https://github.com/stef-k/agent-code-guard/blob/main/docs/platform-support.md)
-- [Skill distribution](https://github.com/stef-k/agent-code-guard/blob/main/docs/skill-distribution.md)
+- [Documentation index](https://stef-k.github.io/agent-code-guard/)
+- [Agent workflow](https://stef-k.github.io/agent-code-guard/agent-workflow.html)
+- [Usage and CLI reference](https://stef-k.github.io/agent-code-guard/usage.html)
+- [Configuration](https://stef-k.github.io/agent-code-guard/configuration.html)
+- [Language support](https://stef-k.github.io/agent-code-guard/language-support.html)
+- [Platform support](https://stef-k.github.io/agent-code-guard/platform-support.html)
+- [Skill distribution](https://stef-k.github.io/agent-code-guard/skill-distribution.html)
 
 ## Feedback, security, and license
 

docs/README.md

@@ -1,7 +1,61 @@
-# Documentation
+---
+title: Agent Code Guard
+permalink: /
+---
 
-The README is the public landing page. These guides hold the durable operating
-contract and the evidence behind it.
+# Agent Code Guard
+
+Deterministic maintainability checks for source code and Markdown changed by a
+human or coding agent. Catch oversized files and functions, deep nesting,
+complex control flow, and documents that are becoming difficult to navigate.
+
+[View on GitHub](https://github.com/stef-k/agent-code-guard) ·
+[Install from PyPI](https://pypi.org/project/agent-code-guard/)
+
+## Get started
+
+Install the command in an isolated environment with
+[pipx](https://pipx.pypa.io/):
+
+```bash
+pipx install agent-code-guard
+code-guard --version
+code-guard doctor
+```
+
+Then check your current changes from a Git worktree:
+
+```bash
+code-guard . --changed-only
+```
+
+No configuration is needed for ordinary use. Outside Git, pass the exact files
+instead, such as `code-guard src/app.py docs/guide.md`.
+
+- **PASS:** continue.
+- **REVIEW:** inspect the finding and improve the structure when that helps.
+  Keeping a cohesive file or section is a valid reviewed outcome.
+- **FAIL:** correct the finding before completing the change.
+- **INCOMPLETE:** restore unavailable analysis before treating the check as complete.
+
+Code Guard measures without rewriting your files. Use it alongside tests,
+compilers, linters, formatters, and design review.
+
+## Use with a coding agent
+
+The package includes a version-matched skill that explains how to interpret
+findings. Locate it with `code-guard --skill-path`, then follow the
+[skill activation guide](skill-distribution.md). The
+[human and agent workflow](agent-workflow.md) covers repeated checks, compact
+JSON output, and optional authorized hooks.
+
+## Keep reviewed documents from growing unnoticed
+
+A cohesive oversized Markdown document can use an explicitly reviewed,
+source-controlled size allowance. Unchanged or smaller documents pass the
+document-size guard; growth returns REVIEW, and section reviews remain active.
+See the [Markdown ratchet workflow](usage.md#reviewed-markdown-document-ratchet)
+for creation, updates, and limitations.
 
 ## User guides
 

docs/_config.yml

@@ -0,0 +1,16 @@
+remote_theme: stef-k/.github@main
+
+plugins:
+  - jekyll-remote-theme
+
+title: Agent Code Guard
+description: Deterministic maintainability checks for source code and Markdown.
+url: https://stef-k.github.io
+baseurl: /agent-code-guard
+repository: stef-k/agent-code-guard
+
+defaults:
+  - scope:
+      path: ""
+    values:
+      layout: documentation

docs/_layouts/documentation.html

@@ -0,0 +1,11 @@
+---
+layout: default
+---
+{% unless page.url == '/' %}
+<nav aria-label="Documentation navigation">
+  <a href="{{ '/' | relative_url }}">Documentation home</a> ·
+  <a href="https://github.com/stef-k/agent-code-guard">View on GitHub</a>
+</nav>
+{% endunless %}
+
+{{ content }}

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "agent-code-guard"
-version = "0.3.1"
+version = "0.4.0"
 description = "Deterministic cross-language guardrails for agent-assisted development"
 readme = "README.md"
 requires-python = ">=3.10"

tests/test_packaging.py

@@ -126,7 +126,7 @@ def test_distribution_metadata_exposes_canonical_navigation(self) -> None:
             ],
         )
         self.assertIn(
-            "https://github.com/stef-k/agent-code-guard/blob/main/docs/guard-admission.md",
+            "https://stef-k.github.io/agent-code-guard/guard-admission.html",
             metadata.get_payload(),
         )
         self.assertNotIn("](docs/", metadata.get_payload())