akm-cli 0.9.0-rc.8 → 0.9.0

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

@@ -2,117 +2,44 @@
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 /**
- * Source-management CLI commands — `akm list/remove/update/upgrade/sync/clone/history`.
+ * Source-management CLI commands — `akm upgrade/sync/clone`.
  *
  * Extracted verbatim from src/cli.ts (WS6). Each `main.subCommands.<key>`
  * registration line stays byte-identical; the args/output shape of every
- * subcommand is unchanged. The `--kind` filter helper (`parseKindFilter` +
- * `VALID_SOURCE_KINDS`), the `runSyncBody` git-commit/push body, and the
- * `wasFormatValueConsumedAsName` citty-mis-parse workaround are used ONLY by
- * this cluster, so they move with it.
+ * subcommand is unchanged. The `runSyncBody` git-commit/push body is used
+ * ONLY by this cluster, so it moves with it.
  *
  * Leaf handlers whose body is a plain `runWithJsonErrors(async () => { … })`
  * are migrated to `defineJsonCommand`, which emits the same JSON envelope
  * (stdout/stderr/exit-code) as the inline form. `sync` keeps `defineCommand`
  * because its `run` delegates to `runSyncBody` (which owns the
  * `runWithJsonErrors` wrapper) rather than wrapping inline.
+ *
+ * 0.9.0 CLI overhaul (S3): top-level `history` was dropped; its
+ * `--accept-rate-by-source` metric was folded into `akm health --report`
+ * (src/commands/health/accept-rate.ts).
+ *
+ * 0.9 CLI overhaul (S7): `list`/`remove`/`update` moved out of this cluster
+ * into the new `akm bundle` group (src/commands/sources/bundle-cli.ts) — no
+ * top-level `list`/`remove`/`update` remains. Root `sync` and this file's
+ * `clone`/`upgrade` stay top-level (the shipped `core/sync.yml` task calls
+ * `akm sync` directly).
  */
 import { defineCommand } from "citty";
 import { getParsedInvocation } from "../../cli/invocation.js";
-import { defineJsonCommand, output, runWithJsonErrors } from "../../cli/shared.js";
+import { defineJsonCommand, GLOBAL_OUTPUT_ARGS, output, runWithJsonErrors } from "../../cli/shared.js";
 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 { resolveWritableOverride, saveGitStash } from "../../sources/providers/git.js";
 import { pkgVersion } from "../../version.js";
-import { akmHistory } from "./history.js";
-import { akmListSources, akmRemove, akmUpdate } from "./installed-stashes.js";
 import { checkForUpdate, performUpgrade } from "./self-update.js";
 import { akmClone } from "./source-clone.js";
