kitfly 0.1.2 → 0.2.1

package/dist/_raw/docs/decisions/ADR-0001-minimalist-site-code.md

@@ -0,0 +1,118 @@
+---
+title: "ADR-0001: Minimalist Site Code"
+description: "Defines thresholds for the site code that kitfly copies to user projects"
+author: "devlead"
+supervised_by: "@3leapsdave"
+date: "2026-02-04"
+status: "accepted"
+tags: ["adr", "architecture", "minimalism", "site-code"]
+---
+
+# ADR-0001: Minimalist Site Code
+
+## Status
+
+Accepted
+
+## Context
+
+When users run `kitfly init`, they receive a complete, standalone site with rendering code. This code becomes **theirs** — they can modify it, version it, and maintain it.
+
+The site code must be:
+
+- **Small**: Understandable in an afternoon
+- **Reviewable**: A security-conscious user can audit it
+- **Modifiable**: Users can customize without fear
+- **Maintainable**: One dependency, no churn
+
+This ADR defines what belongs in site code vs. what stays in the kitfly CLI.
+
+## Decision
+
+### Site Code Thresholds
+
+The site code that `kitfly init` copies should stay within these bounds:
+
+| Metric                 | Target     | Hard Limit |
+| ---------------------- | ---------- | ---------- |
+| Total lines (scripts/) | ~500       | 800        |
+| Dependencies           | 1 (marked) | 2          |
+| Files copied           | ~10        | 15         |
+
+### What Belongs in Site Code
+
+| Component                | Purpose                          | Approximate Size |
+| ------------------------ | -------------------------------- | ---------------- |
+| `scripts/dev.ts`         | Dev server with hot reload       | ~400 lines       |
+| `scripts/build.ts`       | Static site generation           | ~350 lines       |
+| `scripts/bundle.ts`      | Single-file HTML output          | ~250 lines       |
+| `src/theme.ts`           | Theme loading and CSS generation | ~150 lines       |
+| `src/engine.ts`          | Path utilities                   | ~20 lines        |
+| `src/site/template.html` | HTML template                    | ~150 lines       |
+| `src/site/styles.css`    | Default styles                   | ~400 lines       |
+
+**Rule of thumb**: If it can be done with CSS, vanilla JS under 50 lines, or a marked plugin, it belongs in site code.
+
+### What Stays in Kitfly CLI
+
+| Component                | Purpose             | Reason                |
+| ------------------------ | ------------------- | --------------------- |
+| `src/cli.ts`             | CLI entry point     | Users don't need this |
+| `src/commands/init.ts`   | Project scaffolding | Meta-tooling          |
+| `src/commands/update.ts` | Site code updates   | Meta-tooling          |
+| `content/`               | Kitfly's own docs   | Not user content      |
+| `assets/brand/`          | Kitfly branding     | Users have their own  |
+
+### Feature Evaluation
+
+Before adding any feature to site code:
+
+1. **Check the line budget** — Will this exceed 800 lines?
+2. **Check the dependency count** — Does this require a new dependency?
+3. **Check the complexity** — Can a user understand this in an afternoon?
+4. **Check the necessity** — Is this core rendering, or CLI convenience?
+
+Features that fail these checks should:
+
+- Stay in the kitfly CLI (not copied to user sites)
+- Be implemented as optional user customization
+- Trigger a discussion about whether we're solving the right problem
+
+### Migration Path
+
+If site code grows beyond thresholds:
+
+1. **Refactor first** — Can we simplify?
+2. **Extract to CLI** — Move non-essential features to kitfly CLI
+3. **Document the tradeoff** — If complexity is unavoidable, explain why
+
+Users who need more should migrate to Astro, VitePress, or similar. Their content is just markdown — migration is straightforward.
+
+## Consequences
+
+### Positive
+
+- Users receive code they can actually understand
+- Security review is feasible (small surface area)
+- Modifications don't require framework knowledge
+- One `bun install` and they're running
+
+### Negative
+
+- Some features require discipline to implement minimally
+- Visual sophistication bounded by CSS capabilities
+- Power users may want more than we provide
+
+### Neutral
+
+- Feature requests require threshold evaluation
+- "Can we add X?" becomes a structured conversation
+
+## Compliance
+
+All changes to files under `scripts/`, `src/site/`, `src/engine.ts`, or `src/theme.ts` must consider this ADR. These files are copied to user projects.
+
+## References
+
+- [Kitfly Overview](../../content/guide/kitfly-overview.md) — Product philosophy
+- Handbook ADR-0001 — Original minimalist thresholds

