takibibase 1.0.3 → 1.2.0

package/README.md

@@ -9,9 +9,8 @@ Needs Node.js 22+. This directory is also the npm package source:
 `takibi.mjs` stays a single zero-dependency file so the
 `/downloads/takibi.mjs` copy and the published package never drift.
 
-Thin client-side enablement for agents. Its only server pairing is
-`GET /v1/projects`, which lists a key's granted collections — everything
-else lives in this directory.
+Thin client-side enablement for agents. The CLI calls the project, task,
+document, and Notes API routes; its behavior is documented in `SKILL.md`.
 
 - `takibi.mjs` — the CLI. Single-file Node ≥ 22, zero dependencies.
   Run it from a checkout as `node tools/takibi/takibi.mjs …`, or alias it:
@@ -23,7 +22,7 @@ else lives in this directory.
 ## Account-owner setup (once per machine)
 
 1. Mint a key: in the app, Settings → Profiles → new profile with the
-   capabilities the crew needs (`search`, `ask`, `tasks`), scoped to its
+   capabilities the crew needs (`search`, `ask`, `tasks`, `notes`), scoped to its
    project(s). Copy the `<publicId>.<secret>` shown once.
 2. `mkdir -p ~/.takibi && printf '%s\n' '<publicId>.<secret>' > ~/.takibi/key && chmod 600 ~/.takibi/key`
 3. Optional: one base-URL line in `~/.takibi/config` (default
@@ -39,9 +38,10 @@ else lives in this directory.
 ## Give an agent
 
 Key file in place + the skill text (or installed skill). Acceptance: a
-fresh agent asks, searches, and lists tasks against a local boot on the
-first try, with no contract pasted in chat. Reads are free; task writes
-need your approval in conversation; account-only routes stay yours.
+fresh agent asks, searches, lists tasks, appends/searches notes, and
+uses `notes list --all` to find the current version before curation.
+Reads are free; task writes and notes export/keep/remove need your approval
+in conversation; account-only routes stay yours.
 
 ## Known edges
 

package/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: takibi-use
-description: Use the Takibi knowledge base and task board through the takibi CLI (ask, search, tasks, docs). Use whenever the user asks about Takibi content, evidence-backed answers from their docs, or crew task boards.
+description: Use the Takibi knowledge base and task board through the takibi CLI (ask, search, tasks, docs, notes). Use whenever the user asks about Takibi content, evidence-backed answers from their docs, or crew task boards.
 ---
 
 # takibi-use: Takibi via the CLI
@@ -39,6 +39,23 @@ error hints.
   and `takibi tasks artifact add <taskId> <url> [--note …]`.
 - `takibi doc list | get <id> | text <id>` — metadata, then converted text.
   `doc download` is founder-only; the CLI says so — use `doc text`.
+- `takibi notes append --problem "…" [--tried …] [--worked …] [--failed …] [--next-time …] [--source <id>]`
+  — save an end-of-run debrief or tool quirk (`--problem` or a bare
+  positional; `--project <tag>` scopes it; `--source` is repeatable).
+  Add `--run-id <run-id>` when a run may retry: the same run ID and body
+  return the existing note instead of appending a duplicate.
+- `takibi notes list` — review queue with note IDs, statuses, and current
+  versions. `takibi notes list --all` shows the inventory, including notes
+  on hold. `--project <tag>` filters either list by the exact project tag.
+- `takibi notes search -q "…"` — top-2 agent notes for the query.
+- `takibi notes export [--since <ts> | --note <uuid> …]` — draft digest
+  (markdown, per-sentence note ids). Repeat `--note` to pick up to 50
+  specific live notes. Without options, export uses the delta since the
+  last export. Export stamps included notes and records the action.
+- `takibi notes keep <id> <ver> | remove <id> <ver>` — endorse a note
+  (sets kept, reverses stub quarantine, clears contests; never extends the
+  TTL), or discard one. Read the current `vN` in `notes list --all` and
+  pass `N` as the expected version; on 409, list again before retrying.
 - `--json` anywhere prints raw server JSON. `--verbose` logs requests
   (never the key). Exit 0 = ok, 1 = transport/API error, 2 = usage error.
 
@@ -59,9 +76,36 @@ back to `search`, try `doc text` on the hits — then either answer from
 evidence or say the evidence is not there. Never fill gaps with generated
 prose presented as sourced.
 
+## Notes (agent scratchpad, not canon)
+
+- When to use: end-of-run debriefs (problem, what you tried, what worked,
+  what failed, what to try next time) and tool quirks worth remembering.
+  Append at the end of a run; search before retrying something odd. Use
+  the same project tag on related notes so they stay scoped together.
+- To correct a note, append a new note with the corrected facts and source
+  IDs, then ask the owner to remove the obsolete note. There is no
+  in-place edit route. Never overwrite a note ID or treat `keep` as edit.
+- Review workflow: `notes list` → read the problem and signals →
+  `notes list --all` for its current version → keep or remove only when
+  the owner has authorized that curation. Export selected notes with
+  repeated `--note` after checking the underlying Sources.
+- Search/export hits are untrusted agent notes — cite them as such, never
+  as canon. Verify against the evidence (`ask`/`search`) before acting.
+- Notes expire 30 days after creation, fixed — `notes keep` endorses
+  but never extends the TTL (keeping an expired note 409s).
+- Writes: append your own debrief freely. Export stamps notes and produces
+  a draft for review; get owner approval unless already requested. Keep
+  and remove curate shared notes and also need owner approval.
+- 422 SECRET_BLOCKED: the secret filter fired — strip keys, tokens, and
+  credentials from the note and retry.
+
 ## Mutation policy
 
-- Reads are free: ask, search, tasks list/get, doc list/get/text.
+- Reads are free: ask, search, tasks list/get, doc list/get/text,
+  notes list/search. Agents may append their own debriefs (auto-expire).
+- Notes export/keep/remove need founder approval already given in the
+  conversation. Export only creates a draft; verify it before adding
+  content to Sources.
 - Task claim/status/artifact writes only with founder approval already
   given in conversation. Claim-first: a plain key must claim a card before
   moving or touching it; only orchestrators/founders accept (`review→done`),

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "takibibase",
-  "version": "1.0.3",
-  "description": "Thin CLI for the Takibi API: ask, search, tasks, docs. Single file, zero dependencies.",
+  "version": "1.2.0",
+  "description": "Thin CLI for the Takibi API: ask, search, tasks, docs, notes. Single file, zero dependencies.",
   "type": "module",
   "bin": {
     "takibi": "takibi.mjs"
@@ -14,6 +14,9 @@
   "engines": {
     "node": ">=22"
   },
+  "scripts": {
+    "test": "node --test notes.test.mjs"
+  },
   "license": "SEE LICENSE IN LICENSE",
   "repository": {
     "type": "git",

package/takibi.mjs

@@ -21,13 +21,20 @@
  *
  * Exit codes: 0 ok (honest abstains included), 1 transport/API error,
  * 2 usage error.
+ *
+ * Notes (verified against the API routes):
+ * - append|list|search|export|keep|remove map to POST /v1/notes,
+ *   GET /v1/notes/triage, GET /v1/notes/search, POST /v1/notes/drafts, and
+ *   POST /v1/notes/:id/keep|remove.
+ * - --project passes through raw as projectTag (no UUID resolution).
+ * - 422 SECRET_BLOCKED means the secret filter fired — strip and retry.
  */
 import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync, writeSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 
 /** Baked fallback; the published package re-reads package.json next door. */
-const BAKED_VERSION = '1.0.3';
+const BAKED_VERSION = '1.2.0';
 const CLI_INFO = (() => {
   try {
     const pkg = JSON.parse(readFileSync(new URL('./package.json', import.meta.url), 'utf8'));
@@ -270,8 +277,13 @@ function hintFor(status, serverMessage) {
   if (status === 403) return 'Outside this key’s grant, or an owner/orchestrator-only move. Check `tasks get`, or ask the account owner.';
   if (status === 404) return 'Bad id, or outside this key’s grant (the server hides the difference).';
   if (status === 409) return null; // claim conflicts name the winner already.
+  if (status === 422) {
+    if (/secret/i.test(msg)) return 'The secret filter fired — strip keys, tokens, and credentials from the note and retry. Secrets never belong in notes.';
+    return 'The server rejected that shape. Check the fields and retry.';
+  }
   if (status === 429) {
     if (/too many calls/i.test(msg)) return 'Minute throttle (60/min/key). Slow down and retry in a bit.';
+    if (/too many notes writes/i.test(msg)) return 'Notes write throttle (30/min/profile). Slow down and retry in a bit.';
     return 'Daily budget spent. Budgets reset tomorrow; ask the account owner for a bigger one if this blocks work.';
   }
   if (status !== null && status >= 500) return 'Server side. Retry in a moment; if it persists the owner checks API logs.';
@@ -346,15 +358,23 @@ Commands:
   doc list                Documents (metadata)
   doc get <id>            One document's metadata
   doc text <id>           Converted text of one document
+  notes append "problem"  Save an agent note (debriefs, tool quirks)
+  notes list              Review queue with note IDs and current versions
+  notes list --all        Inventory, including notes on hold
+  notes search -q "..."   Search agent notes (top 2, untrusted)
+  notes export            Draft digest of recent notes; stamps exports
+  notes keep <id> <ver>   Endorse a note (expected version)
+  notes remove <id> <ver> Discard a note (expected version)
   projects                Granted projects (names -> uuids for --project)
   version                 What build is serving + jev wired|unwired (no key needed)
 
 Global options (accepted before or after the command):
   --project <name-or-uuid>   Project scope. Names resolve via the API list,
                              then ~/.takibi/projects; single-grant keys
-                             may omit it entirely.
+                             may omit it entirely. Notes send the raw
+                             value as the project tag (no resolution).
   --folder <uuid>            Folder scope (ask, search, doc list only).
-  --json                     Raw server JSON instead of human-readable output.
+  --json                     JSON instead of human-readable output.
   --verbose                  Log method + URL + status to stderr (never the key).
   -h, --help                 This help.  --version prints the CLI version.
 
@@ -363,6 +383,13 @@ Per-command options:
   tasks list: --all (include archived)
   tasks artifact add: --note <text> --size <bytes> --hash <hex>
   doc list: --limit <n> (1-100)   doc text: --max-chars <n>
+  notes append: --problem <text> (or a bare positional),
+    --tried/--worked/--failed/--next-time <text>, --source <id> (repeatable),
+    --run-id <id> (retry-safe within the same run)
+  notes list: --all (inventory instead of review queue)
+  notes search: -q/positional (no -k; top 2)
+  notes export: --since <ts> or --note <uuid> (repeatable; up to 50)
+  notes keep/remove: <id> <expected-version> from notes list --all
   projects: --add <name> <uuid>
 
 Setup: save the owner-provided key (one <publicId>.<secret> line) to
@@ -371,7 +398,7 @@ Env overrides: $TAKIBI_KEY_FILE, $TAKIBI_BASE_URL. Then \`takibi version\`
 to probe the API and \`takibi projects\` to see this key's scope
 (\`projects --add\` keeps local aliases for offline use).
 
-Reads are free. Task claim/status/artifact writes need owner approval in
+Reads are free. Export stamps included notes. Task claim/status/artifact writes need owner approval in
 conversation. Account-only routes (upload, delete, retry, download originals,
 PATCH docs/projects) are never the agent's to call — ask the account owner.
 `;
@@ -410,7 +437,7 @@ function parseArgv(argv) {
       i = ni;
     }
     else if (a.startsWith('--folder=')) globals.folder = a.slice('--folder='.length);
-    else if (a === '--query' || a === '-q' || a === '--q' || a === '-k' || a === '--limit' || a === '--max-chars' || a === '--all' || a === '--add' || a === '--note' || a === '--size' || a === '--hash') {
+    else if (a === '--query' || a === '-q' || a === '--q' || a === '-k' || a === '--limit' || a === '--max-chars' || a === '--all' || a === '--add' || a === '--note' || a === '--size' || a === '--hash' || a === '--problem' || a === '--tried' || a === '--worked' || a === '--failed' || a === '--next-time' || a === '--source' || a === '--since' || a === '--run-id') {
       rest.push(a);
       if (a !== '--all') {
         const [v, ni] = takeValue(a, i);
@@ -521,10 +548,10 @@ function renderDoc(d) {
 }
 
 /** Shared context: baseUrl always; key for every command except version/help. */
-async function ctxFor(globals, { needKey }) {
+async function ctxFor(globals, { needKey, resolveProject = true }) {
   const baseUrl = resolveBaseUrl();
   const key = needKey ? resolveKey() : null;
-  const projectId = await resolveProjectFlag(globals.project, { baseUrl, key, verbose: globals.verbose });
+  const projectId = resolveProject ? await resolveProjectFlag(globals.project, { baseUrl, key, verbose: globals.verbose }) : undefined;
   const { warnings } = loadProjectMap();
   for (const w of warnings) err(`warning: ${w}`);
   if (globals.folder !== undefined && globals.folder !== null && globals.folder !== '' && !UUID_RE.test(globals.folder)) {
@@ -750,6 +777,230 @@ async function cmdDoc(tokens, globals) {
   throw usageError(`Unknown doc command ${JSON.stringify(sub)}. Use list | get | text.`);
 }
 
+const NOTE_SUBS = ['append', 'list', 'search', 'export', 'keep', 'remove'];
+
+/** Notes scope by free-form project tag: --project passes through raw, never UUID-resolved. */
+const projectTagFrom = (v) => {
+  const t = String(v ?? '').trim();
+  return t ? t : undefined;
+};
+
+/** Notes template optionals: blank means absent. */
+const optText = (v) => {
+  if (v === undefined || v === null || String(v).trim() === '') return undefined;
+  return String(v).trim();
+};
+
+const countOf = (v) => (Array.isArray(v) ? v.length : v);
+
+function parseNotesAppendArgs(tokens) {
+  const t = {};
+  const sources = [];
+  const positionals = [];
+  for (let i = 0; i < tokens.length; i++) {
+    const tok = tokens[i];
+    if (tok === '--problem' || tok === '--tried' || tok === '--worked' || tok === '--failed' || tok === '--next-time' || tok === '--run-id') t[tok.slice(2)] = tokens[++i];
+    else if (tok === '--source') sources.push(tokens[++i]);
+    else positionals.push(tok);
+  }
+  if (positionals.length > 1) throw usageError(`Unexpected ${JSON.stringify(positionals[1])}. Usage: takibi notes append [--problem <text>] [--tried …] [--worked …] [--failed …] [--next-time …] [--source <id>]…`);
+  if (positionals.length === 1) {
+    if (String(positionals[0]).startsWith('-')) throw usageError(`Unexpected ${JSON.stringify(positionals[0])}. Usage: takibi notes append [--problem <text>] [--tried …] [--worked …] [--failed …] [--next-time …] [--source <id>]…`);
+    if (t.problem !== undefined) throw usageError('Pass the problem once: a bare positional or --problem, not both.');
+    t.problem = positionals[0];
+  }
+  const problem = optText(t.problem);
+  if (!problem) throw usageError('notes append needs a problem: takibi notes append --problem "..." (a bare positional works too).');
+  const sourceIds = sources.flatMap((s) => String(s).split(',')).map((s) => s.trim()).filter(Boolean);
+  const runId = optText(t['run-id']);
+  if (t['run-id'] !== undefined && !runId) throw usageError('--run-id needs a non-empty value.');
+  if (runId && runId.length > 200) throw usageError('--run-id must be 200 characters or fewer.');
+  return { problem, tried: optText(t.tried), worked: optText(t.worked), failed: optText(t.failed), nextTime: optText(t['next-time']), sourceIds, runId };
+}
+
+function parseNotesSearchArgs(tokens) {
+  let q = null;
+  const positionals = [];
+  for (let i = 0; i < tokens.length; i++) {
+    const tok = tokens[i];
+    if (tok === '-q' || tok === '--query' || tok === '--q') q = tokens[++i];
+    else if (tok === '-k') throw usageError('notes search always returns the top 2 — -k does not apply.');
+    else positionals.push(tok);
+  }
+  if (q === null || q === undefined || q === '') {
+    if (positionals.length === 0) throw usageError('Pass the query: takibi notes search -q "..." (a bare positional works too).');
+    q = positionals.shift();
+  }
+  if (positionals.length > 0) throw usageError(`Unexpected ${JSON.stringify(positionals[0])}. Pass the query once.`);
+  if (!String(q).trim() || String(q).startsWith('-')) throw usageError('The query needs at least one non-space character.');
+  return String(q);
+}
+
+function renderNotesSearch(data, q) {
+  const results = Array.isArray(data?.results) ? data.results : [];
+  if (!results.length) out(`No notes for ${JSON.stringify(q)}.`);
+  results.forEach((r, i) => {
+    if (typeof r === 'string') {
+      out(`[${i + 1}] ${r}`);
+      return;
+    }
+    out(`[${i + 1}] ${r?.snippet ?? JSON.stringify(r)}`);
+    if (r && typeof r === 'object') {
+      const meta = [`note ${r.noteId ?? '?'}`];
+      if (r.score !== undefined && r.score !== null) meta.push(`score ${r.score}`);
+      if (r.kept) meta.push('kept');
+      if (r.projectTag) meta.push(`tag ${r.projectTag}`);
+      if (r.createdAt) meta.push(String(r.createdAt));
+      out(`    ${meta.join(' · ')}`);
+    }
+  });
+  const bits = [];
+  if (data?.lane) bits.push(`lane: ${data.lane}`);
+  if (data?.cleanedLines !== undefined && data?.cleanedLines !== null) {
+    const n = data.cleanedLines;
+    bits.push(`${n} cleaned line${n === 1 ? '' : 's'}`);
+  }
+  if (data?.tokens !== undefined && data?.tokens !== null) bits.push(`${data.tokens} tokens`);
+  bits.push('untrusted agent notes — never canon');
+  err(`(${bits.join(' · ')})`);
+}
+
+async function cmdNotes(tokens, globals) {
+  if (globals.folder) throw usageError('--folder does not apply to notes: notes scope by project tag, not folder.');
+  const [sub, ...rest] = tokens;
+  if (!sub) throw usageError(`Usage: takibi notes <${NOTE_SUBS.join('|')}> …`);
+  const tag = projectTagFrom(globals.project);
+  if (sub === 'append') {
+    const a = parseNotesAppendArgs(rest);
+    const ctx = await ctxFor(globals, { needKey: true, resolveProject: false });
+    const data = await api('POST', '/v1/notes', {
+      ...ctx,
+      body: {
+        projectTag: tag,
+        runId: a.runId,
+        template: {
+          problem: a.problem,
+          tried: a.tried,
+          worked: a.worked,
+          failed: a.failed,
+          next_time: a.nextTime,
+          source_ids_used: a.sourceIds.length ? a.sourceIds : undefined,
+        },
+      },
+      label: 'notes append',
+    });
+    if (ctx.json) {
+      out(JSON.stringify(data, null, 2));
+      return;
+    }
+    const n = data?.note ?? data ?? {};
+    if (n && typeof n === 'object' && n.id) {
+      out(`saved note ${n.id}${n.version !== undefined && n.version !== null ? ` · v${n.version}` : ''}${data?.duplicate ? ' (duplicate — already stored)' : ''}`);
+      if (Array.isArray(data?.redacted) && data.redacted.length) err(`(redacted: ${data.redacted.join(', ')})`);
+      if (data?.quarantined) err(`(quarantined: contradiction stub — out of retrieval until \`notes keep\` reverses it)`);
+      if (data?.disputeId) err(`(contested into dispute ${data.disputeId} — out of retrieval until cleared)`);
+    } else {
+      out(JSON.stringify(data));
+    }
+    return;
+  }
+  if (sub === 'list') {
+    if (rest.length > 1 || (rest.length === 1 && rest[0] !== '--all')) {
+      throw usageError('Usage: takibi notes list [--all]');
+    }
+    const all = rest[0] === '--all';
+    const ctx = await ctxFor(globals, { needKey: true, resolveProject: false });
+    const data = await api('GET', '/v1/notes/triage', { ...ctx, label: 'notes list' });
+    const items = (all ? data?.inventory : data?.queue) ?? [];
+    const matching = tag ? items.filter((item) => item?.note?.projectTag === tag) : items;
+    if (ctx.json) {
+      out(JSON.stringify({ notes: matching, view: all ? 'inventory' : 'queue', projectTag: tag ?? null }, null, 2));
+      return;
+    }
+    if (!matching.length) out(`No ${all ? 'inventory' : 'review'} notes${tag ? ` for tag ${tag}` : ''}.`);
+    for (const item of matching) {
+      const n = item.note ?? {};
+      out(`${n.id ?? '?'} · v${n.version ?? '?'} · ${n.status ?? '?'}${n.kept ? ' · kept' : ''}${n.projectTag ? ` · ${n.projectTag}` : ''}`);
+      out(`    ${n.template?.problem ?? '(no problem)'}`);
+      if (item.gate !== 'skip' && item.why) out(`    ${item.why}`);
+    }
+    err(`(${matching.length} ${all ? 'inventory' : 'review'} note${matching.length === 1 ? '' : 's'}${all ? '' : ' · use --all for notes on hold and current versions'})`);
+    return;
+  }
+  if (sub === 'search') {
+    const q = parseNotesSearchArgs(rest);
+    const ctx = await ctxFor(globals, { needKey: true, resolveProject: false });
+    const data = await api('GET', '/v1/notes/search', {
+      ...ctx,
+      query: qparams([
+        ['q', q],
+        ['projectTag', tag],
+      ]),
+      label: 'notes search',
+    });
+    if (ctx.json) out(JSON.stringify(data, null, 2));
+    else renderNotesSearch(data, q);
+    return;
+  }
+  if (sub === 'export') {
+    let since;
+    const noteIds = [];
+    for (let i = 0; i < rest.length; i++) {
+      if (rest[i] === '--since') since = rest[++i];
+      else if (rest[i] === '--note') noteIds.push(rest[++i]);
+      else throw usageError(`Unexpected ${JSON.stringify(rest[i])}. Usage: takibi notes export [--since <ts> | --note <uuid> …]`);
+    }
+    const sinceText = optText(since);
+    if (since !== undefined && !sinceText) throw usageError('--since needs a timestamp.');
+    if (sinceText !== undefined && Number.isNaN(Date.parse(sinceText))) {
+      throw usageError(`That since timestamp is not a valid date: ${JSON.stringify(sinceText)}. (export --since takes a parseable date.)`);
+    }
+    if (sinceText && noteIds.length) throw usageError('Use --since or --note, not both.');
+    if (noteIds.length > 50 || noteIds.some((id) => !UUID_RE.test(id))) throw usageError('--note takes a UUID and may be repeated up to 50 times.');
+    const ctx = await ctxFor(globals, { needKey: true, resolveProject: false });
+    const data = await api('POST', '/v1/notes/drafts', {
+      ...ctx,
+      body: { projectTag: tag, since: sinceText, noteIds: noteIds.length ? noteIds : undefined },
+      label: 'notes export',
+    });
+    if (ctx.json) {
+      out(JSON.stringify(data, null, 2));
+      return;
+    }
+    if (data?.draft) out(data.draft);
+    else out('No notes to export.');
+    const bits = [];
+    const included = countOf(data?.included);
+    if (included !== undefined && included !== null) bits.push(`included ${included}`);
+    const conflicts = countOf(data?.conflicts);
+    if (conflicts !== undefined && conflicts !== null) bits.push(`conflicts ${conflicts}`);
+    const ex = data?.excluded;
+    if (ex && (ex.quarantined || ex.contested || ex.expired)) {
+      bits.push(`excluded ${ex.quarantined ?? 0} quarantined · ${ex.contested ?? 0} contested · ${ex.expired ?? 0} expired`);
+    }
+    if (data?.deltaSince) bits.push(`since ${data.deltaSince}`);
+    if (bits.length) err(`(${bits.join(' · ')})`);
+    return;
+  }
+  if (sub === 'keep' || sub === 'remove') {
+    const [id, ver, extra] = rest;
+    if (!id || !ver || extra || String(id).startsWith('-')) throw usageError(`Usage: takibi notes ${sub} <id> <expected-version>`);
+    const n = Number(ver);
+    if (!Number.isInteger(n) || n < 1) throw usageError(`<expected-version> takes a positive integer (the note's current version), not ${JSON.stringify(ver)}.`);
+    const expectedVersion = n;
+    const ctx = await ctxFor(globals, { needKey: true, resolveProject: false });
+    const data = await api('POST', `/v1/notes/${id}/${sub}`, { ...ctx, body: { expectedVersion }, label: `notes ${sub}` });
+    if (ctx.json) {
+      out(JSON.stringify(data, null, 2));
+      return;
+    }
+    const v = data?.note?.version ?? data?.version;
+    out(`${sub === 'keep' ? 'kept' : 'removed'} note ${id}${v !== undefined && v !== null ? ` · v${v}` : ''}`);
+    return;
+  }
+  throw usageError(`Unknown notes command ${JSON.stringify(sub)}. Use ${NOTE_SUBS.join(' | ')}.`);
+}
+
 async function cmdProjects(tokens, globals) {
   const { map, warnings, path } = loadProjectMap();
   for (const w of warnings) err(`warning: ${w}`);
@@ -841,6 +1092,7 @@ async function main(argv) {
   if (cmd === 'search') return cmdSearch(tokens, globals);
   if (cmd === 'tasks' || cmd === 'task') return cmdTasks(tokens, globals);
   if (cmd === 'doc' || cmd === 'docs') return cmdDoc(tokens, globals);
+  if (cmd === 'notes' || cmd === 'note') return cmdNotes(tokens, globals);
   if (cmd === 'projects') return cmdProjects(tokens, globals);
   if (cmd === 'version') return cmdVersion(globals);
   throw usageError(`Unknown command ${JSON.stringify(cmd)}. See \`takibi --help\`.`);