-const VALID_SOURCE_KINDS = new Set(["local", "managed", "remote"]);
-function parseKindFilter(raw) {
-    if (!raw)
-        return undefined;
-    const kinds = raw.split(",").map((s) => s.trim());
-    for (const k of kinds) {
-        if (!VALID_SOURCE_KINDS.has(k)) {
-            throw new UsageError(`Invalid --kind value: "${k}". Expected one of: local, managed, remote`);
-        }
-    }
-    return kinds;
-}
-export const listCommand = defineJsonCommand({
-    meta: { name: "list", description: "List all sources (local directories, managed packages, remote providers)" },
-    args: {
-        kind: { type: "string", description: "Filter by source kind (local, managed, remote). Comma-separated." },
-    },
-    async run({ args }) {
-        const kind = parseKindFilter(args.kind);
-        const result = await akmListSources({ kind });
-        output("list", result);
-    },
-});
-export const removeCommand = defineJsonCommand({
-    meta: { name: "remove", description: "Remove a source by id, ref, path, URL, or name" },
-    args: {
-        target: { type: "positional", description: "Source to remove (id, ref, path, URL, or name)", required: true },
-        yes: { type: "boolean", alias: "y", description: "Skip confirmation prompt", default: false },
-    },
-    async run({ args }) {
-        const { confirmDestructive } = await import("../../cli/confirm.js");
-        const confirmed = await confirmDestructive(`Remove source "${args.target}"? This cannot be undone.`, {
-            yes: args.yes === true,
-        });
-        if (!confirmed) {
-            process.stderr.write("Aborted.\n");
-            return;
-        }
-        const result = await akmRemove({ target: args.target });
-        appendEvent({
-            eventType: "remove",
-            metadata: {
-                target: args.target,
-                ref: typeof result.removed?.ref === "string" ? result.removed.ref : null,
-                id: typeof result.removed?.id === "string" ? result.removed.id : null,
-            },
-        });
-        output("remove", result);
-    },
-});
-export const updateCommand = defineJsonCommand({
-    meta: { name: "update", description: "Update one or all managed sources" },
-    args: {
-        target: { type: "positional", description: "Source to update (id or ref)", required: false },
-        all: { type: "boolean", description: "Update all installed entries", default: false },
-        force: { type: "boolean", description: "Force fresh download even if version is unchanged", default: false },
-    },
-    async run({ args }) {
-        const result = await akmUpdate({ target: args.target, all: args.all, force: args.force });
-        appendEvent({
-            eventType: "update",
-            metadata: {
-                target: args.target ?? null,
-                all: args.all === true,
-                force: args.force === true,
-                processed: Array.isArray(result.processed)
-                    ? result.processed.length
-                    : 0,
-            },
-        });
-        output("update", result);
-    },
-});
 export const upgradeCommand = defineJsonCommand({
     meta: { name: "upgrade", description: "Upgrade akm to the latest release" },
     args: {
         check: { type: "boolean", description: "Check for updates without installing", default: false },
         force: { type: "boolean", description: "Force upgrade even if on latest", default: false },
-        "skip-checksum": {
-            type: "boolean",
-            description: "Skip checksum verification (not recommended)",
-            default: false,
-        },
         "skip-post-upgrade": {
             type: "boolean",
             description: "Skip the post-upgrade index rebuild (migration preflight and apply still run)",
@@ -129,57 +56,57 @@ export const upgradeCommand = defineJsonCommand({
             output("upgrade", check);
             return;
         }
-        const skipChecksum = args["skip-checksum"];
         const skipPostUpgrade = args["skip-post-upgrade"];
         const migrationConfig = args["migration-config"];
-        const result = await performUpgrade(check, { force: args.force, skipChecksum, skipPostUpgrade, migrationConfig });
+        const result = await performUpgrade(check, { force: args.force, skipPostUpgrade, migrationConfig });
         output("upgrade", result);
     },
 });
-// `sync` body. Kept as a standalone function so the git-commit/push logic and
-// the `--format`-as-name workaround stay in one place.
-async function runSyncBody(args, verb) {
+// `sync` body, standalone so the git-commit/push logic stays in one place.
+async function runSyncBody(args) {
     await runWithJsonErrors(async () => {
-        // Fix: citty can consume `--format json` (space-separated) as the
-        // positional `name` argument (e.g. `akm sync --format json` parses
-        // name="json"). Detect the mis-parse by checking argv order — only
-        // treat the positional as consumed by --format when --format appears
-        // before any standalone occurrence of the same value in the sync
-        // subcommand's argv slice. This preserves legitimate invocations
-        // like `akm sync json --format json`.
-        const parsedFormat = getParsedInvocation().getFlagValue("--format");
-        const effectiveName = args.name !== undefined &&
-            parsedFormat !== undefined &&
-            args.name === parsedFormat &&
-            wasFormatValueConsumedAsName(args.name, parsedFormat, verb)
-            ? undefined
-            : args.name;
+        // The optional `name` positional is safe to trust: the global output flags
+        // are declared on the command (GLOBAL_OUTPUT_ARGS), so `akm sync --format
+        // json` parses `json` as the flag's value, never as a stash name.
+        const effectiveName = args.name;
         let writable;
         if (effectiveName === undefined) {
-            // Primary stash — honour the root-level writable flag from config.
+            // Primary stash — honour the configured default bundle's writable flag.
             writable = resolveWritableOverride(loadConfig());
         }
         const result = saveGitStash(effectiveName, args.message, writable, { push: args.push !== false });
+        // 0.9.0 breaking change: both "save" holdovers from the command's
+        // pre-rename name are now "sync" — the persisted eventType below and the
+        // envelope shape emitted at the end of this function. Historical state.db
+        // rows still carry "save" — `readEvents`/`tailEvents` (src/core/events.ts)
+        // treat "save" and "sync" as synonyms on READ so `akm log --type save`
+        // keeps returning both old and new rows. Only the WRITE side changes here.
+        // The envelope shape needs no such synonym: it is per-invocation, never
+        // persisted, so nothing can be holding an old value.
         appendEvent({
-            eventType: "save",
+            eventType: "sync",
             metadata: {
                 name: effectiveName ?? null,
                 message: args.message ?? null,
                 ok: result.ok !== false,
             },
         });
-        output("save", result);
+        output("sync", result);
     });
 }
 export const syncCommand = defineCommand({
     meta: {
         name: "sync",
-        description: "Sync changes in a git-backed stash: commits (and pushes when writable + remote is configured). No-op for non-git stashes.",
+        description: "Sync changes in a git-backed bundle: commits (and pushes when writable + remote is configured). No-op for non-git bundles.",
     },
+    // Raw defineCommand (not defineJsonCommand), so the global output flags are
+    // spread in explicitly — without them the optional `name` positional would
+    // swallow a space-separated global flag's value.
     args: {
+        ...GLOBAL_OUTPUT_ARGS,
         name: {
             type: "positional",
-            description: "Name of the git stash to sync (default: primary stash directory)",
+            description: "Name of the git bundle to sync (default: primary bundle directory)",
             required: false,
         },
         message: {
@@ -194,122 +121,44 @@ export const syncCommand = defineCommand({
         },
     },
     async run({ args }) {
-        await runSyncBody(args, "sync");
+        await runSyncBody(args);
     },
 });
 /**
- * Detect whether `--format <value>` was consumed by citty as the optional
- * `name` positional of `akm sync`. Returns true only when `--format` appears
- * in the sync subcommand's argv slice AND the candidate name does NOT
- * appear as a standalone positional elsewhere (before or after the flag).
- *
- * This keeps `akm sync json --format json` routing `json` as the stash name,
- * while `akm sync --format json` (no separate positional) is treated as a
- * primary-stash sync. `verb` is the subcommand token to anchor on.
+ * `--target` was renamed to `--bundle` on `clone` in 0.9 (S8). citty is
+ * non-strict, so the retired spelling is silently absorbed rather than
+ * rejected — the asset then lands in the default bundle instead of the one
+ * the caller named, with exit 0 and no error. Reject it explicitly instead.
  */
-function wasFormatValueConsumedAsName(name, formatValue, verb) {
-    const argv = getParsedInvocation().userArgs;
-    const verbIndex = argv.indexOf(verb);
-    const tokens = verbIndex >= 0 ? argv.slice(verbIndex + 1) : argv;
-    let formatIndex = -1;
-    let formatConsumesNextToken = false;
-    for (let i = 0; i < tokens.length; i += 1) {
-        const token = tokens[i];
-        if (token === "--format") {
-            formatIndex = i;
-            formatConsumesNextToken = true;
-            break;
-        }
-        if (token === `--format=${formatValue}`) {
-            formatIndex = i;
-            break;
-        }
-    }
-    if (formatIndex === -1)
-        return false;
-    // If the name appears as a standalone token before --format, it's the
-    // real positional and --format did not consume it.
-    if (tokens.slice(0, formatIndex).includes(name))
-        return false;
-    // If --format has a space-separated value, skip past the value token
-    // when scanning after the flag; otherwise start right after the flag.
-    const firstTokenAfterFormat = formatIndex + (formatConsumesNextToken ? 2 : 1);
-    if (tokens.slice(firstTokenAfterFormat).includes(name))
-        return false;
-    return true;
+function rejectRetiredCloneTargetFlag() {
+    if (!getParsedInvocation().hasFlag("--target"))
+        return;
+    throw new UsageError("`akm clone --target` was renamed to `--bundle` in 0.9. Use `--bundle <name>` instead.", "INVALID_FLAG_VALUE");
 }
 export const cloneCommand = defineJsonCommand({
     meta: {
         name: "clone",
-        description: "Clone an asset from any source into the working stash or a custom destination",
+        description: "Clone an asset from any source into a managed bundle or an unmanaged custom destination",
     },
     args: {
-        ref: { type: "positional", description: "Asset ref (e.g. npm:@scope/pkg//script:deploy.sh)", required: true },
+        ref: { type: "positional", description: "Asset ref (e.g. npm:@scope/pkg//scripts/deploy.sh)", required: true },
         name: { type: "string", description: "New name for the cloned asset" },
-        force: { type: "boolean", description: "Overwrite if asset already exists in working stash", default: false },
-        dest: { type: "string", description: "Destination directory (default: working stash)" },
+        force: { type: "boolean", description: "Overwrite if the asset already exists at the destination", default: false },
+        bundle: {
+            type: "string",
+            description: "Override the managed destination. Accepts a bundle name from config; falls back to defaultWriteTarget then the working bundle.",
+        },
+        dest: { type: "string", description: "Unmanaged destination directory (cannot be combined with --bundle)" },
     },
     async run({ args }) {
+        rejectRetiredCloneTargetFlag();
         const result = await akmClone({
             sourceRef: args.ref,
             newName: args.name,
             force: args.force,
             dest: args.dest,
+            target: args.bundle,
         });
         output("clone", result);
     },
 });
-export const historyCommand = defineJsonCommand({
-    meta: {
-        name: "history",
-        description: "Show mutation/usage history for a single asset (--ref) or stash-wide.\n\n" +
-            "Event sources:\n" +
-            "  usage_events (default): search, show, and feedback events from the local index.\n" +
-            "  state.db events (--include-proposals): proposal lifecycle events (promoted, rejected)\n" +
-            "    emitted by `akm accept` / `akm reject`.\n\n" +
-            "Results from all active sources are merged and sorted chronologically.",
-    },
-    args: {
-        ref: { type: "string", description: "Asset ref ([bundle//]conceptId). Omit for stash-wide history." },
-        since: { type: "string", description: "ISO timestamp or epoch ms — only events on/after this time" },
-        generator: {
-            type: "string",
-            description: "Filter by event generator: user, improve, task, audit, or unknown.",
-        },
-        "include-proposals": {
-            type: "boolean",
-            description: "Also include proposal lifecycle events (promoted, rejected) from state.db events. " +
-                "Default: false (usage_events only).",
-            default: false,
-        },
-        "accept-rate-by-source": {
-            type: "boolean",
-            description: "Compute accept-rate-per-source metrics from the proposal store and include them in the output (F-4 / #385). " +
-                "Useful for measuring which generators (reflect, distill, …) produce the most accepted proposals.",
-            default: false,
-        },
-        format: { type: "string", description: "Output format (json|jsonl|text|yaml)" },
-    },
-    async run({ args }) {
-        const generatorFlag = args.generator;
-        if (generatorFlag !== undefined &&
-            generatorFlag !== "user" &&
-            generatorFlag !== "improve" &&
-            generatorFlag !== "task" &&
-            generatorFlag !== "audit" &&
-            generatorFlag !== "unknown") {
-            throw new UsageError(`Invalid --generator value: "${generatorFlag}". Must be user, improve, task, audit, or unknown.`, "INVALID_FLAG_VALUE");
-        }
-        const sources = resolveSourceEntries();
-        const stashDir = sources[0]?.path;
-        const result = await akmHistory({
-            ref: args.ref,
-            since: args.since,
-            source: generatorFlag,
-            includeProposals: args["include-proposals"],
-            acceptRateBySource: args["accept-rate-by-source"],
-            stashDir,
-        });
-        output("history", result);
-    },
-});

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

@@ -2,15 +2,18 @@
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 /**
- * 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), and `akm info` (system capabilities + index
- * stats).
+ * Stash-lifecycle command cluster — the index/ingest/inspect verbs for
+ * the working stash and its index database: `akm index` (build/refresh the
+ * search index), `akm import` (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,info}` keys and every subcommand's
+ * `main.subCommands.{index,import,info}` keys and every subcommand's
  * args/output shape stay byte-identical.
  *
+ * 0.9 CLI overhaul (S7): `init` moved out of this cluster into the new
+ * `akm bundle create` (src/commands/sources/bundle-cli.ts) — no top-level
+ * `init` remains.
+ *
  * 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
@@ -18,7 +21,7 @@
  * ./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`) are migrated onto
+ * (`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
@@ -28,49 +31,30 @@ import path from "node:path";
 import { defineCommand } from "citty";
 import * as p from "../../cli/clack.js";
 import { getParsedInvocation } from "../../cli/invocation.js";
-import { defineJsonCommand, output, parseAllFlagValues, runWithJsonErrors } from "../../cli/shared.js";
+import { defineJsonCommand, GLOBAL_OUTPUT_ARGS, output, parseAllFlagValues, runWithJsonErrors } from "../../cli/shared.js";
 import { assertFlatAssetName } from "../../core/asset/asset-create.js";
 import { parseFrontmatter } from "../../core/asset/frontmatter.js";
 import { isHttpUrl, resolveStashDir } from "../../core/common.js";
 import { loadConfig } from "../../core/config/config.js";
 import { UsageError } from "../../core/errors.js";
 import { appendEvent } from "../../core/events.js";
+import { resolveBundleWriteTarget } from "../../core/mutation-target.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 } from "../../output/context.js";
-import { inferAssetName, mergeXrefsIntoContent, readKnowledgeInput, resolveSupersedesForWrite, resolveXrefsForWrite, writeMarkdownAsset, } from "../read/knowledge.js";
+import { inferAssetName, mergeXrefsIntoContent, readKnowledgeInput, resolveSupersedesForWrite, resolveSupersedesWriteTarget, resolveXrefsForWrite, writeMarkdownAsset, } from "../read/knowledge.js";
 import { assembleInfo } from "./info.js";
-import { akmInit } from "./init.js";
-export const initCommand = defineJsonCommand({
-    meta: {
-        name: "init",
-        description: "Initialize akm's working stash directory and persist stashDir in config",
-    },
-    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 invocation = getParsedInvocation();
-        const legacyDir = invocation.getFlagValue("--stashDir") ?? invocation.getFlagValue("--stash-dir");
-        const result = await akmInit({
-            dir: args.dir ?? legacyDir,
-            setDefault: args["set-default"],
-        });
-        output("init", result);
-    },
-});
 export const indexCommand = defineCommand({
     meta: { name: "index", description: "Build search index (incremental by default; --full forces full reindex)" },
     args: {
+        // R-051: `index` is a raw `defineCommand` (not `defineJsonCommand`), so it
+        // does not get `GLOBAL_OUTPUT_ARGS` for free. `--format`/`--detail`/
+        // `--shape`/`--output` already parsed correctly here (this command has no
+        // extra positional for a stray value to fall into), so this is purely a
+        // `--help` visibility / consistency fix, not a behavior change.
+        ...GLOBAL_OUTPUT_ARGS,
         full: { type: "boolean", description: "Force full reindex", default: false },
         clean: {
             type: "boolean",
@@ -82,11 +66,6 @@ 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 () => {
@@ -96,7 +75,6 @@ export const indexCommand = defineCommand({
             if (getHyphenatedBoolean(args, "re-enrich") || getParsedInvocation().getFlagValue("--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"));
@@ -105,7 +83,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 && !isBackground && outputMode.format === "text" ? p.spinner() : null;
+            const spin = !verbose && outputMode.format === "text" ? p.spinner() : null;
             if (spin) {
                 spin.start(`Building search index${args.full ? " (full rebuild)" : ""}...`);
             }
@@ -136,9 +114,7 @@ export const indexCommand = defineCommand({
                 if (spin) {
                     spin.stop(`Indexed ${result.totalEntries} assets.`);
                 }
-                if (!isBackground) {
-                    output("index", result);
-                }
+                output("index", result);
             }
             catch (error) {
                 if (spin) {
@@ -164,7 +140,7 @@ export const infoCommand = defineJsonCommand({
 export const importKnowledgeCommand = defineJsonCommand({
     meta: {
         name: "import",
-        description: "Import a knowledge document or URL into the default stash",
+        description: "Import a knowledge document or URL into the default bundle",
     },
     args: {
         source: {
@@ -187,15 +163,15 @@ export const importKnowledgeCommand = defineJsonCommand({
         },
         target: {
             type: "string",
-            description: "Override the write destination. Accepts a source name from your config; falls back to defaultWriteTarget then the working stash.",
+            description: "Override the write destination. Accepts a source name from your config; falls back to defaultWriteTarget then the working bundle.",
         },
         xref: {
             type: "string",
-            description: "Cross-reference ref merged into the document's `xrefs:` frontmatter (repeatable: --xref knowledge:auth-flow). Existing frontmatter is preserved (dedupe-append, never a nested block); a document whose frontmatter is not parseable YAML aborts the import rather than being rewritten lossily. Each ref must resolve in the write target or a configured source; an unresolvable ref aborts the import.",
+            description: "Cross-reference ref merged into the document's `xrefs:` frontmatter (repeatable: --xref knowledge/auth-flow). Existing frontmatter is preserved (dedupe-append, never a nested block); a document whose frontmatter is not parseable YAML aborts the import rather than being rewritten lossily. Each ref must resolve in the write target or a configured source; an unresolvable ref aborts the import.",
         },
         supersedes: {
             type: "string",
-            description: "Ref of an existing asset this document corrects (repeatable: --supersedes knowledge:legacy-guide). Imports the correction with an xref to the old asset AND demotes the old asset (`beliefState: superseded` + `supersededBy`, a metadata-only edit) so ranking prefers the correction and `--belief current` hides the stale version. An unresolvable or self-referencing ref aborts the import; a ref outside the write target and working stash still imports the correction but skips the demotion (reported as applied: false).",
+            description: "Ref of an existing asset this document corrects (repeatable: --supersedes knowledge/legacy-guide). Imports the correction with an xref to the old asset AND demotes the old asset (`beliefState: superseded` + `supersededBy`, a metadata-only edit) so ranking prefers the correction and `--belief current` hides the stale version. An unresolvable or self-referencing ref aborts the import; a ref outside the write target and working bundle still imports the correction but skips the demotion (reported as applied: false).",
         },
     },
     async run({ args }) {
@@ -205,18 +181,35 @@ export const importKnowledgeCommand = defineJsonCommand({
         // the last value, so read argv directly). Validation happens BEFORE any
         // read/write so an unresolvable ref (UsageError → exit 2) leaves the
         // stash untouched.
-        const xrefs = resolveXrefsForWrite(parseAllFlagValues("--xref"), args.target);
+        const rawSupersedes = parseAllFlagValues("--supersedes");
+        const writeTarget = resolveSupersedesWriteTarget(rawSupersedes, args.target);
+        const xrefs = resolveXrefsForWrite(parseAllFlagValues("--xref"), writeTarget);
         // Collect and validate --supersedes occurrences (repeatable). Same
         // before-any-read/write contract: an unresolvable ref exits 2 with nothing
         // imported AND nothing demoted. The superseded refs fold into the imported
         // doc's xrefs automatically (correction provenance); the demotion runs
         // inside writeMarkdownAsset, ordered before the git boundary commit.
-        const supersedes = resolveSupersedesForWrite(parseAllFlagValues("--supersedes"), args.target);
+        const supersedes = resolveSupersedesForWrite(rawSupersedes, writeTarget);
         for (const s of supersedes) {
             if (!xrefs.includes(s.ref))
                 xrefs.push(s.ref);
         }
-        const stashDir = resolveWriteTarget(loadConfig(), args.target).source.path;
+        const config = loadConfig();
+        const stashDir = (() => {
+            try {
+                return resolveWriteTarget(config, writeTarget).source.path;
+            }
+            catch (error) {
+                if (!writeTarget)
+                    throw error;
+                try {
+                    return resolveBundleWriteTarget(config, writeTarget).source.path;
+                }
+                catch {
+                    throw error;
+                }
+            }
+        })();
         const { content, preferredName } = await readKnowledgeInput(args.source, { stashDir });
         // Imported docs may carry their own frontmatter: merge (dedupe-append)
         // BEFORE the write so write-path indexing sees the final content and no
@@ -237,7 +230,7 @@ export const importKnowledgeCommand = defineJsonCommand({
             fallbackPrefix: "knowledge",
             preferredName: preferredName ?? inferAssetName(parseFrontmatter(content).content, "knowledge"),
             force: args.force,
-            target: args.target,
+            target: writeTarget,
             path: args.path,
             supersedes,
         });