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 SourceRefs 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)