@krimto-labs/krimto 0.2.6 → 0.2.9

package/README.md

@@ -9,18 +9,21 @@ place and reads the right slice of it — Alice's preferences override the team'
 conventions override the org's standards, and every fact carries a paper trail (author, source,
 timestamp, reviewer).
 
-> **Where we are:** this is the **v0.2** surface. Here today: the markdown-in-git storage layer, the
-> `user → team → org` hierarchy, hybrid retrieval, server-enforced access, two-way git sync, and the
-> MCP server over **both stdio and HTTP — the HTTP transport has `Bearer` API-key auth and
-> `/health` endpoints**. On the near-term roadmap: a single-Docker image and the web UI. We claim the
-> team-memory position now and fulfil it in the open — see [ROADMAP.md](ROADMAP.md).
+> **Where we are:** this is the **v0.2.9** surface. Here today: the markdown-in-git storage layer, the
+> `user → team → org` hierarchy, hybrid retrieval, server-enforced access, two-way git sync, the MCP
+> server over **stdio + HTTP** (Bearer API-key auth on HTTP), a **published multi-arch Docker image**
+> (`ghcr.io/krimto-labs/krimto`), a **web UI** with browse/search/admin/diagnostics, and a complete
+> **CLI** (`serve`, `connect`, `init`, `usage`, `storage`, `setup-remote`, `setup-embeddings`,
+> `verify-connection`, `uninit`, `where`, `--help`). We claim the team-memory position now and fulfil
+> it in the open — see [ROADMAP.md](ROADMAP.md) and [CHANGELOG.md](CHANGELOG.md) for what each release adds.
 
 ## Try it in 2 minutes (solo, no account)
 
-1. **Run it** (data stays in `~/.krimto`):
+1. **Run it** — one command, no clone, no Docker (data stays in `~/.krimto`):
    ```bash
-   docker run -d -p 8080:8080 -v ~/.krimto:/data ghcr.io/krimto-labs/krimto:latest    # or, from a clone: pnpm dev
+   npx @krimto-labs/krimto serve
    ```
+   *Prefer Docker?* `docker run -d -p 8080:8080 -v ~/.krimto:/data ghcr.io/krimto-labs/krimto:latest`
 2. **Point Claude Code at it — one line, no key:**
    ```json
    { "mcpServers": { "krimto": { "url": "http://localhost:8080/mcp" } } }
@@ -28,9 +31,10 @@ timestamp, reviewer).
    (or run `claude mcp add --transport http krimto http://localhost:8080/mcp`)
 3. Tell your agent: **"remember that our staging DB resets every Sunday."** Then ask in a *new* chat:
    **"what do you know about staging?"** — it remembers.
-4. Open **http://localhost:8080** to browse. That's your *personal* layer — Krimto's point is the
-   **team** layer: restart with `KRIMTO_BOOTSTRAP_ADMIN=you@acme.com` to turn on accounts and invite
-   teammates.
+4. Open **http://localhost:8080** to browse. The dashboard shows your facts, a *Status* row (git
+   remote + embeddings health), and a *Recent activity* feed (so you can see your agent calling
+   Krimto in real time). That's the *personal* layer — Krimto's point is the **team** layer:
+   restart with `KRIMTO_BOOTSTRAP_ADMIN=you@acme.com` to turn on accounts and invite teammates.
 
 ## Connect your agent
 
@@ -62,9 +66,20 @@ mode); those are best-effort and not yet individually verified.
 
 ### Make it automatic
 
