Expand pgferry.com docs surface for issue #69

[GingerAdonis]

Closes #69

This draft PR makes pgferry.com the primary end-user docs surface instead of a thin shell that points users back to GitHub for the real answer.

What changed

• add full on-site reference/* coverage so the missing reference routes build again
• add Bun-based site CI with a built-site route/link verification crawl
• restructure the docs IA around task-first sections: Start Here, Migration Patterns, Source Guides, Examples, Operations, and Reference
• rewrite the homepage around operator guidance, proof, and concrete next steps
• turn examples into on-site, copy-pasteable example pages with inline configs and SQL snippets
• add source-specific guides and operator guidance pages for plan output, snapshot choice, cutover, resume, unlogged tables, unsupported objects, and failure recovery
• shrink README.md into a concise project entry point that points users to the website for full docs
• retire the duplicated top-level docs/*.md end-user docs in favor of a small pointer page
• add repo-owned site deployment metadata with vercel.json, robots.txt, and stronger canonical/sitemap verification
• set the site CI job up to provision Node via actions/setup-node before Bun so Astro gets a supported runtime on GitHub Actions

Verification

• bun install --frozen-lockfile
• bun run build
• bun run check-routes

Commits are intentionally split into phases:

1. 9709559 Add site reference docs and route checks
2. c9ddc44 Expand site docs IA and example coverage
3. 84031aa Retire repo docs and harden site deploy config
4. fab6879 Set Node 22 for site CI builds
5. 38d46bd Use Node lts in site CI job
6. b65f40b Add operator guidance follow-up pages

Remaining external follow-up

• If www.pgferry.com is attached in Vercel, configure the domain redirect there so the live host behavior matches the apex canonical URLs emitted by the site.

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
pgferry	Ready	Preview, Comment	Mar 13, 2026 3:26pm

[opencode-agent]

Code Review Summary

Positives

• Verification script is well-structured with clear error messages
• Reference docs are comprehensive and well-formatted
• CI properly runs site checks in parallel with Go tests

Issues to Address

1. CI - Missing dependency between site and other jobs

# .github/workflows/ci.yml:214
needs: [test, integration-mysql, integration-sqlite, integration-mysql-postgis, integration-mssql]

The build job doesn't depend on site - intentional?

2. Verification script - Hardcoded expected routes
site/scripts/verify-build.mjs:7-19 - If new routes are added, this script must be manually updated. Consider auto-discovery or a config file.

3. .gitignore change is incomplete
Line 35-37 adds reference/ to gitignore but the path already exists as site/src/content/docs/reference/. The gitignore entry may be for a different reference/ folder at root that doesn't exist yet.

4. Missing check-routes in build pipeline
The site job runs build and check-routes, but the build job (Go binary) doesn't depend on site passing. This is likely intentional for deployment independence.

5. Documentation - No mention of Phase 2
The PR description says Phase 2 is "still in progress" but there's no draft marker or note in the docs indicating incomplete state.

6. Minor: verify-build.mjs line 112

if (pathname.endsWith('/')) {

Should be path.extname(pathname) - currently uses path (the module) not the variable. This will cause runtime error.

Recommendations

• Fix the path.extname bug in verify-build.mjs - this will crash when checking non-HTML assets
• Consider making expected routes configurable rather than hardcoded
• Add a note in the reference docs that they're Phase 1 of the documentation expansion

Overall: Good documentation additions, but the verification script has a bug that will cause CI failures.

opencode session  |  github run