feat(docs-site): rebuild the Pages site as a decision hub with sourced facts and real URLs

[omrsamer]

Summary

Rebuilds the GitHub Pages site (docs-site/) from a hash-routed landing page into a decision-support documentation hub for the four projects, and fixes the factual and accessibility defects found in a full review of the site and the repository. Changes to the rest of the repository are limited to four files (root README.md, assets/repository-atlas-journey.svg, the Pages workflow, and a new .github/dependabot.yml for GitHub Actions only). No file under the four project folders changed.

Why

The previous site rendered about 3,200 words (under 3 percent of the roughly 117,000 words of Markdown in the repository) and sent every task-oriented click to a GitHub blob page. A 28-task persona simulation (platform engineer, security engineer, ML engineer, solutions architect, engineering director) could fully answer 1 task on the site. The same review found 33 factual claims that were wrong or unsourced (for example the cost notice named Aurora, which no project deploys), a skip link that rendered the 404 page because of hash routing, and colour-contrast failures on 9 of 10 pages that the test suite could not see because the contrast rule was disabled.

What changed on the site

• Real URLs and metadata. Path-based routing with build-time prerendering: every route is a real index.html with its own title, description, canonical, Open Graph and Twitter tags. sitemap.xml, llms.txt, a real 404.html and redirect stubs for the six old routes are generated. An inline shim in every page keeps old /#/... links working.
• Facts with provenance. Every adoption-determining fact (validated regions, first deploy time, hands-on time, cost, IaC, account topology, auth and policy posture, status, version, teardown, what it deploys) lives in a typed content model where each value carries a source pointer into the repository, rendered as a link on the page. A test suite verifies every quoted source string exists verbatim in the cited file. Where the repository publishes no number, the site says "not documented" instead of inventing one.
• Decision hub pages. Home tiles that act as a comparison matrix; /start/ (get started, which project fits, prerequisites, costs and cleanup, FAQ); /concepts/ (agent factory, capability contracts with a capability-by-project posture matrix, architecture with all diagrams rendered on-site, glossary); /projects/<id>/ landing pages with status, at-a-glance facts, quickstart, evidence, project-specific sections, figures, known limitations quoted verbatim, documentation index and teardown; /reference/ (security matrix, support envelope).
• Repository documentation rendered on-site. The four project READMEs, the Self-Service docs/ set, its CHANGELOG, the Atlassian connector README and CONTRIBUTING.md are compiled at build time from the sibling folders (no copies) with a sidebar, table of contents, source link and copy buttons on code blocks. Raw HTML is never rendered. The workshop is linked to its public Workshop Studio listing on AWS Builder Center rather than mirrored; notebooks link to GitHub.
• Accessibility and behaviour. Working skip link, focus and scroll management with a polite route announcement, a modal mobile menu with inert content, dropdowns that close on outside click and Tab-out, AA-compliant stage colour tokens with on-dark variants, underlined inline links, fluid type, no horizontal overflow at 320, 390, 1100 or 1440 px, and a legible Atlas SVG (smallest text raised from 10 to 14 units).
• Quality gates. Unit tests (896), a Playwright job over every route at mobile and desktop widths running axe with colour contrast enabled plus behavioural specs (skip link, route change, menu containment, legacy redirects, reflow, no external requests, wording rules), and an extended validate_static.py (prerender outputs, unique titles, canonical and Open Graph tags, hash shim, no externally hosted assets, allow-listed AWS example account IDs, no other-repository references).

Repository-side changes (kept minimal)

