v0.2.5

Kitfly v0.2.5

Release date: 2026-06-22

Overview

A maintenance release focused on CI/release hardening and a dependency refresh.
There are no user-facing feature changes and no breaking changes.

Fixed

• npm publish robustness. The publish workflow now generates the embedded CLI
  docs (src/generated/embedded-docs.ts) before packing. That file backs
  kitfly docs, is gitignored, and is not produced by bun run build — so
  an automated publish from a clean checkout could have shipped a package whose
  kitfly docs command fails to load. The publish path now generates it
  explicitly, alongside the release and Windows ARM64 builds.

Changed

• GitHub Actions on Node 24. Migrated actions/checkout v4 → v5 and
  actions/setup-node v4 → v6 (npm publish runs on Node 24). oven-sh/setup-bun
  already targets Node 24. This clears the upstream Node 20 runtime deprecation.
• Single source of truth for embedded assets. The Bun-setup + install + embed
  step is consolidated into a shared ./.github/actions/build-prep composite
  action used by the release, Windows ARM64, and npm-publish workflows (it was
  previously inlined separately in each). CI continues to get the generated asset
  through the Makefile dependency graph.
• Dependency refresh (patch + minor): @3leaps/sysprims 0.1.15,
  @fulmenhq/tsfulmen 0.2.10, @biomejs/biome 2.5.0, vitest and
  @vitest/coverage-v8 4.1.9, @types/bun 1.3.14, prettier 3.8.4. The
  marked 18 and typescript 6 majors are deferred to dedicated upgrades.

Breaking changes

None.

Notes for upgraders

Nothing to do — drop-in patch. Binaries, the npm package, and the Homebrew
formula are unchanged in behavior.

Full changelog

See CHANGELOG.md for the complete list.

v0.2.4

Kitfly v0.2.4

Release date: 2026-03-08

What's new

Kitfly v0.2.4 adds the planning-visuals plugin with Gantt charts for timeline visualization. Unlike Mermaid's gantt (which breaks in slide viewports), Kitfly's :::gantt widget uses max-depth filtering to let the same dataset drive both summary and detail views.

Gantt charts (planning-visuals plugin)

Render wave-based rollout plans, product roadmaps, or project timelines:

:::gantt
label: "Q2-Q4 Roadmap"
time-unit: month
time-start: "2026-04"
time-end: "2026-12"
max-depth: 1
today: "2026-06"
tracks:
  - label: "Phase 1 — Foundation"
    depth: 1
    start: "2026-04"
    end: "2026-06"
    status: complete
  - label: "Phase 2 — Core Features"
    depth: 1
    start: "2026-07"
    end: "2026-09"
    status: active
  - label: "Phase 3 — Scale"
    depth: 1
    start: "2026-10"
    end: "2026-12"
    status: planned
milestones:
  - label: "Beta Launch"
    date: "2026-06"
  - label: "Public Release"
    date: "2026-09"
markers:
  - label: "Investor Review"
    date: "2026-08"
    color: "#e11d48"
:::

Key features:

• Dual time units: week (ISO weeks, YYYY-Www) or month (YYYY-MM) — business audiences think in months, ops teams need week precision
• Hierarchical depth: max-depth: 1 shows waves only, max-depth: 2 adds clients/items — same YAML, different views
• Status colors: planned (muted), active (accent), complete (green), blocked (amber)
• Milestones: Diamond markers for point-in-time events
• Custom markers: Highlight key dates with color: for visual emphasis
• Overflow handling: max-tracks: 8 truncates with "+N more" — deterministic, no runtime measurement
• Today marker: Vertical dashed line when today: is set

Works in both docs and slides modes from day one.

Embedded CLI documentation

Access curated documentation directly from the compiled binary — no internet or repo clone required:

kitfly docs list              # List available topics with titles
kitfly docs show <slug>       # Output raw markdown to stdout
kitfly docs show ref/config | less  # Pipe to your favorite pager

Build-time codegen reads docs/embed-manifest.yaml (include/exclude globs), strips frontmatter, and bakes content into the binary. Missing slugs suggest similar matches.

Why Kitfly Gantt vs. Mermaid

Mermaid's gantt produces SVGs that break in fixed-aspect slide viewports when you have 5+ waves and 20+ items. Kitfly's solution: level-of-detail control.

# Same data, summary view
max-depth: 1  # Wave-level bars only — for exec slides

# Same data, detail view
max-depth: 2  # Waves + client-level items — for planning reviews

This solves the density problem without maintaining two files or switching tools.

Plugin usage

