npm - kitfly - Versions diffs - 0.2.1 → 0.2.3 - Mend

kitfly 0.2.1 → 0.2.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (108) hide show

package/CHANGELOG.md +56 -0
package/README.md +25 -10
package/VERSION +1 -1
package/dist/_raw/content/guide/branding.md +146 -0
package/dist/_raw/content/guide/data-driven-content.md +204 -0
package/dist/_raw/content/reference/configuration.md +145 -7
package/dist/_raw/content/reference/environment-variables.md +26 -1
package/dist/_raw/content/reference/glossary.md +25 -1
package/dist/_raw/content/reference/key-concepts.md +30 -2
package/dist/_raw/content/reference/plugins.md +14 -0
package/dist/_raw/docs/decisions/ADR-0006-data-driven-content.md +350 -0
package/dist/content/deployment/preflight.html +10 -6
package/dist/content/deployment/recipes/aws-s3.html +10 -6
package/dist/content/deployment/recipes/cloudflare-pages.html +10 -6
package/dist/content/deployment/recipes/cloudflare-r2.html +10 -6
package/dist/content/deployment/recipes/fly-io.html +10 -6
package/dist/content/deployment/recipes/github-pages.html +10 -6
package/dist/content/deployment/recipes/netlify.html +10 -6
package/dist/content/deployment/recipes/vercel.html +10 -6
package/dist/content/deployment/secrets-and-env-vars.html +10 -6
package/dist/content/deployment.html +10 -6
package/dist/content/guide/approaches.html +10 -6
package/dist/content/guide/branding.html +510 -0
package/dist/content/guide/data-driven-content.html +543 -0
package/dist/content/guide/features.html +10 -6
package/dist/content/guide/getting-started.html +10 -6
package/dist/content/guide/kitfly-overview.html +10 -6
package/dist/content/reference/configuration.html +135 -9
package/dist/content/reference/design-catalog.html +10 -6
package/dist/content/reference/environment-variables.html +50 -8
package/dist/content/reference/glossary.html +24 -8
package/dist/content/reference/key-concepts.html +33 -9
package/dist/content/reference/plugins.html +22 -7
package/dist/content/reference/slides-authoring-guidelines.html +10 -6
package/dist/content/reference/structure.html +10 -6
package/dist/content/reference.html +10 -6
package/dist/content/templates/crucible.html +10 -6
package/dist/content/templates/handbook.html +10 -6
package/dist/content/templates/minimal.html +10 -6
package/dist/content/templates/overview.html +10 -6
package/dist/content/templates/pipeline.html +10 -6
package/dist/content/templates/productbook.html +10 -6
package/dist/content/templates/runbook.html +10 -6
package/dist/content/templates/servicebook.html +10 -6
package/dist/content-index.json +29 -2
package/dist/docs/decisions/ADR-0001-minimalist-site-code.html +10 -6
package/dist/docs/decisions/ADR-0002-ai-accessibility.html +10 -6
package/dist/docs/decisions/ADR-0003-single-file-bundle.html +10 -6
package/dist/docs/decisions/ADR-0004-bun-runtime.html +10 -6
package/dist/docs/decisions/ADR-0005-plugin-contract-and-distribution.html +10 -6
package/dist/docs/decisions/ADR-0006-data-driven-content.html +752 -0
package/dist/docs/decisions/DDR-0001-viewport-locked-layout.html +10 -6
package/dist/docs/decisions/DDR-0002-theme-system.html +10 -6
package/dist/docs/decisions/DDR-0003-bounded-logo-slot.html +10 -6
package/dist/docs/decisions/DDR-0004-slides-rendering-model.html +10 -6
package/dist/docs/decisions/DDR-0005-deterministic-layout-boundary.html +10 -6
package/dist/docs/userguide/cli/build.html +10 -6
package/dist/docs/userguide/cli/bundle.html +10 -6
package/dist/docs/userguide/cli/dev.html +10 -6
package/dist/docs/userguide/cli/init.html +10 -6
package/dist/docs/userguide/cli/servers.html +10 -6
package/dist/docs/userguide/cli/stop.html +10 -6
package/dist/docs/userguide/cli/update.html +10 -6
package/dist/docs/userguide/cli/version.html +10 -6
package/dist/docs/userguide/cli.html +10 -6
package/dist/docs/userguide/sharing.html +10 -6
package/dist/index.html +10 -6
package/dist/llms.txt +3 -3
package/dist/provenance.json +4 -4
package/dist/schemas/plugin-registry.schema.html +10 -6
package/dist/schemas/plugin-schemas-notes.html +10 -6
package/dist/schemas/plugin.schema.html +10 -6
package/dist/schemas/plugins.schema.html +10 -6
package/dist/schemas/v0/common.schema.html +14 -10
package/dist/schemas/v0/plugin-registry.schema.html +13 -9
package/dist/schemas/v0/plugin.schema.html +13 -9
package/dist/schemas/v0/plugins.schema.html +13 -9
package/dist/schemas/v0/site.schema.html +67 -7
package/dist/schemas/v0/theme.schema.html +21 -17
package/dist/schemas.html +10 -6
package/dist/styles.css +39 -4
package/package.json +1 -1
package/plugins-dist/latex-runtime.js +140 -0
package/plugins-dist/latex.js +178 -0
package/plugins-dist/slides-charts-lite-runtime.js +179 -0
package/plugins-dist/slides-charts-lite.js +198 -0
package/registry/plugins.yaml +25 -0
package/schemas/v0/site.schema.json +56 -0
package/scripts/build.ts +191 -69
package/scripts/bundle.ts +118 -10
package/scripts/dev.ts +245 -166
package/src/__tests__/brief.test.ts +151 -0
package/src/__tests__/build.test.ts +169 -1
package/src/__tests__/bundle.test.ts +134 -0
package/src/__tests__/init.test.ts +51 -2
package/src/__tests__/latex-runtime.bun.test.ts +35 -0
package/src/__tests__/shared.test.ts +598 -1
package/src/__tests__/slides-charts-lite-runtime.bun.test.ts +45 -0
package/src/cli.ts +11 -4
package/src/commands/init.ts +1 -1
package/src/shared.ts +725 -18
package/src/site/styles.css +39 -4
package/src/site/template.html +5 -2
package/src/templates/brief.ts +486 -0
package/src/templates/deck.ts +59 -0
package/src/templates/driver.ts +46 -13
package/src/templates/handbook.ts +32 -0
package/src/templates/runbook.ts +32 -0

package/dist/docs/decisions/ADR-0006-data-driven-content.html ADDED Viewed

