takibibase 1.0.0

package/LICENSE

@@ -0,0 +1,10 @@
+Copyright (c) 2026, Takibi (also known as Takibi Base, takibibase.com).
+All rights reserved.
+
+This software is proprietary to Takibi. You may install and run it
+solely as a client for Takibi services. You may not copy, modify,
+redistribute, or sublicense it, except as expressly permitted by
+Takibi in writing.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED.

package/README.md

@@ -0,0 +1,51 @@
+# takibi agent kit: CLI + skill
+
+```sh
+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:
+`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. Zero changes to `apps/api`,
+`apps/web`, schema, or grants — this directory is the whole feature.
+
+- `takibi.mjs` — the CLI. Single-file Node ≥ 22, zero dependencies.
+  Run it 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
+  the contract. Install it into your harness's skills dir, or paste it
+  into an agent's first prompt for a zero-install test.
+
+## 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
+   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
+   `http://localhost:3849`). Env overrides: `$TAKIBI_KEY_FILE`,
+   `$TAKIBI_BASE_URL`.
+4. `takibi projects --add <name> <uuid>` per project (UUIDs are in
+   Settings → Projects). `GET /v1/projects` is account-only, so names
+   live in `~/.takibi/projects` as `name=uuid` lines; UUIDs also work
+   directly in `--project`, and single-grant keys may omit it.
+5. `takibi version` — probes the API without needing the key.
+
+## 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.
+
+## 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).
+- The CLI never prints the key: not in output, errors, `--verbose`
+  (method + URL + status only), or exit traces (output is scrubbed).

package/SKILL.md

@@ -0,0 +1,75 @@
+---
+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.
+---
+
+# takibi-use: Takibi via the CLI
+
+Always use the CLI. Never hand-roll curl/fetch against `/v1/*` — the CLI
+already bakes in the auth shape, the `q` param, project resolution, and
+error hints.
+
+## Setup (once)
+
+- CLI: `npx takibibase …` (zero-install), `takibi …` (global install),
+  or `node tools/takibi/takibi.mjs …` from the takibi-base checkout
+  (use the alias when it exists).
+- Key: the founder saves one `<publicId>.<secret>` line to `~/.takibi/key`
+  (`chmod 600`). The key is never printed, never pasted in chat, never
+  committed. If a command says the key is missing, stop and ask.
+- Base URL defaults to `http://localhost:3849` (local boot). Override with
+  `$TAKIBI_BASE_URL` or one URL line in `~/.takibi/config`.
+- Projects: `takibi projects` lists saved names. `--project` takes a name
+  or a UUID; single-grant keys may omit it. New name? Ask the founder for
+  the UUID once, then `takibi projects --add <name> <uuid>`.
+- First probe: `takibi version` (needs no key; shows build + `jev` status).
+
+## Commands
+
+- `takibi ask -q "…"` — answer from the evidence. Output is verbatim spans
+  with citations plus a support line. `--project`, `--folder <uuid>`,
+  `-k 1-12`, `--json`.
+- `takibi search -q "…"` — ranked chunks (snippets + metadata, not full
+  text). Same flags, `-k 1-20`.
+- `takibi tasks list | get <id> | claim <id> | status <id> <todo|in_progress|review|done>`
+  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`.
+- `--json` anywhere prints raw server JSON. `--verbose` logs requests
+  (never the key). Exit 0 = ok, 1 = transport/API error, 2 = usage error.
+
+## Reading answers
+
+- Spans are verbatim with citations (`doc <uuid>`, `chunk <uuid>`) and a
+  versioned support score. Support is not confidence — report the number,
+  never upgrade it into certainty.
+- Honor `answerability` (`answerable|partial|unanswerable|unknown`) and
+  `conflict`. On `conflict: yes`, surface both sides; never smooth it over.
+- Jev-down is not app-down: `/ask` still answers with degraded fields
+  (`answerability: unknown`, `conflict: false`) and search is unaffected.
+
+## Abstains (exit 0, not an error)
+
+`abstained: true` (`No answer in the evidence.`) means: broaden `q`, fall
+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.
+
+## Mutation policy
+
+- Reads are free: ask, search, tasks list/get, doc list/get/text.
+- 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`),
+  assign others, or archive.
+- Founder-only routes (upload, delete, retry, download originals, PATCH
+  docs/projects) are never the agent's to call — ask the founder.
+
+## Failure table
+
+- 401: key wrong/missing/revoked/disabled — or a founder-only route
+  (the CLI names it). 403: outside the grant or orchestrator-only.
+  404: bad id (the server hides grant gaps as 404 too).
+- 409 on claim: someone already holds the card — the message names them.
+- 429: minute throttle (slow down) or daily budget spent (resets tomorrow).
+- Cannot-reach errors: the API is not booted; `takibi version` probes it.

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "takibibase",
+  "version": "1.0.0",
+  "description": "Thin CLI for the Takibi API: ask, search, tasks, docs. Single file, zero dependencies.",
+  "type": "module",
+  "bin": {
+    "takibi": "./takibi.mjs"
+  },
+  "files": [
+    "takibi.mjs",
+    "SKILL.md",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "license": "SEE LICENSE IN LICENSE",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tofuchick3n/takibi-base.git",
+    "directory": "tools/takibi"
+  },
+  "homepage": "https://takibibase.com/docs/agents",
+  "keywords": [
+    "takibi",
+    "cli",
+    "agents",
+    "knowledge-base"
+  ]
+}

