move docs

.githooks/pre-commit

@@ -26,6 +26,12 @@ echo "==> Building all packages (catches publish-time bundler regressions)..."
 bun run build
 bun run build:types
 
+# echo "==> Publish dry run ..."
+# bun run publish:dry
+
+echo "==> jsr.io dry run ..."
+bun run jsr:dry
+
 echo "==> Running unit tests..."
 # Bun sometimes segfaults during shutdown after a successful test run
 # (worker-thread cleanup race). Tolerate non-zero exit when the test

.github/workflows/docs.yml

@@ -3,7 +3,8 @@ on:
   push:
     branches: [main]
     paths:
-      - 'packages/docs/**'
+      - 'docs/**'
+      - 'packages/**'
   workflow_dispatch:
 
 permissions:
@@ -31,15 +32,18 @@ jobs:
 
       - name: Install dependencies
         run: bun install
-        working-directory: packages/docs
+
+      - name: Type-check
+        run: bun run check
+        working-directory: docs
 
       - name: Build
         run: bun run build
-        working-directory: packages/docs
+        working-directory: docs
 
       - uses: actions/upload-pages-artifact@v3
         with:
-          path: packages/docs/dist
+          path: docs/dist
 
   deploy:
     needs: build

CLAUDE.md

@@ -16,8 +16,8 @@ bun run build        # build all packages
 
 Docs site (Astro + Starlight):
 ```sh
-cd packages/docs && bun run dev      # local dev server
-cd packages/docs && bun run build    # production build
+cd docs && bun run dev      # local dev server
+cd docs && bun run build    # production build
 ```
 
 ## Monorepo structure
@@ -29,7 +29,7 @@ cd packages/docs && bun run build    # production build
 - `packages/store-turso` — Remote Turso/libSQL store
 - `packages/store-supabase` — Supabase store
 - `packages/store-postgres` — PostgreSQL/Neon store
-- `packages/docs` — Starlight documentation site
+- `docs/` — Starlight documentation site (at repo root, outside `packages/`)
 
 Dependency order: core → stores → plugins (CLI lives inside core)
 
@@ -64,7 +64,7 @@ Integration tests are guarded by `describe.skipIf(!process.env.INTEGRATION)`.
 - `ci.yml` — unit tests on push to main and all PRs
 - `integration.yml` — integration tests on push to main + manual trigger (Postgres via Docker, Turso in-memory, Supabase via secrets)
 - `flaky-check.yml` — scheduled detection (Monday 9am UTC) + manual trigger
-- `docs.yml` — deploys docs to GitHub Pages when `packages/docs/**` changes
+- `docs.yml` — deploys docs to GitHub Pages when `docs/**` changes
 - `release.yml` — changesets-driven npm publish + GitHub Release
 
 ## GitHub Action

docs/.gitignore

@@ -0,0 +1,2 @@
+# generated by starlight-typedoc
+src/content/docs/api/

packages/docs/astro.config.mjs → docs/astro.config.mjs

@@ -1,6 +1,12 @@
 import starlight from '@astrojs/starlight'
 import catppuccin from '@catppuccin/starlight'
 import { defineConfig } from 'astro/config'
