Docs site — coordination issue

[Mastersam07]

This issue is the coordination point for docs site: what exists, what the constraints are, and what's up for discussion.

The good news: the docs are already written

This is a structuring job, not a writing job. The content, all markdown:

Source	Becomes
skills/kaisel/NAVIGATION.md	Core guide: routes, push/pop, typed results
skills/kaisel/SHELLS.md	Tab shells & nested stacks
skills/kaisel/MODAL_FLOWS.md	Modal flows (run<T>)
skills/kaisel/ADAPTIVE.md	Adaptive layouts (master-detail, panes, foldables)
skills/kaisel/GUARDS.md	Guards
skills/kaisel/CODEC.md	URLs & deep linking
skills/kaisel/MODULES.md	Modules & code-splitting
skills/kaisel/TRANSITIONS.md	Custom transitions & predictive back
packages/kaisel/doc/migration/from-go-router.md	Migration: go_router
packages/kaisel/doc/migration/from-auto-route.md	Migration: auto_route
packages/kaisel/doc/migration/from-navigator.md	Migration: Navigator 1.0
packages/kaisel/example/README.md	Cookbook index (15 runnable examples)
ROADMAP.md	Roadmap page
packages/kaisel/README.md	Mine for the landing page + getting started

API reference stays on pub.dev (dartdoc) — the site should link out, not duplicate it.

Constraints (the load-bearing ones)

1. Single source of truth. The site must consume the markdown above — moved or build-step-copied with frontmatter injected — never hand-forked. A second copy of any guide is how docs rot. If files need to move to make this clean, that's on the table; propose it here first.
2. Site lives in this monorepo (suggest site/), so content fixes and site changes travel in one PR. The site build must not join the pub workspace (add to workspace:-exclusions like kaisel_lint) and must not affect package archives.
3. Migration guides get top billing. They're the adoption funnel — a go_router or autoroute user deciding if switching hurts should hit them from the landing page in one click.

Freedoms (genuinely your call)

• Technology — markdown-driven, built-in search, dark/light. If you'd rather argue for anything(e.g. Astro, docs.page), make the case here.
• Information architecture, landing page design, sidebar order, MDX interactive bits — yours.
• Deploy: GitHub Pages via Actions is the default; if you prefer Vercel/Netlify/Cloudflare, say so.

Brand kit

Everything is in assets/brand/ (see its README): transparent mark, light/dark logo lockups, social card, and the palette — background #060A14, teal ramp #0E7490 → #22D3EE → #A5F3FC. Dark-first design matches the brand, but both themes should work.

Suggested path

1. Comment here with a rough IA sketch (sidebar tree) — cheap to agree on before any code.
2. PR 1: Scaffold in site/ + CI deploy to GitHub Pages, landing page + one guide wired up.
3. PR 2+: remaining sections, one or few per PR — small PRs review fast.

And please note every place the docs confused you as a newcomer — those observations are worth as much as the site itself. File them as separate issues or drop them here.