akm-cli 0.10.261006-beta → 0.10.261007-beta

package/CHANGELOG.md

@@ -6,6 +6,33 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.10.261007] - 2026-10-20
+
+### Added
+
+- **`akm proposal new --bundle <name>` queues a new-asset proposal for another configured bundle.** The bundle must be
+  configured and writable; an unknown, disabled or read-only one is refused with the same error `akm remember --bundle`
+  gives. The generation prompt draws its convention facts from that bundle, and the proposal records it as its target,
+  so `akm proposal accept` writes there. Without the flag the proposal goes to the working bundle, as before.
+
+### Fixed
+
+- **`akm ui` searches and asset views never open the index for write.** In read-only mode, `akm search` and
+  `akm show` still opened `index.db` read-write; closing that connection can checkpoint the WAL into the main file,
+  so browsing could change `index.db` even though nothing was written (seen as an intermittent CI failure). They now
+  use read-only connections.
+- **`akm clone` works on flat skill repos and website pages, and records where the clone came from.** A ref whose
+  concept id is not under a type directory (`my-repo//domain-name-brainstormer`, a page from a `bundle add <url>`
+  source) failed with `TypeError: paths[1] must be string`. The source is now found through the bundle's adapter and
+  placed by what the file is: a skill into `skills/<name>/`, other markdown into `knowledge/<name>.md`, and an asset
+  that cannot be placed fails with a usage error that points to `akm import`. Cloned markdown gains the origin ref in
+  its `sources:` frontmatter. A `knowledge/<name>` ref given without `.md` now clones to `<name>.md`; it used to
+  be written with no extension and left out of the index.
+- **`akm ui`'s Overview no longer stalls while another process writes the index.** Its metrics resolved refs through
+  a disposable copy of `index.db`, which retried for several seconds and printed a "could not take a non-mutating
+  snapshot" warning whenever the index was being written. The UI now reads `index.db` directly in read-only mode;
+  `akm metrics` from the CLI is unchanged.
+
 ## [0.10.261006] - 2026-10-16
 
 ### Added

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

