kitfly 0.1.2 → 0.2.0

package/dist/_raw/docs/decisions/DDR-0004-slides-rendering-model.md

@@ -0,0 +1,113 @@
+---
+title: "DDR-0004: Slides Rendering Model"
+description: "Defines slides mode rendering, segmentation, and navigation behavior across dev/build/bundle"
+author: "devlead"
+supervised_by: "@3leapsdave"
+date: "2026-02-11"
+status: "proposed"
+tags: ["ddr", "slides", "layout", "routing", "rendering"]
+---
+
+# DDR-0004: Slides Rendering Model
+
+## Status
+
+Proposed
+
+## Context
+
+Kitfly is adding a new `mode: slides` experience for fixed-aspect presentation output while preserving existing docs mode behavior.
+
+A design-level decision is needed so all render paths (`dev`, `build`, `bundle`) behave consistently and remain minimal.
+
+## Decision
+
+### 1. Single-page, hash-routed slides
+
+Slides mode renders as a single-page deck with hash navigation (`#slide-n`).
+
+Behavior:
+
+- prev/next controls update active slide,
+- keyboard navigation supports ArrowLeft/ArrowRight/Space/Home/End,
+- URL hash deep-links and restores slide state on reload.
+
+### 2. Explicit slide segmentation delimiter
+
+Within a markdown file, slide boundaries use:
+
+`--- slide ---`
+
+Rules:
+
+- standard YAML frontmatter remains unchanged,
+- plain markdown `---` is treated as content (horizontal rule),
+- one file per slide remains a first-class authoring model.
+
+### 3. Frontmatter metadata for slide behavior
+
+Per-slide frontmatter supports:
+
+- `title` for sidebar/counter labels,
+- `class` for slide-level layout/style hooks.
+
+Rendered slide wrapper form:
+
+`<section class="slide {frontmatter.class?}"> ... </section>`
+
+### 4. Mode branch with parity requirement
+
+Slides mode is a rendering branch, not a separate engine.
+
+Parity requirement:
+
+- `scripts/dev.ts`, `scripts/build.ts`, and `scripts/bundle.ts` must produce equivalent slide ordering, segmentation, and navigation semantics.
+- Shared logic should live in `src/shared.ts` where feasible to avoid divergence.
+
+### 5. Overflow policy
+
+Default slide frame behavior is scrollable overflow (`overflow: auto`) to avoid silent content clipping. Optional strict clipping can be enabled via slide class if needed.
+
+## Consequences
+
+### Positive
+
+- Deterministic routing and shareable deep links.
+- Lower ambiguity for authors/agents due to explicit delimiter.
+- Consistent output across dev/build/bundle.
+- Keeps core implementation compact and understandable.
+
+### Negative
+
+- Authors must learn a non-standard delimiter token for intra-file slides.
+- Very dense slides may still need manual content shaping for best presentation quality.
+
+### Neutral
+
+- Slides mode does not aim to replace full presentation suites; it optimizes markdown-native, web-first decks.
+
+## Non-Goals
+
+- Animated transitions in core,
+- presenter mode/speaker notes in core,
+- runtime slide master system,
+- swipe gestures requirement for v1.
+
+## Alternatives Considered
+
+### Multi-page slide routing
+
+Rejected for v1 due to higher complexity and weaker parity with single-file bundle behavior.
+
+### Reusing plain `---` as slide break
+
+Rejected due to ambiguity with frontmatter and horizontal-rule markdown usage.
+
+### Hidden overflow by default
+
+Rejected because clipped content fails silently and is hard to debug during authoring.
+
+## References
+
+- v0.2.0 slides mode plan (`.plans/active/v0.2.0/`)
+- [DDR-0001: Viewport-Locked Layout](DDR-0001-viewport-locked-layout.md)

package/dist/_raw/docs/decisions/DDR-0005-deterministic-layout-boundary.md

