kitfly 0.1.2 → 0.2.1

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

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

@@ -0,0 +1,76 @@
+# kitfly stop
+
+Stop dev server(s).
+
+## Usage
+
+```bash
+kitfly stop <port|all> [options]
+```
+
+## Description
+
+Stops one or more running kitfly dev servers. Can target a specific port or stop all servers at once.
+
+## Arguments
+
+| Argument | Description                     |
+| -------- | ------------------------------- |
+| `port`   | Port number of server to stop   |
+| `all`    | Stop all running kitfly servers |
+
+## Options
+
+| Option    | Description                              |
+| --------- | ---------------------------------------- |
+| `--force` | Skip graceful shutdown, kill immediately |
+
+## Examples
+
+### Stop specific server
+
+```bash
+# Stop server on port 3333
+kitfly stop 3333
+```
+
+### Stop all servers
+
+```bash
+# Graceful shutdown of all servers
+kitfly stop all
+```
+
+### Force stop
+
+```bash
+# Immediate termination (use if graceful fails)
+kitfly stop 3333 --force
+kitfly stop all --force
+```
+
+## Graceful vs Force Shutdown
+
+**Graceful** (default):
+
+- Sends SIGTERM signal
+- Allows server to clean up
+- Waits briefly for process to exit
+
+**Force** (`--force`):
+
+- Sends SIGKILL signal
+- Immediate termination
+- Use when graceful shutdown hangs
+
+## Exit Codes
+
+| Code | Meaning                                           |
+| ---- | ------------------------------------------------- |
+| 0    | Server(s) stopped successfully                    |
+| 1    | Error (server not found, permission denied, etc.) |
+
+## See Also
+
+- [kitfly servers](servers.md) - List running servers
+- [kitfly dev](dev.md) - Start a server

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

@@ -0,0 +1,78 @@
+# kitfly update
+
+Update standalone site code.
+
+## Usage
+
+```bash
+kitfly update [version] [options]
+```
+
+## Description
+
+Updates the kitfly rendering code in a standalone site to a newer version. Preserves your content and configuration while upgrading the engine.
+
+> **Note**: This command is planned for v0.2.0 and may not be fully implemented yet.
+
+## Arguments
+
+| Argument  | Description                      |
+| --------- | -------------------------------- |
+| `version` | Target version (default: latest) |
+
+## Options
+
+| Option      | Description                                 |
+| ----------- | ------------------------------------------- |
+| `--dry-run` | Preview changes without applying            |
+| `--force`   | Update even if local modifications detected |
+
+## Examples
+
+### Basic usage
+
+```bash
+# Update to latest version
+kitfly update
+
+# Update to specific version
+kitfly update 0.2.0
+
+# Preview changes first
+kitfly update --dry-run
+```
+
+## What Gets Updated
+
+- `scripts/dev.ts`, `scripts/build.ts`, `scripts/bundle.ts`
+- `src/engine.ts`, `src/theme.ts`
+- `src/site/template.html`, `src/site/styles.css`
+- Schema files in `schemas/`
+
+## What Is Preserved
+
+- `content/` - Your documentation
+- `site.yaml` - Site configuration
+- `theme.yaml` - Theme customization
+- Custom modifications (with warning)
+
+## Modification Detection
+
+Kitfly tracks file checksums to detect local modifications. If you've customized engine files:
+
+1. Update will warn about modifications
+2. Use `--force` to overwrite
+3. Or manually merge changes
+
+## Version Compatibility
+
+Updates follow semantic versioning:
+
+- **Patch** (0.1.x): Safe, backward-compatible fixes
+- **Minor** (0.x.0): New features, may need config updates
+- **Major** (x.0.0): Breaking changes, migration may be required
+
+## See Also
+
+- [kitfly init](init.md) - Create new project
+- [kitfly version](version.md) - Check current version

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

@@ -0,0 +1,65 @@
+# kitfly version
+
+Show version information.
+
+## Usage
+
+```bash
+kitfly version [extended]
+kitfly version --extended
+kitfly --version
+kitfly -v
+```
+
+## Description
+
+Displays the current kitfly version. Use `extended` for detailed provenance information useful for debugging and support.
+
+## Options
+
+| Option       | Description                                      |
+| ------------ | ------------------------------------------------ |
+| `extended`   | Show extended version with git and platform info |
+| `--extended` | Same as `extended` subcommand                    |
+
+## Output
+
+### Basic Version
+
+```bash
+$ kitfly version
+0.1.0
+```
+
+### Extended Version
+
+```bash
+$ kitfly version extended
+kitfly 0.1.0
+Git commit: b95c6a8
+Git branch: main
+Git status: clean
+Bun: 1.3.7
+Platform: darwin/arm64
+```
+
+## Extended Output Fields
+
+| Field        | Description                                         |
+| ------------ | --------------------------------------------------- |
+| `kitfly`     | Current version from VERSION file                   |
+| `Git commit` | Short SHA of current commit                         |
+| `Git branch` | Current git branch name                             |
+| `Git status` | "clean" or "dirty (uncommitted changes)"            |
+| `Bun`        | Bun runtime version                                 |
+| `Platform`   | OS and architecture (e.g., darwin/arm64, linux/x64) |
+
+## Use Cases
+
+- **Bug reports**: Include `kitfly version extended` output
+- **Debugging**: Verify which version and commit is running
+- **Support**: Confirm runtime environment
+
+## See Also
+
+- [kitfly help](README.md)

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

