docs-site

Version	2026.215.1207
Repo	superproject

The Astro + Starlight toolchain for the opencharly.ai documentation site, plus a production build of the published site itself, built inside the box.

This candy is what makes the docs site provable rather than merely deployable: it clones the opencharly/docs repository, runs a clean npm ci against its committed lockfile, and builds the production site into /srv/docs/dist. A build failure — a bad frontmatter scalar, a Starlight config a version bump invalidated, a page whose markdown will not parse — fails the IMAGE BUILD, which builds from the same input Cloudflare Pages does, so the box catches it before a deploy can.

WHY IT CLONES rather than copying the docs/ submodule out of the working tree: a candy’s copy: source may not traverse above its own directory (.. is rejected at validate time), and there is no schema field for pointing a candy at a sibling directory. Cloning the published repository is the schema-legal path, and it happens to test the more useful thing — the exact source Cloudflare builds. The consequence is an ordering dependency: this candy builds against the docs repo’s main, so docs content must land there before this box (and the check-docs bed above it) go green.

The checks below assert the site’s SHAPE, not merely its existence: a generated CLI page, a candy page carrying its published acceptance plan, a recipe card from the skill corpus with its cross-references rewritten into site links, and — the load-bearing one — the page of a plugin that is NOT compiled into the charly binary, rendering both its runtime placement and its CUE parameter schema. That last check is what fails if the generator ever narrows to documenting only the default-active set.

Acceptance plan

This candy’s plan: — the runnable spec charly check executes against a live deployment. check: steps are idempotent probes; run: steps change state.

Intent	Step
run	clone the published documentation site source
run	install the site’s node dependencies from the committed lockfile
run	build the production site
check	node is installed and reports a parseable major version
check	the production build produced the site entry point
check	the built site carries a GENERATED CLI reference page (proves the cli tree was emitted and rendered)
check	a generated candy page publishes its plan as a runnable acceptance spec (the ADE surface a reader can see without cloning anything)
check	a recipe card from the skill corpus rendered, with its harness cross-references rewritten into working site links
check	a RUNTIME (out-of-process) plugin’s page renders both its placement and its CUE parameter schema — the assertion that fails if the generator ever documents only what is compiled in
check	the provider cross-index resolves every reserved word to its owning plugin