akm-cli 0.9.0-rc.0 → 0.9.0-rc.13

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

@@ -0,0 +1,332 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// 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/.
+/**
+ * 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
+ * cohesive, self-contained cluster (they call only each other, never
+ * formatters from other domains).
+ */
+/**
+ * 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 runs
+        .map((run) => {
+        const id = typeof run.id === "string" ? run.id : "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}`;
+    })
+        .join("\n");
+}
+export function formatWorkflowStatusPlain(result) {
+    const run = typeof result.run === "object" && result.run !== null ? result.run : undefined;
+    const workflow = typeof result.workflow === "object" && result.workflow !== null
+        ? result.workflow
+        : undefined;
+    if (!run || !workflow)
+        return null;
+    const lines = [
+        `workflow: ${String(workflow.ref ?? "unknown")}`,
+        `run: ${String(run.id ?? "unknown")}`,
+        `title: ${String(run.workflowTitle ?? workflow.title ?? "Workflow")}`,
+        `status: ${String(run.status ?? "unknown")}`,
+    ];
+    if (run.currentStepId)
+        lines.push(`currentStep: ${String(run.currentStepId)}`);
+    const steps = Array.isArray(workflow.steps) ? workflow.steps : [];
+    if (steps.length > 0) {
+        lines.push("steps:");
+        for (const step of steps) {
+            const title = typeof step.title === "string" ? step.title : "Untitled step";
+            const id = typeof step.id === "string" ? step.id : "unknown";
+            const status = typeof step.status === "string" ? step.status : "unknown";
+            lines.push(`  - ${title} [${id}] (${status})`);
+            if (typeof step.notes === "string" && step.notes.trim()) {
+                lines.push(`    notes: ${step.notes}`);
+            }
+        }
+    }
+    // `workflow status --units` (#22): the honest per-unit diagnostic surface —
+    // failure_reason plus any journaled result/error text. Diagnostics only; the
+    // deterministic step evidence above is unaffected.
+    const units = Array.isArray(result.units) ? result.units : undefined;
+    if (units) {
+        lines.push("");
+        lines.push(units.length > 0 ? "units:" : "units: (none journaled)");
+        for (const unit of units) {
+            const id = typeof unit.unitId === "string" ? unit.unitId : "unknown";
+            const status = typeof unit.status === "string" ? unit.status : "unknown";
+            const node = typeof unit.nodeId === "string" ? unit.nodeId : "";
+            const attempts = typeof unit.attempts === "number" ? unit.attempts : undefined;
+            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.
+            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`);
+            }
+            if (typeof unit.failureReason === "string" && unit.failureReason.trim()) {
+                lines.push(`    failure_reason: ${unit.failureReason}`);
+            }
+            if (typeof unit.diagnostic === "string" && unit.diagnostic.trim()) {
+                const diagLines = unit.diagnostic.split("\n");
+                lines.push(`    diagnostic: ${diagLines[0]}`);
+                for (const diagLine of diagLines.slice(1))
+                    lines.push(`      ${diagLine}`);
+            }
+        }
+    }
+    // Review C2: the check-in `continue` directive must survive plain-text
+    // rendering — JSON consumers saw `checkin` but the text path dropped it.
+    const checkinLine = formatWorkflowCheckinLine(result);
+    if (checkinLine) {
+        lines.push("");
+        lines.push(checkinLine);
+    }
+    return lines.join("\n");
+}
+/**
+ * Render the stalled-run check-in directive (#506) when present on a
+ * workflow-next/status result. Returns null when the run is healthy.
+ */
+function formatWorkflowCheckinLine(result) {
+    const checkin = typeof result.checkin === "object" && result.checkin !== null
+        ? result.checkin
+        : undefined;
+    if (!checkin || typeof checkin.directive !== "string" || !checkin.directive.trim())
+        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")}`];
+    const executed = Array.isArray(result.executed) ? result.executed : [];
+    if (executed.length === 0) {
+        lines.push("executed: (no steps — run was already done or blocked)");
+    }
+    else {
+        lines.push("executed:");
+        for (const step of executed) {
+            const marker = step.ok === true ? "ok" : "FAILED";
+            lines.push(`  - ${String(step.stepId ?? "?")} [${marker}] units: ${String(step.unitCount ?? 0)}` +
+                (Number(step.failedUnits ?? 0) > 0 ? ` (${String(step.failedUnits)} failed)` : ""));
+            if (typeof step.summary === "string" && step.summary.trim()) {
+                lines.push(`    ${step.summary}`);
+            }
+        }
+    }
+    const gate = typeof result.gateRejection === "object" && result.gateRejection !== null
+        ? result.gateRejection
+        : undefined;
+    if (gate) {
+        lines.push(`gate rejected step ${String(gate.stepId ?? "?")}: ${String(gate.feedback ?? "")}`);
+        const missing = Array.isArray(gate.missing) ? gate.missing : [];
+        for (const item of missing)
+            lines.push(`  missing: ${String(item)}`);
+    }
+    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)}`;
+    }
+    return null;
+}
+export function formatWorkflowResumePlain(r) {
+    return formatWorkflowStatusPlain(r) ?? `Resumed workflow run ${String(r.id ?? r.runId ?? "?")}`;
+}

package/dist/output/text/workflow.js

@@ -2,7 +2,7 @@
 // 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 { formatWorkflowCompleteRejectedPlain, formatWorkflowCreatePlain, formatWorkflowListPlain, formatWorkflowNextPlain, formatWorkflowResumePlain, formatWorkflowStatusPlain, formatWorkflowValidatePlain, } from "./helpers.js";
+import { formatWorkflowBriefPlain, formatWorkflowCompleteRejectedPlain, formatWorkflowCreatePlain, formatWorkflowListPlain, formatWorkflowNextPlain, formatWorkflowResumePlain, formatWorkflowRunPlain, formatWorkflowStatusPlain, } from "./helpers.js";
 export const workflowFormatters = [
     { command: "workflow-start", handler: (r) => formatWorkflowStatusPlain(r) },
     { command: "workflow-status", handler: (r) => formatWorkflowStatusPlain(r) },
@@ -11,7 +11,8 @@ export const workflowFormatters = [
     { 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,19 +2,17 @@
 // 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 { importFormatters } from "./text/import.js";
 import { indexFormatters } from "./text/index.js";
 import { infoFormatters } from "./text/info.js";
-import { initFormatters } from "./text/init.js";
 import { listFormatters } from "./text/list.js";
 import { proposalProducerFormatters } from "./text/proposal/producer.js";
 import { proposalFormatters } from "./text/proposal/proposal.js";
@@ -22,18 +20,12 @@ import { getTextFormatterHandler, registerTextFormatters } from "./text/registry
 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 { wikiFormatters } from "./text/wiki.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, formatWikiCreatePlain, formatWikiIngestPlain, formatWikiLintPlain, formatWikiListPlain, formatWikiPagesPlain, formatWikiRegisterPlain, formatWikiRemovePlain, formatWikiShowPlain, formatWikiStashPlain, 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
@@ -41,12 +33,12 @@ 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,
     ...curateFormatters,
-    ...wikiFormatters,
     ...workflowFormatters,
     ...listFormatters,
     ...addFormatters,
@@ -54,18 +46,15 @@ const BUILT_IN_TEXT_FORMATTERS = [
     ...updateFormatters,
     ...upgradeFormatters,
     ...cloneFormatters,
-    ...historyFormatters,
     ...eventsFormatters,
     ...proposalFormatters,
     ...proposalProducerFormatters,
-    ...distillFormatters,
     ...infoFormatters,
     ...configFormatters,
     ...feedbackFormatters,
     ...rememberFormatters,
     ...importFormatters,
-    ...saveFormatters,
-    ...enableDisableFormatters,
+    ...syncFormatters,
     ...registryCommandFormatters,
     ...envFormatters,
 ];
@@ -90,12 +79,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))