akm-cli 0.9.0-rc.9 → 0.9.1-beta.1

package/dist/core/asset/akm-markdown.js

@@ -0,0 +1,63 @@
+// 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/.
+import { parse as parseYaml } from "yaml";
+import { localDateStamp } from "../common.js";
+import { UsageError } from "../errors.js";
+import { serializeFrontmatter } from "./asset-serialize.js";
+import { parseFrontmatterBlock, spliceFrontmatterLine } from "./frontmatter.js";
+/**
+ * Ensure an AKM-authored Markdown concept is also a conformant OKF concept.
+ *
+ * Stamps BOTH `type` and `updated`, because both are required of a conformant
+ * document and this is the one chokepoint every `.md` write passes through
+ * (`core/write-source.ts`). Without the `updated` stamp, every asset akm
+ * created for you — `akm remember`, `akm import`, accepted proposals,
+ * authored workflows — was immediately flagged `missing-updated` by akm's own
+ * `akm lint`, so the tool disagreed with itself about its own output.
+ *
+ * An existing `updated` is left alone: this fills a gap, it does not
+ * re-stamp on every write (which would churn timestamps and manufacture
+ * needless diffs in git-backed bundles).
+ *
+ * Source preservation: when the type already matches and the ONLY change is
+ * adding `updated`, the line is spliced into the original block textually —
+ * round-tripping through the YAML serializer would drop user-authored
+ * comments and normalize formatting just to contribute one field. Only a
+ * document whose `type` must actually be corrected takes the re-serialize
+ * path (as it always has).
+ */
+export function ensureAkmMarkdownType(content, type, now = new Date()) {
+    const block = parseFrontmatterBlock(content);
+    if (!block) {
+        return `---\n${serializeFrontmatter({ type, updated: localDateStamp(now) })}\n---\n${content}`;
+    }
+    let parsed;
+    try {
+        parsed = block.frontmatter.trim() ? parseYaml(block.frontmatter) : {};
+    }
+    catch {
+        throw new UsageError("AKM Markdown has malformed YAML frontmatter.", "INVALID_FLAG_VALUE");
+    }
+    if (parsed === null)
+        parsed = {};
+    if (typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new UsageError("AKM Markdown frontmatter must be a YAML mapping.", "INVALID_FLAG_VALUE");
+    }
+    const data = parsed;
+    const needsUpdated = !("updated" in data);
+    if (data.type === type) {
+        if (!needsUpdated)
+            return content;
+        const spliced = spliceFrontmatterLine(content, `updated: ${localDateStamp(now)}`);
+        if (spliced !== null)
+            return spliced;
+        // Unreachable in practice (parseFrontmatterBlock succeeded above), but a
+        // re-serialized document beats a non-conformant one.
+    }
+    const { type: _priorType, ...rest } = data;
+    const next = { type, ...rest };
+    if (needsUpdated)
+        next.updated = localDateStamp(now);
+    return `---\n${serializeFrontmatter(next)}\n---\n${block.content}`;
+}

package/dist/core/asset/asset-placement.js

@@ -46,7 +46,7 @@ const workflowSpec = {
             if (lower.endsWith(ext))
                 return path.join(typeRoot, name);
         }
