akm-cli 0.5.0 → 0.6.0-rc2

package/dist/{registry-build-index.js → registry/build-index.js}

@@ -1,18 +1,28 @@
+/**
+ * Build the v2 JSON registry index consumed by the `static-index` registry
+ * provider. This module emits artifacts that conform to the v2 schema; the
+ * schema itself is the input contract owned by `src/registry/providers/static-index.ts`
+ * (see v1 architecture spec §3.3 — "the v2 JSON index schema belongs to
+ * static-index"). When the schema changes, both the parser in `static-index.ts`
+ * and the JSON Schema in `docs/technical/registry-index.schema.json` must be
+ * updated together with this builder.
+ */
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
-import { fetchWithRetry } from "./common";
-import { asRecord, asString, GITHUB_API_BASE, githubHeaders } from "./github";
-import { copyIncludedPaths, findNearestIncludeConfig } from "./kit-include";
-import { generateMetadataFlat, loadStashFile } from "./metadata";
+import { fetchWithRetry, jsonWithByteCap } from "../core/common";
+import { generateMetadataFlat, loadStashFile } from "../indexer/metadata";
+import { walkStashFlat } from "../indexer/walker";
+import { asRecord, asString, GITHUB_API_BASE, githubHeaders } from "../integrations/github";
+import { copyIncludedPaths, findNearestIncludeConfig } from "../sources/include";
+import { detectStashRoot } from "../sources/providers/provider-utils";
+import { extractTarGzSecure } from "../sources/providers/tar-utils";
 import { parseRegistryIndex } from "./providers/static-index";
-import { detectStashRoot, extractTarGzSecure } from "./registry-install";
-import { walkStashFlat } from "./walker";
 const DEFAULT_NPM_REGISTRY_BASE = "https://registry.npmjs.org";
 const DEFAULT_MANUAL_ENTRIES_PATH = path.resolve("manual-entries.json");
 const DEFAULT_OUTPUT_PATH = path.resolve("index.json");
-const REQUIRED_KEYWORDS = ["akm-kit"];
-const GITHUB_TOPICS = ["akm-kit"];
+const REQUIRED_KEYWORDS = ["akm-stash"];
+const GITHUB_TOPICS = ["akm-stash"];
 const EXCLUDED_REPOS = new Set(["itlackey/akm"]);
 const EXCLUDED_NPM_PACKAGES = new Set(["akm-cli"]);
 const EMPTY_INSPECTION = {};
@@ -25,11 +35,11 @@ export async function buildRegistryIndex(options) {
         scanNpm(npmRegistryBase),
         scanGithub(githubApiBase),
     ]);
