kitfly 0.1.2 → 0.2.0

package/CHANGELOG.md

@@ -2,6 +2,40 @@
 
 All notable changes to Kitfly are documented here.
 
+## [0.2.0] - 2026-02-14
+
+### Added
+
+- Slides mode: `mode: slides` for fixed-aspect, hash-routed decks (`#slide-n`) with keyboard navigation
+- Slide authoring models: one-file-per-slide and intra-file `--- slide ---` segmentation
+- `kitfly init --template deck` for a ready-to-edit slides starter
+- Plugin system: `kitfly.plugins.yaml`, registry-backed asset injection, mode allowlists, and integrity checks (sha256 + SRI where applicable)
+- `slides-visuals` plugin (widgets + deterministic figures) with strict `:::` fence validation and actionable errors
+- `callouts` plugin: styled NOTE/TIP/WARNING/INFO/DANGER blockquotes via `kitfly.plugins.yaml`
+- Design primitives in core styles for deterministic visuals (block flow/grid + shape modifiers)
+- Server management commands: `kitfly servers`, `kitfly stop <port|all>`, `kitfly logs <port>`
+- Site version resolution: `site.yaml version: auto` (read `VERSION` file) and `version: file:<path>`
+- Brand logo fallback initials when logo asset is missing/unreadable
+
+### Changed
+
+- Bundle output to `bundles/` (separate from `dist/`) so static-deploy and single-file outputs don't interfere
+
+### Fixed
+
+- Plugin registry hardening and checksum enforcement (fail fast on mismatches)
+- Dev server behavior when iterating on plugin assets (cache invalidation and parity fixes)
+- Multiple `slides-visuals` parsing/rendering edge cases (list merging, list-style blocks, comparison-table layout)
+
+### Docs
+
+- New Deployment section with beginner-friendly guardrails and provider recipes
+- Expanded Reference docs (plugins contract, environment variables, key concepts, glossary, design catalog)
+
+### Deferred
+
+- Additional live-slides plugins (`slides-charts-lite`, `slides-refresh`, `slides-embed`) planned for v0.2.1
+
 ## [0.1.2] - 2026-02-10
 
 ### Added

package/README.md

@@ -12,13 +12,38 @@
 
 ---
 
