docs: rebuild the documentation site as a product surface - #515

Replace the top tab bar with a left sidebar, and group the pages into
Getting started / Configuring / Reference / About so the whole
documentation set is visible at a glance instead of one tab at a time.
On a rule page the sidebar also nests that page's own table of contents,
putting every rule one click away.

Rewrite the rules reference along the lines of a linter's rule
documentation: an index table per category giving each rule's code,
name, message, the CLI flag that runs it, and whether it is on by
default, followed by a section per rule answering what it does, why it
matters, and how to fix it, with a before/after example and the options
that control it.

Correct several defaults in the configuration reference that had drifted
from the source: subject_capitalized and subject_imperative are off by
default (documented as on), allow_empty_commits and allow_wip_commits
are on (documented as off), and allow_commit_types was missing perf,
build, and ci. The "Default Behavior" tip repeated the same mistake.

Guard all of it with tests, so the documentation cannot drift again:
documented boolean and list defaults are compared against the values in
commit_check/__init__.py, and every rule must have a section heading
that answers what it does, why it is bad, and which options apply.

Also fix four reStructuredText title underlines that were shorter than
their titles, letting the docs build cleanly under -W.

… runtime

The subject-length rules are on by default, not off. `get_default_config()`
sets subject_max_length to 80 and subject_min_length to 5, and
`ConfigMerger.from_all_sources()` starts from it, so with no config file at
all a subject over 80 characters fails CC004. Both the rules reference and
the configuration reference claimed there was no limit.

The same review turned up four more inaccuracies:

- author_email_pattern defaults to `^.+@.+$`, not an empty string.
- require_rebase_target defaults to `""`, not None.
- CC201's option is branch.conventional_branch; it was documented under the
  commit section, where configuration merging would ignore it.
- required_signoff_name and required_signoff_email were documented in the
  example config and in CC012's options, but no such options exist anywhere
  in the code.

Two rule examples also demonstrated values that pass the very check they
illustrate: `root` satisfies the built-in author name pattern, and
`root@localhost` satisfies `^.+@.+$`. Both now use values that actually fail,
with a note explaining how permissive the built-in patterns are and when to
replace them.

Rework the drift guard so this class of error is caught mechanically. Rather
than comparing against a couple of constants, the options table is now parsed
and every row checked against `get_default_config()` — the same dict the CLI
builds its configuration from. Two further tests assert the table and the
runtime describe the same set of options, in both directions, which is what
catches an invented option like required_signoff_name or a newly added one
that nobody documented.

Also scope the rule-index table styling to those tables so long regexes in
the configuration table stay wrappable, and check each rule's heading inside
its own section instead of anywhere on the page.

The regex match may be None, so reading .group() from it before the None
check failed mypy and took the lint session down with it.

CodSpeed reported test_every_rule_is_documented as a 27% regression. It is
not one: that test reads docs/rules.rst and scans it for anchors, and this
branch grows that file from 7.4 KB to 22.2 KB. A 2.99x larger file taking
1.37x longer to read is the expected, sub-linear result, and no runtime code
changed on this branch at all.

The marker is documented as meaning "performance-related tests", which these
are not. Left in place, the performance gate would report a regression every
time somebody expands the rules reference — penalising the act of writing
documentation.

The catalog and rule-builder tests in this file keep their marker; those do
exercise the package.

The deploy preview failed to build:

    ERROR - Config value 'site_url': The URL isn't valid, it should
            include the http:// (scheme)

Values in a [context.*.environment] block are literals — Netlify does not
interpolate them — so SITE_URL reached MkDocs as the unexpanded string
"${DEPLOY_PRIME_URL}", which is indeed not a URL.

Set it in the context's build command instead, which runs in a shell where
the variable expands. The redirect hook now also tolerates a site_url without
a trailing slash, since that is the form DEPLOY_PRIME_URL takes.

The deploy preview could not open /rules/. The build emits a redirect stub at
rules.html for the old Sphinx URL, and Netlify normalises "/rules" and
"/rules/" to the same resource, so that stub was served in place of the page
it points at and redirected to itself forever.

Turn the normalisation off and declare the legacy URLs as Netlify redirects,
which resolve before file lookup and so cannot collide with the page they
target. The emitted stubs stay for GitHub Pages, and now refuse to redirect a
page to itself, so the same collision cannot reappear on another host.

The stubs also carry the fragment across. The links most worth keeping alive
are the per-rule ones — rules.html#cc003 — and a bare redirect dropped the
anchor, landing the reader at the top of a 700-line page.

From review, all verified against the source before fixing:

- The RST converter missed four constructs: `.. Attention::` (it only matched
  lowercase), `.. tip ::` (a space before the colons), and two links whose text
  wrapped across a line. They were rendering as literal text.
- The changelog documented `forbid_ai_attribution`, which does not exist; the
  option is `ai_attribution`, defaulting to "ignore".
- The options table mapped `allow_force_push = true` to
  `CCHK_ALLOW_FORCE_PUSH=false`, describing opposite behaviour for equivalent
  settings.
- Troubleshooting had its two bypass headings the wrong way round: --no-verify
  skips every hook, SKIP= skips one.
- Link colour was #1e85a8 on white, 4.2:1, under the 4.5:1 needed for body
  text. Now #176b89 at 6.0:1.
- The landing page claimed attestation "verified at install time"; only a
  manual verification step exists, so it now says what is true.
- The organization guide said "three lines" above a one-line example.
- pr-comments cannot post on fork pull requests, because a fork's
  `pull_request` run gets a read-only token that `pull-requests: write` does
  not override. Documented, along with why `pull_request_target` is not a
  casual substitute.

The previous logo.svg was a new line-art icon that did not match the
project's actual logo. Vectorize docs/_static/logo.jpg (a 900x504 PNG in
the old Sphinx site) with potrace instead, so the SVG is pixel-identical
to the original: the 'commit' wordmark, the check mark and the branch
shape in the brand color #2C9CCD.

The old logo.jpg could not be used as-is on the new site: Sphinx's
conf.py had it commented out ('can not display well in blue background'),
it carried 10 KB of transparent padding around a 300x293 mark, and the
new header renders the logo via <img>, where currentColor would resolve
to black. The traced SVG keeps the exact shapes with a hardcoded fill,
so it renders identically in the light and dark palettes.

The header background is the brand color #2c9ccd (--md-primary-fg-color),
the same blue the logo is filled with, so the logo was invisible. This is
the same reason the old Sphinx site had html_logo commented out ('can not
display well in blue background').

Keep the original blue logo unchanged and give it a white rounded tile.
On the blue header the tile makes the logo visible; in the drawer, which
sits on a light or dark gray background, the blue logo shows directly.