npm - akm-cli - Versions diffs - 0.9.0-rc.1 → 0.9.0-rc.14 - Mend

akm-cli 0.9.0-rc.1 → 0.9.0-rc.14

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (601) hide show

package/CHANGELOG.md +1284 -52
package/README.md +62 -37
package/SECURITY.md +46 -31
package/dist/akm +162 -38
package/dist/akm-migrate +46 -0
package/dist/assets/backends/schtasks-template.xml +2 -1
package/dist/assets/hints/cli-hints-full.md +267 -118
package/dist/assets/hints/cli-hints-short.md +89 -26
package/dist/assets/{profiles → improve-strategies}/catchup.json +3 -1
package/dist/assets/{profiles → improve-strategies}/consolidate.json +3 -1
package/dist/assets/{profiles → improve-strategies}/default.json +6 -7
package/dist/assets/improve-strategies/frequent.json +15 -0
package/dist/assets/{profiles → improve-strategies}/graph-refresh.json +4 -2
package/dist/assets/{profiles → improve-strategies}/memory-focus.json +4 -1
package/dist/assets/{profiles → improve-strategies}/proactive-maintenance.json +5 -5
package/dist/assets/{profiles → improve-strategies}/quick.json +4 -2
package/dist/assets/improve-strategies/reflect-distill.json +30 -0
package/dist/assets/{profiles → improve-strategies}/thorough.json +1 -1
package/dist/assets/prompts/consolidate-system.md +5 -5
package/dist/assets/prompts/extract-session.md +2 -6
package/dist/assets/prompts/memory-infer-user.md +2 -3
package/dist/assets/prompts/reflect-llm-framed-contract.md +11 -0
package/dist/assets/prompts/reflect-llm-schema-contract.md +3 -0
package/dist/assets/prompts/reflect-output-repair.md +3 -0
package/dist/assets/stash-skeleton/README.md +38 -10
package/dist/assets/stash-skeleton/facts/conventions/assets/agent.md +8 -0
package/dist/assets/stash-skeleton/facts/conventions/assets/command.md +8 -0
package/dist/assets/stash-skeleton/facts/conventions/assets/fact.md +14 -1
package/dist/assets/stash-skeleton/facts/conventions/assets/knowledge.md +13 -1
package/dist/assets/stash-skeleton/facts/conventions/assets/lesson.md +9 -1
package/dist/assets/stash-skeleton/facts/conventions/assets/memory.md +11 -0
package/dist/assets/stash-skeleton/facts/conventions/assets/script.md +9 -0
package/dist/assets/stash-skeleton/facts/conventions/assets/skill.md +9 -0
package/dist/assets/stash-skeleton/facts/conventions/assets/workflow.md +8 -0
package/dist/assets/stash-skeleton/facts/conventions/backlinks.md +100 -0
package/dist/assets/stash-skeleton/facts/conventions/domains.md +64 -0
package/dist/assets/stash-skeleton/facts/conventions/organization.md +136 -0
package/dist/assets/tasks/core/extract.yml +3 -2
package/dist/assets/tasks/core/improve.yml +2 -1
package/dist/assets/tasks/core/index-refresh.yml +1 -0
package/dist/assets/tasks/core/sync.yml +1 -0
package/dist/assets/tasks/core/version-check.yml +2 -1
package/dist/assets/tasks/improve/akm-graph-refresh-weekly.yml +5 -0
package/dist/assets/tasks/improve/akm-improve-catchup.yml +8 -0
package/dist/assets/tasks/improve/akm-improve-consolidate.yml +5 -0
package/dist/assets/tasks/improve/akm-improve-frequent.yml +5 -0
package/dist/assets/tasks/improve/akm-improve-nightly.yml +5 -0
package/dist/assets/templates/html/health.html +5 -4
package/dist/assets/workflows/workflow-template.md +32 -15
package/dist/cli/invocation.js +280 -0
package/dist/cli/parse-args.js +5 -90
package/dist/cli/retired-commands.js +81 -0
package/dist/cli/shared.js +158 -48
package/dist/cli/unknown-flags.js +226 -0
package/dist/cli-node.mjs +2 -1
package/dist/cli.js +732 -294
package/dist/commands/agent/agent-dispatch.js +19 -18
package/dist/commands/agent/agent-support.js +0 -24
package/dist/commands/agent/contribute-cli.js +58 -100
package/dist/commands/completions.js +80 -23
package/dist/commands/config-cli.js +44 -281
package/dist/commands/env/env-binding.js +13 -9
package/dist/commands/env/env-cli.js +76 -159
package/dist/commands/env/env.js +12 -163
package/dist/commands/env/marker-path.js +6 -0
package/dist/commands/env/secret-cli.js +45 -61
package/dist/commands/env/secret.js +32 -62
package/dist/commands/feedback-cli.js +185 -88
package/dist/commands/health/accept-rate.js +58 -0
package/dist/commands/health/advisories.js +7 -8
package/dist/commands/health/checks.js +279 -94
package/dist/commands/health/html-report.js +197 -578
package/dist/commands/health/improve-metrics.js +277 -246
package/dist/commands/health/llm-usage.js +19 -19
package/dist/commands/health/md-report.js +16 -7
package/dist/commands/health/metrics.js +67 -32
package/dist/commands/health/renderers.js +47 -0
package/dist/commands/health/report-view-model.js +508 -0
package/dist/commands/health/stash-exposure.js +1 -1
package/dist/commands/health/surfaces.js +16 -56
package/dist/commands/health/task-runs.js +3 -67
package/dist/{migrate-storage-node.mjs → commands/health/types-checks.js} +1 -5
package/dist/commands/health/types-improve.js +29 -0
package/dist/{output/text/save.js → commands/health/types-metrics.js} +1 -2
package/dist/commands/health/types-result.js +7 -0
package/dist/commands/health/types-runs.js +4 -0
package/dist/commands/health/types-session-log.js +4 -0
package/dist/commands/health/types-windows.js +4 -0
package/dist/commands/health/types.js +26 -21
package/dist/commands/health/windows.js +2 -3
package/dist/commands/health.js +296 -167
package/dist/commands/improve/anti-collapse.js +5 -5
package/dist/commands/improve/autonomy-gate.js +68 -0
package/dist/commands/improve/collapse-detector.js +64 -52
package/dist/commands/improve/consolidate/chunking.js +9 -7
package/dist/commands/improve/consolidate/eligibility.js +1 -23
package/dist/commands/improve/consolidate/merge.js +4 -0
package/dist/commands/improve/consolidate.js +454 -1354
package/dist/commands/improve/content-hash.js +39 -0
package/dist/commands/improve/distill/content-repair.js +4 -10
package/dist/commands/improve/distill/promote-memory.js +89 -64
package/dist/commands/improve/distill/quality-gate.js +118 -42
package/dist/commands/improve/distill-guards.js +1 -1
package/dist/commands/improve/distill-promotion-policy.js +33 -888
package/dist/commands/improve/distill.js +607 -363
package/dist/commands/improve/eligibility.js +165 -79
package/dist/commands/improve/extract-cli.js +35 -126
package/dist/commands/improve/extract-prompt.js +6 -35
package/dist/commands/improve/extract.js +640 -391
package/dist/commands/improve/feedback-valence.js +2 -12
package/dist/commands/improve/improve-cli.js +134 -135
package/dist/commands/improve/improve-result-file.js +30 -50
package/dist/commands/improve/improve-run-types.js +4 -0
package/dist/commands/improve/improve-strategies.js +135 -0
package/dist/commands/improve/improve.js +904 -701
package/dist/commands/improve/locks.js +64 -111
package/dist/commands/improve/loop-stages.js +1110 -923
package/dist/commands/improve/memory/derived-ref.js +124 -0
package/dist/commands/improve/memory/memory-belief.js +79 -7
package/dist/commands/improve/memory/memory-contradiction-detect.js +49 -52
package/dist/commands/improve/memory/memory-improve.js +25 -37
package/dist/commands/improve/outcome-loop.js +25 -88
package/dist/commands/improve/preparation.js +1034 -813
package/dist/commands/improve/proactive-maintenance.js +34 -9
package/dist/commands/improve/proposal-envelope.js +31 -0
package/dist/commands/improve/reflect.js +983 -794
package/dist/commands/improve/run-context.js +119 -0
package/dist/commands/improve/salience.js +24 -127
package/dist/commands/improve/session-asset.js +7 -3
package/dist/commands/improve/shared.js +14 -34
package/dist/commands/improve/source-identity.js +28 -0
package/dist/commands/improve/triage.js +20 -17
package/dist/commands/lint/base-linter.js +343 -328
package/dist/commands/lint/env-key-rules.js +31 -47
package/dist/commands/lint/index.js +198 -43
package/dist/commands/{events.js → log.js} +33 -38
package/dist/commands/migrate-cli.js +54 -0
package/dist/commands/migration-tool.js +54 -0
package/dist/commands/observability-cli.js +70 -208
package/dist/commands/proposal/diff-format.js +50 -0
package/dist/commands/proposal/drain-policies.js +0 -6
package/dist/commands/proposal/drain.js +91 -40
package/dist/commands/proposal/proposal-cli.js +134 -132
package/dist/commands/proposal/proposal-types.js +56 -0
package/dist/commands/proposal/proposal.js +83 -65
package/dist/commands/proposal/propose-cli.js +88 -0
package/dist/commands/proposal/propose.js +105 -88
package/dist/commands/proposal/repository.js +1306 -281
package/dist/commands/proposal/validators/proposal-quality-validators.js +16 -6
package/dist/commands/proposal/validators/proposal-validators.js +61 -12
package/dist/commands/proposal/validators/proposals.js +6 -8
package/dist/commands/read/curate.js +78 -73
package/dist/commands/read/knowledge.js +512 -13
package/dist/commands/read/registry-search.js +2 -2
package/dist/commands/read/remember-cli.js +84 -15
package/dist/commands/read/search-cli.js +203 -96
package/dist/commands/read/search.js +126 -94
package/dist/commands/read/show.js +226 -250
package/dist/commands/registry-cli.js +39 -63
package/dist/commands/remember.js +18 -57
package/dist/commands/sources/add-cli.js +110 -55
package/dist/commands/sources/bundle-cli.js +166 -0
package/dist/commands/sources/bundle-config-ops.js +63 -0
package/dist/commands/sources/info.js +27 -15
package/dist/commands/sources/init.js +30 -40
package/dist/commands/sources/installed-stashes.js +469 -172
package/dist/commands/sources/schema-repair.js +10 -9
package/dist/commands/sources/self-update.js +205 -121
package/dist/commands/sources/source-add.js +183 -177
package/dist/commands/sources/source-clone.js +144 -41
package/dist/commands/sources/source-manage.js +94 -59
package/dist/commands/sources/sources-cli.js +64 -205
package/dist/commands/sources/stash-cli.js +91 -54
package/dist/commands/sources/stash-skeleton.js +1 -1
package/dist/commands/tasks/tasks-cli.js +106 -104
package/dist/commands/tasks/tasks.js +451 -263
package/dist/commands/workflow-cli.js +195 -325
package/dist/core/action-contributors.js +1 -1
package/dist/core/activation-policy.js +49 -0
package/dist/core/adapter/adapters/agent-skills-adapter.js +181 -0
package/dist/core/adapter/adapters/akm-adapter.js +528 -0
package/dist/core/adapter/adapters/akm-lint.js +396 -0
package/dist/core/adapter/adapters/akm-metadata.js +387 -0
package/dist/core/adapter/adapters/akm-task-adapter.js +152 -0
package/dist/core/adapter/adapters/akm-workflow-adapter.js +180 -0
package/dist/core/adapter/adapters/claude-adapter.js +61 -0
package/dist/core/adapter/adapters/dotenv-adapter.js +187 -0
package/dist/core/adapter/adapters/generic-files-adapter.js +119 -0
package/dist/core/adapter/adapters/index.js +80 -0
package/dist/core/adapter/adapters/llm-wiki-adapter.js +419 -0
package/dist/core/adapter/adapters/okf-adapter.js +391 -0
package/dist/core/adapter/adapters/opencode-adapter.js +68 -0
package/dist/core/adapter/adapters/shared.js +286 -0
package/dist/core/adapter/adapters/tool-dir-shared.js +217 -0
package/dist/core/adapter/adapters/website-snapshot-adapter.js +155 -0
package/dist/core/adapter/bundle-adapter.js +4 -0
package/dist/core/adapter/detect-adapter.js +17 -0
package/dist/core/adapter/recognize-match.js +44 -0
package/dist/core/adapter/registry.js +56 -0
package/dist/core/adapter/types.js +4 -0
package/dist/core/asset/akm-markdown.js +63 -0
package/dist/core/asset/asset-placement.js +243 -0
package/dist/core/asset/asset-ref.js +110 -79
package/dist/core/asset/asset-serialize.js +20 -0
package/dist/core/asset/frontmatter.js +50 -12
package/dist/core/asset/markdown.js +40 -51
package/dist/core/asset/resolve-ref.js +294 -0
package/dist/core/asset/stash-meta.js +2 -2
package/dist/core/bundle-id.js +51 -0
package/dist/core/common.js +326 -88
package/dist/core/config/config-io.js +42 -128
package/dist/core/config/config-schema.js +241 -855
package/dist/core/config/config-sources.js +162 -39
package/dist/core/config/config-types.js +16 -11
package/dist/core/config/config-version.js +29 -0
package/dist/core/config/config-walker.js +126 -37
package/dist/core/config/config.js +154 -331
package/dist/core/config/deep-merge.js +41 -0
package/dist/core/config/engine-semantics.js +28 -0
package/dist/core/config/experimental.js +21 -0
package/dist/core/config/schema/embedding.js +38 -0
package/dist/core/config/schema/engines.js +116 -0
package/dist/core/config/schema/experimental.js +39 -0
package/dist/core/config/schema/feedback.js +31 -0
package/dist/core/config/schema/improve-processes.js +389 -0
package/dist/core/config/schema/improve.js +94 -0
package/dist/core/config/schema/index-config.js +176 -0
package/dist/core/config/schema/output.js +18 -0
package/dist/core/config/schema/primitives.js +94 -0
package/dist/core/config/schema/search.js +30 -0
package/dist/core/config/schema/setup.js +18 -0
package/dist/core/config/schema/sources-bundles.js +180 -0
package/dist/core/config/schema/workflow.js +31 -0
package/dist/core/env-secret-ref.js +155 -20
package/dist/core/errors.js +22 -15
package/dist/core/events-types.js +4 -0
package/dist/core/events.js +46 -128
package/dist/core/extra-params.js +62 -0
package/dist/core/file-change.js +17 -0
package/dist/core/file-lock.js +202 -57
package/dist/core/fs-txn.js +392 -0
package/dist/core/git-message.js +59 -0
package/dist/core/improve-result.js +167 -0
package/dist/core/lesson-lint.js +1 -17
package/dist/core/logs-db.js +3 -2
package/dist/core/maintenance-barrier.js +135 -0
package/dist/core/migration-operation.js +44 -0
package/dist/core/mutation-target.js +78 -0
package/dist/core/parse.js +4 -1
package/dist/core/paths.js +22 -25
package/dist/core/platform.js +10 -0
package/dist/core/recognition-util.js +128 -0
package/dist/core/redaction.js +392 -0
package/dist/core/standards/resolve-standards-context.js +36 -65
package/dist/core/standards/resolve-stash-standards.js +2 -2
package/dist/core/standards/resolve-type-conventions.js +5 -5
package/dist/core/state/migrations.js +242 -14
package/dist/core/state-db.js +96 -10
package/dist/core/structured.js +1 -1
package/dist/core/subprocess.js +305 -0
package/dist/core/text-truncation.js +9 -5
package/dist/core/time.js +20 -0
package/dist/core/type-presentation.js +130 -0
package/dist/core/warn.js +0 -3
package/dist/core/write-source.js +834 -118
package/dist/indexer/bundle-identity-guard.js +92 -0
package/dist/indexer/db/graph-db.js +1 -25
package/dist/indexer/db/llm-cache.js +1 -1
package/dist/indexer/ensure-index.js +30 -9
package/dist/indexer/graph/graph-boost.js +9 -30
package/dist/indexer/graph/graph-extraction.js +41 -27
package/dist/indexer/graph/graph-types.js +4 -0
package/dist/indexer/index-writer-lock.js +93 -49
package/dist/indexer/index-written-assets.js +100 -53
package/dist/indexer/indexer.js +761 -329
package/dist/indexer/init.js +18 -25
package/dist/indexer/installations.js +142 -0
package/dist/indexer/passes/dir-staleness.js +18 -10
package/dist/indexer/passes/memory-inference.js +25 -15
package/dist/indexer/passes/metadata.js +412 -243
package/dist/indexer/scan/doc-to-entry.js +160 -0
package/dist/indexer/scan/drain-dir.js +134 -0
package/dist/indexer/search/db-search.js +292 -108
package/dist/indexer/search/fts-query.js +64 -0
package/dist/indexer/search/ranking-contributors.js +145 -25
package/dist/indexer/search/ranking-types.js +4 -0
package/dist/indexer/search/ranking.js +28 -71
package/dist/indexer/search/search-attribution.js +67 -0
package/dist/indexer/search/search-fields.js +18 -3
package/dist/indexer/search/search-hit-enrichers.js +30 -40
package/dist/indexer/search/search-source.js +158 -112
package/dist/indexer/search/semantic-status.js +4 -1
package/dist/indexer/usage/usage-events.js +10 -30
package/dist/indexer/walk/file-context.js +3 -45
package/dist/indexer/walk/matchers.js +45 -74
package/dist/indexer/walk/path-resolver.js +11 -5
package/dist/indexer/walk/walker.js +42 -14
package/dist/integrations/agent/builder-shared.js +7 -0
package/dist/integrations/agent/builders.js +5 -58
package/dist/integrations/agent/config.js +4 -144
package/dist/integrations/agent/detect.js +64 -19
package/dist/integrations/agent/engine-resolution.js +231 -0
package/dist/integrations/agent/index.js +1 -2
package/dist/integrations/agent/model-aliases.js +8 -3
package/dist/integrations/agent/profiles.js +13 -96
package/dist/integrations/agent/prompts.js +46 -18
package/dist/integrations/agent/runner-dispatch.js +78 -13
package/dist/integrations/agent/runner.js +76 -208
package/dist/integrations/agent/spawn.js +48 -280
package/dist/integrations/harnesses/aider/agent-builder.js +9 -8
package/dist/integrations/harnesses/aider/index.js +2 -12
package/dist/integrations/harnesses/amazonq/agent-builder.js +10 -16
package/dist/integrations/harnesses/amazonq/index.js +3 -17
package/dist/integrations/harnesses/claude/agent-builder.js +2 -3
package/dist/integrations/harnesses/claude/config-import.js +1 -3
package/dist/integrations/harnesses/claude/index.js +1 -14
package/dist/integrations/harnesses/claude/session-log.js +27 -75
package/dist/integrations/harnesses/codex/agent-builder.js +8 -7
package/dist/integrations/harnesses/codex/index.js +2 -13
package/dist/integrations/harnesses/copilot/agent-builder.js +9 -9
package/dist/integrations/harnesses/copilot/index.js +1 -13
package/dist/integrations/harnesses/gemini/agent-builder.js +8 -9
package/dist/integrations/harnesses/gemini/index.js +1 -13
package/dist/integrations/harnesses/ids.js +24 -0
package/dist/integrations/harnesses/index.js +31 -33
package/dist/integrations/harnesses/opencode/agent-builder.js +23 -5
package/dist/integrations/harnesses/opencode/config-import.js +1 -3
package/dist/integrations/harnesses/opencode/index.js +1 -18
package/dist/integrations/harnesses/opencode/session-log.js +67 -125
package/dist/integrations/harnesses/opencode-sdk/harness.js +3 -17
package/dist/integrations/harnesses/opencode-sdk/sdk-runner.js +280 -193
package/dist/integrations/harnesses/openhands/agent-builder.js +12 -10
package/dist/integrations/harnesses/openhands/index.js +2 -12
package/dist/integrations/harnesses/pi/agent-builder.js +11 -18
package/dist/integrations/harnesses/pi/index.js +3 -16
package/dist/integrations/harnesses/shared.js +17 -0
package/dist/integrations/harnesses/types.js +38 -34
package/dist/integrations/lockfile.js +166 -24
package/dist/integrations/session-logs/index.js +24 -40
package/dist/integrations/session-logs/provider-base.js +113 -0
package/dist/llm/client.js +182 -110
package/dist/llm/embedders/deterministic.js +2 -2
package/dist/llm/embedders/remote.js +21 -9
package/dist/llm/feature-gate.js +17 -57
package/dist/llm/graph-extract.js +12 -13
package/dist/llm/index-passes.js +8 -42
package/dist/llm/memory-infer.js +144 -1
package/dist/llm/metadata-enhance.js +45 -30
package/dist/llm/structured-call.js +16 -8
package/dist/llm/usage-persist.js +30 -5
package/dist/llm/usage-telemetry.js +59 -6
package/dist/output/cli-hints.js +1 -2
package/dist/output/command-registry.js +27 -0
package/dist/output/context.js +22 -7
package/dist/output/format-exempt.js +80 -0
package/dist/output/generic-render.js +251 -0
package/dist/output/html-render.js +11 -16
package/dist/output/render-registry.js +57 -0
package/dist/output/renderers.js +15 -281
package/dist/output/shapes/curate.js +10 -1
package/dist/output/shapes/events.js +12 -7
package/dist/output/shapes/helpers.js +58 -84
package/dist/output/shapes/passthrough.js +8 -44
package/dist/output/shapes/proposal/producer.js +15 -7
package/dist/output/shapes/registry.js +12 -6
package/dist/output/shapes.js +0 -9
package/dist/output/text/{init.js → bundle-create.js} +3 -1
package/dist/output/text/bundle-show.js +7 -0
package/dist/output/text/command-format.js +562 -0
package/dist/output/text/env.js +1 -3
package/dist/output/text/events.js +8 -7
package/dist/output/text/helpers.js +15 -1375
package/dist/output/text/proposal/producer.js +4 -2
package/dist/output/text/proposal-format.js +202 -0
package/dist/output/text/registry-commands.js +1 -2
package/dist/output/text/registry.js +12 -6
package/dist/output/text/show-directives.js +115 -0
package/dist/output/text/show-format.js +103 -0
package/dist/output/text/sync.js +5 -0
package/dist/output/text/workflow-format.js +277 -0
package/dist/output/text/workflow.js +1 -6
package/dist/output/text.js +10 -19
package/dist/registry/factory.js +4 -6
package/dist/registry/origin-resolve.js +16 -27
package/dist/registry/providers/skills-sh.js +3 -3
package/dist/registry/providers/static-index.js +15 -25
package/dist/registry/resolve.js +43 -94
package/dist/registry/semver.js +43 -0
package/dist/runtime.js +81 -12
package/dist/scripts/akm-migrate-node.js +58773 -0
package/dist/scripts/akm-migrate.js +58114 -0
package/dist/setup/detect.js +45 -22
package/dist/setup/detected-engines.js +136 -0
package/dist/setup/engine-config.js +100 -0
package/dist/setup/registry-stash-loader.js +3 -3
package/dist/setup/semantic-assets.js +12 -9
package/dist/setup/setup.js +445 -209
package/dist/setup/steps/connection-shared.js +120 -0
package/dist/setup/steps/connection.js +108 -305
package/dist/setup/steps/platforms.js +13 -12
package/dist/setup/steps/semantic.js +15 -3
package/dist/setup/steps/sources.js +21 -15
package/dist/setup/steps/stashdir.js +6 -4
package/dist/setup/steps/tasks.js +236 -119
package/dist/setup/steps.js +3 -2
package/dist/sources/freshness.js +39 -0
package/dist/sources/provider-factory.js +11 -17
package/dist/sources/providers/filesystem.js +2 -3
package/dist/sources/providers/git-install.js +278 -34
package/dist/sources/providers/git-provider.js +54 -56
package/dist/sources/providers/git-stash.js +424 -93
package/dist/sources/providers/git.js +2 -2
package/dist/sources/providers/npm.js +16 -19
package/dist/sources/providers/provider-utils.js +47 -22
package/dist/sources/providers/sync-from-ref.js +3 -9
package/dist/sources/providers/website.js +7 -2
package/dist/sources/resolve.js +11 -10
package/dist/sources/snapshot-fetchers/bluesky.js +146 -0
package/dist/sources/snapshot-fetchers/content-extract.js +370 -0
package/dist/sources/snapshot-fetchers/fetcher-util.js +40 -0
package/dist/sources/snapshot-fetchers/host-guard.js +199 -0
package/dist/sources/{wiki-fetchers → snapshot-fetchers}/registry.js +10 -1
package/dist/sources/snapshot-fetchers/robots.js +348 -0
package/dist/sources/snapshot-fetchers/rss.js +279 -0
package/dist/sources/snapshot-fetchers/secret-seam.js +42 -0
package/dist/sources/snapshot-fetchers/types.js +4 -0
package/dist/sources/snapshot-fetchers/website-ingest.js +935 -0
package/dist/sources/snapshot-fetchers/x.js +193 -0
package/dist/storage/database.js +60 -4
package/dist/storage/engines/sqlite-migrations.js +69 -3
package/dist/storage/locations.js +1 -2
package/dist/storage/repositories/canaries-repository.js +1 -1
package/dist/storage/repositories/events-repository.js +51 -11
package/dist/storage/repositories/improve-runs-repository.js +6 -32
package/dist/storage/repositories/index-connection.js +79 -0
package/dist/storage/repositories/index-db.js +4 -3
package/dist/storage/repositories/index-entries-repository.js +863 -0
package/dist/{indexer/db/entry-mapper.js → storage/repositories/index-entry-mapper.js} +19 -2
package/dist/storage/repositories/index-entry-types.js +4 -0
package/dist/storage/repositories/index-fts-repository.js +167 -0
package/dist/storage/repositories/index-llm-cache-repository.js +108 -0
package/dist/storage/repositories/index-meta-repository.js +49 -0
package/dist/{indexer/db/schema.js → storage/repositories/index-schema.js} +226 -100
package/dist/storage/repositories/index-sql.js +12 -0
package/dist/storage/repositories/index-utility-repository.js +356 -0
package/dist/storage/repositories/index-vec-repository.js +250 -0
package/dist/storage/repositories/outcome-repository.js +119 -0
package/dist/storage/repositories/proposals-repository.js +317 -75
package/dist/storage/repositories/registry-cache.js +1 -1
package/dist/storage/repositories/salience-repository.js +172 -0
package/dist/storage/repositories/task-history-repository.js +110 -3
package/dist/storage/repositories/workflow-runs-repository.js +68 -35
package/dist/tasks/backends/cron.js +169 -46
package/dist/tasks/backends/exec-utils.js +76 -3
package/dist/tasks/backends/index.js +6 -9
package/dist/tasks/backends/launchd.js +292 -55
package/dist/tasks/backends/schtasks.js +557 -70
package/dist/tasks/backends/types.js +4 -0
package/dist/tasks/command-executable.js +93 -0
package/dist/tasks/embedded.js +56 -38
package/dist/tasks/parser.js +156 -64
package/dist/tasks/resolve-akm-bin.js +144 -51
package/dist/tasks/runner.js +394 -223
package/dist/tasks/schedule.js +108 -19
package/dist/tasks/scheduler-invocation.js +296 -0
package/dist/tasks/schema.js +25 -2
package/dist/tasks/task-id.js +35 -0
package/dist/tasks/validator.js +30 -16
package/dist/workflows/authoring/authoring.js +96 -148
package/dist/workflows/authoring/scope-key.js +1 -1
package/dist/workflows/concurrency-policy.js +15 -0
package/dist/workflows/exec/brief.js +26 -60
package/dist/workflows/exec/frozen-judge.js +73 -0
package/dist/workflows/exec/native-executor.js +175 -95
package/dist/workflows/exec/report.js +373 -201
package/dist/workflows/exec/run-workflow.js +147 -82
package/dist/workflows/exec/scheduler.js +12 -41
package/dist/workflows/exec/step-work.js +257 -222
package/dist/workflows/exec/unit-dispatch.js +4 -0
package/dist/workflows/exec/workflow-engine-gate.js +65 -0
package/dist/workflows/ir/compile.js +142 -284
package/dist/workflows/ir/freeze.js +241 -0
package/dist/workflows/ir/params.js +134 -10
package/dist/workflows/ir/plan-hash.js +41 -6
package/dist/workflows/ir/schema.js +541 -1
package/dist/workflows/parser.js +878 -306
package/dist/workflows/program/expressions.js +20 -208
package/dist/workflows/program/schema.js +7 -10
package/dist/workflows/renderer.js +100 -122
package/dist/workflows/resource-limits.js +22 -0
package/dist/workflows/runtime/checkin.js +4 -4
package/dist/workflows/runtime/plan-classifier.js +131 -0
package/dist/workflows/runtime/runs.js +243 -135
package/dist/workflows/runtime/unit-checkin.js +1 -1
package/dist/workflows/runtime/unit-phases.js +20 -0
package/dist/workflows/runtime/workflow-asset-loader.js +235 -97
package/dist/workflows/schema.js +1 -11
package/dist/workflows/validate-summary.js +30 -36
package/dist/workflows/validator.js +52 -30
package/docs/README.md +42 -78
package/docs/migration/README.md +8 -0
package/docs/migration/release-notes/0.6.0.md +1 -1
package/docs/migration/release-notes/0.7.0.md +9 -8
package/docs/migration/release-notes/0.9.0.md +185 -14
package/docs/migration/v0.7-to-v0.8.md +46 -47
package/docs/migration/v0.8-to-v0.9.md +813 -0
package/docs/reference/README.md +12 -0
package/docs/reference/data-and-telemetry.md +333 -0
package/package.json +25 -17
package/schemas/akm-asset-envelope.json +93 -0
package/schemas/akm-config.json +4660 -0
package/schemas/akm-task.json +87 -0
package/{dist/schemas → schemas}/akm-workflow.json +127 -82
package/dist/akm-migrate-storage +0 -38
package/dist/assets/help/help-accept.md +0 -12
package/dist/assets/help/help-improve.md +0 -84
package/dist/assets/help/help-proposals.md +0 -17
package/dist/assets/help/help-propose.md +0 -17
package/dist/assets/help/help-reject.md +0 -11
package/dist/assets/profiles/frequent.json +0 -13
package/dist/assets/profiles/recombine-only.json +0 -21
package/dist/assets/profiles/reflect-distill.json +0 -30
package/dist/assets/profiles/synthesize.json +0 -15
package/dist/assets/prompts/procedural-system.md +0 -44
package/dist/assets/prompts/recombine-system.md +0 -40
package/dist/assets/prompts/staleness-detect-system.md +0 -6
package/dist/assets/tasks/core/backup.yml +0 -4
package/dist/assets/tasks/graph-refresh-weekly.yml +0 -10
package/dist/assets/templates/html/default.html +0 -78
package/dist/assets/templates/html/vendor/echarts.min.js +0 -45
package/dist/assets/wiki/index-template.md +0 -12
package/dist/assets/wiki/ingest-workflow-template.md +0 -83
package/dist/assets/wiki/log-template.md +0 -8
package/dist/assets/wiki/schema-template.md +0 -61
package/dist/cli/config-migrate.js +0 -150
package/dist/cli/config-validate.js +0 -39
package/dist/commands/graph/graph-cli.js +0 -124
package/dist/commands/graph/graph.js +0 -487
package/dist/commands/improve/calibration.js +0 -161
package/dist/commands/improve/dedup.js +0 -482
package/dist/commands/improve/extract-watch.js +0 -140
package/dist/commands/improve/hot-probation.js +0 -45
package/dist/commands/improve/improve-auto-accept.js +0 -276
package/dist/commands/improve/improve-profiles.js +0 -168
package/dist/commands/improve/procedural.js +0 -398
package/dist/commands/improve/recombine.js +0 -818
package/dist/commands/improve/schema-similarity-gate.js +0 -168
package/dist/commands/lint/agent-linter.js +0 -44
package/dist/commands/lint/command-linter.js +0 -44
package/dist/commands/lint/default-linter.js +0 -16
package/dist/commands/lint/fact-linter.js +0 -39
package/dist/commands/lint/knowledge-linter.js +0 -16
package/dist/commands/lint/memory-linter.js +0 -61
package/dist/commands/lint/registry.js +0 -41
package/dist/commands/lint/skill-linter.js +0 -45
package/dist/commands/lint/task-linter.js +0 -50
package/dist/commands/lint/workflow-linter.js +0 -81
package/dist/commands/proposal/legacy-import.js +0 -115
package/dist/commands/sources/history.js +0 -196
package/dist/commands/tasks/default-tasks.js +0 -186
package/dist/commands/wiki-cli.js +0 -292
package/dist/core/asset/asset-registry.js +0 -76
package/dist/core/asset/asset-spec.js +0 -316
package/dist/core/config/config-migration.js +0 -602
package/dist/core/deep-merge.js +0 -38
package/dist/core/eval/rank-metrics.js +0 -113
package/dist/core/ripgrep/install.js +0 -163
package/dist/core/ripgrep/resolve.js +0 -81
package/dist/indexer/db/db.js +0 -1414
package/dist/indexer/manifest.js +0 -170
package/dist/indexer/passes/metadata-contributors.js +0 -31
package/dist/indexer/usage/unmigrated-vaults-guard.js +0 -94
package/dist/integrations/harnesses/opencode-sdk/index.js +0 -25
package/dist/llm/call-ai.js +0 -62
package/dist/llm/memory-infer-impl.js +0 -138
package/dist/output/shapes/distill.js +0 -14
package/dist/output/shapes/history.js +0 -11
package/dist/output/text/distill.js +0 -6
package/dist/output/text/enable-disable.js +0 -8
package/dist/output/text/history.js +0 -6
package/dist/output/text/wiki.js +0 -16
package/dist/registry/build-index.js +0 -386
package/dist/schemas/akm-config.json +0 -14225
package/dist/scripts/migrate-storage.js +0 -13169
package/dist/scripts/migrations/import-fs-improve-runs-to-db.js +0 -10169
package/dist/scripts/migrations/v16-to-v17.js +0 -141
package/dist/setup/legacy-config.js +0 -106
package/dist/sources/website-ingest.js +0 -635
package/dist/storage/repositories/consolidation-repository.js +0 -38
package/dist/storage/repositories/recombine-repository.js +0 -213
package/dist/wiki/wiki-templates.js +0 -15
package/dist/wiki/wiki.js +0 -1012
package/dist/workflows/authoring/workflow-program-template.yaml +0 -31
package/dist/workflows/cli.js +0 -53
package/dist/workflows/db.js +0 -350
package/dist/workflows/exec/watch.js +0 -116
package/dist/workflows/program/parser.js +0 -760
package/dist/workflows/program/project.js +0 -105
package/docs/data-and-telemetry.md +0 -227
package/docs/migration/release-notes/0.9.0-beta.60.md +0 -19
/package/dist/sources/{wiki-fetchers → snapshot-fetchers}/youtube.js +0 -0

