agentwheel 0.16.4 → 0.16.5

package/README.md

@@ -54,13 +54,15 @@ install the companion skill, and show the right catalogue flow for your runtime.
 curl -fsSL https://raw.githubusercontent.com/NestDevLab/agentwheel/main/install.md
 ```
 
-**Companion skill**
+**Companion skills**
 
-The companion skill keeps Agentwheel commands and safety rules inside the runtime you are using:
+The management skill keeps Agentwheel commands and safety rules inside the runtime you are using.
+Install the discovery skill separately when you also want proactive, non-installing suggestions:
 
 ```bash
 agentwheel doctor --adapter codex --local
 agentwheel install github:NestDevLab/agentwheel --adapter codex --local --skill agentwheel
+agentwheel install github:NestDevLab/agentwheel --adapter codex --local --skill agentwheel-discovery
 ```
 
 > **Status: early (v0.12).** The public CLI vocabulary is package-manager style:
@@ -167,10 +169,10 @@ Use `--scope registry`, `--scope enriched`, or `--scope vercel` to restrict a qu
 `--scope all` combines every source, deduplicates equivalent artifacts, and reports every
 provenance plus the safe installation route.
 
-Search is deterministic and lexical. The companion skill adds semantic behavior at the agent
-layer: it can generate a small set of related queries, merge and rerank the JSON results against
-the original request, and suggest at most three artifacts. Search never installs or changes
-configuration by itself.
+The optional `agentwheel-discovery` skill notices capability gaps during normal work, uses the
+verified semantic catalogue index, reranks results against the original request, and suggests at
+most three artifacts. It can read one instruction skill with `agentwheel try` before installation.
+Search and trial never install or change configuration by themselves.
 
 Registry maintenance remains available through `agentwheel registry update` and
 `agentwheel registry list`. Registry short names continue to resolve during add/install.
@@ -243,10 +245,14 @@ stderr warning when an update is available. Disable it with `--no-update-check`
 
 ## Companion Skill Doctor
 
-Agentwheel ships its own companion skill in `github:NestDevLab/agentwheel` as `skills/agentwheel`.
-Installing it is optional, but strongly recommended if you want to get the most out of Agentwheel:
-the skill keeps Agentwheel commands, setup guidance, safety rules, and operational patterns available
-inside your agent runtime instead of forcing you to leave the flow and look them up elsewhere.
+Agentwheel ships two optional companion skills in `github:NestDevLab/agentwheel`:
+
+- `skills/agentwheel` provides explicit search, setup guidance, safety rules, and artifact management.
+- `skills/agentwheel-discovery` proactively notices capability gaps, suggests up to three matches,
+  and offers a read-only skill trial before installation.
+
+Install only the management skill when proactive recommendations are unwanted. Install both when
+you want Agentwheel to surface reusable capabilities during normal work.
 
 The CLI never installs the companion skill silently into runtime folders. Use `doctor` to check the
 selected runtime and print the exact preview and install commands when a skill is missing:
@@ -255,6 +261,8 @@ selected runtime and print the exact preview and install commands when a skill i
 agentwheel doctor --adapter copilot --user
 agentwheel install github:NestDevLab/agentwheel --adapter copilot --user --skill agentwheel --dry-run
 agentwheel install github:NestDevLab/agentwheel --adapter copilot --user --skill agentwheel
+agentwheel install github:NestDevLab/agentwheel --adapter copilot --user --skill agentwheel-discovery --dry-run
+agentwheel install github:NestDevLab/agentwheel --adapter copilot --user --skill agentwheel-discovery
 ```
 
 `doctor` also accepts explicit skill checks and machine-readable output. In Syncwheel-managed

package/dist/index.js

@@ -9,11 +9,11 @@ import {
 } from "./chunk-PKAPR55N.js";
 
 // src/cli/index.ts
-import { createHash as createHash12 } from "crypto";
+import { createHash as createHash14 } from "crypto";
 import { existsSync } from "fs";
 import { mkdir as mkdir23, rm as rm12, writeFile as writeFile22 } from "fs/promises";
-import { homedir as homedir11 } from "os";
-import { dirname as dirname32, join as join46, resolve as resolve22 } from "path";
+import { homedir as homedir12 } from "os";
+import { dirname as dirname32, join as join48, resolve as resolve22 } from "path";
 import { fileURLToPath as fileURLToPath3 } from "url";
 import { Command } from "commander";
 
