fapony 0.1.3 → 0.2.1

package/src/mem/commands/read.ts

@@ -0,0 +1,448 @@
+// commands/read.ts — read-only commands: now (default), done, stale, find, kickoff
+
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { basename, join } from "node:path";
+import { doneLines, fmtClose, fmtRow, printOpenRows } from "../render.js";
+import { claimsOf, openRows, staleReport } from "../selectors.js";
+import type { CloseRow, WorkRow } from "../store.js";
+import { allRows, app, memCmd, planDir, rows } from "../store.js";
+import { planSweepCmd, shippedNotMoved } from "./plan.js";
+import { THRESHOLD } from "./rotate.js";
+
+const rotateLine = (n: number) =>
+  n >= THRESHOLD
+    ? `\n## 🗜 log ${n} rows (≥ ${THRESHOLD}) — run: ${memCmd} rotate --apply`
+    : "";
+
+const planSweepLine = () => {
+  const pending = shippedNotMoved();
+  return pending.length
+    ? `\n## 📦 shipped but not archived into done/ (${pending.length})\n` +
+        pending.map((n) => `- ${n}`).join("\n") +
+        `\n(move: ${planSweepCmd} <file.md> --apply)`
+    : "";
+};
+
+export const cmdNow = () => {
+  // mem now (default) — next+bug+hold. decision/note is not pending work → search with find instead
+  const all = rows();
+  console.log(`# ${app} — ${all.length} entries`);
+  printOpenRows(all, { showHold: true });
+  const decisionN = openRows(all).filter((r) => r.kind === "decision").length;
+  const noteN = openRows(all).filter((r) => r.kind === "note").length;
+  console.log(
+    `\n## decision ${decisionN} · note ${noteN} — search: ${memCmd} find <word>`,
+  );
+  const stale = staleReport(all);
+  if (stale.length)
+    console.log(
+      `\n## ⚠ stale (${stale.length})\n` +
+        stale.map((l) => `- ${l}`).join("\n"),
+    );
+  const sweep = planSweepLine();
+  if (sweep) console.log(sweep);
+  const rotate = rotateLine(all.length);
+  if (rotate) console.log(rotate);
+};
+
+export const cmdDone = () => {
+  const all = rows();
+  for (const l of doneLines(all)) console.log(l);
+};
+
+export const cmdStale = () => {
+  for (const l of staleReport(rows())) console.log(l);
+};
+
+export const cmdFind = (a: string[]) => {
+  // mem find <word> — grep text/spec case-insensitively, newest first, capped at 20 rows
+  const q = a.join(" ").toLowerCase();
+  if (!q) {
+    console.error(`usage: ${memCmd} find <word>`);
+    process.exit(1);
+  }
+  // allRows, not rows: find is recall — rotated history counts
+  const hits = allRows()
+    .filter(
+      (r): r is WorkRow =>
+        r.kind !== "close" &&
+        r.kind !== "synced" &&
+        r.kind !== "claim" &&
+        r.kind !== "release",
+    )
+    .filter(
+      (r) =>
+        r.text.toLowerCase().includes(q) ||
+        (r.spec ?? "").toLowerCase().includes(q),
+    )
+    .slice(-20);
+  for (const r of hits)
+    console.log(
+      `- [${r.id}] ${r.ts.slice(0, 10)} ${r.kind} ${r.text}${r.spec ? ` → ${r.spec}` : ""}`,
+    );
+  if (!hits.length) console.log("(no matches)");
+};
+
+/** Read a plan file and extract unchecked checkboxes from the TL;DR section. */
+const readPlanCheckboxes = (planPath: string): string[] => {
+  try {
+    const text = readFileSync(planPath, "utf8");
+    // Skip frontmatter
+    const body = text.replace(/^---\r?\n[\s\S]*?\r?\n---/, "");
+    // Find the first ## section (TL;DR)
+    const start = body.search(/^##\s+/m);
+    if (start < 0) return [];
+    const rest = body.slice(start);
+    const next = rest.slice(3).search(/^##\s+/m);
+    const block = next < 0 ? rest : rest.slice(0, next + 3);
+    // Extract unchecked checkboxes
+    const items: string[] = [];
+    for (const line of block.split("\n")) {
+      const m = /^\s*[-*]\s+\[\s\]\s+(.+)$/.exec(line);
+      if (m) items.push(m[1].trim());
+    }
+    return items;
+  } catch {
+    return [];
+  }
+};
+
+/** Check if a plan has `priority: high` in its frontmatter. */
+const hasHighPriority = (planPath: string): boolean => {
+  try {
+    const head = readFileSync(planPath, "utf8").slice(0, 1024);
+    const m = /^---\r?\n([\s\S]*?)\r?\n---/.exec(head);
+    if (!m) return false;
+    return /^\s*priority\s*:\s*high\s*$/m.test(m[1]);
+  } catch {
+    return false;
+  }
+};
+
+/** Read the title from a plan file (first # heading). */
+const readPlanTitle = (planPath: string): string => {
+  try {
+    const text = readFileSync(planPath, "utf8");
+    const m = /^#\s+(.+)$/m.exec(text);
+    return m ? m[1].trim() : "";
+  } catch {
+    return "";
+  }
+};
+
+const normSpec = (s: string) => s.replace(/\\/g, "/").replace(/^\.\//, "");
+
+// kickoff's spec arg used to be compared to r.spec as a literal string, so
+// `.fapony/plan/PLAN-x.md` had to be retyped byte-for-byte — and a typo printed
+// "(no entries)" with nothing to notice. Resolve against the spec paths the log
+// actually holds: exact path first, then by filename (with or without .md), then by
+// any path suffix. Returns all candidates so the caller can tell unique from ambiguous.
+const resolveSpec = (target: string, specs: string[]): string[] => {
+  const t = normSpec(target);
+  const all = [...new Set(specs)];
+  const exact = all.filter((s) => normSpec(s) === t);
+  if (exact.length) return exact;
+  const base = basename(t);
+  const withMd = base.endsWith(".md") ? base : `${base}.md`;
+  const byName = all.filter((s) => {
+    const b = basename(normSpec(s));
+    return b === base || b === withMd;
+  });
+  if (byName.length) return byName;
+  return all.filter((s) => normSpec(s).endsWith(`/${t}`));
+};
+
+export const cmdKickoff = (a: string[]) => {
+  // mem kickoff [id|spec.md] [--pick <n>]
+  // the spec may be the full path or just its filename
+  const all = rows();
+
+  // Parse --pick flag first
+  let pickIdx: number | null = null;
+  const pickFlagIdx = a.indexOf("--pick");
+  if (pickFlagIdx !== -1) {
+    const val = a[pickFlagIdx + 1];
+    pickIdx = parseInt(val ?? "", 10);
+    if (Number.isNaN(pickIdx) || pickIdx < 1) {
+      console.error("--pick requires a positive number");
+      process.exit(1);
+    }
+  }
+  // Filter out --pick and its value to get the main arguments
+  const mainArgs =
+    pickFlagIdx !== -1
+      ? a.filter((_, i) => i !== pickFlagIdx && i !== pickFlagIdx + 1)
+      : a;
+  const arg = mainArgs[0] ?? "";
+
+  // --- resolve spec/id for the main output ---
+  const workAll = all.filter((r): r is WorkRow => "id" in r);
+  const byId = new Map(workAll.map((r) => [r.id, r] as const));
+  const specNames = [
+    ...new Set(
+      all.flatMap((r) => ("spec" in r && r.spec ? [r.spec as string] : [])),
+    ),
+  ].sort();
+  const target = byId.get(arg);
+  const matches = resolveSpec(arg, specNames);
+  let resolvedSpec = matches.find((s) => normSpec(s) === normSpec(arg));
+
+  // If no arg or arg didn't match an id/spec, check if it's a plan file
+  let planFile: string | null = null;
+  let planCheckboxes: string[] = [];
+
+  if (arg && !resolvedSpec && !target) {
+    if (matches.length === 1) {
+      resolvedSpec = matches[0];
+    } else if (matches.length > 1) {
+      console.error(
+        `"${arg}" could mean ${matches.length} specs — retype one in full:`,
+      );
+      for (const m of matches) console.error(`  ${m}`);
+      process.exit(1);
+    } else if (arg.endsWith(".md")) {
+      // Try to find it as a plan file
+      const dir = planDir;
+      const candidates = [join(dir, basename(arg)), join(dir, arg), arg];
+      for (const c of candidates) {
+        if (existsSync(c)) {
+          planFile = c;
+          break;
+        }
+      }
+      if (!planFile) {
+        console.error(`no entries for spec "${arg}"`);
+        if (specNames.length) {
+          console.error(`specs in the log:`);
+          for (const s of specNames) console.error(`  ${s}`);
+        }
+        process.exit(1);
+      }
+    }
+  }
+
+  // Read plan file if we found one (or if a .md arg matched a spec)
+  if (planFile) {
+    planCheckboxes = readPlanCheckboxes(planFile);
+  } else if (arg && resolvedSpec && arg.endsWith(".md")) {
+    // The spec resolved from the log might be a plan file — try to read it
+    const dir = planDir;
+    const byName = join(dir, basename(arg));
+    if (existsSync(byName)) {
+      planFile = byName;
+      planCheckboxes = readPlanCheckboxes(planFile);
+    }
+  }
+
+  // --- main output (unchanged behavior) ---
+
+  if (!arg && !planFile) {
+    // no args = now + a "recent" section = the last 10 closes
+    console.log(`# ${app} — ${all.length} entries`);
+    printOpenRows(all, { showHold: true });
+    console.log(`\n## recent\n${doneLines(all, 10).join("\n")}`);
+    const stale = staleReport(all);
+    if (stale.length)
+      console.log(
+        `\n## ⚠ stale (${stale.length})\n` +
+          stale.map((l) => `- ${l}`).join("\n"),
+      );
+    const sweep = planSweepLine();
+    if (sweep) console.log(sweep);
+    const rotate = rotateLine(all.length);
+    if (rotate) console.log(rotate);
+  } else if (resolvedSpec) {
+    // spec.md = a brief for that spec
+    const open = openRows(all);
+    const specRows = open.filter((r) => r.spec === resolvedSpec);
+    const specDecisions = all
+      .filter(
+        (r): r is WorkRow => r.kind === "decision" && r.spec === resolvedSpec,
+      )
+      .slice(-5);
+    const specCloses = all
+      .filter((r): r is CloseRow => r.kind === "close")
+      .filter((r) => byId.get(r.ref)?.spec === resolvedSpec)
+      .slice(-3);
+
+    console.log(`# ${resolvedSpec} — ${specRows.length} open rows`);
+    if (specRows.length) {
+      console.log(`\n## open\n${specRows.map((r) => fmtRow(r)).join("\n")}`);
+    }
+    if (specDecisions.length) {
+      console.log(
+        `\n## decisions\n` +
+          specDecisions
+            .map((r) => `- ${r.ts.slice(0, 10)} ${r.text}`)
+            .join("\n"),
+      );
+    }
+    if (specCloses.length) {
+      console.log(
+        `\n## closes\n${specCloses.map((c) => fmtClose(c, byId)).join("\n")}`,
+      );
+    }
+    if (!specRows.length && !specDecisions.length && !specCloses.length) {
+      console.log("(no entries for this spec)");
+    }
+  } else if (target) {
+    // id = a brief for that task
+    const claims = claimsOf(all);
+    const claimInfo = claims.has(arg)
+      ? `\nClaimed by: ${claims.get(arg)?.agent} (${claims.get(arg)?.ts.slice(0, 10)})`
+      : "";
+
+    const spec = target.spec;
+    const open = spec
+      ? openRows(all).filter((r) => r.spec === spec && r.id !== arg)
+      : [];
+    const specDecisions = spec
+      ? all
+          .filter((r): r is WorkRow => r.kind === "decision" && r.spec === spec)
+          .slice(-5)
+      : [];
+    const specNotes = spec
+      ? all
+          .filter((r): r is WorkRow => r.kind === "note" && r.spec === spec)
+          .slice(-5)
+      : [];
+    const specCloses = spec
+      ? all
+          .filter((r): r is CloseRow => r.kind === "close")
+          .filter((r) => byId.get(r.ref)?.spec === spec)
+          .slice(-3)
+      : [];
+
+    console.log(
+      `# [${target.id}] ${target.kind} — ${target.text}${target.spec ? ` → ${target.spec}` : ""}${claimInfo}`,
+    );
+    if (open.length) {
+      console.log(
+        `\n## open (same spec)\n` +
+          open.map((r) => fmtRow(r, claims)).join("\n"),
+      );
+    }
+    if (specDecisions.length || specNotes.length) {
+      console.log(`\n## decisions & notes (spec)\n`);
+      for (const r of [...specDecisions, ...specNotes]) {
+        console.log(`- ${r.ts.slice(0, 10)} ${r.kind} ${r.text}`);
+      }
+    }
+    if (specCloses.length) {
+      console.log(
+        `\n## closes (spec)\n` +
+          specCloses.map((c) => fmtClose(c, byId)).join("\n"),
+      );
+    }
+  } else if (arg) {
+    console.error(`no id "${arg}" in the log`);
+    process.exit(1);
+  }
+
+  // --- next up section (chunk 3) ---
+
+  // A suggestion may carry a fully-runnable command. `manual` marks a command
+  // that is a template with a placeholder (bug close) — show it, never auto-run it.
+  type Suggestion = { text: string; run?: string; manual?: boolean };
+  const suggestions: Suggestion[] = [];
+  const GROUP_CAP = 3; // SPEC §3: at most 3 groups, at most 3 lines each
+
+  const truncate = (s: string, n = 80) =>
+    s.length > n ? `${s.slice(0, n - 1).trimEnd()}…` : s;
+
+  // group 1 — plans: priority: high first, then the first unchecked chunk
+  const planLines: Suggestion[] = [];
+  if (existsSync(planDir)) {
+    const files = readdirSync(planDir).filter((f) => f.endsWith(".md"));
+    for (const file of files) {
+      if (planLines.length >= GROUP_CAP) break;
+      const fullPath = join(planDir, file);
+      // Skip the plan we already showed
+      if (planFile && fullPath === planFile) continue;
+      if (hasHighPriority(fullPath)) {
+        const title = readPlanTitle(fullPath);
+        planLines.push({
+          text: `${title || file} (${file})`,
+          run: `fapony mem kickoff ${file}`,
+        });
+      }
+    }
+  }
+  // Only the first unchecked chunk (SPEC §3) — the body of the plan is the plan's job.
+  // There is no per-chunk command, so this line is context, not a runnable item.
+  if (planLines.length < GROUP_CAP && planCheckboxes.length) {
+    const planName = planFile ? basename(planFile) : "plan";
+    planLines.push({ text: `${planCheckboxes[0]} (${planName})` });
+  }
+  suggestions.push(...planLines);
+
+  // group 2 — open bugs, oldest first. openRows excludes tombstoned refs; the
+  // old bug filter forgot that and offered already-closed bugs as work.
+  const claims = claimsOf(all);
+  const openBugs = openRows(all)
+    .filter((r) => r.kind === "bug" && !claims.has(r.id))
+    .slice(0, GROUP_CAP);
+  for (const b of openBugs) {
+    suggestions.push({
+      text: `bug #${b.id} — ${truncate(b.text)}`,
+      run: `fapony mem close ${b.id} "<msg>"`,
+      manual: true,
+    });
+  }
+
+  // group 3 — the files of the last 3 rows that carried files[]
+  const recentFiles = all
+    .filter(
+      (r): r is WorkRow =>
+        "id" in r && "files" in r && !!(r as WorkRow).files?.length,
+    )
+    .slice(-3)
+    .flatMap((r) => r.files ?? []);
+  const uniqueRecent = [...new Set(recentFiles)].slice(0, GROUP_CAP);
+  if (uniqueRecent.length) {
+    suggestions.push({
+      text: `แตะล่าสุด: ${uniqueRecent.join(", ")}`,
+      run: `fapony review-seed --files ${uniqueRecent.join(",")}`,
+    });
+  }
+
+  // Print and optionally execute. Only a suggestion with a complete command is
+  // runnable — a plan item is context, a bug's close is a template needing a message.
+  if (suggestions.length) {
+    console.log(`\n## next up`);
+    for (let i = 0; i < suggestions.length; i++) {
+      console.log(`  [${i + 1}] ${suggestions[i].text}`);
+      if (suggestions[i].run) console.log(`      → ${suggestions[i].run}`);
+    }
+
+    if (pickIdx !== null) {
+      if (pickIdx > suggestions.length) {
+        console.error(
+          `--pick ${pickIdx}: only ${suggestions.length} suggestion(s) available`,
+        );
+        process.exit(1);
+      }
+      const picked = suggestions[pickIdx - 1];
+      if (!picked.run) {
+        console.error(
+          `--pick ${pickIdx}: "${picked.text}" is context, not a command — nothing to run`,
+        );
+        process.exit(1);
+      }
+      if (picked.manual) {
+        console.error(
+          `--pick ${pickIdx}: the command needs your own message — run it yourself:\n  ${picked.run}`,
+        );
+        process.exit(1);
+      }
+      const cmd = picked.run;
+      console.log(`\n> running: ${cmd}`);
+      const { execSync } = require("node:child_process");
+      try {
+        execSync(cmd, { stdio: "inherit", cwd: process.cwd() });
+      } catch {
+        process.exit(1);
+      }
+    }
+  }
+};

package/src/mem/commands/where.ts

@@ -0,0 +1,56 @@
+// src/mem/commands/where.ts — `fapony mem where`: show which mem dir is resolved and how
+
+import { whereMemDir } from "../../memory.js";
+
+const USAGE = "usage: fapony mem [--mem-dir <path>] where [--from <dir>]";
+
+export function cmdWhere(args: string[], memDir?: string): void {
+  let fromDir: string | undefined;
+
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--from") {
+      const v = args[i + 1];
+      if (!v || v.startsWith("--")) {
+        console.error(`fapony mem where: --from needs a value\n${USAGE}`);
+        process.exit(1);
+      }
+      fromDir = v;
+      i++;
+    } else if (args[i] === "-h" || args[i] === "--help") {
+      console.log(USAGE);
+      return;
+    }
+  }
+
+  const result = whereMemDir(fromDir, memDir);
+
+  if (result.step === "ambiguous") {
+    console.error(
+      "fapony mem: two mem dirs at the same level, refusing to guess",
+    );
+    for (const c of result.candidates ?? []) console.error(`  ${c}`);
+    console.error("cd into one of them, set paths.memDir, or pass --mem-dir");
+    process.exit(1);
+  }
+
+  if (!result.dir) {
+    console.log(
+      `fapony mem where — no .fapony/.memory/ found (step: ${result.step})`,
+    );
+    console.log("  Create one with: fapony init <path>");
+    return;
+  }
+
+  const labels: Record<string, string> = {
+    flag: "--mem-dir flag",
+    config: "paths.memDir in fapony.config.json",
+    "walk-up": "walked up from cwd",
+    "repo-root": "git repo root fallback",
+    ambiguous: "ambiguous",
+    none: "not found",
+  };
+
+  console.log(`fapony mem where`);
+  console.log(`  dir:   ${result.dir}`);
+  console.log(`  step:  ${labels[result.step] ?? result.step}`);
+}

package/{templates → src}/mem/commands/write.ts

@@ -205,10 +205,17 @@ export const cmdHook = async () => {
       ? ((j as { tool_input?: { file_path?: string } }).tool_input?.file_path ??
         "")
       : "";
-  const { app } = await import("../store.js");
-  const rel = f.startsWith(root) ? f.slice(root.length + 1) : f;
-  if (new RegExp(`^apps/${app}/(plan/(done/)?)?PLAN.*\\.md$`).test(rel)) {
-    put({ kind: "synced", spec: rel });
-    console.log(`synced ${rel}`);
+  const { planDir, doneDir } = await import("../store.js");
+  const relF = f.startsWith(root) ? f.slice(root.length + 1) : f;
+  // match PLAN*.md under this project's plan/ or done/
+  const planRe = new RegExp(
+    `^${planDir.replace(`${root}/`, "").replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}/.*PLAN.*\\.md$`,
+  );
+  const doneRe = new RegExp(
+    `^${doneDir.replace(`${root}/`, "").replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}/.*PLAN.*\\.md$`,
+  );
+  if (planRe.test(relF) || doneRe.test(relF)) {
+    put({ kind: "synced", spec: relF });
+    console.log(`synced ${relF}`);
   }
 };

package/src/mem/index.ts

@@ -0,0 +1,144 @@
+// src/mem/index.ts — CLI dispatch for `fapony mem <sub>`
+//
+// Moved from templates/mem/mem.ts (2026-09-19) as part of PLAN-agent-one-call chunk 1.
+// Now an export function called by fapony.ts, not a standalone script.
+
+import { cmdPlanCheck, cmdPlanSweep } from "./commands/plan.js";
+import {
+  cmdDone,
+  cmdFind,
+  cmdKickoff,
+  cmdNow,
+  cmdStale,
+} from "./commands/read.js";
+import { cmdRotate } from "./commands/rotate.js";
+import { cmdWhere } from "./commands/where.js";
+import {
+  cmdAdd,
+  cmdClaim,
+  cmdClose,
+  cmdHook,
+  cmdRelease,
+  cmdSynced,
+} from "./commands/write.js";
+
+const MEM_HELP = `usage: fapony mem [--mem-dir <path>] <sub> [args]
+
+subcommands:
+  where                       show the resolved mem dir and which step won
+  kickoff [<plan.md>] [--pick <n>]   open a session + a next-up list
+  add <kind> "<text>" --files f1,f2 [spec.md]
+  close <id> "<msg>"          close a bug
+  find "<text>"               substring-search every row
+  now | done | stale          views
+  claim <id> | release <id> | synced   bookkeeping
+  plan-sweep [<plan.md> [--apply]]     move shipped plans + fix links
+  plan-check <plan.md>        validate a plan's frontmatter/sections
+  rotate                      archive the live log when it grows
+  hook                        Stop-hook payload reader (installed, not run by hand)
+
+--mem-dir <path> wins over config and the walk-up (global to every sub)
+example: fapony mem add note "decided X because Y" --files src/a.ts`;
+
+const HELP: Record<string, string> = {
+  where: `usage: fapony mem where [--from <dir>]
+show the .fapony/.memory dir the resolver picks and which step won — writes nothing
+  --from <dir>    resolve as if cwd were here
+example: fapony mem where`,
+  kickoff: `usage: fapony mem kickoff [<plan.md>] [--pick <n>]
+open a session and print a "next up" list (priority plans, unchecked chunks, open bugs)
+  <plan.md>   plan whose first unchecked chunk is offered as a context line
+  --pick <n>  run suggestion [n] non-interactively; refuses context/template items
+example: fapony mem kickoff .fapony/plan/PLAN-x.md`,
+  add: `usage: fapony mem add <next|bug|decision|note|hold> "<text>" --files f1,f2 [spec.md]
+append one row to the mem log
+  --files f1,f2   repo-relative paths this row is about (required)
+  --stdin         read <text> from stdin (avoids shell metachar)
+example: fapony mem add decision "chose X because Y" --files src/a.ts,src/b.ts`,
+  close: `usage: fapony mem close <id> "<what was done | commit>"
+tombstone a bug so it stops showing as open work
+  --stdin         read the message from stdin
+example: fapony mem close mt14 "fixed in a2c6beb"`,
+  find: `usage: fapony mem find "<text>"
+substring search over every row's text/spec/ref — all kinds, no default filter
+example: fapony mem find "usage-web"`,
+  now: `usage: fapony mem now
+next + bug + hold still open (decision/note are search-only — use find)
+example: fapony mem now`,
+  done: `usage: fapony mem done
+closed rows with their tombstone message
+example: fapony mem done`,
+  stale: `usage: fapony mem stale
+decisions that never made it into their spec
+example: fapony mem stale`,
+  claim: `usage: fapony mem claim <id>
+claim an open next|bug before working it
+example: fapony mem claim mt14`,
+  release: `usage: fapony mem release <id> [--stdin]
+give back a claimed row without closing it
+example: fapony mem release mt14`,
+  synced: `usage: fapony mem synced [<spec.md>]
+mark a spec as carried into the log
+example: fapony mem synced .fapony/spec/SPEC-x.md`,
+  "plan-sweep": `usage: fapony mem plan-sweep [<plan.md>] [--apply]
+find shipped plans (or move one) and fix the links that point at it
+  --apply   perform the git mv + link fixes (default = dry run)
+example: fapony mem plan-sweep .fapony/plan/PLAN-x.md --apply`,
+  "plan-check": `usage: fapony mem plan-check <plan.md>
+validate a plan's frontmatter and required sections
+example: fapony mem plan-check .fapony/plan/PLAN-x.md`,
+  rotate: `usage: fapony mem rotate
+archive the live log to log.YYYY-MM-DD.jsonl once it crosses the threshold
+example: fapony mem rotate`,
+  hook: `usage: fapony mem hook
+reads the Stop-hook payload on stdin — installed by fapony, not run by hand
+example: (installed hook only)`,
+};
+
+export async function cmdMem(a: string[], memDir?: string): Promise<void> {
+  const [cmd, ...rest] = a;
+
+  // SPEC §2: every subcommand answers --help with signature + flags + one runnable
+  // example, because the reader is an agent that gets one call to get it right.
+  if (cmd === "-h" || cmd === "--help") {
+    console.log(MEM_HELP);
+    return;
+  }
+  if (rest.includes("-h") || rest.includes("--help")) {
+    console.log(HELP[cmd] ?? MEM_HELP);
+    return;
+  }
+
+  if (cmd === "add") {
+    await cmdAdd(rest);
+  } else if (cmd === "close") {
+    await cmdClose(rest);
+  } else if (cmd === "claim") {
+    cmdClaim(rest);
+  } else if (cmd === "release") {
+    await cmdRelease(rest);
+  } else if (cmd === "synced") {
+    cmdSynced(rest);
+  } else if (cmd === "hook") {
+    await cmdHook();
+  } else if (cmd === "done") {
+    cmdDone();
+  } else if (cmd === "stale") {
+    cmdStale();
+  } else if (cmd === "find") {
+    cmdFind(rest);
+  } else if (cmd === "kickoff") {
+    cmdKickoff(rest);
+  } else if (cmd === "where") {
+    cmdWhere(rest, memDir);
+  } else if (cmd === "plan-sweep") {
+    cmdPlanSweep(rest);
+  } else if (cmd === "plan-check") {
+    cmdPlanCheck(rest);
+  } else if (cmd === "rotate") {
+    cmdRotate(rest);
+  } else {
+    // mem now (default) — next+bug+hold. decision/note is not pending work → search with find instead
+    cmdNow();
+  }
+}