takibibase 1.3.0 → 1.7.0

package/SKILL.md

@@ -23,6 +23,10 @@ error hints.
 - Projects: `takibi projects` lists what this key can reach. `--project`
   takes a name or a UUID; single-grant keys may omit it.
   `takibi projects --add <name> <uuid>` keeps local aliases for offline use.
+- Folders: `takibi folders [--project …]` lists folder names → uuids for
+  `--folder` (only folders this key's grants touch; single-grant keys may
+  omit `--project`). Discovery flow: `projects` → `folders` → scoped
+  `ask`/`search`/`doc list`.
 - First probe: `takibi version` (needs no key; shows build + `jev` status).
 - Update notice: the CLI polls the npm registry once a day and nudges on
   stderr when behind (never on `--json`).
@@ -44,17 +48,17 @@ error hints.
   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.
+  versions. `takibi notes list --all` shows the inventory, including
+  flagged notes. `--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.
+  (sets kept; never settles flags or 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.
 
@@ -75,12 +79,19 @@ 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.
 
+Split bundled asks: one narrow ask per field — a combined question
+abstains honestly instead of answering halfway.
+
 ## 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.
+- Write the four body fields (tried, worked, failed, next time) in
+  Markdown (GFM): short lists, `code` and fenced blocks, links, tables.
+  The founder reads the body rendered; the problem title stays plain text
+  and raw HTML never renders. Keep each field tight — one idea per line.
 - 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.
@@ -90,6 +101,9 @@ prose presented as sourced.
   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.
+- Flagged hits contradict another note — both stay retrievable. Surface
+  both sides (`contradicts` links plus the marker line); never smooth a
+  flagged conflict over.
 - 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "takibibase",
-  "version": "1.3.0",
+  "version": "1.7.0",
   "description": "Thin CLI for the Takibi API: ask, search, tasks, docs, notes. Single file, zero dependencies.",
   "type": "module",
   "bin": {

package/takibi.mjs

@@ -15,6 +15,8 @@
  *   reads the API first and --project resolves names through it. A LOCAL
  *   map (~/.takibi/projects, `name=uuid` lines) remains as the offline
  *   fallback and for custom aliases. UUIDs pass straight through.
+ *   `folders` lists granted folders via GET /v1/projects/:id/folders the
+ *   same way (single-grant keys may omit --project; the CLI defaults it).
  * - There is no GET /v1/tasks/:id, so `tasks get` lists and filters.
  * - Account-only routes (doc download, uploads, deletes) answer 401, not
  *   403, to Bearer callers; `doc download` refuses client-side with a hint.
@@ -34,7 +36,7 @@ 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.3.0';
+const BAKED_VERSION = '1.7.0';
 const CLI_INFO = (() => {
   try {
     const pkg = JSON.parse(readFileSync(new URL('./package.json', import.meta.url), 'utf8'));
@@ -364,12 +366,13 @@ Commands:
   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 list --all        Inventory, including flagged notes
   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)
+  folders                 Granted folders (names -> uuids for --folder)
   version                 What build is serving + jev wired|unwired (no key needed)
   skill                   Print the takibi-use agent skill (pipe it to an agent)
   skill --install         Install the skill into agent skills dirs
@@ -392,6 +395,7 @@ Per-command options:
   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)
+    Fields render as Markdown (GFM): short lists, code, links, tables.
   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)
@@ -565,7 +569,7 @@ async function ctxFor(globals, { needKey, resolveProject = true }) {
   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)) {
-    throw usageError(`--folder takes a folder UUID, not ${JSON.stringify(globals.folder)}. (Folder names are not resolvable — keys cannot list folders.)`);
+    throw usageError(`--folder takes a folder UUID, not ${JSON.stringify(globals.folder)}. (Run \`takibi folders\` for this key's folder names.)`);
   }
   return { baseUrl, key, projectId, folder: globals.folder || undefined, json: globals.json, verbose: globals.verbose };
 }
@@ -859,6 +863,8 @@ function renderNotesSearch(data, q) {
       const meta = [`note ${r.noteId ?? '?'}`];
       if (r.score !== undefined && r.score !== null) meta.push(`score ${r.score}`);
       if (r.kept) meta.push('kept');
+      const linked = [...(Array.isArray(r.contradicts) ? r.contradicts : []), ...(Array.isArray(r.contradictedBy) ? r.contradictedBy : [])];
+      if (linked.length) meta.push(`conflicts with ${linked.map((id) => String(id).slice(0, 8)).join(', ')}${r.involvesSource ? ' (Source-involved)' : ''}`);
       if (r.projectTag) meta.push(`tag ${r.projectTag}`);
       if (r.createdAt) meta.push(String(r.createdAt));
       out(`    ${meta.join(' · ')}`);
@@ -907,8 +913,8 @@ async function cmdNotes(tokens, globals) {
     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)`);
+      if (Array.isArray(data?.flagged) && data.flagged.length) err(`(flagged: contradicts ${data.flagged.length} note${data.flagged.length === 1 ? '' : 's'} — both sides stay retrievable)`);
+      if (Array.isArray(data?.unflagged) && data.unflagged.length) err(`(settled ${data.unflagged.length} flagged note${data.unflagged.length === 1 ? '' : 's'} in this scope)`);
     } else {
       out(JSON.stringify(data));
     }
@@ -930,11 +936,12 @@ async function cmdNotes(tokens, globals) {
     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}` : ''}`);
+      const flagCount = (Array.isArray(n.contradicts) ? n.contradicts.length : 0) + (Array.isArray(n.contradictedBy) ? n.contradictedBy.length : 0);
+      out(`${n.id ?? '?'} · v${n.version ?? '?'} · ${n.status ?? '?'}${n.kept ? ' · kept' : ''}${n.projectTag ? ` · ${n.projectTag}` : ''}${flagCount ? ` · conflicts ${flagCount}` : ''}`);
       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'})`);
+    err(`(${matching.length} ${all ? 'inventory' : 'review'} note${matching.length === 1 ? '' : 's'}${all ? '' : ' · use --all for the full inventory and current versions'})`);
     return;
   }
   if (sub === 'search') {
@@ -982,11 +989,14 @@ async function cmdNotes(tokens, globals) {
     const bits = [];
     const included = countOf(data?.included);
     if (included !== undefined && included !== null) bits.push(`included ${included}`);
-    const conflicts = countOf(data?.conflicts);
+    const conflictsRaw = data?.conflicts;
+    const conflicts = Array.isArray(conflictsRaw)
+      ? conflictsRaw.filter((c) => c?.verdict === 'contradicts').length
+      : countOf(conflictsRaw);
     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 (ex && (ex.flagged || ex.expired)) {
+      bits.push(`flagged ${ex.flagged ?? 0} · expired ${ex.expired ?? 0}`);
     }
     if (data?.deltaSince) bits.push(`since ${data.deltaSince}`);
     if (bits.length) err(`(${bits.join(' · ')})`);
@@ -1078,6 +1088,35 @@ async function cmdProjects(tokens, globals) {
   for (const { name, id } of entries) out(`${name} → ${id}`);
 }
 
+async function cmdFolders(tokens, globals) {
+  if (tokens.length > 0) throw usageError(`Unexpected ${JSON.stringify(tokens[0])}. Usage: takibi folders [--project <name-or-uuid>]`);
+  const ctx = await ctxFor(globals, { needKey: true });
+  let projectId = ctx.projectId;
+  if (!projectId) {
+    // The server cannot default a path param, so single-grant keys resolve
+    // their one project client-side (ask/search default server-side).
+    const data = await api('GET', '/v1/projects', { baseUrl: ctx.baseUrl, key: ctx.key, verbose: ctx.verbose, label: 'projects' });
+    const ids = [...new Set((data?.projects ?? []).map((p) => p?.id).filter(Boolean))];
+    // Tag-only grants list no collections, so an empty list is ambiguous:
+    // the key may hold nothing, or hold tags. Say both, accurately.
+    if (ids.length === 0) throw new CliError('This key lists no projects.', { hint: 'Tag-only keys cannot list collections — pass --project <uuid> explicitly (ask the account owner for the id), or grant this profile a collection or folder.' });
+    if (ids.length > 1) throw usageError('This key spans projects — pass --project <name-or-uuid>.');
+    projectId = ids[0];
+  }
+  const data = await api('GET', `/v1/projects/${projectId}/folders`, { baseUrl: ctx.baseUrl, key: ctx.key, verbose: ctx.verbose, label: 'folders' });
+  if (ctx.json) {
+    out(JSON.stringify(data, null, 2));
+    return;
+  }
+  const entries = data?.folders ?? [];
+  if (!entries.length) {
+    out('No folders found.');
+    err('(This project has no folders this key can reach. Tag-only keys see only folders holding their tagged files.)');
+    return;
+  }
+  for (const f of entries) out(`${f.name} → ${f.id}`);
+}
+
 async function cmdVersion(globals) {
   const baseUrl = resolveBaseUrl();
   const data = await api('GET', '/version', { baseUrl, verbose: globals.verbose, label: 'version' });
@@ -1231,6 +1270,7 @@ async function main(argv) {
   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 === 'folders' || cmd === 'folder') return cmdFolders(tokens, globals);
   if (cmd === 'version') return cmdVersion(globals);
   if (cmd === 'skill') return cmdSkill(tokens, globals);
   throw usageError(`Unknown command ${JSON.stringify(cmd)}. See \`takibi --help\`.`);