@@ -1469,15 +1469,15 @@ function appendMcpServers(content, servers) {
 `;
 }
 function formatMcpServer(name, server) {
-  const env = isRecord2(server.env) ? server.env : void 0;
+  const env2 = isRecord2(server.env) ? server.env : void 0;
   const lines = [`[mcp_servers.${quoteTomlKey(name)}]`];
   for (const [key, value] of Object.entries(server)) {
     if (key === "env" || value === void 0) continue;
     lines.push(`${quoteTomlKey(key)} = ${formatTomlValue(value)}`);
   }
-  if (env && Object.keys(env).length > 0) {
+  if (env2 && Object.keys(env2).length > 0) {
     lines.push("", `[mcp_servers.${quoteTomlKey(name)}.env]`);
-    for (const [key, value] of Object.entries(env)) {
+    for (const [key, value] of Object.entries(env2)) {
       lines.push(`${quoteTomlKey(key)} = ${formatTomlValue(value)}`);
     }
   }
@@ -10581,9 +10581,9 @@ async function maybeCheckForUpdate(options) {
   }
 }
 function isDisabled(options) {
-  const env = options.env ?? process.env;
-  if (env.AGENTWHEEL_NO_UPDATE_CHECK === "1" || env.AGENTWHEEL_NO_UPDATE_CHECK === "true") return true;
-  if (env.CI) return true;
+  const env2 = options.env ?? process.env;
+  if (env2.AGENTWHEEL_NO_UPDATE_CHECK === "1" || env2.AGENTWHEEL_NO_UPDATE_CHECK === "true") return true;
+  if (env2.CI) return true;
   if (options.argv?.includes("--no-update-check")) return true;
   if (options.argv?.includes("--offline")) return true;
   const isTTY = options.isTTY ?? process.stderr.isTTY === true;
@@ -11228,7 +11228,7 @@ async function invokeMemberStatus(member, parentWorkspace, chain, options, cliEn
   const args = ["--no-update-check", "status", "--profile", member.profile, "--json"];
   if (options.refresh) args.push("--refresh");
   if (options.offline) args.push("--offline");
-  const env = { ...process.env, AGENTWHEEL_COMPOSITE_CHAIN: JSON.stringify(chain) };
+  const env2 = { ...process.env, AGENTWHEEL_COMPOSITE_CHAIN: JSON.stringify(chain) };
   let stdout = "";
   let stderr = "";
   try {
@@ -11236,7 +11236,7 @@ async function invokeMemberStatus(member, parentWorkspace, chain, options, cliEn
       const workspace = resolve21(parentWorkspace, member.workspace);
       const result = await execFileAsync6(process.execPath, [cliEntry, ...args], {
         cwd: workspace,
-        env,
+        env: env2,
         maxBuffer: 20 * 1024 * 1024
       });
       stdout = result.stdout;
@@ -11251,7 +11251,7 @@ async function invokeMemberStatus(member, parentWorkspace, chain, options, cliEn
         ...args.map(shellQuote2)
       ];
       const result = await execFileAsync6("ssh", [...sshArgs, remoteArgs.join(" ")], {
-        env,
+        env: env2,
         maxBuffer: 20 * 1024 * 1024
       });
       stdout = result.stdout;
@@ -11272,7 +11272,7 @@ async function invokeMemberStatus(member, parentWorkspace, chain, options, cliEn
   }
 }
 async function runMemberAgentwheel(member, parentWorkspace, args, chain) {
-  const env = { ...process.env, AGENTWHEEL_COMPOSITE_CHAIN: JSON.stringify(chain) };
+  const env2 = { ...process.env, AGENTWHEEL_COMPOSITE_CHAIN: JSON.stringify(chain) };
   try {
     if (member.transport === "local") {
       const result2 = await execFileAsync6(
@@ -11280,7 +11280,7 @@ async function runMemberAgentwheel(member, parentWorkspace, args, chain) {
         [process.argv[1], "--no-update-check", ...args],
         {
           cwd: resolve21(parentWorkspace, member.workspace),
-          env,
+          env: env2,
           maxBuffer: 20 * 1024 * 1024
         }
       );
@@ -11295,7 +11295,7 @@ async function runMemberAgentwheel(member, parentWorkspace, args, chain) {
       ...args.map(shellQuote2)
     ];
     const result = await execFileAsync6("ssh", [...sshArguments(member), remoteArgs.join(" ")], {
-      env,
+      env: env2,
       maxBuffer: 20 * 1024 * 1024
     });
     return { stdout: result.stdout, stderr: result.stderr };
@@ -11521,13 +11521,21 @@ var catalogueCacheSchema = z13.object({
   fetchedAt: z13.string().datetime(),
   sources: z13.tuple([z13.string().url(), z13.string().url()]),
   enriched: enrichedCatalogueSchema,
-  vercel: vercelCatalogueSchema
+  vercel: vercelCatalogueSchema,
+  sourceDigests: z13.object({
+    enriched: z13.string().regex(/^[a-f0-9]{64}$/),
+    vercel: z13.string().regex(/^[a-f0-9]{64}$/)
+  }).optional()
 });
 var catalogueCacheEnvelopeSchema = z13.object({
   version: z13.literal(1),
   fetchedAt: z13.string().datetime(),
   sources: z13.tuple([z13.string().url(), z13.string().url()]),
   contentHash: z13.string().regex(/^[a-f0-9]{64}$/).optional(),
+  sourceDigests: z13.object({
+    enriched: z13.string().regex(/^[a-f0-9]{64}$/),
+    vercel: z13.string().regex(/^[a-f0-9]{64}$/)
+  }).optional(),
   enriched: z13.unknown(),
   vercel: z13.unknown()
 });
@@ -11545,13 +11553,15 @@ var searchResultSchema = z13.object({
   installability: installabilitySchema,
   provenances: z13.array(catalogueProvenanceSchema).min(1),
   score: z13.number().int().nonnegative(),
-  matchedFields: z13.array(z13.string())
+  matchedFields: z13.array(z13.string()),
+  semanticScore: z13.number().finite().optional()
 });
 var searchResponseSchema = z13.object({
   schemaVersion: z13.literal(1),
   query: z13.string(),
   scope: searchScopeSchema,
   fromCache: z13.boolean(),
+  searchMode: z13.enum(["lexical", "semantic"]).optional(),
   results: z13.array(searchResultSchema)
 });
 
@@ -11594,24 +11604,35 @@ var CatalogueClient = class {
       return this.fromCache(usableCache, false);
     }
     try {
-      const [enriched, vercel] = await Promise.all([
+      const [enrichedPayload, vercelPayload] = await Promise.all([
         this.fetchJson(this.sources[0], enrichedCatalogueSchema),
         this.fetchJson(this.sources[1], vercelCatalogueSchema)
       ]);
+      const { value: enriched, digest: enrichedDigest } = enrichedPayload;
+      const { value: vercel, digest: vercelDigest } = vercelPayload;
       const fetchedAt = this.now().toISOString();
       const cache = {
         version: 1,
         fetchedAt,
         sources: this.sources,
         enriched,
-        vercel
+        vercel,
+        sourceDigests: { enriched: enrichedDigest, vercel: vercelDigest }
       };
       const cacheFile = {
         ...cache,
         contentHash: catalogueContentHash(enriched, vercel)
       };
       await writeJsonAtomic(this.cachePath, cacheFile);
-      return { enriched, vercel, sources: this.sources, fetchedAt, fromCache: false, stale: false };
+      return {
+        enriched,
+        vercel,
+        sources: this.sources,
+        fetchedAt,
+        fromCache: false,
+        stale: false,
+        sourceDigests: cache.sourceDigests
+      };
     } catch (error) {
       if (!usableCache) throw error;
       const reason = error instanceof Error ? error.message : String(error);
@@ -11652,7 +11673,8 @@ var CatalogueClient = class {
       sources: cache.sources,
       fetchedAt: cache.fetchedAt,
       fromCache: true,
-      stale
+      stale,
+      sourceDigests: cache.sourceDigests
     };
   }
   async fetchJson(source, schema) {
@@ -11662,8 +11684,8 @@ var CatalogueClient = class {
     }
     const declaredLength = response.headers.get("content-length");
     if (declaredLength !== null) {
-      const bytes = Number(declaredLength);
-      if (Number.isFinite(bytes) && bytes > MAX_CATALOGUE_PAYLOAD_BYTES) {
+      const bytes2 = Number(declaredLength);
+      if (Number.isFinite(bytes2) && bytes2 > MAX_CATALOGUE_PAYLOAD_BYTES) {
         throw new Error(`Catalogue payload exceeds 32 MiB limit: ${source}`);
       }
     }
@@ -11671,13 +11693,17 @@ var CatalogueClient = class {
     if (payload.byteLength > MAX_CATALOGUE_PAYLOAD_BYTES) {
       throw new Error(`Catalogue payload exceeds 32 MiB limit: ${source}`);
     }
+    const bytes = new Uint8Array(payload);
     let value;
     try {
       value = JSON.parse(new TextDecoder().decode(payload));
     } catch {
       throw new Error(`Catalogue source returned invalid JSON: ${source}`);
     }
-    return schema.parse(value);
+    return {
+      value: schema.parse(value),
+      digest: createHash11("sha256").update(bytes).digest("hex")
+    };
   }
 };
 function defaultCatalogueCachePath() {
@@ -12048,6 +12074,235 @@ function includesToken(normalizedText, token) {
   return normalizedText === token || normalizedText.startsWith(`${token} `) || normalizedText.endsWith(` ${token}`) || normalizedText.includes(` ${token} `);
 }
 
+// src/semantic/index.ts
+import { createHash as createHash12 } from "crypto";
+import { homedir as homedir11 } from "os";
+import { join as join46 } from "path";
+import { env, pipeline } from "@huggingface/transformers";
+var DEFAULT_SEMANTIC_INDEX_URL = "https://raw.githubusercontent.com/NestDevLab/agentwheel-registry/main/catalogue-semantic-index/gte-v1/";
+var CONTRACT = {
+  schemaVersion: 1,
+  textSchemaVersion: 1,
+  model: {
+    id: "Xenova/gte-small",
+    revision: "5927d1727bb12db490052a1b33265ad78058de08",
+    dimensions: 384,
+    dtype: "q8",
+    pooling: "mean",
+    normalize: true,
+    queryPrefix: "",
+    documentPrefix: ""
+  },
+  vectorFormat: "signed-int8-per-vector-scaled",
+  normFormat: "float32-little-endian"
+};
+var SemanticSearchClient = class {
+  constructor(options = {}) {
+    this.options = options;
+    this.fetchImpl = options.fetch ?? fetch;
+    this.indexUrl = ensureTrailingSlash(options.indexUrl ?? DEFAULT_SEMANTIC_INDEX_URL);
+  }
+  options;
+  fetchImpl;
+  indexUrl;
+  async search(request) {
+    if (!request.catalogueDigests) {
+      throw new Error("Semantic search needs a catalogue cache with source checksums. Run again online with --refresh.");
+    }
+    const metadata = await this.fetchMetadata();
+    validateMetadata(metadata, request.catalogueDigests);
+    const [ids, vectors, norms] = await Promise.all([
+      this.fetchIds(metadata.files.ids),
+      this.fetchBinary(metadata.files.vectors),
+      this.fetchBinary(metadata.files.norms)
+    ]);
+    const decodedNorms = decodeFloat32LittleEndian(norms);
+    validateIndexFiles(metadata, ids, vectors, decodedNorms);
+    const query = await (this.options.embed ?? embedQuery)(request.query);
+    if (query.length !== metadata.dimensions) {
+      throw new Error(`Semantic model returned ${query.length} dimensions; expected ${metadata.dimensions}.`);
+    }
+    const ranked = searchInt8Index(vectors, decodedNorms, metadata.dimensions, query, Math.max(100, request.limit * 10));
+    const entries = new Map(request.entries.map((entry) => [entry.id, entry]));
+    const results = [];
+    for (const candidate of ranked) {
+      const entry = entries.get(ids[candidate.row]);
+      if (!entry || !request.includeArchived && entry.archived) continue;
+      if (request.type && entry.type !== request.type) continue;
+      if (request.ecosystem && entry.ecosystem !== request.ecosystem) continue;
+      results.push(toSearchResult(entry, candidate.score, results.length));
+      if (results.length === request.limit) break;
+    }
+    if (results.length === 0) this.options.warn?.("Semantic index had no candidates matching the selected filters.");
+    return results;
+  }
+  async fetchMetadata() {
+    const response = await this.fetchImpl(new URL("metadata.json", this.indexUrl));
+    if (!response.ok) throw new Error(`Semantic index metadata failed (${response.status}).`);
+    let metadata;
+    try {
+      metadata = JSON.parse(await response.text());
+    } catch {
+      throw new Error("Semantic index metadata is not valid JSON.");
+    }
+    return metadata;
+  }
+  async fetchIds(descriptor) {
+    const bytes = await this.fetchBinary(descriptor);
+    let ids;
+    try {
+      ids = JSON.parse(new TextDecoder().decode(bytes));
+    } catch {
+      throw new Error("Semantic index IDs are not valid JSON.");
+    }
+    if (!Array.isArray(ids) || ids.some((id) => typeof id !== "string" || !id)) {
+      throw new Error("Semantic index IDs are invalid.");
+    }
+    return ids;
+  }
+  async fetchBinary(descriptor) {
+    const response = await this.fetchImpl(new URL(descriptor.path, this.indexUrl));
+    if (!response.ok) throw new Error(`Semantic index file failed (${response.status}): ${descriptor.path}`);
+    const bytes = new Uint8Array(await response.arrayBuffer());
+    if (bytes.byteLength !== descriptor.bytes) throw new Error(`Semantic index file size does not match: ${descriptor.path}`);
+    const digest = createHash12("sha256").update(bytes).digest("hex");
+    if (digest !== descriptor.sha256) throw new Error(`Semantic index checksum does not match: ${descriptor.path}`);
+    return bytes;
+  }
+};
+async function embedQuery(query) {
+  env.cacheDir = join46(homedir11(), ".agentwheel", "semantic-models");
+  const extractor = await pipeline("feature-extraction", CONTRACT.model.id, {
+    revision: CONTRACT.model.revision,
+    dtype: CONTRACT.model.dtype,
+    session_options: { intraOpNumThreads: 1, interOpNumThreads: 1 }
+  });
+  const output = await extractor(query, { pooling: CONTRACT.model.pooling, normalize: CONTRACT.model.normalize });
+  return Float32Array.from(output.data);
+}
+function validateMetadata(metadata, digests) {
+  if (metadata.schemaVersion !== CONTRACT.schemaVersion || metadata.textSchemaVersion !== CONTRACT.textSchemaVersion) {
+    throw new Error("Unsupported semantic index schema.");
+  }
+  if (!Number.isInteger(metadata.count) || metadata.count < 1 || metadata.dimensions !== CONTRACT.model.dimensions) {
+    throw new Error("Semantic index dimensions or count are invalid.");
+  }
+  if (metadata.vectorFormat !== CONTRACT.vectorFormat || metadata.normFormat !== CONTRACT.normFormat) {
+    throw new Error("Semantic index binary format is unsupported.");
+  }
+  for (const [field, value] of Object.entries(CONTRACT.model)) {
+    if (metadata.model?.[field] !== value) throw new Error(`Semantic model ${field} does not match.`);
+  }
+  for (const source of ["enriched", "vercel"]) {
+    if (metadata.catalogue?.[source]?.sha256 !== digests[source]) {
+      throw new Error(`Semantic index catalogue checksum does not match ${source}.`);
+    }
+  }
+  for (const key of ["ids", "vectors", "norms"]) {
+    const descriptor = metadata.files?.[key];
+    if (!descriptor || typeof descriptor.path !== "string" || !Number.isInteger(descriptor.bytes) || descriptor.bytes < 1 || !/^[a-f0-9]{64}$/u.test(descriptor.sha256)) {
+      throw new Error(`Semantic index ${key} descriptor is invalid.`);
+    }
+  }
+}
+function validateIndexFiles(metadata, ids, vectors, norms) {
+  if (ids.length !== metadata.count || vectors.length !== metadata.count * metadata.dimensions || norms.length !== metadata.count) {
+    throw new Error("Semantic index files do not match metadata.");
+  }
+}
+function decodeFloat32LittleEndian(bytes) {
+  if (bytes.byteLength % Float32Array.BYTES_PER_ELEMENT !== 0) throw new Error("Semantic norm file has an invalid length.");
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  const result = new Float32Array(bytes.byteLength / Float32Array.BYTES_PER_ELEMENT);
+  for (let index = 0; index < result.length; index += 1) result[index] = view.getFloat32(index * 4, true);
+  return result;
+}
+function searchInt8Index(vectors, norms, dimensions, query, limit) {
+  const results = [];
+  const signed = new Int8Array(vectors.buffer, vectors.byteOffset, vectors.byteLength);
+  for (let row = 0; row < norms.length; row += 1) {
+    let dot = 0;
+    const offset = row * dimensions;
+    for (let column = 0; column < dimensions; column += 1) dot += signed[offset + column] * query[column];
+    const candidate = { row, score: norms[row] > 0 ? dot / norms[row] : 0 };
+    const index = results.findIndex((item) => candidate.score > item.score);
+    results.splice(index === -1 ? results.length : index, 0, candidate);
+    if (results.length > limit) results.pop();
+  }
+  return results;
+}
+function toSearchResult(entry, semanticScore, rank) {
+  return {
+    id: entry.id,
+    name: entry.name,
+    description: entry.description,
+    type: entry.type,
+    ...entry.ecosystem ? { ecosystem: entry.ecosystem } : {},
+    tags: entry.tags,
+    provides: entry.provides,
+    ...entry.source ? { source: entry.source } : {},
+    ...entry.repoUrl ? { repoUrl: entry.repoUrl } : {},
+    ...entry.installCommand ? { installCommand: entry.installCommand } : {},
+    installability: entry.installability,
+    provenances: entry.provenances,
+    score: 1e5 - rank,
+    matchedFields: ["semantic"],
+    semanticScore: Number(semanticScore.toFixed(6))
+  };
+}
+function ensureTrailingSlash(value) {
+  return value.endsWith("/") ? value : `${value}/`;
+}
+
+// src/trial/skill.ts
+import { createHash as createHash13 } from "crypto";
+import { readFile as readFile34, stat as stat12 } from "fs/promises";
+import { join as join47 } from "path";
+import { parse as parseYaml2 } from "yaml";
+var MAX_TRIAL_SKILL_BYTES = 512 * 1024;
+async function createSkillTrial(driver, resolved, selectors) {
+  const scan = await driver.scan(resolved);
+  if (!scan.ok) throw new Error("Skill trial blocked by source scan findings.");
+  const selected = filterArtifactsBySelection(await driver.list(resolved), selectors);
+  const skills = selected.filter((artifact2) => artifact2.type === "skills");
+  if (skills.length !== 1) {
+    throw new Error("Skill trial requires exactly one selected skill. Use --skill <name> or --select skills/<name>.");
+  }
+  const artifact = skills[0];
+  const path = artifact.kind === "dir" ? join47(artifact.sourcePath, "SKILL.md") : artifact.sourcePath;
+  const info = await stat12(path);
+  if (info.size > MAX_TRIAL_SKILL_BYTES) {
+    throw new Error(`Skill trial exceeds the ${MAX_TRIAL_SKILL_BYTES / 1024} KiB content limit.`);
+  }
+  const content = await readFile34(path, "utf8");
+  const frontmatter = readSkillFrontmatter(content, artifact);
+  return {
+    schemaVersion: 1,
+    mode: "read-only",
+    source: resolved.source,
+    ...resolved.resolvedCommit ? { resolvedCommit: resolved.resolvedCommit } : {},
+    findings: scan.findings,
+    skill: {
+      name: artifact.name,
+      relativePath: artifact.relativePath,
+      sha256: createHash13("sha256").update(content).digest("hex"),
+      frontmatter,
+      content
+    }
+  };
+}
+function readSkillFrontmatter(content, artifact) {
+  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);
+  if (!match) throw new Error(`Skill trial requires YAML frontmatter: ${artifact.relativePath}`);
+  const parsed = parseYaml2(match[1]);
+  if (!parsed || typeof parsed !== "object") throw new Error(`Skill trial frontmatter is invalid: ${artifact.relativePath}`);
+  const value = parsed;
+  if (typeof value.name !== "string" || !value.name.trim() || typeof value.description !== "string" || !value.description.trim()) {
+    throw new Error(`Skill trial frontmatter needs name and description: ${artifact.relativePath}`);
+  }
+  return { name: value.name, description: value.description };
+}
+
 // src/cli/index.ts
 var CLI_VERSION = resolveCliVersion();
 var COMPANION_SKILL_SOURCE = "github:NestDevLab/agentwheel";
@@ -12091,13 +12346,13 @@ program.command("list").description("list artifacts exposed by a package source"
   const resolvedInput = await resolvePackageSource(source, targetRoot);
   const selectedArtifacts = selectedArtifactsFromOptionsOrRegistry(options, resolvedInput.registryEntry);
   const driver = getSourceDriver(options.driver ?? inferSourceDriverName(resolvedInput.source));
-  const resolved = await driver.export(await driver.translate(await driver.fetch(await driver.resolve(resolvedInput.source, { cacheRoot: join46(targetRoot, ".agentwheel", "cache") }))));
+  const resolved = await driver.export(await driver.translate(await driver.fetch(await driver.resolve(resolvedInput.source, { cacheRoot: join48(targetRoot, ".agentwheel", "cache") }))));
   const artifacts = filterArtifactsBySelection(await driver.list(resolved), selectedArtifacts);
   for (const artifact of artifacts) {
     console.log(`${artifact.type}	${artifact.name}	${artifact.relativePath}`);
   }
 });
-program.command("search").description("search registry and public catalogue artifacts").argument("<query>", "search query").option("--json", "print the versioned search response as JSON", false).option("--scope <scope>", "search scope: all, registry, enriched, or vercel", "all").option("--type <type>", "artifact type: package, skill, plugin, mcp, or adapter").option("--ecosystem <ecosystem>", "ecosystem: official, openpack, mcp-registry, clawhub, skillkit, or vercel").option("--limit <n>", "maximum number of results (1-100)", "20").option("--include-archived", "include archived catalogue entries", false).option("--refresh", "refresh registry and catalogue caches", false).option("--offline", "use compatible local caches without network access", false).option("-t, --target-root <path>", "workspace root", process.cwd()).action(async (query, options) => {
+program.command("search").description("search registry and public catalogue artifacts").argument("<query>", "search query").option("--json", "print the versioned search response as JSON", false).option("--scope <scope>", "search scope: all, registry, enriched, or vercel", "all").option("--type <type>", "artifact type: package, skill, plugin, mcp, or adapter").option("--ecosystem <ecosystem>", "ecosystem: official, openpack, mcp-registry, clawhub, skillkit, or vercel").option("--limit <n>", "maximum number of results (1-100)", "20").option("--include-archived", "include archived catalogue entries", false).option("--refresh", "refresh registry and catalogue caches", false).option("--offline", "use compatible local caches without network access", false).option("--semantic", "rank published catalogue entries with the verified semantic index", false).option("-t, --target-root <path>", "workspace root", process.cwd()).action(async (query, options) => {
   const trimmedQuery = query.trim();
   if (!trimmedQuery) {
     throw new Error("Search query must not be empty.");
@@ -12109,17 +12364,28 @@ program.command("search").description("search registry and public catalogue arti
   if (options.refresh && options.offline) {
     throw new Error("--refresh cannot be used with --offline.");
   }
+  if (options.semantic && scope === "registry") {
+    throw new Error("--semantic requires a catalogue scope: all, enriched, or vercel.");
+  }
   const warning = (message) => console.error(message);
   const targetRoot = normalizeTargetRoot(options.targetRoot);
   const registryRequest = scope === "all" || scope === "registry" ? new RegistryClient({ workspaceRoot: targetRoot, offline: options.offline, warn: warning }).getIndex({ refresh: options.refresh }) : void 0;
-  const catalogueRequest = scope === "all" || scope === "enriched" || scope === "vercel" ? new CatalogueClient({ offline: options.offline, warn: warning }).getIndex({ refresh: options.refresh }) : void 0;
+  const catalogueRequest = scope === "all" || scope === "enriched" || scope === "vercel" ? new CatalogueClient({ offline: options.offline, warn: warning }).getIndex({ refresh: options.refresh || options.semantic && !options.offline }) : void 0;
   const [registryIndex, catalogueIndex] = await Promise.all([registryRequest, catalogueRequest]);
   const entries = buildSearchEntries({
     registry: registryIndex?.entries,
     enriched: scope === "all" || scope === "enriched" ? catalogueIndex?.enriched : void 0,
     vercel: scope === "all" || scope === "vercel" ? catalogueIndex?.vercel : void 0
   });
-  const results = searchEntries(entries, trimmedQuery, {
+  const results = options.semantic ? await new SemanticSearchClient({ warn: warning }).search({
+    query: trimmedQuery,
+    entries,
+    catalogueDigests: catalogueIndex?.sourceDigests,
+    type,
+    ecosystem,
+    limit,
+    includeArchived: options.includeArchived
+  }) : searchEntries(entries, trimmedQuery, {
     type,
     ecosystem,
     limit,
@@ -12131,7 +12397,8 @@ program.command("search").description("search registry and public catalogue arti
     query: trimmedQuery,
     scope,
     fromCache: loadedIndexes.every((index) => index.fromCache),
-    results
+    results,
+    ...options.semantic ? { searchMode: "semantic" } : {}
   };
   if (options.json) {
     console.log(JSON.stringify(response, null, 2));
@@ -12139,11 +12406,30 @@ program.command("search").description("search registry and public catalogue arti
   }
   printSearchResults(trimmedQuery, results);
 });
+program.command("try").description("read and validate one skill for the current task without installing it").argument("<source>", "package source").option("--driver <driver>", "source driver").option("--json", "print the read-only skill trial as JSON", false).option("-t, --target-root <path>", "workspace root", process.cwd()).option("--select <type/name>", "select exactly one skill artifact", collectSelectOption, []).option("--skill <name>", "select exactly one skill by name", collectSkillOption, []).action(async (source, options) => {
+  const targetRoot = normalizeTargetRoot(options.targetRoot);
+  const resolvedInput = await resolvePackageSource(source, targetRoot);
+  const driver = getSourceDriver(options.driver ?? inferSourceDriverName(resolvedInput.source));
+  const resolved = await driver.export(await driver.translate(await driver.fetch(await driver.resolve(resolvedInput.source, {
+    cacheRoot: join48(targetRoot, ".agentwheel", "cache")
+  }))));
+  const trial = await createSkillTrial(driver, resolved, selectedArtifactsFromOptionsOrRegistry(options, resolvedInput.registryEntry));
+  if (options.json) {
+    console.log(JSON.stringify(trial, null, 2));
+    return;
+  }
+  console.log(`Read-only skill trial: ${trial.skill.name}`);
+  console.log(`Source: ${trial.source}`);
+  console.log(`Description: ${trial.skill.frontmatter.description}`);
+  console.log("No configuration or runtime files were changed.");
+  console.log("\n--- SKILL.md ---\n");
+  console.log(trial.skill.content);
+});
 program.command("scan").description("scan a package source for validation findings").argument("<source>", "package source").option("--driver <driver>", "source driver").option("-t, --target-root <path>", "workspace root", process.cwd()).action(async (source, options) => {
   const targetRoot = normalizeTargetRoot(options.targetRoot);
   const resolvedInput = await resolvePackageSource(source, targetRoot);
   const driver = getSourceDriver(options.driver ?? inferSourceDriverName(resolvedInput.source));
-  const resolved = await driver.export(await driver.translate(await driver.fetch(await driver.resolve(resolvedInput.source, { cacheRoot: join46(targetRoot, ".agentwheel", "cache") }))));
+  const resolved = await driver.export(await driver.translate(await driver.fetch(await driver.resolve(resolvedInput.source, { cacheRoot: join48(targetRoot, ".agentwheel", "cache") }))));
   const result = await driver.scan(resolved);
   if (result.findings.length === 0) {
     console.log("Scan ok: no findings");
@@ -12411,7 +12697,7 @@ journalCommand.command("list").description("show pending apply journals for reso
     if (!journal) continue;
     pending += 1;
     console.log(`PENDING ${state.adapter.name}/${state.installationType} at ${state.installRoot}`);
-    console.log(`  journal: ${join46(state.installRoot, ".agentwheel", `${state.state.stateKey}.apply-journal.json`)}`);
+    console.log(`  journal: ${join48(state.installRoot, ".agentwheel", `${state.state.stateKey}.apply-journal.json`)}`);
     console.log(`  stateKey: ${state.state.stateKey}`);
     console.log(`  createdAt: ${journal.createdAt}`);
     console.log(`  updatedAt: ${journal.updatedAt}`);
@@ -12714,7 +13000,7 @@ async function packageEntryFromSource(source, targetRoot, options) {
   const bundle = await stageSource(driver, resolvedSource, {
     workspaceRoot: targetRoot,
     adapter,
-    cacheRoot: join46(targetRoot, ".agentwheel", "cache"),
+    cacheRoot: join48(targetRoot, ".agentwheel", "cache"),
     mode: options.mode,
     ref: initialVersion?.ref,
     frozenLock: lockMode,
@@ -13108,7 +13394,7 @@ function scopeUpdatePlanToDependencies(result, selectors, previousLock, manifest
     selectedPreviousNodeIds,
     selectedRootIds
   );
-  const graphLockDigest = createHash12("sha256").update(canonicalGraphLockJson(graphLock)).digest("hex");
+  const graphLockDigest = createHash14("sha256").update(canonicalGraphLockJson(graphLock)).digest("hex");
   return {
     ...result,
     bundle: { ...result.bundle, graphLock },
@@ -13276,7 +13562,7 @@ function scopeUpdatePlanToRoot(result, rootId, previousLock, manifest) {
     selectedPreviousNodeIds,
     /* @__PURE__ */ new Set([rootId])
   );
-  const graphLockDigest = createHash12("sha256").update(canonicalGraphLockJson(graphLock)).digest("hex");
+  const graphLockDigest = createHash14("sha256").update(canonicalGraphLockJson(graphLock)).digest("hex");
   return {
     ...scoped,
     bundle: { ...scoped.bundle, graphLock },
@@ -13348,7 +13634,7 @@ function keepManifestEntryOperation(entry, targetRoot, scopeDescription, operati
     artifactType: entry.artifactType,
     artifactName: entry.artifactName,
     kind: entry.kind,
-    destPath: operation?.destPath ?? join46(targetRoot, entry.path),
+    destPath: operation?.destPath ?? join48(targetRoot, entry.path),
     relativeDestPath: entry.path,
     desiredHash: entry.sourceHash,
     currentHash: operation?.currentHash ?? entry.hash,
@@ -13933,12 +14219,12 @@ async function printDoctor(target, options) {
   const requestedSkills = doctorSkillRequests(target, options);
   const skills = [];
   for (const request of requestedSkills) {
-    const skillPath = join46(state.installRoot, targetMapping.dest, request.name);
+    const skillPath = join48(state.installRoot, targetMapping.dest, request.name);
     const exists = await pathExists(skillPath);
     const manifestEntry = manifest?.entries.find((entry) => {
       if (entry.artifactType !== "skills") return false;
       const legacyInstallName = "installName" in entry && typeof entry.installName === "string" ? entry.installName : void 0;
-      return entry.artifactName === request.name || legacyInstallName === request.name || entry.path === join46(targetMapping.dest, request.name);
+      return entry.artifactName === request.name || legacyInstallName === request.name || entry.path === join48(targetMapping.dest, request.name);
     });
     const status = manifestEntry ? "managed" : exists ? "present-unmanaged" : "missing";
     skills.push({
@@ -14018,7 +14304,7 @@ function doctorSkillLabel(name) {
   return `${name} skill`;
 }
 function isSyncwheelWorkspace(targetRoot) {
-  return existsSync(join46(targetRoot, ".syncwheel", "manifest.json"));
+  return existsSync(join48(targetRoot, ".syncwheel", "manifest.json"));
 }
 function skillInstallCommand(adapter, installationType, options, skill, behavior = {}) {
   const args = [
@@ -14086,7 +14372,7 @@ function normalizeRuntimeScopeOptions(options, behavior = {}) {
   }
   const canDefaultTargetRoot = !options.agent && !options.all && !options.allDetected && !options.profile;
   if (!targetRoot && canDefaultTargetRoot && (options.user || installationType === "user" || behavior.defaultUser)) {
-    targetRoot = homedir11();
+    targetRoot = homedir12();
   }
   if (!installationType && behavior.defaultUser) {
     installationType = "user";
@@ -14106,12 +14392,12 @@ function looksLikeSourceSpecifier(value) {
   return value.includes(":") || value.startsWith("/") || value.startsWith("./") || value.startsWith("../") || value === "~" || value.startsWith("~/");
 }
 function normalizeCliPath(value) {
-  if (value === "~") return homedir11();
-  if (value.startsWith("~/")) return resolve22(homedir11(), value.slice(2));
+  if (value === "~") return homedir12();
+  if (value.startsWith("~/")) return resolve22(homedir12(), value.slice(2));
   return resolve22(value);
 }
 function isHomePath(path) {
-  return resolve22(path) === resolve22(homedir11());
+  return resolve22(path) === resolve22(homedir12());
 }
 function adapterListFromOption(adapter) {
   if (!adapter) return [];
@@ -14166,10 +14452,10 @@ function filterUninstallPlanBySelection(plan, selected) {
   };
 }
 async function initPackage(root) {
-  await mkdir23(join46(root, "instructions"), { recursive: true });
-  await mkdir23(join46(root, "rules"), { recursive: true });
-  await mkdir23(join46(root, "skills"), { recursive: true });
-  const manifestPath = join46(root, "openpack.json");
+  await mkdir23(join48(root, "instructions"), { recursive: true });
+  await mkdir23(join48(root, "rules"), { recursive: true });
+  await mkdir23(join48(root, "skills"), { recursive: true });
+  const manifestPath = join48(root, "openpack.json");
   const manifest = {
     schemaVersion: 2,
     name: "example/agentwheel-package",
@@ -14182,7 +14468,7 @@ async function initPackage(root) {
   };
   await writeFile22(manifestPath, `${JSON.stringify(manifest, null, 2)}
 `, "utf8");
-  await writeFile22(join46(root, "instructions", "AGENTS.md"), "# Agent Instructions\n", "utf8");
+  await writeFile22(join48(root, "instructions", "AGENTS.md"), "# Agent Instructions\n", "utf8");
 }
 async function defaultBootstrapPackage(_root) {
   const packageRoot = await findAgentwheelPackageRoot(dirname32(fileURLToPath3(import.meta.url)));
@@ -14287,6 +14573,7 @@ function printSearchResults(query, results) {
       `${index + 1}. ${result.name} [type=${result.type}; ecosystem=${ecosystem}; installability=${result.installability}; provenance=${provenances}]`
     );
     console.log(`   ${result.description || "(no description)"}`);
+    if (result.semanticScore !== void 0) console.log(`   Semantic score: ${result.semanticScore}`);
     if (result.installCommand) {
       console.log(`   Install: ${result.installCommand}`);
     } else if (result.source) {

package/install.md

@@ -11,8 +11,9 @@ commands, subagents, MCP, hooks, settings, plugins, and fragments.
 1. Inspect the environment.
 2. Install the `agentwheel` CLI if it is missing or too old.
 3. Verify the CLI.
-4. Install the Agentwheel companion skill into the user's active runtime when requested.
-5. Show the user how to browse or install catalogue resources.
+4. Install the Agentwheel management skill into the user's active runtime when requested.
+5. Offer the separate proactive discovery skill when the user wants automatic capability suggestions.
+6. Show the user how to browse or install catalogue resources.
 
 If the user explicitly asked you to install Agentwheel, you may run the installation commands below.
 Ask before destructive operations, `--force`, remote publishing, local adapter code execution, or
@@ -46,7 +47,7 @@ agentwheel --version
 agentwheel doctor --help
 ```
 
-## Install The Companion Skill
+## Install The Companion Skills
 
 Pick the adapter that matches the active runtime:
 
@@ -70,6 +71,15 @@ agentwheel doctor --adapter claude --user
 agentwheel install github:NestDevLab/agentwheel --adapter claude --user --skill agentwheel
 ```
 
+The `agentwheel` skill is not proactive. If the user wants the agent to notice capability gaps,
+suggest up to three semantic matches, and offer read-only trials, preview and install the separate
+discovery skill:
+
+```bash
+agentwheel install github:NestDevLab/agentwheel --adapter claude --user --skill agentwheel-discovery --dry-run
+agentwheel install github:NestDevLab/agentwheel --adapter claude --user --skill agentwheel-discovery
+```
+
 If the user wants to preview first, add `--dry-run` to the `install` command.
 
 ## Use The Catalogue
@@ -115,6 +125,7 @@ npx agentwheel@latest registry publish https://github.com/owner/repo
 
 - `agentwheel --version` works.
 - `agentwheel doctor` runs for the selected adapter.
-- The companion skill is installed if the user requested it.
+- The management skill is installed if the user requested it.
+- The discovery skill is installed only if the user requested proactive suggestions.
 - Any catalogue resource install uses the adapter and installation type the user intended.
 - Catalogue submissions use `agentwheel registry publish` unless the user explicitly wants a manual registry PR.

package/openpack.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 2,
   "name": "NestDevLab/agentwheel",
-  "version": "0.16.4",
+  "version": "0.16.5",
   "provides": [
     { "type": "skills", "path": "skills" }
   ]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentwheel",
-  "version": "0.16.4",
+  "version": "0.16.5",
   "description": "Weave skills, rules, and instructions across every AI agent.",
   "type": "module",
   "license": "MIT",
@@ -49,6 +49,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
+    "@huggingface/transformers": "4.2.0",
     "@skillkit/core": "1.24.0",
     "commander": "14.0.2",
     "jsonc-parser": "3.3.1",

package/skills/agentwheel/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: agentwheel
-description: Discover or manage reusable agent artifacts with Agentwheel. Use when substantive work exposes a missing capability, repeated manual workflow, or unavailable integration, when a requested artifact may already exist, and when adding, installing, updating, customizing, ejecting, or uninstalling agent artifacts across runtimes.
+description: Manage and explicitly inspect reusable agent artifacts with Agentwheel. Use when the user asks to search, add, install, update, customize, eject, or uninstall skills, integrations, workflows, or other OpenPack artifacts across runtimes. For automatic capability suggestions, install the separate agentwheel-discovery skill.
 allowed-tools: [Bash]
 license: MIT
 metadata:
   author: NestDevLab
-  version: "0.16.4"
+  version: "0.16.5"
 ---
 
 # agentwheel
@@ -73,30 +73,34 @@ agentwheel init package
 
 `agentwheel init package` creates `openpack.json`, `instructions/`, `rules/`, `skills/`, and `instructions/AGENTS.md`.
 
-## Discovery And Recommendations
+## Explicit Discovery
 
 Search configured registries and public catalogue sources:
 
 ```bash
 agentwheel search "<query>"
 agentwheel search "<query>" --json --limit 10
+agentwheel search "<query>" --semantic --json --limit 10
 ```
 
-Search automatically when substantive work exposes a missing capability, repeated manual workflow, unavailable integration, or explicit request for a reusable artifact. This is a per-turn judgment, not a background monitor; delegated agents follow the same trigger when the skill is available.
+Search when the user explicitly asks to find, compare, or evaluate an artifact. Search results are
+proposals, not approval, and never change desired state by themselves.
 
-Before searching, inspect the installed skill/tool inventory available in the current session. If nothing suitable is already present:
+### Semantic catalogue search
 
-1. Extract the capability and constraints from the complete request.
-2. Generate one to four short lexical queries using capability terms, synonyms, runtime names, and artifact types. Prefer English catalogue terms when the request uses another language.
-3. Run one `agentwheel search "<query>" --json --limit 10` per variant. Stop after four calls; do not recursively refine without new user requirements.
-4. Merge results by stable `id`. Treat CLI scores as retrieval signals, not semantic confidence.
-5. Rerank against the original request using capabilities, runtime or ecosystem, artifact type, description, tags, `provides`, and installability. Do not infer capabilities absent from result metadata.
-6. Suggest zero to three distinct artifacts. For each, give its name or source, one evidence-based match reason, installability, and a safe next command.
-7. Wait for explicit approval before `add`, `install`, plugin execution, or configuration changes.
+Use `--semantic` for a capability request whose wording is unlikely to match catalogue labels, or after bounded lexical search returns only weak matches. It queries the same published catalogue vector index used by the website and validates its checksums against the loaded catalogue before ranking. It is opt-in because first use may download the model and index assets.
 
-For automatic suggestions, search once per distinct capability gap. Skip discovery when the user explicitly wants custom implementation, has already selected an artifact, an installed artifact clearly satisfies the request, candidates are only weak lexical matches, or the same suggestion was declined or shown without new evidence. Continue useful work while searching when possible; do not interrupt solely to advertise marginal matches.
+```bash
+agentwheel search "remember corrections from earlier conversations" --semantic --json --limit 10
+```
+
+Do not use `--semantic` for a registry-only search, and never describe a semantic score as proof
+that an artifact implements a capability.
+
+Use a trial only for instruction skills. Plugins, MCP servers, hooks, commands, and settings are not trialled because reading them is not equivalent to safely executing them in an isolated runtime.
 
-Search recommendations are conversational only: they do not select OpenPack `suggests`, mutate desired state, or imply installation approval.
+Install `skills/agentwheel-discovery` separately when the user wants proactive capability-gap
+detection, bounded semantic recommendations, and read-only trial suggestions during unrelated work.
 
 Registry maintenance remains explicit:
 

package/skills/agentwheel-discovery/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: agentwheel-discovery
+description: Proactively discover reusable skills, integrations, and workflows when a user's request exposes a missing capability, repeated manual work, or unavailable integration. Use Agentwheel semantic search to suggest up to three evidence-backed matches and offer a read-only trial without installing or changing anything.
+allowed-tools: [Bash]
+license: MIT
+metadata:
+  author: NestDevLab
+  version: "0.16.5"
+---
+
+# Agentwheel Discovery
+
+Find reusable capabilities during normal work without silently changing the user's environment.
+This skill is optional: install it only when proactive recommendations are wanted. The separate
+`agentwheel` skill owns artifact management and explicit installation workflows.
+
+## Safety
+
+- Inspect the skills and tools already available in the current session before searching.
+- Search and trial are read-only. Never add, install, enable, execute, or change configuration
+  without explicit approval for the artifact and target scope.
+- Treat retrieval scores as ranking signals, not proof that an artifact implements a capability.
+- Continue useful work while searching when possible; do not interrupt solely to advertise weak
+  or marginal matches.
+
+## When To Search
+
+Search automatically when substantive work exposes a missing capability, repeated manual workflow,
+or unavailable integration. This is a per-turn judgment, not a background monitor. Delegated agents
+follow the same trigger when this skill is available.
+
+Skip discovery when the user explicitly wants a custom implementation, has already selected an
+artifact, an installed artifact clearly satisfies the request, candidates are only weak lexical
+matches, or the same suggestion was declined or shown without new evidence.
+
+## Discovery Workflow
+
+1. Extract the capability and constraints from the complete request.
+2. Run one fast semantic search using the full capability request:
+   `agentwheel search "<query>" --semantic --json --limit 10`.
+   Use exact lexical search first only when the user supplied an artifact name, source, or registry
+   identifier.
+3. If semantic candidates are weak, absent, or need a precise runtime or type constraint, generate
+   up to three short lexical variants using capability terms, synonyms, runtime names, and artifact
+   types. Prefer English catalogue terms for non-English requests. Stop after four total searches;
+   do not recursively refine without new user requirements.
+4. Merge results by stable `id`. Treat CLI scores as retrieval signals, not semantic confidence.
+5. Rerank against the original request using capabilities, runtime or ecosystem, artifact type,
+   description, tags, `provides`, and installability. Do not infer capabilities absent from result
+   metadata.
+6. Suggest zero to three distinct artifacts. For each, give its name or source, one evidence-based
+   match reason, installability, and a read-only trial command before any installation command.
+7. Search once per distinct capability gap. Do not repeat a recommendation without new evidence.
+
+Do not use `--semantic` for a registry-only search. The semantic path queries the same published
+catalogue vector index used by the website and validates its checksums against the loaded catalogue.
+First use may download the model and index assets.
+
+## Read-Only Trial
+
+When the user wants to evaluate one instruction skill, run:
+
+```bash
+agentwheel try <source> --skill <name> --json
+```
+
+A trial fetches, scans, validates, and reads exactly one `SKILL.md` for the current task. It does not
+add a package, change configuration, write runtime files, or execute code. Do not trial plugins,
+MCP servers, hooks, commands, or settings because reading their metadata is not safe execution.
+
+## Recommendation Contract
+
+Search recommendations are conversational only: they do not select OpenPack `suggests`, mutate
+desired state, or imply installation approval. Wait for explicit approval before `add`, `install`,
+plugin execution, or configuration changes.