kitfly 0.1.2 → 0.2.1

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/slides-authoring-guidelines.md

@@ -0,0 +1,129 @@
+---
+title: "Slides Authoring Guidelines"
+description: "Practical density and layout rules for reliable Kitfly slides"
+last_updated: "2026-02-15"
+---
+
+# Slides Authoring Guidelines
+
+This page is for slide authors and AI agents generating slide content.
+
+Goal: avoid common layouts that look broken but are actually content-density issues.
+
+## Quick rules
+
+- Keep vertical visuals short. If a slide is tall and busy, trim items before adding more styling.
+- Treat highlighted (`.accent`) blocks as emphasis, not interaction.
+- Scroll in slides mode is allowed for dense content. Prefer no scroll for presentation slides.
+
+## DF-006: Single `.accent` in `.block-grid` looks like a tab
+
+### Problem
+
+When one block in a row is accented and others are not, users read it as a selected tab and expect click behavior.
+
+### Do this
+
+- In one grid row, accent all blocks or accent none.
+- If you need real tabs, treat that as a future widget (`slides-widgets`), not static blocks.
+
+### Avoid this
+
+```html
+<div class="block-grid cols-3">
+  <div class="block">Backend</div>
+  <div class="block accent">Platform</div>
+  <div class="block">SRE</div>
+</div>
+```
+
+### Prefer this
+
+```html
+<div class="block-grid cols-3">
+  <div class="block accent">Backend</div>
+  <div class="block accent">Platform</div>
+  <div class="block accent">SRE</div>
+</div>
+```
+
+or
+
+```html
+<div class="block-grid cols-3">
+  <div class="block">Backend</div>
+  <div class="block">Platform</div>
+  <div class="block">SRE</div>
+</div>
+```
+
+## DF-007: `block-flow.vertical` can overflow at 4/3
+
+### Problem
+
+`.block-flow.vertical` (HTML: `class="block-flow vertical"`) with 4 steps can exceed the visible frame at `4/3`.
+
+### Do this
+
+- At `4/3`: limit vertical flows to 3 blocks.
+- At `16/9`: 4 blocks is usually fine.
+- If the slide also has extra text/callouts, reduce steps further.
+
+### Guidance
+
+- If you must keep all steps, scroll is acceptable.
+- For presentation-first slides, split into two slides instead.
+
+### Example target
+
+```html
+<div class="block-flow vertical">
+  <div class="block">1. Intake</div>
+  <div class="block">2. Validate</div>
+  <div class="block">3. Ship</div>
+</div>
+```
+
+## DF-014: `timeline-vertical` + callout can clip at 16/9
+
+### Problem
+
+A 5-event vertical timeline plus a callout often exceeds the frame at `16/9`.
+
+### Do this
+
+- At `16/9`: keep `timeline-vertical` to 4 events when the slide also has a callout.
+- At `4/3`: keep to 3 events with a callout.
+- If you need all events, remove the callout or move it to a follow-up slide.
+
+### Example (safe with callout)
+
+```text
+:::timeline-vertical
+events:
+- label: "Detect"
+  date: "09:15"
+- label: "Triage"
+  date: "09:24"
+- label: "Mitigate"
+  date: "09:42"
+- label: "Recover"
+  date: "10:08"
+:::
+
+> WARNING: External API fallback remained active for 12 minutes.
+```
+
+## Aspect ratio checklist
+
+- `16/9`: medium density, but still cap long vertical stacks.
+- `4/3`: tighter vertical budget. Reduce stacked items first.
+- `16/10`: between `16/9` and `4/3`; apply the same conservative limits when callouts are present.
+
+## Summary
+
+These are authoring constraints, not renderer bugs. When a slide clips:
+
+1. Reduce vertical item count.
+2. Remove or move callouts.
+3. Split dense content across two slides.

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,20 @@
+---
+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
+- [Slides Authoring Guidelines](content/reference/slides-authoring-guidelines.html) — practical do/don't rules for density and visual layout
+- [Glossary](content/reference/glossary.html) — quick definitions