Make the agent guides match reality: Vercel deployment, and remove the Jekyll migration scripts

[Iamfle4ka]

What

AGENTS.md said production deploys via GitHub Actions building and running aws s3 sync to help.keboola.com. The live domain is served by Vercel, and every PR gets a Vercel preview deployment.

Contributor-facing docs are the thing agents and new contributors reason from, so this matters beyond cosmetics: anyone working out 404 handling, redirects, trailing slashes or cache headers from that section would reach the wrong conclusion.

What this does and doesn't claim

The S3 sync in .github/workflows/main.yml is still wired up and still succeeds on every push to main — most recently today. So this documents both rather than pretending the workflow is gone: it records that S3 runs but is not what serves the live domain. Whether the sync is still needed (backup, another domain, leftover) is a separate question for whoever owns the infrastructure, and nothing here assumes an answer.

It also records the two Vercel defaults that actually constrain the build, since vercel.json only sets /pagefind/* cache headers: a missing trailing slash is normalized, and 404.html from the build root answers unmatched paths — so the 404 must stay at the build root.

One local-verification note

Added while nearby, because it costs a real debugging detour: astro preview enforces trailingSlash: 'always' and answers a slash-less URL with its own "Not Found" page instead of the site's 404. Locally that reads as a broken 404 page. Open /404.html directly; production normalizes the slash and behaves correctly.

Verification

Documentation only — no build, config or content changes. Claims checked against the live site (server: Vercel; /compentns and /compentns/ both 404, /components and /components/ both 200), against this repo's vercel.json, and against the main.yml run history (still succeeding on pushes to main).

🤖 Generated with Claude Code

---

Also in this PR: two scripts removed, and the guides made to match

The branch grew past its original scope because everything here is the same class of problem — a contributor guide describing a repo that has moved on.

scripts/migrate.mjs and scripts/switchover.mjs are gone

migrate.mjs was not dead weight but a live hazard. It has no dry-run and no confirmation — main() runs on invocation — and pruneStalePages() walks src/content/docs and rm -rfs every page whose Jekyll source is missing from the repo root. That source was deleted wholesale in dff14ec1, and SKIP_DIRS excludes src from the source walk, so nothing maps back.

Simulated read-only (nothing was run): one node scripts/migrate.mjs deletes 307 of 307 pages, zero survivors. It sat in an agent-readable scripts/ directory with AGENTS.md naming it — and "legacy … no longer used" in prose is not a guard.

switchover.mjs goes with it: it calls migrate.mjs, its own job (removing the Jekyll tree) is finished, and its own output already said migrate.mjs was obsolete and should be dropped in a follow-up. Nothing else references either script — no npm script, no workflow. Git history keeps both.

check-redirects.mjs + _data/redirects/dev-to-help.tsv committed

Both were sitting untracked next to a guide that described them. Committed as a local tool, not a gate: nothing in .github or package.json calls it, and it currently exits 1 because 119 dev URLs have no home in dist until the migration batches land. Its --gen mode additionally needs PLACEMENT-MAP.md, which is not in the repo.

CLAUDE.md

• Adds How to work with me: skills are invoked when they match the task, not before every answer.
• The fact-checker / guide-tester delegation now exists as a real section — .claude/settings.json's PostToolUse hook has been citing "CLAUDE.md Delegation" at a section that did not exist, so the model was being handed an authoritative pointer into nothing.
• Drops the three rules it restated from the @-imported AGENTS.md; they now live in one place.

.gitignore

reports/, the local briefing/plan/map notes, _graph/, .obsidian/, shoot.mjs and screenshots.manifest.json — all local artifacts that were untracked and one git add -A away from being committed. .claude also loses its trailing slash: it is a symlink, and .claude/ only matches a real directory.

Verification for this part

npx astro build clean (306 pages) after the deletions, and check-redirects.mjs runs.

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
connection-docs	Ready	Preview	Aug 4, 2026 9:08pm

[Iamfle4ka]

Superseded by #1086, which consolidates the four PRs that were all editing CLAUDE.md / AGENTS.md / .gitignore (#1000, #1065, #1057, #1076).

What survived into #1086 — the whole guide part: the Vercel-is-production section in this PR's wording (including that main.yml's aws s3 sync still runs and succeeds but isn't what serves the domain), the two Vercel defaults, the astro preview trailing-slash/404 note, How to work with me, and the .gitignore changes including the .claude no-slash fix.

What did NOT survive — still open work, recorded here so it isn't lost:

1. Deleting scripts/migrate.mjs and scripts/switchover.mjs. The hazard this PR found is real and re-verified: main() runs on invocation with no dry-run or confirmation (migrate.mjs:1040), and pruneStalePages() (:877-895) deletes every page under src/content/docs whose Jekyll source is missing from the repo root — a source tree deleted wholesale in dff14ec1. PRDCT-545: unify the contributor guides — house style, migration rules, Vercel reality, gitignore #1086 neutralizes it in prose only: the AGENTS.md repo-map entry now reads DO NOT RUN with the reason, instead of "legacy … no longer used". The files are still there. Worth a small follow-up PR that does nothing but delete them.
2. scripts/check-redirects.mjs + _data/redirects/dev-to-help.tsv. Not dropped on merit — PRDCT-469: docs quality gates #1002 and PRDCT-572: consolidated dev→help redirect map + conservation checker #1043 add the same two paths with a different design (PRDCT-469: docs quality gates #1002 pairs it with _data/redirects/not-yet-migrated.txt as a CI ratchet). Three parallel attempts need deconflicting before any of them lands, and that decision doesn't belong in a guides-only PR.

Closing as a duplicate; the branch stays on the remote, so both pieces above are recoverable from it.