docs: align commit-message section with commitlint.config.js

[bpamiri]

Summary

The "Commit Message Conventions" section in CLAUDE.md drifted from the actual `commitlint.config.js` rules in two ways, and we kept tripping over both. This PR re-syncs the section and adds enough structure that contributors (and Claude Code agents) stop guessing.

What was wrong

1. Seven `web/*` scopes were missing from the docs

The config allows 23 scopes; CLAUDE.md only listed 16. The static-site monorepo's `web`, `web/ui`, `web/landing`, `web/blog`, `web/guides`, `web/api`, `web/starlight` scopes were added to commitlint but never mirrored into the docs. So when picking a scope for a `web/sites/guides/...` change, the visible options didn't include anything obviously matching — leading to either invented scopes (`tutorial`, `package`) that get rejected, or falling back to `docs` and losing the more specific signal.

2. The subject-case rule was stricter than reality

CLAUDE.md said:

Subject must be lowercase. No sentence-case, start-case, or pascal-case.

The config actually only forbids ALL-CAPS:

'subject-case': [2, 'never', ['upper-case']]

With an explicit comment that sentence-case, start-case, and pascal-case are allowed for proper nouns like `Giscus`, `CockroachDB`, `Buttondown`. Over-strict docs led to unnecessary downcasing of legitimate proper nouns.

What this changes

• Adds the full 23-scope list, split into framework layers vs. web monorepo for navigability.
• Adds a "Common scope choices by file path" table — the answer to "what scope do I use here?" is now a two-step lookup instead of guessing.
• Fixes the subject-case rule to match the config (only ALL-CAPS forbidden).
• Adds a "scope is optional" call-out — many commits don't need one, and "no scope" is preferable to guessing.
• Adds a recovery footnote — when CI rejects a commit message, amend + force-push fixes it without a separate commit.
• Names `commitlint.config.js` as the source of truth so future drift can be resolved by re-syncing this section to the config, not the other way around.

How this surfaced

PR #2390 ("add upgrade tip to chapter 1 install section") used `docs(tutorial):` and was rejected by `Validate Commit Messages`. The CLAUDE.md section listed no obvious scope for tutorial content, so I reached for one that seemed semantically reasonable. The actual valid choice was `docs:` (no scope) or `docs(web/guides):` — neither was clearly indicated by the docs at the time.

Test plan

• CI: `Validate Commit Messages` passes on this PR (header is now `docs: align commit-message section with commitlint.config.js` — type `docs`, no scope, lowercase subject, under 100 chars).
• Manual: skim the rendered CLAUDE.md and confirm the table reads sensibly.

🤖 Generated with Claude Code