Docusaurus Website With Live Demo Report

Publish a GitHub Pages website so the README demo report renders in a browser instead of showing HTML source, and give the project a curated landing page plus a small documentation set.

Traceability

• Spec ID: 2026-07-28-docusaurus-site-demo-pages
• Status: Implemented
• Story: none (open-source launch gap: repository-relative HTML demo links are not rendered by GitHub)

Intent

• The strongest conversion path for an open-source tool is seeing the output before installing. The README currently links assets/demo/better-harness-report.html as a repository-relative path, which GitHub renders as source code.
• The repository already contains launch-quality English content (README narrative, docs/concepts.md, docs/glossary.md, models/agent-work-loop.md, docs/adapters/README.md). The website curates that content; it does not fork product judgment.

Design

• docs/ holds an isolated Docusaurus 3 site with its own package.json, colocated with the canonical repository markdown (docs/ARCHITECTURE.md, docs/specs/, docs/adrs/, ...), which stays outside the published site. Curated site pages live under docs/docs/. Root production dependencies and the npm files whitelist exclude all site machinery (docs/docs/, docs/i18n/, docs/src/, docs/static/, docs/scripts/, docs/build/, config files); pack:verify enforces that boundary.
• The landing page tells one story in six blocks: hero, live demo (report + history animation), how it works (Agent Work Loop + architecture), quick start prompt, per-host install links, footer.
• docs/scripts/sync-assets.mjs copies the three published demo assets, the two English SVG diagrams, and the Codex install screenshot into docs/static/ before start/build. Synced targets are gitignored; assets/ stays the single source of truth.
• The demo report is published as a directory route (demo/better-harness-report/index.html) so Docusaurus production preview and GitHub Pages resolve the same base-URL-aware link without rewriting an explicit .html suffix outside /better-harness/.
• Docs are a curated publication view (Getting Started, Concepts, Hosts, Reference). Repository markdown remains canonical; each curated page links back to its GitHub source. No blog, no versioning in v1.
• The site ships two locales: en (default) and zh-Hans. Homepage strings use @docusaurus/Translate ids filled in i18n/zh-Hans/code.json; navbar/footer/sidebar labels and the eight docs pages are translated under i18n/zh-Hans/. Theme strings reuse the official Docusaurus zh-Hans translations. The demo report artifact stays English in both locales.
• .github/workflows/pages.yml builds the site on pushes to main that touch docs/, assets/, or the workflow, and deploys with the official Pages actions (pages: write + id-token: write only).
• README demo links point to the Pages URL; a repository-relative source link is kept for offline clones.

Acceptance Criteria

• DSDP-AC-1: Opening the README demo link renders the interactive HTML report in a browser (Pages URL), not HTML source.
• DSDP-AC-2: https://qoderai.github.io/better-harness/ serves a landing page that reaches the demo report in one click.
• DSDP-AC-3: The site builds locally with npm ci && npm run build inside docs/ on Node >= 22.
• DSDP-AC-4: Root npm test and npm run pack:verify pass; the npm package contains repository docs markdown but no Docusaurus site machinery (docs/docs/, docs/i18n/, docs/src/, docs/static/, docs/scripts/, docs/build/, site config, or lockfile).
• DSDP-AC-5: Installation docs cover Claude Code, Codex, Qoder, and Cursor as separate tabs consistent with the README.
• DSDP-AC-6: Default-locale site content is English (H2+ headings included); the zh-Hans locale carries the Chinese translation set. Demo assets are synced from assets/, not duplicated by hand.
• DSDP-AC-7: The locale dropdown switches between English and 简体中文; the zh-Hans homepage and all eight docs pages render translated content, and npm run build succeeds for both locales with zero broken links.
• DSDP-AC-8: The generated Qoder runtime ZIP retains canonical repository docs but excludes Docusaurus source, dependency, cache, and build paths. Package verification must fail if any excluded site prefix appears in either the npm tarball or runtime ZIP.
• DSDP-AC-9: In npm run serve, the homepage, docs, locale routes, and every demo-report link return their intended page under /better-harness/; the demo link must not redirect to the site homepage.
• DSDP-AC-10: Before commit, the staged snapshot includes the site plus its README, package-boundary, validation, and test integration, and a staged-only npm dry run contains no Docusaurus machinery.

Non-goals

• No second source of truth for product judgment; skills/, models/, references/, and docs/ remain canonical.
• No blog, versioned docs, search service, or locales beyond en/zh-Hans in v1.
• No automatic publishing of freshly generated Harness reports yet; only the checked-in demo report is published (a later spec may add this).
• No change to roadmap.md content (tracked separately).

Plan

1. Add the Docusaurus skeleton inside docs/ with isolated dependencies.
2. Implement the landing page and asset sync script.
3. Curate the docs set and sidebar.
4. Add .github/workflows/pages.yml.
5. Point README demo links at the Pages URL.
6. Filter Docusaurus-only paths from both npm and runtime bundle packaging, and keep the two exclusion contracts under test.
7. Publish the demo report through a directory route that works in Docusaurus production preview and GitHub Pages.
8. Verify: website build, browser routes, root npm test, staged-only npm pack, and npm run pack:verify.

Risks

• Packaging boundary drift can silently ship docs/node_modules, build output, or the site lockfile in the Qoder runtime ZIP even when npm packaging is clean. Mitigation: filter at bundle collection time and independently reject the same prefixes in pack:verify.
• Static .html links are handled differently by Docusaurus production preview and GitHub Pages. Mitigation: use one directory-index URL and exercise it with Playwright against npm run serve.
• The website and root integration span staged and unstaged files. Mitigation: run the final readiness check against the staged snapshot before commit; do not infer readiness from the working-tree test result.

Test / Review Evidence

• DSDP-AC-3/7: cd docs && npm ci && npm run build — must succeed for both locales with zero broken links (onBrokenLinks: 'throw').
• DSDP-AC-4/8: npm run pack:verify — npm and runtime ZIP exclusions must pass; inspect the reported runtime entry count for unexpected growth.
• DSDP-AC-9: start npm run serve, then use Playwright to open English, zh-Hans, docs, and demo routes; retain console/page errors and a screenshot.
• DSDP-AC-4/10: materialize the Git index into a temporary directory and run npm pack --dry-run --json --ignore-scripts; no site machinery may appear.
• DSDP-AC-4/8: npm test at the repository root, including focused runtime bundle boundary coverage.
• Observed 2026-07-29: the two-locale Docusaurus build completed with zero broken links; Playwright received 200 responses for English, zh-Hans, docs, and demo routes with zero console/page errors; npm test passed 860/860; npm run pack:verify passed with 305 npm entries and 332 runtime ZIP entries; and the staged-only npm dry run contained 305 files with zero Docusaurus site machinery entries.
• Post-merge manual steps: Settings → Pages → source "GitHub Actions"; set the repository About website field to the Pages URL; verify the deployed URL in a browser.