akm-cli/docs/migration/release-notes/0.9.16.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.9.16

Scheduled execution is now authorized by host-local config and bound to the
specific source installed under a bundle id. Existing
`scheduler.enabled` entries need a `sourceId` before the 0.9.16 runtime will
load them. Run this once after upgrading:

```sh
akm migrate apply
akm task sync
```

The migrator binds each existing grant to the bundle source currently in
config, drops grants whose bundle no longer exists, and writes a config backup
before changing the file. `akm migrate status` and `akm migrate apply
--dry-run` report this as a blocking migration because silently trusting a new
source would defeat the boundary. Task frontmatter cannot enable scheduling.
Use `akm task enable <bundle//tasks/name>` or `akm task disable ...`; a plain
`akm task sync` reconciles all enabled bundles and removes installed entries
for bundles that have since been disabled.

Replacing a bundle's source locator or component root invalidates its old
scheduler grants. Re-enable the reviewed task after the replacement. Normal
content updates, adapter detection, and website crawl-policy changes keep the
same source identity.
Removing a bundle revokes all grants owned by that bundle. A bundle with
`enabled: false` is inert for content reads, writes, indexing, execution, and
scheduling, and it cannot remain `defaultBundle` or `defaultWriteTarget`.
Explicit lifecycle operations such as `akm bundle update <name>` may still
refresh a disabled bundle without activating its content.

Two bundle ids may no longer point at the same physical content root, including
through symbolic links. This alias is not safe to rewrite automatically because
durable refs name the bundle id. Keep the id whose refs should survive and
remove the duplicate config entry; config errors name both ids and the shared
root.

Config inheritance now has a portable-data boundary. An inherited config may
supply ordinary portable settings, including engine endpoint and model fields,
but host authority is always local. Inherited bundle/default declarations,
scheduler grants, execution policy, credentials, executable paths/arguments,
setup state, registry declarations, and write-capable strategy hooks are
ignored with a warning. Bundle-relative `extends` paths are checked against
the bundle's physical root, including every link in an extends chain.

Commands and personas can no longer set `workspace`, `environment`, or
`runtime` in frontmatter. Those values select host execution context and now
produce a configuration error. Asset-requested tools are constrained by the
local allowlist:

```json
{
  "execution": {
    "allowedTools": ["read_file", "search"]
  }
}
```

Use `"*"` only when every asset the host may execute is trusted. If an asset
requests tools that the selected transport cannot enforce, akm fails before
dispatch instead of sending an over-privileged request.

The old combined `--allow-insecure` switch has been removed. The two unrelated
decisions are now explicit:

- `--allow-insecure-transport` permits a reviewed plain-HTTP bundle or
  registry endpoint.
- `--allow-dangerous-env-keys` permits reviewed dangerous environment-key
  findings during bundle add/update or env activation.

Update scripts to use the narrow flag that matches the risk being accepted.
Neither flag implies the other.