PRDCT-565: docs quality gates

[Iamfle4ka]

Adds automated quality gates to the PR build so content and rendering regressions block merge — prompted by the wide-table display:block bug (PRDCT-379) reaching main unnoticed.

Note on the force-push (4 Aug). This branch had sat unmerged since 8 Jul while main moved 118 commits, and two parallel branches had independently rebuilt the same gates. The history was rewritten to consolidate them into this one PR, fix three defects found while verifying, and — see the last section — restore a documentation section that a bad merge on the superseded branch had silently deleted.

What runs on every PR

.github/workflows/branch.yml builds the PR and then runs four checks. Two are ratchets, not absolute gates: the docs carry real inherited debt (broken links into pages that still live on developers.keboola.com), so they compare against a committed baseline and fail only on breakage the branch introduced.

Check	Fails when	Baseline
npm run lint	a PR adds a broken link or anchor, a missing/placeholder image, frontmatter without title/slug, an unclosed fence, a raw HTML table, a Liquid leftover, a deprecated term	scripts/lint-baseline.json
npm run check:redirects	a PR orphans a dev URL that used to resolve — a page moved, renamed or deleted without a redirect	_data/redirects/not-yet-migrated.txt
npm run check:cli	docs reference kbagent commands or flags the CLI no longer has	—
npm run check:render	a table or layout regresses across viewports	—

Both baselines shrinking is the point — they double as the remaining cleanup list. AGENTS.md documents how to rebaseline and why growing one needs justification.

Three defects fixed in the gate itself

1. A deleted page read as healthy. resolves() in lint-docs.mjs (and audit-phase2.mjs, and inDist() in check-redirects.mjs) accepted dist/<route>/ as proof a page exists. But a page directory outlives its index.html — the page's images sit in it. So the one breakage these gates exist to catch was invisible. Every candidate must now be a file. Measured: deleting dist/storage/tables/index.html produced 0 findings before, 390 after.

2. A CI step with no script behind it. main had gained check:cli; this branch replaced that line in package.json, so the Check CLI reference freshness step that branch.yml already called had nothing to run. Both sets of scripts are kept.

3. A platform-dependent sample. Cherry-picked 6966b5b1, which existed only on the pushed ref: check-render sorts before sampling, because readdir order differs between macOS and Linux and an unsorted sample means local pass / CI fail.

The URL contract now actually runs

check-redirects.mjs and the dev→help map come from PRDCT-572, which wires neither to CI — so the conservation check had never run on a PR. It runs here, tolerating the 119 dev URLs never yet migrated and failing only on ones this branch orphans. Two soft skips keep merge order from mattering: a missing map skips the check; a present map with no baseline reports instead of failing. PRDCT-572 landing therefore cannot redden main.

Baseline regenerated after fixing the detector, not to silence it

630 findings, up from 605 measured against a month-old tree. The 9 that main's newer content added are now listed as known debt — including one real broken link, /404 → /overview/environment/, worth a follow-up.

A documentation section came back

The superseded branch's merge commit b38f12f8 had dropped 20 lines from src/content/docs/workspace/index.md — the whole Bringing Your Own Key Pair section (BYO Snowflake key pair, needed by tools like SAS CI360) plus two cross-references to it. Merging that state would have deleted the section from production. This branch's copy of the file is byte-identical to main.

Worth noting what it implies: no gate here would have caught it. Deleted prose is not a broken link.

Verification

All ten CI steps pass on this commit. Locally, each gate was verified by breaking the build on purpose, not by inspection:

• remove a linked page → lint exits 1 with 390 new findings; restore → exits 0
• remove a contract-mapped page → check:redirects exits 1 naming the orphaned dev URL; restore → exits 0
• move the map away → skip, exits 0; map present, baseline absent → report, exits 0

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
connection-docs	Ready	Preview	Aug 8, 2026 12:08am

[linear-code]

PRDCT-469

PRDCT-378

PRDCT-565

[Iamfle4ka]

Refreshed status (local run, 2026-07-17): branch is already up to date with main (0 behind). Gates verified locally:

• PRDCT-378 title check — in place (branch.yml), matches the convention the whole PR queue now follows.
• Content lint — ✅ green: OK — no new findings vs baseline on a fresh build.
• Render/layout check (playwright vs preview) — ❌ red with ~33 real findings, all one class: /components/extractors/other/telemetry-data/ tables render display:block (the known wide-table clipping — exactly what PRDCT-379: fix wide tables clipping under the TOC instead of scrolling #989 fixes, currently CHANGES_REQUESTED).

Recommendation: merge order #989 → this PR (gate turns on green), or land this first with the telemetry-data findings baselined. Either way this is the cheapest way to get quality gates on every PR — relevant right now with the phase-1 migration PR #1027 in flight.

[Iamfle4ka]

Rebased onto main — CONFLICTING → MERGEABLE.

• package.json conflict resolved by keeping both sides' scripts: audit, lint, check:render (this branch) alongside check:cli (landed on main via PRDCT-490: new top-level CLI section — kbagent #1015). Lockfile regenerated with npm install --package-lock-only, no --force.
• npm run build clean — 306 pages, same count as main.
• npm run check:cli — 0 findings (251 commands vs 306 pages).
• npm run lint went red after the merge, because the baseline predates 118 commits of main; the findings are pre-existing there (mostly /extend/* links waiting on PRDCT-551: Storage API under Storage (re-cut off main) #1053 / PRDCT-552: Generic Extractor under Components › Data Source Connectors (re-cut off main) #1054). Re-baselined on the merged tree: 1155 → 1353 known findings, gate back to exit 0, so only new regressions fail.

Left as a draft on purpose — tooling sits behind the content work in Michal's ordering. Ready to un-draft whenever you want it in the queue.