PRDCT-545: unify the contributor guides — house style, migration rules, Vercel reality, gitignore - #1086
Merged
Conversation
Consolidates four overlapping PRs that all edited the same three files: #1000 (docs house style + revamp process), #1065 (dev→help migration rules), #1057 and #1076 (Vercel-is-production, .claude symlink fix). Two conflicts are resolved by hand rather than by merge order: the Screenshots bullet, which #1000 and #1057 rewrote in different directions, and the Claude-specific notes list, where #1057 dropped three bullets #1000 kept. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
jordanrburger
approved these changes
Aug 5, 2026
This branch was successfully deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Four open PRs were all editing the same three contributor-facing files, partly overlapping and partly contradicting each other. This is their union, hand-merged, so whoever reviews it decides once instead of four times.
Supersedes #1000, #1065, #1057 and #1076 (PRDCT-545 + PRDCT-592) — closed as duplicates of this one.
Why they couldn't just be merged in sequence
Screenshotsbullet in opposite directions: PRDCT-545: add docs-revamp house style + process to CLAUDE.md #1000 splits it into debug shots (never committed) vs. doc UI-locator shots (committed topublic/<section>/); Make the agent guides match reality: Vercel deployment, and remove the Jekyll migration scripts #1057 replaces it with a "keep throwaways out of the repo" wording that drops thepublic/half.Claude-specific notesbullets that PRDCT-545: add docs-revamp house style + process to CLAUDE.md #1000 keeps and builds on.CLAUDE.mddiff is byte-identical, the.gitignorenearly so — but they wordAGENTS.mddifferently, so merging both leaves the loser's wording as a conflict.Whoever merged second would have had to re-decide all of this in a conflict resolution. Resolved here instead.
What's in it
CLAUDE.mdfact-checker/guide-testersubagents after docs changes..claude/settings.json's PostToolUse hook has been citing a "CLAUDE.md Delegation" section that did not exist — this makes the pointer resolve.public/<section>/, andscripts/shoot.mjsis not gitignored so don't commit it.@-importedAGENTS.md(content →src/content/docs/, CSS →custom.css, view-transition verification, ask-a-maintainer). Each verified still present inAGENTS.mdunder Core rules / Verify before pushing — one place, not two.DEV-MIGRATION-PLAN.md, which this PR gitignores. The numbers are inlined instead (2026-08-03 scan: 210 files linking/extend/component, 65 linking/extend/common-interface,keboolaorg alone), so no committed guide points into a local-only note.AGENTS.mdhelp.keboola.comis served by Vercel frommain; PRs get preview URLs. Records the two Vercel defaults that actually constrain the build, sincevercel.jsononly sets/pagefind/*cache headers: missing trailing slashes are normalized, and404.htmlfrom the build root answers unmatched paths — so the 404 must stay at the build root..github/workflows/main.ymlstill runsaws s3 sync dist s3://help.keboola.comon every push tomainand still succeeds (most recently 2026-08-04). Documented as "runs, but is not what serves the live domain" — whether it's still needed is a question for whoever owns the infrastructure, and nothing here assumes an answer.astro previewnote: it enforcestrailingSlash: 'always'and answers a slash-less URL with its own "Not Found" page, so a locally-tested 404 looks broken when it isn't. Open/404.htmldirectly.scripts/map entry formigrate.mjs/switchover.mjsbecomes a guard instead of a label.main()runs on invocation (no dry-run, no confirmation) andpruneStalePages()deletes every page undersrc/content/docswhose Jekyll source is missing from the repo root — and that source tree was deleted wholesale indff14ec1. "Legacy, no longer used" in prose is not a guard for a file sitting in an agent-readable directory..gitignore.claude/→.claude, no trailing slash. This is the load-bearing one: with the slash it matches directories only, so when.claudeis a symlink to a rig kept outside the repo, the symlink itself stayed untracked-and-committable.git add -Afrom being committed:reports/,*-BRIEFING.md(generalized from PRDCT-592: correct the agent guides on Vercel, gitignore the rig symlink #1076's datedAUG5-BRIEFING.md),DEV-MIGRATION-PLAN.md,SECTION-MAP.md,_graph/,.obsidian/,scripts/shoot.mjs,screenshots.manifest.json.What this PR deliberately does not carry
scripts/check-redirects.mjs+_data/redirects/dev-to-help.tsv. Make the agent guides match reality: Vercel deployment, and remove the Jekyll migration scripts #1057 committed them, but so do PRDCT-469: docs quality gates #1002 and PRDCT-572: consolidated dev→help redirect map + conservation checker #1043 — three PRs, two different designs. PRDCT-592: correct the agent guides on Vercel, gitignore the rig symlink #1076 additionally listscheck-redirects.mjsin theAGENTS.mdrepo map without committing it; that line is dropped rather than carried, so the map only describes files that exist. Deconflicting the three is separate work.migrate.mjs/switchover.mjsdeletion from Make the agent guides match reality: Vercel deployment, and remove the Jekyll migration scripts #1057. Neutralized in prose here, but the files remain. Still worth doing as a small follow-up.Verification
npm run buildclean, 306 pages.git check-ignore -v .claude→ matches the new rule;git statusno longer offers the symlink.git diff --stat upstream/main→ exactly the three files, no build or content changes.vercel.json(only/pagefind/*headers),main.yml:30(the S3 sync),main.ymlrun history (succeeding),scripts/migrate.mjs:877-895,1040(pruneStalePages+ baremain()), and each droppedCLAUDE.mdbullet located inAGENTS.md.🤖 Generated with Claude Code