akm-cli 0.9.0-rc.8 → 0.9.0

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "akm-cli",
-  "version": "0.9.0-rc.8",
+  "version": "0.9.0",
   "type": "module",
-  "description": "akm (Agent Knowledge Management) — A package manager for AI agent skills, commands, tools, and knowledge. Works with Claude Code, OpenCode, Cursor, and any AI coding assistant.",
+  "description": "akm (Agent Knowledge Manager) — A knowledge toolkit for AI agents: capture, curate, search, and share skills, commands, tools, and knowledge. Works with Claude Code, OpenCode, Cursor, and any AI coding assistant.",
   "keywords": [
     "akm",
     "agent-knowledge-management",
@@ -33,26 +33,31 @@
   },
   "license": "MPL-2.0",
   "pinNotes": {
-    "@opencode-ai/sdk@1.2.20": "Exact pin. The SDK surface we use (createOpencode + session.create/prompt/delete in src/integrations/agent/sdk-runner.ts) is stable across 1.x, but the SDK has shipped 5+ minor versions of unrelated provider/registry churn. akm-cli is a global CLI install so the pin is isolated from user-project deps. Re-test sdk-runner before bumping."
+    "@opencode-ai/sdk@1.2.20": "Exact pin. The SDK surface we use (createOpencodeClient + session.create/prompt/delete in src/integrations/harnesses/opencode-sdk/sdk-runner.ts) is stable across 1.x, but the SDK has shipped 5+ minor versions of unrelated provider/registry churn. akm-cli is a global CLI install so the pin is isolated from user-project deps. Re-test sdk-runner before bumping. Note this package is an HTTP client only — it declares no dependencies and its own createOpencodeServer spawns `opencode serve` — so it does NOT make the opencode binary available; that install is separate and is what every SDK-path probe checks for."
   },
   "files": [
     "dist",
     "README.md",
     "CHANGELOG.md",
     "SECURITY.md",
+    "STABILITY.md",
     "LICENSE",
     "docs/migration/release-notes",
     "docs/migration/v0.7-to-v0.8.md",
     "docs/migration/v0.8-to-v0.9.md",
+    "docs/migration/v0.9.0-troubleshooting.md",
+    "docs/reference/cli.md",
+    "docs/reference/configuration.md",
     "docs/reference/data-and-telemetry.md",
+    "docs/reference/workflows.md",
     "schemas"
   ],
   "bin": {
     "akm": "dist/akm",
-    "akm-migrate-storage": "dist/akm-migrate-storage"
+    "akm-migrate": "dist/akm-migrate"
   },
   "scripts": {
-    "preinstall": "node -e \"var v=(process.versions.node||'0').split('.').map(function(n){return parseInt(n,10)||0});var ok=v[0]>=22;if(ok){process.exit(0)}console.error('\\n  ERROR: the akm-cli npm package requires Node.js >= 22.\\n  A working Bun >= 1.0 on PATH is optional and preferred for execution.\\n  Upgrade Node.js (https://nodejs.org), or install the runtime-free standalone binary:\\n    curl -fsSL https://github.com/itlackey/akm/releases/latest/download/install.sh | bash\\n');process.exit(1)\"",
+    "preinstall": "node -e \"var v=(process.versions.node||'0').split('.').map(function(n){return parseInt(n,10)||0});var ok=v[0]>=22;if(ok){process.exit(0)}console.error('\\n  ERROR: the akm-cli npm package requires Node.js >= 22.\\n  A working Bun >= 1.0 on PATH is optional and preferred for akm and akm-migrate.\\n  Upgrade Node.js (https://nodejs.org), or install the runtime-free standalone binary:\\n    curl -fsSL https://github.com/itlackey/akm/releases/latest/download/install.sh | bash\\n');process.exit(1)\"",
     "build": "rm -rf dist && bun scripts/gen-config-schema.ts &&bun run tsc --project ./tsconfig.build.json && bun scripts/copy-assets.ts && bun scripts/fix-esm-extensions.ts",
     "check": "bun run lint && bunx tsc --noEmit && bun run test:unit && bun run test:integration",
     "check:fast": "bun run lint && bunx tsc --noEmit && bun run test:unit",
@@ -65,29 +70,33 @@
     "test:node-compat": "AKM_NODE_COMPAT_TESTS=1 bun test --timeout=120000 tests/integration/node-compat.test.ts",
     "test:time": "bun scripts/test-timing-report.ts",
     "lint:isolation": "bun scripts/lint-tests-isolation.ts",
+    "lint:doc-examples": "bun scripts/lint-doc-examples.ts",
     "lint:devto-posts": "bun scripts/lint-devto-posts.ts",
     "lint:devto-posts:fix": "bun scripts/lint-devto-posts.ts --fix",
     "publish:devto": "npx -y @sinedied/devto-cli push \"docs/posts/**/*.md\" --token \"$DEVTO_TOKEN\" --repo \"$GITHUB_REPOSITORY\" --branch \"${GITHUB_REF_NAME:-main}\" --reconcile",
     "release:check": "./tests/release-check.sh",
-    "lint": "bunx biome check src/ tests/ scripts/ && bun scripts/lint-tests-isolation.ts && bun scripts/lint-license-headers.ts && bun scripts/lint-runtime-boundary.ts && bun scripts/lint-process-argv.ts && bun scripts/lint-repository-sql.ts && bun scripts/lint-goldens-presence.ts && bun scripts/lint-test-ref-literals.ts && bun scripts/lint-shipped-assets.ts && bun scripts/gen-config-schema.ts --check",
+    "lint": "bunx biome check src/ tests/ scripts/ && bun scripts/lint-tests-isolation.ts && bun scripts/lint-license-headers.ts && bun scripts/lint-runtime-boundary.ts && bun scripts/lint-write-source-chokepoint.ts && bun scripts/lint-secret-resolver-boundary.ts && bun scripts/lint-process-argv.ts && bun scripts/lint-repository-sql.ts && bun scripts/lint-goldens-presence.ts && bun scripts/lint-golden-captured-at-head.ts && bun scripts/lint-test-ref-literals.ts && bun scripts/lint-shipped-assets.ts && bun scripts/lint-doc-examples.ts && bun scripts/gen-config-schema.ts --check",
     "lint:runtime-boundary": "bun scripts/lint-runtime-boundary.ts",
     "lint:tests-isolation": "bun scripts/lint-tests-isolation.ts",
     "lint:fix": "bunx biome check --write src/ tests/ scripts/",
     "format": "bunx biome format --write src/ tests/ scripts/",
     "prepublishOnly": "cp .github/README.npm.md README.md && bun run build",
-    "postpublish": "git checkout -- README.md"
+    "postpublish": "git checkout -- README.md",
+    "build:install": "bun scripts/package-install.ts install-global",
+    "test:package": "bun scripts/package-install.ts test-package"
   },
   "publishConfig": {
     "access": "public"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.14",
-    "@types/better-sqlite3": "^7.6.11",
     "@types/node": "^22.19.17",
     "@types/semver": "^7.5.8",
+    "@types/turndown": "^5.0.6",
     "bun-types": "^1.3.13",
     "cmd-shim": "9.0.2",
-    "typescript": "^5.9.3"
+    "typescript": "^5.9.3",
+    "zod-to-json-schema": "^3.23.0"
   },
   "optionalDependencies": {
     "@huggingface/transformers": "^4.2.0",
@@ -102,9 +111,11 @@
     "@opencode-ai/sdk": "1.2.20",
     "citty": "^0.2.2",
     "dotenv": "^17.4.2",
+    "fast-xml-parser": "^5.10.1",
+    "node-html-parser": "^9.0.1",
     "semver": "^7.6.0",
+    "turndown": "^7.2.4",
     "yaml": "^2.8.4",
-    "zod": "^3.23.0",
-    "zod-to-json-schema": "^3.23.0"
+    "zod": "^3.23.0"
   }
 }

