kitfly 0.1.2 → 0.2.0

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

@@ -0,0 +1,193 @@
+---
+title: Runbook Template
+description: Operational procedures, troubleshooting, and incident response
+---
+
+# Runbook Template
+
+The `runbook` template creates a structured site for operational documentation. It extends `minimal` with sections designed for on-call engineers, SREs, and operations teams.
+
+## When to Use
+
+- Operations documentation
+- On-call runbooks
+- Incident response procedures
+- System administration guides
+- Deployment and maintenance checklists
+- Any docs that answer "what do I do when..."
+
+## What You Get
+
+Everything from `minimal`, plus:
+
+```
+my-runbook/
+├── site.yaml              # Configured with ops sections
+├── index.md               # Home page with quick links
+├── CUSTOMIZING.md         # How to customize this site (AI + human friendly)
+├── content/
+│   ├── procedures/
+│   │   └── deployment.md         # Step-by-step procedures
+│   ├── troubleshooting/
+│   │   └── common-issues.md      # Problem → solution guides
+│   ├── reference/
+│   │   ├── interfaces/
+│   │   │   └── api-template.md   # Integration/API documentation
+│   │   ├── contacts/
+│   │   │   └── directory.md      # Team and vendor contacts
+│   │   ├── checklists/
+│   │   │   └── pre-deploy.md     # Verification checklists
+│   │   └── analytics/
+│   │       └── dashboards.md     # Metrics and KPI definitions
+│   └── incidents/
+│       └── escalation.md         # Incident response paths
+└── ...
+```
+
+## Sections
+
+| Section             | Purpose                          | Typical Content                                      |
+| ------------------- | -------------------------------- | ---------------------------------------------------- |
+| **Procedures**      | How to perform operational tasks | Deployment steps, maintenance tasks, migrations      |
+| **Troubleshooting** | Diagnose and fix issues          | Error codes, symptoms → causes, remediation          |
+| **Reference**       | Look-up information              | Interfaces, contacts, checklists, glossary           |
+| **Incidents**       | Emergency response               | Escalation paths, severity definitions, post-mortems |
+
+The **Reference** section consolidates supporting materials:
+
+| Subsection              | Purpose                                              |
+| ----------------------- | ---------------------------------------------------- |
+| `reference/interfaces/` | API specs, protocol docs, vendor integration details |
+| `reference/contacts/`   | Team directory, vendor contacts, escalation matrix   |
+| `reference/checklists/` | Pre/post deployment, audit, maintenance checklists   |
+| `reference/analytics/`  | Dashboard links, KPIs, SLA definitions               |
+
+## Usage
+
+```bash
+kitfly init ops-docs --template runbook
+kitfly init ops-docs --template runbook --brand "Platform Team"
+```
+
+## Design Principles
+
+Runbooks differ from handbooks in key ways:
+
+| Aspect           | Handbook      | Runbook                    |
+| ---------------- | ------------- | -------------------------- |
+| **Audience**     | Learning      | Doing (often urgently)     |
+| **Reading mode** | Sequential    | Jump to specific procedure |
+| **Goal**         | Understanding | Task completion            |
+| **Tone**         | Explanatory   | Direct, imperative         |
+
+## Procedure Document Format
+
+Each procedure should follow a consistent structure:
+
+```markdown
+# Procedure Name
+
+## Objective
+
+What this procedure accomplishes and when to use it.
+
+## Prerequisites
+
+- [ ] Required access or permissions
+- [ ] Tools or systems that must be available
+- [ ] Related procedures to complete first
+
+## Steps
+
+1. **First action**
+   - Expected output: `what you should see`
+
+2. **Second action**
+   - Verification: How to confirm success
+
+## Verification
+
+How to confirm the procedure completed successfully.
+
+## Rollback
+
+If something goes wrong, how to revert.
+
+## Related
+
+- Link to related procedures
+- Escalation path if this fails
+```
+
+## Growing Your Runbook
+
+As your runbook matures, consider:
+
+**Numbered sections** for ordering (enterprise pattern):
+
+```
+content/
+├── 00-bootstrap/    # Initial setup, first-run procedures
+├── 01-operations/   # Day-to-day operational tasks
+├── 02-incidents/    # Emergency response
+└── 99-reference/    # Templates, glossaries, checklists
+```
+
+**Recipes** - reusable procedures organized by topic:
+
+```
+content/procedures/
+├── security/
+│   ├── rotate-credentials.md
+│   └── access-review.md
+├── database/
+│   ├── backup.md
+│   └── restore.md
+└── deployment/
+    ├── standard-deploy.md
+    └── hotfix-deploy.md
+```
+
+## The Customizing Guide
+
+Every runbook includes `CUSTOMIZING.md` - a commissioning guide for both humans and AI assistants:
+
+**What it covers:**
+
+- How to add content to each section
+- Adding new sections to `site.yaml`
+- Conventions used in this runbook
+- File linking and cross-references
+
+**Important limitations:**
+
+- Content must live within the site folder (kitfly cannot include files from outside)
+- External resources should be linked via URL, not copied
+- Binary files (PDFs, images) go in `assets/` and are linked, not rendered
+
+This guide helps onboard team members and ensures AI coding assistants understand the structure when helping maintain the runbook.
+
+## Example Use Cases
+
+**Integration Runbook** (like Blossman/Cargas)
+
+- Procedures: Data sync, batch processing, error recovery
+- Troubleshooting: Connection failures, data format errors, timeout issues
+- Reference/Interfaces: ERP API specs (extracted from vendor PDF), protocol details
+- Reference/Contacts: Vendor support, internal integration team
+- Incidents: Sync failure response, data reconciliation
+
+**Platform Runbook**
+
+- Procedures: Deploy service, rotate secrets, scale cluster
+- Troubleshooting: High CPU, memory leaks, connection timeouts
+- Reference/Checklists: Production deploy, database migration
+- Reference/Analytics: SLA dashboard links, key metrics
+- Incidents: P1 response, rollback procedure
+
+**Security Operations**
+
+- Procedures: Credential rotation, access reviews, patch deployment
+- Troubleshooting: Auth failures, certificate expiry, firewall issues
+- Reference/Contacts: Security team, vendor security contacts
+- Incidents: Breach response, compromised credentials

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

