docs(claude-md): make docs/STYLE.md discoverable and add a verify.sh docs step

[datlechin]

docs/STYLE.md is the spec for how a docs page is written. Nothing in the repo said so, so an agent writing a page had no reason to open it.

What went wrong

While writing the docs page for #2383 I never read docs/STYLE.md. The page passed every check I ran and still broke ten of its rules: the first sentence restated the frontmatter description, both alt attributes were byte-identical to the <Frame> caption, five clauses were design rationale, three sentences made TablePro the subject, you can appeared twice, a **Label** bullet list stood in for a table, prose restated the table directly above it, and a load-bearing <Note> carried a fact with no other home.

It also shipped two false claims, which is the failure STYLE.md §9 exists to stop.

Four gaps, not one forgetful agent

1. docs/STYLE.md is referenced nowhere. Not in CLAUDE.md, not in .claude/rules/, not in the fix-issue skill. grep -rn "STYLE.md" outside the file itself returns nothing.

2. verify.sh lint prints a false pass signal. It ends with docs: clean: 266 references check out. That is scripts/check-doc-symbols.sh checking CLAUDE.md and .claude/ for stale symbols; it never opens docs/. The label reads exactly like docs validation, and I reported "docs: clean" on that basis.

3. verify.sh had no docs step. The two scripts that do read docs/ (check-writing-style.sh, check-docs-against-source.py) were in no playbook. I only met the second one when CI failed on Cmd+Return vs Cmd+Enter.

4. .claude/rules/ had no entry for docs/. Four rule files fire on path globs for plugins, sync, UI lifecycle and MCP. Docs had none.

What this changes

.claude/rules/docs-authoring.md (new) fires on docs/**/*.mdx, docs/docs.json, docs/snippets/, docs/images/. It names STYLE.md, names the two scripts, states plainly that the agent docs: line does not cover docs/, and lists the eight rules no script enforces with the defect behind each.

verify.sh docs (new step) runs both docs scripts and reports the failing check with its file:line rather than the twenty passes above it. Tested by reintroducing the exact bug it exists to catch:

$ verify.sh docs                          # clean tree
status: PASS
docs/: house style and source claims both agree

$ verify.sh docs                          # after planting `Cmd+Return`
status: FAIL
  FAIL  keyboard shortcuts
          features/zz-probe.mdx:6: `Cmd+Return` spells the key Return; the corpus spells it Enter
  1 claim(s) in docs/ contradict the source.

verify.sh lint relabels its line agent docs: and carries a comment saying what it covers and what to run for docs/.

CLAUDE.md Mandatory Rule 3 gains the pointer to STYLE.md, the verify.sh docs command, and the distinction between the two checks.

The fix-issue skill gains one Phase 3 bullet: read STYLE.md before writing, write the page last.

docs/STYLE.md §9 gains the scar this PR came from. The section already said "verify before you write"; it did not say the ordering half. A page written early states what the code did that morning, a later commit in the same branch changes the code, and nobody re-reads the page.

Verification

Step	Result
bash -n verify.sh	clean
shellcheck --severity=warning verify.sh	clean
verify.sh docs on a clean tree	PASS
verify.sh docs with the bug reintroduced	FAIL, names the file and line
docs/scripts/check-writing-style.sh	docs/ matches the house style
docs/scripts/check-docs-against-source.py	docs/ agrees with the source

Split out of #2386 so that PR stays a feature change.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
TablePro	🟡 Building	–	Aug 22, 2026, 8:37 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.