akm-cli 0.9.1 → 0.9.2-alpha.2

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

@@ -2,12 +2,12 @@
 // 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/.
 /**
- * The `akm-task` adapter — akm 0.9.0 format-family work item (#46).
+ * The `akm-task` adapter for strict task-v3 `.yml` sources.
  *
  * A native akm task-YAML bundle (spec §6/§7). A `.yml` file derives
  * `type: task`; conceptId strips the `.yml` extension. Tasks are AKM-native
  * YAML, NOT OKF markdown concepts. Recognition does NOT gate on validity — an
- * invalid task (e.g. two targets) is still RECOGNIZED; the `invalid-task-yaml`
+ * invalid task (e.g. `uses` plus `run`) is still RECOGNIZED; the `invalid-task-yaml`
  * violation surfaces only in `validate`.
  *
  * `.yaml` is the one extension `validate` inspects but `recognize` refuses: it
@@ -16,13 +16,11 @@
  *
  * ── validate (spec §6 task validation column) ──
  *
- * A task must declare `version: 2`, a `schedule`, and EXACTLY ONE target
- * (`prompt` XOR `workflow` XOR `command`). `enabled` is OPTIONAL — the parser
- * defaults it to `true`, so an omitted field means an ACTIVE task — but must
- * be a boolean when present. The akm adapter's `TaskLinter` port checks
- * "at least one" target; the native task family here is STRICTER — declaring
- * two targets is `invalid-task-yaml`. So this adapter owns a purpose-built
- * one-target check rather than reusing that port.
+ * Validation enters the canonical task-v3 source parser. That parser owns the
+ * closed key sets, executable-selector XOR, scheduling-source XOR, hostile
+ * YAML policy, trigger classification, built-in action validation, bounds,
+ * and physical `working-directory` containment. The adapter only translates a
+ * parser failure into the format-family diagnostic shape.
  *
  * Conformance oracle (authored, DO NOT modify): fixture
  * `tests/fixtures/bundles/akm-task/` + goldens
@@ -30,14 +28,12 @@
  */
 import fs from "node:fs";
 import path from "node:path";
-import { isPresentTarget, parseTaskYaml, TASK_EXTENSION, TASK_NEAR_MISS_EXTENSION, taskExtensionDetail, taskFieldProblems, taskYamlParseDetail, } from "../../../tasks/schema.js";
+import { parseTaskV3Yaml, TASK_EXTENSION, TASK_NEAR_MISS_EXTENSION, taskExtensionDetail, taskV3SourceErrorDetail, } from "../../../tasks/source-v3.js";
 import { hashContent } from "./shared.js";
 /** A native task bundle is single-component; its one component is `main`. */
 const COMPONENT_ID = "main";
 /** The task YAML extension (spec §6 task row). */
 const TASK_EXT = TASK_EXTENSION;
-/** The mutually-exclusive task target keys (exactly one required). */
-const TARGET_KEYS = ["prompt", "workflow", "command"];
 /** Upper bound on the bounded `content` FTS field (mirrors okf-adapter). */
 const MAX_CONTENT_CHARS = 100_000;
 function toPosix(p) {
@@ -62,29 +58,7 @@ function recognize(c, file) {
         content: raw.length > MAX_CONTENT_CHARS ? raw.slice(0, MAX_CONTENT_CHARS) : raw,
     };
 }