• README.md: cost paragraph rewritten per project (the old sentence claimed all projects deploy DocumentDB and Aurora; none deploys Aurora); Blueprint "PrivateLink egress" replaced with what the code deploys (a private VPC with interface endpoints); Tool Gateway row states the actual authorizers (AWS_IAM in the Blueprint, Cognito JWT elsewhere); link to the workshop on the AWS workshop catalog, listed on AWS Builder Center.
• assets/repository-atlas-journey.svg: legibility and contrast only (text at 14 units or larger, light stage colours on the dark panel, bullet lists removed because the cards below repeat them). Still role="img" with title and description; validated by the existing checks.
• .github/workflows/sample-agent-factory-pages.yml: Node 24 via .nvmrc, actions bumped to current majors pinned by commit SHA, persist-credentials: false, wider path filters for the content the site now renders, a browser-gates job the deploy depends on, production deploys never cancelled, workflow_dispatch.
• .github/dependabot.yml: GitHub Actions ecosystem only, weekly, so the SHA pins stay current.

Verification

• npm run typecheck, npm run lint (zero warnings), npm test (896 tests), npm run build (37 pages prerendered plus 404, 6 redirect stubs, sitemap and llms.txt), npm run validate:static, npm run audit (0 vulnerabilities), npm run test:browser (155 passed, 2 viewport-conditional skips, 0 failed) on Node 22 locally; CI runs the same on Node 24.
• Independent verification pass over the built site: 774 internal links and 403 in-page anchors resolve; 234 external URLs return 200; every GitHub source link points at an existing path and heading; 38 runtime requests observed while browsing, 0 to external hosts, 0 cookies, 0 storage keys, 0 console errors; all 9 images in dist match repository files by hash.
• Persona re-run of the original 28 tasks against the built site: 19 fully answerable, 11 partial (the site shows "not documented" for figures the repository does not publish), 0 unanswerable; median 1 click from Home; 26 of 28 answers carry a source link. Before: 1 fully, 13 partial, 14 unanswerable.
• Lighthouse on the built site (mobile emulation, local preview): performance 98, accessibility 100, best practices 100, SEO 100 on Home and on a project page; accessibility was 89 before. Cumulative layout shift is 0 on every project page.

Decisions worth knowing

• No client-side search, analytics, external assets or raw HTML rendering, per the constraints stated in PR feat(docs): add Atlas Journey repository site #34. Search libraries that fetch an index at runtime were therefore left out.
• Agentic-ai-self-service/docs/MCP_CATALOG.md is linked to GitHub rather than rendered because it contains a 12-digit number that the fail-closed validator rejects.
• Workshop track names ("Fast Path", "Build the Platform", "Full Journey") appear only where the workshop itself is described; the site-level paths use different names to end the earlier collision.
• The main JavaScript bundle is larger than before because hub pages and the content model ship together (about 146 KB gzipped); README and doc pages are code-split and load on demand. Each page remains well under 300 KB gzipped.

Follow-ups outside this PR (repository content, not site)

• workshop-building-agentic-ai-platform/README.md says the scoped deploy policies are {1..4} "split across four files"; seven exist. It also names "Aurora PostgreSQL" in the cost note; the stack runs Postgres as a Fargate sidecar. content/introduction/index.en.md says level 200 and one deployable region; the README and contentspec.yaml say 300 and three regions. The published Workshop Studio build is from an earlier mainline (title, duration and regions differ from the repo).
• Agentic-ai-self-service/docs/COSTS.md omits the always-on WAF web ACL; template count is six in code and README and seven in DEPLOYMENT_INTERNALS.md and the architecture diagram; docs/MCP_CATALOG.md:128 contains a real-looking 12-digit account ID.
• enterprise-mcp-governance-gateway/policies/manifest.json sets validationMode: IGNORE_ALL_FINDINGS while its own comment says FAIL_ON_ANY_FINDINGS; the Cedar action-form guidance in this project contradicts the Self-Service docs.
• Blueprint issues enterprise blueprint: migrate Agent Registry before 2026-09-17 preview cutoff #29 (Agent Registry preview API cutoff) and enterprise blueprint: resolve npm audit findings before deployment #30 (aws-cdk-lib below 2.260.0) remain open and are shown as advisories on the site.

🤖 Generated with Claude Code