akm-cli 0.9.0-rc.8 → 0.9.0

package/dist/commands/read/knowledge.js

@@ -11,6 +11,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { parse as yamlParse } from "yaml";
+import { detectAdapterId } from "../../core/adapter/detect-adapter.js";
 import { assertFlatAssetName, combineCreatePath, normalizeCreateSubPath } from "../../core/asset/asset-create.js";
 import { assetPathForName, stashDirFor } from "../../core/asset/asset-placement.js";
 import { assembleAsset } from "../../core/asset/asset-serialize.js";
@@ -19,11 +20,14 @@ import { conceptIdFromTypeName, parseRefInput } from "../../core/asset/resolve-r
 import { isHttpUrl, isWithin, resolveStashDir, tryReadStdinText } from "../../core/common.js";
 import { loadConfig } from "../../core/config/config.js";
 import { UsageError } from "../../core/errors.js";
+import { resolveBundleWriteTarget, resolveMutationTarget } from "../../core/mutation-target.js";
 import { resolveStashStandards } from "../../core/standards/resolve-stash-standards.js";
 import { warn } from "../../core/warn.js";
 import { commitWriteTargetBoundary, formatRefForMessage, recordWriteTargetPath, resolveWriteTarget, writeAssetToSource, } from "../../core/write-source.js";
 import { indexWrittenAssets } from "../../indexer/index-written-assets.js";
+import { deriveInstallations, slugForPath } from "../../indexer/installations.js";
 import { resolveSourceEntries } from "../../indexer/search/search-source.js";
+import { storeSecretResolver } from "../../sources/snapshot-fetchers/secret-seam.js";
 import { fetchWebsiteMarkdownSnapshot, shouldAllowPrivateWebsiteUrlForTests, } from "../../sources/snapshot-fetchers/website-ingest.js";
 import { writeSupersededEdge } from "../improve/memory/memory-belief.js";
 import { refToRelPath, resolveRefPathInStash } from "../lint/base-linter.js";
@@ -116,19 +120,16 @@ export async function readKnowledgeInput(source, options) {
         return readKnowledgeContent(source);
     const snapshot = await fetchWebsiteMarkdownSnapshot(source, {
         stashDir: options?.stashDir,
+        resolveSecret: storeSecretResolver.resolveSecret,
         allowPrivateHosts: options?.allowPrivateHosts ?? shouldAllowPrivateWebsiteUrlForTests(source),
     });
     return { content: snapshot.content, preferredName: snapshot.preferredName };
 }
 /**
  * Parse a `--xref` / `--supersedes` value through the new-grammar input parser
- * (`parseRefInput`, the 0.9.0 `[bundle//]conceptId` grammar) so malformed and
- * origin-prefixed spellings get a structured error instead of a misleading "did
- * not resolve". Chunk-8 WI-8.5c: the legacy `[origin//]type:name` content-surface
- * arm is retired — `--xref`/`--supersedes` take the conceptId form. A `local//`
- * origin is accepted (it names the same local resolution this validator
- * performs, mirroring lint's `local//` strip); any other origin is rejected —
- * write-time validation only resolves local stash roots.
+ * (`parseRefInput`, the `[bundle//]conceptId` grammar) so malformed values get a
+ * structured error instead of a misleading "did not resolve". Bundle qualifiers
+ * are retained for exact source membership checks.
  */
 function parseWriteRef(raw, flag) {
     let parsed;
@@ -139,21 +140,21 @@ function parseWriteRef(raw, flag) {
         const message = error instanceof Error ? error.message : String(error);
         throw new UsageError(`${flag} "${raw}" is not a valid asset ref: ${message}`, "INVALID_FLAG_VALUE", `Refs use the conceptId form, e.g. ${flag} knowledge/auth-flow.`);
     }
-    if (parsed.origin && parsed.origin !== "local") {
-        throw new UsageError(`${flag} "${raw}" carries the origin prefix "${parsed.origin}//" — ${flag} only resolves refs in the write target, the working stash, and configured sources.`, "INVALID_FLAG_VALUE", `Pass the plain conceptId form, e.g. ${flag} ${conceptIdFromTypeName(parsed.type, parsed.name)}.`);
-    }
-    // Canonical bare conceptId: type alias resolved, name normalized, `local//`
-    // dropped (it names the same local resolution this validator performs). The
-    // bare `<stash-subdir>/<name>` short ref (WI-8.5a) is what lands in the
-    // containing bundle's frontmatter (§11.1 short-ref rule); the name is already
-    // normalized by the parser.
-    return { ref: conceptIdFromTypeName(parsed.type, parsed.name), type: parsed.type, name: parsed.name };
+    // Bundle qualifiers remain explicit so duplicate names resolve in the named
+    // source.
+    const conceptId = conceptIdFromTypeName(parsed.type, parsed.name);
+    const origin = parsed.origin;
+    return {
+        ref: origin ? `${origin}//${conceptId}` : conceptId,
+        type: parsed.type,
+        name: parsed.name,
+        ...(origin ? { origin } : {}),
+    };
 }
 /**
  * Trim, parse, and dedupe `--xref` / `--supersedes` flag values, in argv
- * order. Parsing comes BEFORE deduplication so two alias spellings of the
- * same asset (`environment:prod` and `env:prod`, `local//knowledge:x` and
- * `knowledge:x`) collapse into one canonical entry.
+ * order. Parsing comes before deduplication so normalized spellings collapse
+ * into one canonical entry.
  */
 function parseWriteRefs(rawRefs, flag) {
     const parsedRefs = [];
@@ -167,26 +168,26 @@ function parseWriteRefs(rawRefs, flag) {
     }
     return parsedRefs;
 }
