takibibase 1.2.0 → 1.3.0

package/README.md

@@ -22,12 +22,15 @@ document, and Notes API routes; its behavior is documented in `SKILL.md`.
 ## 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`, `notes`), scoped to its
-   project(s). Copy the `<publicId>.<secret>` shown once.
+   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
+   a whole-collection grant — folder-only or tag-only seats cannot use them.
+   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`.
+3. Only for local setups: one base-URL line in `~/.takibi/config`
+   (default `https://app.takibibase.com`). Env overrides:
+   `$TAKIBI_KEY_FILE`, `$TAKIBI_BASE_URL`.
 4. `takibi projects` — lists the projects this key can reach, straight
    from the API. Names resolve in `--project` (UUIDs work too, from
    Settings → Projects); single-grant keys may omit it. Only for offline
@@ -37,11 +40,14 @@ document, and Notes API routes; its behavior is documented in `SKILL.md`.
 
 ## Give an agent
 
-Key file in place + the skill text (or installed skill). 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.
+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 —
+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.
 
 ## Known edges
 

package/SKILL.md

@@ -12,21 +12,20 @@ error hints.
 ## Setup (once)
 
 - CLI: `npx takibibase …` (zero-install), `takibi …` (global install),
-  or `node tools/takibi/takibi.mjs …` from the takibi-base checkout
+  or `node <path>/takibi.mjs …` for the single-file download
   (use the alias when it exists).
