site/ — Starlight wiki builder #

Type: knowledge

Astro + Starlight project that renders the wiki design corpus (plus the root DESIGN.md doorway for legacy links) as the public Misaligned documentation site for Tangled Sites.

The site root (src/pages/index.astro) is a game-first one-page splash: hero mood, pitch, what you do, why the systems are cool, and a primary CTA to the corpus. Its copy is sourced from wiki/vision/premise.md, wiki/art/visual-identity.md, and wiki/process/living-spec.md. Root DESIGN.md still syncs to the legacy /constitution/ route, but the wiki is the source and the primary destination.

The sync converts each source Type: line into a visible authority banner: LAW, SPEC, KNOWLEDGE, or LOG with a plain-language meaning. Logs explicitly say they are historical, and /constitution/ is labeled NAVIGATION with no design authority. A missing or duplicate supported Type line fails the sync.

Provenance #

Every site asset/page must have a source clause, per wiki/process/living-spec.md's "No unsourced surface" law.

• src/pages/index.astro — public splash, justified by wiki/vision/premise.md, wiki/art/visual-identity.md, and wiki/interface/site.md.
• ../assets/reference/art-direction/homepage-front-2026-07-10.png — Cameron's selected generated homepage master, retained byte-for-byte with its C2PA provenance.
• public/homepage-front-wide.webp and public/homepage-front-mobile.webp — optimized delivery exports from that master, justified by wiki/art/visual-identity.md and wiki/interface/site.md. The mobile export uses a deliberate square crop rather than leaving the browser to improvise.
• public/favicon.svg — browser/site identity affordance for the public documentation site, justified by wiki/interface/site.md and the Starlight public-site workflow in wiki/process/workflows.md.
• Generated src/content/docs/, src/content/assets/, src/generated/, and dist/ — outputs of scripts/sync-wiki.mjs / Astro, justified by wiki/process/wiki.md and wiki/process/workflows.md; never hand-edit them. Sync rewrites corpus-internal markdown links under SITE_BASE (production default /misaligned) so public routes match Tangled sub-path hosting.

Commands #

From the repo root:

pnpm --dir site sync     # wiki → src/content/docs + sidebar
pnpm --dir site dev      # local preview (SITE_BASE=/)
./tools/site-build.sh    # production build (base=/misaligned)
./tools/site-deploy.sh   # build, no-op if unchanged, else force-push orphan `pages` branch
./tools/site-smoke.sh    # require the public edge to name this exact source revision

Production builds embed the full source commit in the splash as misaligned-source-revision metadata. tools/task.sh finish publishes the exact landed main revision after its main-branch push. Direct/manual landings must run site-deploy.sh themselves from a clean committed tree; deploy refuses dirty source. Use site-smoke.sh after edge propagation to distinguish a current public page from a merely successful branch push.

Generated paths (src/content/docs/, src/content/assets/, src/generated/, dist/) are gitignored. Do not hand-edit them.

See wiki/process/workflows.md for Tangled Sites configuration, automatic landing publication, and the deferred CI credential note.