akm-cli 0.9.0-rc.8 → 0.9.0

package/dist/core/adapter/adapters/akm-workflow-adapter.js

@@ -4,27 +4,20 @@
 /**
  * The `akm-workflow` adapter — akm 0.9.0 format-family work item (#46).
  *
- * A native akm workflow bundle (spec §6/§7). Both workflow forms derive
- * `type: workflow`:
- *   - MARKDOWN (`.md`, ≈ an OKF concept) — the classic linear workflow
- *     (`# Workflow:` / `## Step:` / `Step ID:` / `### Instructions`), detected
- *     by the shared `looksLikeWorkflow` probe so the matcher and parser cannot
- *     drift;
- *   - YAML PROGRAM (`.yaml`/`.yml`, an AKM extension) — `version` + `steps`,
- *     detected by `looksLikeWorkflowProgram`.
- * conceptId strips the recognized workflow extension (`.md`/`.yaml`/`.yml`). A
- * plain `.md` that is NOT workflow-shaped (a README, an OKF reserved listing/log
- * file) is abstained on — the content probe subsumes the D-R6 reserved-file
- * exclusion, so no reserved-basename literal is needed here.
+ * A native akm workflow bundle (spec §6/§7). One format now (workflow-format-
+ * unification): `.md` files, orchestration graph in frontmatter, per-step
+ * prose in the body. Recognition is frontmatter `type: workflow`, or — since
+ * this adapter's whole domain IS workflows — simply residing under this
+ * bundle's root; no content sniffing. conceptId strips the `.md` extension. A
+ * plain `.md` that opts out via an explicit non-workflow `type:` frontmatter
+ * key is abstained on.
  *
  * ── validate (spec §6 workflow row) ──
  *
  * Reuses the akm adapter's per-type workflow checks (shared base checks +
- * `placeholder-stub` + `invalid-workflow-structure`, markdown only — the YAML
- * program's correctness is `parseWorkflowProgram`'s own result, not a
- * markdown-lint path). Delegates to the SAME `perTypeValidateChecks` /
- * `runBaseValidateChecks` the `akm` adapter uses, so workflow validation has
- * one home.
+ * `placeholder-stub` + `invalid-workflow-structure`). Delegates to the SAME
+ * `perTypeValidateChecks` / `runBaseValidateChecks` the `akm` adapter uses, so
+ * workflow validation has one home.
  *
  * Conformance oracle (authored, DO NOT modify): fixture
  * `tests/fixtures/bundles/akm-workflow/` + goldens
@@ -32,60 +25,52 @@
  */
 import fs from "node:fs";
 import path from "node:path";
-import { parse as parseYaml } from "yaml";
-import { looksLikeWorkflow } from "../../../workflows/parser.js";
-import { looksLikeWorkflowProgram } from "../../../workflows/program/parser.js";
 import { parseFrontmatter } from "../../asset/frontmatter.js";
 import { perTypeValidateChecks } from "./akm-lint.js";
 import { hashContent, nonEmptyString, readTags, runBaseValidateChecks } from "./shared.js";
 /** A native workflow bundle is single-component; its one component is `main`. */
 const COMPONENT_ID = "main";
-/** Recognized workflow extensions (matcher parity with recognition-util WORKFLOW_EXTENSIONS). */
-const WORKFLOW_EXTS = new Set([".md", ".yaml", ".yml"]);
+/** One recognized workflow extension now (workflow-format-unification): `.md`. */
+const WORKFLOW_EXTS = new Set([".md"]);
 /** Upper bound on the bounded `content` FTS field (mirrors okf-adapter). */
 const MAX_CONTENT_CHARS = 100_000;
 function toPosix(p) {
     return p.replace(/\\/g, "/");
 }
-/** Strip a recognized workflow extension from a component-root-relative path → conceptId. */
+/** Strip the recognized workflow extension from a component-root-relative path → conceptId. */
 function conceptIdOf(relPath) {
-    return toPosix(relPath).replace(/\.(md|ya?ml)$/i, "");
+    return toPosix(relPath).replace(/\.md$/i, "");
 }
