diff --git a/CHANGELOG.md b/CHANGELOG.md index 8c8b202..ccb077e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -21,6 +21,7 @@ _primitives/_rust/target/release/kei-changelog \ > ships must be replaced with the real commit summary before release. ### Added +- **docs (v0.22 — README `## Reference` section):** major new section appended before `## Runtime hook controls`. Documents the actual CLI surface of every shipped component: 25 Rust primitives (clap subcommands + flags + state paths + exit codes extracted from `_primitives/_rust/*/src/main.rs`), 13 shell primitives (header docstrings + flags), all 10 hooks (event + severity + bypass table), 39 skills grouped into 6 collapsible categories, and a deep-dive on the `keisei` exobrain CLI (real flag matrix, exit codes, env vars, marker SSoT, v0.19 security hardening). Every claim is source-verified — flags not present in code are marked absent, not fabricated. Adds ~500 LOC to README.md; collapsible `
` used for the 39-skill table to keep scroll length reasonable. - **primitives/keisei (v0.22 Track C — filesystem-type advisory):** new `fs_type.rs` cube (`<110 LOC`) classifies the brain root via `statfs(2)` on macOS + Linux and returns `FsWarning::{None,ExFat,Fat32,Unknown}`. Windows support deferred (returns `Unknown` until `GetVolumeInformationW` lands). `Brain::load` now prints a stderr advisory when exFAT / FAT32 is detected — SQLite WAL shared-mmap is unreliable there and `keisei mount` (multi-client) WILL corrupt `kei-memory` / `kei-artifact` / `kei-social-store` DBs. Warning is non-blocking — single-client `keisei attach` on exFAT stays supported. New runtime dep `libc = "0.2"` (unix-only). Two new integration tests (`brain_load_on_typical_filesystem_no_warn`, `fs_type_detection_returns_none_on_standard_fs`) — suite now 32/32 pass. - **tests/battle (v0.22 Track C — distro matrix):** two new Dockerfiles alongside the existing `ubuntu:24.04` image. `Dockerfile.install-test-alpine` (Alpine 3.19 — musl libc, exposes musl-static-link quirks in `rusqlite` / `git2` / `aws-sdk-s3`). `Dockerfile.install-test-debian` (Debian 12 bookworm — glibc, different apt structure from Ubuntu). `README.md` documents the 3-image matrix and documents known musl-static-link failures as matrix signal rather than regression. - **docs (v0.22 Track C — USB guide platform split):** `USB-BRAIN-GUIDE.md` restructured into a TOC + platform-agnostic preamble (prerequisites, exFAT/FAT32 warning, invariants, troubleshooting). Three new platform-specific walkthroughs: `USB-BRAIN-GUIDE-macos.md` (Gatekeeper `xattr`, `/Volumes/`, `diskutil`), `USB-BRAIN-GUIDE-linux.md` (`/media/$USER/`, `umount`, ext4, optional systemd-udev auto-attach), `USB-BRAIN-GUIDE-windows.md` (PowerShell, drive letter, NTFS, `Dismount-Volume`, FS-advisory returns `Unknown` caveat). diff --git a/README.md b/README.md index d39a7f4..7b7f82b 100644 --- a/README.md +++ b/README.md @@ -230,6 +230,676 @@ Security hardening (v0.19.0): Known deferred to v0.19.1: supply-chain hardening (commit `bun.lock`, SHA-pin GitHub Actions), marker file perms 0600, terminal-escape sanitization in status output, manifest size bound. +## Reference + +Every shipped component, its real behaviour, and where to look in source. Each subsection documents the actual CLI surface as extracted from `_primitives/_rust/*/src/main.rs`, `_primitives/*.sh`, `hooks/*.sh`, and `skills/*/SKILL.md`. If a flag or subcommand is not listed here, it does not exist in the current build. + +### Rust primitives + +All 25 crates live under `_primitives/_rust//`. After `install.sh` runs, binaries land at `~/.claude/agents/_primitives/_rust/target/release/`. Exit codes: `0` success, `1` usage/IO error, `2` validation/diff-found (per-tool; see each entry). + +#### `kei-ledger` — agent-fork lifecycle ledger (RULE 0.12) + +SQLite-backed append-only log of every non-trivial agent invocation. One row per fork; the orchestrator uses `validate` to check that the 6 required artefacts exist on the child branch before merging. + +``` +kei-ledger [--db ] + init — create ledger file + schema + fork --spec-sha — log a new running agent + [--parent ] [--worktree ] + done --summary — mark running agent done + fail --reason — mark running agent failed + merged — mark done/failed agent merged into parent + list [--status running|done|failed|merged] — dump history + tree — parent → children tree from root id + validate [--repo-root ] — check 6-artefact bundle exists + (spec.md / plan.md / progress.json / + chatlog.md / handoffs.md / review.md) +``` + +State: `$KEI_LEDGER_DB` or `~/.claude/agents/ledger.sqlite`. `validate` exits 2 if artefacts missing. + +#### `kei-migrate` — universal SQL migration runner + +Postgres / SQLite / MySQL via a single `DATABASE_URL`. Up/down/status/create. + +``` +kei-migrate --database-url [--dir ] + up — apply all pending migrations + down [n=1] — revert the last N migrations (needs _.down.sql) + status — list applied vs pending + create — scaffold _.sql (+ .down.sql) +``` + +URL formats accepted: `postgres://...`, `sqlite:///abs/path.db` or `sqlite::memory:`, `mysql://...`. Reads `DATABASE_URL` env var as fallback. + +#### `kei-changelog` — Conventional Commits → Markdown + +Git-cliff-shaped generator. Walks a commit range, groups by conventional-commit type, prepends to `CHANGELOG.md` or emits to stdout. + +``` +kei-changelog [--from ] [--to ] [--unreleased] + [--version ] [--repo ] + [--update ] +``` + +`--update` prepends under `# CHANGELOG` header (idempotent — won't duplicate an existing identical block). Without `--update`, prints to stdout. + +#### `ssh-check` — sshd_config linter + +Reads `/etc/ssh/sshd_config` + every `sshd_config.d/*.conf`, merges via last-wins, scores against the KeiSeiKit hardened-baseline rule matrix. + +``` +ssh-check [--config ] + [--drop-in ] + [--allow-user ]... [--json] +``` + +Repeatable `--allow-user` for extra accepted `AllowUsers` entries (default: `keiadmin`). Exits 2 if violations found. + +#### `firewall-diff` — ufw intent-vs-live diff + +Defensive-only — does NOT execute `ufw` itself. Takes an intent YAML + a captured `ufw status numbered` output (file or stdin) and reports drift. + +``` +firewall-diff --intent (--status-file | --stdin) [--json] +``` + +Exit 2 on any diff. Use via `ufw status numbered | firewall-diff --intent fw.yaml --stdin`. + +#### `mock-render` — WYSIWYD screenshot-and-lock + +Playwright-backed. Enforces the "What You See Is What's Deployed" invariant: every site section's source file is hashed, the hash is locked against a screenshot, and `verify` fails if the source drifts after lock. + +``` +mock-render screenshot --out [--viewport WxH] +mock-render lock --project --section [--screenshot ] +mock-render verify --project --section +mock-render status --project +``` + +Exit 2 on invariant violation (source hash changed since lock). + +#### `visual-diff` — pixel PNG comparator + +Used by `site-wysiwyd-check` hook to detect visual drift. Produces a red-overlay diff PNG when images differ beyond threshold. + +``` +visual-diff [--out ] [--threshold ] +``` + +Exit 2 if mismatch exceeds threshold. Prints percentage + diff-px count. + +#### `tokens-sync` — design tokens → Tailwind + CSS vars + +Single JSON file → Tailwind `theme.extend` config and CSS `:root` custom properties. Either or both output targets; at least one required. + +``` +tokens-sync [--out-tailwind ] [--out-css ] +``` + +JSON minimum shape: `{ colors, fonts, spacing, radius }`. + +#### `kei-memory` — session retrospective + pattern detector (RULE 0.14) + +Offline TF-IDF / recurrence analyzer powering `/self-audit`. Ingests JSONL transcripts, surfaces cross-session patterns. + +``` +kei-memory [--db ] + ingest --session-id --transcript [--prompt ] + analyze [--session ] [--last ] [--summary] + patterns [--cross-session] [--session ] + similar [--limit ] — top-k past sessions by TF-IDF cosine + dump — emit session events as markdown + stats — N sessions / N events / top tools + backlog [--add ] [--list] [--clear] — silent-first audit backlog +``` + +State: `$KEI_MEMORY_DB` or `~/.claude/memory/kei-memory.sqlite`. + +#### `kei-conflict-scan` — deep-sleep conflict scanner (v0.13.0) + +Scans a memory-repo clone for rule conflicts, overlapping hook matchers, >70%-duplicate blocks, orphaned wikilinks, Constructor-Pattern violations. + +``` +kei-conflict-scan --path + [--format json|human] [--only rules|hooks|blocks|orphans|cp] + [--exit-on-hit] +``` + +Emits JSON (default) or human table. Exit 2 only when `--exit-on-hit` AND hits found. + +#### `kei-refactor-engine` — refactor-plan generator (v0.13.0) + +Consumes `kei-conflict-scan` JSON, emits plan markdown + an auto-resolve review file (NOT a unified diff — v0.14.1 retraction). + +``` +kei-refactor-engine [--input |-] [--plan-only] + [--apply-to-branch ] + [--plan-out ] [--patch-out ] +``` + +`--patch-out` writes a markdown review (kept name for backward-compat). `requires_human_decision` items excluded from auto-resolve, listed in plain plan. + +#### `kei-graph-check` — post-refactor graph-integrity gate (v0.13.0) + +Resolves wikilinks + handoff refs + block refs across a memory-repo clone. Used as a gate BEFORE orchestrator commits the deep-sleep fork branch. + +``` +kei-graph-check --path [--after-diff ] [--json] +``` + +`--after-diff` treats any `+++ /dev/null` removal or `# removed:

