akm-cli/docs/migration/release-notes/0.6.0.md

akm (Agent Knowledge Manager) — a portable, local-first capability library for AI agents. Discover, load, share, and improve reusable skills, scripts, workflows, and knowledge across any shell-capable coding agent, including Claude Code, OpenCode, and Cur

Migration notes for akm v0.6.0

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`.
- Registry results are off by default in `akm search`; pass
  `--include-registry` (or `--source registry|both`) to include them.
- Write target resolves as: `--target` flag → `defaultWriteTarget` config
  key → `stashDir` (working stash) → `ConfigError`.
- `writable: true` on `website` / `npm` is rejected at config load.

Manual actions required:
- If your config contains an `openviking` source, remove it. akm exits at
  load with `ConfigError` and points to `akm config sources remove <name>`.
  API-backed sources will return as a separate `QuerySource` tier post-v1.
- If your config sets `writable: true` on a `website` or `npm` source,
  drop the flag or re-add the path as a `filesystem` source.
- If you previously ran `akm enable context-hub` / `akm disable
  context-hub`, those toggles are gone. Add Context Hub as a regular git
  source with `akm add github:andrewyng/context-hub`, or list it as a kit
  entry in your registry.

Automatic (no action required):
- Config key `stashes[]` is loaded as `sources[]` with one deprecation
  warning. The new key is persisted on the next `akm config` write.
- `stash.lock` is renamed to `akm.lock` on startup.
- `config.installed[]` entries are mapped to `config.sources[]` plus
  `akm.lock` records.
- `stashDir` is loaded as an implicit `primary: true` filesystem source.
- Stash type aliases `"context-hub"` and `"github"` normalize to `"git"`.

What changed under the hood (no user impact):
- `SourceProvider` interface simplified to `{ name, kind, init, path,
  sync? }`. Plugin authors should re-read the v1 spec.
- Search and show consult the unified FTS5 index and read files from
  disk; the per-provider fan-out is gone.
- Single write helper (`writeAssetToSource`) handles filesystem and git
  destinations.
- Error classes own their `hint()` text. Hints now print to stderr inline
  without `--verbose`.
- Registry providers (`static-index`, `skills-sh`) loop through a uniform
  interface; the Context Hub special case was deleted.
- `src/` reorganized into purpose-named subdirectories (`commands/`,
  `core/`, `indexer/`, `output/`, `registry/`, `setup/`, `sources/`,
  `wiki/`, `workflows/`). akm has no public API, so external consumers
  are unaffected.
- Removed legacy re-export shims: `src/llm.ts`, `src/registry-provider.ts`,
  `src/ripgrep.ts`.

Earlier-in-cycle terminology cut (still applies):
- The registry wire format `kits[]` is renamed to `stashes[]` with schema
  bumped to v3. `akm-cli >= 0.6.0` only parses v3 indexes.
- npm packages and GitHub repos are discovered via the `akm-stash`
  keyword/topic only. `akm-kit` and `agentikit` are no longer honored.
- Internal types: `RegistryKitEntry` → `RegistryStashEntry`,
  `InstalledKitEntry` → `InstalledStashEntry`,
  `KitInstallStatus` → `StashInstallStatus`, `KitSource` → `StashSource`.
- Documentation: `docs/kit-makers.md` → `docs/stash-makers.md`.

CLI command surface (unchanged in 0.6.0):
add | remove | list | update | search | show | clone | index | setup |
remember | import | feedback | registry * | info | curate | workflow |
vault | wiki | enable | disable | completions | upgrade | save | help |
hints

Full migration guides:
- https://github.com/itlackey/akm/blob/main/docs/archive/pre-1.0-migration.md (pre-1.0
  architecture refactor — read this first if you are coming from 0.5.x or
  an earlier 0.6 pre-release)
- https://github.com/itlackey/akm/blob/main/docs/migration/v0.5-to-v0.6.md
  (terminology cut, registry schema v3, publisher changes)