Add to kitfly.plugins.yaml:

plugins:
  - planning-visuals

The plugin loads in both docs and slides modes (no modes: restriction).

Breaking changes

None. New plugin — opt-in only.

Notes for upgraders

• To use gantt charts: add planning-visuals to your plugin list
• See content/reference/gantt-widget.md for complete authoring reference
• Validators check date formats, ranges, and track ordering at build time

Full changelog

See CHANGELOG.md for the complete list.

v0.2.3

kitfly v0.2.3

Download

Platform	Binary
Linux x64	kitfly-linux-amd64
Linux arm64	kitfly-linux-arm64
macOS arm64	kitfly-darwin-arm64
Windows x64	kitfly-windows-amd64.exe
npm	kitfly-0.2.3.tgz

Install from npm

bun install -g kitfly
# or
npm install -g kitfly

Verification

Once signed artifacts are available:

# Verify checksum signature
minisign -Vm SHA256SUMS -p kitfly-minisign.pub

# Verify package checksum
shasum -a 256 -c SHA256SUMS

v0.2.2

Summary

Kitfly v0.2.2 adds two new CDN plugins (charts and math typesetting), a brief template for product documentation, footer logo support, dark mode logo variants, and hierarchical slide navigation for decks with nested content.

Highlights

Charts plugin (slides-charts-lite)

Bar, line, and pie charts via Chart.js 4.4.7 CDN. Author charts using fenced code blocks:

```chart
type: bar
labels: ["Q1", "Q2", "Q3", "Q4"]
data: [12, 19, 8, 15]
```

Charts render inline, respect theme colors, and re-render on light/dark mode toggle. Works in dev, build, and bundle output.

LaTeX plugin (latex)

Math typesetting via KaTeX 0.16.21 CDN. Three authoring modes:

