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

package/dist/commands/workflow-cli.js

@@ -12,6 +12,7 @@
  * `looksLikeWorkflowRunId` and `resolveWorkflowFilePath` move with the family.
  */
 import { defineCommand } from "citty";
+import { getStringArg } from "../cli/parse-args.js";
 import { defineJsonCommand, output, runWithJsonErrors } from "../cli/shared.js";
 import { assertFlatAssetName, combineCreatePath, normalizeCreateSubPath } from "../core/asset/asset-create.js";
 import { parseAssetRef } from "../core/asset/asset-ref.js";
@@ -22,9 +23,10 @@ import { resolveSourceEntries } from "../indexer/search/search-source.js";
 import { hasBooleanFlag } from "../output/context.js";
 import { resolveSourcesForOrigin } from "../registry/origin-resolve.js";
 import { resolveAssetPath } from "../sources/resolve.js";
-import { createWorkflowAsset, formatWorkflowErrors, getWorkflowTemplate, validateWorkflowSource, } from "../workflows/authoring/authoring.js";
+import { createWorkflowAsset, formatWorkflowErrors, getWorkflowProgramTemplate, getWorkflowTemplate, validateWorkflowProgramSource, validateWorkflowSource, } from "../workflows/authoring/authoring.js";
 import { hasWorkflowSubcommand, parseWorkflowJsonObject, parseWorkflowStepState, WORKFLOW_STEP_STATES, } from "../workflows/cli.js";
