kitfly 0.1.2 → 0.2.0

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 (194) hide show
  1. package/CHANGELOG.md +34 -0
  2. package/README.md +63 -16
  3. package/VERSION +1 -1
  4. package/dist/_raw/content/deployment/preflight.md +134 -0
  5. package/dist/_raw/content/deployment/recipes/aws-s3.md +128 -0
  6. package/dist/_raw/content/deployment/recipes/cloudflare-pages.md +73 -0
  7. package/dist/_raw/content/deployment/recipes/cloudflare-r2.md +156 -0
  8. package/dist/_raw/content/deployment/recipes/fly-io.md +57 -0
  9. package/dist/_raw/content/deployment/recipes/github-pages.md +112 -0
  10. package/dist/_raw/content/deployment/recipes/netlify.md +99 -0
  11. package/dist/_raw/content/deployment/recipes/vercel.md +88 -0
  12. package/dist/_raw/content/deployment/secrets-and-env-vars.md +75 -0
  13. package/dist/_raw/content/deployment.md +128 -0
  14. package/dist/_raw/content/guide/approaches.md +182 -0
  15. package/dist/_raw/content/guide/features.md +121 -0
  16. package/dist/_raw/content/guide/getting-started.md +112 -0
  17. package/dist/_raw/content/guide/kitfly-overview.md +209 -0
  18. package/dist/_raw/content/reference/configuration.md +259 -0
  19. package/dist/_raw/content/reference/design-catalog.md +167 -0
  20. package/dist/_raw/content/reference/environment-variables.md +66 -0
  21. package/dist/_raw/content/reference/glossary.md +92 -0
  22. package/dist/_raw/content/reference/key-concepts.md +118 -0
  23. package/dist/_raw/content/reference/plugins.md +220 -0
  24. package/dist/_raw/content/reference/structure.md +166 -0
  25. package/dist/_raw/content/reference.md +19 -0
  26. package/dist/_raw/content/templates/crucible.md +192 -0
  27. package/dist/_raw/content/templates/handbook.md +83 -0
  28. package/dist/_raw/content/templates/minimal.md +138 -0
  29. package/dist/_raw/content/templates/overview.md +187 -0
  30. package/dist/_raw/content/templates/pipeline.md +151 -0
  31. package/dist/_raw/content/templates/productbook.md +187 -0
  32. package/dist/_raw/content/templates/runbook.md +193 -0
  33. package/dist/_raw/content/templates/servicebook.md +163 -0
  34. package/dist/_raw/docs/decisions/ADR-0001-minimalist-site-code.md +118 -0
  35. package/dist/_raw/docs/decisions/ADR-0002-ai-accessibility.md +153 -0
  36. package/dist/_raw/docs/decisions/ADR-0003-single-file-bundle.md +93 -0
  37. package/dist/_raw/docs/decisions/ADR-0004-bun-runtime.md +98 -0
  38. package/dist/_raw/docs/decisions/ADR-0005-plugin-contract-and-distribution.md +110 -0
  39. package/dist/_raw/docs/decisions/DDR-0001-viewport-locked-layout.md +111 -0
  40. package/dist/_raw/docs/decisions/DDR-0002-theme-system.md +131 -0
  41. package/dist/_raw/docs/decisions/DDR-0003-bounded-logo-slot.md +106 -0
  42. package/dist/_raw/docs/decisions/DDR-0004-slides-rendering-model.md +113 -0
  43. package/dist/_raw/docs/decisions/DDR-0005-deterministic-layout-boundary.md +107 -0
  44. package/dist/_raw/docs/userguide/cli/build.md +85 -0
  45. package/dist/_raw/docs/userguide/cli/bundle.md +81 -0
  46. package/dist/_raw/docs/userguide/cli/dev.md +92 -0
  47. package/dist/_raw/docs/userguide/cli/init.md +116 -0
  48. package/dist/_raw/docs/userguide/cli/servers.md +69 -0
  49. package/dist/_raw/docs/userguide/cli/stop.md +76 -0
  50. package/dist/_raw/docs/userguide/cli/update.md +78 -0
  51. package/dist/_raw/docs/userguide/cli/version.md +65 -0
  52. package/dist/_raw/docs/userguide/cli.md +34 -0
  53. package/dist/_raw/docs/userguide/sharing.md +94 -0
  54. package/dist/_raw/schemas/plugin-schemas-notes.md +71 -0
  55. package/dist/_raw/schemas.md +42 -0
  56. package/dist/assets/brand/kitfly-favicon-32.png +0 -0
  57. package/dist/assets/brand/kitfly-icon-64.png +0 -0
  58. package/dist/assets/brand/kitfly-logo-128.png +0 -0
  59. package/dist/assets/brand/kitfly-logo-512.png +0 -0
  60. package/dist/assets/brand/kitfly-logo.svg +12132 -0
  61. package/dist/assets/brand/kitfly-neon-128.png +0 -0
  62. package/dist/assets/brand/kitfly-neon-192.png +0 -0
  63. package/dist/assets/brand/kitfly-neon-256.png +0 -0
  64. package/dist/assets/brand/kitfly-neon.png +0 -0
  65. package/dist/assets/brand/palette.md +75 -0
  66. package/dist/content/deployment/index.html +11 -0
  67. package/dist/content/deployment/preflight.html +418 -0
  68. package/dist/content/deployment/recipes/aws-s3.html +421 -0
  69. package/dist/content/deployment/recipes/cloudflare-pages.html +372 -0
  70. package/dist/content/deployment/recipes/cloudflare-r2.html +443 -0
  71. package/dist/content/deployment/recipes/fly-io.html +356 -0
  72. package/dist/content/deployment/recipes/github-pages.html +414 -0
  73. package/dist/content/deployment/recipes/index.html +11 -0
  74. package/dist/content/deployment/recipes/netlify.html +394 -0
  75. package/dist/content/deployment/recipes/vercel.html +382 -0
  76. package/dist/content/deployment/secrets-and-env-vars.html +380 -0
  77. package/dist/content/deployment.html +426 -0
  78. package/dist/content/guide/approaches.html +501 -0
  79. package/dist/content/guide/features.html +436 -0
  80. package/dist/content/guide/getting-started.html +403 -0
  81. package/dist/content/guide/index.html +11 -0
  82. package/dist/content/guide/kitfly-overview.html +544 -0
  83. package/dist/content/index.html +11 -0
  84. package/dist/content/reference/configuration.html +580 -0
  85. package/dist/content/reference/design-catalog.html +449 -0
  86. package/dist/content/reference/environment-variables.html +367 -0
  87. package/dist/content/reference/glossary.html +368 -0
  88. package/dist/content/reference/index.html +11 -0
  89. package/dist/content/reference/key-concepts.html +399 -0
  90. package/dist/content/reference/plugins.html +491 -0
  91. package/dist/content/reference/structure.html +463 -0
  92. package/dist/content/reference.html +334 -0
  93. package/dist/content/templates/crucible.html +546 -0
  94. package/dist/content/templates/handbook.html +405 -0
  95. package/dist/content/templates/index.html +11 -0
  96. package/dist/content/templates/minimal.html +447 -0
  97. package/dist/content/templates/overview.html +558 -0
  98. package/dist/content/templates/pipeline.html +494 -0
  99. package/dist/content/templates/productbook.html +540 -0
  100. package/dist/content/templates/runbook.html +543 -0
  101. package/dist/content/templates/servicebook.html +523 -0
  102. package/dist/content-index.json +540 -0
  103. package/dist/docs/decisions/ADR-0001-minimalist-site-code.html +491 -0
  104. package/dist/docs/decisions/ADR-0002-ai-accessibility.html +434 -0
  105. package/dist/docs/decisions/ADR-0003-single-file-bundle.html +412 -0
  106. package/dist/docs/decisions/ADR-0004-bun-runtime.html +409 -0
  107. package/dist/docs/decisions/ADR-0005-plugin-contract-and-distribution.html +402 -0
  108. package/dist/docs/decisions/DDR-0001-viewport-locked-layout.html +459 -0
  109. package/dist/docs/decisions/DDR-0002-theme-system.html +452 -0
  110. package/dist/docs/decisions/DDR-0003-bounded-logo-slot.html +423 -0
  111. package/dist/docs/decisions/DDR-0004-slides-rendering-model.html +399 -0
  112. package/dist/docs/decisions/DDR-0005-deterministic-layout-boundary.html +422 -0
  113. package/dist/docs/decisions/index.html +11 -0
  114. package/dist/docs/userguide/cli/build.html +408 -0
  115. package/dist/docs/userguide/cli/bundle.html +419 -0
  116. package/dist/docs/userguide/cli/dev.html +428 -0
  117. package/dist/docs/userguide/cli/index.html +11 -0
  118. package/dist/docs/userguide/cli/init.html +436 -0
  119. package/dist/docs/userguide/cli/servers.html +393 -0
  120. package/dist/docs/userguide/cli/stop.html +408 -0
  121. package/dist/docs/userguide/cli/update.html +406 -0
  122. package/dist/docs/userguide/cli/version.html +406 -0
  123. package/dist/docs/userguide/cli.html +386 -0
  124. package/dist/docs/userguide/index.html +11 -0
  125. package/dist/docs/userguide/sharing.html +465 -0
  126. package/dist/index.html +387 -0
  127. package/dist/llms.txt +18 -0
  128. package/dist/provenance.json +7 -0
  129. package/dist/schemas/index.html +11 -0
  130. package/dist/schemas/plugin-registry.schema.html +327 -0
  131. package/dist/schemas/plugin-schemas-notes.html +364 -0
  132. package/dist/schemas/plugin.schema.html +327 -0
  133. package/dist/schemas/plugins.schema.html +327 -0
  134. package/dist/schemas/v0/common.schema.html +386 -0
  135. package/dist/schemas/v0/index.html +11 -0
  136. package/dist/schemas/v0/plugin-registry.schema.html +547 -0
  137. package/dist/schemas/v0/plugin.schema.html +497 -0
  138. package/dist/schemas/v0/plugins.schema.html +406 -0
  139. package/dist/schemas/v0/site.schema.html +541 -0
  140. package/dist/schemas/v0/theme.schema.html +615 -0
  141. package/dist/schemas.html +351 -0
  142. package/dist/styles.css +1262 -0
  143. package/package.json +4 -2
  144. package/plugins-dist/callouts.css +32 -0
  145. package/plugins-dist/callouts.js +46 -0
  146. package/plugins-dist/slides-visuals.css +224 -0
  147. package/plugins-dist/slides-visuals.js +598 -0
  148. package/registry/plugins.yaml +35 -0
  149. package/schemas/README.md +10 -0
  150. package/schemas/plugin-registry.schema.json +5 -0
  151. package/schemas/plugin-schemas-notes.md +71 -0
  152. package/schemas/plugin.schema.json +5 -0
  153. package/schemas/plugins.schema.json +5 -0
  154. package/schemas/v0/common.schema.json +64 -0
  155. package/schemas/v0/plugin-registry.schema.json +225 -0
  156. package/schemas/v0/plugin.schema.json +175 -0
  157. package/schemas/v0/plugins.schema.json +84 -0
  158. package/schemas/v0/site.schema.json +56 -9
  159. package/schemas/v0/theme.schema.json +105 -22
  160. package/scripts/build.ts +155 -3
  161. package/scripts/bundle.ts +258 -95
  162. package/scripts/dev.ts +203 -1
  163. package/src/__tests__/build.test.ts +158 -1
  164. package/src/__tests__/bundle.test.ts +31 -0
  165. package/src/__tests__/cli.test.ts +14 -3
  166. package/src/__tests__/fixtures/fences/slides-visuals/invalid/bad-list-indent.md +5 -0
  167. package/src/__tests__/fixtures/fences/slides-visuals/invalid/blank-line.md +5 -0
  168. package/src/__tests__/fixtures/fences/slides-visuals/invalid/compare-object-items.md +9 -0
  169. package/src/__tests__/fixtures/fences/slides-visuals/invalid/indented-fence.md +4 -0
  170. package/src/__tests__/fixtures/fences/slides-visuals/invalid/stat-grid-missing-fields.md +5 -0
  171. package/src/__tests__/fixtures/fences/slides-visuals/invalid/unknown-type.md +3 -0
  172. package/src/__tests__/fixtures/fences/slides-visuals/valid/compare.md +10 -0
  173. package/src/__tests__/fixtures/fences/slides-visuals/valid/comparison-table.md +14 -0
  174. package/src/__tests__/fixtures/fences/slides-visuals/valid/funnel.md +7 -0
  175. package/src/__tests__/fixtures/fences/slides-visuals/valid/kpi.md +5 -0
  176. package/src/__tests__/fixtures/fences/slides-visuals/valid/layer-cake.md +6 -0
  177. package/src/__tests__/fixtures/fences/slides-visuals/valid/pyramid.md +6 -0
  178. package/src/__tests__/fixtures/fences/slides-visuals/valid/quadrant-grid.md +8 -0
  179. package/src/__tests__/fixtures/fences/slides-visuals/valid/scorecard.md +13 -0
  180. package/src/__tests__/fixtures/fences/slides-visuals/valid/stat-grid.md +8 -0
  181. package/src/__tests__/init.test.ts +35 -0
  182. package/src/__tests__/plugin-loader.test.ts +221 -0
  183. package/src/__tests__/shared.test.ts +428 -0
  184. package/src/__tests__/slides-visuals-fence-contract.test.ts +28 -0
  185. package/src/__tests__/slides-visuals-runtime-regressions.bun.test.ts +114 -0
  186. package/src/__tests__/styles.test.ts +35 -0
  187. package/src/cli.ts +9 -4
  188. package/src/plugin-loader.ts +245 -0
  189. package/src/shared.ts +614 -7
  190. package/src/site/styles.css +331 -0
  191. package/src/site/template.html +66 -5
  192. package/src/templates/deck.ts +186 -0
  193. package/src/templates/driver.ts +11 -1
  194. package/src/templates/minimal.ts +1 -0