@@ -0,0 +1,107 @@
+---
+title: "DDR-0005: Deterministic Layout Boundary"
+description: "Defines the boundary between CSS layout primitives/figures and diagramming engines for slide visual composition"
+author: "deliverylead"
+supervised_by: "@3leapsdave"
+date: "2026-02-12"
+status: "proposed"
+tags: ["ddr", "slides", "layout", "primitives", "figures", "diagrams"]
+---
+
+# DDR-0005: Deterministic Layout Boundary
+
+## Status
+
+Proposed
+
+## Context
+
+Kitfly generates slidesites — fixed-aspect pages that are not “infinite scroll” documents. A key use case is AI agents generating presentation-quality slides, including infographic-style layouts with shapes, connectors, and composed visual patterns. (If content is long, it may scroll _within_ the slide frame; the page layout remains slide-like.)
+
+Kitfly is not trying to recreate diagram engines like Mermaid or PlantUML. Those tools compute layout from relationships, which is powerful but hard to control precisely in slide composition and hard for agents to predict.
+
+We need to decide how far to push CSS-based shapes and figures before delegating to diagram engines. The risk on one side is rebuilding a diagram engine inside CSS; the risk on the other is forcing all visual compositions through tools whose auto-layout is difficult for agents to control precisely.
+
+### Observed Problems
+
+1. **Mermaid/PlantUML alignment** — Auto-layout engines optimize for their own constraints. Achieving pixel-precise placement within a slide's visual design is unreliable. Agents cannot predict where nodes will land.
+2. **Agent reasoning** — AI agents generate better results when they can specify placement explicitly ("put X at grid position 2,1") rather than describing relationships and hoping the layout engine produces the desired visual.
+3. **Scope creep** — Without a clear boundary, CSS primitives could grow into a general-purpose diagramming system, duplicating work better handled by existing engines.
+
+## Decision
+
+**Kitfly will maintain two distinct tiers of visual building blocks, separated by a deterministic layout boundary.**
+
+### Tier 1: Shapes (Primitives)
+
+Atomic visual elements (shapes, connectors, text treatments, decorators) with **no internal layout logic**. The author or agent specifies position explicitly. These are analogous to icons in an icon library.
+
+Examples: box, circle, diamond, chevron, block-arrow, line-connector, callout, badge.
+
+### Tier 2: Figures (Deterministic Infographic Patterns)
+
+Parameterized layout templates built from primitives. The figure owns its **internal arrangement** via a deterministic algorithm (CSS Grid, flexbox, trigonometric placement). The agent fills named slots; the figure handles spacing, sizing, and connector routing within its bounding box.
+
+Examples: cycle-wheel, quadrant-grid, layer-cake, funnel, hub-spoke, horizontal-flow, timeline.
+
+### The Boundary Rule
+
+> **If you can name the pieces and where they go (explicit positions or slots), it is a figure. If layout must be computed from relationships between a variable set of nodes, it is a diagram engine.**
+
+| Criterion                                   | Primitives / Figures        | Diagramming Engine  |
+| ------------------------------------------- | --------------------------- | ------------------- |
+| Agent knows element count                   | Yes                         | Maybe not           |
+| Agent controls placement                    | Yes (explicit or via slots) | No (engine decides) |
+| Adding a node requires recalculating others | No                          | Yes                 |
+| Relationships determine layout              | No                          | Yes                 |
+| Topology is fixed per figure type           | Yes                         | No                  |
+
+### Diagramming Engine Integration
+
+For compositions that cross the boundary (flowcharts with variable branching, org charts, dependency graphs, state machines), kitfly's **plugin model** will wrap diagramming engines with a constrained contract:
+
+- The plugin renders into a **declared bounding box** within the slide grid.
+- The plugin accepts a **kitfly theme** (colors, fonts, stroke styles) for visual consistency.
+- Internal layout is fully delegated to the engine.
+- The agent does not attempt to micro-position nodes within the engine's output.
+
+## Consequences
+
+### Implementation Notes (M1.1)
+
+- Core ships **shape primitives** as `.block` modifiers (for example `circle`, `diamond`, `chevron`, `block-arrow`) with deterministic CSS-only behavior.
+- Simple directional flows use existing `block-flow` glyph arrows plus directional shapes; general connector routing remains deferred to plugin/engine phases.
+- This keeps Tier 1 in core without crossing into layout-engine responsibilities.
+
+### Benefits
+
+1. **Agent reliability** — Agents produce consistent, predictable visual output for common infographic patterns that are deterministic layouts.
+2. **Clear plugin contract** — Diagramming engines are scoped to a bounding box with theme passthrough, avoiding the "Mermaid vs. slide layout" fight.
+3. **No engine rebuild** — We explicitly stop before reimplementing graph layout, edge routing, or constraint solving in CSS.
+4. **Catalog-driven authoring** — The figure catalog acts as a vocabulary. Agents pick a pattern and fill slots, similar to choosing an icon from a set.
+
+### Trade-offs
+
+1. **Figure library maintenance** — Each new infographic pattern requires a new figure implementation. This is intentional — it's the cost of deterministic quality.
+2. **Boundary edge cases** — Some compositions (e.g., a flow diagram with exactly 2 branch points) could go either way. Default to figures when topology is fixed and small; to engines when variable.
+3. **Two rendering paths** — Slides mixing figures and engine-rendered diagrams have two rendering subsystems. The plugin model must ensure visual coherence (shared theme tokens).
+
+## Alternatives Considered
+
+### A. CSS-only, no diagramming engines
+
+Rejected. Connector routing and auto-layout for arbitrary graphs is a solved problem in existing engines. Rebuilding it in CSS is high effort, low quality.
+
+### B. Diagramming engine-only (Mermaid/PlantUML for everything)
+
+Rejected. Agents cannot control output placement precisely enough for slide-quality layouts. Simple compositions (4-box grid, layer cake) become unnecessarily complex in diagram DSLs.
+
+### C. Canvas/SVG drawing API exposed to agents
+
+Rejected for primary use. Too low-level — agents generating raw SVG coordinates produce inconsistent results. However, primitives may use inline SVG internally (especially for connectors), hidden behind the primitive's API.
+
+## References
+
+- [Design Catalog: Shapes and Figures](../../content/reference/design-catalog.md)
+- [ADR-0005: Plugin Contract and Distribution Strategy](ADR-0005-plugin-contract-and-distribution.md)
+- [DDR-0004: Slides Rendering Model](DDR-0004-slides-rendering-model.md)