+## Install
+
+Kitfly requires [Bun](https://bun.sh) as its runtime.
+
+```bash
+# Install Bun (if you don't have it)
+curl -fsSL https://bun.sh/install | bash
+
+# Install Kitfly globally (from npm)
+bun add -g kitfly
+
+# Verify
+kitfly --version
+```
+
+Alternative: `npm install -g kitfly` (still requires Bun, because the CLI runs with Bun).
+
+No global install: `bunx kitfly --version`
+
+Note: `bun`/`npm` installs the latest published release. If you’re reading `main` before a release is cut, clone this repo for the newest features.
+
+For contributor/development setup, see [docs/development.md](docs/development.md).
+
+---
+
 ## Three Ways to Use Kitfly
 
-| Approach | Best For | What You Get |
-|----------|----------|--------------|
-| **`kitfly init`** | New projects | Standalone site with your own copy of the code |
-| **`kitfly dev ./folder`** | Existing docs | Quick preview without changing anything |
-| **Clone this repo** | Contributors | The kitfly engine itself |
+| Approach                  | Best For      | What You Get                                   |
+| ------------------------- | ------------- | ---------------------------------------------- |
+| **`kitfly init`**         | New projects  | Standalone site with your own copy of the code |
+| **`kitfly dev ./folder`** | Existing docs | Quick preview without changing anything        |
+| **Clone this repo**       | Contributors  | The kitfly engine itself                       |
 
 ### Create a Standalone Site (Recommended)
 
@@ -29,6 +54,15 @@ bun install
 bun run dev
 ```
 
+Or start a slide deck:
+
+```bash
+kitfly init my-deck --template deck
+cd my-deck
+bun install
+bun run dev
+```
+
 You get a complete, self-contained site: rendering code, template, styles, config. It's yours — modify it, version it, own it. No kitfly CLI required after setup.
 
 ### Preview Existing Docs
@@ -52,7 +86,7 @@ bun run dev
 
 The `content/` folder is the actual kitfly documentation. What you see is what you get.
 
-See [Kitfly Overview](content/guide/kitfly-overview.md) for the full picture.
+For full contributor setup (toolchain, bootstrap, local CLI), see [docs/development.md](docs/development.md). For the product overview, see [Kitfly Overview](content/guide/kitfly-overview.md).
 
 ---
 
@@ -66,15 +100,17 @@ See [Kitfly Overview](content/guide/kitfly-overview.md) for the full picture.
 
 ## What You Get
 
-| Feature | How |
-|---------|-----|
-| Hot reload | Edit markdown, see changes instantly |
-| Navigation | Auto-generated from folder structure |
-| Table of contents | Extracted from headings |
-| Dark mode | System preference + toggle |
-| Diagrams | Mermaid via CDN |
-| Syntax highlighting | Prism.js via CDN |
-| Offline-ready | Static HTML, no server required |
+| Feature             | How                                                                     |
+| ------------------- | ----------------------------------------------------------------------- |
+| Hot reload          | Edit markdown, see changes instantly                                    |
+| Navigation          | Auto-generated from folder structure                                    |
+| Table of contents   | Extracted from headings                                                 |
+| Dark mode           | System preference + toggle                                              |
+| Slides mode         | `mode: slides` for fixed-aspect decks (v0.2.0+)                         |
+| Plugins             | Optional add-ons via `kitfly.plugins.yaml` (pinned + integrity-checked) |
+| Diagrams            | Mermaid via CDN                                                         |
+| Syntax highlighting | Prism.js via CDN                                                        |
+| Offline-ready       | Static HTML, no server required                                         |
 
 ## What You Don't Get
 
@@ -96,6 +132,7 @@ Create `site.yaml` (optional):
 docroot: "content"
 title: "My Documentation"
 home: "index.md"
+mode: "docs" # or "slides" (v0.2.0+)
 
 brand:
   name: "My Project"
@@ -110,6 +147,16 @@ sections:
 
 Or just drop markdown files in `content/` — sections auto-discover.
 
+## Plugins
+
+Plugins are optional CSS/JS add-ons (kept out of core) that you enable per-site.
+
+- Config: `kitfly.plugins.yaml`
+- Versions are pinned (`name@x.y.z`)
+- Assets are integrity-checked (sha256)
+
+See `content/reference/plugins.md` for the contract and examples.
+
 ---
 
 ## Philosophy
@@ -127,7 +174,7 @@ Kitfly is intentionally limited. The goal is a doc site that stays simple and ma
 - **Kit**: Your handbook, runbook, notebook — a collection of docs
 - **Fly**: Fast, instant, launching to the web
 
-*Pack your docs. Watch them fly.*
+_Pack your docs. Watch them fly._
 
 ---
 

package/VERSION

@@ -1 +1 @@
-0.1.2
+0.2.0

package/dist/_raw/content/deployment/preflight.md

@@ -0,0 +1,134 @@
+---
+title: "Preflight and Rollback"
+description: "A beginner-safe checklist before you publish"
+last_updated: "2026-02-12"
+---
+
+# Preflight and Rollback
+
+This page is intentionally simple. The goal is: publish safely, and be able to undo a bad deploy fast.
+
+## Preflight checklist
+
+### 1) Confirm what you're deploying
+
+- You have a single folder you will deploy: `dist/`
+- You know which source folder produced it (your docroot)
+
+### 2) Build clean
+
+From your site root:
+
+```bash
+make build
+```
+
+Or:
+
+```bash
+bun run build
+```
+
+Expected: `dist/` exists and contains `index.html` plus assets.
+
+### 3) Sanity check the output
+
+- Open the built site and click 3–5 pages
+- Check images load
+- Check code blocks render
+- Toggle dark mode (if your theme supports it)
+
+### 4) Decide your URL and DNS shape
+
+- If you can, start with a **subdomain** like `docs.example.com` (simpler DNS + easier to move later).
+- Keep "apex/root" (`example.com`) for your main marketing site unless you have a reason.
+- Avoid subdirectory paths (`example.com/docs/`) — Kitfly currently assumes root-level hosting.
+
+### 5) Verify HTTPS
+
+After your first deploy, confirm:
+
+- The site loads over `https://` (not just `http://`)
+- The browser shows a lock icon (valid certificate)
+- If your host offers "force HTTPS" or "redirect HTTP → HTTPS", enable it
+
+All hosts in the [deployment recipes](.) provision HTTPS automatically (usually via Let's Encrypt). You just need to verify it's working.
+
+### 6) Confirm secrets handling (if any)
+
+Kitfly build output is static. Most deployments need **no secrets**.
+
+If your deployment uses credentials (AWS keys, Netlify token, etc.):
+
+- store them in environment variables or your host's secret store
+- keep them out of git
+
+See: [Secrets and Environment Variables](secrets-and-env-vars.html)
+
+---
+
+## Rollback plan (simple and reliable)
+
+Pick one of these before you deploy:
+
+### Option A: Keep the previous `dist/` folder
+
+- Copy `dist/` to a dated folder before deploying:
+  - `dist-backup-YYYY-MM-DD/`
+- If something breaks, deploy the backup folder again.
+
+### Option B: Use a "previous" deployment on your host
+
+Many hosts keep deploy history. If they do:
+
+- confirm you can re-promote a prior deploy
+- confirm how long deploy history is retained
+
+---
+
+## Common failure modes
+
+- **Wrong folder uploaded** (not `dist/`)
+- **Old build** (you forgot to rebuild after edits)
+- **DNS not updated** (domain points somewhere else)
+- **Aggressive caching** (you deployed, but the browser/CDN serves old content)
+- **HTTPS not provisioned yet** (some hosts take a few minutes to issue the cert)
+
+If you suspect caching:
+
+- hard refresh (Shift+Reload)
+- try a private/incognito window
+- wait a few minutes (some CDNs take time)
+
+---
+
+## Cache invalidation (for CI/CD pipelines)
+
+If you deploy via automation and need to force-clear CDN caches, here are the common commands:
+
+### AWS CloudFront
+
+```bash
+aws cloudfront create-invalidation \
+  --distribution-id "$KITFLY_AWS_CLOUDFRONT_DISTRIBUTION_ID" \
+  --paths "/*"
+```
+
+### Cloudflare (Pages or R2 behind Workers)
+
+Cloudflare Pages automatically invalidates on deploy. If you use R2 with a custom Worker and need to purge:
+
+```bash
+curl -X POST "https://api.cloudflare.com/client/v4/zones/$KITFLY_CF_ZONE_ID/purge_cache" \
+  -H "Authorization: Bearer $KITFLY_CF_API_TOKEN" \
+  -H "Content-Type: application/json" \
+  --data '{"purge_everything":true}'
+```
+
+### Netlify
+
+Netlify invalidates automatically on every deploy. No manual purge needed.
+
+### Vercel
+
+Vercel invalidates CDN cache on deploy. No manual purge needed.

package/dist/_raw/content/deployment/recipes/aws-s3.md

@@ -0,0 +1,128 @@
+---
+title: "Recipe: AWS S3"
+description: "Static hosting on S3 (sync `dist/`)"
+last_updated: "2026-02-12"
+---
+
+# Recipe: AWS S3
+
+S3 is a solid choice when you're already in AWS.
+
+If you're not already on AWS, Netlify or GitHub Pages is usually faster to get right.
+
+## Prerequisites
+
+- An AWS account
+- AWS CLI installed (`aws`)
+- A bucket to host your site
+
+## Secrets (important)
+
+If you use access keys locally, keep them out of git and prefer least-privilege IAM.
+
+Minimal IAM policy for deployment (scope to your bucket):
+
+```json
+{
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Effect": "Allow",
+      "Action": ["s3:PutObject", "s3:DeleteObject", "s3:ListBucket"],
+      "Resource": [
+        "arn:aws:s3:::YOUR_BUCKET_NAME",
+        "arn:aws:s3:::YOUR_BUCKET_NAME/*"
+      ]
+    }
+  ]
+}
+```
+
+If you use CloudFront (see below), add:
+
+```json
+{
+  "Effect": "Allow",
+  "Action": "cloudfront:CreateInvalidation",
+  "Resource": "arn:aws:cloudfront::ACCOUNT_ID:distribution/DISTRIBUTION_ID"
+}
+```
+
+See: [Secrets and Environment Variables](../secrets-and-env-vars.html)
+
+## Build
+
+```bash
+make build
+```
+
+## Deploy (sync `dist/`)
+
+```bash
+aws s3 sync dist/ "s3://$KITFLY_AWS_S3_BUCKET/" --delete
+```
+
+Tip: `--delete` keeps the bucket from accumulating old files when pages change names.
+
+## CloudFront (recommended for production)
+
+S3 alone can serve a website, but CloudFront gives you:
+
+- HTTPS with a custom domain (via ACM certificate)
+- Global CDN caching
+- Better control over headers and redirects
+
+### Basic CloudFront setup shape
+
+1. **Create an ACM certificate** for your domain (must be in `us-east-1` for CloudFront):
+
+   ```bash
+   aws acm request-certificate \
+     --domain-name docs.example.com \
+     --validation-method DNS \
+     --region us-east-1
+   ```
+
+2. **Create a CloudFront distribution** with S3 as origin:
+   - Origin: your S3 bucket (use the S3 REST endpoint, not the website endpoint)
+   - Use Origin Access Control (OAC) so the bucket doesn't need to be public
+   - Set default root object: `index.html`
+   - Attach your ACM certificate
+   - Set alternate domain name: `docs.example.com`
+
+3. **Point DNS** at CloudFront:
+   - `docs.example.com` → **CNAME** to your CloudFront distribution domain (`d1234.cloudfront.net`)
+
+4. **Invalidate cache after deploy:**
+   ```bash
+   aws cloudfront create-invalidation \
+     --distribution-id "$KITFLY_AWS_CLOUDFRONT_DISTRIBUTION_ID" \
+     --paths "/*"
+   ```
+
+The CloudFront console and `aws cloudfront create-distribution` CLI have many options. Start simple and add complexity as needed.
+
+## DNS basics (without CloudFront)
+
+If you use S3 website hosting directly (no CloudFront):
+
+- `docs.example.com` → **CNAME** to `YOUR_BUCKET_NAME.s3-website-REGION.amazonaws.com`
+
+Note: S3 website hosting does not support HTTPS on custom domains. For HTTPS, put CloudFront in front.
+
+## About "S3 static website hosting"
+
+AWS has an S3 "website hosting" mode. It works for simple cases, but most teams prefer putting S3 behind CloudFront:
+
+- HTTPS on custom domains
+- Global edge caching
+- Better security (bucket stays private via OAC)
+
+If you're not sure: start with the simplest approach your org already uses.
+
+## Verify + Rollback
+
+- Verify: load the site, click a few pages, hard refresh, confirm HTTPS lock icon
+- Rollback: re-sync the previous build output (or use S3 versioning if you enabled it)
+
+See: [Preflight and Rollback](../preflight.html)

package/dist/_raw/content/deployment/recipes/cloudflare-pages.md

@@ -0,0 +1,73 @@
+---
+title: "Recipe: Cloudflare Pages"
+description: "Beginner-friendly Cloudflare hosting for static `dist/` output"
+last_updated: "2026-02-12"
+---
+
+# Recipe: Cloudflare Pages
+
+Cloudflare Pages is a strong default if you want Cloudflare to "just host the static site" with CDN performance and a simple custom domain story.
+
+If you were looking at Cloudflare R2: Pages is usually easier. R2 is object storage and is best treated as an advanced building block.
+
+See also:
+
+- [Recipe: Cloudflare R2](cloudflare-r2.html)
+
+## Prerequisites
+
+- A Cloudflare account
+- (Recommended) Your domain on Cloudflare DNS
+- (For CLI deploys) `wrangler` installed: `npm i -g wrangler`
+
+## Build
+
+```bash
+make build
+```
+
+Your deployable output is the `dist/` folder.
+
+## Deploy (three common workflows)
+
+### Option A: Connect a Git repo (repeatable)
+
+1. Create a new Pages project in Cloudflare
+2. Connect your repo
+3. Set build command: `make build`
+4. Set output/publish directory: `dist`
+
+Now "push to main" becomes "deploy the site".
+
+Note: Cloudflare's build environment may not have Bun pre-installed. If the build fails, set the environment variable `BUN_VERSION=1` in the Pages project settings, or use Option B/C instead.
+
+### Option B: Upload static output (quick, via dashboard)
+
+If you just want a link quickly:
+
+1. Build locally (`make build`)
+2. Upload the `dist/` output in the Pages UI
+
+### Option C: Deploy via CLI (repeatable, no git integration)
+
+```bash
+make build
+npx wrangler pages deploy dist/ --project-name=your-project-name
+```
+
+This is useful for CI/CD pipelines or when you don't want to connect a git repo.
+
+## Custom domain (DNS basics)
+
+Typical pattern:
+
+- `docs.example.com` → **CNAME** to the Pages target Cloudflare provides
+
+If you use Cloudflare DNS, Pages will usually guide you through the exact record to create. HTTPS is provisioned automatically.
+
+## Verify + Rollback
+
+- Verify: load the site, click a few pages, hard refresh, confirm HTTPS lock icon
+- Rollback: redeploy the previous build from Pages dashboard (or revert the commit if you deploy from git)
+
+See: [Preflight and Rollback](../preflight.html)

package/dist/_raw/content/deployment/recipes/cloudflare-r2.md

@@ -0,0 +1,156 @@
+---
+title: "Recipe: Cloudflare R2"
+description: "Advanced: publish `dist/` using Cloudflare storage and edge routing"
+last_updated: "2026-02-12"
+---
+
+# Recipe: Cloudflare R2
+
+This recipe is intentionally labeled **advanced**.
+
+If you want the simplest Cloudflare experience for a static site, Cloudflare Pages is usually the easiest path:
+
+- [Recipe: Cloudflare Pages](cloudflare-pages.html)
+
+R2 is great when you want object storage as your origin and you're comfortable wiring edge routing/caching.
+
+## When to use this
+
+- You're already using Cloudflare (DNS, Workers, caching)
+- You want `dist/` stored as objects and served at the edge
+
+## Pages vs R2 (which should I choose?)
+
+### Choose Cloudflare Pages when…
+
+- You want a "deploy and host" product for static sites
+- You're fine with "connect a repo and publish `dist/`" as your workflow
+- You want custom domains + HTTPS without a lot of plumbing
+
+### Choose Cloudflare R2 when…
+
+- You specifically want object storage as the source of truth for site files
+- You already have (or want) a Worker/edge layer in front
+- You care about storing and serving lots of assets and want S3-like primitives
+
+## High-level shape
+
+1. Build your site to `dist/`
+2. Upload `dist/` to an R2 bucket
+3. Serve it via an edge layer (typically a Worker) and attach your domain
+
+Important: R2 is object storage, not "a website host" by itself. You usually need something in front of it to handle requests and return the right file for a path.
+
+## Prerequisites
+
+- A Cloudflare account
+- A domain on Cloudflare DNS (recommended)
+- `wrangler` CLI installed: `npm i -g wrangler`
+- An R2 bucket created (via dashboard or `wrangler r2 bucket create <name>`)
+
+## Build
+
+```bash
+make build
+```
+
+## Upload `dist/` to R2
+
+### Using wrangler (recommended for CI/CD)
+
+Upload individual files:
+
+```bash
+# Upload all files from dist/ to the bucket
+for file in $(find dist -type f); do
+  key="${file#dist/}"
+  wrangler r2 object put "$KITFLY_CF_R2_BUCKET/$key" --file="$file"
+done
+```
+
+Or if you prefer a sync-like approach, use the rclone tool with R2's S3-compatible endpoint:
+
+```bash
+rclone sync dist/ "r2:$KITFLY_CF_R2_BUCKET/" \
+  --s3-provider=Cloudflare \
+  --s3-access-key-id="$KITFLY_CF_R2_ACCESS_KEY_ID" \
+  --s3-secret-access-key="$KITFLY_CF_R2_SECRET_ACCESS_KEY" \
+  --s3-endpoint="https://$KITFLY_CF_R2_ACCOUNT_ID.r2.cloudflarestorage.com"
+```
+
+### Using the dashboard
+
+Fine for small sites, but manual. Upload files in the R2 bucket view.
+
+## Serving: Worker in front of R2
+
+A minimal Worker to serve files from R2:
+
+```javascript
+// wrangler.toml:
+// [[r2_buckets]]
+// binding = "BUCKET"
+// bucket_name = "your-bucket-name"
+
+export default {
+  async fetch(request, env) {
+    const url = new URL(request.url);
+    let key = url.pathname.slice(1) || "index.html";
+    if (key.endsWith("/")) key += "index.html";
+
+    const object = await env.BUCKET.get(key);
+    if (!object) return new Response("Not found", { status: 404 });
+
+    const headers = new Headers();
+    headers.set(
+      "Content-Type",
+      object.httpMetadata?.contentType || "text/html",
+    );
+    return new Response(object.body, { headers });
+  },
+};
+```
+
+Deploy the Worker with `wrangler deploy` and attach your custom domain via the Cloudflare dashboard.
+
+## Secrets
+
+Keep R2 credentials in environment variables and **don't** commit them. See:
+
+- [Secrets and Environment Variables](../secrets-and-env-vars.html)
+
+## Caching (don't fight it)
+
+Cloudflare will cache aggressively if you ask it to. That's great for docs sites, but it can confuse first-time deploys.
+
+If you deploy and still see old content:
+
+- hard refresh (Shift+Reload)
+- try an incognito window
+- wait a minute
+- or purge cache via the Cloudflare dashboard / API (see [Preflight: Cache Invalidation](../preflight.html))
+
+## DNS basics
+
+Typical pattern:
+
+- Use a **subdomain** like `docs.example.com`
+- Point it at your Worker using Cloudflare's "Custom Domains for Workers" feature
+
+HTTPS is handled automatically when using Cloudflare DNS.
+
+## Verify
+
+- Load the site from your custom domain
+- Hard refresh once (caching can make you think deploy didn't work)
+- Click 3–5 pages and confirm assets load
+- Confirm the HTTPS lock icon
+
+## Rollback
+
+Rollback options:
+
+- re-upload the previous `dist/` objects
+- or switch your Worker routing back to a prior bucket/prefix
+
+See: [Preflight and Rollback](../preflight.html)