kitfly 0.1.2 → 0.2.0

package/dist/_raw/content/templates/minimal.md

@@ -0,0 +1,138 @@
+---
+title: Minimal Template
+description: The base template that all others extend
+---
+
+# Minimal Template
+
+The `minimal` template is the foundation. Every other template extends it, inheriting these core files. Use it when you want complete control over your site's structure.
+
+## When to Use
+
+- You want to define your own sections from scratch
+- Your documentation doesn't fit the patterns of handbook, runbook, pipeline, or productbook
+- You're prototyping or experimenting with kitfly
+- You plan to build a custom structure for a specific domain
+
+## What You Get
+
+```
+my-site/
+├── site.yaml        # Basic configuration (no sections)
+├── index.md         # Simple welcome page
+├── .gitignore       # Standard ignores
+├── README.md        # Project documentation
+├── content/         # Empty, ready for your structure
+│   └── .gitkeep
+└── assets/brand/    # Placeholder for logo, favicon
+    └── .gitkeep
+```
+
+## Usage
+
+```bash
+kitfly init my-site
+# or explicitly:
+kitfly init my-site --template minimal
+```
+
+## Building Your Own Structure
+
+Creating a custom site from minimal takes three steps:
+
+### 1. Create content folders
+
+Organize your markdown files under `content/` however makes sense for your domain:
+
+```
+content/
+├── concepts/
+│   ├── overview.md
+│   └── architecture.md
+├── workflows/
+│   ├── onboarding.md
+│   ├── review-process.md
+│   └── advanced/
+│       ├── index.md
+│       └── custom-pipelines.md
+└── api/
+    ├── authentication.md
+    └── endpoints/
+        ├── users.md
+        └── projects.md
+```
+
+### 2. Define sections in `site.yaml`
+
+Each section maps to a folder. The sidebar builds automatically from your files:
+
+```yaml
+title: "My Platform Docs"
+
+brand:
+  name: "Platform"
+  url: "/"
+
+sections:
+  - name: "Concepts"
+    path: "content/concepts"
+  - name: "Workflows"
+    path: "content/workflows"
+  - name: "API"
+    path: "content/api"
+```
+
+### 3. Add markdown files
+
+Write your content. Each `.md` file appears in the sidebar under its section. That's it — no registration step, no config per file.
+
+## Hierarchical Navigation
+
+Kitfly automatically organizes deeper folder structures into collapsible navigation groups. If you nest files inside subdirectories, the sidebar reflects that hierarchy:
+
+```
+WORKFLOWS
+  onboarding
+  review-process
+  ▸ advanced          ← click to expand
+      custom-pipelines
+```
+
+- Subdirectories appear as collapsible groups with expand/collapse indicators
+- An `index.md` inside a subdirectory becomes the clickable link on the group label
+- Flat sections (no subdirectories) render as simple lists — no extra overhead
+- No JavaScript required — this uses native HTML `<details>` elements
+
+This means you can start flat and add depth later without changing any configuration. Just create subdirectories and the sidebar adapts.
+
+## Configuration
+
+The generated `site.yaml` includes commented examples to get you started:
+
+```yaml
+title: "My Site"
+
+brand:
+  name: "My Brand"
+  url: "/"
+
+# Uncomment and customize:
+# sections:
+#   - name: "Guide"
+#     path: "content/guide"
+#   - name: "Reference"
+#     path: "content/reference"
+```
+
+## When to Use a Specialized Template Instead
+
+If your site fits one of these patterns, start with a specialized template — you'll get curated sections, starter content, and a `CUSTOMIZING.md` guide:
+
+| Pattern                   | Template      | Why                                        |
+| ------------------------- | ------------- | ------------------------------------------ |
+| Team knowledge base       | `handbook`    | Overview / Guides / Reference structure    |
+| Service operations        | `runbook`     | Procedures, troubleshooting, incidents     |
+| Data pipeline ops         | `pipeline`    | Stages, sources, destinations, manifests   |
+| Product + business domain | `productbook` | Features, domain processes, planning, ADRs |
+
+You can always restructure later — templates are starting points, not constraints.

