akm-cli 0.9.0-beta.5 → 0.9.0-beta.51

package/dist/commands/sources/stash-cli.js

@@ -5,20 +5,20 @@
  * Stash-lifecycle command cluster — the create/index/ingest/inspect verbs for
  * the working stash and its index database: `akm init` (create the stash +
  * persist stashDir), `akm index` (build/refresh the search index), `akm import`
- * (ingest a knowledge doc/URL), `akm db` (+ nested `backups` — inspect the
- * SQLite data dir), and `akm info` (system capabilities + index stats).
+ * (ingest a knowledge doc/URL), and `akm info` (system capabilities + index
+ * stats).
  * Extracted verbatim from src/cli.ts (WS6) so the God Module shrinks; the
- * `main.subCommands.{init,index,import,db,info}` keys and every subcommand's
+ * `main.subCommands.{init,index,import,info}` keys and every subcommand's
  * args/output shape stay byte-identical.
  *
  * These share no private helper with any command still inline in cli.ts — every
  * dependency is already exported from a shared module (core/paths, core/warn,
  * core/errors, core/events, output/context, cli/shared, cli/parse-args, plus the
- * per-command implementations in ./init, ./indexer, ./info, ./db-cli, ./knowledge,
+ * per-command implementations in ./init, ./indexer, ./info, ./knowledge,
  * ./core/asset-create, ./core/common), so the cluster moves with zero hoisting.
  *
  * The leaf handlers whose body is a plain `runWithJsonErrors(...) + output(...)`
- * (`init`, `import`, `info`, `db`, `db backups`) are migrated onto
+ * (`init`, `import`, `info`) are migrated onto
  * `defineJsonCommand`, which emits the same JSON envelope (stdout/stderr/
  * exit-code) as the inline form. `index` keeps a plain `defineCommand` wrapping
  * `runWithJsonErrors` because its body owns a spinner, an AbortController, and
@@ -27,17 +27,17 @@
 import path from "node:path";
 import * as p from "@clack/prompts";
 import { defineCommand } from "citty";
-import { hasSubcommand } from "../../cli/parse-args.js";
 import { defineJsonCommand, output, runWithJsonErrors } from "../../cli/shared.js";
 import { assertFlatAssetName } from "../../core/asset/asset-create.js";
 import { isHttpUrl } from "../../core/common.js";
+import { loadConfig } from "../../core/config/config.js";
 import { UsageError } from "../../core/errors.js";
 import { appendEvent } from "../../core/events.js";
 import { getCacheDir } from "../../core/paths.js";
 import { clearLogFile, info, isVerbose, setLogFile } from "../../core/warn.js";
+import { resolveWriteTarget } from "../../core/write-source.js";
 import { akmIndex } from "../../indexer/indexer.js";
 import { getHyphenatedBoolean, getOutputMode, parseFlagValue } from "../../output/context.js";
-import { akmDbBackups } from "../db-cli.js";
 import { readKnowledgeInput, writeMarkdownAsset } from "../read/knowledge.js";
 import { assembleInfo } from "./info.js";
 import { akmInit } from "./init.js";
@@ -48,12 +48,20 @@ export const initCommand = defineJsonCommand({
     },
     args: {
         dir: { type: "string", description: "Custom stash directory path (default: ~/akm)" },
+        "set-default": {
+            type: "boolean",
+            description: "Make --dir the default stash (write stashDir to config.json). Without this, `akm init --dir X` scaffolds X but leaves your existing default stash unchanged.",
+            default: false,
+        },
     },
     async run({ args }) {
         // Accept both historical spellings for backwards compatibility with
         // older docs/scripts that used `--stashDir`.
         const legacyDir = parseFlagValue(process.argv, "--stashDir") ?? parseFlagValue(process.argv, "--stash-dir");
-        const result = await akmInit({ dir: args.dir ?? legacyDir });
+        const result = await akmInit({
+            dir: args.dir ?? legacyDir,
+            setDefault: getHyphenatedBoolean(args, "set-default"),
+        });
         output("init", result);
     },
 });