-        // Probe in priority order — `.md` first for back-compat — and fall back
+        // Probe in canonical extension priority order and fall back
         // to the markdown path so error messages keep naming the canonical file.
         for (const ext of WORKFLOW_EXTENSIONS) {
             const candidate = path.join(typeRoot, `${name}${ext}`);
@@ -60,7 +60,7 @@ const markdownSpec = {
     isRelevantFile: (fileName) => path.extname(fileName).toLowerCase() === ".md",
     toCanonicalName: (typeRoot, filePath) => {
         const rel = toPosix(path.relative(typeRoot, filePath));
-        // Strip .md extension from canonical names (agent:code-reviewer, not agent:code-reviewer.md)
+        // Strip .md extension from canonical names.
         return rel.endsWith(".md") ? rel.slice(0, -3) : rel;
     },
     toAssetPath: (typeRoot, name) => {
@@ -74,7 +74,7 @@ const scriptSpec = {
     toCanonicalName: (typeRoot, filePath) => toPosix(path.relative(typeRoot, filePath)),
     toAssetPath: (typeRoot, name) => path.join(typeRoot, name),
 };
-const PLACEMENT_SPECS = {
+const BUILTIN_PLACEMENT_SPECS = {
     skill: {
         stashDir: "skills",
         isRelevantFile: (fileName) => fileName === "SKILL.md",
@@ -89,6 +89,18 @@ const PLACEMENT_SPECS = {
     command: { stashDir: "commands", ...markdownSpec },
     agent: { stashDir: "agents", ...markdownSpec },
     knowledge: { stashDir: "knowledge", ...markdownSpec },
+    // R-045 / Q-18 second half (owner ruling 11, EXECUTE NOW) — `instruction` as
+    // a real stash-resident type, mirroring `knowledge`'s plain markdown spec.
+    // This is distinct from the ADAPTER-OWNED instruction docs emitted by
+    // format-family adapters (root CLAUDE.md/AGENTS.md via `tool-dir-shared.ts`):
+    // those carry `document.ownsPresentation === true` and are routed straight
+    // to their adapter's own projection by `rendererForIndexedEntry`
+    // (`src/commands/read/show.ts`), which checks `ownsPresentation` BEFORE
+    // ever consulting a type/renderer mapping. A stash-resident `instructions/`
+    // asset never sets that marker, so it always renders via the `knowledge-md`
+    // renderer (`TYPE_PRESENTATION.instruction`, `src/core/type-presentation.ts`)
+    // like any other placement type — no collision with the adapter-owned path.
+    instruction: { stashDir: "instructions", ...markdownSpec },
     workflow: { stashDir: "workflows", ...workflowSpec },
     script: { stashDir: "scripts", ...scriptSpec },
     memory: { stashDir: "memories", ...markdownSpec },
@@ -154,6 +166,9 @@ const PLACEMENT_SPECS = {
     // project. A plain markdown spec; see docs/architecture/specs/fact-asset-type.md.
     fact: { stashDir: "facts", ...markdownSpec },
 };
+const _placementKeysSubsetOfKnownTypes = true;
+void _placementKeysSubsetOfKnownTypes;
+const PLACEMENT_SPECS = { ...BUILTIN_PLACEMENT_SPECS };
 /** Live placement spec for a type, or `undefined` for an unknown type. */
 export function placementSpecFor(type) {
     return PLACEMENT_SPECS[type];
@@ -174,9 +189,8 @@ export function stashDirFor(type) {
  * Reverse of {@link stashDirFor}: the placement type owning a stash subdir, or
  * `undefined` when no registered type places into it. The type→subdir map is a
  * bijection over the built-in types (each type has a distinct subdir), so this
- * is the well-defined inverse. Used by the Chunk-5 dual-grammar shim to reverse
- * a D-R2 qualified conceptId (`<stash-subdir>/<name>`) back to a legacy
- * `type:name` predicate so NULL-`item_ref` rows stay findable by new refs.
+ * is the well-defined inverse used to project a path-based conceptId onto the
+ * asset-type metadata required by native adapters.
  */
 export function typeForStashDir(stashDir) {
     for (const [type, spec] of Object.entries(PLACEMENT_SPECS)) {

package/dist/core/asset/asset-ref.js

@@ -11,16 +11,19 @@ function validateName(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.", "MISSING_REQUIRED_ARGUMENT");
-    const normalized = path.posix.normalize(name.replace(/\\/g, "/"));
+    const slashName = name.replace(/\\/g, "/");
+    if (slashName === ".." || slashName.startsWith("../")) {
+        throw new UsageError("Path traversal in asset name.", "MISSING_REQUIRED_ARGUMENT");
+    }
+    if (slashName.split("/").some((seg) => seg === "." || seg === "..")) {
+        throw new UsageError("Asset name cannot contain relative path segments.", "MISSING_REQUIRED_ARGUMENT");
+    }
+    const normalized = path.posix.normalize(slashName);
     if (path.posix.isAbsolute(normalized))
         throw new UsageError("Absolute path in asset name.", "MISSING_REQUIRED_ARGUMENT");
     if (normalized === ".." || normalized.startsWith("../")) {
         throw new UsageError("Path traversal in asset name.", "MISSING_REQUIRED_ARGUMENT");
     }
-    const segments = normalized.split("/");
-    if (segments.some((seg) => seg === "." || seg === "..")) {
-        throw new UsageError("Asset name cannot contain relative path segments.", "MISSING_REQUIRED_ARGUMENT");
-    }
 }
 function normalizeName(name) {
     return path.posix.normalize(name.replace(/\\/g, "/"));
@@ -34,9 +37,8 @@ function normalizeName(name) {
 const BUNDLE_SLUG_RE = /^[^\s:.#/]+$/;
 /**
  * True when `s` is a legal bundle slug (spec §11.1 / D-R5 charset: non-empty,
- * no `:`/`.`/`#`/`/` or whitespace). Exported so the dual-grammar input dispatch
- * (`resolve-ref.ts`) can classify a `prefix//tail` token by whether its prefix
- * is a legal bundle slug — the clean legacy-vs-new-grammar discriminator.
+ * no `:`/`.`/`#`/`/` or whitespace). Exported for input boundaries that need
+ * to distinguish bundle-qualified refs from source locators.
  */
 export function isBundleSlug(s) {
     return BUNDLE_SLUG_RE.test(s);
@@ -53,7 +55,7 @@ export function isBundleSlug(s) {
  * boundary punctuation (brackets/parens/quotes/backtick/comma/angle) so a
  * leading boundary char (e.g. the `[` of a markdown link) is not absorbed into
  * the slug. The concept segment reuses the same terminator charset as the
- * legacy body-ref scan (whitespace/quotes/brackets/comma/nl), and admits `/`,
+ * body-ref scan (whitespace/quotes/brackets/comma/nl), and admits `/`,
  * `.`, and a trailing `#fragment`.
  */
 export const BUNDLE_REF_RE = /(?:^|[\s`"'(,[])([^\s:.#/`"'()[\],<>]+\/\/[^\s"'`)\]>,\n]+)/gm;

package/dist/core/asset/frontmatter-lint.js

@@ -0,0 +1,30 @@
+// 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/.
+import { isScalar, parseDocument } from "yaml";
+/**
+ * Report a colon-bearing description only when YAML parsed it as a plain
+ * scalar. Quoted and block scalars may span physical lines and remain valid.
+ */
+export function checkUnquotedDescriptionColon(frontmatterText) {
+    if (!frontmatterText)
+        return null;
+    const document = parseDocument(frontmatterText);
+    const description = document.get("description", true);
+    if (document.errors.length === 0 &&
+        isScalar(description) &&
+        description.type === "PLAIN" &&
+        typeof description.value === "string" &&
+        description.value.includes(":")) {
+        return `description value contains unquoted colon: ${description.value}`;
+    }
+    // Preserve the existing finding for malformed plain scalars that YAML cannot
+    // construct, while letting valid multiline quoted/block scalars pass above.
+    if (document.errors.length > 0) {
+        const line = frontmatterText.split(/\r?\n/).find((candidate) => candidate.startsWith("description:"));
+        const value = line?.slice("description:".length).trim();
+        if (value?.includes(":"))
+            return `description value contains unquoted colon: ${value}`;
+    }
+    return null;
+}

package/dist/core/asset/frontmatter.js

@@ -10,6 +10,7 @@
  */
 import fs from "node:fs";
 import { parse as yamlParse, stringify as yamlStringify } from "yaml";
+import { recordWrittenPath } from "../write-provenance.js";
 import { assembleAsset, serializeFrontmatter } from "./asset-serialize.js";
 /**
  * Parse YAML frontmatter from a Markdown (or similar) string.
@@ -51,15 +52,11 @@ export function parseFrontmatter(raw) {
     };
 }
 /**
- * Normalize YAML-parsed values to match expected AKM frontmatter types.
+ * Normalize YAML dates to match expected AKM frontmatter types.
  *
- * Two conversions:
- * 1. `Date` → YYYY-MM-DD string: the yaml "core" schema parses bare date
+ * `Date` → YYYY-MM-DD string: the yaml "core" schema parses bare date
  *    scalars like `2026-06-18` as JS Date instances. AKM frontmatter treats
  *    `updated:` and similar fields as plain strings.
- * 2. `null` → `""`: the yaml library parses empty-value keys (`key:` with no
- *    value) as `null`, but AKM callers historically received `""` from the
- *    hand-rolled parser. Convert to preserve backward compatibility.
  */
 function normalizeYamlValues(value) {
     if (value instanceof Date) {
@@ -68,11 +65,9 @@ function normalizeYamlValues(value) {
         const d = String(value.getUTCDate()).padStart(2, "0");
         return `${y}-${m}-${d}`;
     }
-    if (value === null)
-        return "";
     if (Array.isArray(value))
         return value.map(normalizeYamlValues);
-    if (typeof value === "object") {
+    if (value !== null && typeof value === "object") {
         return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, normalizeYamlValues(v)]));
     }
     return value;
@@ -149,6 +144,9 @@ export function mutateFrontmatter(filePath, mutator) {
         ? `---\n${serializeFrontmatter(nextFrontmatter)}\n---\n${parsed.content}`
         : assembleAsset(nextFrontmatter, parsed.content);
     fs.writeFileSync(filePath, next, "utf8");
+    // #652: in-place frontmatter stamps (belief state, contradiction markers,
+    // salience) are real asset mutations — journal them for the run's sync.
+    recordWrittenPath(filePath);
     return true;
 }
 export function parseFrontmatterBlock(raw) {
@@ -182,6 +180,28 @@ function countLines(text) {
         return 0;
     return text.split(/\r?\n/).length - 1;
 }
+/**
+ * Insert one `key: value` line just before the closing `---` of an existing
+ * frontmatter block, leaving every other byte — YAML comments, quoting, key
+ * order, line endings — untouched. Returns null when `raw` has no well-formed
+ * block, so callers can fall back to a parse-and-serialize path.
+ *
+ * This is the source-preserving way to ADD a field to user-authored
+ * frontmatter: round-tripping the mapping through the YAML serializer drops
+ * comments and normalizes formatting, which is unacceptable for a write that
+ * only needs to contribute one line. Shared by `ensureAkmMarkdownType`
+ * (stamping `updated:` on write) and lint's `--fix` for `missing-updated`.
+ */
+export function spliceFrontmatterLine(raw, line) {
+    const lines = raw.split(/\r?\n/);
+    if (lines[0]?.trim() !== "---")
+        return null;
+    const closeIdx = lines.findIndex((l, i) => i > 0 && l.trim() === "---");
+    if (closeIdx === -1)
+        return null;
+    lines.splice(closeIdx, 0, line);
+    return lines.join("\n");
+}
 /**
  * Parse a YAML scalar value (string, boolean, or number).
  *

package/dist/core/asset/markdown.js

@@ -2,6 +2,34 @@
 // 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 { parseFrontmatter } from "./frontmatter.js";
+/** Stable GitHub-style selector for a Markdown heading. */
+export function markdownHeadingSlug(heading) {
+    return heading
+        .trim()
+        .toLowerCase()
+        .replace(/<[^>]*>/g, "")
+        .replace(/[^\p{L}\p{N}\s_-]+/gu, "-")
+        .replace(/[\s_]+/g, "-")
+        .replace(/-+/g, "-")
+        .replace(/^-|-$/g, "");
+}
+export function markdownFragmentSlugs(content) {
+    return uniqueHeadingSlugs(parseMarkdownToc(content).headings).filter(Boolean);
+}
+function uniqueHeadingSlugs(headings) {
+    const used = new Set();
+    return headings.map((heading) => {
+        const base = markdownHeadingSlug(heading.text);
+        if (!base)
+            return "";
+        let slug = base;
+        let suffix = 0;
+        while (used.has(slug))
+            slug = `${base}-${++suffix}`;
+        used.add(slug);
+        return slug;
+    });
+}
 // ── Parsing ─────────────────────────────────────────────────────────────────
 export function parseMarkdownToc(content) {
     const lines = content.split(/\r?\n/);
@@ -31,61 +59,22 @@ export function parseMarkdownToc(content) {
 // ── Extraction ──────────────────────────────────────────────────────────────
 export function extractSection(content, heading) {
     const lines = content.split(/\r?\n/);
-    const target = heading.toLowerCase();
-    let startIdx = -1;
-    let startLevel = 0;
-    for (let i = 0; i < lines.length; i++) {
-        const match = lines[i].match(/^(#{1,6})\s+(.+)$/);
-        if (!match)
-            continue;
-        const text = match[2].replace(/\s+#+\s*$/, "").trim();
-        if (text.toLowerCase() === target && startIdx === -1) {
-            startIdx = i;
-            startLevel = match[1].length;
-        }
-        else if (startIdx !== -1 && match[1].length <= startLevel) {
-            return {
-                content: lines.slice(startIdx, i).join("\n"),
-                startLine: startIdx + 1,
-                endLine: i,
-            };
-        }
-    }
-    if (startIdx === -1)
+    const headings = parseMarkdownToc(content).headings;
+    const fragment = heading.trim();
+    const slugIndex = uniqueHeadingSlugs(headings).indexOf(fragment);
+    const exact = slugIndex < 0 ? headings.find((candidate) => candidate.text.toLowerCase() === fragment.toLowerCase()) : undefined;
+    const selected = slugIndex >= 0 ? headings[slugIndex] : exact;
+    if (!selected)
         return null;
+    const next = headings.find((candidate) => candidate.line > selected.line && candidate.level <= selected.level);
+    const startIdx = selected.line - 1;
+    const endIdx = next ? next.line - 1 : lines.length;
     return {
-        content: lines.slice(startIdx).join("\n"),
-        startLine: startIdx + 1,
-        endLine: lines.length,
+        content: lines.slice(startIdx, endIdx).join("\n"),
+        startLine: selected.line,
+        endLine: endIdx,
     };
 }
-export function extractLineRange(content, start, end) {
-    const lines = content.split(/\r?\n/);
-    if (end < start)
-        return "";
-    const s = Math.max(1, Math.min(start, lines.length));
-    const e = Math.min(end, lines.length);
-    return lines.slice(s - 1, e).join("\n");
-}
-export function extractFrontmatterOnly(content) {
-    const parsed = parseFrontmatter(content);
-    return parsed.frontmatter;
-}
-// ── Formatting ──────────────────────────────────────────────────────────────
-export function formatToc(toc) {
-    if (toc.headings.length === 0) {
-        return `(no headings found — ${toc.totalLines} lines total)`;
-    }
-    const lineWidth = String(toc.totalLines).length;
-    const parts = toc.headings.map((h) => {
-        const lineNum = `L${String(h.line).padStart(lineWidth)}`;
-        const indent = "  ".repeat(h.level - 1);
-        const prefix = "#".repeat(h.level);
-        return `${lineNum}  ${indent}${prefix} ${h.text}`;
-    });
-    parts.push(`\n${toc.totalLines} lines total`);
-    return parts.join("\n");
-}
 // ── Fence stripping ──────────────────────────────────────────────────────────
 /**
  * Best-effort fence stripping. Strips `<think>` reasoning blocks emitted by

package/dist/core/asset/resolve-ref.js

@@ -34,7 +34,7 @@
  * grammar to bridge any more.
  */
 import { NotFoundError, UsageError } from "../errors.js";
-import { stashDirFor, typeForStashDir } from "./asset-placement.js";
+import { deriveCanonicalAssetNameFromStashRoot, placementSpecFor, stashDirFor, typeForStashDir, } from "./asset-placement.js";
 import { isBundleSlug, parseBundleRef } from "./asset-ref.js";
 /**
  * Resolve a maybe-short input ref to a fully-qualified {@link ResolvedRef}
@@ -82,10 +82,10 @@ function notFound(conceptId, triedForms, ctx) {
     return new NotFoundError(`No bundle contains concept "${conceptId}"${scope} (tried ${forms}).`, "ASSET_NOT_FOUND");
 }
 /**
- * D-R2 conceptId derivation from a legacy `type`/`name` pair
+ * D-R2 conceptId derivation from an asset `type`/`name` pair
  * (`stashDirFor(type)/name`; bare name for a foreign type with no placement
  * stash-subdir). Kept self-contained so {@link displayRef} — a PERMANENT display
- * rule — does not depend on the transient legacy shims.
+ * rule remains independent of input parsing.
  *
  * Exported (Chunk-8 WI-8.5c) as the ONE conceptId derivation the improve
  * correlation sites (`eligibility.ts` candidate refs, `salience.ts`
@@ -97,6 +97,19 @@ export function conceptIdFromTypeName(type, name) {
     const stashDir = stashDirFor(type);
     return stashDir !== undefined ? `${stashDir}/${name}` : name;
 }
+/**
+ * User-facing conceptId for a file on disk, derived through the placement
+ * spec's canonical-name rule — the ONE way a diagnostic should spell a ref it
+ * expects the user to paste into `akm show`. (The dangerous-env-key lint used
+ * to hand-build `env:<base>` colon refs the parser rejects; both its emission
+ * sites now route through here.) For a type with no placement spec — which no
+ * built-in caller passes — falls back to the raw name so the output is still
+ * informative rather than empty.
+ */
+export function conceptIdForStashFile(type, stashRoot, filePath) {
+    const name = deriveCanonicalAssetNameFromStashRoot(type, stashRoot, filePath);
+    return name === undefined ? filePath : conceptIdFromTypeName(type, name);
+}
 /**
  * Build the USER-FACING / envelope ref string for an indexed item, applying the
  * Chunk-5 flip F4b output-spelling rule (orchestrator decision; ref-grammar
@@ -116,19 +129,23 @@ export function conceptIdFromTypeName(type, name) {
  *     derived slug bundle id, never the retired `origin//type:name` spelling.
  */
 export function displayRef(item, defaultBundleId) {
-    const conceptId = item.conceptId ?? conceptIdFromTypeName(item.type, item.name);
-    const { bundleId } = item;
-    // Default/primary bundle → SHORT conceptId (the flip). `"local"`/`"stash"` are
-    // the primary-stash origin sentinels (never real bundle slugs — they name the
-    // workspace's own stash, exactly where the pre-0.9.0 output was un-qualified),
-    // so they display short too.
-    if (bundleId === undefined || bundleId === defaultBundleId || bundleId === "local" || bundleId === "stash")
+    return displayRefForConceptId(item.conceptId ?? conceptIdFromTypeName(item.type, item.name), item.bundleId, defaultBundleId);
+}
+/**
+ * The F4b output-spelling flip itself, for a caller that already holds the
+ * conceptId (no `type`/`name` derivation needed — e.g. lint findings built
+ * from {@link conceptIdForStashFile}). {@link displayRef} delegates here, so
+ * the short-default / qualified-secondary rule still has exactly one home.
+ */
+export function displayRefForConceptId(conceptId, bundleId, defaultBundleId) {
+    // Default/primary bundle → SHORT conceptId (the flip).
+    if (bundleId === undefined || bundleId === defaultBundleId)
         return conceptId;
     // Non-default bundle → the new fully-qualified `bundle//conceptId` grammar.
     return `${bundleId}//${conceptId}`;
 }
 /**
- * Split a qualified conceptId (`<stash-subdir>/<name>`) back to its legacy
+ * Split a qualified conceptId (`<stash-subdir>/<name>`) into its asset
  * `type`/`name`, or `undefined` when the leading segment is not a known stash
  * subdir (a bare-name conceptId from a foreign type — no legacy predicate
  * applies). The PERMANENT D-R2 reverse table: the input boundary uses it to map
@@ -144,6 +161,54 @@ export function typeNameFromConceptId(conceptId) {
         return undefined;
     return { type, name: conceptId.slice(slash + 1) };
 }
+/**
+ * D11 — the opaque-adapter-conceptId fallback. `typeNameFromConceptId` only
+ * ever answers for the PLACEMENT_SPECS stash-resident subset (D-R2); a
+ * conceptId whose leading segment is NOT a registered placement stashDir is
+ * still perfectly legal DATA per D11 — an OKF item (`tables/customers`), a
+ * website page, a wiki pageKind, an adapter `instruction` doc, … — and the
+ * ref-consuming commands must accept it rather than treat "not an AKM
+ * placement dir" as "malformed ref". This function draws the line: it accepts
+ * any well-formed `<segment>/<rest>` conceptId (so the shape is still
+ * anchored — a bare no-slash name stays the caller's job to pre-qualify with a
+ * default type, the existing env/secret/`akm mv` "bare name" convenience), and
+ * REJECTS anything shaped like the retired `type:name` colon grammar (Q-02):
+ * a `:` in the leading segment is that grammar smuggled through a conceptId
+ * string (e.g. `script:db/migrate/run.sh`, `workflow:release/train`), not a
+ * real adapter directory name, so it is refused rather than silently
+ * reinterpreted as opaque data.
+ *
+ * `name` deliberately carries the FULL original conceptId, not just the tail.
+ * This is what makes the pair round-trip through the UNCHANGED
+ * {@link conceptIdFromTypeName} (`stashDirFor(type)/name`, bare `name` when
+ * `type` has no placement stashDir): since an opaque `type` never owns a
+ * placement stashDir, `conceptIdFromTypeName(type, name)` falls to its bare-
+ * `name` branch and returns `name` verbatim — the original conceptId,
+ * unchanged — instead of losing the leading segment. `type` itself carries
+ * the leading segment (informational/behavioral use: `.type === "lesson"`
+ * checks correctly miss for opaque data) UNLESS that segment happens to
+ * collide with a real PLACEMENT_SPECS type key that merely uses a different
+ * stashDir spelling (e.g. a foreign top-level dir literally named "skill",
+ * singular) — that pathological case would make `stashDirFor` succeed on the
+ * "type" and corrupt the round-trip, so it falls back to the full conceptId as
+ * `type` too (never a placement key, since a placement key never contains
+ * `/`).
+ *
+ * This intentionally does NOT collapse the KNOWN_TYPES/PLACEMENT_SPECS split:
+ * `typeNameFromConceptId` (PLACEMENT_SPECS only) is untouched, and an opaque
+ * `type` returned here is never a {@link KnownType} — it is a passthrough
+ * label, not a claim that AKM recognizes or owns the concept.
+ */
+function opaqueRefParts(conceptId, allowRoot = false) {
+    const slash = conceptId.indexOf("/");
+    if (slash <= 0)
+        return allowRoot && !conceptId.includes(":") ? { type: conceptId, name: conceptId } : undefined;
+    const segment = conceptId.slice(0, slash);
+    if (segment.includes(":"))
+        return undefined; // retired `type:name` grammar, not opaque data (Q-02).
+    const type = placementSpecFor(segment) === undefined ? segment : conceptId;
+    return { type, name: conceptId };
+}
 /**
  * Parse a RAW user / CLI / API ref string in the 0.9.0 `[bundle//]conceptId`
  * grammar, returning it in today's {@link AssetRef} value-object shape
@@ -154,9 +219,14 @@ export function typeNameFromConceptId(conceptId) {
  *
  * Mapping (new grammar → {@link AssetRef}):
  *   - `conceptId` → `type`/`name` via {@link typeNameFromConceptId} (the D-R2
- *     static stash-subdir table). A conceptId whose leading segment is not a
- *     known stash subdir has no legacy `type` predicate — the same outcome an
- *     unknown asset type produces today (a not-found).
+ *     static stash-subdir table) when the leading segment is a known AKM
+ *     placement stashDir, else via {@link opaqueRefParts} (D11 — the ref-parser
+ *     seam accepts opaque adapter conceptIds, e.g. OKF items, website pages,
+ *     wiki pageKinds, adapter `instruction` docs) when it is merely a well-
+ *     formed but foreign `<segment>/<rest>` shape. A conceptId that is neither
+ *     — no slash at all, or a retired colon-grammar shape smuggled through —
+ *     has no type predicate: the same not-found outcome a genuine typo
+ *     produces today.
  *   - `bundle`    → `origin`. A new-grammar bundle slug is a registryId-shaped
  *     id by construction, so it flows straight into the legacy origin channel
  *     that `resolveSourcesForOrigin` matches on `registryId`. The SHORT form (no
@@ -168,11 +238,11 @@ export function parseRefInput(raw) {
     if (ref.fragment !== undefined) {
         throw new UsageError(`Export fragment "#${ref.fragment}" is not accepted here — drop it from "${raw.trim()}".`, "INVALID_FLAG_VALUE");
     }
-    const legacy = typeNameFromConceptId(ref.conceptId);
-    if (legacy === undefined) {
+    const parts = typeNameFromConceptId(ref.conceptId) ?? opaqueRefParts(ref.conceptId, ref.bundle !== undefined);
+    if (parts === undefined) {
         throw new NotFoundError(`Unrecognized asset ref "${raw.trim()}": conceptId "${ref.conceptId}" has no known asset-type prefix.`, "ASSET_NOT_FOUND");
     }
-    return { type: legacy.type, name: legacy.name, origin: ref.bundle };
+    return { type: parts.type, name: parts.name, origin: ref.bundle };
 }
 /**
  * Parse a CLI/API ref that MAY be qualified by a NON-slug origin — a registry
@@ -215,7 +285,8 @@ export function isFullRefInput(raw) {
     if (!trimmed)
         return false;
     try {
-        return typeNameFromConceptId(parseBundleRef(trimmed).conceptId) !== undefined;
+        const parsed = parseBundleRef(trimmed);
+        return parsed.bundle !== undefined || typeNameFromConceptId(parsed.conceptId) !== undefined;
     }
     catch {
         return false;

package/dist/core/asset/stash-meta.js

@@ -7,7 +7,7 @@
  * A stash may carry an optional, human-authored `.meta/` directory at its
  * root holding orientation docs for the stash as a whole: purpose, key
  * assets, conventions, maintainer info. Because `.meta/` is a dot-directory,
- * the indexer's walker already skips it (see `src/indexer/walker.ts`), so
+ * the indexer's walker already skips it (see `src/indexer/walk/walker.ts`), so
  * these files never pollute the search corpus. They are surfaced on demand
  * via `akm show [<origin>//]meta[:<name>]`, which direct-reads the file
  * rather than going through the index.

package/dist/core/bundle-id.js

@@ -0,0 +1,51 @@
+// 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/.
+import crypto from "node:crypto";
+import path from "node:path";
+import { isBundleSlug } from "./asset/asset-ref.js";
+/** Deterministic, filesystem-safe bundle slug from a source path. */
+export function slugForPath(sourcePath) {
+    const resolved = path.resolve(sourcePath);
+    const base = path
+        .basename(resolved)
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+    if (base.length > 0)
+        return base;
+    return `bundle-${shortHash(resolved)}`;
+}
+/** Derive one batch-unique bundle id. */
+export function deriveBundleId(registryId, sourcePath, usedIds) {
+    const preferred = registryId && registryId.length > 0 && isBundleSlug(registryId) ? registryId : slugForPath(sourcePath);
+    const id = ensureUniqueId(preferred, sourcePath, usedIds);
+    usedIds.add(id);
+    return id;
+}
+/** Derive an ordered batch while reserving every explicit configured bundle id. */
+export function deriveBundleIds(sources) {
+    const usedIds = new Set();
+    const reservedIds = new Set(sources.flatMap((source) => (source.registryId && isBundleSlug(source.registryId) ? [source.registryId] : [])));
+    return sources.map((source) => {
+        const id = source.registryId && isBundleSlug(source.registryId)
+            ? deriveBundleId(source.registryId, source.path, usedIds)
+            : deriveBundleId(undefined, source.path, new Set([...usedIds, ...reservedIds]));
+        usedIds.add(id);
+        return id;
+    });
+}
+function ensureUniqueId(preferred, sourcePath, used) {
+    if (!used.has(preferred))
+        return preferred;
+    const suffixed = `${preferred}-${shortHash(path.resolve(sourcePath))}`;
+    if (!used.has(suffixed))
+        return suffixed;
+    let n = 2;
+    while (used.has(`${suffixed}-${n}`))
+        n++;
+    return `${suffixed}-${n}`;
+}
+function shortHash(input) {
+    return crypto.createHash("sha256").update(input).digest("hex").slice(0, 8);
+}