feat(site): docs site polish — bespoke landing, Feature Forge, anti-slop copy#122
Merged
Conversation
The #94 --farm artifact built a working docs site but it read as a scaffold: stock Starlight chrome, four generic cards, and a landing that printed `/ca:sprint --farm` while explaining neither --farm nor the Feature Forge anywhere on the site. This polish pass makes the site earn a first-time visitor's understanding within one screen: - A bespoke landing with a CSS-only animated gate-catch terminal that shows a gate blocking a banned crypto primitive, then clearing — the actual conversion mechanic, not an assertion. Honors prefers-reduced-motion with a static full transcript; the transcript is real DOM text. - Feature Forge surfaced as the differentiator: a landing showcase, a Concepts section with the two-axis labelling model, and preview badges driven by a site-side generator allowlist (no plugins/ca change). --farm is now linked to its explanation. - Three hand-authored SVG diagrams (lane-flow, two-axis, gate model) and custom callouts across the inner pages. - Copy de-slopped: em-dashes cut from 7/16/10 to 0/0/0 in body prose, plus removal of templated phrasing and LLM-tell vocabulary. - Functional: logo/favicon/social wired, base-safe internal links, Pagefind verified in dist. Reviewed via multi-agent build with adversarial verify (visual design, link/base-path, copy anti-slop); 4 blocking findings caught and fixed. Crypto-compliance gate passed (demo transcript text, no operational crypto). Site suite green: typecheck clean, 104 tests, build 77 pages. CHANGELOG: Public docs site redesigned — bespoke landing with a live gate-catch demo, Feature Forge showcase + preview badges, and a copy anti-slop pass. Ref: .codearbiter/specs/docs-site-polish.md Claude-Session: https://claude.ai/code/session_016NVNTNAPKXzWD8bmmjVHP7
Persist the approved spec that drove the feat(site) docs overhaul and record the two follow-ups its build surfaced, so the out-of-scope work isn't lost: - Allowlist-drift reconciler: a CI/doctor check that the site-side Feature Forge preview allowlist matches real preview status. - Base-path img-href convention: unify the relative vs BASE_URL forms used for diagram/image sources across the site. Ref: .codearbiter/specs/docs-site-polish.md Claude-Session: https://claude.ai/code/session_016NVNTNAPKXzWD8bmmjVHP7
The PR coverage audit confirmed the build green but flagged two spec acceptance criteria the build delivered as content without the automated assertion the spec promised (AC-9 diagram titles, AC-13 Concepts forge section), plus an untested defensive path in forge-status. Record them so the spec's testability promise is honored rather than quietly dropped. Ref: .codearbiter/specs/docs-site-polish.md Claude-Session: https://claude.ai/code/session_016NVNTNAPKXzWD8bmmjVHP7
This was referenced Jun 22, 2026
Merged
SUaDtL
added a commit
that referenced
this pull request
Jun 22, 2026
* docs(changelog): roll up #118/#119/#120 into the 2.5.0 section The 2.5.0 section listed only #116/#117. Adds the task-board lifecycle + /ca:task feature (#118) under Added, and a Fixed group for the farm setup-doc dead-link (#119) and the crypto/secret gate hardening (#120), rolled from each commit's CHANGELOG footer. Dates the section to the release day. Project-state-only changes (.codearbiter/) stay out of the log per its stated scope. Claude-Session: https://claude.ai/code/session_016NVNTNAPKXzWD8bmmjVHP7 * feat(site): docs site polish — bespoke landing, Feature Forge, anti-slop copy (#122) * feat(site): bespoke landing, Feature Forge surfacing, anti-slop copy The #94 --farm artifact built a working docs site but it read as a scaffold: stock Starlight chrome, four generic cards, and a landing that printed `/ca:sprint --farm` while explaining neither --farm nor the Feature Forge anywhere on the site. This polish pass makes the site earn a first-time visitor's understanding within one screen: - A bespoke landing with a CSS-only animated gate-catch terminal that shows a gate blocking a banned crypto primitive, then clearing — the actual conversion mechanic, not an assertion. Honors prefers-reduced-motion with a static full transcript; the transcript is real DOM text. - Feature Forge surfaced as the differentiator: a landing showcase, a Concepts section with the two-axis labelling model, and preview badges driven by a site-side generator allowlist (no plugins/ca change). --farm is now linked to its explanation. - Three hand-authored SVG diagrams (lane-flow, two-axis, gate model) and custom callouts across the inner pages. - Copy de-slopped: em-dashes cut from 7/16/10 to 0/0/0 in body prose, plus removal of templated phrasing and LLM-tell vocabulary. - Functional: logo/favicon/social wired, base-safe internal links, Pagefind verified in dist. Reviewed via multi-agent build with adversarial verify (visual design, link/base-path, copy anti-slop); 4 blocking findings caught and fixed. Crypto-compliance gate passed (demo transcript text, no operational crypto). Site suite green: typecheck clean, 104 tests, build 77 pages. CHANGELOG: Public docs site redesigned — bespoke landing with a live gate-catch demo, Feature Forge showcase + preview badges, and a copy anti-slop pass. Ref: .codearbiter/specs/docs-site-polish.md Claude-Session: https://claude.ai/code/session_016NVNTNAPKXzWD8bmmjVHP7 * docs(governance): record docs-site-polish spec + harvest follow-ups Persist the approved spec that drove the feat(site) docs overhaul and record the two follow-ups its build surfaced, so the out-of-scope work isn't lost: - Allowlist-drift reconciler: a CI/doctor check that the site-side Feature Forge preview allowlist matches real preview status. - Base-path img-href convention: unify the relative vs BASE_URL forms used for diagram/image sources across the site. Ref: .codearbiter/specs/docs-site-polish.md Claude-Session: https://claude.ai/code/session_016NVNTNAPKXzWD8bmmjVHP7 * docs(governance): harvest coverage-auditor follow-ups for docs site The PR coverage audit confirmed the build green but flagged two spec acceptance criteria the build delivered as content without the automated assertion the spec promised (AC-9 diagram titles, AC-13 Concepts forge section), plus an untested defensive path in forge-status. Record them so the spec's testability promise is honored rather than quietly dropped. Ref: .codearbiter/specs/docs-site-polish.md Claude-Session: https://claude.ai/code/session_016NVNTNAPKXzWD8bmmjVHP7 --------- Co-authored-by: SUaDtL <SUaDtL@users.noreply.github.com> * fix(site): use Starlight 0.33+ array syntax for the social config (#124) CI's clean `npm ci` installs the pinned Starlight ^0.40.0, which rejects the legacy `social: { github: ... }` object form and fails the docs build at config:setup. The dev tree masked this: local node_modules held a stale Starlight 0.32.6 that still accepted the object form, so the local build passed while CI went red. Convert to the array-of-link-items syntax 0.33+ requires. Verified against a clean install (Starlight 0.40.0): build exits 0 (77 pages), typecheck clean, 104 tests pass. CHANGELOG: Docs site builds again on the pinned Starlight; the GitHub social link renders in the site header. Closes: docs deploy build failure on PR #123 Claude-Session: https://claude.ai/code/session_016NVNTNAPKXzWD8bmmjVHP7 Co-authored-by: SUaDtL <SUaDtL@users.noreply.github.com> --------- Co-authored-by: SUaDtL <SUaDtL@users.noreply.github.com>
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
1 participant
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.
What this does
Turns the docs site (built by the #94
--farmStep-6 run) from a working scaffold into a public-facing page that earns a first visitor's understanding. The landing now shows a gate catching a real mistake instead of asserting that gates exist, surfaces the Feature Forge as the differentiator, and reads in the project's own voice rather than as generated copy.Spec:
.codearbiter/specs/docs-site-polish.md(22 acceptance criteria). Build path: a multi-agent run with an adversarial verify pass. Scope issite/only; noplugins/ca/**file changed.Changes
prefers-reduced-motiondisables the animation and shows the full transcript statically./ca:sprint --farmline now links to its explanation.dist.Verification
npm run typecheck: clean.npm test: 104 passing (19 files), including new forge-badge and landing suites.npm run build: 77 pages, Pagefind indexed.auth-crypto-reviewer: PASS, 0 findings. The gate-catch demo text tripped the H-09b crypto gate; review confirmed it is teaching content, not operational crypto, and the gate pass is recorded.coverage-auditor: PASS, 0 CRITICAL/HIGH.Known follow-ups (tracked, non-blocking)
The coverage audit flagged two criteria the build shipped as content without the promised automated assertion (AC-9 diagram titles, AC-13 Concepts forge section) plus an untested defensive path in
forge-status, and a link-audit CI gate (AC-2/AC-4). All are on.codearbiter/open-tasks.md; none block this PR.Tradeoff note
Preview status lives in a site-side allowlist rather than plugin frontmatter, to hold the site-only boundary (conflict hierarchy: maintainability over a marginal single-source gain). The cost is that the allowlist can drift when a feature is promoted; a reconciler check is on the board.
Ref:
.codearbiter/specs/docs-site-polish.md