Add documentation website that dogfoods all Sailkit packages

.gitignore

@@ -1,11 +1,6 @@
-# Dependencies
-node_modules/
-
-# Build output
-dist/
-
-# Lock files (using npm)
-package-lock.json
-
-# OS files
-.DS_Store
+.astro
+test-results
+node_modules
+dist
+playwright-report
+.turbo

README.md

@@ -1,4 +1,4 @@
-# Sailkit
+# Bearing
 
 Lightweight, composable utilities for documentation sites.
 

VERIFICATION.md

@@ -0,0 +1,104 @@
+# Manual Verification Guide
+
+## Overview
+
+The sailkit project is a monorepo containing:
+- **6 library packages** (compass, teleport, lantern, atlas, lighthouse, scribe)
+- **1 documentation site** (`docs/`) that dogfoods the libraries
+
+Before merging, verify:
+1. Libraries build correctly
+2. Documentation site builds
+3. Code samples in docs are valid
+4. Interactive features work
+
+---
+
+## Part 1: Library Packages
+
+**What you're checking:** Each library compiles and TypeScript types are correct.
+
+```bash
+# Build all packages
+npm run build --workspaces
+```
+
+**Success:** No errors, each package creates `dist/index.js` and `dist/index.d.ts`.
+
+---
+
+## Part 2: Documentation Site
+
+### 2a. Static Build
+
+**What you're checking:** Astro resolves all imports and generates static pages.
+
+```bash
+cd docs
+npm run build
+```
+
+**Success:** `20 page(s) built`, no errors.
+
+### 2b. Code Sample Validation
+
+**What you're checking:** Code blocks in documentation actually execute.
+
+```bash
+node packages/scribe/dist/cli.js docs/src/content/docs/
+```
+
+**Success:** `Results: 10/10 passed`
+
+### 2c. Interactive Testing
+
+**What you're checking:** Runtime JavaScript features work.
+
+```bash
+cd docs
+npm run dev
+# Visit http://localhost:4321
+```
+
+| Test | How to verify |
+|------|---------------|
+| Theme toggle | Click sun/moon icon, theme switches, persists on reload |
+| j/k navigation | Press `j`/`k` to move through sidebar, highlight moves |
+| Enter to navigate | Highlight item with j/k, press Enter, navigates |
+| Magic links | Visit `/docs/atlas/`, `[[installation]]` links work |
+| Home page nav | On `/`, press j/k to cycle through cards |
+| 404 suggestions | Visit `/docs/compas/` (typo), suggests `/docs/compass/` |
+
+---
+
+## Part 3: Package Naming
+
+**What you're checking:** All references use `@sailkit-dev/*`.
+
+```bash
+grep -r "@sailkit/" --include="*.json" --include="*.ts" --include="*.js" --include="*.mjs" --include="*.astro" --include="*.md" . | grep -v node_modules | grep -v ".git"
+```
+
+**Success:** No output.
+
+---
+
+## Part 4: Git State
+
+```bash
+git status                              # Clean working tree
+git log --oneline origin/docs-website..HEAD  # Nothing (fully pushed)
+```
+
+---
+
+## Summary Checklist
+
+| Step | Command | Expected |
+|------|---------|----------|
+| Build packages | `npm run build --workspaces` | No errors |
+| Build docs | `cd docs && npm run build` | 20 pages built |
+| Validate samples | `node packages/scribe/dist/cli.js docs/src/content/docs/` | 10/10 passed |
+| Check naming | `grep -r "@sailkit/" ...` | No matches |
+| Git clean | `git status` | Clean |
+| Browser test | `cd docs && npm run dev` | Features work |

docs/.gitignore

@@ -0,0 +1,24 @@
+# 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
+
+# jetbrains setting folder
+.idea/

docs/.vscode/extensions.json

@@ -0,0 +1,4 @@
+{
+  "recommendations": ["astro-build.astro-vscode"],
+  "unwantedRecommendations": []
+}

docs/.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"
+    }
+  ]
+}

docs/README.md