package/dist/_raw/content/templates/overview.md

@@ -0,0 +1,187 @@
+---
+title: Templates Overview
+description: How kitfly templates work and the layering model
+---
+
+# Templates
+
+Templates provide starting points for new kitfly sites. Each template creates a folder structure, configuration, and starter content appropriate for a specific use case.
+
+## The Layering Model
+
+Templates follow a simple inheritance pattern:
+
+```
+minimal (base)
+   ├── handbook    (team documentation)
+   ├── runbook     (operational procedures)
+   ├── pipeline    (data pipeline operations)
+   ├── productbook (product & domain knowledge)
+   ├── servicebook (professional services catalog)
+   └── crucible    (information architecture SSOT)
+```
+
+Every template **extends `minimal`**, which provides the essential files every site needs. Specialized templates add sections and starter content on top.
+
+## What Templates Create
+
+When you run `kitfly init`, the template generates:
+
+| Component        | Source                | Purpose                                     |
+| ---------------- | --------------------- | ------------------------------------------- |
+| `site.yaml`      | Template              | Site configuration with sections defined    |
+| `index.md`       | Template              | Home page with navigation to sections       |
+| `content/`       | Template              | Folder structure with starter files         |
+| `.gitignore`     | `minimal`             | Standard ignores for builds, deps, OS files |
+| `README.md`      | `minimal`             | Project readme with dev commands            |
+| `CUSTOMIZING.md` | Specialized templates | How to customize (AI + human friendly)      |
+| `assets/brand/`  | `minimal`             | Placeholder for logo, favicon               |
+
+### The Customizing Guide
+
+Specialized templates include `CUSTOMIZING.md` — an onboarding document that helps both humans and AI assistants understand:
+
+- **Structure**: What each section is for, naming conventions
+- **Adding content**: Where to put new files, how to create sections
+- **Linking**: How to cross-reference within the site
+- **Limitations**: Content must live in the site folder; external files linked via URL
+
+### Provenance Record
+
+Every generated site includes provenance metadata (in `CUSTOMIZING.md` header):
+
+```yaml
+---
+template: runbook
+template_version: 1
+created: 2026-02-04
+kitfly_version: 0.1.0
+---
+```
+
+This tracks:
+
+- **template**: Which template was used
+- **template_version**: Version of that template's structure
+- **created**: When the site was initialized
+- **kitfly_version**: Kitfly version at creation time
+
+Provenance helps when upgrading sites or understanding what conventions were in place at creation time.
+
+## The `.kitfly/` Metadata Folder
+
+Sites can have a `.kitfly/` folder for kitfly-specific metadata (gitignored by default).
+
+### All Sites: `manifest.json`
+
+Every site gets a manifest tracking creation metadata:
+
+```json
+{
+  "template": "runbook",
+  "templateVersion": 1,
+  "created": "2026-02-04T14:30:00Z",
+  "kitflyVersion": "0.1.0",
+  "standalone": false
+}
+```
+
+### Standalone Sites: `provenance.json`
+
+Standalone sites additionally track copied files with SHA256 hashes:
+
+```json
+{
+  "kitflyVersion": "0.1.0",
+  "createdAt": "2026-02-04T14:30:00Z",
+  "template": "runbook",
+  "files": [
+    { "path": "scripts/dev.ts", "sourceHash": "a1b2c3..." },
+    { "path": "src/engine.ts", "sourceHash": "d4e5f6..." }
+  ]
+}
+```
+
+**Why hashes?** For future `kitfly update` support:
+
+- Compare hashes to detect user modifications
+- Safely update unmodified files
+- Warn before overwriting customized code
+- Track version gaps that need bridging
+
+### Future: `updates.json`
+
+When `kitfly update` ships (v0.2.x), we'll track update history:
+
+```json
+{
+  "updates": [
+    {
+      "date": "2026-03-15T10:00:00Z",
+      "fromVersion": "0.1.0",
+      "toVersion": "0.2.0",
+      "filesUpdated": ["scripts/dev.ts", "src/theme.ts"],
+      "filesSkipped": ["scripts/build.ts"]
+    }
+  ]
+}
+```
+
+This enables rollback awareness and audit trails for managed sites.
+
+## Choosing a Template
+
+| Template      | Best For                                           | Sections                                                                |
+| ------------- | -------------------------------------------------- | ----------------------------------------------------------------------- |
+| `minimal`     | Custom structures, experimentation                 | None predefined — you define your own                                   |
+| `handbook`    | Team docs, onboarding, knowledge bases             | Overview, Guides, Reference                                             |
+| `runbook`     | Operations, procedures, incidents                  | Procedures, Troubleshooting, Reference, Incidents                       |
+| `pipeline`    | Data pipeline operations                           | Pipeline, Sources, Destinations, Operations, Troubleshooting, Reference |
+| `productbook` | Product + domain docs for complex engagements      | Product, Domain, Planning, Operations, Guides, Reference                |
+| `servicebook` | Professional services, consulting catalogs         | Offerings, Methodology, Delivery, Verticals, Case Studies, Reference    |
+| `crucible`    | Information architecture SSOT, ecosystem standards | Specs, Schemas, Config, Policies, Guides, Reference                     |
+
+## Usage
+
+```bash
+# Create with default template (minimal)
+kitfly init my-site
+
+# Create with specific template
+kitfly init my-docs --template handbook
+
+# Add branding
+kitfly init my-docs --template handbook --brand "Acme Corp"
+
+# Create standalone (includes kitfly site code)
+kitfly init my-docs --template handbook --standalone
+
+# Add AI assistance instrumentation
+kitfly init my-docs --template runbook --ai-assist
+
+# Skip git initialization
+kitfly init my-docs --template handbook --no-git
+```
+
+## Lifecycle Operations
+
+Kitfly focuses on **creation** only:
+
+| Operation | Support         | Notes                                 |
+| --------- | --------------- | ------------------------------------- |
+| Create    | `kitfly init`   | Full template system                  |
+| Read      | `kitfly dev`    | Preview any markdown folder           |
+| Update    | `kitfly update` | Planned for v0.2.x                    |
+| Delete    | Not supported   | Use `rm -rf` - sites are just folders |
+
+**Why no delete?** Sites are self-contained folders with no external references. Deleting is simply removing the folder. There's no registry or metadata outside the site to clean up.
+
+## Template Details
+
+- [Minimal](minimal) — The base layer every site inherits
+- [Handbook](handbook) — Team documentation structure
+- [Runbook](runbook) — Operational procedures and checklists
+- [Pipeline](pipeline) — Data pipeline stages, sources, and destinations
+- [Productbook](productbook) — Product and domain knowledge for greenfield engagements
+- [Servicebook](servicebook) — Professional services catalog with methodology and delivery
+- [Crucible](crucible) — Information architecture SSOT with specs, schemas, and governance