@@ -0,0 +1,34 @@
+# Kitfly CLI Reference
+
+Command-line interface for kitfly - turn your writing into a website.
+
+## Quick Reference
+
+| Command          | Description                              |
+| ---------------- | ---------------------------------------- |
+| `kitfly dev`     | Start development server with hot reload |
+| `kitfly build`   | Build static site to dist/               |
+| `kitfly bundle`  | Build single-file HTML bundle            |
+| `kitfly init`    | Create new project from template         |
+| `kitfly update`  | Update standalone site code              |
+| `kitfly servers` | List running dev servers                 |
+| `kitfly stop`    | Stop dev server(s)                       |
+| `kitfly version` | Show version information                 |
+| `kitfly help`    | Show help message                        |
+
+## Global Behavior
+
+- All commands read configuration from `site.yaml` if present
+- Environment variables can override most options (prefixed with `KITFLY_`)
+- Exit codes: 0 = success, 1 = error
+
+## Command Documentation
+
+- [dev](dev.md) - Development server
+- [build](build.md) - Static site generation
+- [bundle](bundle.md) - Single-file HTML output
+- [init](init.md) - Project initialization
+- [update](update.md) - Site code updates
+- [servers](servers.md) - Server management
+- [stop](stop.md) - Stop servers
+- [version](version.md) - Version information

package/dist/_raw/docs/userguide/sharing.md

@@ -0,0 +1,94 @@
+---
+title: "Sharing Your Docs"
+description: "How to send, host, and deploy kitfly output"
+last_updated: "2026-02-09"
+---
+
+# Sharing Your Docs
+
+Kitfly has two export modes that serve different sharing needs.
+
+## Send It — Single HTML File
+
+Use `kitfly bundle` when you need to share docs without hosting.
+
+```bash
+kitfly bundle --name my-docs.html
+```
+
+This produces one self-contained HTML file with everything inlined: content, styles, images (as base64), syntax highlighting, and diagrams. No server needed — just open the file.
+
+### When to use bundle
+
+| Scenario            | Example                                 |
+| ------------------- | --------------------------------------- |
+| Email attachment    | Send docs to a client or reviewer       |
+| Slack/Teams upload  | Drop into a channel for quick reference |
+| Shared drive        | Put on Google Drive, Dropbox, OneDrive  |
+| USB/offline handoff | Works without internet                  |
+| Review cycle        | Stakeholders open in any browser        |
+| Archival            | Point-in-time snapshot of your docs     |
+
+### Bundle tips
+
+- **File size**: Typical docs produce 100KB–1MB bundles. Image-heavy sites will be larger (base64 adds ~33% overhead per image).
+- **Custom name**: Use `--name` to give the file a meaningful name for recipients (`--name q1-review.html`).
+- **Strip raw markdown**: Use `--no-raw` if you don't want source `.md` accessible inside the bundle.
+
+## Host It — Static Site
+
+Use `kitfly build` when you want to deploy to a web server.
+
+```bash
+kitfly build --out ./dist
+```
+
+This produces a `dist/` directory with standard HTML, CSS, and assets. Deploy it anywhere that serves static files.
+
+### Deployment targets
+
+| Platform           | How                                                                         |
+| ------------------ | --------------------------------------------------------------------------- |
+| **GitHub Pages**   | Push `dist/` to `gh-pages` branch or configure Pages to serve from a folder |
+| **Netlify**        | Set build command to `kitfly build`, publish directory to `dist`            |
+| **Vercel**         | Same pattern — build command + output directory                             |
+| **AWS S3**         | Sync `dist/` to an S3 bucket with static hosting enabled                    |
+| **Any web server** | Copy `dist/` contents to your server's document root                        |
+| **Local preview**  | `open dist/index.html` in your browser                                      |
+
+### Build tips
+
+- **Custom output**: `--out ./public` if your host expects a different directory name.
+- **Raw markdown included**: By default, `.md` source files are copied alongside HTML for transparency. Use `--no-raw` to exclude them.
+- **AI accessibility**: Build output includes `content-index.json`, `llms.txt`, and a `_raw/` directory so AI agents can read your docs. Use `--no-raw` to opt out.
+
+## Choosing Between Bundle and Build
+
+| Need                          | Use      |
+| ----------------------------- | -------- |
+| Share with one person         | `bundle` |
+| Share with a team (no server) | `bundle` |
+| Publish to the web            | `build`  |
+| Need search engine indexing   | `build`  |
+| Must work offline (no setup)  | `bundle` |
+| CI/CD pipeline                | `build`  |
+| Email attachment              | `bundle` |
+| GitHub Pages / Netlify        | `build`  |
+
+You can use both — `bundle` for quick reviews, `build` for the published site.
+
+## Development Preview
+
+During writing, use the dev server instead of building:
+
+```bash
+kitfly dev
+```
+
+This starts a local server at `http://localhost:3333` with hot reload. Edit any `.md` file and see changes instantly. When you're ready to share, switch to `bundle` or `build`.
+
+## See Also
+
+- [kitfly build](cli/build.md) — Build command reference
+- [kitfly bundle](cli/bundle.md) — Bundle command reference
+- [kitfly dev](cli/dev.md) — Development server

