@chankov/agent-skills 0.1.0 → 0.3.0

package/bin/lib/bootstrap.js

@@ -0,0 +1,254 @@
+// bootstrap.js — drop the minimum installer artifacts a coding agent needs
+// to recognize `/setup-agent-skills` and `/doctor-agent-skills`.
+//
+// The CLI's `init` calls this before the handoff message. Without it, a
+// fresh workspace has no `.claude/commands/setup-agent-skills.md`, `.pi/prompts/setup-agent-skills.md`,
+// etc., so the agent has no idea what `/setup-agent-skills` is and the whole hand-off
+// breaks silently.
+//
+// What we bootstrap (per agent):
+//   - The `setup` slash command (so the user can invoke it)
+//   - The `doctor` slash command (same)
+//   - The `guided-workspace-setup` skill body (the slash command says
+//     "load this skill" — the skill must be present somewhere the agent
+//     auto-discovers)
+//
+// What we do NOT bootstrap:
+//   - Any of the user-facing skills (spec-driven-development,
+//     test-driven-development, …). Those are picked by the user inside
+//     /setup-agent-skills, by design. The CLI never decides the workspace's catalogue
+//     for the user.
+//
+// Method:
+//   `copy`    — safe default; works for npx caches that may be cleaned
+//   `symlink` — leaner; only safe when the source root is stable
+//               (global install / git clone). Warning printed if the
+//               source path looks like an npx cache.
+
+import { existsSync, mkdirSync, copyFileSync, symlinkSync, unlinkSync, lstatSync, rmSync, readdirSync, rmdirSync } from "node:fs";
+import { dirname, join, relative } from "node:path";
+
+// (agent → list of {kind, src, dest}) — kind is just for the report.
+//
+// All installer slash commands are namespaced with `-agent-skills` so they
+// don't collide with workspace-defined or other-tool slash commands. The
+// short names (setup, doctor, as-setup, as-doctor) were used in 0.2.0 and
+// earlier — cleanupLegacyNames() removes those if found.
+function plan({ agent, sourceRoot, workspace }) {
+  const skillSrc = join(sourceRoot, "skills", "guided-workspace-setup", "SKILL.md");
+
+  switch (agent) {
+    case "claude-code":
+      return [
+        { kind: "command", src: join(sourceRoot, ".claude/commands/setup-agent-skills.md"),
+          dest: join(workspace, ".claude/commands/setup-agent-skills.md") },
+        { kind: "command", src: join(sourceRoot, ".claude/commands/doctor-agent-skills.md"),
+          dest: join(workspace, ".claude/commands/doctor-agent-skills.md") },
+        { kind: "skill",   src: skillSrc,
+          dest: join(workspace, ".claude/skills/guided-workspace-setup/SKILL.md") },
+      ];
+
+    case "pi":
+      return [
+        { kind: "prompt", src: join(sourceRoot, ".pi/prompts/setup-agent-skills.md"),
+          dest: join(workspace, ".pi/prompts/setup-agent-skills.md") },
+        { kind: "prompt", src: join(sourceRoot, ".pi/prompts/doctor-agent-skills.md"),
+          dest: join(workspace, ".pi/prompts/doctor-agent-skills.md") },
+        // pi auto-discovers skills from .pi/skills/ and .agents/skills/ —
+        // we use .pi/skills/ to avoid polluting a shared .agents/ dir if
+        // the user has other tools there.
+        { kind: "skill",  src: skillSrc,
+          dest: join(workspace, ".pi/skills/guided-workspace-setup/SKILL.md") },
+      ];
+
+    case "opencode":
+      // OpenCode discovers skills + commands from ~/.config/opencode/ (global)
+      // and references AGENTS.md. A project-local bootstrap is awkward — we
+      // drop the command file into .opencode/commands/ (which OpenCode does
+      // load from the project) and the skill alongside it, then flag the
+      // AGENTS.md gap for the user.
+      return [
+        { kind: "command", src: join(sourceRoot, ".opencode/commands/as-setup-agent-skills.md"),
+          dest: join(workspace, ".opencode/commands/as-setup-agent-skills.md") },
+        { kind: "command", src: join(sourceRoot, ".opencode/commands/as-doctor-agent-skills.md"),
+          dest: join(workspace, ".opencode/commands/as-doctor-agent-skills.md") },
+        { kind: "skill",   src: skillSrc,
+          dest: join(workspace, ".opencode/skills/guided-workspace-setup/SKILL.md") },
+      ];
+
+    default:
+      throw new Error(`bootstrap: unknown agent "${agent}"`);
+  }
+}
+
+// Files that were the bootstrap targets in 0.2.0 and earlier (pre-rename).
+// Removed during bootstrap so a workspace upgraded from 0.2.0 doesn't end
+// up with both the old and new slash commands.
+function legacyPaths({ agent, workspace }) {
+  switch (agent) {
+    case "claude-code":
+      return [
+        join(workspace, ".claude/commands/setup.md"),
+        join(workspace, ".claude/commands/doctor.md"),
+      ];
+    case "pi":
+      return [
+        join(workspace, ".pi/prompts/setup.md"),
+        join(workspace, ".pi/prompts/doctor.md"),
+      ];
+    case "opencode":
+      return [
+        join(workspace, ".opencode/commands/as-setup.md"),
+        join(workspace, ".opencode/commands/as-doctor.md"),
+      ];
+    default:
+      return [];
+  }
+}
+
+/**
+ * Run the bootstrap.
+ *
+ * @param {object} opts
+ * @param {string} opts.agent       claude-code | opencode | pi
+ * @param {string} opts.sourceRoot  Absolute path to the installed package
+ * @param {string} opts.workspace   Absolute path to the target workspace
+ * @param {"copy"|"symlink"} opts.method
+ * @param {boolean} [opts.dryRun]
+ * @returns {{written:Array, skipped:Array, warnings:Array}}
+ */
+export function bootstrap({ agent, sourceRoot, workspace, method, dryRun = false }) {
+  const items = plan({ agent, sourceRoot, workspace });
+  const written = [], skipped = [], removed = [], warnings = [];
+
+  // Warn if the user asked for symlink against an unstable source.
+  if (method === "symlink" && /\/\.npm\/_npx\//.test(sourceRoot)) {
+    warnings.push(
+      "--method symlink against an npx cache path: links will break when " +
+      "the cache is cleaned. Consider --method copy or install globally " +
+      "with `npm install -g @chankov/agent-skills`.",
+    );
+  }
+
+  // Clean up pre-0.3.0 file names if present — they were renamed to
+  // *-agent-skills so they don't collide with other slash commands.
+  for (const oldPath of legacyPaths({ agent, workspace })) {
+    if (!existsSync(oldPath) && !isSymlink(oldPath)) continue;
+    if (dryRun) {
+      removed.push(oldPath);
+      continue;
+    }
+    try {
+      unlinkSync(oldPath);
+      removed.push(oldPath);
+    } catch (err) {
+      warnings.push(`could not remove legacy file ${relative(workspace, oldPath)}: ${err.message}`);
+    }
+  }
+
+  for (const item of items) {
+    if (!existsSync(item.src)) {
+      warnings.push(`missing source: ${relative(sourceRoot, item.src)} (skipping ${item.kind})`);
+      continue;
+    }
+
+    if (dryRun) {
+      written.push({ ...item, method });
+      continue;
+    }
+
+    try {
+      mkdirSync(dirname(item.dest), { recursive: true });
+
+      // Always replace — the bootstrap is installer scaffolding, not user
+      // data. If we left it stale, an upgraded package would still hand off
+      // to the old /setup-agent-skills command. Step 6 of guided-workspace-setup explicitly
+      // never offers these files in the install menu, so we are the only
+      // mechanism that refreshes them.
+      if (existsSync(item.dest) || isSymlink(item.dest)) {
+        unlinkSync(item.dest);
+      }
+
+      if (method === "symlink") {
+        symlinkSync(item.src, item.dest);
+      } else {
+        // copyFileSync handles plain files; for the SKILL.md case the source
+        // may have sibling support files in some skills — but
+        // guided-workspace-setup is a single-file skill, so copyFileSync is
+        // fine. Switch to cpSync if that ever changes.
+        copyFileSync(item.src, item.dest);
+      }
+      written.push({ ...item, method });
+    } catch (err) {
+      skipped.push({ ...item, error: err.message });
+    }
+  }
+
+  return { written, skipped, removed, warnings };
+}
+
+/**
+ * Remove every bootstrap artifact this module knows how to write. Called
+ * by guided-workspace-setup at the end of Step 10 unless the user chose
+ * to keep the installer commands. After cleanup, the only way back to
+ * /setup-agent-skills is to re-run `npx @chankov/agent-skills init`.
+ *
+ * The same `agent` value must be supplied that was used at bootstrap time —
+ * we don't have a tracking file, so we delete based on the plan map.
+ *
+ * @param {object} opts
+ * @param {string} opts.agent
+ * @param {string} opts.workspace
+ * @param {boolean} [opts.dryRun]
+ * @returns {{removed:string[], kept:string[], warnings:string[]}}
+ */
+export function cleanupInstaller({ agent, workspace, dryRun = false }) {
+  const planned = plan({ agent, sourceRoot: workspace, workspace });
+  const removed = [], kept = [], warnings = [];
+
+  for (const item of planned) {
+    if (!existsSync(item.dest) && !isSymlink(item.dest)) {
+      kept.push(item.dest); // already gone — count it as a no-op, not an error
+      continue;
+    }
+    if (dryRun) {
+      removed.push(item.dest);
+      continue;
+    }
+    try {
+      const lst = lstatSync(item.dest);
+      if (lst.isDirectory() && !lst.isSymbolicLink()) {
+        rmSync(item.dest, { recursive: true });
+      } else {
+        unlinkSync(item.dest);
+      }
+      removed.push(item.dest);
+
+      // If we removed the only file in a parent directory we created
+      // (.claude/skills/guided-workspace-setup/), prune the directory too.
+      pruneEmptyDirsUpTo(dirname(item.dest), workspace);
+    } catch (err) {
+      warnings.push(`could not remove ${relative(workspace, item.dest)}: ${err.message}`);
+    }
+  }
+
+  return { removed, kept, warnings };
+}
+
+function pruneEmptyDirsUpTo(dir, workspace) {
+  // Walk upward removing empty parent dirs until we hit a non-empty one or
+  // the workspace root. Never delete the workspace itself.
+  try {
+    while (dir !== workspace && dir.startsWith(workspace)) {
+      const entries = readdirSync(dir);
+      if (entries.length > 0) return;
+      rmdirSync(dir);
+      dir = dirname(dir);
+    }
+  } catch { /* prune is best-effort */ }
+}
+
+function isSymlink(path) {
+  try { return lstatSync(path).isSymbolicLink(); }
+  catch { return false; }
+}

