kitfly 0.2.1 → 0.2.4

package/src/generated/embedded-docs.ts

@@ -0,0 +1,2384 @@
+// AUTO-GENERATED by scripts/embed-docs.ts — do not edit
+export const EMBEDDED_DOCS: ReadonlyArray<readonly [string, string, string]> = [
+	["development", "Development Setup", `# Development Setup
+
+How to set up a Kitfly development environment from a fresh clone.
+
+## Prerequisites
+
+| Tool                                             | Purpose                                 | Install                                                                                                                          |
+| ------------------------------------------------ | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | ----- |
+| [Bun](https://bun.sh)                            | Runtime and package manager             | macOS/Linux: \`curl -fsSL https://bun.sh/install \\| bash\`<br>Windows (PowerShell): \`powershell -c "irm https://bun.sh/install.ps1 | iex"\` |
+| [GNU Make](https://www.gnu.org/software/make/)   | Task runner                             | macOS: included with Xcode CLI tools<br>Linux: \`apt install make\`<br>Windows: \`scoop install make\`                               |
+| [minisign](https://jedisct1.github.io/minisign/) | Signature verification (used by sfetch) | macOS: \`brew install minisign\`<br>Linux: \`apt install minisign\`<br>Windows: \`scoop install minisign\`                             |
+| curl                                             | HTTP client (bootstrap downloads)       | macOS/Linux: usually pre-installed<br>Windows: available in PowerShell (\`Invoke-RestMethod\`)                                     |
+
+## Windows notes (contributors)
+
+Kitfly works well on Windows, but **shell choice matters** for development.
+
+### Recommended setup
+
+- Use **Git Bash** (or MSYS2) for \`make\`-based workflows.
+- Use **PowerShell** for installing Bun.
+
+### Install Bun (PowerShell)
+
+\`\`\`powershell
+powershell -c "irm https://bun.sh/install.ps1|iex"
+\`\`\`
+
+If VS Code’s default terminal is \`cmd.exe\`, you may need to restart VS Code (or ensure \`C:\\Users\\<you>\\.bun\\bin\` is on PATH).
+
+### Install prerequisites (Scoop)
+
+If you don’t already have Scoop, install it from https://scoop.sh.
+
+Then install the tools used by \`make bootstrap\`:
+
+\`\`\`powershell
+scoop install make minisign git
+\`\`\`
+
+### Paths
+
+Kitfly’s bootstrap tools install into \`~/.local/bin\`.
+
+- In Git Bash, that’s the usual \`~/.local/bin\`.
+- In Windows terms, it’s typically \`%USERPROFILE%\\.local\\bin\`.
+
+Ensure that directory is on your PATH in the shell you use.
+
+## Quick Start
+
+\`\`\`bash
+git clone https://github.com/3leaps/kitfly
+cd kitfly
+make bootstrap
+\`\`\`
+
+\`make bootstrap\` installs the full toolchain in four steps:
+
+1. **sfetch** — secure download tool (trust anchor)
+2. **goneat** — formatting and linting tool (installed via sfetch)
+3. **Foundation tools** — standard tooling suite (installed via goneat)
+4. **Bun dependencies** — \`bun install\`
+
+Tools are installed to \`~/.local/bin\`. Ensure this is on your PATH:
+
+\`\`\`bash
+export PATH="$HOME/.local/bin:$PATH"
+\`\`\`
+
+## Verify
+
+\`\`\`bash
+make tools     # Check all external tools are available
+make dev       # Start dev server at http://localhost:3333
+\`\`\`
+
+## Quality gates (before a PR)
+
+\`\`\`bash
+make fmt
+make check-all
+\`\`\`
+
+## Daily Commands
+
+| Command          | What it does                                       |
+| ---------------- | -------------------------------------------------- |
+| \`make dev\`       | Dev server with hot reload                         |
+| \`make build\`     | Build static site to \`dist/\`                       |
+| \`make bundle\`    | Build single-file HTML bundle                      |
+| \`make fmt\`       | Format all code (Biome for TS, goneat for YAML/MD) |
+| \`make test\`      | Run test suite                                     |
+| \`make check-all\` | Full quality check (lint + typecheck + test)       |
+| \`make clean\`     | Remove build artifacts                             |
+
+## Local CLI Install
+
+To use the \`kitfly\` command from anywhere (dogfooding):
+
+\`\`\`bash
+make install
+\`\`\`
+
+On macOS/Linux, this symlinks \`src/cli.ts\` to \`~/.local/bin/kitfly\`.
+
+On Windows (Git Bash/MSYS/MINGW), it installs a small launcher script instead of a symlink (symlinks often require admin/Developer Mode).
+
+Remove with \`make uninstall\`.
+
+## Common gotchas
+
+- If \`kitfly\` isn’t found after \`make install\`, ensure \`~/.local/bin\` is on your \`PATH\`.
+- If port \`3333\` is already in use, run \`kitfly servers\` and \`kitfly stop 3333\` (or use \`--port\`).
+
+## Project Structure
+
+\`\`\`
+kitfly/
+├── src/           # Engine + CLI code
+├── scripts/       # Dev/build/bundle scripts (copied to users)
+├── content/       # Kitfly's own documentation (NOT copied)
+├── schemas/       # JSON schemas (copied to users)
+├── docs/          # Repo docs: decisions, this file
+├── AGENTS.md      # AI agent guide
+└── Makefile       # All task automation
+\`\`\`
+
+See [AGENTS.md](../AGENTS.md) for the full architecture breakdown and coding guidelines.`],
+	["guide/getting-started", "Getting Started", `# Getting Started
+
+Get your documentation site running in under a minute.
+
+## The Site Root Concept
+
+Kitfly always operates on a folder you point it at (the **site root**).
+
+That folder typically contains:
+
+- \`content/\` (or \`docs/\` or any folder you choose)
+- \`site.yaml\` (recommended) for nav + branding
+- \`theme.yaml\` (optional) for colors + typography
+
+## Create A New Site Root (Recommended)
+
+\`\`\`bash
+kitfly init my-docs
+cd my-docs
+kitfly dev
+\`\`\`
+
+Your browser opens to \`http://localhost:3333\` with hot reload.
+
+## Add Your Content
+
+1. **Delete the sample content:**
+
+   \`\`\`bash
+   rm -rf content/*
+   \`\`\`
+
+2. **Add your markdown files:**
+
+   \`\`\`bash
+   cp -r ~/my-docs/* content/
+   \`\`\`
+
+3. **Organize into sections:**
+
+   \`\`\`
+   content/
+   ├── index.md           # Home page
+   ├── guide/             # Becomes "Guide" section
+   │   ├── quickstart.md
+   │   └── tutorial.md
+   └── reference/         # Becomes "Reference" section
+       └── api.md
+   \`\`\`
+
+4. **Preview:**
+   \`\`\`bash
+   bun run dev
+   \`\`\`
+
+Subdirectories automatically become navigation sections. Files within them appear in the sidebar.
+
+## Share It
+
+\`\`\`bash
+kitfly build --out dist
+
+# Single-file bundle (easiest to email/Slack)
+kitfly bundle --out dist --name my-docs.html
+\`\`\`
+
+Output goes to \`dist/\`. You can:
+
+- **Open directly:** \`open dist/index.html\`
+- **Deploy anywhere:** GitHub Pages, Netlify, S3, any static host
+- **Share as zip:** Compress and email for review
+
+The static HTML works offline - no server required.
+
+## Frontmatter
+
+Add metadata to your markdown files:
+
+\`\`\`yaml
+---
+title: "Page Title"
+description: "Brief description"
+last_updated: "2026-02-03"
+---
+# Your Content Here
+\`\`\`
+
+- \`title\` - Appears in browser tab and header
+- \`description\` - For meta tags
+- \`last_updated\` - Shown in page footer
+
+## Next Steps
+
+- [Approaches](approaches.html) - Understand the three ways to use kitfly
+- [Kitfly Overview](kitfly-overview.html) - The big picture and workflows
+- [Features](features.html) - See code highlighting, diagrams, and more
+- [Configuration](../reference/configuration.html) - Customize \`site.yaml\`
+
+## Running From Source
+
+If you're working on the Kitfly engine itself (this repo), you can run the CLI via Bun:
+
+\`\`\`bash
+bun install
+bun run src/cli.ts dev .
+\`\`\``],
+	["guide/kitfly-overview", "Kitfly Overview", `# Kitfly Overview
+
+Kitfly helps people who aren't web developers turn a folder of writing into something shareable:
+
+- A **single-file HTML bundle** you can email or post in Slack
+- A **static site folder** you can zip and host anywhere
+
+It is intentionally small: one dependency (\`marked\`) and a codebase you can understand in an afternoon.
+
+## Mission
+
+Many people have documentation that needs to be shared: runbooks, handbooks, project docs, technical guides. The options are often:
+
+- **Too heavy**: Docusaurus, Hugo, Astro require learning build tooling
+- **Too locked**: Notion, Confluence, GitBook require accounts and subscriptions
+- **Too ugly**: Raw markdown or PDFs don't look professional
+
+Kitfly sits in the gap: professional output, minimal complexity, no lock-in.
+
+## What Kitfly Is
+
+- A renderer for markdown folders with a clean, professional default layout
+- A fast way to preview docs locally (\`kitfly dev\`)
+- A way to ship docs as artifacts (\`kitfly bundle\`, \`kitfly build\`)
+- A tool that gives you **your own copy** of the rendering code
+
+## What Kitfly Is Not
+
+Kitfly is not trying to replace full static site generators or app frameworks. These are excellent — use them when you need their power:
+
+| Tool                | Strength                        | Use When                |
+| ------------------- | ------------------------------- | ----------------------- |
+| **Obsidian**        | Personal knowledge, journaling  | You need a second brain |
+| **Docusaurus**      | React ecosystem, versioned docs | You have a dev team     |
+| **Hugo**            | Speed, themes, flexibility      | You want a powerful SSG |
+| **Astro/Starlight** | Modern, component-driven        | You need interactivity  |
+| **VitePress**       | Vue ecosystem, great DX         | You're in the Vue world |
+
+Use Kitfly when you don't need those. Your content is just markdown — migration is straightforward when you outgrow it.
+
+## Three Ways to Use Kitfly
+
+### 1. Create a Standalone Site (Primary Path)
+
+\`\`\`bash
+kitfly init my-docs
+cd my-docs
+bun install
+bun run dev
+\`\`\`
+
+This creates a **complete, self-contained site** with:
+
+\`\`\`
+my-docs/
+├── .kitfly/              # Provenance metadata
+│   └── manifest.json
+├── content/              # Your docs go here
+├── scripts/              # Rendering code (yours now)
+│   ├── dev.ts
+│   ├── build.ts
+│   └── bundle.ts
+├── src/
+│   ├── engine.ts
+│   ├── theme.ts
+│   └── site/
+│       ├── template.html
+│       └── styles.css
+├── schemas/
+├── site.yaml
+├── package.json          # { "dependencies": { "marked": "^15" } }
+└── VERSION               # Provenance: created from kitfly 0.1.0
+\`\`\`
+
+**The site is detached from kitfly.** You own the code. You can:
+
+- Modify the template, styles, rendering logic
+- Version control the whole thing (\`git init\`)
+- Never touch kitfly CLI again if you don't want to
+
+**Best for:** New documentation projects, teams who want ownership.
+
+### 2. Point at Existing Docs (Quick Preview)
+
+\`\`\`bash
+kitfly dev ./my-existing-docs
+kitfly build ./my-existing-docs --out ./dist
+kitfly bundle ./my-existing-docs --name docs.html
+\`\`\`
+
+Renders any folder of markdown without copying anything into it.
+
+**Best for:** Previewing docs that live in another repo, quick experiments.
+
+### 3. Clone the Kitfly Repo (Contributors)
+
+\`\`\`bash
+git clone https://github.com/3leaps/kitfly
+cd kitfly
+bun install
+bun run dev
+\`\`\`
+
+This is the kitfly engine repo. The \`content/\` folder **is** the kitfly documentation — you're reading it now.
+
+**Best for:** Contributing to kitfly, modifying the CLI, deep customization.
+
+## The "Fly" — How Docs Travel
+
+Kitfly makes docs "fly" by producing artifacts that travel well:
+
+| Command         | Output           | Use Case                   |
+| --------------- | ---------------- | -------------------------- |
+| \`kitfly dev\`    | Live preview     | Writing and editing        |
+| \`kitfly build\`  | \`dist/\` folder   | Deploy to any static host  |
+| \`kitfly bundle\` | Single HTML file | Email, Slack, shared drive |
+
+The bundle is typically 1-2MB and works offline — open it in any browser.
+
+## Philosophy: Minimalist Site Code
+
+The code that \`kitfly init\` copies to your project follows strict constraints:
+
+| Metric       | Target | Rationale                      |
+| ------------ | ------ | ------------------------------ |
+| Total lines  | ~500   | Understandable in an afternoon |
+| Dependencies | 1      | No supply chain risk           |
+| Files        | ~10    | Nothing hidden                 |
+
+> **Rule of thumb**: If it can be done with CSS, vanilla JS under 50 lines, or a marked plugin, it belongs. Otherwise, it doesn't.
+
+This is codified in [ADR-0001: Minimalist Site Code](../../docs/decisions/ADR-0001-minimalist-site-code.md).
+
+Users can modify the code — that's expected. But the starting point should be small enough that modification feels safe, not scary.
+
+## Provenance and Updates
+
+When you run \`kitfly init\`, the site is stamped with provenance:
+
+\`\`\`json
+// .kitfly/manifest.json
+{
+  "version": "0.1.0",
+  "createdAt": "2026-02-04T12:00:00Z",
+  "files": {
+    "scripts/dev.ts": { "hash": "a1b2c3", "managed": true },
+    ...
+  }
+}
+\`\`\`
+
+This enables future updates:
+
+\`\`\`bash
+kitfly update        # Upgrade to latest
+kitfly update 0.2.0  # Upgrade to specific version
+\`\`\`
+
+The update logic:
+
+1. Read manifest → know current version
+2. For each managed file: check if user modified it (hash comparison)
+3. Safe to replace → update file
+4. User modified → warn, offer merge/skip/force
+5. Update manifest with new version
+
+## This Repo Is the Kitfly Docs
+
+The \`content/\` folder in this repository is the actual kitfly documentation. When you run \`kitfly dev .\` here, you're seeing our docs rendered by our tool.
+
+This means:
+
+- **No fake showcase pages** — everything you see is real
+- **Features are demonstrated by use** — Mermaid diagrams, code fences, theming
+- **The docs are always current** — we eat our own cooking
+
+## Architecture Summary
+
+\`\`\`
+kitfly/                          # The tool
+├── src/cli.ts                   # CLI entry (not copied to users)
+├── src/commands/                # init, update (not copied)
+├── content/                     # Kitfly's own docs (not copied)
+│
+├── scripts/                     # ← Copied to user sites
+│   ├── dev.ts
+│   ├── build.ts
+│   └── bundle.ts
+├── src/site/                    # ← Copied to user sites
+│   ├── template.html
+│   └── styles.css
+├── src/engine.ts                # ← Copied
+├── src/theme.ts                 # ← Copied
+└── schemas/                     # ← Copied
+\`\`\`
+
+**Kitfly the tool** can grow thoughtfully (more CLI commands, smarter updates). **Site code** stays minimal.
+
+## Next Steps
+
+- [Getting Started](getting-started.md) — Set up your first site
+- [Features](features.md) — See code highlighting, Mermaid diagrams, theming
+- [Configuration](../reference/configuration.md) — Customize \`site.yaml\` and \`theme.yaml\``],
+	["reference/configuration", "Configuration", `# Configuration
+
+Kitfly uses \`site.yaml\` for configuration. Everything is optional - sensible defaults apply.
+
+## Quick Reference
+
+\`\`\`yaml
+# yaml-language-server: $schema=./schemas/v0/site.schema.json
+schemaVersion: "0.1.0"
+docroot: "content"
+title: "My Documentation"
+version: "2.4.1"
+home: "index.md"
+
+brand:
+  name: "My Project"
+  url: "https://myproject.com"
+  external: true
+
+sections:
+  - name: "Guide"
+    path: "guide"
+  - name: "API"
+    path: "api"
+
+footer:
+  copyright: "© 2026 My Project. All rights reserved."
+  links:
+    - text: "Privacy"
+      url: "/privacy"
+    - text: "Terms"
+      url: "/terms"
+  attribution: true
+\`\`\`
+
+## Settings
+
+### docroot
+
+**The most important setting.** Controls what folder contains your documentation.
+
+\`\`\`yaml
+docroot: "content"
+\`\`\`
+
+| Value       | Meaning                                    |
+| ----------- | ------------------------------------------ |
+| \`"content"\` | Markdown lives in \`content/\` (recommended) |
+| \`"docs"\`    | Markdown lives in \`docs/\`                  |
+| \`"."\`       | Markdown lives in repo root                |
+
+**Why it matters:** Only files under \`docroot\` appear in your built site. Everything else - \`src/\`, \`scripts/\`, \`README.md\`, \`package.json\` - stays out of \`dist/\`.
+
+See [Folder Structure](structure.html) for details.
+
+### dataroot (v0.2.3+)
+
+Data directory used for frontmatter \`data:\` bindings.
+
+\`\`\`yaml
+dataroot: "data"
+\`\`\`
+
+Default: \`data\`
+
+\`dataroot\` must resolve inside the site root (no \`../\`, no absolute paths). Data files are loaded at build time and are not copied into output pages.
+
+### title
+
+Site title. Appears in browser tab and header.
+
+\`\`\`yaml
+title: "My Documentation"
+\`\`\`
+
+### version
+
+Site/content version shown in the footer provenance zone.
+
+\`\`\`yaml
+version: "2.4.1"
+\`\`\`
+
+Version resolution order:
+
+1. \`site.yaml\` \`version\`
+2. Git tag on \`HEAD\` (exact match, \`v\` prefix removed)
+3. Omitted from footer provenance if neither is available
+
+### home
+
+Home page file (relative to docroot). Becomes \`index.html\`.
+
+\`\`\`yaml
+home: "index.md"
+\`\`\`
+
+If omitted, the first file from the first section is used.
+
+### brand
+
+Header branding:
+
+\`\`\`yaml
+brand:
+  name: "My Project" # Text in header
+  url: "/" # Logo link
+  logo: "assets/brand/my-logo.png" # Sidebar logo image
+  logoDark: "assets/brand/my-logo-dark.png" # Dark mode logo (optional)
+  favicon: "assets/brand/favicon-32.png" # Browser tab icon
+  external: true # Open in new tab (optional)
+\`\`\`
+
+When \`logoDark\` is set, kitfly shows it in dark mode instead of applying the default brightness filter. See the [Branding](/content/guide/branding) guide for details on dark mode variants.
+
+The logo renders inside a bounded slot that preserves aspect ratio:
+
+| Breakpoint       | Max Height | Max Width |
+| ---------------- | ---------- | --------- |
+| Desktop          | 64px       | 180px     |
+| Tablet (≤1024px) | 56px       | 150px     |
+| Mobile (≤768px)  | 48px       | 130px     |
+
+Both square marks and wide wordmarks fit cleanly. SVG and PNG formats are supported. For SVGs, ensure the \`viewBox\` is tightly cropped to the artwork — an oversized canvas will render the logo too small.
+
+### sections
+
+Navigation structure. Each section becomes a sidebar group.
+
+\`\`\`yaml
+sections:
+  - name: "Guide" # Display name
+    path: "guide" # Directory (relative to docroot)
+  - name: "Reference"
+    path: "reference"
+\`\`\`
+
+**Auto-discovery:** If \`files\` is omitted, all \`.md\` files in the directory are included, recursively up to \`maxDepth\` levels deep.
+
+\`\`\`yaml
+sections:
+  - name: "Reference"
+    path: "reference"
+    maxDepth: 6 # Discover up to 6 levels deep (default: 4, max: 10)
+\`\`\`
+
+| Setting    | Default | Range | Effect                                            |
+| ---------- | ------- | ----- | ------------------------------------------------- |
+| \`maxDepth\` | 4       | 1–10  | How many directory levels to scan for \`.md\` files |
+
+Deeper sections produce hierarchical sidebar navigation with collapsible groups. This applies to both docs and slides modes — slide decks with subfolder content get nested, collapsible nav while keeping \`#slide-N\` hash navigation. Set a lower \`maxDepth\` for sections where you want a flatter sidebar.
+
+**Explicit files:** For precise control over which files appear (bypasses auto-discovery):
+
+\`\`\`yaml
+sections:
+  - name: "Overview"
+    path: "."
+    files: ["README.md", "CHANGELOG.md"]
+\`\`\`
+
+### profiles (v0.2.3+)
+
+Named content profiles for single-source multi-audience filtering.
+
+\`\`\`yaml
+profiles:
+  alpha:
+    description: "Includes alpha-tagged content"
+    include:
+      tags: ["alpha"]
+  beta:
+    description: "Includes beta-tagged content"
+    include:
+      tags: ["beta"]
+\`\`\`
+
+Activate a profile via CLI flag or environment variable:
+
+\`\`\`bash
+kitfly dev ./mysite --profile alpha
+KITFLY_PROFILE=beta kitfly build ./mysite
+\`\`\`
+
+Files with a matching \`profile:\` frontmatter tag are included. Files without a \`profile:\` field are always included. Tagged files are excluded when no profile is active or when the active profile doesn't match.
+
+Sites without \`profiles:\` in site.yaml are completely unaffected — adding the field has no effect until a profile is explicitly activated.
+
+### prebuild (v0.2.3+)
+
+Run generator commands before \`dev\`, \`build\`, and \`bundle\`.
+
+\`\`\`yaml
+prebuild:
+  - command: "bun run scripts/generate-pricing-data.ts"
+    watch: ["data/raw/pricing-input.json"]
+  - command: "bun run scripts/generate-team-data.ts"
+\`\`\`
+
+Rules:
+
+- Hooks run sequentially in declared order.
+- Non-zero exit halts the command with hook stderr.
+- In dev mode, \`watch:\` patterns re-run matching hooks on file changes.
+- Kitfly sets \`KITFLY_SITE_ROOT\`, \`KITFLY_DATA_DIR\`, \`KITFLY_BUILD_MODE\`, and \`KITFLY_PROFILE\` (when active).
+
+### footer
+
+Footer has three zones: provenance (left), copyright and links (center), and Kitfly attribution (right). Each field is independent — setting one does not affect the others.
+
+\`\`\`
+v0.1.1 · Published 2026-02-10     © 2026 Acme Inc. · acme.com     Built with Kitfly
+← provenance (automatic)          ← copyright + links (configurable) → ← attribution →
+\`\`\`
+
+| Field          | Default                          | What it controls                          |
+| -------------- | -------------------------------- | ----------------------------------------- |
+| \`copyright\`    | \`© {publish-year} {brand.name}\`  | The copyright text in the center zone     |
+| \`copyrightUrl\` | _(none)_                         | Makes the copyright text a clickable link |
+| \`links\`        | Your \`brand.url\` shown as a link | Links after the copyright text (max 10)   |
+| \`attribution\`  | \`true\`                           | "Built with Kitfly" on the right          |
+| \`logo\`         | _(none)_                         | Image logo in the footer-left position    |
+| \`logoDark\`     | _(none)_                         | Dark mode variant of the footer logo      |
+| \`logoUrl\`      | _(none)_                         | Makes the footer logo a clickable link    |
+| \`logoAlt\`      | Copyright text or brand name     | Alt text for the footer logo              |
+| \`logoHeight\`   | \`20\`                             | Max height of footer logo in pixels       |
+
+**Common case: product name differs from copyright holder.** The default copyright uses \`brand.name\`, which is your product title (shown in the header). If your legal entity is different, override it:
+
+\`\`\`yaml
+# brand.name is "Acme Productbook" — that's the product title
+# but the copyright holder is the company
+footer:
+  copyright: "© 2026 Acme, Inc."
+\`\`\`
+
+This changes only the copyright. The brand URL link and attribution are unaffected.
+
+**Make the copyright clickable:**
+
+\`\`\`yaml
+footer:
+  copyright: "© 2026 3 Leaps, LLC"
+  copyrightUrl: "https://3leaps.net"
+\`\`\`
+
+When \`copyrightUrl\` is set, the copyright text becomes a link. When omitted, it renders as plain text.
+
+**Full example with all options:**
+
+\`\`\`yaml
+footer:
+  copyright: "© 2026 My Company, Inc."
+  copyrightUrl: "https://mycompany.com"
+  links:
+    - text: "Privacy"
+      url: "/privacy"
+    - text: "Terms"
+      url: "/terms"
+  attribution: true
+\`\`\`
+
+When \`links\` is set, it replaces the default brand URL link. When \`links\` is omitted, your \`brand.url\` appears as a link (with the protocol stripped — \`https://acme.com\` displays as \`acme.com\`).
+
+Set \`footer.attribution: false\` to remove the "Built with Kitfly" text from the footer entirely.
+
+**Footer logo** — add an image to the footer ribbon (e.g. a parent company logo):
+
+\`\`\`yaml
+footer:
+  logo: "assets/brand/footer-logo.png"
+  logoDark: "assets/brand/footer-logo-dark.png"
+  logoUrl: "https://example.com"
+  logoAlt: "Example Corp"
+  logoHeight: 24
+\`\`\`
+
+The footer logo renders at the leading edge of the ribbon, before provenance info. All footer logo fields are optional — if \`logo\` is omitted, the footer renders as text only. See the [Branding](/content/guide/branding) guide for full details.
+
+### theme layout (\`theme.yaml\`)
+
+\`theme.yaml\` can override layout variables, including sidebar width.
+
+\`\`\`yaml
+# theme.yaml
+layout:
+  sidebarWidth: "320px"
+\`\`\`
+
+This sets \`--sidebar-width\` and applies to dev server, static builds, and bundles.
+
+Recommended range: \`240px\` to \`400px\` depending on logo and nav label length.
+
+## Frontmatter
+
+Each markdown file can have YAML frontmatter:
+
+\`\`\`yaml
+---
+title: "Page Title"
+description: "Brief description for meta tags"
+last_updated: "2026-02-03"
+---
+# Content starts here
+\`\`\`
+
+| Field          | Purpose                                                             |
+| -------------- | ------------------------------------------------------------------- |
+| \`title\`        | Page title (overrides filename)                                     |
+| \`description\`  | Meta description                                                    |
+| \`last_updated\` | Shown in page footer                                                |
+| \`data\`         | Data file for \`{{ key }}\` / \`{{ snippet:name }}\` bindings (v0.2.3+) |
+| \`profile\`      | Profile tag(s) for audience filtering (v0.2.3+)                     |
+
+### \`data\` frontmatter (v0.2.3+)
+
+Bind a page to a data file for value substitution and snippet injection:
+
+\`\`\`yaml
+---
+title: "Pricing"
+data: "data/pricing.yaml"
+---
+\`\`\`
+
+The \`data:\` path is relative to site root. The data file uses a structured format:
+
+\`\`\`yaml
+globals:
+  company: "Acme Corp"
+  baseline_rate: "200"
+
+pages:
+  - path: content/product/pricing.md
+    inject:
+      hero: "Implementation and operating costs"
+    snippets:
+      - slot: pricing-table
+        content: |
+          | Tier | Price |
+          |------|-------|
+          | Basic | $10/mo |
+\`\`\`
+
+**Path convention:** \`pages[].path\` must be relative to site root including the \`content/\` prefix — e.g. \`content/product/pricing.md\`, not \`product/pricing.md\`.
+
+In the markdown body, use \`{{ key }}\` for value substitution and \`{{ snippet:name }}\` for block injection. Formatters apply with pipe syntax: \`{{ baseline_rate | dollar }}\`. See the [Data-Driven Content](/content/guide/data-driven-content) guide for the full formatter reference and generator patterns.
+
+Pages without \`data:\` frontmatter are completely unaffected — literal \`{{ }}\` text passes through as-is.
+
+### \`profile\` frontmatter (v0.2.3+)
+
+Tag a file for profile-based filtering:
+
+\`\`\`yaml
+---
+title: "Engagement Timeline"
+profile: alpha
+---
+\`\`\`
+
+Multiple profiles:
+
+\`\`\`yaml
+---
+title: "Shared Appendix"
+profile: [alpha, beta]
+---
+\`\`\`
+
+Files without a \`profile:\` field are always included regardless of which profile is active. See \`profiles\` in Settings above.
+
+## No Configuration
+
+If you don't create \`site.yaml\`, kitfly will:
+
+1. Look for \`content/\` directory
+2. Auto-discover sections from subdirectories
+3. Use default title ("Documentation") and branding
+
+This means you can start with just markdown files and add \`site.yaml\` later.
+
+## Schema Validation
+
+For editor autocomplete and validation, reference the schema:
+
+\`\`\`yaml
+# yaml-language-server: $schema=./schemas/v0/site.schema.json
+\`\`\`
+
+The schema is in \`schemas/v0/site.schema.json\`.`],
+	["reference/environment-variables", "Environment Variables", `# Environment Variables
+
+An environment variable is a named value your terminal (or hosting platform) provides to a command.
+
+Examples:
+
+- \`PORT=3333\`
+- \`AWS_PROFILE=my-team\`
+- \`NETLIFY_AUTH_TOKEN=...\`
+
+## Why they matter for deployment
+
+Kitfly’s output is static. Deployment tools often need credentials, and environment variables are a common way to provide them without putting secrets in files.
+
+Important: don’t commit secrets to git. See:
+
+- [Deployment: Secrets and Environment Variables](../deployment/secrets-and-env-vars.html)
+
+## How to set an environment variable
+
+### macOS / Linux (bash, zsh)
+
+Set for a single command:
+
+\`\`\`bash
+MY_VAR="hello" my-command
+\`\`\`
+
+Set for your current terminal session:
+
+\`\`\`bash
+export MY_VAR="hello"
+my-command
+\`\`\`
+
+### Windows (PowerShell)
+
+Set for your current session:
+
+\`\`\`powershell
+$env:MY_VAR = "hello"
+my-command
+\`\`\`
+
+## \`.env\` files (optional)
+
+Some tools can read a \`.env\` file.
+
+If you use one:
+
+- keep it local-only
+- make sure it is gitignored
+- consider adding a \`.env.example\` with placeholder values (safe to commit)
+
+## Kitfly environment variables (v0.2.3+)
+
+### \`KITFLY_PROFILE\`
+
+Activate a content profile without the \`--profile\` CLI flag:
+
+\`\`\`bash
+KITFLY_PROFILE=alpha kitfly build ./mysite
+\`\`\`
+
+Equivalent to \`kitfly build ./mysite --profile alpha\`.
+
+### Pre-build hook variables
+
+Kitfly sets these before running each \`prebuild:\` hook:
+
+| Variable            | Value                           | Example                     |
+| ------------------- | ------------------------------- | --------------------------- |
+| \`KITFLY_SITE_ROOT\`  | Absolute path to kitsite root   | \`/Users/me/my-docs\`         |
+| \`KITFLY_DATA_DIR\`   | Data directory relative to root | \`data/\`                     |
+| \`KITFLY_BUILD_MODE\` | Current build mode              | \`dev\`, \`build\`, or \`bundle\` |
+| \`KITFLY_PROFILE\`    | Active content profile (if any) | \`alpha\`                     |
+
+These allow generators to adapt behavior per build context — for example, a generator might skip expensive API calls in \`dev\` mode or produce different output per profile.
+
+## Quick troubleshooting
+
+- If a command says a variable is missing, print it:
+  - macOS/Linux: \`echo "$MY_VAR"\`
+  - PowerShell: \`echo $env:MY_VAR\`
+- If it prints empty, it’s not set in that shell session.`],
+	["reference/key-concepts", "Key Concepts", `# Key Concepts
+
+Kitfly is intentionally small. If you understand these concepts, you understand the whole tool.
+
+## Site root
+
+Your “site root” is the folder you run commands from. It usually contains:
+
+- \`site.yaml\`
+- \`content/\` (your docs)
+
+When you run \`kitfly dev\`, \`kitfly build\`, or \`kitfly bundle\`, you usually run them from your site root.
+
+## \`docroot\`
+
+\`docroot\` is the folder Kitfly renders into a site.
+
+In most projects:
+
+- \`docroot: "content"\`
+
+Think of \`docroot\` as “the folder I’m publishing”.
+
+## Sections
+
+Sections are what you see in the left navigation. Each section maps to a folder.
+
+In \`site.yaml\`, it looks like:
+
+\`\`\`yaml
+sections:
+  - name: "Guide"
+    path: "guide"
+\`\`\`
+
+If you point \`kitfly\` at a folder without a \`site.yaml\`, Kitfly can auto-discover sections from subfolders (handy for quick previews).
+
+## \`dist/\` (build output)
+
+\`kitfly build\` produces a static site folder, commonly:
+
+- \`dist/\`
+
+You deploy by uploading/syncing \`dist/\` to a static host.
+
+## Build vs Bundle vs Dev
+
+- **Dev** (\`kitfly dev\`) is for writing: it runs a local server and reloads when files change.
+- **Build** (\`kitfly build\`) is for hosting: it creates a \`dist/\` folder you can upload.
+- **Bundle** (\`kitfly bundle\`) is for sending: it creates a single HTML file you can email or drop in Slack.
+
+## Build vs Bundle
+
+- **Build**: outputs a folder (\`dist/\`) with multiple files (HTML + assets).
+- **Bundle**: outputs a single HTML file you can email or upload (offline-friendly).
+
+## Markdown + frontmatter
+
+Kitfly renders Markdown files (\`.md\`). You can optionally add YAML frontmatter at the top of a file:
+
+\`\`\`yaml
+---
+title: "My Page"
+description: "What this page is about"
+---
+\`\`\`
+
+Frontmatter is the easiest way to control titles and add metadata without changing your headings.
+
+## Theme (\`theme.yaml\`)
+
+Kitfly themes control the look of your site (colors, typography, layout details). The defaults are meant to be clean and readable.
+
+If you don’t want to think about design: don’t touch it.
+
+If you do: \`theme.yaml\` is your main “make it mine” knob.
+
+## Modes: docs vs slides (v0.2.0+)
+
+Kitfly can render the same Markdown content in two layouts:
+
+- **docs** (default): scrolling pages optimized for reading
+- **slides**: fixed-aspect "one page at a time" slides with keyboard navigation
+
+Slides mode is configured in \`site.yaml\`:
+
+\`\`\`yaml
+mode: slides
+aspect: "16/9"
+\`\`\`
+
+In both modes, organizing content into subfolders produces hierarchical sidebar navigation with collapsible groups. In slides mode, the nav links remain \`#slide-N\` hash anchors — the tree structure is visual grouping only.
+
+## Assets
+
+Kitfly will serve and bundle common “content-adjacent” assets referenced from Markdown, like images and PDFs.
+
+Rule of thumb: if it lives next to your docs, Kitfly tries to do the right thing.
+
+## Content profiles (v0.2.3+)
+
+Profiles let you produce multiple audience-specific outputs from a single kitsite. Tag files with \`profile:\` in frontmatter and activate a profile via \`--profile\` flag or \`KITFLY_PROFILE\` env var.
+
+- Files without \`profile:\` are always included (the common case).
+- Tagged files only appear when their profile is active.
+- No active profile = only untagged content.
+
+This is a startup parameter, not a runtime toggle — changing profiles requires restarting the dev server.
+
+## Data bindings (v0.2.3+)
+
+A page can opt into build-time bindings by setting \`data:\` in frontmatter.
+
+- \`{{ key }}\` resolves scalar values from a data file.
+- \`{{ snippet:name }}\` injects a named markdown block.
+- Formatters like \`dollar\`, \`number\`, \`percent\`, \`round(n)\`, \`upper\`, \`lower\` apply with pipe syntax.
+
+No loops/conditionals are supported in bindings. If you need logic, use a generator script and write data files before render.
+
+## Pre-build hooks (v0.2.3+)
+
+\`prebuild:\` commands in \`site.yaml\` run before \`dev\`, \`build\`, and \`bundle\`.
+
+Use hooks for generators (CSV/API/etc. to \`data/*.yaml\` or \`data/*.json\`). In dev mode, hook \`watch:\` patterns can re-run hooks when source files change.
+
+## Provenance
+
+Kitfly can emit provenance information (version/build date/git info) so you can answer “what did we ship?”.
+
+If you see “unversioned”, it usually means your site didn’t set a \`version\` in \`site.yaml\` and the current git commit isn’t exactly tagged.
+
+## “Static site” (plain language)
+
+A static site is just files. No server-side database, no login, no runtime code required.
+
+That’s why Kitfly sites are easy to:
+
+- host almost anywhere
+- email as an attachment (bundle)
+- keep offline`],
+	["reference/plugins", "Plugins", `# Plugins
+
+Kitfly plugins are small, optional add-ons that inject CSS and/or JS into your generated HTML.
+
+They are designed to stay minimal:
+
+- No build pipeline required
+- Offline-friendly when assets are local
+- You own the files (standalone sites copy \`registry/\` + \`plugins-dist/\`)
+
+## Enable a plugin
+
+Create \`kitfly.plugins.yaml\` in your site root:
+
+\`\`\`yaml
+# yaml-language-server: $schema=./schemas/v0/plugins.schema.json
+plugins:
+  - callouts@0.2.0
+\`\`\`
+
+Canonical plugins are referenced as pinned strings: \`name@x.y.z\`.
+
+### Canonical plugins (v0.2.4)
+
+- \`callouts@0.2.0\` - styled NOTE/TIP/INFO/WARNING/DANGER blockquotes
+- \`slides-visuals@0.2.1\` - slide widgets + figures via \`:::\` blocks (\`slides\` mode only)
+- \`latex@0.2.2\` - KaTeX math rendering for \`$...$\`, \`$$...$$\`, and fenced \`math\` blocks
+- \`slides-charts-lite@0.2.2\` - bar/line/pie charts from fenced \`chart\` blocks (\`slides\` mode only)
+- \`planning-visuals@0.2.4\` - gantt planning widget via \`:::gantt\` blocks (\`docs\` and \`slides\`)
+
+Example:
+
+\`\`\`yaml
+plugins:
+  - latex@0.2.2
+\`\`\`
+
+## Registry + assets
+
+Canonical plugins come from a registry file:
+
+- Site registry: \`registry/plugins.yaml\` (preferred if present)
+- Engine registry: used as a fallback when the site does not include a registry
+
+Registry entries map a plugin id + version to asset locations (\`assets.js\` and/or \`assets.css\`) and per-asset checksums (\`assetSha256\`).
+
+For local/offline registries, \`baseUrl\` may be an empty string.
+
+## Mode allowlist (\`modes\`)
+
+Registry entries may include an optional \`modes\` allowlist to control where a plugin runs:
+
+- Omitted: allowed in \`docs\` and \`slides\`
+- Present with values: allowed only in those modes (example: \`["slides"]\`)
+- Present but empty (\`[]\`): blocked in all modes (quick disable switch)
+
+Example:
+
+\`\`\`yaml
+plugins:
+  slides-widgets:
+    version: "0.2.0"
+    modes: ["slides"]
+    assets:
+      js: "plugins-dist/slides-widgets.js"
+      assetSha256:
+        js: "sha256:..."
+\`\`\`
+
+## Integrity checks
+
+Kitfly verifies every enabled asset against its \`sha256:<hex>\` checksum. If a checksum does not match, the build/dev server fails with an integrity error.
+
+When iterating on a local plugin (for example, editing \`plugins-dist/slides-visuals.js\`), you must also update the matching \`assetSha256\` in \`registry/plugins.yaml\` (or disable the plugin) for Kitfly to load it.
+
+## Triple-colon fence contract (\`slides-visuals\`)
+
+The \`slides-visuals\` plugin adds a \`:::\` block syntax for slides mode (widgets + figures).
+
+To keep authoring predictable and make errors actionable, Kitfly defines a strict contract for these blocks.
+When \`slides-visuals\` is enabled, Kitfly validates blocks before rendering and reports contract violations.
+
+### Valid block shape
+
+- Opening fence: \`:::<type>\` **must** start at column 0 and be the only content on the line.
+- Closing fence: \`:::\` **must** start at column 0 and be the only content on the line.
+- No blank lines inside a \`:::\` block.
+- Content is a narrow YAML subset:
+  - Scalar: \`key: value\`
+  - List: \`key:\` followed by list items
+    - List item start: exactly two spaces, then \`- \` (example: \`␠␠- label: Users\`)
+    - Continuation lines (object fields): exactly four spaces, then \`field: value\`
+
+### Supported types
+
+Widgets:
+
+- \`kpi\` (scalar keys: \`label\`, \`value\`, optional \`trend\`)
+- \`stat-grid\` (list key: \`metrics\` of \`{label,value,trend?}\` objects)
+- \`compare\` (scalar keys: \`left-title\`, \`right-title\`; list keys: \`left\`, \`right\` as **strings only**)
+
+Notes:
+
+- \`compare.left\` and \`compare.right\` items are simple strings (not \`{label: ..., value: ...}\` objects).
+- If you need multi-field items, use \`stat-grid\` / \`scorecard\` instead.
+- If an item contains a colon (\`:\`), quote it as a string.
+
+Figures:
+
+- \`quadrant-grid\` (scalar keys: \`axis-x\`, \`axis-y\`, \`tl\`, \`tr\`, \`bl\`, \`br\`)
+- \`scorecard\` (list key: \`metrics\` of \`{label,value,trend?}\` objects)
+- \`comparison-table\` (list keys: \`headers\` (strings), \`rows\` (strings))
+- \`layer-cake\` (list key: \`layers\` (strings))
+- \`pyramid\` (list key: \`levels\` (strings))
+- \`funnel\` (list key: \`stages\` (strings))
+
+### Example (valid)
+
+\`\`\`markdown
+:::stat-grid
+metrics:
+
+- label: Users
+  value: 1,234
+- label: Uptime
+  value: 99.95%
+  trend: +0.3%
+  :::
+\`\`\`
+
+### How to know it’s correct
+
+When \`slides-visuals@...\` is enabled, Kitfly validates your \`:::\` blocks before it renders pages.
+
+You know your fences are valid if:
+
+- \`kitfly dev\` starts successfully, and pages load normally
+- \`kitfly build\` completes successfully
+- \`kitfly bundle\` completes successfully
+
+If a block is invalid, Kitfly will fail fast with an error that points to the file and the specific contract rule you violated.
+
+### Common mistakes (and how to fix them)
+
+- **Indented fences**: \`:::kpi\` must start at column 0 (no spaces, no list indentation, no blockquote \`>\`).
+- **Blank lines inside the block**: remove empty lines between keys/items.
+- **Wrong list indentation**:
+  - list items must start with exactly two spaces then \`- \`
+  - fields under an item must use exactly four spaces
+- **Unknown type**: the opening fence \`:::<type>\` must be one of the supported types.
+
+### Examples (invalid → fixed)
+
+#### 1) Indented fence (invalid)
+
+\`\`\`markdown
+:::kpi
+label: Users
+value: 1,234
+:::
+\`\`\`
+
+Fixed:
+
+\`\`\`markdown
+:::kpi
+label: Users
+value: 1,234
+:::
+\`\`\`
+
+#### 2) Blank line inside block (invalid)
+
+\`\`\`markdown
+:::kpi
+label: Users
+
+value: 1,234
+:::
+\`\`\`
+
+Fixed:
+
+\`\`\`markdown
+:::kpi
+label: Users
+value: 1,234
+:::
+\`\`\`
+
+#### 3) Bad list indentation (invalid)
+
+\`\`\`markdown
+:::stat-grid
+metrics:
+
+- label: Users
+  value: 1,234
+  :::
+\`\`\`
+
+Fixed:
+
+\`\`\`markdown
+:::stat-grid
+metrics:
+
+- label: Users
+  value: 1,234
+  :::
+\`\`\`
+
+#### 4) Unknown type (invalid)
+
+\`\`\`markdown
+:::stats
+label: Users
+value: 1,234
+:::
+\`\`\`
+
+Fixed: use a supported type (for example \`kpi\`):
+
+\`\`\`markdown
+:::kpi
+label: Users
+value: 1,234
+:::
+\`\`\`
+
+## Triple-colon fence contract (\`planning-visuals\`)
+
+The \`planning-visuals\` plugin adds a \`:::gantt\` block for planning and timeline visualization. Unlike \`slides-visuals\`, it works in both \`docs\` and \`slides\` mode.
+
+Enable it in \`kitfly.plugins.yaml\`:
+
+\`\`\`yaml
+plugins:
+  - planning-visuals@0.2.4
+\`\`\`
+
+### Supported type
+
+- \`gantt\` — horizontal bar chart on a shared time axis with hierarchical depth control
+
+### Chart-level parameters
+
+| Parameter    | Required | Description                                         |
+| ------------ | -------- | --------------------------------------------------- |
+| \`time-unit\`  | yes      | Axis granularity: \`week\` or \`month\`                 |
+| \`time-start\` | yes      | Left edge. \`YYYY-Www\` for week, \`YYYY-MM\` for month |
+| \`time-end\`   | yes      | Right edge. Same format as \`time-start\`             |
+| \`label\`      | no       | Chart title, rendered above the time axis           |
+| \`max-depth\`  | no       | Maximum depth to render. \`1\` = top-level only       |
+| \`max-tracks\` | no       | Maximum rendered rows. Excess shows "+N more"       |
+| \`today\`      | no       | Renders a vertical dashed marker at this date       |
+
+### Track fields
+
+Tracks are horizontal bars spanning a start-to-end range.
+
+| Field    | Required | Default   | Description                                   |
+| -------- | -------- | --------- | --------------------------------------------- |
+| \`label\`  | yes      | —         | Track label in the left column                |
+| \`depth\`  | yes      | —         | Hierarchy level: 1, 2, or 3                   |
+| \`start\`  | yes      | —         | Bar start (format must match \`time-unit\`)     |
+| \`end\`    | yes      | —         | Bar end (format must match \`time-unit\`)       |
+| \`status\` | no       | \`planned\` | \`planned\`, \`active\`, \`complete\`, or \`blocked\` |
+
+### Milestone fields
+
+Milestones are point-in-time markers (diamond icon, not a bar). Listed separately from tracks.
+
+| Field   | Required | Default | Description                                       |
+| ------- | -------- | ------- | ------------------------------------------------- |
+| \`label\` | yes      | —       | Milestone label in the left column                |
+| \`date\`  | yes      | —       | Single date (format must match \`time-unit\`)       |
+| \`depth\` | no       | 1       | Hierarchy level, subject to \`max-depth\` filtering |
+
+### Marker fields
+
+Markers are chart-level vertical annotation lines spanning the full chart height, with a label at the top. Use them for gates, deadlines, and phase boundaries. Not subject to \`max-depth\` or \`max-tracks\` filtering.
+
+| Field   | Required | Description                                                   |
+| ------- | -------- | ------------------------------------------------------------- |
+| \`label\` | yes      | Annotation text (~20 chars recommended). Truncated if longer. |
+| \`date\`  | yes      | Position on axis (format must match \`time-unit\`)              |
+| \`color\` | no       | Marker color (\`#hex\`, \`rgb\`, named color, or CSS variable)    |
+
+Markers with dates outside the axis range produce a build-time warning and are not rendered.
+
+### Row ordering
+
+Tracks and milestones render in **source order** — the order you write them in the fence controls the visual sequence. You can interleave tracks and milestones freely.
+
+### Example (week mode)
+
+\`\`\`markdown
+:::gantt
+label: "Platform Migration — 2026"
+time-unit: week
+time-start: "2026-W14"
+time-end: "2026-W30"
+max-depth: 2
+today: "2026-W20"
+tracks:
+
+- label: "Phase 1 — Foundation"
+  depth: 1
+  start: "2026-W14"
+  end: "2026-W22"
+  status: active
+- label: "Auth Service"
+  depth: 2
+  start: "2026-W14"
+  end: "2026-W18"
+  status: complete
+- label: "Data Layer"
+  depth: 2
+  start: "2026-W17"
+  end: "2026-W22"
+  status: active
+  milestones:
+- label: "Architecture Review"
+  date: "2026-W16"
+- label: "Phase 1 Sign-Off"
+  date: "2026-W23"
+  depth: 2
+  tracks:
+- label: "Phase 2 — Integration"
+  depth: 1
+  start: "2026-W24"
+  end: "2026-W30"
+  status: planned
+  :::
+\`\`\`
+
+### Example (month mode)
+
+\`\`\`markdown
+:::gantt
+label: "Product Roadmap — H2 2026"
+time-unit: month
+time-start: "2026-07"
+time-end: "2027-01"
+tracks:
+
+- label: "Beta Program"
+  depth: 1
+  start: "2026-07"
+  end: "2026-09"
+  status: active
+- label: "GA Release"
+  depth: 1
+  start: "2026-10"
+  end: "2026-12"
+  status: planned
+  milestones:
+- label: "Launch Event"
+  date: "2026-10"
+  :::
+\`\`\`
+
+### Depth filtering
+
+The same data can drive a summary view and a detail view using \`max-depth\`:
+
+- \`max-depth: 1\` renders only depth-1 bars and milestones (wave/phase level)
+- \`max-depth: 2\` adds depth-2 items (individual workstreams)
+- Omitting \`max-depth\` shows everything
+
+### Validation
+
+When \`planning-visuals\` is enabled, Kitfly validates \`:::gantt\` blocks at build time:
+
+- Missing \`time-unit\`, \`time-start\`, \`time-end\`, or \`tracks\` is a build error
+- Tracks missing \`label\`, \`depth\`, \`start\`, or \`end\` is a build error
+- Milestones missing \`label\` or \`date\` is a build error
+- Date format must match \`time-unit\` (\`YYYY-Www\` for week, \`YYYY-MM\` for month)
+- \`time-start\` must be before \`time-end\`; track \`start\` must be before or equal to \`end\`
+- Milestones are optional — a gantt with no \`milestones:\` list is valid
+
+See [Gantt Widget Examples](gantt-widget.md) for more patterns.`],
+	["reference/structure", "Folder Structure", `# Folder Structure
+
+Understanding what's in the template and what ends up in your built site.
+
+## Template Repository
+
+When you clone kitfly, you get:
+
+\`\`\`
+kitfly/
+├── content/              # YOUR DOCS
+│   ├── index.md          # Home page
+│   ├── guide/            # Guide section
+│   └── reference/        # Reference section
+│
+├── src/                  # RENDERING MACHINERY
+│   ├── cli.ts            # CLI entry point
+│   ├── commands/         # CLI commands
+│   └── site/             # HTML template + CSS
+│
+├── scripts/              # BUILD SCRIPTS
+│   ├── dev.ts            # Dev server
+│   └── build.ts          # Static build
+│
+├── assets/               # BRAND ASSETS
+│   └── brand/            # Logo, favicon
+│
+├── dist/                 # BUILD OUTPUT (gitignored)
+│
+├── .plans/               # PLANNING (gitignored)
+│
+├── site.yaml             # CONFIGURATION
+├── package.json          # Dependencies
+├── VERSION               # Version number
+├── README.md             # GitHub readme
+├── AGENTS.md             # AI agent guide
+└── LICENSE               # MIT license
+\`\`\`
+
+## What Gets Built
+
+When you run \`bun run build\`, **only content from \`docroot\` goes into \`dist/\`**:
+
+\`\`\`
+dist/
+├── index.html            # From content/index.md
+├── guide/
+│   ├── index.html        # Redirect to first file
+│   ├── approaches.html   # From content/guide/approaches.md
+│   ├── getting-started.html
+│   └── features.html
+├── reference/
+│   ├── index.html        # Redirect to first file
+│   ├── configuration.html
+│   └── structure.html
+├── styles.css            # From src/site/styles.css
+├── provenance.json       # Build metadata
+└── assets/               # Copied from assets/
+    └── brand/
+\`\`\`
+
+**Not in dist/:**
+
+- \`src/\` - rendering code
+- \`scripts/\` - build scripts
+- \`README.md\` - GitHub readme
+- \`AGENTS.md\` - AI guide
+- \`package.json\` - dependencies
+- \`.plans/\` - planning files
+- Any other repo files
+
+This separation is intentional. Your built site is just documentation - no tooling artifacts.
+
+## The docroot Setting
+
+In \`site.yaml\`:
+
+\`\`\`yaml
+docroot: "content"
+\`\`\`
+
+This tells kitfly where to look for markdown files. Options:
+
+| Setting     | Effect                                     |
+| ----------- | ------------------------------------------ |
+| \`"content"\` | Render from \`content/\` (recommended)       |
+| \`"docs"\`    | Render from \`docs/\` (common in code repos) |
+| \`"."\`       | Render from repo root (use with care)      |
+
+### Why This Matters
+
+With \`docroot: "content"\`:
+
+- Your \`README.md\` stays on GitHub, not in the docs
+- Your \`package.json\` isn't exposed
+- You can have code, tests, and docs in the same repo
+
+With \`docroot: "."\`:
+
+- Everything in the repo root becomes documentation
+- Useful for pure documentation repos
+- You'll want to configure \`sections\` explicitly
+
+## Customizing the Template
+
+### The Machinery
+
+If you want to modify how kitfly renders:
+
+- **HTML template:** \`src/site/template.html\`
+- **Styles:** \`src/site/styles.css\`
+- **Dev server:** \`scripts/dev.ts\`
+- **Build script:** \`scripts/build.ts\`
+
+These are ~500 lines total. Read them, understand them, modify if needed.
+
+### Brand Assets
+
+Replace files in \`assets/brand/\`:
+
+- \`kitfly-logo.svg\` - Vector logo (ensure tight viewBox)
+- \`kitfly-logo-512.png\` - Used in README
+- \`kitfly-logo-128.png\` - Sidebar header fallback
+- \`kitfly-favicon-32.png\` - Browser favicon
+
+These are copied to \`dist/assets/\` during build.
+
+## For Different Use Cases
+
+### Documentation alongside code
+
+\`\`\`
+my-project/
+├── src/              # Your code
+├── tests/            # Your tests
+├── docs/             # Your documentation
+│   ├── index.md
+│   └── api/
+└── site.yaml         # docroot: "docs"
+\`\`\`
+
+### Pure documentation repo
+
+\`\`\`
+my-docs/
+├── index.md
+├── guides/
+├── reference/
+└── site.yaml         # docroot: "."
+\`\`\`
+
+### Existing markdown
+
+Point kitfly at any folder:
+
+\`\`\`bash
+kitfly dev ./path/to/markdown
+\`\`\`
+
+No need to restructure anything.`],
+	["userguide/cli", "Kitfly CLI Reference", `# Kitfly CLI Reference
+
+Command-line interface for kitfly - turn your writing into a website.
+
+## Quick Reference
+
+| Command          | Description                              |
+| ---------------- | ---------------------------------------- |
+| \`kitfly dev\`     | Start development server with hot reload |
+| \`kitfly build\`   | Build static site to dist/               |
+| \`kitfly bundle\`  | Build single-file HTML bundle            |
+| \`kitfly init\`    | Create new project from template         |
+| \`kitfly update\`  | Update standalone site code              |
+| \`kitfly servers\` | List running dev servers                 |
+| \`kitfly stop\`    | Stop dev server(s)                       |
+| \`kitfly version\` | Show version information                 |
+| \`kitfly help\`    | Show help message                        |
+
+## Global Behavior
+
+- All commands read configuration from \`site.yaml\` if present
+- Environment variables can override most options (prefixed with \`KITFLY_\`)
+- Exit codes: 0 = success, 1 = error
+
+## Command Documentation
+
+- [dev](dev.md) - Development server
+- [build](build.md) - Static site generation
+- [bundle](bundle.md) - Single-file HTML output
+- [init](init.md) - Project initialization
+- [update](update.md) - Site code updates
+- [servers](servers.md) - Server management
+- [stop](stop.md) - Stop servers
+- [version](version.md) - Version information`],
+	["userguide/cli/build", "kitfly build", `# kitfly build
+
+Build static site to output directory.
+
+## Usage
+
+\`\`\`bash
+kitfly build [folder] [options]
+\`\`\`
+
+## Description
+
+Generates a complete static HTML site from your markdown files. The output can be deployed to any static hosting service (GitHub Pages, Netlify, S3, etc.).
+
+## Arguments
+
+| Argument | Description                                                                      |
+| -------- | -------------------------------------------------------------------------------- |
+| \`folder\` | Content folder to build (default: current directory or \`docroot\` from site.yaml) |
+
+## Options
+
+| Option        | Environment Variable | Default | Description                      |
+| ------------- | -------------------- | ------- | -------------------------------- |
+| \`--out <dir>\` | \`KITFLY_BUILD_OUT\`   | dist    | Output directory                 |
+| \`--no-raw\`    | -                    | false   | Don't include raw markdown files |
+
+## Examples
+
+### Basic usage
+
+\`\`\`bash
+# Build current project
+kitfly build
+
+# Build specific folder
+kitfly build ./docs
+
+# Custom output directory
+kitfly build --out ./public
+\`\`\`
+
+### Without raw markdown
+
+\`\`\`bash
+# HTML only, no .md files in output
+kitfly build --no-raw
+\`\`\`
+
+## Output Structure
+
+\`\`\`
+dist/
+├── index.html
+├── guide/
+│   ├── getting-started.html
+│   └── getting-started.md    # (if --no-raw not specified)
+├── reference/
+│   └── ...
+└── assets/
+    └── ...
+\`\`\`
+
+## Raw Markdown Files
+
+By default, kitfly includes the original \`.md\` files alongside the generated HTML. This allows:
+
+- Downloading source for offline editing
+- Transparency about content source
+- Easy content migration
+
+Use \`--no-raw\` to exclude these files if not needed.
+
+## Plugin validation errors (triple-colon fences)
+
+Some plugins add special block syntax (for example, \`slides-visuals\` uses \`:::\` fences).
+
+When a plugin is enabled, kitfly may validate your content during the build. If validation fails, \`kitfly build\` will exit with a clear error message so you can fix the content and re-run the build.
+
+See the exact contract (with examples): \`../../../content/reference/plugins.html#triple-colon-fence-contract-slides-visuals\`.
+
+## See Also
+
+- [kitfly dev](dev.md) - Development server
+- [kitfly bundle](bundle.md) - Single-file output`],
+	["userguide/cli/bundle", "kitfly bundle", `# kitfly bundle
+
+Build single-file HTML bundle.
+
+## Usage
+
+\`\`\`bash
+kitfly bundle [folder] [options]
+\`\`\`
+
+## Description
+
+Creates a single, self-contained HTML file with all content, styles, and navigation embedded. Perfect for sharing via email, Slack, or file sharing services.
+
+## Arguments
+
+| Argument | Description                                                                       |
+| -------- | --------------------------------------------------------------------------------- |
+| \`folder\` | Content folder to bundle (default: current directory or \`docroot\` from site.yaml) |
+
+## Options
+
+| Option          | Environment Variable | Default     | Description                    |
+| --------------- | -------------------- | ----------- | ------------------------------ |
+| \`--out <dir>\`   | \`KITFLY_BUILD_OUT\`   | dist        | Output directory               |
+| \`--name <file>\` | -                    | bundle.html | Output filename                |
+| \`--raw\`         | \`KITFLY_BUILD_RAW\`   | true        | Include raw markdown in bundle |
+| \`--no-raw\`      | -                    | -           | Don't include raw markdown     |
+
+## Examples
+
+### Basic usage
+
+\`\`\`bash
+# Create bundle.html in dist/
+kitfly bundle
+
+# Custom filename
+kitfly bundle --name my-docs.html
+
+# Custom output location
+kitfly bundle --out ./release --name handbook.html
+\`\`\`
+
+## Output
+
+A single HTML file containing:
+
+- All page content with images inlined as base64 data URIs
+- Embedded CSS styles
+- Syntax highlighting (Prism.js, inlined)
+- Diagram rendering (Mermaid, inlined)
+- Navigation and table of contents
+- Dark mode support
+- Brand logo and favicon (inlined)
+- No external dependencies (works fully offline)
+
+## Use Cases
+
+- **Email attachment**: Share documentation without hosting
+- **Offline reading**: Works without internet connection
+- **Review cycles**: Send to stakeholders for feedback
+- **Archival**: Single-file snapshot of documentation
+- **Client handoff**: Portable single-file deliverable with all images embedded
+
+## File Size
+
+Bundle size depends on content volume and images. Typical documentation sites produce bundles of 100KB-1MB. Sites with many images will be larger due to base64 encoding (~33% overhead per image).
+
+## Plugin validation errors (triple-colon fences)
+
+Some plugins add special block syntax (for example, \`slides-visuals\` uses \`:::\` fences).
+
+When a plugin is enabled, kitfly may validate your content before bundling. If validation fails, \`kitfly bundle\` will exit with a clear error message so you can fix the content and re-run the bundle.
+
+See the exact contract (with examples): \`../../../content/reference/plugins.html#triple-colon-fence-contract-slides-visuals\`.
+
+## See Also
+
+- [kitfly build](build.md) - Multi-file static build
+- [kitfly dev](dev.md) - Development server`],
+	["userguide/cli/dev", "kitfly dev", `# kitfly dev
+
+Start development server with hot reload.
+
+## Usage
+
+\`\`\`bash
+kitfly dev [folder] [options]
+\`\`\`
+
+## Description
+
+Launches a local development server that renders your markdown files and automatically reloads when content changes. This is the primary command for authoring documentation.
+
+## Arguments
+
+| Argument | Description                                                                      |
+| -------- | -------------------------------------------------------------------------------- |
+| \`folder\` | Content folder to serve (default: current directory or \`docroot\` from site.yaml) |
+
+## Options
+
+| Option           | Environment Variable | Default   | Description                           |
+| ---------------- | -------------------- | --------- | ------------------------------------- |
+| \`--port <n>\`     | \`KITFLY_DEV_PORT\`    | 3333      | Server port                           |
+| \`--host <h>\`     | \`KITFLY_DEV_HOST\`    | localhost | Server host                           |
+| \`--daemon\`, \`-d\` | -                    | false     | Run in background, return immediately |
+| \`--json\`         | -                    | false     | Output JSON (implies --daemon)        |
+| \`--no-open\`      | -                    | false     | Don't open browser automatically      |
+
+## Examples
+
+### Basic usage
+
+\`\`\`bash
+# Serve current directory
+kitfly dev
+
+# Serve specific folder
+kitfly dev ./docs
+
+# Custom port
+kitfly dev --port 8080
+\`\`\`
+
+### Background mode
+
+\`\`\`bash
+# Run as daemon
+kitfly dev --daemon
+
+# Get JSON output for scripting
+kitfly dev --json
+\`\`\`
+
+### Output (JSON mode)
+
+\`\`\`json
+{
+  "pid": 12345,
+  "port": 3333,
+  "url": "http://localhost:3333"
+}
+\`\`\`
+
+## Port Conflict Detection
+
+If the specified port is already in use, kitfly will report an error rather than silently choosing another port. Use \`kitfly servers\` to see what's running.
+
+## Hot Reload
+
+The dev server watches for changes to:
+
+- Markdown files (\`.md\`)
+- Configuration (\`site.yaml\`, \`theme.yaml\`)
+- Template files
+
+Changes are reflected immediately without manual refresh.
+
+## Plugin validation errors (triple-colon fences)
+
+Some plugins add special block syntax (for example, \`slides-visuals\` uses \`:::\` fences).
+
+When a plugin is enabled, kitfly may validate your content before rendering. If validation fails, \`kitfly dev\` will exit with a clear error message so you can fix the content and restart.
+
+See the exact contract (with examples): \`../../../content/reference/plugins.html#triple-colon-fence-contract-slides-visuals\`.
+
+## See Also
+
+- [kitfly build](build.md) - Build static site
+- [kitfly servers](servers.md) - List running servers
+- [kitfly stop](stop.md) - Stop servers`],
+	["userguide/cli/init", "kitfly init", `# kitfly init
+
+Create new project from template.
+
+## Usage
+
+\`\`\`bash
+kitfly init [name] [options]
+\`\`\`
+
+## Description
+
+Initializes a new kitfly project with all necessary files and folder structure. Creates a standalone site that you own and can customize.
+
+## Arguments
+
+| Argument | Description                                         |
+| -------- | --------------------------------------------------- |
+| \`name\`   | Project directory name (default: current directory) |
+
+## Options
+
+| Option              | Description                                                          |
+| ------------------- | -------------------------------------------------------------------- |
+| \`--template <name>\` | Template to use: \`minimal\`, \`handbook\`, \`runbook\` (default: minimal) |
+| \`--standalone\`      | Create self-contained site with rendering code (default: true)       |
+| \`--brand <name>\`    | Set brand name                                                       |
+| \`--brand-url <url>\` | Set brand URL                                                        |
+
+## Templates
+
+### minimal
+
+Basic documentation site with simple structure:
+
+- Single content section
+- Clean starting point
+- Minimal example content
+
+### handbook
+
+Team/company handbook template:
+
+- Multiple sections (About, Policies, Guides, Resources)
+- Onboarding-focused structure
+- Sample policies and guides
+
+### runbook
+
+Operations runbook template:
+
+- Procedures, Troubleshooting, Reference, Incidents sections
+- Operations-focused structure
+- Incident response templates
+
+## Examples
+
+### Basic usage
+
+\`\`\`bash
+# Create in new directory
+kitfly init my-docs
+
+# Create in current directory
+kitfly init .
+
+# Use handbook template
+kitfly init company-handbook --template handbook
+\`\`\`
+
+### With branding
+
+\`\`\`bash
+kitfly init my-docs --brand "Acme Corp" --brand-url "https://acme.com"
+\`\`\`
+
+## Output Structure
+
+\`\`\`
+my-docs/
+├── content/
+│   └── index.md
+├── scripts/
+│   ├── dev.ts
+│   ├── build.ts
+│   └── bundle.ts
+├── src/
+│   └── ...
+├── site.yaml
+├── theme.yaml
+├── package.json
+└── README.md
+\`\`\`
+
+## After Initialization
+
+\`\`\`bash
+cd my-docs
+bun install
+bun run dev
+\`\`\`
+
+## Standalone Mode
+
+By default, \`kitfly init\` creates a standalone site with its own copy of:
+
+- Rendering scripts (dev, build, bundle)
+- Engine and theme code
+- Configuration schemas
+
+This means your site is independent - no kitfly CLI required after setup.
+
+## See Also
+
+- [kitfly update](update.md) - Update site code
+- [kitfly dev](dev.md) - Start development`],
+	["userguide/cli/servers", "kitfly servers", `# kitfly servers
+
+List running dev servers.
+
+## Usage
+
+\`\`\`bash
+kitfly servers [options]
+\`\`\`
+
+## Description
+
+Displays all kitfly dev servers currently running on this machine. Useful for managing multiple documentation projects or finding orphaned servers.
+
+## Options
+
+| Option   | Description    |
+| -------- | -------------- |
+| \`--json\` | Output as JSON |
+
+## Examples
+
+### Basic usage
+
+\`\`\`bash
+$ kitfly servers
+PORT   PID    PROJECT
+3333   12345  /Users/me/docs/handbook
+3340   12346  /Users/me/docs/runbook
+\`\`\`
+
+### JSON output
+
+\`\`\`bash
+$ kitfly servers --json
+[
+  {"port": 3333, "pid": 12345, "project": "/Users/me/docs/handbook"},
+  {"port": 3340, "pid": 12346, "project": "/Users/me/docs/runbook"}
+]
+\`\`\`
+
+### No servers running
+
+\`\`\`bash
+$ kitfly servers
+No kitfly servers running
+\`\`\`
+
+## Output Fields
+
+| Field     | Description            |
+| --------- | ---------------------- |
+| \`PORT\`    | Server port number     |
+| \`PID\`     | Process ID             |
+| \`PROJECT\` | Project directory path |
+
+## Server Registry
+
+Kitfly maintains a registry of running servers at:
+
+- macOS/Linux: \`~/.kitfly/servers.json\`
+- Windows: \`%USERPROFILE%\\.kitfly\\servers.json\`
+
+The registry is automatically cleaned up when servers stop normally.
+
+## See Also
+
+- [kitfly dev](dev.md) - Start a server
+- [kitfly stop](stop.md) - Stop servers`],
+	["userguide/cli/stop", "kitfly stop", `# kitfly stop
+
+Stop dev server(s).
+
+## Usage
+
+\`\`\`bash
+kitfly stop <port|all> [options]
+\`\`\`
+
+## Description
+
+Stops one or more running kitfly dev servers. Can target a specific port or stop all servers at once.
+
+## Arguments
+
+| Argument | Description                     |
+| -------- | ------------------------------- |
+| \`port\`   | Port number of server to stop   |
+| \`all\`    | Stop all running kitfly servers |
+
+## Options
+
+| Option    | Description                              |
+| --------- | ---------------------------------------- |
+| \`--force\` | Skip graceful shutdown, kill immediately |
+
+## Examples
+
+### Stop specific server
+
+\`\`\`bash
+# Stop server on port 3333
+kitfly stop 3333
+\`\`\`
+
+### Stop all servers
+
+\`\`\`bash
+# Graceful shutdown of all servers
+kitfly stop all
+\`\`\`
+
+### Force stop
+
+\`\`\`bash
+# Immediate termination (use if graceful fails)
+kitfly stop 3333 --force
+kitfly stop all --force
+\`\`\`
+
+## Graceful vs Force Shutdown
+
+**Graceful** (default):
+
+- Sends SIGTERM signal
+- Allows server to clean up
+- Waits briefly for process to exit
+
+**Force** (\`--force\`):
+
+- Sends SIGKILL signal
+- Immediate termination
+- Use when graceful shutdown hangs
+
+## Exit Codes
+
+| Code | Meaning                                           |
+| ---- | ------------------------------------------------- |
+| 0    | Server(s) stopped successfully                    |
+| 1    | Error (server not found, permission denied, etc.) |
+
+## See Also
+
+- [kitfly servers](servers.md) - List running servers
+- [kitfly dev](dev.md) - Start a server`],
+	["userguide/cli/update", "kitfly update", `# kitfly update
+
+Update standalone site code.
+
+## Usage
+
+\`\`\`bash
+kitfly update [version] [options]
+\`\`\`
+
+## Description
+
+Updates the kitfly rendering code in a standalone site to a newer version. Preserves your content and configuration while upgrading the engine.
+
+> **Note**: This command is planned for v0.2.0 and may not be fully implemented yet.
+
+## Arguments
+
+| Argument  | Description                      |
+| --------- | -------------------------------- |
+| \`version\` | Target version (default: latest) |
+
+## Options
+
+| Option      | Description                                 |
+| ----------- | ------------------------------------------- |
+| \`--dry-run\` | Preview changes without applying            |
+| \`--force\`   | Update even if local modifications detected |
+
+## Examples
+
+### Basic usage
+
+\`\`\`bash
+# Update to latest version
+kitfly update
+
+# Update to specific version
+kitfly update 0.2.0
+
+# Preview changes first
+kitfly update --dry-run
+\`\`\`
+
+## What Gets Updated
+
+- \`scripts/dev.ts\`, \`scripts/build.ts\`, \`scripts/bundle.ts\`
+- \`src/engine.ts\`, \`src/theme.ts\`
+- \`src/site/template.html\`, \`src/site/styles.css\`
+- Schema files in \`schemas/\`
+
+## What Is Preserved
+
+- \`content/\` - Your documentation
+- \`site.yaml\` - Site configuration
+- \`theme.yaml\` - Theme customization
+- Custom modifications (with warning)
+
+## Modification Detection
+
+Kitfly tracks file checksums to detect local modifications. If you've customized engine files:
+
+1. Update will warn about modifications
+2. Use \`--force\` to overwrite
+3. Or manually merge changes
+
+## Version Compatibility
+
+Updates follow semantic versioning:
+
+- **Patch** (0.1.x): Safe, backward-compatible fixes
+- **Minor** (0.x.0): New features, may need config updates
+- **Major** (x.0.0): Breaking changes, migration may be required
+
+## See Also
+
+- [kitfly init](init.md) - Create new project
+- [kitfly version](version.md) - Check current version`],
+	["userguide/cli/version", "kitfly version", `# kitfly version
+
+Show version information.
+
+## Usage
+
+\`\`\`bash
+kitfly version [extended]
+kitfly version --extended
+kitfly --version
+kitfly -v
+\`\`\`
+
+## Description
+
+Displays the current kitfly version. Use \`extended\` for detailed provenance information useful for debugging and support.
+
+## Options
+
+| Option       | Description                                      |
+| ------------ | ------------------------------------------------ |
+| \`extended\`   | Show extended version with git and platform info |
+| \`--extended\` | Same as \`extended\` subcommand                    |
+
+## Output
+
+### Basic Version
+
+\`\`\`bash
+$ kitfly version
+0.1.0
+\`\`\`
+
+### Extended Version
+
+\`\`\`bash
+$ kitfly version extended
+kitfly 0.1.0
+Git commit: b95c6a8
+Git branch: main
+Git status: clean
+Bun: 1.3.7
+Platform: darwin/arm64
+\`\`\`
+
+## Extended Output Fields
+
+| Field        | Description                                         |
+| ------------ | --------------------------------------------------- |
+| \`kitfly\`     | Current version from VERSION file                   |
+| \`Git commit\` | Short SHA of current commit                         |
+| \`Git branch\` | Current git branch name                             |
+| \`Git status\` | "clean" or "dirty (uncommitted changes)"            |
+| \`Bun\`        | Bun runtime version                                 |
+| \`Platform\`   | OS and architecture (e.g., darwin/arm64, linux/x64) |
+
+## Use Cases
+
+- **Bug reports**: Include \`kitfly version extended\` output
+- **Debugging**: Verify which version and commit is running
+- **Support**: Confirm runtime environment
+
+## See Also
+
+- [kitfly help](README.md)`],
+	["userguide/sharing", "Sharing Your Docs", `# Sharing Your Docs
+
+Kitfly has two export modes that serve different sharing needs.
+
+## Send It — Single HTML File
+
+Use \`kitfly bundle\` when you need to share docs without hosting.
+
+\`\`\`bash
+kitfly bundle --name my-docs.html
+\`\`\`
+
+This produces one self-contained HTML file with everything inlined: content, styles, images (as base64), syntax highlighting, and diagrams. No server needed — just open the file.
+
+### When to use bundle
+
+| Scenario            | Example                                 |
+| ------------------- | --------------------------------------- |
+| Email attachment    | Send docs to a client or reviewer       |
+| Slack/Teams upload  | Drop into a channel for quick reference |
+| Shared drive        | Put on Google Drive, Dropbox, OneDrive  |
+| USB/offline handoff | Works without internet                  |
+| Review cycle        | Stakeholders open in any browser        |
+| Archival            | Point-in-time snapshot of your docs     |
+
+### Bundle tips
+
+- **File size**: Typical docs produce 100KB–1MB bundles. Image-heavy sites will be larger (base64 adds ~33% overhead per image).
+- **Custom name**: Use \`--name\` to give the file a meaningful name for recipients (\`--name q1-review.html\`).
+- **Strip raw markdown**: Use \`--no-raw\` if you don't want source \`.md\` accessible inside the bundle.
+
+## Host It — Static Site
+
+Use \`kitfly build\` when you want to deploy to a web server.
+
+\`\`\`bash
+kitfly build --out ./dist
+\`\`\`
+
+This produces a \`dist/\` directory with standard HTML, CSS, and assets. Deploy it anywhere that serves static files.
+
+### Deployment targets
+
+| Platform           | How                                                                         |
+| ------------------ | --------------------------------------------------------------------------- |
+| **GitHub Pages**   | Push \`dist/\` to \`gh-pages\` branch or configure Pages to serve from a folder |
+| **Netlify**        | Set build command to \`kitfly build\`, publish directory to \`dist\`            |
+| **Vercel**         | Same pattern — build command + output directory                             |
+| **AWS S3**         | Sync \`dist/\` to an S3 bucket with static hosting enabled                    |
+| **Any web server** | Copy \`dist/\` contents to your server's document root                        |
+| **Local preview**  | \`open dist/index.html\` in your browser                                      |
+
+### Build tips
+
+- **Custom output**: \`--out ./public\` if your host expects a different directory name.
+- **Raw markdown included**: By default, \`.md\` source files are copied alongside HTML for transparency. Use \`--no-raw\` to exclude them.
+- **AI accessibility**: Build output includes \`content-index.json\`, \`llms.txt\`, and a \`_raw/\` directory so AI agents can read your docs. Use \`--no-raw\` to opt out.
+
+## Choosing Between Bundle and Build
+
+| Need                          | Use      |
+| ----------------------------- | -------- |
+| Share with one person         | \`bundle\` |
+| Share with a team (no server) | \`bundle\` |
+| Publish to the web            | \`build\`  |
+| Need search engine indexing   | \`build\`  |
+| Must work offline (no setup)  | \`bundle\` |
+| CI/CD pipeline                | \`build\`  |
+| Email attachment              | \`bundle\` |
+| GitHub Pages / Netlify        | \`build\`  |
+
+You can use both — \`bundle\` for quick reviews, \`build\` for the published site.
+
+## Development Preview
+
+During writing, use the dev server instead of building:
+
+\`\`\`bash
+kitfly dev
+\`\`\`
+
+This starts a local server at \`http://localhost:3333\` with hot reload. Edit any \`.md\` file and see changes instantly. When you're ready to share, switch to \`bundle\` or \`build\`.
+
+## See Also
+
+- [kitfly build](cli/build.md) — Build command reference
+- [kitfly bundle](cli/bundle.md) — Bundle command reference
+- [kitfly dev](cli/dev.md) — Development server`],
+];