takibibase 1.0.3 → 1.3.0

package/README.md

@@ -9,9 +9,8 @@ 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. Its only server pairing is
-`GET /v1/projects`, which lists a key's granted collections — everything
-else lives in this directory.
+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.
   Run it from a checkout as `node tools/takibi/takibi.mjs …`, or alias it:
@@ -23,12 +22,15 @@ else lives in this directory.
 ## 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.
+   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
@@ -38,10 +40,14 @@ else lives in this directory.
 
 ## 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.
+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

@@ -1,6 +1,6 @@
 ---
 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.
+description: Use the Takibi knowledge base and task board through the takibi CLI (ask, search, tasks, docs, notes). Use whenever the user asks about Takibi content, evidence-backed answers from their docs, or crew task boards.
 ---
 
 # takibi-use: Takibi via the CLI
@@ -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,24 @@ 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).
+  Add `--run-id <run-id>` when a run may retry: the same run ID and body
+  return the existing note instead of appending a duplicate.
+- `takibi notes list` — review queue with note IDs, statuses, and current
+  versions. `takibi notes list --all` shows the inventory, including notes
+  on hold. `--project <tag>` filters either list by the exact project tag.
+- `takibi notes search -q "…"` — top-2 agent notes for the query.
+- `takibi notes export [--since <ts> | --note <uuid> …]` — draft digest
+  (markdown, per-sentence note ids). Repeat `--note` to pick up to 50
+  specific live notes. Without options, export uses the delta since the
+  last export. Export stamps included notes and records the action.
+- `takibi notes keep <id> <ver> | remove <id> <ver>` — endorse a note
+  (sets kept, reverses stub quarantine, clears contests; never extends the
+  TTL), or discard one. Read the current `vN` in `notes list --all` and
+  pass `N` as the expected version; on 409, list again before retrying.
 - `--json` anywhere prints raw server JSON. `--verbose` logs requests
   (never the key). Exit 0 = ok, 1 = transport/API error, 2 = usage error.
 
@@ -59,21 +75,60 @@ 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.
 
+## Notes (agent scratchpad, not canon)
+
+- When to use: end-of-run debriefs (problem, what you tried, what worked,
+  what failed, what to try next time) and tool quirks worth remembering.
+  Append at the end of a run; search before retrying something odd. Use
+  the same project tag on related notes so they stay scoped together.
+- To correct a note, append a new note with the corrected facts and source
+  IDs, then ask the owner to remove the obsolete note. There is no
+  in-place edit route. Never overwrite a note ID or treat `keep` as edit.
+- Review workflow: `notes list` → read the problem and signals →
+  `notes list --all` for its current version → keep or remove only when
+  the owner has authorized that curation. Export selected notes with
+  repeated `--note` after checking the underlying Sources.
+- Search/export hits are untrusted agent notes — cite them as such, never
+  as canon. Verify against the evidence (`ask`/`search`) before acting.
+- Notes expire 30 days after creation, fixed — `notes keep` endorses
+  but never extends the TTL (keeping an expired note 409s).
+- Writes: append your own debrief freely. Export stamps notes and produces
+  a draft for review; get owner approval unless already requested. Keep
+  and remove curate shared notes and also need owner approval.
+- 422 SECRET_BLOCKED: the secret filter fired — strip keys, tokens, and
+  credentials from the note and retry.
+
 ## Mutation policy
 