package/takibi.mjs

@@ -0,0 +1,723 @@
+#!/usr/bin/env node
+/**
+ * takibi — thin CLI for the Takibi API. Single file, zero dependencies.
+ *
+ * The contract it bakes in (verified against apps/api/src, 2026-09-20):
+ * - Auth: `Authorization: Bearer <publicId>.<secret>`. The key comes from
+ *   disk only ($TAKIBI_KEY_FILE or ~/.takibi/key) and is NEVER printed —
+ *   not in output, errors, --verbose, or exit traces (see scrub()).
+ * - Origin: never sent. Absent Origin on a Bearer call is correct.
+ * - Ask/search take `q`, never `question`.
+ * - Base URL: $TAKIBI_BASE_URL or ~/.takibi/config, else localhost:3849.
+ *
+ * Pure-client deviations the server forces (no apps/api changes allowed):
+ * - GET /v1/projects is account-only, so `projects` reads a LOCAL map
+ *   (~/.takibi/projects, `name=uuid` lines) and --project resolves names
+ *   through it. UUIDs pass straight through.
+ * - 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.
+ *
+ * Exit codes: 0 ok (honest abstains included), 1 transport/API error,
+ * 2 usage error.
+ */
+import { appendFileSync, existsSync, mkdirSync, readFileSync, 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.0';
+const CLI_VERSION = (() => {
+  try {
+    const pkg = JSON.parse(readFileSync(new URL('./package.json', import.meta.url), 'utf8'));
+    if (typeof pkg.version === 'string' && pkg.version.length > 0) return pkg.version;
+  } catch {
+    // Single-file download: no package.json travels with takibi.mjs.
+  }
+  return BAKED_VERSION;
+})();
+const DEFAULT_BASE_URL = 'http://localhost:3849';
+const REQUEST_TIMEOUT_MS = 90_000;
+const USER_AGENT = `takibibase/${CLI_VERSION}`;
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** Mirrors the server's verifyBearer split: <publicId>.<secret>. */
+const KEY_RE = /^[A-Za-z0-9_.-]+\.[A-Za-z0-9_-]+$/;
+const TASK_STATUSES = ['todo', 'in_progress', 'review', 'done'];
+
+/** The live key, for scrubbing only — never interpolated into output. */
+let activeKey = null;
+const scrub = (s) => (activeKey && s.includes(activeKey) ? s.split(activeKey).join('<redacted>') : s);
+
+/** Sync writes: answers (stdout) and metadata (stderr) stay in order when piped. */
+const out = (s) => writeSync(1, `${s}\n`);
+const err = (s) => writeSync(2, `${scrub(s)}\n`);
+
+class CliError extends Error {
+  constructor(message, { hint = null, status = null, code = null, exitCode = 1 } = {}) {
+    super(message);
+    this.hint = hint;
+    this.status = status;
+    this.code = code;
+    this.exitCode = exitCode;
+  }
+}
+const usageError = (message) => new CliError(message, { exitCode: 2 });
+
+const takibiDir = () => join(homedir(), '.takibi');
+
+/** First non-blank, non-comment line of a file, or null when missing. */
+function firstLine(path) {
+  if (!existsSync(path)) return null;
+  const line = readFileSync(path, 'utf8')
+    .split('\n')
+    .map((l) => l.trim())
+    .find((l) => l && !l.startsWith('#'));
+  return line ?? null;
+}
+
+function resolveBaseUrl() {
+  const raw = (process.env.TAKIBI_BASE_URL ?? '').trim() || firstLine(join(takibiDir(), 'config')) || DEFAULT_BASE_URL;
+  const base = raw.replace(/\/+$/, '');
+  if (!/^https?:\/\/.+/.test(base)) {
+    throw new CliError(`Base URL does not look like an http(s) URL: ${base}`, {
+      hint: 'Set $TAKIBI_BASE_URL or write one URL line to ~/.takibi/config.',
+    });
+  }
+  return base;
+}
+
+function resolveKey() {
+  const path = (process.env.TAKIBI_KEY_FILE ?? '').trim() || join(takibiDir(), 'key');
+  if (!existsSync(path)) {
+    throw new CliError(`No API key file at ${path}.`, {
+      hint: 'Ask the account owner for a key, save its one <publicId>.<secret> line there (chmod 600), and retry.',
+    });
+  }
+  const key = firstLine(path);
+  if (!key || !KEY_RE.test(key)) {
+    throw new CliError(`Key file ${path} does not hold a <publicId>.<secret> line.`, {
+      hint: 'The file holds one line: the publicId, a dot, then the secret. Nothing else.',
+    });
+  }
+  activeKey = key;
+  return key;
+}
+
+/** Local name→uuid map. Returns {map, warnings}; missing file is empty, not an error. */
+function loadProjectMap() {
+  const path = join(takibiDir(), 'projects');
+  const map = new Map();
+  const warnings = [];
+  if (!existsSync(path)) return { map, warnings, path };
+  readFileSync(path, 'utf8')
+    .split('\n')
+    .forEach((raw, i) => {
+      const line = raw.trim();
+      if (!line || line.startsWith('#')) return;
+      const eq = line.indexOf('=');
+      const name = eq === -1 ? '' : line.slice(0, eq).trim();
+      const id = eq === -1 ? '' : line.slice(eq + 1).trim();
+      if (!name || !UUID_RE.test(id)) {
+        warnings.push(`${path}:${i + 1}: skipping malformed line (want name=uuid).`);
+        return;
+      }
+      if (!map.has(name)) map.set(name, id);
+    });
+  return { map, warnings, path };
+}
+
+/** --project value → uuid-or-undefined. Names resolve via the local map. */
+function resolveProjectFlag(value) {
+  if (value === undefined || value === null || value === '') return undefined;
+  const v = String(value).trim();
+  if (UUID_RE.test(v)) return v;
+  const { map } = loadProjectMap();
+  const hit = map.get(v);
+  if (hit) return hit;
+  const known = [...map.keys()];
+  throw new CliError(`Unknown project ${JSON.stringify(v)}.`, {
+    hint:
+      known.length > 0
+        ? `Known names: ${known.join(', ')}. Pass a project UUID, or ask the account owner for this one.`
+        : 'Pass a project UUID, or ask the account owner to add names via `takibi projects --add <name> <uuid>`.',
+  });
+}
+
+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 === 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.';
+    if (/disabled/i.test(msg)) return 'That profile is disabled. Ask the account owner to enable it.';
+    return 'The key is missing or wrong. Check ~/.takibi/key (one <publicId>.<secret> line).';
+  }
+  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 === 429) {
+    if (/too many calls/i.test(msg)) return 'Minute throttle (60/min/key). 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.';
+  return null;
+}
+
+/**
+ * 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 } = {}) {
+  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';
+  if (verbose) err(`→ ${method} ${url}`);
+  const started = Date.now();
+  let res;
+  try {
+    res = await fetch(url, {
+      method,
+      headers,
+      body: body === null ? undefined : JSON.stringify(body),
+      signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+    });
+  } catch (e) {
+    const why = e?.name === 'TimeoutError' ? `timed out after ${Math.round(REQUEST_TIMEOUT_MS / 1000)}s` : (e?.message ?? e);
+    throw new CliError(`Cannot reach the API at ${baseUrl} (${why}).`, {
+      hint: 'Is the API booted? `takibi version` probes it without needing a key.',
+    });
+  }
+  if (verbose) err(`← ${res.status} in ${Date.now() - started}ms`);
+  let data = null;
+  try {
+    data = await res.json();
+  } catch {
+    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.`,
+    });
+  }
+  if (!res.ok) {
+    const message = data?.error?.message || `Request failed (HTTP ${res.status}).`;
+    throw new CliError(`${label ?? path}: ${message}`, {
+      status: res.status,
+      code: data?.error?.code ?? null,
+      hint: hintFor(res.status, message),
+    });
+  }
+  return data;
+}
+
+const qparams = (entries) => {
+  const p = new URLSearchParams();
+  for (const [k, v] of entries) if (v !== undefined && v !== null && v !== '') p.set(k, String(v));
+  return p.toString() ? p : null;
+};
+
+const HELP = `takibi ${CLI_VERSION} — thin CLI for the Takibi API.
+
+Usage: takibi [global options] <command> [args]
+
+Commands:
+  ask -q "..."            Answer from the evidence (spans + citations + support)
+  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 claim <id>        Claim an open to-do card (atomic, one winner)
+  tasks status <id> <st>  Move a card: todo | in_progress | review | done
+  tasks artifact add <taskId> <url>   Attach a link-only artifact
+  doc list                Documents (metadata)
+  doc get <id>            One document's metadata
+  doc text <id>           Converted text of one document
+  projects                Saved project 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 ~/.takibi/projects;
+                             single-grant keys may omit it entirely.
+  --folder <uuid>            Folder scope (ask, search, doc list only).
+  --json                     Raw server 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.
+
+Per-command options:
+  ask/search: -q, --query <text> (or a bare positional), -k <n> (ask 1-12, search 1-20)
+  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>
+  projects: --add <name> <uuid>
+
+Setup: save the owner-provided key (one <publicId>.<secret> line) to
+~/.takibi/key (chmod 600), optional base URL line to ~/.takibi/config,
+project names via \`takibi projects --add\`. Env overrides: $TAKIBI_KEY_FILE,
+$TAKIBI_BASE_URL. Then \`takibi version\` to probe the API.
+
+Reads are free. 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.
+`;
+
+/**
+ * Pull globals out of argv wherever they sit; the rest stays positional for
+ * the command parser. Unknown --options fail loud (exit 2), so a typo like
+ * --question never silently becomes something else.
+ */
+function parseArgv(argv) {
+  const globals = { project: undefined, folder: undefined, json: false, verbose: false, help: false, version: false };
+  const rest = [];
+  const takeValue = (flag, i) => {
+    const v = argv[i + 1];
+    if (v === undefined || v === '--') throw usageError(`${flag} needs a value.`);
+    return [v, i + 1];
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--') {
+      rest.push(...argv.slice(i + 1));
+      break;
+    }
+    if (a === '--json') globals.json = true;
+    else if (a === '--verbose' || a === '-v') globals.verbose = true;
+    else if (a === '--help' || a === '-h') globals.help = true;
+    else if (a === '--version') globals.version = true;
+    else if (a === '--project' || a === '-p') {
+      const [v, ni] = takeValue(a, i);
+      globals.project = v;
+      i = ni;
+    } else if (a.startsWith('--project=')) globals.project = a.slice('--project='.length);
+    else if (a === '--folder' || a === '-f') {
+      const [v, ni] = takeValue(a, i);
+      globals.folder = v;
+      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') {
+      rest.push(a);
+      if (a !== '--all') {
+        const [v, ni] = takeValue(a, i);
+        rest.push(v);
+        i = ni;
+        if (a === '--add') {
+          const [v2, ni2] = takeValue(a, i);
+          rest.push(v2);
+          i = ni2;
+        }
+      }
+    } else if (a.startsWith('-') && a.length > 1) {
+      throw usageError(`Unknown option ${JSON.stringify(a)}. See \`takibi --help\`.`);
+    } else {
+      rest.push(a);
+    }
+  }
+  return { globals, rest };
+}
+
+/** Parse `-q/--query <text>`, `-k <n>` plus one optional positional query. */
+function parseQueryArgs(tokens, { kMin, kMax }) {
+  let q = null;
+  let k = null;
+  const positionals = [];
+  for (let i = 0; i < tokens.length; i++) {
+    const t = tokens[i];
+    if (t === '-q' || t === '--query' || t === '--q') q = tokens[++i];
+    else if (t === '-k') k = tokens[++i];
+    else positionals.push(t);
+  }
+  if (q === null || q === undefined || q === '') {
+    if (positionals.length === 0) throw usageError('Pass the query: -q "..." (tip: the param is q, never question).');
+    q = positionals.shift();
+  }
+  if (positionals.length > 0) throw usageError(`Unexpected ${JSON.stringify(positionals[0])}. Pass the query once.`);
+  if (!String(q).trim()) throw usageError('The query needs at least one non-space character.');
+  if (k !== null && k !== undefined) {
+    const n = Number(k);
+    if (!Number.isInteger(n) || n < kMin || n > kMax) throw usageError(`-k takes an integer ${kMin}-${kMax}.`);
+    k = n;
+  }
+  return { q: String(q), k };
+}
+
+const fmtSupport = (a) =>
+  `support ${Number(a.support ?? 0).toFixed(2)} (${a.supportVersion ?? 'v?'}) · answerability: ${a.answerability ?? 'unknown'} · conflict: ${a.conflict ? 'yes — flag it, do not smooth it over' : 'no'} · candidates: ${a.candidateCount ?? 0}`;
+
+function renderAsk(a, q) {
+  if (a.abstained || !a.spans?.length) {
+    out('No answer in the evidence.');
+    err(`(${fmtSupport(a)} — broaden q, fall back to \`takibi search\`, and say so honestly.)`);
+    return;
+  }
+  a.spans.forEach((s, i) => {
+    out(`[${i + 1}] ${s.text}`);
+    out(`    ${s.documentName} — ${s.title}`);
+    out(`    doc ${s.documentId} · chunk ${s.chunkId}`);
+  });
+  err(fmtSupport(a));
+}
+
+function renderSearch(results, q) {
+  if (!results.length) {
+    out(`No results for ${JSON.stringify(q)}.`);
+    return;
+  }
+  results.forEach((r, i) => {
+    out(`[${i + 1}] ${r.snippet}`);
+    out(`    ${r.documentName} — ${r.title} · rank ${r.rank} · doc ${r.documentId} · chunk ${r.chunkId}`);
+  });
+}
+
+const taskLine = (t) => {
+  const bits = [t.id, `· ${t.status}`, `· ${t.title}`, `· ${t.assigneeName ?? 'unassigned'}`];
+  if (t.blocked) bits.push(`· blocked: ${t.blockedReason || 'no reason given'}`);
+  if (t.artifacts?.length) bits.push(`· ${t.artifacts.length} artifact${t.artifacts.length === 1 ? '' : 's'}`);
+  if (t.archivedAt) bits.push('· archived');
+  if (t.dueAt) bits.push(`· due ${t.dueAt}`);
+  return bits.join(' ');
+};
+
+function renderTask(t) {
+  out(taskLine(t));
+  if (t.body) out(`\n${t.body}`);
+  if (t.artifacts?.length) {
+    out('');
+    for (const a of t.artifacts) out(`  - ${a.url}${a.note ? ` — ${a.note}` : ''} [${a.id}]`);
+  }
+  err(`created ${t.createdAt} · updated ${t.updatedAt}`);
+}
+
+const fmtBytes = (n) => {
+  if (n === null || n === undefined) return '?';
+  if (n < 1024) return `${n} B`;
+  if (n < 1024 * 1024) return `${(n / 1024).toFixed(1)} KB`;
+  return `${(n / 1024 / 1024).toFixed(1)} MB`;
+};
+
+const docLine = (d) => `${d.id} · ${d.name} · ${d.mime} · ${fmtBytes(d.bytes)} · ${d.status}${d.stale ? ' · stale' : ''}`;
+
+function renderDoc(d) {
+  out(docLine(d));
+  out(`  folder: ${d.folderId ?? '(unfiled)'} · chars: ${d.charCount ?? '?'} · confidence: ${d.confidence ?? '?'}`);
+  out(`  ttl: ${d.ttlDays}d · created: ${d.createdAt}`);
+  if (d.supersedesId) out(`  supersedes: ${d.supersedesId}`);
+  if (d.quarantineReason) out(`  quarantined: ${d.quarantineReason} — ${d.quarantineAction ?? ''}`);
+}
+
+/** Shared context: baseUrl always; key for every command except version/help. */
+function ctxFor(globals, { needKey }) {
+  const baseUrl = resolveBaseUrl();
+  const key = needKey ? resolveKey() : null;
+  const projectId = resolveProjectFlag(globals.project);
+  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.)`);
+  }
+  return { baseUrl, key, projectId, folder: globals.folder || undefined, json: globals.json, verbose: globals.verbose };
+}
+
+async function cmdAsk(tokens, globals) {
+  const { q, k } = parseQueryArgs(tokens, { kMin: 1, kMax: 12 });
+  const ctx = ctxFor(globals, { needKey: true });
+  // GET carries the contract; POST only when q outgrows a sane URL.
+  const data =
+    q.length > 1500
+      ? await api('POST', '/v1/ask', {
+          ...ctx,
+          body: { q, projectId: ctx.projectId, folderId: ctx.folder, k: k ?? undefined },
+          label: 'ask',
+        })
+      : await api('GET', '/v1/ask', {
+          ...ctx,
+          query: qparams([
+            ['q', q],
+            ['projectId', ctx.projectId],
+            ['folderId', ctx.folder],
+            ['k', k],
+          ]),
+          label: 'ask',
+        });
+  if (ctx.json) out(JSON.stringify(data, null, 2));
+  else renderAsk(data, q);
+}
+
+async function cmdSearch(tokens, globals) {
+  const { q, k } = parseQueryArgs(tokens, { kMin: 1, kMax: 20 });
+  const ctx = ctxFor(globals, { needKey: true });
+  const data = await api('GET', '/v1/search', {
+    ...ctx,
+    query: qparams([
+      ['q', q],
+      ['projectId', ctx.projectId],
+      ['folderId', ctx.folder],
+      ['k', k],
+    ]),
+    label: 'search',
+  });
+  if (ctx.json) out(JSON.stringify(data, null, 2));
+  else renderSearch(data.results ?? [], q);
+}
+
+async function listTasks(ctx, includeArchived) {
+  const data = await api('GET', '/v1/tasks', {
+    ...ctx,
+    query: qparams([
+      ['projectId', ctx.projectId],
+      ['includeArchived', includeArchived ? '1' : undefined],
+    ]),
+    label: 'tasks list',
+  });
+  return data.tasks ?? [];
+}
+
+async function cmdTasks(tokens, globals) {
+  if (globals.folder) throw usageError('--folder does not apply to tasks: cards are project-wide, folder grants stay a KB-read concept.');
+  const [sub, ...rest] = tokens;
+  if (!sub || sub === 'list') {
+    let includeArchived = false;
+    for (const t of rest) {
+      if (t === '--all') includeArchived = true;
+      else throw usageError(`Unexpected ${JSON.stringify(t)}. Usage: takibi tasks list [--all]`);
+    }
+    const ctx = ctxFor(globals, { needKey: true });
+    const tasks = await listTasks(ctx, includeArchived);
+    if (ctx.json) {
+      out(JSON.stringify({ tasks }, null, 2));
+      return;
+    }
+    if (!tasks.length) out(includeArchived ? 'No tasks (archived included).' : 'No tasks.');
+    for (const t of tasks) out(taskLine(t));
+    return;
+  }
+  if (sub === 'get') {
+    const [id, extra] = rest;
+    if (!id || extra) throw usageError('Usage: takibi tasks get <id>');
+    const ctx = 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 (!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);
+    return;
+  }
+  if (sub === 'claim') {
+    const [id, extra] = rest;
+    if (!id || extra) throw usageError('Usage: takibi tasks claim <id>');
+    const ctx = ctxFor(globals, { needKey: true });
+    const data = await api('POST', `/v1/tasks/${id}/claim`, { ...ctx, query: qparams([['projectId', ctx.projectId]]), label: 'tasks claim' });
+    if (ctx.json) out(JSON.stringify(data, null, 2));
+    else renderTask(data.task);
+    return;
+  }
+  if (sub === 'status') {
+    const [id, to, extra] = rest;
+    if (!id || !to || extra) throw usageError('Usage: takibi tasks status <id> <todo|in_progress|review|done>');
+    if (!TASK_STATUSES.includes(to)) throw usageError(`Status is one of ${TASK_STATUSES.join(' | ')}, not ${JSON.stringify(to)}.`);
+    const ctx = ctxFor(globals, { needKey: true });
+    const data = await api('PATCH', `/v1/tasks/${id}`, {
+      ...ctx,
+      query: qparams([['projectId', ctx.projectId]]),
+      body: { status: to },
+      label: 'tasks status',
+    });
+    if (ctx.json) out(JSON.stringify(data, null, 2));
+    else renderTask(data.task);
+    return;
+  }
+  if (sub === 'artifact' || sub === 'artifacts') {
+    const [verb, taskId, url, ...flagTokens] = rest;
+    if (verb !== 'add' || !taskId || !url) throw usageError('Usage: takibi tasks artifact add <taskId> <url> [--note <t> --size <n> --hash <h>]');
+    const flags = {};
+    for (let i = 0; i < flagTokens.length; i++) {
+      const f = flagTokens[i];
+      if (f === '--note' || f === '--size' || f === '--hash') flags[f.slice(2)] = flagTokens[++i];
+      else throw usageError(`Unexpected ${JSON.stringify(f)}. Usage: takibi tasks artifact add <taskId> <url> [--note <t> --size <n> --hash <h>]`);
+    }
+    if (flags.note !== undefined && flags.note === '') throw usageError('--note needs non-empty text.');
+    if (flags.size !== undefined) {
+      const n = Number(flags.size);
+      if (!Number.isInteger(n) || n < 0) throw usageError('--size takes an integer >= 0 (asserted bytes).');
+      flags.size = n;
+    }
+    const ctx = ctxFor(globals, { needKey: true });
+    const data = await api('POST', `/v1/tasks/${taskId}/artifacts`, {
+      ...ctx,
+      query: qparams([['projectId', ctx.projectId]]),
+      body: { url, note: flags.note, assertedSize: flags.size, assertedHash: flags.hash },
+      label: 'tasks artifact add',
+    });
+    if (ctx.json) out(JSON.stringify(data, null, 2));
+    else {
+      out(`attached ${data.artifact.id}`);
+      out(`  ${data.artifact.url}${data.artifact.note ? ` — ${data.artifact.note}` : ''}`);
+    }
+    return;
+  }
+  throw usageError(`Unknown tasks command ${JSON.stringify(sub)}. Use list | get | claim | status | artifact add.`);
+}
+
+async function cmdDoc(tokens, globals) {
+  const [sub, ...rest] = tokens;
+  if (!sub || sub === 'list') {
+    let limit;
+    for (let i = 0; i < rest.length; i++) {
+      if (rest[i] === '--limit') limit = rest[++i];
+      else throw usageError(`Unexpected ${JSON.stringify(rest[i])}. Usage: takibi doc list [--limit <n>]`);
+    }
+    const ctx = ctxFor(globals, { needKey: true });
+    const data = await api('GET', '/v1/documents', {
+      ...ctx,
+      query: qparams([
+        ['projectId', ctx.projectId],
+        ['folderId', ctx.folder],
+        ['limit', limit],
+      ]),
+      label: 'doc list',
+    });
+    const docs = data.documents ?? [];
+    if (ctx.json) {
+      out(JSON.stringify({ documents: docs }, null, 2));
+      return;
+    }
+    if (!docs.length) out('No documents.');
+    for (const d of docs) out(docLine(d));
+    return;
+  }
+  if (sub === 'get' || sub === 'text') {
+    const [id, ...flagTokens] = rest;
+    if (!id) throw usageError(`Usage: takibi doc ${sub} <id>`);
+    let maxChars;
+    for (let i = 0; i < flagTokens.length; i++) {
+      if (sub === 'text' && flagTokens[i] === '--max-chars') maxChars = flagTokens[++i];
+      else throw usageError(`Unexpected ${JSON.stringify(flagTokens[i])}. Usage: takibi doc ${sub} <id>${sub === 'text' ? ' [--max-chars <n>]' : ''}`);
+    }
+    const ctx = ctxFor(globals, { needKey: true });
+    if (sub === 'get') {
+      const data = await api('GET', `/v1/documents/${id}`, { ...ctx, query: qparams([['projectId', ctx.projectId]]), label: 'doc get' });
+      if (ctx.json) out(JSON.stringify(data, null, 2));
+      else renderDoc(data.document);
+      return;
+    }
+    const data = await api('GET', `/v1/documents/${id}/text`, {
+      ...ctx,
+      query: qparams([
+        ['projectId', ctx.projectId],
+        ['maxChars', maxChars],
+      ]),
+      label: 'doc text',
+    });
+    if (ctx.json) {
+      out(JSON.stringify(data, null, 2));
+      return;
+    }
+    if (data.text === null) {
+      out('No converted text for that document.');
+      return;
+    }
+    out(data.text);
+    if (data.truncated) err('(truncated — the server caps converted text; narrow with search/ask.)');
+    return;
+  }
+  if (sub === 'download' || sub === 'delete' || sub === 'retry' || sub === 'upload') {
+    // 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).
+    throw new CliError(`\`doc ${sub}\` is account-only — keys cannot call it.`, {
+      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.`);
+}
+
+async function cmdProjects(tokens, globals) {
+  const { map, warnings, path } = loadProjectMap();
+  for (const w of warnings) err(`warning: ${w}`);
+  if (tokens[0] === '--add') {
+    const [, name, id, extra] = tokens;
+    if (!name || !id || extra) throw usageError('Usage: takibi projects --add <name> <uuid>');
+    if (name.includes('=') || name.includes('\n')) throw usageError('Project names cannot contain = or newlines.');
+    if (!UUID_RE.test(id)) throw usageError(`${JSON.stringify(id)} is not a UUID.`);
+    const prior = map.get(name);
+    if (prior === id) {
+      if (!globals.json) out(`saved ${name} → ${id} (already known)`);
+      else out(JSON.stringify({ name, id }, null, 2));
+      return;
+    }
+    if (prior) {
+      throw new CliError(`${JSON.stringify(name)} already maps to ${prior} in ${path}.`, {
+        hint: 'Edit the file by hand to re-point a name; the CLI never overwrites silently.',
+      });
+    }
+    mkdirSync(takibiDir(), { recursive: true });
+    appendFileSync(path, `${name}=${id}\n`, { mode: 0o600 });
+    if (!globals.json) out(`saved ${name} → ${id}`);
+    else out(JSON.stringify({ name, id }, null, 2));
+    return;
+  }
+  if (tokens.length > 0) throw usageError(`Unexpected ${JSON.stringify(tokens[0])}. Usage: takibi projects [--add <name> <uuid>]`);
+  const entries = [...map.entries()].map(([name, id]) => ({ name, id }));
+  if (globals.json) {
+    out(JSON.stringify({ projects: entries }, null, 2));
+    return;
+  }
+  if (!entries.length) {
+    out('No project names saved.');
+    err(`(GET /v1/projects is account-only, so names live in ${path} as name=uuid lines.\nAdd them with \`takibi projects --add <name> <uuid>\` (ask the account owner for UUIDs),\nor pass --project <uuid> directly. Single-grant keys may omit --project.)`);
+    return;
+  }
+  for (const { name, id } of entries) out(`${name} → ${id}`);
+}
+
+async function cmdVersion(globals) {
+  const baseUrl = resolveBaseUrl();
+  const data = await api('GET', '/version', { baseUrl, verbose: globals.verbose, label: 'version' });
+  if (globals.json) out(JSON.stringify(data, null, 2));
+  else out(`${data.service ?? 'takibi-api'} ${data.version ?? '?'} · jev ${data.jev ?? '?'} · via ${baseUrl}`);
+}
+
+async function main(argv) {
+  const { globals, rest } = parseArgv(argv);
+  if (globals.version) {
+    out(`takibibase ${CLI_VERSION}`);
+    return;
+  }
+  const [cmd, ...tokens] = rest;
+  if (globals.help || !cmd) {
+    out(HELP);
+    return;
+  }
+  if (cmd === 'ask') return cmdAsk(tokens, globals);
+  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 === 'projects') return cmdProjects(tokens, globals);
+  if (cmd === 'version') return cmdVersion(globals);
+  throw usageError(`Unknown command ${JSON.stringify(cmd)}. See \`takibi --help\`.`);
+}
+
+try {
+  await main(process.argv.slice(2));
+} catch (e) {
+  if (e instanceof CliError) {
+    const { globals } = (() => {
+      try {
+        return parseArgv(process.argv.slice(2));
+      } catch {
+        return { globals: { json: false } };
+      }
+    })();
+    if (globals.json) {
+      err(JSON.stringify({ error: { code: e.code ?? (e.exitCode === 2 ? 'USAGE' : 'ERROR'), message: e.message, ...(e.hint ? { hint: e.hint } : {}), ...(e.status ? { status: e.status } : {}) } }, null, 2));
+    } else {
+      err(`takibi: ${e.message}`);
+      if (e.hint) err(`hint: ${e.hint}`);
+    }
+    process.exit(e.exitCode);
+  }
+  err(`takibi: unexpected failure: ${e?.message ?? e}`);
+  process.exit(1);
+}