open-memex 0.3.0 → 0.4.0-alpha.10

package/dist/cli.js

@@ -6,15 +6,213 @@ import { syncScope, upsertFromFile, deleteFromIndex } from "./store/sync.js";
 import { migrateScope, scopeHasFiles } from "./store/migrate.js";
 import { migrateV2 } from "./store/v2migrate.js";
 import { findDuplicates, supersede, setStatus } from "./store/lifecycle.js";
-import { search, list } from "./retrieve/search.js";
-import { writeMemoryFile, readMemoryFile, deleteMemoryFile, ulid, msToRfc3339, } from "./store/markdown.js";
+import { proposeMemories, promoteMemory, listConflicts, resolveConflict, formatReviewHistory } from "./review.js";
+import { getSyncStatus, formatSyncStatus, submitMemories } from "./submit.js";
+import { getPrStatus, formatPrStatus, applyPrStatus } from "./github.js";
+import { search, list, hitStateLabel } from "./retrieve/search.js";
+import { writeMemoryFile, readMemoryFile, ulid, msToRfc3339, } from "./store/markdown.js";
 import { loadConfig } from "./config.js";
-import { paths } from "./paths.js";
+import { paths, projectRoot } from "./paths.js";
 import { redact } from "./redact.js";
 import { resolveMcpCommand } from "./init.js";
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+/** Per-command help, printed by `open-memex <command> --help`.
+    AI assistants discover the CLI through --help, so every command needs one. */
+const COMMAND_HELP = {
+    where: `Show which project scope the current directory resolves to, and where its data lives.
+
+Usage: open-memex where`,
+    list: `List memories in a scope, newest first.
+
+Usage: open-memex list [--scope project|personal] [--type T] [--limit N]
+
+Flags:
+  --scope   project (default) or personal
+  --type    filter by memory type
+  --limit   max results
+
+Examples:
+  open-memex list
+  open-memex list --scope personal --limit 20`,
+    search: `Search memories by keyword (BM25 full-text), best matches first.
+
+Usage: open-memex search "query" [--scope project|personal|both] [--type T] [--limit N]
+
+Flags:
+  --scope   project (default), personal, or both
+  --type    filter by memory type
+  --limit   max results
+
+Example:
+  open-memex search "deploy checklist" --scope both`,
+    add: `Save a fact, preference, decision, or note to local memory.
+
+Usage: open-memex add "content" [--scope project|personal] [--type T] [--tag t1,t2]
+
+Flags:
+  --scope   project (default) or personal (personal never leaves this machine)
+  --type    memory type (default: fact)
+  --tag     comma-separated tags
+
+Example:
+  open-memex add "We deploy on Fridays" --scope project --tag process`,
+    supersede: `Replace a memory with a newer version. The old one is kept as history.
+
+Usage: open-memex supersede <id> "new content" [--type T] [--tag t1,t2]`,
+    status: `Change a memory's lifecycle status.
+
+Usage: open-memex status <id> active|deprecated|retracted|archived`,
+    forget: `Delete a memory by id.
+
+Usage: open-memex forget <id>`,
+    propose: `Copy personal memories into the project outbox as review drafts.
+The personal originals stay put. Nothing enters git at this step.
+
+Usage: open-memex propose <id...> --to project [--local-approve]
+
+Flags:
+  --to             project (required)
+  --local-approve  mark the copies approved right away (solo-dev shortcut)
+
+Example:
+  open-memex propose 01ABC 01DEF --to project`,
+    promote: `Advance a project memory one step up the review ladder
+(proposed → approved → published), or reject it with a note.
+Every transition is appended to the memory's review_history.
+Rejected memories are never deleted — they can be revised and resubmitted.
+
+Usage: open-memex promote <id> [--reject] [--resubmit] [--note "..."] [--by NAME]
+
+Flags:
+  --reject    move back to rejected (requires --note)
+  --resubmit  move a rejected memory back to proposed
+  --note      reason for the transition (recorded in review_history)
+  --by        reviewer name (defaults to the git user)
+
+Examples:
+  open-memex promote 01ABC --note "verified against the runbook"
+  open-memex promote 01ABC --reject --note "outdated after the migration"`,
+    resolve: `List conflicted memories, or 3-way-merge one.
+
+Usage: open-memex resolve [id-or-path]
+
+With no argument, lists conflicts. With an id or file path, shows the
+3-way merge (base / outbox / repo) so you can resolve it by hand.
+Conflicts are never auto-resolved.`,
+    "sync-status": `Show the project memory sync pipeline: when the index last synced
+and what triggered it, drafts waiting in the outbox (appdata), memories in the
+repo awaiting review or published, and repo files not yet committed.
+
+Usage: open-memex sync-status`,
+    pull: `Pull shared project memories from the git remote: fetch + fast-forward
+only. Never auto-merges — a diverged branch fails with a clear message and is
+left for you to resolve by hand. On success the local index re-syncs.
+
+Usage: open-memex pull`,
+    push: `Push the current branch (with its submitted memories) to the git
+remote. Explicit only — open-memex never pushes on its own.
+
+Usage: open-memex push`,
+    export: `Export memories to a portable .tar.gz bundle (markdown source of
+truth + manifest.json) for moving to another machine or another app.
+Excludes visibility:private memories by default; --all includes everything.
+
+Usage: open-memex export [--scope project|personal|both] [--type T] [--tag t] [--all] [-o <file>]
+
+Flags:
+  --scope   project (default), personal, or both
+  --type    filter by memory type
+  --tag     filter by tag
+  --all, -a include private memories (full migration)
+  -o        output file (default: ./open-memex-export-<timestamp>.tar.gz)`,
+    import: `Import a bundle created by \`open-memex export\`. Personal memories
+go to the personal dir; project memories are re-keyed to the current project
+and land in the outbox as drafts. Existing identical memories are skipped;
+conflicting ids are reported, never overwritten.
+
+Usage: open-memex import <bundle.tar.gz> [--dry-run]`,
+    "distill-agents": `Propose an AGENTS.md snippet distilled from project
+memories (decisions, constraints, lessons, gotchas, howtos). Prints markdown
+to stdout, or writes it with -o. Review and merge by hand — open-memex never
+rewrites your AGENTS.md on its own.
+
+Usage: open-memex distill-agents [--scope project|personal] [--type t1,t2] [--limit N] [-o <file>]`,
+    submit: `Move outbox drafts into the repo for review: copies the drafts into
+the repo memory dir as proposed (a local-approved copy keeps its approval),
+commits locally on the CURRENT branch, and moves the outbox originals out.
+Never creates a branch on its own — branch creation is your call.
+
+Usage: open-memex submit <id...> [--branch <name>] [--base <branch>]
+
+Flags:
+  --branch  create this branch and submit onto it (only with your explicit
+            approval for the full chain); default: stay on current branch
+  --base    PR base override (default: the branch you're on)
+
+Example:
+  open-memex submit 01ABC 01DEF`,
+    "pr-status": `Map the current branch's GitHub PR state back onto review_state:
+merged → published, approval → approved (approved_by = the reviewer),
+changes-requested → suggestion only (never auto-rejects).
+Each memory in the PR is mapped independently; a human rejection is never
+overwritten. Report-only by default.
+
+Usage: open-memex pr-status [--apply]
+
+Flags:
+  --apply   write the transitions locally (still never pushes)`,
+    reindex: `Rebuild the SQLite index from the markdown files.
+
+Usage: open-memex reindex`,
+    scopes: `List the known scopes (personal + project).
+
+Usage: open-memex scopes`,
+    migrate: `Move memories between scopes, or convert a legacy my-o-memory data dir.
+
+Usage: open-memex migrate [--from <key>] [--to <key>] [--dry-run] [--on-conflict newer|overwrite|skip]
+       open-memex migrate --to-v2 [--dry-run]
+
+Flags:
+  --from / --to   scope keys (default: current project → personal)
+  --dry-run       preview without moving anything
+  --on-conflict   newer (default), overwrite, or skip
+  --to-v2         convert a legacy my-o-memory data dir to the v2 layout
+
+Always preview with --dry-run first; nothing moves without confirmation.`,
+    mcp: `Start the stdio MCP server (the same server editors connect to).
+
+Usage: open-memex mcp [--print-config vscode|cursor|claude|opencode|visualstudio]
+
+Flags:
+  --print-config   print the MCP client config instead of starting the server`,
+    init: `One-command project setup: writes the MCP config for your editor and the
+agent memory instructions. Existing files are merged, never clobbered.
+
+Usage: open-memex init [--client vscode|cursor|opencode|visualstudio]
+              [--instructions personal|project] [--force] [--yes]
+
+Flags:
+  --client        editor to configure (default: auto-detect)
+  --instructions  personal (default, ~/.copilot/copilot-instructions.md) or project
+  --force         overwrite existing config
+  --yes           accept all defaults, never prompt`,
+    config: `Show config, or set a key.
+
+Usage: open-memex config [set <key> <value>]
+
+Example:
+  open-memex config set sync.autoPull false`,
+    capture: `Preview what the keyword-capture watcher would extract from text.
+
+Usage: open-memex capture --dry-run "text"`,
+    doctor: `Environment health check: Node version, config source, scope resolution,
+storage writability, then boots a real MCP server and runs initialize +
+tools/list against it — all eleven tools must show up.
+
+Usage: open-memex doctor`,
+};
 function usage(exitCode = 1) {
     console.log(`open-memex CLI
 
@@ -26,6 +224,17 @@ Usage:
   open-memex supersede <id> "new content" [--type T] [--tag t1,t2]
   open-memex status <id> active|deprecated|retracted|archived
   open-memex forget <id>
+  open-memex propose <id...> --to project [--local-approve]
+  open-memex promote <id> [--reject] [--resubmit] [--note "..."] [--by NAME]
+  open-memex resolve [id-or-path]
+  open-memex sync-status
+  open-memex pull
+  open-memex push
+  open-memex export [--scope project|personal|both] [--type T] [--tag t] [--all] [-o <file>]
+  open-memex import <bundle.tar.gz> [--dry-run]
+  open-memex distill-agents [--scope project|personal] [--type t1,t2] [--limit N] [-o <file>]
+  open-memex submit <id...> [--branch <name>] [--base <branch>]
+  open-memex pr-status [--apply]
   open-memex reindex
   open-memex scopes
   open-memex migrate [--from <key>] [--to <key>]
@@ -63,9 +272,36 @@ the \`--from\` key when migrating.
 git remote after memories were already stored under the cwd-based key.
 \`migrate --to-v2\` converts v1 memory files to the v2 format (§19):
 user→personal scope rename, epoch→RFC 3339 times, priority→importance,
-type: instruction→role split. Always preview with --dry-run first.`);
+type: instruction→role split. Always preview with --dry-run first.
+
+Run \`open-memex <command> --help\` for details on a single command.`);
     process.exit(exitCode);
 }