package/CHANGELOG.md CHANGED Viewed

@@ -8,36 +8,1008 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 ### Added
+- **RSS, Bluesky, and X sources.** `akm bundle add` now recognizes three new
+  kinds of URL and snapshots them as knowledge assets instead of crawling
+  them as ordinary web pages:
+  ```sh
+  akm bundle add https://blog.example/feed          # RSS 2.0 / Atom / RDF
+  akm bundle add https://bsky.app/profile/<handle>  # public, no auth
+  akm bundle add https://x.com/<user>               # see token note below
+  ```
+  Any of these falling through — a `/feed` URL that actually serves HTML, an
+  unresolvable Bluesky handle — degrades to the normal website crawl rather
+  than failing the command.
+  X needs credentials: set `X_BEARER_TOKEN` for the X API v2, or
+  `X_RSS_TEMPLATE` to an RSS bridge URL containing `{username}`. To keep the
+  token out of your shell history, store it as an akm secret and inject it
+  per-invocation:
+  ```sh
+  akm secret set x-bearer-token
+  akm secret run secrets/x-bearer-token X_BEARER_TOKEN -- akm bundle add https://x.com/<user>
+  ```
+  With neither set, the X fetcher emits one warning and falls through.
+### Changed
+- **X source tokens now resolve from the secret store during bundle update.**
+  The `secrets/x-bearer-token` akm secret is honored on the provider
+  `sync()` / bundle-update path, not just when adding or importing a URL —
+  closing a gap where a refresh saw only the `X_BEARER_TOKEN` environment
+  variable. Implemented as a `SecretResolver` capability injected from above
+  the source-provider import cycle; internals are documented in
+  `docs/architecture/reviews/env-secret-access.md`.
+- **`website` crawls now have a hard time limit.** `crawlTimeoutMs` (default
+  600000 — 10 minutes) bounds the entire crawl, and unlike the previous
+  between-page check it aborts work already in flight: a `Retry-After` sleep
+  could previously park `akm bundle add` for as long as a rate-limiting server
+  asked, well past the advertised cap. Raise it for a large site, or set
+  `"crawlTimeoutMs": 0` to disable the cap. Relatedly, `fetchWithRetry` now
+  honors its caller's `AbortSignal` during retry backoff, so any operation that
+  passes a signal can actually interrupt a long wait.
+- **Website snapshots now extract the page's main content.** Conversion moved
+  from a hand-rolled regex converter to a DOM parse plus Turndown, scoped to
+  the page's content region (`<main>`, `<article>`, `[role=main]`, then common
+  content ids/classes, falling back to `<body>` minus nav/header/footer/aside).
+  Navigation, ads, and boilerplate no longer land in snapshots, and tables,
+  nested lists, and fenced code blocks with language hints now survive
+  conversion. **Existing website snapshots will change on their next refresh**
+  — expect them to get shorter and cleaner. Link discovery still scans the
+  whole page, so crawl coverage is unchanged.
+- **`website` sources now respect `robots.txt` by default.** Before crawling
+  an origin, akm fetches and parses that origin's `/robots.txt` and skips
+  paths disallowed for the `akm`/`akm-cli` product tokens (or `*`), honoring
+  `Crawl-delay` (clamped to 10s) between page fetches. This is a deliberate
+  behavior change: **existing website sources may return fewer pages, or
+  fail with an error if the start URL itself is disallowed, after
+  upgrading.** Re-running `akm bundle update` on a website source is what
+  surfaces it. Opt out with `"respectRobots": false` on the website
+  descriptor to restore the exact pre-upgrade behavior (no `/robots.txt`
+  request at all):
+  ```json
+  { "bundles": { "docs": { "website": { "url": "https://docs.example.com", "respectRobots": false } } } }
+  ```
+## [0.9.0-rc.13] - 2026-07-31
+### Security
+- **`akm update` no longer deletes a previous install directory without
+  confirmation.** When a managed source's resolved content location moves,
+  `update` removed the old directory outright, while `akm remove` had always
+  required `--yes` in non-interactive mode. Only that destructive branch is
+  gated — a normal refresh, where the location does not move, still needs no
+  prompt and no flag, so existing CI invocations are unaffected. Pass
+  `-y`/`--yes` to allow the deletion non-interactively. A cleanup that fails
+  now warns instead of failing silently.
+- **The dangerous-env-key install gate now scans `env/` recursively.** It
+  previously read only the top level, so a stash carrying `LD_PRELOAD` in
+  `env/nested/inner.env` installed cleanly with no warning. Files without a
+  `.env` suffix are still not scanned — no akm code path loads them as
+  environment variables.
+### Added
+- **The `okf` adapter reads OKF v0.2's trust/provenance and lifecycle
+  frontmatter families.** `generated: {by, at}` (with `generated.at` taking
+  precedence over the legacy `timestamp` field, which remains a valid
+  fallback), `verified` (a list, or v0.2's permitted single-mapping
+  shorthand), `sources` (an object list — `resource` required; `id`/`title`/
+  `author`/`usage_count`/`last_modified` optional), `status`
+  (`draft`/`stable`/`deprecated`), and `stale_after` are now parsed leniently
+  from any OKF concept's frontmatter and surfaced on new, namespaced
+  `IndexDocument` fields (`provenance`, `lifecycleStatus`, `staleAfter`,
+  `okfVersion`) that never overload the pre-existing AKM-native `sources`
+  (wiki citation strings), `generation` (consolidation depth), or `quality`
+  fields. As with every other optional OKF field, a missing or malformed
+  value never rejects the document. The `okf` adapter remains consumer-only.
+- **Accepting a proposal now stamps OKF v0.2 provenance onto the written
+  asset's frontmatter**, for AKM-native writes only (never through the `okf`
+  adapter, which stays consumer-only and unaffected by this). `promoteProposal`
+  projects the proposal system's own `source`/`sourceRun`/`gateDecision`/
+  `review` bookkeeping — already tracked in `state.db` but previously never
+  written to disk. `generated: {by, at}` and `verified: [{by, at}]` are written
+  **bare at the top level**, exactly as OKF v0.2 spells them, so a third-party
+  OKF v0.2 reader pointed at an AKM stash sees conformant trust metadata;
+  `sources` alone is namespaced as `provenance: {sources}`, because a bare
+  `sources:` collides with the pre-existing wiki citation-string convention.
+  `generated.by` records whether the content came from an automated pipeline
+  (`akm/<version>`) or a human-initiated source (`human:<id>`); `verified`
+  records whether the promotion itself was an automated gate decision or a
+  direct human accept, and accumulates rather than overwriting across
+  re-promotions; `evidenceSources`, when present, projects as
+  `provenance.sources`. AKM's own adapter rereads what it wrote, so `akm show`
+  surfaces it. Every AKM-native markdown type is stamped, `workflow` included.
+  Two consequences worth knowing: promotion re-serializes the whole frontmatter
+  block, so YAML **comments** in a hand-written proposal's frontmatter are not
+  preserved (values and body bytes are); and for a human-attributed promotion
+  with no configured actor id, `by` falls back to `human:<OS username>`, which
+  puts that username into content you may later commit and share.
+- **Internal: a `capturedAtHead` integrity guard**
+  (`scripts/lint-golden-captured-at-head.ts`, wired into `bun run lint`) now
+  checks every golden fixture's recorded `capturedAtHead` commit SHA — it must
+  exist in the local object database and be reachable from at least one known
+  branch. Post-hoc review of this PR found all four new OKF format-family
+  goldens pointed at a commit that existed locally but was unreachable from
+  any ref (a pre-amend duplicate left behind by an interrupted git operation),
+  which would have 404'd on GitHub and vanished under a local `git gc`; a
+  human fixed that one by hand because nothing caught it. This guard is that
+  catch, going forward. In CI's shallow (`fetch-depth: 1`) checkout, a merely
+  *absent* commit object is inconclusive (indistinguishable from "just not
+  fetched") and only warns; a commit that *exists but is unreachable from any
+  branch* — the actual bug class above — still fails there too, since a
+  shallow clone can tell presence apart from absence just fine.
+- **`akm log list --limit <n>`** returns the most recent N events. The flag was
+  documented but silently ignored, and there was no limiting mechanism at all
+  in the read path — the command returned the entire events table regardless of
+  history size. The default remains unlimited.
+- **`--track-usage` (default on) on `akm search`, `akm curate`, and `akm show`.**
+  Pass `--no-track-usage` for a read-only lookup that does not feed usage
+  telemetry or the utility-score ranking signal. Previously a bare `akm search`
+  silently wrote a `utility_scores` row that influenced future ranking, with no
+  disclosure and no way to opt out.
+- **`akm show` returns the canonical `ref` in every shape.** It was present only
+  under `--shape agent`, so a `--shape summary` consumer had to make a second
+  call at a different shape just to learn which asset it was looking at.
+- **`akm info` gained `stashDir`, `defaultBundle`, and `indexStats.byType`.**
+  Answering "which stash is primary" previously required a separate
+  `akm sources list`.
+- **`instruction` is a stash-resident asset type.** It was already in
+  `KNOWN_TYPES` and had a presentation entry, but had no placement spec — so
+  there was nowhere to put one and the indexer never recognized one. `akm bundle create`
+  now creates an `instructions/` directory, `.md` files under it index as
+  `instruction`, and `--type instruction` is accepted and tab-completable
+  everywhere `--type` is. A compile-time assertion now pins
+  `placementTypes() ⊆ KnownType`, so the half-registered state this fixes
+  cannot recur silently.
+- **Schedule tasks from any configured bundle via `--bundle <bundle>`** (#711).
+  `akm task add`, `run`, `sync`, and `history` accept `--bundle` to
+  operate on a non-default bundle instead of only the primary stash. `add`
+  resolves through the normal writable-target rules; `run --bundle X` resolves
+  the task file and relative asset refs from bundle X. A non-default bundle is
+  recorded in the scheduler entry as `--bundle <bundle>`, so scheduled
+  `akm task run` resolves the right bundle. Scheduler ids stay bare and a
+  collision with another bundle is a hard error rather than a silent clobber.
+- **Orphan-GC pass for unresolvable `asset_salience` / `asset_outcome` state
+  rows** (#733). A new improve maintenance pass (`runOrphanStateGcPass`, run
+  next to the existing orphan-proposal purge) stamps `missing_since` on any
+  state row whose ref no longer resolves against `entries.item_ref`, clears
+  the stamp the moment the ref resolves again, and — only when
+  `improve.stateGc.collect` is set to `true` (**default `false`**) — deletes
+  rows whose stamp is older than a fixed 7-day grace window
+  (`STATE_GC_GRACE_MS`). The pass always runs and always reports counts via
+  the new `asset_state_gc` event (`{pending, collected, byTable}`), emitted
+  only when there is something to report, so live data can prove the report
+  clean before `collect` is ever turned on. Additive migration
+  `021-asset-state-missing-since` adds the `missing_since` column to both
+  tables. Deliberately lean by design (Workstream C): no quarantine archive,
+  no circuit breaker, no health-advisory plumbing, no new tables — "ref not
+  present in `entries.item_ref`" is trusted as the authoritative-deletion
+  predicate because the indexer already preserves a source's last-known-good
+  rows when its scan is incomplete, so a temporarily unreachable source never
+  contributes false candidates. `usage_events` is out of scope (already
+  covered by cascade-on-delete plus its own 90-day retention purge).
+### Changed
+- **Workflow execution is consolidated on stable `akm workflow run`.** The
+  public `workflow start`, `next`, and `complete` commands are removed with
+  explicit `UNKNOWN_COMMAND` migration hints; `run <ref|run-id>` now owns
+  creation, active-run continuation, native dispatch, completion, and durable
+  replay. It is no longer gated by `experimental.workflowEngine`; only the
+  experimental `brief`/`report` external-driver protocol retains that opt-in.
+  Workflow parameters move from the opaque `--params '<json>'` bag to exact
+  declared flags (`--version 1.2.3`, repeated array flags, JSON object/array
+  values) coerced through the frozen parameter schemas. New invocation controls
+  add bounded failed-step retries (`--max-retries`) and a whole-run timeout
+  (`--timeout N|Nms|Ns|Nm`); failures, gate rejection, timeout, and signals now
+  produce non-zero process statuses while leaving interrupted work resumable.
+  Criteria-bearing gates now require `workflow.judgeEngine`, which may name a
+  configured LLM or agent engine and is frozen into the run. Verification is
+  fail-closed: a missing/failing verifier or malformed verdict rejects instead
+  of silently advancing. Scheduled workflow tasks now execute through the same
+  native orchestrator rather than stopping after run creation. Migration:
+  replace `workflow start/next/complete` loops with `workflow run`, replace
+  `--params` with exact declared flags, and configure `workflow.judgeEngine`
+  before running a workflow with a non-empty `### gate` rubric.
+- **The two workflow authoring formats — markdown documents and YAML
+  orchestration programs — are unified into one format**, per
+  `docs/architecture/specs/workflow-format-unification.md`. A workflow is
+  now always a single markdown asset: the standard AKM frontmatter envelope
+  carries the whole orchestration graph (`params`, `steps` with
+  `unit`/`map`/`route`, `inputs`, `output`, `gate`, `defaults`, `budget`),
+  and the body carries each step's instructions under a bare `## <step-id>`
+  heading, joined to the frontmatter by step id. `.yaml`/`.yml` workflow
+  files, the `# Workflow:` / `## Step:` / `Step ID:` markdown headings, and
+  `akm workflow create <name>.yaml` are all gone; `akm workflow create`
+  always writes the one unified template
+  (`src/assets/workflows/workflow-template.md`).
+  **Prose is never interpolated.** The YAML program's `${{ … }}` template
+  language, and the markdown format's decorative — and never
+  substituted — `{{ … }}` moustaches, are both removed. Data reaches a
+  dispatched unit as *attached context* instead: the run's params, its
+  item and index for a map unit, and the artifacts its step's new
+  `inputs:` key declares. Instructions refer to that context in plain
+  language ("clone the repository named by the `repo` parameter") rather
+  than splicing a value into the instruction string. Bare reference
+  strings (two roots, `params.<name>` and `steps.<id>.output…`) now appear
+  only in three frontmatter positions: `map.over`, `route.input`, and
+  `inputs:`.
+  **Gate rubrics move to the body.** A step's completion criteria are no
+  longer a frontmatter `gate.criteria` list or a `### Completion Criteria`
+  bullet section — they live under a step's `### gate` sub-heading, the
+  format's one reserved marker, as full prose a judge receives byte-exact.
+  Frontmatter `gate:` now carries only optional `max_loops` configuration.
+  Omitted or empty rubric text skips validation; a non-empty rubric requires
+  the frozen `workflow.judgeEngine`, and unavailable or malformed judges reject
+  the gate.
+  This is a **pre-1.0 format change**. The ten example workflows under
+  `scripts/akm-eval/example-stash/workflows/` are rewritten to the unified
+  format in this change; existing user-authored workflow assets must be updated
+  manually before execution.
+- **akm is described as a knowledge toolkit, not a package manager** (R-048).
+  The npm one-liner, the README lede, and the `concepts.md` opener all led with
+  "a package manager for AI agent capabilities", which misstates the product to
+  its distribution channel and sets package-manager expectations for verbs
+  (`update` / `upgrade` / `sync`) that don't mean what a package manager's do.
+- **BREAKING: a command group invoked with no subcommand is now always a usage
+  error, exit 2** (owner ruling 12). The eleven `akm <group>` groups did three
+  different things when invoked bare: `graph`, `config`, `env`, `secret`,
+  `task`, `workflow`, and `proposal` ran an implicit default action and exited
+  0 (bare `akm graph` silently rendered `graph summary`); `registry`, `log`, and
+  `lessons` printed citty's human usage banner to stdout; only `migrate` raised
+  a structured error. All eleven now emit the same
+  `MISSING_REQUIRED_ARGUMENT` envelope on stderr, naming the available
+  subcommands, and exit 2 — matching STABILITY.md's exit-code table (2 =
+  usage) and the exit code already used for unknown commands. Matching exit
+  codes alone was not enough: a script could not parse the failure uniformly
+  while three groups answered on stdout in prose.
+  Migration: name the subcommand. `akm graph` → `akm graph summary`,
+  `akm config` → `akm config list`, `akm env` → `akm env list`, `akm secret` →
+  `akm secret list`, `akm task` → `akm task doctor`, `akm workflow` →
+  `akm workflow list --active`, `akm proposal` → `akm proposal list` (which
+  takes the same `--status`/`--queue`/`--ref`/`--type` flags the bare form did).
+- **BREAKING: `akm sync` persists `eventType: "sync"`, not the legacy
+  `"save"`.** The event name now matches the command name. Historical
+  `state.db` rows are left as-is — `akm log` and `akm log tail` treat `"save"`
+  and `"sync"` as synonyms on **read**, so `akm log --type save` keeps
+  returning both old and new rows. Only newly written events use `"sync"`.
+  Migration: none for `akm log --type save`. A script matching raw event rows
+  by `eventType === "save"` — reading state.db directly, bypassing `akm log` —
+  should also match `"sync"` to see new syncs.
+- **BREAKING: dropped the dead `installedKitCount` field from the `add`,
+  `remove`, and `update` JSON envelopes.** It was a raw lockfile-entry count
+  that nothing — internal code or test — ever read.
+  Migration: a script parsing `.config.installedKitCount` should stop; the
+  field is gone, not renamed. `config.sourceCount` remains and is unaffected.
+- **BREAKING: dropped the dead `graphPath` field from every `akm graph *` JSON
+  envelope** (`summary`, `entities`, `relations`, `export`, `related`, `entity`,
+  `orphans`). It always resolved to the shared state.db path, never a
+  per-graph artifact, and carried nothing `stashPath` did not already provide.
+  Migration: a script reading `.graphPath` from any `akm graph` subcommand
+  should stop; `stashPath` remains.
+- **BREAKING: `semanticSearchMode` now defaults to `"off"`.** A bare or
+  headless install (`akm init`, `akm setup --yes`, `akm setup --config`) was
+  silently downloading the ~130 MB local embedding model on its first `akm
+  index`, because the fallback used when the key is absent was `"auto"`. The
+  interactive `akm setup` wizard still pre-selects semantic search **on** — a
+  human is present to decide — and now shows the asset/download warning
+  *before* the prompt rather than after, so the pre-checked box is an informed
+  choice. When a remote `embedding.endpoint` is configured, enabling semantic
+  search downloads nothing.
+  Migration: existing saved configs are unaffected — the flip only changes the
+  fallback used when the key is absent. To keep semantic search on for a
+  headless or CI install, set `semanticSearchMode: "auto"` explicitly, or point
+  `embedding.endpoint` at a remote embedder.
+- **BREAKING: `akm workflow run|brief|report` refuse to run until
+  `experimental.workflowEngine` is set** (0.9.0 decision Q-05). The native
+  workflow executor — including fan-out scheduling and worktree isolation —
+  is experimental, and shipping it enabled by default would have made an
+  unreviewed execution engine reachable from a plain `akm workflow run`. The
+  gated surfaces now exit `78` with a `ConfigError` naming the exact key, and
+  `akm task doctor` reports the gate's state. Authoring and linting the unified
+  markdown format, along with every other `akm workflow` subcommand, remain
+  ungated.
+  Migration: `akm config set experimental.workflowEngine true`.
+- **BREAKING: the `env:<name>` / `secret:<name>` colon ref spelling is
+  rejected** (0.9.0 decision Q-08). Refs are slash conceptIds only — `env/foo`,
+  `secrets/deploy-key`. The colon form previously resolved as an undocumented
+  alias in some places and fell through as a literal filename in others. It now
+  fails with a usage error naming the slash replacement, rather than silently
+  doing the wrong thing.
+  Migration: rewrite `env:<name>` as `env/<name>` and `secret:<name>` as
+  `secrets/<name>`. The error message prints the exact replacement.
+- **`akm improve` is review-first by default; autonomy is opt-in** (0.9.0
+  decision D8). The command stays ON — schedules, reflect/distill proposals, and
+  graph extraction are unchanged — but the lanes that mutate assets *without*
+  review now require `akm config set experimental.improveAutonomy true`:
+  memory-inference writes, the memory-cleanup pass, and triage
+  `applyMode: "promote"` (which downgrades to `queue` rather than disabling
+  triage). Consolidation remains review-oriented and is not gated.
+  A gated lane is never a silent no-op: it warns on stderr naming the lane and
+  the key, appends an `improve_skipped` event with `reason: "autonomy_gated"`,
+  and is counted in `akm health`'s improve skip-reason summary.
+  Migration: set `experimental.improveAutonomy: true` to restore the previous
+  behavior. `sync.push` is **not** affected — it keeps its `true` default and its
+  own `sync.push: false` / `--no-push` controls. Two other direct writes stay
+  ungated by design: `extract`'s additive session indexing and distill's
+  encoding-salience frontmatter stamp. Because the gate is applied before the LLM
+  preflight, a review-first workspace may now need fewer engines configured than
+  before.
+  Also: `akm improve` no longer rejects the global `--format`. It emits an
+  envelope through `output()` (always under `--dry-run`, otherwise under
+  `--json-to-stdout`), so `--format` applies to that envelope; progress output
+  stays on stderr. Previously it exited 2 with `INVALID_FLAG_VALUE`, which made
+  it the one command that rejected a valid global flag.
+- **`akm health --report` replaces the html-only full report** (D7
+  follow-through). The full health report — per-run rows, trend deltas vs the
+  prior window, and the pending proposal queue — is now a **data** flag, not a
+  side effect of asking for html: `akm health --report --format html` renders
+  the rich report, and the identical dataset comes back under `--format json`
+  (previously that data was reachable only as html). The registered md/html
+  renderers fire on the shape of the result, and `akm health` no longer reads
+  `--format` at all.
+  Migration: `akm health --format html` → `akm health --report --format html`
+  (the bare form now renders the plain check generically); the html-only
+  `--compare` flag is removed — use `--window-compare`, which with `--report`
+  defaults to the `--since` window so trend deltas stay like-for-like.
+- **Global output flags parse correctly next to positionals.** citty parses
+  each command level against only its own declared args, so a root-declared
+  global flag was unknown at the leaf and its space-separated value fell
+  through as a positional — `akm sync --format json` synced a bundle named
+  "json", and `akm env unset env:x KEY --format json` tried to unset a key
+  named "json". The global output flags (`--format`, `--detail`, `--shape`,
+  `--output`) are now declared on every leaf command so their values are
+  consumed by the parser; the two bespoke argv-inspection workarounds this
+  replaces are deleted. Three more non-exempt commands (`akm health`, `akm
+  index`, `akm lint`) now declare these flags too, purely for `--help`
+  visibility — all three already parsed `--format`/`--detail`/`--shape`/
+  `--output` correctly, since none of them has a positional a stray value
+  could fall into.
+- **BREAKING: unknown commands and missing required arguments now exit `2`
+  (usage), not `1`.** citty's own command-dispatch wrapper unconditionally
+  called `process.exit(1)` for any error it raised before a command's own
+  body ever ran — `akm totally-bogus` (unknown command), bare `akm log` /
+  `akm lessons` (a subcommand group invoked with no subcommand), and a
+  command missing a required positional (e.g. bare `akm import`) all exited
+  `1`, contradicting the documented exit-code table (`1` = general error /
+  not found, `2` = usage / bad input). The CLI now drives command dispatch
+  directly instead of going through that wrapper, so it can reclassify this
+  one error family as `2` while leaving `--help`, `--version`, and every
+  other exit code unchanged.
+  Migration: a script that treated exit `1` as "something went wrong" for a
+  mistyped command or missing argument should check for `2` instead (or
+  keep treating any non-zero exit as failure, which was already correct).
+- **BREAKING: `akm completions --shell <unsupported>` now exits `2` with the
+  standard JSON error envelope, not `1` with a raw stack trace.**
+  `completions` stays format-exempt (its own output is shell-script source,
+  not a result envelope — see STABILITY.md), but its body is now wrapped in
+  the same error-classification path every other command uses.
+  Migration: a script parsing this failure should now expect
+  `{"ok":false,"error":"...","code":"INVALID_FLAG_VALUE","hint":...}` on
+  stderr and exit code `2` in place of a stack trace and exit code `1`.
+- **BREAKING: `akm index --dry-run` without `--clean` now exits `2` instead
+  of running a real index.** The flag only ever gated the `--clean`
+  stale-entry removal pass — every other phase (walk, LLM enrichment,
+  embeddings, FTS, the adapter-detection config write) ran for real
+  regardless, so `akm index --dry-run` alone silently performed a full index
+  despite its name. The combination is now rejected with the standard usage
+  envelope instead of quietly doing something other than what "dry run"
+  promised.
+  Migration: a script or cron invoking bare `akm index --dry-run` was
+  already getting a real index, so nothing there needs to change in effect —
+  but it will now fail loudly instead. Pass `akm index --clean --dry-run` to
+  preview the stale-entry removal pass, or `akm index --clean` to apply it;
+  drop `--dry-run` entirely to keep running a plain real index.
+- **BREAKING: a corrupt or unparseable `akm.lock` now makes lockfile WRITES
+  throw, instead of silently destroying every entry.** The previous lenient
+  reader returned `[]` on unparseable JSON; a write path that upserted a
+  single entry onto that `[]` then overwrote the file, permanently deleting
+  every other tracked bundle's lock entry. Install/update/remove write paths
+  now use a strict reader that throws on the same corruption instead of
+  reaching the destructive overwrite.
+  Migration: if a write now fails with a lockfile-parse error, `akm.lock` is
+  genuinely corrupt — inspect and repair it by hand, or restore it from a
+  backup (e.g. git history), before retrying the write. Reads elsewhere are
+  unaffected; the lenient read contract is unchanged.
+- **BREAKING: `AKM_NPM_REGISTRY` now redirects npm package METADATA lookups,
+  not just the trusted-tarball allowlist.** Previously the override only
+  widened which tarball hosts were trusted for download while metadata
+  queries stayed hardcoded to `registry.npmjs.org`, so a configured private
+  mirror was never actually consulted for package info — the error hint that
+  points users at this variable was false. The override now also replaces
+  the metadata registry base, matching how a private npm registry is meant
+  to work (like npm's own `--registry` flag: wholesale replacement, not a
+  merge with the public registry).
+  Migration: an operator who set `AKM_NPM_REGISTRY` expecting only tarball
+  downloads to be redirected, with metadata still served from the public
+  registry, should confirm the mirror actually serves equivalent package
+  metadata — `akm add`/`akm update` for npm-sourced bundles now resolve
+  entirely against the configured mirror when it is set.
+- **`akm remember --show-similar` and `akm migrate apply --dry-run` are the
+  documented, canonical spellings** (previously `--showSimilar` /
+  `--dryRun`), matching every other multi-word flag in the CLI. Not a
+  breaking change: citty registers both the camelCase and kebab-case
+  spelling of any declared flag name automatically, so `--showSimilar` /
+  `--dryRun` keep working — they're now explicit, documented aliases instead
+  of an undocumented accident.
+- **`--detail` and `--shape` help text is scoped honestly.** The per-command
+  `--detail` description now names `info`, `list`, and `remember` as the
+  commands where it has no effect (verified byte-identical output at every
+  level — `akm show` is not one of these; it has three distinct
+  brief/normal/full payloads). `--shape`'s per-command help now repeats the
+  "`summary` is only valid on `akm show`" caveat the root help already
+  documented.
+- **All six `--format` values work on every command** (0.9.0 decision D7).
+  `json|jsonl|yaml|text|md|html` are now universal. Previously there were three
+  inconsistent behaviours: `md` silently emitted the JSON envelope everywhere
+  except `akm health`, `html` was rejected with exit 2 everywhere except
+  `akm health`, and `akm health` reached neither because it intercepted the
+  format itself. Rendering is now registry-driven — a command may register a
+  renderer for a document format, and anything unregistered falls back to a real
+  rendering of its own envelope (headings, tables for arrays of uniform objects,
+  lists otherwise). `akm health` keeps its per-run/window-compare tables and its
+  full HTML report by registering them; the output is unchanged.
+  Migration: none required for `json|jsonl|yaml|text`. `--format md` on a
+  non-health command previously returned JSON and now returns Markdown; a script
+  that parsed that JSON should ask for `--format json` explicitly. `--format
+  html` previously exited 2 on non-health commands and now succeeds.
+  Also: `akm graph export --format` is **removed** — it declared `--format`
+  locally as well as globally (one token, two parsers). The artifact payload
+  now follows the `--out` extension (`--out g.jsonl` writes JSONL, anything
+  else JSON); the global flag only renders the command's own envelope. A dead
+  local `--format` declaration on `akm history` was removed too (it was never
+  read). Commands
+  whose output is not an envelope (`completions`, `setup`, `env run`,
+  `secret run`, `agent`, `workflow template`, `help migrate`) are declared
+  format-exempt in `src/output/format-exempt.ts` and now warn when given
+  `--format` instead of ignoring it silently. `output.format` in config accepts
+  all six values.
+- **Subtree browse is a conceptId prefix, not `<type>:`** (0.9.0 decision D4).
+  `akm search` enumerates on `memories/`, `memories/projecta/`, `bundle//`, and
+  `bundle//skills/`; a trailing `/` is still required. The prefix now matches the
+  **conceptId** rather than the item name, so a ref copied out of search output
+  can be truncated to a prefix and pasted straight back in — previously that
+  round-trip degraded silently into a keyword search. Enumeration no longer
+  validates against the `akm` adapter's placement types, so items from every
+  adapter browse the same way, and `bundle//` lists a whole bundle (the
+  replacement for the removed `akm bundle items`).
+  Migration: `akm search "memory:"` → `akm search "memories/"`;
+  `akm search "memory:projectA/"` → `akm search "memories/projectA/"`;
+  `akm search "session:"` → `akm search "sessions/"`. The retired spelling is
+  now an ordinary keyword search; when it returns nothing, the tip names the
+  conceptId spelling that replaces it. `scripts/lint-shipped-assets.ts` no
+  longer exempts the old spelling, so it is an offense in agent-facing assets.
+- **`akm task sync [--bundle <bundle>]` reconciles a single bundle.** Sync now
+  attributes each installed scheduler entry to its bundle (parsed from the
+  `--bundle` token; absent ⇒ primary) and reconciles only the entries for the
+  bundle being synced. A plain (primary) sync never installs from, updates, or
+  removes another bundle's entries, and sync never scans all bundles — task
+  activation stays explicit (`add --bundle` or `sync --bundle`), so registering a bundle
+  still never activates code. When the target is the default bundle (or omitted),
+  installed scheduler entries are byte-identical to before, so upgrading shows no
+  spurious drift.
+- **The R2 salience ranking boost no longer applies to default `search`/`curate`
+  ranking** (#692). `asset_salience.rank_score` (an encoding + outcome +
+  retrieval projection, recomputed every `improve` run) previously composed
+  into every default search as a bounded multiplicative boost
+  (`salience-ranking`, ×[1.0–1.2]), loaded best-effort from `state.db` on the
+  hot path. On live data it measured as noise (max observed multiplier
+  ×1.071, mean ×1.016): the boost was retrieval-dominated with no source
+  filter — double-counting the same `usage_events` the utility-score
+  contributor already reinforces — warm-started non-zero with no outcome
+  evidence, and had zero pack coverage, so it could only ever favor
+  self-generated personal assets over an equally-relevant pack asset.
+  Removing the default `state.db` load also fixes a confirmed hot-path
+  defect: whenever `state.db` already existed, every default search
+  synchronously waited on the maintenance-activity barrier before ranking
+  could even start — up to a 5-second stall on a blocking wait loop, plus a
+  lock-file create, before the load's own 250ms SQLite `busy_timeout` ever
+  applied. No config gate was added: a key for a term being removed would be
+  dead surface for the upcoming 1.0 contract freeze to carry forever.
+  `rank_score` itself, and everything `improve` computes and does with it
+  internally, are unchanged — only its promotion into user-facing ranking is
+  removed. The contributor stays in the codebase (unwired) for a future
+  gated, outcome-backed experiment.
+- **Internal: `asset_salience` / `asset_outcome` state.db access moved behind
+  `src/storage/repositories/{salience,outcome}-repository.ts`** (#672 part 2).
+  Mirrors the existing state.db repository precedents
+  (`proposals-repository.ts`, `improve-runs-repository.ts`,
+  `events-repository.ts`): the raw SQL, row-mapping, and the #644
+  encoding-provenance CASE guards are extracted verbatim, only relocated —
+  `commands/improve/salience.ts` and `outcome-loop.ts` re-export the moved
+  functions, so no importer or test churns. A new `state-table-sql` rule in
+  `scripts/lint-repository-sql.ts` now fails the build if raw
+  `asset_salience`/`asset_outcome` SQL reappears outside the repository
+  directory (or `core/state/migrations.ts`). Not a user-visible behavior
+  change: `rank_score`, `outcome_score`, and everything `improve`/`health`
+  compute from them are identical.
+### Fixed
+- **The compiled standalone binary can run `akm migrate`.** Release binaries
+  compiled only `src/cli.ts`, and the migrator was resolved as a sibling file
+  and spawned — neither candidate exists inside a compiled executable, so the
+  documented `./akm-0.9 migrate status/apply` upgrade path always failed with
+  `FILE_NOT_FOUND`. Standalone builds now compile `scripts/akm-standalone.ts`,
+  a wrapper that embeds both the CLI and the migrator (src never imports
+  scripts/ — the dist build's tsc forbids it); `akm migrate` re-execs the
+  binary with an `AKM_MIGRATE_ENTRY` marker the wrapper dispatches on. The
+  repo and npm layouts keep the subprocess path.
+- **Quarantined migration rows are retained in full, not reduced to a count.**
+  When the 0.8→0.9 cutover met a durable ref it could not map, it recorded
+  surface/ref/count in `legacy_state` and then deleted the rows — destroying
+  proposal payloads, event and task history, fingerprints, and canary anchors,
+  contrary to the migration guide's "quarantined, not dropped". Complete rows
+  are now preserved as JSON in `legacy_state_rows` before leaving the live
+  tables.
+- **A failed content migration fails the apply instead of reporting success.**
+  Root discovery, sidecar folding, or the legacy-proposal import throwing was
+  swallowed and logged; the apply then advanced and cleared its journal, and —
+  because 0.9 removed the live `.stash.json` and filesystem-proposal readers —
+  the affected metadata and pending proposals became permanently inaccessible
+  behind an apparently successful upgrade. The step now fails the apply with
+  the journal intact; the committed cutover is untouched and the next apply
+  retries.
+- **Sidecar provenance survives the fold.** Folding a `.stash.json` into
+  frontmatter dropped `xrefs` and `sources` entirely and mapped legacy
+  `sourceRefs` to a `source_refs` key that could never fire (the validator
+  stopped copying the field) and that 0.9 never reads — then deleted the only
+  copy. `xrefs`/`sources` now fold through, and legacy `sourceRefs` merge into
+  `xrefs`.
+- **A reserved-filename rename re-keys durable state.** The D-R6 rename of a
+  mis-named `index.md`/`log.md` concept ran after the cutover had keyed usage,
+  salience, and proposal rows to the old conceptId, stranding that learned
+  state. The rename now feeds the same re-key engine the cutover uses, with
+  the pairs persisted before re-keying so a crash between the two stays
+  retryable.
+- **v1 tasks in a read-only bundle are surfaced with a remedy instead of being
+  silently skipped.** The 0.9 runtime removed the v1 task parser, so silently
+  skipping a `writable: false` bundle left tasks that would start failing after
+  an upgrade that reported current. The preflight now warns per bundle and
+  lists the stranded files in the plan (`readOnlyLegacyTasks`). It does not
+  block the apply: the migration deliberately never rewrites a read-only
+  bundle, and the fix for a lock-materialized git/npm bundle belongs upstream.
+- **Lock resolution metadata survives migration.** Merging the migrator's
+  sparse lock entries replaced whole rows by id, discarding
+  `resolvedVersion`/`resolvedRevision`/`integrity`/`installedAt` recorded by a
+  real install. Merge now preserves existing fields the incoming entry does
+  not define.
+- **Migrating a pre-0.9 config no longer silently changes source policy.**
+  Three settings were dropped by the config-shape migration: an explicit
+  `writable: false` (an omitted filesystem `writable` reads as `true` in the
+  new shape, so a source the user deliberately protected became writable), an
+  explicit `enabled: false` (resuming refreshes and indexing for content the
+  operator had turned off), and a website source's `maxDepth` (silently
+  resetting crawl depth). All three now round-trip to the runtime source entry;
+  `bundles.<id>.enabled` is a supported key.
+- **`akm mv` refuses a bundle marked `writable: false`.** It renamed the file
+  and rewrote citers anyway, because its preflight checked adapter
+  compatibility rather than writability — every other write command already
+  refused.
+- **Memory belief edges written by `--supersedes` are no longer ignored.**
+  `writeSupersededEdge` persists a fully-qualified conceptId, but the belief
+  analyzer accepted only the internal `memory:<name>` spelling, so every edge
+  from `akm remember --supersedes` / `akm import --supersedes` was dropped and
+  a superseded memory read back as active.
+- **`akm env run <ref> -- <cmd> --help` runs the command.** The builtin
+  help-flag scan read the child tail after `--` and printed akm's own usage
+  instead.
+- **`akm mv` works under an `AKM_STASH_DIR` override again.** A valid override
+  not owned by a configured bundle failed with `No configured bundle owns move
+  source`.
+- **An unexpected internal error exits 70 with the JSON failure envelope.** The
+  residual dispatch boundary exited 1 with an unstructured message, so
+  automation could not tell an internal defect from an ordinary failure.
+- **Concurrent `akm config set` processes no longer give up prematurely.** The
+  contended-lock wait budget was 500ms total, so several concurrent writers on
+  a loaded machine could exhaust it and fail with "Timed out waiting for config
+  lock" against a healthy but busy lock. Abandoned locks are still reclaimed by
+  the stale probe, which this budget does not gate.
+- **Config keys named in indexer output and comments now exist.** Four sites
+  pointed at a top-level `llm.*` namespace that the config schema has no such
+  key for — including the user-facing "Increase llm.timeoutMs" warning on an
+  exceeded enrichment budget. The enrichment budget lives at
+  `index.enrichment.timeoutMs` (or `index.defaults.timeoutMs`). Indexing
+  concurrency is auto-derived (2 remote / 1 local) and currently has no config
+  override on that path: `engines.<name>.concurrency` is a valid schema field
+  but the engine resolver does not forward it (documented in
+  `docs/architecture/internals/indexing.md`).
+- **The bundle-identity-drift warning stops naming a command that doesn't
+  exist.** It told users to "rekey it atomically via the bundle-rename
+  command"; 0.9.0 ships no such command. It now gives the two remedies that
+  work: restore the previous bundle id in `config.json`, or keep the new id and
+  `akm index --full` to re-mint, accepting the loss of learned state keyed to
+  the old id.
+- **The scaffolded `organization.md` convention no longer contradicts `akm
+  mv`.** It told authoring agents "there is no command that preserves an
+  asset's identity or learned state" across a rename and showed a raw `mv`.
+  `akm mv` does exactly that — it rewrites inbound refs and re-keys the index
+  row, usage history, and state.db salience/outcome rows. The convention now
+  points at it, flagged Experimental.
+- **`setup.taskSchedules` is no longer documented.** The key was removed from
+  the schema in 0.9.0 (nothing ever read or wrote it), but
+  `docs/reference/configuration.md` still described its two sub-keys.
+- **A freshly scaffolded stash passes its own `akm lint`.** All 12 shipped
+  `facts/conventions/**` convention templates carry frontmatter but none
+  carried an `updated` field, so the first `akm lint` after `akm init` flagged
+  12 `missing-updated` issues on files the user never wrote. The templates now
+  ship the field, and a regression test lints a freshly scaffolded stash and
+  requires nothing flagged.
+- **`akm show akm//meta` is the documented spelling for the primary stash.**
+  `docs/reference/cli.md` and `docs/guides/concepts.md` showed
+  `akm show local//meta`, which errors with `ASSET_NOT_FOUND` — `local//` is no
+  longer a scoping prefix, so it reads as a bundle named `local`.
+- **`akm sync` emits `shape: "sync"`.** The envelope kept the `"save"` shape
+  from the command's pre-rename name even after the persisted `eventType` was
+  renamed. Unlike the event log, the shape is per-invocation and never
+  persisted, so it needs no read-side synonym.
+- **`akm add <pkg> --provider npm` adds an npm source instead of a broken
+  filesystem bundle.** `--provider` was only read inside the remote-URL branch,
+  so any non-URL target fell through to the filesystem path with the flag
+  ignored, producing a bundle pointed at `<cwd>/<pkg>`. A URL target with
+  `--provider npm` is now rejected at add time rather than storing the URL as a
+  package spec and failing much later at first sync.
+- **`akm add --provider` no longer prints `Installed undefined`.** Two
+  incompatible result shapes reached one text formatter; each is now rendered
+  honestly, including whether a follow-up `akm update` or `akm index` is needed.
+- **`akm update --all` accounts for every configured source.** It previously
+  considered only registry-managed installs and reported `nothing to update`
+  for a stash full of plain sources — nothing was updated because nothing was
+  looked at. Plain git and npm sources are now synced (npm is promoted to a
+  lock-backed install on first sync) and website/filesystem sources are
+  reported through a new `skipped` field with the reason. A successful update of
+  a plain source no longer renders as `nothing to update` either.
+- **`akm search` with no query browses**, as `--help` has always documented,
+  instead of exiting 2.
+- **`akm curate --type <t>` curates within the type instead of bypassing
+  curation.** The filter skipped ranking, intent nudges, the score floor, and
+  family collapse entirely — and could return a hit of the *wrong* type while
+  dropping a higher-scoring correct one.
+- **`akm curate` respects `--limit` for registry hits**, which were capped at a
+  hard-coded 2 regardless.
+- **`akm search --no-project-context` works.** citty strips a leading `--no-`
+  before consulting declared args, so a flag *declared* as `no-project-context`
+  could never be set — the ranking boost was identical with and without it. The
+  flag users type is unchanged.
+- **`akm env run`, `akm secret run`, `akm migrate`, `akm agent`, `akm proposal new`,
+  `akm task run`, and `akm improve` no longer skip cleanup on exit.** They
+  called `process.exit()` directly — in two cases even on success — bypassing
+  teardown of spawned subprocesses. Exit codes, including forwarded non-zero
+  child codes, are unchanged.
+- **The `blocked` semantic-search warning names the cause.** It emitted one
+  fixed string for every failure and discarded the status ledger's reason, so
+  "no embedding provider configured" and "the configured endpoint is failing"
+  read identically.
+- **Shell completion for `--source` no longer suggests `stash|registry|both`
+  on commands where that enum doesn't apply.** `--source` means a closed
+  `stash|registry|both` enum on `akm search`/`akm curate`, but a free-form
+  stash name/path on every `akm graph` subcommand and a free-form URL/ref/
+  path on `akm remember`. The generated completion script keyed its value
+  list by flag name only, so the search/curate enum leaked onto `akm graph
+  --source <TAB>` and `akm remember --source <TAB>`. Value completion is now
+  scoped per command path; commands without a fixed value set get no
+  suggestion instead of the wrong one.
+- **`akm setup --config <file>` / `--from <file>` no longer silently drops
+  six valid config keys** (`index`, `search`, `feedback`,
+  `archiveRetentionDays`, `workflow`, `experimental`). The allowlist was a
+  hand-copied set that had drifted out of sync with the config schema; a
+  user handing setup a config containing any of these keys got a different,
+  silently truncated config written back, with only a warning and exit `0`.
+  The allowlist is now derived from the schema's own key list so it cannot
+  drift again. Keys that remain genuinely retired (`profiles`, `llm`,
+  `agent`, `features`, `stashes`, `bindings`, `writable`) still warn-and-drop
+  as before.
+  Note: a config that previously relied on one of these six keys being
+  ignored (because the drop was silent) will now have it applied — re-check
+  `--config`/`--from` inputs if you were unknowingly depending on that gap.
+- **`akm index` no longer persists adapter auto-detection to `config.json`
+  with zero disclosure.** Detecting and writing a bundle component's adapter
+  (`bundles.<id>.components.<component>.adapter`) previously happened
+  silently on every index run. It is now reported in the result envelope as
+  an additive `configUpdated.detectedAdapters` map and on stderr, and only
+  when a write actually happened.
+- **`akm add owner/repo` now resolves as GitHub shorthand instead of failing
+  with "Local path not found".** Any ref containing a `/` was treated as an
+  explicit local path, so the local-ref resolver threw before the
+  GitHub-shorthand fallback ever ran, making the advertised `owner/repo` form
+  unreachable. A bare two-segment `owner/repo` (or `owner/repo#ref`) now
+  falls through to the registry resolver when no such directory exists on
+  disk; `./`, `../`, absolute, and three-or-more-segment paths still resolve
+  as explicit local paths exactly as before.
+- **Internal output-shape command keys renamed `events-list`/`events-tail` →
+  `log-list`/`log-tail`**, matching the `akm log` command they back (the
+  command group used to be `akm events`, removed in 0.9.0). Internal-only:
+  the shape name is a registry lookup key that never reaches the wire (no
+  output field, no schema change), so this is not a user-visible behavior
+  change and carries no `schemaVersion` bump. The documented `[events-tail]`
+  stderr trailer text is deliberately left as-is pending a separate ruling.
+### Removed
+- **BREAKING: `akm upgrade --skip-checksum` is removed.** STABILITY.md has
+  always said checksum verification is not optional and that the recovery hatch
+  is an environment variable — but the flag shipped anyway, tab-completable,
+  while the documented variable existed nowhere in the source. The code now
+  matches the spec: set `AKM_UPGRADE_SKIP_CHECKSUM=1` if you must bypass a
+  genuinely broken `checksums.txt`. It is deliberately undiscoverable.
+- **BREAKING: `akm config enable|disable` is removed.** It was a hard-coded
+  toggle for one target, the skills.sh registry, and the bare `akm enable` /
+  `akm disable` aliases were already removed in 0.9.0. Use
+  `akm registry add|remove`.
+- **BREAKING: `akm mv` is removed.** No alias, no stub — `akm mv …` fails with
+  the standard unknown-command error. It claimed to preserve identity across a
+  rename, but its inbound-ref rewrite matched bare conceptIds rather than the
+  anchored `bundle//conceptId` prose form, so it could rewrite ordinary prose
+  while leaving real refs dangling. Renames are delete + create per
+  `STABILITY.md`: move the file, `akm index`, `akm lint`. The one capability
+  nothing else covered — carrying an asset's earned signal across the rename —
+  moves to `bun scripts/rekey-asset-ref.ts <old-ref> <new-ref>` (maintainer
+  tooling, `--dry-run` supported, idempotent), which re-keys the index
+  `entries` row in place plus the `asset_salience` / `asset_outcome` /
+  `usage_events` rows. The `mv` event type and output shape are gone; the
+  script emits a `rekey` event instead. A leftover `kind:"mv"` transaction
+  journal from an rc build is now swept by the recovery scanner rather than
+  failing it — an unregistered journal kind no longer bricks index refresh or
+  proposal accept/reject.
+- **The CHURN alert class is removed from the collapse detector.** Its input was
+  a hard-coded `0` from the 0.9.0 confidence-gate deletion onward, so the alert
+  could never fire. The other three alert classes are unaffected. The
+  `improve_cycle_metrics.accepted_actions` column stays and is written as `0`
+  because deployed 0.8 `state.db` files already contain it.
+- **`IndexResponse.graphQuality` is removed** from the `akm index` envelope — it
+  was declared but never assigned in any code path, so it was always absent.
+- **`akm secret path` and `akm secret remove` are removed.** The two resolved a
+  secret ref through *different* stash-selection logic — `path` through the
+  read-side, all-sources resolver and `remove` through the write-target
+  resolver — so for a ref present in more than one stash they could name
+  different files: you could inspect one secret and delete another. Rather than
+  reconcile the resolvers, both subcommands are gone; `akm secret` now exposes
+  only `list`, `run`, and `set`. Both spellings exit 2 with `Unknown command`.
+  Migration: a ref's file lives at `<stash>/secrets/<name>` (run `akm sources
+  list` for stash roots) — locate or delete it directly, or use `akm secret run
+  <ref> <VAR> -- <command>` to consume the value without it touching disk. `akm
+  env path` and `akm env remove` are unaffected.
+- Removed the dead `"backup"` output-shape registration left over from the
+  removed `akm backup` command (superseded by `akm-migrate backup`). Already
+  unreachable; no user-visible effect.
+- **`akm task list`, `akm task show`, and `akm task remove` are removed** as
+  redundant with the generic asset commands. List and inspect tasks with `akm
+  search` / `akm show <bundle//tasks/id>` (both already cross-bundle); to remove a
+  scheduled task, delete its file in the owning bundle and run `akm task sync`
+  (sync uninstalls the orphaned scheduler entry). Run `akm task doctor` for
+  scheduler diagnostics — bare `akm task` is a usage error, see the canonical
+  bare-group change above.
+- **The `akm show <ref> toc|section|lines|frontmatter|full` view-mode grammar is
+  removed** (0.9.0 decision D2). `#fragment` is now the only section selector,
+  and a positional after the ref is a usage error that names it. Migration:
+  | Old | New |
+  | --- | --- |
+  | `akm show knowledge/guide section "Auth"` | `akm show knowledge/guide#auth` |
+  | `akm show knowledge/guide full` | `akm show knowledge/guide` |
+  | `akm show knowledge/guide toc` | `akm show knowledge/guide#<unmatched>` — the error lists the available fragment slugs |
+  | `akm show knowledge/guide lines 10 30` | no replacement — every response carries `path`, so slice the file yourself |
+  | `akm show knowledge/guide frontmatter` | no replacement — if a raw-YAML projection proves necessary it returns as a `--shape` value |
+  The undocumented `--akmView` / `--akmHeading` / `--akmStart` / `--akmEnd`
+  flags the grammar injected into argv are gone with it.
+## [0.9.0] (planned)
+0.9.0 is the format-neutral **bundle / adapter** refactor: it replaces the flat
+asset-type registry with per-format adapters, adopts one canonical ref grammar,
+and consolidates the durable databases and config. This section supersedes the
+earlier `0.9.0-rc.1` / `0.9.0-beta.*` development entries below.
+### Breaking changes & migration
+- **Installed non-akm bundles reclassify on your next `akm index`.** The
+  indexer now dispatches each installed bundle's *detected* adapter (Claude
+  tool dirs, LLM wikis, website snapshots, agent-skills packs, …) instead of
+  recognizing everything with the akm-stash adapter. Entries in such bundles
+  change type and ref spelling to the owning adapter's own scheme the first
+  time you reindex. No action needed — the index is a regenerable cache and
+  rebuilds itself — but searches/saved refs into those bundles may resolve to
+  the new spellings afterwards.
+- **Ref grammar cutover — `type:name` → `[bundle//]conceptId`.** Every ref is
+  now a subdir-qualified concept id inside its bundle (`skills/code-review`,
+  `memories/vpn-note`, `env/prod`), optionally prefixed with a `bundle//`
+  installation slug and suffixed with `#fragment`. Durable state stores the
+  fully-qualified `bundle//conceptId`; the short bundle-omitted form is accepted
+  input only (resolved against `defaultBundle`, then installation-priority
+  order). The pre-0.9.0 `[origin//]type:name` grammar is removed — there is no
+  compatibility parser; the frozen migrator in `scripts/akm-migrate/migrate/`
+  is the only place it survives.
+- **Explicit, crash-resumable cutover (`akm migrate apply`).** The
+  migrator re-keys all durable state to the new spelling, folds the former
+  `workflow.db` into `state.db` (four databases down to three: `state.db` /
+  `index.db` / a separate `logs.db`), and migrates config from the flat
+  `stashDir` / `sources` / `installed` / `wikiName` keys to `bundles` /
+  `defaultBundle`. A semantically verified, installation-scoped **backup manifest v4**
+  (covering the pre-rescue `index.db`) is taken before mutation. One phase-free
+  incomplete sentinel retains that backup and target; expected orphans are
+  quarantined, integrity failures fail closed, and the whole cutover reruns
+  idempotently after a crash. Normal commands refuse an
+  un-migrated or divergent durable schema rather than migrating as a side effect.
+  The retired `stashDir` / `sources` / `installed` keys are **hard-rejected** by
+  the 0.9.0 config schema whenever present (the error names `akm migrate apply`);
+  registry-installed bundles keep only their desired locator (`git`/`npm` +
+  `registryId`) in config, with resolved cache state living exclusively in the
+  lockfile.
+- **`index.md` / `log.md` are reserved structural files.** Per the Open
+  Knowledge Format, `index.md` (directory listing) and `log.md` (update history)
+  are never indexed as concepts and are never valid write / `mv` targets at any
+  bundle depth. Existing stash files with those names are excluded from the
+  index (and renamed by the content migration when they hold a real concept).
+- **`vault` asset type removed.** Use `env` (a whole `.env` group; key names
+  surfaced, values never) and `secret` (a single sensitive value), addressed as
+  `env/<name>` and `secrets/<name>`. `akm-migrate storage` performs the
+  non-destructive `vaults/` → `env/` copy for older stashes.
+- **0.8-era CLI aliases removed.** The flat proposal verbs (`akm proposals`,
+  `akm accept`, `akm reject`, `akm diff`, `akm revert`, `akm show proposal`),
+  `akm save`, top-level `akm enable` / `akm disable`, `akm events`,
+  `--detail summary|agent`, `--for-agent`, `--note`, and `--source` (on
+  accept/reject/history) are gone — use the canonical spellings documented in
+  `STABILITY.md`.
+See `docs/migration/v0.8-to-v0.9.md` and
+`docs/migration/release-notes/0.9.0.md` for the full upgrade procedure.
+### Added
+- **Local downstream value attribution for memory inference and graph
+  extraction.** Private search-hit sidecars now write versioned, source-qualified
+  per-entry `usage_events.metadata` for emitted MI direct/surface value and the
+  active graph contributor's positive applied/capped contribution. Current plain
+  traffic is marked as control, brief/replaced MI surfaces and graph ablations do
+  not claim attribution, and nested curate reads avoid duplicate show rows. The
+  read-only `akm-eval-attribution-rollup` separates user-only exposure,
+  selection/show consumption, current controls, and historical unattributed rows
+  without emitting bodies, query text, or provenance content. Graph contribution
+  is an input attribution signal, not a causal claim that rank changed. No table,
+  migration, dashboard, or health schema was added.
+- **Explicit, crash-resumable 0.9 migration coordination.** `akm migrate
+  status` classifies config, `state.db`, and `workflow.db` independently;
+  `akm migrate apply [--config <prepared>]` creates a semantically verified,
+  installation-scoped config/database backup before applying pending migrations.
+  Apply and restore use one phase-free incomplete sentinel, bounded control-file
+  reads, SQLite integrity and ordered-ledger checks, active-writer barriers,
+  WAL/SHM-safe publication, and idempotent replay. Legacy checksum columns are
+  inert. Routine reads and current database opens no longer depend on a
+  historical cutover bundle. See `docs/migration/release-notes/0.9.0.md`.
 - **Workflow orchestration engine (experimental).** akm can now execute
-  multi-step workflows as deterministic **YAML programs**, driven either by a
-  native engine or by any agent session. This is a new, self-contained
-  surface; classic linear **markdown workflows and the stable workflow CLI
-  contract (`start`/`next`/`complete`/`status`/`list`) are unchanged**. What
-  ships:
-  - **Authoring.** Orchestrated workflows are YAML programs
-    (`workflows/*.yaml`, `version: 1`) validated against a published JSON
-    Schema (`schemas/akm-workflow.json`) by `akm workflow validate`; scaffold
-    one with `akm workflow template --yaml` or `akm workflow create
-    <name>.yaml`. A closed `${{ … }}` expression language (exactly
-    `params.<name>`, `steps.<id>.output.<path>`, `item`, `item_index`, parsed
-    once into an AST) wires steps together. `validate` also surfaces non-fatal
-    **warnings** (a step with no typed `output:` schema; a `${{ params.<name> }}`
-    reference to a param the declared `params:` block omits) that never change
-    the frozen plan or its hash. Creating a workflow whose canonical name
-    collides with an existing asset of a **different** extension (`foo.yaml`
-    while `foo.md` exists, or vice-versa) is refused, since the two would
-    silently shadow each other.
-  - **Compilation + frozen plans.** `akm workflow start` compiles the program
+  multi-step workflows through a native engine or any agent session. Workflow
+  assets use the unified markdown format described above; the stable manual
+  CLI contract (`start`/`next`/`complete`/`status`/`list`) and the experimental
+  engine consume the same asset. What ships:
+  - **Authoring.** A workflow is a markdown asset whose frontmatter graph is
+    validated against `schemas/akm-workflow.json` and whose `## <step-id>` body
+    sections carry instructions and gate rubrics. `akm workflow create`
+    scaffolds that format; `akm lint --type workflows` parses and compiles it.
+    Bare references (`params.<name>` and `steps.<id>.output.<path>`) wire
+    `map.over`, `route.input`, and `inputs`; prose is never interpolated.
+  - **Compilation + frozen plans.** `akm workflow start` compiles the workflow
     into a backend-agnostic Workflow Plan Graph IR (`src/workflows/ir/`) and
     freezes it on the run row (`plan_json` + `plan_hash`); a run executes the
     plan compiled at start, and edits to the source file require a new run.
-  - **Per-step orchestration.** A step can declare a runner, model, timeout,
+  - **Per-step orchestration.** A step can declare an engine, model, timeout,
     fan-out (`map`/`over` with a `concurrency` cap and a `collect` | `vote`
     reducer), a typed `output` JSON Schema (validated via a `runStructured`
     retry-with-feedback loop), `env` bindings (resolved through the existing
     `akm env run` machinery — secret tokens, dangerous-key policy, keys-only
-    audit events), classify-and-dispatch `route` steps, and `depends_on`
-    ordering.
+    audit events), and classify-and-dispatch `route` steps.
   - **Determinism + replay.** Journaled unit identity is content-derived
     (`<step>:<sha256(item)[:12]>`, `:solo` for a single unit), so cached
     results survive item-list reordering; a completed unit whose recorded
