akm-cli 0.6.1 → 0.7.0-rc1

package/dist/src/commands/propose.js

@@ -0,0 +1,171 @@
+/**
+ * `akm propose <type> <name> --task ...` — proposal-producing agent
+ * command (#226).
+ *
+ * Mirrors {@link akmReflect} but for fresh authoring. The agent receives a
+ * task description plus per-asset-type schema hints and is asked to author
+ * a brand-new asset payload. The output lands ONLY in the proposal queue.
+ *
+ * Failures use the same {@link AgentFailureReason} discriminants as
+ * `akm reflect`. `propose_invoked` is emitted at command entry.
+ */
+import { parseAssetRef } from "../core/asset-ref";
+import { TYPE_DIRS } from "../core/asset-spec";
+import { resolveStashDir } from "../core/common";
+import { loadConfig } from "../core/config";
+import { ConfigError, UsageError } from "../core/errors";
+import { appendEvent } from "../core/events";
+import { createProposal } from "../core/proposals";
+import { parseAgentConfig, requireAgentProfile, runAgent, } from "../integrations/agent";
+import { buildProposePrompt, parseAgentProposalPayload } from "../integrations/agent/prompts";
+function loadAgentConfigFromDisk() {
+    const config = loadConfig();
+    return parseAgentConfig(config.agent);
+}
+function resolveProfile(options) {
+    if (options.agentProfile)
+        return options.agentProfile;
+    const agent = options.agentConfig ?? loadAgentConfigFromDisk();
+    return requireAgentProfile(agent, options.profile);
+}
+function failureEnvelope(result, type, name, fallbackReason = "non_zero_exit") {
+    const reason = result.reason ?? fallbackReason;
+    return {
+        schemaVersion: 1,
+        ok: false,
+        reason,
+        error: result.error ?? `agent failure (${reason})`,
+        type,
+        name,
+        exitCode: result.exitCode,
+        ...(result.stdout ? { stdout: result.stdout } : {}),
+        ...(result.stderr ? { stderr: result.stderr } : {}),
+    };
+}
+export async function akmPropose(options) {
+    if (!options.type?.trim()) {
+        throw new UsageError("propose: <type> is required.", "MISSING_REQUIRED_ARGUMENT");
+    }
+    if (!options.name?.trim()) {
+        throw new UsageError("propose: <name> is required.", "MISSING_REQUIRED_ARGUMENT");
+    }
+    if (!options.task?.trim()) {
+        throw new UsageError("propose: --task is required.", "MISSING_REQUIRED_ARGUMENT");
+    }
+    if (!TYPE_DIRS[options.type]) {
+        throw new UsageError(`propose: unknown asset type "${options.type}". Known types: ${Object.keys(TYPE_DIRS).sort().join(", ")}.`, "INVALID_FLAG_VALUE");
+    }
+    const stash = options.stashDir ?? resolveStashDir();
+    // 1. Always emit `propose_invoked` at entry so observers see the attempt.
+    appendEvent({
+        eventType: "propose_invoked",
+        ref: `${options.type}:${options.name}`,
+        metadata: {
+            type: options.type,
+            name: options.name,
+            task: options.task,
+            ...(options.profile ? { profile: options.profile } : {}),
+        },
+    });
+    // 2. Resolve profile.
+    let profile;
+    try {
+        profile = resolveProfile(options);
+    }
+    catch (err) {
+        if (err instanceof ConfigError || err instanceof UsageError)
+            throw err;
+        throw err;
+    }
+    // 3. Build prompt.
+    const prompt = buildProposePrompt({
+        type: options.type,
+        name: options.name,
+        task: options.task,
+    });
+    // 4. Spawn the agent.
+    const runOptions = {
+        stdio: "captured",
+        parseOutput: "text",
+        ...(options.timeoutMs !== undefined ? { timeoutMs: options.timeoutMs } : {}),
+        ...(options.runAgentOptions ?? {}),
+    };
+    const result = await runAgent(profile, prompt, runOptions);
+    if (!result.ok) {
+        return failureEnvelope(result, options.type, options.name);
+    }
+    // 5. Parse the structured response.
+    let payload;
+    try {
+        payload = parseAgentProposalPayload(result.stdout);
+    }
+    catch (err) {
+        return {
+            schemaVersion: 1,
+            ok: false,
+            reason: "parse_error",
+            error: err instanceof Error ? err.message : String(err),
+            type: options.type,
+            name: options.name,
+            exitCode: result.exitCode,
+            stdout: result.stdout,
+            ...(result.stderr ? { stderr: result.stderr } : {}),
+        };
+    }
+    // 6. Insert the proposal. Note: we allow the agent's `ref` to normalise the
+    // asset name (e.g. path-cleanup), but only after validating that the ref is
+    // well-formed and the type still matches the requested type.
+    const expectedRef = `${options.type}:${options.name}`;
+    let ref = expectedRef;
+    if (payload.ref) {
+        let parsedRef;
+        try {
+            parsedRef = parseAssetRef(payload.ref);
+        }
+        catch (err) {
+            return {
+                schemaVersion: 1,
+                ok: false,
+                reason: "parse_error",
+                error: err instanceof Error ? err.message : String(err),
+                type: options.type,
+                name: options.name,
+                exitCode: result.exitCode,
+                stdout: result.stdout,
+                ...(result.stderr ? { stderr: result.stderr } : {}),
+            };
+        }
+        if (parsedRef.type !== options.type) {
+            return {
+                schemaVersion: 1,
+                ok: false,
+                reason: "parse_error",
+                error: `Agent returned ref type ${parsedRef.type} but expected ${options.type}`,
+                type: options.type,
+                name: options.name,
+                exitCode: result.exitCode,
+                stdout: result.stdout,
+                ...(result.stderr ? { stderr: result.stderr } : {}),
+            };
+        }
+        ref = `${parsedRef.type}:${parsedRef.name}`;
+    }
+    const createInput = {
+        ref,
+        source: "propose",
+        sourceRun: `propose-${Date.now()}`,
+        payload: {
+            content: payload.content,
+            ...(payload.frontmatter ? { frontmatter: payload.frontmatter } : {}),
+        },
+    };
+    const proposal = createProposal(stash, createInput, options.ctx);
+    return {
+        schemaVersion: 1,
+        ok: true,
+        proposal,
+        ref: proposal.ref,
+        agentProfile: profile.name,
+        durationMs: result.durationMs,
+    };
+}