package/schemas/akm-asset-envelope.json

@@ -0,0 +1,93 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://itlackey.github.io/akm/schemas/akm-asset-envelope.json",
+  "title": "AKM Markdown Asset Envelope",
+  "description": "The common frontmatter envelope every AKM markdown asset type carries: type/description/tags/when_to_use/xrefs/updated/timestamp, plus the OKF v0.2 machine-stamped families (generated/verified/provenance/status/stale_after). Per-type schemas (e.g. akm-workflow.json) $ref these definitions individually into their own top-level `properties` so `additionalProperties: false` still sees them declared locally (JSON Schema does not merge `allOf` siblings' properties for that check). This file has no `properties`/`required` of its own — it is a definitions-only library.",
+  "definitions": {
+    "type": {
+      "type": "string",
+      "minLength": 1,
+      "description": "The asset's type token (e.g. \"workflow\"). Drives recognition alongside directory residence."
+    },
+    "description": {
+      "type": "string",
+      "description": "Human-readable summary of the asset."
+    },
+    "tags": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "description": "Free-form search/classification tags."
+    },
+    "when_to_use": {
+      "type": "string",
+      "description": "Guidance on when this asset should be applied/selected."
+    },
+    "xrefs": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "description": "Canonical asset refs this asset cross-references. Ref canonicality is checked by semantic validation, not this schema."
+    },
+    "updated": {
+      "type": "string",
+      "description": "Last-updated timestamp (author-maintained)."
+    },
+    "timestamp": {
+      "type": "string",
+      "description": "Legacy creation/authoring timestamp, pre-dating OKF v0.2's `generated:`."
+    },
+    "actorStamp": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["by"],
+      "properties": {
+        "by": { "type": "string", "minLength": 1 },
+        "at": { "type": "string" }
+      },
+      "description": "One OKF v0.2 actor stamp: who (by) and, usually, when (at)."
+    },
+    "generated": {
+      "$ref": "#/definitions/actorStamp",
+      "description": "OKF v0.2 machine-stamped authorship — the replacement for the legacy `timestamp` key."
+    },
+    "verified": {
+      "anyOf": [
+        { "$ref": "#/definitions/actorStamp" },
+        { "type": "array", "items": { "$ref": "#/definitions/actorStamp" } }
+      ],
+      "description": "OKF v0.2 machine-stamped verification(s). A bare mapping or a list of them; independent confirmations accumulate."
+    },
+    "provenanceSource": {
+      "type": "object",
+      "required": ["resource"],
+      "additionalProperties": true,
+      "properties": {
+        "resource": { "type": "string", "minLength": 1 },
+        "id": { "type": "string" },
+        "title": { "type": "string" },
+        "author": { "type": "string" },
+        "usage_count": { "type": "number" },
+        "last_modified": { "type": "string" }
+      }
+    },
+    "provenance": {
+      "type": "object",
+      "additionalProperties": true,
+      "properties": {
+        "sources": {
+          "type": "array",
+          "items": { "$ref": "#/definitions/provenanceSource" }
+        }
+      },
+      "description": "Namespaced OKF v0.2 provenance (kept nested because a bare top-level `sources:` collides with the AKM-native wiki citation-string convention)."
+    },
+    "status": {
+      "enum": ["draft", "stable", "deprecated"],
+      "description": "OKF v0.2 lifecycle status."
+    },
+    "stale_after": {
+      "type": "string",
+      "minLength": 1,
+      "description": "OKF v0.2 staleness horizon (a date or duration, author-maintained)."
+    }
+  }
+}