@@ -46,9 +1018,9 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
     `workflow_run_units` table behind a serialized writer queue.
   - **Execution (`akm workflow run`).** A semaphore-bounded scheduler fans a
     step's units out (concurrency defaults to 1 per the local-model
-    LLM-defaults rule, capped by the engine-wide `workflow.maxConcurrency`
-    config knob — unset = `min(16, max(1, cores − 2))`, explicit values
-    clamped to `[1, 64]`), enforces per-unit
+    LLM-defaults rule and is the minimum of the map request, frozen workflow
+    limit, selected frozen LLM engine limit, and current host safety limit),
+    enforces per-unit
     timeouts (default 10 m) and run **budget ceilings** (`budget.max_tokens` /
     `budget.max_units`, seeded from the journal so they span resumes), and
     advances the run **strictly through `completeWorkflowStep`** so completion
@@ -59,9 +1031,9 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
     criteria-bearing gate judges that **artifact** (canonical JSON, clipped)
     rather than machine prose, and each engine-driven evaluation is journaled
     as a gate unit row. `gate.max_loops` bounds an evaluator-optimizer retry
-    loop (feedback threaded into re-dispatched unit prompts); `gate.required`
-    (or the run-wide `--require-gates`) makes a gate with no available judge
-    **block** for a human instead of failing open.
+    loop (feedback threaded into re-dispatched unit prompts). Gates are
+    optional validation: omitted/empty rubrics and unavailable or malformed
+    judges skip validation.
   - **Failure policy.** Per-unit `on_error: fail | continue` (fail-fast
     default) plus bounded `retry: { max, on: [<failure_reason>…] }` keyed on
     the persisted failure taxonomy.
