akm-cli 0.6.0-rc2 → 0.6.0

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);
         });
     },
@@ -781,7 +790,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 +804,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 +815,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,
                 });

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
@@ -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 {

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.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/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);
@@ -164,6 +164,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 +218,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 +366,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 +388,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)) {

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.0",
   "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": [