package/schemas/akm-config.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://itlackey.github.io/akm/schemas/akm-config.0.9.0.json",
   "title": "AKM Configuration",
-  "description": "Configuration file for the akm CLI (Agent Knowledge Management). Stored at ~/.config/akm/config.json (Linux/macOS) or %APPDATA%\\akm\\config.json (Windows). Supports JSONC (JavaScript-style comments). Auto-generated from src/core/config-schema.ts by scripts/gen-config-schema.ts — do NOT edit by hand.",
+  "description": "Configuration file for the akm CLI (Agent Knowledge Manager). Stored at ~/.config/akm/config.json (Linux/macOS) or %APPDATA%\\akm\\config.json (Windows). Supports JSONC (JavaScript-style comments). Auto-generated from src/core/config/config-schema.ts by scripts/gen-config-schema.ts — do NOT edit by hand.",
   "type": "object",
   "properties": {
     "configVersion": {
@@ -201,7 +201,7 @@
         "off",
         "auto"
       ],
-      "default": "auto"
+      "default": "off"
     },
     "embedding": {
       "type": "object",
@@ -221,7 +221,8 @@
         },
         "dimension": {
           "type": "integer",
-          "exclusiveMinimum": 0
+          "exclusiveMinimum": 0,
+          "maximum": 4096
         },
         "localModel": {
           "type": "string",
@@ -321,22 +322,9 @@
           },
           "additionalProperties": true
         },
