agentwheel 0.15.0 → 0.16.0

package/README.md

@@ -98,6 +98,7 @@ Fragments are Agentwheel composition inputs, not runtime file-drop targets.
 
 | Command | Meaning |
 |---|---|
+| `agentwheel search <query>` | Search configured registries and the public enriched/Vercel catalogue; supports stable JSON output for agent reranking. |
 | `agentwheel add <source>` | Validate and save a package entry in `.agentwheel/config.json`; does not touch runtimes. |
 | `agentwheel plan [name-or-source]` | Preview what `install` would reconcile without writing; supports `--profile <name>` and `--json`. |
 | `agentwheel install` | Reconcile configured packages into the current target or selected fleet. Uses the graph lock as input by default. |
@@ -152,6 +153,28 @@ agentwheel plan
 agentwheel install
 ```
 
+## Artifact Discovery
+
+Search configured registries and the complete public catalogue with one command:
+
+```bash
+agentwheel search "conversation memory"
+agentwheel search "telegram integration" --type skill
+agentwheel search "message recall" --json --limit 10
+```
+
+Use `--scope registry`, `--scope enriched`, or `--scope vercel` to restrict a query. The default
+`--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.
+
+Registry maintenance remains available through `agentwheel registry update` and
+`agentwheel registry list`. Registry short names continue to resolve during add/install.
+
 ## Source Inputs
 
 Agentwheel can install from explicit local paths, Git sources, catalogue short names, provider

package/dist/index.js

@@ -9,11 +9,11 @@ import {
 } from "./chunk-PKAPR55N.js";
 
 // src/cli/index.ts
-import { createHash as createHash11 } from "crypto";
+import { createHash as createHash12 } from "crypto";
 import { existsSync } from "fs";
-import { mkdir as mkdir23, rm as rm11, writeFile as writeFile22 } from "fs/promises";
-import { homedir as homedir9 } from "os";
-import { dirname as dirname32, join as join44, resolve as resolve22 } from "path";
+import { mkdir as mkdir23, rm as rm12, writeFile as writeFile22 } from "fs/promises";
+import { homedir as homedir10 } from "os";
+import { dirname as dirname32, join as join45, resolve as resolve22 } from "path";
 import { fileURLToPath as fileURLToPath3 } from "url";
 import { Command } from "commander";
 
@@ -7759,13 +7759,6 @@ var RegistryClient = class {
     const index = await this.getIndex(options);
     return index.entries.find((entry) => entry.name === name);
   }
-  async search(query, options = {}) {
-    const q = query.toLowerCase();
-    const index = await this.getIndex(options);
-    return index.entries.filter(
-      (entry) => entry.name.toLowerCase().includes(q) || entry.description.toLowerCase().includes(q) || entry.tags.some((tag) => tag.toLowerCase().includes(q))
-    );
-  }
   async clearCache() {
     await rm8(this.cachePath, { force: true });
   }
@@ -11318,6 +11311,628 @@ function valueAfter(lines, prefix) {
   return lines.find((line) => line.startsWith(prefix))?.slice(prefix.length).trim() ?? null;
 }
 
