takibibase 1.14.1 → 1.15.1

package/README.md

@@ -5,14 +5,14 @@ npx takibibase …          # zero-install: always the latest release
 npm i -g takibibase       # or install once, then run `takibi …`
 ```
 
-Needs Node.js 22+. This directory is also the npm package source:
+Needs Node.js 20+. 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. 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.
+- `takibi.mjs` — the CLI. Single-file Node ≥ 20, zero dependencies.
   Run it from a checkout as `node tools/takibi/takibi.mjs …`, or alias it:
   `alias takibi='node <checkout>/tools/takibi/takibi.mjs'`.
 - `SKILL.md` — the `takibi-use` skill. Short on purpose; the CLI carries
@@ -44,8 +44,10 @@ document, and Notes API routes; its behavior is documented in `SKILL.md`.
 ## Give an agent
 
 Key file in place + `takibi skill --install` (puts the `takibi-use` skill
-into the detected agent skills dirs; `--dir` overrides, `--force`
-overwrites). Zero-install alternative: `takibi skill` prints the skill —
+into the detected agent skills dirs; repeat `--dir <skills-root>` per
+custom box (`--dir` replaces detection unless a harness flag is also
+passed), `--force` refreshes an older copy). 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,
@@ -54,7 +56,6 @@ conversation; account-only routes stay yours.
 
 ## Known edges
 
-- `tasks get` filters the board list client-side (no single-task GET).
 - `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

package/SKILL.md

@@ -66,6 +66,15 @@ error hints.
   unassigned unless `--assignee` names someone; the source keeps its
   status, holder, and history, and nothing carries over. Never move a
   done card back to To do to continue it — follow up instead.
