kitfly 0.1.2 → 0.2.1

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 (209) hide show
  1. package/CHANGELOG.md +46 -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/slides-authoring-guidelines.md +129 -0
  25. package/dist/_raw/content/reference/structure.md +166 -0
  26. package/dist/_raw/content/reference.md +20 -0
  27. package/dist/_raw/content/templates/crucible.md +192 -0
  28. package/dist/_raw/content/templates/handbook.md +83 -0
  29. package/dist/_raw/content/templates/minimal.md +138 -0
  30. package/dist/_raw/content/templates/overview.md +187 -0
  31. package/dist/_raw/content/templates/pipeline.md +151 -0
  32. package/dist/_raw/content/templates/productbook.md +187 -0
  33. package/dist/_raw/content/templates/runbook.md +193 -0
  34. package/dist/_raw/content/templates/servicebook.md +163 -0
  35. package/dist/_raw/docs/decisions/ADR-0001-minimalist-site-code.md +118 -0
  36. package/dist/_raw/docs/decisions/ADR-0002-ai-accessibility.md +153 -0
  37. package/dist/_raw/docs/decisions/ADR-0003-single-file-bundle.md +93 -0
  38. package/dist/_raw/docs/decisions/ADR-0004-bun-runtime.md +98 -0
  39. package/dist/_raw/docs/decisions/ADR-0005-plugin-contract-and-distribution.md +110 -0
  40. package/dist/_raw/docs/decisions/DDR-0001-viewport-locked-layout.md +111 -0
  41. package/dist/_raw/docs/decisions/DDR-0002-theme-system.md +131 -0
  42. package/dist/_raw/docs/decisions/DDR-0003-bounded-logo-slot.md +106 -0
  43. package/dist/_raw/docs/decisions/DDR-0004-slides-rendering-model.md +113 -0
  44. package/dist/_raw/docs/decisions/DDR-0005-deterministic-layout-boundary.md +107 -0
  45. package/dist/_raw/docs/userguide/cli/build.md +85 -0
  46. package/dist/_raw/docs/userguide/cli/bundle.md +81 -0
  47. package/dist/_raw/docs/userguide/cli/dev.md +92 -0
  48. package/dist/_raw/docs/userguide/cli/init.md +116 -0
  49. package/dist/_raw/docs/userguide/cli/servers.md +69 -0
  50. package/dist/_raw/docs/userguide/cli/stop.md +76 -0
  51. package/dist/_raw/docs/userguide/cli/update.md +78 -0
  52. package/dist/_raw/docs/userguide/cli/version.md +65 -0
  53. package/dist/_raw/docs/userguide/cli.md +34 -0
  54. package/dist/_raw/docs/userguide/sharing.md +94 -0
  55. package/dist/_raw/schemas/plugin-schemas-notes.md +71 -0
  56. package/dist/_raw/schemas.md +42 -0
  57. package/dist/assets/brand/kitfly-favicon-32.png +0 -0
  58. package/dist/assets/brand/kitfly-icon-64.png +0 -0
  59. package/dist/assets/brand/kitfly-logo-128.png +0 -0
  60. package/dist/assets/brand/kitfly-logo-512.png +0 -0
  61. package/dist/assets/brand/kitfly-logo.svg +12132 -0
  62. package/dist/assets/brand/kitfly-neon-128.png +0 -0
  63. package/dist/assets/brand/kitfly-neon-192.png +0 -0
  64. package/dist/assets/brand/kitfly-neon-256.png +0 -0
  65. package/dist/assets/brand/kitfly-neon.png +0 -0
  66. package/dist/assets/brand/palette.md +75 -0
  67. package/dist/content/deployment/index.html +11 -0
  68. package/dist/content/deployment/preflight.html +418 -0
  69. package/dist/content/deployment/recipes/aws-s3.html +421 -0
  70. package/dist/content/deployment/recipes/cloudflare-pages.html +372 -0
  71. package/dist/content/deployment/recipes/cloudflare-r2.html +443 -0
  72. package/dist/content/deployment/recipes/fly-io.html +356 -0
  73. package/dist/content/deployment/recipes/github-pages.html +414 -0
  74. package/dist/content/deployment/recipes/index.html +11 -0
  75. package/dist/content/deployment/recipes/netlify.html +394 -0
  76. package/dist/content/deployment/recipes/vercel.html +382 -0
  77. package/dist/content/deployment/secrets-and-env-vars.html +380 -0
  78. package/dist/content/deployment.html +426 -0
  79. package/dist/content/guide/approaches.html +501 -0
  80. package/dist/content/guide/features.html +436 -0
  81. package/dist/content/guide/getting-started.html +403 -0
  82. package/dist/content/guide/index.html +11 -0
  83. package/dist/content/guide/kitfly-overview.html +544 -0
  84. package/dist/content/index.html +11 -0
  85. package/dist/content/reference/configuration.html +580 -0
  86. package/dist/content/reference/design-catalog.html +449 -0
  87. package/dist/content/reference/environment-variables.html +367 -0
  88. package/dist/content/reference/glossary.html +368 -0
  89. package/dist/content/reference/index.html +11 -0
  90. package/dist/content/reference/key-concepts.html +399 -0
  91. package/dist/content/reference/plugins.html +491 -0
  92. package/dist/content/reference/slides-authoring-guidelines.html +418 -0
  93. package/dist/content/reference/structure.html +463 -0
  94. package/dist/content/reference.html +335 -0
  95. package/dist/content/templates/crucible.html +546 -0
  96. package/dist/content/templates/handbook.html +405 -0
  97. package/dist/content/templates/index.html +11 -0
  98. package/dist/content/templates/minimal.html +447 -0
  99. package/dist/content/templates/overview.html +558 -0
  100. package/dist/content/templates/pipeline.html +494 -0
  101. package/dist/content/templates/productbook.html +540 -0
  102. package/dist/content/templates/runbook.html +543 -0
  103. package/dist/content/templates/servicebook.html +523 -0
  104. package/dist/content-index.json +549 -0
  105. package/dist/docs/decisions/ADR-0001-minimalist-site-code.html +491 -0
  106. package/dist/docs/decisions/ADR-0002-ai-accessibility.html +434 -0
  107. package/dist/docs/decisions/ADR-0003-single-file-bundle.html +412 -0
  108. package/dist/docs/decisions/ADR-0004-bun-runtime.html +409 -0
  109. package/dist/docs/decisions/ADR-0005-plugin-contract-and-distribution.html +402 -0
  110. package/dist/docs/decisions/DDR-0001-viewport-locked-layout.html +459 -0
  111. package/dist/docs/decisions/DDR-0002-theme-system.html +452 -0
  112. package/dist/docs/decisions/DDR-0003-bounded-logo-slot.html +423 -0
  113. package/dist/docs/decisions/DDR-0004-slides-rendering-model.html +399 -0
  114. package/dist/docs/decisions/DDR-0005-deterministic-layout-boundary.html +422 -0
  115. package/dist/docs/decisions/index.html +11 -0
  116. package/dist/docs/userguide/cli/build.html +408 -0
  117. package/dist/docs/userguide/cli/bundle.html +419 -0
  118. package/dist/docs/userguide/cli/dev.html +428 -0
  119. package/dist/docs/userguide/cli/index.html +11 -0
  120. package/dist/docs/userguide/cli/init.html +436 -0
  121. package/dist/docs/userguide/cli/servers.html +393 -0
  122. package/dist/docs/userguide/cli/stop.html +408 -0
  123. package/dist/docs/userguide/cli/update.html +406 -0
  124. package/dist/docs/userguide/cli/version.html +406 -0
  125. package/dist/docs/userguide/cli.html +386 -0
  126. package/dist/docs/userguide/index.html +11 -0
  127. package/dist/docs/userguide/sharing.html +465 -0
  128. package/dist/index.html +387 -0
  129. package/dist/llms.txt +18 -0
  130. package/dist/provenance.json +7 -0
  131. package/dist/schemas/index.html +11 -0
  132. package/dist/schemas/plugin-registry.schema.html +327 -0
  133. package/dist/schemas/plugin-schemas-notes.html +364 -0
  134. package/dist/schemas/plugin.schema.html +327 -0
  135. package/dist/schemas/plugins.schema.html +327 -0
  136. package/dist/schemas/v0/common.schema.html +386 -0
  137. package/dist/schemas/v0/index.html +11 -0
  138. package/dist/schemas/v0/plugin-registry.schema.html +547 -0
  139. package/dist/schemas/v0/plugin.schema.html +497 -0
  140. package/dist/schemas/v0/plugins.schema.html +406 -0
  141. package/dist/schemas/v0/site.schema.html +541 -0
  142. package/dist/schemas/v0/theme.schema.html +615 -0
  143. package/dist/schemas.html +351 -0
  144. package/dist/styles.css +1262 -0
  145. package/package.json +4 -2
  146. package/plugins-dist/callouts.css +32 -0
  147. package/plugins-dist/callouts.js +46 -0
  148. package/plugins-dist/slides-visuals.css +390 -0
  149. package/plugins-dist/slides-visuals.js +689 -0
  150. package/registry/plugins.yaml +35 -0
  151. package/schemas/README.md +10 -0
  152. package/schemas/plugin-registry.schema.json +5 -0
  153. package/schemas/plugin-schemas-notes.md +71 -0
  154. package/schemas/plugin.schema.json +5 -0
  155. package/schemas/plugins.schema.json +5 -0
  156. package/schemas/v0/common.schema.json +64 -0
  157. package/schemas/v0/plugin-registry.schema.json +225 -0
  158. package/schemas/v0/plugin.schema.json +175 -0
  159. package/schemas/v0/plugins.schema.json +84 -0
  160. package/schemas/v0/site.schema.json +56 -9
  161. package/schemas/v0/theme.schema.json +105 -22
  162. package/scripts/build.ts +158 -3
  163. package/scripts/bundle.ts +261 -95
  164. package/scripts/dev.ts +301 -11
  165. package/src/__tests__/build.test.ts +220 -1
  166. package/src/__tests__/bundle.test.ts +31 -0
  167. package/src/__tests__/cli.test.ts +14 -3
  168. package/src/__tests__/dev-plugin-errors.test.ts +20 -0
  169. package/src/__tests__/fixtures/fences/slides-visuals/invalid/bad-list-indent.md +5 -0
  170. package/src/__tests__/fixtures/fences/slides-visuals/invalid/blank-line.md +5 -0
  171. package/src/__tests__/fixtures/fences/slides-visuals/invalid/compare-object-items.md +9 -0
  172. package/src/__tests__/fixtures/fences/slides-visuals/invalid/flow-branching-no-source.md +5 -0
  173. package/src/__tests__/fixtures/fences/slides-visuals/invalid/flow-converging-no-target.md +6 -0
  174. package/src/__tests__/fixtures/fences/slides-visuals/invalid/indented-fence.md +4 -0
  175. package/src/__tests__/fixtures/fences/slides-visuals/invalid/staircase-empty-steps.md +3 -0
  176. package/src/__tests__/fixtures/fences/slides-visuals/invalid/stat-grid-missing-fields.md +5 -0
  177. package/src/__tests__/fixtures/fences/slides-visuals/invalid/timeline-horizontal-no-events.md +2 -0
  178. package/src/__tests__/fixtures/fences/slides-visuals/invalid/unknown-type.md +3 -0
  179. package/src/__tests__/fixtures/fences/slides-visuals/valid/compare.md +10 -0
  180. package/src/__tests__/fixtures/fences/slides-visuals/valid/comparison-table.md +14 -0
  181. package/src/__tests__/fixtures/fences/slides-visuals/valid/flow-branching-no-split.md +7 -0
  182. package/src/__tests__/fixtures/fences/slides-visuals/valid/flow-branching.md +8 -0
  183. package/src/__tests__/fixtures/fences/slides-visuals/valid/flow-converging-no-merge.md +7 -0
  184. package/src/__tests__/fixtures/fences/slides-visuals/valid/flow-converging.md +8 -0
  185. package/src/__tests__/fixtures/fences/slides-visuals/valid/funnel.md +7 -0
  186. package/src/__tests__/fixtures/fences/slides-visuals/valid/kpi.md +5 -0
  187. package/src/__tests__/fixtures/fences/slides-visuals/valid/layer-cake.md +6 -0
  188. package/src/__tests__/fixtures/fences/slides-visuals/valid/pyramid.md +6 -0
  189. package/src/__tests__/fixtures/fences/slides-visuals/valid/quadrant-grid.md +8 -0
  190. package/src/__tests__/fixtures/fences/slides-visuals/valid/scorecard.md +13 -0
  191. package/src/__tests__/fixtures/fences/slides-visuals/valid/staircase-down.md +7 -0
  192. package/src/__tests__/fixtures/fences/slides-visuals/valid/staircase.md +8 -0
  193. package/src/__tests__/fixtures/fences/slides-visuals/valid/stat-grid.md +8 -0
  194. package/src/__tests__/fixtures/fences/slides-visuals/valid/timeline-horizontal.md +9 -0
  195. package/src/__tests__/fixtures/fences/slides-visuals/valid/timeline-vertical.md +10 -0
  196. package/src/__tests__/init.test.ts +35 -0
  197. package/src/__tests__/plugin-loader.test.ts +221 -0
  198. package/src/__tests__/shared.test.ts +451 -0
  199. package/src/__tests__/slides-visuals-fence-contract.test.ts +28 -0
  200. package/src/__tests__/slides-visuals-runtime-regressions.bun.test.ts +147 -0
  201. package/src/__tests__/styles.test.ts +35 -0
  202. package/src/cli.ts +9 -4
  203. package/src/plugin-loader.ts +245 -0
  204. package/src/shared.ts +650 -7
  205. package/src/site/styles.css +331 -0
  206. package/src/site/template.html +66 -5
  207. package/src/templates/deck.ts +186 -0
  208. package/src/templates/driver.ts +11 -1
  209. package/src/templates/minimal.ts +1 -0