@@ -105,21 +1077,279 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
     result extractor; agent-identity detection and the session-log provider
     list are derived from the registry, and harness-native session ids are
     journaled opportunistically for future session reuse.
-  - **Storage.** Additive `workflow.db` migrations 004–009 (unit journal,
+  - **Storage.** Additive `workflow.db` migrations 004–010 (unit journal,
     harness session ids, frozen plans + run leases, check-in heartbeats,
     attempt counter, unit claims); migrations 001–003 are untouched and linear
     workflows behave exactly as before.
   See "Orchestrated steps" and "Driving a run from any agent" in
   `docs/features/workflows.md`, the redesign addendum in
-  `docs/technical/akm-workflows-orchestration-plan.md`, and `STABILITY.md`
+  `docs/archive/akm-workflows-orchestration-plan.md`, and `STABILITY.md`
   (Experimental).
 - **`fable` built-in model alias** — resolves to `claude-fable-5`
   (`opencode/claude-fable-5` on opencode); recommended resolution target for
   the `deep` workflow model tier.
+- **`akm lint` now checks the frontmatter xref channels for broken refs.**
+  The existing `missing-ref` check additionally scans the `xrefs:`,
+  `supersededBy:`, and `contradictedBy:` frontmatter keys of non-wiki markdown
+  assets (memories, knowledge, lessons, facts, agents, commands, skills,
+  workflows) — the channels the stash back-linking conventions route
+  provenance and correction links through, and previously the only ref channel
+  with zero checking. Dangling refs are flagged with a detail naming the key
+  (`missing ref: <ref> (frontmatter <key>; resolved to <relPath>)`). The
+  `refs: []` body-scan carve-out does not suppress the new pass; `lint_skip:
+  [missing-ref]` suppresses both; non-ref values (URLs, `raw/<slug>`,
+  `<placeholder>` templates, shell vars) are ignored; refs resolving in a
+  configured extra stash root stay clean. **Note for `--fail-on-flagged` CI
+  users:** stashes with already-dangling xrefs (e.g. from past renames) will
+  gain new `missing-ref` findings on upgrade — fix the refs or add
+  `lint_skip: [missing-ref]` per file. `sources:`, `source_refs:`, and
+  `evidenceSources:` are deliberately not checked (wiki `sources:` is covered
+  by `akm wiki lint`; the latter two legitimately point at merged-away
+  assets).
+- **`--xref <ref>` on `akm remember` and `akm import` — write-time
+  cross-references with validation.** The stash back-linking conventions route
+  provenance and associative links through `xrefs:` frontmatter, but neither
+  CLI write flow could express them (remember always generated its own
+  frontmatter block; import wrote content verbatim). The new repeatable flag
+  records refs in the written asset's `xrefs:` frontmatter list, which the
+  indexer folds into search hints — the new asset becomes findable from
+  searches for its source. `remember` merges the refs into its generated
+  frontmatter (composes with `--tag`/scope flags; does not trigger the
+  tags-required check); `import` dedupe-appends into the document's existing
+  frontmatter, or adds a block when the document has none — never a nested
+  second block. A document whose existing frontmatter is not a parseable YAML
+  mapping aborts the import (exit 2, nothing written) rather than being
+  rewritten lossily; importing it without `--xref` still preserves it
+  verbatim. Every ref is validated before anything is written, against the
+  write target plus all configured sources (read-only cross-stash sources
+  count): an unresolvable ref fails with the standard usage envelope (exit 2)
+  and leaves the stash untouched. The conventions' ~5-xref cap stays soft —
+  exceeding it warns on stderr but still writes. Additionally, a type-root
+  write (no `--path`, flat name) into a stash carrying convention facts now
+  returns an additive `hint` output key pointing at the stash's placement
+  conventions (`facts/conventions/organization` when that fact exists), so CLI
+  writers see the conventions that LLM flows already receive by injection.
+- **`--supersedes <ref>` on `akm remember` and `akm import` — atomic
+  correction + demotion of the superseded asset.** The stash conventions'
+  corrections pattern needs TWO writes (the new correction asset with an xref
+  to what it corrects, plus a metadata edit demoting the old asset), which
+  previously meant hand-editing the old file's frontmatter and remembering to
+  reindex it. The new repeatable flag does both: the correction is written
+  with the old ref folded into its `xrefs:` (correction provenance), and the
+  old asset gains `beliefState: superseded` +
+  `supersededBy: [<new ref>]` via the shared `writeSupersededEdge` primitive
+  (sibling of `writeContradictEdge`) — a metadata-only frontmatter edit that
+  preserves every other key and the body byte-for-byte, sorted-set-appended
+  and idempotent across re-runs. The mutated old file is reindexed by the
+  write path, so `--belief current` hides it and ranking demotes it
+  immediately. An unresolvable ref is input validation: exit 2 with the
+  standard `{ok:false,error,code}` envelope and NOTHING written or demoted
+  (no partial correction); a ref resolving to the asset being written itself
+  (self-supersede via `--force` overwrite) is rejected the same way instead
+  of letting a correction demote itself. An old asset that resolves only
+  outside the write target and the working stash (in a read-only source, or
+  in a writable source that is not this write's target) is not mutated: the
+  correction still writes, stderr warns, and the JSON output reports the
+  additive `superseded: [{ref, applied: false, reason}]` key (`applied: true`
+  on success) — the reason names the `--target` remedy when one exists. An
+  old asset whose existing frontmatter is not parseable YAML is likewise
+  skipped (`applied: false`) rather than rewritten through the lossy lenient
+  parser. On a git write target the demotion is ordered before the
+  batch-at-boundary commit, so the correction and the demoted old asset land
+  in one commit.
+- **Ref-prefix search queries — `akm search "<subdir>/<prefix>/"` now enumerates
+  that subtree.** A query shaped like a ref prefix (trailing slash required:
+  `memories/projectA/`; a bare `memories/` lists the whole type) translates to a
+  typed index enumeration narrowed to entry names under the prefix, instead of
+  degenerating into the AND-token FTS query its sanitized form used to produce
+  (`"memory projectA"` — noise, since `entry_type` is not an FTS column). The
+  listing is recursive and `/`-boundary exact (`projectA/` cannot leak a
+  sibling `projectAlpha/…` scope), matches names case-insensitively (the CLI
+  lowercases queries; on-disk scope directories may carry mixed case), and
+  composes with `--limit`, `--belief`, `--filter`, and named `--source`
+  narrowing exactly like the existing empty-query enumeration — hits carry the
+  fixed browse score `1` in deterministic listing order, not a relevance
+  ranking. The parsed type is explicit intent: a bare `sessions/` enumerates
+  sessions just like `--type session` (the default session exclusion is an
+  untyped-path policy), while an explicit `--type` flag always wins over the
+  type parsed from the query (the branch fires only on untyped searches). A
+  full ref without the trailing slash (`memories/projectA/auth-tip`) stays an
+  ordinary keyword search — resolving a single ref is `akm show`'s job.
+  **Stable-surface note:** `akm search` is Stable; this changes results for a
+  query shape that previously returned noise or nothing. A user literally
+  keyword-searching for the string `memories/x/` loses the old fuzzy token
+  behavior — accepted as negligible.
+- **The `category:` frontmatter key is now captured into the index** as
+  `entry.category` (entry_json only — no schema migration). The key already
+  drives convention-fact prompt injection (`resolveStashStandards`) and the
+  fact linter, but the indexer never captured it, so no category-keyed search
+  or ranking policy was implementable. Captured for all markdown asset types
+  alongside `beliefState` (trimmed; blank/non-string values ignored; no
+  default invented), captured directly onto the index entry. Search results
+  and ranking are unchanged — this is capture
+  only (a unit test pins that `category` never enters the FTS search
+  fields). **Requires a reindex to take effect** for existing entries. The
+  companion rank-time demotion of `category: convention` facts on untyped
+  queries was NOT shipped: the prescribed measurement (full skeleton
+  convention facts plus a real `knowledge/auth` asset, untyped `auth` query,
+  semantic off) shows no crowding — FTS is exact-first, so prefix expansion
+  onto the facts' tokens only happens when nothing matches the query exactly,
+  and a real domain asset always outranks the facts. That invariant is pinned
+  by `tests/search-convention-fact-demotion.test.ts`, which becomes the
+  regression guard if a demotion contributor is ever revisited.
+- **Config-gated indexing of the self-situating body opening —
+  `index.indexBodyOpening` (default `false`).** Body prose is not indexed
+  (the FTS `content` column carries only TOC headings and parameters), which
+  is why the stash conventions route orientation into
+  `description:`/`when_to_use:`. With the new flag enabled, the metadata pass
+  captures the first prose paragraph of each markdown asset body — skipping
+  headings (ATX and setext), fenced code blocks, thematic breaks, and a
+  leading nested frontmatter block (only when its content is actually
+  frontmatter-shaped: prose wrapped in decorative `---` lines is captured,
+  not discarded); capped at 280 chars with word-boundary truncation and a
+  trailing ellipsis — into `entry.bodyOpening`, which folds into the
+  lowest-weight `content` FTS column (bm25 weight 1.0, so a name match always
+  outranks a body-opening-only match) and into the search/embedding text.
+  Secret and env files are never read for it, and session-kind memories
+  (`akm_memory_kind` in outer or nested inner frontmatter) are excluded —
+  their bodies are raw transcripts. Both indexing walks and write-path
+  indexing honor the flag (the metadata pass reads the user config directly).
+  With the flag absent or `false`, entries and search fields stay
+  byte-identical to before. **Costs of toggling (either direction):** indexed
+  text changes, so collapse-detector canary recall baselines shift — re-mint
+  via `akm improve canary --refresh` — and embeddings are NOT regenerated for
+  entries that already have one, while incremental runs re-extract only
+  changed files. Run `akm index --full` after toggling: it re-extracts every
+  entry and wipes embeddings so they rebuild from the new text; until then
+  `akm index` warns that the flag differs from the state the index was built
+  with. The conventions' `description:`/`when_to_use:` orientation routing
+  remains primary — this flag makes body openings additionally pay retrieval
+  rent, it does not replace structured metadata. See `docs/configuration.md`.
+- **`akm mv <ref> <new-name>` — rename with inbound-xref rewrite and
+  utility-history preservation (Experimental).** The stash conventions'
+  forced-rename procedure ("grep and fix inbound xrefs in the same pass") was
+  agent-executable except for the part only the CLI can do: a rename used to
+  mint a new index row, orphaning the `utility_scores` /
+  `utility_scores_scoped` / embeddings / salience rows keyed by entry id —
+  the "rename resets learned ranking" cost the conventions warn about. The
+  new verb does the whole pass: it moves the file (a memory's `.derived.md`
+  twin moves together, keeping the `entry_key + ".derived"` belief-inheritance
+  coupling), rewrites inbound refs across the writable stash's markdown files
+  — body prose, frontmatter ref-list keys (`xrefs:`/`refs:`/`supersededBy:`/
+  …), and fenced code blocks — with complete-ref boundary matching (a longer
+  ref sharing the old ref as a prefix is untouched), and re-keys the index
+  row **in place** so the row id and every id-keyed ranking table survive;
+  the moved row and rewritten citers are FTS-refreshed so search reflects the
+  new name immediately. Scope v1: flat-markdown asset types (`memory`,
+  `knowledge`, `command`, `agent`, `workflow`, `lesson`, `session`, `fact`)
+  in the primary writable stash only, and the source ref must be the
+  canonical spelling — a ref that resolves only through one of lint's
+  fallback resolutions (knowledge-subdir alias, direct-path) is rejected
+  naming the canonical ref, since a fallback-keyed move would strand the
+  index row and dangle canonical citers. Wiki refs, cross-type targets,
+  existing targets, unresolvable refs, type-root escapes, `.derived` twin
+  refs as the source (rename the base — the twin follows), and target names
+  ending in `.derived` (reserved twin suffix) are rejected with the
+  standard envelope (exit 2, nothing moved). Read-only sources are scanned
+  but never written — their citing files are reported in `readOnlyCiters` as
+  manual follow-ups. Output:
+  `{ok, from, to, rewrote: [{file, count}], readOnlyCiters, utilityPreserved}`;
+  a successful move appends an exactly-once `mv` event. A durable mutation
+  journal stages citer rewrites and the asset publication, preserves
+  source-qualified utility/salience history, and resumes index/state
+  finalization after interruption. Divergent citers and late-created targets
+  fail closed instead of being overwritten. Added to the v1 §9.4 command
+  surface as an Experimental-tier additive entry (see `STABILITY.md`).
+### Changed
+- **Improve-stage extraction and proactive maintenance now ship opt-in.** The
+  built-in `default` and `frequent` strategies resolve extract off, while
+  `default` and `reflect-distill` resolve `proactiveMaintenance` off. The
+  dedicated `proactive-maintenance` strategy remains enabled. Built-ins such as
+  `thorough` that omit these fields inherit the new `default` off values; user
+  overrides are merged last, so explicit `enabled: true` values still win.
+  Standalone extraction remains independent of the improve-stage toggle but
+  still requires `--type <harness>` or `--auto`. The bundled, unselected
+  `core/extract` task now uses `akm extract --auto`; existing scheduled tasks
+  with invalid bare `akm extract` commands must be updated explicitly.
+- **Indexing dispatches each bundle's detected adapter.** The indexer's per-
+  directory scan now resolves the component's adapter (`adapterForId`) and runs
+  THAT adapter's `recognize`, instead of always using the `akm` adapter. A
+  component whose adapter id is unknown is skipped with a warning. Adapter-owned
+  filtering moves the AKM-stash sensitive/infra exclusions (env/secret
+  `.sensitive`-marker skips, the legacy `vaults/` skip, wiki infra files) out of
+  the core scan and into the `akm` adapter's own recognition, so each adapter
+  owns its bundle's filtering. **Reindex note:** any non-`akm` bundle that was
+  previously probed as one adapter id but still recognized by `akm` will
+  re-index under its own adapter on the next `akm index` — the index is a
+  regenerable cache, so no migration is required.
+- **Improve target identity is now end-to-end and source-qualified.** Explicit
+  targets govern reads, generated proposals, triage promotion, consolidation,
+  retrieval signals, cooldowns, and replay state. Duplicate bare refs in other
+  sources no longer affect the selected corpus. Generated lessons and
+  provenance follow stash placement conventions and canonical `xrefs`.
+- **Writable Git boundaries commit only operation-owned paths.** Improve,
+  proposal, supersedes, and direct write flows preserve unrelated staged or
+  dirty work, including files beside generated assets in `content/` layouts.
+- **Directory (scope/domain) tokens now always merge into `tags` at index
+  time**, even when an asset sets explicit `tags:` frontmatter. Previously
+  explicit tags suppressed all path-derived tags, so a nested asset like
+  `memories/projectA/auth-tip` with `tags: [auth]` silently lost the exact
+  tag-match ranking boost for its scope token unless the author restated it.
+  The merged tokens come from the canonical ref subpath
+  (`extractDirTagsFromName`), which also fixes the flat-walk indexing path
+  losing directory segments in the empty-tags fallback. Filename tokens are
+  still auto-derived only when `tags` is empty (they already live in the FTS
+  name column and aliases), and the empty-tags fallback itself is unchanged.
+  **Operator notes:** the change takes effect on the next reindex and alters
+  indexed tag text for nested assets with explicit tags, so collapse-detector
+  canary recall baselines may shift — re-mint them with `akm improve canary
+  --refresh`. Embeddings are not regenerated when indexed text changes; the
+  drift here is small (the merged tokens already appear in the name field),
+  but a purge/re-embed picks up the new text exactly.
+- **Demoting belief states now cap an entry's final search score**
+  (superseded ≤ 0.25, contradicted ≤ 0.2, archived ≤ 0.15, deprecated ≤
+  0.28). The existing additive belief penalties are applied inside the
+  multiplicative boost sum on a min-max-normalized FTS base (rank-1 vs rank-2
+  base can differ by up to 0.7), so a superseded incumbent that was the best
+  keyword match stayed clamp-pinned at 1.0 above its own correction — the
+  demotion was invisible exactly when the corrections pattern needs it. The
+  ceiling is applied once at the end of the single scoring pipeline (sort
+  order and displayed scores stay consistent); demoted entries remain listed
+  under the default `--belief all`, keep their relative ordering, and the
+  `--belief` filter axis is unchanged. Semantic-only hits are judged against
+  the `search.minScore` floor by their pre-ceiling score, so a ceiling below
+  the floor (archived 0.15 < default 0.2) ranks the hit last instead of
+  silently dropping it. Ordering changes only for stashes containing
+  belief-flagged assets.
+- **`mutateFrontmatter` (belief-edge writers: supersede/contradict edges,
+  belief refresh) now preserves the body bytes verbatim** when the file
+  already has a frontmatter block, instead of re-normalizing the
+  fence-to-body separator through `assembleAsset`. A metadata edit is no
+  longer a (whitespace-level) content edit; files gaining their first
+  frontmatter block still use the canonical shape.
 ### Fixed
+- **Improve RC stabilization.** Restored one ownership-safe whole-run lock from
+  triage through final sync; `--skip-if-locked` is a true no-op; the run deadline
+  now starts before indexing and reaches index waits, generation, reindexing, and
+  quality judges; reflect judges the sanitized final candidate with bounded
+  changed-region context; write-target selectors no longer replace durable source
+  identity; and vLLM thinking controls cannot be overridden through `extraParams`.
+- **Proposal promotion, reversion, and rejection are durable and recoverable.**
+  Acceptance and reversion persist target ownership and content fingerprints,
+  publish atomically across filesystem layouts, index immediately, commit exact
+  Git paths, and emit idempotent lifecycle events. Crash recovery and legacy
+  accepted proposals fail closed on ambiguous targets instead of clobbering
+  another source.
+- **Engine/setup/health behavior now matches the effective improve plan.**
+  Built-in strategies compose over one baseline, setup preserves independent
+  general and LLM defaults, native OpenCode SDK execution does not require an
+  unused fallback, and health checks each enabled process and credential.
 - **Check-in directives now survive plain-text output and `workflow
   status`** (check-in review C2/M1): `formatWorkflowNextPlain` and
   `formatWorkflowStatusPlain` render the `CONTINUE` directive, and every
@@ -129,7 +1359,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
   keys (`name`, `updated` were missing); removed the documented-but-nonexistent
   `akm workflow step` alias from `docs/features/workflows.md`.
-## [0.9.0] — 2026-06-30
+## [0.9.0-rc.1] - 2026-06-30
 ### Fixed
@@ -268,7 +1498,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
   convention, or `.meta/index.md` files. Seeding stays absent-only and never
   overwrites a user-edited file. (#646)
-## [0.9.0-beta.36] — 2026-06-22
+## [0.9.0-beta.36] - 2026-06-22
 ### Added
@@ -303,7 +1533,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 - Corrected a prompt/validator drift where the distill system prompt asked for an
   80–200 char description while the gate enforced 20–400. (#645)
-## [0.9.0-beta.35] — 2026-06-21
+## [0.9.0-beta.35] - 2026-06-21
 ### Fixed
@@ -331,7 +1561,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
   LLM call per processed session (the session summary); set it to `false` to halve
   per-session extract cost. Unchanged/skipped sessions still cost zero.
-## [0.9.0-beta.34] — 2026-06-21
+## [0.9.0-beta.34] - 2026-06-21
 ### Fixed
@@ -346,7 +1576,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
   and falls back to the JSON layout. Verified end-to-end through the plugin's
   `session.idle` hook.
-## [0.9.0-beta.33] — 2026-06-21
+## [0.9.0-beta.33] - 2026-06-21
 ### Fixed
@@ -362,7 +1592,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
   already-extracted session with zero LLM calls) and only `--force` re-extracts. This
   makes a session-end hook firing `extract --session-id <id>` precise AND idempotent.
-## [0.9.0-beta.32] — 2026-06-21
+## [0.9.0-beta.32] - 2026-06-21
 ### Added
@@ -388,7 +1618,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
   with freshly-read timestamp maps INSIDE the lock (`filterProactiveDue`), dropping
   refs a concurrent run already reflected.
-## [0.9.0-beta.31] — 2026-06-20
+## [0.9.0-beta.31] - 2026-06-20
 ### Changed
@@ -401,7 +1631,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
   On the live stash this turns the recombine cluster set from generic 66–171-member
   buckets into tight topical clusters (`auth`, `architecture`, `patterns`, …).
-## [0.9.0-beta.30] — 2026-06-20
+## [0.9.0-beta.30] - 2026-06-20
 ### Changed / Fixed
@@ -420,7 +1650,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
   membership-overlap (≥ 0.7) and reuses its stable ref, so the streak accumulates
   through membership drift. First/non-overlapping induction is unchanged.
-## [0.9.0-beta.29] — 2026-06-20
+## [0.9.0-beta.29] - 2026-06-20
 ### Reverted
@@ -428,7 +1658,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
   `akm fact` CLI shipped in beta.28 was reverted pending rework. Phase 1 (#629, the
   `fact` asset type itself) remains in place.
-## [0.9.0-beta.27] — 2026-06-20
+## [0.9.0-beta.27] - 2026-06-20
 All new behavior is **opt-in / default-preserving** — default runs are byte-identical.
@@ -474,7 +1704,7 @@ All new behavior is **opt-in / default-preserving** — default runs are byte-id
   hang/timeout** (the busy-spin can rarely fire even at `--parallel=1`) and never
   on a real test failure, so genuine red tests still fail fast and are never masked.
-## [0.9.0-beta.26] — 2026-06-20
+## [0.9.0-beta.26] - 2026-06-20
 ### Added
@@ -491,7 +1721,7 @@ All new behavior is **opt-in / default-preserving** — default runs are byte-id
   Azure Container Apps). New docs section "Hosting AKM databases on a network share
   (NFS/SMB)" in `docs/configuration.md`.
-## [0.9.0-beta.25] — 2026-06-19
+## [0.9.0-beta.25] - 2026-06-19
 Completes the recombine / extract-efficiency / graph thread. All new improve
 passes are **opt-in (default off)**, so default behavior is unchanged.
@@ -529,20 +1759,20 @@ passes are **opt-in (default off)**, so default behavior is unchanged.
   sandbox dirs left by force-killed workers — eliminating the tmpfs accumulation
   that caused intermittent `EEXIST: epoll_ctl` test flakes.
-## [0.9.0-beta.20] — 2026-06-18
+## [0.9.0-beta.20] - 2026-06-18
 ### Fixed
 - **`akm update --all` no longer fails for writable `github:` entries stored as `source:"git"`**. `updateRegistryEntry` was using `synced.source` (re-derived from the ref scheme as `"github"`) instead of the existing `entry.source`, causing the config validator to reject `writable:true` on every update cycle.
-## [0.9.0-beta.19] — 2026-06-17
+## [0.9.0-beta.19] - 2026-06-17
 ### Fixed
 - **`akm feedback` now completes in ~0.3s** (was 3+ minutes). Root cause: the command was calling `ensureIndex` with `mode: "blocking"` inside `withIndexWriterLease`, triggering a full reindex on every feedback call. Fix: removed the `ensureIndex` call entirely (feedback only needs the index to exist, not be current — a stale index is fine for ref lookup); removed the application-level writer lock (SQLite WAL + `busy_timeout=30s` handles concurrent access with `akm improve`); added a fast DB-exists guard with a clear error for first-time users.
 - **`akm health --format html` now completes in ~11s** (was ~18s). Root cause: `akmHealth()` was called twice — once for the main result and once to get `deltas`. Fix: merged into a single call passing both `groupBy: "run"` and `windowCompare` together.
-## [0.9.0-beta.18] — 2026-06-17
+## [0.9.0-beta.18] - 2026-06-17
 ### Changed
@@ -994,14 +2224,16 @@ proposal and log storage, `--format html` output, and per-stage LLM telemetry.
 ### Added
-- **Cross-runtime: akm now runs on Node.js (≥ 20) in addition to Bun** (#560,
+- **Cross-runtime: akm now runs on Node.js >= 22 in addition to Bun** (#560,
   #465). A two-file runtime boundary (`src/storage/database.ts` owns SQLite via
   `bun:sqlite` on Bun / `better-sqlite3` on Node; `src/runtime.ts` owns every
   `Bun.*` API) contains all runtime-specific code, enforced by a lint guard so it
   cannot leak back out. A CI `node-smoke` matrix runs the built CLI under Node
-  20 and 22. **Minimum Node is 20** — the prompts dependency (`@clack/core`) uses
-  `node:util.styleText`, added in Node 20.12; Node 18 is EOL and unsupported.
-  Bun remains the primary/default runtime.
+  20 and 22. The prompts dependency (`@clack/core`) uses `node:util.styleText`,
+  added in Node 20.12; Node 18 is EOL and unsupported. The npm package uses Node
+  as its bootstrap and prefers a working Bun >= 1.0 for execution when both are
+  available. Old, unusable, or absent Bun installations fall back to Node.js;
+  standalone binaries remain runtime-free.
 - **`session` asset type — agent sessions are now searchable** (#561). The
   `extract` pass, after distilling memory proposals from a session, additionally
   writes the session itself as a first-class `session` asset
@@ -1610,7 +2842,7 @@ behind an interactive prompt (or `-y` / `--yes` in non-interactive use).
 ### Changed
-- **Rebrand**: the full name "Agent Kit Manager" is now **Agent Knowledge Management** — `akm` stands for Agent Knowledge Management going forward. The binary name, npm package (`akm-cli`), and all APIs remain unchanged.
+- **Rebrand**: the full name "Agent Kit Manager" is now **Agent Knowledge Manager** — `akm` stands for Agent Knowledge Manager going forward. The binary name, npm package (`akm-cli`), and all APIs remain unchanged.
 - **Config layer rewrite** — single-source-of-truth Zod schema in
   `src/core/config-schema.ts` replaces the per-field parse switch AND
@@ -1798,7 +3030,7 @@ See `docs/migration/v0.7-to-v0.8.md` for the user-facing migration guide.
 ### Migration
-- See [`docs/migration/release-notes/0.7.0.md`](docs/migration/release-notes/0.7.0.md) for the operator summary and [`docs/migration/v1.md`](docs/migration/v1.md) for the canonical per-surface delta from any 0.6.x baseline.
+- See [`docs/migration/release-notes/0.7.0.md`](docs/migration/release-notes/0.7.0.md) for the operator summary and the [archived pre-1.0 plan](docs/archive/pre-1.0-migration.md) for the historical per-surface delta from any 0.6.x baseline.
 ## [0.6.0] - 2026-04-23
@@ -1817,7 +3049,7 @@ See `docs/migration/v0.7-to-v0.8.md` for the user-facing migration guide.
 ### Changed (breaking)
-- **v1 architecture refactor.** The internal architecture was rebuilt around a single minimal `SourceProvider` interface (`{ name, kind, init, path, sync? }`), a unified FTS5 index that owns search and show, and a single `writeAssetToSource` helper that owns all writes. The CLI command surface and all user-visible config keys are unchanged. See `docs/migration/v1.md` for the full guide.
+- **v1 architecture refactor.** The internal architecture was rebuilt around a single minimal `SourceProvider` interface (`{ name, kind, init, path, sync? }`), a unified FTS5 index that owns search and show, and a single `writeAssetToSource` helper that owns all writes. The CLI command surface and all user-visible config keys are unchanged. See `docs/archive/pre-1.0-migration.md` for the historical guide.
 - **Config key `stashes[]` renamed to `sources[]`.** Configs with the legacy key load with one deprecation warning and are auto-migrated in memory; the new key is persisted on the next `akm config` write. New configs should use `sources[]`. Configs that contain both keys are rejected with `ConfigError`.
 - **Error hints surface without `--verbose`.** Error classes own their `hint()` text; the regex-on-message hint chain in `cli.ts` is removed. Hints print to stderr inline alongside the error message.
 - **Registry providers loop through a uniform interface.** Context Hub is no longer a special-cased provider type. Add it as a regular git source (`akm add github:andrewyng/context-hub`) or include it as a kit in your registry index. Legacy `type: "context-hub"` entries normalize to `type: "git"` at load time.