docs: add public site

.claude/commands/start.md

@@ -0,0 +1,21 @@
+# /start
+
+Start Tolaria in Tauri dev mode.
+
+## Steps
+
+1. Change to the Tolaria workspace:
+
+```bash
+cd /Users/luca/Workspace/tolaria
+```
+
+2. Start the native development app:
+
+```bash
+pnpm tauri dev
+```
+
+3. Keep the command running. Report the Vite local URL once it appears and leave the dev process alive for the user.
+
+This is a local utility command, not a Laputa task. Do not run `/laputa-next-task`, CodeScene gates, Todoist updates, commits, or pushes for this command unless the user asks separately.

.github/workflows/ci.yml

@@ -65,6 +65,9 @@ jobs:
       - name: Vite build check
         run: pnpm build
 
+      - name: Docs build check
+        run: pnpm docs:build
+
       # ── 1. Coverage-backed tests ──────────────────────────────────────────
       # The coverage commands run the same frontend and Rust test suites, so keep
       # them as the canonical test lane instead of running every suite twice.

.github/workflows/release-stable.yml

@@ -689,10 +689,10 @@ jobs:
             stable-latest.json
 
   # ─────────────────────────────────────────────────────────────
-  # Phase 4: Update GitHub Pages
+  # Phase 4: Update GitHub Pages with docs, release history, and download assets
   # ─────────────────────────────────────────────────────────────
   pages:
-    name: Update release history page
+    name: Update docs and release pages
     needs: [version, release]
     runs-on: ubuntu-latest
     permissions:
@@ -703,23 +703,39 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 10
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: 'pnpm'
+
       - name: Setup Bun
         uses: oven-sh/setup-bun@v2
         with:
           bun-version: latest
 
-      - name: Build release history page
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build docs and release pages
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: |
+          VITEPRESS_BASE="/${GITHUB_REPOSITORY#*/}/" pnpm docs:build
           mkdir -p _site/alpha _site/stable
+          cp -R site/.vitepress/dist/. _site/
           gh api -H "Accept: application/vnd.github.html+json" repos/${{ github.repository }}/releases --paginate > _site/releases.json
           PAGES_URL="https://refactoringhq.github.io/${GITHUB_REPOSITORY#*/}"
 
           curl -fsSL "${PAGES_URL}/alpha/latest.json" -o _site/alpha/latest.json || echo '{}' > _site/alpha/latest.json
           gh release download --repo ${{ github.repository }} "${{ needs.version.outputs.tag }}" --pattern "stable-latest.json" --output _site/stable/latest.json || echo '{}' > _site/stable/latest.json
           bun scripts/build-release-download-page.ts --latest-json _site/stable/latest.json --releases-json _site/releases.json --output-file _site/stable/download/index.html
-          bun scripts/build-release-history-page.ts --releases-json _site/releases.json --output-file _site/index.html
+          bun scripts/build-release-history-page.ts --releases-json _site/releases.json --output-file _site/releases/index.html
           mkdir -p _site/download
           cp _site/stable/download/index.html _site/download/index.html
 

.github/workflows/release.yml

@@ -740,10 +740,10 @@ jobs:
             alpha-latest.json
 
   # ─────────────────────────────────────────────────────────────
-  # Phase 4: Update GitHub Pages with release history
+  # Phase 4: Update GitHub Pages with docs, release history, and download assets
   # ─────────────────────────────────────────────────────────────
   pages:
-    name: Update release history page
+    name: Update docs and release pages
     needs: [version, release]
     runs-on: ubuntu-latest
     permissions:
@@ -754,23 +754,39 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 10
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: 'pnpm'
+
       - name: Setup Bun
         uses: oven-sh/setup-bun@v2
         with:
           bun-version: latest
 
-      - name: Build release history page
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build docs and release pages
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: |
+          VITEPRESS_BASE="/${GITHUB_REPOSITORY#*/}/" pnpm docs:build
           mkdir -p _site/alpha _site/stable
+          cp -R site/.vitepress/dist/. _site/
           gh api -H "Accept: application/vnd.github.html+json" repos/${{ github.repository }}/releases --paginate > _site/releases.json
           PAGES_URL="https://refactoringhq.github.io/${GITHUB_REPOSITORY#*/}"
 
           gh release download --repo ${{ github.repository }} "${{ needs.version.outputs.tag }}" --pattern "alpha-latest.json" --output _site/alpha/latest.json || echo '{}' > _site/alpha/latest.json
           curl -fsSL "${PAGES_URL}/stable/latest.json" -o _site/stable/latest.json || echo '{}' > _site/stable/latest.json
           bun scripts/build-release-download-page.ts --latest-json _site/stable/latest.json --releases-json _site/releases.json --output-file _site/stable/download/index.html
-          bun scripts/build-release-history-page.ts --releases-json _site/releases.json --output-file _site/index.html
+          bun scripts/build-release-history-page.ts --releases-json _site/releases.json --output-file _site/releases/index.html
           mkdir -p _site/download
           cp _site/stable/download/index.html _site/download/index.html
 

.gitignore

@@ -10,6 +10,9 @@ lerna-debug.log*
 node_modules
 dist
 dist-ssr
+site/.vitepress/cache/
+site/.vitepress/dist/
+_site/
 *.local
 
 # Editor directories and files

README.md

@@ -33,10 +33,12 @@ You can find some Loom walkthroughs below — they are short and to the point:
 
 ## Getting started
 