-By default your agent uses Krimto only when you ask. To make it recall and save **on its own**, add a
-standing rule to your agent's rules file — Claude Code: `CLAUDE.md`; Cursor: `.cursor/rules/krimto.mdc`;
-Codex: `AGENTS.md`; Gemini CLI: `GEMINI.md`:
+By default your agent uses Krimto only when you ask ("use krimto to remember X"). One command, run
+once in your project, makes it call Krimto **on its own** (recall before tasks, write when you say
+"remember"):
+
+```bash
+npx @krimto-labs/krimto init
+```
+
+`init` auto-detects which editor you're using (`.cursor/`, `.claude/`, existing `CLAUDE.md` /
+`AGENTS.md` / `GEMINI.md`, `gemini-extension.json`) and writes the rule only into the files that
+match. Pass `--all` to write to every supported rules file. Change your mind later? Run
+`npx @krimto-labs/krimto uninit` to cleanly strip the rule (and delete files that held only it).
+
+The rule it writes:
 
 ```
 # Krimto memory — always use
@@ -77,6 +92,29 @@ Codex: `AGENTS.md`; Gemini CLI: `GEMINI.md`:
 
 The in-product **Connect** page (`/ui/connect`) shows this same rule with a copy button.
 
+### The CLI surface
+
+Everything is reachable via `npx`. Run `npx @krimto-labs/krimto --help` for the full list. Briefly:
+
+| Command | What it does |
+|---|---|
+| (no args) | Start the stdio MCP server (default; for MCP clients to launch) |
+| `serve` | Start the HTTP server (port 8080) — `/ui` dashboard, no clone, no Docker |
+| `connect` | Print copy-paste Claude Code + Cursor config snippets |
+| `init [--all]` | Switch this project to AUTO MODE — write the always-use rule (auto-detects editor; `--all` writes every file) |
+| `uninit` | Switch back to DEFAULT MODE — remove the rule, delete files it created |
+| `usage` | Show the five `krimto_*` tools with chat examples for both modes |
+| `storage` | Explain where Krimto keeps your data (markdown / git / index), how to verify, optional add-ons |
+| `setup-remote <url>` | Wire the data dir to a git remote and verify the initial push |
+| `setup-embeddings` | Send a real test embedding to verify a `KRIMTO_EMBED_*` config |
+| `verify-connection` | Diagnose "is my agent calling Krimto?" (lock status + last 5 calls) |
+| `where` | Print the data directory |
+| `--help`, `-h` | Show the full CLI surface |
+
+The stdio entrypoint enforces a **single-writer lock** on the data dir (`.krimto/lock.json`) — two
+Krimto processes can no longer race on the same `~/.krimto`. A second `serve`/stdio launch is
+refused with a precise error pointing at the holder's PID.
+
 ## How it works
 
 Three layers, one source of truth:
@@ -128,8 +166,21 @@ OpenClaw, Cline use the same shape):
 ```
 
 The first run downloads dependencies (including `better-sqlite3`, which ships prebuilt binaries), then
-starts the **stdio** server with data in `~/.krimto` (override with `KRIMTO_DATA`). This is the solo
-path; HTTP/team mode uses Docker (Option C) or the server below.
+starts the **stdio** server with data in `~/.krimto` (override with `KRIMTO_DATA`; run
+`npx @krimto-labs/krimto where` to print the exact path). Want the browser dashboard too? Stop the
+stdio process and run `npx @krimto-labs/krimto serve` (Option B) — same data folder, plus `/ui`.
+
+**Make your agent actually use Krimto.** By default an editor's agent routes "remember X" to its own
+built-in memory. Run this once in your project so it calls Krimto instead:
+
+```bash
+npx @krimto-labs/krimto init
+```
+
+It auto-detects which editor you're using and writes the idempotent "always use Krimto" rule into the
+matching rules file (`CLAUDE.md` / `AGENTS.md` / `GEMINI.md` / `.cursor/rules/krimto.mdc`). Pass
+`--all` to write all four. Run `npx @krimto-labs/krimto uninit` to cleanly remove the rule later.
+Restart your editor afterward.
 
 From a clone instead of npm, swap the command for `pnpm`:
 
@@ -148,16 +199,23 @@ From a clone instead of npm, swap the command for `pnpm`:
 `KRIMTO_IDENTITY` is who the agent writes as (fact author + access scope). Stdio mode has **no network
 auth** — run it locally/trusted.
 
-### Option B — over HTTP, with bearer auth (teams)
+### Option B — over HTTP (browser dashboard + optional team auth)
 
-For a shared/networked deployment. Start the HTTP server; the first run prints an admin API key once:
+For solo with a browser UI, or a shared/networked deployment with bearer auth. **No clone, no
+Docker** — `npx` starts the HTTP server (default port 8080):
 
 ```bash
-KRIMTO_HTTP_PORT=8080 KRIMTO_BOOTSTRAP_ADMIN=you@acme.com pnpm dev
+# Solo, local-only (no auth, no login on /ui)
+npx @krimto-labs/krimto serve
+
+# Team mode (first run prints an admin API key once)
+KRIMTO_BOOTSTRAP_ADMIN=you@acme.com npx @krimto-labs/krimto serve
 # → "issued admin API key for you@acme.com (shown once): krm_live_…"
 # MCP at http://localhost:8080/mcp ; health at http://localhost:8080/health/ready
 ```
 
