akm-cli 0.9.0-beta.4 → 0.9.0-beta.41

package/dist/commands/read/show.js

@@ -22,18 +22,22 @@ import { parseAssetRef } from "../../core/asset/asset-ref.js";
 import { parseFrontmatter } from "../../core/asset/frontmatter.js";
 import { META_DIR, parseMetaRef, resolveMetaFilePath } from "../../core/asset/stash-meta.js";
 import { asNonEmptyString } from "../../core/common.js";
-import { loadConfig } from "../../core/config/config.js";
+import { getIndexPassConfig, loadConfig } from "../../core/config/config.js";
 import { NotFoundError, rethrowIfTestIsolationError, UsageError } from "../../core/errors.js";
 import { appendEvent, readEvents } from "../../core/events.js";
-import { findEntryIdByRef } from "../../indexer/db/db.js";
+import { closeDatabase, computeBodyHash, findEntryIdByRef, openExistingDatabase } from "../../indexer/db/db.js";
+import { hasGraphData } from "../../indexer/db/graph-db.js";
 import { ensureIndex } from "../../indexer/ensure-index.js";
 import { listRelatedPathsForFile } from "../../indexer/graph/graph-boost.js";
+import { extractGraphForSingleFile } from "../../indexer/graph/graph-extraction.js";
 import { lookup } from "../../indexer/indexer.js";
 import { buildEditHint, findSourceForPath, isEditable, resolveSourceEntries } from "../../indexer/search/search-source.js";
 import { insertUsageEvent } from "../../indexer/usage/usage-events.js";
 import { buildFileContext, buildRenderContext, getRenderer, runMatchers } from "../../indexer/walk/file-context.js";
 import { resolveAssetPath } from "../../indexer/walk/path-resolver.js";
+import { resolveIndexPassLLM } from "../../llm/index-passes.js";
 import { resolveSourcesForOrigin } from "../../registry/origin-resolve.js";
+import { resolveStorageLocations } from "../../storage/locations.js";
 import { withIndexDb } from "../../storage/repositories/index-db.js";
 // Eagerly import source providers to trigger self-registration.
 import "../../sources/providers/index.js";
@@ -383,6 +387,15 @@ export async function showLocal(input) {
     if (activeRun) {
         fullResponse.activeRun = activeRun;
     }
+    // #624-P3: opt-in inline graph extraction. Default OFF — when the flag is
+    // unset this whole block is skipped (no hasGraphData check, no LLM call), so
+    // behavior is byte-identical to today. When ON, it extracts graph data for an
+    // ungraphed asset, but ONLY when a model is configured (model-available
+    // guard) and ALWAYS bounded by a 30s timeout so `show` can never hang. Any
+    // timeout/model-unavailable/error path returns the response unchanged.
+    if (getIndexPassConfig(config.index, "graph")?.lazyGraphExtraction === true) {
+        await maybeExtractGraphInline(config, sourceStashDir, assetPath);
+    }
     if (input.detail === "brief") {
         return buildBriefResponse(fullResponse, assetPath);
     }
@@ -391,6 +404,58 @@ export async function showLocal(input) {
     }
     return fullResponse;
 }
+/**
+ * #624-P3 — opt-in inline graph extraction for `akm show`. Best-effort and
+ * timeout-bounded: never throws, never hangs, never mutates the response.
+ *
+ * Preconditions (caller already checked the flag): a model must be configured
+ * (model-available guard via {@link resolveIndexPassLLM}) and the asset must be
+ * ungraphed ({@link hasGraphData}). Extraction races a 30s timeout so `show`
+ * cannot block on a slow provider; any timeout/error/missing-model path is
+ * swallowed and `show` returns its already-assembled response unchanged.
+ */
+async function maybeExtractGraphInline(config, sourceStashDir, assetPath) {
+    try {
+        // Model-available guard — no provider configured ⇒ silent skip, no LLM call.
+        if (!resolveIndexPassLLM("graph", config))
+            return;
+        let alreadyGraphed = false;
+        let bodyHash;
+        try {
+            const raw = fs.readFileSync(assetPath, "utf8");
+            bodyHash = computeBodyHash(parseFrontmatter(raw).content.trim());
+        }
+        catch {
+            return; // file gone/unreadable ⇒ nothing to extract
+        }
+        withIndexDb((db) => {
+            alreadyGraphed = hasGraphData(db, sourceStashDir, assetPath);
+        });
+        if (alreadyGraphed)
+            return;
+        // Open the db for the async extraction ourselves: `withIndexDb` is
+        // synchronous and would close the connection the instant the async fn
+        // returns its Promise (before extraction completes). Close it explicitly
+        // after the race settles instead.
+        const db = openExistingDatabase(resolveStorageLocations().indexDb);
+        let timer;
+        const timeout = new Promise((resolve) => {
+            timer = setTimeout(resolve, 30_000);
+        });
+        try {
+            await Promise.race([extractGraphForSingleFile(db, sourceStashDir, assetPath, bodyHash, { config }), timeout]);
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+            closeDatabase(db);
+        }
+    }
+    catch (err) {
+        rethrowIfTestIsolationError(err);
+        // Any other failure: silently return the unchanged show response.
+    }
+}
 /**
  * Minimal `show`: ref → indexer lookup → file contents. Used by callers that
  * just need the raw file (e.g. clone, write-source) and don't want the full

package/dist/commands/sources/init.js

@@ -53,6 +53,8 @@ function assertInitSandbox(stashDir, dirExplicitlyProvided) {
     throw new ConfigError(`refusing to persist --dir stashDir to a temporary path while under test runner; set AKM_FORCE_INIT_TMP_STASH=1 if you really mean it (stashDir=${stashDir})`, "INIT_TMP_STASH_REFUSED");
 }
 export async function akmInit(options) {
+    const dirExplicitlyProvided = options?.dir != null;
+    const setDefault = options?.setDefault === true;
     const stashDir = options?.dir ? path.resolve(options.dir) : getDefaultStashDir();
     // Safety check (#473): refuse stashDir at /, $HOME, /etc, ~/.config, etc.
     // Runs BEFORE any disk write — a fat-fingered `akm init --dir /` or
@@ -61,7 +63,7 @@ export async function akmInit(options) {
     assertSafeStashDir(stashDir);
     // Defense-in-depth: refuse to persist an explicit --dir /tmp/... stashDir
     // to config under a test runner. Default HOME-resolved paths are exempt.
-    assertInitSandbox(stashDir, options?.dir != null);
+    assertInitSandbox(stashDir, dirExplicitlyProvided);
     let created = false;
     if (!fs.existsSync(stashDir)) {
         fs.mkdirSync(stashDir, { recursive: true });
@@ -75,15 +77,40 @@ export async function akmInit(options) {
     }
     // Ensure the default stash is a local git repo (no remote required)
     ensureGitRepo(stashDir);
-    if (created) {
-        copyStashSkeleton(stashDir);
-        scaffoldStashMeta(stashDir);
-    }
-    // Persist stashDir in config.json
+    // Run seeding UNCONDITIONALLY (not just when the stash was newly created) so
+    // re-running `akm init` on an existing stash backfills any missing skeleton
+    // files — the README, the per-type SOFT convention templates under
+    // facts/conventions/assets/, and the `.meta/index.md` orientation doc. Both
+    // helpers are absent-only: they never overwrite a file a user has edited.
+    copyStashSkeleton(stashDir);
+    scaffoldStashMeta(stashDir);
+    // Persist stashDir in config.json — but ONLY when the user is actually
+    // setting up / opting into a default. A bare `akm init --dir <secondary>`
+    // must NOT silently repoint the user's real default stash (the footgun
+    // documented in memory:akm-init-persists-stashdir-warning).
+    //
+    // Decision matrix — persist when ANY of:
+    //   (a) no --dir provided           → default HOME-resolved setup flow
+    //   (b) --dir AND no existing stashDir in config → first-time bootstrap
+    //   (c) --dir AND --set-default      → explicit opt-in
+    // Otherwise (--dir + existing default + no --set-default) leave the default
+    // pointer alone; the target dir is still scaffolded above.
     const configPath = getConfigPath();
     const existing = loadUserConfig();
-    if (!existing.stashDir || existing.stashDir !== stashDir) {
-        saveConfig({ ...existing, stashDir });
+    const existingStashDir = existing.stashDir;
+    const shouldPersist = !dirExplicitlyProvided || !existingStashDir || setDefault;
+    let defaultStashUpdated = false;
+    let previousStashDir;
+    if (shouldPersist) {
+        if (!existingStashDir || existingStashDir !== stashDir) {
+            saveConfig({ ...existing, stashDir });
+            defaultStashUpdated = true;
+        }
+        // else: already pointed here — no-op, no spurious rewrite.
+    }
+    else {
+        // Default left untouched; surface it so the CLI can inform the user.
+        previousStashDir = existingStashDir;
     }
     // Ensure ripgrep is available (install to cache/bin if needed)
     let ripgrep;
@@ -95,7 +122,7 @@ export async function akmInit(options) {
     catch {
         // Non-fatal: ripgrep is optional, search works without it
     }
-    return { stashDir, created, configPath, ripgrep };
+    return { stashDir, created, configPath, defaultStashUpdated, previousStashDir, ripgrep };
 }
 /** Initialise `dir` as a git repository if it is not already one. */
 function ensureGitRepo(dir) {

package/dist/commands/sources/installed-stashes.js

@@ -205,7 +205,11 @@ async function updateRegistryEntry(entry, force) {
     const synced = await syncFromRef(entry.ref, { force });
     const installedEntry = {
         id: synced.id,
-        source: synced.source,
+        // Preserve the original source classification. syncFromRef() re-derives the
+        // source type from the ref scheme (e.g. "github:" → source: "github"), but
+        // an update should not reclassify an existing entry. A writable entry stored
+        // as source: "git" would fail config validation if rewritten to "github".
+        source: entry.source,
         ref: synced.ref,
         artifactUrl: synced.artifactUrl,
         resolvedVersion: synced.resolvedVersion,

package/dist/commands/sources/schema-repair.js

@@ -17,7 +17,9 @@ import path from "node:path";
 import { parseAssetRef } from "../../core/asset/asset-ref.js";
 import { assembleAsset } from "../../core/asset/asset-serialize.js";
 import { parseFrontmatter } from "../../core/asset/frontmatter.js";
+import { authoringRulesForType } from "../../core/authoring-rules.js";
 import { appendEvent, readEvents } from "../../core/events.js";
+import { resolveStandardsContext } from "../../core/standards/resolve-standards-context.js";
 import { info, warn } from "../../core/warn.js";
 import { resolveAssetPath } from "../../indexer/walk/path-resolver.js";
 import { chatCompletion, parseEmbeddedJsonResponse } from "../../llm/client.js";
@@ -94,6 +96,16 @@ export async function runSchemaRepairPass(failures, options) {
             const fieldList = missingFields.join(" and ");
             info(`[improve] schema-repair ${failure.ref} (${fieldList})`);
             const bodyPreview = (fm.content ?? raw).slice(0, 2000);
+            // Standards "rulebook" for this target — wiki schema (wiki page) or stash
+            // convention/meta facts (non-wiki asset); empty when neither fires or no
+            // stash dir is available. `resolveStandardsContext` dispatches on the ref.
+            const standardsContext = stashDir ? resolveStandardsContext(failure.ref, stashDir) : "";
+            const standardsSection = standardsContext.trim()
+                ? `\n\nStandards to follow (the rulebook for this target):\n${standardsContext.trim()}`
+                : "";
+            const assetType = parseAssetRef(failure.ref).type;
+            const authoringRules = authoringRulesForType(assetType);
+            const authoringRulesSection = authoringRules ? `\n\n${authoringRules}` : "";
             const llmResponse = await chatFn(llmConfig, [
                 {
                     role: "system",
@@ -101,7 +113,7 @@ export async function runSchemaRepairPass(failures, options) {
                 },
                 {
                     role: "user",
-                    content: `Generate the missing frontmatter fields (${fieldList}) for this ${parseAssetRef(failure.ref).type} asset. Return ONLY valid JSON like {"description": "...", "when_to_use": "..."}\n\n${bodyPreview}`,
+                    content: `Generate the missing frontmatter fields (${fieldList}) for this ${assetType} asset. Return ONLY valid JSON like {"description": "...", "when_to_use": "..."}${standardsSection}${authoringRulesSection}\n\n${bodyPreview}`,
                 },
             ]);
             const parsed = parseEmbeddedJsonResponse(llmResponse.trim());

package/dist/commands/sources/stash-cli.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) {

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/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 = {
@@ -45,6 +46,7 @@ export const ACTION_BUILDERS = {
     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

@@ -154,6 +154,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;
 /**