membot 0.1.0 → 0.1.1

package/.claude/skills/membot.md

@@ -0,0 +1,137 @@
+---
+name: membot
+description: Persistent, versioned context store for AI agents — ingest, search, read, and write knowledge via the membot CLI or MCP server
+trigger: when the user wants to remember, recall, or search project knowledge, ingest documents into a long-lived store, or surface relevant context for a task
+---
+
+# membot — Persistent Context for Agents
+
+You have access to a long-lived context store via `membot`. Files (markdown, PDFs, DOCX, HTML, URLs, agent notes) are ingested, converted to markdown, chunked, embedded locally, and indexed in DuckDB with hybrid search (semantic + BM25). Every artifact is addressed by a virtual `logical_path`. Every change creates a new immutable version — nothing is overwritten in place.
+
+Use this workflow:
+
+## 1. Discover what's already there
+
+Before ingesting, check whether the knowledge already exists.
+
+```bash
+membot tree                         # synthesised directory tree of logical_paths
+membot ls                           # one row per current file (size, mime, refresh status)
+membot ls docs/                     # filter by prefix
+membot search "<question>"          # hybrid search (semantic + keyword)
+```
+
+`search` is the primary discovery tool — prefer it over scanning files.
+
+## 2. Ingest
+
+```bash
+membot add ./README.md                            # single file
+membot add ./docs                                 # recursive directory walk
+membot add "docs/**/*.md"                         # glob
+membot add https://example.com/spec.pdf           # URL (auto-converted to markdown)
+membot add "inline:Decision: use X because Y"     # literal text
+membot add ./docs --refresh-frequency 24h         # auto-refresh every day
+```
+
+Each entry becomes a new version under its own `logical_path`. PDFs/DOCX/HTML are converted to markdown; images get vision captions; original bytes are kept and reachable via `membot read --bytes`.
+
+## 3. Read
+
+```bash
+membot read <logical_path>                       # current markdown surrogate
+membot read <logical_path> --bytes               # original bytes (base64) — PDF/DOCX/image as ingested
+membot read <logical_path> --version <ts>        # historical snapshot
+membot info <logical_path>                       # metadata only (no content)
+membot versions <logical_path>                   # every version, newest first
+membot diff <logical_path> --a <ts> [--b <ts>]   # unified diff between versions
+```
+
+Defaults to the current (non-tombstoned) version. Pass `--version` only when you need history.
+
+## 4. Write your own notes
+
+Persist agent-authored summaries, decisions, or synthesised context so they survive across conversations:
+
+```bash
+membot write notes/decision-2026-05.md --content "Decided to ..."
+```
+
+Inline writes create a new `(logical_path, version_id)` row just like file ingests — `membot versions` lists them, `membot diff` compares them. To mirror an external doc that should re-fetch over time, use `membot add <url> --refresh-frequency` instead.
+
+## 5. Refresh, rename, delete, prune
+
+```bash
+membot refresh <logical_path>          # re-read source; new version only if bytes changed
+membot refresh                         # refresh all rows whose schedule has elapsed
+membot mv old/path new/path            # rename (history preserved under both)
+membot rm <logical_path>               # tombstone (history still queryable)
+membot prune --before <iso-ts>         # drop non-current versions older than cutoff (irreversible)
+```
+
+Tombstones hide a path from `ls` / `tree` / `search` but `versions` and `read --version <ts>` still work. Pruning is the only way to actually remove data.
+
+## Versioning rules
+
+- Defaults always operate on the current, non-tombstoned version.
+- Pass an explicit `--version <timestamp>` (from `membot versions`) to read or diff history.
+- `membot_add`, refresh-with-changes, `write`, and `mv` each create a new version. The previous version is preserved.
+- Mutating an existing version is not possible — corrections are new versions.
+
+## When to use this skill
+
+- The user asks to remember, recall, save, or look up something across conversations.
+- You need project-specific context (specs, decisions, transcripts, rendered docs) that's larger than fits in the prompt.
+- You need to ingest a document (PDF, DOCX, HTML, URL) and reason over it.
+- You're producing a summary or decision that should survive past this conversation.
+
+## When NOT to use this skill
+
+- Reading a file the user just pointed at — use the regular file-read tool unless they want it persisted.
+- Storing secrets, credentials, or anything that shouldn't sit in `~/.membot/index.duckdb`.
+- Quick scratch state for the current turn — keep that in the conversation.
+
+## MCP server
+
+`membot serve` exposes the same operations as MCP tools (`membot_add`, `membot_search`, etc.) over stdio (default) or HTTP (`--http <port>`). When connected, prefer the MCP tools over shelling out — they return structured `outputSchema` data with `version_id` echoed on every read.
+
+## Available commands
+
+| Command                               | Purpose                                                                        |
+| ------------------------------------- | ------------------------------------------------------------------------------ |
+| `membot add <source>`                 | Ingest file, directory, glob, URL, or `inline:<text>` (one new version each)   |
+| `membot ls [prefix]`                  | List current files (size, mime, refresh status)                                |
+| `membot tree [prefix]`                | Render the synthesised logical-path tree                                       |
+| `membot read <path>`                  | Read current markdown surrogate (or `--bytes` for original)                    |
+| `membot write <path> --content <txt>` | Write inline agent-authored markdown as a new version                          |
+| `membot search <query>`               | Hybrid search (semantic + BM25); add `--include-history` to search older versions |
+| `membot info <path>`                  | Inspect metadata (source, fetcher, refresh schedule, digests) without content  |
+| `membot versions <path>`              | List every version newest-first with version_id and change notes               |
+| `membot diff <path> --a <ts>`         | Unified diff between two versions                                              |
+| `membot mv <old> <new>`               | Rename a logical_path (history preserved)                                      |
+| `membot rm <path>`                    | Tombstone a logical_path (history still queryable)                             |
+| `membot refresh [path]`               | Re-read source; create new version only if bytes changed                       |
+| `membot prune --before <ts>`          | Permanently drop non-current versions older than cutoff (irreversible)         |
+| `membot serve`                        | Start MCP server (stdio default, `--http <port>` for HTTP)                     |
+| `membot reindex`                      | Rebuild the FTS keyword index over current chunks                              |
+
+## Output formats
+
+- TTY → spinners, colors, tables. `--no-color` disables ANSI.
+- Piped, `--json`, `CI=true`, or `NO_COLOR` → JSON to stdout, structured logs to stderr, no ANSI bytes.
+- Use `--json` when parsing output programmatically (it's automatic when piped, but explicit is safer).
+- Use `--verbose` if a command fails unexpectedly.
+
+## Troubleshooting
+
+- **"ingest failed: unsupported mime"** → Add a converter or pass `--bytes` to keep the original; LLM-fallback only runs when `ANTHROPIC_API_KEY` is set.
+- **"refresh failed: auth"** → The original fetch used an authenticated mcpx tool; re-auth via `mcpx auth <server>`.
+- **Search returns nothing** → Confirm the file ingested with `membot info <path>`; if needed, run `membot reindex` to rebuild the FTS keyword index.
+- **Stale results after manual DB edits** → `membot reindex`.
+- **Two paths point at the same content** → `membot mv` doesn't merge; tombstone one with `membot rm`.
+
+## Configuration
+
+- Data lives in `~/.membot/index.duckdb` (override via `MEMBOT_HOME`).
+- Optional `ANTHROPIC_API_KEY` enables LLM fallback for messy/binary input. Without it, conversion degrades to deterministic native output.
+- Config file: `~/.membot/config.json` (see `membot --help` for the global flags).

package/.cursor/rules/membot.mdc

@@ -0,0 +1,137 @@
+---
+description: Persistent, versioned context store for AI agents — ingest, search, read, and write knowledge via the membot CLI or MCP server
+globs:
+alwaysApply: true
+---
+
+# membot — Persistent Context for Agents
+
+You have access to a long-lived context store via `membot`. Files (markdown, PDFs, DOCX, HTML, URLs, agent notes) are ingested, converted to markdown, chunked, embedded locally, and indexed in DuckDB with hybrid search (semantic + BM25). Every artifact is addressed by a virtual `logical_path`. Every change creates a new immutable version — nothing is overwritten in place.
+
+Use this workflow:
+
+## 1. Discover what's already there
+
+Before ingesting, check whether the knowledge already exists.
+
+```bash
+membot tree                         # synthesised directory tree of logical_paths
+membot ls                           # one row per current file (size, mime, refresh status)
+membot ls docs/                     # filter by prefix
+membot search "<question>"          # hybrid search (semantic + keyword)
+```
+
+`search` is the primary discovery tool — prefer it over scanning files.
+
+## 2. Ingest
+
+```bash
+membot add ./README.md                            # single file
+membot add ./docs                                 # recursive directory walk
+membot add "docs/**/*.md"                         # glob
+membot add https://example.com/spec.pdf           # URL (auto-converted to markdown)
+membot add "inline:Decision: use X because Y"     # literal text
+membot add ./docs --refresh-frequency 24h         # auto-refresh every day
+```
+
+Each entry becomes a new version under its own `logical_path`. PDFs/DOCX/HTML are converted to markdown; images get vision captions; original bytes are kept and reachable via `membot read --bytes`.
+
+## 3. Read
+
+```bash
+membot read <logical_path>                       # current markdown surrogate
+membot read <logical_path> --bytes               # original bytes (base64) — PDF/DOCX/image as ingested
+membot read <logical_path> --version <ts>        # historical snapshot
+membot info <logical_path>                       # metadata only (no content)
+membot versions <logical_path>                   # every version, newest first
+membot diff <logical_path> --a <ts> [--b <ts>]   # unified diff between versions
+```
+
+Defaults to the current (non-tombstoned) version. Pass `--version` only when you need history.
+
+## 4. Write your own notes
+
+Persist agent-authored summaries, decisions, or synthesised context so they survive across conversations:
+
+```bash
+membot write notes/decision-2026-05.md --content "Decided to ..."
+```
+
+Inline writes create a new `(logical_path, version_id)` row just like file ingests — `membot versions` lists them, `membot diff` compares them. To mirror an external doc that should re-fetch over time, use `membot add <url> --refresh-frequency` instead.
+
+## 5. Refresh, rename, delete, prune
+
+```bash
+membot refresh <logical_path>          # re-read source; new version only if bytes changed
+membot refresh                         # refresh all rows whose schedule has elapsed
+membot mv old/path new/path            # rename (history preserved under both)
+membot rm <logical_path>               # tombstone (history still queryable)
+membot prune --before <iso-ts>         # drop non-current versions older than cutoff (irreversible)
+```
+
+Tombstones hide a path from `ls` / `tree` / `search` but `versions` and `read --version <ts>` still work. Pruning is the only way to actually remove data.
+
+## Versioning rules
+
+- Defaults always operate on the current, non-tombstoned version.
+- Pass an explicit `--version <timestamp>` (from `membot versions`) to read or diff history.
+- `membot_add`, refresh-with-changes, `write`, and `mv` each create a new version. The previous version is preserved.
+- Mutating an existing version is not possible — corrections are new versions.
+
+## When to use this rule
+
+- The user asks to remember, recall, save, or look up something across conversations.
+- You need project-specific context (specs, decisions, transcripts, rendered docs) that's larger than fits in the prompt.
+- You need to ingest a document (PDF, DOCX, HTML, URL) and reason over it.
+- You're producing a summary or decision that should survive past this conversation.
+
+## When NOT to use this rule
+
+- Reading a file the user just pointed at — use the regular file-read tool unless they want it persisted.
+- Storing secrets, credentials, or anything that shouldn't sit in `~/.membot/index.duckdb`.
+- Quick scratch state for the current turn — keep that in the conversation.
+
+## MCP server
+
+`membot serve` exposes the same operations as MCP tools (`membot_add`, `membot_search`, etc.) over stdio (default) or HTTP (`--http <port>`). When connected, prefer the MCP tools over shelling out — they return structured `outputSchema` data with `version_id` echoed on every read.
+
+## Available commands
+
+| Command                               | Purpose                                                                        |
+| ------------------------------------- | ------------------------------------------------------------------------------ |
+| `membot add <source>`                 | Ingest file, directory, glob, URL, or `inline:<text>` (one new version each)   |
+| `membot ls [prefix]`                  | List current files (size, mime, refresh status)                                |
+| `membot tree [prefix]`                | Render the synthesised logical-path tree                                       |
+| `membot read <path>`                  | Read current markdown surrogate (or `--bytes` for original)                    |
+| `membot write <path> --content <txt>` | Write inline agent-authored markdown as a new version                          |
+| `membot search <query>`               | Hybrid search (semantic + BM25); add `--include-history` to search older versions |
+| `membot info <path>`                  | Inspect metadata (source, fetcher, refresh schedule, digests) without content  |
+| `membot versions <path>`              | List every version newest-first with version_id and change notes               |
+| `membot diff <path> --a <ts>`         | Unified diff between two versions                                              |
+| `membot mv <old> <new>`               | Rename a logical_path (history preserved)                                      |
+| `membot rm <path>`                    | Tombstone a logical_path (history still queryable)                             |
+| `membot refresh [path]`               | Re-read source; create new version only if bytes changed                       |
+| `membot prune --before <ts>`          | Permanently drop non-current versions older than cutoff (irreversible)         |
+| `membot serve`                        | Start MCP server (stdio default, `--http <port>` for HTTP)                     |
+| `membot reindex`                      | Rebuild the FTS keyword index over current chunks                              |
+
+## Output formats
+
+- TTY → spinners, colors, tables. `--no-color` disables ANSI.
+- Piped, `--json`, `CI=true`, or `NO_COLOR` → JSON to stdout, structured logs to stderr, no ANSI bytes.
+- Use `--json` when parsing output programmatically (it's automatic when piped, but explicit is safer).
+- Use `--verbose` if a command fails unexpectedly.
+
+## Troubleshooting
+
+- **"ingest failed: unsupported mime"** → Add a converter or pass `--bytes` to keep the original; LLM-fallback only runs when `ANTHROPIC_API_KEY` is set.
+- **"refresh failed: auth"** → The original fetch used an authenticated mcpx tool; re-auth via `mcpx auth <server>`.
+- **Search returns nothing** → Confirm the file ingested with `membot info <path>`; if needed, run `membot reindex` to rebuild the FTS keyword index.
+- **Stale results after manual DB edits** → `membot reindex`.
+- **Two paths point at the same content** → `membot mv` doesn't merge; tombstone one with `membot rm`.
+
+## Configuration
+
+- Data lives in `~/.membot/index.duckdb` (override via `MEMBOT_HOME`).
+- Optional `ANTHROPIC_API_KEY` enables LLM fallback for messy/binary input. Without it, conversion degrades to deterministic native output.
+- Config file: `~/.membot/config.json` (see `membot --help` for the global flags).

package/README.md

@@ -0,0 +1,131 @@
+# membot
+
+> Versioned context store with hybrid search for AI agents. Stdio + HTTP MCP server and CLI.
+
+[![npm](https://img.shields.io/npm/v/membot.svg)](https://www.npmjs.com/package/membot)
+[![license](https://img.shields.io/npm/l/membot.svg)](./LICENSE)
+
+`membot` is a single-binary CLI and MCP server that gives AI agents a persistent, versioned, searchable context store. Files (markdown, PDFs, DOCX, HTML, URLs, agent-authored notes) are ingested, converted to markdown, chunked, embedded **locally** with `@huggingface/transformers` (WASM, no cloud calls), and indexed in DuckDB with hybrid search (semantic vector + BM25). Every change creates a new version — nothing is overwritten in place.
+
+- **Local everything** — embeddings run on your machine; data lives in `~/.membot/index.duckdb`.
+- **One mental model** — every artifact (markdown, PDF, image, audio) becomes a markdown surrogate that flows through the same chunk → embed → search pipeline.
+- **Append-only versioning** — every ingest, refresh, or write creates a new `(logical_path, version_id)` row. History is queryable; nothing is mutated.
+- **Two surfaces, one source of truth** — every operation is exposed identically as a CLI subcommand and an MCP tool. The agent sees `membot_search`; you see `membot search`.
+
+## Install
+
+```bash
+# macOS / Linux — pre-built binary
+curl -fsSL https://raw.githubusercontent.com/evantahler/membot/main/install.sh | bash
+
+# Windows — PowerShell
+iwr -useb https://raw.githubusercontent.com/evantahler/membot/main/install.ps1 | iex
+
+# From npm (requires Bun or Node)
+bun add -g membot
+# or
+npm install -g membot
+```
+
+## Quick start
+
+```bash
+membot add ./docs                        # ingest a directory recursively
+membot add https://example.com/spec.pdf  # ingest a URL (auto-converted to markdown)
+membot ls                                # list current files
+membot search "how does refresh work?"   # hybrid search
+membot read docs/refresh.md              # read the markdown surrogate
+membot serve                             # expose the same operations as MCP tools (stdio)
+```
+
+## Use with Claude Code or Cursor
+
+`membot skill install` drops the agent skill into the right place so Claude Code or Cursor know **when** to call `membot`.
+
+```bash
+membot skill install --claude              # writes ./.claude/skills/membot.md (project)
+membot skill install --cursor              # writes ./.cursor/rules/membot.mdc (project)
+membot skill install --claude --global     # writes ~/.claude/skills/membot.md
+membot skill install --claude --cursor -f  # both, overwrite if present
+```
+
+The skill files describe the discover → ingest → search → read → write workflow and the versioning rules. You can re-run with `--force` to refresh after upgrading membot.
+
+## Commands
+
+| Command                         | Description                                                                       |
+| ------------------------------- | --------------------------------------------------------------------------------- |
+| `membot add <source>`           | Ingest a file, directory, glob, URL, or `inline:<text>`. Each match → new version |
+| `membot ls [prefix]`            | List current files (size, mime, refresh status)                                   |
+| `membot tree [prefix]`          | Render the synthesised logical-path tree                                          |
+| `membot read <path>`            | Read the markdown surrogate (or `--bytes` for original bytes, base64)             |
+| `membot search <query>`         | Hybrid search (semantic + BM25); `--include-history` searches older versions      |
+| `membot info <path>`            | Inspect metadata (source, fetcher, schedule, digests) without content             |
+| `membot versions <path>`        | List every version newest-first                                                   |
+| `membot diff <path> <a> [b]`    | Unified diff between two versions                                                 |
+| `membot write <path>`           | Write inline agent-authored markdown as a new version                             |
+| `membot mv <from> <to>`         | Rename a logical_path (history preserved under both)                              |
+| `membot rm <path>`              | Tombstone a logical_path (history still queryable)                                |
+| `membot refresh [path]`         | Re-read source; new version only if bytes changed                                 |
+| `membot prune --before <ts>`    | Permanently drop non-current versions older than cutoff (irreversible)            |
+| `membot serve`                  | Run the MCP server (stdio default; `--http <port>` for HTTP)                      |
+| `membot reindex`                | Rebuild the FTS keyword index over current chunks                                 |
+| `membot mcpx <subcommand>`      | Forward to the bundled `mcpx` CLI for managing remote MCP servers                 |
+| `membot skill install`          | Install the Claude Code / Cursor agent skill                                      |
+
+Run `membot <command> --help` for full flags and arguments. Every command produces JSON when piped, when `--json` is set, or when `CI=true`.
+
+## MCP server
+
+`membot serve` exposes every operation as an MCP tool. Stdio is the default; pass `--http <port>` for streamable HTTP.
+
+**Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
+
+```json
+{
+  "mcpServers": {
+    "membot": {
+      "command": "membot",
+      "args": ["serve"]
+    }
+  }
+}
+```
+
+**Streamable HTTP** (any MCP client that speaks HTTP):
+
+```bash
+membot serve --http 3000
+# tool endpoint: http://localhost:3000/mcp
+```
+
+Add `--watch` (and optional `--tick <sec>`) to also run the refresh daemon, which re-reads any file whose `refresh_frequency` has elapsed.
+
+## Configuration
+
+- **Data directory:** `~/.membot/` (override with `MEMBOT_HOME=/path` or `--config <path>`).
+  - `~/.membot/index.duckdb` — all content, blobs, chunks, embeddings, and metadata.
+  - `~/.membot/models/` — cached embedding model weights (`Xenova/bge-small-en-v1.5`, 384-dim).
+  - `~/.membot/logs/` — daemon logs when running `serve --watch`.
+- **Config file:** `~/.membot/config.json` (optional; defaults are sane).
+- **Environment variables:**
+  - `ANTHROPIC_API_KEY` — optional. Enables LLM fallback for messy / scanned input (vision captions for images, last-resort markdown conversion). Without it, the pipeline degrades to deterministic native conversion.
+  - `MEMBOT_HOME` — override the data directory.
+  - `NO_COLOR`, `CI`, `FORCE_COLOR` — standard output controls.
+
+## Development
+
+```bash
+bun install
+bun run dev <args>       # run from source
+bun test                 # full test suite (real ephemeral DuckDB per test)
+bun run lint             # biome + tsc
+bun run format           # biome --write
+bun run build            # compile a standalone binary into dist/membot
+```
+
+Architecture, design constraints, and reference projects are documented in [`docs/plan.md`](./docs/plan.md) and [`CLAUDE.md`](./CLAUDE.md).
+
+## License
+
+MIT © Evan Tahler

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "membot",
-	"version": "0.1.0",
+	"version": "0.1.1",
 	"description": "Versioned context store with hybrid search for AI agents. Stdio + HTTP MCP server and CLI.",
 	"type": "module",
 	"exports": {
@@ -16,6 +16,8 @@
 		"src",
 		"patches",
 		"scripts",
+		".claude",
+		".cursor",
 		"README.md",
 		"LICENSE"
 	],
@@ -39,7 +41,7 @@
 		"bun"
 	],
 	"license": "MIT",
-	"author": "Evan Tahler <evan@arcade.dev>",
+	"author": "Evan Tahler <evan@evantahler.com>",
 	"repository": {
 		"type": "git",
 		"url": "https://github.com/evantahler/membot.git"

package/src/cli.ts

@@ -7,6 +7,7 @@ import { registerCheckUpdateCommand } from "./commands/check-update.ts";
 import { registerMcpxCommand } from "./commands/mcpx.ts";
 import { registerReindexCommand } from "./commands/reindex.ts";
 import { registerServeCommand } from "./commands/serve.ts";
+import { registerSkillCommand } from "./commands/skill.ts";
 import { registerUpgradeCommand } from "./commands/upgrade.ts";
 import type { BuildContextOptions } from "./context.ts";
 import { mountAsCommanderCommand } from "./mount/commander.ts";
@@ -57,6 +58,7 @@ for (const op of OPERATIONS) {
 registerServeCommand(program);
 registerReindexCommand(program);
 registerMcpxCommand(program);
+registerSkillCommand(program);
 registerCheckUpdateCommand(program);
 registerUpgradeCommand(program);
 

package/src/commands/skill.ts

@@ -0,0 +1,131 @@
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import type { Command } from "commander";
+import claudeSkill from "../../.claude/skills/membot.md" with { type: "text" };
+import cursorRule from "../../.cursor/rules/membot.mdc" with { type: "text" };
+import { HelpfulError, isHelpfulError, mapKindToExit } from "../errors.ts";
+import { renderCliError } from "../mount/commander.ts";
+import { logger } from "../output/logger.ts";
+import { detectMode, setMode } from "../output/tty.ts";
+
+interface SkillTarget {
+	agentLabel: string;
+	scopeLabel: string;
+	dir: string;
+	filename: string;
+	content: string;
+}
+
+interface SkillInstallOptions {
+	claude?: boolean;
+	cursor?: boolean;
+	global?: boolean;
+	project?: boolean;
+	force?: boolean;
+}
+
+/**
+ * `membot skill install [--claude] [--cursor] [--global|--project] [-f]`
+ *
+ * Drop the membot agent skill into the right location for Claude Code
+ * (`.claude/skills/membot.md`) or Cursor (`.cursor/rules/membot.mdc`),
+ * either in the current project (default) or in the user's home directory
+ * (`--global`). Both flags can be combined to install for both targets at
+ * once. The skill files are bundled into the binary via Bun text imports
+ * so this works in the compiled distribution as well as in `bun run`.
+ */
+export function registerSkillCommand(program: Command): void {
+	const skill = program.command("skill").description("Install agent skills (Claude Code, Cursor)");
+
+	skill
+		.command("install")
+		.description(
+			"Install the membot skill into Claude Code (.claude/skills/membot.md) and/or Cursor (.cursor/rules/membot.mdc)",
+		)
+		.option("--claude", "install for Claude Code")
+		.option("--cursor", "install for Cursor")
+		.option("--global", "install to the user's home directory (default: project)")
+		.option("--project", "install to the current working directory (default)")
+		.option("-f, --force", "overwrite if the skill file already exists")
+		.action((opts: SkillInstallOptions) => {
+			const globalOpts = program.optsWithGlobals<{ json?: boolean; verbose?: boolean; color?: boolean }>();
+			setMode(
+				detectMode({
+					json: globalOpts.json,
+					verbose: globalOpts.verbose,
+					noColor: globalOpts.color === false,
+				}),
+			);
+			try {
+				install(opts);
+			} catch (err) {
+				renderCliError(err);
+				process.exit(isHelpfulError(err) ? mapKindToExit(err.kind) : 1);
+			}
+		});
+}
+
+/**
+ * Resolve and write every requested skill file. Throws `HelpfulError` on
+ * any input or conflict failure so the mount-style error renderer can
+ * surface a uniform JSON / colorized message.
+ */
+function install(opts: SkillInstallOptions): void {
+	if (!opts.claude && !opts.cursor) {
+		throw new HelpfulError({
+			kind: "input_error",
+			message: "no agent target specified",
+			hint: "Pass --claude, --cursor, or both — e.g. `membot skill install --claude`",
+		});
+	}
+
+	const targets = computeTargets(opts);
+	for (const target of targets) {
+		const dest = join(target.dir, target.filename);
+		if (existsSync(dest) && !opts.force) {
+			throw new HelpfulError({
+				kind: "conflict",
+				message: `${dest} already exists`,
+				hint: "Re-run with --force to overwrite",
+			});
+		}
+		mkdirSync(target.dir, { recursive: true });
+		writeFileSync(dest, target.content, "utf-8");
+		logger.info(`installed ${target.agentLabel} skill (${target.scopeLabel}): ${dest}`);
+	}
+}
+
+/**
+ * Materialise the (agent × scope) cartesian product of install targets the
+ * user asked for. Default scope is project when neither --global nor
+ * --project is passed; passing both installs to both locations.
+ */
+function computeTargets(opts: SkillInstallOptions): SkillTarget[] {
+	const scopes: { label: string; resolveDir: (rel: string) => string }[] = [];
+	if (opts.global) scopes.push({ label: "global", resolveDir: (rel) => join(homedir(), rel) });
+	if (opts.project || !opts.global) scopes.push({ label: "project", resolveDir: (rel) => resolve(rel) });
+
+	const targets: SkillTarget[] = [];
+	for (const scope of scopes) {
+		if (opts.claude) {
+			targets.push({
+				agentLabel: "Claude Code",
+				scopeLabel: scope.label,
+				dir: scope.resolveDir(".claude/skills"),
+				filename: "membot.md",
+				content: claudeSkill,
+			});
+		}
+		if (opts.cursor) {
+			targets.push({
+				agentLabel: "Cursor",
+				scopeLabel: scope.label,
+				dir: scope.resolveDir(".cursor/rules"),
+				filename: "membot.mdc",
+				content: cursorRule,
+			});
+		}
+	}
+	return targets;
+}

package/src/ingest/embedder.ts

@@ -31,6 +31,15 @@ function isModelCached(model: string): boolean {
  * Lazily load (and cache) the feature-extraction pipeline for a model. Loading
  * is expensive (downloads weights on first run, ~100s of ms to instantiate
  * ONNX), so we hold one promise per model name for the life of the process.
+ *
+ * Try `wasm` first, fall back to `cpu` on "Unsupported device". The transformers
+ * patch (applied for `bun build --compile` and via `bun run prebuild` for local
+ * dev) registers `wasm` as a supported device backed by onnxruntime-web — that's
+ * mandatory for the single-binary build because native bindings can't be
+ * bundled. When the package is unpatched (npm-installed membot, or `bun dev`
+ * before `prebuild`), `wasm` is rejected and we fall back to the default `cpu`
+ * device, which uses the onnxruntime-node native bindings that ship with the
+ * unpatched package.
  */
 async function getPipeline(model: string): Promise<FeatureExtractionPipeline> {
 	let p = pipelinePromises.get(model);
@@ -40,9 +49,15 @@ async function getPipeline(model: string): Promise<FeatureExtractionPipeline> {
 		} else {
 			logger.info(`embedder: loading model ${model} (first run, downloading weights)`);
 		}
-		// device: "wasm" matches what our transformers patch supports — the
-		// default ("cpu") errors out because the patch removes onnxruntime-node.
-		p = pipeline("feature-extraction", model, { device: "wasm" }) as Promise<FeatureExtractionPipeline>;
+		p = (async () => {
+			try {
+				return (await pipeline("feature-extraction", model, { device: "wasm" })) as FeatureExtractionPipeline;
+			} catch (err) {
+				if (!String((err as Error)?.message ?? "").includes("Unsupported device")) throw err;
+				logger.debug("embedder: wasm backend unavailable, falling back to cpu (onnxruntime-node)");
+				return (await pipeline("feature-extraction", model, { device: "cpu" })) as FeatureExtractionPipeline;
+			}
+		})();
 		pipelinePromises.set(model, p);
 	}
 	return p;

package/src/types/text-modules.d.ts

@@ -0,0 +1,9 @@
+declare module "*.md" {
+	const content: string;
+	export default content;
+}
+
+declare module "*.mdc" {
+	const content: string;
+	export default content;
+}