-/**
- * The ONE root set write-time ref validation resolves against, shared by
- * `resolveXrefsForWrite` and `resolveSupersedesForWrite` so the two flags can
- * never disagree on what a ref resolves to:
- *
- *   1. the resolved write target (mutable),
- *   2. the primary working stash when it is a different directory (mutable) —
- *      a `--target`/`defaultWriteTarget` write must still see working-stash
- *      assets, which `resolveSourceEntries(writeTarget)` alone omits,
- *   3. every other configured source (read-only for demotion purposes).
- *
- * NOTE: this is deliberately a superset of lint's root set (lint roots at the
- * working stash; this roots at the write target AND the working stash).
- */
 function resolveWriteRefRoots(target) {
     const cfg = loadConfig();
-    const stashRoot = resolveWriteTarget(cfg, target).source.path;
+    let writeTarget;
+    try {
+        writeTarget = resolveWriteTarget(cfg, target);
+    }
+    catch (error) {
+        if (!target)
+            throw error;
+        try {
+            writeTarget = resolveBundleWriteTarget(cfg, target);
+        }
+        catch {
+            throw error;
+        }
+    }
+    const stashRoot = writeTarget.source.path;
     let workingStash;
     try {
-        workingStash = resolveStashDir({ readOnly: true });
+        workingStash = resolveStashDir();
     }
     catch {
         // No working stash configured — the write target alone.
@@ -194,15 +195,51 @@ function resolveWriteRefRoots(target) {
     const mutableRoots = [stashRoot];
     if (workingStash && path.resolve(workingStash) !== path.resolve(stashRoot))
         mutableRoots.push(workingStash);
-    const otherSources = resolveSourceEntries(stashRoot, cfg).filter((s) => !mutableRoots.some((m) => path.resolve(m) === path.resolve(s.path)) && fs.existsSync(s.path));
-    return { mutableRoots: mutableRoots.filter((p) => fs.existsSync(p)), otherSources };
+    const namedSources = resolveSourceEntries(undefined, cfg);
+    const installations = deriveInstallations(namedSources);
+    const bundleByPath = new Map(namedSources.flatMap((source, index) => {
+        const bundleId = installations[index]?.id;
+        return bundleId ? [[path.resolve(source.path), bundleId]] : [];
+    }));
+    const otherSources = namedSources.filter((s) => !mutableRoots.some((m) => path.resolve(m) === path.resolve(s.path)) && fs.existsSync(s.path));
+    const roots = [
+        ...mutableRoots
+            .filter((p) => fs.existsSync(p))
+            .map((p) => {
+            const source = namedSources.find((candidate) => path.resolve(candidate.path) === path.resolve(p));
+            const mutable = path.resolve(p) === path.resolve(stashRoot)
+                ? writeTarget.source.adapterId === "akm"
+                : source?.writable === true && (source.adapterId ?? detectAdapterId(p)) === "akm";
+            return {
+                path: p,
+                source,
+                bundleId: bundleByPath.get(path.resolve(p)) ?? slugForPath(p),
+                mutable,
+            };
+        }),
+        ...otherSources.map((source) => ({
+            path: source.path,
+            source,
+            bundleId: bundleByPath.get(path.resolve(source.path)) ?? slugForPath(source.path),
+            mutable: false,
+        })),
+    ];
+    return { roots };
+}
+function rootsForWriteRef(parsed, roots) {
+    if (!parsed.origin)
+        return roots;
+    return roots.filter((root) => root.bundleId === parsed.origin);
+}
+function canonicalWriteRef(parsed, bundleId) {
+    return `${bundleId}//${conceptIdFromTypeName(parsed.type, parsed.name)}`;
 }
 /**
  * True when write-time validation must FAIL OPEN for this ref type — exactly
  * lint's `checkMissingRefs` policy (`if (relPath === null) continue`,
- * base-linter.ts): a type the slug resolver cannot map to a path (`script:` is
- * contract-pinned to return null) is accepted without an existence check
- * rather than being unwinnable. `workflow:` never fails open — it resolves
+ * base-linter.ts): a type the slug resolver cannot map to a path (script refs
+ * are contract-pinned to return null) is accepted without an existence check
+ * rather than being unwinnable. Workflow refs never fail open — they resolve
  * stash-rooted via {@link locateWriteRefInRoot}.
  */
 function isFailOpenRefType(type, name) {
@@ -210,7 +247,7 @@ function isFailOpenRefType(type, name) {
 }
 /**
  * Resolve a write-time ref to its primary on-disk file within a single stash
- * root. Wraps lint's `resolveRefPathInStash` with one addition: `workflow:`
+ * root. Wraps lint's `resolveRefPathInStash` with one addition: workflow
  * refs are probed against the ROOT's workflows/ dir first (every recognized
  * workflow extension), because `workflowSpec.toAssetPath` inside
  * `refToRelPath` probes the CWD — and write validation must not depend on the
@@ -230,8 +267,9 @@ function locateWriteRefInRoot(type, name, root) {
 }
 /** Build the shared exit-2 error for refs that resolved in no root. */
 function unresolvedRefsError(flag, unresolved) {
-    const first = unresolved[0];
-    return new UsageError(`${flag} ref${unresolved.length > 1 ? "s" : ""} did not resolve in the write target or any configured source: ${unresolved.map((u) => u.ref).join(", ")}`, "INVALID_FLAG_VALUE", `Find the intended asset with \`akm search "${first.name}" --type ${first.type}\`. Refs use the form [bundle//]conceptId (e.g. knowledge/guide.md).`);
+    const firstName = unresolved[0]?.name ?? "asset";
+    const firstType = unresolved[0]?.type ?? "knowledge";
+    return new UsageError(`${flag} ref${unresolved.length > 1 ? "s" : ""} did not resolve in the write target or any configured source: ${unresolved.map((u) => u.ref).join(", ")}`, "INVALID_FLAG_VALUE", `Find the intended asset with \`akm search "${firstName}" --type ${firstType}\`. Refs use the form [bundle//]conceptId (e.g. knowledge/guide.md).`);
 }
 // ── Cross-references (--xref) ────────────────────────────────────────────────
 /**
@@ -243,7 +281,7 @@ export const XREF_SOFT_CAP = 5;
 /**
  * Validate `--xref` flag values before ANY write happens.
  *
- * Each ref (`type:name`) must resolve to a real asset in the write-ref root
+ * Each `[bundle//]conceptId` must resolve to a real asset in the write-ref root
  * set (write target + working stash + configured sources — see
  * {@link resolveWriteRefRoots}; cross-stash provenance refs into read-only
  * sources are accepted). An unresolvable ref is input validation of an
@@ -252,33 +290,36 @@ export const XREF_SOFT_CAP = 5;
  * validation leaves the stash untouched. Resolution reuses the lint
  * ref-resolver helpers (`refToRelPath` / `resolveRefPathInStash`) — do not
  * fork a second resolver — and mirrors lint's fail-open policy: a type the
- * resolver cannot map to a path (`script:`) is accepted without an existence
- * check.
+ * resolver cannot map to a path (for example a script concept) is accepted
+ * without an existence check.
  *
- * Returns the CANONICAL `type:name` spellings (alias types resolved, names
- * normalized, `local//` stripped — see {@link ParsedWriteRef}), deduplicated
- * in argv order. More than {@link XREF_SOFT_CAP} refs emits a stderr warning
- * (soft cap) but still returns them all.
+ * Returns fully-qualified durable refs, deduplicated in argv order. More than
+ * {@link XREF_SOFT_CAP} refs emits a stderr warning (soft cap) but still
+ * returns them all.
  */
 export function resolveXrefsForWrite(rawXrefs, target) {
     const parsedRefs = parseWriteRefs(rawXrefs, "--xref");
     if (parsedRefs.length === 0)
         return [];
-    const { mutableRoots, otherSources } = resolveWriteRefRoots(target);
-    const allRoots = [...mutableRoots, ...otherSources.map((s) => s.path)];
+    const { roots } = resolveWriteRefRoots(target);
     const unresolved = [];
+    const xrefs = [];
     for (const parsed of parsedRefs) {
-        if (isFailOpenRefType(parsed.type, parsed.name))
-            continue;
-        if (!allRoots.some((root) => locateWriteRefInRoot(parsed.type, parsed.name, root) !== null)) {
+        const candidates = rootsForWriteRef(parsed, roots);
+        const resolvedRoot = isFailOpenRefType(parsed.type, parsed.name)
+            ? candidates[0]
+            : candidates.find((root) => locateWriteRefInRoot(parsed.type, parsed.name, root.path) !== null);
+        if (!resolvedRoot) {
             unresolved.push(parsed);
+            continue;
         }
+        const ref = canonicalWriteRef(parsed, resolvedRoot.bundleId);
+        if (!xrefs.includes(ref))
+            xrefs.push(ref);
     }
     if (unresolved.length > 0) {
         throw unresolvedRefsError("--xref", unresolved);
     }
-    // The CANONICAL spellings are what land in frontmatter (see ParsedWriteRef).
-    const xrefs = parsedRefs.map((p) => p.ref);
     if (xrefs.length > XREF_SOFT_CAP) {
         warn(`Warning: ${xrefs.length} xrefs exceeds the ~${XREF_SOFT_CAP} soft cap from the back-linking conventions. ` +
             "Each xref folds into this asset's search hints, so extras blur its ranking signal. Writing anyway.");
@@ -300,8 +341,9 @@ export function resolveXrefsForWrite(rawXrefs, target) {
  * scanner and re-serializing that lossy result would destroy list/nested
  * values (`tags: [a, b]` → `tags: ""`). Rather than corrupt data the caller
  * asked to preserve, a block that is not a parseable YAML mapping throws
- * {@link UsageError} (exit 2, before any write) — fix the frontmatter or run
- * the command without `--xref`, which keeps the file verbatim. Known
+ * {@link UsageError} (exit 2, before any write). The AKM write boundary also
+ * rejects malformed frontmatter without `--xref` because it cannot safely add
+ * required type metadata. Known
  * cosmetic limitation: YAML comments and anchors in a VALID block do not
  * survive the round-trip (values are preserved).
  */
@@ -311,7 +353,7 @@ export function mergeXrefsIntoContent(content, xrefs) {
     const parsed = parseFrontmatter(content);
     if (parsed.frontmatter?.trim()) {
         if (!isParseableYamlMapping(parsed.frontmatter)) {
-            throw new UsageError("--xref cannot merge into this document: its frontmatter is not a parseable YAML mapping, and rewriting it would drop the values the parser could not read.", "INVALID_FLAG_VALUE", "Fix the document's frontmatter (e.g. an unterminated quote) and retry, or run the command without --xref to keep the file verbatim.");
+            throw new UsageError("--xref cannot merge into this document: its frontmatter is not a parseable YAML mapping, and rewriting it would drop the values the parser could not read.", "INVALID_FLAG_VALUE", "Fix the document's frontmatter (e.g. an unterminated quote) and retry.");
         }
     }
     const existingValue = parsed.data.xrefs;
@@ -343,6 +385,18 @@ function isParseableYamlMapping(frontmatter) {
         return false;
     }
 }
+/** Resolve any qualified supersedes ref as the mutation target for remember/import. */
+export function resolveSupersedesWriteTarget(rawRefs, target) {
+    const config = loadConfig();
+    let effectiveTarget = target;
+    for (const parsed of parseWriteRefs(rawRefs, "--supersedes")) {
+        if (!parsed.origin)
+            continue;
+        const resolved = resolveMutationTarget(config, { type: parsed.type, name: parsed.name, origin: parsed.origin }, effectiveTarget).target;
+        effectiveTarget = resolved.selector ?? resolved.source.name;
+    }
+    return effectiveTarget;
+}
 /**
  * Asset types `--supersedes` must refuse to demote: the demotion writes a YAML
  * frontmatter block onto the target file, and these types are RAW files whose
@@ -366,7 +420,7 @@ const SUPERSEDE_REJECTED_TYPES = new Set(["secret", "env", "task", "script"]);
  * Because the demotion PREPENDS a YAML frontmatter block when the target file
  * has none, only markdown assets may be demoted: refs of a raw asset type
  * ({@link SUPERSEDE_REJECTED_TYPES}) and refs resolving to any non-`.md` file
- * (e.g. a YAML workflow program) are rejected with {@link UsageError} BEFORE
+ * (for example a task YAML file) are rejected with {@link UsageError} BEFORE
  * any write — never silently corrupted.
  *
  * Demotion targets must live under the resolved write target's source path or
@@ -384,30 +438,28 @@ export function resolveSupersedesForWrite(rawRefs, target) {
     const parsedRefs = parseWriteRefs(rawRefs, "--supersedes");
     if (parsedRefs.length === 0)
         return [];
-    const { mutableRoots, otherSources } = resolveWriteRefRoots(target);
-    // Mutable roots first: when a ref resolves in several roots, demote the copy
-    // this command is allowed to mutate. Non-mutable roots keep their SearchSource
-    // so the skip reason can distinguish "re-run with --target" (a configured
-    // writable source that simply is not this write's target) from genuinely
-    // read-only sources.
-    const orderedRoots = [
-        ...mutableRoots.map((p) => ({ path: p })),
-        ...otherSources.map((s) => ({ path: s.path, source: s })),
-    ];
+    const { roots } = resolveWriteRefRoots(target);
     const plan = [];
     const unresolved = [];
     for (const parsed of parsedRefs) {
+        const orderedRoots = rootsForWriteRef(parsed, roots);
         // Data-corruption gate (SPEC-5): demotion is a frontmatter write; a raw
         // asset type must be rejected up front — resolving it and mutating the
         // file would prepend a YAML block over its raw bytes.
         if (SUPERSEDE_REJECTED_TYPES.has(parsed.type)) {
-            throw new UsageError(`--supersedes cannot demote ${parsed.ref}: "${parsed.type}:" assets are raw files, and the demotion writes YAML frontmatter that would corrupt them.`, "INVALID_FLAG_VALUE", "Only markdown assets (e.g. memory:, knowledge:, fact:) can carry the beliefState/supersededBy demotion. Replace or delete the raw asset instead.");
+            throw new UsageError(`--supersedes cannot demote ${parsed.ref}: asset type "${parsed.type}" uses raw files, and the demotion writes YAML frontmatter that would corrupt them.`, "INVALID_FLAG_VALUE", "Only markdown assets (e.g. memories/note, knowledge/guide, facts/team/tool-stack) can carry the beliefState/supersededBy demotion. Replace or delete the raw asset instead.");
         }
         let located = null;
         for (const root of orderedRoots) {
             const filePath = locateWriteRefInRoot(parsed.type, parsed.name, root.path);
             if (filePath !== null) {
-                located = { root: root.path, source: root.source, filePath };
+                located = {
+                    root: root.path,
+                    source: root.source,
+                    bundleId: root.bundleId,
+                    mutable: root.mutable,
+                    filePath,
+                };
                 break;
             }
         }
@@ -416,20 +468,21 @@ export function resolveSupersedesForWrite(rawRefs, target) {
             continue;
         }
         // Belt-and-suspenders for the same corruption class: whatever the type,
-        // the demotion may only touch a markdown file. Rejects e.g. a YAML
-        // workflow program (`workflow:deploy` resolving to workflows/deploy.yaml,
-        // or the explicit `workflow:deploy.yaml` spelling).
+        // the demotion may only touch a markdown file. Rejects, for example, a task
+        // YAML file reached through a malformed or stale ref.
         if (!located.filePath.toLowerCase().endsWith(".md")) {
             throw new UsageError(`--supersedes ${parsed.ref} resolves to a non-markdown file (${located.filePath}) — the demotion writes YAML frontmatter and would corrupt it.`, "INVALID_FLAG_VALUE", "Only markdown assets can carry the beliefState/supersededBy demotion. Replace or delete the file instead.");
         }
-        const { root, source, filePath } = located;
-        const writable = source === undefined;
+        const { root, source, bundleId, mutable: writable, filePath } = located;
         // The eligibility rule is write-target-or-working-stash, NOT source
         // writability: mutating a non-target writable source would leave it dirty
         // outside any boundary commit. Name the remedy when one exists.
         const namedWritableSource = source?.writable === true ? source.registryId : undefined;
+        const canonicalRef = canonicalWriteRef(parsed, bundleId);
+        if (plan.some((item) => item.ref === canonicalRef))
+            continue;
         plan.push({
-            ref: parsed.ref,
+            ref: canonicalRef,
             filePath,
             stashRoot: root,
             writable,
@@ -460,14 +513,15 @@ export function resolveSupersedesForWrite(rawRefs, target) {
  */
 export async function writeMarkdownAsset(options) {
     const cfg = loadConfig();
-    const target = resolveWriteTarget(cfg, options.target);
-    const { source, config } = target;
-    const typeRoot = path.join(source.path, options.type === "knowledge" ? "knowledge" : "memories");
     // `--name` is the flat asset name; `--path` is the subdirectory under the
     // type root. Combine them into the nested name the path resolver expects.
     const subPath = normalizeCreateSubPath(options.path);
     const baseName = normalizeMarkdownAssetName(options.name, inferAssetName(options.content, options.fallbackPrefix, options.preferredName));
     const normalizedName = combineCreatePath(subPath, baseName);
+    const resolved = resolveMutationTarget(cfg, { type: options.type, name: normalizedName }, options.target);
+    const { target } = resolved;
+    const { source, config } = target;
+    const typeRoot = path.join(source.path, options.type === "knowledge" ? "knowledge" : "memories");
     // Pre-flight: existence + force semantics. The helper itself overwrites
     // unconditionally; the CLI surfaces a friendlier UsageError before any
     // disk activity when --force is absent.
@@ -485,11 +539,12 @@ export async function writeMarkdownAsset(options) {
     // Input validation: exit 2, before any write, nothing demoted.
     for (const item of options.supersedes ?? []) {
         if (path.resolve(item.filePath) === path.resolve(assetPath)) {
-            throw new UsageError(`--supersedes ${item.ref} resolves to the asset being written ("${options.type}:${normalizedName}") — a correction cannot supersede itself.`, "INVALID_FLAG_VALUE", "Write the correction under a different --name, or drop --supersedes when overwriting an asset in place with --force.");
+            throw new UsageError(`--supersedes ${item.ref} resolves to the asset being written ("${resolved.displayRef}") — a correction cannot supersede itself.`, "INVALID_FLAG_VALUE", "Write the correction under a different --name, or drop --supersedes when overwriting an asset in place with --force.");
         }
     }
-    const ref = { type: options.type, name: normalizedName };
-    const result = await writeAssetToSource(source, config, ref, options.content);
+    const result = await writeAssetToSource(source, config, resolved.ref, options.content);
+    const durableRef = result.ref;
+    result.ref = resolved.displayRef;
     // SPEC-5 (--supersedes): demote each superseded asset by mutating its
     // frontmatter (`beliefState: superseded` + sorted-set-append `supersededBy`;
     // every other key and the body are preserved). Ordered BEFORE
@@ -532,12 +587,9 @@ export async function writeMarkdownAsset(options) {
         // on a git target, uncommitted (and a re-run hits RESOURCE_ALREADY_EXISTS).
         // Degrade to the same applied:false report the non-writable path uses.
         try {
-            // supersededBy points at the correction's canonical write ref (F4b-flipped
-            // display spelling), keeping it in lockstep with the reported `result.ref`.
-            // The --xref/--supersedes input path (resolveXrefsForWrite/parseWriteRef)
-            // is now the new-grammar conceptId surface too (WI-8.5c).
-            writeSupersededEdge(item.filePath, result.ref);
-            if (path.resolve(item.stashRoot) === path.resolve(source.path)) {
+            const sameSource = path.resolve(item.stashRoot) === path.resolve(source.path);
+            writeSupersededEdge(item.filePath, durableRef);
+            if (sameSource) {
                 recordWriteTargetPath(source, item.filePath);
             }
         }
@@ -555,7 +607,7 @@ export async function writeMarkdownAsset(options) {
     }
     // 0.9.0 (issue #507): single batch commit at the write boundary for git
     // targets. No-op for filesystem/primary-stash targets.
-    commitWriteTargetBoundary(target, `Update ${formatRefForMessage(ref)}`);
+    commitWriteTargetBoundary(target, `Update ${formatRefForMessage(resolved.ref)}`);
     // Write-path indexing: the asset is searchable immediately. Fail-open; reads
     // no longer trigger reindexes, so keeping the index current is the writer's
     // job. Demoted files reindex under their own containing root (usually the
@@ -564,9 +616,12 @@ export async function writeMarkdownAsset(options) {
     // effect without waiting for the next full index.
     const demotedInTargetRoot = demotedByRoot.get(source.path) ?? [];
     demotedByRoot.delete(source.path);
-    await indexWrittenAssets(source.path, [result.path, ...demotedInTargetRoot]);
+    await indexWrittenAssets(source.path, [result.path, ...demotedInTargetRoot], { bundleId: resolved.ref.origin });
+    const sourceEntries = resolveSourceEntries(undefined, cfg);
+    const sourceInstallations = deriveInstallations(sourceEntries);
     for (const [root, files] of demotedByRoot) {
-        await indexWrittenAssets(root, files);
+        const sourceIndex = sourceEntries.findIndex((entry) => path.resolve(entry.path) === path.resolve(root));
+        await indexWrittenAssets(root, files, { bundleId: sourceInstallations[sourceIndex]?.id });
     }
     // Placement hint (stash-organization conventions): CLI writers never receive
     // the resolveStashStandards prompt injection LLM flows get, so a type-root
@@ -582,7 +637,7 @@ export async function writeMarkdownAsset(options) {
                 // and a dead `akm show` pointer is worse than generic wording.
                 const orgFactPath = path.join(source.path, "facts", "conventions", "organization.md");
                 hint = fs.existsSync(orgFactPath)
-                    ? `Wrote to the ${options.type} root. This stash has placement conventions — see \`akm show fact:conventions/organization\`.`
+                    ? `Wrote to the ${options.type} root. This stash has placement conventions — see \`akm show facts/conventions/organization\`.`
                     : `Wrote to the ${options.type} root. This stash has placement conventions — see the convention facts under its facts/ directory.`;
             }
         }

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

@@ -4,7 +4,7 @@
 import { toErrorMessage } from "../../core/common.js";
 import { DEFAULT_CONFIG } from "../../core/config/config.js";
 import { warn } from "../../core/warn.js";
-import { resolveProviderFactory } from "../../registry/factory.js";
+import { resolveRegistryProviderFactory } from "../../registry/factory.js";
 // ── Eagerly import providers to trigger self-registration ───────────────────
 import "../../registry/providers/index.js";
 // ── Public API ──────────────────────────────────────────────────────────────
@@ -142,7 +142,7 @@ export function resolveRegistries(configRegistries) {
 // ── Provider resolution ─────────────────────────────────────────────────────
 function createProvider(entry, warnings) {
     const providerType = entry.provider ?? "static-index";
-    const factory = resolveProviderFactory(providerType);
+    const factory = resolveRegistryProviderFactory(providerType);
     if (!factory) {
         const label = entry.name ? `${entry.name} (${entry.url})` : entry.url;
         warnings.push(`Registry ${label}: unknown provider type "${providerType}"`);

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

@@ -1,13 +1,14 @@
 // This Source Code Form is subject to the terms of the Mozilla Public
 // 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/.
+import { getParsedInvocation } from "../../cli/invocation.js";
 import { getStringArg } from "../../cli/parse-args.js";
 import { defineJsonCommand, output, parseAllFlagValues } from "../../cli/shared.js";
 import { UsageError } from "../../core/errors.js";
 import { appendEvent } from "../../core/events.js";
 import { resolveUsageEventSource } from "../../indexer/usage/usage-events.js";
-import { buildMemoryFrontmatter, parseDuration, readMemoryContent, resolveRememberContentArg, runAutoHeuristics, runLlmEnrich, } from "../remember.js";
-import { assertFlatAssetName, inferAssetName, resolveSupersedesForWrite, resolveXrefsForWrite, writeMarkdownAsset, } from "./knowledge.js";
+import { buildMemoryFrontmatter, parseDuration, readMemoryContent, runAutoHeuristics, runLlmEnrich } from "../remember.js";
+import { assertFlatAssetName, inferAssetName, resolveSupersedesForWrite, resolveSupersedesWriteTarget, resolveXrefsForWrite, writeMarkdownAsset, } from "./knowledge.js";
 import { akmSearch } from "./search.js";
 // ── Helper: similar memory search ────────────────────────────────────────────
 /**
@@ -32,11 +33,22 @@ async function fetchSimilarMemories(query, excludeRef, eventSource) {
         return [];
     }
 }
+/**
+ * `--target` was renamed to `--bundle` on `remember` in 0.9 (S8). citty is
+ * non-strict, so the retired spelling is silently absorbed rather than
+ * rejected — the memory then lands in the default bundle instead of the one
+ * the caller named, with exit 0 and no error. Reject it explicitly instead.
+ */
+function rejectRetiredTargetFlag() {
+    if (!getParsedInvocation().hasFlag("--target"))
+        return;
+    throw new UsageError("`akm remember --target` was renamed to `--bundle` in 0.9. Use `--bundle <name>` instead.", "INVALID_FLAG_VALUE");
+}
 // ── Command definition ────────────────────────────────────────────────────────
 export const rememberCommand = defineJsonCommand({
     meta: {
         name: "remember",
-        description: "Record a memory in the default stash",
+        description: "Record a memory in the default bundle",
     },
     args: {
         content: {
@@ -75,11 +87,11 @@ export const rememberCommand = defineJsonCommand({
         },
         xref: {
             type: "string",
-            description: "Cross-reference ref recorded in the memory's `xrefs:` frontmatter (repeatable: --xref knowledge:auth-flow --xref memory:vpn-note). Each ref must resolve in the write target or a configured source; an unresolvable ref aborts the write.",
+            description: "Cross-reference ref recorded in the memory's `xrefs:` frontmatter (repeatable: --xref knowledge/auth-flow --xref memories/vpn-note). Each ref must resolve in the write target or a configured source; an unresolvable ref aborts the write.",
         },
         supersedes: {
             type: "string",
-            description: "Ref of an existing asset this memory corrects (repeatable: --supersedes memory:projectA/old-note). Writes 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 write; a ref outside the write target and working stash still writes the correction but skips the demotion (reported as applied: false).",
+            description: "Ref of an existing asset this memory corrects (repeatable: --supersedes memories/projectA/old-note). Writes 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 write; a ref outside the write target and working bundle still writes the correction but skips the demotion (reported as applied: false).",
         },
         auto: {
             type: "boolean",
@@ -91,9 +103,9 @@ export const rememberCommand = defineJsonCommand({
             description: "Call the configured LLM to propose tags and description (requires LLM config)",
             default: false,
         },
-        target: {
+        bundle: {
             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.",
         },
         user: {
             type: "string",
@@ -111,13 +123,23 @@ export const rememberCommand = defineJsonCommand({
             type: "string",
             description: "Scope this memory to a channel name (persisted as `scope_channel` frontmatter)",
         },
-        showSimilar: {
+        "show-similar": {
             type: "boolean",
-            description: "Return top-3 similar existing memories in output (opt-in)",
+            // R-062: canonical spelling is kebab-case, matching every other
+            // multi-word flag in the CLI (--fail-on-flagged, --auto-fix, …).
+            // `--showSimilar` (the pre-rename spelling) is kept as an explicit,
+            // documented alias rather than a silent citty auto-alias — citty
+            // registers BOTH the camelCase and kebab-case spelling of any
+            // declared flag name automatically, so this is a rename, not a
+            // breaking change: both spellings already worked, and both keep
+            // working.
+            alias: "showSimilar",
+            description: "Return top-3 similar existing memories in output (opt-in). Alias: --showSimilar.",
         },
     },
     async run({ args }) {
-        const body = readMemoryContent(resolveRememberContentArg(args.content));
+        rejectRetiredTargetFlag();
+        const body = readMemoryContent(args.content);
         const eventSource = resolveUsageEventSource();
         // `--name` is a flat name; subdirectory placement is `--path`'s job.
         assertFlatAssetName(args.name);
@@ -130,7 +152,9 @@ export const rememberCommand = defineJsonCommand({
         // input validation (UsageError → exit 2) and must leave the stash
         // untouched. Refs resolvable only in a configured extra stash source are
         // accepted (cross-stash provenance).
-        const xrefs = resolveXrefsForWrite(parseAllFlagValues("--xref"), args.target);
+        const rawSupersedes = parseAllFlagValues("--supersedes");
+        const writeTarget = resolveSupersedesWriteTarget(rawSupersedes, args.bundle);
+        const xrefs = resolveXrefsForWrite(parseAllFlagValues("--xref"), writeTarget);
         // Collect and validate --supersedes occurrences (repeatable). Same
         // before-any-write validation contract: an unresolvable ref exits 2 with
         // nothing written AND nothing demoted (no partial correction). The
@@ -138,7 +162,7 @@ export const rememberCommand = defineJsonCommand({
         // (correction provenance per the back-linking conventions); the demotion
         // itself 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);
@@ -157,7 +181,10 @@ export const rememberCommand = defineJsonCommand({
         // --xref counts as structured metadata (it must land in frontmatter) but,
         // like scope, does NOT trigger the tags-required check — provenance
         // without tags is a valid write.
-        const hasStructuredArgs = hasTagRequiringArgs || hasScope || args.auto || xrefs.length > 0;
+        // --enrich is structured (it must reach the Mode-3 dispatch below, not the
+        // zero-flag hot path) but, like --auto, never tag-requiring: enrichment is
+        // fail-soft and a zero-tag outcome still writes.
+        const hasStructuredArgs = hasTagRequiringArgs || hasScope || args.auto || args.enrich || xrefs.length > 0;
         if (!hasStructuredArgs) {
             // Phase 1B / Rec 7: even the zero-flag hot-path emits
             // `captureMode: hot` + `beliefState: asserted` so user-supplied
@@ -176,7 +203,7 @@ export const rememberCommand = defineJsonCommand({
                 fallbackPrefix: "memory",
                 preferredName: inferAssetName(body, "memory"),
                 force: args.force,
-                target: args.target,
+                target: writeTarget,
                 path: args.path,
                 supersedes,
             });
@@ -278,7 +305,7 @@ export const rememberCommand = defineJsonCommand({
             fallbackPrefix: "memory",
             preferredName: inferAssetName(body, "memory"),
             force: args.force,
-            target: args.target,
+            target: writeTarget,
             path: args.path,
             supersedes,
         });