` header as a phantom-removed file. Exit 2 on any broken reference. + +#### `kei-store` — memory-repo backend abstraction (v0.21) + +Unifies GitHub / Forgejo / Gitea / Filesystem / S3 behind one `MemoryStore` trait. Real `aws-sdk-s3` when built with `--features s3`; otherwise falls back to a local-manifest stub (still behind `KEI_STORE_ALLOW_S3_STUB=1`). + +``` +kei-store [--config ] + init [--url ] — write store-config.toml scaffold + read — fetch blob to stdout + write — upload local file + list

— list names under dir + branch — set active branch/prefix + commit --message — commit staged writes + push — push branch to remote + pull — pull branch from remote + status — print backend name +``` + +Config: `~/.claude/agents/_primitives/store-config.toml` (override with `--config`). S3 endpoint override: `KEI_STORE_S3_ENDPOINT` env or `s3.endpoint` TOML field. AWS default credential chain applies. + +#### `kei-artifact` — typed artifact handoff store (v0.16) + +JSON-Schema-validated blob store for inter-agent handoffs. Five built-in schemas: `spec`, `plan`, `patch`, `review`, `research`. Custom schemas registered at runtime auto-sync to the assembler via `schemas.json` export. + +``` +kei-artifact [--db ] + init — register 5 built-in schemas + register-schema --name --path + list-schemas + export-schemas [--path ] — refresh assembler's schemas.json + emit --schema --from --content — write an artifact + [--meta key=val]... [--parent ] + get [--format typed|raw] + list [--schema ] [--from ] [--since s] + validate — re-validate against schema + chain — walk parent-handoff chain +``` + +State: `$KEI_ARTIFACT_DB` or `~/.claude/artifacts/artifacts.sqlite`. + +#### `kei-auth` — HMAC-signed token issuer (v0.14.1 security fix) + +Issue / verify / revoke. Signing secret sourced from `KEI_AUTH_KEY` env var ONLY — the old `--key` CLI flag was removed in v0.14.1 because it leaked the secret through `/proc//cmdline` and shell history. + +``` +kei-auth [--db ] + issue --user --project

