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

package/dist/commands/read/search-cli.js

@@ -63,6 +63,11 @@ export const searchCommand = defineJsonCommand({
             description: "Disable the automatic project-context ranking boost (also disabled by AKM_DISABLE_PROJECT_CONTEXT=1).",
             default: false,
         },
+        "include-sessions": {
+            type: "boolean",
+            description: "Include session assets (excluded from default search results via config.search.defaultExcludeTypes).",
+            default: false,
+        },
     },
     async run({ args }) {
         const query = (args.query ?? "").trim();
@@ -79,10 +84,7 @@ export const searchCommand = defineJsonCommand({
         const includeProposed = args["include-proposed"] === true;
         const belief = parseBeliefFilterMode(typeof args.belief === "string" ? args.belief : undefined);
         const noProjectContext = getHyphenatedBoolean(args, "no-project-context");
-        // --no-project-context sets env so searchDatabase picks it up without
-        // threading the flag through the entire call stack.
-        if (noProjectContext)
-            process.env.AKM_DISABLE_PROJECT_CONTEXT = "1";
+        const includeSessions = getHyphenatedBoolean(args, "include-sessions");
         const result = await akmSearch({
             query,
             type,
@@ -91,6 +93,9 @@ export const searchCommand = defineJsonCommand({
             filters,
             includeProposed,
             belief,
+            includeSessions,
+            disableProjectContext: noProjectContext,
+            disableScopedUtility: noProjectContext,
             eventSource: resolveEventSource(),
         });
         output("search", result);

package/dist/commands/read/search.js

@@ -108,6 +108,9 @@ export async function akmSearch(input) {
             // Without this, the index (which spans every configured source)
             // would leak hits from sources the caller did not request.
             restrictToSources: namedSourceName !== undefined,
+            includeExcludedTypes: input.includeSessions === true,
+            disableProjectContext: input.disableProjectContext === true,
+            disableScopedUtility: input.disableScopedUtility === true,
         });
     const registryResult = source === "stash" ? undefined : await searchRegistry(query, { limit, registries: config.registries });
     if (source === "stash") {
@@ -122,8 +125,9 @@ export async function akmSearch(input) {
             warnings: localResult?.warnings?.length ? localResult.warnings : undefined,
             timing: { totalMs: Date.now() - t0, rankMs: localResult?.rankMs, embedMs: localResult?.embedMs },
         };
-        if (!input.skipLogging)
-            logSearchEvent(query, response, localResult?.mode ?? "keyword", input.eventSource);
+        if (!input.skipLogging) {
+            logSearchEvent(query, response, localResult?.mode ?? "keyword", input.eventSource, input.disableScopedUtility === true);
+        }
         return response;
     }
     const registryHits = (registryResult?.hits ?? []).map((hit) => {
@@ -158,7 +162,7 @@ export async function akmSearch(input) {
             timing: { totalMs: Date.now() - t0 },
         };
         if (!input.skipLogging)
-            logSearchEvent(query, response, undefined, input.eventSource);
+            logSearchEvent(query, response, undefined, input.eventSource, input.disableScopedUtility === true);
         return response;
     }
     // source === "both"
@@ -176,7 +180,7 @@ export async function akmSearch(input) {
         timing: { totalMs: Date.now() - t0 },
     };
     if (!input.skipLogging)
-        logSearchEvent(query, response, undefined, input.eventSource);
+        logSearchEvent(query, response, undefined, input.eventSource, input.disableScopedUtility === true);
     return response;
 }
 /**
@@ -211,7 +215,7 @@ function resolveEntryIds(db, hits) {
  * Per-entry events are recorded only for stash hits because registry hits
  * have no local entry_id to reference.
  */
-function logSearchEvent(query, response, mode = "keyword", eventSource = "user") {
+function logSearchEvent(query, response, mode = "keyword", eventSource = "user", disableScopedUtility = false) {
     // Emit a structured event to events.jsonl so workflow-trace consumers
     // detect akm search invocations without relying on stdout scraping.
     const stashHits = response.hits.filter((h) => h.type !== "registry");
@@ -241,7 +245,7 @@ function logSearchEvent(query, response, mode = "keyword", eventSource = "user")
                 let scopeKey;
                 try {
                     const stashPath = response.stashDir;
-                    const disabled = process.env.AKM_DISABLE_SCOPED_UTILITY === "1" || (stashPath && isTransientStashPath(stashPath));
+                    const disabled = disableScopedUtility || (stashPath && isTransientStashPath(stashPath));
                     scopeKey = disabled ? undefined : getCurrentWorkflowScopeKey();
                 }
                 catch {

package/dist/commands/read/show.js

@@ -18,22 +18,27 @@
  */
 import fs from "node:fs";
 import path from "node:path";
+import { findCittyTopLevelCommandIndex } from "../../cli/parse-args.js";
 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 +388,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 +405,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
@@ -458,6 +524,14 @@ function buildSummaryResponse(full, assetPath) {
 }
 // ── argv normalisation ───────────────────────────────────────────────────────
 const SHOW_VIEW_MODES = new Set(["toc", "frontmatter", "full", "section", "lines"]);
+const SHOW_ARGV_TOP_LEVEL_ARGS = {
+    format: { type: "string" },
+    output: { type: "string" },
+    detail: { type: "string" },
+    shape: { type: "string" },
+    quiet: { type: "boolean", alias: "q" },
+    verbose: { type: "boolean" },
+};
 /**
  * Normalize argv so positional view-mode arguments after the asset ref
  * are rewritten into internal flags that citty can parse.
@@ -471,15 +545,20 @@ const SHOW_VIEW_MODES = new Set(["toc", "frontmatter", "full", "section", "lines
  * Returns a new array; the input is never modified.
  */
 export function normalizeShowArgv(argv) {
-    // argv[0]=bun argv[1]=script argv[2]=subcommand argv[3]=ref argv[4..]=rest
-    if (argv[2] !== "show")
+    const rawArgs = argv.slice(2);
+    const commandIndex = findCittyTopLevelCommandIndex(rawArgs, SHOW_ARGV_TOP_LEVEL_ARGS);
+    if (commandIndex < 0 || rawArgs[commandIndex] !== "show")
         return argv;
-    if (argv.includes("--view") || argv.includes("--heading") || argv.includes("--start") || argv.includes("--end")) {
+    const commandArgs = rawArgs.slice(commandIndex + 1);
+    if (commandArgs.includes("--view") ||
+        commandArgs.includes("--heading") ||
+        commandArgs.includes("--start") ||
+        commandArgs.includes("--end")) {
         throw new UsageError('Legacy show flags are no longer supported. Use positional syntax like `akm show knowledge:guide toc` or `akm show knowledge:guide section "Auth"`.');
     }
     // Separate global flags from positional/show-specific args
-    const prefix = argv.slice(0, 3); // [bun, script, show]
-    const rest = argv.slice(3);
+    const prefix = [...argv.slice(0, 2), ...rawArgs.slice(0, commandIndex + 1)];
+    const rest = commandArgs;
     const globalFlags = [];
     const showArgs = [];
     for (let i = 0; i < rest.length; i++) {

package/dist/commands/sources/init.js

@@ -37,7 +37,7 @@ import { copyStashSkeleton, scaffoldStashMeta } from "./stash-skeleton.js";
 function assertInitSandbox(stashDir, dirExplicitlyProvided) {
     if (!dirExplicitlyProvided)
         return; // Only guard explicit --dir, not default HOME resolution.
-    const isUnderTest = process.env.BUN_TEST === "1" || process.env.NODE_ENV === "test";
+    const isUnderTest = isUnderTestRunner();
     if (!isUnderTest)
         return;
     if (process.env.AKM_FORCE_INIT_TMP_STASH === "1")
@@ -52,7 +52,12 @@ function assertInitSandbox(stashDir, dirExplicitlyProvided) {
         return;
     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");
 }
+function isUnderTestRunner() {
+    return process.env.BUN_TEST === "1" || process.env.NODE_ENV === "test";
+}
 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 +66,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,27 +80,54 @@ 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;
-    try {
-        const binDir = getBinDir();
-        const rgResult = ensureRg(binDir);
-        ripgrep = rgResult;
-    }
-    catch {
-        // Non-fatal: ripgrep is optional, search works without it
+    if (!isUnderTestRunner()) {
+        try {
+            const binDir = getBinDir();
+            const rgResult = ensureRg(binDir);
+            ripgrep = rgResult;
+        }
+        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

@@ -17,7 +17,7 @@ import { removeLockEntry, upsertLockEntry } from "../../integrations/lockfile.js
 import { parseRegistryRef } from "../../registry/resolve.js";
 import { parseGitRepoUrl, syncMirroredRepo } from "../../sources/providers/git.js";
 import { syncFromRef } from "../../sources/providers/sync-from-ref.js";
-import { ensureWebsiteMirror } from "../../sources/website-ingest.js";
+import { ensureWebsiteMirror, shouldAllowPrivateWebsiteUrlForTests } from "../../sources/website-ingest.js";
 import { listWikis, resolveWikisRoot } from "../../wiki/wiki.js";
 import { removeInstalledRegistryEntry, upsertInstalledRegistryEntry } from "./source-add.js";
 import { removeStash } from "./source-manage.js";
@@ -194,7 +194,11 @@ async function updateGitSource(stashDir, target, all, gitSource) {
 /** Re-crawl a website source and return an UpdateResponse. */
 async function updateWebsiteSource(stashDir, target, all, websiteSource) {
     // TODO: full incremental re-crawl with delta tracking (#19)
-    await ensureWebsiteMirror(websiteSource, { requireStashDir: true, force: true });
+    await ensureWebsiteMirror(websiteSource, {
+        requireStashDir: true,
+        force: true,
+        ...(shouldAllowPrivateWebsiteUrlForTests(websiteSource.url ?? "") ? { allowPrivateHosts: true } : {}),
+    });
     return buildUpdateResponse(stashDir, target, all, []);
 }
 /** Sync a single installed registry entry and return the processed record. */
@@ -205,7 +209,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,8 +17,10 @@ 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 { info, warn } from "../../core/warn.js";
+import { resolveStandardsContext } from "../../core/standards/resolve-standards-context.js";
+import { info } from "../../core/warn.js";
 import { resolveAssetPath } from "../../indexer/walk/path-resolver.js";
 import { chatCompletion, parseEmbeddedJsonResponse } from "../../llm/client.js";
 import { createProposal, isProposalSkipped } from "../proposal/validators/proposals.js";
@@ -44,6 +46,9 @@ export async function runSchemaRepairPass(failures, options) {
     const repairs = [];
     const repairedRefs = new Set();
     const { startMs, budgetMs, llmConfig, stashDir, findFilePath = defaultFindFilePath, isLessonCandidateFn = defaultIsLessonCandidate, chatFn = chatCompletion, } = options;
+    if (!stashDir) {
+        throw new Error("runSchemaRepairPass requires stashDir so repairs route through the proposal queue");
+    }
     for (const failure of failures) {
         if (Date.now() - startMs >= budgetMs)
             break;
@@ -94,6 +99,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). `resolveStandardsContext`
+            // dispatches on the ref.
+            const standardsContext = 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 +116,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());
@@ -127,50 +142,33 @@ export async function runSchemaRepairPass(failures, options) {
             // them human-reviewable before they affect search ranking and curate hints.
             // mem0 open gaps (arXiv:2504.19413) — any LLM write to a memory field
             // should be human-reviewable.
-            if (stashDir) {
-                const proposalResult = createProposal(stashDir, {
-                    ref: failure.ref,
-                    source: "schema-repair",
-                    payload: {
-                        content: newContent,
-                        ...(Object.keys(newFm).length > 0 ? { frontmatter: newFm } : {}),
-                    },
-                });
-                if (isProposalSkipped(proposalResult)) {
-                    info(`[improve] schema-repair proposal skipped for ${failure.ref}: ${proposalResult.message}`);
-                    repairs.push({ ref: failure.ref, reason: failure.reason, outcome: "skipped" });
-                    continue;
-                }
-                info(`[improve] schema-repair queued: ${failure.ref} (proposal id: ${proposalResult.id})`);
-                appendEvent({
-                    eventType: "schema_repair_invoked",
-                    ref: failure.ref,
-                    metadata: { outcome: "queued", reason: failure.reason, proposalId: proposalResult.id },
-                });
-                repairs.push({
-                    ref: failure.ref,
-                    reason: failure.reason,
-                    outcome: "queued",
-                    proposalId: proposalResult.id,
-                });
-                // Mark as repaired so the caller removes it from the validation-failure set.
-                repairedRefs.add(failure.ref);
-            }
-            else {
-                // Fallback: no stash dir available — write directly (legacy path).
-                // This should not occur in production; stashDir is always provided by
-                // `runSchemaRepairPass` callers in improve.ts.
-                warn(`[improve] schema-repair: no stashDir available for ${failure.ref}, falling back to direct write`);
-                fs.writeFileSync(filePath, newContent, "utf8");
-                info(`[improve] schema-repair written: ${failure.ref}`);
-                appendEvent({
-                    eventType: "schema_repair_invoked",
-                    ref: failure.ref,
-                    metadata: { outcome: "written", reason: failure.reason },
-                });
-                repairs.push({ ref: failure.ref, reason: failure.reason, outcome: "written" });
-                repairedRefs.add(failure.ref);
+            const proposalResult = createProposal(stashDir, {
+                ref: failure.ref,
+                source: "schema-repair",
+                payload: {
+                    content: newContent,
+                    ...(Object.keys(newFm).length > 0 ? { frontmatter: newFm } : {}),
+                },
+            });
+            if (isProposalSkipped(proposalResult)) {
+                info(`[improve] schema-repair proposal skipped for ${failure.ref}: ${proposalResult.message}`);
+                repairs.push({ ref: failure.ref, reason: failure.reason, outcome: "skipped" });
+                continue;
             }
+            info(`[improve] schema-repair queued: ${failure.ref} (proposal id: ${proposalResult.id})`);
+            appendEvent({
+                eventType: "schema_repair_invoked",
+                ref: failure.ref,
+                metadata: { outcome: "queued", reason: failure.reason, proposalId: proposalResult.id },
+            });
+            repairs.push({
+                ref: failure.ref,
+                reason: failure.reason,
+                outcome: "queued",
+                proposalId: proposalResult.id,
+            });
+            // Mark as repaired so the caller removes it from the validation-failure set.
+            repairedRefs.add(failure.ref);
         }
         catch (e) {
             appendEvent({

package/dist/commands/sources/self-update.js

@@ -306,8 +306,8 @@ export async function performUpgrade(check, opts) {
  * The new binary's `akm index` does the work for us:
  *   1. loadConfig() runs at startup — auto-migrates legacy `stashes` →
  *      `sources` if the on-disk config still uses the old key.
- *   2. ensureSchema() detects DB_VERSION mismatch and rebuilds index.db
- *      tables (preserving usage_events).
+ *   2. ensureSchema() converges index.db forward via its idempotent baseline
+ *      schema + additive migrations (no destructive rebuild).
  *   3. The full reindex repopulates entries + workflow_documents + FTS.
  */
 function runPostUpgradeTasks(akmBin, opts) {

package/dist/commands/sources/source-add.js

@@ -11,7 +11,7 @@ import { upsertLockEntry } from "../../integrations/lockfile.js";
 import { parseRegistryRef } from "../../registry/resolve.js";
 import { detectStashRoot } from "../../sources/providers/provider-utils.js";
 import { syncFromRef } from "../../sources/providers/sync-from-ref.js";
-import { ensureWebsiteMirror, validateWebsiteInputUrl } from "../../sources/website-ingest.js";
+import { ensureWebsiteMirror, shouldAllowPrivateWebsiteUrlForTests, validateWebsiteInputUrl, } from "../../sources/website-ingest.js";
 import { ensureWikiNameAvailable, validateWikiName } from "../../wiki/wiki.js";
 const VALID_OVERRIDE_TYPES = new Set(["wiki"]);
 export async function akmAdd(input) {
@@ -126,7 +126,8 @@ async function addLocalSource(ref, sourcePath, stashDir, wikiName, explicitName)
     };
 }
 async function addWebsiteSource(ref, stashDir, name, options, wikiName) {
-    const normalizedUrl = validateWebsiteInputUrl(ref);
+    const allowPrivateHosts = shouldAllowPrivateWebsiteUrlForTests(ref);
+    const normalizedUrl = validateWebsiteInputUrl(ref, { allowPrivateHosts });
     const config = loadUserConfig();
     const sources = [...getSources(config)];
     let entry = sources.find((stash) => stash.type === "website" && stash.url === normalizedUrl);
@@ -154,7 +155,10 @@ async function addWebsiteSource(ref, stashDir, name, options, wikiName) {
         if (changed)
             saveConfig({ ...config, sources });
     }
-    const cachePaths = await ensureWebsiteMirror(entry, { requireStashDir: true });
+    const cachePaths = await ensureWebsiteMirror(entry, {
+        requireStashDir: true,
+        ...(allowPrivateHosts ? { allowPrivateHosts: true } : {}),
+    });
     const index = await akmIndex({ stashDir });
     const updatedConfig = loadConfig();
     return {