+(`pnpm dev` is the dev-mode equivalent — only useful when working on Krimto itself.)
+
 Then point your agent at it with that key:
 
 ```json
@@ -225,12 +283,25 @@ docker run -d --name krimto -p 8080:8080 \
 
 ### Web UI (humans)
 
-When the HTTP server is running, open `http://localhost:8080/ui` and **sign in with any Krimto API
-key**. You can browse and search the facts you're allowed to see, open a fact, and manage your own API
-keys (issue / revoke). It reuses the same access control as the MCP tools, so you only ever see facts
-you can read. Set `KRIMTO_SESSION_SECRET` to keep sessions valid across restarts (otherwise a random
-per-boot secret is used). The UI is read-only for facts; editing with a review/approval flow lands in
-v0.3.
+When the HTTP server is running, open `http://localhost:8080/ui`. In local mode (no
+`KRIMTO_BOOTSTRAP_ADMIN`), there's no login. In team mode, sign in with any Krimto API key.
+
+The dashboard shows:
+
+- **How Krimto works** — personal → team → org explainer for first-time users.
+- **Behind the scenes — your data, your files** — names the data folder; reminds you it's just
+  markdown in git that you can open in any editor.
+- **Status** — green/gold/red dots for the two optional add-ons (git remote sync; semantic embeddings).
+- **Recent activity** — last 5 MCP tool calls (tool, detail, caller, relative timestamp). Critical
+  for diagnosing "did my agent actually search?" without grepping stderr.
+- **Fact list / detail** — browse and search the facts you're allowed to see; the detail page shows
+  the absolute source-file path so you can open the underlying `.md` in any editor.
+- **API keys** — issue/revoke your own keys (team mode).
+- **Team admin** (`/ui/admin`, org admins only) — add members, manage teams, issue keys for others.
+
+The UI reuses the same access control as the MCP tools — you only ever see what you can read. Set
+`KRIMTO_SESSION_SECRET` to keep sessions valid across restarts (otherwise a random per-boot secret is
+used). The UI is read-only for facts; editing with a review/approval flow lands in v0.3.
 
 ## The eight promises (current status)
 
@@ -240,9 +311,9 @@ v0.3.
 | 2 | Hierarchical scope (`user`/`team`/`org`) as primary primitive | ✓ v0.2 |
 | 3 | Cross-vendor SDK (MCP server + per-marketplace plugins) | ✓ MCP server over stdio + HTTP v0.2; native plugins planned |
 | 4 | Attribution baked into every fact | ✓ v0.2 |
-| 5 | Self-hostable, single Docker | ✓ v0.2 — stdio, HTTP, or **Docker** (`docker build` + `docker run`); a published pull-image is next |
+| 5 | Self-hostable, single Docker | ✓ v0.2 — published multi-arch image at `ghcr.io/krimto-labs/krimto`; also `npx krimto serve` (no Docker needed) and `pnpm dev` |
 | 6 | Apache-2.0 — fully open, no rug-pull | ✓ |
-| 7 | Web interface for humans, on top of git | ✓ minimal v0.2 (`/ui` — login, browse/search, fact detail, API keys); full UI + PR approval in v0.3 |
+| 7 | Web interface for humans, on top of git | ✓ v0.2.8 — `/ui` with browse/search, fact detail (with source-file path), status panel, recent-activity feed, API keys, team admin; full editing + PR approval in v0.3 |
 | 8 | Zero-friction migration between self-hosted and Cloud | ⏳ full flow with v1.0 Cloud (`git clone` works today) |
 
 ## How Krimto compares

package/bin/krimto.mjs

