akm-cli 0.5.0 → 0.6.0-rc1

package/dist/stash-resolve.js

@@ -30,20 +30,20 @@ function resolveInTypeDir(stashDir, typeDir, type, name) {
     const resolvedRoot = resolveAndValidateTypeRoot(root, type, name);
     const resolvedTarget = path.resolve(target);
     if (!isWithin(resolvedTarget, resolvedRoot)) {
-        throw new UsageError("Ref resolves outside the stash root.");
+        throw new UsageError("Ref resolves outside the stash root.", "PATH_ESCAPE_VIOLATION");
     }
     if (!fs.existsSync(resolvedTarget) || !fs.statSync(resolvedTarget).isFile()) {
-        throw new NotFoundError(`Stash asset not found for ref: ${type}:${name}`);
+        throw new NotFoundError(`Stash asset not found for ref: ${type}:${name}`, "ASSET_NOT_FOUND");
     }
     const realTarget = fs.realpathSync(resolvedTarget);
     if (!isWithin(realTarget, resolvedRoot)) {
-        throw new UsageError("Ref resolves outside the stash root.");
+        throw new UsageError("Ref resolves outside the stash root.", "PATH_ESCAPE_VIOLATION");
     }
     if (!isRelevantAssetFile(type, path.basename(resolvedTarget))) {
         if (type === "script") {
             throw new NotFoundError("Script ref must resolve to a file with a supported script extension. Refer to the akm documentation for the complete list of supported script extensions.");
         }
-        throw new NotFoundError(`Stash asset not found for ref: ${type}:${name}`);
+        throw new NotFoundError(`Stash asset not found for ref: ${type}:${name}`, "ASSET_NOT_FOUND");
     }
     return realTarget;
 }
@@ -77,7 +77,7 @@ async function resolveByCanonicalName(stashDir, type, name) {
         const realTarget = fs.realpathSync(ctx.absPath);
         const resolvedRoot = fs.realpathSync(stashDir);
         if (!isWithin(realTarget, resolvedRoot)) {
-            throw new UsageError("Ref resolves outside the stash root.");
+            throw new UsageError("Ref resolves outside the stash root.", "PATH_ESCAPE_VIOLATION");
         }
         return realTarget;
     }

package/dist/stash-search.js

@@ -1,6 +1,6 @@
 import { loadConfig } from "./config";
 import { closeDatabase, openDatabase } from "./db";
-import { searchLocal } from "./local-search";
+import { searchLocal } from "./db-search";
 import { resolveStashProviders } from "./stash-provider-factory";
 // Eagerly import stash providers to trigger self-registration
 import "./stash-providers/index";
