kitfly 0.1.2 → 0.2.0

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.

package/dist/_raw/schemas.md

@@ -0,0 +1,42 @@
+---
+title: "Kitfly Schemas"
+description: "Schema versioning policy for site.yaml and theme.yaml"
+last_updated: "2026-02-05"
+---
+
+# Schemas
+
+Kitfly ships JSON Schemas for editor validation and migration detection.
+
+## Versioned Folders
+
+Schemas live under versioned folders:
+
+- `schemas/v0/` - alpha schemas (Kitfly v0.x.x)
+- `schemas/v1/` - stable schemas (when Kitfly reaches v1.x.x)
+
+The `v0/` folder name indicates the maturity track, not the exact schema content version.
+
+## Embedded Version
+
+Each schema includes:
+
+- `$id` - canonical identity (absolute URI)
+- `$version` - schema content version (semver string)
+
+Standalone sites are detached copies, so schemas must be self-describing.
+
+## Backward Compatibility
+
+For convenience, `schemas/site.schema.json` and `schemas/theme.schema.json` remain as thin wrappers
+that `$ref` the latest `schemas/v0/*` schemas.
+
+Plugin-related schemas follow the same pattern:
+
+- `schemas/plugin.schema.json` → `schemas/v0/plugin.schema.json`
+- `schemas/plugin-registry.schema.json` → `schemas/v0/plugin-registry.schema.json`
+- `schemas/plugins.schema.json` → `schemas/v0/plugins.schema.json`
+
+Shared definitions live in:
+
+- `schemas/v0/common.schema.json` (shared `$defs` referenced by multiple schemas)