@@ -7,8 +7,124 @@ import process from "node:process";
 import { tsImport } from "tsx/esm/api";
 
 try {
-  const mod = await tsImport("../src/server/index.ts", import.meta.url);
-  await mod.main();
+  const cmd = process.argv[2];
+  if (cmd === "--help" || cmd === "-h" || cmd === "help") {
+    // `krimto --help` — surface every subcommand so a user who didn't read the README can still
+    // discover them. Version is read from the server module so it never drifts from KRIMTO_VERSION.
+    const { formatHelp } = await tsImport("../src/cli/help.ts", import.meta.url);
+    const { KRIMTO_VERSION } = await tsImport("../src/server/index.ts", import.meta.url);
+    process.stdout.write(formatHelp(KRIMTO_VERSION));
+  } else if (cmd === "init") {
+    // `krimto init` — drop the always-use-Krimto rule into this project's agent rules files.
+    // By default, auto-detects the editor (.cursor/, CLAUDE.md, etc.) and writes only matching
+    // files. Pass `--all` to write to every supported rules file regardless of signals.
+    const all = process.argv.slice(3).includes("--all");
+    const { runInit } = await tsImport("../src/cli/init.ts", import.meta.url);
+    const res = await runInit(process.cwd(), { all });
+    if (res.written.length === 0) {
+      const why = res.detected
+        ? `(detected: ${res.considered.join(", ")}). Re-run with --all to also write the others.`
+        : "";
+      process.stderr.write(`krimto: agent rules already up to date — nothing to change. ${why}\n`);
+    } else {
+      const detectionLine = res.detected
+        ? `Detected editor signals in this project — writing only the matching rule files.\n` +
+          `(Run with --all to write all 4 supported rule files instead.)\n\n`
+        : !all
+          ? `No editor signals found — writing all supported rule files. Re-run with --all to\n` +
+            `keep this behavior explicitly, or remove any you don't need with \`krimto uninit\`.\n\n`
+          : "";
+      process.stderr.write(
+        detectionLine +
+          `krimto: wrote the always-use-Krimto rule to:\n  ${res.written.join("\n  ")}\n` +
+          "\n" +
+          "What changed: a short marker-delimited block was added to each file telling your\n" +
+          "agent to call krimto_recall before tasks and krimto_write when you say \"remember\".\n" +
+          "Existing content was preserved; running `init` again is a no-op.\n" +
+          "\n" +
+          "To remove the rule: delete the block between <!-- krimto:start --> and\n" +
+          "<!-- krimto:end --> in each file above. Nothing else in those files will be affected.\n" +
+          "(Or run `krimto uninit` to remove the rule from every file.)\n" +
+          "\n" +
+          "Restart your editor so the rule takes effect.\n",
+      );
+    }
+  } else if (cmd === "uninit") {
+    // `krimto uninit` — remove the always-use-Krimto rule from this project's rules files,
+    // flipping the project back from AUTO MODE to DEFAULT MODE.
+    const { runUninit } = await tsImport("../src/cli/uninit.ts", import.meta.url);
+    const res = await runUninit(process.cwd());
+    if (res.cleaned.length === 0) {
+      process.stderr.write("krimto: no Krimto rule found — nothing to remove.\n");
+    } else {
+      const rewritten = res.cleaned.filter((f) => !res.deleted.includes(f));
+      const lines = ["krimto: removed the always-use-Krimto rule."];
+      if (rewritten.length > 0) lines.push("Rule block stripped (file kept):", ...rewritten.map((f) => `  ${f}`));
+      if (res.deleted.length > 0) lines.push("File deleted (it held only our rule):", ...res.deleted.map((f) => `  ${f}`));
+      lines.push("", "Your project is back in DEFAULT MODE: Krimto tools are still wired up, but");
+      lines.push("your agent will only call them when you explicitly ask.");
+      lines.push("Restart your editor so it picks up the change.");
+      process.stderr.write(lines.join("\n") + "\n");
+    }
+  } else if (cmd === "where") {
+    // `krimto where` — print the data directory (honors KRIMTO_DATA), so files aren't a surprise.
+    const { resolveDataDir } = await tsImport("../src/server/index.ts", import.meta.url);
+    process.stdout.write(`${resolveDataDir()}\n`);
+  } else if (cmd === "setup-remote") {
+    // `krimto setup-remote <url>` — point the data dir's git repo at a remote and verify a push.
+    // Krimto must NOT be running while this is invoked (locks the .git/ index).
+    const url = process.argv[3];
+    if (!url) {
+      process.stderr.write("Usage: krimto setup-remote <git-remote-url>\n  e.g. krimto setup-remote git@github.com:acme/krimto-data.git\n");
+      process.exit(2);
+    }
+    const { runSetupRemote } = await tsImport("../src/cli/setupRemote.ts", import.meta.url);
+    const { resolveDataDir } = await tsImport("../src/server/index.ts", import.meta.url);
+    const result = await runSetupRemote(resolveDataDir(), url);
+    process.stdout.write(result.message + "\n");
+    if (result.status !== "ok") process.exitCode = 1;
+  } else if (cmd === "verify-connection") {
+    // `krimto verify-connection` — read the lockfile + activity JSONL to answer "is my agent
+    // actually calling Krimto right now?" Works from any terminal regardless of how Krimto launched.
+    const { runVerifyConnection } = await tsImport("../src/cli/verifyConnection.ts", import.meta.url);
+    const { resolveDataDir } = await tsImport("../src/server/index.ts", import.meta.url);
+    const result = await runVerifyConnection(resolveDataDir());
+    process.stdout.write(result.message);
+    if (result.status === "none") process.exitCode = 1;
+  } else if (cmd === "setup-embeddings") {
+    // `krimto setup-embeddings` — verify KRIMTO_EMBED_* config by sending one real test embedding,
+    // so the user finds out about a bad key now, not after they've turned embeddings on.
+    const { runSetupEmbeddings } = await tsImport("../src/cli/setupEmbeddings.ts", import.meta.url);
+    const result = await runSetupEmbeddings();
+    process.stdout.write(result.message + "\n");
+    if (result.status !== "ok") process.exitCode = 1;
+  } else if (cmd === "storage") {
+    // `krimto storage` — explain where Krimto keeps data (markdown / git / index) in plain English,
+    // so the "you own your data" half of Krimto's pitch is reachable without reading the README.
+    const { formatStorage } = await tsImport("../src/cli/storage.ts", import.meta.url);
+    const { resolveDataDir } = await tsImport("../src/server/index.ts", import.meta.url);
+    process.stdout.write(formatStorage(resolveDataDir()));
+  } else if (cmd === "serve") {
+    // `krimto serve` — boot the HTTP server (with /ui and /ui/connect) from the npx on-ramp,
+    // so a stranger doesn't have to clone the repo or install Docker just to see the dashboard.
+    // Defaults to port 8080; honors an existing KRIMTO_HTTP_PORT if the caller set one.
+    if (!process.env.KRIMTO_HTTP_PORT) process.env.KRIMTO_HTTP_PORT = "8080";
+    const mod = await tsImport("../src/server/index.ts", import.meta.url);
+    await mod.main();
+  } else if (cmd === "usage") {
+    // `krimto usage` — the long-form guide: the five tools, both modes, copy-paste examples.
+    const { formatUsage } = await tsImport("../src/cli/usage.ts", import.meta.url);
+    const { KRIMTO_VERSION } = await tsImport("../src/server/index.ts", import.meta.url);
+    process.stdout.write(formatUsage(KRIMTO_VERSION));
+  } else if (cmd === "connect") {
+    // `krimto connect` — print stdio connect snippets (the npx on-ramp shape), so a solo user
+    // doesn't have to chase the README. Honors KRIMTO_IDENTITY when set.
+    const { formatConnect } = await tsImport("../src/cli/connect.ts", import.meta.url);
+    process.stdout.write(formatConnect({ identity: process.env.KRIMTO_IDENTITY }));
+  } else {
+    const mod = await tsImport("../src/server/index.ts", import.meta.url);
+    await mod.main();
+  }
 } catch (e) {
   process.stderr.write(`krimto: ${e instanceof Error ? e.message : String(e)}\n`);
   process.exit(1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@krimto-labs/krimto",
-  "version": "0.2.6",
+  "version": "0.2.9",
   "description": "Open-source team memory layer for AI agents — markdown files in git, user/team/org hierarchy, cross-vendor MCP server.",
   "license": "Apache-2.0",
   "type": "module",
@@ -10,7 +10,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/krimto-labs/krimto.git"
+    "url": "git+https://github.com/krimto-labs/krimto.git"
   },
   "homepage": "https://krimto.com",
   "bin": {

package/src/agentRule.ts

@@ -0,0 +1,64 @@
+// The standing "always use Krimto" rule, plus idempotent application to an agent's rules file.
+// Single source of truth for both the CLI (`krimto init`) and the web connect panel — so the
+// rule a user pastes from /ui/connect and the rule `krimto init` writes can never drift.
+//
+// This is the fix for the discovery problem: by default, an editor's agent routes "remember X" to
+// its own built-in memory, not Krimto. Dropping this rule into the agent's rules file makes the
+// agent call krimto_recall / krimto_write on its own.
+
+export const AGENT_RULE = `# Krimto memory — always use
+- Before a task, call krimto_recall to load what we already know.
+- When I say "remember", or you learn a durable fact, call krimto_write
+  (user/me = personal, team/<slug> = shared).
+- Respect precedence: user beats team beats org.
+- Don't save secrets or one-off chatter.`;
+
+const START = "<!-- krimto:start -->";
+const END = "<!-- krimto:end -->";
+
+/** The rule wrapped in stable markers, so it can be found and updated in place later. */
+export function ruleBlock(): string {
+  return `${START}\n${AGENT_RULE}\n${END}`;
+}
+
+/**
+ * Insert or refresh the Krimto rule block in an agent rules file's content, idempotently:
+ * - null/blank existing  → just the block (with a trailing newline)
+ * - existing WITHOUT our markers → append the block, preserving all existing content
+ * - existing WITH our markers    → replace only the marked block, preserving the rest
+ * Re-applying the same rule yields identical content (so callers can detect a no-op).
+ */
+export function applyRule(existing: string | null): string {
+  const block = ruleBlock();
+  if (!existing || existing.trim() === "") return `${block}\n`;
+
+  const startIdx = existing.indexOf(START);
+  const endIdx = existing.indexOf(END);
+  if (startIdx !== -1 && endIdx !== -1 && endIdx > startIdx) {
+    return existing.slice(0, startIdx) + block + existing.slice(endIdx + END.length);
+  }
+
+  const sep = existing.endsWith("\n") ? "\n" : "\n\n";
+  return `${existing}${sep}${block}\n`;
+}
+
+/**
+ * Inverse of `applyRule` — remove the marker-delimited Krimto rule block.
+ * Returns:
+ *   - the original string when no markers are found (caller treats as no-op)
+ *   - the cleaned content (markers + everything between them stripped) otherwise
+ *   - `null` when removing the block leaves the file empty/whitespace-only,
+ *     signalling "delete this file" (it had no pre-existing content)
+ */
+export function removeRule(existing: string | null): string | null {
+  if (existing === null) return null;
+  const startIdx = existing.indexOf(START);
+  const endIdx = existing.indexOf(END);
+  if (startIdx === -1 || endIdx === -1 || endIdx <= startIdx) return existing;
+
+  // Strip the block. Also consume one trailing newline so re-applying doesn't leave a blank gap.
+  const after = endIdx + END.length;
+  const trimmedAfter = after < existing.length && existing[after] === "\n" ? after + 1 : after;
+  const cleaned = existing.slice(0, startIdx) + existing.slice(trimmedAfter);
+  return cleaned.trim() === "" ? null : cleaned;
+}

package/src/cli/connect.ts

@@ -0,0 +1,49 @@
+// `krimto connect` — print the stdio connect snippets so a user on the npx on-ramp doesn't have to
+// dig the README out of a closed browser tab. The shapes come from `stdioConnectSnippets` so this
+// surface and the /ui/connect panel can never drift.
+
+import { stdioConnectSnippets } from "../server/connect";
+
+export interface ConnectOpts {
+  /** Identity to embed in the Cursor env block. Defaults to a generic placeholder. */
+  identity?: string;
+}
+
+/** Build the multi-line, copy-pasteable output `krimto connect` prints to stdout. */
+export function formatConnect(opts: ConnectOpts = {}): string {
+  const { claude, cursorJson } = stdioConnectSnippets(opts);
+  return [
+    "Connect your agent to Krimto (solo, stdio — no key needed):",
+    "",
+    "Claude Code:",
+    `  ${claude}`,
+    "",
+    "Cursor (~/.cursor/mcp.json):",
+    ...cursorJson.split("\n").map((line) => `  ${line}`),
+    "",
+    "What you get after pasting the snippet above:",
+    "  The five Krimto tools (write, recall, read, supersede, list_scopes) are",
+    "  available to your agent — but it only calls them when YOU explicitly ask,",
+    "  e.g. \"use krimto to remember X\" or \"use krimto to recall what we know\".",
+    "",
+    "Want your agent to use Krimto AUTOMATICALLY (recall before tasks, save what",
+    "it learns when you say \"remember\")? Also run this once per project:",
+    "  npx @krimto-labs/krimto init",
+    "",
+    "  Skip `init` if you only want Krimto on-demand. The rule it writes can be",
+    "  removed at any time — `krimto init` will explain how when you run it.",
+    "",
+    "Optional add-ons — add these to the `env` block above if you want them:",
+    '  "KRIMTO_GIT_REMOTE": "git@github.com:acme/krimto-data.git"',
+    "      ↑ pushes every batch to a private git remote (team sync across machines)",
+    "      Set this up safely first: `krimto setup-remote <url>` verifies the push works.",
+    '  "KRIMTO_EMBED_PROVIDER": "openai"',
+    '  "KRIMTO_EMBED_API_KEY":  "sk-..."',
+    "      ↑ turns on semantic / vector search (recall matches paraphrases, not just",
+    "      keywords). Verify the provider works first: `krimto setup-embeddings`.",
+    "  Both are optional — Krimto works fully without them.",
+    "",
+    "For team mode (HTTP + bearer auth), start the server and open /ui/connect.",
+    "",
+  ].join("\n");
+}

package/src/cli/help.ts

@@ -0,0 +1,57 @@
+// `krimto --help` — list every subcommand a user could otherwise only discover by reading the README.
+// Single source of truth so bin/krimto.mjs and any future surface can't drift.
+
+/** Build the help text printed by `krimto --help` / `krimto -h` / `krimto help`. */
+export function formatHelp(version: string): string {
+  return [
+    `krimto — open-source team memory layer for AI coding agents (v${version})`,
+    "",
+    "TWO WAYS TO USE KRIMTO",
+    "  DEFAULT MODE — your agent uses Krimto only when you explicitly ask",
+    '    ("use krimto to remember X" / "use krimto to recall what we know").',
+    "    Setup: paste the `connect` snippet into your editor's MCP config.",
+    "    Want the browser dashboard too? Run `serve` (no Docker / no clone needed).",
+    "",
+    "  AUTO MODE — your agent uses Krimto automatically: recall before tasks,",
+    '    save what it learns when you say "remember".',
+    "    Setup: `connect` (as above), THEN run `init` once in your project.",
+    "    Switch back to DEFAULT MODE at any time with `uninit`.",
+    "",
+    "Usage:",
+    "  npx @krimto-labs/krimto [command]",
+    "",
+    "Commands:",
+    "  (no args)    Start the stdio MCP server (default; for MCP clients to launch)",
+    "  serve        Start the HTTP server (port 8080) — gives you /ui dashboard",
+    "               → use this if you want the browser UI without Docker / pnpm",
+    "  connect      Print copy-paste config snippets for Claude Code & Cursor",
+    "               → use this once per editor / per machine",
+    "  init [--all] Switch this project to AUTO MODE — write the always-use rule",
+    "               → use this once per project (auto-detects your editor; --all = every file)",
+    "  uninit       Switch this project back to DEFAULT MODE — remove the rule",
+    "               → cleanly reverses `init` (deletes files it created)",
+    "  usage        Show the five krimto_* tools and chat examples for both modes",
+    "               → read this AFTER `connect` to learn how to actually use Krimto",
+    "  storage      Explain where Krimto keeps your data (markdown / git / index)",
+    "               → run this to see what's on your disk and what you can edit",
+    "  setup-remote Wire the data dir to a git remote and verify the push works",
+    "               → one-time setup for cross-machine / teammate sync",
+    "  setup-embeddings",
+    "               Verify a KRIMTO_EMBED_* config by sending a real test embedding",
+    "               → one-time check before turning on semantic / vector search",
+    "  verify-connection",
+    "               Diagnose if your agent is actually calling Krimto (live status + last 5 calls)",
+    "               → run this when 'I asked the agent but recall returned nothing'",
+    "  where        Print the Krimto data directory",
+    "  --help, -h   Show this help",
+    "",
+    "Environment:",
+    "  KRIMTO_DATA              Override the data directory (default: ~/.krimto)",
+    "  KRIMTO_IDENTITY          Identity used for writes (default: user@localhost)",
+    "  KRIMTO_HTTP_PORT         Serve MCP over HTTP on this port instead of stdio",
+    "  KRIMTO_BOOTSTRAP_ADMIN   First-admin email — turns on team mode + key auth",
+    "",
+    "Learn more: https://krimto.com · https://github.com/krimto-labs/krimto",
+    "",
+  ].join("\n");
+}

package/src/cli/init.ts

@@ -0,0 +1,110 @@
+// `krimto init` — drop the always-use-Krimto standing rule into a project's agent rules files so the
+// agent actually uses Krimto (fix for the discovery problem). Idempotent and non-destructive: it only
+// adds/refreshes a marker-delimited block, never clobbering other content (see ../agentRule).
+//
+// G4 — by default, init now auto-detects which editor is in use (`.cursor/`, `.claude/`, existing
+// CLAUDE.md / AGENTS.md / GEMINI.md, etc.) and writes ONLY matching files instead of all four. If
+// no signals are present, it falls back to writing all four so a brand-new project still picks up
+// the rule for whichever editor ships next. `--all` keeps the legacy "write everything" behavior.
+
+import { promises as fs } from "node:fs";
+import * as path from "node:path";
+
+import { applyRule } from "../agentRule";
+
+/** The agent rules files `krimto init` targets, relative to the project dir. */
+export const INIT_TARGETS = [
+  "CLAUDE.md",
+  "AGENTS.md",
+  "GEMINI.md",
+  path.join(".cursor", "rules", "krimto.mdc"),
+];
+
+export interface InitResult {
+  /** Relative paths that were created or updated (empty when everything was already current). */
+  written: string[];
+  /** Targets considered (after detection/--all decisions). Exposed for the CLI's success message. */
+  considered: string[];
+  /** True when targets came from auto-detection (some editor signals matched). */
+  detected: boolean;
+}
+
+async function exists(p: string): Promise<boolean> {
+  try {
+    await fs.access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Auto-detect which editor rules files the project should get based on local signals.
+ * Returns the subset of INIT_TARGETS that has a positive signal, OR an empty array when
+ * nothing matches (caller falls back to writing everything).
+ */
+export async function detectEditorTargets(cwd: string): Promise<string[]> {
+  const matches: string[] = [];
+
+  // CLAUDE.md — Claude Code
+  if ((await exists(path.join(cwd, "CLAUDE.md"))) || (await exists(path.join(cwd, ".claude"))) || (await exists(path.join(cwd, ".claude-plugin")))) {
+    matches.push("CLAUDE.md");
+  }
+  // AGENTS.md — Codex CLI / generic
+  if (await exists(path.join(cwd, "AGENTS.md"))) {
+    matches.push("AGENTS.md");
+  }
+  // GEMINI.md — Gemini CLI
+  if ((await exists(path.join(cwd, "GEMINI.md"))) || (await exists(path.join(cwd, "gemini-extension.json"))) || (await exists(path.join(cwd, ".gemini")))) {
+    matches.push("GEMINI.md");
+  }
+  // .cursor/rules/krimto.mdc — Cursor
+  if (await exists(path.join(cwd, ".cursor"))) {
+    matches.push(path.join(".cursor", "rules", "krimto.mdc"));
+  }
+
+  return matches;
+}
+
+export interface RunInitOptions {
+  /** Force writing all four files regardless of detection (the legacy behavior). */
+  all?: boolean;
+  /** Override the target list directly (tests; takes precedence over `all` + detection). */
+  targets?: string[];
+}
+
+/** Write/refresh the Krimto standing rule into each target rules file under `cwd`, idempotently. */
+export async function runInit(cwd: string, opts: RunInitOptions = {}): Promise<InitResult> {
+  let targets: string[];
+  let detected = false;
+  if (opts.targets) {
+    targets = opts.targets;
+  } else if (opts.all) {
+    targets = INIT_TARGETS;
+  } else {
+    const auto = await detectEditorTargets(cwd);
+    if (auto.length > 0) {
+      targets = auto;
+      detected = true;
+    } else {
+      targets = INIT_TARGETS;
+    }
+  }
+
+  const written: string[] = [];
+  for (const rel of targets) {
+    const file = path.join(cwd, rel);
+    let existing: string | null = null;
+    try {
+      existing = await fs.readFile(file, "utf8");
+    } catch {
+      existing = null; // file doesn't exist yet — we'll create it
+    }
+    const next = applyRule(existing);
+    if (next === existing) continue; // already up to date
+    await fs.mkdir(path.dirname(file), { recursive: true });
+    await fs.writeFile(file, next, "utf8");
+    written.push(rel);
+  }
+  return { written, considered: targets, detected };
+}