kitfly 0.1.2 → 0.2.0

package/dist/_raw/content/reference/plugins.md

@@ -0,0 +1,220 @@
+---
+title: "Plugins"
+description: "Enable small add-ons (CSS/JS) for docs and slides"
+last_updated: "2026-02-12"
+---
+
+# Plugins
+
+Kitfly plugins are small, optional add-ons that inject CSS and/or JS into your generated HTML.
+
+They are designed to stay minimal:
+
+- No build pipeline required
+- Offline-friendly when assets are local
+- You own the files (standalone sites copy `registry/` + `plugins-dist/`)
+
+## Enable a plugin
+
+Create `kitfly.plugins.yaml` in your site root:
+
+```yaml
+# yaml-language-server: $schema=./schemas/v0/plugins.schema.json
+plugins:
+  - callouts@0.2.0
+```
+
+Canonical plugins are referenced as pinned strings: `name@x.y.z`.
+
+## Registry + assets
+
+Canonical plugins come from a registry file:
+
+- Site registry: `registry/plugins.yaml` (preferred if present)
+- Engine registry: used as a fallback when the site does not include a registry
+
+Registry entries map a plugin id + version to asset locations (`assets.js` and/or `assets.css`) and per-asset checksums (`assetSha256`).
+
+For local/offline registries, `baseUrl` may be an empty string.
+
+## Mode allowlist (`modes`)
+
+Registry entries may include an optional `modes` allowlist to control where a plugin runs:
+
+- Omitted: allowed in `docs` and `slides`
+- Present with values: allowed only in those modes (example: `["slides"]`)
+- Present but empty (`[]`): blocked in all modes (quick disable switch)
+
+Example:
+
+```yaml
+plugins:
+  slides-widgets:
+    version: "0.2.0"
+    modes: ["slides"]
+    assets:
+      js: "plugins-dist/slides-widgets.js"
+      assetSha256:
+        js: "sha256:..."
+```
+
+## Integrity checks
+
+Kitfly verifies every enabled asset against its `sha256:<hex>` checksum. If a checksum does not match, the build/dev server fails with an integrity error.
+
+When iterating on a local plugin (for example, editing `plugins-dist/slides-visuals.js`), you must also update the matching `assetSha256` in `registry/plugins.yaml` (or disable the plugin) for Kitfly to load it.
+
+## Triple-colon fence contract (`slides-visuals`)
+
+The `slides-visuals` plugin adds a `:::` block syntax for slides mode (widgets + figures).
+
+To keep authoring predictable and make errors actionable, Kitfly defines a strict contract for these blocks.
+When `slides-visuals` is enabled, Kitfly validates blocks before rendering and reports contract violations.
+
+### Valid block shape
+
+- Opening fence: `:::<type>` **must** start at column 0 and be the only content on the line.
+- Closing fence: `:::` **must** start at column 0 and be the only content on the line.
+- No blank lines inside a `:::` block.
+- Content is a narrow YAML subset:
+  - Scalar: `key: value`
+  - List: `key:` followed by list items
+    - List item start: exactly two spaces, then `- ` (example: `␠␠- label: Users`)
+    - Continuation lines (object fields): exactly four spaces, then `field: value`
+
+### Supported types
+
+Widgets:
+
+- `kpi` (scalar keys: `label`, `value`, optional `trend`)
+- `stat-grid` (list key: `metrics` of `{label,value,trend?}` objects)
+- `compare` (scalar keys: `left-title`, `right-title`; list keys: `left`, `right` as **strings only**)
+
+Notes:
+
+- `compare.left` and `compare.right` items are simple strings (not `{label: ..., value: ...}` objects).
+- If you need multi-field items, use `stat-grid` / `scorecard` instead.
+- If an item contains a colon (`:`), quote it as a string.
+
+Figures:
+
+- `quadrant-grid` (scalar keys: `axis-x`, `axis-y`, `tl`, `tr`, `bl`, `br`)
+- `scorecard` (list key: `metrics` of `{label,value,trend?}` objects)
+- `comparison-table` (list keys: `headers` (strings), `rows` (strings))
+- `layer-cake` (list key: `layers` (strings))
+- `pyramid` (list key: `levels` (strings))
+- `funnel` (list key: `stages` (strings))
+
+### Example (valid)
+
+```markdown
+:::stat-grid
+metrics:
+
+- label: Users
+  value: 1,234
+- label: Uptime
+  value: 99.95%
+  trend: +0.3%
+  :::
+```
+
+### How to know it’s correct
+
+When `slides-visuals@...` is enabled, Kitfly validates your `:::` blocks before it renders pages.
+
+You know your fences are valid if:
+
+- `kitfly dev` starts successfully, and pages load normally
+- `kitfly build` completes successfully
+- `kitfly bundle` completes successfully
+
+If a block is invalid, Kitfly will fail fast with an error that points to the file and the specific contract rule you violated.
+
+### Common mistakes (and how to fix them)
+
+- **Indented fences**: `:::kpi` must start at column 0 (no spaces, no list indentation, no blockquote `>`).
+- **Blank lines inside the block**: remove empty lines between keys/items.
+- **Wrong list indentation**:
+  - list items must start with exactly two spaces then `- `
+  - fields under an item must use exactly four spaces
+- **Unknown type**: the opening fence `:::<type>` must be one of the supported types.
+
+### Examples (invalid → fixed)
+
+#### 1) Indented fence (invalid)
+
+```markdown
+:::kpi
+label: Users
+value: 1,234
+:::
+```
+
+Fixed:
+
+```markdown
+:::kpi
+label: Users
+value: 1,234
+:::
+```
+
+#### 2) Blank line inside block (invalid)
+
+```markdown
+:::kpi
+label: Users
+
+value: 1,234
+:::
+```
+
+Fixed:
+
+```markdown
+:::kpi
+label: Users
+value: 1,234
+:::
+```
+
+#### 3) Bad list indentation (invalid)
+
+```markdown
+:::stat-grid
+metrics:
+
+- label: Users
+  value: 1,234
+  :::
+```
+
+Fixed:
+
+```markdown
+:::stat-grid
+metrics:
+
+- label: Users
+  value: 1,234
+  :::
+```
+
+#### 4) Unknown type (invalid)
+
+```markdown
+:::stats
+label: Users
+value: 1,234
+:::
+```
+
+Fixed: use a supported type (for example `kpi`):
+
+```markdown
+:::kpi
+label: Users
+value: 1,234
+:::
+```