@@ -36,9 +36,9 @@ export async function akmSearch(input) {
     // stash root. Safe because the empty-sources case is handled above.
     const stashDir = sources[0].path;
     // Resolve additional stash providers (e.g. OpenViking) from config.
-    // Exclude filesystem (handled by resolveStashSources) and context-hub/github
-    // (content now indexed through the unified FTS5 pipeline).
-    const additionalStashProviders = resolveStashProviders(config).filter((p) => p.type !== "filesystem" && p.type !== "context-hub" && p.type !== "git");
+    // Exclude filesystem (handled by resolveStashSources) and git (content
+    // now indexed through the unified FTS5 pipeline).
+    const additionalStashProviders = resolveStashProviders(config).filter((p) => p.type !== "filesystem" && p.type !== "git");
     const localResult = source === "registry"
         ? undefined
         : await searchLocal({

package/dist/stash-show.js

@@ -66,14 +66,14 @@ function resolveRegisteredWikiAssetPath(wikiRoot, wikiName, assetName) {
     const candidate = path.resolve(wikiRoot, `${pageName}.md`);
     const resolvedRoot = fs.realpathSync(wikiRoot);
     if (!candidate.startsWith(resolvedRoot + path.sep)) {
-        throw new UsageError("Ref resolves outside the stash root.");
+        throw new UsageError("Ref resolves outside the stash root.", "PATH_ESCAPE_VIOLATION");
     }
     if (!fs.existsSync(candidate) || !fs.statSync(candidate).isFile()) {
         throw new NotFoundError(`Stash asset not found for ref: wiki:${assetName}`);
     }
     const realTarget = fs.realpathSync(candidate);
     if (!realTarget.startsWith(resolvedRoot + path.sep)) {
-        throw new UsageError("Ref resolves outside the stash root.");
+        throw new UsageError("Ref resolves outside the stash root.", "PATH_ESCAPE_VIOLATION");
     }
     return realTarget;
 }
@@ -203,7 +203,7 @@ export async function showLocal(input) {
     if (!assetPath && parsed.origin && searchSources.length === 0) {
         const installCmd = `akm add ${parsed.origin}`;
         throw new NotFoundError(`Stash asset not found for ref: ${displayType}:${parsed.name}. ` +
-            `Kit "${parsed.origin}" is not installed. Run: ${installCmd}`);
+            `Stash "${parsed.origin}" is not installed. Run: ${installCmd}`);
     }
     if (!assetPath) {
         throw (lastError ??

package/dist/wiki.js

@@ -82,17 +82,17 @@ export function resolveWikiSource(stashDir, name) {
     const external = registeredWikiSources(stashDir).find((source) => source.name === name);
     if (external)
         return external;
-    throw new NotFoundError(wikiNotFoundMessage(name));
+    throw new NotFoundError(wikiNotFoundMessage(name), "STASH_NOT_FOUND");
 }
 export function ensureWikiNameAvailable(stashDir, name) {
     validateWikiName(name);
     const wikiDir = resolveWikiDir(stashDir, name);
     if (fs.existsSync(wikiDir)) {
-        throw new UsageError(`Wiki already exists: ${name}.`);
+        throw new UsageError(`Wiki already exists: ${name}.`, "RESOURCE_ALREADY_EXISTS");
     }
     const external = registeredWikiSources(stashDir).find((source) => source.name === name);
     if (external) {
-        throw new UsageError(`Wiki already registered: ${name}.`);
+        throw new UsageError(`Wiki already registered: ${name}.`, "RESOURCE_ALREADY_EXISTS");
     }
 }
 /**
@@ -305,7 +305,7 @@ export function showWiki(stashDir, name) {
 export function createWiki(stashDir, name) {
     const existing = registeredWikiSources(stashDir).find((source) => source.name === name);
     if (existing) {
-        throw new UsageError(`Wiki already registered: ${name}.`);
+        throw new UsageError(`Wiki already registered: ${name}.`, "RESOURCE_ALREADY_EXISTS");
     }
     const wikiDir = resolveWikiDir(stashDir, name);
     fs.mkdirSync(wikiDir, { recursive: true });
@@ -373,11 +373,11 @@ export function removeWiki(stashDir, name, options = {}) {
         };
     }
     if (!fs.existsSync(wikiDir)) {
-        throw new NotFoundError(`Wiki not found: ${name}.`);
+        throw new NotFoundError(`Wiki not found: ${name}.`, "STASH_NOT_FOUND");
     }
     const wikisRoot = resolveWikisRoot(stashDir);
     if (!isWithin(wikiDir, wikisRoot)) {
-        throw new UsageError(`Refusing to remove a path outside the wikis root: ${wikiDir}`);
+        throw new UsageError(`Refusing to remove a path outside the wikis root: ${wikiDir}`, "PATH_ESCAPE_VIOLATION");
     }
     const removed = [];
     const rawDir = path.join(wikiDir, RAW_SUBDIR);

package/dist/workflow-authoring.js

@@ -3,6 +3,7 @@ import path from "node:path";
 import { resolveAssetPathFromName } from "./asset-spec";
 import { isWithin, resolveStashDir } from "./common";
 import { UsageError } from "./errors";
+import { warn } from "./warn";
 import { parseWorkflowMarkdown, WorkflowValidationError } from "./workflow-markdown";
 const DEFAULT_WORKFLOW_TEMPLATE = renderWorkflowTemplate({
     title: "Example Workflow",
@@ -32,13 +33,13 @@ export function createWorkflowAsset(input) {
     const normalizedName = normalizeWorkflowName(input.name);
     const assetPath = resolveAssetPathFromName("workflow", typeRoot, normalizedName);
     if (!isWithin(assetPath, typeRoot)) {
-        throw new UsageError(`Resolved workflow path escapes the stash: "${normalizedName}"`);
+        throw new UsageError(`Resolved workflow path escapes the stash: "${normalizedName}"`, "PATH_ESCAPE_VIOLATION");
     }
     if (fs.existsSync(assetPath) && !input.force) {
-        throw new UsageError(`Workflow "${normalizedName}" already exists. Re-run with --force to overwrite it.`);
+        throw new UsageError(`Workflow "${normalizedName}" already exists. Re-run with --force to overwrite it.`, "RESOURCE_ALREADY_EXISTS");
     }
     const content = input.from
-        ? readWorkflowSource(input.from)
+        ? readWorkflowSource(input.from, stashDir)
         : (input.content ?? buildWorkflowTemplate(normalizedName));
     try {
         parseWorkflowMarkdown(content);
@@ -57,7 +58,7 @@ export function createWorkflowAsset(input) {
         stashDir,
     };
 }
-function readWorkflowSource(source) {
+function readWorkflowSource(source, stashDir) {
     const resolved = path.resolve(source);
     let stat;
     try {
@@ -69,6 +70,13 @@ function readWorkflowSource(source) {
     if (!stat.isFile()) {
         throw new UsageError(`Workflow source must be a file: "${source}".`);
     }
+    // The user is allowed to import any readable file as a workflow body, but
+    // an import from outside the stash is unusual enough to warn about. Anyone
+    // running `akm workflow create --from /etc/passwd` deserves a heads-up.
+    if (!isWithin(resolved, stashDir)) {
+        warn(`Importing workflow content from outside the stash: ${resolved}\n  ` +
+            `If this was unintentional, abort and re-run with a --from path inside ${stashDir}.`);
+    }
     return fs.readFileSync(resolved, "utf8");
 }
 function normalizeWorkflowName(name) {

package/dist/workflow-markdown.js

@@ -92,6 +92,15 @@ function extractWorkflowSteps(body) {
     }
     const steps = [];
     let index = titleLineIndex + 1;
+    // Skip optional intro prose before the first ## Step: section.
+    while (index < lines.length && !/^##\s+Step:\s+/.test((lines[index] ?? "").trim())) {
+        const line = lines[index] ?? "";
+        const trimmed = line.trim();
+        if (trimmed.startsWith("# ") && !/^#\s+Workflow:\s+/.test(trimmed)) {
+            throw new WorkflowValidationError(`Unexpected top-level heading after workflow title: "${trimmed}".`);
+        }
+        index++;
+    }
     while (index < lines.length) {
         const line = lines[index] ?? "";
         const trimmed = line.trim();

package/dist/workflow-runs.js

@@ -108,9 +108,19 @@ export function resumeWorkflowRun(runId) {
             const steps = readWorkflowRunSteps(workflowDb, run.id);
             return buildWorkflowRunDetail(run, steps);
         }
-        // blocked or failed → flip back to active
+        // blocked or failed → flip back to active and re-open the current step so
+        // it can be reclassified (completed, failed, skipped) after resuming.
         const now = new Date().toISOString();
-        workflowDb.prepare("UPDATE workflow_runs SET status = 'active', updated_at = ? WHERE id = ?").run(now, run.id);
+        workflowDb.transaction(() => {
+            if (run.current_step_id) {
+                workflowDb
+                    .prepare(`UPDATE workflow_run_steps
+             SET status = 'pending', notes = NULL, evidence_json = NULL, completed_at = NULL
+             WHERE run_id = ? AND step_id = ? AND status IN ('blocked', 'failed')`)
+                    .run(run.id, run.current_step_id);
+            }
+            workflowDb.prepare("UPDATE workflow_runs SET status = 'active', updated_at = ? WHERE id = ?").run(now, run.id);
+        })();
         const updated = { ...run, status: "active", updated_at: now };
         const steps = readWorkflowRunSteps(workflowDb, run.id);
         return buildWorkflowRunDetail(updated, steps);

package/docs/README.md

@@ -0,0 +1,30 @@
+# Documentation
+
+## Getting Started
+
+- [Concepts](concepts.md) -- Stashes, registries, asset types, and refs
+- [Getting Started](getting-started.md) -- Quick setup guide
+- [Agent Install Guide](agents/agent-install.md) -- Step-by-step automated install for agents
+- [Stash Maker's Guide](stash-makers.md) -- Build and share a stash on GitHub, npm, or a network directory
+
+## Upgrading
+
+- [v0.5 → v0.6 migration guide](migration/v0.5-to-v0.6.md) -- Every breaking change with before/after code, publisher checklist, and troubleshooting
+
+## Reference
+
+- [CLI](cli.md) -- All `akm` commands and flags
+- [Registry](registry.md) -- Registries, search, hosting, and managing sources
+- [Configuration](configuration.md) -- Providers, settings, and Ollama setup
+- [Filesystem](technical/filesystem.md) -- Directory layout and `.stash.json` schema
+
+## Internals
+
+- [Search](technical/search.md) -- Hybrid search architecture and scoring
+- [Indexing](technical/indexing.md) -- How the search index is built
+- [Classification](technical/classification.md) -- Matcher and renderer behavior
+- [Show Response](technical/show-response.md) -- `akm show` output fields by asset type
+- [Testing Workflow](technical/testing-workflow.md) -- End-to-end, Docker, deployment, and upgrade validation
+- [Ref Format](technical/ref.md) -- Wire format for asset references
+- [Test Coverage Guide](technical/test-coverage-guide.md) -- High-value testing areas
+- [Core Principles](technical/akm-core-principles.md) -- Design principles and constraints

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

@@ -0,0 +1,4 @@
+Migration notes for akm v0.0.13
+
+- Initial public release.
+- No migration steps are required for earlier akm versions.

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

@@ -0,0 +1,6 @@
+Migration notes for akm v0.1.0
+
+- The package and project were rebranded from Agent-i-Kit to akm.
+- Update package references from `agent-i-kit` to `akm-cli`.
+- Update config, registry, plugin, path, and environment-variable references from `agent-i-kit` / `AGENT_I_KIT_*` to `akm` / `AKM_*`.
+- The `tool` asset type and `submit` command were removed.

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

@@ -0,0 +1,6 @@
+Migration notes for akm v0.2.0
+
+- Asset refs are user-facing `type:name` values; do not rely on URI-style refs.
+- The old fixed asset-type union was replaced by an extensible asset type system.
+- `tool` assets were removed; use `script` assets instead.
+- Config and docs should treat remote provider scores and local scores as part of one shared search pipeline.

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

@@ -0,0 +1,5 @@
+Migration notes for akm v0.3.0
+
+- The old `stash` and `kit` command groups were folded into the top-level CLI.
+- Use `akm add`, `akm list`, and `akm remove` instead of the older split command surfaces.
+- Documentation and examples from older releases should be updated to the unified source model.

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

@@ -0,0 +1,6 @@
+Migration notes for akm v0.5.0
+
+- New top-level surfaces: `akm wiki …`, `akm workflow …`, `akm vault …`, and `akm save`.
+- If you tried the unreleased single-wiki LLM prototype, move to the new `akm wiki …` workflow.
+- Removed from the prototype surface: `akm lint`, `akm import --llm`, `akm import --dry-run`, `knowledge.pageKinds`, and the old ingest/lint LLM prompts.
+- Existing raw wiki-like content should be moved into `wikis/<name>/raw/` and then managed with the new wiki commands.

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

@@ -0,0 +1,29 @@
+Migration notes for akm v0.6.0
+
+This release is a clean break: the runtime "kit" / "source" concept is renamed to **stash**, the registry wire format moves from `kits[]` to `stashes[]` (schema v3), and the discovery keyword/topic is renamed from `akm-kit` to `akm-stash`.
+
+Automatic (no action required):
+- `stash.lock` is renamed to `akm.lock` on startup.
+- `config.installed[]` entries are mapped to `config.stashes[]` + `akm.lock` records.
+- `stashDir` is loaded as an implicit `primary: true` filesystem stash entry.
+- Stash type aliases `"context-hub"` and `"github"` normalize to `"git"` in memory.
+
+Manual actions required:
+- Replace `akm enable context-hub` / `akm disable context-hub` with
+  `akm add github:andrewyng/context-hub --name context-hub`.
+- Switch error-handling scripts from string-matching the `error` message
+  to comparing the new machine-readable `code` field.
+- Replace `--for-agent` with `--detail=agent` (old flag is retained as a
+  deprecated alias for one release cycle).
+- Replace `disableGlobalStashes: true` with `stashInheritance: "replace"`.
+
+Publishers:
+- The discovery keyword/topic was renamed from `akm-kit` to `akm-stash`.
+  Update your npm `keywords` and GitHub topics. Legacy keywords are no
+  longer honored — clean break, no transition window.
+
+Self-hosted registries:
+- The wire format `kits[]` is renamed to `stashes[]`. Schema is bumped
+  to v3 and `akm-cli >= 0.6.0` only parses v3.
+
+Full migration guide: https://github.com/itlackey/akm/blob/main/docs/migration/v0.5-to-v0.6.md

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

@@ -0,0 +1,21 @@
+# Release-notes corpus for `akm help migrate`
+
+This directory holds one `.md` file per release. Each file is the short,
+focused migration note that `akm help migrate <version>` prints to the
+terminal. The longform cross-release guides (e.g. `v0.5-to-v0.6.md`)
+live one level up in `docs/migration/`.
+
+## Adding notes for a new release
+
+1. Create `<version>.md` in this directory (e.g. `0.7.0.md`).
+2. Write plain text — the content is printed verbatim. Start the body
+   with a line like `Migration notes for akm v0.7.0`, then list the
+   automatic migrations, manual actions, publisher changes, etc.
+3. The file ships with the published package via `package.json` →
+   `files[]` and is resolved at runtime from either `src/` or `dist/`,
+   so no code change is required.
+4. Link to the longform guide in the last paragraph if one exists.
+
+Keep each note self-contained: it should tell a user everything they
+need to upgrade without requiring them to open a browser (the longform
+guide link is the last resort, not the first).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akm-cli",
-  "version": "0.5.0",
+  "version": "0.6.0-rc1",
   "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": [
@@ -35,7 +35,8 @@
     "dist",
     "README.md",
     "CHANGELOG.md",
-    "LICENSE"
+    "LICENSE",
+    "docs/migration/release-notes"
   ],
   "bin": {
     "akm": "dist/cli.js"