package/dist/_raw/docs/userguide/cli/build.md

@@ -0,0 +1,85 @@
+# kitfly build
+
+Build static site to output directory.
+
+## Usage
+
+```bash
+kitfly build [folder] [options]
+```
+
+## Description
+
+Generates a complete static HTML site from your markdown files. The output can be deployed to any static hosting service (GitHub Pages, Netlify, S3, etc.).
+
+## Arguments
+
+| Argument | Description                                                                      |
+| -------- | -------------------------------------------------------------------------------- |
+| `folder` | Content folder to build (default: current directory or `docroot` from site.yaml) |
+
+## Options
+
+| Option        | Environment Variable | Default | Description                      |
+| ------------- | -------------------- | ------- | -------------------------------- |
+| `--out <dir>` | `KITFLY_BUILD_OUT`   | dist    | Output directory                 |
+| `--no-raw`    | -                    | false   | Don't include raw markdown files |
+
+## Examples
+
+### Basic usage
+
+```bash
+# Build current project
+kitfly build
+
+# Build specific folder
+kitfly build ./docs
+
+# Custom output directory
+kitfly build --out ./public
+```
+
+### Without raw markdown
+
+```bash
+# HTML only, no .md files in output
+kitfly build --no-raw
+```
+
+## Output Structure
+
+```
+dist/
+├── index.html
+├── guide/
+│   ├── getting-started.html
+│   └── getting-started.md    # (if --no-raw not specified)
+├── reference/
+│   └── ...
+└── assets/
+    └── ...
+```
+
+## Raw Markdown Files
+
+By default, kitfly includes the original `.md` files alongside the generated HTML. This allows:
+
+- Downloading source for offline editing
+- Transparency about content source
+- Easy content migration
+
+Use `--no-raw` to exclude these files if not needed.
+
+## Plugin validation errors (triple-colon fences)
+
+Some plugins add special block syntax (for example, `slides-visuals` uses `:::` fences).
+
+When a plugin is enabled, kitfly may validate your content during the build. If validation fails, `kitfly build` will exit with a clear error message so you can fix the content and re-run the build.
+
+See the exact contract (with examples): `../../../content/reference/plugins.html#triple-colon-fence-contract-slides-visuals`.
+
+## See Also
+
+- [kitfly dev](dev.md) - Development server
+- [kitfly bundle](bundle.md) - Single-file output

package/dist/_raw/docs/userguide/cli/bundle.md

