@agentprojectcontext/apx 1.33.1 → 1.35.0

package/src/interfaces/cli/commands/pair.js

@@ -8,6 +8,7 @@
 import os from "node:os";
 import qrcode from "qrcode-terminal";
 import { http } from "../http.js";
+import { CHANNELS } from "#core/constants/channels.js";
 
 const c = {
   reset:  "\x1b[0m",
@@ -88,10 +89,10 @@ async function runPairing(args, channel) {
   // 2. QR payload differs per channel — no mixing.
   //    deck: JSON {v,url,pid,fp} that the Deck app parses.
   //    web : the scan-to-login URL the browser understands.
-  const qrData = channel === "web"
+  const qrData = channel === CHANNELS.WEB
     ? webLink
     : JSON.stringify({ v: 1, url: baseUrl, pid: init.pairing_id, fp: init.fingerprint });
-  const title = channel === "web" ? "APX pairing (web)" : "APX pairing (deck)";
+  const title = channel === CHANNELS.WEB ? "APX pairing (web)" : "APX pairing (deck)";
 
   console.log("");
   console.log(`  ${fmt.bold(title)}  ${fmt.gray("·")}  ${fmt.dim(`expires in ${ttlSec}s`)}`);
@@ -100,7 +101,7 @@ async function runPairing(args, channel) {
     console.log(qr);
   });
 
-  if (channel === "web") {
+  if (channel === CHANNELS.WEB) {
     console.log(`  ${fmt.gray("scan with the phone camera — opens the web already linked")}`);
     console.log(`  ${fmt.gray("link:")} ${fmt.cyan(webLink)}`);
     console.log(`  ${fmt.gray("code:")} ${fmt.bold(init.pairing_id)}  ${fmt.dim("(or paste it in the web pairing screen)")}`);
@@ -111,7 +112,7 @@ async function runPairing(args, channel) {
   console.log("");
 
   // 3. Poll /pair/status until confirmed or expired.
-  const reRun = channel === "web" ? "apx pair web" : "apx pair";
+  const reRun = channel === CHANNELS.WEB ? "apx pair web" : "apx pair";
   const deadline = Date.now() + (init.ttl_ms || 90_000) + 5_000;
   while (Date.now() < deadline) {
     await sleep(1500);

package/src/interfaces/cli/commands/search.js

@@ -3,7 +3,7 @@
 // Uses the daemon's tools/search.js module directly (no HTTP roundtrip,
 // no need to have `apx daemon start` running).
 
-import { webSearch } from "#core/tools/search.js";
+import { webSearch } from "#core/http-tools/search.js";
 
 const DIM   = "\x1b[2m";
 const BOLD  = "\x1b[1m";

package/src/interfaces/cli/commands/sessions.js

@@ -5,6 +5,7 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { apcProjectFile } from "#core/apc/paths.js";
 
 // ── shared helpers ───────────────────────────────────────────────────────────
 
@@ -124,7 +125,7 @@ function readApxProjects(opts) {
       const proj = { path: path.resolve(e.path), name: null, apxId: null };
       try {
         const pj = JSON.parse(
-          fs.readFileSync(path.join(proj.path, ".apc", "project.json"), "utf8")
+          fs.readFileSync(apcProjectFile(proj.path), "utf8")
         );
         if (pj.name) proj.name = pj.name;
         if (pj.apx_id) proj.apxId = pj.apx_id;
@@ -608,7 +609,7 @@ const apxEngine = {
     let apxId = null;
     try {
       const pj = JSON.parse(
-        fs.readFileSync(path.join(dir, ".apc", "project.json"), "utf8")
+        fs.readFileSync(apcProjectFile(dir), "utf8")
       );
       apxId = pj.apx_id || null;
     } catch {}

package/src/interfaces/cli/commands/skills.js

@@ -4,6 +4,7 @@ import path from "node:path";
 import os from "node:os";
 import readline from "node:readline";
 import { findApfRoot } from "#core/apc/parser.js";
+import { apcSkillsDir } from "#core/apc/paths.js";
 import { http } from "../http.js";
 import {
   IDE_TARGETS,
@@ -11,7 +12,23 @@ import {
   installGlobalSkills,
   listBundledSkillSlugs,
   listBundledSkills,
+  listEngineSkills,
+  listLegacyPruneSlugs,
 } from "#core/apc/scaffold.js";
+import {
+  ensureIndex,
+  planIndex,
+  readIndex,
+  clearIndex,
+  indexPath,
+} from "#core/agent/skills/index-store.js";
+import { isInspectorEnabled } from "#core/agent/skills/inspector.js";
+import {
+  inspectPromptForSkills,
+  summarizeTrace,
+  INSPECTOR_DEFAULTS,
+} from "#core/agent/skills/inspector.js";
+import { readConfig, writeConfig } from "#core/config/index.js";
 
 // ---------------------------------------------------------------------------
 // Prompt helper
@@ -27,6 +44,31 @@ function ask(question) {
   });
 }
 
+// When the Skill Inspector is on, the catalog it scores against must stay in
+// sync with what's installed. Called after add/sync so a freshly available
+// skill is searchable immediately, without a separate `apx skills index`.
+// No-op (silent) when the inspector is disabled — nothing reads the index then.
+async function reindexInspectorIfEnabled() {
+  let config;
+  try {
+    config = readConfig();
+  } catch {
+    return;
+  }
+  if (!isInspectorEnabled(config)) return;
+  try {
+    const plan = planIndex({});
+    const work = plan.missing.length + plan.stale.length + plan.gone.length;
+    if (work === 0) return;
+    process.stdout.write(`\n  Skill Inspector on — reindexing ${work} changed skill(s)… `);
+    const out = await ensureIndex({ embedOpts: { globalConfig: config } });
+    const c = out.changed;
+    console.log(`done (${out.embedder}: +${c.added.length} ~${c.refreshed.length} -${c.removed.length}).`);
+  } catch (e) {
+    console.log(`\n  (skill index refresh failed: ${e.message})`);
+  }
+}
+
 // ---------------------------------------------------------------------------
 // apx skills add [<target>...] [--global] [--project]
 // ---------------------------------------------------------------------------
@@ -62,6 +104,7 @@ export async function cmdSkillsAdd(args) {
     }
     console.log("\n  Loaded by: Claude Code, Cursor, Codex (OpenAI), Antigravity, and skills.sh-compatible tools.");
     console.log("  Activates automatically when working in a project with AGENTS.md or .apc/");
+    await reindexInspectorIfEnabled();
     return;
   }
 
@@ -90,6 +133,7 @@ export async function cmdSkillsAdd(args) {
     console.log("");
     for (const t of notes) console.log(`  note: ${t.note}`);
   }
+  await reindexInspectorIfEnabled();
 }
 
 // ---------------------------------------------------------------------------
@@ -100,37 +144,27 @@ export async function cmdSkillsAdd(args) {
 // ---------------------------------------------------------------------------
 
 export async function cmdSkillsSync(args) {
-  const includeOptional = !!args?.flags?.["include-optional"] || !!args?.flags?.optional;
-  const includeInternal = !!args?.flags?.["include-internal"] || !!args?.flags?.internal;
   const prune = args?.flags?.["no-prune"] ? false : true;
 
-  const results = installGlobalSkills({ includeOptional, includeInternal, prune });
+  const results = installGlobalSkills({ prune });
   const home = os.homedir();
 
-  // Group by skill so the output is dense and scannable.
   const bySkill = {};
-  const scopeOf = {};
   for (const r of results) {
     if (!bySkill[r.skill]) bySkill[r.skill] = [];
-    bySkill[r.skill].push({ dir: r.dir.replace(home, "~"), status: r.status });
-    scopeOf[r.skill] = r.scope;
+    bySkill[r.skill].push({ dir: r.dir.replace(home, "~"), status: r.status, scope: r.scope });
   }
 
-  const slugs = Object.keys(bySkill).sort();
-  if (slugs.length === 0) {
-    console.log("(no bundled skills found in skills/)");
+  const engineSet = listEngineSkills().map((s) => s.slug);
+  if (engineSet.length === 0) {
+    console.log("(no engine skills found in skills/engines/)");
     return;
   }
 
-  const filters = [];
-  if (includeOptional) filters.push("+optional");
-  if (includeInternal) filters.push("+internal");
-  console.log(
-    `Syncing ${slugs.length} bundled skill(s) to global skill dirs` +
-      (filters.length ? ` [${filters.join(" ")}]` : "") + ":\n"
-  );
+  console.log(`Syncing engine skill set (${engineSet.join(", ")}) to global dirs:\n`);
 
-  const sw = Math.max(...slugs.map((s) => s.length));
+  const slugs = Object.keys(bySkill).sort();
+  const sw = Math.max(...slugs.map((s) => s.length), 8);
   const totals = { unchanged: 0, updated: 0, created: 0, pruned: 0 };
   for (const slug of slugs) {
     const entries = bySkill[slug];
@@ -141,9 +175,8 @@ export async function cmdSkillsSync(args) {
     for (const k of ["created", "updated", "unchanged", "pruned"]) {
       if (counts[k]) parts.push(`${counts[k]} ${k}`);
     }
-    const scope = scopeOf[slug];
-    const tag = scope === "public" ? "" : ` [${scope}]`;
-    console.log(`  ${slug.padEnd(sw)}${tag.padEnd(11)}  ${parts.join(", ")}`);
+    const tag = entries[0]?.scope === "legacy" ? " [legacy]" : "";
+    console.log(`  ${slug.padEnd(sw)}${tag.padEnd(10)}  ${parts.join(", ")}`);
   }
   console.log("");
   console.log(`Targets: .claude/skills, .cursor/skills, .codex/skills, .agents/skills`);
@@ -153,21 +186,6 @@ export async function cmdSkillsSync(args) {
   }
   console.log(`Totals:  ${totalParts.join(", ") || "(no changes)"}`);
 
-  // Hint about non-default tiers.
-  const skipped = listBundledSkills().filter(
-    (s) =>
-      (s.scope === "internal" && !includeInternal) ||
-      (s.scope === "optional" && !includeOptional)
-  );
-  if (skipped.length > 0) {
-    console.log("");
-    console.log("Skipped (not pushed by default):");
-    for (const s of skipped) console.log(`  ${s.slug.padEnd(sw)}  scope=${s.scope}`);
-    console.log("");
-    console.log("Re-run with --include-optional / --include-internal to push them too,");
-    console.log("or `apx skills add <slug> --global` for one-off install.");
-  }
-
   if (args?.flags?.verbose) {
     console.log("");
     for (const slug of slugs) {
@@ -177,6 +195,7 @@ export async function cmdSkillsSync(args) {
       }
     }
   }
+  await reindexInspectorIfEnabled();
 }
 
 // ---------------------------------------------------------------------------
@@ -184,8 +203,8 @@ export async function cmdSkillsSync(args) {
 // ---------------------------------------------------------------------------
 
 export async function cmdSkillsList(args = {}) {
-  // --all queries the daemon, which returns project + global + bundled +
-  // runtime-skills (same catalog the super-agent sees and the web picker uses).
+  // --all queries the daemon, which returns project + global + bundled
+  // (the same catalog the super-agent sees and the web picker uses).
   // Without --all we only list `.apc/skills/` (what the user installed in
   // THIS project), matching the historical behaviour.
   if (args?.flags?.all) {
@@ -205,7 +224,7 @@ export async function cmdSkillsList(args = {}) {
   }
 
   const root = findApfRoot();
-  const skillsDir = root ? path.join(root, ".apc", "skills") : null;
+  const skillsDir = root ? apcSkillsDir(root) : null;
   const files = skillsDir && fs.existsSync(skillsDir)
     ? fs.readdirSync(skillsDir).filter((f) => f.endsWith(".md"))
     : [];
@@ -224,17 +243,15 @@ export async function cmdSkillsList(args = {}) {
 export async function cmdSkillsStatus() {
   const root = findApfRoot();
 
-  // Global — discovered list of every bundled skill with its scope.
-  const bundled = listBundledSkills();
-  const byScope = {
-    public: bundled.filter((s) => s.scope === "public"),
-    optional: bundled.filter((s) => s.scope === "optional"),
-    internal: bundled.filter((s) => s.scope === "internal"),
-  };
+  const engineSet = listEngineSkills();        // what we publish to engines
+  const bundled = listBundledSkills();          // what stays in-repo for the super-agent
+  const legacy = listLegacyPruneSlugs();        // slugs APX shipped historically — pruned on sync
+
   console.log(
-    `Bundled skills: ${bundled.length} total (${byScope.public.length} public, ` +
-      `${byScope.optional.length} optional, ${byScope.internal.length} internal)`
+    `Engine skill set (replicated to global dirs): ${engineSet.length} ` +
+      `(${engineSet.map((s) => s.slug).join(", ") || "—"})`
   );
+  console.log(`In-repo bundled skills (super-agent only): ${bundled.length}`);
   console.log("");
   console.log(`Global skill dirs:`);
   const GLOBAL_DIRS = [
@@ -243,17 +260,23 @@ export async function cmdSkillsStatus() {
     { label: "Codex",                       dir: path.join(os.homedir(), ".codex",  "skills") },
     { label: "Antigravity / others",        dir: path.join(os.homedir(), ".agents", "skills") },
   ];
-  const sw = Math.max(...bundled.map((s) => s.slug.length));
+  const allSlugs = [...engineSet.map((s) => s.slug), ...legacy];
+  const sw = Math.max(...allSlugs.map((s) => s.length), 8);
   for (const { label, dir } of GLOBAL_DIRS) {
     console.log(`\n  ${label} — ${dir.replace(os.homedir(), "~")}`);
-    for (const { slug, scope } of bundled) {
+    for (const { slug } of engineSet) {
       const dest = path.join(dir, slug, "SKILL.md");
       const present = fs.existsSync(dest);
-      const tag = scope === "public" ? "" : ` [${scope}]`;
-      const state = present
-        ? "✓ installed"
-        : (scope === "public" ? "✗ MISSING (run `apx skills sync`)" : "—");
-      console.log(`    ${slug.padEnd(sw)}${tag.padEnd(11)}  ${state}`);
+      const state = present ? "✓ installed" : "✗ MISSING (run `apx skills sync`)";
+      console.log(`    ${slug.padEnd(sw)}             ${state}`);
+    }
+    const stale = legacy.filter((slug) =>
+      fs.existsSync(path.join(dir, slug, "SKILL.md"))
+    );
+    if (stale.length) {
+      for (const slug of stale) {
+        console.log(`    ${slug.padEnd(sw)} [legacy]    ⚠ stale (run \`apx skills sync\` to prune)`);
+      }
     }
   }
 
@@ -280,3 +303,215 @@ export async function cmdSkillsStatus() {
   console.log("\n  Tip: run `apx skills add` for an interactive install.");
   console.log("  Claude Desktop has no project-file support (use apx-mcp instead).");
 }
+
+// ---------------------------------------------------------------------------
+// apx skills index [--reset] [--force]
+//
+// Build the persistent vector index that powers the skill Inspector. Runs the
+// configured embedding provider (defaults to local: ollama → tf fallback) over
+// every skill's condensed description and writes ~/.apx/skills/.index.json.
+// ---------------------------------------------------------------------------
+
+function renderBar(done, total, width = 24) {
+  if (!Number.isFinite(total) || total <= 0) return "";
+  const ratio = Math.max(0, Math.min(1, done / total));
+  const filled = Math.round(ratio * width);
+  return "[" + "█".repeat(filled) + " ".repeat(width - filled) + "]";
+}
+
+export async function cmdSkillsIndex(args = {}) {
+  const reset = !!args?.flags?.reset;
+  const force = !!args?.flags?.force;
+  if (reset) clearIndex();
+
+  const config = readConfig();
+  const root = findApfRoot();
+  const projectPath = root || undefined;
+
+  const plan = planIndex({ projectPath });
+  if (plan.total === 0) {
+    console.log("(no skills available — install some first with `apx skills sync` or drop a SKILL.md in ~/.apx/skills/<slug>/)");
+    return;
+  }
+
+  const headline = force
+    ? `Rebuilding index for ${plan.total} skills (force).`
+    : `Indexing ${plan.total} skills (${plan.existing.length} cached · ${plan.missing.length} new · ${plan.stale.length} stale · ${plan.gone.length} gone).`;
+  console.log(headline);
+
+  const t0 = Date.now();
+  let lastLine = "";
+  const out = await ensureIndex({
+    projectPath,
+    embedOpts: { globalConfig: config },
+    force,
+    onProgress: ({ done, total, slug, action }) => {
+      const bar = renderBar(done, total);
+      const tag = action.padEnd(9);
+      const line = `\r${bar} ${done}/${total}  ${tag}  ${slug}`.padEnd(lastLine.length, " ");
+      process.stdout.write(line);
+      lastLine = line;
+    },
+  });
+
+  const elapsedMs = Date.now() - t0;
+  process.stdout.write("\r" + " ".repeat(lastLine.length) + "\r");
+
+  const c = out.changed;
+  console.log(
+    `Done in ${(elapsedMs / 1000).toFixed(1)}s using ${out.embedder} (dim ${out.dim}).\n` +
+    `  added:     ${c.added.length}\n` +
+    `  refreshed: ${c.refreshed.length}\n` +
+    `  removed:   ${c.removed.length}\n` +
+    `  kept:      ${c.kept.length}\n` +
+    `  index:     ${indexPath()}`
+  );
+  if (c.added.length || c.refreshed.length) {
+    const sample = [...c.added, ...c.refreshed].slice(0, 6).join(", ");
+    if (sample) console.log(`  changes:   ${sample}${(c.added.length + c.refreshed.length) > 6 ? ", …" : ""}`);
+  }
+  if (out.embedder === "tf") {
+    console.log("  note:      using offline TF fallback (no embedding provider reachable). Configure one in config.memory.embeddings for better recall.");
+  }
+}
+
+// ---------------------------------------------------------------------------
+// apx skills inspect <prompt>
+//
+// Show what the Inspector would inject for a given user prompt. Doesn't touch
+// the model — pure middleware debug. Useful to tune thresholds and to see why
+// a skill did or didn't fire.
+// ---------------------------------------------------------------------------
+
+export async function cmdSkillsInspect(args) {
+  const promptParts = args?._ || [];
+  const prompt = promptParts.join(" ").trim();
+  if (!prompt) {
+    console.error("usage: apx skills inspect \"<prompt text>\"");
+    process.exitCode = 2;
+    return;
+  }
+
+  const config = readConfig();
+  const root = findApfRoot();
+  const projectPath = root || undefined;
+
+  // Force the inspector on for this command even if config has it off — the
+  // operator is explicitly asking "what WOULD the inspector do?".
+  const probedConfig = structuredClone(config);
+  probedConfig.skills = probedConfig.skills || {};
+  probedConfig.skills.inspector = {
+    ...INSPECTOR_DEFAULTS,
+    ...(probedConfig.skills.inspector || {}),
+    enabled: true,
+  };
+
+  const out = await inspectPromptForSkills({
+    prompt,
+    projectPath,
+    globalConfig: probedConfig,
+  });
+
+  console.log(`prompt:    ${prompt}`);
+  console.log(`embedder:  ${out.trace.embedder || "(none)"}`);
+  console.log(`decision:  ${summarizeTrace(out.trace)}`);
+  if (out.trace.scored?.length) {
+    console.log("scores:");
+    for (const s of out.trace.scored) console.log(`  ${s.sim.toFixed(3)}  ${s.slug}`);
+  }
+  if (out.contextNote) {
+    console.log("");
+    console.log("--- contextNote that would be injected ---");
+    console.log(out.contextNote);
+    console.log("--- end ---");
+  }
+}
+
+// ---------------------------------------------------------------------------
+// apx skills inspector [enable|disable|status|set <key> <value>]
+//
+// Manage config.skills.inspector. All keys live under that namespace; this
+// command is a thin shortcut so you don't have to remember the path.
+// ---------------------------------------------------------------------------
+
+const KNOWN_INSPECTOR_KEYS = Object.keys(INSPECTOR_DEFAULTS);
+
+function ensureInspectorBlock(cfg) {
+  cfg.skills = cfg.skills || {};
+  cfg.skills.inspector = { ...INSPECTOR_DEFAULTS, ...(cfg.skills.inspector || {}) };
+  return cfg;
+}
+
+function printInspectorStatus(cfg) {
+  const insp = cfg.skills?.inspector || {};
+  const merged = { ...INSPECTOR_DEFAULTS, ...insp };
+  console.log(`Skill Inspector: ${merged.enabled ? "ENABLED" : "disabled"}`);
+  for (const k of KNOWN_INSPECTOR_KEYS) {
+    if (k === "enabled") continue;
+    console.log(`  ${k.padEnd(16)} ${merged[k]}`);
+  }
+  const idx = readIndex();
+  const count = Object.keys(idx.items || {}).length;
+  console.log("");
+  console.log(`Index: ${count} skills (${idx.embedder || "—"}, dim ${idx.dim || "—"})`);
+  console.log(`File:  ${indexPath()}`);
+}
+
+export async function cmdSkillsInspector(args) {
+  const sub = (args?._ || [])[0];
+  const cfg = readConfig();
+
+  if (!sub || sub === "status") {
+    printInspectorStatus(cfg);
+    return;
+  }
+  if (sub === "enable" || sub === "on") {
+    ensureInspectorBlock(cfg).skills.inspector.enabled = true;
+    writeConfig(cfg);
+    console.log("Skill Inspector ENABLED. The catalog-wide hint block will be suppressed; per-turn RAG decides what skills go into context.");
+    console.log("Tip: run `apx skills index` once so the inspector has cached vectors to score against.");
+    return;
+  }
+  if (sub === "disable" || sub === "off") {
+    ensureInspectorBlock(cfg).skills.inspector.enabled = false;
+    writeConfig(cfg);
+    console.log("Skill Inspector disabled. Falling back to the legacy slug hint + passive RAG nudge.");
+    return;
+  }
+  if (sub === "set") {
+    const key = args._[1];
+    const value = args._[2];
+    if (!key || value === undefined) {
+      console.error("usage: apx skills inspector set <key> <value>");
+      console.error(`keys: ${KNOWN_INSPECTOR_KEYS.join(", ")}`);
+      process.exitCode = 2;
+      return;
+    }
+    if (!KNOWN_INSPECTOR_KEYS.includes(key)) {
+      console.error(`unknown key "${key}". Known: ${KNOWN_INSPECTOR_KEYS.join(", ")}`);
+      process.exitCode = 2;
+      return;
+    }
+    ensureInspectorBlock(cfg);
+    const def = INSPECTOR_DEFAULTS[key];
+    let coerced = value;
+    if (typeof def === "boolean") coerced = value === "true" || value === "1" || value === "on";
+    else if (typeof def === "number") {
+      const n = Number(value);
+      if (!Number.isFinite(n)) {
+        console.error(`value for "${key}" must be a number; got "${value}"`);
+        process.exitCode = 2;
+        return;
+      }
+      coerced = n;
+    }
+    cfg.skills.inspector[key] = coerced;
+    writeConfig(cfg);
+    console.log(`skills.inspector.${key} = ${coerced}`);
+    return;
+  }
+
+  console.error(`unknown inspector subcommand: ${sub}`);
+  console.error("usage: apx skills inspector [status|enable|disable|set <key> <value>]");
+  process.exitCode = 2;
+}

package/src/interfaces/cli/index.js

@@ -100,7 +100,7 @@ import {
 import { cmdPluginsList, cmdPluginStatus } from "./commands/plugins.js";
 import { cmdDesktopStart, cmdDesktopStop, cmdDesktopStatus, cmdDesktopInstall, cmdDesktopUninstall } from "./commands/desktop.js";
 import { cmdVoiceSay, cmdVoiceListen, cmdVoiceProviders } from "./commands/voice.js";
-import { cmdSkillsAdd, cmdSkillsList, cmdSkillsStatus, cmdSkillsSync } from "./commands/skills.js";
+import { cmdSkillsAdd, cmdSkillsList, cmdSkillsStatus, cmdSkillsSync, cmdSkillsIndex, cmdSkillsInspect, cmdSkillsInspector } from "./commands/skills.js";
 import { cmdIdentity } from "./commands/identity.js";
 import { cmdCommandList, cmdCommandShow } from "./commands/command.js";
 import { cmdUpdate } from "./commands/update.js";
@@ -110,6 +110,7 @@ import { cmdModel } from "./commands/model.js";
 import { cmdPair, cmdPairWeb, cmdPairList, cmdPairRevoke } from "./commands/pair.js";
 import { checkForUpdate } from "#core/update-check.js";
 import { mascot } from "#core/mascot.js";
+import { apxHeader, apxBanner } from "./branding.js";
 import {
   cmdRoutineList,
   cmdRoutineGet,
@@ -1350,12 +1351,23 @@ const HELP_TOPICS = new Map(Object.entries({
   skills: topic({
     title: "apx skills",
     summary: "Install and inspect APX skill files for IDEs and agent tools.",
-    usage: ["apx skills [add] [targets] [--global]", "apx skills sync", "apx skills list", "apx skills status"],
+    usage: [
+      "apx skills [add] [targets] [--global]",
+      "apx skills sync",
+      "apx skills list",
+      "apx skills status",
+      "apx skills index [--reset] [--force]",
+      "apx skills inspect \"<prompt>\"",
+      "apx skills inspector [status|enable|disable|set <key> <value>]",
+    ],
     commands: [
       ["add [targets]", "Install APX skills into selected targets."],
       ["sync | refresh", "Re-install every bundled skill to every global skill dir (idempotent)."],
       ["list | ls", "List skills installed in this project's .apc/skills/."],
       ["status", "Show which bundled skills are present in each global dir."],
+      ["index", "Build/refresh the local RAG vector index used by the Skill Inspector."],
+      ["inspect", "Show which skills the Inspector would surface for a given prompt (debug)."],
+      ["inspector", "Toggle and tune the Skill Inspector (per-turn skill RAG middleware)."],
     ],
     examples: [
       "apx skills add claude-code cursor",
@@ -1403,6 +1415,40 @@ const HELP_TOPICS = new Map(Object.entries({
     usage: ["apx skills status"],
     examples: ["apx skills status"],
   }),
+  "skills index": topic({
+    title: "apx skills index",
+    summary:
+      "Build or refresh the local vector index that powers the Skill Inspector. Embeds each skill's condensed description with the configured embeddings provider (defaults to local: ollama → tf fallback). Idempotent: skills with unchanged file+description are kept. Use --force to re-embed everything; --reset to also delete the on-disk index first.",
+    usage: ["apx skills index [--reset] [--force]"],
+    options: [
+      ["--force", "Re-embed every skill, ignoring cached vectors."],
+      ["--reset", "Delete the index file before rebuilding."],
+    ],
+    examples: ["apx skills index", "apx skills index --force", "apx skills index --reset"],
+  }),
+  "skills inspect": topic({
+    title: "apx skills inspect",
+    summary:
+      "Dry-run the Skill Inspector against a prompt. Shows top similarity scores, which skill (if any) would be loaded inline, which would be hinted, and the actual contextNote that would be injected into the next turn's system prompt. The model is NOT called.",
+    usage: ["apx skills inspect \"<prompt text>\""],
+    examples: [
+      "apx skills inspect \"crear un video promocional\"",
+      "apx skills inspect \"profile the slow endpoint\"",
+    ],
+  }),
+  "skills inspector": topic({
+    title: "apx skills inspector",
+    summary:
+      "Toggle and tune the Skill Inspector (per-turn skill RAG). When ON: the static slug-dump in the system prompt is suppressed and a local RAG picks 0–N skills per turn — loading the body of high-confidence matches, hinting mid-confidence ones, injecting nothing below threshold. When OFF: legacy behaviour (full slug list + passive suggestion). Opt-in test feature.",
+    usage: ["apx skills inspector [status|enable|disable|set <key> <value>]"],
+    examples: [
+      "apx skills inspector enable",
+      "apx skills inspector disable",
+      "apx skills inspector status",
+      "apx skills inspector set load_threshold 0.5",
+      "apx skills inspector set max_loaded 2",
+    ],
+  }),
   plugins: topic({
     title: "apx plugins",
     summary: "Inspect loaded APX daemon plugins.",
@@ -2530,6 +2576,9 @@ async function dispatch(cmd, rest) {
         else if (sub === "list" || sub === "ls") await cmdSkillsList(a);
         else if (sub === "status") await cmdSkillsStatus();
         else if (sub === "sync" || sub === "refresh") await cmdSkillsSync(a);
+        else if (sub === "index") await cmdSkillsIndex(a);
+        else if (sub === "inspect") await cmdSkillsInspect(a);
+        else if (sub === "inspector") await cmdSkillsInspector(a);
         else die(`unknown skills subcommand: ${sub}`);
         break;
       }
@@ -2583,8 +2632,41 @@ async function dispatch(cmd, rest) {
 }
 
 const [topCmd, ...topRest] = argv;
+
+// ── CLI branding ────────────────────────────────────────────────────────────
+// Every command prints an "APX CLI · vX · <command>" mark to stderr (so stdout
+// pipes stay clean). Two exceptions:
+//   - SELF_BRANDED: commands that already render their own logo/mascot/status
+//     block — re-stamping them would double up.
+//   - BANNERED: branding-heavy moments that get the big ASCII wordmark instead
+//     of the compact line.
+// Suppress everything with APX_QUIET=1 / APX_NO_BANNER=1 (see branding.js).
+const SELF_BRANDED = new Set([
+  "status", "setup", "install", "daemon", "update", "upgrade", "help",
+]);
+const BANNERED = new Set(["init"]);
+
+function brandFor(cmd, rest) {
+  if (SELF_BRANDED.has(cmd)) return;
+  // Subtitle = the command path only (cmd + leading subcommand tokens), never
+  // free-form args. Stop at the first token that looks like an argument: a flag,
+  // something with spaces (a quoted prompt), or anything long. So
+  // `skills inspector status` shows fully, but `exec "long prompt…"` shows just
+  // `exec`.
+  const path = [cmd];
+  for (const tok of rest) {
+    if (!tok || tok.startsWith("-") || /\s/.test(tok) || tok.length > 24) break;
+    path.push(tok);
+    if (path.length >= 3) break;
+  }
+  const subtitle = path.join(" ");
+  if (BANNERED.has(cmd)) apxBanner(VERSION, subtitle);
+  else apxHeader(VERSION, subtitle);
+}
+
 (async () => {
   try {
+    brandFor(topCmd, topRest);
     await dispatch(topCmd, topRest);
     checkForUpdate(VERSION);
   } catch (err) {