diff --git a/CLAUDE.md b/CLAUDE.md
index 70d4baa60..5877ed343 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -115,7 +115,9 @@ pnpm build
pnpm preview
```
-Docs content lives in `docs/src/content/docs/` as `.md` and `.mdx` files organized by topic: `domain/`, `persistence/`, `application/`, `subscriptions/`, `read-models/`, `producers/`, `gateway/`, `diagnostics/`, and `infra/` (per-provider: esdb, postgres, mongodb, mssql, sqlite, kafka, rabbitmq, pubsub, elastic). MDX files can use Astro components. Mermaid diagrams are supported via `starlight-client-mermaid` plugin. Versioned docs (0.15) are managed by the `starlight-versions` plugin in `docs/src/content/docs/0.15/`. Sidebar is configured in `astro.config.mjs`. Frontmatter uses Starlight format (`sidebar.order` for ordering, not `sidebar_position`).
+Docs content lives in `docs/src/content/docs/` as `.md` and `.mdx` files organized by topic: `domain/`, `persistence/`, `application/`, `subscriptions/`, `read-models/`, `producers/`, `gateway/`, `diagnostics/`, and `infra/` (per-provider: esdb, postgres, mongodb, mssql, sqlite, kafka, rabbitmq, pubsub, azure-service-bus, elastic). MDX files can use Astro components. Mermaid diagrams are supported via `starlight-client-mermaid` plugin. Sidebar is auto-generated from directories in `astro.config.mjs`. Frontmatter uses Starlight format (`sidebar.order` for ordering, not `sidebar_position`).
+
+For detailed docs versioning and authoring rules, see `docs/DOCS_VERSIONING.md`.
## Code Style
diff --git a/docs/DOCS_VERSIONING.md b/docs/DOCS_VERSIONING.md
new file mode 100644
index 000000000..9259ac461
--- /dev/null
+++ b/docs/DOCS_VERSIONING.md
@@ -0,0 +1,82 @@
+# Docs Versioning & Authoring Guide
+
+This file is for Claude Code. It documents how the Eventuous docs site versioning works so docs can be updated correctly.
+
+## Version Structure
+
+Managed by the `starlight-versions` plugin in `astro.config.mjs`.
+
+```
+docs/src/content/docs/ ← "current" version (root, shown by default)
+docs/src/content/docs/0.15/ ← archived v0.15 snapshot
+docs/src/content/docs/next/ ← preview placeholder for future version
+docs/src/content/versions/ ← sidebar configs per version (JSON)
+```
+
+- **Root** (`docs/src/content/docs/`) is always the current stable version.
+- **Archived versions** (e.g. `0.15/`) are read-only snapshots. Don't edit unless fixing a bug in old docs.
+- **`next/`** is a minimal placeholder. When preparing a new release, content accumulates here, then gets promoted to root.
+
+## Config in astro.config.mjs
+
+```js
+starlightVersions({
+ current: { label: 'v0.16 (Stable)' },
+ versions: [
+ { slug: '0.15', label: 'v0.15' },
+ { slug: 'next', label: 'Preview' },
+ ],
+}),
+```
+
+Each entry in `versions` must have a matching directory under `docs/src/content/docs/{slug}/` and a sidebar config at `docs/src/content/versions/{slug}.json`.
+
+## Relative Path Rules
+
+Component imports and markdown links use different base paths. Getting these wrong breaks the build.
+
+### Component imports (filesystem-relative)
+
+From `docs/src/content/docs/` to `docs/src/components/`:
+
+| File location | Import path |
+|---|---|
+| Root subdirectory (e.g. `subscriptions/checkpoint.mdx`) | `../../../components/Foo.astro` (3 levels) |
+| Versioned subdirectory (e.g. `0.15/subscriptions/checkpoint.mdx`) | `../../../../components/Foo.astro` (4 levels) |
+
+### Markdown links (doc-tree-relative)
+
+Internal doc links resolve within the doc tree, not the filesystem:
+
+| File location | Link to another section |
+|---|---|
+| Root subdirectory (e.g. `infra/esdb.md`) | `../../application/app-service` (2 levels) |
+| `next/` subdirectory (e.g. `next/infra/esdb.md`) | `../../../application/app-service` (3 levels) |
+
+### Hero image (index.mdx)
+
+| File location | Image path to `src/assets/logo.png` |
+|---|---|
+| Root `index.mdx` | `../../assets/logo.png` |
+| `0.15/index.mdx` | `../../../assets/logo.png` |
+
+## How to Release a New Version
+
+To promote `next/` to a new stable version (e.g. v0.17):
+
+1. **Archive current root** → copy root content (excluding `next/` and version dirs) into a new directory (e.g. `0.16/`). Create a matching `src/content/versions/0.16.json` sidebar config (copy from `next.json` template).
+2. **Replace root with `next/`** → delete root content files, copy `next/` to root.
+3. **Fix relative paths** → reduce all `../` depths by 1 in the new root files (component imports: 4→3, markdown links: 3→2, hero image: 3→2).
+4. **Fix archived version paths** → increase all `../` depths by 1 in the archived directory (component imports: 3→4).
+5. **Update `astro.config.mjs`** → change `current.label`, add archived version to `versions` array.
+6. **Reset `next/`** → delete all content, create a single `whats-new.mdx` placeholder. Update `next.json` sidebar to only reference `whats-new`.
+7. **Build and verify** → `pnpm build` must pass. Check page count and spot-check version selector.
+
+> **Do not** rely on the plugin's auto-snapshot feature (`ensureNewVersion`). It fails on MDX files with complex Astro expressions. Always snapshot manually.
+
+## Adding New Doc Pages
+
+- Add `.md` or `.mdx` files to the appropriate topic directory under root docs.
+- The sidebar auto-generates from directory contents. Use `sidebar.order` in frontmatter to control ordering.
+- For new infrastructure providers, add to `infra/` with a descriptive filename (e.g. `azure-service-bus.md`).
+- If adding pages to `next/` for a future version, remember that all relative paths need one extra `../` compared to root.
diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs
index 3ff708870..b249b2fb6 100644
--- a/docs/astro.config.mjs
+++ b/docs/astro.config.mjs
@@ -18,8 +18,11 @@ export default defineConfig({
customCss: ['./src/styles/custom.css'],
plugins: [
starlightVersions({
- current: { label: 'v0.15 (Stable)' },
- versions: [{ slug: 'next', label: 'Preview' }],
+ current: { label: 'v0.16 (Stable)' },
+ versions: [
+ { slug: '0.15', label: 'v0.15' },
+ { slug: 'next', label: 'Preview' },
+ ],
}),
starlightMermaid(),
],
diff --git a/docs/src/components/ThemedImage.astro b/docs/src/components/ThemedImage.astro
index 74244d241..a36c7c7d3 100644
--- a/docs/src/components/ThemedImage.astro
+++ b/docs/src/components/ThemedImage.astro
@@ -1,16 +1,19 @@
---
+import { Image } from 'astro:assets';
+import type { ImageMetadata } from 'astro';
+
interface Props {
alt: string;
- lightSrc: string;
- darkSrc: string;
+ lightSrc: ImageMetadata;
+ darkSrc: ImageMetadata;
}
const { alt, lightSrc, darkSrc } = Astro.props;
---
-
-
+
+