@@ -71,6 +79,11 @@ export const indexCommand = defineCommand({
             description: "When combined with --clean, report stale entries without deleting them.",
             default: false,
         },
+        background: {
+            type: "boolean",
+            description: "Run as a background process (suppresses interactive output, manages PID file).",
+            default: false,
+        },
     },
     async run({ args }) {
         await runWithJsonErrors(async () => {
@@ -80,6 +93,7 @@ export const indexCommand = defineCommand({
             if (getHyphenatedBoolean(args, "re-enrich") || parseFlagValue(process.argv, "--re-enrich") !== undefined) {
                 throw new UsageError("`akm index --re-enrich` has been removed. Re-enrichment of index-time LLM passes is not exposed in this slice.");
             }
+            const isBackground = args.background === true;
             const outputMode = getOutputMode();
             const controller = new AbortController();
             const abort = () => controller.abort(new Error("index interrupted"));
@@ -88,7 +102,7 @@ export const indexCommand = defineCommand({
             const indexLogFile = path.join(getCacheDir(), "logs", "index", `${new Date().toISOString().replace(/[:.]/g, "-")}.log`);
             setLogFile(indexLogFile);
             const verbose = isVerbose();
-            const spin = !verbose && outputMode.format === "text" ? p.spinner() : null;
+            const spin = !verbose && !isBackground && outputMode.format === "text" ? p.spinner() : null;
             if (spin) {
                 spin.start(`Building search index${args.full ? " (full rebuild)" : ""}...`);
             }
@@ -114,7 +128,9 @@ export const indexCommand = defineCommand({
                 if (spin) {
                     spin.stop(`Indexed ${result.totalEntries} assets.`);
                 }
-                output("index", result);
+                if (!isBackground) {
+                    output("index", result);
+                }
             }
             catch (error) {
                 if (spin) {
@@ -137,35 +153,6 @@ export const infoCommand = defineJsonCommand({
         output("info", result);
     },
 });
-// MVP DB administration. Currently only `akm db backups`; restore is manual —
-// stop akm and run `scripts/migrations/restore-data-dir.sh <backup>`.
-// Single source of truth: the routing set is derived from the subCommands keys
-// (M10) so adding a subcommand can never silently desync from `hasSubcommand`.
-const dbSubCommands = {
-    backups: defineJsonCommand({
-        meta: {
-            name: "backups",
-            description: "List pre-upgrade snapshots of the data directory (newest first). Backups are created automatically before destructive DB version upgrades unless AKM_DB_BACKUP=0.",
-        },
-        run() {
-            output("db-backups", akmDbBackups());
-        },
-    }),
-};
-const DB_SUBCOMMAND_SET = new Set(Object.keys(dbSubCommands));
-export const dbCommand = defineJsonCommand({
-    meta: {
-        name: "db",
-        description: "Inspect the AKM SQLite data directory. Currently exposes `backups`; to restore from a snapshot, stop akm and run scripts/migrations/restore-data-dir.sh against the chosen backup.",
-    },
-    subCommands: dbSubCommands,
-    run({ args }) {
-        if (hasSubcommand(args, DB_SUBCOMMAND_SET))
-            return;
-        // Default action: list backups.
-        output("db-backups", akmDbBackups());
-    },
-});
 export const importKnowledgeCommand = defineJsonCommand({
     meta: {
         name: "import",
@@ -198,7 +185,8 @@ export const importKnowledgeCommand = defineJsonCommand({
     async run({ args }) {
         // `--name` is a flat name; subdirectory placement is `--path`'s job.
         assertFlatAssetName(args.name);
-        const { content, preferredName } = await readKnowledgeInput(args.source);
+        const stashDir = resolveWriteTarget(loadConfig(), args.target).source.path;
+        const { content, preferredName } = await readKnowledgeInput(args.source, { stashDir });
         const result = await writeMarkdownAsset({
             type: "knowledge",
             content,

package/dist/commands/sources/stash-skeleton.js

@@ -6,27 +6,42 @@ import path from "node:path";
 import { getDirname } from "../../runtime.js";
 const SKELETON_DIR = path.join(getDirname(import.meta.url), "../../assets/stash-skeleton");
 /**
- * Copy the default stash skeleton into a newly created stash directory.
+ * Copy the default stash skeleton into a stash directory.
  *
- * Each file in src/assets/stash-skeleton/ is written to the stash root only
- * if the destination does not already exist — existing files are never
- * overwritten. Non-fatal: if the skeleton directory is missing or a copy
- * fails the caller continues normally.
+ * The skeleton tree under src/assets/stash-skeleton/ is mirrored **recursively**
+ * into the stash root, preserving relative subpaths (e.g.
+ * `facts/conventions/assets/skill.md` lands at the matching stash subpath).
+ * Each file is written only if the destination does not already exist — existing
+ * (possibly user-edited) files are never overwritten. Intermediate directories
+ * are created as needed.
+ *
+ * Idempotent and absent-only: running it again on an existing stash backfills
+ * any skeleton files that are missing without clobbering present ones. Non-fatal:
+ * if the skeleton directory is missing or a copy fails the caller continues.
  */
 export function copyStashSkeleton(stashDir) {
+    copySkeletonDir(SKELETON_DIR, stashDir);
+}
+/** Recursively mirror `srcDir` into `destDir`, writing files only when absent. */
+function copySkeletonDir(srcDir, destDir) {
     let entries;
     try {
-        entries = fs.readdirSync(SKELETON_DIR);
+        entries = fs.readdirSync(srcDir, { withFileTypes: true });
     }
     catch {
         return;
     }
     for (const entry of entries) {
-        const src = path.join(SKELETON_DIR, entry);
-        const dest = path.join(stashDir, entry);
+        const src = path.join(srcDir, entry.name);
+        const dest = path.join(destDir, entry.name);
+        if (entry.isDirectory()) {
+            copySkeletonDir(src, dest);
+            continue;
+        }
         if (fs.existsSync(dest))
             continue;
         try {
+            fs.mkdirSync(path.dirname(dest), { recursive: true });
             fs.copyFileSync(src, dest);
         }
         catch {

package/dist/commands/tasks/tasks-cli.js

@@ -13,8 +13,8 @@
  * with the family.
  */
 import { defineCommand } from "citty";
-import { hasSubcommand, parsePositiveIntFlag } from "../../cli/parse-args.js";
-import { defineJsonCommand, output, runWithJsonErrors } from "../../cli/shared.js";
+import { parsePositiveIntFlag } from "../../cli/parse-args.js";
+import { defineGroupCommand, defineJsonCommand, output, runWithJsonErrors } from "../../cli/shared.js";
 import { getHyphenatedArg } from "../../output/context.js";
 import { detectServerDefault, registerDefaultTasks } from "./default-tasks.js";
 import { akmTasksAdd, akmTasksDoctor, akmTasksHistory, akmTasksList, akmTasksRemove, akmTasksRun, akmTasksSetEnabled, akmTasksShow, akmTasksSync, parseTaskRef, } from "./tasks.js";
@@ -176,35 +176,27 @@ const tasksDoctorCommand = defineJsonCommand({
         output("tasks-doctor", result);
     },
 });
-// Single source of truth: the routing set is derived from the subCommands keys
-// (M10) so adding a subcommand can never silently desync from `hasSubcommand`.
-const tasksSubCommands = {
-    add: tasksAddCommand,
-    init: tasksInitCommand,
-    list: tasksListCommand,
-    show: tasksShowCommand,
-    remove: tasksRemoveCommand,
-    enable: tasksEnableCommand,
-    disable: tasksDisableCommand,
-    run: tasksRunCommand,
-    history: tasksHistoryCommand,
-    sync: tasksSyncCommand,
-    doctor: tasksDoctorCommand,
-};
-const TASKS_SUBCOMMAND_SET = new Set(Object.keys(tasksSubCommands));
-export const tasksCommand = defineCommand({
+export const tasksCommand = defineGroupCommand({
     meta: {
         name: "tasks",
         alias: "task",
         description: "Schedule workflows or prompts via the OS-native scheduler (cron / launchd / schtasks)",
     },
-    subCommands: tasksSubCommands,
-    run({ args }) {
-        return runWithJsonErrors(async () => {
-            if (hasSubcommand(args, TASKS_SUBCOMMAND_SET))
-                return;
-            const result = await akmTasksList();
-            output("tasks-list", result);
-        });
+    subCommands: {
+        add: tasksAddCommand,
+        init: tasksInitCommand,
+        list: tasksListCommand,
+        show: tasksShowCommand,
+        remove: tasksRemoveCommand,
+        enable: tasksEnableCommand,
+        disable: tasksDisableCommand,
+        run: tasksRunCommand,
+        history: tasksHistoryCommand,
+        sync: tasksSyncCommand,
+        doctor: tasksDoctorCommand,
+    },
+    async defaultRun() {
+        const result = await akmTasksList();
+        output("tasks-list", result);
     },
 });

package/dist/commands/tasks/tasks.js

@@ -16,11 +16,12 @@ import { isWithin, resolveStashDir } from "../../core/common.js";
 import { loadConfig } from "../../core/config/config.js";
 import { ConfigError, NotFoundError, UsageError } from "../../core/errors.js";
 import { getTaskHistoryDir, getTaskLogDir } from "../../core/paths.js";
+import { commitWriteTargetBoundary, deleteAssetFromSource, resolveWriteTarget, writeAssetToSource, } from "../../core/write-source.js";
 import { listAgentProfileNames } from "../../integrations/agent/index.js";
 import { resolveAssetPath } from "../../sources/resolve.js";
 import { backendNameForPlatform, selectBackend } from "../../tasks/backends/index.js";
 import { parseTaskDocument } from "../../tasks/parser.js";
-import { resolveAkmInvocation } from "../../tasks/resolveAkmBin.js";
+import { resolveAkmInvocation } from "../../tasks/resolve-akm-bin.js";
 import { exitCodeForStatus, readTaskHistory, runTask } from "../../tasks/runner.js";
 import { parseSchedule, SCHEDULE_SUPPORTED_SUBSET_HINT, translateToCron } from "../../tasks/schedule.js";
 import { validateTaskDocument } from "../../tasks/validator.js";
@@ -38,7 +39,8 @@ export async function akmTasksAdd(input) {
     // Validate the schedule for the active backend before writing anything.
     const backend = backendNameForPlatform();
     parseSchedule(input.schedule, backend);
-    const stashDir = resolveStashDir();
+    const target = resolveTaskWriteTarget();
+    const stashDir = target.source.path;
     const typeRoot = path.join(stashDir, "tasks");
     fs.mkdirSync(typeRoot, { recursive: true });
     const assetPath = resolveAssetPathFromName("task", typeRoot, id);
@@ -64,7 +66,8 @@ export async function akmTasksAdd(input) {
     });
     const task = parseTaskDocument({ yaml, filePath: assetPath, id });
     await validateTaskDocument(task, { backend, stashDir });
-    fs.writeFileSync(assetPath, yaml.endsWith("\n") ? yaml : `${yaml}\n`, "utf8");
+    const ref = taskAssetRef(id);
+    await writeAssetToSource(target.source, target.config, ref, yaml);
     // Install in the OS scheduler. If install fails after the file was written,
     // delete the file so the on-disk state never claims a task is registered
     // when it isn't.
@@ -74,13 +77,14 @@ export async function akmTasksAdd(input) {
     }
     catch (err) {
         try {
-            fs.rmSync(assetPath, { force: true });
+            await deleteAssetFromSource(target.source, target.config, ref);
         }
         catch {
             /* ignore */
         }
         throw err;
     }
+    commitWriteTargetBoundary(target, `Update task:${id}`);
     return {
         id,
         ref: `task:${id}`,
@@ -192,30 +196,47 @@ export async function akmTasksShow(id) {
 }
 export async function akmTasksRemove(id) {
     const normalised = normaliseTaskId(id);
-    const stashDir = resolveStashDir();
+    const target = resolveTaskWriteTarget();
+    const stashDir = target.source.path;
     const typeRoot = path.join(stashDir, "tasks");
     if (fs.existsSync(typeRoot))
         warnLegacyMdTaskFiles(typeRoot);
-    const filePath = await resolveAssetPath(stashDir, "task", normalised);
+    await resolveAssetPath(stashDir, "task", normalised);
+    const ref = taskAssetRef(normalised);
     const sched = selectBackend();
+    let uninstallError;
+    let deleteError;
     try {
         await sched.uninstall(normalised);
     }
-    finally {
-        fs.rmSync(filePath, { force: true });
+    catch (err) {
+        uninstallError = err;
+    }
+    try {
+        await deleteAssetFromSource(target.source, target.config, ref);
     }
+    catch (err) {
+        deleteError = err;
+    }
+    if (uninstallError !== undefined)
+        throw uninstallError;
+    if (deleteError !== undefined)
+        throw deleteError;
+    commitWriteTargetBoundary(target, `Remove task:${normalised}`);
     return { id: normalised, removed: true, backend: sched.name };
 }
 export async function akmTasksSetEnabled(id, enabled) {
     const normalised = normaliseTaskId(id);
-    const stashDir = resolveStashDir();
+    const target = resolveTaskWriteTarget();
+    const stashDir = target.source.path;
     const typeRoot = path.join(stashDir, "tasks");
     if (fs.existsSync(typeRoot))
         warnLegacyMdTaskFiles(typeRoot);
     const filePath = await resolveAssetPath(stashDir, "task", normalised);
     const yaml = fs.readFileSync(filePath, "utf8");
     const updated = setEnabledInYaml(yaml, enabled);
-    fs.writeFileSync(filePath, updated, "utf8");
+    const ref = taskAssetRef(normalised);
+    await writeAssetToSource(target.source, target.config, ref, updated);
     const sched = selectBackend();
     try {
         // Reinstall from the (just-updated) definition rather than only toggling
@@ -229,9 +250,10 @@ export async function akmTasksSetEnabled(id, enabled) {
     catch (err) {
         // Roll the file back so the YAML source-of-truth and the OS
         // scheduler don't diverge silently when the backend call fails.
-        fs.writeFileSync(filePath, yaml, "utf8");
+        await writeAssetToSource(target.source, target.config, ref, yaml);
         throw err;
     }
+    commitWriteTargetBoundary(target, `Update task:${normalised}`);
     return { id: normalised, enabled, backend: sched.name };
 }
 export async function akmTasksRun(id) {
@@ -392,6 +414,12 @@ function normaliseTaskId(raw) {
     }
     return id;
 }
+function taskAssetRef(id) {
+    return { type: "task", name: id };
+}
+function resolveTaskWriteTarget() {
+    return resolveWriteTarget(loadConfig());
+}
 function renderTaskYaml(input) {
     const obj = { schedule: input.schedule };
     if (input.workflow) {

package/dist/commands/wiki-cli.js

@@ -11,9 +11,9 @@
  * `process.exit(1)` after the wrapper when findings exist.
  */
 import { defineCommand } from "citty";
-import { getStringArg, hasSubcommand, parsePositiveIntFlag } from "../cli/parse-args.js";
-import { defineJsonCommand, output, runWithJsonErrors } from "../cli/shared.js";
-import { isHttpUrl, resolveStashDir } from "../core/common.js";
+import { getStringArg, parsePositiveIntFlag } from "../cli/parse-args.js";
+import { defineGroupCommand, defineJsonCommand, output, runWithJsonErrors } from "../cli/shared.js";
+import { resolveStashDir } from "../core/common.js";
 import { loadConfig, resolveConfiguredSources } from "../core/config/config.js";
 import { ConfigError, UsageError } from "../core/errors.js";
 import { getHyphenatedArg, getHyphenatedBoolean } from "../output/context.js";
@@ -168,13 +168,6 @@ const wikiStashCommand = defineJsonCommand({
     },
     async run({ args }) {
         const { stashRaw } = await import("../wiki/wiki.js");
-        const { content, preferredName } = await (async () => {
-            if (!isHttpUrl(args.source))
-                return readKnowledgeInput(args.source);
-            const { fetchWebsiteMarkdownSnapshot } = await import("../sources/website-ingest.js");
-            const snapshot = await fetchWebsiteMarkdownSnapshot(args.source);
-            return { content: snapshot.content, preferredName: args.as ?? snapshot.preferredName };
-        })();
         let stashDir;
         if (args.target) {
             // Resolve the named source to its filesystem path.
@@ -193,6 +186,7 @@ const wikiStashCommand = defineJsonCommand({
         else {
             stashDir = resolveStashDir();
         }
+        const { content, preferredName } = await readKnowledgeInput(args.source, { stashDir });
         const result = stashRaw({
             stashDir,
             wikiName: args.name,
@@ -274,34 +268,26 @@ const wikiIngestCommand = defineJsonCommand({
         });
     },
 });
-// Single source of truth: the routing set is derived from the subCommands keys
-// (M10) so adding a subcommand can never silently desync from `hasSubcommand`.
-const wikiSubCommands = {
-    create: wikiCreateCommand,
-    register: wikiRegisterCommand,
-    list: wikiListCommand,
-    show: wikiShowCommand,
-    remove: wikiRemoveCommand,
-    pages: wikiPagesCommand,
-    search: wikiSearchCommand,
-    stash: wikiStashCommand,
-    lint: wikiLintCommand,
-    ingest: wikiIngestCommand,
-};
-const WIKI_SUBCOMMAND_SET = new Set(Object.keys(wikiSubCommands));
-export const wikiCommand = defineCommand({
+export const wikiCommand = defineGroupCommand({
     meta: {
         name: "wiki",
         description: "Manage multiple markdown wikis (Karpathy-style). akm surfaces (lifecycle, raw/, lint, index); the agent writes pages.",
     },
-    subCommands: wikiSubCommands,
-    run({ args }) {
-        return runWithJsonErrors(async () => {
-            if (hasSubcommand(args, WIKI_SUBCOMMAND_SET))
-                return;
-            // Default action: list wikis
-            const { listWikis } = await import("../wiki/wiki.js");
-            output("wiki-list", { wikis: listWikis(resolveStashDir()) });
-        });
+    subCommands: {
+        create: wikiCreateCommand,
+        register: wikiRegisterCommand,
+        list: wikiListCommand,
+        show: wikiShowCommand,
+        remove: wikiRemoveCommand,
+        pages: wikiPagesCommand,
+        search: wikiSearchCommand,
+        stash: wikiStashCommand,
+        lint: wikiLintCommand,
+        ingest: wikiIngestCommand,
+    },
+    async defaultRun() {
+        // Default action: list wikis
+        const { listWikis } = await import("../wiki/wiki.js");
+        output("wiki-list", { wikis: listWikis(resolveStashDir()) });
     },
 });

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

@@ -3,8 +3,10 @@
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 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`;
 const markdownSpec = {
     isRelevantFile: (fileName) => path.extname(fileName).toLowerCase() === ".md",
@@ -89,7 +91,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 +156,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;
 /**