@canonry/canonry 4.167.0 → 4.168.0

package/README.md

@@ -41,33 +41,45 @@ The dashboard, CLI, and agent tools share the same project API.
 
 You need Node.js `>=22.14` and `<26`, plus a public, crawlable site. Site Health does not need an answer-provider key.
 
-```bash
-npm install -g @canonry/canonry
-cnry bootstrap
-cnry serve
-```
+1. Install Canonry.
 
-`cnry bootstrap` creates the local configuration, SQLite database, and full-instance API key. Keep its output private. Provider credentials are optional. Bootstrap imports supported variables already in your environment.
+   ```bash
+   npm install -g @canonry/canonry
+   ```
 
-Open [http://127.0.0.1:4100/setup](http://127.0.0.1:4100/setup). By default, the first open asks you to create a dashboard password. Enter your domain and approve the public-site crawl to build a persisted Page Health baseline. AI Visibility is optional.
+2. Create the local configuration, SQLite database, and full-instance API key.
 
-To use the terminal instead of the setup page, keep `cnry serve` running and open a second terminal:
+   ```bash
+   cnry bootstrap
+   ```
 
-```bash
-cnry project create my-site --domain example.com --country US --language en
-cnry technical-aeo run my-site --max-pages 100 --wait --format json
-```
+   Keep the output private. Provider credentials are optional. Bootstrap imports supported variables that are already in your environment.
 
-The run command returns a run ID and status. If the status is `completed` or `partial`, read evidence from that run:
+3. Start Canonry.
 
-```bash
-cnry technical-aeo score my-site --run-id <run-id> --format json
-cnry technical-aeo pages my-site --run-id <run-id> --sort score-asc --limit 10 --format jsonl
-```
+   ```bash
+   cnry serve
+   ```
+
+4. Open [http://127.0.0.1:4100/setup](http://127.0.0.1:4100/setup). If prompted, create a dashboard password.
+
+5. Enter your domain and approve the public-site crawl. This crawl creates a persisted Page Health baseline. AI Visibility is optional.
+
+6. To use the terminal instead, keep `cnry serve` running. Open a second terminal and run:
+
+   ```bash
+   cnry project create my-site --domain example.com --country US --language en
+   cnry technical-aeo run my-site --max-pages 100 --wait --format json
+   ```
+
+7. Read the run ID and status from the output. If the status is `completed` or `partial`, read evidence from that run:
 
-`--wait` polls for up to 15 minutes. If the scan remains active, use the progress command below. If it fails or is cancelled, inspect it with `cnry run show <run-id> --format json`.
+   ```bash
+   cnry technical-aeo score my-site --run-id <run-id> --format json
+   cnry technical-aeo pages my-site --run-id <run-id> --sort score-asc --limit 10 --format jsonl
+   ```
 
-The CLI installs as both `cnry` and `canonry`. The commands are interchangeable. The compatibility package `@ainyc/canonry` remains available. Use `@canonry/canonry` for new installations.
+   `--wait` polls for up to 15 minutes. If the scan remains active, use the progress command below. If it fails or is cancelled, inspect it with `cnry run show <run-id> --format json`.
 
 ## Or use any shell-capable coding agent
 

package/assets/agent-workspace/skills/aero/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: aero
-description: AEO analyst orchestration — coordinates canonry sweeps and aeo-audit analysis with persistent memory and proactive regression response.
+description: "Diagnose AEO regressions and report on them: why mention or citation coverage moved, which queries and answer engines changed, and what to do about it. Use when a coverage number moved and needs explaining, when preparing a client report or month-over-month comparison, or when a `cnry` sweep completed and needs analysis. Coordinates canonry sweeps with aeo-audit site analysis and keeps durable project memory. Use the canonry skill for setup and operations instead."
 metadata:
   homepage: https://canonry.ai
   repository: https://github.com/AINYC/aero

package/assets/agent-workspace/skills/canonry/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: canonry
-description: "Set up and operate Canonry AEO projects. Inspect mention and citation coverage, diagnose regressions, and run technical audits. Connect Cloudflare direct-push or queue-pull traffic. Act through the Canonry CLI or MCP tools. Examples: inspect project acme coverage (run + report), diagnose query drift via attribution (report.html + visibility-attribution), or submit GSC sitemaps (gsc-sitemap-submission batched)."
+description: "Operate Canonry (the `cnry` / `canonry` CLI) for AEO. Load this BEFORE any canonry operator task: creating or configuring a project, connecting GSC, GA4, Bing, Google Business Profile or a Cloudflare traffic source, running or scheduling a sweep, reading mention and citation coverage, running a technical audit, submitting sitemaps, or diagnosing why a number moved. Covers anything touching cnry, canonry doctor, ~/.canonry, @canonry/canonry, the canonry_* MCP tools, mention share, or direct-push / queue-pull traffic. Load it before acting, not after something fails."
 compatibility: Requires Node.js 22.14+ and globally installed @canonry/canonry; canonry-mcp must be on PATH.
 metadata:
   agent: >-

package/dist/chunk-76JMZAFZ.js

@@ -0,0 +1,123 @@
+import {
+  BUNDLED_SKILL_NAMES,
+  PACKAGE_VERSION,
+  configExists,
+  installSkills,
+  loadConfigRaw,
+  saveConfigPatch
+} from "./chunk-C4UWZLQX.js";
+import {
+  SKILL_MANIFEST_FILENAME,
+  SkillsClients
+} from "./chunk-TP4KXU3E.js";
+
+// src/skills-autosync.ts
+import fs from "fs";
+import os from "os";
+import path from "path";
+var DEFAULT_SYNC_INTERVAL_SECONDS = 24 * 60 * 60;
+function peekVersionChange() {
+  if (!configExists()) return { state: "unknown" };
+  const raw = loadConfigRaw();
+  if (raw === null) return { state: "unknown" };
+  const lastSeen = raw.lastSkillsSyncedVersion;
+  if (lastSeen === PACKAGE_VERSION) return { state: "unchanged" };
+  return { state: "changed", lastSeen };
+}
+function syncIntervalSeconds(env = process.env) {
+  const raw = env.CANONRY_SKILLS_SYNC_SECS;
+  if (!raw) return DEFAULT_SYNC_INTERVAL_SECONDS;
+  const parsed = Number(raw);
+  return Number.isFinite(parsed) && parsed >= 0 ? parsed : DEFAULT_SYNC_INTERVAL_SECONDS;
+}
+function isDisabled(env = process.env) {
+  const raw = env.CANONRY_NO_AUTO_SKILLS_SYNC;
+  return raw === "1" || raw === "true";
+}
+function ownedInstallTargets(cwd = process.cwd(), home = os.homedir()) {
+  const seen = /* @__PURE__ */ new Set();
+  const candidates = [
+    { dir: path.resolve(home), user: true },
+    { dir: path.resolve(cwd), user: false }
+  ];
+  const targets = [];
+  for (const { dir, user } of candidates) {
+    if (seen.has(dir)) continue;
+    seen.add(dir);
+    const skills = BUNDLED_SKILL_NAMES.filter(
+      (name) => fs.existsSync(path.join(dir, ".claude", "skills", name, SKILL_MANIFEST_FILENAME))
+    );
+    if (skills.length === 0) continue;
+    const hasCodex = skills.some((name) => {
+      try {
+        return fs.lstatSync(path.join(dir, ".codex", "skills", name)).isSymbolicLink();
+      } catch {
+        return false;
+      }
+    });
+    targets.push({ dir, user, skills, client: hasCodex ? SkillsClients.all : SkillsClients.claude });
+  }
+  return targets;
+}
+async function autoSyncSkills(env = process.env) {
+  const skipped = { ran: false, reason: "skipped", updated: [], conflicts: [], targets: [] };
+  if (isDisabled(env)) return skipped;
+  const probe = peekVersionChange();
+  if (probe.state === "unknown") return skipped;
+  let reason;
+  if (probe.state === "changed") {
+    reason = "version-changed";
+  } else {
+    const intervalSeconds = syncIntervalSeconds(env);
+    if (intervalSeconds === 0) return skipped;
+    const raw = loadConfigRaw();
+    if (raw === null) return skipped;
+    const last = raw.lastSkillsVerifiedAt ? Date.parse(raw.lastSkillsVerifiedAt) : 0;
+    const elapsed = (Date.now() - (Number.isFinite(last) ? last : 0)) / 1e3;
+    if (elapsed < intervalSeconds) return skipped;
+    reason = "interval-elapsed";
+  }
+  const targets = ownedInstallTargets();
+  if (targets.length === 0) {
+    return skipped;
+  }
+  const updated = [];
+  const conflicts = [];
+  for (const target of targets) {
+    for (const skill of target.skills) {
+      try {
+        const summary = await installSkills({
+          ...target.user ? { user: true } : { dir: target.dir },
+          skills: [skill],
+          client: target.client
+        });
+        for (const result of summary.results) {
+          for (const p of result.updated ?? []) updated.push(p);
+          for (const p of result.conflicts ?? []) conflicts.push(p);
+        }
+      } catch {
+      }
+    }
+  }
+  recordVerified();
+  return { ran: true, reason, updated, conflicts, targets: targets.map((t) => t.dir) };
+}
+function recordVerified() {
+  try {
+    saveConfigPatch({
+      lastSkillsSyncedVersion: PACKAGE_VERSION,
+      lastSkillsVerifiedAt: (/* @__PURE__ */ new Date()).toISOString()
+    });
+  } catch {
+  }
+}
+function formatAutoSyncNotice(result) {
+  if (!result.ran || result.conflicts.length === 0) return null;
+  const count = result.conflicts.length;
+  return `canonry: ${count} locally edited skill file${count === 1 ? "" : "s"} kept as-is (engine is now v${PACKAGE_VERSION}). Run "canonry skills install --force" to take the new version.`;
+}
+
+export {
+  autoSyncSkills,
+  formatAutoSyncNotice
+};

package/dist/{chunk-P5LR3NDQ.js → chunk-C4UWZLQX.js}

@@ -1,8 +1,11 @@
 import {
   AGENT_MEMORY_KEY_MAX_LENGTH,
   AGENT_MEMORY_VALUE_MAX_BYTES,
+  CodingAgents,
   DISCOVERY_MAX_PROBES_CAP,
   DISCOVERY_PROBE_CONCURRENCY_CAP,
+  SKILL_MANIFEST_FILENAME,
+  SkillsClients,
   adsActivateTreeRequestSchema,
   adsAdCreateRequestSchema,
   adsAdGroupCreateRequestSchema,
@@ -16,6 +19,8 @@ import {
   adsPauseRequestSchema,
   adsUnresolvedOperationListQuerySchema,
   backlinkSourceSchema,
+  classifySkillFile,
+  coerceSkillManifest,
   competitorBatchRequestSchema,
   describeError,
   discoveryBucketSchema,
@@ -77,6 +82,7 @@ import {
   runTriggerRequestSchema,
   schedulableRunKindSchema,
   scheduleUpsertRequestSchema,
+  skillsClientSchema,
   trafficConnectCloudRunRequestSchema,
   trafficConnectVercelRequestSchema,
   trafficConnectWordpressRequestSchema,
@@ -626,7 +632,7 @@ var serializeObjectParam = ({
 
 // ../api-client-generated/src/generated/core/utils.gen.ts
 var PATH_PARAM_RE = /\{[^{}]+\}/g;
-var defaultPathSerializer = ({ path: path2, url: _url }) => {
+var defaultPathSerializer = ({ path: path3, url: _url }) => {
   let url = _url;
   const matches = _url.match(PATH_PARAM_RE);
   if (matches) {
@@ -645,7 +651,7 @@ var defaultPathSerializer = ({ path: path2, url: _url }) => {
         name = name.substring(1);
         style = "matrix";
       }
-      const value = path2[name];
+      const value = path3[name];
       if (value === void 0 || value === null) {
         continue;
       }
@@ -689,15 +695,15 @@ var defaultPathSerializer = ({ path: path2, url: _url }) => {
 };
 var getUrl = ({
   baseUrl,
-  path: path2,
+  path: path3,
   query,
   querySerializer,
   url: _url
 }) => {
   const pathUrl = _url.startsWith("/") ? _url : `/${_url}`;
   let url = (baseUrl ?? "") + pathUrl;
-  if (path2) {
-    url = defaultPathSerializer({ path: path2, url });
+  if (path3) {
+    url = defaultPathSerializer({ path: path3, url });
   }
   let search = query ? querySerializer(query) : "";
   if (search.startsWith("?")) {
@@ -5376,9 +5382,9 @@ var ApiClient = class {
    * structured-error behavior of `request()`; the caller reads `res.body`
    * and releases the response when done.
    */
-  async streamPost(path2, body, signal) {
+  async streamPost(path3, body, signal) {
     await this.probeBasePath();
-    const url = `${this.originUrl}/api/v1${path2}`;
+    const url = `${this.originUrl}/api/v1${path3}`;
     const headers = {
       Authorization: `Bearer ${this.apiKey}`,
       "Content-Type": "application/json",
@@ -7809,6 +7815,384 @@ import { createRequire } from "module";
 var _require = createRequire(import.meta.url);
 var PACKAGE_VERSION = _require("../package.json").version;
 
+// src/commands/skills.ts
+import crypto from "crypto";
+import fs2 from "fs";
+import os2 from "os";
+import path2 from "path";
+import { fileURLToPath } from "url";
+var BUNDLED_SKILL_NAMES = ["canonry", "aero"];
+function resolveBundledSkillsRoot(pkgDir) {
+  const here = pkgDir ?? path2.dirname(fileURLToPath(import.meta.url));
+  const candidates = [
+    path2.join(here, "../assets/agent-workspace/skills"),
+    path2.join(here, "../../assets/agent-workspace/skills"),
+    path2.join(here, "../../../../skills")
+  ];
+  for (const candidate of candidates) {
+    if (BUNDLED_SKILL_NAMES.every((name) => fs2.existsSync(path2.join(candidate, name, "SKILL.md")))) {
+      return candidate;
+    }
+  }
+  throw new CliError({
+    code: "INTERNAL_ERROR",
+    message: `Bundled skills not found. Searched:
+  ${candidates.join("\n  ")}`,
+    exitCode: 2
+  });
+}
+function parseDescription(content) {
+  const fmMatch = /^---\n([\s\S]*?)\n---/.exec(content);
+  if (!fmMatch) return "";
+  const descMatch = /^description:\s*(\S.*)$/m.exec(fmMatch[1]);
+  if (!descMatch) return "";
+  return descMatch[1].replace(/^["']|["']$/g, "").trim();
+}
+function getBundledSkills(pkgDir) {
+  const root = resolveBundledSkillsRoot(pkgDir);
+  return BUNDLED_SKILL_NAMES.map((name) => {
+    const skillDir = path2.join(root, name);
+    const skillFile = path2.join(skillDir, "SKILL.md");
+    const content = fs2.readFileSync(skillFile, "utf-8");
+    return { name, description: parseDescription(content), bundledPath: skillDir };
+  });
+}
+function walkRelative(dir, prefix = "") {
+  const out = [];
+  for (const entry of fs2.readdirSync(dir, { withFileTypes: true })) {
+    const rel = prefix ? path2.join(prefix, entry.name) : entry.name;
+    const full = path2.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      out.push(...walkRelative(full, rel));
+    } else if (entry.isFile()) {
+      out.push(rel);
+    }
+  }
+  return out.sort();
+}
+function sha256File(filePath) {
+  return crypto.createHash("sha256").update(fs2.readFileSync(filePath)).digest("hex");
+}
+function readSkillManifest(skillDir) {
+  try {
+    return coerceSkillManifest(JSON.parse(fs2.readFileSync(path2.join(skillDir, SKILL_MANIFEST_FILENAME), "utf-8")));
+  } catch {
+    return null;
+  }
+}
+function writeSkillManifest(skillDir, manifest) {
+  fs2.writeFileSync(path2.join(skillDir, SKILL_MANIFEST_FILENAME), `${JSON.stringify(manifest, null, 2)}
+`, "utf-8");
+}
+function reconcileSkillTree(srcDir, destDir, manifest, force) {
+  const result = { added: [], updated: [], unchanged: [], conflicts: [], bundledHashes: /* @__PURE__ */ new Map() };
+  for (const rel of walkRelative(srcDir)) {
+    const srcPath = path2.join(srcDir, rel);
+    const destPath = path2.join(destDir, rel);
+    const bundledHash = sha256File(srcPath);
+    result.bundledHashes.set(rel, bundledHash);
+    const installedHash = fs2.existsSync(destPath) ? sha256File(destPath) : void 0;
+    const state = classifySkillFile({ bundledHash, installedHash, manifestHash: manifest?.files[rel] });
+    switch (state) {
+      case "missing":
+        fs2.mkdirSync(path2.dirname(destPath), { recursive: true });
+        fs2.copyFileSync(srcPath, destPath);
+        result.added.push(rel);
+        break;
+      case "unchanged":
+        result.unchanged.push(rel);
+        break;
+      case "stale":
+        fs2.copyFileSync(srcPath, destPath);
+        result.updated.push(rel);
+        break;
+      case "edited":
+        if (force) {
+          fs2.copyFileSync(srcPath, destPath);
+          result.updated.push(rel);
+        } else {
+          result.conflicts.push(rel);
+        }
+        break;
+    }
+  }
+  return result;
+}
+function buildManifest(skillName, recon, prior) {
+  const conflicts = new Set(recon.conflicts);
+  const files = {};
+  for (const [rel, bundledHash] of recon.bundledHashes) {
+    files[rel] = conflicts.has(rel) ? prior?.files[rel] ?? bundledHash : bundledHash;
+  }
+  return { skill: skillName, version: PACKAGE_VERSION, files };
+}
+function describeChanges(recon) {
+  const parts = [];
+  if (recon.added.length > 0) parts.push(`${recon.added.length} added`);
+  if (recon.updated.length > 0) parts.push(`${recon.updated.length} refreshed`);
+  return parts.length > 0 ? parts.join(", ") : "no changes";
+}
+function buildClaudeMessage(name, status, recon) {
+  const rel = `.claude/skills/${name}`;
+  let message = status === "installed" ? `Installed ${rel}` : status === "updated" ? `Updated ${rel} (${describeChanges(recon)})` : `Already installed: ${rel}`;
+  if (recon.conflicts.length > 0) {
+    message += ` \u2014 ${recon.conflicts.length} file(s) differ from the bundle (local edits kept; pass --force to overwrite)`;
+  }
+  return message;
+}
+function installClaudeSkill(skill, targetDir, force) {
+  const targetPath = path2.join(targetDir, ".claude", "skills", skill.name);
+  const existedBefore = fs2.existsSync(path2.join(targetPath, "SKILL.md"));
+  const priorManifest = readSkillManifest(targetPath);
+  fs2.mkdirSync(targetPath, { recursive: true });
+  const recon = reconcileSkillTree(skill.bundledPath, targetPath, priorManifest, force);
+  writeSkillManifest(targetPath, buildManifest(skill.name, recon, priorManifest));
+  const changed = recon.added.length + recon.updated.length;
+  const status = !existedBefore ? "installed" : changed > 0 ? "updated" : "already-installed";
+  return {
+    skill: skill.name,
+    client: CodingAgents.claude,
+    targetPath,
+    status,
+    message: buildClaudeMessage(skill.name, status, recon),
+    added: recon.added,
+    updated: recon.updated,
+    unchanged: recon.unchanged,
+    conflicts: recon.conflicts
+  };
+}
+function installCodexSymlink(skill, targetDir, force) {
+  const codexPath = path2.join(targetDir, ".codex", "skills", skill.name);
+  const claudePath = path2.join(targetDir, ".claude", "skills", skill.name);
+  const linkTarget = path2.relative(path2.dirname(codexPath), claudePath);
+  fs2.mkdirSync(path2.dirname(codexPath), { recursive: true });
+  let stat;
+  try {
+    stat = fs2.lstatSync(codexPath);
+  } catch {
+    stat = void 0;
+  }
+  if (stat?.isSymbolicLink()) {
+    const existing = fs2.readlinkSync(codexPath);
+    if (existing === linkTarget) {
+      return {
+        skill: skill.name,
+        client: CodingAgents.codex,
+        targetPath: codexPath,
+        status: "already-linked",
+        message: `Already linked: .codex/skills/${skill.name}`
+      };
+    }
+    if (!force) {
+      throw new CliError({
+        code: "VALIDATION_ERROR",
+        message: `.codex/skills/${skill.name} is a symlink pointing elsewhere (${existing}). Pass --force to relink.`,
+        details: { skill: skill.name, targetPath: codexPath, existingTarget: existing },
+        exitCode: 1
+      });
+    }
+    fs2.unlinkSync(codexPath);
+    fs2.symlinkSync(linkTarget, codexPath);
+    return {
+      skill: skill.name,
+      client: CodingAgents.codex,
+      targetPath: codexPath,
+      status: "relinked",
+      message: `Relinked .codex/skills/${skill.name} \u2192 ${linkTarget}`
+    };
+  }
+  if (stat) {
+    if (!force) {
+      throw new CliError({
+        code: "VALIDATION_ERROR",
+        message: `.codex/skills/${skill.name} exists but is not a symlink. Pass --force to replace.`,
+        details: { skill: skill.name, targetPath: codexPath },
+        exitCode: 1
+      });
+    }
+    fs2.rmSync(codexPath, { recursive: true, force: true });
+  }
+  fs2.symlinkSync(linkTarget, codexPath);
+  return {
+    skill: skill.name,
+    client: CodingAgents.codex,
+    targetPath: codexPath,
+    status: stat ? "relinked" : "linked",
+    message: stat ? `Replaced and linked .codex/skills/${skill.name} \u2192 ${linkTarget}` : `Linked .codex/skills/${skill.name} \u2192 ${linkTarget}`
+  };
+}
+function buildSummaryMessage(results) {
+  const counts = {};
+  for (const r of results) counts[r.status] = (counts[r.status] ?? 0) + 1;
+  const parts = Object.entries(counts).map(([status, n]) => `${n} ${status}`);
+  let message = `Skills install summary: ${parts.join(", ")}.`;
+  const totalConflicts = results.reduce((sum, r) => sum + (r.conflicts?.length ?? 0), 0);
+  if (totalConflicts > 0) {
+    message += ` ${totalConflicts} file(s) differ from the bundle and were kept \u2014 pass --force to overwrite local edits.`;
+  }
+  return message;
+}
+function getBundledSkillSnapshots(pkgDir) {
+  return getBundledSkills(pkgDir).map((skill) => {
+    const files = {};
+    for (const rel of walkRelative(skill.bundledPath)) {
+      files[rel] = sha256File(path2.join(skill.bundledPath, rel));
+    }
+    return {
+      name: skill.name,
+      version: PACKAGE_VERSION,
+      files,
+      description: readBundledSkillDescription(skill.bundledPath)
+    };
+  });
+}
+function readBundledSkillDescription(skillDir) {
+  let raw;
+  try {
+    raw = fs2.readFileSync(path2.join(skillDir, "SKILL.md"), "utf-8");
+  } catch {
+    return void 0;
+  }
+  const parts = raw.split("---");
+  if (parts.length < 3) return void 0;
+  const lines = (parts[1] ?? "").split("\n");
+  const collected = [];
+  let inside = false;
+  for (const line of lines) {
+    const isTopLevelKey = /^[a-z][\w-]*:/i.test(line);
+    if (inside && isTopLevelKey) break;
+    if (isTopLevelKey && line.startsWith("description:")) {
+      inside = true;
+      collected.push(line.slice("description:".length).trim());
+      continue;
+    }
+    if (inside) collected.push(line.trim());
+  }
+  if (!inside) return void 0;
+  const value = collected.join(" ").trim();
+  const unquoted = value.length >= 2 && value.startsWith('"') && value.endsWith('"') ? value.slice(1, -1) : value;
+  return unquoted.length > 0 ? unquoted : void 0;
+}
+async function installSkills(opts = {}) {
+  const targetDir = opts.user ? os2.homedir() : path2.resolve(opts.dir ?? process.cwd());
+  const client2 = opts.client ?? SkillsClients.all;
+  const force = opts.force ?? false;
+  const allSkills = getBundledSkills();
+  const requestedNames = opts.skills && opts.skills.length > 0 ? opts.skills : allSkills.map((s) => s.name);
+  const knownNames = new Set(allSkills.map((s) => s.name));
+  const unknown = requestedNames.filter((n) => !knownNames.has(n));
+  if (unknown.length > 0) {
+    throw new CliError({
+      code: "VALIDATION_ERROR",
+      message: `Unknown skill(s): ${unknown.join(", ")}. Available: ${[...knownNames].join(", ")}`,
+      details: { unknownSkills: unknown, availableSkills: [...knownNames] },
+      exitCode: 1
+    });
+  }
+  const skillsToInstall = allSkills.filter((s) => requestedNames.includes(s.name));
+  fs2.mkdirSync(targetDir, { recursive: true });
+  const results = [];
+  for (const skill of skillsToInstall) {
+    results.push(installClaudeSkill(skill, targetDir, force));
+    if (client2 !== SkillsClients.claude) {
+      results.push(installCodexSymlink(skill, targetDir, force));
+    }
+  }
+  return {
+    targetDir,
+    results,
+    message: buildSummaryMessage(results)
+  };
+}
+async function listSkills(opts = {}) {
+  const skills = getBundledSkills();
+  if (isMachineFormat(opts.format)) {
+    console.log(JSON.stringify({
+      skills: skills.map((s) => ({
+        name: s.name,
+        description: s.description,
+        claudePath: `.claude/skills/${s.name}`,
+        codexPath: `.codex/skills/${s.name}`
+      }))
+    }, null, 2));
+    return;
+  }
+  console.log("Bundled canonry skills:\n");
+  for (const skill of skills) {
+    console.log(`  ${skill.name}`);
+    if (skill.description) console.log(`    ${skill.description}`);
+    console.log(`    Claude: .claude/skills/${skill.name}/`);
+    console.log(`    Codex:  .codex/skills/${skill.name} (symlink \u2192 ../../.claude/skills/${skill.name})`);
+    console.log();
+  }
+}
+function emitInstallSummary(summary, format) {
+  if (isMachineFormat(format)) {
+    console.log(JSON.stringify(summary, null, 2));
+    return;
+  }
+  for (const r of summary.results) console.log(r.message);
+  console.log(`
+Target: ${summary.targetDir}`);
+  console.log(summary.message);
+}
+function getMissingUserSkillsNudge(home, agentPlugin) {
+  if (!home) return null;
+  const skillsBase = path2.join(home, ".claude", "skills");
+  const installed = [];
+  const missing = [];
+  for (const name of BUNDLED_SKILL_NAMES) {
+    const skillFile = path2.join(skillsBase, name, "SKILL.md");
+    if (existsSafe(skillFile)) installed.push(name);
+    else missing.push(name);
+  }
+  if (agentPlugin && agentPlugin.configuredClients.length > 0) {
+    const unverifiedClients = agentPlugin.configuredClients.filter((client2) => !agentPlugin.verifiedClients.includes(client2));
+    const mismatchedClients = agentPlugin.verifiedClients.filter((client2) => agentPlugin.verifiedClientVersions?.[client2] !== PACKAGE_VERSION);
+    if (unverifiedClients.length === 0 && mismatchedClients.length === 0) return null;
+    const displayClients = (clients) => clients.map((client2) => client2 === "claude-code" ? "Claude Code" : "Codex").join(" + ");
+    const problems = [];
+    if (unverifiedClients.length > 0) {
+      problems.push(`The Canonry plugin is enabled for ${displayClients(unverifiedClients)}, but its cached manifest and skill assets could not be verified.`);
+    }
+    if (mismatchedClients.length > 0) {
+      const versions = mismatchedClients.map((client2) => `${client2 === "claude-code" ? "Claude Code" : "Codex"} v${agentPlugin.verifiedClientVersions?.[client2] ?? "unknown"}`).join(", ");
+      problems.push(`${versions} ${mismatchedClients.length === 1 ? "does" : "do"} not match the running Canonry v${PACKAGE_VERSION}.`);
+    }
+    return {
+      message: `Tip: ${problems.join(" ")} Update or reinstall \`canonry@canonry\` with the affected client plugin manager.`,
+      missing,
+      installed
+    };
+  }
+  if (missing.length === 0) return null;
+  const fix = missing.length === BUNDLED_SKILL_NAMES.length ? "canonry skills install --user" : `canonry skills install ${missing.join(" ")} --user`;
+  return {
+    message: `Tip: ${missing.join(" + ")} skill${missing.length === 1 ? "" : "s"} not installed in ~/.claude/skills/. Run \`${fix}\` so Claude/Codex sessions on this host auto-load the canonry reference docs.`,
+    missing,
+    installed
+  };
+}
+function existsSafe(p) {
+  try {
+    return fs2.existsSync(p);
+  } catch {
+    return false;
+  }
+}
+function parseSkillsClient(value) {
+  if (!value) return SkillsClients.all;
+  const parsed = skillsClientSchema.safeParse(value);
+  if (parsed.success) return parsed.data;
+  const allowed = skillsClientSchema.options;
+  throw new CliError({
+    code: "VALIDATION_ERROR",
+    message: `Invalid --client value "${value}". Must be one of: ${allowed.join(", ")}`,
+    details: { flag: "client", value, allowed },
+    exitCode: 1
+  });
+}
+
 // src/mcp/tool-registry.ts
 import { z as z3 } from "zod";
 
@@ -11064,9 +11448,16 @@ export {
   isEndpointMissing,
   systemError,
   printCliError,
+  PACKAGE_VERSION,
+  BUNDLED_SKILL_NAMES,
+  getBundledSkillSnapshots,
+  installSkills,
+  listSkills,
+  emitInstallSummary,
+  getMissingUserSkillsNudge,
+  parseSkillsClient,
   createApiClient,
   ApiClient,
-  PACKAGE_VERSION,
   measurementDraftOperationSchema,
   runMeasurementDraftAction,
   canonryMcpTools,