-/** Which workflow form (if any) `file` is — the recognition gate. */
-function workflowForm(ext, raw) {
-    if (ext === ".md")
-        return looksLikeWorkflow(parseFrontmatter(raw).content) ? "markdown" : null;
-    if (ext === ".yaml" || ext === ".yml")
-        return looksLikeWorkflowProgram(raw) ? "yaml-program" : null;
-    return null;
+/** `README.md` (case-insensitive) is documentation, never the typed asset — mirrors the akm matcher stack's D-R6 reserved-file exclusion (`TYPED_DIR_DOC_FILES`). */
+function isReservedDocFile(fileName) {
+    return fileName.toLowerCase() === "readme.md";
 }
-/** The workflow's projected `description` — frontmatter for markdown, the program `description:` for YAML. */
-function workflowDescription(form, raw) {
-    if (form === "markdown")
-        return nonEmptyString(parseFrontmatter(raw).data.description);
-    try {
-        const doc = parseYaml(raw);
-        if (doc && typeof doc === "object" && !Array.isArray(doc)) {
-            return nonEmptyString(doc.description);
-        }
-    }
-    catch {
-        // malformed YAML — no description
-    }
-    return undefined;
+/**
+ * Recognition gate: any `.md` file in this bundle IS a workflow (this
+ * adapter's entire domain is workflows — spec §2.5, "residence under
+ * workflows/"), UNLESS its frontmatter declares a DIFFERENT non-empty
+ * `type:` (an explicit opt-out, e.g. a README-shaped doc that wants to be
+ * something else). No content sniffing.
+ */
+function isWorkflowFile(raw) {
+    const data = parseFrontmatter(raw).data;
+    const type = data.type;
+    return type === undefined || type === "workflow";
 }
 function recognize(c, file) {
     if (!WORKFLOW_EXTS.has(file.ext))
         return null;
+    if (isReservedDocFile(file.fileName))
+        return null;
     const raw = file.content();
-    const form = workflowForm(file.ext, raw);
-    if (form === null)
+    if (!isWorkflowFile(raw))
         return null;
     const conceptId = conceptIdOf(file.relPath);
     const name = conceptId.split("/").pop() ?? conceptId;
-    const description = workflowDescription(form, raw);
-    const body = form === "markdown" ? parseFrontmatter(raw).content : raw;
-    const tags = readTags(parseFrontmatter(raw).data.tags);
+    const parsed = parseFrontmatter(raw);
+    const description = nonEmptyString(parsed.data.description);
+    const body = parsed.content;
+    const tags = readTags(parsed.data.tags);
     const doc = {
         ref: `${c.id}//${conceptId}`,
         bundle: c.id,
@@ -113,18 +98,11 @@ async function validate(c, changes, ctx) {
         if (typeof raw !== "string")
             continue;
         const ext = path.extname(change.path).toLowerCase();
-        if (!WORKFLOW_EXTS.has(ext) || workflowForm(ext, raw) === null)
+        if (!WORKFLOW_EXTS.has(ext) || isReservedDocFile(path.basename(change.path)) || !isWorkflowFile(raw))
             continue;
         const relPath = toPosix(change.path);
-        // Markdown workflows parse via frontmatter; YAML programs are pure YAML (no frontmatter).
-        let parsed;
-        if (ext === ".md") {
-            const p = parseFrontmatter(raw);
-            parsed = { data: p.data, content: p.content, frontmatter: p.frontmatter };
-        }
-        else {
-            parsed = { data: {}, content: raw, frontmatter: null };
-        }
+        const p = parseFrontmatter(raw);
+        const parsed = { data: p.data, content: p.content, frontmatter: p.frontmatter };
         diagnostics.push(...(await runBaseValidateChecks(relPath, parsed, c.root, ctx)));
         diagnostics.push(...(await perTypeValidateChecks({
             type: "workflow",
@@ -139,13 +117,22 @@ async function validate(c, changes, ctx) {
     }
     return diagnostics;
 }
-/** True when a top-level file in `root` is workflow-shaped (used by looksLikeRoot). */
+/**
+ * True when a top-level file in `root` is workflow-shaped (used by
+ * looksLikeRoot). Unlike `isWorkflowFile` (which admits an absent `type:` —
+ * the lenient default ONCE a source is already known to be this bundle),
+ * this requires an EXPLICIT `type: workflow` — the install-time probe is
+ * choosing WHICH adapter owns an unconfigured root among several candidates
+ * (spec §1.2), and an incidental `.md` with no frontmatter type at all
+ * (common in an OKF or llm-wiki bundle) must not misclassify that root as
+ * akm-workflow's.
+ */
 function hasTopLevelWorkflowFile(root, entries) {
     for (const entry of entries) {
         if (!entry.isFile())
             continue;
         const ext = path.extname(entry.name).toLowerCase();
-        if (!WORKFLOW_EXTS.has(ext))
+        if (!WORKFLOW_EXTS.has(ext) || isReservedDocFile(entry.name))
             continue;
         let raw;
         try {
@@ -154,7 +141,7 @@ function hasTopLevelWorkflowFile(root, entries) {
         catch {
             continue;
         }
-        if (workflowForm(ext, raw) !== null)
+        if (parseFrontmatter(raw).data.type === "workflow")
             return true;
     }
     return false;
@@ -162,13 +149,13 @@ function hasTopLevelWorkflowFile(root, entries) {
 export const akmWorkflowAdapter = {
     id: "akm-workflow",
     version: "0.9.0",
-    extensions: [".md", ".yaml", ".yml"],
+    extensions: [".md"],
     recognize,
     validate,
-    /** Default markdown placement; an explicit `.yaml`/`.yml`/`.md` conceptId short-circuits to that extension. */
+    /** Markdown placement; an explicit `.md` conceptId short-circuits to that extension. */
     placeNew(c, conceptId) {
         const posix = toPosix(conceptId);
-        if (/\.(md|ya?ml)$/i.test(posix))
+        if (/\.md$/i.test(posix))
             return path.join(c.root, posix);
         return path.join(c.root, `${posix}.md`);
     },
@@ -177,11 +164,8 @@ export const akmWorkflowAdapter = {
         return ["."];
     },
     /**
-     * Install-time probe (§1.2): a root holding a workflow file at top level — a
-     * `.yaml`/`.yml` program (`version` + `steps`) or a workflow-shaped `.md`. The
-     * content probe means an okf reserved listing, a wiki `schema.md`, or a README
-     * never trips it, so the probe stays disjoint from the other adapters' roots
-     * without any structural exclusion.
+     * Install-time probe (§1.2): a root holding a workflow-shaped `.md` file at
+     * top level (frontmatter `type: workflow` or no `type:` at all).
      */
     looksLikeRoot(root) {
         let entries;

package/dist/core/adapter/adapters/dotenv-adapter.js

@@ -18,7 +18,7 @@
  *
  * ── validate (spec §6 env/secret validation column) ──
  *
- * The dangerous-key scan (`dangerous-vault-key`), reusing the akm adapter's
+ * The dangerous-key scan (`dangerous-env-key`), reusing the akm adapter's
  * `dangerousEnvKeyDiagnostics` — which preserves the code-grounded narrowness:
  * it runs ONLY on `*.env`-suffixed files, so `secrets/<bare-name>` is never
  * scanned (its whole content is an opaque secret value). Reads KEY NAMES only.

package/dist/core/adapter/adapters/generic-files-adapter.js

@@ -71,6 +71,8 @@ function recognize(c, file) {
         name,
         content: body.length > MAX_CONTENT_CHARS ? body.slice(0, MAX_CONTENT_CHARS) : body,
     };
+    if (type !== "script")
+        doc.ownsPresentation = true;
     const description = nonEmptyString(parsed.data.description);
     if (description !== undefined)
         doc.description = description;

package/dist/core/adapter/adapters/index.js

@@ -33,10 +33,10 @@ export { websiteSnapshotAdapter } from "./website-snapshot-adapter.js";
  *
  * Probe-precedence rationale (grounds "cannot shadow the existing three"):
  *
- *  - The three loosest probes — `llm-wiki` (schema.md + pages/), `okf` (root
- *    index doc), `akm` (a placement stash subdir / `.stash`) — stay LAST and in
- *    their established order (`llm-wiki` BEFORE `okf`: a wiki root also carries a
- *    root index doc, so the more-specific wiki probe must win the overlap).
+ *  - The three loosest probes — `llm-wiki`, `akm`, and `okf` — stay LAST.
+ *    Native AKM evidence wins before OKF because AKM Markdown is an OKF
+ *    superset; the AKM probe is correspondingly strict enough not to claim an
+ *    OKF bundle merely because it contains one familiar directory name.
  *  - `akm.looksLikeRoot` fires on ANY root carrying a stash-subdir-named
  *    directory — which includes a `.claude`/`.opencode` tool dir (`commands/`,
  *    `agents/`, `skills/`) and a dotenv bundle (`env/`, `secrets/`). So
@@ -62,10 +62,10 @@ export const BUILTIN_ADAPTERS = Object.freeze([
     // Native akm sub-formats (disjoint content-shape probes).
     akmWorkflowAdapter,
     akmTaskAdapter,
-    // The three established loose probes, in their established order.
+    // Loose probes: specific native layouts before the portable OKF baseline.
     llmWikiAdapter,
-    okfAdapter,
     akmAdapter,
+    okfAdapter,
     // Explicit-config fallback (never auto-selected) — last.
     genericFilesAdapter,
 ]);

package/dist/core/adapter/adapters/llm-wiki-adapter.js

@@ -5,8 +5,8 @@
  * The first-class `llm-wiki` adapter — akm 0.9.0 chunk-4 (DEV-7 restore).
  *
  * The `wiki` ASSET-TYPE dies in chunk 4 (plan §11 Chunk 4 / §7.4), but the LLM
- * Wiki structure stays first-class as its OWN adapter. This relocates the native
- * wiki semantics from `src/wiki/wiki.ts` + `src/wiki/wiki-templates.ts` into a
+ * Wiki structure stays first-class as its OWN adapter. This relocates the
+ * native wiki semantics from the retired `src/wiki/` module into a
  * `BundleAdapter` implementing `docs/architecture/specs/akm-0.9.0-bundle-adapter-spec.md` §7
  * (llm-wiki row), §6 (wiki-page row), §0.2 (the `wiki` asset-type is retired;
  * the adapter is first-class), §1.2 (probe = schema.md + pages/), §9 (links).
@@ -42,7 +42,8 @@
  *
  * ── validate (spec §6/§7, §9) — native wiki checks ONLY ──
  *
- * The native structural checks ported from `wiki.ts#lintWiki`: `broken-xref`
+ * The native structural checks ported from the retired `src/wiki/` module's
+ * `lintWiki`: `broken-xref`
  * (an xref target that does not resolve to an existing page), `uncited-raw`
  * (a `raw/` source not cited by any page's `sources:`), `missing-description`
  * (a page with no description), and `broken-source` (a page `sources:` entry
@@ -58,11 +59,15 @@
  *
  * ── Cycle-safety ──
  *
- * Imported ONLY by the test-only `adapters/index.ts` barrel (nothing in `src/`
- * imports that), so this leaf can never gain an inbound edge from a cycle
- * participant. It value-imports only pure leaves (`frontmatter`, `shared`) plus
- * Node builtins + `yaml` (already a runtime dep). Verified: `bun
- * scripts/lint-import-cycles.ts` stays within baseline (13) with this file present.
+ * Imported by the `adapters/index.ts` barrel, which is NOT test-only: `core/
+ * adapter/registry.ts:33` imports it in production for the frozen
+ * `BUILTIN_ADAPTERS` list (`installations.ts#detectAdapterId`,
+ * `provider-utils.ts#detectStashRoot`). This still can never gain an inbound
+ * edge from a cycle participant, since neither the barrel nor the registry
+ * import anything that imports back into this file. It value-imports only
+ * pure leaves (`frontmatter`, `shared`) plus Node builtins + `yaml` (already a
+ * runtime dep). Verified: `bun scripts/lint-import-cycles.ts` reports 0 cycle
+ * participants with this file present.
  */
 import fs from "node:fs";
 import path from "node:path";
@@ -272,6 +277,7 @@ function recognize(c, file) {
         path: file.absPath,
         hash: hashContent(raw),
         adapterId: "llm-wiki",
+        ownsPresentation: true,
         type: isRaw ? WIKI_SOURCE_TYPE : (fm.pageKind ?? DEFAULT_PAGE_KIND),
         name: lastSegment,
         content: body.length > MAX_CONTENT_CHARS ? body.slice(0, MAX_CONTENT_CHARS) : body,

package/dist/core/adapter/adapters/okf-adapter.js

@@ -25,12 +25,106 @@
  *    WARNING (consumers tolerate broken links). Reads go through
  *    `ctx.readFile`; ref existence via `ctx.resolveRef`. Never touches the live
  *    filesystem.
- *  - placeNew / directoryList / looksLikeRoot per §5 / §1.2.
+ *  - directoryList / looksLikeRoot per §5 / §1.2. Authoring is deliberately
+ *    absent; AKM-native writers fail before mutating an OKF bundle.
  */
 import fs from "node:fs";
 import path from "node:path";
 import { parseFrontmatter } from "../../asset/frontmatter.js";
 import { hashContent, nonEmptyString, readTags, runBaseValidateChecks } from "./shared.js";
+/** v0.2 frontmatter keys consumed into first-class fields below (§0.1) — excluded from the generic `documentJson` extras fold alongside the v0.1 five, so nothing is duplicated between a first-class field and the opaque extras bag. */
+const CONSUMED_FRONTMATTER_KEYS = [
+    "type",
+    "title",
+    "description",
+    "tags",
+    "timestamp",
+    "generated",
+    "verified",
+    "sources",
+    "status",
+    "stale_after",
+    "okf_version",
+];
+/** True for a plain (non-null, non-array) object — the shape every v0.2 mapping (`generated`, one `verified`/`sources` entry) must have. */
+function isPlainObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+/**
+ * Parse one `verified:` actor mapping (`{by, at?}`). Tolerant: a missing/blank
+ * `by` yields `undefined` (the entry is dropped, never rejecting the document
+ * — OKF conformance leniency); `at` is independently optional.
+ */
+function parseActorMapping(value) {
+    if (!isPlainObject(value))
+        return undefined;
+    const by = nonEmptyString(value.by);
+    if (by === undefined)
+        return undefined;
+    const at = nonEmptyString(value.at);
+    return at !== undefined ? { by, at } : { by };
+}
+/**
+ * Parse the `verified:` family. v0.2 permits EITHER a list of `{by, at?}`
+ * mappings OR a single mapping written without the list dash (the shorthand
+ * form) — both normalize to a non-empty array here. Malformed entries are
+ * dropped individually; an entirely-empty/malformed result is `undefined`
+ * rather than `[]` (mirrors every other optional-field convention on this
+ * adapter: absent, not empty).
+ */
+function parseVerified(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    const candidates = Array.isArray(value) ? value : [value];
+    const out = [];
+    for (const candidate of candidates) {
+        const parsed = parseActorMapping(candidate);
+        if (parsed)
+            out.push(parsed);
+    }
+    return out.length > 0 ? out : undefined;
+}
+/**
+ * Parse the `sources:` object-list family. Each entry needs at minimum a
+ * non-empty `resource`; entries failing that are dropped individually (never
+ * rejects the document). This is a DIFFERENT shape from the AKM-native
+ * `IndexDocument.sources: string[]` (wiki citations) — the two are never
+ * mixed, hence the caller lands this under `provenance.sources` instead.
+ */
+function parseOkfSources(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    const out = [];
+    for (const item of value) {
+        if (!isPlainObject(item))
+            continue;
+        const resource = nonEmptyString(item.resource);
+        if (resource === undefined)
+            continue;
+        const entry = { resource };
+        const id = nonEmptyString(item.id);
+        if (id !== undefined)
+            entry.id = id;
+        const title = nonEmptyString(item.title);
+        if (title !== undefined)
+            entry.title = title;
+        const author = nonEmptyString(item.author);
+        if (author !== undefined)
+            entry.author = author;
+        if (typeof item.usage_count === "number" && Number.isFinite(item.usage_count)) {
+            entry.usage_count = item.usage_count;
+        }
+        const lastModified = nonEmptyString(item.last_modified);
+        if (lastModified !== undefined)
+            entry.last_modified = lastModified;
+        out.push(entry);
+    }
+    return out.length > 0 ? out : undefined;
+}
+/** Parse the `status:` lifecycle field — a strict whitelist; any other value (including a foreign/future status) is left unset rather than guessed at. */
+function parseLifecycleStatus(value) {
+    return value === "draft" || value === "stable" || value === "deprecated" ? value : undefined;
+}
 /** Reserved OKF files (case-insensitive) — recognized, never indexed as concepts (§5, OKF §1.4). */
 const RESERVED_FILES = new Set(["index.md", "log.md"]);
 /** Upper bound on the bounded `content` FTS field (§3: "content: FTS 1 (bounded)"). Small fixtures are never truncated. */
@@ -59,13 +153,24 @@ function isReservedFileName(name) {
  */
 export function resolveOkfLinks(body, fileRelPath) {
     const dir = path.posix.dirname(toPosix(fileRelPath));
-    const linkRe = /\[[^\]]*\]\(([^)]+)\)/g;
+    const definitions = new Map();
+    for (const match of body.matchAll(/^\s*\[([^\]]+)\]:\s*(\S+)/gm)) {
+        definitions.set(match[1].trim().toLowerCase(), match[2]);
+    }
+    const candidates = [];
+    for (const match of body.matchAll(/\[[^\]]*\]\(([^)]+)\)/g)) {
+        candidates.push({ index: match.index, target: match[1] });
+    }
+    for (const match of body.matchAll(/(?<!!)\[[^\]]*\]\[([^\]]+)\]/g)) {
+        const target = definitions.get(match[1].trim().toLowerCase());
+        if (target)
+            candidates.push({ index: match.index, target });
+    }
+    candidates.sort((a, b) => a.index - b.index);
     const out = [];
     const seen = new Set();
-    let match;
-    // biome-ignore lint/suspicious/noAssignInExpressions: idiomatic regex loop
-    while ((match = linkRe.exec(body)) !== null) {
-        let target = match[1].trim();
+    for (const candidate of candidates) {
+        let target = candidate.target.trim();
         // Drop an optional markdown link title: `[x](/a.md "Title")`.
         const wsIdx = target.search(/\s/);
         if (wsIdx >= 0)
@@ -127,8 +232,33 @@ function recognize(c, file) {
     const name = nonEmptyString(data.title) ?? lastSegment;
     const description = nonEmptyString(data.description);
     const tags = readTags(data.tags);
-    const updated = nonEmptyString(data.timestamp);
     const links = resolveOkfLinks(body, file.relPath);
+    // v0.2 trust/provenance/lifecycle families (§0.1, okf-support.md v0.2 note).
+    // `generated.at` — v0.2's replacement for `timestamp` — takes precedence;
+    // `timestamp` remains a fully valid fallback (the v0.2-permitted legacy
+    // reading, not merely tolerated). Both stay fully optional (never rejects).
+    const generatedMapping = isPlainObject(data.generated) ? data.generated : undefined;
+    const generatedAt = generatedMapping ? nonEmptyString(generatedMapping.at) : undefined;
+    const generatedBy = generatedMapping ? nonEmptyString(generatedMapping.by) : undefined;
+    const legacyTimestamp = nonEmptyString(data.timestamp);
+    const updated = generatedAt ?? legacyTimestamp;
+    const verified = parseVerified(data.verified);
+    const okfSources = parseOkfSources(data.sources);
+    const provenance = generatedBy !== undefined || generatedAt !== undefined || verified !== undefined || okfSources !== undefined
+        ? {
+            ...(generatedBy !== undefined ? { generatedBy } : {}),
+            ...(generatedAt !== undefined ? { generatedAt } : {}),
+            ...(verified !== undefined ? { verified } : {}),
+            ...(okfSources !== undefined ? { sources: okfSources } : {}),
+        }
+        : undefined;
+    const lifecycleStatus = parseLifecycleStatus(data.status);
+    const staleAfter = nonEmptyString(data.stale_after);
+    // `okf_version` is upstream-declared only on a bundle-root `index.md` (never
+    // indexed as a concept, §5) — read defensively from any concept anyway
+    // (best-effort, conformance Rule 9); a producer that also tags ordinary
+    // concepts with it is neither rejected nor silently ignored.
+    const okfVersion = nonEmptyString(data.okf_version);
     const doc = {
         ref: `${c.id}//${conceptId}`,
         bundle: c.id,
@@ -139,6 +269,7 @@ function recognize(c, file) {
         // incrementality/fingerprints (`types.ts` hash doc comment).
         hash: hashContent(raw),
         adapterId: "okf",
+        ownsPresentation: true,
         type,
         name,
         content: body.length > MAX_CONTENT_CHARS ? body.slice(0, MAX_CONTENT_CHARS) : body,
@@ -151,6 +282,17 @@ function recognize(c, file) {
         doc.updated = updated;
     if (links.length > 0)
         doc.links = links;
+    if (provenance !== undefined)
+        doc.provenance = provenance;
+    if (lifecycleStatus !== undefined)
+        doc.lifecycleStatus = lifecycleStatus;
+    if (staleAfter !== undefined)
+        doc.staleAfter = staleAfter;
+    if (okfVersion !== undefined)
+        doc.okfVersion = okfVersion;
+    const extras = Object.fromEntries(Object.entries(data).filter(([key]) => !CONSUMED_FRONTMATTER_KEYS.includes(key)));
+    if (Object.keys(extras).length > 0)
+        doc.documentJson = extras;
     return doc;
 }
 async function validate(c, changes, ctx) {
@@ -165,14 +307,11 @@ async function validate(c, changes, ctx) {
         const fileName = relPath.split("/").pop() ?? relPath;
         const reserved = isReservedFileName(fileName);
         const parsed = parseFrontmatter(raw);
-        // Base checks (unquoted-colon / missing-updated / stale-path / missing-ref).
+        // Base checks shared with native AKM formats. OKF's timestamp is optional,
+        // so the AKM-specific freshness diagnostic is removed unconditionally.
         const base = await runBaseValidateChecks(relPath, parsed, c.root, ctx);
-        // §0.1: for OKF content a `timestamp` satisfies the freshness requirement
-        // (the base-linter's `missing-updated` maps to `timestamp`). Suppress the
-        // `missing-updated` diagnostic when a non-empty `timestamp` is present.
-        const hasTimestamp = nonEmptyString(parsed.data.timestamp) !== undefined;
         for (const diag of base) {
-            if (hasTimestamp && diag.issue === "missing-updated")
+            if (diag.issue === "missing-updated")
                 continue;
             diagnostics.push(diag);
         }
@@ -208,16 +347,45 @@ export const okfAdapter = {
     extensions: [".md"],
     recognize,
     validate,
-    /** `<c.root>/<conceptId>.md` (§5). */
-    placeNew(c, conceptId) {
-        return path.join(c.root, `${conceptId}.md`);
-    },
     /** OKF concepts live anywhere under the component root (§5). */
     directoryList(_c) {
         return ["."];
     },
-    /** Install-time probe: a root is an OKF bundle when it has a root `index.md` (§1.2; `okf_version` NOT required). */
+    /**
+     * Install-time probe. A root index is sufficient; an index-less root is also
+     * OKF when it contains at least one conformant concept with a non-empty open
+     * `type`. More-specific native adapters run before this portable baseline.
+     */
     looksLikeRoot(root) {
-        return fs.existsSync(path.join(root, "index.md"));
+        if (fs.existsSync(path.join(root, "index.md")))
+            return true;
+        const stack = [root];
+        while (stack.length > 0) {
+            const current = stack.pop();
+            if (!current)
+                continue;
+            let entries;
+            try {
+                entries = fs.readdirSync(current, { withFileTypes: true });
+            }
+            catch {
+                continue;
+            }
+            for (const entry of entries) {
+                if (entry.isSymbolicLink() || entry.name === ".git")
+                    continue;
+                const absolute = path.join(current, entry.name);
+                if (entry.isDirectory()) {
+                    stack.push(absolute);
+                    continue;
+                }
+                if (!entry.isFile() || !entry.name.toLowerCase().endsWith(".md") || isReservedFileName(entry.name))
+                    continue;
+                const type = nonEmptyString(parseFrontmatter(fs.readFileSync(absolute, "utf8")).data.type);
+                if (type)
+                    return true;
+            }
+        }
+        return false;
     },
 };

package/dist/core/adapter/adapters/shared.js

@@ -49,6 +49,7 @@
  */
 import { createHash } from "node:crypto";
 import { parseFrontmatter } from "../../asset/frontmatter.js";
+import { checkUnquotedDescriptionColon } from "../../asset/frontmatter-lint.js";
 // ── Small pure helpers, reused across the concrete adapters ──────────────────
 /** Content hash feeding `IndexDocument.hash` (incrementality/fingerprints, `types.ts` doc comment). */
 export function hashContent(content) {
@@ -69,23 +70,6 @@ export function readTags(value) {
     return tags.length > 0 ? tags : undefined;
 }
 // ── Base validate checks (port of `BaseLinter.runBaseChecks`) ────────────────
-function checkUnquotedColon(frontmatterText) {
-    if (!frontmatterText)
-        return null;
-    for (const line of frontmatterText.split(/\r?\n/)) {
-        const match = line.match(/^description:\s*(.*)/);
-        if (!match)
-            continue;
-        const value = match[1].trim();
-        if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
-            return null;
-        }
-        if (value.includes(":")) {
-            return `description value contains unquoted colon: ${value}`;
-        }
-    }
-    return null;
-}
 function checkMissingUpdated(data, frontmatterText) {
     return frontmatterText !== null && !("updated" in data);
 }
@@ -207,7 +191,7 @@ function readRefStringOrArray(value) {
 export async function runBaseValidateChecks(relPath, parsed, componentRoot, ctx) {
     const diagnostics = [];
     const { data, content: body, frontmatter } = parsed;
-    const unquotedColonDetail = checkUnquotedColon(frontmatter);
+    const unquotedColonDetail = checkUnquotedDescriptionColon(frontmatter);
     if (unquotedColonDetail) {
         diagnostics.push({ file: relPath, issue: "unquoted-colon", detail: unquotedColonDetail, fixed: false });
     }
@@ -228,7 +212,7 @@ export async function runBaseValidateChecks(relPath, parsed, componentRoot, ctx)
         if (found !== null)
             continue;
         const portableHint = candidate.startsWith(componentRoot)
-            ? ` (portable form: $AKM_STASH_DIR${candidate.slice(componentRoot.length)})`
+            ? ` (portable form: $AKM_BUNDLE_DIR${candidate.slice(componentRoot.length)})`
             : "";
         diagnostics.push({
             file: relPath,

package/dist/core/adapter/adapters/tool-dir-shared.js

@@ -41,9 +41,12 @@
  * ── Cycle-safety ──
  *
  * Imported only by `claude-adapter.ts` / `opencode-adapter.ts` (themselves
- * imported only by the test-only `adapters/index.ts` barrel), so this leaf can
- * never gain an inbound edge from a cycle participant. It value-imports only
- * pure leaves (`shared`, `akm-lint`, `frontmatter`) plus Node builtins.
+ * imported by the `adapters/index.ts` barrel — NOT test-only: `core/adapter/
+ * registry.ts:33` imports it in production for the frozen `BUILTIN_ADAPTERS`
+ * list). This leaf still can never gain an inbound edge from a cycle
+ * participant, since nothing on that import chain imports back into it. It
+ * value-imports only pure leaves (`shared`, `akm-lint`, `frontmatter`) plus
+ * Node builtins.
  */
 import path from "node:path";
 import { parseFrontmatter } from "../../asset/frontmatter.js";
@@ -121,6 +124,8 @@ export function recognizeToolDir(layout, c, file) {
         name,
         content: body.length > MAX_CONTENT_CHARS ? body.slice(0, MAX_CONTENT_CHARS) : body,
     };
+    if (cls.type === "instruction")
+        doc.ownsPresentation = true;
     if (description !== undefined)
         doc.description = description;
     if (tags !== undefined)