@@ -53,7 +53,7 @@ export function metricsIncludeRows(mode) {
  * `bundle//conceptId`; resolving here keeps one asset from showing as two rows.
  * A ref that does not resolve (registry results, removed assets) is kept as is.
  */
-async function durableSelects(selects) {
+async function durableSelects(selects, indexSnapshot = true) {
     const unqualified = [];
     for (const ref of new Set(selects.map((select) => select.ref))) {
         try {
@@ -65,7 +65,7 @@ async function durableSelects(selects) {
             // Not a local bundle ref: keep the ref as recorded.
         }
     }
-    const entries = await lookupBundleRefsReadonly(unqualified.map(({ parsed }) => parsed));
+    const entries = await lookupBundleRefsReadonly(unqualified.map(({ parsed }) => parsed), { isolatedSnapshot: indexSnapshot });
     const resolved = new Map(unqualified.map(({ ref }, i) => [ref, entries[i]?.itemRef ?? ref]));
     return selects.map((select) => ({ ts: select.ts, ref: resolved.get(select.ref) ?? select.ref }));
 }
@@ -190,7 +190,7 @@ export async function akmMetrics(options = {}) {
     finally {
         stateDb.close();
     }
-    input.selects = await durableSelects(selects);
+    input.selects = await durableSelects(selects, options.indexSnapshot ?? true);
     return buildMetricsResult(input);
 }
 export const metricsCommand = defineJsonCommand({

package/dist/commands/proposal/propose-cli.js

@@ -47,6 +47,10 @@ export const proposeCommand = defineCommand({
         },
         task: { type: "string", description: "Task description for the agent (what should the asset do?)" },
         file: { type: "string", description: "Read the task or prompt text from a UTF-8 file" },
+        bundle: {
+            type: "string",
+            description: "Configured writable bundle to queue the proposal for and draw convention facts from (default: the working bundle)",
+        },
         engine: { type: "string", description: "Engine to use (defaults to defaults.engine)" },
         "timeout-ms": { type: "string", description: "Override the engine timeout in milliseconds" },
     },
@@ -73,6 +77,7 @@ export const proposeCommand = defineCommand({
                 name: proposedName,
                 task: taskText,
                 engine: getStringArg(args, "engine"),
+                bundle: getStringArg(args, "bundle"),
                 ...(timeoutMs !== undefined ? { timeoutMs } : {}),
             });
             output("proposal-new", result);

package/dist/commands/proposal/propose.js

@@ -23,6 +23,7 @@ import { redactSensitiveText } from "../../core/redaction.js";
 import { resolveStandardsContext } from "../../core/standards/resolve-standards-context.js";
 import { runStructured } from "../../core/structured.js";
 import { warn } from "../../core/warn.js";
+import { resolveWriteTarget } from "../../core/write-source.js";
 import { deriveEntryProvenance } from "../../indexer/installations.js";
 import { fallbackAnnouncement } from "../../integrations/agent/engine-fallback.js";
 import { buildExecution, resolveExecution } from "../../integrations/agent/execution.js";
@@ -144,10 +145,13 @@ export async function akmPropose(options) {
     if (!stashDirFor(options.type)) {
         throw new UsageError(`propose: unknown asset type "${options.type}". Known types: ${[...placementTypes()].sort().join(", ")}.`, "INVALID_FLAG_VALUE");
     }
-    const stash = options.stashDir ?? resolveStashDir();
     // 1. Resolve the write target. Engine/model/inference resolution happens
-    // exactly once below through the shared execution cascade.
+    // exactly once below through the shared execution cascade. `--bundle` names a
+    // configured, writable bundle (same resolver and errors as `akm remember
+    // --bundle`); its root becomes the stash the proposal is queued for and the
+    // prompt's standards are read from.
     const config = options.agentConfig ?? (await import("../../core/config/config.js")).loadConfig();
+    const stash = options.stashDir ?? (options.bundle ? resolveWriteTarget(config, options.bundle).source.path : resolveStashDir());
     const target = resolveProposalQueueTarget(stash, config);
     // 2. Build terminal user content.
     // Standards "rulebook" for this target — wiki schema (wiki page) or stash

package/dist/commands/read/show.js

@@ -33,7 +33,7 @@ import { appendEvent } from "../../core/events.js";
 import { SCRIPT_EXTENSIONS } from "../../core/recognition-util.js";
 import { presentationFor } from "../../core/type-presentation.js";
 import { warn, warnOnce } from "../../core/warn.js";
-import { lookupBundleRef, lookupBundleRefWithResolution } from "../../indexer/indexer.js";
+import { lookupBundleRef, lookupBundleRefWithResolution, lookupBundleRefWithResolutionReadonly, } from "../../indexer/indexer.js";
 import { projectMarkdownFragmentContent } from "../../indexer/passes/metadata.js";
 import { ensurePrimaryIndexForRead, resolveReadSources } from "../../indexer/read-preflight.js";
 import { buildEditHint, findSourceForPath, isEditable, resolveSourceEntries, } from "../../indexer/search/search-source.js";
@@ -213,7 +213,9 @@ export async function showLocal(input) {
     const allSources = resolveSourceEntries(input.stashDir);
     const searchSources = resolveSourcesForOrigin(parsed.bundle, allSources);
     const allSourceDirs = searchSources.map((s) => s.path);
-    const resolution = await lookupBundleRefWithResolution(parsed);
+    const resolution = input.readOnly
+        ? await lookupBundleRefWithResolutionReadonly(parsed)
+        : await lookupBundleRefWithResolution(parsed);
     if (resolution.indexError !== undefined)
         throw resolution.indexError;
     const indexedEntry = resolution.entry;
@@ -262,7 +264,9 @@ export async function showLocal(input) {
     // Only resolve the indexed-safe revision when the selector itself is opaque,
     // or when the caller explicitly opts into indexed-safe contextual output.
     const indexedFragment = parsed.fragment && (opaqueFragmentSelector || input.contextMode === "lead")
-        ? withIndexDb((db) => getIndexedMarkdownFragment(db, indexedEntry.itemRef, parsed.fragment))
+        ? withIndexDb((db) => getIndexedMarkdownFragment(db, indexedEntry.itemRef, parsed.fragment), {
+            readOnly: input.readOnly === true,
+        })
         : undefined;
     const indexedFragmentContent = opaqueFragmentSelector ? indexedFragment?.content : undefined;
     const indexedRenderer = rendererForIndexedEntry(indexedEntry, fileCtx);
@@ -366,7 +370,7 @@ export async function showLocal(input) {
         origin: source?.registryId ?? null,
         editable,
         ...(!editable ? { editHint: buildEditHint(canonicalRef) } : {}),
-        ...showLinks(indexedEntry.itemRef, displayDefaultBundle),
+        ...showLinks(indexedEntry.itemRef, displayDefaultBundle, input.readOnly === true),
     };
     const activeRun = input.readOnly ? null : await getActiveWorkflowRun(getCurrentWorkflowScopeKey());
     if (activeRun) {
@@ -387,10 +391,10 @@ const LINKS_PER_KIND = 10;
  * authored order, incoming by ref, and unresolved tokens as authored. Empty
  * parts are omitted, and the field when nothing links either way.
  */
-function showLinks(itemRef, defaultBundle) {
+function showLinks(itemRef, defaultBundle, readOnly = false) {
     let rows;
     try {
-        rows = withIndexDb((db) => readEntryLinks(db, itemRef));
+        rows = withIndexDb((db) => readEntryLinks(db, itemRef), { readOnly });
     }
     catch (err) {
         rethrowIfTestIsolationError(err);

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

@@ -4,9 +4,14 @@
 import { randomUUID } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
-import { stashDirFor } from "../../core/asset/asset-placement.js";
+import { isDeepStrictEqual } from "node:util";
+import { detectAdapterId } from "../../core/adapter/detect-adapter.js";
+import { adapterForId } from "../../core/adapter/registry.js";
+import { placementSpecFor, stashDirFor } from "../../core/asset/asset-placement.js";
 import { isBundleSlug } from "../../core/asset/asset-ref.js";
-import { displayRef, parseQualifiedRefInput } from "../../core/asset/resolve-ref.js";
+import { serializeFrontmatter } from "../../core/asset/asset-serialize.js";
+import { parseFrontmatter, replaceFrontmatterBlocks } from "../../core/asset/frontmatter.js";
+import { conceptIdFromTypeName, displayRef, parseQualifiedRefInput } from "../../core/asset/resolve-ref.js";
 import { isWithin } from "../../core/common.js";
 import { loadConfig } from "../../core/config/config.js";
 import { ConfigError, NotFoundError, UsageError } from "../../core/errors.js";
@@ -15,10 +20,13 @@ import { warn } from "../../core/warn.js";
 import { commitWriteTargetBoundary, prepareWriteTargetForMutation, resolveWriteTarget, } from "../../core/write-source.js";
 import { withAssetMutationLease } from "../../indexer/index-writer-lock.js";
 import { indexWrittenAssets } from "../../indexer/index-written-assets.js";
+import { resolveAdapterConceptOwner } from "../../indexer/lookup/adapter-concept-owner.js";
 import { findSourceForPath, resolveSourceEntries } from "../../indexer/search/search-source.js";
+import { buildFileContext } from "../../indexer/walk/file-context.js";
 import { isRemoteOrigin, resolveSourcesForLocator, resolveSourcesForOrigin } from "../../registry/origin-resolve.js";
 import { syncFromRef } from "../../sources/providers/sync-from-ref.js";
 import { resolveAssetPath } from "../../sources/resolve.js";
+import { inferAssetName } from "../read/knowledge.js";
 function destinationRef(config, target, type, name) {
     if (!config || !target)
         return undefined;
@@ -77,11 +85,25 @@ export async function akmClone(options) {
             cacheDir: installResult.cacheDir,
         };
     }
+    // A ref whose conceptId is not under a known type directory (a flat skill
+    // repo, a website or wiki page) is opaque: its source and type come from the
+    // adapter that owns the concept, not from the shape of the ref.
+    const known = placementSpecFor(parsed.type) !== undefined;
     let sourcePath;
+    let opaqueType;
     let lastError;
     for (const source of searchSources) {
         try {
-            sourcePath = await resolveAssetPath(source.path, parsed.type, parsed.name);
+            if (known) {
+                sourcePath = await resolveAssetPath(source.path, parsed.type, parsed.name);
+            }
+            else {
+                const owned = resolveOpaqueAsset(source, parsed.name);
+                if (!owned)
+                    throw new NotFoundError(`Source asset not found for ref: ${options.sourceRef}`, "ASSET_NOT_FOUND");
+                sourcePath = owned.path;
+                opaqueType = owned.type;
+            }
             break;
         }
         catch (err) {
@@ -95,8 +117,20 @@ export async function akmClone(options) {
         throw lastError ?? new NotFoundError(`Source asset not found for ref: ${options.sourceRef}`, "ASSET_NOT_FOUND");
     }
     const sourceSource = findSourceForPath(sourcePath, allSources);
-    const destName = options.newName ?? parsed.name;
-    const typeDir = stashDirFor(parsed.type);
+    // Where the clone lands: a known-type ref keeps its type and name; an opaque
+    // one is placed by what the source file is.
+    const sourceExt = path.extname(sourcePath);
+    const cloneType = known ? parsed.type : placementTypeForOpaque(options.sourceRef, sourcePath, opaqueType);
+    const defaultName = known ? parsed.name : slugName(parsed.name);
+    const destName = options.newName ?? defaultName;
+    const typeDir = stashDirFor(cloneType);
+    // A ref's name often omits its extension (`knowledge/<name>` names `<name>.md`), and an opaque one is a slug:
+    // either way the copy keeps the source file's extension, or it would be written as a file the index ignores.
+    const destFileName = path.extname(destName) ? destName : destName + sourceExt;
+    const isSkill = cloneType === "skill";
+    // A concept id is the path without its markdown extension.
+    const originConceptId = (known ? conceptIdFromTypeName(parsed.type, parsed.name) : parsed.name).replace(/\.md$/i, "");
+    const originRef = sourceSource?.registryId ? `${sourceSource.registryId}//${originConceptId}` : undefined;
     // Validate destName to prevent path traversal (parsed.name is already
     // validated by the ref parser, but newName comes directly from user input).
     // Run whenever newName is provided, including empty string.
@@ -128,7 +162,7 @@ export async function akmClone(options) {
             ? `in target "${writeTarget.selector}"`
             : "in working stash";
     // Guard against self-clone
-    if (parsed.type === "skill") {
+    if (isSkill) {
         const sourceSkillDir = path.resolve(path.dirname(sourcePath));
         const destSkillDir = path.resolve(path.join(destRoot, typeDir, destName));
         if (sourceSkillDir === destSkillDir) {
@@ -137,8 +171,7 @@ export async function akmClone(options) {
     }
     else {
         const resolvedSource = path.resolve(sourcePath);
-        const sourceExt = path.extname(sourcePath);
-        const effectiveDestName = !path.extname(destName) && sourceExt ? destName + sourceExt : destName;
+        const effectiveDestName = !path.extname(destFileName) && sourceExt ? destFileName + sourceExt : destFileName;
         const resolvedDest = path.resolve(path.join(destRoot, typeDir, effectiveDestName));
         if (resolvedSource === resolvedDest) {
             throw new Error(`Source and destination are the same path. Use --name to provide a new name for the clone.`);
@@ -148,7 +181,7 @@ export async function akmClone(options) {
         let destPath;
         let overwritten;
         let operationPaths;
-        if (parsed.type === "skill") {
+        if (isSkill) {
             const sourceSkillDir = path.dirname(sourcePath);
             const destSkillDir = path.join(destRoot, typeDir, destName);
             assertNoDestinationSymlinkParent(destRoot, destSkillDir);
@@ -163,6 +196,7 @@ export async function akmClone(options) {
             const stagingDir = `${destSkillDir}.tmp-${randomUUID()}`;
             try {
                 fs.cpSync(sourceSkillDir, stagingDir, { recursive: true, errorOnExist: true, force: false });
+                stampCloneOrigin(path.join(stagingDir, "SKILL.md"), originRef);
                 if (overwritten)
                     fs.rmSync(destSkillDir, { recursive: true, force: true });
                 fs.renameSync(stagingDir, destSkillDir);
@@ -175,7 +209,7 @@ export async function akmClone(options) {
             operationPaths = [...new Set([...replacedPaths, ...listTreeFiles(destSkillDir)])];
         }
         else {
-            destPath = path.join(destRoot, typeDir, destName);
+            destPath = path.join(destRoot, typeDir, destFileName);
             assertNoDestinationSymlinkParent(destRoot, destPath);
             const existing = lstatIfExists(destPath);
             overwritten = existing !== undefined;
@@ -186,6 +220,8 @@ export async function akmClone(options) {
             const stagingPath = `${destPath}.tmp-${randomUUID()}`;
             try {
                 fs.copyFileSync(sourcePath, stagingPath, fs.constants.COPYFILE_EXCL);
+                if (cloneType !== "workflow" && sourceExt.toLowerCase() === ".md")
+                    stampCloneOrigin(stagingPath, originRef);
                 if (overwritten)
                     fs.rmSync(destPath, { recursive: true, force: true });
                 fs.renameSync(stagingPath, destPath);
@@ -196,7 +232,7 @@ export async function akmClone(options) {
             }
             operationPaths = [destPath];
         }
-        const ref = destinationRef(config, writeTarget, parsed.type, destName);
+        const ref = destinationRef(config, writeTarget, cloneType, destName);
         if (writeTarget) {
             const commitRoot = writeTarget.source.repoPath ?? writeTarget.source.path;
             const commitPaths = operationPaths.map((filePath) => path.relative(commitRoot, filePath).replaceAll(path.sep, "/"));
@@ -213,6 +249,82 @@ export async function akmClone(options) {
         };
     });
 }
+/**
+ * Find an opaque concept (one whose id is not under a known type directory) in
+ * a source through the adapter that owns it, and name the type that adapter
+ * recognizes the file as. The same ownership + recognition `akm show` and the
+ * index use, so a clone sees exactly the file the index holds for the ref.
+ */
+function resolveOpaqueAsset(source, conceptId) {
+    const adapterId = source.adapterId ?? detectAdapterId(source.path);
+    const owner = resolveAdapterConceptOwner(source.path, adapterId, conceptId, { mode: "read" });
+    if (!owner)
+        return undefined;
+    let type;
+    try {
+        const component = { id: adapterId, adapter: adapterId, root: source.path, writable: false };
+        type = adapterForId(adapterId)?.recognize(component, buildFileContext(source.path, owner.path))?.type;
+    }
+    catch {
+        // An adapter that cannot recognize the file leaves its type unknown.
+    }
+    return { path: owner.realPath, type };
+}
+/**
+ * Where an opaque asset is cloned: a skill (SKILL.md) as a directory under
+ * `skills/`, any other recognized placement type under its own directory, and
+ * markdown of an unknown type (a website or wiki page, a flat doc) as
+ * `knowledge/`. Anything else cannot be placed.
+ */
+function placementTypeForOpaque(sourceRef, sourcePath, indexedType) {
+    if (indexedType === "skill" && path.basename(sourcePath) === "SKILL.md")
+        return "skill";
+    if (indexedType !== undefined && indexedType !== "skill" && placementSpecFor(indexedType) !== undefined) {
+        return indexedType;
+    }
+    if (path.extname(sourcePath).toLowerCase() === ".md")
+        return "knowledge";
+    throw new UsageError(`cannot clone ${sourceRef}: its type${indexedType ? ` "${indexedType}"` : ""} has no place in a bundle and ` +
+        `${path.basename(sourcePath)} is not markdown; use \`akm import <path>\` or copy the file.`);
+}
+/** Clone name of an opaque asset: the last segment of its concept id, slugified like every other asset name. */
+function slugName(conceptId) {
+    const last = conceptId.split("/").pop() ?? conceptId;
+    const stem = last.replace(/\.[A-Za-z0-9]{1,5}$/, "");
+    return inferAssetName("", "clone", stem);
+}
+/**
+ * Record where a cloned markdown asset came from by merging the origin ref into
+ * its `sources:` frontmatter. `sources:` is free-form provenance that `akm lint` does
+ * not resolve, unlike `xrefs:`: the origin bundle is often not installed where the
+ * clone is read (a shared domain bundle), and an `xrefs:` entry would be reported as
+ * a missing ref there. Only the `sources` block is rewritten; every other
+ * byte stays as written. A file whose frontmatter cannot be edited that way
+ * (and still parse back to exactly the intended mapping) is left untouched.
+ */
+function stampCloneOrigin(filePath, originRef) {
+    if (!originRef)
+        return;
+    const raw = fs.readFileSync(filePath, "utf8");
+    const parsed = parseFrontmatter(raw);
+    const existing = parsed.data.sources;
+    const prior = Array.isArray(existing) ? existing : typeof existing === "string" ? [existing] : [];
+    if (existing !== undefined && prior.length === 0)
+        return;
+    if (prior.includes(originRef))
+        return;
+    const sources = [...prior, originRef];
+    let next;
+    if (parsed.frontmatter === null) {
+        next = `---\n${serializeFrontmatter({ sources })}\n---\n${raw}`;
+    }
+    else {
+        next = replaceFrontmatterBlocks(raw, ["sources"], serializeFrontmatter({ sources }).split("\n"));
+        if (next === null || !isDeepStrictEqual(parseFrontmatter(next).data, { ...parsed.data, sources }))
+            return;
+    }
+    fs.writeFileSync(filePath, next);
+}
 function lstatIfExists(filePath) {
     try {
         return fs.lstatSync(filePath);

package/dist/commands/ui/api.js

@@ -212,7 +212,7 @@ async function overview(query) {
         }), null);
         return { ...base, ...(report ? { report } : {}) };
     });
-    const metrics = await section(errors, "metrics", () => akmMetrics({ since: query.get("metricsSince") || "30d" }));
+    const metrics = await section(errors, "metrics", () => akmMetrics({ since: query.get("metricsSince") || "30d", indexSnapshot: false }));
     const stateReads = await section(errors, "state", () => withReadonlyStateDb((db) => ({
         improveRuns: listRecentImproveRuns(db, IMPROVE_RUNS_SHOWN).map(summarizeImproveRun),
         usageByDay: usageByDay(db, Date.now()),

package/dist/core/asset/resolve-ref.js

@@ -232,13 +232,17 @@ function opaqueRefParts(conceptId, allowRoot = false) {
  *     that `resolveSourcesForOrigin` matches on `registryId`. The SHORT form (no
  *     bundle) leaves `origin` undefined = search-all-sources.
  *   - `#fragment` → rejected. No input boundary consumes an export fragment.
+ *
+ * `originGiven` — the caller already split a (non-slug) origin off the ref, so a
+ * single-segment conceptId (a flat skill repo's `domain-name-brainstormer`) is
+ * qualified and parses as opaque, exactly as it does behind a slug `bundle//`.
  */
-export function parseRefInput(raw) {
+export function parseRefInput(raw, originGiven = false) {
     const ref = parseBundleRef(raw);
     if (ref.fragment !== undefined) {
         throw new UsageError(`Export fragment "#${ref.fragment}" is not accepted here — drop it from "${raw.trim()}".`, "INVALID_FLAG_VALUE");
     }
-    const parts = typeNameFromConceptId(ref.conceptId) ?? opaqueRefParts(ref.conceptId, ref.bundle !== undefined);
+    const parts = typeNameFromConceptId(ref.conceptId) ?? opaqueRefParts(ref.conceptId, originGiven || ref.bundle !== undefined);
     if (parts === undefined) {
         throw new NotFoundError(`Unrecognized asset ref "${raw.trim()}": conceptId "${ref.conceptId}" has no known asset-type prefix.`, "ASSET_NOT_FOUND");
     }
@@ -265,7 +269,7 @@ export function parseQualifiedRefInput(raw) {
     if (boundary > 0) {
         const origin = trimmed.slice(0, boundary);
         if (!isBundleSlug(origin)) {
-            return { ...parseRefInput(trimmed.slice(boundary + 2)), origin };
+            return { ...parseRefInput(trimmed.slice(boundary + 2), true), origin };
         }
     }
     return parseRefInput(trimmed);

package/dist/indexer/indexer.js

@@ -1196,6 +1196,18 @@ borrowed = false) {
 export async function lookupBundleRefWithResolution(ref) {
     return lookupBundleRefWithResolutionUsing(ref, openExistingDatabase);
 }
+/**
+ * {@link lookupBundleRefWithResolution} on a plain read-only connection (`akm ui`): a read-write one can checkpoint
+ * the WAL into the main file when it closes, changing the file although nothing was written.
+ */
+export async function lookupBundleRefWithResolutionReadonly(ref) {
+    return lookupBundleRefWithResolutionUsing(ref, (dbPath) => {
+        const db = openReadonlyExistingDatabase(dbPath);
+        if (!db)
+            throw new Error(`Index database not found at ${dbPath}. Run 'akm index' to build it.`);
+        return db;
+    });
+}
 /** Resolve an adapter-owned `[bundle//]conceptId` without interpreting its path as an AKM type. */
 export async function lookupBundleRef(ref) {
     const resolution = await lookupBundleRefWithResolution(ref);
@@ -1223,12 +1235,12 @@ export async function lookupBundleRefReadonly(ref) {
  * index, which is copied once rather than once per ref. A ref that does not
  * resolve, or an index that cannot be read, gives `null` for that ref.
  */
-export async function lookupBundleRefsReadonly(refs) {
+export async function lookupBundleRefsReadonly(refs, options = {}) {
     if (refs.length === 0)
         return [];
     let db;
     try {
-        db = openReadonlyExistingDatabase(getDbPath(), { isolatedSnapshot: true });
+        db = openReadonlyExistingDatabase(getDbPath(), { isolatedSnapshot: options.isolatedSnapshot ?? true });
     }
     catch {
         // Unreadable index: every ref stays unresolved.

package/dist/indexer/search/db-search.js

@@ -21,7 +21,7 @@ import { presentationFor } from "../../core/type-presentation.js";
 import { embed } from "../../llm/embedder.js";
 import { applyEmbeddingTemplate, resolveEmbeddingProfile } from "../../llm/embedders/profile.js";
 import { normalizeEmbeddingEndpoint } from "../../llm/embedders/remote.js";
-import { assertIndexPathReadable, closeDatabase, openExistingDatabase, } from "../../storage/repositories/index-connection.js";
+import { assertIndexPathReadable, closeDatabase, openExistingDatabase, openReadonlyExistingDatabase, } from "../../storage/repositories/index-connection.js";
 import { getAllEntries, getBaseBeliefStatesForDerivedTwins, getEntryById, getEntryCount, getEntryRefsAndTypes, } from "../../storage/repositories/index-entries-repository.js";
 import { searchFts } from "../../storage/repositories/index-fts-repository.js";
 import { getMeta } from "../../storage/repositories/index-meta-repository.js";
@@ -128,7 +128,10 @@ export async function searchLocal(input) {
             mode: "keyword",
         };
     }
-    const db = openExistingDatabase(dbPath);
+    // A read-only search (`akm ui`) must not open the index for write: closing a
+    // read-write connection can checkpoint the WAL into the main file, which
+    // changes it even though nothing was written.
+    const db = input.readOnly ? openReadonlyExistingDatabase(dbPath) : openExistingDatabase(dbPath);
     try {
         const entryCount = getEntryCount(db);
         if (entryCount === 0) {

package/dist/storage/repositories/index-db.js

@@ -3,7 +3,7 @@
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import { resolveStorageLocations } from "../locations.js";
 import { withManagedDb } from "../managed-db.js";
-import { openExistingDatabase } from "./index-connection.js";
+import { openExistingDatabase, openReadonlyExistingDatabase } from "./index-connection.js";
 /**
  * Busy-timeout (ms) for read-path telemetry writers. Small on purpose: a
  * usage-event insert contending with a background reindex should be dropped,
@@ -41,7 +41,15 @@ export const TELEMETRY_BUSY_TIMEOUT_MS = 250;
  * @returns Whatever `fn` returns.
  */
 export function withIndexDb(fn, opts) {
-    return withManagedDb(() => openExistingDatabase(resolveStorageLocations().indexDb), (db) => {
+    return withManagedDb(() => {
+        const dbPath = resolveStorageLocations().indexDb;
+        if (!opts?.readOnly)
+            return openExistingDatabase(dbPath);
+        const db = openReadonlyExistingDatabase(dbPath);
+        if (!db)
+            throw new Error(`Index database not found at ${dbPath}. Run 'akm index' to build it.`);
+        return db;
+    }, (db) => {
         if (opts?.busyTimeoutMs !== undefined) {
             db.exec(`PRAGMA busy_timeout = ${Math.max(0, Math.floor(opts.busyTimeoutMs))}`);
         }

package/docs/reference/cli.md

@@ -1558,6 +1558,23 @@ akm clone "npm:@scope/pkg//scripts/deploy.sh" --dest /tmp/preview
 
 Skills (directories) are copied recursively. Other types copy a single file.
 
+**Refs outside the type directories.** A ref whose concept id is not under a
+type directory (a skill in a flat skills repo, `my-repo//domain-name-brainstormer`;
+a page from a website or wiki bundle) is placed by what the source file is: a
+`SKILL.md` directory clones to `skills/<name>/`, any other recognized type to its
+own directory, and markdown of any other type to `knowledge/<name>.md`. `<name>`
+is the last segment of the concept id, slugified; `--name` overrides it. An asset
+that is not markdown and has no place in a bundle fails with a usage error that
+points to `akm import <path>`.
+
+**Provenance.** A cloned markdown asset (a skill's `SKILL.md` included) records
+where it came from: the origin ref, `<bundle>//<concept-id>`, is added to its
+`sources:` frontmatter, keeping any entries already listed. `sources:` is free-form
+provenance that `akm lint` does not resolve, so a clone shared where the origin
+bundle is not installed does not report a missing ref. Other bytes of the file
+stay as written, non-markdown files and workflows are copied unchanged, and the
+origin is never modified.
+
 **Remote clone:** When the origin in the ref points to a package that is not
 installed locally (e.g. an npm package or local path not in your bundle
 sources), akm fetches it to the cache automatically and extracts the
@@ -3030,11 +3047,13 @@ akm proposal new <type> <name> --file ./prompt.md
 akm proposal new skill code-review --task "PR-style review skill"
 akm proposal new lesson docker-cleanup --file ./prompts/docker-cleanup.md
 akm proposal new skill code-review --path team --task "PR-style review skill"  # writes under skills/team/
+akm proposal new skill code-review --bundle team --task "PR-style review skill"  # queued for the `team` bundle
 ```
 
 | Flag | Description |
 | --- | --- |
 | `--path` | Relative subdirectory under the type dir to place the proposed asset in (e.g. `release`). The filename comes from `<name>`. |
+| `--bundle` | Configured writable bundle to queue the proposal for. The prompt takes its convention facts from that bundle, the proposal records it as its target (so `akm proposal accept` writes there), and it is queued in that bundle's queue (`akm proposal list --queue <bundle>`). An unknown, disabled or read-only bundle is refused, as for `akm remember --bundle`. Default: the working bundle |
 | `--task` | Inline task text |
 | `--file` | Read task text from a UTF-8 file |
 | `--engine` | Override the default execution engine. Any kind works: an LLM engine, an agent CLI or `opencode-sdk` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akm-cli",
-  "version": "0.10.261006-beta",
+  "version": "0.10.261007-beta",
   "type": "module",
   "description": "akm (Agent Knowledge Manager) — a portable, local-first capability library for AI agents. Discover, load, share, and improve reusable skills, scripts, workflows, and knowledge across any shell-capable coding agent, including Claude Code, OpenCode, and Cursor.",
   "keywords": [