docs: rewrite the corpus against the source

[datlechin]

Rewrites the docs corpus against the source it describes, and adds the gates that keep it there.

The corpus grew by accretion: pages were extended one changelog entry at a time, so it read as a
list of features rather than as documentation, and 39 factual claims had drifted away from the
Swift that defines them. docs/STYLE.md is the contract this rewrite was measured against.

What the rewrite corrected

Each of these was checked against the file that defines it, not against another doc page.

Page	Was	Is
development/setup	The app "references NSGlassEffectView in the quick switcher"	It does not. That symbol appears only in a doc comment explaining why it is not used. The real macOS 26 dependency is glassEffect(_:in:) behind if #available
development/plugin-development	A plugin "must be signed by TablePro's signing team"	PluginCodeSignatureVerifier.evaluate accepts any Developer ID leaf and PluginDeveloperTrustStore gates it. Third-party signing works and no page said so
development/plugin-registry	Bundled plugins "are never published to the registry"	Six of the fourteen (sqlite, clickhouse, redis, xlsx, mql, sqlimport) carry registry arms, so a fix can reach users already on a shipped app
development/testing-plugins	Add your bundle to a "Copy Plug-Ins" build phase	No such phase exists, and the edit targets a generated .xcodeproj that the next generate discards
development/code-style	"Treat acronyms as words: JsonEncoder not JSONEncoder"	Inverted. 147 files use JSONEncoder and none use JsonEncoder; declared type names run SQL 183 to Sql 20, MCP 181 to Mcp 1
development/architecture	Undo goes through the window's UndoManager	windowWillReturnUndoManager resolves it to workspaces.selected, so the stack is per connection. Structure edits use a private manager inside StructureChangeManager
development/building	Release env needs APPLE_ID; five jobs gate the release	No script reads APPLE_ID; it is NOTARY_PROFILE. The release job needs four, with build a matrix over both architectures

development/building was 60% steps a contributor cannot run without a Developer ID, so release,
notarization, DMG packaging and library publishing moved to development/releasing.

Prose

The rewrite was measured, not eyeballed. Openings were the worst of it: uniform in length and
shape across pages that have nothing else in common.

	Before	After
Opening sentence, mean	18.7 words	15.5
Opening sentence, median	19	14
Openings of 25 words or more	25	11
Openings that are a compound or carry a colon	65 of 113 (58%)	49 of 113 (43%)

Body prose averages 11.8 words a sentence, so openings were 59% longer than the pages behind them.
They now sit close to the prose they introduce.

Adjacent pages that opened on the same furniture were re-led: three consecutive colon-and-list
openings in the SQL editor group, data-grid next to query-results, cloudflare-tunnel next to
cloud-sql-proxy, and five of six Customization pages that put Cmd+, in their first two
sentences. The group index owns that shortcut now and no tab page repeats it.

Six repeated facts became snippets. All 17 registry-plugin pages share one sentence about
installation rather than 17 rewordings of it.

The new gate

docs/scripts/check-links.py resolves every internal link, anchor, redirect and image against the
files on disk, and answers what the Mintlify CLI does not: a page that exists in no navigation
group, so nothing links to it and the sidebar never shows it. That has happened twice here. It is
plain Python with no native dependencies, which matters because the Mintlify CLI stopped running
locally this week when npm began blocking install scripts.

Verified by reintroducing each failure class: a dead link, a dead anchor, and an orphaned page.

Also

CLAUDE.md attributed -skipPackagePluginValidation to a SwiftLint plugin in
CodeEditSourceEditor. No Package.swift under LocalPackages/ or Packages/ declares any plugin.
The flag is still required; the reason given for it was not true, so it is gone rather than
replaced with a second guess.

Checks

Source parity, writing style, and links and navigation coverage all pass. mint validate,
broken-links and a11y run in CI.

The Databases group has a landing page

It had 26 leaves and no answer to the question the group is named after. databases/index now owns
the 27-row table; the home page keeps a pointer rather than a second copy of it.

A second gate keeps that table honest. It reads every ("TypeId", PluginMetadataSnapshot(…)) tuple
out of PluginMetadataRegistry*.swift and its extensions, which is the one place a new engine has
to be declared, and fails on a missing row, a wrong default port, or an engine the chooser does not
offer. Verified by reintroducing all three. The count last drifted to 26 against a real 27.

[chatgpt-codex-connector]

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