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.
• public/misaligned-cartoon.png — hero atmosphere for the splash, justified by wiki/art/visual-identity.md and "Public-page scope", plus wiki/interface/site.md's reference composition. If the hero stops using it, delete it.
• 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 + force-push orphan `pages` branch

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 and the deferred CI deploy note.