@@ -0,0 +1,81 @@
+# kitfly bundle
+
+Build single-file HTML bundle.
+
+## Usage
+
+```bash
+kitfly bundle [folder] [options]
+```
+
+## Description
+
+Creates a single, self-contained HTML file with all content, styles, and navigation embedded. Perfect for sharing via email, Slack, or file sharing services.
+
+## Arguments
+
+| Argument | Description                                                                       |
+| -------- | --------------------------------------------------------------------------------- |
+| `folder` | Content folder to bundle (default: current directory or `docroot` from site.yaml) |
+
+## Options
+
+| Option          | Environment Variable | Default     | Description                    |
+| --------------- | -------------------- | ----------- | ------------------------------ |
+| `--out <dir>`   | `KITFLY_BUILD_OUT`   | dist        | Output directory               |
+| `--name <file>` | -                    | bundle.html | Output filename                |
+| `--raw`         | `KITFLY_BUILD_RAW`   | true        | Include raw markdown in bundle |
+| `--no-raw`      | -                    | -           | Don't include raw markdown     |
+
+## Examples
+
+### Basic usage
+
+```bash
+# Create bundle.html in dist/
+kitfly bundle
+
+# Custom filename
+kitfly bundle --name my-docs.html
+
+# Custom output location
+kitfly bundle --out ./release --name handbook.html
+```
+
+## Output
+
+A single HTML file containing:
+
+- All page content with images inlined as base64 data URIs
+- Embedded CSS styles
+- Syntax highlighting (Prism.js, inlined)
+- Diagram rendering (Mermaid, inlined)
+- Navigation and table of contents
+- Dark mode support
+- Brand logo and favicon (inlined)
+- No external dependencies (works fully offline)
+
+## Use Cases
+
+- **Email attachment**: Share documentation without hosting
+- **Offline reading**: Works without internet connection
+- **Review cycles**: Send to stakeholders for feedback
+- **Archival**: Single-file snapshot of documentation
+- **Client handoff**: Portable single-file deliverable with all images embedded
+
+## File Size
+
+Bundle size depends on content volume and images. Typical documentation sites produce bundles of 100KB-1MB. Sites with many images will be larger due to base64 encoding (~33% overhead per image).
+
+## Plugin validation errors (triple-colon fences)
+
+Some plugins add special block syntax (for example, `slides-visuals` uses `:::` fences).
+
+When a plugin is enabled, kitfly may validate your content before bundling. If validation fails, `kitfly bundle` will exit with a clear error message so you can fix the content and re-run the bundle.
+
+See the exact contract (with examples): `../../../content/reference/plugins.html#triple-colon-fence-contract-slides-visuals`.
+
+## See Also
+
+- [kitfly build](build.md) - Multi-file static build
+- [kitfly dev](dev.md) - Development server

package/dist/_raw/docs/userguide/cli/dev.md

@@ -0,0 +1,92 @@
+# kitfly dev
+
+Start development server with hot reload.
+
+## Usage
+
+```bash
+kitfly dev [folder] [options]
+```
+
+## Description
+
+Launches a local development server that renders your markdown files and automatically reloads when content changes. This is the primary command for authoring documentation.
+
+## Arguments
+
+| Argument | Description                                                                      |
+| -------- | -------------------------------------------------------------------------------- |
+| `folder` | Content folder to serve (default: current directory or `docroot` from site.yaml) |
+
+## Options
+
+| Option           | Environment Variable | Default   | Description                           |
+| ---------------- | -------------------- | --------- | ------------------------------------- |
+| `--port <n>`     | `KITFLY_DEV_PORT`    | 3333      | Server port                           |
+| `--host <h>`     | `KITFLY_DEV_HOST`    | localhost | Server host                           |
+| `--daemon`, `-d` | -                    | false     | Run in background, return immediately |
+| `--json`         | -                    | false     | Output JSON (implies --daemon)        |
+| `--no-open`      | -                    | false     | Don't open browser automatically      |
+
+## Examples
+
+### Basic usage
+
+```bash
+# Serve current directory
+kitfly dev
+
+# Serve specific folder
+kitfly dev ./docs
+
+# Custom port
+kitfly dev --port 8080
+```
+
+### Background mode
+
+```bash
+# Run as daemon
+kitfly dev --daemon
+
+# Get JSON output for scripting
+kitfly dev --json
+```
+
+### Output (JSON mode)
+
+```json
+{
+  "pid": 12345,
+  "port": 3333,
+  "url": "http://localhost:3333"
+}
+```
+
+## Port Conflict Detection
+
+If the specified port is already in use, kitfly will report an error rather than silently choosing another port. Use `kitfly servers` to see what's running.
+
+## Hot Reload
+
+The dev server watches for changes to:
+
+- Markdown files (`.md`)
+- Configuration (`site.yaml`, `theme.yaml`)
+- Template files
+
+Changes are reflected immediately without manual refresh.
+
+## Plugin validation errors (triple-colon fences)
+
+Some plugins add special block syntax (for example, `slides-visuals` uses `:::` fences).
+
+When a plugin is enabled, kitfly may validate your content before rendering. If validation fails, `kitfly dev` will exit with a clear error message so you can fix the content and restart.
+
+See the exact contract (with examples): `../../../content/reference/plugins.html#triple-colon-fence-contract-slides-visuals`.
+
+## See Also
+
+- [kitfly build](build.md) - Build static site
+- [kitfly servers](servers.md) - List running servers
+- [kitfly stop](stop.md) - Stop servers