package/bin/lib/doctor.js

@@ -1,6 +1,6 @@
 // Doctor scan — deterministic preflight extracted from
 // guided-workspace-setup Step 5. Both `agent-skills doctor` (CLI) and the
-// `/doctor` slash command call into this so behaviour cannot drift.
+// `/doctor-agent-skills` slash command call into this so behaviour cannot drift.
 //
 // Two classes of findings:
 //   1. Broken symlinks — links whose source has been moved, renamed, or deleted

package/bin/lib/update-notifier.js

@@ -0,0 +1,195 @@
+// update-notifier — zero-dependency check for newer versions on the npm
+// registry, shared by the CLI, the Claude Code session hook, and the pi
+// extension.
+//
+// Behaviour:
+//   - Cache lives at $XDG_CACHE_HOME/agent-skills/latest-version.json
+//     (falls back to ~/.cache/agent-skills/) with a 24h TTL.
+//   - The CLI invokes checkAndNotify() at the top of every command. If the
+//     cache is fresh and shows an upgrade, we print a banner immediately.
+//     If the cache is stale or absent, we start a background fetch (detached,
+//     non-blocking) and use whatever we have right now.
+//   - Network failures, JSON parse errors, and missing cache files are all
+//     swallowed silently — update checks must NEVER block the CLI or break
+//     a hook.
+//   - Opt-out: AGENT_SKILLS_NO_UPDATE_CHECK=1 in the environment disables
+//     everything in this module.
+
+import { mkdirSync, readFileSync, writeFileSync, existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { request } from "node:https";
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+const PACKAGE_NAME = "@chankov/agent-skills";
+const REGISTRY = "https://registry.npmjs.org";
+const TTL_MS = 24 * 60 * 60 * 1000;
+
+const CACHE_DIR = join(
+  process.env.XDG_CACHE_HOME || join(homedir(), ".cache"),
+  "agent-skills",
+);
+const CACHE_FILE = join(CACHE_DIR, "latest-version.json");
+
+// ── Public surface ───────────────────────────────────────────────────────
+
+/**
+ * Run the standard check + banner flow used by the CLI.
+ *
+ * @param {string} currentVersion  The version of the running CLI
+ * @param {object} [opts]
+ * @param {boolean} [opts.silent]  If true, return the banner string instead of printing
+ * @returns {string|null}  The banner that would be (or was) printed
+ */
+export function checkAndNotify(currentVersion, opts = {}) {
+  if (isDisabled()) return null;
+
+  const cached = readCache();
+  const fresh = cached && Date.now() - cached.checkedAt < TTL_MS;
+
+  if (!fresh) startBackgroundFetch();
+
+  const latest = cached?.latest;
+  if (!latest || !gt(latest, currentVersion)) return null;
+
+  const banner = formatBanner(currentVersion, latest);
+  if (!opts.silent) process.stderr.write(banner + "\n");
+  return banner;
+}
+
+/**
+ * Synchronously fetch the latest version, write the cache, and return it.
+ * Used by the standalone check-update entry point (hooks block on this
+ * intentionally — they need the answer before the session continues).
+ *
+ * @param {number} [timeoutMs]   Default 2000ms — hooks must not stall the UI
+ * @returns {Promise<string|null>}
+ */
+export async function fetchLatestSync(timeoutMs = 2000) {
+  if (isDisabled()) return null;
+  try {
+    const latest = await fetchLatest(timeoutMs);
+    writeCache({ latest, checkedAt: Date.now() });
+    return latest;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Read the cached latest version without touching the network. Hook scripts
+ * use this on the fast path — if the cache is fresh, no fetch is needed.
+ *
+ * @returns {{latest:string, checkedAt:number, stale:boolean}|null}
+ */
+export function readCacheStatus() {
+  const c = readCache();
+  if (!c) return null;
+  return { ...c, stale: Date.now() - c.checkedAt >= TTL_MS };
+}
+
+export function formatBanner(current, latest) {
+  const lines = [
+    `agent-skills update available: ${current} → ${latest}`,
+    `  Run: npx ${PACKAGE_NAME}@latest update`,
+    `  Releases: https://github.com/chankov/agent-skills/releases`,
+  ];
+  const w = Math.max(...lines.map((l) => l.length)) + 2;
+  const bar = "─".repeat(w);
+  return [
+    `┌${bar}┐`,
+    ...lines.map((l) => `│ ${l.padEnd(w - 1)}│`),
+    `└${bar}┘`,
+  ].join("\n");
+}
+
+// ── Internals ────────────────────────────────────────────────────────────
+
+function isDisabled() {
+  return process.env.AGENT_SKILLS_NO_UPDATE_CHECK === "1"
+      || process.env.CI === "true"   // never spam CI logs
+      || process.env.NO_UPDATE_NOTIFIER === "1";  // honour the common convention
+}
+
+function readCache() {
+  try {
+    if (!existsSync(CACHE_FILE)) return null;
+    return JSON.parse(readFileSync(CACHE_FILE, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function writeCache(payload) {
+  try {
+    mkdirSync(CACHE_DIR, { recursive: true });
+    writeFileSync(CACHE_FILE, JSON.stringify(payload, null, 2), "utf8");
+  } catch {
+    // Read-only home dir, full disk, etc. — caching is best-effort.
+  }
+}
+
+function fetchLatest(timeoutMs) {
+  return new Promise((resolve, reject) => {
+    const url = `${REGISTRY}/${encodeURIComponent(PACKAGE_NAME).replace("%40", "@")}/latest`;
+    const req = request(url, { method: "GET", headers: { accept: "application/json" } }, (res) => {
+      if (res.statusCode !== 200) {
+        reject(new Error(`registry returned ${res.statusCode}`));
+        res.resume();
+        return;
+      }
+      let body = "";
+      res.setEncoding("utf8");
+      res.on("data", (chunk) => { body += chunk; });
+      res.on("end", () => {
+        try {
+          const parsed = JSON.parse(body);
+          if (typeof parsed.version !== "string") throw new Error("missing version field");
+          resolve(parsed.version);
+        } catch (err) { reject(err); }
+      });
+    });
+    req.on("error", reject);
+    req.setTimeout(timeoutMs, () => {
+      req.destroy(new Error("timeout"));
+    });
+    req.end();
+  });
+}
+
+function startBackgroundFetch() {
+  // Detached worker: never blocks the CLI, never inherits stdio.
+  // We re-enter this module via dynamic import in a fresh node process and
+  // run fetchLatestSync there — keeps the parent CLI exit unaffected.
+  try {
+    const modPath = fileURLToPath(import.meta.url);
+    const child = spawn(process.execPath, [
+      "-e",
+      `import(${JSON.stringify(modPath)}).then(m => m.fetchLatestSync(8000)).catch(() => {})`,
+    ], { detached: true, stdio: "ignore" });
+    child.unref();
+  } catch {
+    // If spawn fails (e.g. restricted env), skip — the next CLI run will retry.
+  }
+}
+
+// ── Tiny semver-gt comparator ────────────────────────────────────────────
+// Enough for X.Y.Z comparisons; anything pre-release falls back to string
+// compare on the suffix, which is good enough for "is the user behind?"
+
+export function gt(a, b) {
+  const [aMain, aPre = ""] = a.split("-", 2);
+  const [bMain, bPre = ""] = b.split("-", 2);
+  const aParts = aMain.split(".").map(Number);
+  const bParts = bMain.split(".").map(Number);
+  for (let i = 0; i < 3; i++) {
+    const ai = aParts[i] ?? 0;
+    const bi = bParts[i] ?? 0;
+    if (ai !== bi) return ai > bi;
+  }
+  // Equal main versions: a release (no prerelease) outranks a prerelease.
+  if (!aPre && bPre) return true;
+  if (aPre && !bPre) return false;
+  return aPre > bPre;
+}

package/docs/getting-started.md

@@ -14,7 +14,7 @@ Each skill is a Markdown file (`SKILL.md`) that describes a specific engineering
 |---|---|---|
 | **Most users** — you want to use the skills in your projects | `npx @chankov/agent-skills init` | One command; semver updates; cross-platform; no source dir to babysit. See [docs/npm-install.md](npm-install.md). |
 | **Claude Code users** — you live in Claude Code and want plugin-managed updates | `/plugin marketplace add chankov/agent-skills` | Best UX inside Claude Code; marketplace handles the lifecycle. |
-| **Skill authors / contributors** — you want to edit the skills and have changes flow into every connected workspace | `git clone` + `symlink` mode in `/setup` | Edit-in-place; every connected workspace sees the change instantly. |
+| **Skill authors / contributors** — you want to edit the skills and have changes flow into every connected workspace | `git clone` + `symlink` mode in `/setup-agent-skills` | Edit-in-place; every connected workspace sees the change instantly. |
 
 All three converge on the same `guided-workspace-setup` skill — they only differ in how the source files reach your workspace. None is being deprecated.
 
@@ -124,7 +124,7 @@ The `.claude/commands/` directory contains slash commands for Claude Code:
 
 | Command | Skill Invoked |
 |---------|---------------|
-| `/setup` | guided-workspace-setup |
+| `/setup-agent-skills` | guided-workspace-setup |
 | `/spec` | spec-driven-development |
 | `/plan` | planning-and-task-breakdown |
 | `/build` | incremental-implementation + test-driven-development |

package/docs/npm-install.md

@@ -31,18 +31,41 @@ So:
 # In the workspace you want to configure:
 npx @chankov/agent-skills init
 # Then open your coding agent in this directory and run:
-#   /setup
+#   /setup-agent-skills
 ```
 
 That's it. `npx` fetches the package, the CLI detects your coding agent and
-prints the next-step command, and `/setup` runs the full guided install
+prints the next-step command, and `/setup-agent-skills` runs the full guided install
 inside your agent.
 
 ## Commands
 
 ### `npx @chankov/agent-skills init`
 
-Materializes the package and hands off to `/setup`.
+Materializes the package, **bootstraps the installer artifacts** into the
+workspace (so the agent has a `/setup-agent-skills` and `/doctor-agent-skills` command to invoke),
+and hands off to `/setup-agent-skills`.
+
+What `init` writes per agent:
+
+| Agent | Files written to the workspace |
+|---|---|
+| `claude-code` | `.claude/commands/setup-agent-skills.md`, `.claude/commands/doctor-agent-skills.md`, `.claude/skills/guided-workspace-setup/SKILL.md` |
+| `pi` | `.pi/prompts/setup-agent-skills.md`, `.pi/prompts/doctor-agent-skills.md`, `.pi/skills/guided-workspace-setup/SKILL.md` |
+| `opencode` | `.opencode/commands/as-setup-agent-skills.md`, `.opencode/commands/as-doctor-agent-skills.md`, `.opencode/skills/guided-workspace-setup/SKILL.md` |
+
+These are **just the plumbing** — the slash commands, plus the skill they
+invoke. The actual catalogue (spec-driven-development, code-reviewer,
+test-engineer, pi extensions, …) is picked by you inside `/setup-agent-skills`. Re-run
+`init` to refresh the plumbing after a package upgrade; bootstrap files
+are always overwritten because they're scaffolding, not user data.
+
+After `/setup-agent-skills` finishes its install pass, **the bootstrap files
+are removed by default** so they don't clutter your agent's slash-command
+list. Re-run `npx @chankov/agent-skills init` whenever you want
+`/setup-agent-skills` back. To keep them in place across runs, reply `keep`
+to the Step 9 confirmation prompt — the skill will record
+`keep-installer: true` in `.ai/agent-skills-setup.md`.
 
 | Flag | Default | Purpose |
 |------|---------|---------|
@@ -60,7 +83,7 @@ npx @chankov/agent-skills init --workspace ~/projects/foo --method symlink
 
 Deterministic preflight scan — walks every install-target directory, lists
 broken symlinks and stale persona references, and offers fixes. Same scan
-that `/doctor` runs inside the agent.
+that `/doctor-agent-skills` runs inside the agent.
 
 | Flag | Default | Purpose |
 |------|---------|---------|
@@ -78,13 +101,13 @@ npx @chankov/agent-skills doctor -y
 Reads the workspace's `.ai/agent-skills-setup.md`, compares the recorded
 package version against the installed package version, and prints the next
 step. The actual diff-aware refresh runs inside the coding agent via
-`/setup`.
+`/setup-agent-skills`.
 
 ```bash
 # Upgrade the package itself first, then check the delta:
 npm install -g @chankov/agent-skills@latest
 npx agent-skills update --workspace .
-# Then open your agent and run /setup to review per-artifact diffs.
+# Then open your agent and run /setup-agent-skills to review per-artifact diffs.
 ```
 
 ## Versioning
@@ -137,7 +160,7 @@ npm is the recommended path for most users. The other two stay supported:
 - **[Claude Code plugin marketplace](../README.md#quick-start)** — best UX
   inside Claude Code. Same skills, marketplace-managed updates.
 - **Git clone + symlinks** — best for skill authors and contributors. Clone
-  the repo, run `/setup` from there, choose `symlink` in Step 8. Updates
+  the repo, run `/setup-agent-skills` from there, choose `symlink` in Step 8. Updates
   flow through `git pull`. Symlinks need Developer Mode on Windows.
 
 All three paths converge on the same `guided-workspace-setup` skill — the
@@ -153,9 +176,69 @@ npx --yes @chankov/agent-skills@latest init --agent claude-code --method copy --
 ```
 
 `doctor` accepts `--yes` for non-interactive repair. Note that the
-LLM-driven `/setup` flow is not CI-runnable by design — confirmation gates
+LLM-driven `/setup-agent-skills` flow is not CI-runnable by design — confirmation gates
 exist precisely so a human approves every write.
 
+## Receiving update notifications
+
+Three independent mechanisms surface "a new version is published" without
+you having to remember to check. All three share a single cache at
+`$XDG_CACHE_HOME/agent-skills/latest-version.json` (24h TTL) so the
+registry is hit at most once per day.
+
+### 1. CLI update-notifier (always on)
+
+Every `npx @chankov/agent-skills <cmd>` invocation runs a fast cache read
+on entry. If the cached latest version exceeds the running CLI version, a
+banner prints to stderr before the command output:
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│ agent-skills update available: 0.1.0 → 0.2.0                 │
+│   Run: npx @chankov/agent-skills@latest update               │
+│   Releases: https://github.com/chankov/agent-skills/releases │
+└──────────────────────────────────────────────────────────────┘
+```
+
+If the cache is stale, a detached background process refreshes it for the
+*next* invocation — the current run is never blocked.
+
+### 2. Claude Code session-start hook
+
+When `hooks/session-start.sh` is installed (offered in Group 18 of `/setup-agent-skills`),
+every new Claude Code session runs the check with a 3-second wall-clock cap.
+If an upgrade is available, the banner is injected into the session context
+so Claude can mention it on its first turn — e.g. *"Note: agent-skills 0.2.0
+is available; want me to apply it via `/setup-agent-skills`?"*
+
+### 3. pi extension (`agent-skills-update-check`)
+
+When installed (offered in Group 10 of `/setup-agent-skills`), the extension fires on the
+first `agent_start` event of each pi session and emits a `ctx.ui.notify`
+message in the pi UI if a newer version is published. Reads the same cache
+as the CLI — no double-fetching.
+
+### Opting out
+
+Any of these environment variables disables all three:
+
+```bash
+export AGENT_SKILLS_NO_UPDATE_CHECK=1   # agent-skills-specific
+export NO_UPDATE_NOTIFIER=1             # conventional, also honoured
+# CI=true is auto-detected — banners never appear in CI logs
+```
+
+### Forcing a manual check
+
+```bash
+# Block on a single registry fetch; print the banner if outdated
+npx @chankov/agent-skills check-update
+
+# Bypass the cache entirely
+rm ~/.cache/agent-skills/latest-version.json
+npx @chankov/agent-skills check-update
+```
+
 ## Troubleshooting
 
 - **"Could not auto-detect your coding agent."** Pass `--agent` or run