akm-cli 0.6.0-rc2 → 0.6.1

package/CHANGELOG.md

@@ -10,9 +10,17 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ### Added
 
+- **`akm workflow validate <ref|path>`** — new subcommand that validates a workflow markdown file or ref, surfacing every error in one pass (without running a full reindex).
+- **`akm feedback` now accepts any indexed ref** — previously type-restricted. `memory:`, `vault:`, `workflow:`, `wiki:` refs all work. Vault feedback never echoes vault values.
+- **`akm upgrade` runs post-upgrade tasks automatically.** After a successful upgrade, the new binary is invoked as a child process running `akm index`, which auto-migrates any legacy `stashes` → `sources` config keys via `loadConfig` and rebuilds the index against the new schema (`DB_VERSION` 8 → 9 forces a rebuild). Pass `--skip-post-upgrade` to opt out (config migration still runs on the next `akm` invocation; you'd just need to run `akm index` yourself). Result is reported in the `postUpgrade` field of the upgrade response.
 - **`writable` flag on sources.** New optional `SourceConfigEntry.writable` controls whether write commands (`akm remember`, `akm import`, `akm save`, `akm clone`) may target the source. Defaults: `true` for `filesystem`, `false` for `git` / `website` / `npm`. `writable: true` on `website` or `npm` is rejected at config load with `ConfigError("writable: true is only supported on filesystem and git sources")`.
 - **`defaultWriteTarget` root config key.** Names the source that receives writes when no `--target` flag is given. Resolution order: `--target` → `defaultWriteTarget` → `stashDir` (working stash) → `ConfigError("no writable source configured; run \`akm init\`")`. There is no implicit "first writable in `sources[]` order" fallback.
 
+### Changed
+
+- **Workflows are now stored as validated `WorkflowDocument` JSON** — workflows are compiled into a validated `WorkflowDocument` JSON shape with line-anchored `SourceRef`s back into the source markdown, cached in a new `workflow_documents` table in `index.db`. The run engine reads from the cache on `akm workflow next` instead of re-parsing markdown each step.
+- **Feedback events flow into utility recomputation** — positive/negative feedback signals now feed utility scoring alongside search/show events. Telemetry records both `entry_ref` and `entry_id` so feedback signals survive a reindex.
+
 ### Changed (breaking)
 
 - **v1 architecture refactor.** The internal architecture was rebuilt around a single minimal `SourceProvider` interface (`{ name, kind, init, path, sync? }`), a unified FTS5 index that owns search and show, and a single `writeAssetToSource` helper that owns all writes. The CLI command surface and all user-visible config keys are unchanged. See `docs/migration/v1.md` for the full guide.
@@ -30,6 +38,10 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
   - **Migration**: a curated registry author should regenerate their `index.json` (rename `kits` → `stashes`, drop legacy keyword filtering). Publishers should add the `akm-stash` keyword/topic and remove `akm-kit`/`agentikit`.
 - **`akm registry` description**: changed from "Manage kit registries" to "Manage stash registries".
 
+### Migration / Breaking
+
+- **`DB_VERSION` bumped 8 → 9.** On first run after upgrade, the version-mismatch path in `ensureSchema()` drops + recreates all `index.db` tables (preserving `usage_events` via a typed backup); the next `akm index` rebuilds the index. `workflow.db` (run state) is unaffected.
+
 ### Removed (breaking)
 
 - **OpenViking source provider.** The `openviking` source kind is no longer supported. Configs that contain one fail to load with `ConfigError("openviking is not supported in akm v1. …")` and a hint pointing to `akm config sources remove <name>`. API-backed sources will return as a separate `QuerySource` tier post-v1. To downgrade in the meantime, pin to `akm-cli@0.5`.

package/dist/cli.js

@@ -25,7 +25,7 @@ import { ConfigError, NotFoundError, UsageError } from "./core/errors";
 import { getCacheDir, getDbPath, getDefaultStashDir } from "./core/paths";
 import { setQuiet, warn } from "./core/warn";
 import { resolveWriteTarget, writeAssetToSource } from "./core/write-source";
-import { closeDatabase, openDatabase } from "./indexer/db";
+import { closeDatabase, findEntryIdByRef, openDatabase } from "./indexer/db";
 import { akmIndex } from "./indexer/indexer";
 import { resolveSourceEntries } from "./indexer/search-source";
 import { insertUsageEvent } from "./indexer/usage-events";
@@ -115,7 +115,10 @@ const initCommand = defineCommand({
     },
     async run({ args }) {
         await runWithJsonErrors(async () => {
-            const result = await akmInit({ dir: args.dir });
+            // Accept both historical spellings for backwards compatibility with
+            // older docs/scripts that used `--stashDir`.
+            const legacyDir = parseFlagValue(process.argv, "--stashDir") ?? parseFlagValue(process.argv, "--stash-dir");
+            const result = await akmInit({ dir: args.dir ?? legacyDir });
             output("init", result);
         });
     },
@@ -378,6 +381,11 @@ const upgradeCommand = defineCommand({
             description: "Skip checksum verification (not recommended)",
             default: false,
         },
+        "skip-post-upgrade": {
+            type: "boolean",
+            description: "Skip the post-upgrade `akm index` rebuild (config auto-migration still runs on next `akm` invocation)",
+            default: false,
+        },
     },
     async run({ args }) {
         await runWithJsonErrors(async () => {
@@ -387,7 +395,8 @@ const upgradeCommand = defineCommand({
                 return;
             }
             const skipChecksum = getHyphenatedBoolean(args, "skip-checksum");
-            const result = await performUpgrade(check, { force: args.force, skipChecksum });
+            const skipPostUpgrade = getHyphenatedBoolean(args, "skip-post-upgrade");
+            const result = await performUpgrade(check, { force: args.force, skipChecksum, skipPostUpgrade });
             output("upgrade", result);
         });
     },
@@ -436,7 +445,8 @@ const showCommand = defineCommand({
                 }
             }
             const cliDetail = getOutputMode().detail;
-            const showDetail = cliDetail === "summary" ? "summary" : undefined;
+            const explicitDetail = parseFlagValue(process.argv, "--detail");
+            const showDetail = explicitDetail === "brief" ? "brief" : cliDetail === "summary" ? "summary" : undefined;
             const result = await akmShowUnified({ ref: args.ref, view, detail: showDetail });
             output("show", result);
         });
@@ -781,7 +791,7 @@ const registryCommand = defineCommand({
 const feedbackCommand = defineCommand({
     meta: {
         name: "feedback",
-        description: "Record positive or negative feedback for a stash asset",
+        description: "Record positive or negative feedback for any indexed stash asset",
     },
     args: {
         ref: { type: "positional", description: "Asset ref (type:name)", required: true },
@@ -795,6 +805,7 @@ const feedbackCommand = defineCommand({
             if (!ref) {
                 throw new UsageError("Asset ref is required. Usage: akm feedback <ref> --positive|--negative");
             }
+            parseAssetRef(ref);
             if (args.positive && args.negative) {
                 throw new UsageError("Specify either --positive or --negative, not both.");
             }
@@ -805,9 +816,14 @@ const feedbackCommand = defineCommand({
             const metadata = args.note ? JSON.stringify({ note: args.note }) : undefined;
             const db = openDatabase();
             try {
+                const entryId = findEntryIdByRef(db, ref);
+                if (entryId === undefined) {
+                    throw new UsageError(`Ref "${ref}" is not in the current index. Run "akm index" and try again.`);
+                }
                 insertUsageEvent(db, {
                     event_type: "feedback",
                     entry_ref: ref,
+                    entry_id: entryId,
                     signal,
                     metadata,
                 });
@@ -1520,6 +1536,53 @@ function listVaultsRecursive(listKeysFn) {
     walk(vaultsDir);
     return result;
 }
+function wasRefMisparsedAsFlagValue(ref, flag, flagValue) {
+    const argv = process.argv.slice(2);
+    const vaultIndex = argv.indexOf("vault");
+    const listIndex = vaultIndex >= 0 ? argv.indexOf("list", vaultIndex + 1) : -1;
+    const tokens = listIndex >= 0 ? argv.slice(listIndex + 1) : argv;
+    let flagIndex = -1;
+    let flagConsumesNextToken = false;
+    for (let i = 0; i < tokens.length; i += 1) {
+        const token = tokens[i];
+        if (token === flag) {
+            flagIndex = i;
+            flagConsumesNextToken = true;
+            break;
+        }
+        if (token === `${flag}=${flagValue}`) {
+            flagIndex = i;
+            break;
+        }
+    }
+    if (flagIndex === -1)
+        return false;
+    // If the same token appeared before the flag, the user explicitly passed it
+    // as the positional ref and it was not consumed by the output flag.
+    if (tokens.slice(0, flagIndex).includes(ref))
+        return false;
+    // Skip past either `--flag value` (2 tokens) or `--flag=value` (1 token)
+    // before checking whether the ref appears elsewhere as a real positional.
+    const TOKENS_AFTER_SPACE_FLAG = 2;
+    const TOKENS_AFTER_EQUALS_FLAG = 1;
+    const firstTokenAfterFlag = flagIndex + (flagConsumesNextToken ? TOKENS_AFTER_SPACE_FLAG : TOKENS_AFTER_EQUALS_FLAG);
+    if (tokens.slice(firstTokenAfterFlag).includes(ref))
+        return false;
+    return true;
+}
+function resolveVaultListRef(ref) {
+    if (ref === undefined)
+        return undefined;
+    const parsedFormat = parseFlagValue(process.argv, "--format");
+    if (parsedFormat !== undefined && ref === parsedFormat && wasRefMisparsedAsFlagValue(ref, "--format", parsedFormat)) {
+        return undefined;
+    }
+    const parsedDetail = parseFlagValue(process.argv, "--detail");
+    if (parsedDetail !== undefined && ref === parsedDetail && wasRefMisparsedAsFlagValue(ref, "--detail", parsedDetail)) {
+        return undefined;
+    }
+    return ref;
+}
 const vaultListCommand = defineCommand({
     meta: { name: "list", description: "List vaults, or list keys (no values) inside one vault" },
     args: {
@@ -1528,8 +1591,9 @@ const vaultListCommand = defineCommand({
     run({ args }) {
         return runWithJsonErrors(async () => {
             const { listKeys, listEntries } = await import("./commands/vault.js");
-            if (args.ref) {
-                const { name, absPath } = resolveVaultPath(args.ref);
+            const effectiveRef = resolveVaultListRef(args.ref);
+            if (effectiveRef) {
+                const { name, absPath } = resolveVaultPath(effectiveRef);
                 if (!fs.existsSync(absPath)) {
                     throw new NotFoundError(`Vault not found: vault:${name}`);
                 }

package/dist/commands/installed-stashes.js

@@ -6,7 +6,7 @@
  */
 import fs from "node:fs";
 import path from "node:path";
-import { resolveStashDir } from "../core/common";
+import { isWithin, resolveStashDir } from "../core/common";
 import { loadConfig } from "../core/config";
 import { NotFoundError, UsageError } from "../core/errors";
 import { akmIndex } from "../indexer/indexer";
@@ -14,6 +14,7 @@ import { removeLockEntry, upsertLockEntry } from "../integrations/lockfile";
 import { parseRegistryRef } from "../registry/resolve";
 import { syncFromRef } from "../sources/providers/sync-from-ref";
 import { ensureWebsiteMirror } from "../sources/providers/website";
+import { listWikis, resolveWikisRoot } from "../wiki/wiki";
 import { auditInstallCandidate, deriveRegistryLabels, enforceRegistryInstallPolicy, formatInstallAuditFailure, } from "./install-audit";
 import { removeInstalledRegistryEntry, upsertInstalledRegistryEntry } from "./source-add";
 import { removeStash } from "./source-manage";
@@ -57,6 +58,31 @@ export async function akmListSources(input) {
             status: { exists: directoryExists(entry.stashRoot) },
         });
     }
+    if (!kindFilter || kindFilter.includes("filesystem")) {
+        const wikisRoot = resolveWikisRoot(stashDir);
+        const seenPaths = new Set(sources
+            .map((source) => source.path)
+            .filter((sourcePath) => typeof sourcePath === "string")
+            .map((sourcePath) => path.resolve(sourcePath)));
+        for (const wiki of listWikis(stashDir)) {
+            // `listWikis()` also includes externally-registered wikis. `akm list`
+            // should synthesize source entries here only for stash-owned wiki dirs.
+            if (!isWithin(wiki.path, wikisRoot))
+                continue;
+            const resolvedPath = path.resolve(wiki.path);
+            if (seenPaths.has(resolvedPath))
+                continue;
+            seenPaths.add(resolvedPath);
+            sources.push({
+                name: wiki.name,
+                kind: "filesystem",
+                wiki: wiki.name,
+                path: wiki.path,
+                writable: true,
+                status: { exists: directoryExists(wiki.path) },
+            });
+        }
+    }
     return {
         schemaVersion: 1,
         stashDir,

package/dist/commands/self-update.js

@@ -80,6 +80,7 @@ export async function checkForUpdate(currentVersion) {
 export async function performUpgrade(check, opts) {
     const { currentVersion, latestVersion, installMethod } = check;
     const force = opts?.force === true;
+    const skipPostUpgrade = opts?.skipPostUpgrade === true;
     // All install methods can short-circuit here unless the user explicitly forces an upgrade.
     if (!check.updateAvailable && !force) {
         return {
@@ -113,6 +114,7 @@ export async function performUpgrade(check, opts) {
             upgraded: true,
             installMethod,
             message: `akm upgraded via ${installMethod}`,
+            postUpgrade: runPostUpgradeTasks("akm", { skip: skipPostUpgrade }),
         };
     }
     if (installMethod === "unknown") {
@@ -283,8 +285,72 @@ export async function performUpgrade(check, opts) {
         installMethod,
         binaryPath: execPath,
         checksumVerified,
+        // For binary installs, the new binary now lives at execPath; spawn it
+        // directly so the post-upgrade work runs against the new code.
+        postUpgrade: runPostUpgradeTasks(execPath, { skip: skipPostUpgrade }),
     };
 }
+/**
+ * Run the post-upgrade tasks against the *new* binary as a child process.
+ *
+ * Why a child process: the running akm process still has the old code in
+ * memory. Calling loadConfig()/akmIndex() in-process would use the old
+ * implementations and miss any DB_VERSION / config-key changes the new
+ * release introduces.
+ *
+ * The new binary's `akm index` does the work for us:
+ *   1. loadConfig() runs at startup — auto-migrates legacy `stashes` →
+ *      `sources` if the on-disk config still uses the old key.
+ *   2. ensureSchema() detects DB_VERSION mismatch and rebuilds index.db
+ *      tables (preserving usage_events).
+ *   3. The full reindex repopulates entries + workflow_documents + FTS.
+ */
+function runPostUpgradeTasks(akmBin, opts) {
+    if (opts.skip) {
+        return {
+            ok: true,
+            skipped: true,
+            message: "Skipped post-upgrade tasks. Run `akm index` manually to migrate config and rebuild the index.",
+        };
+    }
+    try {
+        const result = childProcess.spawnSync(akmBin, ["index"], {
+            encoding: "utf8",
+            env: process.env,
+            stdio: "pipe",
+        });
+        if (result.error) {
+            return {
+                ok: false,
+                skipped: false,
+                message: `Post-upgrade tasks could not start: ${result.error.message}. Run \`akm index\` manually.`,
+            };
+        }
+        if (result.status !== 0) {
+            const detail = (result.stderr ?? "").trim() || (result.stdout ?? "").trim() || `exit code ${result.status}`;
+            return {
+                ok: false,
+                skipped: false,
+                exitCode: result.status,
+                message: `Post-upgrade \`akm index\` failed (${detail}). Run \`akm index\` manually.`,
+            };
+        }
+        return {
+            ok: true,
+            skipped: false,
+            exitCode: 0,
+            message: "Config migrated (if needed) and index rebuilt against the new binary.",
+        };
+    }
+    catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        return {
+            ok: false,
+            skipped: false,
+            message: `Post-upgrade tasks failed: ${detail}. Run \`akm index\` manually.`,
+        };
+    }
+}
 function parseChecksumForFile(checksumsText, filename) {
     for (const line of checksumsText.split("\n")) {
         const trimmed = line.trim();

package/dist/commands/show.js

@@ -25,15 +25,15 @@ import { parseAssetRef } from "../core/asset-ref";
 import { loadConfig } from "../core/config";
 import { NotFoundError, UsageError } from "../core/errors";
 import { parseFrontmatter, toStringOrUndefined } from "../core/frontmatter";
-import { closeDatabase, openDatabase } from "../indexer/db";
+import { closeDatabase, findEntryIdByRef, openDatabase } from "../indexer/db";
 import { buildFileContext, buildRenderContext, getRenderer, runMatchers } from "../indexer/file-context";
 import { lookup } from "../indexer/indexer";
 import { loadStashFile } from "../indexer/metadata";
 import { buildEditHint, findSourceForPath, isEditable, resolveSourceEntries } from "../indexer/search-source";
+import { insertUsageEvent } from "../indexer/usage-events";
 import { resolveSourcesForOrigin } from "../registry/origin-resolve";
 // Eagerly import source providers to trigger self-registration.
 import "../sources/providers/index";
-import { insertUsageEvent } from "../indexer/usage-events";
 import { resolveAssetPath } from "../sources/resolve";
 /**
  * Show a wiki root (no page path) — returns the same payload as
@@ -98,8 +98,8 @@ function resolveRegisteredWikiAssetPath(wikiRoot, wikiName, assetName) {
  * type-dir resolution if the index has no row. Spec §6.2; no remote provider
  * fallback.
  *
- * When `detail` is `"summary"`, the response omits content/template/prompt and
- * returns only compact metadata (name, type, description, tags, parameters).
+ * When `detail` is `"brief"` or `"summary"`, the response omits
+ * content/template/prompt and returns compact metadata.
  */
 export async function akmShowUnified(input) {
     const ref = input.ref.trim();
@@ -136,15 +136,10 @@ function logShowEvent(ref, existingDb) {
     try {
         const db = existingDb ?? openDatabase();
         try {
-            const parsed = parseAssetRef(ref);
-            const safeName = parsed.name.replace(/%/g, "\\%").replace(/_/g, "\\_");
-            const row = db
-                .prepare("SELECT id FROM entries WHERE entry_key LIKE ? ESCAPE '\\' AND entry_type = ? LIMIT 1")
-                .get(`%:${parsed.type}:${safeName}`, parsed.type);
             insertUsageEvent(db, {
                 event_type: "show",
                 entry_ref: ref,
-                entry_id: row?.id,
+                entry_id: findEntryIdByRef(db, ref),
             });
         }
         finally {
@@ -256,6 +251,9 @@ export async function showLocal(input) {
         editable,
         ...(!editable ? { editHint: buildEditHint(assetPath, parsed.type, parsed.name, source?.registryId) } : {}),
     };
+    if (input.detail === "brief") {
+        return buildBriefResponse(fullResponse, assetPath);
+    }
     if (input.detail === "summary") {
         return buildSummaryResponse(fullResponse, assetPath);
     }
@@ -275,6 +273,24 @@ export async function showByRef(ref) {
     const body = await fs.promises.readFile(entry.filePath, "utf8");
     return { filePath: entry.filePath, body };
 }
+/**
+ * Build a reduced brief response from a full ShowResponse.
+ *
+ * Keeps routing/identification fields while omitting content/template/prompt.
+ */
+function buildBriefResponse(full, assetPath) {
+    const summary = buildSummaryResponse(full, assetPath);
+    return {
+        type: summary.type,
+        name: summary.name,
+        path: summary.path,
+        ...(summary.description ? { description: summary.description } : {}),
+        ...(summary.action ? { action: summary.action } : {}),
+        ...(summary.run ? { run: summary.run } : {}),
+        ...(summary.origin !== undefined ? { origin: summary.origin } : {}),
+        ...(full.editable !== undefined ? { editable: full.editable } : {}),
+    };
+}
 /**
  * Build a compact summary response from a full ShowResponse.
  *

package/dist/core/config.js

@@ -108,20 +108,7 @@ export function saveConfig(config) {
     const dir = path.dirname(configPath);
     fs.mkdirSync(dir, { recursive: true });
     const sanitized = sanitizeConfigForWrite(config);
-    const tmpPath = `${configPath}.tmp.${process.pid}.${Math.random().toString(36).slice(2)}`;
-    try {
-        fs.writeFileSync(tmpPath, `${JSON.stringify(sanitized, null, 2)}\n`, "utf8");
-        fs.renameSync(tmpPath, configPath);
-    }
-    catch (err) {
-        try {
-            fs.unlinkSync(tmpPath);
-        }
-        catch {
-            /* ignore cleanup failure */
-        }
-        throw err;
-    }
+    writeConfigObject(configPath, sanitized);
 }
 /**
  * Strip apiKey fields before writing config to disk.
@@ -230,12 +217,9 @@ function pickKnownKeys(raw) {
     else {
         const legacyStashes = parseStashesConfig(raw.stashes);
         if (legacyStashes) {
-            // Backwards-compat migration: `stashes[]` → `sources[]` in-memory.
-            // Emit a one-time deprecation warning and carry the value forward as
-            // `sources`. The renamed key is persisted on the next `akm config` write.
-            warn('Config key "stashes" is deprecated; rename it to "sources" in your config file ' +
-                `(edit it directly at ${_getConfigPath()}). ` +
-                "Your configuration has been loaded successfully — no manual action is required right now.");
+            // Backwards-compat fallback: configs that still carry `stashes[]` are
+            // normalized to `sources[]` after the raw file loader has had a chance to
+            // auto-migrate the on-disk key.
             config.sources = legacyStashes;
         }
     }
@@ -264,20 +248,16 @@ function pickKnownKeys(raw) {
 }
 function readNormalizedConfig(configPath) {
     const raw = readConfigObject(configPath);
-    const expanded = raw ? expandEnvVars(raw) : undefined;
+    const migrated = raw ? maybeAutoMigrateLegacyStashes(configPath, raw) : undefined;
+    const expanded = migrated ? expandEnvVars(migrated) : undefined;
     return expanded ? pickKnownKeys(expanded) : undefined;
 }
-function readNormalizedConfigFromText(_configPath, text) {
-    let raw;
-    try {
-        raw = JSON.parse(stripJsonComments(text));
-    }
-    catch {
+function readNormalizedConfigFromText(configPath, text) {
+    const raw = parseConfigObjectFromText(text);
+    if (!raw)
         return undefined;
-    }
-    if (typeof raw !== "object" || raw === null || Array.isArray(raw))
-        return undefined;
-    const expanded = expandEnvVars(raw);
+    const migrated = maybeAutoMigrateLegacyStashes(configPath, raw);
+    const expanded = expandEnvVars(migrated);
     return pickKnownKeys(expanded);
 }
 function parseOutputConfig(value) {
@@ -340,6 +320,14 @@ function expandEnvVars(value, fieldName) {
 function readConfigObject(configPath) {
     try {
         const text = fs.readFileSync(configPath, "utf8");
+        return parseConfigObjectFromText(text);
+    }
+    catch {
+        return undefined;
+    }
+}
+function parseConfigObjectFromText(text) {
+    try {
         const raw = JSON.parse(stripJsonComments(text));
         if (typeof raw !== "object" || raw === null || Array.isArray(raw))
             return undefined;
@@ -349,6 +337,47 @@ function readConfigObject(configPath) {
         return undefined;
     }
 }
+/**
+ * Best-effort on-disk config migration for the legacy `stashes` key.
+ *
+ * When a config file still uses `stashes` and does not already define
+ * `sources`, rewrite the file in place with `sources` replacing `stashes`,
+ * emit a one-time notice on success, and return the migrated object. If the
+ * rewrite fails, emit a warning and return the original object so the loader
+ * can still continue with an in-memory fallback.
+ */
+function maybeAutoMigrateLegacyStashes(configPath, raw) {
+    if (Object.hasOwn(raw, "sources") || !Object.hasOwn(raw, "stashes")) {
+        return raw;
+    }
+    const migrated = Object.fromEntries(Object.entries(raw).map(([key, value]) => (key === "stashes" ? ["sources", value] : [key, value])));
+    try {
+        writeConfigObject(configPath, migrated);
+        warn('Config migrated: "stashes" → "sources" in config.json');
+        return migrated;
+    }
+    catch {
+        warn('Failed to migrate "stashes" → "sources" in config.json; continuing with the legacy key in memory. ' +
+            "Check file permissions or rename the key manually if this persists.");
+        return raw;
+    }
+}
+function writeConfigObject(configPath, config) {
+    const tmpPath = `${configPath}.tmp.${process.pid}.${Math.random().toString(36).slice(2)}`;
+    try {
+        fs.writeFileSync(tmpPath, `${JSON.stringify(config, null, 2)}\n`, "utf8");
+        fs.renameSync(tmpPath, configPath);
+    }
+    catch (err) {
+        try {
+            fs.unlinkSync(tmpPath);
+        }
+        catch {
+            /* ignore cleanup failure */
+        }
+        throw err;
+    }
+}
 /**
  * Strip JavaScript-style comments from a JSON string (JSONC support).
  * Handles // line comments and /* block comments while preserving

package/dist/indexer/db-search.js

@@ -17,7 +17,7 @@ import { defaultRendererRegistry } from "../core/asset-registry";
 import { deriveCanonicalAssetNameFromStashRoot } from "../core/asset-spec";
 import { getDbPath } from "../core/paths";
 import { warn } from "../core/warn";
-import { closeDatabase, getAllEntries, getEntryById, getEntryCount, getMeta, getUtilityScoresByIds, openDatabase, searchFts, searchVec, } from "./db";
+import { closeDatabase, getAllEntries, getEntryById, getEntryCount, getMeta, getUtilityScoresByIds, openDatabase, sanitizeFtsQuery, searchFts, searchVec, } from "./db";
 import { getRenderer } from "./file-context";
 import { generateMetadataFlat, loadStashFile, shouldIndexStashFile } from "./metadata";
 import { buildSearchText } from "./search-fields";
@@ -115,8 +115,11 @@ export async function searchLocal(input) {
 }
 // ── Database search ─────────────────────────────────────────────────────────
 async function searchDatabase(db, query, searchType, limit, stashDir, allSourceDirs, config, sources, rendererRegistry = defaultRendererRegistry) {
-    // Empty query: return all entries
-    if (!query) {
+    const hasSearchableTokens = query.length > 0 && sanitizeFtsQuery(query).length > 0;
+    // Empty queries — including ones that sanitize down to no searchable FTS
+    // tokens such as "." — should enumerate matching entries instead of
+    // returning an empty result set from FTS.
+    if (!hasSearchableTokens) {
         const typeFilter = searchType === "any" ? undefined : searchType;
         const allEntries = getAllEntries(db, typeFilter);
         // Deduplicate by file path — multiple entries can share the same file

package/dist/indexer/db.js

@@ -2,6 +2,7 @@ import { Database } from "bun:sqlite";
 import fs from "node:fs";
 import { createRequire } from "node:module";
 import path from "node:path";
+import { parseAssetRef } from "../core/asset-ref";
 import { getDbPath } from "../core/paths";
 import { warn } from "../core/warn";
 import { cosineSimilarity } from "../llm/embedders/types";
@@ -717,6 +718,14 @@ export function getAllEntries(db, entryType) {
     }
     return entries;
 }
+export function findEntryIdByRef(db, ref) {
+    const parsed = parseAssetRef(ref);
+    const suffix = `${parsed.type}:${parsed.name}`;
+    const row = db
+        .prepare("SELECT id FROM entries WHERE entry_type = ? AND substr(entry_key, length(entry_key) - length(?) + 1) = ? LIMIT 1")
+        .get(parsed.type, suffix, suffix);
+    return row?.id;
+}
 export function getEntryCount(db) {
     const row = db.prepare("SELECT COUNT(*) AS cnt FROM entries").get();
     return row.cnt;

package/dist/indexer/indexer.js

@@ -772,8 +772,10 @@ const USAGE_EVENT_RETENTION_DAYS = 90;
  * For each entry:
  *   - Count search appearances (event_type = 'search')
  *   - Count show events (event_type = 'show')
+ *   - Count positive/negative feedback events
  *   - Compute select_rate = showCount / searchCount, clamped to [0, 1]
- *   - Update utility via EMA: utility = previousUtility * 0.7 + selectRate * 0.3
+ *   - Convert feedback counts into a positive-only feedback_rate
+ *   - Update utility via EMA from the stronger of select_rate / feedback_rate
  *
  * Also purges usage_events older than 90 days and ensures the M-1
  * usage_events table exists before querying.
@@ -803,6 +805,8 @@ export function recomputeUtilityScores(db) {
       SELECT entry_id,
              SUM(CASE WHEN event_type = 'search' THEN 1 ELSE 0 END) AS search_count,
              SUM(CASE WHEN event_type = 'show'   THEN 1 ELSE 0 END) AS show_count,
+             SUM(CASE WHEN event_type = 'feedback' AND signal = 'positive' THEN 1 ELSE 0 END) AS positive_feedback_count,
+             SUM(CASE WHEN event_type = 'feedback' AND signal = 'negative' THEN 1 ELSE 0 END) AS negative_feedback_count,
              MAX(created_at) AS last_used_at
       FROM usage_events
       WHERE entry_id IS NOT NULL
@@ -821,8 +825,11 @@ export function recomputeUtilityScores(db) {
     }
     for (const row of usageRows) {
         const selectRate = row.search_count > 0 ? Math.min(1, row.show_count / row.search_count) : 0;
+        const feedbackTotal = row.positive_feedback_count + row.negative_feedback_count;
+        const feedbackRate = feedbackTotal > 0 ? Math.max(0, row.positive_feedback_count - row.negative_feedback_count) / feedbackTotal : 0;
+        const effectiveRate = Math.max(selectRate, feedbackRate);
         const prevUtility = existingScores.get(row.entry_id) ?? 0;
-        const utility = prevUtility * emaDecay + selectRate * emaNew;
+        const utility = prevUtility * emaDecay + effectiveRate * emaNew;
         upsertUtilityScore(db, row.entry_id, {
             utility,
             showCount: row.show_count,

package/dist/indexer/metadata.js

@@ -255,10 +255,9 @@ const WIKI_INFRA_FILES = new Set(["schema.md", "index.md", "log.md"]);
  * Apply wiki-specific index exclusions while leaving all other stash files
  * untouched.
  *
- * - In a normal stash, excludes `wikis/<name>/raw/**` and wiki-root
- *   `schema.md`, `index.md`, `log.md`.
- * - In a wiki-root stash source (`wikiName`), excludes `raw/**` and those same
- *   root-level infrastructure files.
+ * - In a normal stash, excludes wiki-root `schema.md`, `index.md`, `log.md`.
+ * - In a wiki-root stash source (`wikiName`), excludes those same root-level
+ *   infrastructure files.
  */
 export function shouldIndexStashFile(stashRoot, file, options) {
     const relPath = path.relative(stashRoot, file);
@@ -268,8 +267,6 @@ export function shouldIndexStashFile(stashRoot, file, options) {
     if (segments.length === 0)
         return true;
     if (options?.treatStashRootAsWikiRoot) {
-        if (segments[0] === "raw")
-            return false;
         return !(segments.length === 1 && WIKI_INFRA_FILES.has(segments[0]));
     }
     const wikisIdx = segments.indexOf("wikis");
@@ -278,8 +275,6 @@ export function shouldIndexStashFile(stashRoot, file, options) {
     const wikiRelativeSegments = segments.slice(wikisIdx + 2);
     if (wikiRelativeSegments.length === 0)
         return true;
-    if (wikiRelativeSegments[0] === "raw")
-        return false;
     return !(wikiRelativeSegments.length === 1 && WIKI_INFRA_FILES.has(wikiRelativeSegments[0]));
 }
 /**

package/dist/output/cli-hints.js

@@ -125,6 +125,8 @@ akm workflow validate workflows/foo.md         # Validate a workflow file or ref
 akm workflow next workflow:ship-release        # Start or resume the next workflow step
 akm feedback skill:code-review --positive      # Record that an asset helped
 akm feedback agent:reviewer --negative         # Record that an asset missed the mark
+akm feedback memory:deployment-notes --positive # Works for memories too
+akm feedback vault:prod --positive             # Records vault feedback without surfacing values
 \`\`\`
 
 Use \`akm feedback\` whenever an asset materially helps or fails so future search

package/dist/output/text.js

@@ -433,7 +433,7 @@ export function formatWikiRemovePlain(r) {
     const preserved = r.preservedRaw === true;
     const removed = Array.isArray(r.removed) ? r.removed.length : 0;
     const base = `Removed wiki ${String(r.name ?? "?")} (${removed} path(s))`;
-    return preserved ? `${base}; preserved ${String(r.rawPath ?? "raw/")}` : base;
+    return preserved ? `${base}; raw/ preserved at ${String(r.rawPath ?? "raw/")}` : base;
 }
 export function formatWikiPagesPlain(r) {
     const pages = Array.isArray(r.pages) ? r.pages : [];

package/dist/wiki/wiki.js

@@ -76,7 +76,7 @@ function registeredWikiSources(stashDir) {
 export function resolveWikiSource(stashDir, name) {
     validateWikiName(name);
     const wikiDir = resolveWikiDir(stashDir, name);
-    if (fs.existsSync(wikiDir)) {
+    if (fs.existsSync(wikiDir) && isRecognizedStashWiki(wikiDir)) {
         return { name, path: wikiDir, mode: "stash" };
     }
     const external = registeredWikiSources(stashDir).find((source) => source.name === name);
@@ -87,7 +87,7 @@ export function resolveWikiSource(stashDir, name) {
 export function ensureWikiNameAvailable(stashDir, name) {
     validateWikiName(name);
     const wikiDir = resolveWikiDir(stashDir, name);
-    if (fs.existsSync(wikiDir)) {
+    if (fs.existsSync(wikiDir) && isRecognizedStashWiki(wikiDir)) {
         throw new UsageError(`Wiki already exists: ${name}.`, "RESOURCE_ALREADY_EXISTS");
     }
     const external = registeredWikiSources(stashDir).find((source) => source.name === name);
@@ -99,8 +99,9 @@ export function ensureWikiNameAvailable(stashDir, name) {
  * Walk a wiki directory and bucket files into pages vs raws.
  *
  * "Pages" are any `.md` files under the wiki root EXCEPT `schema.md`,
- * `index.md`, `log.md`, or anything under `raw/`. This matches the set the
- * agent edits, and the set `akm wiki pages` exposes.
+ * `index.md`, or `log.md`. Raw sources are bucketed separately so callers can
+ * distinguish authored pages from ingested source material while still
+ * surfacing both.
  *
  * Returns two mtime signals:
  *   - `lastModifiedMs` — newest across all .md files. Used for the `show` /
@@ -164,6 +165,17 @@ function scanWikiFiles(wikiDir) {
     }
     return { pages, raws, lastModifiedMs, pagesLastModifiedMs };
 }
+function hasWikiInfrastructure(wikiDir) {
+    for (const file of WIKI_SPECIAL_FILES) {
+        if (fs.existsSync(path.join(wikiDir, file)))
+            return true;
+    }
+    return false;
+}
+function isRecognizedStashWiki(wikiDir, buckets) {
+    const scanned = buckets ?? scanWikiFiles(wikiDir);
+    return scanned.pages.length > 0 || hasWikiInfrastructure(wikiDir);
+}
 function readSchemaDescription(wikiDir) {
     const schemaPath = path.join(wikiDir, SCHEMA_MD);
     let raw;
@@ -207,6 +219,8 @@ export function listWikis(stashDir) {
     }
     const summarize = (name, dir) => {
         const buckets = scanWikiFiles(dir);
+        if (!isRecognizedStashWiki(dir, buckets))
+            return;
         const summary = {
             name,
             path: dir,
@@ -353,9 +367,11 @@ export function createWiki(stashDir, name) {
  * ignore that (e.g. idempotent cleanup) by catching.
  */
 export function removeWiki(stashDir, name, options = {}) {
-    const resolved = resolveWikiSource(stashDir, name);
-    const wikiDir = resolved.path;
-    if (resolved.mode === "external") {
+    validateWikiName(name);
+    const wikiDir = resolveWikiDir(stashDir, name);
+    const external = registeredWikiSources(stashDir).find((source) => source.name === name);
+    const isStashWiki = fs.existsSync(wikiDir) && isRecognizedStashWiki(wikiDir);
+    if (!isStashWiki && external) {
         const config = loadUserConfig();
         const filteredSources = (config.sources ?? config.stashes ?? []).filter((entry) => entry.wikiName !== name);
         const installed = (config.installed ?? []).filter((entry) => entry.wikiName !== name);
@@ -373,8 +389,8 @@ export function removeWiki(stashDir, name, options = {}) {
             unregistered: true,
         };
     }
-    if (!fs.existsSync(wikiDir)) {
-        throw new NotFoundError(`Wiki not found: ${name}.`, "STASH_NOT_FOUND");
+    if (!fs.existsSync(wikiDir) || (!isStashWiki && !options.withSources)) {
+        throw new NotFoundError(wikiNotFoundMessage(name), "STASH_NOT_FOUND");
     }
     const wikisRoot = resolveWikisRoot(stashDir);
     if (!isWithin(wikiDir, wikisRoot)) {
@@ -480,15 +496,16 @@ function readPageFrontmatter(absPath) {
     return out;
 }
 /**
- * List the pages in a wiki, excluding `schema.md`, `index.md`, `log.md`, and
- * anything under `raw/`. Each entry carries its ref (`wiki:<name>/<page>`),
- * path, and frontmatter-derived fields for orientation.
+ * List the addressable markdown entries in a wiki, excluding only the
+ * infrastructure files `schema.md`, `index.md`, and `log.md`. This includes
+ * both authored pages and `raw/` sources so `wiki pages` can inventory content
+ * written via `akm wiki stash`.
  */
 export function listPages(stashDir, name) {
     const wikiDir = resolveWikiSource(stashDir, name).path;
-    const { pages } = scanWikiFiles(wikiDir);
+    const { pages, raws } = scanWikiFiles(wikiDir);
     const result = [];
-    for (const abs of pages) {
+    for (const abs of [...pages, ...raws]) {
         const pageName = pageNameFromPath(wikiDir, abs);
         const ref = `wiki:${name}/${pageName}`;
         const fm = readPageFrontmatter(abs);
@@ -525,7 +542,6 @@ export async function searchInWiki(input) {
         }
         throw err;
     }
-    const rawDir = path.join(wikiDir, RAW_SUBDIR);
     const filtered = [];
     for (const hit of response.hits) {
         // hits can be SourceSearchHit or RegistrySearchResultHit (union); filter
@@ -541,9 +557,6 @@ export async function searchInWiki(input) {
         const basename = path.basename(stashHit.path);
         if (WIKI_SPECIAL_FILES.has(basename) && path.dirname(stashHit.path) === wikiDir)
             continue;
-        // Exclude anything under raw/
-        if (isWithin(stashHit.path, rawDir))
-            continue;
         filtered.push(stashHit);
     }
     return { ...response, hits: filtered, registryHits: undefined };

package/docs/migration/release-notes/0.6.0.md

@@ -4,6 +4,28 @@ This release ships the v1 architecture refactor on top of the earlier 0.6
 terminology cut (`kit` → `stash` in the registry wire format). The CLI
 command surface is unchanged. Most users have nothing to do.
 
+## Workflows: schema-driven indexing
+
+Workflows are now compiled into a validated `WorkflowDocument` JSON shape
+with line-anchored `SourceRef`s back into the source markdown, cached in a
+new `workflow_documents` table in `index.db`. `akm workflow next` reads from
+the cache instead of re-parsing markdown each step.
+
+A new `akm workflow validate <ref|path>` subcommand surfaces every error in
+one pass (without running a full reindex), formatted as `path:line — message`.
+
+`DB_VERSION` is bumped 8 → 9 to introduce the table; first run after upgrade
+drops + recreates all `index.db` tables (preserving `usage_events`). The next
+`akm index` rebuilds. Run-state in `workflow.db` is untouched.
+
+## Feedback expanded to any indexed ref
+
+`akm feedback <ref>` now accepts any indexed ref — `memory:`, `vault:`,
+`workflow:`, `wiki:` etc. The ref must be present in the local index.
+Vault feedback never echoes vault values. Telemetry persists both
+`entry_ref` and `entry_id` so signals survive a reindex, and feedback
+events now feed into utility recomputation alongside search/show signals.
+
 Locked v1 decisions:
 - `writable` defaults to `true` on `filesystem`, `false` on `git` /
   `website` / `npm`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akm-cli",
-  "version": "0.6.0-rc2",
+  "version": "0.6.1",
   "type": "module",
   "description": "akm (Agent Kit Manager) — A package manager for AI agent skills, commands, tools, and knowledge. Works with Claude Code, OpenCode, Cursor, and any AI coding assistant.",
   "keywords": [