-        "stalenessDetection": {
-          "type": "object",
-          "properties": {
-            "enabled": {
-              "type": "boolean"
-            },
-            "thresholdDays": {
-              "type": "integer",
-              "exclusiveMinimum": 0
-            }
-          },
-          "additionalProperties": true
-        },
         "indexBodyOpening": {
           "type": "boolean",
-          "description": "Index the first prose paragraph of each markdown asset body (capped at 280 chars) into the lowest-weight `content` search column and the embedding text (default false). Secret/env files and session-kind memories are never captured. Toggling the flag changes indexed text: run `akm index --full` afterwards to re-extract every entry and regenerate embeddings, and re-mint collapse-detector canary baselines via `akm improve canary --refresh`."
+          "description": "Index the first prose paragraph of each markdown asset body (capped at 280 chars) into the lowest-weight `content` search column and the embedding text (default false). Secret/env files and session-kind memories are never captured. Toggling the flag changes indexed text: run `akm index --full` afterwards to re-extract every entry and regenerate embeddings, and re-mint collapse-detector canary baselines via `bun scripts/refresh-canary-set.ts --refresh`."
         }
       },
       "additionalProperties": {
@@ -471,6 +459,13 @@
               "maxDepth": {
                 "type": "integer",
                 "exclusiveMinimum": 0
+              },
+              "respectRobots": {
+                "type": "boolean"
+              },
+              "crawlTimeoutMs": {
+                "type": "integer",
+                "minimum": 0
               }
             },
             "required": [
@@ -485,6 +480,9 @@
           "writable": {
             "type": "boolean"
           },
+          "enabled": {
+            "type": "boolean"
+          },
           "registryId": {
             "type": "string",
             "minLength": 1
@@ -528,7 +526,10 @@
           "enum": [
             "json",
             "yaml",
-            "text"
+            "text",
+            "jsonl",
+            "md",
+            "html"
           ]
         },
         "detail": {
@@ -542,9 +543,6 @@
       },
       "additionalProperties": true
     },
-    "writable": {
-      "type": "boolean"
-    },
     "defaultWriteTarget": {
       "type": "string",
       "minLength": 1
@@ -1507,9 +1505,6 @@
                 "type": "integer",
                 "exclusiveMinimum": 0
               },
-              "symmetricValence": {
-                "type": "boolean"
-              },
               "sync": {
                 "type": "object",
                 "properties": {
@@ -1601,16 +1596,21 @@
               "minimum": 0,
               "maximum": 1
             },
-            "churnMinAcceptedActions": {
-              "type": "integer",
-              "minimum": 1
-            },
             "retentionDays": {
               "type": "integer",
               "minimum": 1
             }
           },
           "additionalProperties": true
+        },
+        "stateGc": {
+          "type": "object",
+          "properties": {
+            "collect": {
+              "type": "boolean"
+            }
+          },
+          "additionalProperties": true
         }
       },
       "additionalProperties": true
@@ -1621,26 +1621,25 @@
         "maxConcurrency": {
           "type": "integer",
           "exclusiveMinimum": 0
+        },
+        "judgeEngine": {
+          "type": "string",
+          "maxLength": 63,
+          "pattern": "^(?!akm-)[a-z][a-z0-9]*(?:-[a-z0-9]+)*$"
         }
       },
       "additionalProperties": true
     },
     "setup": {
+      "type": "object",
+      "properties": {},
+      "additionalProperties": true
+    },
+    "experimental": {
       "type": "object",
       "properties": {
-        "taskSchedules": {
-          "type": "object",
-          "properties": {
-            "improve": {
-              "type": "string",
-              "minLength": 1
-            },
-            "index": {
-              "type": "string",
-              "minLength": 1
-            }
-          },
-          "additionalProperties": true
+        "improveAutonomy": {
+          "type": "boolean"
         }
       },
       "additionalProperties": true
@@ -1850,7 +1849,7 @@
             "off",
             "auto"
           ],
-          "default": "auto"
+          "default": "off"
         },
         "embedding": {
           "type": "object",
@@ -1870,7 +1869,8 @@
             },
             "dimension": {
               "type": "integer",
-              "exclusiveMinimum": 0
+              "exclusiveMinimum": 0,
+              "maximum": 4096
             },
             "localModel": {
               "type": "string",
@@ -1970,22 +1970,9 @@
               },
               "additionalProperties": true
             },