+// src/catalogue/client.ts
+import { createHash as createHash11 } from "crypto";
+import { readFile as readFile32, rm as rm11 } from "fs/promises";
+import { homedir as homedir9 } from "os";
+import { join as join44 } from "path";
+
+// src/model/catalogue.ts
+import { z as z13 } from "zod";
+var searchScopeSchema = z13.enum(["all", "registry", "enriched", "vercel"]);
+var searchTypeSchema = z13.enum(["package", "skill", "plugin", "mcp", "adapter"]);
+var searchEcosystemSchema = z13.enum([
+  "official",
+  "openpack",
+  "mcp-registry",
+  "clawhub",
+  "skillkit",
+  "vercel"
+]);
+var catalogueProvenanceSchema = z13.enum(["registry", "enriched", "vercel"]);
+var installabilitySchema = z13.enum(["registry", "source", "informational"]);
+var nullableString = z13.string().nullable();
+var nullableStringArray = z13.array(z13.string()).nullable();
+var enrichedCatalogueEntrySchema = z13.object({
+  id: z13.string().min(1),
+  name: z13.string().min(1),
+  ecosystem: searchEcosystemSchema.nullable(),
+  type: searchTypeSchema.nullable(),
+  description: nullableString,
+  tags: nullableStringArray,
+  source: nullableString,
+  installCommand: nullableString,
+  repoUrl: nullableString,
+  homepageUrl: nullableString.optional(),
+  homepageLinkLabel: nullableString.optional(),
+  stars: z13.number().finite().nullable().optional(),
+  lastPush: nullableString.optional(),
+  archived: z13.boolean().nullable(),
+  provides: nullableStringArray,
+  version: nullableString,
+  featured: z13.boolean().nullable().optional()
+});
+var enrichedCatalogueSchema = z13.object({
+  schemaVersion: z13.literal(1),
+  generatedAt: z13.string().datetime(),
+  entries: z13.array(enrichedCatalogueEntrySchema)
+}).superRefine((value, context) => {
+  const seen = /* @__PURE__ */ new Set();
+  value.entries.forEach((entry, index) => {
+    if (seen.has(entry.id)) {
+      context.addIssue({
+        code: "custom",
+        path: ["entries", index, "id"],
+        message: `duplicate catalogue id: ${entry.id}`
+      });
+    }
+    seen.add(entry.id);
+  });
+});
+var vercelCatalogueEntrySchema = z13.object({
+  o: z13.string().min(1),
+  r: z13.string().min(1),
+  s: z13.string().min(1),
+  d: z13.string().nullable().optional()
+});
+var vercelCatalogueSchema = z13.object({
+  schemaVersion: z13.literal(1),
+  generatedAt: z13.string().datetime(),
+  count: z13.number().int().nonnegative(),
+  entries: z13.array(vercelCatalogueEntrySchema)
+}).superRefine((value, context) => {
+  if (value.count !== value.entries.length) {
+    context.addIssue({
+      code: "custom",
+      path: ["count"],
+      message: `count must equal entries length (${value.entries.length})`
+    });
+  }
+  const seen = /* @__PURE__ */ new Set();
+  value.entries.forEach((entry, index) => {
+    const id = `${entry.o}/${entry.r}/${entry.s}`;
+    if (seen.has(id)) {
+      context.addIssue({
+        code: "custom",
+        path: ["entries", index],
+        message: `duplicate Vercel catalogue id: ${id}`
+      });
+    }
+    seen.add(id);
+  });
+});
+var catalogueCacheSchema = z13.object({
+  version: z13.literal(1),
+  fetchedAt: z13.string().datetime(),
+  sources: z13.tuple([z13.string().url(), z13.string().url()]),
+  enriched: enrichedCatalogueSchema,
+  vercel: vercelCatalogueSchema
+});
+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(),
+  enriched: z13.unknown(),
+  vercel: z13.unknown()
+});
+var searchResultSchema = z13.object({
+  id: z13.string().min(1),
+  name: z13.string().min(1),
+  description: z13.string(),
+  type: searchTypeSchema,
+  ecosystem: searchEcosystemSchema.optional(),
+  tags: z13.array(z13.string()),
+  provides: z13.array(z13.string()),
+  source: z13.string().min(1).optional(),
+  repoUrl: z13.string().min(1).optional(),
+  installCommand: z13.string().min(1).optional(),
+  installability: installabilitySchema,
+  provenances: z13.array(catalogueProvenanceSchema).min(1),
+  score: z13.number().int().nonnegative(),
+  matchedFields: z13.array(z13.string())
+});
+var searchResponseSchema = z13.object({
+  schemaVersion: z13.literal(1),
+  query: z13.string(),
+  scope: searchScopeSchema,
+  fromCache: z13.boolean(),
+  results: z13.array(searchResultSchema)
+});
+
+// src/catalogue/client.ts
+var DEFAULT_ENRICHED_CATALOGUE_URL = "https://raw.githubusercontent.com/NestDevLab/agentwheel-registry/main/catalogue-data.json";
+var DEFAULT_VERCEL_CATALOGUE_URL = "https://raw.githubusercontent.com/NestDevLab/agentwheel-registry/main/catalogue-vercel-index.json";
+var DEFAULT_CATALOGUE_TTL_MS = 24 * 60 * 60 * 1e3;
+var MAX_CATALOGUE_PAYLOAD_BYTES = 32 * 1024 * 1024;
+var CatalogueClient = class {
+  constructor(options = {}) {
+    this.options = options;
+    this.cachePath = options.cachePath ?? defaultCatalogueCachePath();
+    this.now = options.now ?? (() => /* @__PURE__ */ new Date());
+    this.fetchImpl = options.fetch ?? fetch;
+    this.sources = [
+      options.enrichedUrl ?? DEFAULT_ENRICHED_CATALOGUE_URL,
+      options.vercelUrl ?? DEFAULT_VERCEL_CATALOGUE_URL
+    ];
+  }
+  options;
+  cachePath;
+  now;
+  fetchImpl;
+  sources;
+  async getIndex(options = {}) {
+    const cached = await this.readCache();
+    const usableCache = cached && sameSources2(cached.sources, this.sources) ? cached : void 0;
+    const expired = usableCache ? this.isExpired(usableCache) : false;
+    if (this.options.offline) {
+      if (!usableCache) {
+        throw new Error("Offline catalogue cache is missing. Run without --offline first.");
+      }
+      const stale = expired;
+      this.options.warn?.(
+        stale ? "Offline: using stale catalogue cache because refresh is disabled." : "Offline: using cached catalogue data."
+      );
+      return this.fromCache(usableCache, stale);
+    }
+    if (!options.refresh && usableCache && !expired) {
+      return this.fromCache(usableCache, false);
+    }
+    try {
+      const [enriched, vercel] = await Promise.all([
+        this.fetchJson(this.sources[0], enrichedCatalogueSchema),
+        this.fetchJson(this.sources[1], vercelCatalogueSchema)
+      ]);
+      const fetchedAt = this.now().toISOString();
+      const cache = {
+        version: 1,
+        fetchedAt,
+        sources: this.sources,
+        enriched,
+        vercel
+      };
+      const cacheFile = {
+        ...cache,
+        contentHash: catalogueContentHash(enriched, vercel)
+      };
+      await writeJsonAtomic(this.cachePath, cacheFile);
+      return { enriched, vercel, sources: this.sources, fetchedAt, fromCache: false, stale: false };
+    } catch (error) {
+      if (!usableCache) throw error;
+      const reason = error instanceof Error ? error.message : String(error);
+      this.options.warn?.(`Catalogue refresh failed; using stale catalogue cache: ${reason}`);
+      return this.fromCache(usableCache, true);
+    }
+  }
+  async clearCache() {
+    await rm11(this.cachePath, { force: true });
+  }
+  async readCache() {
+    if (!await pathExists(this.cachePath)) return void 0;
+    try {
+      const value = JSON.parse(await readFile32(this.cachePath, "utf8"));
+      const envelope = catalogueCacheEnvelopeSchema.parse(value);
+      if (envelope.contentHash) {
+        const contentHash = catalogueContentHash(envelope.enriched, envelope.vercel);
+        if (contentHash !== envelope.contentHash) {
+          throw new Error("catalogue cache integrity check failed");
+        }
+        return envelope;
+      }
+      return catalogueCacheSchema.parse(value);
+    } catch (error) {
+      const reason = error instanceof Error ? error.message : String(error);
+      this.options.warn?.(`Ignoring invalid catalogue cache: ${reason}`);
+      return void 0;
+    }
+  }
+  isExpired(cache) {
+    const ttlMs = this.options.ttlMs ?? DEFAULT_CATALOGUE_TTL_MS;
+    return this.now().getTime() - new Date(cache.fetchedAt).getTime() > ttlMs;
+  }
+  fromCache(cache, stale) {
+    return {
+      enriched: cache.enriched,
+      vercel: cache.vercel,
+      sources: cache.sources,
+      fetchedAt: cache.fetchedAt,
+      fromCache: true,
+      stale
+    };
+  }
+  async fetchJson(source, schema) {
+    const response = await this.fetchImpl(source);
+    if (!response.ok) {
+      throw new Error(`Catalogue source failed (${response.status}): ${source}`);
+    }
+    const declaredLength = response.headers.get("content-length");
+    if (declaredLength !== null) {
+      const bytes = Number(declaredLength);
+      if (Number.isFinite(bytes) && bytes > MAX_CATALOGUE_PAYLOAD_BYTES) {
+        throw new Error(`Catalogue payload exceeds 32 MiB limit: ${source}`);
+      }
+    }
+    const payload = await response.arrayBuffer();
+    if (payload.byteLength > MAX_CATALOGUE_PAYLOAD_BYTES) {
+      throw new Error(`Catalogue payload exceeds 32 MiB limit: ${source}`);
+    }
+    let value;
+    try {
+      value = JSON.parse(new TextDecoder().decode(payload));
+    } catch {
+      throw new Error(`Catalogue source returned invalid JSON: ${source}`);
+    }
+    return schema.parse(value);
+  }
+};
+function defaultCatalogueCachePath() {
+  return join44(homedir9(), ".agentwheel", "catalogue-cache.json");
+}
+function sameSources2(a, b) {
+  return a.length === b.length && a.every((source, index) => source === b[index]);
+}
+function catalogueContentHash(enriched, vercel) {
+  return createHash11("sha256").update(JSON.stringify({ enriched, vercel })).digest("hex");
+}
+
+// src/search/index.ts
+var SCORE = {
+  exactName: 1e4,
+  namePrefix: 5e3,
+  namePhrase: 3e3,
+  tagProvidesPhrase: 2e3,
+  descriptionPhrase: 1e3,
+  typeEcosystemPhrase: 800,
+  repositoryPhrase: 400,
+  nameToken: 300,
+  nameTokenPrefix: 200,
+  tagProvidesToken: 180,
+  descriptionToken: 80,
+  typeEcosystemToken: 60,
+  repositoryToken: 40,
+  allTerms: 500
+};
+var PROVENANCE_ORDER = ["registry", "enriched", "vercel"];
+var MATCHED_FIELD_ORDER = ["name", "tags", "provides", "description", "type", "ecosystem", "repository"];
+function buildSearchEntries(input) {
+  const enriched = catalogueEntries(input.enriched);
+  const vercel = catalogueEntries(input.vercel);
+  assertUniqueIdentities(enriched.map((entry) => entry.id), "enriched catalogue");
+  assertUniqueIdentities(vercel.map((entry) => `${entry.o}/${entry.r}/${entry.s}`), "Vercel catalogue");
+  const records = [
+    ...(input.registry ?? []).map(normalizeRegistryEntry),
+    ...enriched.map(normalizeEnrichedEntry),
+    ...vercel.map(normalizeVercelEntry)
+  ];
+  const byId = /* @__PURE__ */ new Map();
+  for (const record of records) {
+    const existing = byId.get(record.id);
+    byId.set(record.id, existing ? mergeEntry(existing, record) : record);
+  }
+  for (const [registryId, registryEntry] of [...byId]) {
+    if (registryEntry.provenances.length !== 1 || registryEntry.provenances[0] !== "registry" || registryEntry.hasRegistrySelectors || !registryEntry.source) {
+      continue;
+    }
+    const canonicalSource = canonicalizeSource(registryEntry.source);
+    const candidates = [...byId.entries()].filter(
+      ([candidateId2, candidate2]) => candidateId2 !== registryId && !candidate2.provenances.includes("registry") && candidate2.name === registryEntry.name && candidate2.source !== void 0 && canonicalizeSource(candidate2.source) === canonicalSource
+    );
+    if (candidates.length !== 1) continue;
+    const [candidateId, candidate] = candidates[0];
+    byId.set(candidateId, mergeEntry(registryEntry, candidate, candidateId));
+    byId.delete(registryId);
+  }
+  return [...byId.values()].sort(compareStableEntries);
+}
+function searchEntries(entries, query, options = {}) {
+  const normalizedQuery = normalizeSearchText(query);
+  const queryTokens = tokenizeSearchText(query);
+  if (!normalizedQuery || queryTokens.length === 0) return [];
+  const results = entries.filter((entry) => options.includeArchived || !entry.archived).filter((entry) => options.type === void 0 || entry.type === options.type).filter((entry) => options.ecosystem === void 0 || entry.ecosystem === options.ecosystem).map((entry) => ({ entry, result: scoreEntry(entry, normalizedQuery, queryTokens) })).filter(({ result }) => result.score > 0).sort(
+    (a, b) => b.result.score - a.result.score || Number(b.entry.featured) - Number(a.entry.featured) || (b.entry.stars ?? Number.NEGATIVE_INFINITY) - (a.entry.stars ?? Number.NEGATIVE_INFINITY) || compareText(b.entry.lastPush ?? "", a.entry.lastPush ?? "") || compareText(normalizeSearchText(a.result.name), normalizeSearchText(b.result.name)) || compareText(a.result.id, b.result.id)
+  ).map(({ result }) => result);
+  const limit = options.limit === void 0 ? 20 : Math.min(100, Math.max(0, Math.trunc(options.limit)));
+  return results.slice(0, limit);
+}
+function normalizeSearchText(value) {
+  return value.normalize("NFKC").toLowerCase().replace(/[^\p{L}\p{N}]+/gu, " ").trim().replace(/\s+/g, " ");
+}
+function tokenizeSearchText(value) {
+  const normalized = normalizeSearchText(value);
+  return normalized ? [...new Set(normalized.split(" "))] : [];
+}
+function normalizeRegistryEntry(entry) {
+  return {
+    id: `registry:${entry.name}`,
+    name: entry.name,
+    description: entry.description,
+    type: entry.type,
+    ecosystem: inferEcosystem(entry.source),
+    tags: sortedUniqueStrings(entry.tags),
+    provides: [],
+    source: entry.source,
+    installCommand: `npx agentwheel install ${shellQuote2(entry.name)}`,
+    installability: "registry",
+    provenances: ["registry"],
+    archived: false,
+    featured: false,
+    alternateDescriptions: [],
+    descriptionRank: 2,
+    hasRegistrySelectors: Boolean(entry.select?.length || entry.skills?.length)
+  };
+}
+function normalizeEnrichedEntry(entry) {
+  const source = nonEmpty(entry.source);
+  const installCommand = enrichedInstallCommand(entry, source);
+  return {
+    id: entry.id,
+    name: entry.name,
+    description: entry.description ?? "",
+    type: entry.type ?? inferType(entry.ecosystem),
+    ecosystem: entry.ecosystem ?? void 0,
+    tags: sortedUniqueStrings(entry.tags ?? []),
+    provides: sortedUniqueStrings(entry.provides ?? []),
+    source,
+    repoUrl: nonEmpty(entry.repoUrl),
+    installCommand,
+    installability: source || installCommand ? "source" : "informational",
+    provenances: ["enriched"],
+    archived: entry.archived ?? false,
+    featured: entry.featured ?? false,
+    stars: entry.stars ?? void 0,
+    lastPush: nonEmpty(entry.lastPush),
+    alternateDescriptions: [],
+    descriptionRank: 3,
+    hasRegistrySelectors: false
+  };
+}
+function normalizeVercelEntry(entry) {
+  const path = `${entry.o}/${entry.r}/${entry.s}`;
+  const source = `vercel:skills.sh/${path}`;
+  return {
+    id: `vercel:${path}`,
+    name: entry.s,
+    description: entry.d ?? "",
+    type: "skill",
+    ecosystem: "vercel",
+    tags: [],
+    provides: ["skills"],
+    source,
+    repoUrl: `https://github.com/${entry.o}/${entry.r}`,
+    installCommand: `npx agentwheel install ${shellQuote2(source)}`,
+    installability: "source",
+    provenances: ["vercel"],
+    archived: false,
+    featured: false,
+    alternateDescriptions: [],
+    descriptionRank: 1,
+    hasRegistrySelectors: false
+  };
+}
+function mergeEntry(first, second, id = first.id) {
+  const primary = second.description && second.descriptionRank > first.descriptionRank ? second : first;
+  const secondary = primary === first ? second : first;
+  const descriptions = uniqueStrings([
+    primary.description,
+    ...primary.alternateDescriptions,
+    secondary.description,
+    ...secondary.alternateDescriptions
+  ]).filter(Boolean);
+  const description = descriptions[0] ?? "";
+  return {
+    id,
+    name: first.name || second.name,
+    description,
+    type: first.type ?? second.type,
+    ecosystem: first.ecosystem ?? second.ecosystem,
+    tags: sortedUniqueStrings([...first.tags, ...second.tags]),
+    provides: sortedUniqueStrings([...first.provides, ...second.provides]),
+    source: first.source ?? second.source,
+    repoUrl: first.repoUrl ?? second.repoUrl,
+    installCommand: first.installCommand ?? second.installCommand,
+    installability: betterInstallability(first.installability, second.installability),
+    provenances: PROVENANCE_ORDER.filter(
+      (provenance) => first.provenances.includes(provenance) || second.provenances.includes(provenance)
+    ),
+    archived: first.archived || second.archived,
+    featured: first.featured || second.featured,
+    stars: maxDefined(first.stars, second.stars),
+    lastPush: maxText(first.lastPush, second.lastPush),
+    alternateDescriptions: descriptions.slice(1),
+    descriptionRank: Math.max(first.descriptionRank, second.descriptionRank),
+    hasRegistrySelectors: first.hasRegistrySelectors || second.hasRegistrySelectors
+  };
+}
+function scoreEntry(entry, query, queryTokens) {
+  let score = 0;
+  const matched = /* @__PURE__ */ new Set();
+  const name = normalizeSearchText(entry.name);
+  const descriptions = [entry.description, ...entry.alternateDescriptions].map(normalizeSearchText);
+  const tags = entry.tags.map(normalizeSearchText);
+  const provides = entry.provides.map(normalizeSearchText);
+  const type = normalizeSearchText(entry.type);
+  const ecosystem = normalizeSearchText(entry.ecosystem ?? "");
+  const repositories = [entry.source ?? "", entry.repoUrl ?? ""].map(normalizeSearchText);
+  if (name === query) {
+    score += SCORE.exactName;
+    matched.add("name");
+  } else if (name.startsWith(query)) {
+    score += SCORE.namePrefix;
+    matched.add("name");
+  } else if (name.includes(query)) {
+    score += SCORE.namePhrase;
+    matched.add("name");
+  }
+  const tagsPhraseMatch = matchesPhrase(tags, query);
+  const providesPhraseMatch = matchesPhrase(provides, query);
+  if (tagsPhraseMatch || providesPhraseMatch) {
+    score += SCORE.tagProvidesPhrase;
+    if (tagsPhraseMatch) matched.add("tags");
+    if (providesPhraseMatch) matched.add("provides");
+  }
+  if (matchesPhrase(descriptions, query)) {
+    score += SCORE.descriptionPhrase;
+    matched.add("description");
+  }
+  const typePhraseMatch = type.includes(query);
+  const ecosystemPhraseMatch = ecosystem.includes(query);
+  if (typePhraseMatch || ecosystemPhraseMatch) {
+    score += SCORE.typeEcosystemPhrase;
+    if (typePhraseMatch) matched.add("type");
+    if (ecosystemPhraseMatch) matched.add("ecosystem");
+  }
+  if (matchesPhrase(repositories, query)) {
+    score += SCORE.repositoryPhrase;
+    matched.add("repository");
+  }
+  const nameTokens = name.split(" ");
+  const tagTokenText = tags.join(" ");
+  const provideTokenText = provides.join(" ");
+  const descriptionTokenText = descriptions.join(" ");
+  const repositoryTokenText = repositories.join(" ");
+  let allTermsCovered = true;
+  for (const token of queryTokens) {
+    const nameTokenMatch = includesToken(name, token);
+    if (nameTokenMatch) {
+      score += SCORE.nameToken;
+      matched.add("name");
+    } else if (nameTokens.some((candidate) => candidate.startsWith(token))) {
+      score += SCORE.nameTokenPrefix;
+      matched.add("name");
+    }
+    const tagTokenMatch = includesToken(tagTokenText, token);
+    const provideTokenMatch = includesToken(provideTokenText, token);
+    if (tagTokenMatch || provideTokenMatch) {
+      score += SCORE.tagProvidesToken;
+      if (tagTokenMatch) matched.add("tags");
+      if (provideTokenMatch) matched.add("provides");
+    }
+    const descriptionTokenMatch = includesToken(descriptionTokenText, token);
+    if (descriptionTokenMatch) {
+      score += SCORE.descriptionToken;
+      matched.add("description");
+    }
+    const typeTokenMatch = includesToken(type, token);
+    const ecosystemTokenMatch = includesToken(ecosystem, token);
+    if (typeTokenMatch || ecosystemTokenMatch) {
+      score += SCORE.typeEcosystemToken;
+      if (typeTokenMatch) matched.add("type");
+      if (ecosystemTokenMatch) matched.add("ecosystem");
+    }
+    const repositoryTokenMatch = includesToken(repositoryTokenText, token);
+    if (repositoryTokenMatch) {
+      score += SCORE.repositoryToken;
+      matched.add("repository");
+    }
+    if (!nameTokenMatch && !tagTokenMatch && !provideTokenMatch && !descriptionTokenMatch && !typeTokenMatch && !ecosystemTokenMatch && !repositoryTokenMatch) {
+      allTermsCovered = false;
+    }
+  }
+  if (allTermsCovered) {
+    score += SCORE.allTerms;
+  }
+  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,
+    matchedFields: MATCHED_FIELD_ORDER.filter((field) => matched.has(field))
+  };
+}
+function catalogueEntries(catalogue) {
+  if (!catalogue) return [];
+  return Array.isArray(catalogue) ? catalogue : catalogue.entries;
+}
+function canonicalizeSource(source) {
+  const value = source.normalize("NFKC").trim();
+  const github = value.match(
+    /^(?:github:|git:(?:git\+)?https?:\/\/github\.com\/|(?:git\+)?https?:\/\/github\.com\/)([^/#]+)\/([^#]+?)(?:#(.*))?$/i
+  );
+  if (github) {
+    const owner = github[1].toLowerCase();
+    const repository = github[2].replace(/\.git$/i, "").replace(/\/+$/, "").toLowerCase();
+    const ref = github[3];
+    return `github:${owner}/${repository}${ref === void 0 ? "" : `#${ref}`}`;
+  }
+  return value.replace(/\/+$/, "");
+}
+function inferEcosystem(source) {
+  const canonical = canonicalizeSource(source);
+  if (canonical.startsWith("vercel:")) return "vercel";
+  if (canonical.startsWith("mcp-registry:")) return "mcp-registry";
+  if (canonical.startsWith("clawhub:")) return "clawhub";
+  if (canonical.startsWith("skillkit:")) return "skillkit";
+  return void 0;
+}
+function inferType(ecosystem) {
+  if (ecosystem === "vercel" || ecosystem === "skillkit") return "skill";
+  if (ecosystem === "mcp-registry") return "mcp";
+  if (ecosystem === "clawhub") return "plugin";
+  return "package";
+}
+function betterInstallability(a, b) {
+  const rank = { registry: 3, source: 2, informational: 1 };
+  return rank[a] >= rank[b] ? a : b;
+}
+function nonEmpty(value) {
+  return value?.trim() ? value : void 0;
+}
+function uniqueStrings(values) {
+  return [...new Set(values)];
+}
+function sortedUniqueStrings(values) {
+  return uniqueStrings(values).sort(compareText);
+}
+function enrichedInstallCommand(entry, source) {
+  const catalogueCommand = nonEmpty(entry.installCommand);
+  if (!source) return catalogueCommand;
+  if (entry.ecosystem === "mcp-registry" || entry.ecosystem === "clawhub") {
+    return catalogueCommand ?? `npx agentwheel install ${shellQuote2(source)}`;
+  }
+  return `npx agentwheel install ${shellQuote2(source)}`;
+}
+function shellQuote2(value) {
+  return `'${value.replaceAll("'", `'"'"'`)}'`;
+}
+function matchesPhrase(fields, query) {
+  return fields.some((field) => field.includes(query));
+}
+function compareStableEntries(a, b) {
+  return compareText(normalizeSearchText(a.name), normalizeSearchText(b.name)) || compareText(a.id, b.id);
+}
+function maxDefined(a, b) {
+  if (a === void 0) return b;
+  if (b === void 0) return a;
+  return Math.max(a, b);
+}
+function maxText(a, b) {
+  if (a === void 0) return b;
+  if (b === void 0) return a;
+  return a >= b ? a : b;
+}
+function assertUniqueIdentities(ids, label) {
+  const seen = /* @__PURE__ */ new Set();
+  for (const id of ids) {
+    if (seen.has(id)) throw new Error(`Duplicate ${label} id: ${id}`);
+    seen.add(id);
+  }
+}
+function compareText(a, b) {
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+function includesToken(normalizedText, token) {
+  return normalizedText === token || normalizedText.startsWith(`${token} `) || normalizedText.endsWith(` ${token}`) || normalizedText.includes(` ${token} `);
+}
+
 // src/cli/index.ts
 var CLI_VERSION = resolveCliVersion();
 var COMPANION_SKILL_SOURCE = "github:NestDevLab/agentwheel";
@@ -11361,17 +11976,59 @@ 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: join44(targetRoot, ".agentwheel", "cache") }))));
+  const resolved = await driver.export(await driver.translate(await driver.fetch(await driver.resolve(resolvedInput.source, { cacheRoot: join45(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) => {
+  const trimmedQuery = query.trim();
+  if (!trimmedQuery) {
+    throw new Error("Search query must not be empty.");
+  }
+  const scope = parseSearchScope(options.scope);
+  const type = options.type === void 0 ? void 0 : parseSearchType(options.type);
+  const ecosystem = options.ecosystem === void 0 ? void 0 : parseSearchEcosystem(options.ecosystem);
+  const limit = parseSearchLimit(options.limit);
+  if (options.refresh && options.offline) {
+    throw new Error("--refresh cannot be used with --offline.");
+  }
+  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 [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, {
+    type,
+    ecosystem,
+    limit,
+    includeArchived: options.includeArchived
+  });
+  const loadedIndexes = [registryIndex, catalogueIndex].filter((index) => index !== void 0);
+  const response = {
+    schemaVersion: 1,
+    query: trimmedQuery,
+    scope,
+    fromCache: loadedIndexes.every((index) => index.fromCache),
+    results
+  };
+  if (options.json) {
+    console.log(JSON.stringify(response, null, 2));
+    return;
+  }
+  printSearchResults(trimmedQuery, results);
+});
 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: join44(targetRoot, ".agentwheel", "cache") }))));