@@ -0,0 +1,163 @@
+---
+title: Servicebook Template
+description: Professional services catalog with offerings, methodology, and delivery documentation
+---
+
+# Servicebook Template
+
+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.
+
+## When to Use
+
+- Consulting practices documenting their service portfolio
+- Professional services teams standardizing delivery methodology
+- Technical assessment or advisory services needing consistent scoping
+- Organizations building a body of case studies and industry expertise
+- Any situation where the deliverable is expertise, not a product
+
+## What You Get
+
+Everything from `minimal`, plus:
+
+```
+my-servicebook/
+├── site.yaml              # Configured with 6 sections
+├── index.md               # Home page with service catalog summary
+├── CUSTOMIZING.md         # How to customize (AI + human friendly)
+├── content/
+│   ├── offerings/
+│   │   ├── overview.md            # Service tiers, engagement models
+│   │   └── assess/
+│   │       ├── overview.md        # Example: assessment service
+│   │       ├── deliverables.md    # What the client receives
+│   │       └── scoping.md         # How we scope an engagement
+│   ├── methodology/
+│   │   ├── phases.md              # Explore → Analyze → Synthesize → Deliver
+│   │   ├── tools.md               # Tools used in delivery
+│   │   ├── frameworks.md          # Assessment frameworks, scoring models
+│   │   └── decisions/
+│   │       ├── index.md           # Methodology decision log
+│   │       └── mdr-template.md    # Decision record template
+│   ├── delivery/
+│   │   ├── engagement-lifecycle.md  # End-to-end engagement flow
+│   │   ├── client-onboarding.md     # Prerequisites, setup, kickoff
+│   │   ├── quality-gates.md         # Checkpoints throughout delivery
+│   │   └── templates/
+│   │       └── index.md             # Deliverable templates and report shells
+│   ├── verticals/
+│   │   └── overview.md             # How to document industry context
+│   ├── case-studies/
+│   │   └── index.md               # Case study catalog with template
+│   └── reference/
+│       ├── team-expertise.md      # Capabilities, specializations
+│       ├── pricing-models.md      # Engagement pricing structures
+│       └── contacts/
+│           └── directory.md       # Team contacts, escalation
+└── ...
+```
+
+## Sections
+
+| Section          | Purpose               | Typical Content                                          |
+| ---------------- | --------------------- | -------------------------------------------------------- |
+| **Offerings**    | What we deliver       | Service tiers, engagement models, deliverables, scoping  |
+| **Methodology**  | How we do it          | Phases, tools, frameworks, methodology decisions         |
+| **Delivery**     | Engagement operations | Lifecycle, onboarding, quality gates, templates          |
+| **Verticals**    | Industry context      | Regulations, terminology, common challenges per vertical |
+| **Case Studies** | Proof of capability   | Past engagements (anonymized), outcomes, lessons learned |
+| **Reference**    | Look-up material      | Team expertise, pricing models, contacts                 |
+
+## The Methodology Section
+
+This is what makes servicebook different. It captures **how your practice delivers value** — not just what you sell.
+
+For a technical assessment practice, this might hold:
+
+- **Phases**: Explore (stakeholder interviews) → Analyze (gap analysis) → Synthesize (recommendations) → Deliver (presentation)
+- **Tools**: Interview frameworks, scoring rubrics, analysis templates
+- **Frameworks**: Maturity models, SWOT analysis, weighted scoring for vendor evaluation
+- **Decisions**: Why we switched from 3-phase to 4-phase methodology (MDR-001)
+
+For a management consulting practice:
+
+- **Phases**: Current State → Target State → Gap Analysis → Roadmap
+- **Tools**: Workshop facilitation tools, benchmarking databases, financial modeling
+- **Frameworks**: Operating model canvas, capability mapping, value stream analysis
+- **Decisions**: Why we standardized on a specific assessment framework
+
+The methodology section turns "how we work" from oral tradition into documented, repeatable process.
+
+## Usage
+
+```bash
+kitfly init consulting-docs --template servicebook
+kitfly init consulting-docs --template servicebook --brand "Apex Advisory"
+
+# With AI assistance instrumentation
+kitfly init consulting-docs --template servicebook --standalone --ai-assist
+```
+
+## Servicebook vs. Other Templates
+
+| Aspect          | Productbook                 | Servicebook                | Handbook          |
+| --------------- | --------------------------- | -------------------------- | ----------------- |
+| **Orientation** | What we build               | What we sell & deliver     | How we work       |
+| **Assumes**     | One product, iterated       | Multiple service offerings | Team exists       |
+| **Key section** | Domain                      | Methodology                | Guides            |
+| **Audience**    | Product team + stakeholders | Delivery team + clients    | Team members      |
+| **Tone**        | Analytical                  | Professional, prescriptive | Explanatory       |
+| **Lifecycle**   | Product releases            | Engagement lifecycle       | Knowledge updates |
+
+## Growing Your Servicebook
+
+As the practice matures, the sections grow naturally:
+
+**Offerings expand as services are defined** — each service gets its own folder with overview, deliverables, and scoping:
+
+```
+content/offerings/
+├── overview.md
+├── assess/
+│   ├── overview.md
+│   ├── deliverables.md
+│   └── scoping.md
+├── advisory/
+│   ├── overview.md
+│   └── engagement-models.md
+└── implement/
+    ├── overview.md
+    ├── deliverables.md
+    └── scoping.md
+```
+
+**Verticals deepen with experience** — each industry vertical captures specialized knowledge:
+
+```
+content/verticals/
+├── overview.md
+├── healthcare.md
+├── financial-services.md
+└── manufacturing.md
+```
+
+**Case studies accumulate** — the portfolio of evidence grows with each completed engagement.
+
+**Methodology evolves through decisions** — the MDR log tracks why the practice changed its approach.
+
+## Example Use Cases
+
+**Technical Assessment Practice**
+
+- Offerings: Security assessment, architecture review, cloud readiness evaluation
+- Methodology: Discovery interviews, tooling analysis, gap scoring, recommendations
+- Delivery: 2-4 week fixed-scope engagements with standardized quality gates
+- Verticals: Healthcare (HIPAA), finance (SOC 2), government (FedRAMP)
+- Case Studies: Anonymized assessment outcomes with measurable improvements
+
+**Management Consulting Practice**
+
+- Offerings: Strategy advisory, operating model design, transformation planning
+- Methodology: Current-state analysis, target operating model, roadmap development
+- Delivery: Retainer-based advisory with milestone-based transformation work
+- Verticals: Retail, energy, telecommunications
+- Case Studies: Transformation outcomes, efficiency gains, capability maturation

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

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

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

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