commit-check · shenxianpeng · Aug 5, 2026 · Aug 5, 2026 · Aug 5, 2026 · Aug 5, 2026
diff --git a/docs/changelog.md b/docs/changelog.md
@@ -281,7 +281,7 @@ Configuration Format:
 
 * `.commit-check.yml` has been replaced with `cchk.toml` or `commit-check.toml`.
 * All YAML configurations must be migrated to TOML from this version onward.
-* See the [Migration Guide](migration.md) for step-by-step instructions.
+* See [Migrating from v1](migration.md) for step-by-step instructions.
 
 Removed Pre-commit Hooks and CLI Options:
 

diff --git a/docs/getting-started.md b/docs/getting-started.md
@@ -187,3 +187,6 @@ $ gh attestation verify commit_check-*.whl --repo commit-check/commit-check
   plus the environment variable and CLI flag that override it.
 - **[Command-line recipes](example.md)** — checking a range, wiring up CI,
   reading the JSON output.
+- **[Troubleshooting](troubleshoot.md)** — a check failing that you did not
+  turn on, nothing running at all, and how to get a commit through when you
+  have to.
diff --git a/docs/index.md b/docs/index.md
@@ -40,7 +40,6 @@ whatever your AI agent is committing on your behalf.
         hooks:
           - id: check-message
           - id: check-branch
-          - id: check-author-email
     ```
 
 === "GitHub Actions"
@@ -68,58 +67,49 @@ whatever your AI agent is committing on your behalf.
     }
     ```
 
+## Start with two commands
+
+```console
+$ pip install commit-check
+$ commit-check --message --branch
+```
-```console
-$ pip install commit-check
-$ commit-check --message --branch
-```
+    pip install commit-check
+    commit-check --message --branch
-```console
-$ pip install commit-check
-$ commit-check --message --branch
-```
+    pip install commit-check
+    commit-check --message --branch
+
+No configuration file needed to start — sensible defaults apply immediately, and
+you tighten them when you are ready. Releases carry
+[SLSA Level 3](https://slsa.dev) build provenance, so you can verify an artifact
+came from this repository's pipeline before you install it.
+
+[Get started :octicons-arrow-right-24:](getting-started.md){ .md-button .md-button--primary }
+[Rules reference](rules.md){ .md-button }
+
 ## Why it exists
 
 Git history is a database that every team writes to and almost nobody validates.
 
 The cost shows up later, and indirectly. Release notes get written by hand
-because commit subjects cannot be grouped. `git bisect` walks through merge
-commits that record nothing but a sync. A commit is attributed to `ec2-user`
-because a build box had no `user.name`. A contribution has to be rejected months
-after the fact because it never carried a `Signed-off-by` trailer.
+because commit subjects cannot be grouped. A `git bisect` ends on a merge
+commit, where the change that broke the build could be in either parent or in
+the resolution. A commit is attributed to `ec2-user` because a build box had no
+`user.name`. A branch has its history rewritten months later because none of its
+commits carried a `Signed-off-by` trailer.
 
 None of these are caught by a linter, a type checker, or a test suite. They are
 all caught by review — which means inconsistently, by whoever happens to be
 looking, and only after the work is done.
 
-Commit Check treats commit metadata the way linters treat code: a policy written
-down once, enforced identically everywhere, with a stable identifier for every
-diagnostic so findings can be discussed, cited, and tracked.
-
-<div class="grid cards" markdown>
-
--   :material-file-cog-outline:{ .lg .middle } __One config__
-
-    ---
-
-    A single `cchk.toml` drives the CLI, the pre-commit hook, the GitHub Action
-    and the MCP server. There is no second place where the rules can disagree
-    with themselves.
-
--   :material-lightning-bolt-outline:{ .lg .middle } __Fails where it is cheap__
-
-    ---
-
-    The same check that runs in CI runs in your `commit-msg` hook. A malformed
-    subject costs a second locally, or a full CI cycle plus a force-push
-    remotely.
-
--   :material-tag-outline:{ .lg .middle } __Stable rule IDs__
-
-    ---
-
-    Every rule has an ID like `CC003` that never changes once released. Cite it
-    in a review comment, link to its documentation, suppress it per-rule.
-
--   :material-shield-check:{ .lg .middle } __Built to be trusted__
+Commit Check makes them mechanical instead, and catches them where it is
+cheapest: the check that runs in CI is the same one that runs in your
+`commit-msg` hook, where a malformed subject costs a second to fix rather than a
+full CI cycle and a force-push.
 
-    ---
+It treats commit metadata the way linters treat code — a policy written down
+once, enforced identically everywhere, with a stable identifier for every
+diagnostic so findings can be discussed, cited, and tracked.
 
-    SLSA Level 3 build provenance with artifact attestation you can verify
-    before installing. A failure names the rule, quotes the offending value,
-    and says how to fix it.
-
-</div>
+Not all of that policy is on to begin with. Two of the four problems above are
+decisions rather than defects — whether merge commits belong in your history,
+and whether contributors must sign off — and they stay off until you make them.
+The [rules reference](rules.md#rule-index) marks which rules start on.
 
 ## What it checks
 
@@ -347,19 +337,6 @@ graph TB
 
 And [many more](https://github.com/commit-check/commit-check-action/network/dependents).
 
-## Ready in two minutes
-
-```console
-$ pip install commit-check
-$ commit-check --message --branch
-```
-
-No configuration file needed to start — sensible defaults apply immediately, and
-you tighten them when you are ready.
-
-[Get started :octicons-arrow-right-24:](getting-started.md){ .md-button .md-button--primary }
-[Rules reference](rules.md){ .md-button }
-
 ---
 
 <div class="community-section" markdown>

diff --git a/mkdocs.yml b/mkdocs.yml
@@ -139,19 +139,27 @@ plugins:
 hooks:
   - scripts/mkdocs_hooks.py
 
+# Two groups, split by what the reader is doing: Guides are pages you follow to
+# get something done, Reference is what you look a fact up in. The pages are
+# ordered within each group by how often they are needed.
+#
+# There was a third group, "About", holding migration, troubleshooting and the
+# changelog — none of which is about the project. Troubleshooting was the
+# problem: it is the page you want when a build has just gone red, and nobody
+# looks under "About" for that. It has exactly one inbound link in the whole
+# site, so the nav was doing nearly all the work of making it findable.
 nav:
   - Home: index.md
   - Getting started: getting-started.md
   - Guides:
       - Integrations: guides/integrations.md
       - Policy guides: guides/policies.md
       - Command-line recipes: example.md
+      - Troubleshooting: troubleshoot.md
+      - Migrating from v1: migration.md
   - Reference:
       - Rules: rules.md
       - Configuration: configuration.md
-  - About:
-      - Migrating from v1: migration.md
-      - Troubleshooting: troubleshoot.md
       - Changelog: changelog.md
   - Blog:
       - blog/index.md