docs(site): build a first-class learning product - #554
Merged
Conversation
Keep the public release route, governing skill, version surfaces, and changelog-footer policy consistent across all four plugin targets. CHANGELOG: Correct the release command and skill contracts for target selection and required changelog footers.
Turn the documentation into a source-aware curriculum and product-quality reference so a new operator can progress from installation to governed power-user workflows with verifiable evidence. Replace simulated splash content with a rendered replay of a direct shipped-hook invocation, add a custom visual system, and make host availability and generated references derive from shipped source.
Move the target-aware release documentation into core/surface and regenerate Claude, Codex, and Pi host files so hosted parity checks cannot overwrite or reject the reviewed contract. Restore the required Feature Forge preview disclosure on the product splash. CHANGELOG: Keep the target-aware release command synchronized across every generated governance host.
Remove the lone prose-separator dash from the learning capstone so the site voice check passes on the hosted Linux generator job.
Allow source renderers to accept an explicit source ref in tests while preserving the production default from GITHUB_SHA. This keeps exact-revision links and makes detached CI runs deterministic.
Advance ca-codex to 0.3.5 and ca-pi to 0.1.41, regenerate Pi root package metadata, and record the canonical release-surface synchronization in both host changelogs.
Reframe the documentation as a novice-to-power-user product, upgrade the shared visual system and generated references, and align the README with the same source-backed learning path. CHANGELOG: Rebuilds the documentation and README into a branded, source-backed learning path from first install to power-user operation.
SUaDtL
changed the title
SUaDtL
marked this pull request as ready for review
July 30, 2026 21:32
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.
Summary
maininto the worktree branch and removes unrelated release/version drift from this documentation-only changeThis PR intentionally remains draft/WIP. It must not be merged accidentally.
Evidence
docs/reports/docs-site/page-audit.mdVerification on
da167389f11f12a9ac200ae5b2f17ecfbb7df339npm test— 47 files, 492 tests passednpm run typecheck— passednpm run coverage— passednpm run build— passed; 134 pages built and Pagefind indexed 140 HTML filesnpm run link-audit— 20,057 internal links across 140 pages resolve; favicon and hashed logo presentnpm run audit:diagrams— passedpython tools/sync-core.py --check— 53 core files across 3 plugins are byte-identicalpython tools/build-surface.py --check— Claude, Codex, and Pi generated surfaces are in syncnpm run gen:readme-heroplus diff check — deterministic and cleangit diff --check— passedDesign decision
SMARTS selected a hybrid visual system: rendered atmosphere for distinction, editable SVG for diagrams and the exact brand mark, and real captured product behavior for training evidence. This keeps the site memorable without making operational claims it cannot prove.