package/dist/_raw/docs/userguide/cli/init.md

@@ -0,0 +1,116 @@
+# kitfly init
+
+Create new project from template.
+
+## Usage
+
+```bash
+kitfly init [name] [options]
+```
+
+## Description
+
+Initializes a new kitfly project with all necessary files and folder structure. Creates a standalone site that you own and can customize.
+
+## Arguments
+
+| Argument | Description                                         |
+| -------- | --------------------------------------------------- |
+| `name`   | Project directory name (default: current directory) |
+
+## Options
+
+| Option              | Description                                                          |
+| ------------------- | -------------------------------------------------------------------- |
+| `--template <name>` | Template to use: `minimal`, `handbook`, `runbook` (default: minimal) |
+| `--standalone`      | Create self-contained site with rendering code (default: true)       |
+| `--brand <name>`    | Set brand name                                                       |
+| `--brand-url <url>` | Set brand URL                                                        |
+
+## Templates
+
+### minimal
+
+Basic documentation site with simple structure:
+
+- Single content section
+- Clean starting point
+- Minimal example content
+
+### handbook
+
+Team/company handbook template:
+
+- Multiple sections (About, Policies, Guides, Resources)
+- Onboarding-focused structure
+- Sample policies and guides
+
+### runbook
+
+Operations runbook template:
+
+- Procedures, Troubleshooting, Reference, Incidents sections
+- Operations-focused structure
+- Incident response templates
+
+## Examples
+
+### Basic usage
+
+```bash
+# Create in new directory
+kitfly init my-docs
+
+# Create in current directory
+kitfly init .
+
+# Use handbook template
+kitfly init company-handbook --template handbook
+```
+
+### With branding
+
+```bash
+kitfly init my-docs --brand "Acme Corp" --brand-url "https://acme.com"
+```
+
+## Output Structure
+
+```
+my-docs/
+├── content/
+│   └── index.md
+├── scripts/
+│   ├── dev.ts
+│   ├── build.ts
+│   └── bundle.ts
+├── src/
+│   └── ...
+├── site.yaml
+├── theme.yaml
+├── package.json
+└── README.md
+```
+
+## After Initialization
+
+```bash
+cd my-docs
+bun install
+bun run dev
+```
+
+## Standalone Mode
+
+By default, `kitfly init` creates a standalone site with its own copy of:
+
+- Rendering scripts (dev, build, bundle)
+- Engine and theme code
+- Configuration schemas
+
+This means your site is independent - no kitfly CLI required after setup.
+
+## See Also
+
+- [kitfly update](update.md) - Update site code
+- [kitfly dev](dev.md) - Start development

package/dist/_raw/docs/userguide/cli/servers.md

@@ -0,0 +1,69 @@
+# kitfly servers
+
+List running dev servers.
+
+## Usage
+
+```bash
+kitfly servers [options]
+```
+
+## Description
+
+Displays all kitfly dev servers currently running on this machine. Useful for managing multiple documentation projects or finding orphaned servers.
+
+## Options
+
+| Option   | Description    |
+| -------- | -------------- |
+| `--json` | Output as JSON |
+
+## Examples
+
+### Basic usage
+
+```bash
+$ kitfly servers
+PORT   PID    PROJECT
+3333   12345  /Users/me/docs/handbook
+3340   12346  /Users/me/docs/runbook
+```
+
+### JSON output
+
+```bash
+$ kitfly servers --json
+[
+  {"port": 3333, "pid": 12345, "project": "/Users/me/docs/handbook"},
+  {"port": 3340, "pid": 12346, "project": "/Users/me/docs/runbook"}
+]
+```
+
+### No servers running
+
+```bash
+$ kitfly servers
+No kitfly servers running
+```
+
+## Output Fields
+
+| Field     | Description            |
+| --------- | ---------------------- |
+| `PORT`    | Server port number     |
+| `PID`     | Process ID             |
+| `PROJECT` | Project directory path |
+
+## Server Registry
+
+Kitfly maintains a registry of running servers at:
+
+- macOS/Linux: `~/.kitfly/servers.json`
+- Windows: `%USERPROFILE%\.kitfly\servers.json`
+
+The registry is automatically cleaned up when servers stop normally.
+
+## See Also
+
+- [kitfly dev](dev.md) - Start a server
+- [kitfly stop](stop.md) - Stop servers