akm-cli 0.10.261009-beta → 0.10.261010-beta

package/dist/commands/read/knowledge.js

@@ -8,10 +8,12 @@
  * (knowledge and memory) from the CLI. Extracted to keep the CLI entry point
  * focused on command definitions and routing.
  */
+import { createHash } from "node:crypto";
 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 { normalizeAkmMarkdown } from "../../core/asset/akm-markdown.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";
@@ -24,6 +26,7 @@ import { resolveBundleWriteTarget, resolveMutationTarget } from "../../core/muta
 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 { withAssetMutationLease } from "../../indexer/index-writer-lock.js";
 import { indexWrittenAssets } from "../../indexer/index-written-assets.js";
 import { deriveInstallations, slugForPath } from "../../indexer/installations.js";
 import { resolveSourceEntries } from "../../indexer/search/search-source.js";
@@ -502,16 +505,10 @@ export function resolveSupersedesForWrite(rawRefs, target, targetFlag) {
     }
     return plan;
 }
-// ── Asset writing ────────────────────────────────────────────────────────────
-/**
- * Write a markdown asset (knowledge or memory) to the resolved write target.
- *
- * Resolves the write target via the v1 precedence chain (`--bundle` →
- * `defaultWriteTarget` → working stash), validates the path is within the
- * type root, enforces `--force` semantics, and delegates the actual write
- * to `writeAssetToSource`.
- */
 export async function writeMarkdownAsset(options) {
+    if (options.expectedContentHash !== undefined && !/^[0-9a-f]{64}$/.test(options.expectedContentHash)) {
+        throw new UsageError("The expected content hash must be a lowercase hex SHA-256 digest (64 characters).", "INVALID_FLAG_VALUE");
+    }
     const cfg = loadConfig();
     // `--name` is the flat asset name; `--path` is the subdirectory under the
     // type root. Combine them into the nested name the path resolver expects.
@@ -524,16 +521,10 @@ export async function writeMarkdownAsset(options) {
     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.
     const assetPath = assetPathForName(options.type, typeRoot, normalizedName);
     if (!isWithin(assetPath, typeRoot)) {
         throw new UsageError(`Resolved ${options.type} path escapes the stash: "${normalizedName}"`);
     }
-    if (fs.existsSync(assetPath) && !options.force) {
-        throw new UsageError(`${options.type === "knowledge" ? "Knowledge" : "Memory"} "${normalizedName}" already exists. Re-run with --force to overwrite it.`, "RESOURCE_ALREADY_EXISTS");
-    }
     // A correction cannot supersede ITSELF. Under `--force` the ref resolves to
     // the very file this command is about to overwrite, and the demotion would
     // immediately mark the fresh correction superseded (plus a self-xref) —
@@ -544,72 +535,113 @@ export async function writeMarkdownAsset(options) {
             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 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
-    // commitWriteTargetBoundary so a git target batches the correction and the
-    // demoted incumbent into the single boundary commit instead of leaving the
-    // metadata edit as dirty residue after it.
-    const superseded = [];
-    const demotedByRoot = new Map();
-    for (const item of options.supersedes ?? []) {
-        if (!item.writable) {
-            const reason = item.reason ?? "target is not writable";
-            warn(`Warning: superseded asset ${item.ref} was NOT demoted (${reason}). ` +
-                "The correction was written and cites it in xrefs; demote the old asset where it is writable.");
-            superseded.push({ ref: item.ref, applied: false, reason });
-            continue;
-        }
-        // The demotion round-trips the old file's frontmatter through the YAML
-        // parser. A malformed block would silently fall back to the lossy lenient
-        // scanner and re-serializing that result destroys list/nested values —
-        // skip instead of rewriting, mirroring mergeXrefsIntoContent's
-        // abort-on-malformed policy (the correction itself still writes).
-        let oldFrontmatter = null;
-        try {
-            oldFrontmatter = parseFrontmatter(fs.readFileSync(item.filePath, "utf8")).frontmatter;
-        }
-        catch {
-            // Unreadable file — let writeSupersededEdge surface the real fs error.
-        }
-        if (oldFrontmatter?.trim() && !isParseableYamlMapping(oldFrontmatter)) {
-            const reason = "its existing frontmatter is not a parseable YAML mapping — rewriting it would drop the values the parser could not read";
-            warn(`Warning: superseded asset ${item.ref} was NOT demoted (${reason}). ` +
-                "The correction was written and cites it in xrefs; fix the old asset's frontmatter and re-run the correction with --force.");
-            superseded.push({ ref: item.ref, applied: false, reason });
-            continue;
+    // The lease covers only what reads or changes authored files: the existence
+    // and revision checks, the write, the demotions and the boundary commit. The
+    // commit pushes inside the lease on purpose: a push from a writer that has
+    // released it would race the next writer's commit on the same branch (the
+    // conflicting-commit hazard the lease exists for), and the sync write path
+    // (`withWriteTargetMutation`) draws the same boundary. Indexing is a
+    // regenerable cache and runs after release.
+    const written = await withAssetMutationLease("markdown-write", async () => {
+        // Pre-flight: existence + force semantics. The helper itself overwrites
+        // unconditionally; the CLI surfaces a friendlier UsageError before any
+        // disk activity when --force is absent.
+        if (fs.existsSync(assetPath) && !options.force) {
+            throw new UsageError(`${options.type === "knowledge" ? "Knowledge" : "Memory"} "${normalizedName}" already exists. Re-run with --force to overwrite it.`, "RESOURCE_ALREADY_EXISTS");
         }
-        // A demotion failure (fs error, concurrent delete, malformed YAML the
-        // pre-check missed) must NOT abort the correction: the new asset is
-        // already on disk, and bailing out here would skip the boundary commit and
-        // the write-path indexing below — leaving the correction unindexed and,
-        // 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 {
-            const sameSource = path.resolve(item.stashRoot) === path.resolve(source.path);
-            writeSupersededEdge(item.filePath, durableRef);
-            if (sameSource) {
-                recordWriteTargetPath(source, item.filePath);
+        if (options.expectedContentHash !== undefined) {
+            let existing;
+            try {
+                existing = fs.readFileSync(assetPath);
+            }
+            catch (error) {
+                if (error.code !== "ENOENT")
+                    throw error;
+            }
+            if (!existing || createHash("sha256").update(existing).digest("hex") !== options.expectedContentHash) {
+                throw new UsageError("The document changed or was removed after it was loaded. Reload its source before saving.", "ASSET_CONTENT_CHANGED");
+            }
+            // Unchanged when the live bytes are the submission itself (an untouched
+            // document keeps its bytes, missing metadata included) or exactly what
+            // the writer would write for it (e.g. the submission only lacks the
+            // final line break the writer adds).
+            const unchanged = existing.equals(Buffer.from(options.content, "utf8")) ||
+                existing.equals(Buffer.from(normalizeAkmMarkdown(options.content, resolved.ref.type), "utf8"));
+            if (unchanged && !options.supersedes?.length) {
+                return { ref: resolved.displayRef, path: assetPath, stashDir: source.path, unchanged: true };
             }
         }
-        catch (error) {
-            const reason = `demotion failed: ${error instanceof Error ? error.message : String(error)}`;
-            warn(`Warning: superseded asset ${item.ref} was NOT demoted (${reason}). ` +
-                "The correction was written and cites it in xrefs; demote the old asset manually or re-run the correction with --force.");
-            superseded.push({ ref: item.ref, applied: false, reason });
-            continue;
+        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
+        // commitWriteTargetBoundary so a git target batches the correction and the
+        // demoted incumbent into the single boundary commit instead of leaving the
+        // metadata edit as dirty residue after it.
+        const superseded = [];
+        const demotedByRoot = new Map();
+        for (const item of options.supersedes ?? []) {
+            if (!item.writable) {
+                const reason = item.reason ?? "target is not writable";
+                warn(`Warning: superseded asset ${item.ref} was NOT demoted (${reason}). ` +
+                    "The correction was written and cites it in xrefs; demote the old asset where it is writable.");
+                superseded.push({ ref: item.ref, applied: false, reason });
+                continue;
+            }
+            // The demotion round-trips the old file's frontmatter through the YAML
+            // parser. A malformed block would silently fall back to the lossy lenient
+            // scanner and re-serializing that result destroys list/nested values —
+            // skip instead of rewriting, mirroring mergeXrefsIntoContent's
+            // abort-on-malformed policy (the correction itself still writes).
+            let oldFrontmatter = null;
+            try {
+                oldFrontmatter = parseFrontmatter(fs.readFileSync(item.filePath, "utf8")).frontmatter;
+            }
+            catch {
+                // Unreadable file — let writeSupersededEdge surface the real fs error.
+            }
+            if (oldFrontmatter?.trim() && !isParseableYamlMapping(oldFrontmatter)) {
+                const reason = "its existing frontmatter is not a parseable YAML mapping — rewriting it would drop the values the parser could not read";
+                warn(`Warning: superseded asset ${item.ref} was NOT demoted (${reason}). ` +
+                    "The correction was written and cites it in xrefs; fix the old asset's frontmatter and re-run the correction with --force.");
+                superseded.push({ ref: item.ref, applied: false, reason });
+                continue;
+            }
+            // A demotion failure (fs error, concurrent delete, malformed YAML the
+            // pre-check missed) must NOT abort the correction: the new asset is
+            // already on disk, and bailing out here would skip the boundary commit and
+            // the write-path indexing below — leaving the correction unindexed and,
+            // 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 {
+                const sameSource = path.resolve(item.stashRoot) === path.resolve(source.path);
+                writeSupersededEdge(item.filePath, durableRef);
+                if (sameSource) {
+                    recordWriteTargetPath(source, item.filePath);
+                }
+            }
+            catch (error) {
+                const reason = `demotion failed: ${error instanceof Error ? error.message : String(error)}`;
+                warn(`Warning: superseded asset ${item.ref} was NOT demoted (${reason}). ` +
+                    "The correction was written and cites it in xrefs; demote the old asset manually or re-run the correction with --force.");
+                superseded.push({ ref: item.ref, applied: false, reason });
+                continue;
+            }
+            superseded.push({ ref: item.ref, applied: true });
+            const files = demotedByRoot.get(item.stashRoot) ?? [];
+            files.push(item.filePath);
+            demotedByRoot.set(item.stashRoot, files);
         }
-        superseded.push({ ref: item.ref, applied: true });
-        const files = demotedByRoot.get(item.stashRoot) ?? [];
-        files.push(item.filePath);
-        demotedByRoot.set(item.stashRoot, files);
-    }
-    // 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(resolved.ref)}`);
+        // 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(resolved.ref)}`);
+        return { result, superseded, demotedByRoot };
+    });
+    if (written.unchanged)
+        return written;
+    const { result, superseded, demotedByRoot } = written;
     // 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

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

@@ -139,14 +139,13 @@ const updateCommand = defineJsonCommand({
             description: "Allow an update containing dangerous env keys (e.g. LD_PRELOAD, PATH). Use only after explicitly reviewing the staged bundle.",
             default: false,
         },
-        // F1/R-058: gates ONLY the rare branch where the resolved content
-        // directory moves and the previous `localRoot` is deleted — a normal
-        // refresh (the overwhelming majority of updates) deletes nothing and
-        // never consults this flag. Mirrors `remove`'s `-y/--yes`.
+        // Deprecated no-op, accepted through 0.10 so scripts that pass it do not
+        // fail with UNKNOWN_FLAG. Deleting the previous directory of a read-only
+        // install whose content moved no longer asks: it is a re-fetchable cache.
         yes: {
             type: "boolean",
             alias: "y",
-            description: "Skip the confirmation prompt when an update needs to delete a previous install directory (because the resolved content location moved). No effect on a normal refresh, which deletes nothing.",
+            description: "Deprecated, no effect: update no longer asks before deleting a moved read-only install directory. Accepted through 0.10 for existing scripts.",
             default: false,
         },
     },
@@ -157,7 +156,6 @@ const updateCommand = defineJsonCommand({
                 target: args.target,
                 all: args.all,
                 force: args.force,
-                yes: args.yes,
                 allowDangerousEnvKeys: args["allow-dangerous-env-keys"],
             });
         }

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

@@ -611,15 +611,13 @@ function managedInstallViewOfPlainNpm(config, npmSource) {
  * Sync a single registry-managed install and return the processed record:
  * fetch into staging, audit, publish, write its lock entry, reindex.
  *
- * `yes` gates ONLY the destructive branch below (deleting a previous
- * `localRoot` whose content moved) — it has no effect on the sync itself. A
- * normal refresh that resolves the SAME content directory (the overwhelming
- * majority of updates) never reaches that branch, so it never prompts and
- * never requires `--yes` (F1/R-058: `update` must stay usable bare in
- * scripts; only the branch that can `rm -rf` needs a gate, not the whole
- * command).
+ * Read-only installs are keyed by resolved revision, so every upstream change
+ * resolves a new content directory, and the previous one is deleted once the
+ * new one is published. That directory is a re-fetchable cache: local and
+ * writable installs never take this path, and a directory another bundle or
+ * lock entry still references is kept. So deleting it never asks for confirmation.
  */
-async function updateManagedInstall(managed, force, yes, stashDir, allowDangerousEnvKeys) {
+async function updateManagedInstall(managed, force, stashDir, allowDangerousEnvKeys) {
     const { synced, staged } = await stageManagedUpdate(managed, force);
     try {
         await auditStagedUpdate(staged.auditRoot, managed.ref, allowDangerousEnvKeys);
@@ -642,12 +640,6 @@ async function updateManagedInstall(managed, force, yes, stashDir, allowDangerou
             path.resolve(managed.localRoot) !== path.resolve(synced.contentDir) &&
             managed.source !== "local" &&
             !managed.writable;
-        if (movedRoot) {
-            const { confirmDestructive } = await import("../../cli/confirm.js");
-            const confirmed = await confirmDestructive(`Update resolved a new content directory for "${managed.installId}" (${synced.contentDir}) and would delete the previous install directory at ${managed.localRoot}. This cannot be undone.`, { yes });
-            if (!confirmed)
-                throw new UsageError(`Update cancelled for "${managed.installId}"; no configuration was changed.`);
-        }
         const index = await publishAndIndex(stashDir, async () => {
             staged.publish();
             await upsertLockEntry({
@@ -724,7 +716,6 @@ export async function akmUpdate(input) {
     const target = input?.target?.trim();
     const all = input?.all === true;
     const force = input?.force === true;
-    const yes = input?.yes === true;
     const allowDangerousEnvKeys = input?.allowDangerousEnvKeys === true;
     const config = loadConfig();
     const managedInstalls = listManagedInstalls(config);
@@ -732,7 +723,7 @@ export async function akmUpdate(input) {
         // Registry-managed install (lock-backed) — re-download from its locator.
         const managed = resolveManagedTarget(config, target);
         if (managed) {
-            const updated = await updateManagedInstall(managed, force, yes, stashDir, allowDangerousEnvKeys);
+            const updated = await updateManagedInstall(managed, force, stashDir, allowDangerousEnvKeys);
             return buildUpdateResponse(stashDir, target, all, [updated.item], { index: updated.index });
         }
         // Plain git / website source (bundles without a lock) — provider re-sync.
@@ -789,7 +780,7 @@ export async function akmUpdate(input) {
             return false;
         });
         if (npmMatch) {
-            const updated = await updateManagedInstall(managedInstallViewOfPlainNpm(config, npmMatch), force, yes, stashDir, allowDangerousEnvKeys);
+            const updated = await updateManagedInstall(managedInstallViewOfPlainNpm(config, npmMatch), force, stashDir, allowDangerousEnvKeys);
             return buildUpdateResponse(stashDir, target, all, [updated.item], { index: updated.index });
         }
         const filesystemMatch = stashes.find((source) => {
@@ -812,7 +803,7 @@ export async function akmUpdate(input) {
     let latestIndex;
     for (const managed of selected) {
         try {
-            const updated = await updateManagedInstall(managed, force, yes, stashDir, allowDangerousEnvKeys);
+            const updated = await updateManagedInstall(managed, force, stashDir, allowDangerousEnvKeys);
             processed.push(updated.item);
             latestIndex = updated.index;
         }
@@ -842,7 +833,7 @@ export async function akmUpdate(input) {
                     latestIndex = updated.index;
                 }
                 else if (plain.type === "npm") {
-                    const updated = await updateManagedInstall(managedInstallViewOfPlainNpm(config, plain), force, yes, stashDir, allowDangerousEnvKeys);
+                    const updated = await updateManagedInstall(managedInstallViewOfPlainNpm(config, plain), force, stashDir, allowDangerousEnvKeys);
                     processed.push(updated.item);
                     latestIndex = updated.index;
                 }

package/dist/commands/ui/api.js

@@ -2,8 +2,8 @@
 // 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/.
 /**
- * The read-only JSON API behind `akm ui`. (The three proposal writes live in
- * `proposal-actions.ts`; nothing in this file writes.) Every handler calls the function the
+ * The read-only JSON API behind `akm ui`. Explicit writes live in
+ * `proposal-actions.ts` and `workspace-actions.ts`; nothing in this file writes. Every handler calls the function the
  * matching CLI command renders (`akmHealth`, `akmMetrics`, `akmSearch`,
  * `akmShowUnified`, the proposal repository, ...), so the UI and the CLI never
  * disagree and there is no second data layer. Documented in
@@ -14,8 +14,11 @@
  * `readOnly` (no usage events, no index build), and git is only queried.
  */
 import fs from "node:fs";
+import path from "node:path";
 import { parsePositiveIntFlag } from "../../cli/parse-args.js";
 import { parseBundleRef } from "../../core/asset/asset-ref.js";
+import { parseMarkdownToc, uniqueHeadingSlugs } from "../../core/asset/markdown.js";
+import { markdownLinkTargets } from "../../core/asset/markdown-link-targets.js";
 import { typeNameFromConceptId } from "../../core/asset/resolve-ref.js";
 import { resolveStashDir } from "../../core/common.js";
 import { getConfigValueSource, loadConfig } from "../../core/config/config.js";
@@ -24,6 +27,7 @@ import { getConfigPath, getDataDir, getDbPath } from "../../core/paths.js";
 import { getStateDbPath, listPendingStateMigrations } from "../../core/state-db.js";
 import { DURATION_UNITS, parseDuration } from "../../core/time.js";
 import { resolveWriteTarget } from "../../core/write-source.js";
+import { findSourceForPath, resolveSourceEntries } from "../../indexer/search/search-source.js";
 import { openDatabase } from "../../storage/database.js";
 import { listRecentImproveRuns } from "../../storage/repositories/improve-runs-repository.js";
 import { closeDatabase, openReadonlyExistingDatabase } from "../../storage/repositories/index-connection.js";
@@ -40,11 +44,12 @@ import { akmMetrics } from "../metrics/metrics-cli.js";
 import { isRetireProposal, proposalWaitingSince } from "../proposal/proposal-types.js";
 import { diffLoadedProposal, resolveProposalIdIn } from "../proposal/repository.js";
 import { validateProposal } from "../proposal/validators/proposals.js";
-import { akmSearch } from "../read/search.js";
+import { akmSearch, normalizeScopeFilters, parseBeliefFilterMode } from "../read/search.js";
 import { akmShowUnified } from "../read/show.js";
 import { assembleInfo } from "../sources/info.js";
 import { akmListSources } from "../sources/installed-stashes.js";
-import { readBundleGitStatus, readRecentCommits } from "./git-read.js";
+import { readDocumentSource } from "./document-source.js";
+import { readBundleGitStatus, readFileRevision, readRecentCommits } from "./git-read.js";
 import { isSecretEnvName, redactForUi } from "./redact.js";
 const DEFAULT_LIST_LIMIT = 50;
 const MAX_LIST_LIMIT = 200;
@@ -236,6 +241,13 @@ async function bundles() {
         source: source.source,
         path: source.path ?? null,
         writable: source.writable,
+        enabled: config.bundles?.[source.name]?.enabled !== false,
+        writableSetting: config.bundles?.[source.name]?.writable,
+        components: source.components.map((component) => ({
+            ...component,
+            configured: !!config.bundles?.[source.name]?.components?.[component.name],
+        })),
+        settingsSource: configSource(["bundles", source.name]),
         version: source.version ?? null,
         exists: source.status.exists,
         itemCount: source.itemCount,
@@ -475,6 +487,8 @@ async function search(query) {
         limit: limitParam(query, 20),
         // `--from <name>` narrows to one configured bundle; absent means every local bundle, as `akm search` does.
         source: bundle ?? "local",
+        belief: parseBeliefFilterMode(query.get("belief") || "current"),
+        filters: normalizeScopeFilters(Object.fromEntries(["user", "agent", "run", "channel"].map((key) => [key, query.get(`scope_${key}`) ?? ""]))),
         readOnly: true,
     });
 }
@@ -528,7 +542,81 @@ async function asset(query) {
     }
     const shown = await akmShowUnified({ ref, readOnly: true });
     const durableRef = shown.path ? durableRefForPath(shown.path) : null;
-    return { redacted: false, durableRef, asset: shown, feedback: feedbackFor(durableRef) };
+    const content = shown.content ?? "";
+    const headings = parseMarkdownToc(content).headings;
+    const slugs = uniqueHeadingSlugs(headings);
+    const links = {};
+    if (shown.path && durableRef) {
+        const owner = parseBundleRef(durableRef).bundle;
+        const db = openReadonlyExistingDatabase(getDbPath());
+        if (db) {
+            try {
+                for (const raw of markdownLinkTargets(content, false)) {
+                    if (/^(?:[a-z][a-z0-9+.-]*:|\/\/|#)/i.test(raw))
+                        continue;
+                    const [file, fragment] = raw.split("#", 2);
+                    if (!file?.toLowerCase().endsWith(".md") || file.startsWith("/"))
+                        continue;
+                    let decoded;
+                    try {
+                        decoded = decodeURIComponent(file);
+                    }
+                    catch {
+                        continue;
+                    }
+                    const id = getEntryIdByFilePath(db, path.resolve(path.dirname(shown.path), decoded));
+                    const target = id === undefined ? undefined : getItemRefById(db, id);
+                    if (target && parseBundleRef(target).bundle === owner)
+                        links[raw] = target + (fragment ? `#${fragment}` : "");
+                }
+            }
+            finally {
+                closeDatabase(db);
+            }
+        }
+    }
+    return {
+        redacted: false,
+        durableRef,
+        bundle: durableRef ? parseBundleRef(durableRef).bundle : null,
+        asset: shown,
+        feedback: feedbackFor(durableRef),
+        feedbackRequireReason: loadConfig().feedback?.requireReason !== false,
+        links,
+        headings: headings.map((heading, i) => ({ ...heading, slug: slugs[i] })),
+    };
+}
+async function assetHistory(query) {
+    const selected = await asset(query);
+    if (selected.redacted || !selected.asset?.path)
+        return { available: false, commits: [] };
+    const source = findSourceForPath(selected.asset.path, resolveSourceEntries(undefined, loadConfig()));
+    if (!source)
+        return { available: false, commits: [] };
+    const file = path.relative(source.path, selected.asset.path).split(path.sep).join("/");
+    if (file.startsWith("../") || path.isAbsolute(file))
+        throw new UsageError("Asset path is outside its bundle.");
+    const commits = await readRecentCommits(source.path, limitParam(query, 30), file);
+    const revision = query.get("revision");
+    if (revision && !commits?.some((commit) => commit.sha === revision))
+        throw new UsageError("Choose a revision from this asset's history.");
+    const diff = revision ? await readFileRevision(source.path, file, revision) : null;
+    const before = capSide(diff?.before ?? null);
+    const after = capSide(diff?.after ?? null);
+    return {
+        available: commits !== null,
+        commits: commits ?? [],
+        ...(diff
+            ? {
+                diff: {
+                    before: before.text,
+                    after: after.text,
+                    unified: diff.unified.slice(0, DIFF_SIDE_MAX_CHARS),
+                    truncated: before.truncated || after.truncated || diff.unified.length > DIFF_SIDE_MAX_CHARS,
+                },
+            }
+            : {}),
+    };
 }
 // ── Routing ──────────────────────────────────────────────────────────────────
 const ROUTES = {
@@ -540,6 +628,8 @@ const ROUTES = {
     "/api/changes": changes,
     "/api/search": search,
     "/api/asset": asset,
+    "/api/asset/history": assetHistory,
+    "/api/asset/source": (query) => readDocumentSource(query.get("ref") ?? ""),
 };
 const PROPOSAL_ROUTE = /^\/api\/proposals\/([^/]+)$/;
 /** What {@link handleApiRequest} returns for a path that is not an API route. */

package/dist/commands/ui/document-source.js

@@ -0,0 +1,51 @@
+// 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 { createHash } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { assetPathForName, stashDirFor } from "../../core/asset/asset-placement.js";
+import { parseRefInput } from "../../core/asset/resolve-ref.js";
+import { loadConfig } from "../../core/config/config.js";
+import { UsageError } from "../../core/errors.js";
+import { resolveBundleWriteTarget } from "../../core/mutation-target.js";
+import { assertAkmAssetWrite } from "../../core/write-source.js";
+import { closeDatabase, openReadonlyExistingDatabase } from "../../storage/repositories/index-connection.js";
+import { getEntryIdByFilePath, getItemRefById } from "../../storage/repositories/index-entries-repository.js";
+import { akmShowUnified } from "../read/show.js";
+import { redactUrlsInText } from "./redact.js";
+/** Authoring reads are limited to indexed, writable AKM knowledge/memory files, never arbitrary paths. */
+export async function readDocumentSource(ref) {
+    const parsed = parseRefInput(ref);
+    if (parsed.type !== "knowledge" && parsed.type !== "memory")
+        throw new UsageError("Only knowledge and memory support source editing in this UI.");
+    const shown = await akmShowUnified({ ref, readOnly: true });
+    if (!shown.path)
+        throw new UsageError("The document has no local source file.");
+    const db = openReadonlyExistingDatabase();
+    let canonical;
+    if (db) {
+        try {
+            const id = getEntryIdByFilePath(db, shown.path);
+            canonical = id === undefined ? undefined : (getItemRefById(db, id) ?? undefined);
+        }
+        finally {
+            closeDatabase(db);
+        }
+    }
+    if (!canonical)
+        throw new UsageError("Only indexed documents can be edited.");
+    const identity = parseRefInput(canonical);
+    const target = resolveBundleWriteTarget(loadConfig(), identity.origin);
+    assertAkmAssetWrite(target.source);
+    const expectedPath = assetPathForName(parsed.type, path.join(target.source.path, stashDirFor(parsed.type)), identity.name);
+    if (path.resolve(expectedPath) !== path.resolve(shown.path))
+        throw new UsageError("The indexed source no longer matches the writable document target. Refresh the index before editing.");
+    const raw = fs.readFileSync(shown.path);
+    const content = raw.toString("utf8");
+    if (!Buffer.from(content, "utf8").equals(raw))
+        throw new UsageError("This source is not valid UTF-8; edit it outside the UI.");
+    if (redactUrlsInText(content) !== content)
+        throw new UsageError("This document contains URL credentials hidden by the UI. Edit it outside the UI to preserve those values.");
+    return { ref: canonical, type: parsed.type, content, revision: createHash("sha256").update(raw).digest("hex") };
+}

package/dist/commands/ui/git-read.js

@@ -73,10 +73,17 @@ export function classifyCommitOrigin(subject) {
     return "other";
 }
 /** The `limit` most recent commits of the repository at `repoDir`, newest first; `null` when it is not a git root. */
-export async function readRecentCommits(repoDir, limit) {
+export async function readRecentCommits(repoDir, limit, file) {
     if (!isGitRoot(repoDir))
         return null;
-    const out = await git(repoDir, ["log", "-n", String(limit), "--name-only", "--format=%x1e%H%x1f%cI%x1f%an%x1f%s"]);
+    const out = await git(repoDir, [
+        "log",
+        "-n",
+        String(limit),
+        "--name-only",
+        "--format=%x1e%H%x1f%cI%x1f%an%x1f%s",
+        ...(file ? ["--", file] : []),
+    ]);
     if (out === null)
         return [];
     const commits = [];
@@ -99,3 +106,12 @@ export async function readRecentCommits(repoDir, limit) {
     }
     return commits;
 }
+/** Caller supplies an indexed asset path inside this bundle and a commit ID it took from {@link readRecentCommits}. */
+export async function readFileRevision(repoDir, file, sha) {
+    const after = await git(repoDir, ["show", `${sha}:${file}`]);
+    if (after === null)
+        return null;
+    const before = await git(repoDir, ["show", `${sha}^:${file}`]);
+    const unified = await git(repoDir, ["show", "--no-ext-diff", "--no-textconv", "--format=", sha, "--", file]);
+    return { before, after, unified: unified ?? "" };
+}

package/dist/commands/ui/proposal-actions.js

@@ -2,14 +2,14 @@
 // 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/.
 /**
- * The only writes `akm ui` makes: accept and reject a proposal, and accept
+ * Proposal writes `akm ui` makes: accept and reject a proposal, and accept
  * several at once. Each handler calls the function `akm proposal accept` /
  * `reject` calls, with the arguments the CLI passes, so a UI decision is
  * recorded exactly like a CLI one (same state.db rows, events and commit).
  *
  * The server decides whether a request may reach this module (token header,
  * Origin, content type, body size); see `server.ts`. Everything else in the UI
- * stays read-only and lives in `api.ts`.
+ * is either a read in `api.ts` or an explicit action in `workspace-actions.ts`.
  */
 import { AkmError, TransientError, UsageError } from "../../core/errors.js";
 import { acquireAssetMutationLease } from "../../indexer/index-writer-lock.js";
@@ -56,6 +56,8 @@ export function classifyProposalError(error) {
     const message = error instanceof Error ? error.message : String(error);
     const byMessage = codeForMessage(message);
     if (error instanceof AkmError) {
+        if (error.code === "ASSET_CONTENT_CHANGED")
+            return { status: 409, code: error.code, message };
         if (byMessage === "PROPOSAL_STALE" || byMessage === "PROPOSAL_NOT_PENDING") {
             return { status: 409, code: byMessage, message };
         }
@@ -112,7 +114,7 @@ function batchIds(body) {
  * reject functions would wait up to ten minutes for it, which in a browser is a
  * hung button; the probe turns a held lease into an immediate, retryable 409.
  */
-async function assertWriteLeaseFree(purpose) {
+export async function assertWriteLeaseFree(purpose) {
     const lease = await acquireAssetMutationLease({ mode: "try", purpose });
     if (!lease) {
         throw new TransientError("Another akm process or request is writing to the bundle right now. Try again in a moment.", "ASSET_MUTATION_LEASE_HELD");