@jbarket/loomai 0.5.0 → 0.6.0

package/dist/cli/person.js

@@ -0,0 +1,116 @@
+/**
+ * loom person — read person cards (docs/specs/person-cards.md).
+ *
+ *   loom person show <slug> [--include-archived] [--json]
+ *   loom person list [--include-archived] [--json]
+ *
+ * Read-only: cards are written through the MCP tools. Exit codes for show:
+ * 0 found, 3 no such card, 4 archived (without --include-archived), 1 error.
+ * A bridge can splice `show` output into a prompt and treat any non-zero
+ * exit as "no card".
+ */
+import { parseArgs } from 'node:util';
+import { readPerson, listPeople } from '../tools/person.js';
+import { assertStackVersionCompatible } from '../config.js';
+import { extractGlobalFlags, resolveEnv } from './args.js';
+import { renderJson } from './io.js';
+const USAGE = `Usage: loom person <subcommand> [options]
+
+Subcommands:
+  show <slug>   Print the rendered card (or the person result with --json)
+  list          List cards: slug, name, freshness counts, memories since synthesis
+
+Options:
+  --include-archived   Show/list archived cards too
+  --json               Machine-readable output
+
+Exit codes (show): 0 found, 3 no such card, 4 archived, 1 error.
+`;
+export async function run(argv, io) {
+    const { flags: global, rest } = extractGlobalFlags(argv);
+    const sub = rest[0];
+    if (!sub || sub === '--help' || sub === '-h') {
+        io.stdout(USAGE);
+        return sub ? 0 : 2;
+    }
+    if (sub !== 'show' && sub !== 'list') {
+        io.stderr(`Unknown person subcommand: ${sub}\n${USAGE}`);
+        return 2;
+    }
+    let parsed;
+    try {
+        parsed = parseArgs({
+            args: rest.slice(1),
+            options: { 'include-archived': { type: 'boolean' }, help: { type: 'boolean', short: 'h' } },
+            allowPositionals: true,
+        });
+    }
+    catch (err) {
+        io.stderr(`${err.message}\n${USAGE}`);
+        return 2;
+    }
+    if (parsed.values.help) {
+        io.stdout(USAGE);
+        return 0;
+    }
+    const env = resolveEnv(global, io.env);
+    try {
+        assertStackVersionCompatible(env.contextDir);
+    }
+    catch (err) {
+        io.stderr(`${err.message}\n`);
+        return 1;
+    }
+    const includeArchived = Boolean(parsed.values['include-archived']);
+    if (sub === 'list') {
+        if (parsed.positionals.length) {
+            io.stderr(`person list takes no arguments.\n${USAGE}`);
+            return 2;
+        }
+        const entries = listPeople(env.contextDir, includeArchived);
+        if (env.json) {
+            renderJson(io, entries);
+            return 0;
+        }
+        io.stdout(entries.length === 0
+            ? 'no person cards\n'
+            : entries
+                .map((e) => `${e.slug}\t${e.name}${e.archived ? ' [archived]' : ''}\tupdated ${e.updated}\t` +
+                `synthesized ${e.synthesized_at ?? 'never'}\tstale ${e.stale}\tunverified ${e.unverified}\t` +
+                `memories since synthesis ${e.memories_since_synthesis}`)
+                .join('\n') + '\n');
+        return 0;
+    }
+    const slug = parsed.positionals[0];
+    if (!slug || parsed.positionals.length > 1) {
+        io.stderr(`person show takes one slug.\n${USAGE}`);
+        return 2;
+    }
+    let result;
+    try {
+        result = readPerson(env.contextDir, slug, includeArchived);
+    }
+    catch (err) {
+        io.stderr(`${err.message}\n`);
+        return 1;
+    }
+    if (!result.found) {
+        if (env.json)
+            renderJson(io, result);
+        else
+            io.stderr(`no card for ${slug}\n`);
+        return 3;
+    }
+    if (!('rendered' in result)) {
+        if (env.json)
+            renderJson(io, result);
+        else
+            io.stderr(`card for ${slug} is archived (pass --include-archived)\n`);
+        return 4;
+    }
+    if (env.json)
+        renderJson(io, result);
+    else
+        io.stdout(result.rendered + '\n');
+    return 0;
+}

package/dist/cli/recall.js

@@ -13,7 +13,8 @@ Search memories semantically.
 
 Options:
   --category <name>      Filter by category
-  --project <name>       Filter by project
+  --project <name>       Scope to a project — excludes other projects' project-scoped
+                          memories (t-337); global-scoped memories still come through
   --limit <n>            Max results (default backend-specific)
   --diversity <f>        MMR diversity 0..1 (default 0.3); 0 = pure relevance order
   --json                 Emit MemoryMatch[] as JSON

package/dist/cli/remember.js

@@ -14,6 +14,9 @@ Body is read from stdin (when piped) or $EDITOR (when interactive).
 Options:
   --category <name>      Category: user|project|self|feedback|reference|pursuit (default: reference)
   --project <name>       Project tag
+  --scope <project|global>  Override recall visibility (default: category default — see
+                          backends/scope.ts; "global" for a fact that applies regardless
+                          of which project it was learned on)
   --ttl <dur>            TTL like "7d", "30d", or "permanent"
   --refs <csv>           Comma-separated reference refs stored in metadata
   --meta <json>          JSON object merged into metadata (e.g. '{"where":"voice"}')
@@ -30,6 +33,7 @@ export async function run(argv, io) {
             options: {
                 category: { type: 'string' },
                 project: { type: 'string' },
+                scope: { type: 'string' },
                 ttl: { type: 'string' },
                 refs: { type: 'string' },
                 meta: { type: 'string' },
@@ -57,6 +61,11 @@ export async function run(argv, io) {
         io.stderr(`Unknown category "${category}". Valid categories: ${MEMORY_CATEGORIES.join(', ')}.\n`);
         return 2;
     }
+    const scope = parsed.values.scope;
+    if (scope !== undefined && scope !== 'project' && scope !== 'global') {
+        io.stderr(`--scope must be "project" or "global".\n`);
+        return 2;
+    }
     const env = resolveEnv(global, io.env);
     try {
         assertStackVersionCompatible(env.contextDir);
@@ -99,6 +108,7 @@ export async function run(argv, io) {
         title,
         content: body,
         project: parsed.values.project,
+        scope,
         ttl: parsed.values.ttl,
         metadata,
     });

package/dist/cli/remote.d.ts

@@ -0,0 +1,36 @@
+import type { IOStreams } from './io.js';
+export declare const REMOTE_VERBS: ReadonlySet<string>;
+/**
+ * `memory` subcommands with no MCP equivalent: recompute-salience rewrites
+ * every row's salience, and recall-stats returns other callers' query text.
+ * The consolidation lane runs them where the stack is.
+ */
+export declare const LOCAL_MEMORY_SUBCOMMANDS: ReadonlySet<string>;
+/** POST /cli request body. */
+export interface CliRequest {
+    argv: string[];
+    /** The body for verbs that read one (remember, update). */
+    stdin?: string;
+    /** Harness hints only; the server owns everything else in its env. */
+    env?: {
+        LOOM_CLIENT?: string;
+        LOOM_MODEL?: string;
+    };
+}
+/** POST /cli 200 response body. */
+export interface CliResponse {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+}
+/**
+ * The /cli endpoint beside the MCP URL: http://h:8787/mcp → http://h:8787/cli,
+ * and a proxy prefix is kept (https://h/loom/mcp → https://h/loom/cli). A URL
+ * without /mcp is taken as the server's base (http://h:8787 → /cli).
+ */
+export declare function cliEndpoint(url: string): URL;
+/**
+ * Run `sub` with `rest` (the argv minus the subcommand token, globals
+ * included) on the loom-http at `url`.
+ */
+export declare function runRemote(sub: string, rest: string[], url: string, io: IOStreams): Promise<number>;

package/dist/cli/remote.js

@@ -0,0 +1,173 @@
+/**
+ * Remote mode — run a CLI verb against a loom-http server instead of a
+ * local stack (t-1472).
+ *
+ * A body whose loom lives elsewhere (a container, another host) still has
+ * hooks and scripts that shell out to `loom recall`, `loom remember --json`,
+ * `loom person show`. With `--url` or LOOM_URL set, those verbs ship their
+ * argv (and stdin body) to loom-http's POST /cli, which runs the SAME CLI
+ * server-side against its own stack and returns stdout, stderr and the exit
+ * code. Output, --json shapes and exit codes match the local CLI by
+ * construction, not by a second implementation that could drift.
+ *
+ * The server's half is src/transport/cli-endpoint.ts. Only REMOTE_VERBS
+ * travel: the ones that read or write the stores, every one of which the
+ * MCP tools already expose under the same bearer token, so /cli grants
+ * nothing /mcp doesn't. Two `memory` subcommands have no MCP tool and stay
+ * local too (LOCAL_MEMORY_SUBCOMMANDS). Verbs about the local machine (inject, install,
+ * doctor, serve, bootstrap, migrate, harness, update-identity) always run
+ * locally.
+ *
+ * The bearer token comes from a file (LOOM_TOKEN_FILE), never argv, so it
+ * stays out of `ps` and shell history.
+ */
+import { readFile } from 'node:fs/promises';
+import { readBody } from './io.js';
+export const REMOTE_VERBS = new Set([
+    'wake', 'recall', 'remember', 'update', 'forget', 'memory', 'knowledge', 'person',
+]);
+/**
+ * `memory` subcommands with no MCP equivalent: recompute-salience rewrites
+ * every row's salience, and recall-stats returns other callers' query text.
+ * The consolidation lane runs them where the stack is.
+ */
+export const LOCAL_MEMORY_SUBCOMMANDS = new Set(['recompute-salience', 'recall-stats']);
+const REMOTE_TIMEOUT_MS = 300_000;
+/** `argv` with every `--url <value>` pair removed. */
+function withoutUrl(argv) {
+    const out = [];
+    for (let i = 0; i < argv.length; i++) {
+        if (argv[i] === '--url') {
+            i++;
+            continue;
+        }
+        out.push(argv[i]);
+    }
+    return out;
+}
+/**
+ * Whether the local CLI would read a body for this call. Mirrors the verbs'
+ * own rules (remember always; update unless it's a pure --confirm or
+ * --contradict observation; neither under --help). Reading stdin for any other verb would hang a caller whose stdin
+ * is an open pipe it never writes to.
+ */
+function readsBody(sub, argv) {
+    if (argv.includes('--help') || argv.includes('-h'))
+        return false;
+    if (sub === 'remember')
+        return true;
+    if (sub === 'update')
+        return !argv.some((a) => /^--(confirm|contradict)(=|$)/.test(a));
+    return false;
+}
+/**
+ * The /cli endpoint beside the MCP URL: http://h:8787/mcp → http://h:8787/cli,
+ * and a proxy prefix is kept (https://h/loom/mcp → https://h/loom/cli). A URL
+ * without /mcp is taken as the server's base (http://h:8787 → /cli).
+ */
+export function cliEndpoint(url) {
+    const u = new URL(url);
+    const base = u.pathname.replace(/\/+$/, '').replace(/\/mcp$/, '');
+    u.pathname = `${base}/cli`;
+    u.search = '';
+    u.hash = '';
+    return u;
+}
+function isCliResponse(v) {
+    const r = v;
+    return typeof r === 'object' && r !== null &&
+        Number.isInteger(r.exitCode) && typeof r.stdout === 'string' && typeof r.stderr === 'string';
+}
+/**
+ * Run `sub` with `rest` (the argv minus the subcommand token, globals
+ * included) on the loom-http at `url`.
+ */
+export async function runRemote(sub, rest, url, io) {
+    const args = withoutUrl(rest);
+    if (args.some((a) => a === '--context-dir' || a.startsWith('--context-dir='))) {
+        io.stderr(`loom: --context-dir names a local stack, but this call goes to ${url}. ` +
+            `Drop --url / unset LOOM_URL to use the local one.\n`);
+        return 2;
+    }
+    let endpoint;
+    try {
+        endpoint = cliEndpoint(url);
+    }
+    catch {
+        io.stderr(`loom: not a URL: ${url}\n`);
+        return 2;
+    }
+    const headers = { 'content-type': 'application/json' };
+    const tokenFile = io.env.LOOM_TOKEN_FILE;
+    if (tokenFile) {
+        let token;
+        try {
+            token = (await readFile(tokenFile, 'utf-8')).trim();
+        }
+        catch (err) {
+            io.stderr(`loom: can't read LOOM_TOKEN_FILE: ${err.message}\n`);
+            return 1;
+        }
+        headers.authorization = `Bearer ${token}`;
+    }
+    const request = { argv: [sub, ...args] };
+    if (readsBody(sub, args)) {
+        // Local stdin or the local $EDITOR: an editor can't run over the wire.
+        try {
+            request.stdin = await readBody(io, sub);
+        }
+        catch (err) {
+            io.stderr(`${err.message}\n`);
+            return 1;
+        }
+    }
+    const hints = {};
+    if (io.env.LOOM_CLIENT)
+        hints.LOOM_CLIENT = io.env.LOOM_CLIENT;
+    if (io.env.LOOM_MODEL)
+        hints.LOOM_MODEL = io.env.LOOM_MODEL;
+    if (Object.keys(hints).length)
+        request.env = hints;
+    let res;
+    try {
+        res = await fetch(endpoint, {
+            method: 'POST',
+            headers,
+            body: JSON.stringify(request),
+            signal: AbortSignal.timeout(REMOTE_TIMEOUT_MS),
+        });
+    }
+    catch (err) {
+        const cause = err.cause?.message;
+        io.stderr(`loom: can't reach ${endpoint}: ${cause ?? err.message}\n`);
+        return 1;
+    }
+    const text = await res.text();
+    if (res.status !== 200) {
+        let message = text;
+        try {
+            message = JSON.parse(text).error ?? text;
+        }
+        catch { /* not JSON */ }
+        if (res.status === 404)
+            message = `no CLI endpoint at ${endpoint} (an older loom-http, or a knowledge-only server)`;
+        io.stderr(`loom: ${endpoint} answered ${res.status}: ${message}\n`);
+        return res.status === 400 ? 2 : 1;
+    }
+    let out;
+    try {
+        out = JSON.parse(text);
+    }
+    catch {
+        io.stderr(`loom: ${endpoint} sent a response that isn't JSON\n`);
+        return 1;
+    }
+    // A malformed answer must never read as success (a missing exitCode would exit 0).
+    if (!isCliResponse(out)) {
+        io.stderr(`loom: ${endpoint} sent a malformed CLI response\n`);
+        return 1;
+    }
+    io.stdout(out.stdout);
+    io.stderr(out.stderr);
+    return out.exitCode;
+}

package/dist/cli/serve.d.ts

@@ -1,2 +1,9 @@
 import type { IOStreams } from './io.js';
+/**
+ * Parse "identity:token,identity:token" into a token → identity map ready
+ * for startHttpServer's `tokens` option (checkBearerMulti). Throws with a
+ * message naming the offending pair on malformed input — fail loud at CLI
+ * startup rather than silently dropping an identity.
+ */
+export declare function parseIdentityTokens(raw: string): Record<string, string>;
 export declare function run(argv: string[], io: IOStreams): Promise<number>;

package/dist/cli/serve.js

@@ -4,10 +4,19 @@
  * optional bearer token. Host/port/token come from flags or env:
  *   --http  --host <h>  --port <n>   (LOOM_HTTP_HOST, LOOM_HTTP_PORT, LOOM_BEARER_TOKEN)
  * Bind-safety refuses a public/0.0.0.0 host; Tailscale is the access control.
+ *
+ * `--scope knowledge` (t-677) starts the standalone knowledge-only service
+ * instead of the full server — same transport, tailscale-bind-safety, and
+ * bearer-gating pattern, but the MCP tool surface is knowledge_* only and
+ * auth is per-identity (LOOM_KNOWLEDGE_BEARER_TOKENS, "identity:token,...")
+ * so the acting identity is derivable server-side for attribution. It is
+ * NOT started by default and ships disabled — nothing in this repo enables
+ * or deploys it; standing it up is a separate, deliberate operational step.
  */
 import { parseArgs } from 'node:util';
-import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { StdioServerTransport } from '@modelcontextprotocol/server/stdio';
 import { createLoomServer } from '../server.js';
+import { createKnowledgeOnlyServer } from '../transport/knowledge-server.js';
 import { startHttpServer } from '../transport/http-server.js';
 import { resolveContextDir } from '../config.js';
 const USAGE = `Usage: loom serve [options]
@@ -17,12 +26,49 @@ mesh-reachable HTTP daemon instead.
 
 Options:
   --http                 Serve over HTTP instead of stdio
+  --scope <full|knowledge>  Tool surface for --http (default full);
+                         knowledge without --http is rejected
   --host <h>             HTTP bind host (env LOOM_HTTP_HOST, default 127.0.0.1)
-  --port <n>             HTTP port (env LOOM_HTTP_PORT, default 8787)
+  --port <n>             HTTP port (env LOOM_HTTP_PORT, or LOOM_KNOWLEDGE_HTTP_PORT
+                         for --scope knowledge, default 8787 / 8788)
   --help, -h             Show this help
 
-Bearer token comes from LOOM_BEARER_TOKEN. Bind-safety refuses a public host.
+--scope full (default): bearer token from LOOM_BEARER_TOKEN.
+--scope knowledge: per-identity bearer from LOOM_KNOWLEDGE_BEARER_TOKENS,
+  format "identity:token,identity:token" — e.g. "art:abc123,mark:def456".
+  Required and non-empty; the knowledge-only service refuses to boot without
+  at least one identity configured. Registers knowledge_* tools only — no
+  identity/memory/dossier tools on this surface.
+
+Bind-safety refuses a public host in both scopes.
 `;
+/**
+ * Parse "identity:token,identity:token" into a token → identity map ready
+ * for startHttpServer's `tokens` option (checkBearerMulti). Throws with a
+ * message naming the offending pair on malformed input — fail loud at CLI
+ * startup rather than silently dropping an identity.
+ */
+export function parseIdentityTokens(raw) {
+    const tokens = {};
+    const pairs = raw.split(',');
+    for (let i = 0; i < pairs.length; i++) {
+        const trimmed = pairs[i].trim();
+        if (!trimmed)
+            continue;
+        const idx = trimmed.indexOf(':');
+        const identity = idx > 0 ? trimmed.slice(0, idx).trim() : '';
+        const token = idx > 0 ? trimmed.slice(idx + 1).trim() : '';
+        if (!identity || !token) {
+            // Never echo `trimmed` — a malformed pair is exactly the shape a
+            // pasted-without-colon secret takes, and this error can land in
+            // stderr/journal/CI logs. Report position only, never content.
+            throw new Error(`malformed identity:token pair at position ${i + 1} — expected "identity:token", ` +
+                `got ${identity ? 'an identity with no token' : 'no identity'} (value withheld from this error)`);
+        }
+        tokens[identity] = token;
+    }
+    return tokens;
+}
 export async function run(argv, io) {
     let values;
     try {
@@ -30,6 +76,7 @@ export async function run(argv, io) {
             args: argv,
             options: {
                 http: { type: 'boolean', default: false },
+                scope: { type: 'string', default: 'full' },
                 host: { type: 'string' },
                 port: { type: 'string' },
                 help: { type: 'boolean', short: 'h' },
@@ -46,19 +93,61 @@ export async function run(argv, io) {
         io.stdout(USAGE);
         return 0;
     }
+    if (values.scope !== 'full' && values.scope !== 'knowledge') {
+        io.stderr(`Unknown --scope "${values.scope}" — expected "full" or "knowledge".\n${USAGE}`);
+        return 2;
+    }
+    // The knowledge-only surface exists only as an HTTP service. Without
+    // --http the stdio branch below would open the FULL server — every
+    // identity/memory/dossier tool — under a flag that asked for less
+    // (PR #124 review). Refuse before any transport opens.
+    if (values.scope === 'knowledge' && !values.http) {
+        io.stderr(`--scope knowledge requires --http — the knowledge-only surface is HTTP-only; ` +
+            `refusing to start the full stdio server instead.\n${USAGE}`);
+        return 2;
+    }
     const contextDir = resolveContextDir();
+    // Optional: gaps directory for recall-miss logging (LOOM_GAPS_DIR env var).
+    // When set, knowledge_recall misses are appended to ${gapsDir}/recall-miss.jsonl
+    // so the knowledge-mine script can surface them as expansion candidates.
+    const gapsDir = process.env.LOOM_GAPS_DIR || undefined;
+    if (values.http && values.scope === 'knowledge') {
+        const host = values.host ?? process.env.LOOM_HTTP_HOST ?? '127.0.0.1';
+        const port = Number(values.port ?? process.env.LOOM_KNOWLEDGE_HTTP_PORT ?? 8788);
+        const rawTokens = process.env.LOOM_KNOWLEDGE_BEARER_TOKENS ?? '';
+        let tokens;
+        try {
+            tokens = parseIdentityTokens(rawTokens);
+        }
+        catch (err) {
+            io.stderr(`${err.message}\n${USAGE}`);
+            return 2;
+        }
+        if (Object.keys(tokens).length === 0) {
+            io.stderr(`--scope knowledge requires LOOM_KNOWLEDGE_BEARER_TOKENS ` +
+                `("identity:token,identity:token") — refusing to start unauthenticated.\n${USAGE}`);
+            return 2;
+        }
+        const handle = await startHttpServer({
+            contextDir, host, port, tokens, gapsDir, createServer: createKnowledgeOnlyServer,
+        });
+        io.stderr(`loom: knowledge-only HTTP MCP daemon on http://${handle.host}:${handle.port} ` +
+            `(per-identity bearer: ${Object.keys(tokens).join(', ')})\n`);
+        await new Promise(() => { });
+        return 0;
+    }
     if (values.http) {
         const host = values.host ?? process.env.LOOM_HTTP_HOST ?? '127.0.0.1';
         const port = Number(values.port ?? process.env.LOOM_HTTP_PORT ?? 8787);
         const token = process.env.LOOM_BEARER_TOKEN || undefined;
-        const handle = await startHttpServer({ contextDir, host, port, token });
+        const handle = await startHttpServer({ contextDir, host, port, token, gapsDir });
         io.stderr(`loom: HTTP MCP daemon on http://${handle.host}:${handle.port} ` +
             `(${token ? 'bearer-gated' : 'open — network is the boundary'})\n`);
         // Hold open until the process is signalled.
         await new Promise(() => { });
         return 0;
     }
-    const { server } = createLoomServer({ contextDir });
+    const { server } = createLoomServer({ contextDir, gapsDir });
     const transport = new StdioServerTransport();
     await server.connect(transport);
     // connect() resolves when the stdio transport STARTS, not when it closes.

package/dist/cli/subcommands.d.ts

@@ -3,5 +3,5 @@
  * (src/cli/index.ts) and the CLI-vs-MCP routing gate (src/index.ts) so
  * the set never drifts between entry points.
  */
-export declare const SUBCOMMANDS: readonly ['wake', 'recall', 'remember', 'forget', 'update', 'memory', 'knowledge', 'update-identity', 'bootstrap', 'serve', 'inject', 'harness', 'install', 'doctor', 'migrate'];
+export declare const SUBCOMMANDS: readonly ['wake', 'recall', 'remember', 'forget', 'update', 'memory', 'knowledge', 'person', 'update-identity', 'bootstrap', 'serve', 'inject', 'harness', 'install', 'doctor', 'migrate'];
 export type Subcommand = typeof SUBCOMMANDS[number];

package/dist/cli/subcommands.js

@@ -5,7 +5,7 @@
  */
 export const SUBCOMMANDS = [
     'wake', 'recall', 'remember', 'forget', 'update',
-    'memory', 'knowledge', 'update-identity', 'bootstrap', 'serve',
+    'memory', 'knowledge', 'person', 'update-identity', 'bootstrap', 'serve',
     'inject', 'harness',
     'install', 'doctor', 'migrate',
 ];

package/dist/cli/update.js

@@ -11,11 +11,14 @@ const USAGE = `Usage: loom update <ref> [options]
        loom update --category <cat> --title <exact> [options]
 
 Updates content (from stdin or \$EDITOR) and/or metadata on an existing
-memory.
+memory. --confirm/--contradict record an observation against a feedback
+memory's confidence instead — no body required for those.
 
 Options:
   --category <name>      Identify by category (with --title)
   --title <exact>        Identify by title (with --category)
+  --confirm               Feedback memories only: raise confidence (+0.05)
+  --contradict            Feedback memories only: lower confidence (-0.1)
   --json                 Emit UpdateResult
   --context-dir <path>   Agent context dir
   --help, -h             Show this help
@@ -29,6 +32,8 @@ export async function run(argv, io) {
             options: {
                 category: { type: 'string' },
                 title: { type: 'string' },
+                confirm: { type: 'boolean' },
+                contradict: { type: 'boolean' },
                 help: { type: 'boolean', short: 'h' },
             },
             strict: true,
@@ -49,6 +54,15 @@ export async function run(argv, io) {
         io.stderr(`Provide a <ref> or --category+--title.\n${USAGE}`);
         return 2;
     }
+    if (parsed.values.confirm && parsed.values.contradict) {
+        io.stderr(`--confirm and --contradict are mutually exclusive.\n${USAGE}`);
+        return 2;
+    }
+    const observation = parsed.values.confirm
+        ? 'confirm'
+        : parsed.values.contradict
+            ? 'contradict'
+            : undefined;
     const env = resolveEnv(global, io.env);
     try {
         assertStackVersionCompatible(env.contextDir);
@@ -57,23 +71,28 @@ export async function run(argv, io) {
         io.stderr(`${err.message}\n`);
         return 1;
     }
+    // A pure observation needs no new body — --confirm/--contradict alone is a
+    // complete update. Any other call still requires one (existing behavior).
     let body;
-    try {
-        body = await readBody(io, 'update');
-    }
-    catch (err) {
-        io.stderr(`${err.message}\n`);
-        return 1;
-    }
-    if (!body) {
-        io.stderr(`body cannot be empty\n`);
-        return 2;
+    if (!observation) {
+        try {
+            body = await readBody(io, 'update');
+        }
+        catch (err) {
+            io.stderr(`${err.message}\n`);
+            return 1;
+        }
+        if (!body) {
+            io.stderr(`body cannot be empty\n`);
+            return 2;
+        }
     }
     const input = {
         ref,
         category: parsed.values.category,
         title: parsed.values.title,
         content: body,
+        observation,
     };
     if (env.json) {
         const backend = createBackend(env.contextDir);

package/dist/clients.js

@@ -14,17 +14,20 @@
 import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { assertSafePathSegment } from './path-safety.js';
+import { INSTALL_TARGETS } from './install/harnesses.js';
 // ─── Tool list ────────────────────────────────────────────────────────────────
 // Canonical tool names — used to generate the prefix-specific list per client
 export const TOOLS = [
     'identity', 'dossier', 'remember', 'recall', 'update', 'forget',
     'memory_list', 'memory_prune', 'find_similar', 'memory_audit', 'episodes',
-    'memory_archive', 'memory_restore',
+    'memory_archive', 'memory_restore', 'memory_merge', 'memory_history', 'memory_revision_restore',
     'memory_propose', 'memory_proposals', 'memory_ratify', 'memory_reject',
     'update_identity', 'bootstrap', 'harness_init', 'harness_describe',
     'knowledge_write', 'knowledge_recall', 'knowledge_maintain',
     'knowledge_archive', 'knowledge_restore', 'knowledge_supersede', 'knowledge_move', 'knowledge_merge',
     'knowledge_purge', 'knowledge_verify', 'knowledge_history',
+    'person_write', 'person_verify', 'person_archive', 'person_restore',
+    'person', 'person_list', 'person_history', 'person_revision_restore',
 ];
 function toolList(prefix) {
     return TOOLS.map((t) => `\`${prefix}${t}\``).join(', ');
@@ -34,11 +37,11 @@ const ADAPTERS = {
     'claude-code': `## Runtime: Claude Code
 
 You are running in Claude Code (Anthropic CLI). Loom tools use double-underscore prefix:
-${toolList('mcp__loom__')}`,
+${toolList(INSTALL_TARGETS['claude-code'].toolPrefix)}`,
     'gemini-cli': `## Runtime: Gemini CLI
 
-You are running in Gemini CLI (Google). Loom tools use double-underscore prefix:
-${toolList('mcp__loom__')}`,
+You are running in Gemini CLI (Google). Loom tools use single-underscore prefix:
+${toolList(INSTALL_TARGETS['gemini-cli'].toolPrefix)}`,
 };
 // ─── Loader ──────────────────────────────────────────────────────────────────
 export function getBuiltInAdapter(client) {