-    const kits = deduplicateKits([...manualKits, ...npmKits, ...githubKits]).sort((a, b) => a.name.localeCompare(b.name));
+    const stashes = deduplicateStashes([...manualKits, ...npmKits, ...githubKits]).sort((a, b) => a.name.localeCompare(b.name));
     const index = {
-        version: 2,
+        version: 3,
         updatedAt: new Date().toISOString(),
-        kits,
+        stashes,
     };
     return {
         index,
@@ -37,7 +47,7 @@ export async function buildRegistryIndex(options) {
             manual: manualKits.length,
             npm: npmKits.length,
             github: githubKits.length,
-            total: kits.length,
+            total: stashes.length,
         },
         paths: {
             manualEntriesPath,
@@ -51,7 +61,7 @@ export function writeRegistryIndex(index, outPath) {
     return resolved;
 }
 async function scanNpm(npmRegistryBase) {
-    const kits = [];
+    const stashes = [];
     const seen = new Set();
     for (const keyword of REQUIRED_KEYWORDS) {
         let offset = 0;
@@ -83,7 +93,7 @@ async function scanNpm(npmRegistryBase) {
                 }
                 const inspection = await inspectNpmPackage(npmRegistryBase, latestMetadata).catch(() => EMPTY_INSPECTION);
                 const tags = mergeStrings((pkg.keywords ?? []).filter((value) => !REQUIRED_KEYWORDS.includes(value.toLowerCase())), inspection.tags);
-                kits.push(normalizeKit({
+                stashes.push(normalizeStash({
                     id,
                     name: pkg.name,
                     description: inspection.description ?? pkg.description,
@@ -103,7 +113,7 @@ async function scanNpm(npmRegistryBase) {
             offset += size;
         }
     }
-    return kits;
+    return stashes;
 }
 async function inspectNpmPackage(_npmRegistryBase, latestMetadata) {
     const dist = asRecord(latestMetadata.dist);
@@ -121,7 +131,7 @@ async function inspectNpmPackage(_npmRegistryBase, latestMetadata) {
     };
 }
 async function scanGithub(githubApiBase) {
-    const kits = [];
+    const stashes = [];
     const seen = new Set();
     const headers = githubHeaders();
     for (const topic of GITHUB_TOPICS) {
@@ -140,7 +150,7 @@ async function scanGithub(githubApiBase) {
                 seen.add(id);
                 const inspection = await inspectArchive(`${githubApiBase}/repos/${repo.full_name}/tarball/${encodeURIComponent(repo.default_branch)}`, headers).catch(() => EMPTY_INSPECTION);
                 const topics = repo.topics.filter((value) => !GITHUB_TOPICS.includes(value));
-                kits.push(normalizeKit({
+                stashes.push(normalizeStash({
                     id,
                     name: repo.name,
                     description: inspection.description ?? repo.description ?? undefined,
@@ -160,7 +170,7 @@ async function scanGithub(githubApiBase) {
             page += 1;
         }
     }
-    return kits;
+    return stashes;
 }
 async function inspectArchive(url, headers) {
     const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "akm-registry-build-"));
@@ -269,36 +279,42 @@ function applyIncludeConfigForInspection(stashRoot, tempDir, searchRoot) {
 async function loadManualEntries(manualEntriesPath) {
     try {
         const raw = JSON.parse(fs.readFileSync(manualEntriesPath, "utf8"));
-        const candidateKits = Array.isArray(raw) ? raw : asRecord(raw).kits;
-        const parsed = parseRegistryIndex({ version: 2, updatedAt: new Date().toISOString(), kits: candidateKits });
+        const candidateKits = Array.isArray(raw) ? raw : asRecord(raw).stashes;
+        const parsed = parseRegistryIndex({ version: 3, updatedAt: new Date().toISOString(), stashes: candidateKits });
         if (!parsed)
             return [];
-        return parsed.kits.map((kit) => normalizeKit({ ...kit, curated: kit.curated ?? true }));
+        return parsed.stashes.map((stash) => normalizeStash({ ...stash, curated: stash.curated ?? true }));
     }
     catch {
         return [];
     }
 }
+// npm / GitHub API JSON pages; 25 MB cap covers the largest realistic
+// search result set while still bounding memory against a malicious or
+// misconfigured upstream that streams unbounded JSON.
+const BUILD_INDEX_JSON_BYTE_CAP = 25 * 1024 * 1024;
 async function fetchJson(url, headers) {
     const response = await fetchWithRetry(url, headers ? { headers } : undefined, { timeout: 30_000 });
     if (!response.ok) {
+        // Error-body sampling is intentionally small; 4 KB is plenty to
+        // include upstream hints in the thrown error.
         const body = await response.text().catch(() => "");
         throw new Error(`HTTP ${response.status} from ${url}: ${body.slice(0, 200)}`);
     }
-    return (await response.json());
+    return jsonWithByteCap(response, BUILD_INDEX_JSON_BYTE_CAP);
 }
-function deduplicateKits(kits) {
+function deduplicateStashes(stashes) {
     const byId = new Map();
-    for (const kit of kits) {
-        const existing = byId.get(kit.id);
-        byId.set(kit.id, existing ? mergeEntries(existing, kit) : kit);
+    for (const stash of stashes) {
+        const existing = byId.get(stash.id);
+        byId.set(stash.id, existing ? mergeEntries(existing, stash) : stash);
     }
     return [...byId.values()];
 }
 function mergeEntries(a, b) {
     const assets = mergeAssets(a.assets, b.assets);
     const assetTypes = mergeStrings(a.assetTypes, b.assetTypes, assets ? deriveAssetTypes(assets) : undefined);
-    return normalizeKit({
+    return normalizeStash({
         id: a.id,
         name: a.name,
         description: a.description ?? b.description,
@@ -343,12 +359,12 @@ function extractNonReservedKeywords(value) {
         .filter((item) => !REQUIRED_KEYWORDS.includes(item.toLowerCase()));
     return filtered.length > 0 ? filtered : undefined;
 }
-function normalizeKit(kit) {
-    const assets = kit.assets ? sortAssets(kit.assets) : undefined;
+function normalizeStash(stash) {
+    const assets = stash.assets ? sortAssets(stash.assets) : undefined;
     return {
-        ...kit,
-        ...(kit.tags && kit.tags.length > 0 ? { tags: kit.tags } : {}),
-        ...(kit.assetTypes && kit.assetTypes.length > 0 ? { assetTypes: kit.assetTypes } : {}),
+        ...stash,
+        ...(stash.tags && stash.tags.length > 0 ? { tags: stash.tags } : {}),
+        ...(stash.assetTypes && stash.assetTypes.length > 0 ? { assetTypes: stash.assetTypes } : {}),
         ...(assets && assets.length > 0 ? { assets } : {}),
     };
 }

package/dist/{create-provider-registry.js → registry/create-provider-registry.js}

@@ -2,8 +2,8 @@
  * Generic factory-map utility.
  *
  * Creates a lightweight registry that maps string keys to factory functions.
- * Both registry-factory.ts (kit discovery) and stash-provider-factory.ts
- * (stash source providers) are built on this utility.
+ * Both registry/factory.ts (registry discovery) and sources/provider-factory.ts
+ * (source providers) are built on this utility.
  */
 export function createProviderRegistry() {
     const map = new Map();
@@ -14,5 +14,9 @@ export function createProviderRegistry() {
         resolve(type) {
             return map.get(type) ?? null;
         },
+        /** Snapshot of all registered keys. Iteration order matches insertion order. */
+        list() {
+            return [...map.keys()];
+        },
     };
 }

package/dist/registry/factory.js

@@ -0,0 +1,33 @@
+/**
+ * Registry provider factory map.
+ *
+ * Maps registry provider type identifiers (e.g. "static-index", "skills-sh")
+ * to factory functions that create RegistryProvider instances.
+ *
+ * "Registry" here refers to the kit discovery registries (static index files,
+ * skills.sh API) — not to be confused with the source provider factory map in
+ * `sources/provider-factory.ts` or the installed-source operations in
+ * `installed-stashes.ts`.
+ *
+ * Phase 6 (v1 architecture refactor): factories are now the
+ * `RegistryProviderFactory` type owned by `src/registry/providers/types.ts`.
+ * The legacy alias in `src/registry-provider.ts` is kept as a thin re-export
+ * for transitional callers and will be removed after the dust settles.
+ */
+import { createProviderRegistry } from "./create-provider-registry";
+// ── Factory map ─────────────────────────────────────────────────────────────
+const registry = createProviderRegistry();
+export function registerProvider(type, factory) {
+    registry.register(type, factory);
+}
+export function resolveProviderFactory(type) {
+    return registry.resolve(type);
+}
+/**
+ * Iterate over all registered registry providers. Used by the orchestrator
+ * (`src/commands/registry-search.ts`) to fan out queries through the same
+ * `RegistryProvider` interface regardless of provider kind.
+ */
+export function listProviderTypes() {
+    return registry.list();
+}

package/dist/{origin-resolve.js → registry/origin-resolve.js}

@@ -1,5 +1,5 @@
 import path from "node:path";
-import { parseRegistryRef } from "./registry-resolve";
+import { parseRegistryRef } from "./resolve";
 /**
  * Given an origin string (from an AssetRef) and the full list of stash
  * sources, return the subset of sources to search.

package/dist/registry/providers/index.js

@@ -0,0 +1,11 @@
+/**
+ * Centralized registry provider registration.
+ *
+ * Import this module (side-effect import) to register all built-in registry
+ * providers with the provider registry. This replaces the individual
+ * side-effect imports that were duplicated in registry-search.ts.
+ *
+ * Mirrors the pattern used by `sources/providers/index.ts`.
+ */
+import "./static-index";
+import "./skills-sh";

package/dist/{providers → registry/providers}/skills-sh.js

@@ -1,8 +1,8 @@
 import fs from "node:fs";
 import path from "node:path";
-import { fetchWithRetry } from "../common";
-import { getRegistryIndexCacheDir } from "../paths";
-import { registerProvider } from "../registry-factory";
+import { fetchWithRetry } from "../../core/common";
+import { getRegistryIndexCacheDir } from "../../core/paths";
+import { registerProvider } from "../factory";
 // ── Constants ───────────────────────────────────────────────────────────────
 /** Per-query cache TTL in milliseconds (15 minutes). */
 const QUERY_CACHE_TTL_MS = 15 * 60 * 1000;
@@ -32,6 +32,62 @@ class SkillsShProvider {
             return { hits: [], warnings: [`Registry ${label}: ${message}`] };
         }
     }
+    // ── v1-spec §3.1 surface ────────────────────────────────────────────────
+    async searchKits(q) {
+        const result = await this.search({
+            query: q.text,
+            limit: q.limit ?? 20,
+            includeAssets: false,
+        });
+        return result.hits.map((hit) => ({
+            id: hit.id,
+            title: hit.title,
+            summary: hit.description,
+            installRef: hit.installRef,
+            score: hit.score,
+        }));
+    }
+    async searchAssets(q) {
+        const result = await this.search({
+            query: q.text,
+            limit: q.limit ?? 20,
+            includeAssets: true,
+        });
+        return (result.assetHits ?? []).map((hit) => ({
+            kitId: hit.stash.id,
+            type: hit.assetType,
+            name: hit.assetName,
+            summary: hit.description,
+            cloneRef: hit.action.replace(/^akm add\s+/, ""),
+        }));
+    }
+    /**
+     * skills.sh has no `getKit` API — every entry corresponds to a GitHub
+     * repository whose metadata we already include in the search result. We
+     * synthesize a manifest from the search hit when the caller knows the kit
+     * id; if not present in the most recent results, return null.
+     */
+    async getKit(id) {
+        if (!id.startsWith("skills-sh:"))
+            return null;
+        const slug = id.slice("skills-sh:".length);
+        // Best-effort: the API gives us search-by-name; extract the leaf segment.
+        const segments = slug.split("/").filter(Boolean);
+        const leaf = segments[segments.length - 1] ?? slug;
+        const result = await this.search({ query: leaf, limit: 50, includeAssets: false });
+        const match = result.hits.find((hit) => hit.id === id);
+        if (!match)
+            return null;
+        return { id: match.id, installRef: match.installRef };
+    }
+    /**
+     * skills.sh entries are always GitHub repositories. Claim only refs whose
+     * parsed source is `github`; defer everything else (npm tarballs, local
+     * paths, raw git URLs) to other registries.
+     */
+    canHandle(ref) {
+        return ref.source === "github";
+    }
     async fetchSkills(query, limit) {
         // Check per-query cache first
         const cachePath = this.queryCachePath(query, limit);
@@ -103,7 +159,7 @@ class SkillsShProvider {
                 type: "registry-asset",
                 assetType: "skill",
                 assetName: entry.name,
-                kit: { id: `skills-sh:${entry.id}`, name: entry.name },
+                stash: { id: `skills-sh:${entry.id}`, name: entry.name },
                 registryName,
                 action: `akm add github:${ownerRepo}`,
                 score: Math.round((entry.installs / maxInstalls) * 1000) / 1000,

package/dist/{providers → registry/providers}/static-index.js

@@ -1,9 +1,9 @@
 import fs from "node:fs";
 import path from "node:path";
-import { fetchWithRetry, toErrorMessage } from "../common";
-import { asString } from "../github";
-import { getRegistryIndexCacheDir } from "../paths";
-import { registerProvider } from "../registry-factory";
+import { fetchWithRetry, jsonWithByteCap, toErrorMessage } from "../../core/common";
+import { getRegistryIndexCacheDir } from "../../core/paths";
+import { asString } from "../../integrations/github";
+import { registerProvider } from "../factory";
 // ── Constants ───────────────────────────────────────────────────────────────
 /** Cache TTL in milliseconds (1 hour). */
 const CACHE_TTL_MS = 60 * 60 * 1000;
@@ -18,13 +18,70 @@ class StaticIndexProvider {
     }
     async search(options) {
         const warnings = [];
+        const allKits = await this.loadAllKits(warnings);
+        const hits = scoreKits(allKits, options.query, options.limit);
+        let assetHits;
+        if (options.includeAssets) {
+            const scored = scoreAssets(allKits, options.query, options.limit);
+            if (scored.length > 0)
+                assetHits = scored;
+        }
+        return { hits, assetHits, warnings: warnings.length > 0 ? warnings : undefined };
+    }
+    // ── v1-spec §3.1 surface ────────────────────────────────────────────────
+    async searchKits(q) {
+        const result = await this.search({
+            query: q.text,
+            limit: q.limit ?? 20,
+            includeAssets: false,
+        });
+        return result.hits.map(hitToKitResult);
+    }
+    async searchAssets(q) {
+        const result = await this.search({
+            query: q.text,
+            limit: q.limit ?? 20,
+            includeAssets: true,
+        });
+        return (result.assetHits ?? []).map(assetHitToPreview);
+    }
+    async getKit(id) {
+        const allKits = await this.loadAllKits([]);
+        const found = allKits.find(({ stash }) => stash.id === id);
+        if (!found)
+            return null;
+        const installRef = buildInstallRef(found.stash.source, found.stash.ref);
+        return {
+            id: found.stash.id,
+            installRef,
+            assets: found.stash.assets?.map((asset) => ({
+                kitId: found.stash.id,
+                type: asset.type,
+                name: asset.name,
+                summary: asset.description,
+                cloneRef: installRef,
+            })),
+        };
+    }
+    /**
+     * Static-index doesn't own a URL prefix — any `ParsedRegistryRef` could
+     * theoretically be backed by an entry in some static-index registry. We
+     * therefore claim every ref. The orchestrator picks the first matching
+     * provider, and `static-index` is registered first by `index.ts`, so this
+     * is effectively the default catch-all.
+     */
+    canHandle(_ref) {
+        return true;
+    }
+    // ── Internals ───────────────────────────────────────────────────────────
+    async loadAllKits(warnings) {
         const allKits = [];
         try {
             const index = await loadIndex(this.config);
             if (index) {
                 const regName = this.config.name;
-                for (const kit of index.kits) {
-                    allKits.push({ kit, registryName: regName });
+                for (const stash of index.stashes) {
+                    allKits.push({ stash, registryName: regName });
                 }
             }
         }
@@ -32,16 +89,27 @@ class StaticIndexProvider {
             const label = this.config.name ? `${this.config.name} (${this.config.url})` : this.config.url;
             warnings.push(`Registry ${label}: ${toErrorMessage(err)}`);
         }
-        const hits = scoreKits(allKits, options.query, options.limit);
-        let assetHits;
-        if (options.includeAssets) {
-            const scored = scoreAssets(allKits, options.query, options.limit);
-            if (scored.length > 0)
-                assetHits = scored;
-        }
-        return { hits, assetHits, warnings: warnings.length > 0 ? warnings : undefined };
+        return allKits;
     }
 }
+function hitToKitResult(hit) {
+    return {
+        id: hit.id,
+        title: hit.title,
+        summary: hit.description,
+        installRef: hit.installRef,
+        score: hit.score,
+    };
+}
+function assetHitToPreview(hit) {
+    return {
+        kitId: hit.stash.id,
+        type: hit.assetType,
+        name: hit.assetName,
+        summary: hit.description,
+        cloneRef: hit.action.replace(/^akm add\s+/, ""),
+    };
+}
 // ── Self-register ───────────────────────────────────────────────────────────
 registerProvider("static-index", (config) => new StaticIndexProvider(config));
 // ── Index loading with cache ────────────────────────────────────────────────
@@ -58,7 +126,9 @@ async function loadIndex(entry) {
         if (!response.ok) {
             throw new Error(`HTTP ${response.status}`);
         }
-        const data = (await response.json());
+        // Cap at 50 MB — registry indexes can grow large but unbounded
+        // responses from a compromised server would OOM us.
+        const data = await jsonWithByteCap(response, 50 * 1024 * 1024);
         const index = parseRegistryIndex(data);
         if (index) {
             writeCachedIndex(cachePath, index);
@@ -120,20 +190,20 @@ export function parseRegistryIndex(data) {
     if (typeof data !== "object" || data === null || Array.isArray(data))
         return null;
     const obj = data;
-    if (typeof obj.version !== "number" || (obj.version !== 1 && obj.version !== 2))
+    if (typeof obj.version !== "number" || obj.version !== 3)
         return null;
     if (typeof obj.updatedAt !== "string")
         return null;
-    if (!Array.isArray(obj.kits))
+    if (!Array.isArray(obj.stashes))
         return null;
-    const kits = obj.kits.flatMap((raw) => {
-        const kit = parseKitEntry(raw);
-        return kit ? [kit] : [];
+    const stashes = obj.stashes.flatMap((raw) => {
+        const stash = parseStashEntry(raw);
+        return stash ? [stash] : [];
     });
-    return { version: obj.version, updatedAt: obj.updatedAt, kits };
+    return { version: obj.version, updatedAt: obj.updatedAt, stashes };
 }
-// ── Kit entry parsing ───────────────────────────────────────────────────────
-function parseKitEntry(raw) {
+// ── Stash entry parsing ───────────────────────────────────────────────────────
+function parseStashEntry(raw) {
     if (typeof raw !== "object" || raw === null || Array.isArray(raw))
         return null;
     const obj = raw;
@@ -160,23 +230,23 @@ function parseKitEntry(raw) {
     };
 }
 // ── Scoring ─────────────────────────────────────────────────────────────────
-function scoreKits(kits, query, limit) {
+function scoreKits(stashes, query, limit) {
     const tokens = query.toLowerCase().split(/\s+/).filter(Boolean);
     const scored = [];
-    for (const { kit, registryName } of kits) {
-        const score = scoreKit(kit, tokens);
+    for (const { stash, registryName } of stashes) {
+        const score = scoreStash(stash, tokens);
         if (score > 0) {
-            scored.push({ kit, registryName, score });
+            scored.push({ stash, registryName, score });
         }
     }
     scored.sort((a, b) => b.score - a.score);
-    return scored.slice(0, limit).map(({ kit, registryName, score }) => toSearchHit(kit, score, registryName));
+    return scored.slice(0, limit).map(({ stash, registryName, score }) => toSearchHit(stash, score, registryName));
 }
-function scoreKit(kit, tokens) {
+function scoreStash(stash, tokens) {
     let score = 0;
-    const nameLower = kit.name.toLowerCase();
-    const descLower = (kit.description ?? "").toLowerCase();
-    const tagsLower = (kit.tags ?? []).map((t) => t.toLowerCase());
+    const nameLower = stash.name.toLowerCase();
+    const descLower = (stash.description ?? "").toLowerCase();
+    const tagsLower = (stash.tags ?? []).map((t) => t.toLowerCase());
     for (const token of tokens) {
         // Exact name match is strongest signal
         if (nameLower === token) {
@@ -197,34 +267,34 @@ function scoreKit(kit, tokens) {
             score += 0.2;
         }
         // Author match
-        if (kit.author?.toLowerCase().includes(token)) {
+        if (stash.author?.toLowerCase().includes(token)) {
             score += 0.15;
         }
     }
     // Normalize by token count so multi-word queries don't inflate scores
     return tokens.length > 0 ? score / tokens.length : 0;
 }
-function toSearchHit(kit, score, registryName) {
+function toSearchHit(stash, score, registryName) {
     const metadata = {};
-    if (kit.latestVersion)
-        metadata.version = kit.latestVersion;
-    if (kit.author)
-        metadata.author = kit.author;
-    if (kit.license)
-        metadata.license = kit.license;
-    if (kit.assetTypes?.length)
-        metadata.assetTypes = kit.assetTypes.join(", ");
+    if (stash.latestVersion)
+        metadata.version = stash.latestVersion;
+    if (stash.author)
+        metadata.author = stash.author;
+    if (stash.license)
+        metadata.license = stash.license;
+    if (stash.assetTypes?.length)
+        metadata.assetTypes = stash.assetTypes.join(", ");
     return {
-        source: kit.source,
-        id: kit.id,
-        title: kit.name,
-        description: kit.description,
-        ref: kit.ref,
-        installRef: buildInstallRef(kit.source, kit.ref),
-        homepage: kit.homepage,
+        source: stash.source,
+        id: stash.id,
+        title: stash.name,
+        description: stash.description,
+        ref: stash.ref,
+        installRef: buildInstallRef(stash.source, stash.ref),
+        homepage: stash.homepage,
         score: Math.round(score * 1000) / 1000,
         metadata,
-        curated: kit.curated,
+        curated: stash.curated,
         registryName,
     };
 }
@@ -255,16 +325,16 @@ function parseAssetEntry(raw) {
     };
 }
 // ── Asset-level scoring ─────────────────────────────────────────────────────
-function scoreAssets(kits, query, limit) {
+function scoreAssets(stashes, query, limit) {
     const tokens = query.toLowerCase().split(/\s+/).filter(Boolean);
     if (tokens.length === 0)
         return [];
     const scored = [];
-    for (const { kit, registryName } of kits) {
-        if (!kit.assets || kit.assets.length === 0)
+    for (const { stash, registryName } of stashes) {
+        if (!stash.assets || stash.assets.length === 0)
             continue;
-        const installRef = buildInstallRef(kit.source, kit.ref);
-        for (const asset of kit.assets) {
+        const installRef = buildInstallRef(stash.source, stash.ref);
+        for (const asset of stash.assets) {
             const score = scoreAsset(asset, tokens);
             if (score > 0) {
                 scored.push({
@@ -274,7 +344,7 @@ function scoreAssets(kits, query, limit) {
                         assetName: asset.name,
                         description: asset.description,
                         estimatedTokens: asset.estimatedTokens,
-                        kit: { id: kit.id, name: kit.name },
+                        stash: { id: stash.id, name: stash.name },
                         registryName,
                         action: `akm add ${installRef}`,
                         score: Math.round(score * 1000) / 1000,

package/dist/registry/providers/types.js

@@ -0,0 +1,25 @@
+/**
+ * Registry provider interface (v1 architecture spec §3.1).
+ *
+ * A `RegistryProvider` is a read-only catalog that lists installable kits and
+ * (optionally) previews assets within them. It is *not* a `SourceProvider`:
+ * registry providers do not materialise files to disk — they only answer
+ * discovery queries.
+ *
+ * The two built-in registry providers at v1 are:
+ *
+ * - `static-index` — reads the v2 JSON index schema (the official akm registry
+ *   and any static-hosted team registry). The v2 schema is owned by this
+ *   provider, not by core akm.
+ * - `skills-sh` — wraps the skills.sh REST API.
+ *
+ * Context Hub is **not** a registry provider — it is an ordinary git repository
+ * recommended via the official static-index registry (see CLAUDE.md).
+ *
+ * Note: the simple `search()` method is the v0.6 surface and remains the
+ * primary entry point used by the orchestrator. The `searchKits` /
+ * `searchAssets` / `getKit` / `canHandle` methods are the v1-spec contract
+ * (§3.1) which built-in providers also implement so the orchestrator can be
+ * iterated cleanly post-Phase 6 without reaching into provider-specific shapes.
+ */
+export {};