• Inline: $E = mc^2$
• Display: $$\int_0^\infty e^{-x} dx = 1$$
• Fenced: ```math blocks

Works in both docs and slides modes.

Brief template

New kitfly init --template brief for external-audience product documentation. Four sections: Product, Use Cases, Getting Started, Reference. Includes starter content with <!-- ← CUSTOMIZE --> markers.

Footer logo

Add an image logo to the footer ribbon — typically a parent company or client logo distinct from the header brand:

footer:
  logo: "assets/brand/footer-logo.png"
  logoUrl: "https://example.com"
  logoAlt: "Example Corp"
  logoHeight: 24

Renders at the leading edge of the footer, before version and publish date. All fields are optional.

Dark mode logo variants

Provide separate light/dark images for precise brand control:

brand:
  logo: "assets/brand/logo.png"
  logoDark: "assets/brand/logo-dark.png"

footer:
  logo: "assets/brand/footer-logo.png"
  logoDark: "assets/brand/footer-logo-dark.png"

When logoDark is set, kitfly shows it in dark mode instead of applying the default brightness filter. The swap is pure CSS — instant on theme toggle, no JavaScript.

Hierarchical slide navigation

Slide decks with subfolder content now render nested navigation with collapsible groups, matching the same tree pattern docs mode already uses:

Data Integration
  ├── Overview
  ├── Sources
  │   └── POS Data
  ├── Transforms
  │   └── ETL Pipeline

When content has no subfolders (the common case), the output is identical to the previous flat nav. Works in dev, build, and bundle.

Branding documentation

New canonical branding guide at content/guide/branding.md covering header logos, footer logos, dark mode variants, and recommended asset files. Configuration reference updated with all new fields.

Template brand asset docs

All built-in templates (handbook, runbook, brief, deck) updated with expanded Brand Assets documentation covering footer logo and dark mode variant configuration.

Breaking Changes

None.

Plugin Fixes

• Fixed $ replacement corruption in template injection that broke LaTeX delimiter rendering
• Fixed CDN loader path resolution for LaTeX plugin assets

Deferred to v0.3.0

• Build-time marked extension hook (both plugins sidestepped the need)
• Visual figures Phase 3 (radial types: cycle-wheel, hub-spoke, concentric-rings, venn)
• General connectors (7 types)
• slides-embed (iframe/video)
• slides-refresh (live polling)
• Offline cache polish
• PlantUML rendering (no viable client-side option; build-time only)
• Plugin repo split
• kitfly update command
• Windows operation (separate release)

v0.2.1

Summary

Kitfly v0.2.1 completes Phase 2 of the visual figures set in the slides-visuals plugin, adding five new ::: figure types for timelines, flows, and maturity models. It also improves developer experience with friendlier error handling and new authoring guidelines.

Highlights

Phase 2 figures (slides-visuals plugin)

Five new deterministic figure types, all following the same ::: fence contract introduced in v0.2.0:

Figure	Description
timeline-horizontal	Left-to-right chronology strip (flexbox)
timeline-vertical	Top-to-bottom chronology (flexbox)
flow-branching	Single split point with deterministic branches (CSS grid)
flow-converging	Multiple inputs merging to one output (CSS grid)
staircase	Ascending/descending stepped blocks for maturity models

Example:

:::timeline-horizontal
events:
  - label: "Kickoff"
    date: "Jan 2026"
  - label: "Alpha"
    date: "Mar 2026"
  - label: "GA Release"
    date: "Jun 2026"
:::

All five types work in dev, build, and bundle output. They respect theme colors and dark mode. Validation rejects missing required fields with clear diagnostics.

Friendlier plugin errors in dev preview

When a plugin version mismatch or loader error occurs, the dev server now renders a styled error page with actionable guidance instead of a raw 500 stack trace.

Slides authoring guidelines

New reference doc (content/reference/slides-authoring-guidelines.md) with practical do/don't guidance for content-density pitfalls discovered during dogfooding:

• Don't use .accent on a single block in a grid row (looks like a selected tab)
• Limit vertical flows to 3 blocks at 4:3 aspect ratio
• Limit timeline-vertical to 4 events at 16:9, 3 at 4:3

Test compatibility

Fixed vitest/bun dual-runtime compatibility so bunx vitest run and bun test both work cleanly.

Breaking Changes

None.

Deferred to v0.2.2

• slides-charts-lite (CDN/SRI pattern)
• latex (KaTeX, same CDN pattern)
• Build-time ::: support via marked extension hook (decision memo in progress)
• slides-embed (iframe/video)

v0.2.0

Summary

Kitfly v0.2.0 adds slides mode and a minimal plugin system—so you can ship fixed-aspect decks, add optional visuals/widgets, and still keep the core small and auditable.

Highlights

Slides mode (mode: slides)

Slides mode renders your content as a single-page, hash-routed deck (#slide-n) with keyboard navigation and a fixed aspect ratio.

# site.yaml
mode: slides
aspect: "16/9"

Authoring models:

• One file per slide
• One file, many slides using the explicit delimiter: --- slide ---

If you're starting fresh, kitfly init --template deck gives you a ready-to-edit slide project.

Plugins (optional, pinned, integrity-checked)

Plugins are small opt-in add-ons that inject CSS/JS. They are designed to stay minimal and predictable:

• Pinned versions (name@x.y.z)
• Integrity checked assets (sha256)
• Optional mode allowlists (run only in slides, etc.)

Enable plugins via kitfly.plugins.yaml in your site root.

For details (including registry layout, checksums, and mode allowlists), see:

• content/reference/plugins.md

callouts plugin

The callouts plugin transforms blockquotes starting with NOTE:/TIP:/WARNING:/INFO:/DANGER: into styled callout boxes. Works in both docs and slides modes.

slides-visuals and the ::: fence contract

The first "live slides" plugin, slides-visuals, introduces a strict ::: block syntax for widgets and deterministic figures.

Kitfly now validates ::: blocks when the plugin is enabled and fails fast with actionable errors. This is intentional: the contract avoids "looks like it worked" failures where a deck silently renders the wrong thing.

See: content/reference/plugins.md (Triple-colon fence contract).

Deterministic design primitives (shapes + figures)

v0.2.0 introduces core CSS primitives for slide-friendly visuals (block flow/grid plus shape modifiers) and documents a design catalog to standardize terminology:

• Shapes (primitives): atomic building blocks
• Figures: deterministic infographic patterns built from shapes

See: content/reference/design-catalog.md

Server management

New CLI commands for managing dev server instances:

• kitfly servers — list running dev servers
• kitfly stop <port|all> — stop dev server(s)
• kitfly logs <port> — view daemon server logs (supports --follow)

Site versioning

Set version in site.yaml to display your site's version in the sidebar and footer across dev, build, and bundle outputs:

version: "1.0.0"    # explicit
version: auto        # read from VERSION file

Brand logo fallback

When no logo file is configured or the image can't load, Kitfly renders a CSS initial (first letter of the site title) instead of showing a broken image icon.

Bundle output separation

Bundle output now writes to bundles/ (separate from dist/) so static-deploy and single-file outputs don't interfere.

Breaking Changes

None for docs-mode sites.

If you enable slides-visuals, invalid ::: blocks are now treated as build errors (by design).

Deferred to v0.2.1

The v0.2.0 cycle intentionally shipped the minimum "slides + plugin" core and deferred additional live-slides capabilities:

• slides-charts-lite
• slides-refresh
• slides-embed
• Build-time ::: support via a marked extension hook (v0.2.0 uses a runtime DOM transform)

v0.1.2

Summary

Provenance bug fix, sidebar UX improvements, configurable sidebar width, and a major test coverage expansion. Site footer now displays the user's site version instead of the kitfly engine version. Sidebar folder indicators are larger and animated. Sidebar width is configurable via theme.yaml.

Highlights

Provenance version source (bug fix)

• generateProvenance() was reading kitfly's own VERSION file — every site showed the same version
• Now resolves version from: site.yaml version field → git tag on HEAD → omit
• Added version field to site.schema.json
• Kitfly's engine version is never displayed as site provenance

Sidebar folder indicators (UX)

• Replaced ▸/▾ Unicode triangles at 0.7em with › chevron at 0.85em
• Added rotate(90deg) CSS transition on details[open] (150ms ease)
• Single character rotates between states — no content swap needed
• CSS-only change, bundles pick up automatically

Configurable sidebar width (feature)

• New layout section in theme.schema.json with sidebarWidth property
• generateThemeCSS() emits --sidebar-width override from theme config
• Pattern validation: ^[0-9]+(px|rem|em|%)$
• Default remains 280px, recommended range 240px–400px
• Propagates to dev server, static builds, and bundles automatically

Test coverage expansion

• 466 → 1,174 tests across 15 test files
• Statement coverage: 56.9% → 68.7%
• Function coverage: 42.3% → 79.6%
• Template coverage: crucible, pipeline, productbook, runbook, servicebook all at 100%
• Bundle coverage: 12.5% → 45.4% (parseArgs, imageMime, rewriteContentLinks, fileToDataUri, inlineLocalImages)
• Theme tests refactored: removed vi.mock() in favor of real temp directories
• All non-null assertion lint warnings eliminated (541 → 0 in changed files)
• Bun/Node dual-runtime test compatibility for v8 coverage

Breaking Changes

None. All additions are backwards-compatible. Sites without a version field gracefully omit version from provenance.

Migration

No migration needed. To use new features:

# site.yaml — add site version
version: "1.0.0"

# theme.yaml — customize sidebar width
layout:
  sidebarWidth: "320px"

v0.1.1

Summary

Footer branding customization, Kitfly attribution, and release infrastructure hardening. Users can now fully configure footer content — copyright, links, attribution — via site.yaml. Platform binary releases validated across all targets.

Highlights

Footer customization

• Three-zone footer layout: provenance (left), copyright + links (center), attribution (right)
• footer.copyright — override auto-generated copyright text
• footer.copyrightUrl — make copyright text a clickable link
• footer.links — custom footer links (max 10), replaces default brand link; empty array suppresses all center links
• footer.attribution — toggle "Built with Kitfly" (default: true)
• Provenance label changed from bare date to Published YYYY-MM-DD
• Copyright year derived from publish date (provenance), not runtime

KitflyBrand architecture

• Immutable KITFLY_BRAND constant — tool identity separate from user's SiteBrand
• Attribution references KITFLY_BRAND, not user config — survives site customization
• Not overridable by design: on/off toggle only, no "Built with <X>" config path

Bundle parity

• Bundles show Kitfly attribution by default
• Bundle footer uses shared buildBundleFooter() instead of inline copy
• All footer config options (copyright, copyrightUrl, links, attribution) work in bundles

Security

• All user-provided config strings (copyright, copyrightUrl, links[].text, links[].url, brand.name, brand.url) are HTML-escaped before interpolation
• Prevents markup injection from malformed config values

Release infrastructure

• Platform binary builds: Linux x64/arm64, macOS arm64, Windows x64/arm64
• Simplified release tag pattern in workflow
• Release script improvements for asset and provenance uploads

Bug fixes

• brand.url: "/" (relative URL) now displays brand.name as link text instead of bare /
• Footer wrapping on narrow viewports: min-height replaces fixed height to prevent overflow

Breaking Changes

None. All footer additions are opt-in. Existing sites get "Built with Kitfly" attribution by default (disable with footer.attribution: false).

Migration

No migration needed. To customize the footer, add a footer: block to site.yaml:

footer:
  copyright: "© 2026 My Company, Inc."
  copyrightUrl: "https://mycompany.com"
  links:
    - text: "Privacy"
      url: "/privacy"
  attribution: true