akm-cli 0.9.0-rc.8 → 0.9.0

package/dist/output/text/workflow-format.js

@@ -5,58 +5,22 @@
  * Plain-text renderers for `akm workflow *` commands.
  *
  * Split out of `helpers.ts` (formerly 1418 lines / 59 fns) as its own
- * sibling module: the workflow run/step/status/brief renderers form a
+ * sibling module: the workflow list/status/run/create/resume renderers form a
  * cohesive, self-contained cluster (they call only each other, never
  * formatters from other domains).
  */
-export function formatWorkflowValidatePlain(r) {
-    const ok = r.ok !== false;
-    const pathValue = String(r.path ?? "?");
-    if (!ok)
-        return `workflow validate: failed (${pathValue})`;
-    const title = typeof r.title === "string" ? r.title : "";
-    const stepCount = typeof r.stepCount === "number" ? r.stepCount : 0;
-    const lines = [`workflow validate: ok — ${title || pathValue} (${stepCount} step(s))`];
-    // Non-fatal advisories: clearly marked, printed after the ok line so `ok`
-    // is never in doubt. Absent/empty for markdown and fully-typed programs.
-    const warnings = Array.isArray(r.warnings) ? r.warnings : [];
-    if (warnings.length > 0) {
-        lines.push(`  ${warnings.length} warning(s):`);
-        for (const w of warnings) {
-            const line = typeof w.line === "number" ? w.line : "?";
-            lines.push(`    warning: ${pathValue}:${line} — ${String(w.message ?? "")}`);
-        }
-    }
-    return lines.join("\n");
-}
-/**
- * Plain-text rendering for a step-completion that was rejected by the
- * summary-validation gate (#506): the step stays pending and the agent gets
- * corrective feedback on what to finish/fix.
- */
-export function formatWorkflowCompleteRejectedPlain(r) {
-    const stepId = String(r.stepId ?? "?");
-    const feedback = typeof r.feedback === "string" ? r.feedback : "";
-    const missing = Array.isArray(r.missing) ? r.missing.map((m) => String(m)) : [];
-    const lines = [`workflow complete: rejected — step "${stepId}" does not meet its completion criteria`];
-    if (feedback)
-        lines.push(`  feedback: ${feedback}`);
-    if (missing.length > 0) {
-        lines.push("  outstanding:");
-        for (const m of missing)
-            lines.push(`    - ${m}`);
-    }
-    return lines.join("\n");
-}
 export function formatWorkflowListPlain(result) {
     const runs = Array.isArray(result.runs) ? result.runs : [];
     if (runs.length === 0) {
-        return "No workflow runs in the current working scope. Start one with `akm workflow next workflows/<name>` or author one with `akm workflow create <name>`.";
+        return "No workflow runs in the current working scope. Start one with `akm workflow run workflows/<name>` or author one with `akm workflow create <name>`.";
     }
     return runs
         .map((run) => {
         const id = typeof run.id === "string" ? run.id : "unknown";
-        const ref = typeof run.workflowRef === "string" ? run.workflowRef : "workflow:unknown";
+        // Fallback matches the `id`/`status` convention just below (plain
+        // "unknown", not a `type:name`-shaped placeholder — that shape reads as
+        // a ref in the dead colon grammar, which this fallback must not model).
+        const ref = typeof run.workflowRef === "string" ? run.workflowRef : "unknown";
         const status = typeof run.status === "string" ? run.status : "unknown";
         const currentStep = typeof run.currentStepId === "string" ? ` (current: ${run.currentStepId})` : "";
         return `${id} ${ref} [${status}]${currentStep}`;
@@ -71,7 +35,7 @@ export function formatWorkflowStatusPlain(result) {
     if (!run || !workflow)
         return null;
     const lines = [
-        `workflow: ${String(workflow.ref ?? "workflow:unknown")}`,
+        `workflow: ${String(workflow.ref ?? "unknown")}`,
         `run: ${String(run.id ?? "unknown")}`,
         `title: ${String(run.workflowTitle ?? workflow.title ?? "Workflow")}`,
         `status: ${String(run.status ?? "unknown")}`,
@@ -106,8 +70,8 @@ export function formatWorkflowStatusPlain(result) {
             const suffix = attempts !== undefined && attempts > 1 ? `, attempt ${attempts}` : "";
             lines.push(`  - ${id} [${node}] (${status}${suffix})`);
             // Codex round-3 finding B: a `running` claim gone silent past the check-in
-            // window — the driver likely died. Surface it (with the claim holder) so a
-            // human can reclaim/re-run the unit, matching what `brief` reports.
+            // window — the process holding it likely died. Surface it (with the claim
+            // holder) so a human can reclaim/re-run the unit.
             if (unit.stale === true) {
                 const holder = typeof unit.claimHolder === "string" && unit.claimHolder.trim() ? ` claimed by ${unit.claimHolder}` : "";
                 lines.push(`    stale: claim went silent past the check-in window${holder} — its driver may have died`);
@@ -134,7 +98,7 @@ export function formatWorkflowStatusPlain(result) {
 }
 /**
  * Render the stalled-run check-in directive (#506) when present on a
- * workflow-next/status result. Returns null when the run is healthy.
+ * workflow-status result. Returns null when the run is healthy.
  */
 function formatWorkflowCheckinLine(result) {
     const checkin = typeof result.checkin === "object" && result.checkin !== null
@@ -144,52 +108,16 @@ function formatWorkflowCheckinLine(result) {
         return null;
     return checkin.directive.trim();
 }
-export function formatWorkflowNextPlain(result) {
-    const base = formatWorkflowStatusPlain(result);
-    const step = typeof result.step === "object" && result.step !== null ? result.step : undefined;
-    if (!step)
-        return base;
-    const lines = base ? [base, "", "next:"] : ["next:"];
-    lines.push(`  ${String(step.title ?? "Untitled step")} [${String(step.id ?? "unknown")}]`);
-    if (typeof step.instructions === "string" && step.instructions.trim()) {
-        const instrLines = step.instructions.trim().split("\n");
-        lines.push(`  instructions: ${instrLines[0]}`);
-        for (const instrLine of instrLines.slice(1))
-            lines.push(`    ${instrLine}`);
-    }
-    const completion = Array.isArray(step.completionCriteria) ? step.completionCriteria : [];
-    if (completion.length > 0) {
-        lines.push("  completion:");
-        for (const criterion of completion) {
-            lines.push(`    - ${String(criterion)}`);
-        }
-    }
-    // T2-3: surface run-id as labeled field
-    const run = typeof result.run === "object" && result.run !== null ? result.run : undefined;
-    const runId = typeof run?.id === "string" ? run.id : null;
-    const stepId = typeof step?.id === "string" ? step.id : null;
-    if (runId) {
-        lines.push("");
-        lines.push(`runId: ${runId}`);
-    }
-    // T1-6: complete command
-    if (runId && stepId) {
-        lines.push("");
-        lines.push("COMPLETE THIS STEP:");
-        lines.push(`  akm workflow complete '${runId}' --step '${stepId}'`);
-    }
-    else if (runId) {
-        lines.push("");
-        lines.push("COMPLETE THIS STEP:");
-        lines.push(`  akm workflow complete '${runId}' --step '<step-id>'`);
-    }
-    return lines.join("\n");
-}
 export function formatWorkflowRunPlain(result) {
     const run = typeof result.run === "object" && result.run !== null ? result.run : undefined;
     if (!run)
         return null;
     const lines = [`run: ${String(run.id ?? "unknown")}`, `status: ${String(run.status ?? "unknown")}`];
+    // Creation-time notices (e.g. the implicit engine fallback) must survive the
+    // text renderer: JSON/YAML pass them through, and dropping them here would
+    // hide the announcement from the DEFAULT output mode — where it matters most.
+    for (const warning of Array.isArray(result.warnings) ? result.warnings : [])
+        lines.push(`! ${String(warning)}`);
     const executed = Array.isArray(result.executed) ? result.executed : [];
     if (executed.length === 0) {
         lines.push("executed: (no steps — run was already done or blocked)");
@@ -214,127 +142,20 @@ export function formatWorkflowRunPlain(result) {
         for (const item of missing)
             lines.push(`  missing: ${String(item)}`);
     }
+    if (result.aborted === true) {
+        lines.push(result.timedOut === true
+            ? "workflow timed out; the run remains resumable."
+            : "workflow interrupted; the run remains resumable.");
+    }
     if (result.done === true)
         lines.push("workflow completed.");
     return lines.join("\n");
 }
-export function formatWorkflowBriefPlain(result) {
-    const run = typeof result.run === "object" && result.run !== null ? result.run : undefined;
-    if (!run)
-        return null;
-    const lines = [];
-    lines.push(`# Workflow brief: ${String(run.id ?? "unknown")}`);
-    lines.push(`workflow: ${String(run.workflowRef ?? "?")}  (${String(run.workflowTitle ?? "")})`);
-    lines.push(`status: ${String(run.status ?? "?")}`);
-    if (typeof result.message === "string")
-        lines.push(result.message);
-    const lease = typeof result.engineLease === "object" && result.engineLease !== null
-        ? result.engineLease
-        : undefined;
-    if (lease) {
-        const live = lease.live === true ? "LIVE" : "expired";
-        lines.push(`engine lease: ${String(lease.holder ?? "?")} (until ${String(lease.until ?? "?")}) [${live}]`);
-    }
-    const warnings = Array.isArray(result.warnings) ? result.warnings : [];
-    for (const w of warnings)
-        lines.push(`! ${String(w)}`);
-    if (result.done === true) {
-        lines.push("");
-        lines.push("This run is completed — no work remains.");
-        return lines.join("\n");
-    }
-    const step = typeof result.step === "object" && result.step !== null ? result.step : undefined;
-    if (!step) {
-        return lines.join("\n");
-    }
-    const gate = typeof step.gate === "object" && step.gate !== null ? step.gate : undefined;
-    lines.push("");
-    lines.push(`## Active step: ${String(step.stepId ?? "?")} — ${String(step.title ?? "")}  [${String(step.kind ?? "execute")}]`);
-    if (gate) {
-        const criteria = Array.isArray(gate.criteria) ? gate.criteria : [];
-        lines.push(`gate: loop ${String(gate.currentLoop ?? 1)} of max ${String(gate.maxLoops ?? 1)}` +
-            (criteria.length > 0 ? `; criteria: ${criteria.map(String).join("; ")}` : "; no completion criteria") +
-            (gate.judgesArtifact === true ? " (artifact-judged)" : ""));
-    }
-    if (step.outputSchema !== undefined)
-        lines.push("outputSchema: declared (see JSON output)");
-    const feedback = typeof result.gateFeedback === "object" && result.gateFeedback !== null
-        ? result.gateFeedback
-        : undefined;
-    if (feedback) {
-        lines.push(`gate feedback (previous loop rejected): ${String(feedback.feedback ?? "")}`);
-        const missing = Array.isArray(feedback.missing) ? feedback.missing : [];
-        for (const m of missing)
-            lines.push(`  - missing: ${String(m)}`);
-    }
-    const route = typeof result.route === "object" && result.route !== null ? result.route : undefined;
-    if (route) {
-        lines.push("");
-        lines.push(`## Route contract on ${String(route.input ?? "?")}`);
-        const when = typeof route.when === "object" && route.when !== null ? route.when : {};
-        for (const [value, target] of Object.entries(when))
-            lines.push(`  when "${value}" → ${String(target)}`);
-        if (route.defaultStepId !== undefined)
-            lines.push(`  default → ${String(route.defaultStepId)}`);
-        const decision = typeof route.decision === "object" && route.decision !== null
-            ? route.decision
-            : undefined;
-        if (decision)
-            lines.push(`  decision NOW: value "${String(decision.value)}" → ${String(decision.selected)}`);
-        else if (typeof route.decisionError === "string")
-            lines.push(`  decision error: ${route.decisionError}`);
-        else
-            lines.push("  decision: pending this step's output (evaluated after units complete)");
-    }
-    const workList = typeof result.workList === "object" && result.workList !== null
-        ? result.workList
-        : undefined;
-    const units = workList && Array.isArray(workList.units) ? workList.units : [];
-    if (workList?.error) {
-        lines.push("");
-        lines.push(`work-list error: ${String(workList.error)}`);
-    }
-    else if (units.length > 0) {
-        lines.push("");
-        lines.push(`## Units (${units.length})`);
-        for (const u of units) {
-            const model = u.model ? ` model=${String(u.model)}` : "";
-            const journaled = typeof u.journaled === "object" && u.journaled !== null ? u.journaled : undefined;
-            const jstatus = journaled ? ` [journaled: ${String(journaled.status)}]` : "";
-            lines.push(`- ${String(u.unitId)}  (runner=${String(u.runner)}${model})${jstatus}`);
-            const env = Array.isArray(u.env) ? u.env : [];
-            if (env.length > 0)
-                lines.push(`    env (names): ${env.map(String).join(", ")}`);
-            if (u.outputSchema !== undefined)
-                lines.push("    outputSchema: declared (see JSON output)");
-            const resolved = typeof u.resolved === "object" && u.resolved !== null ? u.resolved : undefined;
-            if (resolved && resolved.ok === false)
-                lines.push(`    RESOLUTION ERROR: ${String(resolved.error)}`);
-            if (typeof u.report === "string")
-                lines.push(`    report: ${u.report}`);
-        }
-    }
-    // Finding D: a non-dispatching step (route-only / empty / all-unresolvable)
-    // advances via the `--settle` verb, surfaced so a driver can advance the spine.
-    if (typeof result.settleCommand === "string") {
-        lines.push("");
-        lines.push("## Advance (no reportable units)");
-        lines.push(`settle: ${result.settleCommand}`);
-    }
-    const guidance = typeof result.reportGuidance === "object" && result.reportGuidance !== null
-        ? result.reportGuidance
-        : undefined;
-    if (guidance) {
-        lines.push("");
-        lines.push("## Reporting");
-        if (typeof guidance.checkin === "string")
-            lines.push(`heartbeat: ${guidance.checkin}`);
-        if (typeof guidance.failure === "string")
-            lines.push(`on failure: ${guidance.failure}`);
-    }
-    return lines.join("\n");
-}
 export function formatWorkflowCreatePlain(r) {
+    // `workflow create --print`: no file is written, just the template text
+    // (dropped `workflow template`'s output, moved onto this shape).
+    if (typeof r.template === "string")
+        return r.template;
     if (r.ref && r.path) {
         return `Created ${String(r.ref)} at ${String(r.path)}`;
     }

package/dist/output/text/workflow.js

@@ -2,18 +2,12 @@
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 // Output text formatters for all `akm workflow *` commands.
-import { formatWorkflowBriefPlain, formatWorkflowCompleteRejectedPlain, formatWorkflowCreatePlain, formatWorkflowListPlain, formatWorkflowNextPlain, formatWorkflowResumePlain, formatWorkflowRunPlain, formatWorkflowStatusPlain, formatWorkflowValidatePlain, } from "./helpers.js";
+import { formatWorkflowCreatePlain, formatWorkflowListPlain, formatWorkflowResumePlain, formatWorkflowRunPlain, formatWorkflowStatusPlain, } from "./helpers.js";
 export const workflowFormatters = [
-    { command: "workflow-start", handler: (r) => formatWorkflowStatusPlain(r) },
     { command: "workflow-status", handler: (r) => formatWorkflowStatusPlain(r) },
-    { command: "workflow-complete", handler: (r) => formatWorkflowStatusPlain(r) },
-    { command: "workflow-complete-rejected", handler: (r) => formatWorkflowCompleteRejectedPlain(r) },
-    { command: "workflow-next", handler: (r) => formatWorkflowNextPlain(r) },
     { command: "workflow-list", handler: (r) => formatWorkflowListPlain(r) },
     { command: "workflow-create", handler: (r) => formatWorkflowCreatePlain(r) },
-    { command: "workflow-validate", handler: (r) => formatWorkflowValidatePlain(r) },
     { command: "workflow-resume", handler: (r) => formatWorkflowResumePlain(r) },
     { command: "workflow-abandon", handler: (r) => formatWorkflowStatusPlain(r) },
     { command: "workflow-run", handler: (r) => formatWorkflowRunPlain(r) },
-    { command: "workflow-brief", handler: (r) => formatWorkflowBriefPlain(r) },
 ];

package/dist/output/text.js

@@ -2,37 +2,33 @@
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import { addFormatters } from "./text/add.js";
+import { bundleCreateFormatters } from "./text/bundle-create.js";
+import { bundleShowFormatters } from "./text/bundle-show.js";
 import { cloneFormatters } from "./text/clone.js";
 import { configFormatters } from "./text/config.js";
 import { curateFormatters } from "./text/curate.js";
-import { distillFormatters } from "./text/distill.js";
-import { enableDisableFormatters } from "./text/enable-disable.js";
 import { envFormatters } from "./text/env.js";
 import { eventsFormatters } from "./text/events.js";
 import { feedbackFormatters } from "./text/feedback.js";
-import { historyFormatters } from "./text/history.js";
+import { healthFormatters } from "./text/health.js";
 import { importFormatters } from "./text/import.js";
 import { indexFormatters } from "./text/index.js";
 import { infoFormatters } from "./text/info.js";
-import { initFormatters } from "./text/init.js";
+import { lintFormatters } from "./text/lint.js";
 import { listFormatters } from "./text/list.js";
+import { migrateFormatters } from "./text/migrate.js";
 import { proposalProducerFormatters } from "./text/proposal/producer.js";
 import { proposalFormatters } from "./text/proposal/proposal.js";
 import { getTextFormatterHandler, registerTextFormatters } from "./text/registry.js";
 import { registryCommandFormatters } from "./text/registry-commands.js";
 import { rememberFormatters } from "./text/remember.js";
 import { removeFormatters } from "./text/remove.js";
-import { saveFormatters } from "./text/save.js";
 import { searchFormatters } from "./text/search.js";
 import { showFormatters } from "./text/show.js";
+import { syncFormatters } from "./text/sync.js";
 import { updateFormatters } from "./text/update.js";
 import { upgradeFormatters } from "./text/upgrade.js";
 import { workflowFormatters } from "./text/workflow.js";
-// Re-export helpers so existing imports from `text.ts` keep working.
-export { formatAddPlain, formatClonePlain, formatConfigPlain, formatCuratePlain, formatDistillPlain, formatEventLine, formatEventsPlain, formatFeedbackPlain, formatHistoryPlain, formatImportPlain, formatIndexPlain, formatInfoPlain, formatInitPlain, formatListPlain, formatProposalAcceptPlain, formatProposalDiffPlain, formatProposalListPlain, formatProposalProducerPlain, formatProposalRejectPlain, formatProposalShowPlain, formatRegistryAddPlain, formatRegistryBuildIndexPlain, formatRegistryListPlain, formatRegistryRemovePlain, formatRegistrySearchPlain, formatRememberPlain, formatRemovePlain, formatSavePlain, formatSearchPlain, formatShowPlain, formatToggleComponentPlain, formatUpdatePlain, formatUpgradePlain, formatWorkflowCreatePlain, formatWorkflowListPlain, formatWorkflowNextPlain, formatWorkflowResumePlain, formatWorkflowStatusPlain, formatWorkflowValidatePlain, } from "./text/helpers.js";
-// Re-export registry API so callers can use this module as the single entry
-// point (backward compat).
-export { deregisterTextFormatter, registerTextFormatter } from "./text/registry.js";
 // ── Explicit built-in formatter assembly ──────────────────────────────────────
 // Each entry below is a pure exported `TextFormatterEntry[]` from a per-command
 // module. The set is registered ONCE, deterministically, with no reliance on
@@ -40,7 +36,8 @@ export { deregisterTextFormatter, registerTextFormatter } from "./text/registry.
 // and because each name is referenced statically, a deleted export fails to
 // compile instead of silently disappearing at runtime.
 const BUILT_IN_TEXT_FORMATTERS = [
-    ...initFormatters,
+    ...bundleCreateFormatters,
+    ...bundleShowFormatters,
     ...indexFormatters,
     ...showFormatters,
     ...searchFormatters,
@@ -52,20 +49,20 @@ const BUILT_IN_TEXT_FORMATTERS = [
     ...updateFormatters,
     ...upgradeFormatters,
     ...cloneFormatters,
-    ...historyFormatters,
     ...eventsFormatters,
     ...proposalFormatters,
     ...proposalProducerFormatters,
-    ...distillFormatters,
     ...infoFormatters,
+    ...healthFormatters,
+    ...lintFormatters,
     ...configFormatters,
     ...feedbackFormatters,
     ...rememberFormatters,
     ...importFormatters,
-    ...saveFormatters,
-    ...enableDisableFormatters,
+    ...syncFormatters,
     ...registryCommandFormatters,
     ...envFormatters,
+    ...migrateFormatters,
 ];
 registerTextFormatters(BUILT_IN_TEXT_FORMATTERS);
 // ── JSONL output (unchanged — not part of the formatPlain dispatch) ───────────
@@ -88,12 +85,14 @@ export function outputJsonl(command, shaped) {
 // ── Dispatcher ────────────────────────────────────────────────────────────────
 /**
  * Return a plain-text string for commands that are better as short messages,
- * or null to fall through to YAML output.
+ * or null to fall through to the generic text rendering of the shaped
+ * envelope (`renderGenericText`, applied in `output()` in
+ * `src/cli/shared.ts` — this module stays dependency-free of that renderer).
  */
 export function formatPlain(command, result, detail) {
     const handler = getTextFormatterHandler(command);
     if (handler) {
         return handler(result, detail);
     }
-    return null; // fall through to YAML
+    return null; // fall through to the generic text renderer, not YAML
 }

package/dist/registry/factory.js

@@ -12,17 +12,15 @@
  * `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.
+ * Factories use the `RegistryProviderFactory` type owned by
+ * `src/registry/providers/types.ts`.
  */
 import { createProviderRegistry } from "./create-provider-registry.js";
 // ── Factory map ─────────────────────────────────────────────────────────────
 const registry = createProviderRegistry();
-export function registerProvider(type, factory) {
+export function registerRegistryProvider(type, factory) {
     registry.register(type, factory);
 }
-export function resolveProviderFactory(type) {
+export function resolveRegistryProviderFactory(type) {
     return registry.resolve(type);
 }

package/dist/registry/origin-resolve.js

@@ -2,56 +2,45 @@
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import path from "node:path";
+import { isBundleSlug } from "../core/asset/asset-ref.js";
+import { deriveInstallations } from "../indexer/installations.js";
 import { parseRegistryRef } from "./resolve.js";
 /**
  * Given an origin string (from an AssetRef) and the full list of stash
  * sources, return the subset of sources to search.
  *
- * Resolution order:
- *   1. undefined   → all sources
- *   2. "local"     → primary stash only (first entry)
- *   3. exact match → source whose registryId matches verbatim
- *   4. parsed match → parse origin as a registry ref, match by parsed ID
- *   5. path match  → source whose resolved path matches the origin
- *   6. empty       → indicates a remote/uninstalled origin (caller decides)
+ * Qualified asset refs use bundle identity only. Install locators and paths are
+ * a separate grammar handled by {@link resolveSourcesForLocator}.
  */
 export function resolveSourcesForOrigin(origin, allSources) {
     if (!origin)
         return allSources;
-    // "local" means the primary stash (first entry)
-    if (origin === "local") {
-        return allSources.length > 0 ? [allSources[0]] : [];
-    }
-    // Exact registryId match (e.g. origin is "npm:@scope/pkg")
-    const byExactId = allSources.filter((s) => s.registryId !== undefined && s.registryId === origin);
+    const installations = deriveInstallations(allSources);
+    return allSources.filter((_, index) => installations[index]?.id === origin);
+}
+/** Resolve the non-asset source locator grammar used by `akm clone`. */
+export function resolveSourcesForLocator(locator, allSources) {
+    const byExactId = allSources.filter((source) => source.registryId === locator);
     if (byExactId.length > 0)
         return byExactId;
-    // Parse origin as a registry ref and match by parsed ID.
-    // Allows shorthand: "owner/repo" matches "github:owner/repo",
-    // "@scope/pkg" matches "npm:@scope/pkg".
     try {
-        const parsed = parseRegistryRef(origin);
+        const parsed = parseRegistryRef(locator);
         const byParsedId = allSources.filter((s) => s.registryId !== undefined && s.registryId === parsed.id);
         if (byParsedId.length > 0)
             return byParsedId;
     }
     catch {
-        // Not a valid registry ref — continue to path matching
+        // Not a registry locator; continue to path matching.
     }
-    // Match by resolved path (any source, including installed)
-    const resolvedOrigin = path.resolve(origin);
-    const byPath = allSources.filter((s) => path.resolve(s.path) === resolvedOrigin);
-    if (byPath.length > 0)
-        return byPath;
-    // No match — origin may be remote/uninstalled
-    return [];
+    const resolvedLocator = path.resolve(locator);
+    return allSources.filter((source) => path.resolve(source.path) === resolvedLocator);
 }
 /**
  * Check whether an origin refers to something that could be fetched remotely
  * (i.e. it looks like a registry ref but isn't installed locally).
  */
 export function isRemoteOrigin(origin, allSources) {
-    if (origin === "local")
+    if (isBundleSlug(origin))
         return false;
-    return resolveSourcesForOrigin(origin, allSources).length === 0;
+    return resolveSourcesForLocator(origin, allSources).length === 0;
 }

package/dist/registry/providers/skills-sh.js

@@ -4,7 +4,7 @@
 import { fetchWithRetry } from "../../core/common.js";
 import { md5Hex } from "../../runtime.js";
 import { fetchCachedJson } from "../../storage/repositories/registry-cache.js";
-import { registerProvider } from "../factory.js";
+import { registerRegistryProvider } from "../factory.js";
 // ── Constants ───────────────────────────────────────────────────────────────
 /** Per-query cache TTL in milliseconds (15 minutes). */
 const QUERY_CACHE_TTL_MS = 15 * 60 * 1000;
@@ -112,7 +112,7 @@ class SkillsShProvider {
                 assetName: entry.name,
                 stash: { id: `skills-sh:${entry.id}`, name: entry.name },
                 registryName,
-                action: `akm add github:${ownerRepo}`,
+                action: `akm bundle add github:${ownerRepo}`,
                 score: Math.round((entry.installs / maxInstalls) * 1000) / 1000,
             };
         });
@@ -125,7 +125,7 @@ class SkillsShProvider {
     }
 }
 // ── Self-register ───────────────────────────────────────────────────────────
-registerProvider("skills-sh", (config) => new SkillsShProvider(config));
+registerRegistryProvider("skills-sh", (config) => new SkillsShProvider(config));
 // ── Response parsing ────────────────────────────────────────────────────────
 function parseSkillsResponse(data) {
     if (typeof data !== "object" || data === null || Array.isArray(data))

package/dist/registry/providers/static-index.js

@@ -4,13 +4,11 @@
 import { fetchWithRetry, jsonWithByteCap, toErrorMessage } from "../../core/common.js";
 import { asString } from "../../integrations/github.js";
 import { fetchCachedJson } from "../../storage/repositories/registry-cache.js";
-import { registerProvider } from "../factory.js";
+import { registerRegistryProvider } from "../factory.js";
 import { buildInstallRef } from "../resolve.js";
 // ── Constants ───────────────────────────────────────────────────────────────
 /** Cache TTL in milliseconds (1 hour). */
 const CACHE_TTL_MS = 60 * 60 * 1000;
-/** Maximum age before cache is considered stale but still usable as fallback (7 days). */
-const CACHE_STALE_MS = 7 * 24 * 60 * 60 * 1000;
 // ── Provider class ──────────────────────────────────────────────────────────
 class StaticIndexProvider {
     type = "static-index";
@@ -20,25 +18,25 @@ class StaticIndexProvider {
     }
     async search(options) {
         const warnings = [];
-        const allKits = await this.loadAllKits(warnings);
-        const hits = scoreKits(allKits, options.query, options.limit);
+        const bundles = await this.loadBundles(warnings);
+        const hits = scoreBundles(bundles, options.query, options.limit);
         let assetHits;
         if (options.includeAssets) {
-            const scored = scoreAssets(allKits, options.query, options.limit);
+            const scored = scoreAssets(bundles, options.query, options.limit);
             if (scored.length > 0)
                 assetHits = scored;
         }
         return { hits, assetHits, warnings: warnings.length > 0 ? warnings : undefined };
     }
     // ── Internals ───────────────────────────────────────────────────────────
-    async loadAllKits(warnings) {
-        const allKits = [];
+    async loadBundles(warnings) {
+        const bundles = [];
         try {
             const index = await loadIndex(this.config);
             if (index) {
                 const regName = this.config.name;
                 for (const stash of index.stashes) {
-                    allKits.push({ stash, registryName: regName });
+                    bundles.push({ stash, registryName: regName });
                 }
             }
         }
@@ -46,18 +44,18 @@ class StaticIndexProvider {
             const label = this.config.name ? `${this.config.name} (${this.config.url})` : this.config.url;
             warnings.push(`Registry ${label}: ${toErrorMessage(err)}`);
         }
-        return allKits;
+        return bundles;
     }
 }
 // ── Self-register ───────────────────────────────────────────────────────────
-registerProvider("static-index", (config) => new StaticIndexProvider(config));
+registerRegistryProvider("static-index", (config) => new StaticIndexProvider(config));
 // ── Index loading with cache ────────────────────────────────────────────────
 async function loadIndex(entry) {
     return fetchCachedJson({
         cacheKey: entry.url,
         ttlMs: CACHE_TTL_MS,
         // Both the fresh hit and the stale fallback parse identically; a corrupt
-        // cache row lets JSON.parse throw out of the load (legacy behaviour).
+        // cache row lets JSON.parse throw out of the load.
         parseCache: (json) => parseRegistryIndex(JSON.parse(json)) ?? undefined,
         fetchFresh: async () => {
             const response = await fetchWithRetry(entry.url, undefined, { timeout: 10_000 });
@@ -77,12 +75,6 @@ async function loadIndex(entry) {
         },
     });
 }
-export function isCacheExpired(mtimeMs) {
-    return Date.now() - mtimeMs > CACHE_TTL_MS;
-}
-export function isCacheStale(mtimeMs) {
-    return Date.now() - mtimeMs > CACHE_STALE_MS;
-}
 // ── Index parsing (exported for reuse) ──────────────────────────────────────
 export function parseRegistryIndex(data) {
     if (typeof data !== "object" || data === null || Array.isArray(data))
@@ -113,9 +105,7 @@ function parseBundleEntry(raw) {
     const source = asSource(obj.source);
     if (!id || !name || !ref || !source)
         return null;
-    // The legacy registry boolean `curated` is removed in v1. Legacy index JSON
-    // containing a `curated` key parses normally; the key is silently ignored
-    // (v1 spec §4.2, docs/migration/v1.md).
+    // Some published indexes include `curated`; it is intentionally ignored.
     return {
         id,
         name,
@@ -132,7 +122,7 @@ function parseBundleEntry(raw) {
     };
 }
 // ── Scoring ─────────────────────────────────────────────────────────────────
-function scoreKits(stashes, query, limit) {
+function scoreBundles(stashes, query, limit) {
     const tokens = query.toLowerCase().split(/\s+/).filter(Boolean);
     const scored = [];
     for (const { stash, registryName } of stashes) {
@@ -247,7 +237,7 @@ function scoreAssets(stashes, query, limit) {
                         estimatedTokens: asset.estimatedTokens,
                         stash: { id: stash.id, name: stash.name },
                         registryName,
-                        action: `akm add ${installRef}`,
+                        action: `akm bundle add ${installRef}`,
                         score: Math.round(score * 1000) / 1000,
                     },
                     score,