Mastersam07 · Mastersam07 · Jul 17, 2026 · Jul 17, 2026 · Jul 17, 2026 · Jul 17, 2026
diff --git a/assets/brand/README.md b/assets/brand/README.md
@@ -10,7 +10,8 @@ of them, then re-render with `rsvg-convert` (see commands below).
 | `kaisel-icon.svg` | Master mark on the dark tile. Source of truth. |
 | `kaisel-icon-1024.png` | Hi-res square tile. Downscale for any avatar or icon slot. |
 | `kaisel-icon-rounded.svg/png` | App-icon tile with rounded corners. Avatars: X, Discord, Medium, pub.dev publisher. |
-| `kaisel-mark.svg/png` | Transparent mark. Package READMEs (core, lint, devtools); anywhere the background should show through. |
+| `kaisel-mark.svg/png` | Transparent mark for dark backgrounds. Package READMEs (core, lint, devtools); docs-site logo and hero (dark theme). |
+| `kaisel-mark-light.svg/png` | Transparent mark with a deepened ramp for white backgrounds. Docs-site logo and hero (light theme). |
 | `kaisel-logo-dark.svg/png` | Transparent lockup, white wordmark. README headers on dark backgrounds. |
 | `kaisel-logo-light.svg/png` | Transparent lockup, slate wordmark. README headers on light backgrounds. |
 | `kaisel-banner.png` | Lockup on the dark tile. dev.to covers, Medium headers, slides — wide slots that want a baked background. |

diff --git a/assets/brand/kaisel-mark-light.png b/assets/brand/kaisel-mark-light.png
diff --git a/assets/brand/kaisel-mark-light.svg b/assets/brand/kaisel-mark-light.svg
diff --git a/packages/kaisel/doc/migration/README.md b/packages/kaisel/doc/migration/README.md
@@ -14,9 +14,9 @@ your migration branch will actually look like.
 
 | Guide                                       | Best for                                              | Effort                  |
 | ------------------------------------------- | ----------------------------------------------------- | ----------------------- |
-| [`from-go-router.md`](from-go-router.md)    | Apps using `GoRouter` with string paths               | ~3–4 days, 30 screens   |
-| [`from-auto-route.md`](from-auto-route.md)  | Apps using `@AutoRouterConfig` with `build_runner`    | ~2 days, 30 screens     |
-| [`from-navigator.md`](from-navigator.md)    | Apps on Flutter's `Navigator` — imperative `push`, named routes, or the Router/Pages API (2.0) | ~2–4 days, 30 screens (less from named/2.0) |
+| [From go_router](from-go-router.md)    | Apps using `GoRouter` with string paths               | ~3–4 days, 30 screens   |
+| [From auto_route](from-auto-route.md)  | Apps using `@AutoRouterConfig` with `build_runner`    | ~2 days, 30 screens     |
+| [From Navigator](from-navigator.md)    | Apps on Flutter's `Navigator` — imperative `push`, named routes, or the Router/Pages API (2.0) | ~2–4 days, 30 screens (less from named/2.0) |
 
 ## Which guide is for you
 

diff --git a/packages/kaisel/pubspec.yaml b/packages/kaisel/pubspec.yaml
@@ -4,6 +4,7 @@ version: 1.0.0
 repository: https://github.com/Mastersam07/kaisel
 homepage: https://github.com/Mastersam07/kaisel
 issue_tracker: https://github.com/Mastersam07/kaisel/issues
+documentation: https://kaisel.dev
 topics:
   - router
   - navigation

diff --git a/packages/kaisel_core/pubspec.yaml b/packages/kaisel_core/pubspec.yaml
@@ -4,6 +4,7 @@ version: 1.0.0
 repository: https://github.com/Mastersam07/kaisel/tree/dev/packages/kaisel_core
 homepage: https://github.com/Mastersam07/kaisel/tree/dev/packages/kaisel_core
 issue_tracker: https://github.com/Mastersam07/kaisel/issues
+documentation: https://kaisel.dev
 resolution: workspace
 topics:
   - router

diff --git a/packages/kaisel_lint/pubspec.yaml b/packages/kaisel_lint/pubspec.yaml
@@ -4,6 +4,7 @@ version: 0.5.1
 repository: https://github.com/Mastersam07/kaisel/tree/dev/packages/kaisel_lint
 homepage: https://github.com/Mastersam07/kaisel/tree/dev/packages/kaisel_lint
 issue_tracker: https://github.com/Mastersam07/kaisel/issues
+documentation: https://kaisel.dev/tooling/lints/
 
 screenshots:
   - description: The kaisel mark

diff --git a/site/.gitignore b/site/.gitignore
@@ -0,0 +1,29 @@
+# build output
+dist/
+# generated types
+.astro/
+
+# dependencies
+node_modules/
+
+# logs
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+
+
+# environment variables
+.env
+.env.production
+
+# macOS-specific files
+.DS_Store
+
+# generated by scripts/sync-docs.mjs — canonical sources live in
+# skills/kaisel/, packages/kaisel/doc/migration/, and ROADMAP.md
+src/content/docs/guides/
+src/content/docs/migration/
+src/content/docs/roadmap.md
+src/content/docs/tooling/devtools.md
+src/content/docs/tooling/lints.md
diff --git a/site/.vscode/extensions.json b/site/.vscode/extensions.json
@@ -0,0 +1,4 @@
+{
+  "recommendations": ["astro-build.astro-vscode"],
+  "unwantedRecommendations": []
+}
diff --git a/site/.vscode/launch.json b/site/.vscode/launch.json
@@ -0,0 +1,11 @@
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "command": "./node_modules/.bin/astro dev",
+      "name": "Development server",
+      "request": "launch",
+      "type": "node-terminal"
+    }
+  ]
+}
diff --git a/site/AGENTS.md b/site/AGENTS.md
@@ -0,0 +1,27 @@
+# kaisel docs site
+
+## Development
+
+Always use the npm scripts, never `astro` directly — the `predev`/`prebuild`
+hooks run `scripts/sync-docs.mjs`, which pulls the canonical docs
+(`skills/kaisel/`, `packages/kaisel/doc/migration/`, `ROADMAP.md`) into
+`src/content/docs/`. Running Astro directly serves stale or missing content.
+
+```sh
+npm run dev      # sync + dev server at localhost:4321
+npm run build    # sync + production build + Pagefind search index
+npm run preview  # serve dist/ (search only works here, not in dev)
+npm run sync     # re-sync after editing canonical docs while dev is running
+```
+
+Never edit `src/content/docs/guides/`, `src/content/docs/migration/`, or
+`src/content/docs/roadmap.md` — they are gitignored, generated copies. Edit
+the canonical files instead.
+
+`npx astro check` / `npx astro add` are fine to call directly — they don't
+serve or build content.
+
+## Documentation
+
+Astro/Starlight docs: https://docs.astro.build and
+https://starlight.astro.build
diff --git a/site/CLAUDE.md b/site/CLAUDE.md
@@ -0,0 +1 @@
+AGENTS.md
diff --git a/site/README.md b/site/README.md
@@ -0,0 +1,49 @@
+# Starlight Starter Kit: Basics
+
+[![Built with Starlight](https://astro.badg.es/v2/built-with-starlight/tiny.svg)](https://starlight.astro.build)
+
+```
+npm create astro@latest -- --template starlight
+```
+
+> 🧑‍🚀 **Seasoned astronaut?** Delete this file. Have fun!
+
+## 🚀 Project Structure
+
+Inside of your Astro + Starlight project, you'll see the following folders and files:
+
+```
+.
+├── public/
+├── src/
+│   ├── assets/
+│   ├── content/
+│   │   └── docs/
+│   └── content.config.ts
+├── astro.config.mjs
+├── package.json
+└── tsconfig.json
+```
+
+Starlight looks for `.md` or `.mdx` files in the `src/content/docs/` directory. Each file is exposed as a route based on its file name.
+
+Images can be added to `src/assets/` and embedded in Markdown with a relative link.
+
+Static assets, like favicons, can be placed in the `public/` directory.
+
+## 🧞 Commands
+
+All commands are run from the root of the project, from a terminal:
+
+| Command                   | Action                                           |
+| :------------------------ | :----------------------------------------------- |
+| `npm install`             | Installs dependencies                            |
+| `npm run dev`             | Starts local dev server at `localhost:4321`      |
+| `npm run build`           | Build your production site to `./dist/`          |
+| `npm run preview`         | Preview your build locally, before deploying     |
+| `npm run astro ...`       | Run CLI commands like `astro add`, `astro check` |
+| `npm run astro -- --help` | Get help using the Astro CLI                     |
+
+## 👀 Want to learn more?
+
+Check out [Starlight’s docs](https://starlight.astro.build/), read [the Astro documentation](https://docs.astro.build), or jump into the [Astro Discord server](https://astro.build/chat).
diff --git a/site/astro.config.mjs b/site/astro.config.mjs
@@ -0,0 +1,124 @@
+// @ts-check
+import { readFileSync } from 'node:fs';
+import { defineConfig } from 'astro/config';
+import starlight from '@astrojs/starlight';
+import starlightLinksValidator from 'starlight-links-validator';
+
+// Set by the docs workflow for PR preview deploys (e.g. /pr-42). Previews
+// live under a subpath of the production origin and must not be indexed.
+const previewBase = process.env.SITE_BASE;
+
+const kaiselVersion = readFileSync(
+  new URL('../packages/kaisel/pubspec.yaml', import.meta.url),
+  'utf8',
+).match(/^version:\s*(\S+)/m)[1];
+
+export default defineConfig({
+  site: 'https://kaisel.dev',
+  base: previewBase ?? '/',
+  integrations: [
+    starlight({
+      plugins: previewBase ? [] : [starlightLinksValidator()],
+      title: 'kaisel',
+      description:
+        'A Dart 3-native router for Flutter — sealed routes, pattern matching, and a stack-as-value model. No string paths, no codegen.',
+      logo: {
+        dark: './src/assets/kaisel-mark.svg',
+        light: './src/assets/kaisel-mark-light.svg',
+        alt: 'kaisel',
+      },
+      social: [
+        {
+          icon: 'github',
+          label: 'GitHub',
+          href: 'https://github.com/Mastersam07/kaisel',
+        },
+        {
+          icon: 'seti:dart',
+          label: 'pub.dev',
+          href: 'https://pub.dev/packages/kaisel',
+        },
+      ],
+      editLink: {
+        baseUrl:
+          'https://github.com/Mastersam07/kaisel/edit/dev/site/src/content/docs/',
+      },
+      customCss: ['./src/styles/custom.css'],
+      head: [
+        ...(previewBase
+          ? [
+              {
+                tag: 'meta',
+                attrs: { name: 'robots', content: 'noindex, nofollow' },
+              },
+            ]
+          : []),
+        {
+          tag: 'style',
+          content: `:root { --kaisel-version: 'v${kaiselVersion}'; }`,
+        },
+        {
+          tag: 'meta',
+          attrs: { property: 'og:image', content: 'https://kaisel.dev/og.png' },
+        },
+        {
+          tag: 'meta',
+          attrs: { name: 'twitter:card', content: 'summary_large_image' },
+        },
+        {
+          tag: 'meta',
+          attrs: { name: 'twitter:image', content: 'https://kaisel.dev/og.png' },
+        },
+      ],
+      sidebar: [
+        { label: 'Start here', items: ['getting-started'] },
+        {
+          label: 'Guides',
+          items: [
+            { label: 'Navigation', slug: 'guides/navigation' },
+            { label: 'Shells & tabs', slug: 'guides/shells' },
+            { label: 'Modal flows', slug: 'guides/modal-flows' },
+            { label: 'Adaptive layouts', slug: 'guides/adaptive-layouts' },
+            { label: 'Guards', slug: 'guides/guards' },
+            { label: 'URLs & deep linking', slug: 'guides/urls-and-deep-linking' },
+            { label: 'Modules', slug: 'guides/modules' },
+            { label: 'Transitions', slug: 'guides/transitions' },
+          ],
+        },
+        {
+          label: 'Migration',
+          items: [
+            { label: 'Overview', slug: 'migration' },
+            { label: 'From go_router', slug: 'migration/from-go-router' },
+            { label: 'From auto_route', slug: 'migration/from-auto-route' },
+            { label: 'From Navigator', slug: 'migration/from-navigator' },
+          ],
+        },
+        {
+          label: 'Tooling',
+          items: [
+            { label: 'DevTools extension', slug: 'tooling/devtools' },
+            { label: 'Lints', slug: 'tooling/lints' },
+            { label: 'AI & editor skills', slug: 'tooling/ai-skills' },
+          ],
+        },
+        {
+          label: 'Project',
+          items: [
+            { label: 'Roadmap', slug: 'roadmap' },
+            {
+              label: 'API reference',
+              link: 'https://pub.dev/documentation/kaisel/latest/',
+              attrs: { target: '_blank' },
+            },
+            {
+              label: 'Examples',
+              link: 'https://github.com/Mastersam07/kaisel/tree/dev/packages/kaisel/example',
+              attrs: { target: '_blank' },
+            },
+          ],
+        },
+      ],
+    }),
+  ],
+});