-- Key: the founder saves one `<publicId>.<secret>` line to `~/.takibi/key`
+- Key: the owner 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`.
+- Base URL defaults to Takibi's servers (`https://app.takibibase.com`).
+  Only local setups override with `$TAKIBI_BASE_URL` or one URL line in
+  `~/.takibi/config`.
 - 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.
 - 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`). Silence it with
-  `TAKIBI_NO_UPDATE_CHECK=1`; point it at a mirror with
-  `TAKIBI_REGISTRY_URL`.
+  stderr when behind (never on `--json`).
 
 ## Commands
 
@@ -38,7 +37,7 @@ error hints.
 - `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`.
+  `doc download` is account-only; the CLI says so — use `doc text`.
 - `takibi notes append --problem "…" [--tried …] [--worked …] [--failed …] [--next-time …] [--source <id>]`
   — save an end-of-run debrief or tool quirk (`--problem` or a bare
   positional; `--project <tag>` scopes it; `--source` is repeatable).
@@ -103,21 +102,33 @@ prose presented as sourced.
 
 - Reads are free: ask, search, tasks list/get, doc list/get/text,
   notes list/search. Agents may append their own debriefs (auto-expire).
-- Notes export/keep/remove need founder approval already given in the
+- 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/artifact writes only with founder approval already
+- Task claim/status/artifact 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/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.
+  moving or touching it; only orchestrators/owners accept (`review→done`),
+  assign others, or archive. Title/body edits need the create cap —
+  claim-only keys can drive a card but cannot rewrite its text.
+- 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
+  missing-capability 403 first).
+- 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
+  docs/projects) are never the agent's to call — ask the account owner.
 
 ## Failure table
 
-- 401: key wrong/missing/revoked/disabled — or a founder-only route
-  (the CLI names it). 403: outside the grant or orchestrator-only.
+- 401: key wrong/missing/revoked/disabled — or an account-only route
+  (the CLI names it). 403: outside the grant, orchestrator-only, missing
+  capability (notes are opt-in), or folder-/tag-only key on a board route.
   404: bad id (the server hides grant gaps as 404 too).
 - 409 on claim: someone already holds the card — the message names them.
+- 422 SECRET_BLOCKED: the secret filter fired — it covers task
+  title/body/blockedReason/artifact text as well as notes. Strip keys,
+  tokens, and credentials and retry.
 - 429: minute throttle (slow down) or daily budget spent (resets tomorrow).
-- Cannot-reach errors: the API is not booted; `takibi version` probes it.
+- Cannot-reach errors: check the network and service status; `takibi version` probes it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "takibibase",
-  "version": "1.2.0",
+  "version": "1.3.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"
+    "test": "node --test notes.test.mjs skill.test.mjs"
   },
   "license": "SEE LICENSE IN LICENSE",
   "repository": {

package/takibi.mjs

@@ -8,7 +8,7 @@
  *   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.
+ * - Base URL: $TAKIBI_BASE_URL or ~/.takibi/config, else Takibi's servers.
  *
  * Pure-client deviations the server forces (no apps/api changes allowed):
  * - Keys list their own granted scope via GET /v1/projects, so `projects`
@@ -34,7 +34,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.2.0';
+const BAKED_VERSION = '1.3.0';
 const CLI_INFO = (() => {
   try {
     const pkg = JSON.parse(readFileSync(new URL('./package.json', import.meta.url), 'utf8'));
@@ -47,7 +47,7 @@ const CLI_INFO = (() => {
   return { version: BAKED_VERSION, singleFile: true };
 })();
 const CLI_VERSION = CLI_INFO.version;
-const DEFAULT_BASE_URL = 'http://localhost:3849';
+const DEFAULT_BASE_URL = 'https://app.takibibase.com';
 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;
@@ -97,11 +97,10 @@ function versionBehind(current, latest) {
 /** Once-a-day latest-version poll. Stderr only (stdout stays clean),
  * best-effort, never fails the command. Failures are cached too, so an
  * unreachable registry costs one slow run a day, not every invocation.
- * Skipped for --json (errors there are a single JSON object), in CI, and
- * with TAKIBI_NO_UPDATE_CHECK=1. */
+ * Skipped for --json (errors there are a single JSON object) and in CI. */
 async function maybeNotifyUpdate({ json = false } = {}) {
   try {
-    if (json || process.env.CI || process.env.TAKIBI_NO_UPDATE_CHECK === '1') return;
+    if (json || process.env.CI) return;
     const path = join(takibiDir(), 'update-check');
     let cached = null;
     try {
@@ -274,11 +273,16 @@ function hintFor(status, serverMessage) {
     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 === 403) {
+    // 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;
+    return 'Outside this key’s grant, or an owner/orchestrator-only move. Check `tasks get`, or ask the account owner.';
+  }
   if (status === 404) return 'Bad id, or outside this key’s grant (the server hides the difference).';
   if (status === 409) return null; // claim conflicts name the winner already.
   if (status === 422) {
-    if (/secret/i.test(msg)) return 'The secret filter fired — strip keys, tokens, and credentials from the note and retry. Secrets never belong in notes.';
+    if (/secret/i.test(msg)) return 'The secret filter fired — strip keys, tokens, and credentials and retry. Secrets never belong in notes or task text.';
     return 'The server rejected that shape. Check the fields and retry.';
   }
   if (status === 429) {
@@ -313,7 +317,7 @@ async function api(method, path, { query = null, body = null, key = null, baseUr
   } 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.',
+      hint: 'Check the network and service status; `takibi version` probes it without needing a key.',
     });
   }
   if (verbose) err(`← ${res.status} in ${Date.now() - started}ms`);
@@ -367,6 +371,8 @@ Commands:
   notes remove <id> <ver> Discard a note (expected version)
   projects                Granted projects (names -> uuids for --project)
   version                 What build is serving + jev wired|unwired (no key needed)
+  skill                   Print the takibi-use agent skill (pipe it to an agent)
+  skill --install         Install the skill into agent skills dirs
 
 Global options (accepted before or after the command):
   --project <name-or-uuid>   Project scope. Names resolve via the API list,
@@ -391,12 +397,16 @@ Per-command options:
   notes export: --since <ts> or --note <uuid> (repeatable; up to 50)
   notes keep/remove: <id> <expected-version> from notes list --all
   projects: --add <name> <uuid>
+  skill: --install [--force] [--agents] [--claude] [--codex] [--dir <skills-root>]
 
 Setup: save the owner-provided key (one <publicId>.<secret> line) to
-~/.takibi/key (chmod 600), optional base URL line to ~/.takibi/config.
+~/.takibi/key (chmod 600). The API defaults to Takibi's servers; only
+local setups need a base URL line in ~/.takibi/config.
 Env overrides: $TAKIBI_KEY_FILE, $TAKIBI_BASE_URL. Then \`takibi version\`
 to probe the API and \`takibi projects\` to see this key's scope
 (\`projects --add\` keeps local aliases for offline use).
+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,
@@ -437,9 +447,9 @@ function parseArgv(argv) {
       i = ni;
     }
     else if (a.startsWith('--folder=')) globals.folder = a.slice('--folder='.length);
-    else if (a === '--query' || a === '-q' || a === '--q' || a === '-k' || a === '--limit' || a === '--max-chars' || a === '--all' || a === '--add' || a === '--note' || a === '--size' || a === '--hash' || a === '--problem' || a === '--tried' || a === '--worked' || a === '--failed' || a === '--next-time' || a === '--source' || a === '--since' || a === '--run-id') {
+    else if (a === '--query' || a === '-q' || a === '--q' || a === '-k' || a === '--limit' || a === '--max-chars' || a === '--all' || a === '--add' || a === '--note' || a === '--size' || a === '--hash' || a === '--problem' || a === '--tried' || a === '--worked' || a === '--failed' || a === '--next-time' || a === '--source' || a === '--since' || a === '--run-id' || a === '--install' || a === '--force' || a === '--agents' || a === '--claude' || a === '--codex' || a === '--dir') {
       rest.push(a);
-      if (a !== '--all') {
+      if (a !== '--all' && a !== '--install' && a !== '--force' && a !== '--agents' && a !== '--claude' && a !== '--codex') {
         const [v, ni] = takeValue(a, i);
         rest.push(v);
         i = ni;
@@ -1075,6 +1085,132 @@ async function cmdVersion(globals) {
   else out(`${data.service ?? 'takibi-api'} ${data.version ?? '?'} · jev ${data.jev ?? '?'} · via ${baseUrl}`);
 }
 
+const SKILL_NAME = 'takibi-use';
+const SKILL_FILE = 'SKILL.md';
+const DOCS_AGENTS_URL = 'https://takibibase.com/docs/agents';
+
+/** Test hook: redirect ~ for skill installs only (key resolution always uses the real home). */
+const skillHome = () => process.env.TAKIBI_HOME || homedir();
+
+/** The skill text travelling next to the CLI in the published package; null in the lone-file copy. */
+function skillText() {
+  try {
+    return readFileSync(new URL('./SKILL.md', import.meta.url), 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+const SKILL_TARGETS = [
+  { flag: '--agents', harness: '.agents', dir: '.agents/skills' },
+  { flag: '--claude', harness: '.claude', dir: '.claude/skills' },
+  { flag: '--codex', harness: '.codex', dir: '.codex/skills' },
+];
+
+const SKILL_USAGE = 'Usage: takibi skill [--install [--force] [--agents] [--claude] [--codex] [--dir <skills-root>]]';
+
+/** First-run skill nudge. Stderr only (stdout stays clean), best-effort,
+ * never fails the command. Skipped for --json, in CI, with
+ * TAKIBI_NO_SKILL_NUDGE=1, when any standard skills dir already holds the
+ * skill, and within a day of the last nudge. */
+function maybeNudgeSkill({ json = false } = {}) {
+  try {
+    if (json || process.env.CI || process.env.TAKIBI_NO_SKILL_NUDGE === '1') return;
+    const home = skillHome();
+    if (SKILL_TARGETS.some((t) => existsSync(join(home, t.dir, SKILL_NAME, SKILL_FILE)))) return;
+    const path = join(home, '.takibi', 'skill-nudge');
+    let lastAt = 0;
+    try {
+      const cached = JSON.parse(readFileSync(path, 'utf8'));
+      if (typeof cached?.at === 'number') lastAt = cached.at;
+    } catch {
+      // First run: no marker yet.
+    }
+    if (Date.now() - lastAt < UPDATE_CHECK_TTL_MS) return;
+    try {
+      mkdirSync(join(home, '.takibi'), { recursive: true });
+      writeFileSync(path, JSON.stringify({ at: Date.now() }));
+    } catch {
+      // 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.');
+  } catch {
+    // Nudges never fail commands.
+  }
+}
+
+function cmdSkill(tokens, globals) {
+  let install = false;
+  let force = false;
+  let customRoot = null;
+  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);
+    } 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)) {
+    throw usageError(`Those flags need \`--install\`. ${SKILL_USAGE}`);
+  }
+  const text = skillText();
+  if (!install) {
+    if (text !== null) {
+      out(text.trimEnd());
+      return;
+    }
+    out(`# ${SKILL_NAME} — not bundled in this single-file copy\n\nInstall the package and retry:\n  npm i -g takibibase && takibi skill --install\nDocs: ${DOCS_AGENTS_URL}`);
+    return;
+  }
+  if (text === null) {
+    throw new CliError('This single-file copy carries no SKILL.md to install.', {
+      hint: `Install the package first (\`npm i -g takibibase\`), then \`takibi skill --install\`. Docs: ${DOCS_AGENTS_URL}.`,
+    });
+  }
+  const home = skillHome();
+  let targets;
+  if (customRoot && 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 }];
+  const results = [];
+  for (const t of targets) {
+    const dir = t.custom ? join(customRoot, SKILL_NAME) : join(home, t.dir, SKILL_NAME);
+    const dest = join(dir, SKILL_FILE);
+    if (existsSync(dest)) {
+      let same = false;
+      try {
+        same = readFileSync(dest, 'utf8') === text;
+      } catch {
+        same = false;
+      }
+      if (same) {
+        results.push({ path: dest, status: 'already-installed' });
+        continue;
+      }
+      if (!force) {
+        throw new CliError(`${dest} already holds a different skill file.`, {
+          hint: 'Re-run with --force to overwrite it.',
+        });
+      }
+    }
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(dest, text);
+    results.push({ path: dest, status: 'installed' });
+  }
+  if (globals.json) out(JSON.stringify({ skill: SKILL_NAME, results }, null, 2));
+  else for (const r of results) out(`${r.status === 'installed' ? 'installed' : 'already installed'} ${r.path}`);
+}
+
 async function main(argv) {
   const { globals, rest } = parseArgv(argv);
   if (globals.version) {
@@ -1088,6 +1224,7 @@ async function main(argv) {
     out(HELP);
     return;
   }
+  if (cmd !== 'skill') maybeNudgeSkill({ json: globals.json });
   if (cmd === 'ask') return cmdAsk(tokens, globals);
   if (cmd === 'search') return cmdSearch(tokens, globals);
   if (cmd === 'tasks' || cmd === 'task') return cmdTasks(tokens, globals);
@@ -1095,6 +1232,7 @@ async function main(argv) {
   if (cmd === 'notes' || cmd === 'note') return cmdNotes(tokens, globals);
   if (cmd === 'projects') return cmdProjects(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\`.`);
 }