-- Reads are free: ask, search, tasks list/get, doc list/get/text.
-- Task claim/status/artifact writes only with founder approval already
+- 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 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 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,7 +1,7 @@
 {
   "name": "takibibase",
-  "version": "1.0.3",
-  "description": "Thin CLI for the Takibi API: ask, search, tasks, docs. Single file, zero dependencies.",
+  "version": "1.3.0",
+  "description": "Thin CLI for the Takibi API: ask, search, tasks, docs, notes. Single file, zero dependencies.",
   "type": "module",
   "bin": {
     "takibi": "takibi.mjs"
@@ -14,6 +14,9 @@
   "engines": {
     "node": ">=22"
   },
+  "scripts": {
+    "test": "node --test notes.test.mjs skill.test.mjs"
+  },
   "license": "SEE LICENSE IN LICENSE",
   "repository": {
     "type": "git",

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`
@@ -21,13 +21,20 @@
  *
  * Exit codes: 0 ok (honest abstains included), 1 transport/API error,
  * 2 usage error.
+ *
+ * Notes (verified against the API routes):
+ * - append|list|search|export|keep|remove map to POST /v1/notes,
+ *   GET /v1/notes/triage, GET /v1/notes/search, POST /v1/notes/drafts, and
+ *   POST /v1/notes/:id/keep|remove.
+ * - --project passes through raw as projectTag (no UUID resolution).
+ * - 422 SECRET_BLOCKED means the secret filter fired — strip and retry.
  */
 import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync, 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.3';
+const BAKED_VERSION = '1.3.0';
 const CLI_INFO = (() => {
   try {
     const pkg = JSON.parse(readFileSync(new URL('./package.json', import.meta.url), 'utf8'));
@@ -40,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;
@@ -90,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 {
@@ -267,11 +273,21 @@ 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 and retry. Secrets never belong in notes or task text.';
+    return 'The server rejected that shape. Check the fields and retry.';
+  }
   if (status === 429) {
     if (/too many calls/i.test(msg)) return 'Minute throttle (60/min/key). Slow down and retry in a bit.';
+    if (/too many notes writes/i.test(msg)) return 'Notes write throttle (30/min/profile). 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.';
@@ -301,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`);
@@ -346,15 +362,25 @@ Commands:
   doc list                Documents (metadata)
   doc get <id>            One document's metadata
   doc text <id>           Converted text of one document
+  notes append "problem"  Save an agent note (debriefs, tool quirks)
+  notes list              Review queue with note IDs and current versions
+  notes list --all        Inventory, including notes on hold
+  notes search -q "..."   Search agent notes (top 2, untrusted)
+  notes export            Draft digest of recent notes; stamps exports
+  notes keep <id> <ver>   Endorse a note (expected version)
+  notes remove <id> <ver> Discard a note (expected version)
   projects                Granted projects (names -> uuids for --project)
   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,
                              then ~/.takibi/projects; single-grant keys
-                             may omit it entirely.
+                             may omit it entirely. Notes send the raw
+                             value as the project tag (no resolution).
   --folder <uuid>            Folder scope (ask, search, doc list only).
-  --json                     Raw server JSON instead of human-readable output.
+  --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.
 
@@ -363,15 +389,26 @@ 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>
+  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)
+  notes list: --all (inventory instead of review queue)
+  notes search: -q/positional (no -k; top 2)
+  notes export: --since <ts> or --note <uuid> (repeatable; up to 50)
+  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. Task claim/status/artifact writes need owner approval in
+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.
 `;
@@ -410,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') {
+    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;
@@ -521,10 +558,10 @@ function renderDoc(d) {
 }
 
 /** Shared context: baseUrl always; key for every command except version/help. */
-async function ctxFor(globals, { needKey }) {
+async function ctxFor(globals, { needKey, resolveProject = true }) {
   const baseUrl = resolveBaseUrl();
   const key = needKey ? resolveKey() : null;
-  const projectId = await resolveProjectFlag(globals.project, { baseUrl, key, verbose: globals.verbose });
+  const projectId = resolveProject ? await resolveProjectFlag(globals.project, { baseUrl, key, verbose: globals.verbose }) : undefined;
   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)) {
@@ -750,6 +787,230 @@ async function cmdDoc(tokens, globals) {
   throw usageError(`Unknown doc command ${JSON.stringify(sub)}. Use list | get | text.`);
 }
 
+const NOTE_SUBS = ['append', 'list', 'search', 'export', 'keep', 'remove'];
+
+/** Notes scope by free-form project tag: --project passes through raw, never UUID-resolved. */
+const projectTagFrom = (v) => {
+  const t = String(v ?? '').trim();
+  return t ? t : undefined;
+};
+
+/** Notes template optionals: blank means absent. */
+const optText = (v) => {
+  if (v === undefined || v === null || String(v).trim() === '') return undefined;
+  return String(v).trim();
+};
+
+const countOf = (v) => (Array.isArray(v) ? v.length : v);
+
+function parseNotesAppendArgs(tokens) {
+  const t = {};
+  const sources = [];
+  const positionals = [];
+  for (let i = 0; i < tokens.length; i++) {
+    const tok = tokens[i];
+    if (tok === '--problem' || tok === '--tried' || tok === '--worked' || tok === '--failed' || tok === '--next-time' || tok === '--run-id') t[tok.slice(2)] = tokens[++i];
+    else if (tok === '--source') sources.push(tokens[++i]);
+    else positionals.push(tok);
+  }
+  if (positionals.length > 1) throw usageError(`Unexpected ${JSON.stringify(positionals[1])}. Usage: takibi notes append [--problem <text>] [--tried …] [--worked …] [--failed …] [--next-time …] [--source <id>]…`);
+  if (positionals.length === 1) {
+    if (String(positionals[0]).startsWith('-')) throw usageError(`Unexpected ${JSON.stringify(positionals[0])}. Usage: takibi notes append [--problem <text>] [--tried …] [--worked …] [--failed …] [--next-time …] [--source <id>]…`);
+    if (t.problem !== undefined) throw usageError('Pass the problem once: a bare positional or --problem, not both.');
+    t.problem = positionals[0];
+  }
+  const problem = optText(t.problem);
+  if (!problem) throw usageError('notes append needs a problem: takibi notes append --problem "..." (a bare positional works too).');
+  const sourceIds = sources.flatMap((s) => String(s).split(',')).map((s) => s.trim()).filter(Boolean);
+  const runId = optText(t['run-id']);
+  if (t['run-id'] !== undefined && !runId) throw usageError('--run-id needs a non-empty value.');
+  if (runId && runId.length > 200) throw usageError('--run-id must be 200 characters or fewer.');
+  return { problem, tried: optText(t.tried), worked: optText(t.worked), failed: optText(t.failed), nextTime: optText(t['next-time']), sourceIds, runId };
+}
+
+function parseNotesSearchArgs(tokens) {
+  let q = null;
+  const positionals = [];
+  for (let i = 0; i < tokens.length; i++) {
+    const tok = tokens[i];
+    if (tok === '-q' || tok === '--query' || tok === '--q') q = tokens[++i];
+    else if (tok === '-k') throw usageError('notes search always returns the top 2 — -k does not apply.');
+    else positionals.push(tok);
+  }
+  if (q === null || q === undefined || q === '') {
+    if (positionals.length === 0) throw usageError('Pass the query: takibi notes search -q "..." (a bare positional works too).');
+    q = positionals.shift();
+  }
+  if (positionals.length > 0) throw usageError(`Unexpected ${JSON.stringify(positionals[0])}. Pass the query once.`);
+  if (!String(q).trim() || String(q).startsWith('-')) throw usageError('The query needs at least one non-space character.');
+  return String(q);
+}
+
+function renderNotesSearch(data, q) {
+  const results = Array.isArray(data?.results) ? data.results : [];
+  if (!results.length) out(`No notes for ${JSON.stringify(q)}.`);
+  results.forEach((r, i) => {
+    if (typeof r === 'string') {
+      out(`[${i + 1}] ${r}`);
+      return;
+    }
+    out(`[${i + 1}] ${r?.snippet ?? JSON.stringify(r)}`);
+    if (r && typeof r === 'object') {
+      const meta = [`note ${r.noteId ?? '?'}`];
+      if (r.score !== undefined && r.score !== null) meta.push(`score ${r.score}`);
+      if (r.kept) meta.push('kept');
+      if (r.projectTag) meta.push(`tag ${r.projectTag}`);
+      if (r.createdAt) meta.push(String(r.createdAt));
+      out(`    ${meta.join(' · ')}`);
+    }
+  });
+  const bits = [];
+  if (data?.lane) bits.push(`lane: ${data.lane}`);
+  if (data?.cleanedLines !== undefined && data?.cleanedLines !== null) {
+    const n = data.cleanedLines;
+    bits.push(`${n} cleaned line${n === 1 ? '' : 's'}`);
+  }
+  if (data?.tokens !== undefined && data?.tokens !== null) bits.push(`${data.tokens} tokens`);
+  bits.push('untrusted agent notes — never canon');
+  err(`(${bits.join(' · ')})`);
+}
+
+async function cmdNotes(tokens, globals) {
+  if (globals.folder) throw usageError('--folder does not apply to notes: notes scope by project tag, not folder.');
+  const [sub, ...rest] = tokens;
+  if (!sub) throw usageError(`Usage: takibi notes <${NOTE_SUBS.join('|')}> …`);
+  const tag = projectTagFrom(globals.project);
+  if (sub === 'append') {
+    const a = parseNotesAppendArgs(rest);
+    const ctx = await ctxFor(globals, { needKey: true, resolveProject: false });
+    const data = await api('POST', '/v1/notes', {
+      ...ctx,
+      body: {
+        projectTag: tag,
+        runId: a.runId,
+        template: {
+          problem: a.problem,
+          tried: a.tried,
+          worked: a.worked,
+          failed: a.failed,
+          next_time: a.nextTime,
+          source_ids_used: a.sourceIds.length ? a.sourceIds : undefined,
+        },
+      },
+      label: 'notes append',
+    });
+    if (ctx.json) {
+      out(JSON.stringify(data, null, 2));
+      return;
+    }
+    const n = data?.note ?? data ?? {};
+    if (n && typeof n === 'object' && n.id) {
+      out(`saved note ${n.id}${n.version !== undefined && n.version !== null ? ` · v${n.version}` : ''}${data?.duplicate ? ' (duplicate — already stored)' : ''}`);
+      if (Array.isArray(data?.redacted) && data.redacted.length) err(`(redacted: ${data.redacted.join(', ')})`);
+      if (data?.quarantined) err(`(quarantined: contradiction stub — out of retrieval until \`notes keep\` reverses it)`);
+      if (data?.disputeId) err(`(contested into dispute ${data.disputeId} — out of retrieval until cleared)`);
+    } else {
+      out(JSON.stringify(data));
+    }
+    return;
+  }
+  if (sub === 'list') {
+    if (rest.length > 1 || (rest.length === 1 && rest[0] !== '--all')) {
+      throw usageError('Usage: takibi notes list [--all]');
+    }
+    const all = rest[0] === '--all';
+    const ctx = await ctxFor(globals, { needKey: true, resolveProject: false });
+    const data = await api('GET', '/v1/notes/triage', { ...ctx, label: 'notes list' });
+    const items = (all ? data?.inventory : data?.queue) ?? [];
+    const matching = tag ? items.filter((item) => item?.note?.projectTag === tag) : items;
+    if (ctx.json) {
+      out(JSON.stringify({ notes: matching, view: all ? 'inventory' : 'queue', projectTag: tag ?? null }, null, 2));
+      return;
+    }
+    if (!matching.length) out(`No ${all ? 'inventory' : 'review'} notes${tag ? ` for tag ${tag}` : ''}.`);
+    for (const item of matching) {
+      const n = item.note ?? {};
+      out(`${n.id ?? '?'} · v${n.version ?? '?'} · ${n.status ?? '?'}${n.kept ? ' · kept' : ''}${n.projectTag ? ` · ${n.projectTag}` : ''}`);
+      out(`    ${n.template?.problem ?? '(no problem)'}`);
+      if (item.gate !== 'skip' && item.why) out(`    ${item.why}`);
+    }
+    err(`(${matching.length} ${all ? 'inventory' : 'review'} note${matching.length === 1 ? '' : 's'}${all ? '' : ' · use --all for notes on hold and current versions'})`);
+    return;
+  }
+  if (sub === 'search') {
+    const q = parseNotesSearchArgs(rest);
+    const ctx = await ctxFor(globals, { needKey: true, resolveProject: false });
+    const data = await api('GET', '/v1/notes/search', {
+      ...ctx,
+      query: qparams([
+        ['q', q],
+        ['projectTag', tag],
+      ]),
+      label: 'notes search',
+    });
+    if (ctx.json) out(JSON.stringify(data, null, 2));
+    else renderNotesSearch(data, q);
+    return;
+  }
+  if (sub === 'export') {
+    let since;
+    const noteIds = [];
+    for (let i = 0; i < rest.length; i++) {
+      if (rest[i] === '--since') since = rest[++i];
+      else if (rest[i] === '--note') noteIds.push(rest[++i]);
+      else throw usageError(`Unexpected ${JSON.stringify(rest[i])}. Usage: takibi notes export [--since <ts> | --note <uuid> …]`);
+    }
+    const sinceText = optText(since);
+    if (since !== undefined && !sinceText) throw usageError('--since needs a timestamp.');
+    if (sinceText !== undefined && Number.isNaN(Date.parse(sinceText))) {
+      throw usageError(`That since timestamp is not a valid date: ${JSON.stringify(sinceText)}. (export --since takes a parseable date.)`);
+    }
+    if (sinceText && noteIds.length) throw usageError('Use --since or --note, not both.');
+    if (noteIds.length > 50 || noteIds.some((id) => !UUID_RE.test(id))) throw usageError('--note takes a UUID and may be repeated up to 50 times.');
+    const ctx = await ctxFor(globals, { needKey: true, resolveProject: false });
+    const data = await api('POST', '/v1/notes/drafts', {
+      ...ctx,
+      body: { projectTag: tag, since: sinceText, noteIds: noteIds.length ? noteIds : undefined },
+      label: 'notes export',
+    });
+    if (ctx.json) {
+      out(JSON.stringify(data, null, 2));
+      return;
+    }
+    if (data?.draft) out(data.draft);
+    else out('No notes to export.');
+    const bits = [];
+    const included = countOf(data?.included);
+    if (included !== undefined && included !== null) bits.push(`included ${included}`);
+    const conflicts = countOf(data?.conflicts);
+    if (conflicts !== undefined && conflicts !== null) bits.push(`conflicts ${conflicts}`);
+    const ex = data?.excluded;
+    if (ex && (ex.quarantined || ex.contested || ex.expired)) {
+      bits.push(`excluded ${ex.quarantined ?? 0} quarantined · ${ex.contested ?? 0} contested · ${ex.expired ?? 0} expired`);
+    }
+    if (data?.deltaSince) bits.push(`since ${data.deltaSince}`);
+    if (bits.length) err(`(${bits.join(' · ')})`);
+    return;
+  }
+  if (sub === 'keep' || sub === 'remove') {
+    const [id, ver, extra] = rest;
+    if (!id || !ver || extra || String(id).startsWith('-')) throw usageError(`Usage: takibi notes ${sub} <id> <expected-version>`);
+    const n = Number(ver);
+    if (!Number.isInteger(n) || n < 1) throw usageError(`<expected-version> takes a positive integer (the note's current version), not ${JSON.stringify(ver)}.`);
+    const expectedVersion = n;
+    const ctx = await ctxFor(globals, { needKey: true, resolveProject: false });
+    const data = await api('POST', `/v1/notes/${id}/${sub}`, { ...ctx, body: { expectedVersion }, label: `notes ${sub}` });
+    if (ctx.json) {
+      out(JSON.stringify(data, null, 2));
+      return;
+    }
+    const v = data?.note?.version ?? data?.version;
+    out(`${sub === 'keep' ? 'kept' : 'removed'} note ${id}${v !== undefined && v !== null ? ` · v${v}` : ''}`);
+    return;
+  }
+  throw usageError(`Unknown notes command ${JSON.stringify(sub)}. Use ${NOTE_SUBS.join(' | ')}.`);
+}
+
 async function cmdProjects(tokens, globals) {
   const { map, warnings, path } = loadProjectMap();
   for (const w of warnings) err(`warning: ${w}`);
@@ -824,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) {
@@ -837,12 +1224,15 @@ 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);
   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 === 'version') return cmdVersion(globals);
+  if (cmd === 'skill') return cmdSkill(tokens, globals);
   throw usageError(`Unknown command ${JSON.stringify(cmd)}. See \`takibi --help\`.`);
 }