@@ -0,0 +1,151 @@
1
+ ---
2
+ title: Pipeline Template
3
+ description: Data pipeline operations with stages, sources, destinations, and manifests
4
+ ---
5
+
6
+ # Pipeline Template
7
+
8
+ The `pipeline` template creates a structured site for data pipeline operations. It extends `minimal` with sections designed for teams that build, run, and maintain data pipelines — index builds, content extraction, transfer/reflow, and validation.
9
+
10
+ ## When to Use
11
+
12
+ - Data pipeline operational documentation
13
+ - ETL/ELT process runbooks
14
+ - Data migration projects
15
+ - Batch processing operations
16
+ - Any workflow with sequential stages moving data from sources to destinations
17
+
18
+ ## What You Get
19
+
20
+ Everything from `minimal`, plus:
21
+
22
+ ```
23
+ my-pipeline/
24
+ ├── site.yaml # Configured with pipeline sections
25
+ ├── index.md # Pipeline status dashboard with quick links
26
+ ├── CUSTOMIZING.md # How to customize (AI + human friendly)
27
+ ├── content/
28
+ │ ├── pipeline/
29
+ │ │ ├── overview.md # End-to-end dataflow
30
+ │ │ ├── index-build.md # Index build stage
31
+ │ │ ├── extract.md # Content extraction stage
32
+ │ │ ├── transfer.md # Transfer / reflow stage
33
+ │ │ └── validate.md # Validation stage
34
+ │ ├── sources/
35
+ │ │ └── index.md # Source system catalog
36
+ │ ├── destinations/
37
+ │ │ └── index.md # Destination catalog
38
+ │ ├── operations/
39
+ │ │ ├── run-pipeline.md # Full execution procedure
40
+ │ │ └── schedules.md # Pipeline schedule table
41
+ │ ├── troubleshooting/
42
+ │ │ └── common-issues.md # Pipeline-specific issues
43
+ │ └── reference/
44
+ │ ├── manifests/
45
+ │ │ └── index.md # Job manifest YAML templates
46
+ │ ├── field-mappings/
47
+ │ │ └── index.md # Source → destination mappings
48
+ │ ├── metrics/
49
+ │ │ └── index.md # Pipeline KPIs and SLAs
50
+ │ ├── checklists/
51
+ │ │ └── pre-run.md # Pre-run verification
52
+ │ └── contacts/
53
+ │ └── directory.md # Team contacts and escalation
54
+ └── ...
55
+ ```
56
+
57
+ ## Sections
58
+
59
+ | Section | Purpose | Typical Content |
60
+ | ------------------- | --------------------------- | ----------------------------------------------------------------- |
61
+ | **Pipeline** | Core dataflow documentation | Stage definitions, data movement, processing logic |
62
+ | **Sources** | Input systems | Connection details, schemas, auth profiles, data formats |
63
+ | **Destinations** | Output systems | Target structures, path layouts, landing zones |
64
+ | **Operations** | Run procedures | Execution steps, schedules, checkpoint/resume |
65
+ | **Troubleshooting** | Problem resolution | Auth expiry, index locks, duplicate conflicts, collision handling |
66
+ | **Reference** | Supporting materials | Manifests, field mappings, metrics, checklists, contacts |
67
+
68
+ ### Pipeline vs. Runbook
69
+
70
+ Both are operational templates, but they serve different shapes of work:
71
+
72
+ | Aspect | Runbook | Pipeline |
73
+ | ------------------- | -------------------------------- | ---------------------------------------- |
74
+ | **Focus** | Service operations | Data movement |
75
+ | **Structure** | Procedures + incidents | Sequential stages + sources/destinations |
76
+ | **Key question** | "What do I do when X breaks?" | "How does data flow from A to B?" |
77
+ | **Reference model** | Interfaces, contacts, checklists | Manifests, field mappings, metrics |
78
+
79
+ ## Usage
80
+
81
+ ```bash
82
+ kitfly init data-ops --template pipeline
83
+ kitfly init data-ops --template pipeline --brand "Data Platform"
84
+
85
+ # With AI assistance instrumentation
86
+ kitfly init data-ops --template pipeline --standalone --ai-assist
87
+ ```
88
+
89
+ ## The Pipeline Section
90
+
91
+ The core of this template. Each stage is documented with:
92
+
93
+ - **Objective** — what the stage accomplishes
94
+ - **Prerequisites** — what must be in place before running
95
+ - **Procedure** — step-by-step execution
96
+ - **Verification** — how to confirm success
97
+
98
+ The default stages follow a common data pipeline pattern:
99
+
100
+ ```
101
+ Source → Index Build → Content Extraction → Transfer/Reflow → Validation → Destination
102
+ ```
103
+
104
+ Adapt these to your actual pipeline. Add, remove, or rename stages as needed.
105
+
106
+ ## Growing Your Pipeline Docs
107
+
108
+ As your pipeline matures, consider expanding:
109
+
110
+ **Multiple pipelines** — add subdirectories under `content/pipeline/`:
111
+
112
+ ```
113
+ content/pipeline/
114
+ ├── overview.md
115
+ ├── daily-sync/
116
+ │ ├── index.md
117
+ │ ├── extract.md
118
+ │ └── validate.md
119
+ └── quarterly-migration/
120
+ ├── index.md
121
+ └── stages.md
122
+ ```
123
+
124
+ The sidebar automatically organizes these into collapsible groups — each subdirectory becomes an expandable section in the navigation.
125
+
126
+ **Multiple sources/destinations** — add a page per system:
127
+
128
+ ```
129
+ content/sources/
130
+ ├── index.md # Catalog table
131
+ ├── salesforce.md # Source details
132
+ └── data-warehouse.md # Source details
133
+ ```
134
+
135
+ ## Example Use Cases
136
+
137
+ **Cloud Data Migration**
138
+
139
+ - Pipeline: S3 scan → content probe → key rewrite → validation
140
+ - Sources: AWS S3 buckets with legacy key structure
141
+ - Destinations: GCS with date-partitioned layout
142
+ - Operations: Weekly full sync, daily incremental
143
+ - Reference/Manifests: Job definitions per source bucket
144
+
145
+ **ETL for Analytics**
146
+
147
+ - Pipeline: Extract from APIs → transform/enrich → load to warehouse
148
+ - Sources: REST APIs, SFTP drops, webhook events
149
+ - Destinations: Snowflake tables, Parquet files in S3
150
+ - Troubleshooting: Rate limits, schema drift, partial loads
151
+ - Reference/Metrics: Row counts, freshness SLAs, error rates
@@ -0,0 +1,187 @@
1
+ ---
2
+ title: Productbook Template
3
+ description: Product and domain documentation for complex greenfield engagements
4
+ ---
5
+
6
+ # Productbook Template
7
+
8
+ The `productbook` template creates a documentation site that captures both **product definition** and **business domain knowledge**. It extends `minimal` with six sections designed for greenfield engagements where the product operates in a complex business domain.
9
+
10
+ ## When to Use
11
+
12
+ - Greenfield product development in complex business domains
13
+ - Client engagements that need to capture domain expertise alongside product specs
14
+ - Products with regulatory, industry, or process complexity
15
+ - Projects where the team needs a shared reference for "how this business works"
16
+ - Any situation where product decisions depend on deep domain understanding
17
+
18
+ ## What You Get
19
+
20
+ Everything from `minimal`, plus:
21
+
22
+ ```
23
+ my-productbook/
24
+ ├── site.yaml # Configured with 6 sections
25
+ ├── index.md # Home page with product status and quick links
26
+ ├── CUSTOMIZING.md # How to customize (AI + human friendly)
27
+ ├── content/
28
+ │ ├── product/
29
+ │ │ ├── overview.md # Vision, users, capabilities
30
+ │ │ ├── features/
31
+ │ │ │ └── index.md # Feature catalog
32
+ │ │ └── releases/
33
+ │ │ └── index.md # Release log
34
+ │ ├── domain/
35
+ │ │ ├── overview.md # Business domain context
36
+ │ │ ├── processes/
37
+ │ │ │ └── index.md # Business process catalog
38
+ │ │ ├── data-dictionary.md # Terms and definitions
39
+ │ │ └── industry-notes.md # Regulations and standards
40
+ │ ├── planning/
41
+ │ │ ├── roadmap.md # Phases and priorities
42
+ │ │ ├── decisions/
43
+ │ │ │ ├── index.md # Decision log (ADR pattern)
44
+ │ │ │ └── adr-template.md # ADR template
45
+ │ │ ├── specs/
46
+ │ │ │ └── index.md # Specification index
47
+ │ │ └── research/
48
+ │ │ └── index.md # Research index
49
+ │ ├── operations/
50
+ │ │ ├── environments.md # Dev, staging, production
51
+ │ │ └── deployment.md # Deployment procedures
52
+ │ ├── guides/
53
+ │ │ ├── getting-started.md # Onboarding guide
54
+ │ │ └── user-guide.md # End-user documentation
55
+ │ └── reference/
56
+ │ ├── architecture/
57
+ │ │ └── overview.md # System architecture
58
+ │ ├── integrations/
59
+ │ │ └── index.md # Integration catalog
60
+ │ ├── data-models/
61
+ │ │ └── overview.md # Schemas and data flow
62
+ │ ├── contacts/
63
+ │ │ └── directory.md # Team and vendor contacts
64
+ │ └── metrics/
65
+ │ └── overview.md # KPIs and dashboards
66
+ └── ...
67
+ ```
68
+
69
+ ## Sections
70
+
71
+ | Section | Purpose | Typical Content |
72
+ | -------------- | -------------------- | ---------------------------------------------------------- |
73
+ | **Product** | What we're building | Vision, features, releases, acceptance criteria |
74
+ | **Domain** | The business reality | Processes, terminology, data dictionary, industry context |
75
+ | **Planning** | Why and when | Roadmap, ADRs, specifications, research |
76
+ | **Operations** | How we run it | Environments, deployment, configuration |
77
+ | **Guides** | How to use it | Onboarding, tutorials, user documentation |
78
+ | **Reference** | Look-up material | Architecture, integrations, data models, contacts, metrics |
79
+
80
+ ## The Domain Section
81
+
82
+ This is what makes productbook different from every other template. It captures the **complex business reality** that the product operates in.
83
+
84
+ For a propane delivery company, this might hold:
85
+
86
+ - **Processes**: Tank monitoring workflow, delivery scheduling, seasonal demand forecasting
87
+ - **Data Dictionary**: What "will-call" vs "automatic" delivery means, ERP entity definitions
88
+ - **Industry Notes**: DOT regulations for hazmat transport, state-level propane licensing
89
+
90
+ For a healthcare platform:
91
+
92
+ - **Processes**: Claims adjudication, prior authorization, formulary management
93
+ - **Data Dictionary**: CPT codes, NDC numbers, explanation of benefits
94
+ - **Industry Notes**: HIPAA requirements, CMS guidelines, state insurance mandates
95
+
96
+ This section is the "context dump" that every new team member and AI agent needs. It turns tribal knowledge into navigable documentation.
97
+
98
+ ## Planning Artifacts
99
+
100
+ The planning section includes built-in support for common planning patterns:
101
+
102
+ **Decision Records (ADRs)** — each decision documented with:
103
+
104
+ - Context: What prompted this decision
105
+ - Options: What we considered
106
+ - Decision: What we chose and why
107
+ - Consequences: What follows from this choice
108
+
109
+ **Specifications** — feature specs with:
110
+
111
+ - Problem statement
112
+ - Proposed solution
113
+ - Acceptance criteria
114
+ - Status tracking
115
+
116
+ **Research** — structured research outputs:
117
+
118
+ - Market analysis
119
+ - User research findings
120
+ - Technology assessments
121
+
122
+ The sidebar organizes these into collapsible groups — decisions, specs, and research each appear as expandable subsections under Planning.
123
+
124
+ ## Usage
125
+
126
+ ```bash
127
+ kitfly init client-docs --template productbook
128
+ kitfly init client-docs --template productbook --brand "Project Atlas"
129
+
130
+ # With AI assistance instrumentation
131
+ kitfly init client-docs --template productbook --standalone --ai-assist
132
+ ```
133
+
134
+ ## Productbook vs. Other Templates
135
+
136
+ | Aspect | Handbook | Runbook | Productbook |
137
+ | --------------- | ------------ | ---------------------- | --------------------------- |
138
+ | **Orientation** | How we work | How we keep it running | What we're building and why |
139
+ | **Assumes** | Team exists | System exists | Starting from scratch |
140
+ | **Key section** | Guides | Procedures | Domain |
141
+ | **Audience** | Team members | Operators | Product team + stakeholders |
142
+ | **Tone** | Explanatory | Imperative | Analytical |
143
+
144
+ ## Growing Your Productbook
145
+
146
+ As the engagement matures, the sections grow naturally:
147
+
148
+ **Domain deepens first** — business process docs accumulate as the team learns the domain:
149
+
150
+ ```
151
+ content/domain/processes/
152
+ ├── index.md
153
+ ├── order-fulfillment.md
154
+ ├── returns-processing.md
155
+ ├── inventory-reconciliation.md
156
+ └── seasonal-forecasting.md
157
+ ```
158
+
159
+ **Product fills in as features ship** — feature pages link to the domain processes they automate:
160
+
161
+ ```
162
+ content/product/features/
163
+ ├── index.md
164
+ ├── auto-scheduling.md # References domain/processes/delivery-scheduling
165
+ ├── tank-monitoring.md # References domain/processes/tank-monitoring
166
+ └── customer-portal.md
167
+ ```
168
+
169
+ **Planning captures decisions over time** — the ADR log becomes a valuable historical record.
170
+
171
+ ## Example Use Cases
172
+
173
+ **Enterprise SaaS for Complex Industry**
174
+
175
+ - Product: Platform features, integrations, user workflows
176
+ - Domain: Industry processes, regulatory requirements, competitive context
177
+ - Planning: Roadmap, ADRs for technology and vendor choices
178
+ - Guides: Customer onboarding, admin guides
179
+ - Reference: API architecture, third-party integrations, data models
180
+
181
+ **Client Engagement with Legacy System Modernization**
182
+
183
+ - Product: New platform capabilities replacing legacy functions
184
+ - Domain: Existing business processes, data structures, edge cases the legacy handles
185
+ - Planning: Migration specs, cutover decisions, research on replacement options
186
+ - Operations: Parallel-run environments, migration deployment procedures
187
+ - Reference: Legacy system documentation, data mapping, vendor contacts
@@ -0,0 +1,193 @@
1
+ ---
2
+ title: Runbook Template
3
+ description: Operational procedures, troubleshooting, and incident response
4
+ ---
5
+
6
+ # Runbook Template
7
+
8
+ The `runbook` template creates a structured site for operational documentation. It extends `minimal` with sections designed for on-call engineers, SREs, and operations teams.
9
+
10
+ ## When to Use
11
+
12
+ - Operations documentation
13
+ - On-call runbooks
14
+ - Incident response procedures
15
+ - System administration guides
16
+ - Deployment and maintenance checklists
17
+ - Any docs that answer "what do I do when..."
18
+
19
+ ## What You Get
20
+
21
+ Everything from `minimal`, plus:
22
+
23
+ ```
24
+ my-runbook/
25
+ ├── site.yaml # Configured with ops sections
26
+ ├── index.md # Home page with quick links
27
+ ├── CUSTOMIZING.md # How to customize this site (AI + human friendly)
28
+ ├── content/
29
+ │ ├── procedures/
30
+ │ │ └── deployment.md # Step-by-step procedures
31
+ │ ├── troubleshooting/
32
+ │ │ └── common-issues.md # Problem → solution guides
33
+ │ ├── reference/
34
+ │ │ ├── interfaces/
35
+ │ │ │ └── api-template.md # Integration/API documentation
36
+ │ │ ├── contacts/
37
+ │ │ │ └── directory.md # Team and vendor contacts
38
+ │ │ ├── checklists/
39
+ │ │ │ └── pre-deploy.md # Verification checklists
40
+ │ │ └── analytics/
41
+ │ │ └── dashboards.md # Metrics and KPI definitions
42
+ │ └── incidents/
43
+ │ └── escalation.md # Incident response paths
44
+ └── ...
45
+ ```
46
+
47
+ ## Sections
48
+
49
+ | Section | Purpose | Typical Content |
50
+ | ------------------- | -------------------------------- | ---------------------------------------------------- |
51
+ | **Procedures** | How to perform operational tasks | Deployment steps, maintenance tasks, migrations |
52
+ | **Troubleshooting** | Diagnose and fix issues | Error codes, symptoms → causes, remediation |
53
+ | **Reference** | Look-up information | Interfaces, contacts, checklists, glossary |
54
+ | **Incidents** | Emergency response | Escalation paths, severity definitions, post-mortems |
55
+
56
+ The **Reference** section consolidates supporting materials:
57
+
58
+ | Subsection | Purpose |
59
+ | ----------------------- | ---------------------------------------------------- |
60
+ | `reference/interfaces/` | API specs, protocol docs, vendor integration details |
61
+ | `reference/contacts/` | Team directory, vendor contacts, escalation matrix |
62
+ | `reference/checklists/` | Pre/post deployment, audit, maintenance checklists |
63
+ | `reference/analytics/` | Dashboard links, KPIs, SLA definitions |
64
+
65
+ ## Usage
66
+
67
+ ```bash
68
+ kitfly init ops-docs --template runbook
69
+ kitfly init ops-docs --template runbook --brand "Platform Team"
70
+ ```
71
+
72
+ ## Design Principles
73
+
74
+ Runbooks differ from handbooks in key ways:
75
+
76
+ | Aspect | Handbook | Runbook |
77
+ | ---------------- | ------------- | -------------------------- |
78
+ | **Audience** | Learning | Doing (often urgently) |
79
+ | **Reading mode** | Sequential | Jump to specific procedure |
80
+ | **Goal** | Understanding | Task completion |
81
+ | **Tone** | Explanatory | Direct, imperative |
82
+
83
+ ## Procedure Document Format
84
+
85
+ Each procedure should follow a consistent structure:
86
+
87
+ ```markdown
88
+ # Procedure Name
89
+
90
+ ## Objective
91
+
92
+ What this procedure accomplishes and when to use it.
93
+
94
+ ## Prerequisites
95
+
96
+ - [ ] Required access or permissions
97
+ - [ ] Tools or systems that must be available
98
+ - [ ] Related procedures to complete first
99
+
100
+ ## Steps
101
+
102
+ 1. **First action**
103
+ - Expected output: `what you should see`
104
+
105
+ 2. **Second action**
106
+ - Verification: How to confirm success
107
+
108
+ ## Verification
109
+
110
+ How to confirm the procedure completed successfully.
111
+
112
+ ## Rollback
113
+
114
+ If something goes wrong, how to revert.
115
+
116
+ ## Related
117
+
118
+ - Link to related procedures
119
+ - Escalation path if this fails
120
+ ```
121
+
122
+ ## Growing Your Runbook
123
+
124
+ As your runbook matures, consider:
125
+
126
+ **Numbered sections** for ordering (enterprise pattern):
127
+
128
+ ```
129
+ content/
130
+ ├── 00-bootstrap/ # Initial setup, first-run procedures
131
+ ├── 01-operations/ # Day-to-day operational tasks
132
+ ├── 02-incidents/ # Emergency response
133
+ └── 99-reference/ # Templates, glossaries, checklists
134
+ ```
135
+
136
+ **Recipes** - reusable procedures organized by topic:
137
+
138
+ ```
139
+ content/procedures/
140
+ ├── security/
141
+ │ ├── rotate-credentials.md
142
+ │ └── access-review.md
143
+ ├── database/
144
+ │ ├── backup.md
145
+ │ └── restore.md
146
+ └── deployment/
147
+ ├── standard-deploy.md
148
+ └── hotfix-deploy.md
149
+ ```
150
+
151
+ ## The Customizing Guide
152
+
153
+ Every runbook includes `CUSTOMIZING.md` - a commissioning guide for both humans and AI assistants:
154
+
155
+ **What it covers:**
156
+
157
+ - How to add content to each section
158
+ - Adding new sections to `site.yaml`
159
+ - Conventions used in this runbook
160
+ - File linking and cross-references
161
+
162
+ **Important limitations:**
163
+
164
+ - Content must live within the site folder (kitfly cannot include files from outside)
165
+ - External resources should be linked via URL, not copied
166
+ - Binary files (PDFs, images) go in `assets/` and are linked, not rendered
167
+
168
+ This guide helps onboard team members and ensures AI coding assistants understand the structure when helping maintain the runbook.
169
+
170
+ ## Example Use Cases
171
+
172
+ **Integration Runbook** (like Blossman/Cargas)
173
+
174
+ - Procedures: Data sync, batch processing, error recovery
175
+ - Troubleshooting: Connection failures, data format errors, timeout issues
176
+ - Reference/Interfaces: ERP API specs (extracted from vendor PDF), protocol details
177
+ - Reference/Contacts: Vendor support, internal integration team
178
+ - Incidents: Sync failure response, data reconciliation
179
+
180
+ **Platform Runbook**
181
+
182
+ - Procedures: Deploy service, rotate secrets, scale cluster
183
+ - Troubleshooting: High CPU, memory leaks, connection timeouts
184
+ - Reference/Checklists: Production deploy, database migration
185
+ - Reference/Analytics: SLA dashboard links, key metrics
186
+ - Incidents: P1 response, rollback procedure
187
+
188
+ **Security Operations**
189
+
190
+ - Procedures: Credential rotation, access reviews, patch deployment
191
+ - Troubleshooting: Auth failures, certificate expiry, firewall issues
192
+ - Reference/Contacts: Security team, vendor security contacts
193
+ - Incidents: Breach response, compromised credentials
@@ -0,0 +1,163 @@
1
+ ---
2
+ title: Servicebook Template
3
+ description: Professional services catalog with offerings, methodology, and delivery documentation
4
+ ---
5
+
6
+ # Servicebook Template
7
+
8
+ The `servicebook` template creates a documentation site for **professional services practices** — what you sell, how you deliver, and proof of capability. It extends `minimal` with six sections organized around service offerings, delivery methodology, and engagement operations.
9
+
10
+ ## When to Use
11
+
12
+ - Consulting practices documenting their service portfolio
13
+ - Professional services teams standardizing delivery methodology
14
+ - Technical assessment or advisory services needing consistent scoping
15
+ - Organizations building a body of case studies and industry expertise
16
+ - Any situation where the deliverable is expertise, not a product
17
+
18
+ ## What You Get
19
+
20
+ Everything from `minimal`, plus:
21
+
22
+ ```
23
+ my-servicebook/
24
+ ├── site.yaml # Configured with 6 sections
25
+ ├── index.md # Home page with service catalog summary
26
+ ├── CUSTOMIZING.md # How to customize (AI + human friendly)
27
+ ├── content/
28
+ │ ├── offerings/
29
+ │ │ ├── overview.md # Service tiers, engagement models
30
+ │ │ └── assess/
31
+ │ │ ├── overview.md # Example: assessment service
32
+ │ │ ├── deliverables.md # What the client receives
33
+ │ │ └── scoping.md # How we scope an engagement
34
+ │ ├── methodology/
35
+ │ │ ├── phases.md # Explore → Analyze → Synthesize → Deliver
36
+ │ │ ├── tools.md # Tools used in delivery
37
+ │ │ ├── frameworks.md # Assessment frameworks, scoring models
38
+ │ │ └── decisions/
39
+ │ │ ├── index.md # Methodology decision log
40
+ │ │ └── mdr-template.md # Decision record template
41
+ │ ├── delivery/
42
+ │ │ ├── engagement-lifecycle.md # End-to-end engagement flow
43
+ │ │ ├── client-onboarding.md # Prerequisites, setup, kickoff
44
+ │ │ ├── quality-gates.md # Checkpoints throughout delivery
45
+ │ │ └── templates/
46
+ │ │ └── index.md # Deliverable templates and report shells
47
+ │ ├── verticals/
48
+ │ │ └── overview.md # How to document industry context
49
+ │ ├── case-studies/
50
+ │ │ └── index.md # Case study catalog with template
51
+ │ └── reference/
52
+ │ ├── team-expertise.md # Capabilities, specializations
53
+ │ ├── pricing-models.md # Engagement pricing structures
54
+ │ └── contacts/
55
+ │ └── directory.md # Team contacts, escalation
56
+ └── ...
57
+ ```
58
+
59
+ ## Sections
60
+
61
+ | Section | Purpose | Typical Content |
62
+ | ---------------- | --------------------- | -------------------------------------------------------- |
63
+ | **Offerings** | What we deliver | Service tiers, engagement models, deliverables, scoping |
64
+ | **Methodology** | How we do it | Phases, tools, frameworks, methodology decisions |
65
+ | **Delivery** | Engagement operations | Lifecycle, onboarding, quality gates, templates |
66
+ | **Verticals** | Industry context | Regulations, terminology, common challenges per vertical |
67
+ | **Case Studies** | Proof of capability | Past engagements (anonymized), outcomes, lessons learned |
68
+ | **Reference** | Look-up material | Team expertise, pricing models, contacts |
69
+
70
+ ## The Methodology Section
71
+
72
+ This is what makes servicebook different. It captures **how your practice delivers value** — not just what you sell.
73
+
74
+ For a technical assessment practice, this might hold:
75
+
76
+ - **Phases**: Explore (stakeholder interviews) → Analyze (gap analysis) → Synthesize (recommendations) → Deliver (presentation)
77
+ - **Tools**: Interview frameworks, scoring rubrics, analysis templates
78
+ - **Frameworks**: Maturity models, SWOT analysis, weighted scoring for vendor evaluation
79
+ - **Decisions**: Why we switched from 3-phase to 4-phase methodology (MDR-001)
80
+
81
+ For a management consulting practice:
82
+
83
+ - **Phases**: Current State → Target State → Gap Analysis → Roadmap
84
+ - **Tools**: Workshop facilitation tools, benchmarking databases, financial modeling
85
+ - **Frameworks**: Operating model canvas, capability mapping, value stream analysis
86
+ - **Decisions**: Why we standardized on a specific assessment framework
87
+
88
+ The methodology section turns "how we work" from oral tradition into documented, repeatable process.
89
+
90
+ ## Usage
91
+
92
+ ```bash
93
+ kitfly init consulting-docs --template servicebook
94
+ kitfly init consulting-docs --template servicebook --brand "Apex Advisory"
95
+
96
+ # With AI assistance instrumentation
97
+ kitfly init consulting-docs --template servicebook --standalone --ai-assist
98
+ ```
99
+
100
+ ## Servicebook vs. Other Templates
101
+
102
+ | Aspect | Productbook | Servicebook | Handbook |
103
+ | --------------- | --------------------------- | -------------------------- | ----------------- |
104
+ | **Orientation** | What we build | What we sell & deliver | How we work |
105
+ | **Assumes** | One product, iterated | Multiple service offerings | Team exists |
106
+ | **Key section** | Domain | Methodology | Guides |
107
+ | **Audience** | Product team + stakeholders | Delivery team + clients | Team members |
108
+ | **Tone** | Analytical | Professional, prescriptive | Explanatory |
109
+ | **Lifecycle** | Product releases | Engagement lifecycle | Knowledge updates |
110
+
111
+ ## Growing Your Servicebook
112
+
113
+ As the practice matures, the sections grow naturally:
114
+
115
+ **Offerings expand as services are defined** — each service gets its own folder with overview, deliverables, and scoping:
116
+
117
+ ```
118
+ content/offerings/
119
+ ├── overview.md
120
+ ├── assess/
121
+ │ ├── overview.md
122
+ │ ├── deliverables.md
123
+ │ └── scoping.md
124
+ ├── advisory/
125
+ │ ├── overview.md
126
+ │ └── engagement-models.md
127
+ └── implement/
128
+ ├── overview.md
129
+ ├── deliverables.md
130
+ └── scoping.md
131
+ ```
132
+
133
+ **Verticals deepen with experience** — each industry vertical captures specialized knowledge:
134
+
135
+ ```
136
+ content/verticals/
137
+ ├── overview.md
138
+ ├── healthcare.md
139
+ ├── financial-services.md
140
+ └── manufacturing.md
141
+ ```
142
+
143
+ **Case studies accumulate** — the portfolio of evidence grows with each completed engagement.
144
+
145
+ **Methodology evolves through decisions** — the MDR log tracks why the practice changed its approach.
146
+
147
+ ## Example Use Cases
148
+
149
+ **Technical Assessment Practice**
150
+
151
+ - Offerings: Security assessment, architecture review, cloud readiness evaluation
152
+ - Methodology: Discovery interviews, tooling analysis, gap scoring, recommendations
153
+ - Delivery: 2-4 week fixed-scope engagements with standardized quality gates
154
+ - Verticals: Healthcare (HIPAA), finance (SOC 2), government (FedRAMP)
155
+ - Case Studies: Anonymized assessment outcomes with measurable improvements
156
+
157
+ **Management Consulting Practice**
158
+
159
+ - Offerings: Strategy advisory, operating model design, transformation planning
160
+ - Methodology: Current-state analysis, target operating model, roadmap development
161
+ - Delivery: Retainer-based advisory with milestone-based transformation work
162
+ - Verticals: Retail, energy, telecommunications
163
+ - Case Studies: Transformation outcomes, efficiency gains, capability maturation