package/dist/_raw/schemas/plugin-schemas-notes.md

@@ -0,0 +1,71 @@
+---
+title: "Plugin Schema Notes"
+description: "Rationale and validation rules for plugin.yaml and registry/plugins.yaml schemas"
+last_updated: "2026-02-12"
+status: "draft"
+tags:
+  - plugins
+  - schemas
+  - supply-chain
+---
+
+# Plugin Schema Notes (v0.2.0)
+
+This note accompanies the draft schemas:
+
+- `schemas/plugin.schema.json` → `schemas/v0/plugin.schema.json` (plugin.yaml)
+- `schemas/plugin-registry.schema.json` → `schemas/v0/plugin-registry.schema.json` (registry/plugins.yaml)
+
+## Hook validation rules (plugin.yaml)
+
+The `hooks` block is validated as a strict object:
+
+- Allowed keys: `marked-extension`, `template-head`, `template-body-end`
+- Value type: boolean (`true`/`false`) only
+- Unknown keys: **invalid** (schema rejects via `additionalProperties: false`)
+
+Rationale: Contract-first + minimal loader. Unknown hooks should be caught at validation time rather than ignored at runtime.
+
+## Supply chain constraints
+
+- `dependencies.cdn[]` requires both `url` and `integrity`.
+- `integrity` must be an SRI string (`sha256|sha384|sha512` + base64).
+- Registry entries use **per-asset** SHA256 checksums: `assets.assetSha256.js` and/or `assets.assetSha256.css`.
+
+Rationale: The brief mandates SRI on all CDN resources; the schema encodes this as required fields, not optional hints.
+
+Rationale (checksums): Release-time `CHECKSUMS.yaml` is per-asset, and install-time verification should validate each fetched asset independently (JS and CSS can be cached and verified separately). Using an algorithm-specific field name (`assetSha256`) keeps room for future parallel algorithms without overloading a generic `checksums` structure.
+
+## Registry asset types
+
+The registry schema intentionally only supports `assets.js` and `assets.css` in v0.2.0.
+
+Rationale: Keep the contract minimal; add additional asset types only when a concrete plugin requires them.
+
+## Local registries (`baseUrl: ""`)
+
+For offline/local registries that only reference on-disk assets (e.g. `plugins-dist/...`), `baseUrl` may be an empty string.
+
+## Mode allowlisting (`modes`)
+
+Both plugin manifests (`plugin.yaml`) and registry entries may include an optional `modes` field.
+
+Semantics:
+
+- Omitted: allowed in **all** Kitfly modes
+- Present with values (e.g. `["docs"]`): allowed only in those modes
+- Present but empty (`[]`): blocked in **all** modes (useful for temporarily disabling a plugin without removing it from `kitfly.plugins.yaml`)
+
+Rationale: Kitfly has two primary rendering modes (`docs` and `slides`). Mode allowlisting is an intentionally small mechanism to keep plugins predictable and easy to dogfood across both surfaces.
+
+## Version range validation
+
+The `kitfly` field is required and validated as a simple “space-separated comparator” string (e.g. `>=0.2.0 <1.0.0`).
+
+Rationale: JSON Schema cannot fully validate npm/semver range syntax without embedding a custom parser. This pattern check is intentionally minimal: it enforces “looks like comparator(s) + semver” while leaving exact semantics to the loader.
+
+## Atomic plugins (no plugin-to-plugin dependencies)
+
+The schema defines `dependencies` with `additionalProperties: false` and only allows a `cdn` field.
+
+Rationale: This makes `dependencies.plugins` (or any other dependency category) invalid by construction, matching the “atomic plugins” decision.