package/dist/_raw/content/templates/pipeline.md

@@ -0,0 +1,151 @@
+---
+title: Pipeline Template
+description: Data pipeline operations with stages, sources, destinations, and manifests
+---
+
+# Pipeline Template
+
+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.
+
+## When to Use
+
+- Data pipeline operational documentation
+- ETL/ELT process runbooks
+- Data migration projects
+- Batch processing operations
+- Any workflow with sequential stages moving data from sources to destinations
+
+## What You Get
+
+Everything from `minimal`, plus:
+
+```
+my-pipeline/
+├── site.yaml              # Configured with pipeline sections
+├── index.md               # Pipeline status dashboard with quick links
+├── CUSTOMIZING.md         # How to customize (AI + human friendly)
+├── content/
+│   ├── pipeline/
+│   │   ├── overview.md          # End-to-end dataflow
+│   │   ├── index-build.md       # Index build stage
+│   │   ├── extract.md           # Content extraction stage
+│   │   ├── transfer.md          # Transfer / reflow stage
+│   │   └── validate.md          # Validation stage
+│   ├── sources/
+│   │   └── index.md             # Source system catalog
+│   ├── destinations/
+│   │   └── index.md             # Destination catalog
+│   ├── operations/
+│   │   ├── run-pipeline.md      # Full execution procedure
+│   │   └── schedules.md         # Pipeline schedule table
+│   ├── troubleshooting/
+│   │   └── common-issues.md     # Pipeline-specific issues
+│   └── reference/
+│       ├── manifests/
+│       │   └── index.md         # Job manifest YAML templates
+│       ├── field-mappings/
+│       │   └── index.md         # Source → destination mappings
+│       ├── metrics/
+│       │   └── index.md         # Pipeline KPIs and SLAs
+│       ├── checklists/
+│       │   └── pre-run.md       # Pre-run verification
+│       └── contacts/
+│           └── directory.md     # Team contacts and escalation
+└── ...
+```
+
+## Sections
+
+| Section             | Purpose                     | Typical Content                                                   |
+| ------------------- | --------------------------- | ----------------------------------------------------------------- |
+| **Pipeline**        | Core dataflow documentation | Stage definitions, data movement, processing logic                |
+| **Sources**         | Input systems               | Connection details, schemas, auth profiles, data formats          |
+| **Destinations**    | Output systems              | Target structures, path layouts, landing zones                    |
+| **Operations**      | Run procedures              | Execution steps, schedules, checkpoint/resume                     |
+| **Troubleshooting** | Problem resolution          | Auth expiry, index locks, duplicate conflicts, collision handling |
+| **Reference**       | Supporting materials        | Manifests, field mappings, metrics, checklists, contacts          |
+
+### Pipeline vs. Runbook
+
+Both are operational templates, but they serve different shapes of work:
+
+| Aspect              | Runbook                          | Pipeline                                 |
+| ------------------- | -------------------------------- | ---------------------------------------- |
+| **Focus**           | Service operations               | Data movement                            |
+| **Structure**       | Procedures + incidents           | Sequential stages + sources/destinations |
+| **Key question**    | "What do I do when X breaks?"    | "How does data flow from A to B?"        |
+| **Reference model** | Interfaces, contacts, checklists | Manifests, field mappings, metrics       |
+
+## Usage
+
+```bash
+kitfly init data-ops --template pipeline
+kitfly init data-ops --template pipeline --brand "Data Platform"
+
+# With AI assistance instrumentation
+kitfly init data-ops --template pipeline --standalone --ai-assist
+```
+
+## The Pipeline Section
+
+The core of this template. Each stage is documented with:
+
+- **Objective** — what the stage accomplishes
+- **Prerequisites** — what must be in place before running
+- **Procedure** — step-by-step execution
+- **Verification** — how to confirm success
+
+The default stages follow a common data pipeline pattern:
+
+```
+Source → Index Build → Content Extraction → Transfer/Reflow → Validation → Destination
+```
+
+Adapt these to your actual pipeline. Add, remove, or rename stages as needed.
+
+## Growing Your Pipeline Docs
+
+As your pipeline matures, consider expanding:
+
+**Multiple pipelines** — add subdirectories under `content/pipeline/`:
+
+```
+content/pipeline/
+├── overview.md
+├── daily-sync/
+│   ├── index.md
+│   ├── extract.md
+│   └── validate.md
+└── quarterly-migration/
+    ├── index.md
+    └── stages.md
+```
+
+The sidebar automatically organizes these into collapsible groups — each subdirectory becomes an expandable section in the navigation.
+
+**Multiple sources/destinations** — add a page per system:
+
+```
+content/sources/
+├── index.md           # Catalog table
+├── salesforce.md      # Source details
+└── data-warehouse.md  # Source details
+```
+
+## Example Use Cases
+
+**Cloud Data Migration**
+
+- Pipeline: S3 scan → content probe → key rewrite → validation
+- Sources: AWS S3 buckets with legacy key structure
+- Destinations: GCS with date-partitioned layout
+- Operations: Weekly full sync, daily incremental
+- Reference/Manifests: Job definitions per source bucket
+
+**ETL for Analytics**
+
+- Pipeline: Extract from APIs → transform/enrich → load to warehouse
+- Sources: REST APIs, SFTP drops, webhook events
+- Destinations: Snowflake tables, Parquet files in S3
+- Troubleshooting: Rate limits, schema drift, partial loads
+- Reference/Metrics: Row counts, freshness SLAs, error rates