package/dist/src/commands/reflect.js

@@ -0,0 +1,193 @@
+/**
+ * `akm reflect [ref]` — proposal-producing agent command (#226).
+ *
+ * Pipeline:
+ *
+ *   1. Emit `reflect_invoked` event at command entry (always, even on failure).
+ *   2. If `ref` is provided, look the asset up via the FTS index and read its
+ *      content. Pull recent feedback (`feedback` events for that ref) and
+ *      lesson-lint findings to surface as schema hints.
+ *   3. Build the prompt via {@link buildReflectPrompt}.
+ *   4. Spawn the configured agent profile via {@link runAgent}.
+ *   5. Parse the agent's stdout into a {@link AgentProposalPayload}.
+ *   6. Insert into the proposal queue via {@link createProposal} with
+ *      `source: "reflect"`.
+ *
+ * Failures are surfaced as structured envelopes carrying an
+ * {@link AgentFailureReason} discriminant. Reflect NEVER calls
+ * `writeAssetToSource` directly — the proposal queue is the only path to
+ * a committed asset, and the `accept` flow is the bridge.
+ */
+import fs from "node:fs";
+import { parseAssetRef } from "../core/asset-ref";
+import { resolveStashDir } from "../core/common";
+import { loadConfig } from "../core/config";
+import { ConfigError, UsageError } from "../core/errors";
+import { appendEvent, readEvents } from "../core/events";
+import { lintLessonContent } from "../core/lesson-lint";
+import { createProposal } from "../core/proposals";
+import { lookup } from "../indexer/indexer";
+import { parseAgentConfig, requireAgentProfile, runAgent, } from "../integrations/agent";
+import { buildReflectPrompt, parseAgentProposalPayload } from "../integrations/agent/prompts";
+const MAX_FEEDBACK_LINES = 10;
+const MAX_GLOBAL_FEEDBACK_LINES = 20;
+/**
+ * Pull recent `feedback` events from events.jsonl. When `ref` is present we
+ * scope to that asset; otherwise we surface the most recent feedback across
+ * all assets so `akm reflect` can operate in a general "review recent
+ * signals" mode. Best-effort — a missing or empty events stream returns `[]`.
+ */
+function readRecentFeedback(ref) {
+    try {
+        const result = readEvents({ type: "feedback", ...(ref ? { ref } : {}) });
+        const lines = [];
+        const limit = ref ? MAX_FEEDBACK_LINES : MAX_GLOBAL_FEEDBACK_LINES;
+        for (const event of result.events.slice(-limit)) {
+            const md = (event.metadata ?? {});
+            const signal = typeof md.signal === "string" ? md.signal : "?";
+            const note = typeof md.note === "string" ? md.note : typeof md.reason === "string" ? md.reason : "";
+            const details = note ? `[${signal}] ${note}` : `[${signal}]`;
+            lines.push(!ref && event.ref ? `${event.ref} ${details}` : details);
+        }
+        return lines;
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Build schema/lint hints for the prompt. For lesson refs, run the lesson
+ * lint over the current content and surface any findings — they are a
+ * concrete starting point for the agent's revision.
+ */
+function buildSchemaHints(type, content) {
+    if (!content)
+        return [];
+    if (type !== "lesson")
+        return [];
+    const report = lintLessonContent(content, "reflect");
+    return report.findings.map((f) => `[${f.kind}] ${f.message}`);
+}
+function loadAgentConfigFromDisk() {
+    const config = loadConfig();
+    return parseAgentConfig(config.agent);
+}
+function resolveProfile(options) {
+    if (options.agentProfile)
+        return options.agentProfile;
+    const agent = options.agentConfig ?? loadAgentConfigFromDisk();
+    return requireAgentProfile(agent, options.profile);
+}
+function failureEnvelope(result, ref, fallbackReason = "non_zero_exit") {
+    const reason = result.reason ?? fallbackReason;
+    return {
+        schemaVersion: 1,
+        ok: false,
+        reason,
+        error: result.error ?? `agent failure (${reason})`,
+        ...(ref ? { ref } : {}),
+        exitCode: result.exitCode,
+        ...(result.stdout ? { stdout: result.stdout } : {}),
+        ...(result.stderr ? { stderr: result.stderr } : {}),
+    };
+}
+export async function akmReflect(options = {}) {
+    const stash = options.stashDir ?? resolveStashDir();
+    // 1. Always emit `reflect_invoked` at command entry — observers see the
+    // attempt regardless of downstream success/failure.
+    appendEvent({
+        eventType: "reflect_invoked",
+        ...(options.ref ? { ref: options.ref } : {}),
+        metadata: {
+            ...(options.task ? { task: options.task } : {}),
+            ...(options.profile ? { profile: options.profile } : {}),
+        },
+    });
+    // 2. Resolve target asset content (if a ref is supplied).
+    let assetContent;
+    let parsedRef;
+    if (options.ref) {
+        parsedRef = parseAssetRef(options.ref);
+        try {
+            const entry = await lookup(parsedRef);
+            if (entry?.filePath && fs.existsSync(entry.filePath)) {
+                assetContent = fs.readFileSync(entry.filePath, "utf8");
+            }
+        }
+        catch {
+            // Index miss is non-fatal — the agent can still propose a fresh asset.
+        }
+    }
+    // 3. Resolve agent profile. ConfigError surfaces as a thrown error so the
+    // CLI dispatcher renders the standard envelope.
+    let profile;
+    try {
+        profile = resolveProfile(options);
+    }
+    catch (err) {
+        if (err instanceof ConfigError || err instanceof UsageError)
+            throw err;
+        throw err;
+    }
+    // 4. Build the prompt.
+    const feedback = readRecentFeedback(options.ref);
+    const schemaHints = buildSchemaHints(parsedRef?.type ?? "", assetContent);
+    const prompt = buildReflectPrompt({
+        ...(options.ref ? { ref: options.ref } : {}),
+        ...(parsedRef?.type ? { type: parsedRef.type } : {}),
+        ...(parsedRef?.name ? { name: parsedRef.name } : {}),
+        ...(assetContent !== undefined ? { assetContent } : {}),
+        ...(feedback.length > 0 ? { feedback } : {}),
+        ...(schemaHints.length > 0 ? { schemaHints } : {}),
+        ...(options.task ? { task: options.task } : {}),
+    });
+    // 5. Spawn the agent. Force captured stdio + JSON parse so we can extract
+    // the structured payload without confusing terminal control codes.
+    const runOptions = {
+        stdio: "captured",
+        parseOutput: "text",
+        ...(options.timeoutMs !== undefined ? { timeoutMs: options.timeoutMs } : {}),
+        ...(options.runAgentOptions ?? {}),
+    };
+    const result = await runAgent(profile, prompt, runOptions);
+    if (!result.ok) {
+        return failureEnvelope(result, options.ref);
+    }
+    // 6. Parse stdout into a proposal payload.
+    let payload;
+    try {
+        payload = parseAgentProposalPayload(result.stdout);
+    }
+    catch (err) {
+        return {
+            schemaVersion: 1,
+            ok: false,
+            reason: "parse_error",
+            error: err instanceof Error ? err.message : String(err),
+            ...(options.ref ? { ref: options.ref } : {}),
+            exitCode: result.exitCode,
+            stdout: result.stdout,
+            ...(result.stderr ? { stderr: result.stderr } : {}),
+        };
+    }
+    // 7. Create the proposal. The proposal queue is the ONLY thing reflect
+    // writes — promotion to a real asset is gated by `akm proposal accept`.
+    const createInput = {
+        ref: payload.ref,
+        source: "reflect",
+        sourceRun: `reflect-${Date.now()}`,
+        payload: {
+            content: payload.content,
+            ...(payload.frontmatter ? { frontmatter: payload.frontmatter } : {}),
+        },
+    };
+    const proposal = createProposal(stash, createInput, options.ctx);
+    return {
+        schemaVersion: 1,
+        ok: true,
+        proposal,
+        ref: proposal.ref,
+        agentProfile: profile.name,
+        durationMs: result.durationMs,
+    };
+}

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";
@@ -90,7 +91,7 @@ export function resolveRegistries(configRegistries) {
             if (!url)
                 continue;
             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 });

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

@@ -45,6 +45,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 +56,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 +80,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 +89,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") {
@@ -188,6 +194,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

@@ -129,9 +129,53 @@ 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);
+    }
     logShowEvent(ref);
     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}").`);
+        }
+    }
+}
 function logShowEvent(ref, existingDb) {
     try {
         const db = existingDb ?? openDatabase();

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);