Product-writing audit of README and FEATURES, plus two doc-truth tests

[debabsah]

Copy only. Stacked on #3, so the base is fix/review-tier-1-2 and this diff
shows just the writing. GitHub will retarget it to main when #3 merges.

Split out from #3 deliberately: that PR wants a code reviewer, this one wants
an eye on voice.

Two factual errors, both previously reported as fixed

FEATURES.md said the MCP server exposes "Six tools". It exposes ten. This
is v2 roadmap item 20, which was corrected in the README and VERIFICATION.md
and never in FEATURES.md.

The CLI Verbs table was missing brief, advise, redesign and
calibrate. That is v2 roadmap item 21, which DESIGN-BRAIN-V2.md claims
landed and which never landed at all. Four shipped verbs were undocumented.

Neither is maintained by hand any more. tests/test_docs.py now parses
add_parser calls out of cli.py and asserts the verb table matches in both
directions (a missing verb fails, and so does a documented verb that does not
exist), and counts @mcp.tool() decorators against every "N tools" claim in
the prose.

DESIGN-BRAIN-V2.md's status line is corrected from 36 of 37 to 35, including
the note that the first correction was itself wrong because nobody had checked
item 21 before writing it.

README

The hero named the spec file as the thing you write, which puts a format's
learning curve in the first ten words. It now leads with the round trip, names
the command line, uses three verbs (builds, updates, decompiles) so create-only
is not a possible reading, and puts the AI as a closing beat rather than a
premise.

Other changes:

• Decompile moved onto the first screen. "I already have 200 dashboards" is
  the objection that disqualifies a dashboards-as-code tool, and the answer was
  below the fold.
• chartwright plan and its non-zero exit are named where the CI story
  lives. Per COMPARISON.md nothing else diffs a spec against a live dashboard,
  and it was described in five words that mentioned neither the command nor CI.
• COMPARISON.md is linked for the first time. It was unreachable from the
  front door.
• The word "design" had two meanings (the spec's expressive surface, and
  visual quality). Now one.
• Every page in docs/ except the v2 review record is reachable from the
  README.

Editorial pass

Punctuation normalised across the user-facing docs, and several sentences
tightened where a clause was doing two jobs. Two of those rewrites exposed
rule-4 violations the punctuation had been hiding: "no fork of the rulebook"
and "zero extra API calls" both defined a capability by what does not happen.

The rule-table cells in DESIGN-BRAIN.md are generated, so that is fixed in
gen_rule_table.py rather than in its output; fixing the output by hand would
be undone by the next --write.

DESIGN-BRAIN-V2.md is left as-is. It is a verbatim record of review findings,
and editing quoted findings would make the record less faithful.

Verification

256 tests pass under both pytest invocations, params_drift --all is clean
against 4.1.4, 5.0.0 and 6.1.0, gen_rule_table.py --check matches the
registry, and the README's JSON and TOML examples were re-validated after every
edit.

Not done here

• The GitHub repo description still reads Dashboard compiler for Apache Superset, which is weaker than the hero it now sits above and reaches more
  people than the README does.
• Several bold names are slogans rather than descriptions ("A Visual Designer
  On Call", "It Learns From You", "Your Data Stays Put", the "AI-Native"
  section header). Left alone: that is voice, and it is the author's call.
• "No Empty First Load" promises charts open on the full data range, while the
  new data.unwindowed-history rule warns when nothing bounds the window. Both
  are true and they address different problems, but a reader meeting both could
  think the tool argues with itself.