+/**
+ * Build a saveConfig patch for a (possibly dotted) config key, preserving
+ * sibling keys already present in the nested object.
+ */
+function setConfigPath(key, value) {
+    const parts = key.split(".");
+    if (parts.length === 1)
+        return { [key]: value };
+    const cfg = loadConfig();
+    const top = parts[0];
+    const cur = cfg[top] && typeof cfg[top] === "object"
+        ? { ...cfg[top] }
+        : {};
+    let node = cur;
+    for (let i = 1; i < parts.length - 1; i++) {
+        const seg = parts[i];
+        const nxt = node[seg] && typeof node[seg] === "object"
+            ? { ...node[seg] }
+            : {};
+        node[seg] = nxt;
+        node = nxt;
+    }
+    node[parts[parts.length - 1]] = value;
+    return { [top]: cur };
+}
 function parseFlags(argv) {
     const out = {};
     for (let i = 0; i < argv.length; i++) {
@@ -163,6 +399,16 @@ async function main() {
         console.log(`open-memex ${pkg.version}`);
         return;
     }
+    // Per-command help: `open-memex <command> --help`. Checked before loadConfig()
+    // so it works even when the environment is broken.
+    if (rest.includes("--help") || rest.includes("-h")) {
+        const h = COMMAND_HELP[cmd];
+        if (h) {
+            console.log(`open-memex ${cmd}\n\n${h}`);
+            return;
+        }
+        usage(0);
+    }
     const cfg = loadConfig();
     const project = resolveProjectScope(process.cwd());
     // `migrate --to-v2` is a pure file operation (V2-DESIGN §19) — it runs
@@ -235,7 +481,9 @@ async function main() {
             }
             try {
                 const saved = validate(value);
-                const file = saveConfig({ [key]: saved });
+                // Dotted keys (e.g. sync.autoPull) write into the nested config
+                // object, preserving sibling keys already on disk.
+                const file = saveConfig(setConfigPath(key, saved));
                 console.log(`set ${key} = ${JSON.stringify(saved)} (${file})`);
             }
             catch (err) {
@@ -294,15 +542,15 @@ async function main() {
         return;
     }
     if (cmd === "reindex") {
-        const a = syncScope(project.key);
-        const b = syncScope(PERSONAL_SCOPE.key);
+        const a = syncScope(project.key, "cli");
+        const b = syncScope(PERSONAL_SCOPE.key, "cli");
         console.log(`reindexed. project: +${a.added} ~${a.updated} -${a.removed} (scanned ${a.scanned}), personal: +${b.added} ~${b.updated} -${b.removed} (scanned ${b.scanned})`);
         return;
     }
     if (cmd === "list") {
         const flags = parseFlags(rest);
         const s = resolveCliScope(flags, project);
-        syncScope(s.key);
+        syncScope(s.key, "cli");
         const hits = list(s.key, {
             type: flags.type,
             limit: flags.limit ? Number(flags.limit) : undefined,
@@ -313,7 +561,8 @@ async function main() {
         }
         for (const h of hits) {
             const dep = h.status === "deprecated" ? " [deprecated]" : "";
-            console.log(`[${h.type}]${dep} ${h.id}  ${h.snippet.replace(/\s+/g, " ").trim()}`);
+            const rev = hitStateLabel(h);
+            console.log(`[${h.type}]${dep}${rev} ${h.id}  ${h.snippet.replace(/\s+/g, " ").trim()}`);
         }
         return;
     }
@@ -322,8 +571,8 @@ async function main() {
         if (!query || query.startsWith("--"))
             usage();
         const flags = parseFlags(rest.slice(1));
-        syncScope(project.key);
-        syncScope(PERSONAL_SCOPE.key);
+        syncScope(project.key, "cli");
+        syncScope(PERSONAL_SCOPE.key, "cli");
         const keys = flags.scope === "personal" || flags.scope === "user"
             ? [PERSONAL_SCOPE.key]
             : flags.scope === "project"
@@ -341,7 +590,8 @@ async function main() {
         for (const h of hits) {
             const tag = h.scope_key === PERSONAL_SCOPE.key ? "personal" : "project";
             const dep = h.status === "deprecated" ? " [deprecated]" : "";
-            console.log(`[${tag}/${h.type}]${dep} ${h.id}  ${h.snippet.replace(/\s+/g, " ").trim()}`);
+            const rev = hitStateLabel(h);
+            console.log(`[${tag}/${h.type}]${dep}${rev} ${h.id}  ${h.snippet.replace(/\s+/g, " ").trim()}`);
         }
         return;
     }
@@ -384,6 +634,12 @@ async function main() {
             updated_at: rfc,
             supersedes: null,
             superseded_by: null,
+            review_state: "draft",
+            proposed_by: null,
+            approved_by: null,
+            derived_from: null,
+            review_note: null,
+            review_history: [],
         };
         const { filePath } = writeMemoryFile(fm, red);
         const mf = readMemoryFile(filePath);
@@ -447,16 +703,329 @@ async function main() {
         const id = rest[0];
         if (!id)
             usage();
-        const row = db().prepare(`SELECT scope_key FROM memories WHERE id = ?`).get(id);
+        const row = db().prepare(`SELECT file_path FROM memories WHERE id = ?`).get(id);
         if (!row) {
             console.error("not found");
             process.exit(1);
         }
-        deleteMemoryFile(row.scope_key, id);
+        // Delete by indexed file_path — location-agnostic (appdata or in-repo, 2B/D24).
+        if (row.file_path) {
+            try {
+                fs.unlinkSync(row.file_path);
+            }
+            catch {
+                /* already gone */
+            }
+        }
         deleteFromIndex(id);
         console.log(`deleted ${id}`);
         return;
     }
+    /** Positional args with flags (and their values) skipped. */
+    function positionalArgs(argv) {
+        const out = [];
+        for (let i = 0; i < argv.length; i++) {
+            const a = argv[i];
+            if (a.startsWith("--")) {
+                const val = argv[i + 1];
+                if (val !== undefined && !val.startsWith("--"))
+                    i++; // skip the flag's value
+            }
+            else {
+                out.push(a);
+            }
+        }
+        return out;
+    }
+    if (cmd === "propose") {
+        const flags = parseFlags(rest);
+        const ids = positionalArgs(rest);
+        if (ids.length === 0)
+            usage();
+        const to = flags.to ?? "project";
+        if (to !== "project") {
+            console.error(`propose --to "${to}" is not supported yet (org sharing is Phase 4).`);
+            process.exit(2);
+        }
+        try {
+            const batch = proposeMemories(ids, { localApprove: flags["local-approve"] === "true" });
+            for (const { sourceId, result: r } of batch) {
+                console.log(`proposed ${sourceId} → ${r.id}  [${r.reviewState}]`);
+            }
+            console.log(`Next: these are drafts in the outbox (appdata) — nothing is in git yet.`);
+            console.log(`  open-memex sync-status`);
+            console.log(`  open-memex submit ${batch.map(({ result: r }) => r.id).join(" ")}   # new branch, local commit; prints push + PR commands`);
+        }
+        catch (e) {
+            console.error(`propose failed: ${e.message}`);
+            process.exit(2);
+        }
+        return;
+    }
+    if (cmd === "promote") {
+        const flags = parseFlags(rest);
+        const id = rest.find((a) => !a.startsWith("--"));
+        if (!id)
+            usage();
+        try {
+            const r = promoteMemory(id, {
+                reject: flags.reject === "true",
+                resubmit: flags.resubmit === "true",
+                note: flags.note,
+                by: flags.by,
+            });
+            console.log(`promote ${r.id}: ${r.from} → ${r.to}`);
+            if (r.to === "published") {
+                console.log(`  merged to the shared branch? Teammates pick it up with an explicit pull.`);
+            }
+            if (r.to === "rejected") {
+                console.log(`  not deleted — the file stays on your branch. Your call:`);
+                console.log(`  accept: close the PR and delete the branch;`);
+                console.log(`  revise: edit the file, then \`open-memex promote ${r.id} --resubmit\`;`);
+                console.log(`  keep: leave it as a [rejected] record.`);
+            }
+            if (r.history.length > 0) {
+                console.log(`  history (${r.history.length}):`);
+                for (const h of formatReviewHistory(r.history))
+                    console.log(h);
+            }
+        }
+        catch (e) {
+            console.error(`promote failed: ${e.message}`);
+            process.exit(2);
+        }
+        return;
+    }
+    if (cmd === "resolve") {
+        const target = rest.find((a) => !a.startsWith("--"));
+        try {
+            if (!target) {
+                const conflicts = listConflicts();
+                if (conflicts.length === 0) {
+                    console.log("(no conflicted memory files)");
+                }
+                else {
+                    for (const c of conflicts)
+                        console.log(`conflicted: ${c.id}  ${c.filePath}`);
+                    console.log(`\nRun \`open-memex resolve <id>\` to attempt a field-level 3-way merge.`);
+                }
+                return;
+            }
+            const outcome = resolveConflict(target);
+            if (!outcome.ok) {
+                console.error(`cannot auto-resolve ${path.basename(outcome.filePath)} — semantic conflicts need a human:`);
+                for (const c of outcome.conflicts) {
+                    console.error(`  ${c.field}:`);
+                    console.error(`    base:   ${c.base}`);
+                    console.error(`    ours:   ${c.ours}`);
+                    console.error(`    theirs: ${c.theirs}`);
+                }
+                console.error(`Edit the file manually, then \`git add\` it. Nothing was written.`);
+                process.exit(3);
+            }
+            console.log(`resolved ${path.basename(outcome.filePath)}`);
+            if (outcome.autoMerged.length > 0)
+                console.log(`  auto-merged: ${outcome.autoMerged.join(", ")}`);
+            console.log(`  next: git add ${path.relative(process.cwd(), outcome.filePath)}`);
+        }
+        catch (e) {
+            console.error(`resolve failed: ${e.message}`);
+            process.exit(2);
+        }
+        return;
+    }
+    if (cmd === "sync-status") {
+        syncScope(project.key, "cli");
+        syncScope(PERSONAL_SCOPE.key, "cli");
+        try {
+            console.log(formatSyncStatus(getSyncStatus()));
+        }
+        catch (e) {
+            console.error(`sync-status failed: ${e.message}`);
+            process.exit(2);
+        }
+        return;
+    }
+    // §9 / D12: explicit pull — fetch + fast-forward only, never auto-merge.
+    if (cmd === "pull") {
+        const { GitProvider } = await import("./providers/git.js");
+        const root = projectRoot();
+        try {
+            const r = new GitProvider().pull(root);
+            const stats = syncScope(project.key, "pull");
+            if (r.fastForwarded) {
+                console.log(`pulled ${r.branch} from ${r.remote}: ${r.before.slice(0, 8)} → ${r.after.slice(0, 8)} (fast-forward)`);
+            }
+            else {
+                console.log(`already up to date: ${r.branch} @ ${r.after.slice(0, 8)}`);
+            }
+            console.log(`index: +${stats.added} ~${stats.updated} -${stats.removed} (scanned ${stats.scanned})`);
+        }
+        catch (e) {
+            console.error(`pull failed: ${e.message}`);
+            process.exit(2);
+        }
+        return;
+    }
+    // Explicit push — open-memex never pushes on its own (D36).
+    if (cmd === "push") {
+        const { GitProvider } = await import("./providers/git.js");
+        const root = projectRoot();
+        try {
+            const r = new GitProvider().push(root);
+            syncScope(project.key, "push");
+            console.log(`pushed ${r.branch} to ${r.remote} @ ${r.head.slice(0, 8)}`);
+        }
+        catch (e) {
+            console.error(`push failed: ${e.message}`);
+            process.exit(2);
+        }
+        return;
+    }
+    // §9 / D40: portable export bundle (markdown + manifest).
+    if (cmd === "export") {
+        const { exportMemories } = await import("./export.js");
+        const flags = parseFlags(rest);
+        const all = flags["all"] === "true" || flags["a"] === "true" || rest.includes("--all") || rest.includes("-a");
+        const scopeFlag = flags["scope"] ?? "project";
+        // parseFlags only handles `--` flags; `-o <file>` is picked up here.
+        const oIdx = rest.findIndex((a) => a === "-o");
+        const outFile = flags["o"] ?? flags["output"] ?? (oIdx >= 0 ? rest[oIdx + 1] : undefined);
+        const scopeKeys = scopeFlag === "both"
+            ? [project.key, PERSONAL_SCOPE.key]
+            : scopeFlag === "personal"
+                ? [PERSONAL_SCOPE.key]
+                : [project.key];
+        try {
+            const r = exportMemories({
+                scopeKeys,
+                type: flags["type"],
+                tag: flags["tag"],
+                includePrivate: all,
+                outFile,
+            });
+            console.log(`exported ${r.exported} memories → ${r.file}`);
+            if (!r.includePrivate && r.skippedPrivate > 0) {
+                console.log(`skipped ${r.skippedPrivate} private memories (use --all to include them)`);
+            }
+        }
+        catch (e) {
+            console.error(`export failed: ${e.message}`);
+            process.exit(2);
+        }
+        return;
+    }
+    if (cmd === "import") {
+        const { importBundle } = await import("./export.js");
+        const flags = parseFlags(rest);
+        const bundle = positionalArgs(rest)[0];
+        if (!bundle) {
+            console.error(`usage: open-memex import <bundle.tar.gz> [--dry-run]`);
+            process.exit(2);
+        }
+        const dryRun = flags["dry-run"] === "true";
+        try {
+            const r = importBundle(bundle, { projectScopeKey: project.key, dryRun });
+            if (!dryRun) {
+                syncScope(project.key, "cli");
+                syncScope(PERSONAL_SCOPE.key, "cli");
+            }
+            console.log(`${dryRun ? "DRY RUN: " : ""}imported ${r.imported}, skipped ${r.skippedIdentical} identical`);
+            for (const c of r.skippedConflict) {
+                console.log(`  conflict (kept existing): ${c.id} from ${c.file}`);
+            }
+        }
+        catch (e) {
+            console.error(`import failed: ${e.message}`);
+            process.exit(2);
+        }
+        return;
+    }
+    // Phase 3: distill project memories into a proposed AGENTS.md snippet.
+    if (cmd === "distill-agents") {
+        const { distillAgentsMarkdown } = await import("./distill-agents.js");
+        const flags = parseFlags(rest);
+        const scopeFlag = flags["scope"] ?? "project";
+        const scopeKeys = scopeFlag === "personal" ? [PERSONAL_SCOPE.key] : [project.key];
+        const types = flags["type"]
+            ? flags["type"].split(",").map((t) => t.trim()).filter(Boolean)
+            : undefined;
+        const limit = flags["limit"] ? parseInt(flags["limit"], 10) : undefined;
+        const oIdx = rest.findIndex((a) => a === "-o");
+        const outFile = oIdx >= 0 ? rest[oIdx + 1] : undefined;
+        try {
+            const md = distillAgentsMarkdown({ scopeKeys, types, limit });
+            if (!md) {
+                console.log("no distillable memories found (decisions, constraints, lessons, gotchas, howtos)");
+                return;
+            }
+            if (outFile) {
+                fs.writeFileSync(outFile, md, "utf8");
+                console.log(`wrote proposed AGENTS.md snippet → ${outFile} (review and merge by hand)`);
+            }
+            else {
+                console.log(md);
+            }
+        }
+        catch (e) {
+            console.error(`distill-agents failed: ${e.message}`);
+            process.exit(2);
+        }
+        return;
+    }
+    if (cmd === "pr-status") {
+        const flags = parseFlags(rest);
+        try {
+            const st = getPrStatus();
+            console.log(formatPrStatus(st));
+            if (flags.apply === "true") {
+                const applied = applyPrStatus(st);
+                if (applied.length === 0) {
+                    console.log(`nothing to apply.`);
+                }
+                else {
+                    for (const a of applied) {
+                        console.log(`applied ${a.memoryId.slice(0, 8)}: ${a.from} → ${a.to} (by ${a.by})`);
+                    }
+                }
+            }
+        }
+        catch (e) {
+            console.error(`pr-status failed: ${e.message}`);
+            process.exit(2);
+        }
+        return;
+    }
+    if (cmd === "submit") {
+        const flags = parseFlags(rest);
+        const ids = positionalArgs(rest);
+        if (ids.length === 0)
+            usage();
+        syncScope(project.key, "submit");
+        try {
+            const r = submitMemories(ids, { branch: flags.branch, base: flags.base });
+            for (const s of r.submitted) {
+                console.log(`submitted ${s.id} → ${path.relative(process.cwd(), s.filePath)}  [${s.reviewState}]`);
+            }
+            for (const id of r.skippedIdentical) {
+                console.log(`already on branch: ${id} (identical content — outbox copy removed)`);
+            }
+            if (!r.committed) {
+                console.log(`nothing new to commit — branch ${r.branch} already holds these memories.`);
+            }
+            else {
+                console.log(`committed on ${r.branch}.`);
+            }
+            console.log(`Next (needs your approval — open-memex never pushes for you):`);
+            console.log(`  ${r.pushCommand}`);
+            console.log(`  ${r.prCommand}`);
+        }
+        catch (e) {
+            console.error(`submit failed: ${e.message}`);
+            process.exit(2);
+        }
+        return;
+    }
     if (cmd === "scopes") {
         const { memories } = paths();
         if (!fs.existsSync(memories)) {