package/dist/_raw/docs/decisions/ADR-0002-ai-accessibility.md

@@ -0,0 +1,153 @@
+---
+title: "ADR-0002: AI Accessibility for Published Sites"
+description: "Standard for making kitfly sites consumable by AI agents"
+author: "devlead"
+supervised_by: "@3leapsdave"
+date: "2026-02-04"
+status: "accepted"
+tags: ["adr", "architecture", "ai", "accessibility", "llms"]
+---
+
+# ADR-0002: AI Accessibility for Published Sites
+
+## Status
+
+Accepted
+
+## Context
+
+Kitfly sites are primarily viewed by humans in browsers. However, AI agents increasingly need to consume documentation:
+
+- Agents browsing deployed sites on cloud storage or intranets
+- LLMs researching documentation during coding tasks
+- Automated documentation indexing and search
+
+HTML parsing is inefficient for AI agents. They prefer:
+
+- Structured metadata for discovery
+- Raw markdown for content consumption
+- Predictable paths for programmatic access
+
+## Decision
+
+### Standard Files Generated
+
+Every `kitfly build` generates these AI accessibility files:
+
+#### 1. `content-index.json`
+
+Machine-readable index of all pages:
+
+```json
+{
+  "version": "0.1.0",
+  "generated": "2026-02-04T12:00:00Z",
+  "title": "Site Title",
+  "baseUrl": "/",
+  "rawMarkdownPath": "/_raw",
+  "pages": [
+    {
+      "path": "/guide/getting-started",
+      "htmlPath": "/guide/getting-started.html",
+      "rawPath": "/_raw/guide/getting-started.md",
+      "title": "Getting Started",
+      "section": "Guide",
+      "source": "content/guide/getting-started.md",
+      "description": "Optional description from frontmatter"
+    }
+  ]
+}
+```
+
+#### 2. `llms.txt`
+
+Following the emerging [llms.txt convention](https://llmstxt.org/):
+
+```
+# llms.txt - AI agent guidance for Site Title
+name: Site Title
+version: 0.1.0
+generated: 2026-02-04T12:00:00Z
+
+content-index: /content-index.json
+raw-markdown: /_raw/{path}.md
+preferred-format: markdown
+
+sections: Guide, Reference
+total-pages: 10
+```
+
+#### 3. `_raw/` Directory
+
+Raw markdown files mirroring the site structure:
+
+```
+_raw/
+├── guide/
+│   ├── getting-started.md
+│   └── features.md
+└── reference/
+    └── configuration.md
+```
+
+### Bundle Format
+
+Single-file bundles embed accessibility data as hidden JSON:
+
+```html
+<script type="application/json" id="kitfly-content-index">
+  { ... content index ... }
+</script>
+<script type="application/json" id="kitfly-raw-markdown">
+  { "guide/getting-started": "# Getting Started\n...", ... }
+</script>
+```
+
+### Opt-Out for Size-Sensitive Use Cases
+
+The `--no-raw` flag disables raw markdown for smaller output:
+
+```bash
+kitfly build --no-raw     # No _raw/ directory
+kitfly bundle --no-raw    # No embedded raw markdown
+```
+
+Content index and llms.txt are always generated (minimal overhead).
+
+## Agent Consumption Pattern
+
+An AI agent discovering a kitfly site:
+
+1. Fetch `/llms.txt` to understand the site
+2. Fetch `/content-index.json` for full page inventory
+3. Fetch raw markdown from `/_raw/{path}.md` for content
+4. Fall back to HTML parsing only if raw unavailable
+
+## Consequences
+
+### Positive
+
+- Agents can efficiently consume kitfly sites
+- Raw markdown preserves frontmatter and original formatting
+- Structured index enables smart navigation
+- Standard paths work across all kitfly sites
+- Minimal size overhead (JSON index + optional raw copies)
+
+### Negative
+
+- Slightly larger build output (mitigated by `--no-raw`)
+- Raw markdown exposes source (acceptable for docs)
+
+### Neutral
+
+- Agents may still parse HTML for sites without llms.txt
+- Convention is emerging, not yet universal
+
+## Compliance
+
+All kitfly builds must generate `content-index.json` and `llms.txt`. Raw markdown is on by default but can be disabled.
+
+## References
+
+- [llms.txt specification](https://llmstxt.org/)
+- [ADR-0001: Minimalist Site Code](ADR-0001-minimalist-site-code.md)

package/dist/_raw/docs/decisions/ADR-0003-single-file-bundle.md

@@ -0,0 +1,93 @@
+---
+title: "ADR-0003: Single-File Bundle Output"
+description: "Kitfly produces a self-contained HTML file as an alternative to static site build"
+author: "deliverylead"
+supervised_by: "@3leapsdave"
+date: "2026-02-09"
+status: "accepted"
+tags: ["adr", "bundle", "architecture", "sharing"]
+---
+
+# ADR-0003: Single-File Bundle Output
+
+## Status
+
+Accepted
+
+## Context
+
+Documentation is often shared outside of web hosting — via email, Slack uploads, shared drives, or USB handoff. Traditional static site generators produce a directory of HTML, CSS, JS, and images that require a web server or careful relative-path handling to open locally.
+
+Kitfly needed a sharing model that works without any infrastructure: one file, any browser, no server.
+
+## Decision
+
+Implement `kitfly bundle` as a first-class output mode alongside `kitfly build`. The bundle produces a **single self-contained HTML file** with all dependencies inlined.
+
+### What Gets Inlined
+
+| Asset                          | Inlining Strategy                           |
+| ------------------------------ | ------------------------------------------- |
+| CSS (styles.css)               | `<style>` block in `<head>`                 |
+| Theme CSS                      | Generated `<style id="kitfly-theme">` block |
+| Images (PNG, JPG, SVG, GIF)    | Base64 data URIs in `<img src>`             |
+| Brand logo + favicon           | Base64 data URIs                            |
+| Prism.js (syntax highlighting) | Full JS inlined in `<script>`               |
+| Mermaid (diagrams)             | Full JS inlined in `<script>`               |
+| Dark mode toggle               | Inline `<script>`                           |
+| All page content               | Inline HTML sections with `id` anchors      |
+
+### Navigation Model
+
+The bundle uses **hash-based navigation** rather than page-per-file:
+
+- Each content page becomes a `<section id="slug">` within the single document
+- Sidebar links use `href="#slug"` anchors
+- JavaScript shows/hides sections on hash change
+- The sidebar hierarchy uses the same `buildSectionNav()` function as the static build, with a hash-link adapter: `makeHref = (urlPath) => '#' + slugify(urlPath)`
+
+This ensures nav structure parity between `build` and `bundle` output.
+
+### Raw Markdown
+
+By default, raw `.md` source is embedded in the bundle as hidden `<script type="text/markdown">` blocks, accessible to AI agents. The `--no-raw` flag omits them to reduce file size.
+
+### File Size
+
+Typical documentation produces 100KB–1MB bundles. Image-heavy sites are larger due to base64 overhead (~33% per image). The tradeoff is acceptable because the primary use case is sharing, not serving at scale.
+
+## Consequences
+
+### Positive
+
+- **Zero-infrastructure sharing**: Email, Slack, Google Drive — recipients open in any browser
+- **Offline by default**: No network requests, no CDN dependencies
+- **Point-in-time snapshot**: Bundle captures exact state of docs at build time
+- **Same navigation as build**: `buildSectionNav()` shared between both output modes
+- **AI-accessible**: Raw markdown available inside the bundle
+
+### Negative
+
+- Large bundles with many images (base64 adds ~33% overhead)
+- No incremental loading — entire document loads at once
+- Hash navigation doesn't support deep-linking from external URLs (fine for the sharing use case)
+- Prism + Mermaid JS inlining adds ~500KB to every bundle
+
+### Neutral
+
+- Bundle and build share `collectFiles()`, `loadConfig()`, and `buildSectionNav()` from `shared.ts` — shared code stays in one place
+- Bundle is a separate script (`scripts/bundle.ts`) rather than a mode flag on `scripts/build.ts`, keeping each focused
+
+## Alternatives Considered
+
+### PDF export
+
+Widely shareable but loses interactivity (dark mode, collapsible nav, syntax highlighting themes). Would require a headless browser dependency (Puppeteer/Playwright). May be added later as a third output mode.
+
+### MHTML / Web Archive
+
+Browser-native single-file formats. Rejected because support is inconsistent (Safari doesn't support MHTML, Chrome's implementation has quirks) and generation requires browser automation.
+
+### ZIP of static files
+
+Solves the single-artifact problem but requires recipients to extract before viewing. Adds friction compared to double-clicking an HTML file.

package/dist/_raw/docs/decisions/ADR-0004-bun-runtime.md

@@ -0,0 +1,98 @@
+---
+title: "ADR-0004: Bun Runtime"
+description: "Kitfly uses Bun as its runtime instead of Node.js"
+author: "deliverylead"
+supervised_by: "@3leapsdave"
+date: "2026-02-09"
+status: "accepted"
+tags: ["adr", "runtime", "architecture", "tooling"]
+---
+
+# ADR-0004: Bun Runtime
+
+## Status
+
+Accepted
+
+## Context
+
+Kitfly is a TypeScript CLI tool and static site generator. It needs a JavaScript runtime that can:
+
+1. Execute TypeScript directly (no transpilation step)
+2. Run fast — dev server startup, build times, and test execution should feel instant
+3. Provide a built-in test runner (reduce dev dependencies)
+4. Support the Node.js API surface used by kitfly (fs, path, http)
+
+The project has a strict minimalism goal (ADR-0001): single production dependency (`marked`), minimal toolchain complexity.
+
+## Decision
+
+Use **Bun** as the primary runtime for development, testing, and production execution.
+
+### What Bun Provides
+
+| Capability                  | Replaces                                                   |
+| --------------------------- | ---------------------------------------------------------- |
+| Native TypeScript execution | `tsc` compilation step, `ts-node`, `tsx`                   |
+| Built-in test runner        | Separate test framework install (jest/mocha for execution) |
+| Fast startup (~25ms)        | Node.js cold start (~100-200ms)                            |
+| Built-in package manager    | npm/yarn/pnpm (for install speed)                          |
+| `Bun.serve()` HTTP server   | Express, Koa, or manual `http.createServer`                |
+
+### Runtime Boundary
+
+Kitfly's source code uses standard Node.js APIs (`node:fs/promises`, `node:path`, `node:http`) rather than Bun-specific APIs where possible. The main Bun-specific usage is:
+
+- `Bun.serve()` in the dev server (`scripts/dev.ts`)
+- `bun run` as the script executor
+- `bun test` via vitest (which uses Bun's runtime)
+
+### User Requirement
+
+Users must have Bun installed to run `kitfly`. This is documented in getting-started and enforced at CLI startup. Bun installation is a single command on all major platforms:
+
+```bash
+curl -fsSL https://bun.sh/install | bash
+```
+
+### Test Runner
+
+Tests use **vitest** running on the Bun runtime. This provides:
+
+- vitest's assertion API and test organization
+- Bun's fast execution speed
+- Watch mode for development (`bun test:watch`)
+
+## Consequences
+
+### Positive
+
+- **No build step**: TypeScript executes directly — `bun run src/cli.ts` just works
+- **Fast iteration**: Dev server starts in under 100ms, full test suite runs in ~500ms (427 tests)
+- **Fewer dependencies**: No need for `ts-node`, `tsx`, or a separate transpiler
+- **Aligned with minimalism**: Bun's built-in capabilities reduce the toolchain surface
+
+### Negative
+
+- **Bun is a user prerequisite**: Users who only have Node.js installed need to install Bun first
+- **Ecosystem maturity**: Bun is newer than Node.js — edge cases in compatibility exist (though kitfly's API surface is well-supported)
+- **CI consideration**: CI environments need Bun installed (GitHub Actions: `oven-sh/setup-bun`)
+
+### Neutral
+
+- The standard Node.js API usage means a future port to Node.js (with a TypeScript loader) is feasible if needed
+- Bun's package manager is used for `bun install` but `package.json` remains standard — compatible with npm/yarn if users prefer for dependency management
+
+## Alternatives Considered
+
+### Node.js + tsx
+
+Node.js with `tsx` for TypeScript execution. Viable but slower startup, requires additional dev dependency, and doesn't provide a built-in test runner or fast HTTP server.
+
+### Deno
+
+Native TypeScript support and built-in tooling. Rejected because Deno's module resolution (URL imports, import maps) would complicate the project structure and `kitfly init` copy model. Bun's Node.js compatibility is more aligned with kitfly's design.
+
+### Node.js + esbuild compilation
+
+Compile TypeScript to JavaScript, ship compiled output. Rejected because it adds a build step to the development workflow and contradicts the "edit and run" simplicity goal.

package/dist/_raw/docs/decisions/ADR-0005-plugin-contract-and-distribution.md

@@ -0,0 +1,110 @@
+---
+title: "ADR-0005: Plugin Contract and Distribution Strategy"
+description: "Defines plugin contract stability, versioning policy, and in-repo-first distribution with extraction path"
+author: "devlead"
+supervised_by: "@3leapsdave"
+date: "2026-02-11"
+status: "proposed"
+tags: ["adr", "plugins", "architecture", "versioning", "supply-chain"]
+---
+
+# ADR-0005: Plugin Contract and Distribution Strategy
+
+## Status
+
+Proposed
+
+## Context
+
+Kitfly v0.2.0 introduces optional plugin capabilities to support advanced use cases (starting with slides and live-slide extensions) without bloating core site code.
+
+As of M1.1, basic slide **shape primitives** remain core CSS. Plugin scope starts at higher-level figures/widgets and engine integrations where deterministic core CSS stops.
+
+Two operational choices must be explicit:
+
+1. **Contract stability**: plugin authors and site operators need a clear, versioned interface that remains predictable.
+2. **Repository strategy**: plugins can live in the main repo or a separate repo; we need a pragmatic default and a low-risk migration path.
+
+## Decision
+
+### 1. Treat plugin contract as versioned API
+
+Kitfly will define a versioned plugin contract (`plugin.schema.json` + hook semantics) as a compatibility boundary.
+
+Contract rules:
+
+- Contract version is explicit (e.g. `contract: "1"`).
+- Breaking changes require a new major contract version.
+- Backward-compatible additions are allowed within a contract major version.
+- Deprecations must include migration guidance before removal.
+
+### 2. Start plugins in-repo for v0.2.0
+
+For v0.2.0 delivery speed, first-party plugins are developed in the main kitfly repository under a dedicated plugin path and registry/config structure.
+
+Why now:
+
+- Faster iteration while contract and hooks are stabilizing.
+- Lower coordination overhead across core + plugin changes.
+- Simpler QA and dogfooding in a single branch/CI surface.
+
+### 3. Keep extraction path explicit
+
+In-repo is not permanent by requirement. Plugin layout, manifest format, and loader/registry interfaces must remain portable so plugins can move to `kitfly-plugins` later with minimal disruption.
+
+Extraction trigger signals:
+
+- plugin maintenance cadence diverges from core,
+- external contribution volume rises,
+- plugin release/security pipeline becomes materially heavier.
+
+### 4. Security and policy baseline
+
+Distribution policy applies regardless of repo location:
+
+- version pinning required,
+- checksum verification required,
+- SRI required for CDN assets,
+- untrusted third-party plugins denied by default unless explicit opt-in.
+
+## Consequences
+
+### Positive
+
+- Contract clarity reduces integration breakage and support ambiguity.
+- In-repo startup reduces delivery friction for v0.2.0.
+- Future repo split remains available without contract rewrite.
+
+### Negative
+
+- Core repo grows in scope and review surface in the short term.
+- Requires discipline to prevent plugin internals from leaking into core assumptions.
+
+### Neutral
+
+- Repo location is an implementation detail; contract/API stability is the true long-term commitment.
+
+## Compatibility Policy (Initial)
+
+- Contract v1 supported throughout v0.2.x.
+- If contract v2 is introduced, v1 support remains for at least one minor release.
+- Compatibility matrix (kitfly version ↔ contract version) must be documented in plugin docs.
+
+## Alternatives Considered
+
+### Separate plugin repo immediately
+
+Pros: cleaner ownership and release boundaries from day one.
+Cons: slower early iteration and more cross-repo coordination while contracts are still fluid.
+
+Decision: defer split until signals justify it.
+
+### No formal contract versioning
+
+Rejected: too much ambiguity and high breakage risk once plugins exist in the wild.
+
+## References
+
+- [DDR-0005: Deterministic Layout Boundary](DDR-0005-deterministic-layout-boundary.md)
+- [Design Catalog: Shapes and Figures](../../content/reference/design-catalog.md)
+- [ADR-0001: Minimalist Site Code](ADR-0001-minimalist-site-code.md)

package/dist/_raw/docs/decisions/DDR-0001-viewport-locked-layout.md

@@ -0,0 +1,111 @@
+---
+title: "DDR-0001: Viewport-Locked Layout with Fixed Footer Ribbon"
+description: "Defines the kitfly page layout model: fixed chrome (header/footer) with scrollable middle band"
+author: "uxdev"
+supervised_by: "@3leapsdave"
+date: "2026-02-06"
+status: "accepted"
+tags: ["ddr", "layout", "css", "ux"]
+---
+
+# DDR-0001: Viewport-Locked Layout with Fixed Footer Ribbon
+
+## Status
+
+Accepted
+
+## Context
+
+Kitfly sites use a three-column layout: sidebar navigation, main content, and a table-of-contents panel. The original footer was appended to the content flow with `margin-left` to offset past the sidebar, which caused several problems:
+
+- Footer only covered the content pane, not the full viewport width
+- Sidebar navigation extended below the footer, breaking visual hierarchy
+- Footer position depended on content length — short pages had it mid-screen, long pages required scrolling to find it
+- On mobile the footer needed separate margin overrides per breakpoint
+
+## Decision
+
+Adopt a **viewport-locked layout** where fixed chrome (footer ribbon, and mobile header) occupies known height at viewport edges, and the middle band (sidebar + content + TOC) fills the remaining space between them.
+
+### Layout Model
+
+```
+┌──────────────────────────────────────────────────┐
+│ (mobile header — 768px and below only)           │
+├────────────┬─────────────────────────┬───────────┤
+│            │                         │           │
+│  SIDEBAR   │       CONTENT           │   TOC     │
+│  fixed     │       scrollable        │   fixed   │
+│  left      │       center            │   right   │
+│  280px     │       flex: 1           │   200px   │
+│            │                         │           │
+│  top: 0    │  margin-left: sidebar   │  top: 6r  │
+│  bottom:   │  padding-bottom:        │           │
+│   footer   │   footer + 1rem        │           │
+│            │                         │           │
+├────────────┴─────────────────────────┴───────────┤
+│                 FOOTER RIBBON                     │
+│  position: fixed; bottom: 0; left: 0; right: 0   │
+│  height: var(--footer-height)  z-index: 300       │
+│  full-width — spans all columns                   │
+└──────────────────────────────────────────────────┘
+```
+
+### CSS Variables
+
+| Variable          | Value     | Purpose              |
+| ----------------- | --------- | -------------------- |
+| `--sidebar-width` | `280px`   | Sidebar column width |
+| `--footer-height` | `2.25rem` | Footer ribbon height |
+
+### Z-Index Stack
+
+| Layer          | Z-Index | Element                     |
+| -------------- | ------- | --------------------------- |
+| Footer ribbon  | 300     | `.site-footer`              |
+| Mobile header  | 200     | `.mobile-header`            |
+| Mobile sidebar | 100     | `.sidebar` (mobile overlay) |
+
+### Key Rules
+
+1. **Footer is viewport-fixed**, not content-appended. It uses `position: fixed; bottom: 0` and spans full width.
+2. **Sidebar stops above footer** via `bottom: var(--footer-height)` — no overlap, sidebar scrolls independently within its band.
+3. **Content has bottom padding** of `calc(var(--footer-height) + 1rem)` so the last content line is never hidden behind the footer.
+4. **Layout min-height** is `calc(100vh - var(--footer-height))` to prevent the document from extending behind the footer.
+5. **Mobile breakpoints** inherit the same `--footer-height` variable — no per-breakpoint footer overrides needed.
+6. **Print styles** hide the footer entirely (`.site-footer { display: none !important }`).
+
+### Responsive Behavior
+
+| Breakpoint | Sidebar            | TOC         | Footer                   |
+| ---------- | ------------------ | ----------- | ------------------------ |
+| > 1200px   | Fixed left         | Fixed right | Fixed bottom, full-width |
+| 769–1200px | Fixed left (240px) | Hidden      | Fixed bottom, full-width |
+| ≤ 768px    | Overlay (toggle)   | Hidden      | Fixed bottom, full-width |
+
+The footer ribbon is consistent across all breakpoints — it never changes position or width.
+
+## Consequences
+
+### Positive
+
+- Footer is always visible as a status/provenance ribbon without scrolling
+- Sidebar navigation never extends below footer
+- Single `--footer-height` variable controls all spacing — easy to adjust
+- No per-breakpoint footer margin overrides
+- Clean visual hierarchy: chrome frames content
+
+### Negative
+
+- Content needs `padding-bottom` to avoid being hidden — if `--footer-height` changes, padding must match (mitigated by using the CSS variable)
+- Fixed footer consumes ~36px of viewport permanently — acceptable for the information density it provides (version, date, copyright, brand link)
+
+## Alternatives Considered
+
+### Sticky footer (content-appended)
+
+The original approach. Footer stays in document flow but sticks to bottom on short pages. Rejected because it doesn't span the sidebar and creates layout inconsistencies across page lengths.
+
+### CSS Grid viewport layout
+
+Use `grid-template-rows: 1fr auto` on the body. Would work but requires restructuring the HTML template (moving sidebar inside a grid container). More invasive than necessary for the current fix.