-import { completeWorkflowStep, getNextWorkflowStep, getWorkflowStatus, listWorkflowRuns, resumeWorkflowRun, startWorkflowRun, } from "../workflows/runtime/runs.js";
+import { isWorkflowProgramPath } from "../workflows/program/project.js";
+import { abandonWorkflowRun, completeWorkflowStep, getNextWorkflowStep, getWorkflowStatus, listWorkflowRuns, resumeWorkflowRun, startWorkflowRun, } from "../workflows/runtime/runs.js";
 const workflowStartCommand = defineJsonCommand({
     meta: {
         name: "start",
@@ -140,9 +142,16 @@ const workflowStatusCommand = defineJsonCommand({
     },
     args: {
         target: { type: "positional", description: "Workflow run id or workflow ref (workflow:<name>)", required: true },
+        units: {
+            type: "boolean",
+            description: "Also list per-unit rows from the run journal (unit id, status, failure_reason, and any result/error " +
+                "diagnostic text). Diagnostics only — step evidence stays deterministic and is unaffected (#22).",
+            default: false,
+        },
     },
     async run({ args }) {
         const target = args.target;
+        const includeUnits = args.units === true;
         // Check if target looks like a workflow ref
         const parsed = (() => {
             try {
@@ -161,11 +170,11 @@ const workflowStatusCommand = defineJsonCommand({
             const mostRecent = runs[0];
             if (!mostRecent)
                 throw new NotFoundError(`No workflow runs found for ${ref}`, "WORKFLOW_NOT_FOUND");
-            const result = await getWorkflowStatus(mostRecent.id);
+            const result = await getWorkflowStatus(mostRecent.id, { includeUnits });
             output("workflow-status", result);
         }
         else {
-            const result = await getWorkflowStatus(target);
+            const result = await getWorkflowStatus(target, { includeUnits });
             output("workflow-status", result);
         }
     },
@@ -187,19 +196,22 @@ const workflowListCommand = defineJsonCommand({
 const workflowCreateCommand = defineJsonCommand({
     meta: {
         name: "create",
-        description: "Create a workflow markdown document in the working stash",
+        description: "Create a workflow in the working stash (markdown document by default; a .yaml/.yml name writes a YAML program)",
     },
     args: {
         name: {
             type: "positional",
-            description: "Workflow name (flat, no '/'; use --path for a subdirectory)",
+            description: "Workflow name (flat, no '/'; use --path for a subdirectory). A .yaml/.yml suffix creates a YAML program.",
             required: true,
         },
         path: {
             type: "string",
             description: "Relative subdirectory under workflows/ to place the workflow in (e.g. 'release'). The filename comes from the name.",
         },
-        from: { type: "string", description: "Import and validate markdown from an existing file" },
+        from: {
+            type: "string",
+            description: "Import and validate content from an existing file (parsed per the destination extension)",
+        },
         force: {
             type: "boolean",
             description: "Overwrite an existing workflow (requires --from or --reset)",
@@ -237,26 +249,54 @@ const workflowCreateCommand = defineJsonCommand({
 const workflowTemplateCommand = defineCommand({
     meta: {
         name: "template",
-        description: "Print a valid workflow markdown template",
+        description: "Print a valid workflow template (markdown by default, --yaml for a YAML program)",
     },
-    run() {
-        process.stdout.write(getWorkflowTemplate());
+    args: {
+        yaml: {
+            type: "boolean",
+            description: "Print a minimal valid YAML workflow program instead of the markdown template",
+            default: false,
+        },
+    },
+    run({ args }) {
+        process.stdout.write(args.yaml ? getWorkflowProgramTemplate() : getWorkflowTemplate());
     },
 });
 const workflowValidateCommand = defineJsonCommand({
     meta: {
         name: "validate",
-        description: "Validate a workflow markdown file or ref and print any errors",
+        description: "Validate a workflow file or ref (markdown document or YAML program) and print any errors",
     },
     args: {
         target: {
             type: "positional",
-            description: "Workflow ref (workflow:<name>) or filesystem path to a workflow .md",
+            description: "Workflow ref (workflow:<name>) or filesystem path to a workflow .md/.yaml",
             required: true,
         },
     },
     async run({ args }) {
         const filePath = await resolveWorkflowFilePath(args.target);
+        // YAML programs (redesign addendum, R1) validate through the program
+        // parser AND compiler so expression/reference errors surface at lint
+        // time; both error lists carry line numbers. Markdown is unchanged.
+        if (isWorkflowProgramPath(filePath)) {
+            const { result } = validateWorkflowProgramSource(filePath);
+            if (!result.ok) {
+                throw new UsageError(formatWorkflowErrors(filePath, result.errors));
+            }
+            // Non-fatal WARNINGS ride the envelope additively — `ok` stays true. The
+            // text formatter renders them clearly marked for humans; the JSON key is
+            // the machine channel. Empty array when the program is fully typed/declared.
+            output("workflow-validate", {
+                ok: true,
+                path: filePath,
+                format: "program",
+                title: result.program.name,
+                stepCount: result.program.steps.length,
+                warnings: result.warnings.map((w) => ({ line: w.line, message: w.message })),
+            });
+            return;
+        }
         const { parse } = validateWorkflowSource(filePath);
         if (parse.ok) {
             output("workflow-validate", {
@@ -271,7 +311,15 @@ const workflowValidateCommand = defineJsonCommand({
     },
 });
 async function resolveWorkflowFilePath(target) {
-    if (!target.startsWith("workflow:"))
+    // A bare (`workflow:<name>`) OR origin-qualified (`<origin>//workflow:<name>`)
+    // ref resolves through the source search, exactly like `workflow start` /
+    // `status` / `next`. Anything else is treated as a filesystem path. Detecting
+    // the origin-qualified form here (not just the bare prefix) keeps `validate`'s
+    // ref contract in lockstep with the rest of the workflow command family — an
+    // `extra//workflow:foo` ref validates the file that `extra//workflow:foo`
+    // starts, rather than being mistaken for a relative path that does not exist.
+    const looksLikeWorkflowRef = target.startsWith("workflow:") || target.includes("//workflow:");
+    if (!looksLikeWorkflowRef)
         return target;
     const parsed = parseAssetRef(target);
     if (parsed.type !== "workflow") {
@@ -290,6 +338,231 @@ async function resolveWorkflowFilePath(target) {
     }
     throw new UsageError(`Workflow not found for ref: workflow:${parsed.name}`);
 }
+const workflowRunCommand = defineJsonCommand({
+    meta: {
+        name: "run",
+        description: "EXPERIMENTAL: execute a workflow's steps with the native engine — akm dispatches each step's units " +
+            "(fan-out, schema output) to the configured runner and advances the run through the normal completion gates",
+    },
+    args: {
+        target: { type: "positional", description: "Workflow run id or workflow ref (auto-starts a run)", required: true },
+        params: { type: "string", description: "Workflow parameters as a JSON object (only for auto-started runs)" },
+        "max-steps": { type: "string", description: "Stop after executing this many steps" },
+        "require-gates": {
+            type: "boolean",
+            description: "Treat every criteria-bearing completion gate as required: if no LLM judge is available, BLOCK the step " +
+                "(for a human to resolve via `akm workflow resume`) instead of failing open. A per-step `gate.required: true` " +
+                "in the workflow does the same on every surface; this is the run-wide override (#18).",
+            default: false,
+        },
+    },
+    async run({ args }) {
+        const { runWorkflowSteps } = await import("../workflows/exec/run-workflow.js");
+        const rawMaxSteps = getStringArg(args, "max-steps");
+        let maxSteps;
+        if (rawMaxSteps !== undefined) {
+            maxSteps = Number.parseInt(rawMaxSteps, 10);
+            if (!/^\d+$/.test(rawMaxSteps) || maxSteps <= 0) {
+                throw new UsageError(`--max-steps must be a positive integer, got "${rawMaxSteps}".`, "INVALID_FLAG_VALUE");
+            }
+        }
+        const result = await runWorkflowSteps({
+            target: args.target,
+            ...(args.params ? { params: parseWorkflowJsonObject(args.params, "--params") } : {}),
+            ...(maxSteps !== undefined ? { maxSteps } : {}),
+            ...(args["require-gates"] === true ? { requireGates: true } : {}),
+        });
+        output("workflow-run", result);
+    },
+});
+const workflowBriefCommand = defineJsonCommand({
+    meta: {
+        name: "brief",
+        description: "EXPERIMENTAL: describe a run's active step as an executable work-list for ANY agent session (the " +
+            "harness-neutral driver protocol) — read-only, takes no engine lease, mutates nothing; prints per-unit " +
+            "instructions, output schema, env binding names, and the exact `akm workflow report` command lines",
+    },
+    args: {
+        target: {
+            type: "positional",
+            description: "Workflow run id (or a workflow ref with an active run)",
+            required: true,
+        },
+    },
+    async run({ args }) {
+        const { buildWorkflowBrief } = await import("../workflows/exec/brief.js");
+        const result = await buildWorkflowBrief(args.target);
+        output("workflow-brief", result);
+    },
+});
+const WORKFLOW_REPORT_STATES = ["completed", "failed", "running"];
+const workflowReportCommand = defineJsonCommand({
+    meta: {
+        name: "report",
+        description: "EXPERIMENTAL: report a unit's result back into a run (the mutating half of the harness-neutral driver " +
+            "protocol) — ingested through the SAME shared step semantics the engine uses. --status running claims/" +
+            "heartbeats a unit; completed/failed records it and, when the step's work-list is fully terminal, runs the " +
+            "engine's completion path (reducer, artifact + schema validation, gate). --settle (no --unit) advances a run " +
+            "parked on a route-only/empty step. Refused while a live engine lease exists",
+    },
+    args: {
+        target: {
+            type: "positional",
+            description: "Workflow run id (or a workflow ref with an active run)",
+            required: true,
+        },
+        unit: {
+            type: "string",
+            description: "Content-derived unit id from `akm workflow brief` (copy it verbatim). Omit with --settle.",
+        },
+        settle: {
+            type: "boolean",
+            description: "Advance/finalize a run whose active step has NO unit left to report: a non-dispatching step (params-based route, empty fan-out, all-unresolvable) OR a fully-terminal step still needing finalization (every unit ran but the gate never judged — e.g. after resuming a required-gate block). Runs the deterministic completion path. Mutually exclusive with --unit; refused when the step still has genuinely pending units",
+            default: false,
+        },
+        "expect-step": {
+            type: "string",
+            description: "Guard: the step id you briefed against. Refuses the report if the run's active step has since moved (from the `brief` report/settle command line)",
+        },
+        status: { type: "string", description: `Unit status: ${WORKFLOW_REPORT_STATES.join(", ")}` },
+        result: { type: "string", description: "Result payload (JSON for a schema unit, else text). completed only." },
+        "result-file": { type: "string", description: "Read the result payload from this file instead of --result/stdin" },
+        tokens: { type: "string", description: "Tokens spent on this unit (counts against a declared budget)" },
+        "session-id": { type: "string", description: "Harness-native session id revealed while executing the unit" },
+        "failure-reason": { type: "string", description: "Structured failure vocabulary for a --status failed report" },
+        note: { type: "string", description: "Short progress note for a --status running heartbeat (not persisted)" },
+        rerun: {
+            type: "boolean",
+            description: "Re-run an already-FAILED unit: record a NEW attempt (re-applies budget) instead of refusing a differing re-report",
+            default: false,
+        },
+    },
+    async run({ args }) {
+        // --settle: the unit-less verb that advances a run parked on a
+        // non-dispatching step. Mutually exclusive with the per-unit report flags.
+        if (args.settle === true) {
+            if (getStringArg(args, "unit") !== undefined || getStringArg(args, "status") !== undefined) {
+                throw new UsageError("--settle advances a route-only/empty step and takes no --unit or --status. Drop them, or report a " +
+                    "specific unit with `--unit <id> --status <state>` instead.", "INVALID_FLAG_VALUE");
+            }
+            const { settleWorkflowSpine } = await import("../workflows/exec/report.js");
+            const result = await settleWorkflowSpine({
+                target: args.target,
+                ...(getStringArg(args, "expect-step") !== undefined ? { expectStep: getStringArg(args, "expect-step") } : {}),
+            });
+            output("workflow-report", result);
+            return;
+        }
+        const status = args.status;
+        if (!status) {
+            throw new UsageError("--status is required (completed | failed | running), or pass --settle to advance a non-dispatching step.", "MISSING_REQUIRED_ARGUMENT");
+        }
+        if (!WORKFLOW_REPORT_STATES.includes(status)) {
+            throw new UsageError(`Invalid --status "${status}". Expected one of: ${WORKFLOW_REPORT_STATES.join(", ")}.`, "INVALID_FLAG_VALUE");
+        }
+        const unitId = getStringArg(args, "unit");
+        if (!unitId) {
+            throw new UsageError("--unit is required (the content-derived unit id from `akm workflow brief`), or pass --settle for a route-only/empty step.", "MISSING_REQUIRED_ARGUMENT");
+        }
+        let tokens;
+        const rawTokens = getStringArg(args, "tokens");
+        if (rawTokens !== undefined) {
+            tokens = Number.parseInt(rawTokens, 10);
+            if (!/^\d+$/.test(rawTokens)) {
+                throw new UsageError(`--tokens must be a non-negative integer, got "${rawTokens}".`, "INVALID_FLAG_VALUE");
+            }
+        }
+        // Result payload precedence: --result, then --result-file, then stdin
+        // (completed/failed only; a running heartbeat carries no result).
+        let resultRaw;
+        if (status !== "running") {
+            const resultFile = getStringArg(args, "result-file");
+            if (args.result !== undefined && resultFile !== undefined) {
+                throw new UsageError("Pass at most one of --result or --result-file.", "INVALID_FLAG_VALUE");
+            }
+            if (args.result !== undefined) {
+                resultRaw = String(args.result);
+            }
+            else if (resultFile !== undefined) {
+                const fs = await import("node:fs");
+                resultRaw = fs.readFileSync(resultFile, "utf8");
+            }
+            else if (!process.stdin.isTTY) {
+                resultRaw = await readStdin();
+            }
+        }
+        const { reportWorkflowUnit } = await import("../workflows/exec/report.js");
+        const result = await reportWorkflowUnit({
+            target: args.target,
+            unitId,
+            status: status,
+            ...(getStringArg(args, "expect-step") !== undefined ? { expectStep: getStringArg(args, "expect-step") } : {}),
+            ...(resultRaw !== undefined ? { resultRaw } : {}),
+            ...(tokens !== undefined ? { tokens } : {}),
+            ...(args.rerun === true ? { rerun: true } : {}),
+            ...(getStringArg(args, "session-id") !== undefined ? { sessionId: getStringArg(args, "session-id") } : {}),
+            ...(getStringArg(args, "failure-reason") !== undefined
+                ? { failureReason: getStringArg(args, "failure-reason") }
+                : {}),
+            ...(getStringArg(args, "note") !== undefined ? { note: getStringArg(args, "note") } : {}),
+        });
+        output("workflow-report", result);
+    },
+});
+async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(chunk);
+    return Buffer.concat(chunks).toString("utf8");
+}
+const workflowWatchCommand = defineJsonCommand({
+    meta: {
+        name: "watch",
+        description: "Print a run's workflow_* events (state.db events table) as NDJSON and exit; --stream polls in the " +
+            "foreground until the run reaches a terminal status (no daemon)",
+    },
+    args: {
+        runId: { type: "positional", description: "Workflow run id", required: true },
+        stream: {
+            type: "boolean",
+            description: "Keep polling for new events until the run leaves 'active' (completed/failed/blocked)",
+            default: false,
+        },
+        "interval-ms": { type: "string", description: "Poll interval in milliseconds for --stream (default: 1000)" },
+    },
+    async run({ args }) {
+        const rawInterval = getStringArg(args, "interval-ms");
+        let intervalMs;
+        if (rawInterval !== undefined) {
+            intervalMs = Number.parseInt(rawInterval, 10);
+            if (!/^\d+$/.test(rawInterval) || intervalMs <= 0) {
+                throw new UsageError(`--interval-ms must be a positive integer, got "${rawInterval}".`, "INVALID_FLAG_VALUE");
+            }
+        }
+        const { watchWorkflowRun } = await import("../workflows/exec/watch.js");
+        const result = await watchWorkflowRun({
+            runId: args.runId,
+            stream: args.stream === true,
+            ...(intervalMs !== undefined ? { intervalMs } : {}),
+        });
+        // The event lines above are raw NDJSON on stdout; this trailing envelope
+        // is the machine-readable command result (counts + terminal status).
+        output("workflow-watch", { ok: true, ...result });
+    },
+});
+const workflowAbandonCommand = defineJsonCommand({
+    meta: {
+        name: "abandon",
+        description: "Give up on a workflow run: mark it failed so it stops counting as active (resume can reopen it)",
+    },
+    args: {
+        runId: { type: "positional", description: "Workflow run id", required: true },
+    },
+    async run({ args }) {
+        const result = await abandonWorkflowRun(args.runId);
+        output("workflow-abandon", result);
+    },
+});
 const workflowResumeCommand = defineJsonCommand({
     meta: {
         name: "resume",
@@ -317,7 +590,12 @@ export const workflowCommand = defineCommand({
         create: workflowCreateCommand,
         template: workflowTemplateCommand,
         resume: workflowResumeCommand,
+        abandon: workflowAbandonCommand,
         validate: workflowValidateCommand,
+        run: workflowRunCommand,
+        brief: workflowBriefCommand,
+        report: workflowReportCommand,
+        watch: workflowWatchCommand,
     },
     run({ args }) {
         return runWithJsonErrors(async () => {

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

@@ -29,6 +29,7 @@ export const TYPE_TO_RENDERER = {
     wiki: "wiki-md",
     task: "task-yaml",
     session: "session-md",
+    fact: "fact-md",
 };
 /** Map asset types to action builder functions for search results. */
 export const ACTION_BUILDERS = {
@@ -40,11 +41,12 @@ export const ACTION_BUILDERS = {
     lesson: (ref) => `akm show ${ref} -> read the lesson and apply when_to_use`,
     memory: (ref) => `akm show ${ref} -> recall context`,
     workflow: (ref) => buildWorkflowAction(ref),
-    env: (ref) => `akm show ${ref} -> inspect key names; akm env run ${ref} -- <command> -> run with the whole .env injected (the agent-safe path — values never reach stdout). akm env export ${ref} --out <file> writes a sourceable script (values to a file, not stdout).`,
+    env: (ref) => `akm show ${ref} -> inspect key names; akm env run ${ref} -- <command> -> run with the whole .env injected (prefer --clean to minimize inherited parent env; child stdout is not redacted). akm env export ${ref} --out <file> writes a sourceable script (values to a file, not stdout).`,
     secret: (ref) => `akm show ${ref} -> name only (value never shown); akm secret path ${ref} -> file path; akm secret run ${ref} <VAR> -- <command> -> run with value injected into $VAR`,
     wiki: (ref) => `akm show ${ref} -> read the wiki page`,
     task: (ref) => `akm tasks show ${ref.replace(/^task:/, "")} -> inspect; akm tasks run <id> -> run now; akm tasks remove <id> -> unschedule`,
     session: (ref) => `akm show ${ref} -> read the session summary; follow the \`access\` frontmatter to open the raw log at \`log_path\``,
+    fact: (ref) => `akm show ${ref} -> read the stash fact and apply it as durable context`,
 };
 /**
  * Register a type-to-renderer mapping.

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

@@ -1,11 +1,67 @@
 // 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 fs from "node:fs";
 import path from "node:path";
 import { buildWorkflowAction } from "../../output/renderers.js";
-import { toPosix } from "../common.js";
 import { registerActionBuilder, registerTypeRenderer } from "./asset-registry.js";
+function toPosix(input) {
+    return input.replace(/\\/g, "/");
+}
 const buildTaskAction = (ref) => `akm tasks show ${ref.replace(/^task:/, "")} -> inspect; akm tasks run <id> -> run now; akm tasks remove <id> -> unschedule`;
+/**
+ * Recognized workflow asset extensions, in resolution-priority order.
+ * `.md` (classic linear markdown workflows — the stable contract) stays
+ * FIRST for back-compat; `.yaml`/`.yml` hold YAML workflow *programs*
+ * (redesign addendum, R1). `workflow:<name>` refs resolve against this list.
+ */
+export const WORKFLOW_EXTENSIONS = [".md", ".yaml", ".yml"];
+/**
+ * Strip a recognized workflow extension (`.md`/`.yaml`/`.yml`) from a workflow
+ * asset *name* so `foo`, `foo.yaml`, `foo.yml`, and `foo.md` collapse to one
+ * canonical identity — the same collapse `workflowSpec.toCanonicalName`
+ * performs on a resolved file path. Callers that turn a `workflow:<name>` ref
+ * into run identity (the active-run guard, list/status filters) MUST route the
+ * name through this so an aliased spelling (`workflow:foo.yaml`) and the
+ * canonical `workflow:foo` cannot start or hide parallel runs of the same
+ * workflow. Names without a recognized workflow extension pass through
+ * unchanged.
+ */
+export function canonicalizeWorkflowName(name) {
+    const lower = name.toLowerCase();
+    for (const ext of WORKFLOW_EXTENSIONS) {
+        if (lower.endsWith(ext))
+            return name.slice(0, -ext.length);
+    }
+    return name;
+}
+const workflowSpec = {
+    isRelevantFile: (fileName) => WORKFLOW_EXTENSIONS.includes(path.extname(fileName).toLowerCase()),
+    toCanonicalName: (typeRoot, filePath) => {
+        const rel = toPosix(path.relative(typeRoot, filePath));
+        for (const ext of WORKFLOW_EXTENSIONS) {
+            if (rel.toLowerCase().endsWith(ext))
+                return rel.slice(0, -ext.length);
+        }
+        return rel;
+    },
+    toAssetPath: (typeRoot, name) => {
+        // Explicit extension wins (accepts refs like "release/ship.yaml").
+        const lower = name.toLowerCase();
+        for (const ext of WORKFLOW_EXTENSIONS) {
+            if (lower.endsWith(ext))
+                return path.join(typeRoot, name);
+        }
+        // Probe in priority order — `.md` first for back-compat — 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}`);
+            if (fs.existsSync(candidate))
+                return candidate;
+        }
+        return path.join(typeRoot, `${name}.md`);
+    },
+};
 const markdownSpec = {
     isRelevantFile: (fileName) => path.extname(fileName).toLowerCase() === ".md",
     toCanonicalName: (typeRoot, filePath) => {
@@ -60,15 +116,19 @@ const ASSET_SPECS_INTERNAL = {
     knowledge: { stashDir: "knowledge", ...markdownSpec },
     workflow: {
         stashDir: "workflows",
-        ...markdownSpec,
+        ...workflowSpec,
+        // Type-level renderer for markdown workflows; YAML programs are claimed by
+        // the dedicated `workflowProgramMatcher`, which names the
+        // "workflow-program-yaml" renderer directly on its MatchResult.
         rendererName: "workflow-md",
         actionBuilder: (ref) => buildWorkflowAction(ref),
     },
     script: { stashDir: "scripts", ...scriptSpec },
     memory: { stashDir: "memories", ...markdownSpec },
     // Environment assets — whole `.env` files sourced/injected wholesale. Replaced
-    // the deprecated `vault` type (removed in 0.9.0). Key NAMES + start-of-line
-    // comments are surfaced as metadata; values are never read for indexing.
+    // the deprecated `vault` type (removed in 0.9.0). Only key NAMES are surfaced
+    // as metadata; values and comment text are never read for indexing (comments
+    // routinely contain commented-out credentials).
     env: {
         stashDir: "env",
         isRelevantFile: (fileName) => fileName === ".env" || fileName.endsWith(".env"),
@@ -89,7 +149,7 @@ const ASSET_SPECS_INTERNAL = {
             return path.join(typeRoot, name.endsWith(".env") ? name : `${name}.env`);
         },
         rendererName: "env-file",
-        actionBuilder: (ref) => `akm show ${ref} -> inspect key names; akm env run ${ref} -- <command> -> run with the whole .env injected (values never reach stdout); akm env export ${ref} --out <file> -> write a sourceable script to a file`,
+        actionBuilder: (ref) => `akm show ${ref} -> inspect key names; akm env run ${ref} -- <command> -> run with the whole .env injected (prefer --clean to minimize inherited parent env; child stdout is not redacted); akm env export ${ref} --out <file> -> write a sourceable script to a file`,
     },
     // Secrets — a single sensitive value used on its own for authentication (a
     // PEM key, API token, TLS cert). Unlike `env` (a group of related .env
@@ -154,6 +214,20 @@ const ASSET_SPECS_INTERNAL = {
         rendererName: "session-md",
         actionBuilder: (ref) => `akm show ${ref} -> read the session summary; follow the \`access\` frontmatter to open the raw log at \`log_path\``,
     },
+    // Durable stash-level semantic knowledge — facts about the user, team, or
+    // project (personal details, team tool stacks, coding conventions /
+    // "constitution", and stash-meta like naming conventions or the active
+    // projects list). Unlike `memory` (episodic, recency-decayed) these are
+    // mostly-static declarations meant to be reliably surfaced as context. A
+    // plain markdown spec; `category` frontmatter scopes the fact and
+    // `pinned: true` marks the small always-injected core. See
+    // docs/design/fact-asset-type.md.
+    fact: {
+        stashDir: "facts",
+        ...markdownSpec,
+        rendererName: "fact-md",
+        actionBuilder: (ref) => `akm show ${ref} -> read the stash fact and apply it as durable context`,
+    },
 };
 export const ASSET_SPECS = ASSET_SPECS_INTERNAL;
 /**