takibibase 1.2.0 → 1.5.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,24 +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.
+  versions. `takibi notes list --all` shows the inventory, including
+  flagged notes. `--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.
+  (sets kept; never settles flags or 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.
 
@@ -82,6 +81,10 @@ prose presented as sourced.
   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.
+- Write the four body fields (tried, worked, failed, next time) in
+  Markdown (GFM): short lists, `code` and fenced blocks, links, tables.
+  The founder reads the body rendered; the problem title stays plain text
+  and raw HTML never renders. Keep each field tight — one idea per line.
 - 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.
@@ -91,6 +94,9 @@ prose presented as sourced.
   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.
+- Flagged hits contradict another note — both stay retrievable. Surface
+  both sides (`contradicts` links plus the marker line); never smooth a
+  flagged conflict over.
 - 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
@@ -103,21 +109,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.5.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.5.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`);
@@ -360,13 +364,15 @@ Commands:
   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 list --all        Inventory, including flagged notes
   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,
@@ -386,17 +392,22 @@ Per-command options:
   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)
+    Fields render as Markdown (GFM): short lists, code, links, tables.
   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. Export stamps included notes. Task claim/status/artifact writes need owner approval in
 conversation. Account-only routes (upload, delete, retry, download originals,
@@ -437,9 +448,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;
@@ -849,6 +860,8 @@ function renderNotesSearch(data, q) {
       const meta = [`note ${r.noteId ?? '?'}`];
       if (r.score !== undefined && r.score !== null) meta.push(`score ${r.score}`);
       if (r.kept) meta.push('kept');
+      const linked = [...(Array.isArray(r.contradicts) ? r.contradicts : []), ...(Array.isArray(r.contradictedBy) ? r.contradictedBy : [])];
+      if (linked.length) meta.push(`conflicts with ${linked.map((id) => String(id).slice(0, 8)).join(', ')}${r.involvesSource ? ' (Source-involved)' : ''}`);
       if (r.projectTag) meta.push(`tag ${r.projectTag}`);
       if (r.createdAt) meta.push(String(r.createdAt));
       out(`    ${meta.join(' · ')}`);
@@ -897,8 +910,8 @@ async function cmdNotes(tokens, globals) {
     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)`);
+      if (Array.isArray(data?.flagged) && data.flagged.length) err(`(flagged: contradicts ${data.flagged.length} note${data.flagged.length === 1 ? '' : 's'} — both sides stay retrievable)`);
+      if (Array.isArray(data?.unflagged) && data.unflagged.length) err(`(settled ${data.unflagged.length} flagged note${data.unflagged.length === 1 ? '' : 's'} in this scope)`);
     } else {
       out(JSON.stringify(data));
     }
@@ -920,11 +933,12 @@ async function cmdNotes(tokens, globals) {
     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}` : ''}`);
+      const flagCount = (Array.isArray(n.contradicts) ? n.contradicts.length : 0) + (Array.isArray(n.contradictedBy) ? n.contradictedBy.length : 0);
+      out(`${n.id ?? '?'} · v${n.version ?? '?'} · ${n.status ?? '?'}${n.kept ? ' · kept' : ''}${n.projectTag ? ` · ${n.projectTag}` : ''}${flagCount ? ` · conflicts ${flagCount}` : ''}`);
       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'})`);
+    err(`(${matching.length} ${all ? 'inventory' : 'review'} note${matching.length === 1 ? '' : 's'}${all ? '' : ' · use --all for the full inventory and current versions'})`);
     return;
   }
   if (sub === 'search') {
@@ -972,11 +986,14 @@ async function cmdNotes(tokens, globals) {
     const bits = [];
     const included = countOf(data?.included);
     if (included !== undefined && included !== null) bits.push(`included ${included}`);
-    const conflicts = countOf(data?.conflicts);
+    const conflictsRaw = data?.conflicts;
+    const conflicts = Array.isArray(conflictsRaw)
+      ? conflictsRaw.filter((c) => c?.verdict === 'contradicts').length
+      : countOf(conflictsRaw);
     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 (ex && (ex.flagged || ex.expired)) {
+      bits.push(`flagged ${ex.flagged ?? 0} · expired ${ex.expired ?? 0}`);
     }
     if (data?.deltaSince) bits.push(`since ${data.deltaSince}`);
     if (bits.length) err(`(${bits.join(' · ')})`);
@@ -1075,6 +1092,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 +1231,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 +1239,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\`.`);
 }