package/dist/_raw/content/reference/structure.md

@@ -0,0 +1,166 @@
+---
+title: "Folder Structure"
+description: "What lives where in a kitfly project"
+last_updated: "2026-02-03"
+---
+
+# Folder Structure
+
+Understanding what's in the template and what ends up in your built site.
+
+## Template Repository
+
+When you clone kitfly, you get:
+
+```
+kitfly/
+├── content/              # YOUR DOCS
+│   ├── index.md          # Home page
+│   ├── guide/            # Guide section
+│   └── reference/        # Reference section
+│
+├── src/                  # RENDERING MACHINERY
+│   ├── cli.ts            # CLI entry point
+│   ├── commands/         # CLI commands
+│   └── site/             # HTML template + CSS
+│
+├── scripts/              # BUILD SCRIPTS
+│   ├── dev.ts            # Dev server
+│   └── build.ts          # Static build
+│
+├── assets/               # BRAND ASSETS
+│   └── brand/            # Logo, favicon
+│
+├── dist/                 # BUILD OUTPUT (gitignored)
+│
+├── .plans/               # PLANNING (gitignored)
+│
+├── site.yaml             # CONFIGURATION
+├── package.json          # Dependencies
+├── VERSION               # Version number
+├── README.md             # GitHub readme
+├── AGENTS.md             # AI agent guide
+└── LICENSE               # MIT license
+```
+
+## What Gets Built
+
+When you run `bun run build`, **only content from `docroot` goes into `dist/`**:
+
+```
+dist/
+├── index.html            # From content/index.md
+├── guide/
+│   ├── index.html        # Redirect to first file
+│   ├── approaches.html   # From content/guide/approaches.md
+│   ├── getting-started.html
+│   └── features.html
+├── reference/
+│   ├── index.html        # Redirect to first file
+│   ├── configuration.html
+│   └── structure.html
+├── styles.css            # From src/site/styles.css
+├── provenance.json       # Build metadata
+└── assets/               # Copied from assets/
+    └── brand/
+```
+
+**Not in dist/:**
+
+- `src/` - rendering code
+- `scripts/` - build scripts
+- `README.md` - GitHub readme
+- `AGENTS.md` - AI guide
+- `package.json` - dependencies
+- `.plans/` - planning files
+- Any other repo files
+
+This separation is intentional. Your built site is just documentation - no tooling artifacts.
+
+## The docroot Setting
+
+In `site.yaml`:
+
+```yaml
+docroot: "content"
+```
+
+This tells kitfly where to look for markdown files. Options:
+
+| Setting     | Effect                                     |
+| ----------- | ------------------------------------------ |
+| `"content"` | Render from `content/` (recommended)       |
+| `"docs"`    | Render from `docs/` (common in code repos) |
+| `"."`       | Render from repo root (use with care)      |
+
+### Why This Matters
+
+With `docroot: "content"`:
+
+- Your `README.md` stays on GitHub, not in the docs
+- Your `package.json` isn't exposed
+- You can have code, tests, and docs in the same repo
+
+With `docroot: "."`:
+
+- Everything in the repo root becomes documentation
+- Useful for pure documentation repos
+- You'll want to configure `sections` explicitly
+
+## Customizing the Template
+
+### The Machinery
+
+If you want to modify how kitfly renders:
+
+- **HTML template:** `src/site/template.html`
+- **Styles:** `src/site/styles.css`
+- **Dev server:** `scripts/dev.ts`
+- **Build script:** `scripts/build.ts`
+
+These are ~500 lines total. Read them, understand them, modify if needed.
+
+### Brand Assets
+
+Replace files in `assets/brand/`:
+
+- `kitfly-logo.svg` - Vector logo (ensure tight viewBox)
+- `kitfly-logo-512.png` - Used in README
+- `kitfly-logo-128.png` - Sidebar header fallback
+- `kitfly-favicon-32.png` - Browser favicon
+
+These are copied to `dist/assets/` during build.
+
+## For Different Use Cases
+
+### Documentation alongside code
+
+```
+my-project/
+├── src/              # Your code
+├── tests/            # Your tests
+├── docs/             # Your documentation
+│   ├── index.md
+│   └── api/
+└── site.yaml         # docroot: "docs"
+```
+
+### Pure documentation repo
+
+```
+my-docs/
+├── index.md
+├── guides/
+├── reference/
+└── site.yaml         # docroot: "."
+```
+
+### Existing markdown
+
+Point kitfly at any folder:
+
+```bash
+kitfly dev ./path/to/markdown
+```
+
+No need to restructure anything.

package/dist/_raw/content/reference.md

@@ -0,0 +1,19 @@
+---
+title: "Reference"
+description: "Key concepts and lookup docs for Kitfly"
+last_updated: "2026-02-12"
+---
+
+# Reference
+
+Use this section when you want quick definitions, mental models, and “what does this setting mean?” answers.
+
+## Start here
+
+- [Configuration](content/reference/configuration.html) — `site.yaml` and common settings
+- [Plugins](content/reference/plugins.html) — enable small CSS/JS add-ons
+- [Structure](content/reference/structure.html) — recommended folder layout and conventions
+- [Environment Variables](content/reference/environment-variables.html) — what they are and how to set them
+- [Key Concepts](content/reference/key-concepts.html) — `docroot`, `dist/`, “bundle vs build”, and more
+- [Design Catalog](content/reference/design-catalog.html) — shapes and deterministic infographic figures
+- [Glossary](content/reference/glossary.html) — quick definitions

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