@@ -0,0 +1,43 @@
+# Astro Starter Kit: Minimal
+
+```sh
+npm create astro@latest -- --template minimal
+```
+
+> 🧑‍🚀 **Seasoned astronaut?** Delete this file. Have fun!
+
+## 🚀 Project Structure
+
+Inside of your Astro project, you'll see the following folders and files:
+
+```text
+/
+├── public/
+├── src/
+│   └── pages/
+│       └── index.astro
+└── package.json
+```
+
+Astro looks for `.astro` or `.md` files in the `src/pages/` directory. Each page is exposed as a route based on its file name.
+
+There's nothing special about `src/components/`, but that's where we like to put any Astro/React/Vue/Svelte/Preact components.
+
+Any static assets, like images, 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?
+
+Feel free to check [our documentation](https://docs.astro.build) or jump into our [Discord server](https://astro.build/chat).

docs/astro.config.mjs

@@ -0,0 +1,15 @@
+// @ts-check
+import { defineConfig } from 'astro/config';
+import { remarkMagicLinks } from '@sailkit-dev/atlas';
+
+// https://astro.build/config
+export default defineConfig({
+  markdown: {
+    remarkPlugins: [
+      [remarkMagicLinks, {
+        urlBuilder: (id) => `/docs/${id}/`,
+        syntax: 'wiki',
+      }],
+    ],
+  },
+});

docs/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "docs",
+  "type": "module",
+  "version": "0.0.1",
+  "scripts": {
+    "dev": "astro dev",
+    "build": "astro build",
+    "preview": "astro preview",
+    "astro": "astro"
+  },
+  "dependencies": {
+    "astro": "^5.16.5",
+    "@sailkit-dev/compass": "*",
+    "@sailkit-dev/teleport": "*",
+    "@sailkit-dev/lantern": "*",
+    "@sailkit-dev/lighthouse": "*",
+    "@sailkit-dev/atlas": "*"
+  }
+}

docs/src/components/PrevNext.astro

@@ -0,0 +1,110 @@
+---
+import { getTitle } from '../navigation';
+
+interface Props {
+  prev: string | null;
+  next: string | null;
+}
+
+const { prev, next } = Astro.props;
+---
+
+{(prev || next) && (
+  <nav class="prev-next" aria-label="Page navigation">
+    {prev ? (
+      <a href={`/docs/${prev}/`} class="prev-next-link prev">
+        <span class="prev-next-label">Previous</span>
+        <span class="prev-next-title">{getTitle(prev)}</span>
+        <span class="prev-next-hint">
+          <kbd>h</kbd>
+        </span>
+      </a>
+    ) : (
+      <div></div>
+    )}
+    {next ? (
+      <a href={`/docs/${next}/`} class="prev-next-link next">
+        <span class="prev-next-label">Next</span>
+        <span class="prev-next-title">{getTitle(next)}</span>
+        <span class="prev-next-hint">
+          <kbd>l</kbd>
+        </span>
+      </a>
+    ) : (
+      <div></div>
+    )}
+  </nav>
+)}
+
+<style>
+  .prev-next {
+    display: grid;
+    grid-template-columns: 1fr 1fr;
+    gap: 1.5rem;
+    margin-top: 3rem;
+    padding-top: 2rem;
+    border-top: 1px solid var(--color-border);
+  }
+
+  .prev-next-link {
+    display: flex;
+    flex-direction: column;
+    gap: 0.25rem;
+    padding: 1rem;
+    border: 1px solid var(--color-border);
+    border-radius: 8px;
+    text-decoration: none;
+    transition: border-color 0.15s, background-color 0.15s;
+    position: relative;
+  }
+
+  .prev-next-link:hover {
+    border-color: var(--color-accent);
+    background: var(--color-accent-dim);
+  }
+
+  .prev-next-link.next {
+    text-align: right;
+  }
+
+  .prev-next-label {
+    font-size: 0.75rem;
+    color: var(--color-text-muted);
+    text-transform: uppercase;
+    letter-spacing: 0.05em;
+  }
+
+  .prev-next-title {
+    font-weight: 500;
+    color: var(--color-accent);
+  }
+
+  .prev-next-hint {
+    position: absolute;
+    top: 0.75rem;
+    color: var(--color-text-muted);
+    font-size: 0.75rem;
+  }
+
+  .prev:hover .prev-next-hint,
+  .next:hover .prev-next-hint {
+    color: var(--color-accent);
+  }
+
+  .prev .prev-next-hint {
+    right: 0.75rem;
+  }
+
+  .next .prev-next-hint {
+    left: 0.75rem;
+  }
+
+  .prev-next-hint kbd {
+    padding: 0.125rem 0.375rem;
+    background: var(--color-code-bg);
+    border: 1px solid var(--color-border);
+    border-radius: 4px;
+    font-family: ui-monospace, monospace;
+    font-size: 0.625rem;
+  }
+</style>