+- `takibi tasks create --title "…"` — open a fresh card on the board
+  (`--body`, `--due <date>`, `--assignee` with the same name rules as
+  follow-up). Needs the create cap; naming anyone other than yourself
+  needs Orchestrator. The card lands at To do, unassigned unless
+  `--assignee` names someone — claim it before driving it.
+- `takibi tasks update <id> [--title …] [--body …] [--due …]` — amend a
+  card without spinning a follow-up (at least one flag; empty `--due`
+  clears the date). A holder edits its own card; an orchestrator may
+  edit any card on the board. Title/body edits need the create cap.
 - `@name` in a task names the handoff target: the FIRST explicit
   `assign to @name` (or the first @name clearly meaning "who gets the
   card next"). Later @ names describing someone else's downstream step
@@ -166,13 +175,14 @@ abstains honestly instead of answering halfway.
 - Notes export/keep/remove need owner approval already given in the
   conversation. Export only creates a draft; verify it before adding
   content to Sources.
-- Task claim/status/handoff/artifact/escalation/follow-up writes only with owner approval
+- Task create/update/claim/status/handoff/artifact/escalation/follow-up writes only with owner approval
   already given in conversation. Claim-first: a plain key must claim a card before
   moving or touching it; only orchestrators/owners accept (`review→done`),
   assign or release cards they do not hold, or archive. A holder may hand
   its own card to another eligible profile (`tasks handoff`). Title/body edits need the create cap —
-  claim-only keys can drive a card but cannot rewrite its text. Follow-ups need
-  the create cap too, and any granted creator may spin one off a card it does not hold.
+  claim-only keys can drive a card but cannot rewrite its text. Creates and
+  follow-ups need the create cap too, and any granted creator may spin a
+  follow-up off a card it does not hold.
 - Boards need a whole-collection grant: folder-only or tag-only keys 403
   on every task route (the full-collection server message says so verbatim
   when the key holds the required cap; keys lacking the cap get the generic

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "takibibase",
-  "version": "1.14.1",
+  "version": "1.15.1",
   "description": "Thin CLI for the Takibi API: ask, search, tasks, docs, notes. Single file, zero dependencies.",
   "type": "module",
   "bin": {
@@ -12,7 +12,7 @@
     "README.md"
   ],
   "engines": {
-    "node": ">=22"
+    "node": ">=20"
   },
   "scripts": {
     "test": "node --test notes.test.mjs skill.test.mjs tasks.test.mjs upload.test.mjs"

package/takibi.mjs

@@ -17,7 +17,9 @@
  *   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.
+ * - Task ids are board-wide: `tasks get` reads GET /v1/tasks/:id straight
+ *   off (no --project needed); `tasks create` posts POST /v1/tasks and
+ *   `tasks update` patches PATCH /v1/tasks/:id, both project-scoped.
  * - 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.
@@ -37,7 +39,7 @@ import { homedir } from 'node:os';
 import { basename, join } from 'node:path';
 
 /** Baked fallback; the published package re-reads package.json next door. */
-const BAKED_VERSION = '1.14.1';
+const BAKED_VERSION = '1.15.1';
 const CLI_INFO = (() => {
   try {
     const pkg = JSON.parse(readFileSync(new URL('./package.json', import.meta.url), 'utf8'));
@@ -145,6 +147,10 @@ async function maybeNotifyUpdate({ json = false } = {}) {
         ? 'hint: download the latest takibi.mjs from https://takibibase.com/downloads/takibi.mjs'
         : 'hint: `npm i -g takibibase@latest`, or `npx takibibase@latest` for one-shot runs.',
     );
+    // Stale skills misroute crews (the upgrade bumps skill copy too), so
+    // the version nudge carries the refresh recipe. Single-file copies
+    // carry no SKILL.md to install — nothing to refresh there.
+    if (!CLI_INFO.singleFile) err('hint: then `takibi skill --install --force` refreshes agent skills (repeat `--dir <root>` per custom box).');
   } catch {
     // Offline, broken cache, slow registry: stay silent, run the command.
   }
@@ -302,7 +308,7 @@ 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, form = 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, blockHint = null } = {}) {
   const qs = query ? `?${query.toString()}` : '';
   const url = `${baseUrl}${path}${qs}`;
   const headers = { accept: 'application/json', 'user-agent': USER_AGENT };
@@ -330,6 +336,13 @@ async function api(method, path, { query = null, body = null, form = null, key =
   try {
     data = await res.json();
   } catch {
+    const responseType = res.headers.get('content-type') ?? '';
+    if (res.status === 403 && responseType.includes('text/html')) {
+      throw new CliError(`${label ?? path}: blocked by network security before reaching the API (HTTP 403).`, {
+        status: res.status,
+        hint: blockHint ?? 'The hosting filter flagged this request. Reword anything command-like and retry.',
+      });
+    }
     throw new CliError(`Unexpected response from ${label ?? path} (HTTP ${res.status}, not JSON).`, {
       status: res.status,
       hint: `Is ${baseUrl} the Takibi API? \`takibi version\` says what is serving there.`,
@@ -361,8 +374,10 @@ Commands:
   search -q "..."         Ranked chunks (snippets + metadata, no full text)
   tasks list              Board cards for the project
   tasks get <id>          One card with body + artifacts
+  tasks create            Open a fresh card [--title/--body/--assignee/--due]
   tasks claim <id>        Claim an open to-do card (atomic, one winner)
   tasks status <id> <st>  Move a card: todo | in_progress | review | done [--note <text>]
+  tasks update <id>       Amend a card's title, body, or due date [--title/--body/--due]
   tasks handoff <id> <profile>  Hand a card you hold to another profile [--review --note <text>]
   tasks follow-up <id>  Spin a fresh linked todo off any card [--title/--body/--assignee/--due]
   tasks escalate <id>       Ask the Founder for help on a held card [--reason <text>]
@@ -406,6 +421,11 @@ Per-command options:
   tasks escalate: --reason <text> (required, max 500 chars — what do you need from the Founder?)
   tasks follow-up: --title <text> (required, max 300 chars), --body <text> (max 20000 chars),
                  --assignee <name-or-uuid>, --due <date>; the source card is never modified
+  tasks create: --title <text> (required, max 300 chars), --body <text> (max 20000 chars),
+                 --assignee <name-or-uuid>, --due <date>; needs the create cap,
+                 lands at To do unassigned unless --assignee names someone
+  tasks update: --title/--body/--due (at least one; same limits as create;
+                 empty --due clears the date)
   tasks get: sent-back cards carry previousReviewNote, the last handoff note
   tasks artifact add <url>: --note <text> --size <bytes> --hash <hex> (links only)
   tasks artifact add --markdown <file|->: --title <text> --note <text> (content from file or stdin -, max 50000 chars; title max 140 chars)
@@ -422,6 +442,7 @@ Per-command options:
   notes keep/remove: <id> <expected-version> from notes list --all
   projects: --add <name> <uuid>
   skill: --install [--force] [--agents] [--claude] [--codex] [--dir <skills-root>]
+                 (repeat --dir per custom box; --dir alone skips detection)
 
 Setup: save the owner-provided key (one <publicId>.<secret> line) to
 ~/.takibi/key (chmod 600). The API defaults to Takibi's servers; only
@@ -432,7 +453,7 @@ 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/handoff/artifact/escalation/follow-up writes and doc uploads
+Reads are free. Export stamps included notes. Task create/update/claim/status/handoff/artifact/escalation/follow-up 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.
@@ -729,16 +750,47 @@ async function cmdTasks(tokens, globals) {
   if (sub === 'get') {
     const [id, extra] = rest;
     if (!id || extra) throw usageError('Usage: takibi tasks get <id>');
+    // Ids are board-wide: no --project to resolve (same as follow-up).
+    const ctx = await ctxFor(globals, { needKey: true, resolveProject: false });
+    const data = await api('GET', `/v1/tasks/${id}`, { ...ctx, label: 'tasks get' });
+    if (ctx.json) out(JSON.stringify({ task: data.task }, null, 2));
+    else renderTask(data.task);
+    return;
+  }
+  if (sub === 'create') {
+    const usage = 'Usage: takibi tasks create --title <text> [--body <text>] [--assignee <name-or-uuid>] [--due <date>]';
+    let title;
+    let body;
+    let assignee;
+    let due;
+    for (let i = 0; i < rest.length; i++) {
+      const f = rest[i];
+      if (f === '--title') title = rest[++i];
+      else if (f === '--body') body = rest[++i];
+      else if (f === '--assignee') assignee = rest[++i];
+      else if (f === '--due') due = rest[++i];
+      else throw usageError(`Unexpected ${JSON.stringify(f)}. ${usage}`);
+    }
+    // Validate everything before touching the key or network, mirroring
+    // the server limits so failures name the flag instead of 400ing.
+    if (title === undefined || title.trim() === '') throw usageError('--title needs non-empty text.');
+    if (title.trim().length > 300) throw usageError('--title is max 300 chars.');
+    if (body !== undefined && body.length > 20000) throw usageError('--body is max 20000 chars.');
+    if (due !== undefined && due.trim() === '') throw usageError('--due needs a date.');
+    if (assignee !== undefined && String(assignee).trim() === '') throw usageError('--assignee needs a profile name or UUID.');
     const ctx = await ctxFor(globals, { needKey: true });
-    let tasks = await listTasks(ctx, false);
-    let found = tasks.find((t) => t.id === id);
-    if (!found) {
-      tasks = await listTasks(ctx, true);
-      found = tasks.find((t) => t.id === id);
+    if (assignee !== undefined) {
+      const v = String(assignee).trim();
+      assignee = UUID_RE.test(v) ? v : (await resolveAssignee(v, ctx, 'tasks create')).id;
     }
-    if (!found) throw new CliError(`tasks get: No such task in this project (${id}).`, { status: 404, hint: hintFor(404, '') });
-    if (ctx.json) out(JSON.stringify({ task: found }, null, 2));
-    else renderTask(found);
+    const data = await api('POST', '/v1/tasks', {
+      ...ctx,
+      query: qparams([['projectId', ctx.projectId]]),
+      body: { title: title.trim(), body, assigneeProfileId: assignee, dueAt: due },
+      label: 'tasks create',
+    });
+    if (ctx.json) out(JSON.stringify(data, null, 2));
+    else renderTask(data.task);
     return;
   }
   if (sub === 'claim') {
@@ -803,6 +855,41 @@ async function cmdTasks(tokens, globals) {
     else renderTask(data.task);
     return;
   }
+  if (sub === 'update') {
+    const usage = 'Usage: takibi tasks update <id> [--title <text>] [--body <text>] [--due <date>]';
+    const [id, ...flagTokens] = rest;
+    if (!id || id.startsWith('--')) throw usageError(usage);
+    let title;
+    let body;
+    let due;
+    for (let i = 0; i < flagTokens.length; i++) {
+      const f = flagTokens[i];
+      if (f === '--title') title = flagTokens[++i];
+      else if (f === '--body') body = flagTokens[++i];
+      else if (f === '--due') due = flagTokens[++i];
+      else throw usageError(`Unexpected ${JSON.stringify(f)}. ${usage}`);
+    }
+    if (title === undefined && body === undefined && due === undefined) {
+      throw usageError(`Nothing to change — pass at least one of --title, --body, --due. ${usage}`);
+    }
+    if (title !== undefined && title.trim() === '') throw usageError('--title needs non-empty text.');
+    if (title !== undefined && title.trim().length > 300) throw usageError('--title is max 300 chars.');
+    if (body !== undefined && body.length > 20000) throw usageError('--body is max 20000 chars.');
+    // An explicit empty --due clears the date (the server treats '' and
+    // null as clear). Create keeps rejecting it: omit and clear are the
+    // same on POST.
+    if (due !== undefined && due.trim() === '') due = null;
+    const ctx = await ctxFor(globals, { needKey: true });
+    const data = await api('PATCH', `/v1/tasks/${id}`, {
+      ...ctx,
+      query: qparams([['projectId', ctx.projectId]]),
+      body: { title: title?.trim(), body, dueAt: due },
+      label: 'tasks update',
+    });
+    if (ctx.json) out(JSON.stringify(data, null, 2));
+    else renderTask(data.task);
+    return;
+  }
   if (sub === 'artifact' || sub === 'artifacts') {
     const LINK_USAGE = 'Usage: takibi tasks artifact add <taskId> <url> [--note <t> --size <n> --hash <h>]';
     const MD_USAGE = 'Usage: takibi tasks artifact add <taskId> --markdown <file|-> [--title <t>] [--note <t>]';
@@ -945,7 +1032,7 @@ async function cmdTasks(tokens, globals) {
     // Validate everything before touching the key or network, mirroring
     // the server limits so failures name the flag instead of 400ing.
     if (title === undefined || title.trim() === '') throw usageError('--title needs non-empty text.');
-    if (title.length > 300) throw usageError('--title is max 300 chars.');
+    if (title.trim().length > 300) throw usageError('--title is max 300 chars.');
     if (body !== undefined && body.length > 20000) throw usageError('--body is max 20000 chars.');
     if (due !== undefined && due.trim() === '') throw usageError('--due needs a date.');
     if (assignee !== undefined && String(assignee).trim() === '') throw usageError('--assignee needs a profile name or UUID.');
@@ -970,7 +1057,7 @@ async function cmdTasks(tokens, globals) {
     else renderTask(data.task);
     return;
   }
-  throw usageError(`Unknown tasks command ${JSON.stringify(sub)}. Use list | get | claim | status | handoff | follow-up | escalate | deescalate | artifact add | artifact show.`);
+  throw usageError(`Unknown tasks command ${JSON.stringify(sub)}. Use list | get | create | claim | status | update | handoff | follow-up | escalate | deescalate | artifact add | artifact show.`);
 }
 
 async function cmdDoc(tokens, globals) {
@@ -1049,16 +1136,16 @@ async function cmdDoc(tokens, globals) {
     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)));
+    // Base64 keeps file bytes opaque to edge filters, which pattern-match raw multipart bodies.
     const data = await api('POST', '/v1/documents', {
       ...ctx,
       query: qparams([
         ['projectId', ctx.projectId],
         ['folderId', ctx.folder],
       ]),
-      form,
+      body: { name: basename(path), contentBase64: bytes.toString('base64') },
       label: 'doc upload',
+      blockHint: 'The hosting filter flagged this file. Reword command-like text and upload it again.',
     });
     if (ctx.json) {
       out(JSON.stringify(data, null, 2));
@@ -1437,7 +1524,7 @@ const SKILL_TARGETS = [
   { flag: '--codex', harness: '.codex', dir: '.codex/skills' },
 ];
 
-const SKILL_USAGE = 'Usage: takibi skill [--install [--force] [--agents] [--claude] [--codex] [--dir <skills-root>]]';
+const SKILL_USAGE = 'Usage: takibi skill [--install [--force] [--agents] [--claude] [--codex] [--dir <skills-root>]…] (repeat --dir per custom box)';
 
 /** First-run skill nudge. Stderr only (stdout stays clean), best-effort,
  * never fails the command. Skipped for --json, in CI, with
@@ -1464,7 +1551,7 @@ function maybeNudgeSkill({ json = false } = {}) {
       // Read-only home: nudge once per process run instead of daily.
     }
     err('takibi: no takibi-use skill installed for your agents.');
-    err('hint: `takibi skill --install` puts it where assistants look.');
+    err('hint: `takibi skill --install` puts it where assistants look (repeat `--dir <skills-root>` per custom box; `--force` refreshes).');
   } catch {
     // Nudges never fail commands.
   }
@@ -1473,19 +1560,20 @@ function maybeNudgeSkill({ json = false } = {}) {
 function cmdSkill(tokens, globals) {
   let install = false;
   let force = false;
-  let customRoot = null;
+  const customRoots = [];
   const picked = new Set();
   for (let i = 0; i < tokens.length; i++) {
     const t = tokens[i];
     if (t === '--install') install = true;
     else if (t === '--force') force = true;
     else if (t === '--dir') {
-      customRoot = tokens[++i];
-      if (!customRoot) throw usageError('`--dir` needs a skills root. ' + SKILL_USAGE);
+      const root = tokens[++i];
+      if (!root) throw usageError('`--dir` needs a skills root. ' + SKILL_USAGE);
+      customRoots.push(root);
     } else if (t === '--agents' || t === '--claude' || t === '--codex') picked.add(t);
     else throw usageError(`Unexpected ${JSON.stringify(t)}. ${SKILL_USAGE}`);
   }
-  if (!install && (force || picked.size > 0 || customRoot)) {
+  if (!install && (force || picked.size > 0 || customRoots.length > 0)) {
     throw usageError(`Those flags need \`--install\`. ${SKILL_USAGE}`);
   }
   const text = skillText();
@@ -1504,17 +1592,17 @@ function cmdSkill(tokens, globals) {
   }
   const home = skillHome();
   let targets;
-  if (customRoot && picked.size === 0) targets = [];
+  if (customRoots.length > 0 && picked.size === 0) targets = [];
   else if (picked.size === 0) {
     const detected = SKILL_TARGETS.filter((t) => existsSync(join(home, t.harness)));
     targets = detected.length > 0 ? detected : [SKILL_TARGETS[0]];
   } else {
     targets = SKILL_TARGETS.filter((t) => picked.has(t.flag));
   }
-  if (customRoot) targets = [...targets, { flag: '--dir', custom: true }];
+  for (const root of customRoots) targets.push({ flag: '--dir', custom: true, root });
   const results = [];
   for (const t of targets) {
-    const dir = t.custom ? join(customRoot, SKILL_NAME) : join(home, t.dir, SKILL_NAME);
+    const dir = t.custom ? join(t.root, SKILL_NAME) : join(home, t.dir, SKILL_NAME);
     const dest = join(dir, SKILL_FILE);
     if (existsSync(dest)) {
       let same = false;