package/dist/docs/decisions/ADR-0002-ai-accessibility.html ADDED
@@ -0,0 +1,434 @@
1
+ <!DOCTYPE html>
2
+ <html lang="en">
3
+ <head>
4
+ <meta charset="UTF-8">
5
+ <meta name="viewport" content="width=device-width, initial-scale=1.0">
6
+ <title>ADR-0002: AI Accessibility for Published Sites - Kitfly Docs</title>
7
+ <link rel="icon" type="image/png" sizes="32x32" href="../../assets/brand/kitfly-favicon-32.png">
8
+ <link rel="icon" type="image/png" sizes="64x64" href="../../assets/brand/kitfly-neon-256.png">
9
+ <link rel="stylesheet" href="../../styles.css">
10
+ <style id="kitfly-theme">
11
+ :root { --color-bg: #ffffff;
12
+ --color-bg-sidebar: #f5f7f8;
13
+ --color-text: #374151;
14
+ --color-text-muted: #6b7280;
15
+ --color-border: #e5e7eb;
16
+ --color-link: #007182;
17
+ --color-link-hover: #0a6172;
18
+ --color-accent: #152F46;
19
+ --color-code-bg: #f5f7f8;
20
+ --color-logo: #152F46;
21
+ --sidebar-width: 280px;
22
+ --font-sans: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
23
+ --font-headings: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
24
+ --font-mono: ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, monospace; }
25
+ html { font-size: 16px; }
26
+ @media (prefers-color-scheme: dark) {
27
+ :root:not([data-theme="light"]) { --color-bg: #0d1117;
28
+ --color-bg-sidebar: #152F46;
29
+ --color-text: #e5e7eb;
30
+ --color-text-muted: #9ca3af;
31
+ --color-border: #374151;
32
+ --color-link: #709EA6;
33
+ --color-link-hover: #8fb5bc;
34
+ --color-accent: #f9fafb;
35
+ --color-code-bg: #152F46;
36
+ --color-logo: #f9fafb; }
37
+ }
38
+ [data-theme="dark"] { --color-bg: #0d1117;
39
+ --color-bg-sidebar: #152F46;
40
+ --color-text: #e5e7eb;
41
+ --color-text-muted: #9ca3af;
42
+ --color-border: #374151;
43
+ --color-link: #709EA6;
44
+ --color-link-hover: #8fb5bc;
45
+ --color-accent: #f9fafb;
46
+ --color-code-bg: #152F46;
47
+ --color-logo: #f9fafb; }
48
+ [data-theme="light"] { --color-bg: #ffffff;
49
+ --color-bg-sidebar: #f5f7f8;
50
+ --color-text: #374151;
51
+ --color-text-muted: #6b7280;
52
+ --color-border: #e5e7eb;
53
+ --color-link: #007182;
54
+ --color-link-hover: #0a6172;
55
+ --color-accent: #152F46;
56
+ --color-code-bg: #f5f7f8;
57
+ --color-logo: #152F46;
58
+ --sidebar-width: 280px;
59
+ --font-sans: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
60
+ --font-headings: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
61
+ --font-mono: ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, monospace; }
62
+ </style>
63
+ <!-- Syntax highlighting - Prism.js -->
64
+ <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/prismjs@1/themes/prism.min.css" id="prism-light">
65
+ <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/prismjs@1/themes/prism-okaidia.min.css" id="prism-dark" disabled>
66
+
67
+ <script>
68
+ // Apply saved theme immediately to prevent flash
69
+ (function() {
70
+ const saved = localStorage.getItem('theme');
71
+ if (saved) {
72
+ document.documentElement.setAttribute('data-theme', saved);
73
+ }
74
+ // Set Prism theme based on saved or system preference
75
+ const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
76
+ const isDark = saved === 'dark' || (!saved && prefersDark);
77
+ if (isDark) {
78
+ document.getElementById('prism-light')?.setAttribute('disabled', '');
79
+ document.getElementById('prism-dark')?.removeAttribute('disabled');
80
+ }
81
+ })();
82
+ </script>
83
+ </head>
84
+ <body class="mode-docs">
85
+ <div class="mobile-header">
86
+ <button class="nav-toggle" onclick="toggleNav()" aria-label="Toggle navigation">
87
+ <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
88
+ <path d="M3 12h18M3 6h18M3 18h18"/>
89
+ </svg>
90
+ </button>
91
+ <a href="../../" class="mobile-logo" title="Home" data-initial="K">
92
+ <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')"/>
93
+ </a>
94
+ <button class="mobile-theme-toggle" onclick="toggleTheme()" title="Toggle theme" aria-label="Toggle theme">
95
+ <svg class="icon-sun" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
96
+ <circle cx="12" cy="12" r="5"/>
97
+ <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"/>
98
+ </svg>
99
+ <svg class="icon-moon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
100
+ <path d="M21 12.79A9 9 0 1 1 11.21 3 7 7 0 0 0 21 12.79z"/>
101
+ </svg>
102
+ </button>
103
+ </div>
104
+ <div class="layout">
105
+ <nav class="sidebar">
106
+ <div class="sidebar-header">
107
+ <div class="logo logo-icon">
108
+ <a href="/" class="logo-icon" data-initial="K">
109
+ <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')"/>
110
+ </a>
111
+ <span class="logo-text">
112
+ <a href="/" class="brand">Kitfly</a>
113
+ <a href="../../" class="product">Kitfly Docs</a>
114
+ </span>
115
+ </div>
116
+ <div class="header-tools">
117
+ <button class="theme-toggle" onclick="toggleTheme()" title="Toggle theme" aria-label="Toggle theme">
118
+ <svg class="icon-sun" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
119
+ <circle cx="12" cy="12" r="5"/>
120
+ <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"/>
121
+ </svg>
122
+ <svg class="icon-moon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
123
+ <path d="M21 12.79A9 9 0 1 1 11.21 3 7 7 0 0 0 21 12.79z"/>
124
+ </svg>
125
+ </button>
126
+ <div class="sidebar-meta">
127
+ <span class="meta-version">v0.2.0</span>
128
+ <span class="meta-branch">HEAD</span>
129
+ </div>
130
+ </div>
131
+ </div>
132
+ <div class="sidebar-nav">
133
+ <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/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/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" class="active">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/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>
134
+ </div>
135
+ </nav>
136
+ <main class="content">
137
+ <article class="prose">
138
+ <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-0002-ai-accessibility</span></nav>
139
+
140
+ <h1 id="adr-0002-ai-accessibility-for-published-sites">ADR-0002: AI Accessibility for Published Sites</h1>
141
+ <h2 id="status">Status</h2>
142
+ <p>Accepted</p>
143
+ <h2 id="context">Context</h2>
144
+ <p>Kitfly sites are primarily viewed by humans in browsers. However, AI agents increasingly need to consume documentation:</p>
145
+ <ul>
146
+ <li>Agents browsing deployed sites on cloud storage or intranets</li>
147
+ <li>LLMs researching documentation during coding tasks</li>
148
+ <li>Automated documentation indexing and search</li>
149
+ </ul>
150
+ <p>HTML parsing is inefficient for AI agents. They prefer:</p>
151
+ <ul>
152
+ <li>Structured metadata for discovery</li>
153
+ <li>Raw markdown for content consumption</li>
154
+ <li>Predictable paths for programmatic access</li>
155
+ </ul>
156
+ <h2 id="decision">Decision</h2>
157
+ <h3 id="standard-files-generated">Standard Files Generated</h3>
158
+ <p>Every <code>kitfly build</code> generates these AI accessibility files:</p>
159
+ <h4 id="1-content-indexjson">1. <code>content-index.json</code></h4>
160
+ <p>Machine-readable index of all pages:</p>
161
+ <pre><code class="language-json">{
162
+ &quot;version&quot;: &quot;0.1.0&quot;,
163
+ &quot;generated&quot;: &quot;2026-02-04T12:00:00Z&quot;,
164
+ &quot;title&quot;: &quot;Site Title&quot;,
165
+ &quot;baseUrl&quot;: &quot;/&quot;,
166
+ &quot;rawMarkdownPath&quot;: &quot;/_raw&quot;,
167
+ &quot;pages&quot;: [
168
+ {
169
+ &quot;path&quot;: &quot;/guide/getting-started&quot;,
170
+ &quot;htmlPath&quot;: &quot;/guide/getting-started.html&quot;,
171
+ &quot;rawPath&quot;: &quot;/_raw/guide/getting-started.md&quot;,
172
+ &quot;title&quot;: &quot;Getting Started&quot;,
173
+ &quot;section&quot;: &quot;Guide&quot;,
174
+ &quot;source&quot;: &quot;content/guide/getting-started.md&quot;,
175
+ &quot;description&quot;: &quot;Optional description from frontmatter&quot;
176
+ }
177
+ ]
178
+ }
179
+ </code></pre>
180
+ <h4 id="2-llmstxt">2. <code>llms.txt</code></h4>
181
+ <p>Following the emerging <a href="https://llmstxt.org/">llms.txt convention</a>:</p>
182
+ <pre><code># llms.txt - AI agent guidance for Site Title
183
+ name: Site Title
184
+ version: 0.1.0
185
+ generated: 2026-02-04T12:00:00Z
186
+
187
+ content-index: /content-index.json
188
+ raw-markdown: /_raw/{path}.md
189
+ preferred-format: markdown
190
+
191
+ sections: Guide, Reference
192
+ total-pages: 10
193
+ </code></pre>
194
+ <h4 id="3-_raw-directory">3. <code>_raw/</code> Directory</h4>
195
+ <p>Raw markdown files mirroring the site structure:</p>
196
+ <pre><code>_raw/
197
+ ├── guide/
198
+ │ ├── getting-started.md
199
+ │ └── features.md
200
+ └── reference/
201
+ └── configuration.md
202
+ </code></pre>
203
+ <h3 id="bundle-format">Bundle Format</h3>
204
+ <p>Single-file bundles embed accessibility data as hidden JSON:</p>
205
+ <pre><code class="language-html">&lt;script type=&quot;application/json&quot; id=&quot;kitfly-content-index&quot;&gt;
206
+ { ... content index ... }
207
+ &lt;/script&gt;
208
+ &lt;script type=&quot;application/json&quot; id=&quot;kitfly-raw-markdown&quot;&gt;
209
+ { &quot;guide/getting-started&quot;: &quot;# Getting Started\n...&quot;, ... }
210
+ &lt;/script&gt;
211
+ </code></pre>
212
+ <h3 id="opt-out-for-size-sensitive-use-cases">Opt-Out for Size-Sensitive Use Cases</h3>
213
+ <p>The <code>--no-raw</code> flag disables raw markdown for smaller output:</p>
214
+ <pre><code class="language-bash">kitfly build --no-raw # No _raw/ directory
215
+ kitfly bundle --no-raw # No embedded raw markdown
216
+ </code></pre>
217
+ <p>Content index and llms.txt are always generated (minimal overhead).</p>
218
+ <h2 id="agent-consumption-pattern">Agent Consumption Pattern</h2>
219
+ <p>An AI agent discovering a kitfly site:</p>
220
+ <ol>
221
+ <li>Fetch <code>/llms.txt</code> to understand the site</li>
222
+ <li>Fetch <code>/content-index.json</code> for full page inventory</li>
223
+ <li>Fetch raw markdown from <code>/_raw/{path}.md</code> for content</li>
224
+ <li>Fall back to HTML parsing only if raw unavailable</li>
225
+ </ol>
226
+ <h2 id="consequences">Consequences</h2>
227
+ <h3 id="positive">Positive</h3>
228
+ <ul>
229
+ <li>Agents can efficiently consume kitfly sites</li>
230
+ <li>Raw markdown preserves frontmatter and original formatting</li>
231
+ <li>Structured index enables smart navigation</li>
232
+ <li>Standard paths work across all kitfly sites</li>
233
+ <li>Minimal size overhead (JSON index + optional raw copies)</li>
234
+ </ul>
235
+ <h3 id="negative">Negative</h3>
236
+ <ul>
237
+ <li>Slightly larger build output (mitigated by <code>--no-raw</code>)</li>
238
+ <li>Raw markdown exposes source (acceptable for docs)</li>
239
+ </ul>
240
+ <h3 id="neutral">Neutral</h3>
241
+ <ul>
242
+ <li>Agents may still parse HTML for sites without llms.txt</li>
243
+ <li>Convention is emerging, not yet universal</li>
244
+ </ul>
245
+ <h2 id="compliance">Compliance</h2>
246
+ <p>All kitfly builds must generate <code>content-index.json</code> and <code>llms.txt</code>. Raw markdown is on by default but can be disabled.</p>
247
+ <h2 id="references">References</h2>
248
+ <ul>
249
+ <li><a href="https://llmstxt.org/">llms.txt specification</a></li>
250
+ <li><a href="ADR-0001-minimalist-site-code.md">ADR-0001: Minimalist Site Code</a></li>
251
+ </ul>
252
+
253
+ </article>
254
+ <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><a href="#decision">Decision</a></li><li class="toc-h3"><a href="#standard-files-generated">Standard Files Generated</a></li><li class="toc-h3"><a href="#bundle-format">Bundle Format</a></li><li class="toc-h3"><a href="#opt-out-for-size-sensitive-use-cases">Opt-Out for Size-Sensitive Use Cases</a></li><li><a href="#agent-consumption-pattern">Agent Consumption Pattern</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="#compliance">Compliance</a></li><li><a href="#references">References</a></li></ul></aside>
255
+ </main>
256
+ </div>
257
+
258
+ <footer class="site-footer">
259
+ <div class="footer-content">
260
+ <div class="footer-left">
261
+ <span class="footer-version">v0.2.0</span>
262
+ <span class="footer-separator">·</span>
263
+ <span class="footer-commit" title="Commit: 33ccd68">Published 2026-02-15</span>
264
+ </div>
265
+ <div class="footer-center">
266
+ <span class="footer-copyright"><a href="https://3leaps.net" class="footer-link">© 2026 3 Leaps, LLC</a></span>
267
+ <span class="footer-separator">·</span><a href="/" class="footer-link">Kitfly</a>
268
+ </div>
269
+ <div class="footer-right">
270
+ <a href="https://kitfly.dev" class="footer-link">Built with Kitfly</a>
271
+ </div>
272
+ </div>
273
+ </footer>
274
+ <!-- Syntax highlighting - Prism.js -->
275
+ <script src="https://cdn.jsdelivr.net/npm/prismjs@1/components/prism-core.min.js"></script>
276
+ <script src="https://cdn.jsdelivr.net/npm/prismjs@1/plugins/autoloader/prism-autoloader.min.js"></script>
277
+ <!-- Mermaid diagram support -->
278
+ <script type="module">
279
+ import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
280
+
281
+ function getMermaidTheme() {
282
+ const theme = document.documentElement.getAttribute('data-theme');
283
+ const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
284
+ const isDark = theme === 'dark' || (!theme && prefersDark);
285
+ return isDark ? 'dark' : 'neutral';
286
+ }
287
+
288
+ mermaid.initialize({
289
+ startOnLoad: true,
290
+ theme: getMermaidTheme()
291
+ });
292
+
293
+ // Re-render mermaid diagrams when theme changes
294
+ window.reinitMermaid = async function() {
295
+ mermaid.initialize({ startOnLoad: false, theme: getMermaidTheme() });
296
+ const diagrams = document.querySelectorAll('.mermaid');
297
+ for (const el of diagrams) {
298
+ const code = el.getAttribute('data-mermaid-source');
299
+ if (code) {
300
+ el.innerHTML = code;
301
+ el.removeAttribute('data-processed');
302
+ }
303
+ }
304
+ await mermaid.run({ nodes: diagrams });
305
+ };
306
+ </script>
307
+
308
+ <script>
309
+ function toggleTheme() {
310
+ const html = document.documentElement;
311
+ const current = html.getAttribute('data-theme');
312
+ const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
313
+
314
+ let next;
315
+ if (current === 'dark') {
316
+ next = 'light';
317
+ } else if (current === 'light') {
318
+ next = 'dark';
319
+ } else {
320
+ // No explicit theme set, toggle from system preference
321
+ next = prefersDark ? 'light' : 'dark';
322
+ }
323
+
324
+ html.setAttribute('data-theme', next);
325
+ localStorage.setItem('theme', next);
326
+
327
+ // Switch Prism theme
328
+ const prismLight = document.getElementById('prism-light');
329
+ const prismDark = document.getElementById('prism-dark');
330
+ if (next === 'dark') {
331
+ prismLight?.setAttribute('disabled', '');
332
+ prismDark?.removeAttribute('disabled');
333
+ } else {
334
+ prismLight?.removeAttribute('disabled');
335
+ prismDark?.setAttribute('disabled', '');
336
+ }
337
+
338
+ // Re-render mermaid diagrams with new theme
339
+ if (window.reinitMermaid) {
340
+ window.reinitMermaid();
341
+ }
342
+ }
343
+
344
+ // Slides mode hash routing
345
+ (function initSlidesMode() {
346
+ const shell = document.querySelector('.slides-shell');
347
+ if (!shell) return;
348
+
349
+ const slides = Array.from(document.querySelectorAll('.slide'));
350
+ if (!slides.length) return;
351
+
352
+ const prevBtn = document.querySelector('.slide-prev');
353
+ const nextBtn = document.querySelector('.slide-next');
354
+ const counter = document.querySelector('.slide-counter');
355
+ const progressBar = document.querySelector('.slide-progress-bar');
356
+ const navLinks = Array.from(document.querySelectorAll('.sidebar-nav a[href^="#slide-"]'));
357
+ let current = 0;
358
+
359
+ function setActive(n) {
360
+ current = Math.max(0, Math.min(n, slides.length - 1));
361
+ slides.forEach((slide, idx) => slide.classList.toggle('active', idx === current));
362
+ navLinks.forEach((link) => {
363
+ const active = link.getAttribute('href') === '#' + slides[current].id;
364
+ link.classList.toggle('active', active);
365
+ });
366
+ if (counter) counter.textContent = (current + 1) + ' / ' + slides.length;
367
+ if (progressBar) progressBar.style.width = (((current + 1) / slides.length) * 100) + '%';
368
+ if (prevBtn) prevBtn.disabled = current === 0;
369
+ if (nextBtn) nextBtn.disabled = current === slides.length - 1;
370
+ history.replaceState(null, '', '#' + slides[current].id);
371
+ }
372
+
373
+ function setFromHash() {
374
+ const hash = window.location.hash || '';
375
+ const idx = slides.findIndex((s) => '#' + s.id === hash);
376
+ if (idx >= 0) setActive(idx);
377
+ else setActive(0);
378
+ }
379
+
380
+ prevBtn?.addEventListener('click', () => setActive(current - 1));
381
+ nextBtn?.addEventListener('click', () => setActive(current + 1));
382
+
383
+ document.addEventListener('keydown', (e) => {
384
+ if (e.key === 'ArrowRight' || e.key === ' ') {
385
+ e.preventDefault();
386
+ setActive(current + 1);
387
+ } else if (e.key === 'ArrowLeft') {
388
+ e.preventDefault();
389
+ setActive(current - 1);
390
+ } else if (e.key === 'Home') {
391
+ e.preventDefault();
392
+ setActive(0);
393
+ } else if (e.key === 'End') {
394
+ e.preventDefault();
395
+ setActive(slides.length - 1);
396
+ }
397
+ });
398
+
399
+ window.addEventListener('hashchange', setFromHash);
400
+ setFromHash();
401
+ })();
402
+
403
+ // Copy code button
404
+ document.querySelectorAll('.prose pre code').forEach(block => {
405
+ const button = document.createElement('button');
406
+ button.className = 'copy-button';
407
+ button.textContent = 'Copy';
408
+ button.onclick = async () => {
409
+ await navigator.clipboard.writeText(block.textContent);
410
+ button.textContent = 'Copied!';
411
+ setTimeout(() => button.textContent = 'Copy', 2000);
412
+ };
413
+ block.parentElement.appendChild(button);
414
+ });
415
+
416
+ // Mobile nav toggle
417
+ function toggleNav() {
418
+ document.querySelector('.sidebar').classList.toggle('open');
419
+ }
420
+
421
+ // Close nav when clicking outside on mobile
422
+ document.addEventListener('click', (e) => {
423
+ const sidebar = document.querySelector('.sidebar');
424
+ const toggle = document.querySelector('.nav-toggle');
425
+ if (sidebar.classList.contains('open') &&
426
+ !sidebar.contains(e.target) &&
427
+ !toggle.contains(e.target)) {
428
+ sidebar.classList.remove('open');
429
+ }
430
+ });
431
+ </script>
432
+
433
+ </body>
434
+ </html>