docs(readme): split 89 KB monolith into hero-pitch + 6 docs/ files
README down from 89 KB to 7.8 KB (11x reduction, target was 10-15 KB). Visitor-facing README now loads in one screen — hero + 3 killer features + what-it-solves + quick install + docs index. Extracted 6 new files under docs/: - INSTALL.md (15 KB) — prerequisites, profiles, interactive install, MCP binary, keisei CLI intro, runtime hook controls, what-you-get table - REFERENCE.md (35 KB) — every one of 25 Rust primitives + 13 shell primitives + 10 hooks + 39 skills with actual CLI surface (clap flags, exit codes, env vars, state paths), keisei CLI deep-dive, 12 pipelines - ARCHITECTURE.md (11 KB) — build pipeline, creating-a-new-agent, adding custom blocks/manifests, agents overview, cross-tool bridges, meta-composer, regen counts, workflow-file editing protocol - SLEEP-LAYER.md (11 KB) — three-phase nightly cycle diagram, session self-audit (RULE 0.14), Cloud REM sync, sleep-on-it incubation, deep-sleep NREM consolidation with 4-primitive pipeline + example - SECURITY.md (7.6 KB) — threat surface table + 8 mitigations in detail (memory-repo privacy, secrets-guard patterns, supply-chain SHA pinning, S3 SSRF, brain path/name validation, exFAT warning, battle matrix) - WHY.md (3.6 KB) — full 'From the author' manifesto restored from git history (pre-1f3aaca product pivot). Medium/dev.to-friendly for virality, separate from the product README New docs cross-link each other + README has docs index in tail. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Parfii-bot
parent
b55c3d6ef3
commit
ce9ba61ee0
7 changed files with 1409 additions and 1255 deletions
142
docs/ARCHITECTURE.md
Normal file
142
docs/ARCHITECTURE.md
Normal file
|
|
@ -0,0 +1,142 @@
|
|||
# Architecture
|
||||
|
||||
How agents, blocks, manifests, the assembler, and cross-tool bridges fit together.
|
||||
|
||||
---
|
||||
|
||||
## The build pipeline
|
||||
|
||||
```
|
||||
Manifest (_manifests/<name>.toml) <-- source of truth
|
||||
|
|
||||
| [assembler/src/*.rs] <-- Rust binary
|
||||
v
|
||||
Generated agent (.claude/agents/<name>.md) <-- regenerated, never hand-edited
|
||||
^
|
||||
| [hook: assemble-agents]
|
||||
Block edit (_blocks/<block>.md) <-- triggers rebuild of ALL agents
|
||||
```
|
||||
|
||||
10 hooks enforce the pipeline (7 pipeline + 3 session-audit):
|
||||
|
||||
- **`assemble-agents`** (PostToolUse, Write/Edit) — rebuilds the affected agent(s) whenever a manifest or a block changes. No manual rebuild needed.
|
||||
- **`assemble-validate`** (PreToolUse, Bash) — blocks `git commit` inside `~/.claude` if any manifest fails validation. Keeps the repo in a buildable state at all times.
|
||||
- **`no-hand-edit-agents`** (PreToolUse, Edit/Write) — refuses edits to any `.md` under `~/.claude/agents/` that starts with the `<!-- GENERATED -->` marker, pointing you at the manifest instead. Override with `AGENT_MIGRATION=1` for emergencies only.
|
||||
- **`tomd-preread`** (PreToolUse, Read) — auto-converts opaque binary formats (`.docx`, `.doc`, `.xlsx`, `.pptx`, `.csv`) to markdown via the `tomd` primitive and redirects Claude to read the cached `.md` instead.
|
||||
- **`agent-fork-logger`** (PreToolUse, Agent) — RULE 0.12 advisory: logs every Agent subagent invocation to the `kei-ledger` SQLite DB so the orchestrator can validate the fork bundle. Never blocks; silent no-op if `kei-ledger` is absent.
|
||||
- **`orchestrator-dirty-check`** (PreToolUse, Agent) — RULE 0.13 advisory: stderr-warns when `git status --porcelain` of the current repo is non-empty before spawning a sub-agent, so orchestrators don't compound uncommitted output across parallel agents. Never blocks; bypass with `ORCHESTRATOR_DIRTY_OK=1` (per-call) or `ORCHESTRATOR_META=1` (meta-orchestrator).
|
||||
- **`site-wysiwyd-check`** (PostToolUse, Edit/Write) — on frontend-source edits (`.tsx`, `.vue`, `.svelte`, `.astro`, `.css`, `.html`, `.jsx`, `.ts`) in a project with a live dev server (`.keisei/dev-server.pid`), takes a Playwright screenshot via `mock-render` and diffs against `.keisei/target.png` via `visual-diff`. Advisory-only — drift is reported to stderr, never blocks.
|
||||
- **`session-end-dump`** (Stop event) — RULE 0.14 self-audit: archives the session JSONL trace and ingests it into `kei-memory`.
|
||||
- **`milestone-commit-hook`** (PostToolUse, Bash) — RULE 0.14 self-audit: appends a one-line session summary to `~/.claude/memory/audit-backlog.md` on every `feat:`/`refactor:`/merge commit.
|
||||
- **`error-spike-detector`** (PostToolUse, any tool) — RULE 0.14 self-audit: tags + logs the pattern when 3+ errors occur within the last 20 tool calls.
|
||||
|
||||
## Creating a new agent
|
||||
|
||||
Run the wizard in Claude Code:
|
||||
|
||||
```
|
||||
/new-agent
|
||||
```
|
||||
|
||||
You'll be asked (via multiple option-picker batches, not free-text) — each batch groups several click-only questions into a single `AskUserQuestion` call:
|
||||
|
||||
1. Project stack (Rust CLI / axum / SwiftUI / Flutter / FastAPI / Next.js / React-Vite / Vue-Nuxt / SvelteKit / Astro / Go / Embedded / Python ML)
|
||||
2. Deploy target (local-only / EC2 / Cloudflare / Modal / Docker / none)
|
||||
3. Uses paid APIs? (Yes / No)
|
||||
4. Contains ML? (Yes / No)
|
||||
5. Has credentials? (Yes / No)
|
||||
6. Uses scrapers? (None / Free-tier / Paid tier)
|
||||
|
||||
Then one free-text prompt for slug + description + path + gotchas. The wizard composes the manifest, validates it, assembles the `.md`, and prints a two-step git-commit command you can run or edit first.
|
||||
|
||||
## Adding custom blocks
|
||||
|
||||
Blocks are plain markdown in `~/.claude/agents/_blocks/`. To add one:
|
||||
|
||||
1. `touch ~/.claude/agents/_blocks/stack-mystack.md` and write the block.
|
||||
2. Reference it in a manifest's `blocks = [...]` list.
|
||||
3. The PostToolUse hook rebuilds the affected agent(s) automatically.
|
||||
|
||||
Blocks should be 10-50 lines, single-concern, and readable in isolation. If a block exceeds ~60 lines, split it into two.
|
||||
|
||||
## Adding custom manifests
|
||||
|
||||
Copy `_templates/specialist.toml.template` and fill the placeholders, OR run `/new-agent` and answer the wizard. Either way, the assembler validates the manifest and generates the `.md` on write.
|
||||
|
||||
## Agents overview
|
||||
|
||||
All kit agents are namespaced under `kei-*` so they won't collide with your own agents (e.g. your personal `validator` or `critic`) living in `~/.claude/agents/`.
|
||||
|
||||
| Agent | Role |
|
||||
|---|---|
|
||||
| `kei-code-implementer` | Write production code, Constructor Pattern enforced, Test-First discipline |
|
||||
| `kei-infra-implementer` | Deploy scripts, CI/CD, secrets management, cost-aware paid infra |
|
||||
| `kei-ml-implementer` | Training scripts, inference code, Modal jobs, exact param counts |
|
||||
| `kei-critic` | Read-only anti-pattern / bug / security / perf / debt finder |
|
||||
| `kei-validator` | Fact-checker; verifies API existence, version compat, citations, doc claims |
|
||||
| `kei-security-auditor` | Risk-classified security audit with variant analysis + supply chain check |
|
||||
| `kei-architect` | Read-only structural analysis; dep graph, patterns, coupling |
|
||||
| `kei-researcher` | Generic web + codebase research, evidence-graded findings |
|
||||
| `kei-ml-researcher` | ML literature, benchmarks, reproducibility, tooling-reuse search |
|
||||
| `kei-cost-guardian` | Pre-launch GO/NO-GO for paid compute (Modal, AWS, fal.ai, Apify, etc.) |
|
||||
| `kei-modal-runner` | Modal compute orchestrator with KILL GUARD (never stops running jobs) |
|
||||
| `kei-fal-ai-runner` | fal.ai image/video/3D generation expert |
|
||||
|
||||
## Cross-tool bridges
|
||||
|
||||
KeiSeiKit ships 11 verified tool-bridge templates under `_bridges/`. Render them into any project and the same Constructor-Pattern ruleset is visible to every AI coding tool you use — no drift, one source of truth.
|
||||
|
||||
**Tools covered:**
|
||||
|
||||
| Tool | Output file |
|
||||
|---|---|
|
||||
| Cursor (legacy) | `.cursorrules` |
|
||||
| Cursor (modern MDC) | `.cursor/rules/main.mdc` |
|
||||
| Codex CLI / Warp / Zed / Antigravity fallback | `AGENTS.md` |
|
||||
| GitHub Copilot | `.github/copilot-instructions.md` |
|
||||
| Windsurf | `.windsurf/rules/main.md` |
|
||||
| JetBrains Junie | `.junie/guidelines.md` |
|
||||
| Continue.dev | `.continue/rules/main.md` |
|
||||
| Google Antigravity / Gemini CLI | `GEMINI.md` |
|
||||
| Aider | `CONVENTIONS.md` + `.aider.conf.yml` |
|
||||
| Replit Agent | `replit.md` |
|
||||
|
||||
**Three ways to generate:**
|
||||
|
||||
1. **At install time** — `./install.sh --with-bridges` renders all 11 into `$PWD` after the normal install completes. Skipped if `$PWD` is the KeiSeiKit repo itself.
|
||||
2. **From the `/new-agent` wizard** — Phase 8 asks click-only whether to generate all 11, just `AGENTS.md`, or skip.
|
||||
3. **Manually, any time** — `~/.claude/agents/_bridges/emit.sh <project-dir>` (the install copies `_bridges/` into your agent fleet dir). Add `--only <output-path>` to restrict to a single file.
|
||||
|
||||
All paths are idempotent: existing bridge files in the project are skipped, never overwritten. See `_bridges/README.md` for the full template→output-path table.
|
||||
|
||||
## Meta-composer
|
||||
|
||||
`/compose-solution` is the meta-creator: tell it what you want to solve in one free-text paragraph, it decomposes the task, greps existing blocks / skills / manifests / primitives / bridges for prior art, proposes a minimal math-first architecture, and assembles the right artefact — agent, skill, hook, rule, block, or pipeline invocation. Every decision except the intake is a click (option-picker), never free-text.
|
||||
|
||||
Example: "I want a hook that blocks `rm -rf ~/` in any Bash call" → Phase 2 decomposes into (pattern-match, severity, event, wiki entry) → Phase 3 greps `hooks/`, `_blocks/`, `_primitives/` for prior art → Phase 5 proposes `hook = PreToolUse:Bash + pattern + exit 2` → Phase 7 hands off to `/escalate-recurrence` with severity and event pre-filled.
|
||||
|
||||
Phase 6 is the feedback loop: when a component has no prior art, the skill drafts a new `_blocks/<slug>.md` and — on your click — persists it. Next time `/compose-solution` (or `/new-agent`) runs, that block is discoverable. Every session leaves the kit a little smarter; the report prints `_blocks/` count before → after so the growth is visible.
|
||||
|
||||
See `skills/compose-solution/SKILL.md` and its phase files (`phase-1-intake.md` through `phase-7-assemble.md`) for the full 7-phase pipeline.
|
||||
|
||||
## Regenerating counts
|
||||
|
||||
Every number in the README / INSTALL.md (crates / skills / hooks / blocks / primitives / profile sizes) is wrapped in an HTML-comment marker — `<!-- count:NAME -->24<!-- /count:NAME -->` — and regenerated from sources of truth (`_primitives/MANIFEST.toml`, `_primitives/_rust/Cargo.toml`, filesystem walks). No more drift when a primitive or skill is added.
|
||||
|
||||
```bash
|
||||
./scripts/regen-counts.sh # rewrite README.md in place
|
||||
./scripts/regen-counts.sh --check # exit 1 if drift detected (no writes)
|
||||
```
|
||||
|
||||
Pre-commit gate: `scripts/precommit-counts-check.sh` — wire it into your hook manager (or symlink into `.git/hooks/pre-commit`) to block commits when README counts drift from the sources.
|
||||
|
||||
## Workflow-file editing protocol
|
||||
|
||||
Every `.github/workflows/*.yml` edit is defended by three gates. The v0.20.1 incident (a real-but-wrong-semantic SHA pin on `dtolnay/rust-toolchain` broke CI for 30 minutes before discovery) motivated formalising them.
|
||||
|
||||
- **`scripts/lint-workflows.sh`** — runs [`actionlint`](https://github.com/rhysd/actionlint) over every workflow file. Catches syntax errors, expression typos, dead `if:` branches, and shell-injection risks. If the binary isn't on PATH, the script prints an install hint and exits 0 (advisory). Install with `bash scripts/install-actionlint.sh` or `brew install actionlint`.
|
||||
- **`scripts/validate-workflow-shas.sh`** — extracts every `uses: <repo>@<sha40>` pin from `.github/workflows/*.yml` + `.github/dependabot.yml` and runs `git ls-remote https://github.com/<repo>.git <sha>`. A fabricated or force-pushed-out-of-existence SHA exits 1 with `SHA MISSING:`. Network errors are soft (`[UNVERIFIED]`). Tag refs like `@v4` or `@stable` are skipped (policy decision). Add trailing comment `# validate-workflow-shas: skip=<reason>` on a line to intentionally skip it.
|
||||
- **CI job `workflow-lint`** — runs both scripts on every push and PR. Finishes in well under 30 s.
|
||||
- **Optional pre-commit hook:** `ln -sf ../../scripts/pre-commit-workflow-lint.sh .git/hooks/pre-commit` — runs the two scripts only when a workflow file is staged.
|
||||
|
||||
SHA-pinning third-party actions defeats tag re-point attacks (CVE-2025-30066 class), but only if the SHA you wrote is real AND means what you think it means. `actionlint` catches the first class of mistake; `validate-workflow-shas.sh` catches the second. Together they close the window between local edit and CI-fail.
|
||||
224
docs/INSTALL.md
Normal file
224
docs/INSTALL.md
Normal file
|
|
@ -0,0 +1,224 @@
|
|||
# Installation
|
||||
|
||||
Complete install guide. Quick-start lives in the main [README](../README.md#install).
|
||||
|
||||
---
|
||||
|
||||
## Two install paths
|
||||
|
||||
| Path | Command | Best for |
|
||||
|---|---|---|
|
||||
| **Plugin** (v0.16+, recommended on Claude Code 2.1+) | `/plugin marketplace add KeiSei84/KeiSeiKit` then `/plugin install keisei@keisei-marketplace` | Agents + skills + hooks + MCP. Zero cargo build. See [PLUGIN.md](../PLUGIN.md). |
|
||||
| **Classic** `./install.sh` | Below | Full kit incl. 25 Rust primitives + 13 shell primitives. Required for `ops` / `dev` / `full` profiles. |
|
||||
|
||||
## Prerequisites
|
||||
|
||||
**Hard** (needed for every install, regardless of profile):
|
||||
|
||||
- **Rust** (stable toolchain) — the assembler Cargo workspace is always built
|
||||
- **jq** — used by the shell hooks for JSON parsing (`brew install jq` / `apt install jq`)
|
||||
- **Claude Code** — the agents, hooks, and skills target Claude Code's agent / skill / hook surface
|
||||
|
||||
**Soft** (only needed if the chosen profile pulls the primitive in):
|
||||
|
||||
- **pandoc** — `tomd` uses it for `.docx` / `.pptx` / `.html` (needed for `core` / `full` profile)
|
||||
- **Node + Playwright** — for the 3 browser-driven frontend primitives `design-scrape`, `live-preview`, `mock-render` (`frontend` / `full` profile); install with `npm i -g playwright && playwright install chromium`
|
||||
- **sqlite3 CLI** — optional for manual DB inspection of `kei-ledger` / `kei-migrate` (their binaries embed SQLite via `rusqlite`; `ops` / `dev` profile)
|
||||
- **hcloud / vultr-cli** — wrapped by `provision-hetzner` / `provision-vultr` (`ops` profile)
|
||||
- **yq v4** (mikefarah/yq Go impl) — required by `kei-ci-lint` (`dev` profile)
|
||||
|
||||
`install.sh` checks only the deps relevant to the selected profile and soft-warns once per missing tool.
|
||||
|
||||
## Classic install
|
||||
|
||||
```bash
|
||||
git clone <your-fork-of-this-repo> KeiSeiKit
|
||||
cd KeiSeiKit
|
||||
./install.sh # profile=minimal (default, no primitives)
|
||||
```
|
||||
|
||||
`install.sh` is idempotent. It:
|
||||
|
||||
1. Creates `~/.claude/agents/{_blocks,_manifests,_primitives,_bridges,_templates,_assembler,_generated}`, `~/.claude/hooks`, `~/.claude/skills`
|
||||
2. Copies all blocks + bridges (overwrites — these are SSoT from the kit)
|
||||
3. Copies primitives ONLY for the selected profile (default: `minimal` = none). Tracks installed set in `~/.claude/agents/_primitives/.installed`.
|
||||
4. Copies generic manifests (skips if you already have a manifest with that name)
|
||||
5. Builds the Rust assembler (`cargo build --release` in `_assembler/`)
|
||||
6. If any Rust primitive is in the selected profile: writes a scoped workspace `Cargo.toml` listing ONLY the installed crates, then `cargo build --release`
|
||||
7. Generates agent `.md` files in-place with `AGENT_ROOT=~/.claude/agents assemble --in-place`
|
||||
8. Copies the 10 hooks and 39 skills
|
||||
|
||||
After install, the only remaining step is merging `settings-snippet.json` into your `~/.claude/settings.json` to activate the hooks. You can do this automatically with `./install.sh --activate-hooks` or answer `y` at the end-of-install TTY prompt.
|
||||
|
||||
### Interactive install
|
||||
|
||||
Run `./install.sh` with no profile flag on a TTY and you get a menu:
|
||||
|
||||
- `whiptail` or `dialog` detected → curses-style TUI (radiolist for profile, checklist for custom)
|
||||
- neither available → plain-text numbered picker (`1-7` + a `custom` option)
|
||||
|
||||
After the profile is chosen, an **Install Plan** screen summarizes what will be copied, which soft-deps are present (`jq`, `pandoc`, `playwright`, `cargo`, `hcloud`, `vultr-cli`, `yq`, `sqlite3`, `curl`), and the rough time + disk footprint — then asks `Proceed? [Y/n]`. Pass `--yes` to skip the confirm screen (the menu still runs). Pass `--no-execute` to parse menu + confirm and exit without copying anything (useful for dry-run). The menu is **skipped automatically** when any selection flag is passed (`--profile`, `--add`, `--remove`, `--list`) or when stdin/stdout is not a TTY (CI runs default to `minimal` exactly as before).
|
||||
|
||||
## Install profiles
|
||||
|
||||
By default `./install.sh` is **minimal** — agents + hooks + skills + bridges, no primitives. Fastest (~5s) and zero Rust compile for primitives. You opt into primitives via `--profile=<name>` or one-at-a-time via `--add=<name>`.
|
||||
|
||||
| Profile | Primitives added | Install time | Disk (approx) |
|
||||
|---|---|---|---|
|
||||
| `minimal` (default) | none | ~5s | ~2 MB |
|
||||
| `core` | `tomd` | ~5s | ~2 MB |
|
||||
| `frontend` | 8 site tools: `mock-render`, `visual-diff`, `tokens-sync`, `design-scrape`, `live-preview`, `figma-tokens`, `frontend-inspect`, `screenshot-decode` | ~60s | ~80 MB |
|
||||
| `ops` | 8 infra tools: `kei-ledger`, `ssh-check`, `firewall-diff`, `provision-hetzner`, `provision-vultr`, `harden-base`, `metrics-scrape`, `log-ship` | ~90s | ~50 MB |
|
||||
| `dev` | 10 dev tools: `kei-migrate`, `kei-changelog`, `kei-ci-lint`, `kei-docs-scaffold`, `kei-memory`, `kei-conflict-scan`, `kei-refactor-engine`, `kei-graph-check`, `kei-store`, `kei-artifact` | ~60s | ~40 MB |
|
||||
| `full` | everything (38 primitives) | ~5 min | ~200 MB |
|
||||
|
||||
Examples:
|
||||
|
||||
```bash
|
||||
./install.sh # minimal (no primitives)
|
||||
./install.sh --profile=frontend # minimal + 8 site tools
|
||||
./install.sh --profile=full # everything (old default behaviour)
|
||||
./install.sh --add=kei-ledger # add a single primitive on top of current install
|
||||
./install.sh --add=kei-ledger,ssh-check
|
||||
./install.sh --add=ops # a profile name works too — unions its members in
|
||||
./install.sh --list # show each primitive: name | kind | installed? | description
|
||||
./install.sh --remove=kei-migrate # remove one (rebuilds scoped rust workspace if needed)
|
||||
```
|
||||
|
||||
Profile resolution lives in `_primitives/MANIFEST.toml` — one `[primitive.<name>]` entry per primitive plus a `[profile]` block. Edit the manifest to define new profiles without touching `install.sh`.
|
||||
|
||||
> **Migrating from a full install:** if you're re-running `install.sh` after an earlier version that installed all primitives unconditionally, the new default (`minimal`) will REMOVE them. To preserve the old behaviour explicitly, pass `--profile=full`.
|
||||
|
||||
> **Re-install disclaimer:** `install.sh` is idempotent for clean state but **overwrites kit-owned `_blocks/`, `_primitives/`, `_bridges/`, `_templates/`, `_assembler/`, `hooks/`, and `skills/` on re-run** — local modifications under those directories are backed up to `<dir>.bak-TIMESTAMP/` (or, for shared hook files, to `<file>.bak-TIMESTAMP`). User-owned `_manifests/*.toml` are never overwritten.
|
||||
|
||||
## MCP server binary (zero-install path, v0.18)
|
||||
|
||||
From v0.18 each GitHub release ships a **single static binary** of the `@keisei/mcp-server` package for five platforms — no Node, no `npm install`. Drop the binary anywhere (USB stick, S3 bucket, Downloads folder) and run it. This is Phase 1 of the "exobrain" distribution goal: any MCP-capable client can mount KeiSeiKit from read-only media.
|
||||
|
||||
| Platform | Asset name |
|
||||
|---|---|
|
||||
| Linux x64 | `kei-mcp-server-linux-x64` |
|
||||
| Linux arm64 | `kei-mcp-server-linux-arm64` |
|
||||
| macOS x64 | `kei-mcp-server-darwin-x64` |
|
||||
| macOS arm64 | `kei-mcp-server-darwin-arm64` |
|
||||
| Windows x64 | `kei-mcp-server-windows-x64.exe` |
|
||||
|
||||
```bash
|
||||
# Linux / macOS
|
||||
curl -L -o kei-mcp-server \
|
||||
https://github.com/<your-fork>/KeiSeiKit/releases/latest/download/kei-mcp-server-darwin-arm64
|
||||
chmod +x kei-mcp-server
|
||||
# macOS only — clear Gatekeeper quarantine on the downloaded binary:
|
||||
xattr -d com.apple.quarantine ./kei-mcp-server 2>/dev/null || true
|
||||
./kei-mcp-server --stdio
|
||||
```
|
||||
|
||||
Every asset has a matching `<name>.sha256` for integrity verification. Build details and local cross-compile recipes: `_ts_packages/packages/mcp-server/BUILD.md`.
|
||||
|
||||
If you drop the binary at `~/.claude/agents/_primitives/_rust/target/release/kei-mcp-server-<os>-<arch>[.exe]` (the same layout `install.sh` uses for Rust primitives), re-running `install.sh` will detect it and skip any bun/npm build step. Set `KEI_SKIP_MCP_BUILD=1` to force-skip that step regardless of detection.
|
||||
|
||||
## The `keisei` CLI — multi-client exobrain mount (v0.19+)
|
||||
|
||||
The `keisei` Rust crate is the entry-point that turns a **brain directory** (portable, filesystem-backed AI state — memory + artifacts + manifests + MCP server binaries) into an attachment on one or more AI clients in a single command. Brain layout:
|
||||
|
||||
```
|
||||
<brain-root>/
|
||||
├── manifest.toml # schema_version, brain name, path pointers
|
||||
├── memory/ # kei-memory git store (session traces, audit backlog)
|
||||
├── artifacts/ # kei-artifact SQLite (typed handoff bundles)
|
||||
├── manifests/ # user persona TOML library
|
||||
└── bin/
|
||||
├── kei-mcp-server-darwin-arm64
|
||||
├── kei-mcp-server-darwin-x64
|
||||
├── kei-mcp-server-linux-x64
|
||||
├── kei-mcp-server-linux-arm64
|
||||
└── kei-mcp-server-windows-x64.exe
|
||||
```
|
||||
|
||||
**`manifest.toml` — schema v2 (recommended, v0.20+)** dispatches to the right binary for the host at attach time:
|
||||
|
||||
```toml
|
||||
[brain]
|
||||
schema_version = 2
|
||||
name = "my-brain"
|
||||
created = "2026-04-22T00:00:00Z"
|
||||
|
||||
[paths.mcp_server]
|
||||
darwin-arm64 = "bin/kei-mcp-server-darwin-arm64"
|
||||
darwin-x64 = "bin/kei-mcp-server-darwin-x64"
|
||||
linux-x64 = "bin/kei-mcp-server-linux-x64"
|
||||
linux-arm64 = "bin/kei-mcp-server-linux-arm64"
|
||||
windows-x64 = "bin/kei-mcp-server-windows-x64.exe"
|
||||
```
|
||||
|
||||
A single brain on USB/iCloud now serves every host automatically. Schema v1 (single-string `mcp_server = "bin/..."`) is still accepted for backward-compat.
|
||||
|
||||
Four CLI commands:
|
||||
|
||||
| Command | What it does |
|
||||
|---|---|
|
||||
| `keisei attach <brain-path> [--scope user\|project]` | Mount brain into a single detected client (default: first detected) |
|
||||
| `keisei mount <brain-path>` | Auto-attach to **every** detected client (Claude Code, Cursor, Continue, Zed) in one call |
|
||||
| `keisei detach` | Unmount — strips `mcpServers.keisei` from every client's config, deletes marker |
|
||||
| `keisei list-adapters` | Tabular status of every adapter: name / detected / config path |
|
||||
| `keisei status` | Show currently-attached brain, client list, health (does `mcp_server` binary still exist?) |
|
||||
|
||||
Use cases:
|
||||
|
||||
- **Laptop travel.** Brain lives on USB / iCloud Drive. Plug in at home → `keisei mount /Volumes/MyBrain` attaches to Claude Code + Cursor simultaneously. Unplug → `keisei detach` clears everything.
|
||||
- **Team shared persona library.** Commit a brain repo to your private Forgejo/GitHub. Every developer clones it, runs `keisei mount ./team-brain`, same 30-agent persona library active in their Claude Code.
|
||||
- **Cloud brain.** Point `keisei attach s3://my-bucket/brain/` at an S3-backed brain synced via `kei-store` (v0.21 — real S3 / R2 / MinIO backend behind the `s3` feature flag). Memory follows you to any machine with network.
|
||||
- **Experimental personas in isolation.** Spin up a test brain via `cp -r ~/production-brain ~/experimental-brain`, `keisei attach ~/experimental-brain`. Iterate without touching production state.
|
||||
|
||||
For full flag matrix + env vars + security hardening details → [REFERENCE.md § `keisei` CLI](./REFERENCE.md#keisei-cli--exobrain-entry-point).
|
||||
|
||||
## 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`:
|
||||
|
||||
- `KEI_DISABLED_HOOKS` — comma- or space-list of hook base names (no `.sh`), e.g. `KEI_DISABLED_HOOKS=site-wysiwyd-check,milestone-commit-hook`. The literal `all` disables every hook.
|
||||
- `KEI_HOOK_PROFILE` — one of `full` (default), `advisory-off`, `minimal`, `off`.
|
||||
|
||||
| Profile | What stays on |
|
||||
|---|---|
|
||||
| `full` (default) | Every hook |
|
||||
| `advisory-off` | Disables pure-stderr advisories (`recurrence-suggest`, `citation-verify`, `error-spike-detector`, `milestone-commit-hook`). Safety gates stay on. |
|
||||
| `minimal` | Only safety-critical: `no-github-push`, `genesis-leak-guard`, `no-hand-edit-agents`, `secrets-guard`, `assemble-validate`, `git-pre-commit-genesis`. Everything else off. |
|
||||
| `off` | Every hook off — escape hatch for debugging hook interactions. |
|
||||
|
||||
```bash
|
||||
# One-session disable of a single noisy hook:
|
||||
export KEI_DISABLED_HOOKS=site-wysiwyd-check
|
||||
|
||||
# Permanent quieter profile (paste into ~/.zshrc / ~/.bashrc):
|
||||
export KEI_HOOK_PROFILE=advisory-off
|
||||
|
||||
# Full re-enable:
|
||||
unset KEI_DISABLED_HOOKS KEI_HOOK_PROFILE
|
||||
```
|
||||
|
||||
Interactive wizard: run `/hooks-control` — click-only picker that shows current state and emits the `export` / `unset` command for you to paste. The skill never executes anything itself.
|
||||
|
||||
## What you get
|
||||
|
||||
| Category | Count | Examples |
|
||||
|---|---:|---|
|
||||
| Behavioral blocks | 79 | `baseline`, `evidence-grading`, `rule-math-first`, `stack-rust-axum`, `stack-react-vite`, `stack-sveltekit`, `stack-astro`, `deploy-modal`, `api-fal-ai`, ... |
|
||||
| Generic agents (manifests) | 12 | `kei-code-implementer`, `kei-critic`, `kei-validator`, `kei-security-auditor`, `kei-architect`, `kei-researcher`, `kei-ml-implementer`, `kei-cost-guardian`, `kei-modal-runner`, ... |
|
||||
| Hooks (PreToolUse / PostToolUse) | 10 | `assemble-agents`, `assemble-validate`, `no-hand-edit-agents`, `tomd-preread`, `agent-fork-logger`, `orchestrator-dirty-check`, `site-wysiwyd-check`, `session-end-dump`, `milestone-commit-hook`, `error-spike-detector` |
|
||||
| Portable skills | 39 | `compose-solution`, `new-agent`, `new-project`, `site-create`, `schema-design`, `observability-setup`, `auth-setup`, `api-design`, `ci-scaffold`, `test-matrix`, `docs-scaffold`, `vm-provision`, ... |
|
||||
| Primitives (Rust crates, opt-in) | 25 | `kei-ledger`, `kei-migrate`, `kei-changelog`, `ssh-check`, `firewall-diff`, `mock-render`, `visual-diff`, `tokens-sync`, `kei-memory`, `kei-conflict-scan`, `kei-refactor-engine`, `kei-graph-check`, `kei-store`, `kei-router`, `kei-sage`, `kei-task`, `kei-chat-store`, `kei-crossdomain`, `kei-search-core`, `kei-content-store`, `kei-social-store`, `kei-curator`, `kei-auth` |
|
||||
| Primitives (shell, opt-in via profile) | 13 | `tomd`, `design-scrape`, `live-preview`, `figma-tokens`, `frontend-inspect`, `screenshot-decode`, `metrics-scrape`, `log-ship`, `provision-hetzner`, `provision-vultr`, `harden-base`, `kei-ci-lint`, `kei-docs-scaffold` |
|
||||
| Shell helpers (always copied) | 3 | `kei-sleep-setup`, `kei-sleep-sync`, `kei-sleep-queue` (dormant until you run `/sleep-setup`) |
|
||||
| Cross-tool bridges | 11 | Cursor legacy/MDC, Codex, Copilot, Windsurf, Junie, Continue, Gemini, Aider, Replit |
|
||||
|
||||
Of the 79 blocks, the **8 base blocks** (`baseline`, `evidence-grading`, `memory-protocol`, `rule-pre-dev-gate`, `rule-test-first`, `rule-error-budget`, `rule-double-audit`, `rule-math-first`) are referenced directly by the 12 shipped manifests. The remaining blocks (`stack-*`, `deploy-*`, `api-*`, `scraper-*`, `domain-*`) are a library consumed by the `/new-agent` wizard and the hub-and-spoke pipeline skills.
|
||||
|
||||
**Cognitive mode blocks** (`_blocks/mode-*.md`) are composable behavioural skews — `mode-skeptic`, `mode-devils-advocate`, `mode-minimalist`, `mode-maximalist`, `mode-first-principles`. Add any combination to an agent's manifest `blocks = [...]` list to stack the mode. See `_blocks/README.md` for the full list.
|
||||
|
||||
## Next steps
|
||||
|
||||
- [ARCHITECTURE.md](./ARCHITECTURE.md) — how agents, blocks, manifests, and the assembler fit together
|
||||
- [REFERENCE.md](./REFERENCE.md) — every primitive / hook / skill with its actual CLI surface
|
||||
- [SLEEP-LAYER.md](./SLEEP-LAYER.md) — nightly cycle + self-audit + cloud REM
|
||||
- [SECURITY.md](./SECURITY.md) — threat model + mitigations
|
||||
694
docs/REFERENCE.md
Normal file
694
docs/REFERENCE.md
Normal file
|
|
@ -0,0 +1,694 @@
|
|||
# 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.
|
||||
|
||||
**Index:** [Rust primitives](#rust-primitives) · [Shell primitives](#shell-primitives) · [Hooks](#hooks) · [Skills](#skills-grouped) · [`keisei` CLI deep-dive](#keisei-cli--exobrain-entry-point) · [Pipelines](#pipelines)
|
||||
|
||||
---
|
||||
|
||||
## Rust primitives
|
||||
|
||||
All 25 crates live under `_primitives/_rust/<name>/`. After `install.sh` runs, binaries land at `~/.claude/agents/_primitives/_rust/target/release/<name>`. 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 <path>] <subcommand>
|
||||
init — create ledger file + schema
|
||||
fork <id> <branch> --spec-sha <sha> — log a new running agent
|
||||
[--parent <id>] [--worktree <path>]
|
||||
done <id> --summary <s> — mark running agent done
|
||||
fail <id> --reason <r> — mark running agent failed
|
||||
merged <id> — mark done/failed agent merged into parent
|
||||
list [--status running|done|failed|merged] — dump history
|
||||
tree <id> — parent → children tree from root id
|
||||
validate <branch> [--repo-root <path>] — 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 <url> [--dir <path=migrations>] <subcommand>
|
||||
up — apply all pending migrations
|
||||
down [n=1] — revert the last N migrations (needs <ts>_<name>.down.sql)
|
||||
status — list applied vs pending
|
||||
create <name> — scaffold <ts>_<name>.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 <ref>] [--to <ref=HEAD>] [--unreleased]
|
||||
[--version <label=v0.1.0>] [--repo <path=.>]
|
||||
[--update <file>]
|
||||
```
|
||||
|
||||
`--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 <path=/etc/ssh/sshd_config>]
|
||||
[--drop-in <dir=/etc/ssh/sshd_config.d>]
|
||||
[--allow-user <name>]... [--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 <yaml> (--status-file <path> | --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 <url> --out <png> [--viewport WxH]
|
||||
mock-render lock --project <dir> --section <src> [--screenshot <png>]
|
||||
mock-render verify --project <dir> --section <src>
|
||||
mock-render status --project <dir>
|
||||
```
|
||||
|
||||
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 <a.png> <b.png> [--out <file=diff.png>] [--threshold <pct=1.0>]
|
||||
```
|
||||
|
||||
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 <tokens.json> [--out-tailwind <path>] [--out-css <path>]
|
||||
```
|
||||
|
||||
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 <path>] <subcommand>
|
||||
ingest --session-id <id> --transcript <path.jsonl> [--prompt <text>]
|
||||
analyze [--session <id>] [--last <n=1>] [--summary]
|
||||
patterns [--cross-session] [--session <id>]
|
||||
similar <prompt> [--limit <k=5>] — top-k past sessions by TF-IDF cosine
|
||||
dump <session-id> — emit session events as markdown
|
||||
stats — N sessions / N events / top tools
|
||||
backlog [--add <s>] [--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 <root>
|
||||
[--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 <conflicts.json>|-] [--plan-only]
|
||||
[--apply-to-branch <branch>]
|
||||
[--plan-out <path>] [--patch-out <path>]
|
||||
```
|
||||
|
||||
`--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 <root> [--after-diff <patch>] [--json]
|
||||
```
|
||||
|
||||
`--after-diff` treats any `+++ /dev/null` removal or `# removed: <p>` 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 <path>] <subcommand>
|
||||
init <backend> [--url <url>] — write store-config.toml scaffold
|
||||
read <path> — fetch blob to stdout
|
||||
write <path> <file> — upload local file
|
||||
list <dir> — list names under dir
|
||||
branch <name> — set active branch/prefix
|
||||
commit --message <msg> — commit staged writes
|
||||
push <branch> — push branch to remote
|
||||
pull <branch> — 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 <path>] <subcommand>
|
||||
init — register 5 built-in schemas
|
||||
register-schema --name <n> --path <schema.json>
|
||||
list-schemas
|
||||
export-schemas [--path <out>] — refresh assembler's schemas.json
|
||||
emit --schema <n> --from <agent> --content <json> — write an artifact
|
||||
[--meta key=val]... [--parent <id>]
|
||||
get <id> [--format typed|raw]
|
||||
list [--schema <n>] [--from <agent>] [--since <N>s]
|
||||
validate <id> — re-validate against schema
|
||||
chain <id> — 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/<pid>/cmdline` and shell history.
|
||||
|
||||
```
|
||||
kei-auth [--db <path>] <subcommand>
|
||||
issue --user <u> --project <p> [--scope read|write|admin=read] [--ttl <sec=86400>]
|
||||
verify <token>
|
||||
revoke <token>
|
||||
```
|
||||
|
||||
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 <query> [--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 <path>] <subcommand>
|
||||
import <vault> — import .md files with frontmatter
|
||||
search <query> [--limit <n=20>] — FTS5 over title+content
|
||||
related <key> [--depth <d=2>] — BFS from a vault path/key
|
||||
rank [--limit <n=20>] — PageRank over wikilinks
|
||||
add --title <t> [--content <c>] [--vault-path <p>] [--grade <g=E4>]
|
||||
edit <id> [--title <t>] [--content <c>] [--grade <g>]
|
||||
link <src> <dst> [--edge-type <t=related>]
|
||||
```
|
||||
|
||||
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 <path>] <subcommand>
|
||||
create <title> [--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](#keisei-cli--exobrain-entry-point) 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 in [INSTALL.md](./INSTALL.md#runtime-hook-controls)). 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 in [INSTALL.md](./INSTALL.md#the-keisei-cli--multi-client-exobrain-mount-v019)) 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.
|
||||
|
||||
**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`)
|
||||
|
||||
## Pipelines
|
||||
|
||||
Hub-and-spoke skills that combine primitives into end-to-end flows. Each one is an option-picker-first, free-text-last wizard; every phase has a verify-criterion.
|
||||
|
||||
| Skill | One-line purpose |
|
||||
|---|---|
|
||||
| `/compose-solution` | Meta-composer: decompose any task, grep prior art, propose math-first architecture, assemble the right artefact (agent / skill / hook / block) |
|
||||
| `/new-project` | Bootstrap a project specialist agent + repo skeleton + bridges + ledger row |
|
||||
| `/new-agent` | Interactive 6-question wizard that builds a project-specialist manifest and its `.md` |
|
||||
| `/site-create` | Frontend stack pick → design tokens → scaffold → WYSIWYD loop (mock-render, visual-diff, tokens-sync) |
|
||||
| `/schema-design` | DB schema design → migrations → `kei-migrate` apply (PG/SQLite/MySQL autodetect) |
|
||||
| `/observability-setup` | Pick metrics + logs stack → scrape + ship config (`metrics-scrape`, `log-ship`) |
|
||||
| `/auth-setup` | Pick auth model (session / JWT / OAuth2) → emit routes + middleware + token rotation |
|
||||
| `/api-design` | Contract-first: pick REST vs GraphQL vs gRPC, emit types + handlers + tests |
|
||||
| `/ci-scaffold` | GitHub Actions / Forgejo Actions workflow skeleton + `kei-ci-lint` pre-commit |
|
||||
| `/test-matrix` | Test stack matrix: unit / integration / e2e / visual; pick stack, emit skeleton |
|
||||
| `/docs-scaffold` | Doc site skeleton (mdbook / docusaurus / astro-starlight) + `kei-changelog` generator |
|
||||
| `/vm-provision` | VM provider pick → `provision-*` primitive → `harden-base` + `ssh-check` + `firewall-diff` verification |
|
||||
|
||||
All pipelines share a single discovery layer: `/compose-solution` Phase 3's prior-art grep covers `_blocks/`, `_manifests/`, `_primitives/` (shell + Rust), `skills/`, `_bridges/`, `hooks/` — so any pipeline can reuse primitives without re-inventing them.
|
||||
120
docs/SECURITY.md
Normal file
120
docs/SECURITY.md
Normal file
|
|
@ -0,0 +1,120 @@
|
|||
# Security model
|
||||
|
||||
What the kit touches, what it never touches, and the mitigations baked in.
|
||||
|
||||
---
|
||||
|
||||
## Threat surface overview
|
||||
|
||||
| Risk | Where it lives | Mitigation |
|
||||
|---|---|---|
|
||||
| Memory-repo leaks session content | Sleep-sync pushes trace JSONL off-machine | Private repo enforced by wizard; `[PATENT-IP]` sessions skip push entirely |
|
||||
| Hardcoded tokens in source | Edits by agents / humans | `secrets-guard` Rust hook (PreToolUse Edit\|Write) blocks known token shapes |
|
||||
| GitHub push of patent-sensitive content | `git push` command | `no-github-push.sh` hook + `genesis-leak-guard.sh` pre-commit symlink |
|
||||
| Malicious GitHub Action tag re-point | `.github/workflows/*.yml` | SHA-pinning + `validate-workflow-shas.sh` + `actionlint` in CI |
|
||||
| S3 SSRF / IMDS credential exfil | `kei-store` with custom endpoint | `validate_endpoint` rejects loopback / link-local / metadata hosts |
|
||||
| Escape-sequence injection via brain name | `keisei status` / `attach` output | Control-byte sanitiser on every manifest-sourced string |
|
||||
| Brain → `$HOME` pivot via symlink | `keisei attach <USB>` | Brain root rejected if symlink; `mcp_server` path must be relative + inside brain |
|
||||
| SQLite WAL corruption on USB mount | `keisei mount <exFAT drive>` | Runtime advisory; exFAT/FAT32 warning in USB guide |
|
||||
|
||||
## Key mitigations in detail
|
||||
|
||||
### Memory-repo must be private
|
||||
|
||||
Sleep-sync pushes your session traces (prompts, tool calls, file paths, code snippets) to a git repo you control. `/sleep-setup` Phase 1 warns loudly on PUBLIC visibility. A public memory-repo leaks everything your agents have seen.
|
||||
|
||||
If the session is marked `[PATENT-IP]` in the prompt or runs in a banned-project CWD, `session-end-dump.sh` skips the push entirely — local trace is kept, never leaves the machine.
|
||||
|
||||
### No GitHub push for kit-internal state
|
||||
|
||||
RULE 0.1 forbids `git push` to github.com for any repo containing unfiled-patent IP. Kit ships `genesis-leak-guard.sh` as a pre-commit hook symlink template to keep patent-sensitive terms off any remote.
|
||||
|
||||
Override for legitimate public push: set env `GENESIS_LEAK_BYPASS=1` for the single commit + document the bypass reason in the commit body. The hook logs every bypass to `~/.claude/memory/genesis-bypass-log.md`.
|
||||
|
||||
### Secrets by reference only
|
||||
|
||||
`secrets-guard` Rust hook blocks hardcoded tokens at `PreToolUse(Edit|Write)`. Every SSH key, API key, deploy token lives in `~/.claude/secrets/.env` (chmod 600, gitignored) or per-project `secrets/*.env`.
|
||||
|
||||
Hook detects these token shapes:
|
||||
|
||||
| Pattern | Source |
|
||||
|---|---|
|
||||
| `sk-[A-Za-z0-9]{20+}` | OpenAI/Anthropic legacy |
|
||||
| `sk-ant-[A-Za-z0-9_-]{40+}` | Anthropic current |
|
||||
| `ghp_[A-Za-z0-9]{36}` | GitHub classic PAT |
|
||||
| `github_pat_[A-Za-z0-9_]{82}` | GitHub fine-grained |
|
||||
| `xoxb-[0-9]+-[0-9]+-[A-Za-z0-9]+` | Slack bot |
|
||||
| `[0-9]{8,10}:[A-Za-z0-9_-]{35}` | Telegram bot |
|
||||
| `AKIA[A-Z0-9]{16}` | AWS access key |
|
||||
| `-----BEGIN (RSA \|EC \|OPENSSH )?PRIVATE KEY-----` | PEM private keys |
|
||||
| `Bearer [A-Za-z0-9._-]{20+}` | generic bearer |
|
||||
|
||||
Allowlist (no false-positives): env references (`$VAR`, `os.environ[...]`, `std::env::var(...)`), placeholders (`YOUR_TOKEN_HERE`, `<redacted>`), safe paths (`*/secrets/**`, `*.env.example`).
|
||||
|
||||
Bypass for emergency: set env `SECRETS_GUARD_BYPASS=1` on the single call.
|
||||
|
||||
### Supply-chain defences
|
||||
|
||||
All GitHub Actions in `.github/workflows/` are pinned by full commit SHA (defends against CVE-2025-30066-class mutable-tag attacks).
|
||||
|
||||
- `scripts/validate-workflow-shas.sh` verifies every pin exists upstream via `git ls-remote`
|
||||
- `scripts/install-actionlint.sh` checks SHA-256 of the downloaded tarball before extraction
|
||||
- `scripts/lint-workflows.sh` runs `actionlint` over every workflow file
|
||||
- CI job `workflow-lint` runs all three on every push + PR (< 30 s)
|
||||
- `dependabot.yml` raises weekly PRs for SHA updates across github-actions, npm, and cargo ecosystems
|
||||
|
||||
### S3 / R2 / MinIO hardening
|
||||
|
||||
`kei-store::s3_cloud::validate_endpoint` rejects loopback, link-local, and cloud-metadata hosts by default to close the SSRF / IMDS-credential-leak surface:
|
||||
|
||||
- `127.0.0.0/8`, `::1` (loopback)
|
||||
- `169.254.0.0/16`, `fe80::/10` (link-local)
|
||||
- `metadata.google.internal`, `metadata.aws.internal` (cloud metadata)
|
||||
|
||||
Plain HTTP requires opt-in via `KEI_STORE_S3_ALLOW_INSECURE=1`. When a custom (non-AWS) endpoint is set, explicit `access_key_env` + `secret_key_env` are REQUIRED — the AWS default credential chain is not consulted for non-AWS endpoints (closes the "IMDS credentials leaked to unrelated endpoint" path).
|
||||
|
||||
### Brain attach-marker is owner-only
|
||||
|
||||
`~/.keisei/attached.toml` is `chmod 0o600` on unix (Windows unchanged — no equivalent bit). Every manifest-sourced string printed by `keisei status` / `attach` / `mount` / `detach` is scrubbed through `display::sanitize_display`, which replaces every ASCII control byte (`< 0x20` or `== 0x7F`) with `?`. Closes the escape-sequence-injection surface from a malicious `brain.name` like `"evil\x1b[2Jpayload"` that would otherwise clear the user's terminal or rewrite already-printed lines.
|
||||
|
||||
`manifest.toml` is capped at 64 KiB — `fs::metadata` check runs before `read_to_string` so an attacker-supplied 1 GB file can't exhaust memory inside the TOML parser.
|
||||
|
||||
### Brain path & name validation
|
||||
|
||||
- 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`)
|
||||
|
||||
### exFAT / FAT32 warning
|
||||
|
||||
SQLite WAL shared-memory mmap is unreliable on those filesystems; `keisei mount` (multi-client) WILL corrupt `kei-memory` / `kei-artifact` / `kei-social-store` DBs. Brain load prints an advisory when exFAT/FAT32 is detected via `statfs(2)`. Single-client `keisei attach` on exFAT stays supported.
|
||||
|
||||
See [USB-BRAIN-GUIDE-macos.md](./USB-BRAIN-GUIDE-macos.md) / [-linux.md](./USB-BRAIN-GUIDE-linux.md) / [-windows.md](./USB-BRAIN-GUIDE-windows.md) for APFS / ext4 / NTFS-native walkthroughs.
|
||||
|
||||
## Battle-test matrix
|
||||
|
||||
Install-test battle matrix runs every profile against three base images before each release (`tests/battle/`):
|
||||
|
||||
| Image | Libc | Known quirks |
|
||||
|---|---|---|
|
||||
| `ubuntu:24.04` | glibc | baseline; most widely deployed |
|
||||
| `alpine:3.19` | musl | exposes musl-static-link issues in `rusqlite`, `git2`, `aws-sdk-s3` |
|
||||
| `debian:12` bookworm | glibc | different apt structure from Ubuntu |
|
||||
|
||||
Assertions per run: blocks ≥ 79, skills ≥ 39, top hooks ≥ 10, `_lib` hooks ≥ 2; `hooks/_lib/test-gate.sh` runs; `settings.json` validates. "Does it work on a fresh machine?" signal before every version ships.
|
||||
|
||||
See `tests/battle/README.md` for running locally.
|
||||
|
||||
## Rule references
|
||||
|
||||
For the underlying discipline: these mitigations are driven by rules in the user's Claude Code CLAUDE.md. The relevant ones:
|
||||
|
||||
- **RULE 0.1** — NO GITHUB PUSH (unless patent-IP review clears)
|
||||
- **RULE 0.4** — NO HALLUCINATION / CITATION VERIFY
|
||||
- **RULE 0.8** — SECRETS SINGLE SOURCE
|
||||
- **RULE 0.10** — RECURRENCE ESCALATE (same mistake ≥2× → codify via `/escalate-recurrence`)
|
||||
- **RULE 0.13** — ORCHESTRATOR BRANCH FIRST (agents write files; orchestrator owns git)
|
||||
- **RULE 0.14** — SESSION SELF-AUDIT
|
||||
- **RULE 0.15** — SLEEP LAYER (three-phase nightly consolidation)
|
||||
135
docs/SLEEP-LAYER.md
Normal file
135
docs/SLEEP-LAYER.md
Normal file
|
|
@ -0,0 +1,135 @@
|
|||
# Sleep Layer & Session Self-Audit
|
||||
|
||||
Day sessions → overnight consolidation → morning report. Three nightly phases on an Anthropic-cloud agent, plus an always-on session retrospective.
|
||||
|
||||
---
|
||||
|
||||
## The nightly cycle at a glance
|
||||
|
||||
The sleep layer is a **three-phase nightly cycle** on an Anthropic-cloud agent. The three phases run in order on the same scheduled trigger.
|
||||
|
||||
```
|
||||
YOUR NIGHT
|
||||
┌──────────────────────────────────────────────────────┐
|
||||
Day →→→ │ Phase A Phase B Phase C │ →→→ Morning
|
||||
│ INCUBATION REM NREM │
|
||||
│ "sleep on it" consolidation deep-sleep │
|
||||
│ v0.12.0 v0.11.0 v0.13.0 │
|
||||
│ (queued tasks) (trace patterns) (conflict │
|
||||
│ refactor) │
|
||||
└──────────────────────────────────────────────────────┘
|
||||
↓ ↓ ↓
|
||||
sleep-results/ reports/sleep-*.md sleep-deep/*.md
|
||||
<uuid>.md (always) (every N days)
|
||||
```
|
||||
|
||||
**Biological analog.** Your Mac is the hippocampus (fast, stateful, volatile — captures raw episodes). The memory-repo is the transport layer. The cloud agent is the neocortex (slow, stateless, generalising). The morning `git pull` is the recall. Phase A mirrors the "sleep on it" effect (Wagner et al. 2004, *Nature*), Phase B mirrors REM dream-state pattern extraction, Phase C mirrors NREM slow-wave system consolidation.
|
||||
|
||||
**Phase interaction rules (important):**
|
||||
|
||||
- A `marathon` task in Phase A (8-hour budget, 1 task only) **owns the whole night** — Phases B and C are skipped for that night. Traces are append-only, so the next night's Phase B picks up the skipped backlog.
|
||||
- Phase C only fires when today is a multiple of `DEEP_SLEEP_CRON_DAYS` (default 7) counted from your install date. Anchor lives in `sync-repo/reports/install-anchor.txt`.
|
||||
- The morning report is for **HUMAN review**. It is NEVER auto-injected into a Claude Code session. Any rule or hook that emerges from it is installed via `/escalate-recurrence` — not by the cloud agent.
|
||||
|
||||
Governed end-to-end by RULE 0.15 in `~/.claude/rules/sleep-layer.md`.
|
||||
|
||||
## Session self-audit (RULE 0.14)
|
||||
|
||||
KeiSeiKit auto-analyzes sessions on 3 triggers:
|
||||
|
||||
- **Stop event** — session ended; `session-end-dump.sh` archives the JSONL trace and ingests it into `kei-memory`.
|
||||
- **Milestone commits** — `git commit -m "feat:"` / `"refactor:"` / `git merge`; `milestone-commit-hook.sh` appends a one-line session summary to `~/.claude/memory/audit-backlog.md`.
|
||||
- **Error spike** — 3+ errors in the last 20 tool calls; `error-spike-detector.sh` tags the pattern and logs it.
|
||||
|
||||
Findings surface via click-only `AskUserQuestion`, routing to `/escalate-recurrence` (codify rule + wiki + hook), `/debug-deep` (5-phase RCA), or the audit backlog (log-only). **Silent-first**: the first 10 sessions log only — prompts activate from session 11 onward so the memory store has a useful baseline before it interrupts you. Counter lives in `~/.claude/memory/audit-backlog.md` as `<!-- session_count: N -->`.
|
||||
|
||||
Manual trigger: `/self-audit` skill (same flow, invoked on demand).
|
||||
|
||||
Requires the `kei-memory` primitive. Included in the `dev` and `full` profiles; otherwise add via `./install.sh --add=kei-memory`.
|
||||
|
||||
## Cloud REM sync (v0.11.0) — Phase B
|
||||
|
||||
Run a nightly "sleep" cycle on Anthropic's cloud — no laptop, no infra, no DevOps.
|
||||
|
||||
**How it works:**
|
||||
- Each session: your Mac pushes trace JSONL to a private git repo you control
|
||||
- 03:00 local time: a remote Claude Code agent clones the repo, analyzes the last 24h of traces, writes `reports/sleep-YYYY-MM-DD.md`, and commits back
|
||||
- Next morning: `git pull` and read the consolidated findings
|
||||
|
||||
**Setup (one-time, ~5 min):**
|
||||
|
||||
1. Create an empty private repo on GitHub / GitLab / Bitbucket / self-hosted Forgejo
|
||||
2. In Claude Code run `/sleep-setup`
|
||||
3. The wizard generates an SSH deploy key → you paste it into the repo's deploy-key settings with WRITE access
|
||||
4. The wizard emits a ready-to-paste `/schedule create` command, converted to your local 03:00 in UTC
|
||||
|
||||
After that, the sleep cycle runs every night automatically. The morning report is yours to read — nothing is auto-injected back into any session.
|
||||
|
||||
**Requires** the `kei-memory` primitive (shipped in the `dev` and `full` profiles; add via `./install.sh --add=kei-memory` otherwise). Sleep-sync scripts themselves are installed unconditionally and stay dormant until you opt in via `/sleep-setup`.
|
||||
|
||||
Opt in at install time with `./install.sh --with-sleep-sync` (TTY-only). Governed by RULE 0.15 in `~/.claude/rules/sleep-layer.md`.
|
||||
|
||||
## Sleep on it (incubation, v0.12.0) — Phase A
|
||||
|
||||
Defer a hard question or research task to the nightly remote agent: run `/sleep-on-it`, fill in one free-text field plus three clicks (type / priority / format), submit. The task lands in `sync-repo/sleep-queue/` and the nightly agent processes it before REM consolidation.
|
||||
|
||||
Priority maps to a wall-clock budget. Pick the one that matches the task's difficulty:
|
||||
|
||||
| Priority | Budget | When to pick |
|
||||
|---|---|---|
|
||||
| Quick | 15 min, this night | Simple questions, fast lookups |
|
||||
| Standard | 60 min, this night | Default, medium research |
|
||||
| Deep | 4 hours, this night | Serious derivations, thorough prior-art |
|
||||
| Marathon | Full night (up to 8 h), **1 task only** | Hard equations, full autonomy; Phase B REM skipped that night |
|
||||
| Weekly batch | 60 min, next Sunday UTC | Non-urgent research |
|
||||
|
||||
Checkpointing: Standard / Deep / Marathon runs commit a `.partial.md` every 20–30 minutes, so if the cloud session is cut short you still get the partial on morning pull.
|
||||
|
||||
Typical use:
|
||||
- "Should I use CfC for memory re-ranker?" → deep-research → architectural recommendation by morning
|
||||
- "Compare SvelteKit vs Astro vs Next.js App Router for the kit's landing" → comparative study
|
||||
- "Derive closed form for the CfC attractor on Stiefel V(p,k=2)" → marathon mode, full night of autonomous derivation
|
||||
- "What patterns in audit-backlog have highest impact?" → pattern analysis
|
||||
|
||||
Results in `sync-repo/sleep-results/<uuid>.md`, linked from the next morning's REM report. Biological analog: the REM-sleep "sleep on it" effect (Wagner et al. 2004, *Nature*). Queue mutations go through the `kei-sleep-queue` helper.
|
||||
|
||||
## Deep-sleep NREM consolidation (v0.13.0) — Phase C
|
||||
|
||||
A third nightly phase — **Phase C** — runs after REM on a user-chosen cadence (default: every 7 days). Biological analog: NREM slow-wave-sleep system consolidation. The remote agent scans your memory-repo for conflicts across rules, hooks, `_blocks/`, and memory (contradictory directives, overlapping hook matchers, >70%-duplicate blocks, orphaned wikilinks, Constructor-Pattern violations) and produces a structured refactor plan.
|
||||
|
||||
**4-primitive pipeline, in order:**
|
||||
|
||||
```
|
||||
kei-conflict-scan → kei-refactor-engine → kei-graph-check (via kei-store transport)
|
||||
(detect) (propose) (verify) (read/write memory-repo)
|
||||
```
|
||||
|
||||
1. `kei-conflict-scan` reads `_rules/`, `hooks/hooks.json`, `_blocks/`, and `memory/` and emits a typed conflict list (name-collision, matcher-overlap, duplicate-block, orphan-wikilink, CP-violation).
|
||||
2. `kei-refactor-engine` groups conflicts by safe-to-auto-resolve vs `requires_human_decision` and writes the plan + auto-resolve markdown.
|
||||
3. `kei-graph-check` walks every wikilink / block-ref / handoff-ref in the proposed state; if anything fails to resolve, the fork branch is blocked and the plan is annotated.
|
||||
4. `kei-store` is the transport — reads the pre-state from your GitHub / Forgejo / Gitea / FS / S3 backend and writes the two output files back atomically.
|
||||
|
||||
**Concrete example** (real category, paraphrased):
|
||||
|
||||
> Conflict detected: hook `no-github-push.sh` (PreToolUse:Bash, matcher `git push`) and rule file `patents.md` (§"Never reference unfiled applications") both govern the same risk surface — a github push containing unfiled-patent language. The hook blocks on URL; the rule blocks on content. Suggested refactor: keep both (they are complementary), but add a cross-ref from `patents.md` to the hook so a future reader sees the two-layer defence. Auto-resolvable (pure documentation edit, no behaviour change). Written to `YYYY-MM-DD-autoresolve.md` for human review.
|
||||
|
||||
Two output modes, chosen once in `/sleep-setup` Phase 3b:
|
||||
|
||||
- **Plan only** (default) — markdown report in `sync-repo/sleep-deep/YYYY-MM-DD-plan.md`. Read in the morning, decide what to merge by hand.
|
||||
- **Plan + fork** — same plan plus an auto-resolve review markdown (`YYYY-MM-DD-autoresolve.md`) listing the auto-resolvable conflicts with WHY / EXAMPLE / TRADEOFF per item. You open each file in an editor, apply the suggested change, commit on a `deep-sleep/YYYY-MM-DD` branch, then let the graph-check gate verify the wikilinks still resolve.
|
||||
|
||||
> v0.14.1 retraction: earlier README claimed a `git apply`-ready patch. The engine cannot synthesise real unified-diff hunks without reading the source files — that would risk fabricated edits (RULE 0.4). The autoresolve file is now plain markdown reviewed and applied by hand; the "fork" path only automates the rename/move class of ops, not content edits.
|
||||
|
||||
**Zero-conflict guarantee:** any conflict the engine marks `requires_human_decision` is EXCLUDED from the auto-resolve markdown and listed plainly in the plan. No silent auto-apply of ambiguous changes.
|
||||
|
||||
**Store backends** (picked in Phase 3b, consumed via the new `kei-store` trait):
|
||||
|
||||
| Backend | Status | Notes |
|
||||
|---|---|---|
|
||||
| GitHub private | production | SSH deploy key or PAT; default |
|
||||
| Forgejo self-hosted | production | Same wire protocol as GitHub |
|
||||
| Gitea self-hosted | production | Same wire protocol |
|
||||
| Filesystem only | production | Local `.git`; no push; fastest |
|
||||
| S3 / R2 / MinIO | production (v0.21, behind `s3` feature) | Real GetObject / PutObject / ListObjectsV2 via `aws-sdk-s3`. Build with `cargo build -p kei-store --features s3` and set `[s3] bucket = "..."` in `store-config.toml`. AWS default credential chain (env vars → `~/.aws/credentials` → IMDS). Custom endpoint for R2 / MinIO / Wasabi via `KEI_STORE_S3_ENDPOINT` env or `s3.endpoint` TOML field. Binary grows ~5 MB when the feature is on. Omit the feature OR omit `s3.bucket` to fall back to the v0.14 local-manifest stub (still gated by `KEI_STORE_ALLOW_S3_STUB=1`). |
|
||||
|
||||
Requires the new `kei-conflict-scan`, `kei-refactor-engine`, `kei-graph-check`, and `kei-store` primitives (shipped in the `dev` and `full` profiles). Governed by the Phase C extension of RULE 0.15 in `~/.claude/rules/sleep-layer.md`.
|
||||
31
docs/WHY.md
Normal file
31
docs/WHY.md
Normal file
|
|
@ -0,0 +1,31 @@
|
|||
# Why I built KeiSeiKit
|
||||
|
||||
*By Denis Parfionovich. Restored from the original README preamble (pre-v0.22 product pivot), available separately for those who want the full philosophical background. The main README keeps the product-oriented pitch.*
|
||||
|
||||
---
|
||||
|
||||
Hello.
|
||||
|
||||
Transformers are statistically wired to lie. It is not a bug, it is the core operation: they pick the next token by sampling a probability distribution conditioned on whatever context happens to fit the window. They cannot reliably hold long context, they will drag a hallucination picked up three thousand tokens ago into a confident final sentence, and they may deliver a brilliant insight right next to a fabricated citation. This is not fixable inside the model — it is mathematically baked in from the moment of tokenization onward.
|
||||
|
||||
This kit is my humble attempt to build scaffolding *around* those errors. Not to fix the transformer, but to make it behave a little closer to my own working logic: catch the common failure modes before they reach a commit, give it external memory that survives session boundaries, give it a rhythm resembling human work (day sessions → overnight consolidation → morning report), and let parallel agents coordinate through a shared state instead of stepping on each other.
|
||||
|
||||
I work across 4 to 8 parallel Claude terminals most days. The problems I hit are mundane: forgetting between sessions, repeating the same mistake on the third try, parallel agents clobbering each other's files, a hallucinated API name shipped to production. None of these are solvable by a better prompt. They are solvable by structure around the prompt.
|
||||
|
||||
Most of what is here is well-established bricks (git-as-state, cron, TF-IDF, constructor-pattern composition). What may be new in the Claude Code context is the Constructor Pattern for agents (composable blocks, deterministic build, rebuild-on-block-edit hooks) and sleep-sync (using a git repo as the transport layer between sessions, with an Anthropic-cloud agent doing nightly REM-style consolidation).
|
||||
|
||||
## Why Rust, not Python
|
||||
|
||||
Transformers write Python confidently and wrongly. Five minutes to a plausible-looking function, two hours to debug why `dict.get("key", None) or []` silently swallowed an empty list, or why an async context manager leaked a file handle across a retry loop. Rust's type system catches whole categories of those errors at compile-time — the model literally cannot ship a `None`-vs-`[]` confusion, a missing `.await`, or an unhandled `Result`, because the compiler refuses. For an LLM-written codebase this is not aesthetic preference, it is survival. Every Rust primitive here is one category of hallucination the transformer is no longer allowed to commit.
|
||||
|
||||
## It is not a product
|
||||
|
||||
It helps me personally. If it resonates with you, let me know. If enough feedback comes in, there will be a next version — more primitives, more patterns against the "forgetful" transformer. But that needs input; without it, I just keep using this quietly myself.
|
||||
|
||||
Forks and PRs welcome from everyone, not only from those who write code. If you hit a problem with Claude Code and have an idea for solving it, open an issue with the description. A well-formulated problem is already half the solution.
|
||||
|
||||
Hope it is a small Kei for someone to make vibecoding better.
|
||||
|
||||
And double sorry if I'm repeating someone — I never tried other kits, since this one is just all my rules stacked in one place. I can't always tell what I have seen somewhere and what came from my own head — so treat this as just my sample, not a claim of originality.
|
||||
|
||||
Thanks.
|
||||
Loading…
Reference in a new issue