-/**
- * The native `invalid-task-yaml` check: the shared field rules
- * ({@link taskFieldProblems} — see its doc for the lint-vs-parser
- * reconciliation story) plus this adapter's stricter EXACTLY-ONE-target rule.
- */
-function taskDiagnostics(relPath, data) {
-    if (Object.keys(data).length === 0)
-        return [];
-    const problems = taskFieldProblems(data);
-    // Shared presence rule (src/tasks/schema.ts): an empty string or empty array
-    // is not a target, matching the runtime parser.
-    const targets = TARGET_KEYS.filter((k) => isPresentTarget(data[k]));
-    if (targets.length === 0)
-        problems.push("exactly one target (prompt, workflow, or command)");
-    else if (targets.length > 1)
-        problems.push(`exactly one target — declares ${targets.length} (${targets.join(", ")})`);
-    if (problems.length === 0)
-        return [];
-    return [
-        { file: relPath, issue: "invalid-task-yaml", detail: `task field errors: ${problems.join("; ")}`, fixed: false },
-    ];
-}
-async function validate(_c, changes, ctx) {
+async function validate(c, changes, ctx) {
     const diagnostics = [];
     for (const change of changes) {
         if (change.op === "delete")
@@ -106,27 +80,25 @@ async function validate(_c, changes, ctx) {
                 detail: taskExtensionDetail(relPath),
                 fixed: false,
             });
+            continue;
+        }
+        try {
+            parseTaskV3Yaml({ yaml: raw, filePath: relPath, workspaceRoot: c.root });
         }
-        const parsed = parseTaskYaml(raw);
-        if (!parsed.ok) {
-            // Distinguish "unparseable" from "empty": `taskDiagnostics` returns []
-            // for an empty mapping, so collapsing a parse failure onto `{}` made a
-            // broken task file lint clean.
+        catch (cause) {
             diagnostics.push({
                 file: relPath,
                 issue: "invalid-task-yaml",
-                detail: taskYamlParseDetail(parsed.error),
+                detail: taskV3SourceErrorDetail(cause),
                 fixed: false,
             });
-            continue;
         }
-        diagnostics.push(...taskDiagnostics(relPath, parsed.data));
     }
     return diagnostics;
 }
 export const akmTaskAdapter = {
     id: "akm-task",
-    version: "0.9.0",
+    version: "0.9.2",
     // `.yaml` is listed as a COLLECTION hint only — `recognize` still gates on
     // `.yml`, so a `.yaml` file is never indexed as a task. Listing it is what
     // routes the near-miss file into `validate`, where it is reported instead of
@@ -134,6 +106,13 @@ export const akmTaskAdapter = {
     extensions: [TASK_EXT, TASK_NEAR_MISS_EXTENSION],
     recognize,
     validate,
+    readCandidates(c, conceptId) {
+        const posix = toPosix(conceptId).replace(/\.ya?ml$/i, "");
+        return [
+            { path: path.join(c.root, `${posix}.yml`), conceptId: posix },
+            { path: path.join(c.root, `${posix}.yaml`), conceptId: posix },
+        ];
+    },
     /** A task places to `<conceptId>.yml`; an already-suffixed conceptId is idempotent. */
     placeNew(c, conceptId) {
         const posix = toPosix(conceptId);
@@ -144,9 +123,9 @@ export const akmTaskAdapter = {
         return ["."];
     },
     /**
-     * Install-time probe (§1.2): a root holding a top-level `.yml` file that
-     * parses as a task (a `schedule` key). The task-shape probe keeps it disjoint
-     * from non-task YAML.
+     * Install-time probe (§1.2): a root holding a top-level, valid task-v3
+     * `.yml` file. The full parser keeps this disjoint from unrelated YAML and
+     * prevents probe semantics from drifting from validation semantics.
      */
     looksLikeRoot(root) {
         let entries;
@@ -166,9 +145,13 @@ export const akmTaskAdapter = {
             catch {
                 continue;
             }
-            const { data } = parseTaskYaml(raw);
-            if (typeof data.schedule === "string" && data.schedule.trim() !== "")
+            try {
+                parseTaskV3Yaml({ yaml: raw, filePath: entry.name, workspaceRoot: root });
                 return true;
+            }
+            catch {
+                // Continue probing the remaining top-level .yml files.
+            }
         }
         return false;
     },

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

@@ -4,13 +4,9 @@
 /**
  * The `akm-workflow` adapter — akm 0.9.0 format-family work item (#46).
  *
- * 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.
+ * A native akm workflow bundle. AKM Markdown and the strict local GitHub-shaped
+ * `.yml` subset are peer source formats. Both compile through the source IR;
+ * neither source is rewritten or projected onto the other.
  *
  * ── validate (spec §6 workflow row) ──
  *
@@ -25,13 +21,14 @@
  */
 import fs from "node:fs";
 import path from "node:path";
+import { looksLikeGithubWorkflowSource } from "../../../workflows/source-ir/compile.js";
 import { parseFrontmatter } from "../../asset/frontmatter.js";
-import { perTypeValidateChecks } from "./akm-lint.js";
+import { perTypeValidateChecks, workflowYamlSourceDiagnostics } 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";
-/** One recognized workflow extension now (workflow-format-unification): `.md`. */
-const WORKFLOW_EXTS = new Set([".md"]);
+/** The two authoritative workflow source formats. `.yaml` is deliberately not accepted. */
+const WORKFLOW_EXTS = new Set([".md", ".yml"]);
 /** Upper bound on the bounded `content` FTS field (mirrors okf-adapter). */
 const MAX_CONTENT_CHARS = 100_000;
 function toPosix(p) {
@@ -39,7 +36,7 @@ function toPosix(p) {
 }
 /** Strip the recognized workflow extension from a component-root-relative path → conceptId. */
 function conceptIdOf(relPath) {
-    return toPosix(relPath).replace(/\.md$/i, "");
+    return toPosix(relPath).replace(/\.(?:md|yml)$/i, "");
 }
 /** `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) {
@@ -63,14 +60,14 @@ function recognize(c, file) {
     if (isReservedDocFile(file.fileName))
         return null;
     const raw = file.content();
-    if (!isWorkflowFile(raw))
+    if (file.ext === ".md" && !isWorkflowFile(raw))
         return null;
     const conceptId = conceptIdOf(file.relPath);
     const name = conceptId.split("/").pop() ?? conceptId;
     const parsed = parseFrontmatter(raw);
-    const description = nonEmptyString(parsed.data.description);
-    const body = parsed.content;
-    const tags = readTags(parsed.data.tags);
+    const description = file.ext === ".md" ? nonEmptyString(parsed.data.description) : undefined;
+    const body = file.ext === ".md" ? parsed.content : raw;
+    const tags = file.ext === ".md" ? readTags(parsed.data.tags) : undefined;
     const doc = {
         ref: `${c.id}//${conceptId}`,
         bundle: c.id,
@@ -98,9 +95,15 @@ async function validate(c, changes, ctx) {
         if (typeof raw !== "string")
             continue;
         const ext = path.extname(change.path).toLowerCase();
-        if (!WORKFLOW_EXTS.has(ext) || isReservedDocFile(path.basename(change.path)) || !isWorkflowFile(raw))
+        if (!WORKFLOW_EXTS.has(ext) || isReservedDocFile(path.basename(change.path)))
             continue;
         const relPath = toPosix(change.path);
+        if (ext === ".yml") {
+            diagnostics.push(...workflowYamlSourceDiagnostics(relPath, raw, relPath, c.root).errors);
+            continue;
+        }
+        if (!isWorkflowFile(raw))
+            continue;
         const p = parseFrontmatter(raw);
         const parsed = { data: p.data, content: p.content, frontmatter: p.frontmatter };
         diagnostics.push(...(await runBaseValidateChecks(relPath, parsed, c.root, ctx)));
@@ -141,21 +144,33 @@ function hasTopLevelWorkflowFile(root, entries) {
         catch {
             continue;
         }
-        if (parseFrontmatter(raw).data.type === "workflow")
+        if (ext === ".yml" && looksLikeGithubWorkflowSource(raw))
+            return true;
+        if (ext === ".md" && parseFrontmatter(raw).data.type === "workflow")
             return true;
     }
     return false;
 }
 export const akmWorkflowAdapter = {
     id: "akm-workflow",
-    version: "0.9.0",
-    extensions: [".md"],
+    version: "0.9.2",
+    extensions: [".md", ".yml"],
     recognize,
     validate,
-    /** Markdown placement; an explicit `.md` conceptId short-circuits to that extension. */
+    readCandidates(c, conceptId) {
+        const posix = toPosix(conceptId);
+        const canonical = posix.replace(/\.(?:md|yml)$/i, "");
+        return /\.(?:md|yml)$/i.test(posix)
+            ? [{ path: path.join(c.root, posix), conceptId: canonical }]
+            : [
+                { path: path.join(c.root, `${posix}.md`), conceptId: canonical },
+                { path: path.join(c.root, `${posix}.yml`), conceptId: canonical },
+            ];
+    },
+    /** Markdown remains the default; an explicit `.md`/`.yml` suffix is preserved. */
     placeNew(c, conceptId) {
         const posix = toPosix(conceptId);
-        if (/\.md$/i.test(posix))
+        if (/\.(?:md|yml)$/i.test(posix))
             return path.join(c.root, posix);
         return path.join(c.root, `${posix}.md`);
     },
@@ -164,8 +179,8 @@ export const akmWorkflowAdapter = {
         return ["."];
     },
     /**
-     * Install-time probe (§1.2): a root holding a workflow-shaped `.md` file at
-     * top level (frontmatter `type: workflow` or no `type:` at all).
+     * Install-time probe (§1.2): a root holding an explicitly typed Markdown
+     * workflow or a complete GitHub-shaped YAML workflow at top level.
      */
     looksLikeRoot(root) {
         let entries;

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

@@ -96,6 +96,19 @@ function scanKeyNames(raw) {
     }
     return keys;
 }
+function conceptIdForPath(type, relativePath) {
+    const posix = toPosix(relativePath);
+    if (type === "secret")
+        return posix;
+    const stripped = posix.replace(/\.env$/i, "");
+    return stripped.endsWith("/") ? `${stripped}default` : stripped;
+}
+function recognizePathCandidates(_c, file) {
+    const type = classify(file.relPath);
+    if (type === null || hasSensitiveMarker(file.absPath, type))
+        return [];
+    return [conceptIdForPath(type, file.relPath)];
+}
 function recognize(c, file) {
     const type = classify(file.relPath);
     if (type === null)
@@ -106,7 +119,7 @@ function recognize(c, file) {
     const raw = file.content();
     if (type === "env") {
         // env: strip `.env`; surface KEY NAMES only (never values/comments/content).
-        const conceptId = posix.replace(/\.env$/i, "");
+        const conceptId = conceptIdForPath(type, posix);
         const name = (conceptId.split("/").pop() ?? conceptId) || "default";
         const keys = scanKeyNames(raw);
         const doc = {
@@ -159,7 +172,23 @@ export const dotenvAdapter = {
     version: "0.9.0",
     extensions: [".env"],
     recognize,
+    recognizePathCandidates,
     validate,
+    readCandidates(c, conceptId) {
+        const posix = toPosix(conceptId);
+        const slash = posix.indexOf("/");
+        if (slash <= 0)
+            return [];
+        const head = posix.slice(0, slash);
+        const rest = posix.slice(slash + 1);
+        const type = typeForStashDir(head);
+        if ((type !== "env" && type !== "secret") || rest.length === 0)
+            return [];
+        const primary = assetPathForName(type, path.join(c.root, head), rest);
+        return (type === "env"
+            ? [primary, primary.replace(/\.env$/i, ".sensitive")]
+            : [primary, `${primary}.sensitive`, `${primary}.lock`]).map((candidatePath) => ({ path: candidatePath, conceptId: posix }));
+    },
     /**
      * env places to `env/<name>.env`, secret to `secrets/<name>` (identity join,
      * no extension logic) — reusing the shared `assetPathForName` so the env

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

@@ -102,6 +102,17 @@ export const genericFilesAdapter = {
     extensions: [".md", ".txt"],
     recognize,
     validate,
+    readCandidates(c, conceptId) {
+        const posix = toPosix(conceptId);
+        const extension = path.extname(posix).toLowerCase();
+        const documentCandidates = [...DOCUMENT_EXTENSIONS].map((candidateExtension) => ({
+            path: path.join(c.root, `${posix}${candidateExtension}`),
+            conceptId: posix,
+        }));
+        return DOCUMENT_EXTENSIONS.has(extension)
+            ? documentCandidates
+            : [{ path: path.join(c.root, posix), conceptId: posix }, ...documentCandidates];
+    },
     /**
      * IDENTITY placement (open-question-5): a conceptId that carries an extension
      * (`script`/`file`) places to itself; an extension-less conceptId (a

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

@@ -69,12 +69,3 @@ export const BUILTIN_ADAPTERS = Object.freeze([
     // Explicit-config fallback (never auto-selected) — last.
     genericFilesAdapter,
 ]);
-/**
- * DEPRECATED no-op retained for test back-compat only. The built-in set is now
- * the static, frozen {@link BUILTIN_ADAPTERS}, exposed by the registry at
- * module load (normative §12.6), so there is nothing to register. New code MUST
- * NOT call this — `getAdapters()` / `adapterForId()` are always populated.
- */
-export function registerBuiltinAdapters() {
-    // intentionally empty — BUILTIN_ADAPTERS is static; see the doc comment above.
-}

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

@@ -395,6 +395,10 @@ export const llmWikiAdapter = {
     extensions: [".md"],
     recognize,
     validate,
+    readCandidates(c, conceptId) {
+        const canonical = toPosix(conceptId).replace(/\.md$/i, "");
+        return [{ path: path.join(c.root, `${canonical}.md`), conceptId: canonical }];
+    },
     /** `<c.root>/<conceptId>.md` — the conceptId already carries its `pages/`/`raw/` prefix (placement golden). */
     placeNew(c, conceptId) {
         return path.join(c.root, `${conceptId}.md`);

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

@@ -347,6 +347,10 @@ export const okfAdapter = {
     extensions: [".md"],
     recognize,
     validate,
+    readCandidates(c, conceptId) {
+        const canonical = conceptId.replace(/\\/g, "/").replace(/\.md$/i, "");
+        return [{ path: path.join(c.root, `${canonical}.md`), conceptId: canonical }];
+    },
     /** OKF concepts live anywhere under the component root (§5). */
     directoryList(_c) {
         return ["."];

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

@@ -9,10 +9,7 @@
  * https://opencode.ai/docs/{commands,agents,skills,rules}/): a root `AGENTS.md`
  * → `instruction`, `commands/*.md` → `command`, `agents/*.md` → `agent`,
  * `skills/<name>/SKILL.md` → `skill`, and ABSTAINS on `opencode.json` runtime
- * config. Per open-question-6 (RESOLVED, accept BOTH forms) the SINGULAR
- * `command/`/`agent/`/`skill/` dirs are accepted as backwards-compat aliases on
- * READ (the conceptId preserves the on-disk spelling, e.g. `command/legacy`);
- * WRITES normalize to the canonical plural (handled in the shared codec).
+ * config. Only OpenCode's canonical plural tool directories are accepted.
  *
  * All behavior lives in the shared tool-dir codec ({@link makeToolDirAdapter});
  * this module supplies only the `.opencode` layout + the install-time probe.
@@ -29,12 +26,12 @@ const LAYOUT = {
     componentId: ".opencode",
     instructionFile: "AGENTS.md",
     instructionConceptId: "AGENTS",
-    commandDirs: new Set(["commands", "command"]),
-    agentDirs: new Set(["agents", "agent"]),
-    skillDirs: new Set(["skills", "skill"]),
+    commandDirs: new Set(["commands"]),
+    agentDirs: new Set(["agents"]),
+    skillDirs: new Set(["skills"]),
 };
 const CONFIG_FILES = ["opencode.json", "opencode.jsonc"];
-const TOOL_DIRS = ["commands", "command", "agents", "agent", "skills", "skill"];
+const TOOL_DIRS = ["commands", "agents", "skills"];
 function fileExists(p) {
     try {
         return fs.existsSync(p);

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

@@ -8,10 +8,8 @@
  * open AKM `type` vocabulary (spec §6/§7): a root instruction file
  * (CLAUDE.md / AGENTS.md) → `instruction`, `commands/*.md` → `command`,
  * `agents/*.md` → `agent`, `skills/<name>/SKILL.md` → `skill` (item = the dir).
- * They differ only in three parameters carried on {@link ToolDirLayout}:
+ * They differ only in two parameters carried on {@link ToolDirLayout}:
  *   - the instruction basename + its concept id,
- *   - the accepted subdir spellings (opencode accepts the SINGULAR
- *     `command/`/`agent/`/`skill/` aliases per open-question-6, claude does not),
  *   - the adapter id + component id.
  *
  * The SKILL.md codec is shared with the `agent-skills` adapter as functions
@@ -49,7 +47,9 @@
  * Node builtins.
  */
 import path from "node:path";
+import { createAdapterExtensions, } from "../../../execution/source.js";
 import { parseFrontmatter } from "../../asset/frontmatter.js";
+import { executionDefaultsFromFrontmatter, renderMarkdownExecutionSource } from "../execution-source.js";
 import { skillDirectoryDiagnostics } from "./akm-lint.js";
 import { hashContent, nonEmptyString, readTags, runBaseValidateChecks } from "./shared.js";
 /** OKF reserved structural files (D-R6) — excluded at every depth, case-insensitive. */
@@ -85,7 +85,7 @@ function classify(relPath, layout) {
     // skill: <skillDir>/<name>/SKILL.md — the item is the DIRECTORY. Any other
     // file under a skill dir (bundled resources) is part of the item, not a concept.
     if (layout.skillDirs.has(head)) {
-        if (segs.length >= 3 && base === SKILL_MANIFEST) {
+        if (segs.length === 3 && base === SKILL_MANIFEST) {
             return { type: "skill", conceptId: `${segs[0]}/${segs[1]}`, name: segs[1] };
         }
         return null;
@@ -155,6 +155,25 @@ export function placeNewToolDir(layout, c, conceptId) {
     }
     return path.join(c.root, `${posix}.md`);
 }
+/** List native read spellings. */
+export function readCandidatesToolDir(layout, c, conceptId) {
+    const posix = toPosix(conceptId);
+    if (posix === layout.instructionConceptId) {
+        return [{ path: path.join(c.root, layout.instructionFile), conceptId: posix }];
+    }
+    const segs = posix.split("/").filter((segment) => segment.length > 0);
+    const head = segs[0];
+    const rest = segs.slice(1).join("/");
+    if (!head || !rest)
+        return [];
+    if (layout.skillDirs.has(head)) {
+        return segs.length === 2 ? [{ path: path.join(c.root, head, rest, SKILL_MANIFEST), conceptId: posix }] : [];
+    }
+    if (layout.commandDirs.has(head) || layout.agentDirs.has(head)) {
+        return [{ path: path.join(c.root, head, `${rest}.md`), conceptId: posix }];
+    }
+    return [];
+}
 /** LENIENT command/agent check: a diagnostic only when NEITHER a name/description NOR a type-shaped signal is present. */
 function nameOrSignalDiagnostics(type, relPath, data, body) {
     if (nonEmptyString(data.name) !== undefined || nonEmptyString(data.description) !== undefined)
@@ -187,8 +206,7 @@ export async function validateToolDir(layout, c, changes, ctx) {
         // The one coded skill check (missing-skill-md) fires on ANY change under a
         // `<skillDir>/<name>/…` package (self-gated + deduped), even a bundled
         // resource — mirrors the akm adapter's per-change SkillLinter.lintDirectory
-        // pass. `layout.skillDirs` is passed so opencode's singular `skill/` alias
-        // is checked identically to `skills/` (issue #774).
+        // pass.
         diagnostics.push(...(await skillDirectoryDiagnostics(relPath, seenSkillDirs, ctx, layout.skillDirs)));
         const cls = classify(change.path, layout);
         if (cls === null)
@@ -204,6 +222,43 @@ export async function validateToolDir(layout, c, changes, ctx) {
     }
     return diagnostics;
 }
+function nativeExecutionExtensions(layout, cls, data) {
+    const values = {};
+    if (layout.adapterId === "claude" && cls.type === "command" && Object.hasOwn(data, "argument-hint")) {
+        if (typeof data["argument-hint"] !== "string") {
+            throw new TypeError("frontmatter.argument-hint must be a string");
+        }
+        values.argumentHint = data["argument-hint"];
+    }
+    if (layout.adapterId === "opencode" && Object.hasOwn(data, "mode")) {
+        if (typeof data.mode !== "string")
+            throw new TypeError("frontmatter.mode must be a string");
+        values.mode = data.mode;
+    }
+    return Object.keys(values).length > 0 ? createAdapterExtensions(layout.adapterId, values) : undefined;
+}
+/** Translate a native Claude/OpenCode command or agent without exposing raw frontmatter. */
+export function renderToolDirExecutionSource(layout, c, file) {
+    const cls = classify(file.relPath, layout);
+    if (cls?.type !== "command" && cls?.type !== "agent")
+        return null;
+    const raw = file.content();
+    return renderMarkdownExecutionSource({
+        kind: cls.type === "command" ? "command" : "persona",
+        raw,
+        identity: {
+            ref: `${c.id}//${cls.conceptId}`,
+            bundle: c.id,
+            adapter: layout.adapterId,
+            file: file.relPath,
+        },
+        defaults: (data) => executionDefaultsFromFrontmatter(data, {
+            kind: cls.type === "command" ? "command" : "persona",
+            toolsKeys: layout.adapterId === "claude" && cls.type === "command" ? ["allowed-tools", "tools"] : ["tools"],
+        }),
+        extensions: (data) => nativeExecutionExtensions(layout, cls, data),
+    });
+}
 /** Build the concrete `BundleAdapter` from a layout + a `looksLikeRoot` probe (claude/opencode share everything else). */
 export function makeToolDirAdapter(layout, looksLikeRoot) {
     return {
@@ -211,7 +266,9 @@ export function makeToolDirAdapter(layout, looksLikeRoot) {
         version: "0.9.0",
         extensions: [".md"],
         recognize: (c, file) => recognizeToolDir(layout, c, file),
+        renderExecutionSource: (c, file) => renderToolDirExecutionSource(layout, c, file),
         validate: (c, changes, ctx) => validateToolDir(layout, c, changes, ctx),
+        readCandidates: (c, conceptId) => readCandidatesToolDir(layout, c, conceptId),
         placeNew: (c, conceptId) => placeNewToolDir(layout, c, conceptId),
         directoryList: () => [CANONICAL_COMMAND_DIR, CANONICAL_AGENT_DIR, CANONICAL_SKILL_DIR],
         looksLikeRoot,

package/dist/core/adapter/adapters/website-snapshot-adapter.js

@@ -129,6 +129,10 @@ export const websiteSnapshotAdapter = {
     extensions: [".md"],
     recognize,
     validate,
+    readCandidates(c, conceptId) {
+        const canonical = toPosix(conceptId).replace(/\.md$/i, "");
+        return [{ path: path.join(c.root, PAGES_PREFIX, `${canonical}.md`), conceptId: canonical }];
+    },
     // No placeNew: the snapshot is READ-ONLY (Mode A). Export (Mode B) routes
     // content through the DESTINATION adapter, which owns placement.
     /**