0be354a920
Single-commit clean baseline after security scrub of niche-tells, project codenames, internal jargon, and contributor-email leaks. Contents: - 100 Rust crates (_primitives/_rust/) - 37 agent manifests (_manifests/) + generated specs (_generated/) - 67 user-invocable skills (skills/) - 33 hooks (hooks/) - Composition blocks (_blocks/) - Documentation (docs/, README.md) - TS adapter packages (_ts_packages/) - Assembler (_assembler/) - Roles (_roles/) - Templates (_templates/) - Forgejo CI (.forgejo/) Author: Denis Parfionovich <info@greendragon.info> License: see LICENSE.
98 lines
6.1 KiB
Markdown
98 lines
6.1 KiB
Markdown
# USB Exobrain — Step-by-Step Test Recipe
|
||
|
||
> Put a KeiSeiKit "brain" on a portable USB drive, mount it into Claude Code (and Cursor / Continue / Zed if installed), verify MCP tools, unplug — verify clean detach.
|
||
>
|
||
> This top-level document holds prerequisites, the shared filesystem warning, the TOC, and platform-agnostic troubleshooting. Step-by-step walkthroughs live in the three platform sub-documents.
|
||
|
||
## Platform walkthroughs
|
||
|
||
- [macOS walkthrough](./USB-BRAIN-GUIDE-macos.md) — `/Volumes/<LABEL>`, APFS recommended, Gatekeeper / `xattr` handling.
|
||
- [Linux walkthrough](./USB-BRAIN-GUIDE-linux.md) — `/media/$USER/<LABEL>`, ext4 recommended, `umount` / optional systemd-udev auto-attach.
|
||
- [Windows walkthrough](./USB-BRAIN-GUIDE-windows.md) — drive letter, NTFS recommended, `Dismount-Volume` / PowerShell.
|
||
|
||
---
|
||
|
||
## 0. Prerequisites (all platforms)
|
||
|
||
On the host:
|
||
|
||
- KeiSeiKit installed: `./install.sh --profile=full` ran successfully, `cargo test -p keisei` shows 32/32 pass (v0.22).
|
||
- `keisei` CLI on PATH: `ls ~/.claude/agents/_primitives/_rust/target/release/keisei` returns the binary. Symlink into `~/.local/bin/` or `%USERPROFILE%\bin` as convenient.
|
||
- At least one supported client installed (Claude Code / Cursor / Continue / Zed) — `keisei` auto-detects all four.
|
||
- A USB stick or flash card physically attached and mounted by the OS.
|
||
|
||
On the USB drive:
|
||
|
||
- Free space: ~500 MB recommended (5 mcp-server binaries × ~90 MB each + room for memory/artifacts SQLite).
|
||
- Filesystem — see the warning below.
|
||
|
||
---
|
||
|
||
## ⚠️ Filesystem warning — exFAT / FAT32 are NOT safe for multi-client attach
|
||
|
||
SQLite WAL mode (used by `kei-memory`, `kei-artifact`, `kei-social-store` inside a brain) requires a filesystem with reliable shared-memory mmap. exFAT and FAT32 do NOT provide this, and `keisei mount` (multi-client fan-out) WILL corrupt the memory DBs if the brain lives on one of those filesystems.
|
||
|
||
Since v0.22 `keisei` itself prints an advisory on stderr when it detects an exFAT / FAT32 root at load time (via `statfs(2)` on macOS + Linux; Windows returns `Unknown` pending `GetVolumeInformationW`). The warning is non-blocking — single-client `keisei attach` on exFAT is still a supported path.
|
||
|
||
- On exFAT / FAT32: use the brain with **ONE client at a time** (`keisei attach --scope=user`). Do NOT run `keisei mount`.
|
||
- For reliable multi-client use, format the stick as **APFS (macOS)**, **ext4 (Linux)**, or **NTFS (Windows)**. exFAT is fine for single-client or read-only cross-platform transport.
|
||
- If you already ran `keisei mount` on an exFAT brain and see SQLite errors, see "SQLite corruption on mount-attach" in Troubleshooting below.
|
||
|
||
---
|
||
|
||
## Brain safety invariants (all platforms)
|
||
|
||
The following load-time checks fire regardless of OS. They prevent the most common misuse and attack patterns:
|
||
|
||
- **Name regex** — `brain.name` must match `^[a-z][a-z0-9_-]{0,63}$` (lowercase letter start, 1-64 chars, word chars + hyphen).
|
||
- **Relative paths** — every `[paths.*]` entry must be relative; no absolute paths, no `..` components. Canonical form must live under the brain root.
|
||
- **Symlink reject** — the brain root itself cannot be a symlink. Pass the resolved path; this closes a USB→host pivot surface.
|
||
- **Manifest size cap** — `manifest.toml` is bounded at 64 KiB.
|
||
- **Schema** — `schema_version ∈ {1, 2}`. v1 uses single-string `mcp_server`; v2 uses per-platform map.
|
||
|
||
---
|
||
|
||
## Platform-agnostic troubleshooting
|
||
|
||
### "BrainNotFound" on attach
|
||
- Check `<BRAIN>/manifest.toml` exists.
|
||
- Pass an absolute path to `keisei attach`, not a relative one.
|
||
|
||
### "PathEscape" on attach
|
||
- Every `[paths.*]` entry must be relative and resolve inside the brain root. No `../`, no absolute paths.
|
||
|
||
### "BrainIsSymlink" on attach
|
||
- The brain root is a symlink. Pass the resolved path instead — `keisei` refuses symlink roots to prevent accidental host-dir pivot via a crafted USB.
|
||
|
||
### "NoPlatformBinary" on first use
|
||
- Your platform's binary isn't in `bin/`. Check `std::env::consts::{OS, ARCH}` on your host — the expected filename is `kei-mcp-server-<os-renamed>-<arch-renamed>` where `macos→darwin`, `x86_64→x64`, `aarch64→arm64`.
|
||
|
||
### "NameConflict" on attach
|
||
- An MCP server with the same name already exists in the client's config. Either rename your brain (`name` in `manifest.toml`) or remove the existing entry manually.
|
||
|
||
### SQLite corruption on mount-attach
|
||
- `kei-memory` / `kei-artifact` / `kei-social-store` databases show "disk image is malformed" or "database is locked" after `keisei mount` on a USB drive.
|
||
- Root cause: the brain lives on **exFAT or FAT32**, which don't reliably support SQLite WAL shared-memory mmap. Multi-client attach corrupts the DB.
|
||
- Fix:
|
||
1. Copy the brain dir to an APFS (macOS) / ext4 (Linux) / NTFS (Windows) volume.
|
||
2. Re-attach via `keisei attach <new-path>` or `keisei mount <new-path>`.
|
||
3. For single-client use on the same exFAT drive, restrict to `keisei attach --scope=user`. Do NOT use `keisei mount`.
|
||
|
||
### Filesystem-warning advisory not appearing
|
||
- `keisei` prints the exFAT/FAT32 warning to **stderr** (not stdout). Shells that redirect stderr away will hide it.
|
||
- Windows `detect_fs_warning` returns `Unknown` in v0.22 — format as NTFS manually.
|
||
|
||
---
|
||
|
||
## What this tests end-to-end
|
||
|
||
1. **Portable brain** — works from a USB drive, no installer needed on the brain itself.
|
||
2. **Per-platform dispatch** — schema v2 picks the right binary for the host OS+arch.
|
||
3. **Multi-client fan-out** — `keisei mount` attaches to every detected client in one call.
|
||
4. **Clean detach** — zero residue in host configs, preserves unrelated MCP servers.
|
||
5. **Safety gates** — path confinement, name regex, symlink rejection, manifest size bound, filesystem-type advisory (v0.22).
|
||
6. **Schema v1 compat** — an older v1 brain with a single-string `mcp_server` still works.
|
||
|
||
If the walkthrough for your platform passes end-to-end, the v0.22 exobrain is production-ready for single-user workflows on that platform.
|
||
|
||
For shared-brain scenarios (team members all mounting the same brain over git / S3) see the `kei-store` backend docs — `keisei attach s3://my-bucket/brain/` requires `--features s3` at install.
|