akm-cli 0.6.1 → 0.7.0

package/dist/{commands → src/commands}/registry-search.js

@@ -1,5 +1,6 @@
 import { toErrorMessage } from "../core/common";
 import { DEFAULT_CONFIG, loadConfig } from "../core/config";
+import { warn } from "../core/warn";
 import { resolveProviderFactory } from "../registry/factory";
 // ── Eagerly import providers to trigger self-registration ───────────────────
 import "../registry/providers/index";
@@ -22,6 +23,9 @@ export async function searchRegistry(query, options) {
         return provider.search({ query: trimmed, limit, includeAssets: options?.includeAssets });
     }));
     // Merge results grouped by provider
+    // Each provider batch is normalized to [0, 1] before merging so that raw
+    // scores from different providers (e.g. static-index can exceed 1.85 while
+    // skills-sh uses installs-relative scoring) are comparable in the merged list.
     const allHits = [];
     const allAssetHits = [];
     for (let i = 0; i < results.length; i++) {
@@ -35,23 +39,34 @@ export async function searchRegistry(query, options) {
             continue;
         const registryLabel = entries[i].name ? `"${entries[i].name}"` : entries[i].url;
         let dropped = 0;
+        const validHits = [];
         for (const hit of value.hits) {
             if (isCompleteHit(hit)) {
-                allHits.push(hit);
+                validHits.push(hit);
             }
             else {
                 dropped++;
             }
         }
+        // Normalize scores within this provider's batch before merging
+        normalizeScores(validHits);
+        for (const hit of validHits) {
+            allHits.push(hit);
+        }
         if (value.assetHits) {
+            const validAssetHits = [];
             for (const hit of value.assetHits) {
                 if (isCompleteAssetHit(hit)) {
-                    allAssetHits.push(hit);
+                    validAssetHits.push(hit);
                 }
                 else {
                     dropped++;
                 }
             }
+            normalizeScores(validAssetHits);
+            for (const hit of validAssetHits) {
+                allAssetHits.push(hit);
+            }
         }
         if (dropped > 0) {
             warnings.push(`Registry ${registryLabel} returned ${dropped} incomplete hit(s); dropped from response.`);
@@ -59,7 +74,7 @@ export async function searchRegistry(query, options) {
         if (value.warnings)
             warnings.push(...value.warnings);
     }
-    // Sort merged hits by score descending, apply limit
+    // Sort merged hits by normalized score descending, apply limit
     allHits.sort((a, b) => (b.score ?? 0) - (a.score ?? 0));
     const limitedHits = allHits.slice(0, limit);
     allAssetHits.sort((a, b) => (b.score ?? 0) - (a.score ?? 0));
@@ -79,6 +94,11 @@ export async function searchRegistry(query, options) {
  * 1. AKM_REGISTRY_URL env var (CI override, comma-separated)
  * 2. config.registries (filtered by enabled !== false)
  * 3. Default registries from DEFAULT_CONFIG
+ *
+ * AKM_REGISTRY_URL syntax (comma-separated):
+ *   - Bare URL: `https://example.com/index.json`  → defaults to provider "static-index"
+ *   - Typed URL: `skills-sh::https://skills.sh/api`  → explicit provider type
+ *     Format: `<provider-type>::<url>`
  */
 export function resolveRegistries(configRegistries) {
     // Allow env var override (comma-separated URLs) — CI escape hatch
@@ -86,14 +106,30 @@ export function resolveRegistries(configRegistries) {
     if (envUrls) {
         const entries = [];
         for (const raw of envUrls.split(",")) {
-            const url = raw.trim();
-            if (!url)
+            const trimmed = raw.trim();
+            if (!trimmed)
                 continue;
+            // Parse optional `<provider-type>::<url>` prefix
+            let provider;
+            let url;
+            const colonColonIdx = trimmed.indexOf("::");
+            if (colonColonIdx !== -1 && !trimmed.startsWith("http://") && !trimmed.startsWith("https://")) {
+                // Only treat as `provider::url` if the prefix doesn't look like a URL scheme itself
+                provider = trimmed.slice(0, colonColonIdx).trim();
+                url = trimmed.slice(colonColonIdx + 2).trim();
+                if (!provider) {
+                    warn(`[akm] Ignoring AKM_REGISTRY_URL entry: empty provider type before "::" in "${trimmed}"`);
+                    continue;
+                }
+            }
+            else {
+                url = trimmed;
+            }
             if (!url.startsWith("http://") && !url.startsWith("https://")) {
-                console.warn(`[akm] Ignoring AKM_REGISTRY_URL entry: must start with http:// or https://, got "${url}"`);
+                warn(`[akm] Ignoring AKM_REGISTRY_URL entry: must start with http:// or https://, got "${url}"`);
                 continue;
             }
-            entries.push({ url });
+            entries.push(provider ? { url, provider } : { url });
         }
         return entries;
     }
@@ -112,6 +148,34 @@ function createProvider(entry, warnings) {
     return factory(entry);
 }
 // ── Utilities ───────────────────────────────────────────────────────────────
+/**
+ * Normalize the `score` field of a batch of hits in-place to [0, 1].
+ *
+ * Different registry providers use incompatible score scales
+ * (static-index can exceed 1.85; skills-sh uses installs-relative values
+ * in [0, 1]).  Normalizing each provider's batch independently before merging
+ * makes the merged sort order meaningful.
+ *
+ * When all scores are identical (or absent), scores are left unchanged so
+ * relative ordering within the batch is preserved (all-same is effectively
+ * already normalized).
+ */
+function normalizeScores(hits) {
+    if (hits.length === 0)
+        return;
+    const rawScores = hits.map((h) => h.score ?? 0);
+    const max = Math.max(...rawScores);
+    if (max <= 0)
+        return; // all zero or negative — leave as-is
+    const min = Math.min(...rawScores);
+    const range = max - min;
+    for (let i = 0; i < hits.length; i++) {
+        const raw = rawScores[i];
+        // Min-max normalize: [0, 1]. When all scores are equal (range === 0),
+        // fall back to dividing by max so the value stays in [0, 1].
+        hits[i].score = range > 0 ? (raw - min) / range : raw / max;
+    }
+}
 function clampLimit(limit) {
     if (!limit || !Number.isFinite(limit))
         return 20;

package/dist/{commands → src/commands}/remember.js

@@ -10,6 +10,7 @@ import { toErrorMessage, tryReadStdinText } from "../core/common";
 import { loadConfig } from "../core/config";
 import { UsageError } from "../core/errors";
 import { warn } from "../core/warn";
+import { SCOPE_KEYS } from "../indexer/metadata";
 /**
  * Parse a shorthand duration string to a number of milliseconds.
  * Supports: `30d` (days), `12h` (hours), `6m` (months, approximated as 30d).
@@ -52,6 +53,17 @@ export function buildMemoryFrontmatter(fields) {
         obj.expires = fields.expires;
     if (fields.subjective)
         obj.subjective = true;
+    // Scope keys are emitted as flat top-level keys (`scope_user`, …) so the
+    // existing one-level frontmatter parser can read them without nesting.
+    // A scope object with no populated values is dropped.
+    if (fields.scope) {
+        for (const key of SCOPE_KEYS) {
+            const value = fields.scope[key];
+            if (typeof value === "string" && value.trim()) {
+                obj[`scope_${key}`] = value.trim();
+            }
+        }
+    }
     // No fields populated → emit a bare delimiter pair so callers don't
     // produce `---\n{}\n---` (the YAML serializer's empty-object form).
     if (Object.keys(obj).length === 0)

package/dist/{commands → src/commands}/search.js

@@ -10,6 +10,7 @@
  */
 import { loadConfig } from "../core/config";
 import { UsageError } from "../core/errors";
+import { appendEvent } from "../core/events";
 import { closeDatabase, openDatabase } from "../indexer/db";
 import { searchLocal } from "../indexer/db-search";
 import { resolveSourceEntries } from "../indexer/search-source";
@@ -45,6 +46,8 @@ export async function akmSearch(input) {
     // Primary stash directory — used for DB path lookups and as the default
     // stash root. Safe because the empty-sources case is handled above.
     const stashDir = sources[0].path;
+    const filters = normalizeScopeFilters(input.filters);
+    const includeProposed = input.includeProposed === true;
     const localResult = source === "registry"
         ? undefined
         : await searchLocal({
@@ -54,6 +57,8 @@ export async function akmSearch(input) {
             stashDir,
             sources,
             config,
+            filters,
+            includeProposed,
         });
     const registryResult = source === "stash" ? undefined : await searchRegistry(query, { limit, registries: config.registries });
     if (source === "stash") {
@@ -76,6 +81,8 @@ export async function akmSearch(input) {
         // prefixed), otherwise derive it from source + ref for backward compat.
         const installRef = hit.installRef ??
             (hit.source === "npm" ? `npm:${hit.ref}` : hit.source === "git" ? `git+${hit.ref}` : `github:${hit.ref}`);
+        // The legacy registry boolean `curated` was removed in v1 (spec §4.2).
+        // Hit-level `warnings` are forwarded when the provider surfaced any.
         return {
             type: "registry",
             name: hit.title,
@@ -83,8 +90,8 @@ export async function akmSearch(input) {
             description: hit.description,
             action: `akm add ${installRef} -> then search again`,
             score: hit.score,
-            curated: hit.curated,
             registryName: hit.registryName,
+            ...(hit.warnings && hit.warnings.length > 0 ? { warnings: hit.warnings } : {}),
         };
     });
     if (source === "registry") {
@@ -141,13 +148,30 @@ function resolveEntryIds(db, hits) {
 /**
  * Fire-and-forget: log a search event to the usage_events table.
  * Never blocks the caller; errors are silently ignored.
+ *
+ * Result count semantics:
+ *   - `stashHitCount`: number of local stash hits (response.hits, source-only
+ *     entries). Always 0 for registry-only searches.
+ *   - `registryHitCount`: number of registry hits (response.registryHits).
+ *     Only non-zero when source is "registry" or "both".
+ *   - `resultCount`: total across both pools so telemetry reflects the actual
+ *     number of results the user saw, regardless of source mode.
+ *
+ * Per-entry events are recorded only for stash hits because registry hits
+ * have no local entry_id to reference.
  */
 function logSearchEvent(query, response, existingDb) {
+    // Emit a structured event to events.jsonl so workflow-trace consumers
+    // detect akm search invocations without relying on stdout scraping.
+    const stashHits = response.hits.filter((h) => h.type !== "registry");
+    appendEvent({
+        eventType: "search",
+        metadata: { query, hitCount: stashHits.length, resultRefs: stashHits.map((h) => h.ref) },
+    });
     try {
         const db = existingDb ?? openDatabase();
         try {
-            const stashHits = response.hits.filter((h) => h.type !== "registry").slice(0, 50);
-            const resolved = resolveEntryIds(db, stashHits);
+            const resolved = resolveEntryIds(db, stashHits.slice(0, 50));
             for (const { entryId, ref } of resolved) {
                 insertUsageEvent(db, {
                     event_type: "search",
@@ -156,10 +180,19 @@ function logSearchEvent(query, response, existingDb) {
                     entry_ref: ref,
                 });
             }
+            // Count registry hits separately so registry-only searches record a
+            // non-zero resultCount. response.hits is always [] when source="registry".
+            const stashHitCount = response.hits.length;
+            const registryHitCount = Array.isArray(response.registryHits) ? response.registryHits.length : 0;
             insertUsageEvent(db, {
                 event_type: "search",
                 query,
-                metadata: JSON.stringify({ resultCount: response.hits.length, resolvedCount: resolved.length }),
+                metadata: JSON.stringify({
+                    resultCount: stashHitCount + registryHitCount,
+                    stashHitCount,
+                    registryHitCount,
+                    resolvedCount: resolved.length,
+                }),
             });
         }
         finally {
@@ -188,6 +221,73 @@ export function parseSearchSource(source) {
         return "stash";
     throw new UsageError(`Invalid value for --source: ${String(source)}. Expected one of: stash|registry|both`, "INVALID_SOURCE_VALUE");
 }
+/**
+ * Strip empty / non-string values from a scope filter object. Returns
+ * `undefined` when nothing meaningful remains, so callers don't pay for an
+ * empty-filter post-walk in `searchLocal`.
+ */
+function normalizeScopeFilters(raw) {
+    if (!raw)
+        return undefined;
+    const out = {};
+    for (const key of ["user", "agent", "run", "channel"]) {
+        const value = raw[key];
+        if (typeof value === "string" && value.trim()) {
+            out[key] = value.trim();
+        }
+    }
+    return Object.keys(out).length > 0 ? out : undefined;
+}
+/**
+ * Parse repeated `--filter k=v` / `--scope k=v` argv tokens into a
+ * `StashEntryScope`. Throws a {@link UsageError} for malformed tokens
+ * (missing `=`, unknown key) so callers don't see ambiguous misses.
+ *
+ * Used by both `akm search --filter` and `akm show --scope`.
+ */
+export function parseScopeFilterFlags(values, flagName = "--filter") {
+    if (values.length === 0)
+        return undefined;
+    const out = {};
+    for (const raw of values) {
+        const eq = raw.indexOf("=");
+        if (eq <= 0) {
+            throw new UsageError(`Invalid ${flagName} value "${raw}". Expected key=value (e.g. user=alice).`);
+        }
+        const key = raw.slice(0, eq).trim();
+        const value = raw.slice(eq + 1).trim();
+        if (key !== "user" && key !== "agent" && key !== "run" && key !== "channel") {
+            throw new UsageError(`Unknown scope key "${key}" in ${flagName}. Valid keys: user, agent, run, channel.`);
+        }
+        if (!value) {
+            throw new UsageError(`${flagName} ${key}=… requires a non-empty value.`);
+        }
+        out[key] = value;
+    }
+    return Object.keys(out).length > 0 ? out : undefined;
+}
+/**
+ * Returns true iff `entry.scope` (when present) satisfies every key in
+ * `filters`. A missing `entry.scope` (legacy memories) only matches when
+ * `filters` is empty / undefined.
+ *
+ * Filter semantics:
+ *   - No filter passed → all entries match (legacy behavior preserved).
+ *   - `filters.user = "alice"` → entry must have `scope.user === "alice"`.
+ *   - Multiple keys → AND-joined; every supplied key must match.
+ */
+export function entryMatchesScopeFilters(scope, filters) {
+    if (!filters)
+        return true;
+    for (const key of ["user", "agent", "run", "channel"]) {
+        const expected = filters[key];
+        if (expected === undefined)
+            continue;
+        if (!scope || scope[key] !== expected)
+            return false;
+    }
+    return true;
+}
 /**
  * Merge stash hits and registry hits via simple concatenation.
  */

package/dist/{commands → src/commands}/self-update.js

@@ -3,6 +3,7 @@ import { createHash } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import { fetchWithRetry, IS_WINDOWS } from "../core/common";
+import { warn } from "../core/warn";
 import { githubHeaders } from "../integrations/github";
 const REPO = "itlackey/akm";
 const DEFAULT_PACKAGE_NAME = "akm-cli";
@@ -147,7 +148,7 @@ export async function performUpgrade(check, opts) {
         const checksumsResponse = await fetchWithRetry(checksumsUrl);
         if (!checksumsResponse.ok) {
             if (skipChecksum) {
-                console.warn(`WARNING: checksums.txt fetch failed (HTTP ${checksumsResponse.status}). Proceeding without verification because --skip-checksum was provided.`);
+                warn(`WARNING: checksums.txt fetch failed (HTTP ${checksumsResponse.status}). Proceeding without verification because --skip-checksum was provided.`);
             }
             else {
                 throw new Error(`Checksum verification failed: could not fetch ${checksumsUrl} (HTTP ${checksumsResponse.status}). ` +
@@ -166,7 +167,7 @@ export async function performUpgrade(check, opts) {
             }
             else {
                 if (skipChecksum) {
-                    console.warn(`WARNING: ${binaryName} not found in checksums.txt. Proceeding without verification because --skip-checksum was provided.`);
+                    warn(`WARNING: ${binaryName} not found in checksums.txt. Proceeding without verification because --skip-checksum was provided.`);
                 }
                 else {
                     throw new Error(`Checksum verification failed: ${binaryName} not listed in checksums.txt. ` +
@@ -182,7 +183,7 @@ export async function performUpgrade(check, opts) {
         }
         // Network or parse failure
         if (skipChecksum) {
-            console.warn(`WARNING: Could not fetch or parse checksums: ${err instanceof Error ? err.message : String(err)}. Proceeding because --skip-checksum was provided.`);
+            warn(`WARNING: Could not fetch or parse checksums: ${err instanceof Error ? err.message : String(err)}. Proceeding because --skip-checksum was provided.`);
         }
         else {
             throw new Error(`Checksum verification failed: ${err instanceof Error ? err.message : String(err)}. ` +

package/dist/{commands → src/commands}/show.js

@@ -24,6 +24,7 @@ import path from "node:path";
 import { parseAssetRef } from "../core/asset-ref";
 import { loadConfig } from "../core/config";
 import { NotFoundError, UsageError } from "../core/errors";
+import { appendEvent, readEvents } from "../core/events";
 import { parseFrontmatter, toStringOrUndefined } from "../core/frontmatter";
 import { closeDatabase, findEntryIdByRef, openDatabase } from "../indexer/db";
 import { buildFileContext, buildRenderContext, getRenderer, runMatchers } from "../indexer/file-context";
@@ -35,6 +36,7 @@ import { resolveSourcesForOrigin } from "../registry/origin-resolve";
 // Eagerly import source providers to trigger self-registration.
 import "../sources/providers/index";
 import { resolveAssetPath } from "../sources/resolve";
+import { getActiveWorkflowRun } from "../workflows/runs";
 /**
  * Show a wiki root (no page path) — returns the same payload as
  * `akm wiki show <name>`.
@@ -129,10 +131,77 @@ export async function akmShowUnified(input) {
     }
     // Try local filesystem (FTS5 index lookup, then on-disk fallback)
     const result = await showLocal(input);
+    // Scope filter narrows resolution: if --scope was supplied, the asset's
+    // frontmatter scope must satisfy every supplied key. We re-read the file
+    // (cheap — already on the show hot path) so we don't have to thread scope
+    // through the renderer chain just for one verification step.
+    if (input.scope && hasAnyScopeKey(input.scope) && result.path) {
+        enforceScopeOrThrow(result.path, ref, input.scope);
+    }
+    // Count prior shows of this ref before logging the current one.
+    const priorShowCount = recentShowCount(ref);
     logShowEvent(ref);
+    if (priorShowCount >= 2) {
+        // Agent has shown this same asset 3+ times — inject a loop-break hint.
+        result.showLoopWarning = priorShowCount + 1;
+    }
     return result;
 }
+function hasAnyScopeKey(scope) {
+    return Boolean(scope.user || scope.agent || scope.run || scope.channel);
+}
+/**
+ * Read the asset file's frontmatter and verify its `scope_*` keys satisfy
+ * every supplied filter. Throws a {@link NotFoundError} on mismatch so the
+ * caller surfaces a uniform "not found in this scope" envelope rather than
+ * leaking out-of-scope content.
+ */
+function enforceScopeOrThrow(filePath, ref, scope) {
+    let raw;
+    try {
+        raw = fs.readFileSync(filePath, "utf8");
+    }
+    catch {
+        // The file path was just resolved by the indexer/disk-walk — a read
+        // failure here means the on-disk state moved out from under us. Treat
+        // that as "not found in this scope" so the caller does not learn the
+        // file's prior contents.
+        throw new NotFoundError(`Asset not found for scope filter: ${ref}`);
+    }
+    const fm = parseFrontmatter(raw).data;
+    const expected = [
+        ["user", scope.user],
+        ["agent", scope.agent],
+        ["run", scope.run],
+        ["channel", scope.channel],
+    ];
+    for (const [key, expectedValue] of expected) {
+        if (expectedValue === undefined)
+            continue;
+        const actual = toStringOrUndefined(fm[`scope_${key}`]);
+        if (actual !== expectedValue) {
+            throw new NotFoundError(`Asset "${ref}" exists but is out of scope (expected scope_${key}="${expectedValue}").`);
+        }
+    }
+}
+/**
+ * Count how many times `ref` has been shown in the current session by reading
+ * recent events. Returns the count BEFORE the current invocation.
+ */
+function recentShowCount(ref) {
+    try {
+        const { events } = readEvents({ type: "show", ref });
+        return events.length;
+    }
+    catch {
+        return 0;
+    }
+}
 function logShowEvent(ref, existingDb) {
+    // Emit a structured event to events.jsonl so workflow-trace consumers
+    // detect akm show invocations without relying on stdout scraping.
+    const parsed = parseAssetRef(ref);
+    appendEvent({ eventType: "show", ref, metadata: { type: parsed.type, name: parsed.name } });
     try {
         const db = existingDb ?? openDatabase();
         try {
@@ -251,6 +320,10 @@ export async function showLocal(input) {
         editable,
         ...(!editable ? { editHint: buildEditHint(assetPath, parsed.type, parsed.name, source?.registryId) } : {}),
     };
+    const activeRun = getActiveWorkflowRun();
+    if (activeRun) {
+        fullResponse.activeRun = activeRun;
+    }
     if (input.detail === "brief") {
         return buildBriefResponse(fullResponse, assetPath);
     }

package/dist/{commands → src/commands}/source-add.js

@@ -2,7 +2,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { isHttpUrl, resolveStashDir } from "../core/common";
 import { loadConfig, loadUserConfig, saveConfig } from "../core/config";
-import { UsageError } from "../core/errors";
+import { ConfigError, UsageError } from "../core/errors";
 import { warn } from "../core/warn";
 import { akmIndex } from "../indexer/indexer";
 import { upsertLockEntry } from "../integrations/lockfile";
@@ -190,6 +190,10 @@ async function addWebsiteSource(ref, stashDir, name, options, wikiName) {
  * persisting the lock entry.
  */
 async function addRegistryStash(ref, stashDir, trustThisInstall, writable, wikiName) {
+    const parsedRef = parseRegistryRef(ref);
+    if (writable === true && parsedRef.source !== "git") {
+        throw new ConfigError("writable: true is only supported on filesystem and git sources", "INVALID_CONFIG_FILE");
+    }
     // Pre-sync registry-policy enforcement uses just the parsed ref (no fetch needed),
     // so we keep parity with the historical behavior where `enforceRegistryInstallPolicy`
     // ran before `extractTarGzSecure` etc.

package/dist/{commands → src/commands}/source-manage.js

@@ -1,6 +1,6 @@
 import path from "node:path";
 import { loadConfig, loadUserConfig, saveConfig } from "../core/config";
-import { UsageError } from "../core/errors";
+import { ConfigError, UsageError } from "../core/errors";
 import { resolveSourceEntries } from "../indexer/search-source";
 // ── Operations ──────────────────────────────────────────────────────────────
 /**
@@ -12,6 +12,12 @@ import { resolveSourceEntries } from "../indexer/search-source";
  */
 export function addStash(opts) {
     const { target, name, providerType, options: providerOptions, writable } = opts;
+    if (providerType === "openviking") {
+        throw new ConfigError("openviking is not supported in akm v1.", "INVALID_CONFIG_FILE");
+    }
+    if (writable === true && providerType && providerType !== "filesystem" && providerType !== "git") {
+        throw new ConfigError("writable: true is only supported on filesystem and git sources", "INVALID_CONFIG_FILE");
+    }
     const config = loadUserConfig();
     const sources = [...(config.sources ?? config.stashes ?? [])];
     const isRemoteUrl = target.startsWith("http://") ||

package/dist/{core → src/core}/asset-ref.js

@@ -56,16 +56,16 @@ export function parseAssetRef(ref) {
 // ── Validation ──────────────────────────────────────────────────────────────
 function validateName(name) {
     if (!name)
-        throw new UsageError("Empty asset name.");
+        throw new UsageError("Empty asset name.", "MISSING_REQUIRED_ARGUMENT");
     if (name.includes("\0"))
-        throw new UsageError("Null byte in asset name.");
+        throw new UsageError("Null byte in asset name.", "MISSING_REQUIRED_ARGUMENT");
     if (/^[A-Za-z]:/.test(name))
-        throw new UsageError("Windows drive path in asset name.");
+        throw new UsageError("Windows drive path in asset name.", "MISSING_REQUIRED_ARGUMENT");
     const normalized = path.posix.normalize(name.replace(/\\/g, "/"));
     if (path.posix.isAbsolute(normalized))
-        throw new UsageError("Absolute path in asset name.");
+        throw new UsageError("Absolute path in asset name.", "MISSING_REQUIRED_ARGUMENT");
     if (normalized === ".." || normalized.startsWith("../")) {
-        throw new UsageError("Path traversal in asset name.");
+        throw new UsageError("Path traversal in asset name.", "MISSING_REQUIRED_ARGUMENT");
     }
 }
 function normalizeName(name) {

package/dist/{core → src/core}/asset-spec.js

@@ -90,6 +90,18 @@ const ASSET_SPECS_INTERNAL = {
         rendererName: "wiki-md",
         actionBuilder: (ref) => `akm show ${ref} -> read the wiki page`,
     },
+    // v1 spec §13 — `lesson` asset type. Required frontmatter fields are
+    // `description` and `when_to_use`; lint enforces both (see
+    // `src/core/lesson-lint.ts`). Lessons normally arrive as proposals via
+    // `akm distill <ref>` (§14.5) and are promoted via `akm proposal accept`,
+    // but they can also be authored directly with `akm import` /
+    // `akm remember`-style flows.
+    lesson: {
+        stashDir: "lessons",
+        ...markdownSpec,
+        rendererName: "lesson-md",
+        actionBuilder: (ref) => `akm show ${ref} -> read the lesson and apply when_to_use`,
+    },
 };
 export const ASSET_SPECS = ASSET_SPECS_INTERNAL;
 /**

package/dist/{core → src/core}/common.js

@@ -111,7 +111,7 @@ export function isWithin(candidate, root) {
  * consistent even when the directory hierarchy contains symlinks (e.g.
  * macOS /tmp → /private/tmp, or a HOME that is itself a symlink).
  */
-function safeRealpath(p) {
+export function safeRealpath(p) {
     const resolved = path.resolve(p);
     try {
         return fs.realpathSync(resolved);