+  const resolved = await driver.export(await driver.translate(await driver.fetch(await driver.resolve(resolvedInput.source, { cacheRoot: join45(targetRoot, ".agentwheel", "cache") }))));
   const result = await driver.scan(resolved);
   if (result.findings.length === 0) {
     console.log("Scan ok: no findings");
@@ -11434,7 +12091,7 @@ program.command("deps").description("inspect the OpenPack dependency graph").add
           for (const decision of result.bundle.graphLock.canonical.overrides) {
             console.log(`OVERRIDE ${decision.graphNodeId}:${decision.type}/${decision.name} replaces ${decision.overriddenGraphNodeId}:${decision.type}/${decision.name} via ${decision.rootId} (${decision.selector})`);
           }
-          await rm11(result.bundle.root, { recursive: true, force: true });
+          await rm12(result.bundle.root, { recursive: true, force: true });
         }
         continue;
       }
@@ -11466,11 +12123,6 @@ program.command("registry").description("manage optional registry indexes").addC
     const client = new RegistryClient({ workspaceRoot: normalizeTargetRoot(options.targetRoot), warn: (message) => console.warn(message) });
     printRegistryEntries((await client.getIndex()).entries);
   })
-).addCommand(
-  new Command("search").description("search registry entries").argument("<query>", "search query").option("-t, --target-root <path>", "workspace root", process.cwd()).action(async (query, options) => {
-    const client = new RegistryClient({ workspaceRoot: normalizeTargetRoot(options.targetRoot), warn: (message) => console.warn(message) });
-    printRegistryEntries(await client.search(query));
-  })
 ).addCommand(
   new Command("publish").description("draft a catalogue submission for a public source").argument("<source>", "public resource source or GitHub URL").option("--name <name>", "registry short name").option("--type <type>", "entry type (package, skill, plugin, mcp, or adapter)").option("--description <text>", "short catalogue description").option("--tag <tag>", "search tag (repeatable or comma-separated)", collectTagOption, []).option("--select <type/name>", "selected artifact inside a larger package (repeatable or comma-separated)", collectSelectOption, []).option("--skill <name>", "selected skill inside a larger package (repeatable or comma-separated)", collectSkillOption, []).option("--json", "print only the registry entry JSON", false).action(async (source, options) => {
     const draft = createRegistryPublishDraft(source, {
@@ -11644,7 +12296,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: ${join44(state.installRoot, ".agentwheel", `${state.state.stateKey}.apply-journal.json`)}`);
+    console.log(`  journal: ${join45(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}`);
@@ -11784,7 +12436,7 @@ async function runInstallCommand(nameOrSource, options, behavior) {
         console.log(`Applied ${result.plan.adapter} at ${result.plan.targetRoot}.`);
         if (reloaded) console.log(`Reloaded runtime via ${formatReloadCommands(target.reloadCommands)}.`);
       }
-      await rm11(result.bundle.root, { recursive: true, force: true });
+      await rm12(result.bundle.root, { recursive: true, force: true });
       if (result.plan.hasBlockingChanges) process.exitCode = 1;
     }
     if (behavior.apply && extraPackage && !targetOptions.onlySource) {
@@ -11879,7 +12531,7 @@ async function buildPlanReport(nameOrSource, options) {
     for (const result of results) {
       reportTargets.push(installPlanReportTarget(result.plan, result.graphLockDigest));
       reportWarnings.push(...result.warnings);
-      await rm11(result.bundle.root, { recursive: true, force: true });
+      await rm12(result.bundle.root, { recursive: true, force: true });
     }
   }
   return planReport(reportTargets, reportWarnings);
@@ -11935,7 +12587,7 @@ async function packageEntryFromSource(source, targetRoot, options) {
   const bundle = await stageSource(driver, resolvedSource, {
     workspaceRoot: targetRoot,
     adapter,
-    cacheRoot: join44(targetRoot, ".agentwheel", "cache"),
+    cacheRoot: join45(targetRoot, ".agentwheel", "cache"),
     mode: options.mode,
     ref: initialVersion?.ref,
     frozenLock: lockMode,
@@ -11961,7 +12613,7 @@ async function packageEntryFromSource(source, targetRoot, options) {
       overrides: overrideArtifactsFromOptions(options)
     };
   } finally {
-    await rm11(bundle.root, { recursive: true, force: true });
+    await rm12(bundle.root, { recursive: true, force: true });
   }
 }
 function findConfiguredPackage(packages, value) {
@@ -12112,7 +12764,7 @@ async function runConfiguredGraphPackages(target, options, behavior) {
       console.log(`Applied ${result.plan.adapter} at ${result.plan.targetRoot}.`);
       if (reloaded) console.log(`Reloaded runtime via ${formatReloadCommands(target.reloadCommands)}.`);
     }
-    await rm11(result.bundle.root, { recursive: true, force: true });
+    await rm12(result.bundle.root, { recursive: true, force: true });
     if (result.plan.hasBlockingChanges) process.exitCode = 1;
   }
 }
@@ -12329,7 +12981,7 @@ function scopeUpdatePlanToDependencies(result, selectors, previousLock, manifest
     selectedPreviousNodeIds,
     selectedRootIds
   );
-  const graphLockDigest = createHash11("sha256").update(canonicalGraphLockJson(graphLock)).digest("hex");
+  const graphLockDigest = createHash12("sha256").update(canonicalGraphLockJson(graphLock)).digest("hex");
   return {
     ...result,
     bundle: { ...result.bundle, graphLock },
@@ -12497,7 +13149,7 @@ function scopeUpdatePlanToRoot(result, rootId, previousLock, manifest) {
     selectedPreviousNodeIds,
     /* @__PURE__ */ new Set([rootId])
   );
-  const graphLockDigest = createHash11("sha256").update(canonicalGraphLockJson(graphLock)).digest("hex");
+  const graphLockDigest = createHash12("sha256").update(canonicalGraphLockJson(graphLock)).digest("hex");
   return {
     ...scoped,
     bundle: { ...scoped.bundle, graphLock },
@@ -12569,7 +13221,7 @@ function keepManifestEntryOperation(entry, targetRoot, scopeDescription, operati
     artifactType: entry.artifactType,
     artifactName: entry.artifactName,
     kind: entry.kind,
-    destPath: operation?.destPath ?? join44(targetRoot, entry.path),
+    destPath: operation?.destPath ?? join45(targetRoot, entry.path),
     relativeDestPath: entry.path,
     desiredHash: entry.sourceHash,
     currentHash: operation?.currentHash ?? entry.hash,
@@ -12686,7 +13338,7 @@ async function uninstallConfiguredPackage(target, packageName, options) {
     if (!options.dryRun) {
       console.log(formatUninstallResult(result));
     }
-    if (renderedRoot) await rm11(renderedRoot, { recursive: true, force: true });
+    if (renderedRoot) await rm12(renderedRoot, { recursive: true, force: true });
     if (plan.hasBlockingChanges) process.exitCode = 1;
   }
 }
@@ -13137,7 +13789,7 @@ async function collectPendingInstallWork(target, options) {
     const message = error instanceof Error ? error.message : String(error);
     return { pendingCount: 0, driftCount: 0, conflictCount: 0, counts: {}, error: message };
   } finally {
-    await Promise.all(results.map((result) => rm11(result.bundle.root, { recursive: true, force: true })));
+    await Promise.all(results.map((result) => rm12(result.bundle.root, { recursive: true, force: true })));
   }
 }
 async function printDoctor(target, options) {
@@ -13154,12 +13806,12 @@ async function printDoctor(target, options) {
   const requestedSkills = doctorSkillRequests(target, options);
   const skills = [];
   for (const request of requestedSkills) {
-    const skillPath = join44(state.installRoot, targetMapping.dest, request.name);
+    const skillPath = join45(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 === join44(targetMapping.dest, request.name);
+      return entry.artifactName === request.name || legacyInstallName === request.name || entry.path === join45(targetMapping.dest, request.name);
     });
     const status = manifestEntry ? "managed" : exists ? "present-unmanaged" : "missing";
     skills.push({
@@ -13239,7 +13891,7 @@ function doctorSkillLabel(name) {
   return `${name} skill`;
 }
 function isSyncwheelWorkspace(targetRoot) {
-  return existsSync(join44(targetRoot, ".syncwheel", "manifest.json"));
+  return existsSync(join45(targetRoot, ".syncwheel", "manifest.json"));
 }
 function skillInstallCommand(adapter, installationType, options, skill, behavior = {}) {
   const args = [
@@ -13307,7 +13959,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 = homedir9();
+    targetRoot = homedir10();
   }
   if (!installationType && behavior.defaultUser) {
     installationType = "user";
@@ -13327,12 +13979,12 @@ function looksLikeSourceSpecifier(value) {
   return value.includes(":") || value.startsWith("/") || value.startsWith("./") || value.startsWith("../") || value === "~" || value.startsWith("~/");
 }
 function normalizeCliPath(value) {
-  if (value === "~") return homedir9();
-  if (value.startsWith("~/")) return resolve22(homedir9(), value.slice(2));
+  if (value === "~") return homedir10();
+  if (value.startsWith("~/")) return resolve22(homedir10(), value.slice(2));
   return resolve22(value);
 }
 function isHomePath(path) {
-  return resolve22(path) === resolve22(homedir9());
+  return resolve22(path) === resolve22(homedir10());
 }
 function adapterListFromOption(adapter) {
   if (!adapter) return [];
@@ -13387,10 +14039,10 @@ function filterUninstallPlanBySelection(plan, selected) {
   };
 }
 async function initPackage(root) {
-  await mkdir23(join44(root, "instructions"), { recursive: true });
-  await mkdir23(join44(root, "rules"), { recursive: true });
-  await mkdir23(join44(root, "skills"), { recursive: true });
-  const manifestPath = join44(root, "openpack.json");
+  await mkdir23(join45(root, "instructions"), { recursive: true });
+  await mkdir23(join45(root, "rules"), { recursive: true });
+  await mkdir23(join45(root, "skills"), { recursive: true });
+  const manifestPath = join45(root, "openpack.json");
   const manifest = {
     schemaVersion: 2,
     name: "example/agentwheel-package",
@@ -13403,7 +14055,7 @@ async function initPackage(root) {
   };
   await writeFile22(manifestPath, `${JSON.stringify(manifest, null, 2)}
 `, "utf8");
-  await writeFile22(join44(root, "instructions", "AGENTS.md"), "# Agent Instructions\n", "utf8");
+  await writeFile22(join45(root, "instructions", "AGENTS.md"), "# Agent Instructions\n", "utf8");
 }
 async function defaultBootstrapPackage(_root) {
   const packageRoot = await findAgentwheelPackageRoot(dirname32(fileURLToPath3(import.meta.url)));
@@ -13474,6 +14126,49 @@ function printRegistryEntries(entries) {
     console.log(`${entry.name}	${entry.type}	${entry.source}	${entry.description}${tags}`);
   }
 }
+function parseSearchScope(value) {
+  const parsed = searchScopeSchema.safeParse(value);
+  if (parsed.success) return parsed.data;
+  throw new Error(`Invalid search scope: ${value}. Expected one of: ${searchScopeSchema.options.join(", ")}.`);
+}
+function parseSearchType(value) {
+  const parsed = searchTypeSchema.safeParse(value);
+  if (parsed.success) return parsed.data;
+  throw new Error(`Invalid artifact type: ${value}. Expected one of: ${searchTypeSchema.options.join(", ")}.`);
+}
+function parseSearchEcosystem(value) {
+  const parsed = searchEcosystemSchema.safeParse(value);
+  if (parsed.success) return parsed.data;
+  throw new Error(`Invalid ecosystem: ${value}. Expected one of: ${searchEcosystemSchema.options.join(", ")}.`);
+}
+function parseSearchLimit(value) {
+  const limit = Number(value);
+  if (!Number.isInteger(limit) || limit < 1 || limit > 100) {
+    throw new Error(`Invalid search limit: ${value}. Expected an integer from 1 to 100.`);
+  }
+  return limit;
+}
+function printSearchResults(query, results) {
+  if (results.length === 0) {
+    console.log(`No artifacts found for ${JSON.stringify(query)}.`);
+    return;
+  }
+  for (const [index, result] of results.entries()) {
+    const ecosystem = result.ecosystem ?? "unknown";
+    const provenances = result.provenances.join("+");
+    console.log(
+      `${index + 1}. ${result.name} [type=${result.type}; ecosystem=${ecosystem}; installability=${result.installability}; provenance=${provenances}]`
+    );
+    console.log(`   ${result.description || "(no description)"}`);
+    if (result.installCommand) {
+      console.log(`   Install: ${result.installCommand}`);
+    } else if (result.source) {
+      console.log(`   Source: ${result.source}`);
+    } else {
+      console.log("   Install: unavailable");
+    }
+  }
+}
 async function main() {
   await maybeCheckForUpdate({
     currentVersion: CLI_VERSION,

package/openpack.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentwheel",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "Weave skills, rules, and instructions across every AI agent.",
   "type": "module",
   "license": "MIT",

package/skills/agentwheel/SKILL.md

@@ -1,16 +1,16 @@
 ---
 name: agentwheel
-description: Use agentwheel to discover, add, install, update, customize, eject, and uninstall agent skills, rules, instructions, commands, MCP, hooks, settings, and plugin artifacts across runtimes.
+description: Discover or manage reusable agent artifacts with Agentwheel. Use when a requested agent capability, integration, workflow, policy, or tool may already exist, and when adding, installing, updating, customizing, ejecting, or uninstalling skills, rules, instructions, commands, MCP, hooks, settings, plugins, or subagents across runtimes.
 allowed-tools: [Bash]
 license: MIT
 metadata:
   author: NestDevLab
-  version: "0.15.0"
+  version: "0.16.0"
 ---
 
 # agentwheel
 
-Use this skill when a user wants to install, manage, update, remove, or inspect agent skills or other agentwheel-managed artifacts.
+Agentwheel discovers reusable artifacts and manages their desired state across runtimes.
 
 agentwheel is the control plane. It reads packages from sources, stores desired state in `.agentwheel/config.json`, plans runtime changes, and writes only through `install`. Treat runtime output directories as generated files.
 
@@ -29,11 +29,12 @@ Mental model:
 - Gmail, Drive, registry publishing, git commits, pushes, and runtime reloads/restarts are separate external side effects. Get explicit approval for them.
 - Programmatic adapters execute local code. Use `--adapter-module` only with `--allow-adapter-code` after the user approves that local code execution.
 - OpenClaw plugin artifacts are only planned by default. Use `--execute-plugins` only after explicit approval.
+- Search results are proposals, not approval. Never add, install, enable, or change configuration until the user confirms the artifact and target scope.
 
 ## Core Flow
 
 ```bash
-agentwheel registry search tmux
+agentwheel search tmux
 agentwheel add github:NestDevLab/agent-mesh --skill codex-tmux --adapter codex --installation-type local --mode tracking
 agentwheel plan
 agentwheel install
@@ -72,14 +73,34 @@ agentwheel init package
 
 `agentwheel init package` creates `openpack.json`, `instructions/`, `rules/`, `skills/`, and `instructions/AGENTS.md`.
 
-## Discovery
+## Discovery And Recommendations
 
-Refresh and search the optional registry:
+Search configured registries and public catalogue sources:
+
+```bash
+agentwheel search "<query>"
+agentwheel search "<query>" --json --limit 10
+```
+
+When a reusable artifact could satisfy the request:
+
+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.
+
+For automatic suggestions, 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 already shown without new evidence.
+
+Search recommendations are conversational only: they do not select OpenPack `suggests`, mutate desired state, or imply installation approval.
+
+Registry maintenance remains explicit:
 
 ```bash
 agentwheel registry update
 agentwheel registry list
-agentwheel registry search <query>
 ```
 
 Inspect an explicit source before adding it:
@@ -91,7 +112,7 @@ agentwheel list ./local-agent-pack
 agentwheel scan ./local-agent-pack
 ```
 
-Filter discovery to specific artifacts:
+Filter source inspection to specific artifacts:
 
 ```bash
 agentwheel list github:owner/repo --select skills/review --select rules/core.md
@@ -498,11 +519,11 @@ If a selected artifact is missing:
 agentwheel list <source>
 ```
 
-If registry short names fail:
+If a registry short name fails:
 
 ```bash
 agentwheel registry update
-agentwheel registry search <query>
+agentwheel search "<query>" --scope registry
 ```
 
 If npm update checks are noisy: