takibibase 1.5.0 → 1.8.0

package/README.md

@@ -23,10 +23,13 @@ document, and Notes API routes; its behavior is documented in `SKILL.md`.
 
 1. Mint a key: in the app, Settings → Profiles → new profile with the
    capabilities the crew needs (`search`, `ask`, `tasks`, plus `task:create`
-   for authors, `task:assign` for orchestrators, and `notes` / `notes:append` /
-   `notes:export` for observers), scoped to its project(s). Task boards need
+   for authors, `task:assign` for orchestrators, `notes` / `notes:append` /
+   `notes:export` for observers, and Uploads for pipelines that file
+   documents), scoped to its project(s). Task boards need
    a whole-collection grant — folder-only or tag-only seats cannot use them.
-   Copy the `<publicId>.<secret>` shown once.
+   Uploads land only in granted collections and pass the same secret scan,
+   quality gate, and budgets as app uploads. Copy the `<publicId>.<secret>`
+   shown once.
 2. `mkdir -p ~/.takibi && printf '%s\n' '<publicId>.<secret>' > ~/.takibi/key && chmod 600 ~/.takibi/key`
 3. Only for local setups: one base-URL line in `~/.takibi/config`
    (default `https://app.takibibase.com`). Env overrides:
@@ -45,15 +48,17 @@ into the detected agent skills dirs; `--dir` overrides, `--force`
 overwrites). Zero-install alternative: `takibi skill` prints the skill —
 paste it into the agent's first prompt. Acceptance: a 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.
+to find the current version before curation. Reads are free; task writes,
+notes export/keep/remove, and doc uploads need your approval in
+conversation; account-only routes stay yours.
 
 ## Known edges
 
 - `tasks get` filters the board list client-side (no single-task GET).
-- `doc download`/`delete`/`retry`/`upload` refuse client-side with a
-  pointer — Bearer keys can never reach account-only routes (the server
-  answers those 401, not 403).
+- `doc download`/`delete`/`retry` refuse client-side with a pointer —
+  Bearer keys can never reach account-only routes (the server answers
+  those 401, not 403). `doc upload` is the exception: keys holding the
+  Uploads grant (`documents:ingest`) may file into granted collections
+  (keys without it 403).
 - The CLI never prints the key: not in output, errors, `--verbose`
   (method + URL + status only), or exit traces (output is scrubbed).

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`).
@@ -38,6 +42,15 @@ error hints.
   and `takibi tasks artifact add <taskId> <url> [--note …]`.
 - `takibi doc list | get <id> | text <id>` — metadata, then converted text.
   `doc download` is account-only; the CLI says so — use `doc text`.
+- `takibi doc upload <file> [--project …] [--folder <uuid>]` — file one
+  document (pdf, md, txt, docx, max 10MB). Needs the Uploads grant
+  (`documents:ingest`) on the key plus owner approval in conversation;
+  without the grant the server 403s. Same checks as app uploads: secret
+  scan, quality gate, dedupe, daily budgets. One file per call — the
+  server 400s multi-file batches on keys. Folder-scoped keys must pass
+  `--folder` with a granted folder (unfiled needs a project-wide grant).
+  Held files report their reason — tell the owner instead of retrying in
+  a loop.
 - `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).
@@ -75,6 +88,9 @@ 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,
@@ -124,7 +140,10 @@ prose presented as sourced.
 - Notes are opt-in per profile: append, export, keep, and remove may 403
   with missing-capability on keys without the notes caps — ask the owner
   to enable them in the profile editor.
-- Account-only routes (upload, delete, retry, download originals, PATCH
+- `doc upload` only with owner approval already given in conversation,
+  and only on keys holding the Uploads grant — ask the owner to enable it
+  in the profile editor when the server 403s.
+- Account-only routes (delete, retry, download originals, PATCH
   docs/projects) are never the agent's to call — ask the account owner.
 
 ## Failure table

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "takibibase",
-  "version": "1.5.0",
+  "version": "1.8.0",
   "description": "Thin CLI for the Takibi API: ask, search, tasks, docs, notes. Single file, zero dependencies.",
   "type": "module",
   "bin": {
@@ -15,7 +15,7 @@
     "node": ">=22"
   },
   "scripts": {
-    "test": "node --test notes.test.mjs skill.test.mjs"
+    "test": "node --test notes.test.mjs skill.test.mjs upload.test.mjs"
   },
   "license": "SEE LICENSE IN LICENSE",
   "repository": {

package/takibi.mjs

@@ -15,9 +15,12 @@
  *   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.
+ * - Account-only routes (doc download, deletes) answer 401, not 403, to
+ *   Bearer [REDACTED]; `doc download` refuses client-side with a hint. Uploads
+ *   accept keys holding documents:ingest (`doc upload`); keys without it 403.
  *
  * Exit codes: 0 ok (honest abstains included), 1 transport/API error,
  * 2 usage error.
@@ -31,10 +34,10 @@
  */
 import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync, writeSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { join } from 'node:path';
+import { basename, join } from 'node:path';
 
 /** Baked fallback; the published package re-reads package.json next door. */
-const BAKED_VERSION = '1.5.0';
+const BAKED_VERSION = '1.8.0';
 const CLI_INFO = (() => {
   try {
     const pkg = JSON.parse(readFileSync(new URL('./package.json', import.meta.url), 'utf8'));
@@ -266,7 +269,7 @@ async function resolveProjectFlag(value, ctx) {
 
 function hintFor(status, serverMessage) {
   const msg = serverMessage || '';
-  if (status === 400 && /spans projects/i.test(msg)) return 'This key spans projects — pass --project <name-or-uuid>.';
+  if (status === 400 && /spans (projects|collections)/i.test(msg)) return 'This key spans projects — pass --project <name-or-uuid>.';
   if (status === 401) {
     if (/login required/i.test(msg)) return 'That route is account-only. Ask the account owner; never the agent.';
     if (/no longer valid/i.test(msg)) return 'That key is revoked or expired. Ask the account owner to mint a fresh one.';
@@ -277,6 +280,7 @@ function hintFor(status, serverMessage) {
     // The full-collection message is displayable verbatim (contract §11) —
     // it already prints as the error, so no generic hint on top of it.
     if (/full collection/i.test(msg)) return null;
+    if (/capability/i.test(msg)) return 'That profile lacks the capability for this call — ask the account owner to enable it.';
     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).';
@@ -298,12 +302,13 @@ function hintFor(status, serverMessage) {
  * One API call. Verbose logs method + URL + status only — headers (which
  * carry the key) are never logged, printed, or interpolated anywhere.
  */
-async function api(method, path, { query = null, body = null, key = null, baseUrl, verbose = false, label = null } = {}) {
+async function api(method, path, { query = null, body = null, form = null, key = null, baseUrl, verbose = false, label = null } = {}) {
   const qs = query ? `?${query.toString()}` : '';
   const url = `${baseUrl}${path}${qs}`;
   const headers = { accept: 'application/json', 'user-agent': USER_AGENT };
   if (key) headers.authorization = `Bearer ${key}`;
   if (body !== null) headers['content-type'] = 'application/json';
+  // form (multipart) carries its own content-type with boundary — never set it here.
   if (verbose) err(`→ ${method} ${url}`);
   const started = Date.now();
   let res;
@@ -311,7 +316,7 @@ async function api(method, path, { query = null, body = null, key = null, baseUr
     res = await fetch(url, {
       method,
       headers,
-      body: body === null ? undefined : JSON.stringify(body),
+      body: body === null ? (form ?? undefined) : JSON.stringify(body),
       signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
     });
   } catch (e) {
@@ -362,6 +367,7 @@ Commands:
   doc list                Documents (metadata)
   doc get <id>            One document's metadata
   doc text <id>           Converted text of one document
+  doc upload <file>       File one document (needs the Uploads grant)
   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 flagged notes
@@ -370,6 +376,7 @@ Commands:
   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
@@ -379,7 +386,7 @@ Global options (accepted before or after the command):
                              then ~/.takibi/projects; single-grant keys
                              may omit it entirely. Notes send the raw
                              value as the project tag (no resolution).
-  --folder <uuid>            Folder scope (ask, search, doc list only).
+  --folder <uuid>            Folder scope (ask, search, doc list, doc upload).
   --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.
@@ -389,6 +396,7 @@ 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>
+  doc upload: <file> (pdf, md, txt, docx, max 10MB)
   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)
@@ -409,9 +417,10 @@ to probe the API and \`takibi projects\` to see this key's scope
 Agents: \`takibi skill --install\` puts the takibi-use skill where
 assistants look for it.
 
-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.
+Reads are free. Export stamps included notes. Task claim/status/artifact writes and doc uploads
+need owner approval in conversation (uploads also need the Uploads grant on the key).
+Account-only routes (delete, retry, download originals, PATCH docs/projects)
+are never the agent's to call — ask the account owner.
 `;
 
 /**
@@ -566,7 +575,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 };
 }
@@ -777,7 +786,43 @@ async function cmdDoc(tokens, globals) {
     if (data.truncated) err('(truncated — the server caps converted text; narrow with search/ask.)');
     return;
   }
-  if (sub === 'download' || sub === 'delete' || sub === 'retry' || sub === 'upload') {
+  if (sub === 'upload') {
+    const [path, extra] = rest;
+    if (!path || extra) throw usageError('Usage: takibi doc upload <file> [--project <name-or-uuid>] [--folder <uuid>]');
+    const ctx = await ctxFor(globals, { needKey: true });
+    let bytes;
+    try {
+      bytes = readFileSync(path);
+    } catch {
+      throw usageError(`No such file: ${path}.`);
+    }
+    if (bytes.length === 0) throw usageError(`${path} is empty — nothing to upload.`);
+    if (bytes.length > 10 * 1024 * 1024) {
+      throw new CliError(`${path} is over the 10MB per-file limit.`, { hint: 'Split it and upload the parts.' });
+    }
+    const form = new FormData();
+    form.set('file', new File([bytes], basename(path)));
+    const data = await api('POST', '/v1/documents', {
+      ...ctx,
+      query: qparams([
+        ['projectId', ctx.projectId],
+        ['folderId', ctx.folder],
+      ]),
+      form,
+      label: 'doc upload',
+    });
+    if (ctx.json) {
+      out(JSON.stringify(data, null, 2));
+      return;
+    }
+    for (const d of data.documents ?? []) {
+      out(`uploaded ${d.id} · ${d.name} · ${d.status}${d.quarantineReason ? ` — ${d.quarantineReason}` : ''}`);
+    }
+    for (const r of data.refused ?? []) out(`refused ${r.name} — ${r.reason}${r.existingId ? ` (see ${r.existingId})` : ''}`);
+    if (!(data.documents?.length) && !(data.refused?.length)) out('Nothing uploaded.');
+    return;
+  }
+  if (sub === 'download' || sub === 'delete' || sub === 'retry') {
     // Account-only by design, and unreachable with a Bearer key: refuse
     // here with the pointer instead of burning a doomed request that the
     // server would answer 401 (account routes never see Bearer callers).
@@ -785,7 +830,7 @@ async function cmdDoc(tokens, globals) {
       hint: sub === 'download' ? 'Use `takibi doc text <id>` for the converted text; ask the account owner for originals.' : 'Ask the account owner to do this in the app.',
     });
   }
-  throw usageError(`Unknown doc command ${JSON.stringify(sub)}. Use list | get | text.`);
+  throw usageError(`Unknown doc command ${JSON.stringify(sub)}. Use list | get | text | upload.`);
 }
 
 const NOTE_SUBS = ['append', 'list', 'search', 'export', 'keep', 'remove'];
@@ -1085,6 +1130,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' });
@@ -1238,6 +1312,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\`.`);