@@ -0,0 +1,752 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>ADR-0006: Data-Driven Content - Kitfly Docs</title>
+  <link rel="icon" type="image/png" sizes="32x32" href="../../assets/brand/kitfly-favicon-32.png">
+  <link rel="icon" type="image/png" sizes="64x64" href="../../assets/brand/kitfly-neon-256.png">
+  <link rel="stylesheet" href="../../styles.css">
+  <style id="kitfly-theme">
+  :root { --color-bg: #ffffff;
+    --color-bg-sidebar: #f5f7f8;
+    --color-text: #374151;
+    --color-text-muted: #6b7280;
+    --color-border: #e5e7eb;
+    --color-link: #007182;
+    --color-link-hover: #0a6172;
+    --color-accent: #152F46;
+    --color-code-bg: #f5f7f8;
+    --color-logo: #152F46;
+    --sidebar-width: 280px;
+    --font-sans: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
+    --font-headings: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
+    --font-mono: ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, monospace; }
+  html { font-size: 16px; }
+  @media (prefers-color-scheme: dark) {
+    :root:not([data-theme="light"]) { --color-bg: #0d1117;
+    --color-bg-sidebar: #152F46;
+    --color-text: #e5e7eb;
+    --color-text-muted: #9ca3af;
+    --color-border: #374151;
+    --color-link: #709EA6;
+    --color-link-hover: #8fb5bc;
+    --color-accent: #f9fafb;
+    --color-code-bg: #152F46;
+    --color-logo: #f9fafb; }
+  }
+  [data-theme="dark"] { --color-bg: #0d1117;
+    --color-bg-sidebar: #152F46;
+    --color-text: #e5e7eb;
+    --color-text-muted: #9ca3af;
+    --color-border: #374151;
+    --color-link: #709EA6;
+    --color-link-hover: #8fb5bc;
+    --color-accent: #f9fafb;
+    --color-code-bg: #152F46;
+    --color-logo: #f9fafb; }
+  [data-theme="light"] { --color-bg: #ffffff;
+    --color-bg-sidebar: #f5f7f8;
+    --color-text: #374151;
+    --color-text-muted: #6b7280;
+    --color-border: #e5e7eb;
+    --color-link: #007182;
+    --color-link-hover: #0a6172;
+    --color-accent: #152F46;
+    --color-code-bg: #f5f7f8;
+    --color-logo: #152F46;
+    --sidebar-width: 280px;
+    --font-sans: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
+    --font-headings: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
+    --font-mono: ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, monospace; }
+</style>
+  <!-- Syntax highlighting - Prism.js -->
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/prismjs@1/themes/prism.min.css" id="prism-light">
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/prismjs@1/themes/prism-okaidia.min.css" id="prism-dark" disabled>
+  <script>
+    // Apply saved theme immediately to prevent flash
+    (function() {
+      const saved = localStorage.getItem('theme');
+      if (saved) {
+        document.documentElement.setAttribute('data-theme', saved);
+      }
+      // Set Prism theme based on saved or system preference
+      const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
+      const isDark = saved === 'dark' || (!saved && prefersDark);
+      if (isDark) {
+        document.getElementById('prism-light')?.setAttribute('disabled', '');
+        document.getElementById('prism-dark')?.removeAttribute('disabled');
+      }
+    })();
+  </script>
+</head>
+<body class="mode-docs">
+  <div class="mobile-header">
+    <button class="nav-toggle" onclick="toggleNav()" aria-label="Toggle navigation">
+      <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+        <path d="M3 12h18M3 6h18M3 18h18"/>
+      </svg>
+    </button>
+    <a href="../../" class="mobile-logo" title="Home" data-initial="K">
+      <img src="../../assets/brand/kitfly-neon-256.png" alt="Kitfly" class="logo-img logo-icon"  onerror="this.onerror=null;this.style.display='none';this.parentElement.classList.add('logo-fallback')">
+    </a>
+    <button class="mobile-theme-toggle" onclick="toggleTheme()" title="Toggle theme" aria-label="Toggle theme">
+      <svg class="icon-sun" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+        <circle cx="12" cy="12" r="5"/>
+        <path d="M12 1v2M12 21v2M4.22 4.22l1.42 1.42M18.36 18.36l1.42 1.42M1 12h2M21 12h2M4.22 19.78l1.42-1.42M18.36 5.64l1.42-1.42"/>
+      </svg>
+      <svg class="icon-moon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+        <path d="M21 12.79A9 9 0 1 1 11.21 3 7 7 0 0 0 21 12.79z"/>
+      </svg>
+    </button>
+  </div>
+  <div class="layout">
+    <nav class="sidebar">
+      <div class="sidebar-header">
+        <div class="logo logo-icon">
+          <a href="/" class="logo-icon" data-initial="K">
+            <img src="../../assets/brand/kitfly-neon-256.png" alt="Kitfly" class="logo-img"  onerror="this.onerror=null;this.style.display='none';this.parentElement.classList.add('logo-fallback')">
+          </a>
+          <span class="logo-text">
+            <a href="/" class="brand">Kitfly</a>
+            <a href="../../" class="product">Kitfly Docs</a>
+          </span>
+        </div>
+        <div class="header-tools">
+          <button class="theme-toggle" onclick="toggleTheme()" title="Toggle theme" aria-label="Toggle theme">
+            <svg class="icon-sun" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+              <circle cx="12" cy="12" r="5"/>
+              <path d="M12 1v2M12 21v2M4.22 4.22l1.42 1.42M18.36 18.36l1.42 1.42M1 12h2M21 12h2M4.22 19.78l1.42-1.42M18.36 5.64l1.42-1.42"/>
+            </svg>
+            <svg class="icon-moon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+              <path d="M21 12.79A9 9 0 1 1 11.21 3 7 7 0 0 0 21 12.79z"/>
+            </svg>
+          </button>
+          <div class="sidebar-meta">
+            <span class="meta-version">v0.2.3</span>
+            <span class="meta-branch">HEAD</span>
+          </div>
+        </div>
+      </div>
+      <div class="sidebar-nav">
+        <ul><li><a href="../../index.html" class="nav-home">Home</a></li><li><span class="nav-section">Guide</span><ul><li><a href="../../content/guide/approaches.html">approaches</a></li><li><a href="../../content/guide/branding.html">branding</a></li><li><a href="../../content/guide/data-driven-content.html">data-driven-content</a></li><li><a href="../../content/guide/features.html">features</a></li><li><a href="../../content/guide/getting-started.html">getting-started</a></li><li><a href="../../content/guide/kitfly-overview.html">kitfly-overview</a></li></ul></li><li><span class="nav-section">Templates</span><ul><li><a href="../../content/templates/crucible.html">crucible</a></li><li><a href="../../content/templates/handbook.html">handbook</a></li><li><a href="../../content/templates/minimal.html">minimal</a></li><li><a href="../../content/templates/overview.html">overview</a></li><li><a href="../../content/templates/pipeline.html">pipeline</a></li><li><a href="../../content/templates/productbook.html">productbook</a></li><li><a href="../../content/templates/runbook.html">runbook</a></li><li><a href="../../content/templates/servicebook.html">servicebook</a></li></ul></li><li><a href="../../content/reference.html" class="nav-section">Reference</a><ul><li><a href="../../content/reference/configuration.html">configuration</a></li><li><a href="../../content/reference/design-catalog.html">design-catalog</a></li><li><a href="../../content/reference/environment-variables.html">environment-variables</a></li><li><a href="../../content/reference/glossary.html">glossary</a></li><li><a href="../../content/reference/key-concepts.html">key-concepts</a></li><li><a href="../../content/reference/plugins.html">plugins</a></li><li><a href="../../content/reference/slides-authoring-guidelines.html">slides-authoring-guidelines</a></li><li><a href="../../content/reference/structure.html">structure</a></li></ul></li><li><a href="../../content/deployment.html" class="nav-section">Deployment</a><ul><li><a href="../../content/deployment/preflight.html">preflight</a></li><li><details><summary class="nav-group">recipes</summary><ul><li><a href="../../content/deployment/recipes/aws-s3.html">aws-s3</a></li><li><a href="../../content/deployment/recipes/cloudflare-pages.html">cloudflare-pages</a></li><li><a href="../../content/deployment/recipes/cloudflare-r2.html">cloudflare-r2</a></li><li><a href="../../content/deployment/recipes/fly-io.html">fly-io</a></li><li><a href="../../content/deployment/recipes/github-pages.html">github-pages</a></li><li><a href="../../content/deployment/recipes/netlify.html">netlify</a></li><li><a href="../../content/deployment/recipes/vercel.html">vercel</a></li></ul></details></li><li><a href="../../content/deployment/secrets-and-env-vars.html">secrets-and-env-vars</a></li></ul></li><li><span class="nav-section">User Guide</span><ul><li><details><summary class="nav-group"><a href="../../docs/userguide/cli.html">cli</a></summary><ul><li><a href="../../docs/userguide/cli/build.html">build</a></li><li><a href="../../docs/userguide/cli/bundle.html">bundle</a></li><li><a href="../../docs/userguide/cli/dev.html">dev</a></li><li><a href="../../docs/userguide/cli/init.html">init</a></li><li><a href="../../docs/userguide/cli/servers.html">servers</a></li><li><a href="../../docs/userguide/cli/stop.html">stop</a></li><li><a href="../../docs/userguide/cli/update.html">update</a></li><li><a href="../../docs/userguide/cli/version.html">version</a></li></ul></details></li><li><a href="../../docs/userguide/sharing.html">sharing</a></li></ul></li><li><span class="nav-section">Decisions</span><ul><li><a href="../../docs/decisions/ADR-0001-minimalist-site-code.html">ADR-0001-minimalist-site-code</a></li><li><a href="../../docs/decisions/ADR-0002-ai-accessibility.html">ADR-0002-ai-accessibility</a></li><li><a href="../../docs/decisions/ADR-0003-single-file-bundle.html">ADR-0003-single-file-bundle</a></li><li><a href="../../docs/decisions/ADR-0004-bun-runtime.html">ADR-0004-bun-runtime</a></li><li><a href="../../docs/decisions/ADR-0005-plugin-contract-and-distribution.html">ADR-0005-plugin-contract-and-distribution</a></li><li><a href="../../docs/decisions/ADR-0006-data-driven-content.html" class="active">ADR-0006-data-driven-content</a></li><li><a href="../../docs/decisions/DDR-0001-viewport-locked-layout.html">DDR-0001-viewport-locked-layout</a></li><li><a href="../../docs/decisions/DDR-0002-theme-system.html">DDR-0002-theme-system</a></li><li><a href="../../docs/decisions/DDR-0003-bounded-logo-slot.html">DDR-0003-bounded-logo-slot</a></li><li><a href="../../docs/decisions/DDR-0004-slides-rendering-model.html">DDR-0004-slides-rendering-model</a></li><li><a href="../../docs/decisions/DDR-0005-deterministic-layout-boundary.html">DDR-0005-deterministic-layout-boundary</a></li></ul></li><li><a href="../../schemas.html" class="nav-section">Schemas</a><ul><li><a href="../../schemas/plugin-registry.schema.html">plugin-registry.schema</a></li><li><a href="../../schemas/plugin-schemas-notes.html">plugin-schemas-notes</a></li><li><a href="../../schemas/plugin.schema.html">plugin.schema</a></li><li><a href="../../schemas/plugins.schema.html">plugins.schema</a></li><li><details><summary class="nav-group">v0</summary><ul><li><a href="../../schemas/v0/common.schema.html">common.schema</a></li><li><a href="../../schemas/v0/plugin-registry.schema.html">plugin-registry.schema</a></li><li><a href="../../schemas/v0/plugin.schema.html">plugin.schema</a></li><li><a href="../../schemas/v0/plugins.schema.html">plugins.schema</a></li><li><a href="../../schemas/v0/site.schema.html">site.schema</a></li><li><a href="../../schemas/v0/theme.schema.html">theme.schema</a></li></ul></details></li></ul></li></ul>
+      </div>
+    </nav>
+    <main class="content">
+      <article class="prose">
+        <nav class="breadcrumbs"><a href="../../docs/userguide/cli/build.html">Docs</a><span class="separator">›</span><a href="../../docs/decisions/ADR-0001-minimalist-site-code.html">Decisions</a><span class="separator">›</span><span>ADR-0006-data-driven-content</span></nav>
+        <h1 id="adr-0006-data-driven-content">ADR-0006: Data-Driven Content</h1>
+<h2 id="status">Status</h2>
+<p>Accepted (2026-02-17)</p>
+<h2 id="context">Context</h2>
+<p>Client engagements surfaced a real pattern: pages driven by structured data. The motivating case is a pricing page where ~15 scalar values appear in prose and ~10 computed tables/diagrams are generated from a 98-line JSON data file by a 368-line Python script.</p>
+<p>Today&#39;s pipeline:</p>
+<pre><code>pricing.json → generate-pricing.py → pricing.md (complete page) → kitfly → HTML
+</code></pre>
+<p>This works, but it conflates two concerns. The Python generator owns both computation (discount percentages, marginal bracket math, worked examples) and presentation (every paragraph of prose is embedded in string concatenation). Changing a word in a paragraph means editing Python. Changing a rate means regenerating the entire page.</p>
+<p>The question is whether kitfly should provide any support for data-driven content, and if so, how much and with what constraints.</p>
+<h3 id="what-we-are-not-building">What We Are Not Building</h3>
+<p>This decision must be read against kitfly&#39;s identity. Kitfly is not a composable content framework. It is not Hugo, Eleventy, Astro, or Docusaurus. Those tools have mature data/template systems with loops, conditionals, expression evaluation, inheritance, and plugin hooks. If a project needs that power, it should use those tools.</p>
+<p>Kitfly is a minimal markdown renderer. Data-driven content support must remain consistent with that identity: small, predictable, auditable, and bounded.</p>
+<h2 id="terminology">Terminology</h2>
+<p>A <strong>kitsite</strong> is the workspace that kitfly renders — the directory tree containing <code>site.yaml</code>, <code>content/</code>, <code>data/</code>, and optionally <code>scripts/</code>. A kitsite may be a documentation site, a slide deck, or any other kitfly output mode. It is typically a git repository but does not have to be. A kitsite created by <code>kitfly init</code> is standalone: it builds with <code>bun run build</code> and requires no kitfly CLI after setup.</p>
+<p>A <strong>generator</strong> is any program that writes data files into a kitsite&#39;s data directory. Generators are user code, not kitfly code. They may live inside the kitsite (as a pre-build hook script) or outside it (as a separate service, CI step, or pipeline stage).</p>
+<h2 id="decision">Decision</h2>
+<h3 id="1-build-time-string-substitution-with-a-file-based-contract">1. Build-time string substitution with a file-based contract</h3>
+<p>Kitfly will support resolving <code>{{ key }}</code> placeholders in markdown to string values from YAML or JSON data files, and <code>{{ snippet:name }}</code> placeholders to pre-rendered markdown blocks. Resolution happens before markdown rendering. Output is deterministic: same data + same markdown = same HTML.</p>
+<p>The contract between kitfly and the outside world is the <strong>data file</strong> — not a code interface, not an import, not an API. A generator (in any language) writes a file into the kitsite. Kitfly reads and validates it. This is the entire integration surface.</p>
+<h3 id="2-the-boundary-substitution-yes-logic-no">2. The boundary: substitution yes, logic no</h3>
+<p>Kitfly handles:</p>
+<table>
+<thead>
+<tr>
+<th>Capability</th>
+<th>Example</th>
+<th>Nature</th>
+</tr>
+</thead>
+<tbody><tr>
+<td>Scalar value substitution</td>
+<td><code>{{ baseline_rate | dollar }}</code></td>
+<td>Lookup + format</td>
+</tr>
+<tr>
+<td>Snippet injection</td>
+<td><code>{{ snippet:pricing-table }}</code></td>
+<td>Named block insertion</td>
+</tr>
+<tr>
+<td>Built-in formatters</td>
+<td><code>dollar</code>, <code>number</code>, <code>percent</code>, <code>round(n)</code>, <code>upper</code>, <code>lower</code></td>
+<td>Pure display transforms</td>
+</tr>
+<tr>
+<td>Formatter chaining</td>
+<td><code>{{ key | round(0) | dollar }}</code></td>
+<td>Left-to-right composition</td>
+</tr>
+<tr>
+<td>Schema validation</td>
+<td><code>data/pricing.schema.json</code></td>
+<td>JSON Schema 2020-12</td>
+</tr>
+<tr>
+<td>Error on missing values</td>
+<td>Unresolved <code>{{ key }}</code> = build error</td>
+<td>Fail loud, never silent</td>
+</tr>
+</tbody></table>
+<p>Kitfly does not handle:</p>
+<table>
+<thead>
+<tr>
+<th>Excluded</th>
+<th>Why</th>
+</tr>
+</thead>
+<tbody><tr>
+<td>Loops (<code>{% for %}</code>)</td>
+<td>Template engine territory</td>
+</tr>
+<tr>
+<td>Conditionals (<code>{% if %}</code>)</td>
+<td>Template engine territory</td>
+</tr>
+<tr>
+<td>Expression evaluation (<code>{{ x * y }}</code>)</td>
+<td>Computation belongs in generators</td>
+</tr>
+<tr>
+<td>User-defined formatters</td>
+<td>Extensibility risk; closed set keeps contract stable</td>
+</tr>
+<tr>
+<td>Object/array iteration</td>
+<td>Pre-build hook territory</td>
+</tr>
+<tr>
+<td>Data fetching (HTTP, DB)</td>
+<td>Network I/O in builds violates determinism</td>
+</tr>
+</tbody></table>
+<p>This boundary is the core architectural decision. Everything above the line is kitfly. Everything below the line is user code, triggered by pre-build hooks. The line does not move.</p>
+<h3 id="3-formatters-are-deterministic-declarative-and-closed">3. Formatters are deterministic, declarative, and closed</h3>
+<p>Every formatter is a pure function: <code>y = f(x)</code>. String in, string out. No side effects, no data access, no branching, no state.</p>
+<p>Chaining composes left to right: <code>{{ key | round(2) | dollar }}</code> is <code>dollar(round(2, key))</code>. Each stage receives a string and returns a string. The pipeline is deterministic and testable in isolation.</p>
+<p>The formatter set is closed. Adding a formatter requires a kitfly code change, review, and release. There are no user-defined formatters, no plugin hooks into the binding layer, no runtime extension points. This constraint is deliberate: it keeps the substitution layer auditable and prevents kitfly from becoming a template engine through accumulation.</p>
+<h3 id="4-no-code-interface-for-generators">4. No code interface for generators</h3>
+<p>Kitfly does not provide a TypeScript interface, base class, or SDK for generator scripts. The contract is:</p>
+<table>
+<thead>
+<tr>
+<th>Convention</th>
+<th>Requirement</th>
+</tr>
+</thead>
+<tbody><tr>
+<td>Output location</td>
+<td>Write to <code>data/</code> with a path matching the page&#39;s <code>data:</code> frontmatter</td>
+</tr>
+<tr>
+<td>Output format</td>
+<td>YAML or JSON, conforming to schema if one exists</td>
+</tr>
+<tr>
+<td>Exit code</td>
+<td>0 on success, non-zero on failure</td>
+</tr>
+<tr>
+<td>Idempotency</td>
+<td>Same input should produce same output</td>
+</tr>
+<tr>
+<td>Language</td>
+<td>Any (TypeScript recommended if kitfly-managed; Python, Go, shell all valid)</td>
+</tr>
+<tr>
+<td>Check mode</td>
+<td>Generators SHOULD support <code>--check</code> to verify output is current without regenerating</td>
+</tr>
+</tbody></table>
+<p>This is a file-based contract. The generator writes a file; kitfly reads it. No imports, no extends, no implements. The schema is the type system. The file system is the integration bus.</p>
+<p><strong>Rationale:</strong> A code interface would couple user code to kitfly internals, exclude non-TypeScript generators, and create a dependency direction that doesn&#39;t exist today. The Unix pattern — programs communicate through files and exit codes — is more aligned with kitfly&#39;s philosophy and more portable.</p>
+<h3 id="5-pre-build-hooks-pass-environment-context">5. Pre-build hooks pass environment context</h3>
+<p>When kitfly runs a pre-build hook, it sets environment variables so the generator can discover its context without hardcoding paths:</p>
+<table>
+<thead>
+<tr>
+<th>Variable</th>
+<th>Value</th>
+<th>Example</th>
+</tr>
+</thead>
+<tbody><tr>
+<td><code>KITFLY_SITE_ROOT</code></td>
+<td>Absolute path to site root</td>
+<td><code>/Users/me/my-docs</code></td>
+</tr>
+<tr>
+<td><code>KITFLY_DATA_DIR</code></td>
+<td>Data directory relative to root</td>
+<td><code>data/</code></td>
+</tr>
+<tr>
+<td><code>KITFLY_BUILD_MODE</code></td>
+<td>Current build mode</td>
+<td><code>dev</code>, <code>build</code>, or <code>bundle</code></td>
+</tr>
+<tr>
+<td><code>KITFLY_PROFILE</code></td>
+<td>Active content profile (if any)</td>
+<td><code>internal</code></td>
+</tr>
+</tbody></table>
+<p>Generators use these or ignore them. Most simple generators (like the pricing case) won&#39;t need them — they know their own paths. The env vars exist for the case where a generator serves multiple sites or adapts to build context.</p>
+<h3 id="6-generators-are-a-first-class-concern-outside-kitfly-core">6. Generators are a first-class concern — outside kitfly core</h3>
+<p>The generator — the code that transforms external business data into kitfly&#39;s data file contract — is where real-world friction lives. Kitfly&#39;s binding layer is ~90 lines of bounded substitution. The generator that turns &quot;pricing spreadsheet managed by a VP of Sales&quot; into <code>data/pricing.yaml</code> is the actual work.</p>
+<p><strong>Data rarely belongs in the repo.</strong> In-repo JSON or YAML is a development convenience. In production, business data lives in:</p>
+<ul>
+<li>Spreadsheets (Excel, Google Sheets) maintained by business stakeholders</li>
+<li>Headless CMS platforms (Directus, Strapi, Sanity)</li>
+<li>SaaS APIs (Airtable, Notion databases, internal services)</li>
+<li>Backend-as-a-Service or configuration stores</li>
+<li>CI/CD secrets or environment-specific config</li>
+</ul>
+<p>The generator bridges that gap. Kitfly does not own generator code, but kitfly has a responsibility to make the generator&#39;s job clear and achievable.</p>
+<p><strong>What kitfly provides for generators:</strong></p>
+<table>
+<thead>
+<tr>
+<th>Layer</th>
+<th>Kitfly&#39;s contribution</th>
+</tr>
+</thead>
+<tbody><tr>
+<td>Contract</td>
+<td>The data file schema — what shape the output must take</td>
+</tr>
+<tr>
+<td>Validation</td>
+<td>Schema enforcement at build time — generators get clear error messages when output is wrong</td>
+</tr>
+<tr>
+<td>Environment</td>
+<td><code>KITFLY_*</code> env vars so generators can discover site context</td>
+</tr>
+<tr>
+<td>Conventions</td>
+<td>Documented patterns for exit codes, idempotency, <code>--check</code> mode</td>
+</tr>
+<tr>
+<td>Reference examples</td>
+<td>Documented, tested generator patterns for common data sources (CSV, API, spreadsheet)</td>
+</tr>
+</tbody></table>
+<p><strong>What kitfly does not provide:</strong></p>
+<table>
+<thead>
+<tr>
+<th>Layer</th>
+<th>Why not</th>
+</tr>
+</thead>
+<tbody><tr>
+<td>Generator SDK / base class</td>
+<td>Would couple user code to kitfly internals and exclude non-TypeScript generators</td>
+</tr>
+<tr>
+<td>Data source connectors</td>
+<td>Network I/O, auth, pagination — these are generator concerns, not build concerns</td>
+</tr>
+<tr>
+<td>Generator hosting / registry</td>
+<td>Generators are site-local scripts, not distributable packages</td>
+</tr>
+</tbody></table>
+<p><strong>Future consideration: <code>kitflygen</code> tooling.</strong> As the generator pattern matures, there may be value in a separate tool or package that scaffolds generators for common data sources: <code>kitflygen init --source airtable</code>, <code>kitflygen init --source csv</code>. This is a v0.3+ concern and a separate domain — but the data file contract defined here is designed to be stable enough to support it. Naming it now prevents us from accidentally making architectural choices that foreclose it.</p>
+<h3 id="7-the-control-plane-pattern-is-supported-not-owned">7. The control plane pattern is supported, not owned</h3>
+<p>A common architecture uses site generators as build steps in a signal-driven pipeline. Kitfly supports this pattern at two levels of complexity, depending on where the generator lives.</p>
+<p><strong>Simple: generator inside the kitsite (pre-build hook)</strong></p>
+<pre><code>External signal → CI checks out kitsite → prebuild hook runs generator → data.yaml → kitfly build → deploy
+</code></pre>
+<p>The generator is a script in <code>scripts/</code>, declared as a <code>prebuild:</code> command in site.yaml. It runs in the kitsite&#39;s environment, fetches or transforms data, and writes to <code>data/</code>. This is the default pattern for teams whose data acquisition is straightforward (single API call, CSV download, config lookup).</p>
+<p><strong>Advanced: generator outside the kitsite (separate pipeline stage)</strong></p>
+<pre><code>External signal → data pipeline runs generator → writes data files into kitsite → kitfly build → deploy
+</code></pre>
+<p>The generator lives in its own repository, service, or CI job. It has its own dependencies, credentials, and error handling. Its only interaction with the kitsite is writing schema-conforming data files into the data directory. The kitsite doesn&#39;t need to know how the data arrived — it validates and builds.</p>
+<p>This model is appropriate when:</p>
+<ul>
+<li>The generator has complex dependencies (database drivers, API clients, ML models) that don&#39;t belong in a kitsite</li>
+<li>Multiple kitsites consume output from the same generator</li>
+<li>Data acquisition requires credentials or network access that shouldn&#39;t be in the kitsite&#39;s environment</li>
+<li>The generator runs on a schedule independent of site builds</li>
+</ul>
+<p><strong>What kitfly provides for both models:</strong></p>
+<ul>
+<li>Data files are validated against schemas (the contract holds regardless of data source)</li>
+<li>Builds are deterministic (same data.yaml = same HTML, always)</li>
+<li>Exit codes propagate (pre-build hook failure = build failure)</li>
+<li>Missing or malformed data files are build errors, not silent omissions</li>
+</ul>
+<p><strong>What kitfly does not own:</strong> signal routing (that&#39;s CI/CD), data acquisition (that&#39;s the generator), deployment (that&#39;s infrastructure), and generator lifecycle (that&#39;s the team&#39;s engineering concern). Kitfly is a reliable, predictable build step in someone else&#39;s pipeline. This is the right scope.</p>
+<p>The important implication: <strong>a kitsite can be &quot;live&quot; without being dynamic.</strong> A site that rebuilds on webhook from a headless CMS delivers fresh content without client-side JavaScript, without a runtime server, without a database connection. The content is always static HTML. The pipeline is what makes it responsive to change.</p>
+<h3 id="8-data-lives-inside-the-kitsite-no-tree-escaping">8. Data lives inside the kitsite — no tree escaping</h3>
+<p>Data files in their final, schema-conforming form must reside within the kitsite workspace. The data directory (default <code>data/</code>, configurable via <code>dataroot:</code> in site.yaml) is relative to site root and must resolve within the kitsite&#39;s directory tree.</p>
+<p><strong>Containment rules:</strong></p>
+<table>
+<thead>
+<tr>
+<th>Rule</th>
+<th>Rationale</th>
+</tr>
+</thead>
+<tbody><tr>
+<td>Data paths are relative to site root</td>
+<td>Portability — the kitsite works on any machine</td>
+</tr>
+<tr>
+<td>No <code>../</code> traversal out of the kitsite</td>
+<td>Security and containment — builds are self-contained</td>
+</tr>
+<tr>
+<td>No absolute paths</td>
+<td>Portability — no machine-specific assumptions</td>
+</tr>
+<tr>
+<td>No symlinks to external locations</td>
+<td>The kitsite is the boundary; dependencies must be materialized inside it</td>
+</tr>
+<tr>
+<td>No URI schemes (<code>s3://</code>, <code>https://</code>)</td>
+<td>Data fetching belongs in generators, not in kitfly&#39;s path resolution</td>
+</tr>
+</tbody></table>
+<p><strong>The source data can be anything, anywhere.</strong> An Excel sheet on SharePoint. An Airtable base. A Directus collection. A REST API. A database query. Kitfly doesn&#39;t know and doesn&#39;t care. The generator is the adapter that bridges external data into the kitsite&#39;s data directory in a form that conforms to the schema.</p>
+<p><strong>The generator can live anywhere too.</strong> It may be a script inside the kitsite (the simple case: <code>scripts/generate-pricing-data.ts</code> run as a pre-build hook). Or it may live in a completely separate environment — a CI pipeline step, a scheduled job, a microservice that writes data files into a mounted volume or committed checkout. Kitfly&#39;s only requirement is that by build time, the data files exist inside the kitsite and pass schema validation.</p>
+<p><strong><code>dataroot:</code> configuration.</strong> The data directory name defaults to <code>data/</code> but can be overridden in site.yaml for teams that prefer <code>_data/</code>, <code>src/data/</code>, or another convention. The same containment rules apply — the path must resolve within the kitsite.</p>
+<p><strong>Typical layout — generator with external data source:</strong></p>
+<pre><code>my-kitsite/
+├── site.yaml
+├── data/
+│   ├── pricing.yaml          # OUTPUT of generator (committed or .gitignored)
+│   └── pricing.schema.json   # validates generator output
+├── content/
+│   └── product/
+│       └── pricing.md        # uses {{ key }} bindings
+└── scripts/
+    └── generate-pricing-data.ts  # pre-build hook — fetches from API/CSV/CMS
+</code></pre>
+<p><strong>Simpler layout — hand-authored data (DRY / small sites):</strong></p>
+<pre><code>my-kitsite/
+├── site.yaml
+├── data/
+│   └── team.yaml             # hand-maintained, values reused across pages
+└── content/
+    ├── about.md              # {{ lead_name }}, {{ team_size }}
+    └── contact.md            # {{ lead_email }}
+</code></pre>
+<p><strong>Automated layout — generator lives outside the kitsite:</strong></p>
+<pre><code># The kitsite (deployed, built by CI)
+my-kitsite/
+├── site.yaml
+├── data/
+│   └── pricing.yaml          # written by external pipeline before build
+├── content/
+│   └── product/
+│       └── pricing.md
+# Separate repo / service (not part of the kitsite)
+data-pipeline/
+├── generators/
+│   └── pricing-generator.ts  # fetches from Airtable, writes to kitsite/data/
+└── config/
+    └── sources.yaml          # data source credentials and endpoints
+</code></pre>
+<p>Whether <code>data/pricing.yaml</code> is committed (reproducible builds without generator) or <code>.gitignored</code> (always regenerated) is a team decision. Both patterns are valid. The schema validates the shape regardless of provenance.</p>
+<h3 id="9-error-handling-fail-loud-never-silent">9. Error handling: fail loud, never silent</h3>
+<table>
+<thead>
+<tr>
+<th>Condition</th>
+<th>Behavior</th>
+</tr>
+</thead>
+<tbody><tr>
+<td>Data file not found</td>
+<td>Build error with path context</td>
+</tr>
+<tr>
+<td>Unresolved <code>{{ key }}</code></td>
+<td>Build error — never silently empty</td>
+</tr>
+<tr>
+<td>Unknown snippet slot</td>
+<td>Build error with file and slot name</td>
+</tr>
+<tr>
+<td>Formatter parse failure</td>
+<td>Build error (e.g., <code>dollar</code> on <code>&quot;hello&quot;</code>)</td>
+</tr>
+<tr>
+<td>Unknown formatter</td>
+<td>Build error with formatter name</td>
+</tr>
+<tr>
+<td>Schema validation failure</td>
+<td>Build error with field path and constraint</td>
+</tr>
+</tbody></table>
+<p>This is non-negotiable for data-driven content. A pricing page with a missing value means publishing wrong numbers. A report with an empty <code>{{ revenue }}</code> is worse than a build failure. The system must refuse to produce output when data is incomplete.</p>
+<h2 id="constraints">Constraints</h2>
+<p>These constraints are guardrails, not limitations. They keep kitfly honest about what it is.</p>
+<ol>
+<li><p><strong>~90 lines of site code.</strong> The binding resolution layer (load data, resolve values, resolve snippets, formatters) must fit within kitfly&#39;s line budget. If it can&#39;t be implemented in ~90 lines, the design is too complex.</p>
+</li>
+<li><p><strong>No new dependencies.</strong> YAML parsing uses the existing parser in <code>shared.ts</code>. JSON Schema validation uses built-in <code>Bun</code> APIs or stays under 50 lines of hand-written validation. No ajv, no yaml library, no template engine.</p>
+</li>
+<li><p><strong>No syntax beyond <code>{{ key }}</code> and <code>{{ snippet:name }}</code>.</strong> No block tags, no comment directives, no frontmatter-driven conditionals. If you need logic, write a generator.</p>
+</li>
+<li><p><strong>Formatters are the only &quot;logic.&quot;</strong> And they are pure functions on single values. If a formatter needs to read data, branch on conditions, or access context — it doesn&#39;t belong in the formatter set.</p>
+</li>
+<li><p><strong>The file-based contract is the only integration surface.</strong> No TypeScript interfaces for generators. No kitfly SDK. No plugin hooks into the binding layer. The schema validates the shape. The file system carries the data.</p>
+</li>
+<li><p><strong>Data values are strings.</strong> Formatters handle display concerns. There is no type system, no coercion rules, no typed objects in the binding layer.</p>
+</li>
+</ol>
+<h2 id="consequences">Consequences</h2>
+<h3 id="positive">Positive</h3>
+<ul>
+<li><strong>Separation of concerns.</strong> Prose lives in markdown files that humans can read and edit. Computation lives in generator scripts. Data lives in validated YAML/JSON. Each layer does what it&#39;s good at.</li>
+<li><strong>The pricing page becomes maintainable.</strong> Changing a word in a paragraph means editing markdown. Changing a rate means editing a data file. Changing computation logic means editing a TypeScript generator. No single file owns everything.</li>
+<li><strong>Python dependency eliminated.</strong> The generator migrates to TypeScript (same ecosystem as kitfly). Not a hard requirement — the contract is language-agnostic — but a practical win for teams already using Bun.</li>
+<li><strong>Hot reload path.</strong> Pre-build hooks + data watching means: edit data → hook runs → data.yaml updates → kitfly resolves bindings → page rebuilds. No manual generator step during development.</li>
+<li><strong>CI/CD composability.</strong> Kitfly is a predictable build step. Signal-driven rebuild pipelines (webhook → generator → kitfly build → deploy) work without kitfly owning the orchestration.</li>
+<li><strong>Data externalization is a documented path.</strong> Teams are guided toward keeping business data in business systems (spreadsheets, CMS, APIs) and using generators to bridge the gap — rather than embedding data in the repo as a default.</li>
+</ul>
+<h3 id="negative">Negative</h3>
+<ul>
+<li><strong>Two-stage debugging.</strong> When a value looks wrong, you debug across two layers: is the generator producing the right data? Or is the binding resolving correctly? Mitigation: clear error messages with file, line, and key context. The <code>--check</code> convention helps CI catch stale data.</li>
+<li><strong>Snippet-heavy data files are awkward.</strong> A data file with 10 pre-rendered markdown tables is a serialized markdown artifact stored in YAML. It&#39;s generated output in a data format. This is structurally sound but aesthetically uncomfortable. Documentation should distinguish between values (simple key-value) and fragments (pre-rendered blocks).</li>
+<li><strong>The 80/20 split favors generators.</strong> For a pricing page, ~80% of content is computed (tables, diagrams, worked examples). Data bindings handle the ~20% that&#39;s scalar values in prose. Teams must understand that data bindings complement generators — they don&#39;t replace them.</li>
+<li><strong>Generator guidance is a commitment.</strong> Acknowledging generators as a first-class concern means maintaining reference patterns and documentation for common data sources. This is a content and support obligation, not a code obligation — but it&#39;s real work.</li>
+</ul>
+<h3 id="neutral">Neutral</h3>
+<ul>
+<li><strong>&quot;Can kitfly do X?&quot; has a clear answer.</strong> Lookup + format = yes. Logic + iteration = no, use a generator. The boundary is documented and stable.</li>
+<li><strong>Migration path is unchanged.</strong> Teams that outgrow this pattern — needing loops, conditionals, component composition — should migrate to Astro, Eleventy, or Hugo. Their content is still markdown. Their data files are still YAML/JSON. The migration cost is in build tooling, not content.</li>
+</ul>
+<h2 id="alternatives-considered">Alternatives Considered</h2>
+<h3 id="embed-a-template-engine-nunjucks-liquid-handlebars">Embed a template engine (Nunjucks, Liquid, Handlebars)</h3>
+<p>Rejected. Any general-purpose template engine violates kitfly&#39;s minimalist philosophy, adds a dependency, and creates a second rendering pipeline alongside marked. The incremental value over <code>{{ key }}</code> substitution is loops and conditionals — which belong in generator scripts, not in kitfly&#39;s rendering path.</p>
+<h3 id="dot-path-access-into-nested-objects-pricinguser_licenserate-">Dot-path access into nested objects (<code>{{ pricing.user_license.rate }}</code>)</h3>
+<p>Deferred. The merged proposal uses flat strings with globals + page-level inject. Dot-path access adds syntax complexity (array indices, <code>.length</code>, edge cases with missing intermediate keys). If flat strings + generators cover the real-world cases, nested access isn&#39;t needed. Can revisit based on feedback.</p>
+<h3 id="user-defined-formatters">User-defined formatters</h3>
+<p>Rejected. Extensible formatters turn kitfly into a plugin-hosting platform for display logic. The closed set (dollar, number, percent, round, upper, lower) covers the documented use cases. Adding a formatter is a kitfly code change — intentional friction that prevents scope creep.</p>
+<h3 id="typescript-interfacesdk-for-generators">TypeScript interface/SDK for generators</h3>
+<p>Rejected (see Decision §4). The file-based contract is more portable, more Unix-aligned, and doesn&#39;t create coupling between user code and kitfly internals. The schema is the type system. The file system is the integration bus.</p>
+<h3 id="data-fetching-in-the-build-pipeline-data-httpsapiexamplecompricing">Data fetching in the build pipeline (<code>data: https://api.example.com/pricing</code>)</h3>
+<p>Rejected. Network I/O in builds violates determinism and introduces failure modes kitfly cannot control (timeouts, auth, rate limits, changed APIs). Generators handle data acquisition. Kitfly handles data consumption. The boundary is the file.</p>
+<h3 id="symlinks-to-external-data-directories">Symlinks to external data directories</h3>
+<p>Rejected. Symlinks that escape the kitsite break containment, create invisible dependencies on external paths, and make the kitsite non-portable. If data lives outside the kitsite, the generator materializes it inside the kitsite before build. The data directory contains real files, not references to files.</p>
+<h3 id="arbitrary-absolute-data-paths">Arbitrary / absolute data paths</h3>
+<p>Rejected. Allowing <code>data: /opt/shared/pricing.yaml</code> or <code>data: ../other-repo/data/pricing.yaml</code> breaks portability (the kitsite doesn&#39;t clone/deploy correctly on another machine) and containment (the build depends on state outside its control). The <code>dataroot:</code> config allows naming flexibility within the kitsite; generators handle externalization.</p>
+<h2 id="compliance">Compliance</h2>
+<p>All changes to the data binding layer in <code>src/shared.ts</code>, and all pre-build hook integration in <code>scripts/dev.ts</code>, <code>scripts/build.ts</code>, and <code>scripts/bundle.ts</code>, must conform to this ADR.</p>
+<p>Feature requests that would expand the substitution syntax beyond <code>{{ key }}</code> and <code>{{ snippet:name }}</code>, or that would add logic to the binding layer, require a new ADR and explicit review.</p>
+<h2 id="references">References</h2>
+<ul>
+<li><a href="ADR-0001-minimalist-site-code.md">ADR-0001: Minimalist Site Code</a> — Line budget and feature evaluation</li>
+<li><a href="ADR-0005-plugin-contract-and-distribution.md">ADR-0005: Plugin Contract and Distribution</a> — Precedent for versioned contracts</li>
+<li><code>.plans/active/v0.2.3/explorations/data-driven-merged-proposal.md</code> — Merged proposal (deliverylead + entarch)</li>
+<li><code>.plans/active/v0.2.3/explorations/data-driven-content-schema.md</code> — Initial schema exploration</li>
+<li><code>generate-pricing.py</code> (Epiphany client site) — Motivating real-world case</li>
+</ul>
+      </article>
+      <aside class="toc"><span class="toc-title">On this page</span><ul><li><a href="#status">Status</a></li><li><a href="#context">Context</a></li><li class="toc-h3"><a href="#what-we-are-not-building">What We Are Not Building</a></li><li><a href="#terminology">Terminology</a></li><li><a href="#decision">Decision</a></li><li class="toc-h3"><a href="#1-build-time-string-substitution-with-a-file-based-contract">1. Build-time string substitution with a file-based contract</a></li><li class="toc-h3"><a href="#2-the-boundary-substitution-yes-logic-no">2. The boundary: substitution yes, logic no</a></li><li class="toc-h3"><a href="#3-formatters-are-deterministic-declarative-and-closed">3. Formatters are deterministic, declarative, and closed</a></li><li class="toc-h3"><a href="#4-no-code-interface-for-generators">4. No code interface for generators</a></li><li class="toc-h3"><a href="#5-pre-build-hooks-pass-environment-context">5. Pre-build hooks pass environment context</a></li><li class="toc-h3"><a href="#6-generators-are-a-first-class-concern-outside-kitfly-core">6. Generators are a first-class concern — outside kitfly core</a></li><li class="toc-h3"><a href="#7-the-control-plane-pattern-is-supported-not-owned">7. The control plane pattern is supported, not owned</a></li><li class="toc-h3"><a href="#8-data-lives-inside-the-kitsite-no-tree-escaping">8. Data lives inside the kitsite — no tree escaping</a></li><li class="toc-h3"><a href="#9-error-handling-fail-loud-never-silent">9. Error handling: fail loud, never silent</a></li><li><a href="#constraints">Constraints</a></li><li><a href="#consequences">Consequences</a></li><li class="toc-h3"><a href="#positive">Positive</a></li><li class="toc-h3"><a href="#negative">Negative</a></li><li class="toc-h3"><a href="#neutral">Neutral</a></li><li><a href="#alternatives-considered">Alternatives Considered</a></li><li class="toc-h3"><a href="#embed-a-template-engine-nunjucks-liquid-handlebars">Embed a template engine (Nunjucks, Liquid, Handlebars)</a></li><li class="toc-h3"><a href="#user-defined-formatters">User-defined formatters</a></li><li class="toc-h3"><a href="#typescript-interfacesdk-for-generators">TypeScript interface/SDK for generators</a></li><li class="toc-h3"><a href="#symlinks-to-external-data-directories">Symlinks to external data directories</a></li><li class="toc-h3"><a href="#arbitrary-absolute-data-paths">Arbitrary / absolute data paths</a></li><li><a href="#compliance">Compliance</a></li><li><a href="#references">References</a></li></ul></aside>
+    </main>
+  </div>
+    <footer class="site-footer">
+      <div class="footer-content">
+        <div class="footer-left">
+          <span class="footer-version">v0.2.3</span>
+          <span class="footer-separator">·</span>
+          <span class="footer-commit" title="Commit: 664328f">Published 2026-02-18</span>
+        </div>
+        <div class="footer-center">
+          <span class="footer-copyright"><a href="https://3leaps.net" class="footer-link">© 2026 3 Leaps, LLC</a></span>
+          <span class="footer-separator">·</span><a href="/" class="footer-link">Kitfly</a>
+        </div>
+        <div class="footer-right">
+          <a href="https://kitfly.dev" class="footer-link">Built with Kitfly</a>
+        </div>
+      </div>
+    </footer>
+  <!-- Syntax highlighting - Prism.js -->
+  <script src="https://cdn.jsdelivr.net/npm/prismjs@1/components/prism-core.min.js"></script>
+  <script src="https://cdn.jsdelivr.net/npm/prismjs@1/plugins/autoloader/prism-autoloader.min.js"></script>
+  <!-- Mermaid diagram support -->
+  <script type="module">
+    import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
+    function getMermaidTheme() {
+      const theme = document.documentElement.getAttribute('data-theme');
+      const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
+      const isDark = theme === 'dark' || (!theme && prefersDark);
+      return isDark ? 'dark' : 'neutral';
+    }
+    mermaid.initialize({
+      startOnLoad: true,
+      theme: getMermaidTheme()
+    });
+    // Re-render mermaid diagrams when theme changes
+    window.reinitMermaid = async function() {
+      mermaid.initialize({ startOnLoad: false, theme: getMermaidTheme() });
+      const diagrams = document.querySelectorAll('.mermaid');
+      for (const el of diagrams) {
+        const code = el.getAttribute('data-mermaid-source');
+        if (code) {
+          el.innerHTML = code;
+          el.removeAttribute('data-processed');
+        }
+      }
+      await mermaid.run({ nodes: diagrams });
+    };
+  </script>
+  <script>
+    function toggleTheme() {
+      const html = document.documentElement;
+      const current = html.getAttribute('data-theme');
+      const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
+      let next;
+      if (current === 'dark') {
+        next = 'light';
+      } else if (current === 'light') {
+        next = 'dark';
+      } else {
+        // No explicit theme set, toggle from system preference
+        next = prefersDark ? 'light' : 'dark';
+      }
+      html.setAttribute('data-theme', next);
+      localStorage.setItem('theme', next);
+      // Switch Prism theme
+      const prismLight = document.getElementById('prism-light');
+      const prismDark = document.getElementById('prism-dark');
+      if (next === 'dark') {
+        prismLight?.setAttribute('disabled', '');
+        prismDark?.removeAttribute('disabled');
+      } else {
+        prismLight?.removeAttribute('disabled');
+        prismDark?.setAttribute('disabled', '');
+      }
+      // Re-render mermaid diagrams with new theme
+      if (window.reinitMermaid) {
+        window.reinitMermaid();
+      }
+      if (window.reinitCharts) {
+        window.reinitCharts();
+      }
+    }
+    // Slides mode hash routing
+    (function initSlidesMode() {
+      const shell = document.querySelector('.slides-shell');
+      if (!shell) return;
+      const slides = Array.from(document.querySelectorAll('.slide'));
+      if (!slides.length) return;
+      const prevBtn = document.querySelector('.slide-prev');
+      const nextBtn = document.querySelector('.slide-next');
+      const counter = document.querySelector('.slide-counter');
+      const progressBar = document.querySelector('.slide-progress-bar');
+      const navLinks = Array.from(document.querySelectorAll('.sidebar-nav a[href^="#slide-"]'));
+      let current = 0;
+      function setActive(n) {
+        current = Math.max(0, Math.min(n, slides.length - 1));
+        slides.forEach((slide, idx) => slide.classList.toggle('active', idx === current));
+        navLinks.forEach((link) => {
+          const active = link.getAttribute('href') === '#' + slides[current].id;
+          link.classList.toggle('active', active);
+        });
+        if (counter) counter.textContent = (current + 1) + ' / ' + slides.length;
+        if (progressBar) progressBar.style.width = (((current + 1) / slides.length) * 100) + '%';
+        if (prevBtn) prevBtn.disabled = current === 0;
+        if (nextBtn) nextBtn.disabled = current === slides.length - 1;
+        history.replaceState(null, '', '#' + slides[current].id);
+      }
+      function setFromHash() {
+        const hash = window.location.hash || '';
+        const idx = slides.findIndex((s) => '#' + s.id === hash);
+        if (idx >= 0) setActive(idx);
+        else setActive(0);
+      }
+      prevBtn?.addEventListener('click', () => setActive(current - 1));
+      nextBtn?.addEventListener('click', () => setActive(current + 1));
+      document.addEventListener('keydown', (e) => {
+        if (e.key === 'ArrowRight' || e.key === ' ') {
+          e.preventDefault();
+          setActive(current + 1);
+        } else if (e.key === 'ArrowLeft') {
+          e.preventDefault();
+          setActive(current - 1);
+        } else if (e.key === 'Home') {
+          e.preventDefault();
+          setActive(0);
+        } else if (e.key === 'End') {
+          e.preventDefault();
+          setActive(slides.length - 1);
+        }
+      });
+      window.addEventListener('hashchange', setFromHash);
+      setFromHash();
+    })();
+    // Copy code button
+    document.querySelectorAll('.prose pre code').forEach(block => {
+      const button = document.createElement('button');
+      button.className = 'copy-button';
+      button.textContent = 'Copy';
+      button.onclick = async () => {
+        await navigator.clipboard.writeText(block.textContent);
+        button.textContent = 'Copied!';
+        setTimeout(() => button.textContent = 'Copy', 2000);
+      };
+      block.parentElement.appendChild(button);
+    });
+    // Mobile nav toggle
+    function toggleNav() {
+      document.querySelector('.sidebar').classList.toggle('open');
+    }
+    // Close nav when clicking outside on mobile
+    document.addEventListener('click', (e) => {
+      const sidebar = document.querySelector('.sidebar');
+      const toggle = document.querySelector('.nav-toggle');
+      if (sidebar.classList.contains('open') &&
+          !sidebar.contains(e.target) &&
+          !toggle.contains(e.target)) {
+        sidebar.classList.remove('open');
+      }
+    });
+  </script>
+</body>
+</html>