+import starlightChangelogs, {
+  makeChangelogsSidebarLinks,
+} from 'starlight-changelogs'
+import starlightLinksValidator from 'starlight-links-validator'
+import starlightLlmsTxt from 'starlight-llms-txt'
+import starlightTypeDoc, { typeDocSidebarGroup } from 'starlight-typedoc'
 
 export default defineConfig({
   site: 'https://brewpirate.github.io',
@@ -10,15 +16,27 @@ export default defineConfig({
       title: 'flaky-tests',
       description:
         'Zero-friction flaky test detection for Bun and Vitest. Catches patterns, generates prompts, opens issues.',
+      favicon: '/favicon.svg',
+      lastUpdated: true,
       logo: {
-        src: './src/assets/mrflaky.png',
+        light: './src/assets/logo-light.svg',
+        dark: './src/assets/logo-dark.svg',
         replacesTitle: false,
       },
       plugins: [
         catppuccin({
           dark: { flavor: 'mocha', accent: 'red' },
           light: { flavor: 'latte', accent: 'red' },
         }),
+        starlightLinksValidator(),
+        starlightLlmsTxt(),
+        starlightTypeDoc({
+          entryPoints: ['../packages/core/src/index.ts'],
+          tsconfig: '../packages/core/tsconfig.json',
+          output: 'api',
+          sidebar: { label: 'API (generated)', collapsed: true },
+        }),
+        starlightChangelogs(),
       ],
       social: [
         {
@@ -28,8 +46,7 @@ export default defineConfig({
         },
       ],
       editLink: {
-        baseUrl:
-          'https://github.com/brewpirate/flaky-tests/edit/main/packages/docs/',
+        baseUrl: 'https://github.com/brewpirate/flaky-tests/edit/main/docs/',
       },
       sidebar: [
         {
@@ -40,6 +57,7 @@ export default defineConfig({
               label: 'What is a flaky test?',
               slug: 'getting-started/what-is-a-flaky-test',
             },
+            { label: 'Install', slug: 'getting-started/install' },
             { label: 'Quick Start', slug: 'getting-started/quick-start' },
           ],
         },
@@ -91,6 +109,48 @@ export default defineConfig({
             },
           ],
         },
+        typeDocSidebarGroup,
+        {
+          label: 'Changelogs',
+          collapsed: true,
+          items: makeChangelogsSidebarLinks([
+            {
+              type: 'recent',
+              base: 'changelog/core',
+              label: '@flaky-tests/core',
+            },
+            {
+              type: 'recent',
+              base: 'changelog/plugin-bun',
+              label: '@flaky-tests/plugin-bun',
+            },
+            {
+              type: 'recent',
+              base: 'changelog/plugin-vitest',
+              label: '@flaky-tests/plugin-vitest',
+            },
+            {
+              type: 'recent',
+              base: 'changelog/store-sqlite',
+              label: '@flaky-tests/store-sqlite',
+            },
+            {
+              type: 'recent',
+              base: 'changelog/store-turso',
+              label: '@flaky-tests/store-turso',
+            },
+            {
+              type: 'recent',
+              base: 'changelog/store-supabase',
+              label: '@flaky-tests/store-supabase',
+            },
+            {
+              type: 'recent',
+              base: 'changelog/store-postgres',
+              label: '@flaky-tests/store-postgres',
+            },
+          ]),
+        },
       ],
     }),
   ],

packages/docs/package.json → docs/package.json

@@ -6,6 +6,7 @@
   "scripts": {
     "dev": "astro dev",
     "build": "astro build",
+    "check": "astro check",
     "preview": "astro preview"
   },
   "dependencies": {
@@ -15,6 +16,14 @@
     "sharp": "^0.33.0"
   },
   "devDependencies": {
-    "starlight-package-managers": "^0.12.0"
+    "@astrojs/check": "^0.9.8",
+    "starlight-changelogs": "^0.5.0",
+    "starlight-links-validator": "^0.23.0",
+    "starlight-llms-txt": "^0.8.1",
+    "starlight-package-managers": "^0.12.0",
+    "starlight-typedoc": "^0.21.5",
+    "typedoc": "^0.28.19",
+    "typedoc-plugin-markdown": "^4.11.0",
+    "typescript": "^6.0.3"
   }
 }

docs/src/content.config.ts

@@ -0,0 +1,47 @@
+import { defineCollection } from 'astro:content'
+import { docsLoader } from '@astrojs/starlight/loaders'
+import { docsSchema } from '@astrojs/starlight/schema'
+import { changelogsLoader } from 'starlight-changelogs/loader'
+
+export const collections = {
+  docs: defineCollection({ loader: docsLoader(), schema: docsSchema() }),
+  changelogs: defineCollection({
+    loader: changelogsLoader([
+      {
+        provider: 'changeset',
+        base: 'changelog/core',
+        changelog: '../packages/core/CHANGELOG.md',
+      },
+      {
+        provider: 'changeset',
+        base: 'changelog/plugin-bun',
+        changelog: '../packages/plugin-bun/CHANGELOG.md',
+      },
+      {
+        provider: 'changeset',
+        base: 'changelog/plugin-vitest',
+        changelog: '../packages/plugin-vitest/CHANGELOG.md',
+      },
+      {
+        provider: 'changeset',
+        base: 'changelog/store-sqlite',
+        changelog: '../packages/store-sqlite/CHANGELOG.md',
+      },
+      {
+        provider: 'changeset',
+        base: 'changelog/store-turso',
+        changelog: '../packages/store-turso/CHANGELOG.md',
+      },
+      {
+        provider: 'changeset',
+        base: 'changelog/store-supabase',
+        changelog: '../packages/store-supabase/CHANGELOG.md',
+      },
+      {
+        provider: 'changeset',
+        base: 'changelog/store-postgres',
+        changelog: '../packages/store-postgres/CHANGELOG.md',
+      },
+    ]),
+  }),
+}