diff --git a/docs/changelog.md b/docs/changelog.md
index 06ec4c7..b3d2a6f 100644
--- 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
index b3af7d4..6159745 100644
--- 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
index 60710d0..a41a0fc 100644
--- 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
+```
+
+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.
-
-
-
-- :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.
-
-
+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 }
-
---