package/dist/_raw/content/templates/productbook.md

@@ -0,0 +1,187 @@
+---
+title: Productbook Template
+description: Product and domain documentation for complex greenfield engagements
+---
+
+# Productbook Template
+
+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.
+
+## When to Use
+
+- Greenfield product development in complex business domains
+- Client engagements that need to capture domain expertise alongside product specs
+- Products with regulatory, industry, or process complexity
+- Projects where the team needs a shared reference for "how this business works"
+- Any situation where product decisions depend on deep domain understanding
+
+## What You Get
+
+Everything from `minimal`, plus:
+
+```
+my-productbook/
+├── site.yaml              # Configured with 6 sections
+├── index.md               # Home page with product status and quick links
+├── CUSTOMIZING.md         # How to customize (AI + human friendly)
+├── content/
+│   ├── product/
+│   │   ├── overview.md            # Vision, users, capabilities
+│   │   ├── features/
+│   │   │   └── index.md           # Feature catalog
+│   │   └── releases/
+│   │       └── index.md           # Release log
+│   ├── domain/
+│   │   ├── overview.md            # Business domain context
+│   │   ├── processes/
+│   │   │   └── index.md           # Business process catalog
+│   │   ├── data-dictionary.md     # Terms and definitions
+│   │   └── industry-notes.md      # Regulations and standards
+│   ├── planning/
+│   │   ├── roadmap.md             # Phases and priorities
+│   │   ├── decisions/
+│   │   │   ├── index.md           # Decision log (ADR pattern)
+│   │   │   └── adr-template.md    # ADR template
+│   │   ├── specs/
+│   │   │   └── index.md           # Specification index
+│   │   └── research/
+│   │       └── index.md           # Research index
+│   ├── operations/
+│   │   ├── environments.md        # Dev, staging, production
+│   │   └── deployment.md          # Deployment procedures
+│   ├── guides/
+│   │   ├── getting-started.md     # Onboarding guide
+│   │   └── user-guide.md          # End-user documentation
+│   └── reference/
+│       ├── architecture/
+│       │   └── overview.md        # System architecture
+│       ├── integrations/
+│       │   └── index.md           # Integration catalog
+│       ├── data-models/
+│       │   └── overview.md        # Schemas and data flow
+│       ├── contacts/
+│       │   └── directory.md       # Team and vendor contacts
+│       └── metrics/
+│           └── overview.md        # KPIs and dashboards
+└── ...
+```
+
+## Sections
+
+| Section        | Purpose              | Typical Content                                            |
+| -------------- | -------------------- | ---------------------------------------------------------- |
+| **Product**    | What we're building  | Vision, features, releases, acceptance criteria            |
+| **Domain**     | The business reality | Processes, terminology, data dictionary, industry context  |
+| **Planning**   | Why and when         | Roadmap, ADRs, specifications, research                    |
+| **Operations** | How we run it        | Environments, deployment, configuration                    |
+| **Guides**     | How to use it        | Onboarding, tutorials, user documentation                  |
+| **Reference**  | Look-up material     | Architecture, integrations, data models, contacts, metrics |
+
+## The Domain Section
+
+This is what makes productbook different from every other template. It captures the **complex business reality** that the product operates in.
+
+For a propane delivery company, this might hold:
+
+- **Processes**: Tank monitoring workflow, delivery scheduling, seasonal demand forecasting
+- **Data Dictionary**: What "will-call" vs "automatic" delivery means, ERP entity definitions
+- **Industry Notes**: DOT regulations for hazmat transport, state-level propane licensing
+
+For a healthcare platform:
+
+- **Processes**: Claims adjudication, prior authorization, formulary management
+- **Data Dictionary**: CPT codes, NDC numbers, explanation of benefits
+- **Industry Notes**: HIPAA requirements, CMS guidelines, state insurance mandates
+
+This section is the "context dump" that every new team member and AI agent needs. It turns tribal knowledge into navigable documentation.
+
+## Planning Artifacts
+
+The planning section includes built-in support for common planning patterns:
+
+**Decision Records (ADRs)** — each decision documented with:
+
+- Context: What prompted this decision
+- Options: What we considered
+- Decision: What we chose and why
+- Consequences: What follows from this choice
+
+**Specifications** — feature specs with:
+
+- Problem statement
+- Proposed solution
+- Acceptance criteria
+- Status tracking
+
+**Research** — structured research outputs:
+
+- Market analysis
+- User research findings
+- Technology assessments
+
+The sidebar organizes these into collapsible groups — decisions, specs, and research each appear as expandable subsections under Planning.
+
+## Usage
+
+```bash
+kitfly init client-docs --template productbook
+kitfly init client-docs --template productbook --brand "Project Atlas"
+
+# With AI assistance instrumentation
+kitfly init client-docs --template productbook --standalone --ai-assist
+```
+
+## Productbook vs. Other Templates
+
+| Aspect          | Handbook     | Runbook                | Productbook                 |
+| --------------- | ------------ | ---------------------- | --------------------------- |
+| **Orientation** | How we work  | How we keep it running | What we're building and why |
+| **Assumes**     | Team exists  | System exists          | Starting from scratch       |
+| **Key section** | Guides       | Procedures             | Domain                      |
+| **Audience**    | Team members | Operators              | Product team + stakeholders |
+| **Tone**        | Explanatory  | Imperative             | Analytical                  |
+
+## Growing Your Productbook
+
+As the engagement matures, the sections grow naturally:
+
+**Domain deepens first** — business process docs accumulate as the team learns the domain:
+
+```
+content/domain/processes/
+├── index.md
+├── order-fulfillment.md
+├── returns-processing.md
+├── inventory-reconciliation.md
+└── seasonal-forecasting.md
+```
+
+**Product fills in as features ship** — feature pages link to the domain processes they automate:
+
+```
+content/product/features/
+├── index.md
+├── auto-scheduling.md      # References domain/processes/delivery-scheduling
+├── tank-monitoring.md       # References domain/processes/tank-monitoring
+└── customer-portal.md
+```
+
+**Planning captures decisions over time** — the ADR log becomes a valuable historical record.
+
+## Example Use Cases
+
+**Enterprise SaaS for Complex Industry**
+
+- Product: Platform features, integrations, user workflows
+- Domain: Industry processes, regulatory requirements, competitive context
+- Planning: Roadmap, ADRs for technology and vendor choices
+- Guides: Customer onboarding, admin guides
+- Reference: API architecture, third-party integrations, data models
+
+**Client Engagement with Legacy System Modernization**
+
+- Product: New platform capabilities replacing legacy functions
+- Domain: Existing business processes, data structures, edge cases the legacy handles
+- Planning: Migration specs, cutover decisions, research on replacement options
+- Operations: Parallel-run environments, migration deployment procedures
+- Reference: Legacy system documentation, data mapping, vendor contacts