-            "stalenessDetection": {
-              "type": "object",
-              "properties": {
-                "enabled": {
-                  "type": "boolean"
-                },
-                "thresholdDays": {
-                  "type": "integer",
-                  "exclusiveMinimum": 0
-                }
-              },
-              "additionalProperties": true
-            },
             "indexBodyOpening": {
               "type": "boolean",
-              "description": "Index the first prose paragraph of each markdown asset body (capped at 280 chars) into the lowest-weight `content` search column and the embedding text (default false). Secret/env files and session-kind memories are never captured. Toggling the flag changes indexed text: run `akm index --full` afterwards to re-extract every entry and regenerate embeddings, and re-mint collapse-detector canary baselines via `akm improve canary --refresh`."
+              "description": "Index the first prose paragraph of each markdown asset body (capped at 280 chars) into the lowest-weight `content` search column and the embedding text (default false). Secret/env files and session-kind memories are never captured. Toggling the flag changes indexed text: run `akm index --full` afterwards to re-extract every entry and regenerate embeddings, and re-mint collapse-detector canary baselines via `bun scripts/refresh-canary-set.ts --refresh`."
             }
           },
           "additionalProperties": {
@@ -2120,6 +2107,13 @@
                   "maxDepth": {
                     "type": "integer",
                     "exclusiveMinimum": 0
+                  },
+                  "respectRobots": {
+                    "type": "boolean"
+                  },
+                  "crawlTimeoutMs": {
+                    "type": "integer",
+                    "minimum": 0
                   }
                 },
                 "required": [
@@ -2134,6 +2128,9 @@
               "writable": {
                 "type": "boolean"
               },
+              "enabled": {
+                "type": "boolean"
+              },
               "registryId": {
                 "type": "string",
                 "minLength": 1
@@ -2177,7 +2174,10 @@
               "enum": [
                 "json",
                 "yaml",
-                "text"
+                "text",
+                "jsonl",
+                "md",
+                "html"
               ]
             },
             "detail": {
@@ -2191,9 +2191,6 @@
           },
           "additionalProperties": true
         },
-        "writable": {
-          "type": "boolean"
-        },
         "defaultWriteTarget": {
           "type": "string",
           "minLength": 1
@@ -3156,9 +3153,6 @@
                     "type": "integer",
                     "exclusiveMinimum": 0
                   },
-                  "symmetricValence": {
-                    "type": "boolean"
-                  },
                   "sync": {
                     "type": "object",
                     "properties": {
@@ -3250,16 +3244,21 @@
                   "minimum": 0,
                   "maximum": 1
                 },
-                "churnMinAcceptedActions": {
-                  "type": "integer",
-                  "minimum": 1
-                },
                 "retentionDays": {
                   "type": "integer",
                   "minimum": 1
                 }
               },
               "additionalProperties": true
+            },
+            "stateGc": {
+              "type": "object",
+              "properties": {
+                "collect": {
+                  "type": "boolean"
+                }
+              },
+              "additionalProperties": true
             }
           },
           "additionalProperties": true
@@ -3270,26 +3269,25 @@
             "maxConcurrency": {
               "type": "integer",
               "exclusiveMinimum": 0
+            },
+            "judgeEngine": {
+              "type": "string",
+              "maxLength": 63,
+              "pattern": "^(?!akm-)[a-z][a-z0-9]*(?:-[a-z0-9]+)*$"
             }
           },
           "additionalProperties": true
         },
         "setup": {
+          "type": "object",
+          "properties": {},
+          "additionalProperties": true
+        },
+        "experimental": {
           "type": "object",
           "properties": {
-            "taskSchedules": {
-              "type": "object",
-              "properties": {
-                "improve": {
-                  "type": "string",
-                  "minLength": 1
-                },
-                "index": {
-                  "type": "string",
-                  "minLength": 1
-                }
-              },
-              "additionalProperties": true
+            "improveAutonomy": {
+              "type": "boolean"
             }
           },
           "additionalProperties": true
@@ -3385,7 +3383,8 @@
         },
         "dimension": {
           "type": "integer",
-          "exclusiveMinimum": 0
+          "exclusiveMinimum": 0,
+          "maximum": 4096
         },
         "localModel": {
           "type": "string",
@@ -4608,9 +4607,6 @@
           "type": "integer",
           "exclusiveMinimum": 0
         },
-        "symmetricValence": {
-          "type": "boolean"
-        },
         "sync": {
           "type": "object",
           "properties": {
@@ -4656,49 +4652,6 @@
         "url"
       ],
       "additionalProperties": true
-    },
-    "StashConfigEntry": {
-      "type": "object",
-      "properties": {
-        "type": {
-          "type": "string",
-          "minLength": 1
-        },
-        "path": {
-          "type": "string",
-          "minLength": 1
-        },
-        "url": {
-          "type": "string",
-          "minLength": 1
-        },
-        "name": {
-          "type": "string",
-          "minLength": 1
-        },
-        "enabled": {
-          "type": "boolean"
-        },
-        "writable": {
-          "type": "boolean"
-        },
-        "primary": {
-          "type": "boolean"
-        },
-        "options": {
-          "type": "object",
-          "properties": {
-            "pushOnCommit": {
-              "type": "boolean"
-            }
-          },
-          "additionalProperties": true
-        }
-      },
-      "required": [
-        "type"
-      ],
-      "additionalProperties": true
     }
   }
 }