[--scope read|write|admin=read] [--ttl ] + verify + revoke +``` + +Key source (per RULE 0.8): `export KEI_AUTH_KEY="$(openssl rand -hex 32)"` or sourced from `~/.claude/secrets/.env`. State: `$KEI_AUTH_DB` or `~/.claude/auth/auth.sqlite`. + +#### `kei-router` — natural-language → tool-call JSON + +Rule-based NL router. Parses a short query into a structured tool-call JSON object. Used by the compose-solution skill as a first-pass dispatcher. + +``` +kei-router [--forward] +``` + +`--forward` adds `_forward=true` hinting remote-MCP forwarding on fallback. Prints pretty JSON to stdout. + +#### `kei-sage` — Obsidian-style knowledge vault + +SQLite-backed FTS5 knowledge store with BFS-related and PageRank. Can import an Obsidian vault wholesale. + +``` +kei-sage [--db ] + import — import .md files with frontmatter + search [--limit ] — FTS5 over title+content + related [--depth ] — BFS from a vault path/key + rank [--limit ] — PageRank over wikilinks + add --title [--content ] [--vault-path

] [--grade ] + edit [--title ] [--content ] [--grade ] + link [--edge-type ] +``` + +State: `$KEI_VAULT_DB` or `~/.claude/sage/vault.sqlite`. + +#### `kei-task` — task DAG CLI + +SQLite task graph with dependencies, milestones, FTS search. Dep types arbitrary (`blocks`, `relates`, ...). + +``` +kei-task [--db ] + create [--description <d>] [--priority low|medium|high=medium] + update <id> [--status <s>] [--title <t>] + add-dependency <from> <to> [--dep-type <t=blocks>] + graph — list all edges + dependency-chain <id> — topologically walk deps + search <query> [--limit <n=20>] + milestone <name> [--description <d>] + link-milestone <task-id> <milestone-id> +``` + +State: `$KEI_TASK_DB` or `~/.claude/task/task.sqlite`. + +#### `kei-chat-store` — chat session archive + +Session + message CRUD with token/cost accounting, FTS search, archive flag. + +``` +kei-chat-store [--db <path>] <subcommand> + start --project <p> [--title <t>] [--model <m>] + save --session-id <id> --role <user|assistant|system> <content> + [--tokens-in <n>] [--tokens-out <n>] [--cost <f>] + search <query> [--limit <n=20>] + archive <session-id> + stats — JSON summary +``` + +State: `$KEI_CHAT_DB` or `~/.claude/chat/chat.sqlite`. + +#### `kei-crossdomain` — cross-domain link graph + +Generic typed-edge graph for linking any URIs. Used to wire rules ↔ memory ↔ artefacts ↔ chats. + +``` +kei-crossdomain [--db <path>] <subcommand> + link <from> <to> [--edge-type <t=related>] [--weight <w=1.0>] [--evidence <g=E4>] + unlink <from> <to> [--edge-type <t=related>] + query <node> — all edges touching node + graph <start> [--depth <d=2>] — BFS + auto-link <node> — propose + add edges via heuristic + stats — count per edge type +``` + +State: `$KEI_CROSS_DB` or `~/.claude/cross/cross.sqlite`. + +#### `kei-search-core` — research pipeline scaffold + +Budget-bounded research runner. Current build ships a `StubFetcher` (real web fetch pluggable); runs the research-pipeline cubes end-to-end and persists results for markdown/JSON export. + +``` +kei-search-core [--db <path>] <subcommand> + run <prompt> [--budget <microusd=1_000_000>] — default budget = 1 USD + stop <id> + export <id> [--format md|json=md] +``` + +State: `$KEI_SEARCH_DB` or `~/.claude/search/research.sqlite`. + +#### `kei-content-store` — creative asset + prompt registry + +Register generated assets, prompts, campaigns; track prompt version history. + +``` +kei-content-store [--db <path>] <subcommand> + register-asset <title> [--file-path <p>] [--media-type <m>] [--provider <n>] + register-prompt <prompt-text> [--model <m>] [--prompt-type <t>] + create-campaign <name> [--description <d>] + attach-asset <campaign-id> <asset-id> + prompt-history <prompt-id> +``` + +State: `$KEI_CONTENT_DB` or `~/.claude/content/content.sqlite`. + +#### `kei-social-store` — people + organisation CRM + +Person/org registry with interaction log + relationship graph. + +``` +kei-social-store [--db <path>] <subcommand> + search-people <query> [--limit <n=20>] + add-person <name> [--email <e>] [--handle <h>] [--source <s=manual>] + add-org <name> [--org-type <t=company>] + log-interaction <person-id> <interaction-type> [--content <c>] + [--channel <ch=manual>] [--target-id <n>] + relationship-graph +``` + +State: `$KEI_SOCIAL_DB` or `~/.claude/social/social.sqlite`. + +#### `kei-curator` — edge decay + orphan pruning + +Operates on any of the `kei-sage` / `kei-crossdomain` SQLite databases. Periodic cleanup: exponential decay on edge weights, prune orphans. + +``` +kei-curator --db <path> <subcommand> + decay [--default-lambda <λ=0.05>] [--threshold <θ=0.1>] + prune-orphans +``` + +Requires an explicit `--db <path>` — there is no default. + +#### `keisei` — exobrain multi-client CLI (v0.19+) + +Entry-point that mounts a portable brain directory into one or more AI clients. See the dedicated deep-dive section below. + +### Shell primitives + +All 13 live under `_primitives/*.sh`. Installed with `chmod +x` at `~/.claude/agents/_primitives/`. Shell primitives are POSIX sh where feasible; two (`provision-hetzner`, `provision-vultr`, `harden-base`) use bash explicitly. + +#### `tomd.sh` — universal format → markdown + +Converts PDF / DOCX / DOC / HTML / PPTX / XLSX / CSV / images / source code to markdown. Used by the `tomd-preread` hook to auto-convert binary formats before Claude reads them. Deps: `pandoc`, `python3`, `jq`. Optional: `pymupdf4llm` (better PDF), `openpyxl` (XLSX tables), `tesseract` (OCR). + +#### `design-scrape.sh` — Playwright site scrape + +Scrapes a live URL into tokens + section map + desktop/mobile screenshots. + +``` +design-scrape <url> [--out <dir>] +``` + +Output: `<out>/desktop.png`, `<out>/mobile.png`, `<out>/tokens.json`, `<out>/structure.json`. Requires `npx` + Playwright chromium. + +#### `live-preview.sh` — dev-server wrapper + +Detects framework from `package.json`, runs `npm run dev`, writes PID to `.keisei/dev-server.pid` for the `site-wysiwyd-check` hook to discover. + +``` +live-preview start <dir> +live-preview stop [pid] — default: reads .keisei/dev-server.pid +live-preview status +``` + +#### `figma-tokens.sh` — Figma → tokens.json + +Fetches Figma Variables + Styles via REST API, emits a `tokens.json` consumable by `tokens-sync`. + +``` +FIGMA_TOKEN=figd_xxx figma-tokens <file-key> [--out <path=tokens.json>] +``` + +Token MUST come from env (RULE 0.8). File-key is the segment after `/design/` or `/file/` in the Figma URL. + +#### `frontend-inspect.sh` — project fingerprint + +Reports framework (Astro / Next / SvelteKit / Vite-React / static / unknown), styling (tailwind4 / tailwind3 / css-modules / plain), package manager, component count, whether tests exist. + +``` +frontend-inspect [<dir>] [--json] +``` + +#### `screenshot-decode.sh` — vision-API screenshot → structured description + +Posts a PNG + prompt to the Anthropic Messages API (claude-sonnet-4) and prints the text response. + +``` +ANTHROPIC_API_KEY=sk-ant-xxx screenshot-decode <png> [--prompt <text>] +``` + +Default prompt asks for token + layout + sections as JSON. API key MUST come from env (RULE 0.8). + +#### `metrics-scrape.sh` — Prometheus /metrics scraper + +Scrape + format / filter / alert-check. POSIX sh. + +``` +metrics-scrape <url> # table (default) +metrics-scrape <url> --format json # needs jq +metrics-scrape <url> --format alert-check --filter <re> --threshold <n> +metrics-scrape <url> --filter '^http_requests_total' +``` + +`alert-check` format exits non-zero if any filtered metric exceeds threshold. + +#### `log-ship.sh` — structured log tee + forward + +Pipes JSON-line logs from stdin to stdout and optionally forwards to Loki / Datadog / generic HTTP. Local tee ALWAYS happens, even if forward fails — observability must degrade gracefully. + +``` +cat log.jsonl | log-ship --target stdout +journalctl -o json | log-ship --target loki --endpoint http://loki:3100/loki/api/v1/push --label job=api +tail -f app.log | log-ship --target datadog --endpoint <dd-url> +cat log.jsonl | log-ship --target http --endpoint <url> +cat log.jsonl | log-ship --target stdout --validate +``` + +Env (no CLI token leak): `LOG_SHIP_DD_API_KEY`, `LOG_SHIP_BEARER`. + +#### `provision-hetzner.sh` — Hetzner Cloud provisioner + +Idempotent wrapper over `hcloud` CLI. Re-running `create <name>` on an existing server prints its IP and exits 0. + +``` +provision-hetzner create <name> [--type cx22|cax11] [--location fsn1] + [--image debian-12] [--ssh-key <id>] + [--firewall <name>] [--user-data <file>] +provision-hetzner status <name> +provision-hetzner destroy <name> [--force] +provision-hetzner list +``` + +Env (RULE 0.8): `HCLOUD_TOKEN`. + +#### `provision-vultr.sh` — Vultr provisioner + +Same shape as Hetzner. Uses `vultr-cli` v3. + +``` +provision-vultr create <label> [--plan vc2-1c-1gb] [--region ams] + [--os-id 2136] [--ssh-key <id>] + [--firewall <group-id>] [--user-data <file>] +provision-vultr status <label> +provision-vultr destroy <label> [--force] +provision-vultr list +``` + +Env (RULE 0.8): `VULTR_API_KEY`. Idempotency key is the human `label` field. + +#### `harden-base.sh` — post-provision baseline hardening + +Runs ON the target VPS. Ports generic patterns from Vortex `setup.sh` (apt, ssh drop-in, ufw, fail2ban, auditd, unattended-upgrades). Never reboots — surfaces `needrestart` hints only. + +``` +sudo bash harden-base.sh [--admin-user <name=keiadmin>] [--ssh-port <n=22>] + [--allow-port <n/proto>]... [--no-caddy] + [--no-reboot] [--skip apt|ssh|ufw|fail2ban|auditd|unattended] +``` + +Every step is test → configure → reload — re-running is safe. + +#### `kei-ci-lint.sh` — GitHub/Forgejo Actions linter + +7 rule suite (R1-R7): required fields, least-privilege permissions, OIDC-vs-long-lived-token, cache-hit hygiene, SHA pinning, deprecated-action flags, pwn-request pattern. + +``` +kei-ci-lint <file.yml> [file2.yml ...] +kei-ci-lint --dir .github/workflows [--warn] +kei-ci-lint --dir .forgejo/workflows +``` + +Requires `yq` v4+ (mikefarah/yq Go impl — not the Python one). + +#### `kei-docs-scaffold.sh` — auto-doc generator + +Detects project type (Cargo.toml / package.json / pyproject.toml / pubspec.yaml / go.mod / Package.swift / docker-compose), emits CLAUDE.md / DECISIONS.md / runbook / README. + +``` +kei-docs-scaffold [--type=all|claude|decisions|runbook|readme] + [--force] [--dry-run] [DIR] +``` + +Default: `--type=all`. Idempotent without `--force`. + +### Hooks + +All 10 kit-shipped hooks live under `hooks/*.sh`, get copied to `~/.claude/hooks/` on install. Every hook respects `KEI_DISABLED_HOOKS` and `KEI_HOOK_PROFILE` (see Runtime hook controls below). Silent fall-through on missing `jq` — never aborts a tool call system-wide. + +| Hook | Event | Severity | Bypass | +|---|---|---|---| +| `assemble-agents` | `PostToolUse:Edit\|Write` | advisory (rebuilds; never blocks) | — | +| `assemble-validate` | `PreToolUse:Bash` | **block** — exit 1 on `git commit` in `~/.claude` when manifests fail validation | — | +| `no-hand-edit-agents` | `PreToolUse:Edit\|Write` | **block** — exit 2 on generated `.md` edit attempts | `AGENT_MIGRATION=1` | +| `tomd-preread` | `PreToolUse:Read` | redirect — exit 2 with stderr pointing to cached `.md` | — | +| `agent-fork-logger` | `PreToolUse:Agent` | advisory (logs to `kei-ledger`; silent if absent) | — | +| `orchestrator-dirty-check` | `PreToolUse:Agent` | warn (stderr only) | `ORCHESTRATOR_META=1` or `ORCHESTRATOR_DIRTY_OK=1` | +| `site-wysiwyd-check` | `PostToolUse:Edit\|Write` | warn (stderr drift report) | — | +| `session-end-dump` | `Stop` | advisory (archives trace + calls `kei-memory ingest`) | — | +| `milestone-commit-hook` | `PostToolUse:Bash` | advisory (appends to audit-backlog on `feat:`/`refactor:`/merge) | — | +| `error-spike-detector` | `PostToolUse:*` | warn (stderr when ≥3 errors in 20-call window) | — | + +Details beyond the table: + +- **`assemble-agents`** — diff source: `_manifests/*.toml` rebuilds one agent; `_blocks/*.md` rebuilds ALL. Calls `_assembler/target/release/assemble --in-place`. +- **`assemble-validate`** — only fires when `git commit` runs inside `~/.claude`; validates every manifest; stderr-lists failures and exits 1 on any. +- **`no-hand-edit-agents`** — SSoT marker is `<!-- GENERATED by _assembler -->` on line 1. Files without the marker pass silently (legacy hand-authored agents). `AGENT_MIGRATION=1` overrides during migration only. +- **`tomd-preread`** — whitelist: `.docx`, `.doc`, `.xlsx`, `.pptx`, `.csv`. Cache key: basename + mtime + short path-hash (prevents collision between two same-basename files). Cache dir: `$KEISEI_TOMD_CACHE` or `/tmp/keisei-tomd-cache`. +- **`agent-fork-logger`** — extracts `subagent_type` + `prompt` + `isolation`; branch = `agent/<slug>-<ts>` when `isolation=worktree`, else `inline-<slug>-<ts>`. Spec-SHA = first 16 hex chars of SHA-256(prompt). +- **`orchestrator-dirty-check`** — runs `git status --porcelain` on repo root, stderr-warns with modified + untracked counts. +- **`site-wysiwyd-check`** — triggers on `.tsx` / `.vue` / `.svelte` / `.astro` / `.css` / `.html` / `.jsx` / `.ts`. Walks up to find `.keisei/dev-server.pid`; bails if no live server or no `.keisei/target.png`. +- **`session-end-dump`** — copies transcript JSONL to `~/.claude/memory/traces/<session_id>.jsonl`, calls `kei-memory ingest`, then best-effort calls `kei-sleep-sync.sh` (RULE 0.15, silent if sleep-sync not opted in). +- **`milestone-commit-hook`** — case-sensitive prefix match on `feat:`, `refactor:`, `merge` (avoids false-firing on `feature-docs.md`). +- **`error-spike-detector`** — rolling window in `~/.claude/memory/error-window.txt`; error-classifier = `is_error=true` OR message matches `/error:|failed|panic|denied/i`. + +### Skills (grouped) + +39 skills under `skills/<name>/SKILL.md`. Each is invoked as `/<skill-name>` inside Claude Code. Free-text is used only for intake fields; every other decision is a click via `AskUserQuestion`. + +<details> +<summary><b>Meta / project setup (4)</b></summary> + +| Skill | One-liner | +|---|---| +| `/compose-solution` | Meta-orchestrator — converts a free-text task into the right artefact (agent / skill / hook / rule / block) by composing existing primitives. Enriches `_blocks/` over time. | +| `/new-project` | 4-phase bootstrap — intake, fork skeleton (branch + ledger row + sub-agent spawn), parallel execution with progress aggregation, per-branch merge ceremony. RULE 0.12 at project scale. | +| `/new-agent` | Interactive 6-question wizard that builds a project-specialist manifest and its `.md`. | +| `/onboard` | Scan a project (or scope) and propose agents + hooks + primitives based on detected stack. Three modes: Full auto, Step-by-step, Full manual. | + +</details> + +<details> +<summary><b>Design / frontend (18)</b></summary> + +| Skill | One-liner | +|---|---| +| `/site-create` | End-to-end site pipeline — intake → design → sections → WYSIWYD mock-render loop → audits → preview → deploy. The verify gate HARD-BLOCKS deploy of unlocked sections. | +| `/site-builder` | Build a site from block recipes. WYSIWYD invariant via `mock-render`. | +| `/site-teardown` | Deconstruct any live site into a reusable recipe — HTML, CSS, JS, tokens, animations. | +| `/landing-page` | Orchestrates design + copy + assets + animations + SEO for a landing page. Supports recipes (apple-product, saas, portfolio, ecommerce). | +| `/design-system` | Build a design system — tokens, base components, Tailwind config, dark mode, docs. | +| `/ui-component` | Build a UI component — API design, variants, a11y, animations, tests. | +| `/form-builder` | Multi-step forms — Zod validation, Turnstile anti-spam, serverless backends, upload, progressive enhancement. | +| `/scroll-animation` | Scroll-driven animation — GSAP ScrollTrigger, CSS scroll-timeline, parallax, pin/scrub. | +| `/motion-design` | Motion design — page transitions, element animations, View Transitions API, Rive/Lottie, a11y. | +| `/web-effects` | Visual web effects — WebGL shaders, particles, noise/grain, displacement maps, CSS-only. | +| `/web-assets` | Image / font / video optimization — AVIF, responsive srcset, font subsetting, Sharp.js. | +| `/figma-to-code` | Figma design → code — screenshot, context, tokens, responsive implementation. | +| `/frontend-design` | Anti-AI-slop aesthetic philosophy — typography pairing, color theory, spatial composition, motion guidelines, design archetypes. | +| `/responsive-audit` | 6-breakpoint audit — layout, touch targets, overflow, images. | +| `/a11y-audit` | WCAG 2.2 AA compliance — contrast, keyboard nav, screen reader, prefers-reduced-motion. | +| `/perf-audit` | Perf baseline → profile → top-3 bottlenecks → fix → remeasure. | +| `/seo-audit` | Technical + content SEO via WebFetch + code inspection. | +| `/web-deploy` | Cloudflare Pages / Vercel / edge functions / caching / Core Web Vitals / CI/CD / DNS. | + +</details> + +<details> +<summary><b>Infra / ops (4)</b></summary> + +| Skill | One-liner | +|---|---| +| `/vm-provision` | End-to-end VPS — provider → plan → provision → harden → `ssh-check` + `firewall-diff` hard-gate → handoff. Stops if either verification fails. | +| `/ci-scaffold` | Production CI/CD plan — platform (GitHub vs Forgejo), build matrix, OIDC-vs-token, release automation, security gate. Emits workflow YAML + runs `kei-ci-lint`. | +| `/observability-setup` | Logs + metrics + traces triad on an existing service — instrumentation → scrape+ship → dashboard → alerts. | +| `/auth-setup` | Production auth/IAM plan — user flows, IdPs, session strategy, authorization model, threat mitigations. Never writes secret values. | + +</details> + +<details> +<summary><b>API / schema / docs / tests (5)</b></summary> + +| Skill | One-liner | +|---|---| +| `/api-design` | API design — style (REST / GraphQL / tRPC / gRPC), resource model, OpenAPI 3.1 or GraphQL SDL, versioning, rate-limit + auth handoff, codegen. | +| `/schema-design` | Relational schema → migrations → `kei-migrate` apply. PG / SQLite / MySQL autodetect. | +| `/docs-scaffold` | 5-phase — detect project type, audit existing docs, generate CLAUDE.md / DECISIONS.md / runbook / README / diagrams / CHANGELOG. | +| `/test-matrix` | Beyond-unit test stack — fuzzing, property-based, load, E2E, mutation. Composes right mix per language × critical path × CI target. | +| `/test-gen` | Generate tests for untested code — happy path, edge cases, error handling. | + +</details> + +<details> +<summary><b>Retro / audit / research (5)</b></summary> + +| Skill | One-liner | +|---|---| +| `/self-audit` | RULE 0.14 session retrospective triage — runs `kei-memory analyze + patterns`, routes findings to `/escalate-recurrence` / `/debug-deep` / audit-backlog. | +| `/pr-review` | PR review — Constructor Pattern awareness, security, SSoT check. | +| `/refactor` | Refactor with behavior preservation — checkpoint, extract, test, audit. | +| `/debug-deep` | 5-phase RCA using multi-agent analysis + error pattern matching. | +| `/research` | Deep research via parallel agents + web search + cross-referencing. | + +</details> + +<details> +<summary><b>Sleep layer + runtime (3)</b></summary> + +| Skill | One-liner | +|---|---| +| `/sleep-setup` | RULE 0.15 one-time wizard — local-only / remote-only / hybrid, trigger time, memory-repo init, SSH deploy key, `/schedule create` + cron snippet. | +| `/sleep-on-it` | v0.12 incubation — defer a question to the nightly remote agent. Up to 5 tasks per night (15 min each). Priority maps to budget. | +| `/hooks-control` | v0.15.1 click-only runtime enable/disable — emits shell `export` / `unset` for user to paste. Does NOT execute anything itself. | + +</details> + +### `keisei` CLI — exobrain entry point + +`keisei` is the only Rust primitive that mounts state into OTHER tools' configs. It reads a portable brain directory (see brain layout above) and writes `mcpServers.keisei` entries into each detected AI client's config file. + +**Five subcommands** (every flag listed is the actual clap arg surface in `_primitives/_rust/keisei/src/main.rs`): + +``` +keisei attach <brain-path> [--scope user|project] +keisei mount <brain-path> +keisei detach +keisei status +keisei list-adapters +``` + +**Flag matrix:** + +| Subcommand | Required args | Flags | Notes | +|---|---|---|---| +| `attach` | `<brain-path>` (dir with `manifest.toml`) | `--scope user\|project` (default `user`) | Attaches to the **first detected** client. Adapters that don't support requested scope error out cleanly. | +| `mount` | `<brain-path>` | — | Auto-attach to EVERY detected AI client. Always user-scope (host-wide fan-out by design). | +| `detach` | — | — | Removes `mcpServers.keisei` from every client in the marker; preserves the user's other MCP entries. Deletes marker. | +| `status` | — | — | Brain name + path + attach timestamp + per-client config path + health (brain root is a dir? `mcp_server` binary exists?). | +| `list-adapters` | — | — | Tabular view: `name / detected / config_path / scopes`. | + +**Supported adapters (v0.21):** Claude Code, Cursor, Continue, Zed. Claude Code and Cursor advertise both `user` + `project` scope. Continue and Zed are user-only. + +**Exit codes:** +- `0` — success +- `1` — error (brain validation fail, no adapter detected, NameConflict, scope unsupported, IO) + +No separate exit code for "config invalid" — all errors funnel through exit 1 with the specific message printed to stderr. (The task brief mentioned exit 2 for config-invalid, but the current main.rs only returns `ExitCode::SUCCESS` or `ExitCode::from(1)`.) + +**Env vars:** + +| Var | Purpose | +|---|---| +| `KEISEI_HOME` | Test hook — overrides `$HOME` for marker-file resolution and adapter config-path lookup | +| `KEI_STORE_S3_ENDPOINT` | Custom S3-compatible endpoint (R2 / MinIO / Wasabi) — consumed by `kei-store` when built with `--features s3` | +| `KEI_STORE_ALLOW_S3_STUB` | Set to `1` to permit the local-manifest S3 stub when the real `s3` feature isn't built | +| `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` / `AWS_REGION` | Standard AWS credential chain — consumed via `aws-sdk-s3` default resolver | +| `KEI_AUTH_KEY` | HMAC secret for `kei-auth` (NOT a CLI flag since v0.14.1) | + +**Marker SSoT:** `~/.keisei/attached.toml` (v0.21+). Schema v3 entries have a `scope` field. Legacy `~/.claude/keisei-attached.toml` auto-migrates on first read (one-shot: legacy deleted, new location written, stderr notice printed). + +**Security hardening (v0.19):** +- Brain `mcp_server` path MUST be relative + inside the brain root (rejects `/usr/bin/curl`, `../../etc/shadow`, Windows-style `..\..\`) +- Brain `name` matches `^[a-z][a-z0-9_-]{0,63}$` +- Brain root rejected if it's a symlink (blocks USB → `$HOME` pivot) +- Adapters refuse to clobber existing `mcpServers.<name>` entries — explicit `NameConflict` error, no silent overwrite +- All config writes go through `fsx::write_atomic_json` (Windows-safe via `tempfile::NamedTempFile::persist`) + ## Runtime hook controls Every kit-shipped hook (v0.14.2+) honours two env vars so you can silence noise or isolate a failure without editing `~/.claude/settings.json`: