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

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

@@ -3,13 +3,11 @@
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import fs from "node:fs";
 import path from "node:path";
-import * as p from "@clack/prompts";
-import { defineCommand } from "citty";
-import { output, runWithJsonErrors } from "../../cli/shared.js";
+import * as p from "../../cli/clack.js";
+import { defineJsonCommand, output } from "../../cli/shared.js";
 import { UsageError } from "../../core/errors.js";
 import { appendEvent } from "../../core/events.js";
 import { warn } from "../../core/warn.js";
-import { getHyphenatedBoolean } from "../../output/context.js";
 import { akmRemove } from "./installed-stashes.js";
 import { akmAdd } from "./source-add.js";
 import { addStash } from "./source-manage.js";
@@ -149,7 +147,7 @@ export async function auditInstalledStashForDangerousKeys(opts) {
     return { blocked: true, exitCode: 1 };
 }
 // ── Command definition ────────────────────────────────────────────────────────
-export const addCommand = defineCommand({
+export const addCommand = defineJsonCommand({
     meta: {
         name: "add",
         description: "Add a source (local directory, website, npm package, GitHub repo, git URL, or remote provider)",
@@ -181,48 +179,11 @@ export const addCommand = defineCommand({
         },
     },
     async run({ args }) {
-        await runWithJsonErrors(async () => {
-            const ref = args.ref.trim();
-            const allowInsecure = getHyphenatedBoolean(args, "allow-insecure");
-            const allowDangerousKeys = allowInsecure;
-            // URL with --provider → stash source (remote or git provider)
-            if (args.provider) {
-                if (shouldWarnOnPlainHttp(ref)) {
-                    if (!allowInsecure) {
-                        throw new UsageError("Source URL uses plain HTTP (not HTTPS). An on-path attacker could substitute a malicious payload. " +
-                            "Use https:// or pass --allow-insecure if you have explicitly accepted the risk.", "INVALID_FLAG_VALUE", "Re-run with `--allow-insecure` only after confirming the URL is trusted.");
-                    }
-                    warn("Warning: source URL uses plain HTTP (not HTTPS). --allow-insecure was set; an on-path attacker could substitute a malicious payload.");
-                }
-                let parsedOptions;
-                if (args.options) {
-                    try {
-                        const parsed = JSON.parse(args.options);
-                        if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
-                            throw new UsageError("--options must be a JSON object");
-                        }
-                        parsedOptions = parsed;
-                    }
-                    catch (err) {
-                        if (err instanceof UsageError)
-                            throw err;
-                        throw new UsageError("--options must be valid JSON");
-                    }
-                }
-                const result = addStash({
-                    target: ref,
-                    name: args.name,
-                    providerType: args.provider,
-                    options: parsedOptions,
-                    writable: args.writable,
-                });
-                appendEvent({
-                    eventType: "add",
-                    metadata: { target: ref, provider: args.provider, name: args.name ?? null, writable: args.writable === true },
-                });
-                output("add", result);
-                return;
-            }
+        const ref = args.ref.trim();
+        const allowInsecure = args["allow-insecure"];
+        const allowDangerousKeys = allowInsecure;
+        // URL with --provider → stash source (remote or git provider)
+        if (args.provider) {
             if (shouldWarnOnPlainHttp(ref)) {
                 if (!allowInsecure) {
                     throw new UsageError("Source URL uses plain HTTP (not HTTPS). An on-path attacker could substitute a malicious payload. " +
@@ -230,64 +191,99 @@ export const addCommand = defineCommand({
                 }
                 warn("Warning: source URL uses plain HTTP (not HTTPS). --allow-insecure was set; an on-path attacker could substitute a malicious payload.");
             }
-            const websiteOptions = buildWebsiteOptions(args);
-            if (args.type === "wiki") {
-                const { registerWikiSource } = await import("./source-add.js");
-                const result = await registerWikiSource({
-                    ref,
-                    name: args.name,
-                    options: Object.keys(websiteOptions).length > 0 ? websiteOptions : undefined,
-                    writable: args.writable,
-                });
-                appendEvent({
-                    eventType: "add",
-                    metadata: { target: ref, type: "wiki", name: args.name ?? null, writable: args.writable === true },
-                });
-                output("add", result);
-                return;
+            let parsedOptions;
+            if (args.options) {
+                try {
+                    const parsed = JSON.parse(args.options);
+                    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+                        throw new UsageError("--options must be a JSON object");
+                    }
+                    parsedOptions = parsed;
+                }
+                catch (err) {
+                    if (err instanceof UsageError)
+                        throw err;
+                    throw new UsageError("--options must be valid JSON");
+                }
             }
-            const result = await akmAdd({
+            const result = addStash({
+                target: ref,
+                name: args.name,
+                providerType: args.provider,
+                options: parsedOptions,
+                writable: args.writable,
+            });
+            appendEvent({
+                eventType: "add",
+                metadata: { target: ref, provider: args.provider, name: args.name ?? null, writable: args.writable === true },
+            });
+            output("add", result);
+            return;
+        }
+        if (shouldWarnOnPlainHttp(ref)) {
+            if (!allowInsecure) {
+                throw new UsageError("Source URL uses plain HTTP (not HTTPS). An on-path attacker could substitute a malicious payload. " +
+                    "Use https:// or pass --allow-insecure if you have explicitly accepted the risk.", "INVALID_FLAG_VALUE", "Re-run with `--allow-insecure` only after confirming the URL is trusted.");
+            }
+            warn("Warning: source URL uses plain HTTP (not HTTPS). --allow-insecure was set; an on-path attacker could substitute a malicious payload.");
+        }
+        const websiteOptions = buildWebsiteOptions(args);
+        if (args.type === "wiki") {
+            const { registerWikiSource } = await import("./source-add.js");
+            const result = await registerWikiSource({
                 ref,
                 name: args.name,
-                overrideType: args.type,
                 options: Object.keys(websiteOptions).length > 0 ? websiteOptions : undefined,
                 writable: args.writable,
             });
             appendEvent({
                 eventType: "add",
-                metadata: {
-                    target: ref,
-                    name: args.name ?? null,
-                    overrideType: args.type ?? null,
-                    writable: args.writable === true,
-                },
+                metadata: { target: ref, type: "wiki", name: args.name ?? null, writable: args.writable === true },
             });
-            // ── Post-install env key audit ──────────────────────────────────────────
-            // Resolve the stash root from the install result and scan any env files
-            // for dangerous env var keys.  When findings are present the install is
-            // gated: TTY → interactive confirmation prompt; non-TTY without
-            // --allow-insecure → hard failure (exit 1).  Pass
-            // --allow-insecure to skip the prompt non-interactively.
-            const installedStashRoot = result.installed?.stashRoot ??
-                (result.sourceAdded && "stashRoot" in result.sourceAdded ? result.sourceAdded.stashRoot : undefined);
-            if (installedStashRoot) {
-                // Use the canonical installed id (most reliably resolved by akmRemove) rather
-                // than the raw user-supplied ref which may not match after URL normalisation.
-                const rollbackTarget = result.installed?.id ?? result.sourceAdded?.stashRoot ?? ref;
-                // The audit RETURNS its decision; we decide `process.exit` here, OUTSIDE
-                // any catch, so the abort cannot be lost to a swallowed exception (C3).
-                const decision = await auditInstalledStashForDangerousKeys({
-                    installedStashRoot,
-                    ref,
-                    allowDangerousKeys,
-                    rollbackTarget,
-                    isTTY: process.stdin.isTTY === true,
-                });
-                if (decision.blocked) {
-                    process.exit(decision.exitCode);
-                }
-            }
             output("add", result);
+            return;
+        }
+        const result = await akmAdd({
+            ref,
+            name: args.name,
+            overrideType: args.type,
+            options: Object.keys(websiteOptions).length > 0 ? websiteOptions : undefined,
+            writable: args.writable,
+        });
+        appendEvent({
+            eventType: "add",
+            metadata: {
+                target: ref,
+                name: args.name ?? null,
+                overrideType: args.type ?? null,
+                writable: args.writable === true,
+            },
         });
+        // ── Post-install env key audit ──────────────────────────────────────────
+        // Resolve the stash root from the install result and scan any env files
+        // for dangerous env var keys.  When findings are present the install is
+        // gated: TTY → interactive confirmation prompt; non-TTY without
+        // --allow-insecure → hard failure (exit 1).  Pass
+        // --allow-insecure to skip the prompt non-interactively.
+        const installedStashRoot = result.installed?.stashRoot ??
+            (result.sourceAdded && "stashRoot" in result.sourceAdded ? result.sourceAdded.stashRoot : undefined);
+        if (installedStashRoot) {
+            // Use the canonical installed id (most reliably resolved by akmRemove) rather
+            // than the raw user-supplied ref which may not match after URL normalisation.
+            const rollbackTarget = result.installed?.id ?? result.sourceAdded?.stashRoot ?? ref;
+            // The audit RETURNS its decision; we decide `process.exit` here, OUTSIDE
+            // any catch, so the abort cannot be lost to a swallowed exception (C3).
+            const decision = await auditInstalledStashForDangerousKeys({
+                installedStashRoot,
+                ref,
+                allowDangerousKeys,
+                rollbackTarget,
+                isTTY: process.stdin.isTTY === true,
+            });
+            if (decision.blocked) {
+                process.exit(decision.exitCode);
+            }
+        }
+        output("add", result);
     },
 });

package/dist/commands/sources/history.js

@@ -22,7 +22,7 @@ import { readEvents } from "../../core/events.js";
 import { isoToSqlite, parseSinceToIso } from "../../core/time.js";
 import { closeDatabase, openExistingDatabase } from "../../indexer/db/db.js";
 import { getUsageEvents } from "../../indexer/usage/usage-events.js";
-import { listProposals } from "../proposal/validators/proposals.js";
+import { listProposals } from "../proposal/repository.js";
 // Proposal lifecycle event types emitted by the proposal substrate (#225).
 const PROPOSAL_EVENT_TYPES = new Set(["promoted", "rejected"]);
 // ── Helpers ──────────────────────────────────────────────────────────────────

package/dist/commands/sources/init.js

@@ -15,7 +15,7 @@ import { loadUserConfig, saveConfig } from "../../core/config/config.js";
 import { ConfigError } from "../../core/errors.js";
 import { assertSafeStashDir, getBinDir, getConfigPath, getDefaultStashDir } from "../../core/paths.js";
 import { ensureRg } from "../../core/ripgrep/install.js";
-import { copyStashSkeleton, scaffoldStashMeta } from "./stash-skeleton.js";
+import { copyStashSkeleton, ensureStashGitignore, scaffoldStashMeta } from "./stash-skeleton.js";
 /**
  * Refuse to persist a temporary-directory stashDir to the user's config when
  * running under a test runner AND `--dir <tempdir>` was passed explicitly.
@@ -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,24 @@ 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";
+}
+// ── Test seam ────────────────────────────────────────────────────────────────
+// Swap-and-restore override. Inert in production; only tests call the setter.
+let akmInitOverride;
+/** TEST-ONLY. Swap the implementation of `akmInit`; pass undefined to restore. */
+export function _setAkmInitForTests(fake) {
+    akmInitOverride = fake;
+}
 export async function akmInit(options) {
+    if (akmInitOverride)
+        return akmInitOverride(options);
+    return akmInitReal(options);
+}
+async function akmInitReal(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 +78,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 +92,58 @@ 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
+    // 08-F1: scaffold a default `.gitignore` that keeps env/ + secrets/ out of git
+    // so a `git push` can never leak them. Idempotent + non-clobbering; the user
+    // opts into versioning by un-ignoring a path.
+    ensureStashGitignore(stashDir);
+    // 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,11 +17,13 @@ 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";
+import { createProposal, isProposalSkipped } from "../proposal/repository.js";
 // ── Constants ────────────────────────────────────────────────────────────────
 /** Minimum gap between schema-repair attempts on the same asset. */
 const SCHEMA_REPAIR_COOLDOWN_MS = 7 * 24 * 60 * 60 * 1000; // 7 days
@@ -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 {

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

@@ -23,7 +23,7 @@ import { loadConfig } from "../../core/config/config.js";
 import { UsageError } from "../../core/errors.js";
 import { appendEvent } from "../../core/events.js";
 import { resolveSourceEntries } from "../../indexer/search/search-source.js";
-import { getHyphenatedBoolean, parseFlagValue } from "../../output/context.js";
+import { parseFlagValue } from "../../output/context.js";
 import { resolveWritableOverride, saveGitStash } from "../../sources/providers/git.js";
 import { pkgVersion } from "../../version.js";
 import { akmHistory } from "./history.js";
@@ -125,8 +125,8 @@ export const upgradeCommand = defineJsonCommand({
             output("upgrade", check);
             return;
         }
-        const skipChecksum = getHyphenatedBoolean(args, "skip-checksum");
-        const skipPostUpgrade = getHyphenatedBoolean(args, "skip-post-upgrade");
+        const skipChecksum = args["skip-checksum"];
+        const skipPostUpgrade = args["skip-post-upgrade"];
         const result = await performUpgrade(check, { force: args.force, skipChecksum, skipPostUpgrade });
         output("upgrade", result);
     },