kitfly 0.1.2 → 0.2.1

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

@@ -0,0 +1,192 @@
+---
+title: Crucible Template
+description: Information architecture SSOT with specs, schemas, config, and governance
+---
+
+# Crucible Template
+
+The `crucible` template creates a **layer-0 information architecture site** — the single source of truth (SSOT) for an ecosystem's specifications, schemas, configuration, and governance. It extends `minimal` with six sections and a four-zone layout that separates rendered documentation from machine-consumable artifacts.
+
+## When to Use
+
+- Establishing the foundational standards for a new ecosystem or platform
+- Centralizing specs, schemas, and config that multiple projects depend on
+- Governing an organization's technical standards, policies, and decision records
+- Creating a reference architecture that AI agents and humans consume together
+- Any situation where you need a "layer 0" that everything else builds on
+
+## What You Get
+
+Everything from `minimal`, plus:
+
+```
+my-crucible/
+├── site.yaml              # Configured with 6 sections
+├── index.md               # Home page with standards status and zone overview
+├── CUSTOMIZING.md         # Four-zone layout guide (AI + human friendly)
+├── content/
+│   ├── specs/
+│   │   ├── overview.md            # Standards catalog with status table
+│   │   └── spec-template.md       # Specification template (RFC 2119)
+│   ├── schemas/
+│   │   ├── index.md               # Schema catalog linking to raw files
+│   │   └── versioning.md          # Schema versioning policy
+│   ├── config/
+│   │   ├── overview.md            # Config catalog overview
+│   │   ├── roles.md               # Role definitions documentation
+│   │   └── prompts.md             # Prompt templates documentation
+│   ├── policies/
+│   │   ├── security-model.md      # Security baseline
+│   │   ├── dependency-policy.md   # Dependency governance
+│   │   └── change-procedure.md    # How changes are approved
+│   ├── guides/
+│   │   ├── getting-started.md     # Consuming the crucible
+│   │   └── contributing.md        # Adding specs, schemas, config
+│   └── reference/
+│       ├── decisions/
+│       │   ├── index.md           # Decision log (ADR pattern)
+│       │   └── adr-template.md    # ADR template
+│       ├── changelog/
+│       │   └── index.md           # Release log
+│       └── glossary.md            # Terminology
+├── internal/
+│   └── ops/
+│       └── README.md              # Explains the internal zone
+└── ...
+```
+
+## Sections
+
+| Section       | Purpose                | Typical Content                                                 |
+| ------------- | ---------------------- | --------------------------------------------------------------- |
+| **Specs**     | What the standards are | Specifications, technical definitions, RFC 2119 requirements    |
+| **Schemas**   | The contracts          | Schema catalog, versioning policy, field documentation          |
+| **Config**    | The data               | Configuration catalogs, taxonomies, role and prompt definitions |
+| **Policies**  | The rules              | Security model, dependency governance, change procedures        |
+| **Guides**    | How to use it          | Getting started, contributing, integration guides               |
+| **Reference** | Look-up material       | Decision records, changelog, glossary                           |
+
+## The Four-Zone Model
+
+This is what makes crucible different from every other template. Crucibles serve two audiences simultaneously — **humans reading documentation** and **machines consuming schemas and config**. The four-zone layout makes this explicit:
+
+```
+my-crucible/
+├── content/           ← RENDERED: kitfly documentation sections
+├── schemas/           ← MACHINE: JSON Schema files (consumed by code)
+├── config/            ← MACHINE: YAML catalogs, roles, prompts
+├── internal/          ← PROJECT: repo ops, project code, automation
+├── src/               ← KITFLY: site engine (standalone only)
+└── scripts/           ← KITFLY: build scripts (standalone only)
+```
+
+**Zone rules:**
+
+- `content/` documents the artifacts in other zones (e.g., `content/schemas/` documents `schemas/`)
+- `schemas/` and `config/` are machine-consumable — other projects `$ref` or import from these paths
+- `internal/` holds repo housekeeping, project code (lang wrappers, code generators), and automation
+- `src/` and `scripts/` are kitfly's territory (standalone mode only)
+
+For a WASM skill platform, this might look like:
+
+- **Machine zone**: `schemas/ipc/v0/control.schema.json`, `config/agentic/roles/devlead.yaml`
+- **Content zone**: `content/schemas/ipc-protocol.md` documenting those schemas
+- **Internal zone**: `internal/src/` for language-specific SDK generators
+
+## The Config Section
+
+Crucibles define the **agentic catalog** — roles and prompts that AI agents use across the ecosystem:
+
+```
+config/agentic/
+├── roles/           # WHO — role definitions (scope, mindset, anti-patterns)
+├── prompts/         # HOW — reusable prompt templates for specific tasks
+└── README.md
+```
+
+Roles define identity ("I am a devlead"). Prompts define approach ("Write a spec following this template"). The `content/config/` section documents these for human consumption.
+
+## Usage
+
+```bash
+kitfly init my-crucible --template crucible
+kitfly init my-crucible --template crucible --brand "Lanyte Standards"
+
+# With AI assistance instrumentation
+kitfly init my-crucible --template crucible --standalone --ai-assist
+```
+
+## Crucible vs. Other Templates
+
+| Aspect                | Handbook     | Productbook    | Crucible                        |
+| --------------------- | ------------ | -------------- | ------------------------------- |
+| **Orientation**       | How we work  | What we build  | What everything is built on     |
+| **Assumes**           | Team exists  | Product exists | Ecosystem starting              |
+| **Key section**       | Guides       | Domain         | Specs                           |
+| **Audience**          | Team members | Product team   | All consumers + machines        |
+| **Tone**              | Explanatory  | Analytical     | Prescriptive (RFC 2119)         |
+| **Machine artifacts** | None         | None           | Schemas + config alongside docs |
+
+## Growing Your Crucible
+
+As the ecosystem matures, the sections grow naturally:
+
+**Specs accumulate as standards are defined** — each standard gets its own page:
+
+```
+content/specs/
+├── overview.md
+├── spec-template.md
+├── skill-abi-v1.md
+├── ipc-protocol.md
+├── autonomy-model.md
+└── capability-model.md
+```
+
+**Schemas grow with the type system** — organized by domain and version:
+
+```
+schemas/
+├── ipc/v0/
+│   ├── control.schema.json
+│   ├── command.schema.json
+│   └── telemetry.schema.json
+├── skill/v0/
+│   ├── manifest.schema.json
+│   └── capability.schema.json
+└── config/v0/
+    └── autonomy-gates.schema.json
+```
+
+**Policies solidify through experience** — security model, dependency rules, and change procedures evolve.
+
+**Decisions capture the "why"** — the ADR log becomes the institutional memory.
+
+## Example Use Cases
+
+**WASM Skill Platform (Lanyte)**
+
+- Specs: Skill ABI, IPC protocol, autonomy model, capability taxonomy
+- Schemas: IPC message schemas, skill manifest, assessment pipeline
+- Config: Autonomy gates, delegation rules, proxy policies
+- Policies: Security model, dependency policy, skill assessment criteria
+- Guides: Writing skills, deployment, skill assessment process
+- Reference: ADRs for architecture choices, CalVer changelog
+
+**Enterprise Ecosystem (FulmenHQ-style)**
+
+- Specs: Coding standards, repository category standards, testing standards
+- Schemas: Logging schemas, config schemas, error handling schemas
+- Config: Repository taxonomy, fixture catalog, branding ecosystem
+- Policies: Stream output policy, dependency governance, publishing standards
+- Guides: Bootstrap guide, integration patterns, consuming assets
+- Reference: Two-tier ADR system, release notes, glossary
+
+**Open Source Foundation**
+
+- Specs: API standards, data format specifications, interop requirements
+- Schemas: API schemas, event schemas, config schemas
+- Config: Project taxonomy, maintainer roles
+- Policies: Contribution policy, security disclosure, licensing
+- Guides: Getting started, SDK integration, migration guides
+- Reference: Governance decisions, release history, terminology

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

