@bigknoxy/hashpilot 4.6.3

package/docs/INTEGRATION-MCP.md

@@ -0,0 +1,196 @@
+# HashPilot as an MCP server
+
+HashPilot speaks the [Model Context Protocol](https://modelcontextprotocol.io) over
+stdio. Point any MCP host at `hashpilot mcp --stdio` and every editing tier —
+AST, hash-anchored, and diff — shows up as a typed tool, with the same advisory
+locking, provenance, and snapshot/undo guarantees the CLI gets.
+
+MCP is now the recommended integration path. The CLI remains fully supported and
+is the fallback for hosts without MCP support, and for shell and CI use.
+
+## Why MCP over the CLI
+
+| | MCP | CLI |
+|---|---|---|
+| Multi-line content with quotes and backticks | Rides inside JSON; no escaping | Needs `@file` indirection to dodge the shell |
+| Tool discovery | The host lists tools and schemas to the model | The model must be told the commands |
+| Errors | Structured, with `code` and `recovery` the model can act on | Same envelope, but parsed out of stdout |
+| Availability | Requires an MCP-capable host | Anywhere with a shell |
+
+## Install
+
+```bash
+npm install -g hashpilot     # or: bun add -g hashpilot
+hashpilot doctor             # confirm the install is healthy
+```
+
+## Configure your host
+
+### Claude Code
+
+```bash
+claude mcp add hashpilot -- hashpilot mcp --stdio
+```
+
+Or add it to `~/.claude.json` by hand:
+
+```json
+{
+  "mcpServers": {
+    "hashpilot": {
+      "command": "hashpilot",
+      "args": ["mcp", "--stdio"]
+    }
+  }
+}
+```
+
+### Claude Desktop
+
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS
+(`%APPDATA%\Claude\claude_desktop_config.json` on Windows):
+
+```json
+{
+  "mcpServers": {
+    "hashpilot": {
+      "command": "hashpilot",
+      "args": ["mcp", "--stdio"]
+    }
+  }
+}
+```
+
+Restart Claude Desktop afterwards; it reads the config only at launch.
+
+### Cursor
+
+`.cursor/mcp.json` in the project, or `~/.cursor/mcp.json` globally:
+
+```json
+{
+  "mcpServers": {
+    "hashpilot": {
+      "command": "hashpilot",
+      "args": ["mcp", "--stdio"]
+    }
+  }
+}
+```
+
+### Zed, Continue, and other hosts
+
+Any host that launches a stdio MCP server takes the same three fields — command
+`hashpilot`, args `["mcp", "--stdio"]`, and no environment beyond your shell's.
+If your host wants an absolute path, use `which hashpilot`.
+
+### Running from a checkout
+
+Without a global install, point the host at the repo:
+
+```json
+{
+  "mcpServers": {
+    "hashpilot": {
+      "command": "bun",
+      "args": ["run", "/absolute/path/to/HashPilot/src/cli.ts", "mcp", "--stdio"]
+    }
+  }
+}
+```
+
+## Tools
+
+Every tool is generated from the operation registry in
+[`src/core/operations.ts`](../src/core/operations.ts), which is the same list the
+CLI surface is verified against — the two cannot drift.
+
+### Reading
+
+| Tool | Use it for |
+|---|---|
+| `read_many` | Whole files plus a content hash per file. The hash is the anchor a later `replace_hash` verifies against. |
+| `read_hash` | One line with context and its hash, when you already know the line. |
+| `grep_many` | Regex search across paths. The cheapest way to locate code. |
+| `symbol_lookup_many` | Where symbols are *defined* (not referenced). |
+| `find_symbols` | Every symbol declared in one file. |
+| `ast_capabilities` | Which languages and AST operations are supported. |
+
+### Editing
+
+| Tool | Tier | Use it for |
+|---|---|---|
+| `rename_symbol` | AST | Binding-aware, file-scoped rename. |
+| `replace_body` | AST | Swap a function body, keep the signature. |
+| `add_import` / `remove_import` | AST | Imports, in the language's own style. |
+| `insert_before` / `insert_after` | AST | Code anchored to a symbol, not a line number. |
+| `replace_hash` | Hash | Verified replacement — refuses if the file changed since you read it. |
+| `replace_content` | Diff | Exact-match fallback; refuses on an ambiguous match. |
+| `route_edit` | auto | Any operation, letting HashPilot pick the strongest tier available. |
+
+### Verification
+
+`verify_changes` runs the project's own formatter, linter, type checker, and
+tests, scoped to the files you edited. Pass `useBaseline: true` so tests that
+were already failing do not get blamed on your edit.
+
+Every mutating tool accepts `dryRun`, plus `actor`, `taskId`, and `reason` for
+provenance — the same fields the CLI records, queryable afterwards with
+`hashpilot provenance query <file>`.
+
+## Error handling
+
+A failed edit comes back as a normal MCP result with `isError: true`, not as a
+JSON-RPC error. Protocol errors are the host's problem; tool errors are yours to
+read and recover from. The payload is the standard envelope:
+
+```json
+{
+  "apiVersion": "1",
+  "ok": false,
+  "command": "replace_hash",
+  "data": null,
+  "error": {
+    "code": "STALE_ANCHOR",
+    "message": "the file changed since the hash was taken",
+    "recovery": "Re-read the file and retry with the new hash."
+  },
+  "warnings": []
+}
+```
+
+Act on `error.code`; `error.recovery` says what to do next. The codes are the
+same ones the CLI reports — see [ADAPTER-CONTRACT.md](ADAPTER-CONTRACT.md).
+
+Every tool response — success or failure — carries all five envelope fields,
+byte-for-byte the shape the CLI writes: `command` names the tool that answered,
+`data` and `error` are both present with one of them `null`, and `warnings`
+reports route fallbacks and relocated hash anchors. That last one is the reason
+this matters: an AST edit that quietly became a diff edit is otherwise
+indistinguishable from one that stayed on the AST tier ([#104](../../issues/104)).
+
+## Write boundary
+
+The MCP server enforces exactly the same boundary as the CLI: writes are
+confined to the project root, and credentials, shell config, and system paths
+are refused unconditionally. A tool call cannot widen it. Widen the project's
+own `allowedRoots` in `.hashpilot.json` if you legitimately need more.
+
+## Troubleshooting
+
+**The host shows no tools.** Check the binary runs: `hashpilot mcp --stdio`
+should sit waiting on stdin rather than exiting. `hashpilot doctor` diagnoses a
+broken install.
+
+**Edits fail with `PATH_DENIED`.** The target is outside the project root. Start
+the host from the project directory, or add the location to `allowedRoots`.
+
+**AST tools fall back to hash or diff.** tree-sitter is a native module; if the
+bindings did not build, parsers load as `null` and routing degrades silently.
+Reinstall, then check `ast_capabilities`.
+
+**Verify a host's view by hand:**
+
+```bash
+printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | hashpilot mcp --stdio
+```

package/docs/INTEGRATION-OPENCODE.md

@@ -0,0 +1,136 @@
+# HashPilot — OpenCode Integration Guide
+
+## Integration Pattern
+
+HashPilot integrates with OpenCode as a **skill** (for inline guidance) and a **subagent** (for delegated editing tasks).
+
+## Installed Components
+
+### Skill: `~/.config/opencode/skills/hashpilot/SKILL.md`
+
+Provides instructions that OpenCode's AI can reference when deciding how to edit files. The skill triggers when:
+- The user asks to edit files precisely
+- Hash-anchored edits are appropriate
+- TypeScript/TSX symbol-level edits are needed
+
+### Agent: `~/.config/opencode/agent/hashpilot.md`
+
+A subagent definition with full tool access (bash, write, edit, read, grep, glob) that:
+- Prefers AST commands for TypeScript, TSX, JavaScript, Python, Go, Rust
+- Uses hash-anchored edits for other files
+- Verifies changes after editing
+- Handles stale anchors by re-reading and retrying
+
+## Setup
+
+The skill and agent are already installed. If you need to set them up manually:
+
+```bash
+# Skill
+mkdir -p ~/.config/opencode/skills/hashpilot
+cp ~/.agentic-tools/structured-editing/templates/opencode-skill.md ~/.config/opencode/skills/hashpilot/SKILL.md
+
+# Agent (already auto-discovered from ~/.config/opencode/agent/)
+# No additional setup needed
+```
+
+### PATH requirement
+
+Ensure `~/.agentic-tools/bin` is in PATH before launching OpenCode:
+
+```bash
+# Add to ~/.bashrc or ~/.zshrc
+export PATH="$HOME/.agentic-tools/bin:$PATH"
+```
+
+## Usage in OpenCode Sessions
+
+### Inline skill usage
+
+When OpenCode detects file editing tasks, it will reference the hashpilot skill and use `hashpilot` commands directly via bash tool:
+
+```bash
+# OpenCode agent using hash-anchored edit
+HASH=$(hashpilot read-many src/config.ts | jq -r '.[0].hash')
+hashpilot replace-hash src/config.ts "$HASH" "new content"
+
+# OpenCode agent using AST edit for TypeScript
+hashpilot ast rename-symbol src/api.ts oldFunc newFunc
+```
+
+### Subagent delegation
+
+Use the HashPilot subagent for complex multi-file editing tasks:
+
+```
+/agent hashpilot
+
+Rename the function 'processData' to 'transformData' across all files 
+in src/ and update the imports accordingly.
+```
+
+The subagent will:
+1. Find all files containing `processData`
+2. Use `ast rename-symbol` for .ts files
+3. Use `replace-hash` for other files
+4. Run `verify-changes` on all modified files
+
+## When to Use HashPilot vs Raw Editing
+
+| Task | Use HashPilot | Use Direct |
+|------|--------------|------------|
+| Edit existing TS/JS/Python/Go/Rust files | ✅ AST commands | ❌ |
+| Edit any file with hash safety | ✅ replace-hash | ❌ |
+| Rename symbols across files | ✅ ast rename-symbol | ❌ |
+| Add/remove imports | ✅ ast add-import / remove-import | ❌ |
+| Replace function body | ✅ ast replace-body | ❌ |
+| Batch read multiple files | ✅ read-many | ❌ |
+| Verify changes (lint+test) | ✅ verify-changes | ❌ |
+| Create new files | ❌ | ✅ write |
+| Delete files/directories | ❌ | ✅ bash rm |
+| Move/rename files | ❌ | ✅ bash mv |
+| Simple one-line edits | optional | ✅ direct edit |
+| Single-file exploration | optional | ✅ direct read |
+
+**General rule**: HashPilot for precision edits to existing files; direct tools for creation, deletion, and file system operations.
+
+## Key Advantages Over Raw Editing
+
+| Aspect | Raw Edit | HashPilot |
+|--------|----------|-----------|
+| Line counting | Required, error-prone | Hash-anchored, robust |
+| TypeScript edits | Text-based, imprecise | AST-aware, symbol-level |
+| Conflict detection | None | Stale anchor rejection |
+| Verification | Manual | Bundled formatter+linter+tests |
+| Audit trail | None | Telemetry logging |
+
+## Reference: Complete Command List
+
+```
+hashpilot read-many <files...>
+hashpilot read-hash <file> <line> [-c <context>]
+hashpilot grep-many <pattern> <paths...>
+hashpilot symbol-lookup-many <paths...> --names n1,n2
+hashpilot replace-hash <file> <hash> <content> [--range s:e] [--dry-run] [--actor] [--task-id] [--reason]
+hashpilot ast find-symbols <file>
+hashpilot ast capabilities
+hashpilot ast rename-symbol <file> <old> <new> [--actor] [--task-id] [--reason]
+hashpilot ast replace-body <file> <symbol> <body> [--actor] [--task-id] [--reason]
+hashpilot ast add-import <file> '<spec>' [--actor] [--task-id] [--reason]
+hashpilot ast remove-import <file> '<spec>' [--actor] [--task-id] [--reason]
+hashpilot ast insert-before <file> <symbol> <content> [--actor] [--task-id] [--reason]
+hashpilot ast insert-after <file> <symbol> <content> [--actor] [--task-id] [--reason]
+hashpilot diff generate <file> <old> <new>
+hashpilot diff apply <file> --patch <file> [--dry-run]
+hashpilot route <file> <op> [--policy <json>]
+hashpilot route-edit <file> <op> [--method <route>] [--dry-run]
+hashpilot batch <op> <files...> [--serial] [--dry-run]
+hashpilot intent '<json>' [--project-root <dir>] [--dry-run]
+hashpilot config
+hashpilot doctor
+hashpilot verify-changes <files...> [--formatter] [--linter] [--typecheck] [--test-filter] [--auto-detect]
+hashpilot provenance query <file> [<line>] [--human]
+hashpilot provenance changeset <changeSetId> [--human]
+hashpilot telemetry [show|summary|health|clear|sessions|export|prune]
+hashpilot telemetry health [-w <days>] [--trend]
+```

package/docs/INTEGRATION-PI.md

@@ -0,0 +1,195 @@
+# HashPilot — Pi Integration Guide
+
+## Two Integration Modes
+
+HashPilot integrates with Pi in two ways:
+
+1. **Native Extension** (recommended) — Custom tools registered in Pi's tool system, available in every session
+2. **CLI Mode** — Direct shell commands via `hashpilot`
+
+## Mode 1: Native Pi Extension (Recommended)
+
+The HashPilot Pi extension is installed at `~/.pi/agent/extensions/hashpilot.ts`. It registers 7 custom tools and a `/hp` slash command.
+
+### Registered Tools
+
+| Tool | Description |
+|------|-------------|
+| `hashpilot_read` | Batch read files with content hashes |
+| `hashpilot_search` | Grep regex across paths |
+| `hashpilot_read_hash` | Read line with hash anchor and context |
+| `hashpilot_replace_hash` | Hash-anchored content replacement |
+| `hashpilot_ast` | AST operations for supported languages (find-symbols, rename, replace-body, add/remove import, insert) |
+| `hashpilot_verify` | Run formatter + linter + tests on files |
+| `hashpilot_status` | Show routing info and telemetry summary |
+
+### Slash Command
+
+`/hp <subcommand>` — Quick access to HashPilot:
+- `/hp route <file> <op>` — Show which edit route would be chosen
+- `/hp telemetry` — Show telemetry summary
+
+### Skill
+
+The `hashpilot` skill at `~/.pi/agent/skills/hashpilot/SKILL.md` provides routing instructions and workflow guidance. Use `/skill:hashpilot` to load it.
+
+### How It Works
+
+The extension calls `hashpilot` CLI under the hood via `pi.exec()`. Each tool:
+1. Validates parameters using TypeBox schemas
+2. Calls the appropriate `hashpilot` command
+3. Parses JSON output
+4. Returns structured results to the LLM
+
+For `hashpilot_replace_hash`, stale-anchor detection is built in — if the hash is stale, the tool returns a clear error message telling the agent to re-read and retry.
+
+### Enabling/Disabling
+
+The `hashpilot_enabled` flag controls whether tools appear in Pi's Available Tools. Default: enabled.
+
+## Mode 2: CLI Direct Usage
+
+If the extension isn't loaded, Pi can call `hashpilot` directly via shell:
+
+```bash
+# Read files with hashes
+hashpilot read-many src/main.ts src/worker.ts
+
+# Read a line with context
+hashpilot read-hash src/main.ts 42
+
+# Hash-anchored replacement
+HASH=$(hashpilot read-many src/config.py | jq -r '.[0].hash')
+hashpilot replace-hash src/config.py "$HASH" "new content"
+
+# AST operations (TypeScript, TSX, JavaScript, Python, Go, Rust)
+hashpilot ast find-symbols src/main.ts
+hashpilot ast rename-symbol src/main.ts oldFunc newFunc
+hashpilot ast replace-body src/main.ts myFunc 'return 42;'
+hashpilot ast add-import src/app.ts '{ Router } from express'
+hashpilot ast remove-import src/app.ts './bar'
+
+# Generate and apply unified diffs
+hashpilot diff generate src/main.ts "$(cat old.ts)" "$(cat new.ts)"
+hashpilot diff apply src/main.ts --patch changes.patch
+
+# Route decisions and config
+hashpilot route src/main.ts rename-symbol
+hashpilot config
+
+# Batch edit across files
+hashpilot batch add-import src/*.ts --import-spec "{ z } from zod" --dry-run
+
+# Edit provenance
+hashpilot provenance query src/main.ts --human
+
+# Verify changes (with auto-detection)
+hashpilot verify-changes src/main.ts --auto-detect
+```
+
+## Routing Strategy
+
+HashPilot uses a strict priority for edit method selection:
+
+1. **AST** — For supported languages (TypeScript, TSX, JavaScript, Python, Go, Rust) with AST-compatible operations (rename, replace-body, add/remove import, insert)
+2. **Hash** — For hash-anchored content identification (any file type)
+3. **Diff** — Fallback for unsupported operations
+
+Check routing: `hashpilot route <file> <operation> [--policy <json>]`
+
+For detailed explanation with policy matches, use `--policy` to test override behavior:
+
+```bash
+hashpilot route src/main.ts rename-symbol
+# → { route: "ast", explanation: { reasons: ["Language 'typescript' supports AST operations"], ... } }
+
+hashpilot route src/main.py rename-symbol --policy '{"languageOverrides":{"python":"hash"}}'
+# → { route: "hash", explanation: { policyApplied: true, ... } }
+```
+
+## Configuration
+
+HashPilot supports layered configuration via files and environment variables:
+
+| Source | Path | Priority |
+|--------|------|----------|
+| Global config | `~/.config/hashpilot/config.json` | Lowest (applied first) |
+| Project config | `.hashpilot.json` in cwd | Medium |
+| CLI override | `--config <path>` | Higher |
+| Environment | `HASHPILOT_ROUTE_POLICY` env var | Highest |
+
+Example project config (`.hashpilot.json`):
+
+```json
+{
+  "routePolicy": {
+    "languageOverrides": { "python": "hash" },
+    "operationOverrides": { "add-import": "diff" }
+  }
+}
+```
+
+View current merged config: `hashpilot config`
+
+## Stale Anchor Recovery
+
+HashPilot has **auto-recovery** for stale anchors. When the file has changed since the hash was computed, `replace-hash` auto-recovers by applying the edit to the current content and returning `"retries": 1`. This is always safe for full-file replaces.
+
+If auto-recovery fails or is disabled:
+1. Re-read the file: `hashpilot read-many <file>`
+2. Get the new hash from the response
+3. Retry `replace-hash` with the updated hash
+
+The native `hashpilot_replace_hash` tool surfaces stale-anchor status in its response details (`details.stale`), and the extension handles the result accordingly.
+
+## Telemetry
+
+All operations are logged to `~/.agentic-tools/logs/telemetry.jsonl`.
+
+```bash
+hashpilot telemetry summary       # Operation counts and timing
+hashpilot telemetry show -n 50    # Last 50 events
+hashpilot telemetry health -w 7   # Health report with per-language stats and warnings
+hashpilot telemetry health -w 7 --trend  # Compare to previous window
+hashpilot telemetry sessions      # List session-level summaries
+hashpilot telemetry export --from 2026-01-01  # Export events as NDJSON
+hashpilot telemetry prune --older-than 30  # Delete old rotated files
+hashpilot telemetry clear         # Clear log
+```
+
+## When to Use HashPilot Tools vs Raw Commands
+
+| Task | Use HashPilot | Use Direct |
+|------|--------------|------------|
+| Edit existing TS/JS/Python/Go/Rust files | ✅ ast commands | ❌ |
+| Edit any file with hash safety | ✅ replace-hash | ❌ |
+| Rename symbols across files | ✅ ast rename-symbol | ❌ |
+| Add/remove imports | ✅ ast add-import / remove-import | ❌ |
+| Replace function body | ✅ ast replace-body | ❌ |
+| Batch read multiple files | ✅ hashpilot_read | ❌ |
+| Verify changes | ✅ hashpilot_verify | ❌ |
+| Create new files | ❌ | ✅ raw write |
+| Delete files/dirs | ❌ | ✅ bash |
+| Move/rename files | ❌ | ✅ bash |
+| Simple one-line edits | optional | ✅ direct edit |
+| Single-file exploration | optional | ✅ direct read |
+
+## Key Benefits
+
+1. **Reduced token usage** — Hash anchoring eliminates line-counting and re-reading
+2. **Fewer retries** — Stale anchor detection catches conflicts before corruption
+3. **Structured output** — JSON responses parse easily in agent logic
+4. **Verification batching** — One command to run all checks
+5. **Audit trail** — Telemetry logs every operation for debugging
+6. **Native Pi integration** — Custom tools appear in Pi's tool system with proper schemas and guidelines
+
+## Troubleshooting
+
+| Issue | Solution |
+|-------|----------|
+| `hashpilot: command not found` | Add `~/.agentic-tools/bin` to PATH in `~/.bashrc` |
+| `Module not found` errors | Run `bun install` in `~/.agentic-tools/structured-editing/` |
+| Tree-sitter errors | `bun add tree-sitter tree-sitter-typescript` in the structured-editing dir |
+| Pi extension not loading | Check `~/.pi/agent/extensions/hashpilot.ts` exists and has no syntax errors |
+| Tools not appearing | Restart Pi; check `~/.pi/agent/settings.json` doesn't disable extensions |
+| Stale hash errors | Re-read the file with `read-many` or `read-hash` and use the fresh hash |

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "@bigknoxy/hashpilot",
+  "version": "4.6.3",
+  "description": "HashPilot — Global Tool-Agnostic Structured Editing Core for Coding Agents",
+  "type": "module",
+  "engines": {
+    "bun": ">=1.2.0"
+  },
+  "bin": {
+    "hashpilot": "./src/cli-node.cjs"
+  },
+  "scripts": {
+    "test": "bun test",
+    "build": "bun build src/cli.ts --outdir dist --target bun",
+    "install-cli": "bash scripts/install-cli.sh",
+    "semantic-release": "semantic-release",
+    "gen:cli-quickref": "bun run scripts/gen-cli-quickref.ts",
+    "gen:cli-quickref:check": "bun run scripts/gen-cli-quickref.ts --check",
+    "lint:roadmap": "bun run scripts/roadmap-lint.ts",
+    "lint:docs": "bun run gen:cli-quickref:check && bun run lint:roadmap",
+    "bench": "bun run bench/runner.ts"
+  },
+  "files": [
+    "src/",
+    "scripts/",
+    "templates/",
+    "docs/",
+    "LICENSE",
+    "package.json",
+    "tsconfig.json"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bigknoxy/HashPilot.git"
+  },
+  "keywords": [
+    "structured-editing",
+    "coding-agents",
+    "tree-sitter",
+    "claude",
+    "opencode",
+    "pi"
+  ],
+  "author": "bigknoxy",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "bugs": {
+    "url": "https://github.com/bigknoxy/HashPilot/issues"
+  },
+  "homepage": "https://github.com/bigknoxy/HashPilot#readme",
+  "dependencies": {
+    "chalk": "^6.0.0",
+    "commander": "^15.0.0",
+    "glob": "^13.0.6",
+    "tree-sitter": "^0.25.1",
+    "tree-sitter-go": "0.25.0",
+    "tree-sitter-javascript": "0.25.0",
+    "tree-sitter-python": "^0.25.0",
+    "tree-sitter-rust": "^0.24.0",
+    "tree-sitter-typescript": "^0.23.2"
+  },
+  "devDependencies": {
+    "@semantic-release/changelog": "^7.0.0",
+    "@semantic-release/commit-analyzer": "^13.0.0",
+    "@semantic-release/git": "^11.0.1",
+    "@semantic-release/github": "^12.0.9",
+    "@semantic-release/npm": "^13.1.5",
+    "@semantic-release/release-notes-generator": "^14.0.0",
+    "@types/bun": "^1.1.0",
+    "@types/node": "^26.4.0",
+    "conventional-changelog-conventionalcommits": "^10.4.0",
+    "fast-check": "^4.9.0",
+    "semantic-release": "^25.0.9"
+  }
+}

package/scripts/build-site.sh

@@ -0,0 +1,39 @@
+#!/usr/bin/env bash
+# Build the GitHub Pages site into site/.
+#
+# The Pages workflow used to publish the repository root, which served internal
+# planning documents (M5_PLAN.md, M6_AUTOPLAN_REVIEW.md, AUDIT-2026-08.md),
+# workflow files, and the whole source tree under the docs domain (#49). The
+# site is now an explicit allowlist: anything not named here is not published.
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+OUT="$ROOT/site"
+
+rm -rf "$OUT"
+mkdir -p "$OUT/docs"
+
+cp "$ROOT/index.html" "$OUT/index.html"
+cp "$ROOT/README.md" "$OUT/README.md"
+cp "$ROOT/LICENSE" "$OUT/LICENSE"
+
+# Docs the landing page links to, or that are written for public consumption.
+PUBLIC_DOCS=(
+  ADAPTER-CONTRACT.md
+  ARCHITECTURE.md
+  CLI-QUICKREF.md
+  COMPETITIVE-ANALYSIS.md
+  INSTALL.md
+  INTEGRATION-CLAUDE.md
+  INTEGRATION-MCP.md
+  INTEGRATION-OPENCODE.md
+  INTEGRATION-PI.md
+)
+for doc in "${PUBLIC_DOCS[@]}"; do
+  cp "$ROOT/docs/$doc" "$OUT/docs/$doc"
+done
+
+# Jekyll would otherwise skip files and directories beginning with an underscore.
+touch "$OUT/.nojekyll"
+
+echo "Built site/ with $(find "$OUT" -type f | wc -l | tr -d ' ') files"