-Download the [latest release here](https://github.com/refactoringhq/tolaria/releases/latest/download/Tolaria.app.tar.gz).
+Download the [latest release here](https://refactoringhq.github.io/tolaria/download/).
 
 When you open Tolaria for the first time you get the chance of cloning the [getting started vault](https://github.com/refactoringhq/tolaria-getting-started) — which gives you a walkthrough of the whole app.
 
+The public user docs live in [`site/`](site/) and are intended for GitHub Pages. Start with [Install Tolaria](site/start/install.md), then [First Launch](site/start/first-launch.md).
+
 ## Open source and local setup
 
 Tolaria is open source and built with Tauri, React, and TypeScript. If you want to run or contribute to the app locally, here is [how to get started](https://github.com/refactoringhq/tolaria/blob/main/docs/GETTING-STARTED.md). You can also find the gist below 👇

docs/PUBLIC-DOCS-PLAN.md

@@ -0,0 +1,34 @@
+# Public Docs Plan
+
+This document records the phase 1 information architecture for public Tolaria documentation. The public docs source lives in `site/`; the existing `docs/` directory remains contributor, architecture, and agent context.
+
+## Audiences
+
+| Audience | Needs | Primary location |
+|---|---|---|
+| New users | Install, first launch, understand the app layout, clone the starter vault | `site/start/` |
+| Active users | Learn concrete workflows such as organizing, Git sync, custom views, and AI | `site/guides/` |
+| Power users | Understand file layout, frontmatter, filters, shortcuts, and platform support | `site/reference/` |
+| Contributors and agents | Architecture, abstractions, ADRs, development workflow | `docs/`, `AGENTS.md` |
+
+## Hosting Shape
+
+The GitHub Pages output should reserve the root for public docs and mount release assets underneath it:
+
+```text
+/                  public docs home
+/releases/         release history
+/download/         latest stable download redirect
+/stable/latest.json
+/alpha/latest.json
+/latest.json       compatibility alias for alpha latest
+/latest-canary.json compatibility alias for alpha latest
+```
+
+Every user-visible app change should answer:
+
+```text
+Public docs impact:
+- updated: <pages>
+- not needed because: <reason>
+```

package.json

@@ -8,6 +8,9 @@
     "dev": "vite",
     "build": "tsc -b && vite build",
     "bundle-mcp": "node scripts/bundle-mcp-server.mjs",
+    "docs:dev": "vitepress dev site --host 127.0.0.1",
+    "docs:build": "vitepress build site",
+    "docs:preview": "vitepress preview site --host 127.0.0.1",
     "lint": "eslint .",
     "l10n:translate": "lara-cli translate",
     "l10n:translate:force": "lara-cli translate --force",
@@ -99,6 +102,7 @@
     "typescript": "~5.9.3",
     "typescript-eslint": "^8.48.0",
     "vite": "^7.3.1",
+    "vitepress": "^1.6.4",
     "vitest": "^4.0.18",
     "ws": "^8.19.0"
   }

site/.vitepress/config.ts

@@ -0,0 +1,101 @@
+import { defineConfig } from "vitepress";
+
+const base = process.env.VITEPRESS_BASE ?? "/";
+
+export default defineConfig({
+  title: "Tolaria",
+  description:
+    "Tolaria is a local-first Markdown knowledge base with native relationships, Git history, and AI workflows.",
+  base,
+  cleanUrls: true,
+  head: [
+    ["link", { rel: "icon", type: "image/png", href: `${base}landing/favicon.png` }],
+    ["meta", { property: "og:title", content: "Tolaria" }],
+    [
+      "meta",
+      {
+        property: "og:description",
+        content:
+          "A second brain for the AI era. Free forever, local-first, Markdown-based, Git-ready, and AI-friendly.",
+      },
+    ],
+  ],
+  themeConfig: {
+    logo: { src: "/landing/tolaria-icon.png", alt: "Tolaria" },
+    nav: [
+      { text: "Features", link: "/#features" },
+      { text: "Start", link: "/start/install" },
+      { text: "Concepts", link: "/concepts/vaults" },
+      { text: "Guides", link: "/guides/capture-a-note" },
+      { text: "Reference", link: "/reference/supported-platforms" },
+      { text: "Releases", link: "/releases/" },
+    ],
+    search: {
+      provider: "local",
+    },
+    socialLinks: [{ icon: "github", link: "https://github.com/refactoringhq/tolaria" }],
+    sidebar: [
+      {
+        text: "Start Here",
+        items: [
+          { text: "Install Tolaria", link: "/start/install" },
+          { text: "First Launch", link: "/start/first-launch" },
+          { text: "Getting Started Vault", link: "/start/getting-started-vault" },
+          { text: "Open Or Create A Vault", link: "/start/open-or-create-vault" },
+        ],
+      },
+      {
+        text: "Concepts",
+        items: [
+          { text: "Vaults", link: "/concepts/vaults" },
+          { text: "Notes", link: "/concepts/notes" },
+          { text: "Properties", link: "/concepts/properties" },
+          { text: "Types", link: "/concepts/types" },
+          { text: "Relationships", link: "/concepts/relationships" },
+          { text: "Inbox", link: "/concepts/inbox" },
+          { text: "Git", link: "/concepts/git" },
+          { text: "AI", link: "/concepts/ai" },
+        ],
+      },
+      {
+        text: "Guides",
+        items: [
+          { text: "Capture A Note", link: "/guides/capture-a-note" },
+          { text: "Organize The Inbox", link: "/guides/organize-inbox" },
+          { text: "Use Wikilinks", link: "/guides/use-wikilinks" },
+          { text: "Create Types", link: "/guides/create-types" },
+          { text: "Build Custom Views", link: "/guides/build-custom-views" },
+          { text: "Connect A Git Remote", link: "/guides/connect-a-git-remote" },
+          { text: "Commit And Push", link: "/guides/commit-and-push" },
+          { text: "Use The AI Panel", link: "/guides/use-ai-panel" },
+          { text: "Use The Command Palette", link: "/guides/use-command-palette" },
+        ],
+      },
+      {
+        text: "Reference",
+        items: [
+          { text: "Supported Platforms", link: "/reference/supported-platforms" },
+          { text: "File Layout", link: "/reference/file-layout" },
+          { text: "Frontmatter Fields", link: "/reference/frontmatter-fields" },
+          { text: "View Filters", link: "/reference/view-filters" },
+          { text: "Keyboard Shortcuts", link: "/reference/keyboard-shortcuts" },
+          { text: "Docs Maintenance", link: "/reference/docs-maintenance" },
+        ],
+      },
+      {
+        text: "Troubleshooting",
+        items: [
+          { text: "Vault Not Loading", link: "/troubleshooting/vault-not-loading" },
+          { text: "Git Authentication", link: "/troubleshooting/git-auth" },
+          { text: "AI Agent Not Found", link: "/troubleshooting/ai-agent-not-found" },
+          { text: "Sync Conflicts", link: "/troubleshooting/sync-conflicts" },
+        ],
+      },
+    ],
+    footer: {
+      message: "Free and open source. Local-first, Git-first, and Markdown-based.",
+      copyright:
+        "Tolaria is AGPL-3.0-or-later. The Tolaria name and logo remain covered by the project trademark policy.",
+    },
+  },
+});

site/.vitepress/theme/Layout.vue

@@ -0,0 +1,28 @@
+<script setup lang="ts">
+import DefaultTheme from "vitepress/theme";
+import { onBeforeUnmount, onMounted } from "vue";
+import { useData } from "vitepress";
+
+const { frontmatter } = useData();
+
+const scrollClass = "tolaria-scrolled";
+const updateScrollClass = () => {
+  document.documentElement.classList.toggle(scrollClass, window.scrollY > 8);
+};
+
+onMounted(() => {
+  updateScrollClass();
+  window.addEventListener("scroll", updateScrollClass, { passive: true });
+});
+
+onBeforeUnmount(() => {
+  window.removeEventListener("scroll", updateScrollClass);
+  document.documentElement.classList.remove(scrollClass);
+});
+</script>
+
+<template>
+  <div :class="{ 'tolaria-landing-shell': frontmatter.landing }">
+    <DefaultTheme.Layout />
+  </div>
+</template>

site/.vitepress/theme/index.ts

@@ -0,0 +1,12 @@
+import DefaultTheme from "vitepress/theme";
+import LandingHome from "./LandingHome.vue";
+import Layout from "./Layout.vue";
+import "./styles.css";
+
+export default {
+  extends: DefaultTheme,
+  Layout,
+  enhanceApp({ app }) {
+    app.component("LandingHome", LandingHome);
+  },
+};

site/.vitepress/theme/styles.css

@@ -0,0 +1,171 @@
+@font-face {
+  font-family: "RefactoringSans";
+  src: url("./assets/RefactoringSans.otf") format("opentype");
+  font-display: swap;
+  font-style: normal;
+  font-weight: 400 900;
+}
+
+:root {
+  --vp-font-family-base:
+    "Inter", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+  --vp-font-family-mono: "SF Mono", "Fira Code", ui-monospace, monospace;
+  --tolaria-font-brand:
+    "RefactoringSans", "Inter", -apple-system, BlinkMacSystemFont, sans-serif;
+  --tolaria-bg: #faf9f5;
+  --tolaria-surface: #ffffff;
+  --tolaria-surface-muted: #f7f6f3;
+  --tolaria-text: #1a1a18;
+  --tolaria-text-secondary: #6b6b60;
+  --tolaria-text-muted: #9b9b90;
+  --tolaria-border: #e5e5e0;
+  --tolaria-blue: #155dff;
+  --tolaria-blue-hover: #4a5ad6;
+  --tolaria-blue-soft: #e8eeff;
+  --vp-c-bg: var(--tolaria-surface);
+  --vp-c-bg-alt: var(--tolaria-surface-muted);
+  --vp-c-bg-elv: var(--tolaria-surface);
+  --vp-c-bg-soft: var(--tolaria-surface-muted);
+  --vp-c-text-1: var(--tolaria-text);
+  --vp-c-text-2: var(--tolaria-text-secondary);
+  --vp-c-text-3: var(--tolaria-text-muted);
+  --vp-c-border: var(--tolaria-border);
+  --vp-c-divider: var(--tolaria-border);
+  --vp-c-brand-1: var(--tolaria-blue);
+  --vp-c-brand-2: var(--tolaria-blue-hover);
+  --vp-c-brand-3: var(--tolaria-blue);
+  --vp-c-brand-soft: var(--tolaria-blue-soft);
+  --vp-button-brand-bg: var(--tolaria-blue);
+  --vp-button-brand-hover-bg: var(--tolaria-blue-hover);
+  --vp-button-brand-border: var(--tolaria-blue);
+  --vp-code-bg: #eeeeea;
+  --vp-code-color: var(--tolaria-text-secondary);
+}
+
+.dark {
+  --vp-c-bg: #1f1e1b;
+  --vp-c-bg-alt: #191814;
+  --vp-c-bg-elv: #23221f;
+  --vp-c-bg-soft: #23221f;
+  --vp-c-text-1: #e6e1d8;
+  --vp-c-text-2: #b8b1a6;
+  --vp-c-text-3: #7f776d;
+  --vp-c-border: #34322d;
+  --vp-c-divider: #34322d;
+  --vp-c-brand-1: #78a4ff;
+  --vp-c-brand-2: #9bbeff;
+  --vp-c-brand-3: #78a4ff;
+  --vp-c-brand-soft: rgba(120, 164, 255, 0.16);
+  --vp-code-bg: #2d2b27;
+  --vp-code-color: #d8d1c6;
+}
+
+.VPNavBarTitle .logo {
+  width: auto;
+  height: 28px;
+}
+
+.VPNavBarTitle .title {
+  color: var(--vp-c-text-1);
+  font-family: var(--tolaria-font-brand);
+  font-size: 22px;
+  font-weight: 800;
+  letter-spacing: 0;
+}
+
+.tolaria-landing-shell {
+  --vp-c-bg: var(--tolaria-bg);
+}
+
+.tolaria-landing-shell .VPNav,
+.tolaria-landing-shell .VPNavBar,
+.tolaria-landing-shell .VPNavBar .content-body {
+  background: color-mix(in srgb, var(--tolaria-bg) 94%, transparent);
+  backdrop-filter: blur(14px);
+}
+
+.tolaria-landing-shell .VPNavBar .divider,
+.tolaria-landing-shell .VPNavBar .divider-line {
+  background-color: transparent;
+}
+
+.tolaria-landing-shell .VPNavBar .divider-line {
+  opacity: 0;
+  transition: opacity 160ms ease;
+}
+
+.tolaria-landing-shell .VPLocalNav {
+  display: none;
+}
+
+.tolaria-scrolled .tolaria-landing-shell .VPNav {
+  box-shadow: 0 10px 24px rgba(26, 26, 24, 0.06);
+}
+
+.tolaria-scrolled .tolaria-landing-shell .VPNavBar .divider-line {
+  opacity: 1;
+}
+
+.DocSearch-Button {
+  border-radius: 999px;
+}
+
+.vp-doc h1,
+.vp-doc h2,
+.vp-doc h3 {
+  letter-spacing: 0;
+}
+
+.vp-doc a,
+.VPNavBarMenuLink.active,
+.VPLink.active {
+  color: var(--vp-c-brand-1);
+}
+
+.vp-doc table {
+  display: table;
+  width: 100%;
+}
+
+.vp-doc th {
+  color: var(--vp-c-text-1);
+  background: var(--vp-c-bg-soft);
+}
+
+.vp-doc td,
+.vp-doc th {
+  border-color: var(--vp-c-divider);
+}
+
+.tolaria-landing-shell .VPContent,
+.tolaria-landing-shell .VPPage,
+.tolaria-landing-shell .VPDoc,
+.tolaria-landing-shell .VPDoc .container,
+.tolaria-landing-shell .VPDoc .content,
+.tolaria-landing-shell .VPDoc .content-container,
+.tolaria-landing-shell .VPDoc .main,
+.tolaria-landing-shell .vp-doc {
+  max-width: none;
+  padding: 0;
+  margin: 0;
+}
+
+.tolaria-landing-shell .VPPage {
+  padding-top: var(--vp-nav-height);
+}
+
+.tolaria-landing-shell .VPDoc {
+  padding-top: var(--vp-nav-height);
+}
+
+.tolaria-landing-shell .vp-doc > div {
+  width: 100%;
+}
+
+.tolaria-landing-shell .vp-doc a {
+  text-decoration: none;
+}
+
+.tolaria-landing-shell .VPFooter {
+  display: none;
+}

site/concepts/ai.md

@@ -0,0 +1,20 @@
+# AI
+
+Tolaria is designed for local AI agents that can work with files and tools rather than a hidden cloud-only notes API.
+
+## Agent Panel
+
+The AI panel streams messages from supported local CLI agents. It shows reasoning, tool activity, and file changes in the app.
+
+## MCP Server
+
+Tolaria exposes an MCP server so tools such as Claude Code and Codex can search, read, and edit vault notes through explicit tools.
+
+## Why Git Matters For AI
+
+AI-generated changes should be inspectable. Git gives you diffs, history, rollback, and a clear boundary between suggestions and committed work.
+
+## Current Direction
+
+Claude Code is the primary integration. Codex and other CLI agents are supported through the shared agent architecture as the app evolves.
+

site/concepts/git.md

@@ -0,0 +1,21 @@
+# Git
+
+Git is Tolaria's history and sync layer. It keeps the model local-first while still supporting remote backup and multi-device workflows.
+
+## What Tolaria Uses Git For
+
+- Local commit history.
+- Diff views.
+- Per-note history.
+- Pull and push.
+- Conflict detection and resolution.
+- Remote connection for local-only vaults.
+
+## Local Commits
+
+You can commit changes inside Tolaria without leaving the app. This gives you useful restore points even before a remote is configured.
+
+## Remotes
+
+Connect a compatible Git remote when you want sync or backup. Tolaria relies on your system Git authentication, so GitHub CLI, SSH keys, credential helpers, and existing Git configuration can continue to work.
+

site/concepts/inbox.md

@@ -0,0 +1,22 @@
+# Inbox
+
+The Inbox is for notes that have been captured but not yet organized.
+
+## Why It Exists
+
+Fast capture should not require perfect structure. The Inbox gives you a place to put incomplete notes, then process them later.
+
+## Organizing Inbox Notes
+
+When reviewing the Inbox:
+
+1. Give the note a clear H1.
+2. Set its `type`.
+3. Add status, dates, or URL if useful.
+4. Add relationships with wikilinks or frontmatter fields.
+5. Move it into a folder only if the folder adds value.
+
+## Healthy Inbox Habit
+
+Keep the Inbox small enough that it can be reviewed in one focused pass. Tolaria works best when capture is fast and organization is deliberate.
+

site/concepts/notes.md

@@ -0,0 +1,31 @@
+# Notes
+
+A note is a Markdown file with optional YAML frontmatter. Tolaria reads the first H1 as the primary title and keeps the file on disk as the durable representation.
+
+## Anatomy
+
+```md
+---
+type: Project
+status: Active
+belongs_to:
+  - "[[workspace]]"
+---
+
+# Launch Documentation
+
+Draft the public Tolaria docs and keep them close to code changes.
+```
+
+## Titles
+
+The first H1 is the main title. Older notes can still use a `title:` frontmatter fallback, but new notes should rely on the H1.
+
+## Body Links
+
+Use `[[wikilinks]]` to connect notes from the body. Tolaria can resolve links by filename, title, and aliases.
+
+## Frontmatter
+
+Use frontmatter for structured fields such as type, status, date, URL, and relationships. Keep free-form thinking in the body.
+

site/concepts/properties.md

@@ -0,0 +1,25 @@
+# Properties
+
+Properties are frontmatter fields that Tolaria can display, filter, and edit.
+
+## Common Properties
+
+| Field | Purpose |
+| --- | --- |
+| `type` | Groups the note into a type such as Project, Person, or Topic. |
+| `status` | Tracks lifecycle state such as Active, Done, or Blocked. |
+| `url` | Stores a canonical external link. |
+| `date` | Represents a single date. |
+| `start_date`, `end_date` | Represents a date range. |
+| `aliases` | Gives a note alternative names for wikilink resolution. |
+
+## System Properties
+
+Fields that start with `_` are system properties. They remain in plain text but are hidden from normal property editing.
+
+Examples include `_icon`, `_color`, `_order`, and `_pinned_properties` on type documents.
+
+## Property Editing
+
+The Inspector is the safest place to edit structured properties. Use raw Markdown mode when you need direct control over YAML.
+

site/concepts/relationships.md

@@ -0,0 +1,27 @@
+# Relationships
+
+Relationships make a vault feel like a graph instead of a pile of documents.
+
+## Relationship Fields
+
+Any frontmatter field containing wikilinks can become a relationship.
+
+```yaml
+belongs_to:
+  - "[[product-work]]"
+related_to:
+  - "[[documentation]]"
+blocked_by:
+  - "[[release-process]]"
+```
+
+Tolaria does not need a hardcoded list of relationship names. It detects relationship fields dynamically.
+
+## Body Links Versus Relationship Fields
+
+Use body links when the relationship appears naturally in writing. Use frontmatter relationships when the connection is important enough to show in navigation, filters, or the Inspector.
+
+## Backlinks
+
+Tolaria can show incoming links and inverse relationships, making it easier to navigate from a note to the rest of its context.
+

site/concepts/types.md

@@ -0,0 +1,38 @@
+# Types
+
+Types describe what kind of thing a note represents: Project, Person, Topic, Procedure, Event, or any category you create.
+
+## Type Field
+
+The `type:` field assigns a note to a type.
+
+```yaml
+type: Project
+```
+
+Tolaria does not infer type from folder location. Moving a file into another folder does not change its type.
+
+## Type Documents
+
+Type documents live in the `type/` folder and describe how a type should appear.
+
+```yaml
+---
+type: Type
+icon: folder
+color: blue
+sidebar_label: Projects
+sort: modified:desc
+---
+
+# Project
+```
+
+## What Types Control
+
+- Sidebar grouping.
+- Type icon and color.
+- Default sort.
+- Pinned properties.
+- New-note templates.
+

site/concepts/vaults.md

@@ -0,0 +1,29 @@
+# Vaults
+
+A vault is the folder Tolaria reads and writes. The filesystem is the source of truth; the app state and cache are derived from files.
+
+## Core Rules
+
+- Notes are Markdown files.
+- YAML frontmatter provides structure.
+- Attachments are normal files inside the vault.
+- Type definitions and saved views are also files.
+- Git tracks history and supports remote sync.
+
+## Why Local Files Matter
+
+Local files keep your notes inspectable. You can open them in another editor, search with command-line tools, back them up with your own system, and version them with Git.
+
+Tolaria should never become the only way to read your data.
+
+## App State Versus Vault State
+
+Vault-level information should travel with the vault. Machine-specific preferences stay with the app installation.
+
+| Vault state | App state |
+| --- | --- |
+| Type icons and colors | Editor zoom |
+| Saved views | Window size |
+| Pinned properties | Recent vault list |
+| Relationship conventions | Local cache |
+

site/download/index.md

@@ -0,0 +1,17 @@
+# Download
+
+Download Tolaria from the latest stable release.
+
+## macOS
+
+[Download the latest stable build](https://refactoringhq.github.io/tolaria/download/)
+
+macOS is the primary supported platform.
+
+## Linux And Windows
+
+Linux and Windows builds are best effort for now. Check the [latest GitHub release](https://github.com/refactoringhq/tolaria/releases/latest) for available artifacts.
+
+## Verify The Version
+
+After launching the app, check the version shown in Tolaria's status bar or release surface.

site/guides/build-custom-views.md

@@ -0,0 +1,20 @@
+# Build Custom Views
+
+Custom views are saved filters for recurring questions.
+
+## Good View Candidates
+
+- Active projects.
+- People without a recent follow-up.
+- Drafts ready for review.
+- Notes changed this week.
+- Events in a date range.
+
+## View Definition
+
+Saved views live as files in the vault. They describe filters, sorting, and visible columns using structured data.
+
+## Design The Question First
+
+Before creating a view, write the question it answers. A good view is not "all fields with all filters"; it is a focused lens.
+

site/guides/capture-a-note.md

@@ -0,0 +1,20 @@
+# Capture A Note
+
+Use capture when you need to get an idea into the vault before you know where it belongs.
+
+## Steps
+
+1. Open the command palette with `Cmd+K` or `Ctrl+K`.
+2. Run `New Note`.
+3. Write a clear H1.
+4. Add the rough content.
+5. Leave structure for later if you are still thinking.
+
+## Capture Well
+
+Prefer a useful title over a perfect taxonomy. You can add type, status, and relationships during inbox review.
+
+## When To Add Structure Immediately
+
+Add structure while capturing if the note is obviously a Project, Person, Event, or Procedure and the context is already known.
+

site/guides/commit-and-push.md

@@ -0,0 +1,19 @@
+# Commit And Push
+
+Tolaria lets you commit and push vault changes from inside the app.
+
+## Commit
+
+1. Open the Git or changes surface.
+2. Review changed files.
+3. Write a short commit message.
+4. Commit locally.
+
+## Push
+
+Push after committing when a remote is configured. If the remote has changed, pull first and resolve any conflicts.
+
+## Use Small Commits
+
+Small commits make it easier to understand what changed, roll back safely, and review AI-generated edits.
+

site/guides/connect-a-git-remote.md

@@ -0,0 +1,23 @@
+# Connect A Git Remote
+
+Connect a remote when you want backup or sync beyond the current machine.
+
+## Before You Start
+
+Make sure the remote repository exists and your system Git can authenticate to it. Tolaria uses system Git rather than storing provider-specific credentials.
+
+## Steps
+
+1. Open the bottom status bar remote chip, or run `Add Remote` from the command palette.
+2. Paste the remote URL.
+3. Confirm the remote name.
+4. Fetch or push according to the app prompt.
+
+## Recommended Auth
+
+- SSH keys.
+- GitHub CLI authentication.
+- Existing Git credential helpers.
+
+If authentication fails, see [Git Authentication](/troubleshooting/git-auth).
+

site/guides/create-types.md

@@ -0,0 +1,27 @@
+# Create Types
+
+Create a type when several notes share the same role in your system.
+
+## Steps
+
+1. Create a note in the `type/` folder.
+2. Set `type: Type` in frontmatter.
+3. Give the document a clear H1.
+4. Add optional icon, color, sort, and sidebar label.
+
+```yaml
+---
+type: Type
+icon: briefcase
+color: blue
+sidebar_label: Projects
+sort: modified:desc
+---
+
+# Project
+```
+
+## Use Types Sparingly
+
+A type should represent a recurring category, not a one-off label. If you only need a temporary grouping, use a saved view or property instead.
+

site/guides/organize-inbox.md

@@ -0,0 +1,26 @@
+# Organize The Inbox
+
+Inbox review turns quick captures into usable knowledge.
+
+## Review Checklist
+
+- Rename unclear notes.
+- Add or correct the first H1.
+- Set `type`.
+- Add `status` for actionable notes.
+- Add `belongs_to`, `related_to`, or other relationship fields when useful.
+- Archive or delete notes that no longer matter.
+
+## Make Notes Navigable
+
+A note is organized when you can answer:
+
+- What kind of thing is this?
+- What is it connected to?
+- What should happen next?
+- Where would I expect to find it later?
+
+## Avoid Over-Structuring
+
+Do not add fields just because they exist. Add the structure that will help future navigation, review, or automation.
+

site/guides/use-ai-panel.md

@@ -0,0 +1,19 @@
+# Use The AI Panel
+
+The AI panel connects Tolaria to local CLI agents.
+
+## Before Using It
+
+Install a supported agent such as Claude Code and make sure it is available from your shell. Tolaria detects common install locations, but explicit shell availability is still the simplest setup.
+
+## Good Requests
+
+- "Find notes related to this project."
+- "Summarize what changed in this note."
+- "Draft a weekly review from these linked notes."
+- "Update this checklist based on the current project status."
+
+## Review Changes
+
+AI edits are file edits. Review them with Tolaria's diff and Git history before committing.
+

site/guides/use-command-palette.md

@@ -0,0 +1,24 @@
+# Use The Command Palette
+
+The command palette is the fastest way to move around Tolaria.
+
+Open it with:
+
+- `Cmd+K` on macOS.
+- `Ctrl+K` on Linux and Windows.
+
+## Common Commands
+
+- New Note.
+- Search.
+- Open Settings.
+- Reload Vault.
+- Add Remote.
+- Open Getting Started Vault.
+- Toggle Raw Mode.
+- Open in New Window.
+
+## Keyboard-First Workflow
+
+Use the palette when you know what you want to do but do not want to hunt through panels. It is also the best place to discover commands as the app grows.
+

site/guides/use-wikilinks.md

@@ -0,0 +1,25 @@
+# Use Wikilinks
+
+Wikilinks connect notes by name.
+
+```md
+This project belongs to [[content-systems]] and is related to [[git-workflows]].
+```
+
+## Link From The Body
+
+Use body links when the connection is part of the sentence you are writing.
+
+## Link From Frontmatter
+
+Use frontmatter links when the relationship should become structured metadata.
+
+```yaml
+related_to:
+  - "[[git-workflows]]"
+```
+
+## Keep Links Stable
+
+Prefer clear note titles and filenames. Use aliases when people or projects are known by multiple names.
+

site/index.md

@@ -0,0 +1,10 @@
+---
+layout: page
+sidebar: false
+aside: false
+landing: true
+title: Tolaria
+description: A second brain for the AI era. Free forever.
+---
+
+<LandingHome />

site/public/tolaria-icon.svg

@@ -0,0 +1,10 @@
+<svg width="266" height="363" viewBox="0 0 266 363" fill="none" xmlns="http://www.w3.org/2000/svg">
+<g clip-path="url(#clip0_111_151)">
+<path fill-rule="evenodd" clip-rule="evenodd" d="M119.524 5.31219C126.607 -1.77073 138.117 -1.77073 145.2 5.31219C178.844 40.7268 265.61 147.856 265.61 230.195C265.61 303.68 206.29 363 132.805 363C59.3195 363 0 303.68 0 230.195C0 147.856 86.7659 40.7268 119.524 5.31219ZM59.5947 242.88C58.1619 234.744 50.3952 229.074 42.2195 230.195C34.0438 231.316 28.5932 238.799 30.0259 246.935C37.6847 290.425 72.2734 325.622 116.094 334.485C117.821 334.836 119.552 334.864 121.178 334.641C127.269 333.806 132.289 329.26 133.371 322.934C134.756 314.893 129.25 307.054 121.086 305.401C89.7767 299.057 65.0615 273.923 59.5947 242.88Z" fill="#155DFF"/>
+</g>
+<defs>
+<clipPath id="clip0_111_151">
+<rect width="266" height="363" fill="white"/>
+</clipPath>
+</defs>
+</svg>

site/reference/docs-maintenance.md

@@ -0,0 +1,38 @@
+# Docs Maintenance
+
+The public docs live in the app repo so documentation changes can ship with behavior changes.
+
+## Update Docs When You Change
+
+- A Tauri command.
+- A new component or hook that changes user behavior.
+- A data model or frontmatter convention.
+- Git, AI, onboarding, or release behavior.
+- Platform support.
+- Keyboard shortcuts.
+
+## Suggested Workflow
+
+1. Make the code change.
+2. Update the matching concept, guide, or reference page.
+3. Add a troubleshooting page if the change creates a new failure mode.
+4. Run `pnpm docs:build`.
+5. Check the home page, search, and changed docs pages in a browser.
+
+## Page Types
+
+| Type | Purpose |
+| --- | --- |
+| Start | Helps a new user get into the app. |
+| Concepts | Explains mental models. |
+| Guides | Teaches workflows. |
+| Reference | Gives stable facts and tables. |
+| Troubleshooting | Starts from a symptom and ends with recovery. |
+
+## Review Checklist
+
+- Does the page describe current behavior?
+- Does it mention macOS primary and Linux/Windows best effort when platform support matters?
+- Are links relative and VitePress-compatible?
+- Can a user discover the page with local search?
+

site/reference/file-layout.md

@@ -0,0 +1,35 @@
+# File Layout
+
+A typical vault stays simple.
+
+```txt
+my-vault/
+  project-alpha.md
+  weekly-review.md
+  people/
+    ada-lovelace.md
+  attachments/
+    diagram.png
+  type/
+    project.md
+    person.md
+  views/
+    active-projects.yml
+```
+
+## Root Notes
+
+Tolaria can work with flat vaults and nested folders. Type is not inferred from folder location; it comes from frontmatter.
+
+## Special Folders
+
+| Folder | Purpose |
+| --- | --- |
+| `type/` | Type definition documents. |
+| `views/` | Saved custom views. |
+| `attachments/` | Images and other attached files. |
+
+## Git Files
+
+If the vault is a Git repository, `.git/` belongs to Git. Tolaria reads Git state but does not treat `.git/` as notes.
+

site/reference/frontmatter-fields.md

@@ -0,0 +1,26 @@
+# Frontmatter Fields
+
+Tolaria uses conventions instead of a required schema.
+
+| Field | Meaning |
+| --- | --- |
+| `type` | The note's entity type. |
+| `status` | Lifecycle state. |
+| `icon` | Per-note icon. |
+| `url` | External URL. |
+| `date` | Single date. |
+| `start_date` | Start of a date range. |
+| `end_date` | End of a date range. |
+| `aliases` | Alternative names for link resolution. |
+| `belongs_to` | Parent relationship. |
+| `related_to` | Lateral relationship. |
+| `has` | Contained relationship. |
+
+## Custom Fields
+
+You can add your own fields. If a field contains wikilinks, Tolaria can treat it as a relationship.
+
+## System Fields
+
+Fields starting with `_` are reserved for system behavior and hidden from standard property editing.
+

site/reference/keyboard-shortcuts.md

@@ -0,0 +1,15 @@
+# Keyboard Shortcuts
+
+| Shortcut | Action |
+| --- | --- |
+| `Cmd+K` / `Ctrl+K` | Open command palette. |
+| `Cmd+N` / `Ctrl+N` | Create a new note. |
+| `Cmd+S` / `Ctrl+S` | Save current note. |
+| `Cmd+[` / `Alt+Left` | Navigate back when available. |
+| `Cmd+]` / `Alt+Right` | Navigate forward when available. |
+| `Cmd+Shift+O` / `Ctrl+Shift+O` | Open current note in a new window. |
+
+Some shortcuts vary by platform because macOS, Linux, and Windows reserve different key combinations.
+
+Use the command palette to discover the current command set.
+

site/reference/supported-platforms.md

@@ -0,0 +1,24 @@
+# Supported Platforms
+
+Tolaria is a desktop app built with Tauri.
+
+| Platform | Current support | Notes |
+| --- | --- | --- |
+| macOS | Primary | Main development and QA target. Apple Silicon is first-class. |
+| Linux | Best effort | Depends on distribution WebKitGTK packaging and desktop integration behavior. |
+| Windows | Best effort | Builds exist, but platform-specific behavior may lag macOS. |
+
+## Support Policy
+
+Primary support means the platform is part of normal development and release validation. Best-effort support means builds may be available, but bugs can take longer to diagnose and fix.
+
+## Reporting Platform Bugs
+
+Include:
+
+- Tolaria version.
+- Operating system and version.
+- CPU architecture.
+- Whether the vault is local-only or connected to a remote.
+- Steps to reproduce.
+

site/reference/view-filters.md

@@ -0,0 +1,26 @@
+# View Filters
+
+View filters define saved lists of notes.
+
+## Common Filter Ideas
+
+| Goal | Filter direction |
+| --- | --- |
+| Active projects | `type` is Project and `status` is Active |
+| Drafts | `type` is Article and `status` is Draft |
+| People follow-up | `type` is Person and date is before today |
+| Recent work | modified date is within a recent range |
+
+## Sorting
+
+Useful sorts include:
+
+- Recently modified first.
+- Title ascending.
+- Status ascending.
+- A custom property ascending or descending.
+
+## Keep Views Focused
+
+A view should answer one recurring question. If it becomes too broad, split it into two views.
+

site/releases/index.md

@@ -0,0 +1,16 @@
+# Releases
+
+Tolaria releases are published on GitHub.
+
+- [Latest release](https://github.com/refactoringhq/tolaria/releases/latest)
+- [All releases](https://github.com/refactoringhq/tolaria/releases)
+- [Download page](/download/)
+
+## Release Channels
+
+Stable builds are intended for normal use. Pre-release builds may contain newer features and rougher edges.
+
+## Before Updating
+
+Commit or push important vault changes before updating the app. Your notes are local files, but having a clean Git state makes recovery easier.
+

site/start/first-launch.md

@@ -0,0 +1,32 @@
+# First Launch
+
+The first launch flow is designed to get you into a real vault quickly without hiding the local-first model.
+
+## What You Choose
+
+Tolaria asks whether you want to:
+
+- Create or clone the Getting Started vault.
+- Open an existing local vault.
+- Create a new empty vault.
+
+The Getting Started vault is cloned locally and then disconnected from its remote. That keeps the sample safe to edit without accidentally pushing tutorial changes.
+
+## What Tolaria Creates
+
+Tolaria stores app-level settings on the local machine. Your notes stay in the vault folder you choose.
+
+| Data | Stored in |
+| --- | --- |
+| Notes and attachments | Your vault folder |
+| Type definitions and saved views | Your vault folder |
+| Window size, zoom, recent vaults | Local app settings |
+| Cache data | Rebuildable local cache |
+
+## First Commands To Try
+
+- `Cmd+K` / `Ctrl+K`: open the command palette.
+- `New Note`: create a note in the current vault.
+- `Open Getting Started Vault`: clone the public sample vault.
+- `Reload Vault`: rescan files after external edits.
+

site/start/getting-started-vault.md

@@ -0,0 +1,24 @@
+# Getting Started Vault
+
+The Getting Started vault is a small public sample vault hosted at [refactoringhq/tolaria-getting-started](https://github.com/refactoringhq/tolaria-getting-started).
+
+It exists to show Tolaria's conventions without requiring you to restructure your own notes first.
+
+## What It Demonstrates
+
+- Markdown notes with YAML frontmatter.
+- Types such as Project, Person, Topic, and Procedure.
+- Wikilinks in note bodies.
+- Relationship fields in frontmatter.
+- A local Git repository that can be connected to a remote later.
+
+## Local-Only By Default
+
+When Tolaria clones the sample, it removes the remote from the local copy. This makes the sample vault disposable. You can edit it freely, commit locally, and delete it later.
+
+To connect a vault to your own remote, use the bottom status bar remote chip or run `Add Remote` from the command palette.
+
+## When To Move On
+
+After you understand the sample, open your own vault. Tolaria does not require a special folder structure: a folder of Markdown files is enough to start.
+

site/start/install.md

@@ -0,0 +1,28 @@
+# Install Tolaria
+
+Tolaria is developed and tested primarily on macOS. Linux and Windows builds are published on a best-effort basis while the app matures.
+
+## Download
+
+Use the latest stable release unless you are intentionally testing pre-release builds:
+
+- [Download the latest stable build](https://refactoringhq.github.io/tolaria/download/)
+- [Browse all GitHub releases](https://github.com/refactoringhq/tolaria/releases)
+- [Read the release notes](/releases/)
+
+## Platform Status
+
+| Platform | Status | Notes |
+| --- | --- | --- |
+| macOS | Primary | Apple Silicon is the first-class desktop target. |
+| Linux | Best effort | Builds exist, but desktop integration varies by distribution and WebKitGTK packaging. |
+| Windows | Best effort | Builds exist, but behavior may lag macOS while the app is still early. |
+
+See [Supported Platforms](/reference/supported-platforms) for the current support policy.
+
+## After Installing
+
+1. Open Tolaria.
+2. Choose the Getting Started vault if you want a guided sample.
+3. Or open an existing folder of Markdown files as a vault.
+4. Use the command palette with `Cmd+K` on macOS or `Ctrl+K` on Linux and Windows.

site/start/open-or-create-vault.md

@@ -0,0 +1,25 @@
+# Open Or Create A Vault
+
+A Tolaria vault is a folder on disk. The folder can contain Markdown notes, attachments, type definitions, saved views, and Git metadata.
+
+## Open An Existing Folder
+
+Choose an existing folder if you already have Markdown notes. Tolaria scans `.md` files and uses frontmatter when it exists.
+
+Good starting points:
+
+- A folder of plain Markdown files.
+- An Obsidian-style vault.
+- A Git repository containing notes.
+- A copy of the Getting Started vault.
+
+## Create A New Vault
+
+Choose a new empty folder if you want Tolaria conventions from the start. New notes are created as Markdown files, and optional type definitions live in the `type/` folder.
+
+## Git Repository Requirement
+
+Tolaria's history and sync features expect the vault to be a Git repository. If a vault is not already a repository, Tolaria can initialize one for you.
+
+Use Git because it gives Tolaria reliable local history, diff views, recovery, and remote sync without a proprietary backend.
+

site/troubleshooting/ai-agent-not-found.md

@@ -0,0 +1,23 @@
+# AI Agent Not Found
+
+Tolaria can only launch local CLI agents that are installed and discoverable.
+
+## Symptoms
+
+- The AI panel says no supported agent is available.
+- Claude Code or another agent works in one shell but not in Tolaria.
+
+## Checks
+
+Open a terminal and run the agent command directly. For Claude Code:
+
+```bash
+claude --version
+```
+
+If the command fails, install or repair the agent first.
+
+## Path Issues
+
+Desktop apps can inherit a different `PATH` from your interactive shell. Tolaria checks common install locations, but shell setup can still vary. Prefer installing CLI tools in standard locations or making them available from your login shell.
+

site/troubleshooting/git-auth.md

@@ -0,0 +1,26 @@
+# Git Authentication
+
+Tolaria uses system Git authentication. It does not manage provider passwords directly.
+
+## Symptoms
+
+- Push fails.
+- Pull asks for credentials repeatedly.
+- Remote fetch works in one terminal but not in Tolaria.
+
+## Checks
+
+1. Open a terminal.
+2. `cd` into the vault.
+3. Run `git remote -v`.
+4. Run `git fetch`.
+
+If `git fetch` fails in the terminal, fix system Git auth first.
+
+## Common Fixes
+
+- Sign in with GitHub CLI.
+- Configure SSH keys.
+- Update the remote URL.
+- Check your credential helper.
+

site/troubleshooting/sync-conflicts.md

@@ -0,0 +1,20 @@
+# Sync Conflicts
+
+Sync conflicts happen when local and remote changes touch the same content.
+
+## What To Do
+
+1. Stop editing the conflicted note.
+2. Open the conflict resolver if Tolaria presents it.
+3. Review both sides.
+4. Choose the correct content or merge manually.
+5. Commit the resolved file.
+6. Push again.
+
+## Prevent Conflicts
+
+- Pull before starting work on another device.
+- Push after meaningful sessions.
+- Keep AI-generated edits in small commits.
+- Avoid editing the same note on multiple devices at the same time.
+

site/troubleshooting/vault-not-loading.md

@@ -0,0 +1,25 @@
+# Vault Not Loading
+
+Use this checklist when Tolaria cannot open or refresh a vault.
+
+## Check The Folder
+
+- Confirm the folder exists.
+- Confirm the folder contains readable files.
+- Confirm Tolaria has permission to access the folder.
+- Try opening a smaller test vault to isolate the issue.
+
+## Check Git
+
+If the vault is a Git repository, verify it is not in a broken state:
+
+```bash
+git status
+```
+
+Resolve interrupted merges or corrupted repository state before retrying.
+
+## Reload
+
+Run `Reload Vault` from the command palette. This clears derived cache and rescans the filesystem.
+

src/components/EditorTheme.css

@@ -273,6 +273,7 @@
 }
 
 .editor__blocknote-container .mermaid-diagram {
+  position: relative;
   width: 100%;
   margin: 10px 0;
   color: var(--colors-text);
@@ -287,6 +288,20 @@
   background: var(--surface-editor);
 }
 
+.editor__blocknote-container .mermaid-diagram__expand-button {
+  position: absolute;
+  top: 8px;
+  right: 8px;
+  z-index: 1;
+  opacity: 0;
+  background: var(--surface-editor);
+  box-shadow: 0 6px 16px rgb(15 23 42 / 0.14);
+}
+
+.editor__blocknote-container .mermaid-diagram:is(:hover, :focus-within) .mermaid-diagram__expand-button {
+  opacity: 1;
+}
+
 .editor__blocknote-container .mermaid-diagram__viewport:focus-visible {
   outline: 2px solid var(--border-focus);
   outline-offset: 2px;
@@ -300,6 +315,42 @@
   margin: 0 auto;
 }
 
+@media (hover: none) {
+  .editor__blocknote-container .mermaid-diagram__expand-button {
+    opacity: 1;
+  }
+}
+
+.mermaid-diagram__dialog {
+  width: calc(100vw - 32px);
+  max-width: calc(100vw - 32px);
+  height: calc(100dvh - 32px);
+  max-height: calc(100dvh - 32px);
+  overflow: hidden;
+  padding: 0;
+}
+
+.mermaid-diagram__dialog-viewport {
+  width: 100%;
+  height: 100%;
+  overflow: auto;
+  padding: 24px;
+  background: #fff;
+}
+
+.mermaid-diagram__dialog-viewport:focus-visible {
+  outline: 2px solid var(--border-focus);
+  outline-offset: -2px;
+}
+
+.mermaid-diagram__dialog-viewport svg {
+  display: block;
+  max-width: none;
+  min-width: min-content;
+  height: auto;
+  margin: auto;
+}
+
 .editor__blocknote-container .mermaid-diagram--error {
   padding: 12px;
   border: 1px solid var(--destructive);

src/components/MermaidDiagram.test.tsx

@@ -1,4 +1,4 @@
-import { render, screen, waitFor } from '@testing-library/react'
+import { fireEvent, render, screen, waitFor } from '@testing-library/react'
 import { beforeEach, describe, expect, it, vi } from 'vitest'
 import { MermaidDiagram } from './MermaidDiagram'
 
@@ -31,6 +31,23 @@ describe('MermaidDiagram', () => {
       expect(screen.getByTestId('mermaid-diagram-viewport').querySelector('svg')).not.toBeNull()
     })
     expect(mermaidMock.render).toHaveBeenCalledWith(expect.stringMatching(/^tolaria-mermaid-/), 'flowchart LR\nA --> B')
+    expect(mermaidMock.initialize).toHaveBeenCalledWith(expect.objectContaining({ theme: 'default' }))
+  })
+
+  it('opens the rendered SVG in a lightbox', async () => {
+    render(
+      <MermaidDiagram
+        diagram={'flowchart LR\nA --> B'}
+        source={'```mermaid\nflowchart LR\nA --> B\n```'}
+      />,
+    )
+
+    await waitFor(() => {
+      expect(screen.getByTestId('mermaid-diagram-viewport').querySelector('svg')).not.toBeNull()
+    })
+
+    fireEvent.click(screen.getByRole('button', { name: 'Open Mermaid diagram' }))
+    expect(screen.getByTestId('mermaid-diagram-dialog-viewport').querySelector('svg')).not.toBeNull()
   })
 
   it('falls back to the original source when Mermaid cannot render', async () => {

src/components/MermaidDiagram.tsx

@@ -1,4 +1,13 @@
 import { useEffect, useId, useMemo, useState } from 'react'
+import { Maximize2 } from 'lucide-react'
+import { Button } from '@/components/ui/button'
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogTitle,
+  DialogTrigger,
+} from '@/components/ui/dialog'
 
 type MermaidApi = typeof import('mermaid')['default']
 
@@ -7,6 +16,13 @@ interface MermaidDiagramProps {
   source: string
 }
 
+interface MermaidSvgViewportProps {
+  ariaLabel: string
+  className: string
+  svg: string
+  testId: string
+}
+
 interface RenderState {
   diagram: string
   svg: string
@@ -27,15 +43,8 @@ function initializeMermaid(mermaid: MermaidApi) {
   mermaid.initialize({
     startOnLoad: false,
     securityLevel: 'strict',
-    theme: 'base',
+    theme: 'default',
     themeVariables: {
-      background: '#ffffff',
-      primaryColor: '#f8fafc',
-      primaryTextColor: '#111827',
-      primaryBorderColor: '#94a3b8',
-      lineColor: '#64748b',
-      secondaryColor: '#f1f5f9',
-      tertiaryColor: '#e0f2fe',
       fontFamily: 'ui-sans-serif, system-ui, sans-serif',
     },
   })
@@ -60,6 +69,50 @@ async function renderMermaidDiagram({
   return nextRender
 }
 
+function MermaidSvgViewport({ ariaLabel, className, svg, testId }: MermaidSvgViewportProps) {
+  return (
+    <div
+      aria-label={ariaLabel}
+      className={className}
+      data-testid={testId}
+      role="img"
+      tabIndex={0}
+      dangerouslySetInnerHTML={{ __html: svg }}
+    />
+  )
+}
+
+function MermaidLightbox({ svg }: { svg: string }) {
+  return (
+    <Dialog>
+      <DialogTrigger asChild>
+        <Button
+          aria-label="Open Mermaid diagram"
+          className="mermaid-diagram__expand-button"
+          size="icon-sm"
+          title="Open diagram"
+          type="button"
+          variant="outline"
+        >
+          <Maximize2 aria-hidden="true" />
+        </Button>
+      </DialogTrigger>
+      <DialogContent className="mermaid-diagram__dialog" showCloseButton>
+        <DialogTitle className="sr-only">Mermaid diagram</DialogTitle>
+        <DialogDescription className="sr-only">
+          Expanded view of the rendered Mermaid diagram.
+        </DialogDescription>
+        <MermaidSvgViewport
+          ariaLabel="Expanded Mermaid diagram"
+          className="mermaid-diagram__dialog-viewport"
+          svg={svg}
+          testId="mermaid-diagram-dialog-viewport"
+        />
+      </DialogContent>
+    </Dialog>
+  )
+}
+
 export function MermaidDiagram({ diagram, source }: MermaidDiagramProps) {
   const reactId = useId()
   const renderId = useMemo(() => renderIdFromReactId(reactId), [reactId])
@@ -92,13 +145,12 @@ export function MermaidDiagram({ diagram, source }: MermaidDiagramProps) {
 
   return (
     <figure className="mermaid-diagram" data-testid="mermaid-diagram">
-      <div
-        aria-label="Mermaid diagram"
+      <MermaidLightbox svg={currentState.svg} />
+      <MermaidSvgViewport
+        ariaLabel="Mermaid diagram"
         className="mermaid-diagram__viewport"
-        data-testid="mermaid-diagram-viewport"
-        role="img"
-        tabIndex={0}
-        dangerouslySetInnerHTML={{ __html: currentState.svg }}
+        svg={currentState.svg}
+        testId="mermaid-diagram-viewport"
       />
     </figure>
   )

tests/smoke/mermaid-diagram-notes.spec.ts

@@ -19,6 +19,55 @@ const SECOND_DIAGRAM = [
   '  Alice->>Bob: Hello',
   '```',
 ].join('\n')
+const SYSTEM_OVERVIEW_DIAGRAM = [
+  '```mermaid',
+  'flowchart TD',
+  '    subgraph TW["Tauri v2 Window"]',
+  '        subgraph FE["React Frontend"]',
+  '            App["App.tsx (orchestrator)"]',
+  '            WS["WelcomeScreen\\n(onboarding)"]',
+  '            SB["Sidebar\\n(navigation + filters + types)"]',
+  '            NL["NoteList / PulseView\\n(filtered list / activity)"]',
+  '            ED["Editor\\n(BlockNote + diff + raw)"]',
+  '            IN["Inspector\\n(metadata + relationships)"]',
+  '            AIP["AiPanel\\n(selected CLI agent + tools)"]',
+  '            SP["SearchPanel\\n(keyword search)"]',
+  '            ST["StatusBar\\n(vault picker + sync + version)"]',
+  '            CP["CommandPalette\\n(Cmd+K launcher)"]',
+  '',
+  '            App --> WS & SB & NL & ED & SP & ST & CP',
+  '            ED --> IN & AIP',
+  '        end',
+  '',
+  '        subgraph RB["Rust Backend"]',
+  '            LIB["lib.rs → Tauri commands"]',
+  '            VAULT["vault/"]',
+  '            FM["frontmatter/"]',
+  '            GIT["git/\\n(commit, sync, clone)"]',
+  '            SETTINGS["settings.rs"]',
+  '            SEARCH["search.rs"]',
+  '            CLI["ai_agents.rs\\n+ claude_cli.rs"]',
+  '        end',
+  '',
+  '        subgraph EXT["External Services"]',
+  '            CCLI["Claude / Codex / OpenCode / Pi CLI\\n(agent subprocesses)"]',
+  '            MCP["MCP Server\\n(ws://9710, 9711)"]',
+  '            GCLI["git CLI\\n(system executable)"]',
+  '            REMOTE["Git remotes\\n(GitHub/GitLab/Gitea/etc.)"]',
+  '        end',
+  '',
+  '        FE -->|"Tauri IPC"| RB',
+  '        CLI -->|"spawn subprocess"| CCLI',
+  '        LIB -->|"register / monitor"| MCP',
+  '        GIT -->|"clone / fetch / push / pull"| GCLI',
+  '        GCLI -->|"network auth via user config"| REMOTE',
+  '    end',
+  '',
+  '    style FE fill:#e8f4fd,stroke:#2196f3,color:#000',
+  '    style RB fill:#fff8e1,stroke:#ff9800,color:#000',
+  '    style EXT fill:#f3e5f5,stroke:#9c27b0,color:#000',
+  '```',
+].join('\n')
 const INVALID_DIAGRAM = [
   '```mermaid',
   'not a diagram',
@@ -100,6 +149,19 @@ async function expectRenderedDiagramCount(page: Page, count: number): Promise<vo
   await expect(page.locator('[data-testid="mermaid-diagram-viewport"] svg')).toHaveCount(count, { timeout: 15_000 })
 }
 
+async function countLargeBlackFilledShapes(page: Page, diagramIndex: number): Promise<number> {
+  return page.locator('[data-testid="mermaid-diagram-viewport"] svg').nth(diagramIndex).evaluate((svg) => {
+    const shapes = Array.from(svg.querySelectorAll<SVGGraphicsElement>('rect,path,polygon'))
+
+    return shapes.filter((shape) => {
+      const box = shape.getBoundingClientRect()
+      return getComputedStyle(shape).fill === 'rgb(0, 0, 0)'
+        && box.width > 12
+        && box.height > 8
+    }).length
+  })
+}
+
 function readNoteBFile(): string {
   return fs.readFileSync(path.join(tempVaultDir, 'note', 'note-b.md'), 'utf8')
 }
@@ -116,27 +178,36 @@ ${FIRST_DIAGRAM}
 ${INVALID_DIAGRAM}
 
 ${SECOND_DIAGRAM}
+
+${SYSTEM_OVERVIEW_DIAGRAM}
 `
 
   await setRawEditorContent(page, nextContent)
   await expect.poll(readNoteBFile).toContain(FIRST_DIAGRAM)
 
   await toggleRawMode(page, '.bn-editor')
-  await expectRenderedDiagramCount(page, 2)
+  await expectRenderedDiagramCount(page, 3)
+  await expect.poll(() => countLargeBlackFilledShapes(page, 2)).toBe(0)
   await expect(page.locator('[data-testid="mermaid-diagram-error"]')).toHaveCount(1)
   await expect(page.locator('[data-testid="mermaid-diagram-error"]')).toContainText('not a diagram')
 
+  await page.locator('[data-testid="mermaid-diagram"]').nth(2).hover()
+  await page.getByRole('button', { name: 'Open Mermaid diagram' }).nth(2).click()
+  await expect(page.locator('[data-testid="mermaid-diagram-dialog-viewport"] svg')).toBeVisible()
+  await page.keyboard.press('Escape')
+
   await toggleRawMode(page, '.cm-content')
   const rawAfterRichMode = await getRawEditorContent(page)
   expect(rawAfterRichMode).toContain(FIRST_DIAGRAM)
   expect(rawAfterRichMode).toContain(INVALID_DIAGRAM)
   expect(rawAfterRichMode).toContain(SECOND_DIAGRAM)
+  expect(rawAfterRichMode).toContain(SYSTEM_OVERVIEW_DIAGRAM)
 
   await setRawEditorContent(page, rawAfterRichMode.replace(FIRST_DIAGRAM, UPDATED_FIRST_DIAGRAM))
   await expect.poll(readNoteBFile).toContain(UPDATED_FIRST_DIAGRAM)
 
   await toggleRawMode(page, '.bn-editor')
-  await expectRenderedDiagramCount(page, 2)
+  await expectRenderedDiagramCount(page, 3)
   await expect(page.locator('[data-testid="mermaid-diagram-viewport"]').first()).toContainText('Published')
 
   await openNote(page, 'Note C')
@@ -147,4 +218,5 @@ ${SECOND_DIAGRAM}
   expect(reopenedRaw).toContain(UPDATED_FIRST_DIAGRAM)
   expect(reopenedRaw).toContain(INVALID_DIAGRAM)
   expect(reopenedRaw).toContain(SECOND_DIAGRAM)
+  expect(reopenedRaw).toContain(SYSTEM_OVERVIEW_DIAGRAM)
 })