@@ -0,0 +1,83 @@
+---
+title: Handbook Template
+description: Team documentation with overview, guides, and reference sections
+---
+
+# Handbook Template
+
+The `handbook` template creates a structured documentation site for teams. It extends `minimal` with three predefined sections.
+
+## When to Use
+
+- Team onboarding documentation
+- Internal knowledge bases
+- Product documentation
+- Developer handbooks
+- Any docs that explain "what" and "how"
+
+## What You Get
+
+Everything from `minimal`, plus:
+
+```
+my-handbook/
+├── site.yaml              # Configured with sections
+├── index.md               # Home page linking to sections
+├── CUSTOMIZING.md         # How to customize this site (AI + human friendly)
+├── content/
+│   ├── overview/
+│   │   └── introduction.md    # High-level concepts
+│   ├── guides/
+│   │   └── getting-started.md # Step-by-step tutorials
+│   └── reference/
+│       └── glossary.md        # Terminology and definitions
+└── ...
+```
+
+## Sections
+
+| Section       | Purpose               | Typical Content                         |
+| ------------- | --------------------- | --------------------------------------- |
+| **Overview**  | Big picture, concepts | Architecture, key decisions, principles |
+| **Guides**    | How to do things      | Tutorials, walkthroughs, recipes        |
+| **Reference** | Look-up information   | API docs, glossaries, specifications    |
+
+This follows the [Diátaxis](https://diataxis.fr/) documentation framework's distinction between explanation (Overview), how-to guides (Guides), and reference material (Reference).
+
+## Usage
+
+```bash
+kitfly init team-docs --template handbook
+kitfly init team-docs --template handbook --brand "Engineering"
+```
+
+## Customization
+
+After creation, you can:
+
+- **Add sections**: Edit `site.yaml` to add more sections
+- **Rename sections**: Change the `name` field in `site.yaml`
+- **Restructure**: Move folders and update paths in `site.yaml`
+- **Add files**: Create new `.md` files in any section folder
+
+The starter files are placeholders with `<!-- ← CUSTOMIZE -->` comments showing where to add your content.
+
+## Example Use Cases
+
+**Engineering Handbook**
+
+- Overview: Team principles, tech stack decisions
+- Guides: Development setup, deployment process, code review
+- Reference: API contracts, environment variables, tooling
+
+**Product Documentation**
+
+- Overview: Product vision, target users
+- Guides: Getting started, common workflows
+- Reference: Feature specs, integration docs
+
+**Onboarding Docs**
+
+- Overview: Company culture, team structure
+- Guides: First week checklist, tool setup
+- Reference: Glossary, org chart, contacts

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