akm-cli 0.10.261129 → 0.10.261130-beta.2

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 (114) hide show
  1. package/CHANGELOG.md +58 -0
  2. package/STABILITY.md +11 -0
  3. package/dist/assets/hints/cli-hints-full.md +1 -1
  4. package/dist/assets/hints/cli-hints-short.md +1 -0
  5. package/dist/assets/stash-skeleton/facts/conventions/assets/rule.md +1 -1
  6. package/dist/cli/usage-report.js +184 -0
  7. package/dist/cli/usage.js +24 -7
  8. package/dist/cli.js +8 -2
  9. package/dist/commands/completions.js +5 -4
  10. package/dist/commands/health/checks.js +18 -4
  11. package/dist/commands/health/connections-and-harnesses-check.js +1 -0
  12. package/dist/commands/health/egress.js +1 -2
  13. package/dist/commands/health/plugin-staleness.js +75 -159
  14. package/dist/commands/health/scheduler-binary.js +7 -2
  15. package/dist/commands/health/semantic-search-check.js +7 -6
  16. package/dist/commands/health/version-drift.js +2 -0
  17. package/dist/commands/improve/extract.js +2 -2
  18. package/dist/commands/improve/preparation.js +6 -1
  19. package/dist/commands/lint/base-linter.js +90 -48
  20. package/dist/commands/lint/index.js +128 -185
  21. package/dist/commands/lint/moved-refs.js +69 -0
  22. package/dist/commands/lint/scope.js +41 -0
  23. package/dist/commands/metrics/collect.js +25 -2
  24. package/dist/commands/metrics/report-view.js +11 -2
  25. package/dist/commands/proposal/proposal.js +7 -2
  26. package/dist/commands/proposal/repository.js +16 -11
  27. package/dist/commands/read/rules.js +142 -0
  28. package/dist/commands/read/search-cli.js +5 -5
  29. package/dist/commands/read/search.js +1 -1
  30. package/dist/commands/sources/plugin-upgrade.js +139 -71
  31. package/dist/commands/sources/source-clone.js +4 -4
  32. package/dist/commands/sources/sources-cli.js +3 -20
  33. package/dist/commands/sources/sync.js +24 -0
  34. package/dist/commands/tasks/tasks.js +1 -1
  35. package/dist/core/adapter/adapters/akm-adapter.js +32 -23
  36. package/dist/core/adapter/adapters/akm-lint.js +55 -61
  37. package/dist/core/adapter/adapters/akm-workflow-adapter.js +10 -14
  38. package/dist/core/adapter/adapters/llm-wiki-adapter.js +6 -17
  39. package/dist/core/adapter/adapters/okf-adapter.js +5 -9
  40. package/dist/core/adapter/adapters/shared.js +52 -200
  41. package/dist/core/adapter/adapters/tool-dir-shared.js +3 -2
  42. package/dist/core/adapter/adapters/website-snapshot-adapter.js +4 -4
  43. package/dist/core/adapter/validate-context.js +7 -11
  44. package/dist/core/asset/asset-placement.js +29 -0
  45. package/dist/core/asset/frontmatter-edit.js +124 -0
  46. package/dist/core/asset/lint-text.js +18 -2
  47. package/dist/core/asset/llm-wiki-root.js +30 -0
  48. package/dist/core/asset/ref-rewrite.js +39 -0
  49. package/dist/core/asset/type-keys.js +59 -0
  50. package/dist/core/config/schema/local-state.js +5 -1
  51. package/dist/core/config/schema/output.js +4 -4
  52. package/dist/core/config/schema/search.js +4 -0
  53. package/dist/core/write-source.js +75 -25
  54. package/dist/indexer/index-written-assets.js +16 -8
  55. package/dist/indexer/indexer.js +68 -19
  56. package/dist/indexer/legacy-refs.js +1 -26
  57. package/dist/indexer/links/declared-links.js +13 -11
  58. package/dist/indexer/ref-moves.js +75 -0
  59. package/dist/indexer/search/db-search.js +3 -2
  60. package/dist/indexer/walk/place-rules.js +25 -0
  61. package/dist/indexer/walk/walker.js +5 -1
  62. package/dist/integrations/session-logs/pre-filter.js +1 -0
  63. package/dist/output/context.js +6 -2
  64. package/dist/output/shapes/passthrough.js +1 -0
  65. package/dist/output/text/rules.js +14 -0
  66. package/dist/output/text.js +2 -0
  67. package/dist/scripts/akm-migrate-node.js +4651 -3584
  68. package/dist/scripts/akm-migrate.js +4650 -3584
  69. package/dist/setup/registry-stash-loader.js +4 -2
  70. package/dist/sources/providers/git-stash.js +13 -5
  71. package/dist/storage/repositories/index-entries-repository.js +8 -3
  72. package/dist/storage/repositories/index-llm-cache-repository.js +4 -0
  73. package/dist/workspace/activity.js +69 -8
  74. package/dist/workspace/asset-improve.js +9 -5
  75. package/dist/workspace/assets.js +33 -19
  76. package/dist/workspace/bundle-files.js +39 -2
  77. package/dist/workspace/bundles.js +53 -3
  78. package/dist/workspace/check-text.js +121 -0
  79. package/dist/workspace/config.js +3 -0
  80. package/dist/workspace/copy-entry.js +129 -0
  81. package/dist/workspace/derive.js +13 -4
  82. package/dist/workspace/documents.js +11 -16
  83. package/dist/workspace/file-actions.js +130 -0
  84. package/dist/workspace/frontmatter.js +41 -0
  85. package/dist/workspace/git-read.js +42 -27
  86. package/dist/workspace/graph.js +11 -2
  87. package/dist/workspace/impact.js +14 -5
  88. package/dist/workspace/metrics.js +1 -1
  89. package/dist/workspace/misses.js +8 -3
  90. package/dist/workspace/moved-links.js +57 -0
  91. package/dist/workspace/new-file.js +141 -0
  92. package/dist/workspace/proposals.js +12 -38
  93. package/dist/workspace/pulse.js +16 -9
  94. package/dist/workspace/readers.js +14 -0
  95. package/dist/workspace/sensitive.js +12 -6
  96. package/dist/workspace/setup.js +2 -1
  97. package/dist/workspace/stats.js +4 -0
  98. package/dist/workspace.d.ts +100 -1
  99. package/docs/architecture/adapters.md +15 -0
  100. package/docs/architecture/internals/health-advisories.md +13 -8
  101. package/docs/architecture/internals/indexing.md +1 -0
  102. package/docs/architecture/internals/storage-locations.md +3 -3
  103. package/docs/architecture/persisted-data-compat.md +2 -0
  104. package/docs/architecture/specs/ref.md +27 -13
  105. package/docs/guides/author-bundles.md +13 -12
  106. package/docs/integration/bundling-akm.md +3 -0
  107. package/docs/maintainers/implementation-details.md +1 -1
  108. package/docs/reference/api.md +3 -3
  109. package/docs/reference/cli.md +143 -35
  110. package/docs/reference/configuration.md +2 -1
  111. package/docs/reference/data-and-telemetry.md +49 -10
  112. package/docs/reference/workspace.md +122 -36
  113. package/package.json +1 -1
  114. package/schemas/akm-config.json +6 -0
@@ -25,9 +25,13 @@ that.
25
25
  through the exported `scrubUrlCredentials` before showing it, which masks credentials inside any URL (userinfo,
26
26
  `token=`, `api_key=`, `sig=`, ...); Desktop does this on every response.
27
27
  - **Timestamps** are ISO 8601 UTC unless noted. Counts that cannot be computed are `null`, never `NaN`.
28
- - **Reads.** A read operation opens `state.db` and `index.db` read-only and never creates or migrates them: a missing or
29
- behind-on-migrations `state.db` makes the sections that need it empty (and `health` report it as a failing check), not
30
- an error. Searching and showing record no usage events and build no index. Reads write nothing to a bundle, config
28
+ - **Reads.** A read operation opens `state.db` and `index.db` read-only and never creates or migrates them. A missing or
29
+ behind-on-migrations `state.db` is reported, never read as empty: the operations that need it return
30
+ `{ "available": false, "reason": "absent" | "needs-migration" }` (`proposals.list`, `activity.pulse`,
31
+ `assets.improvement`, `assets.searchMisses`, `activity.retrievalTrend`, `activity.improveImpact`, and `taskRuns`,
32
+ `workflowRuns` and `events` with their usual shape); `activity.overview` names it in `errors.state` and `health` reports
33
+ it as a failing check. `activity.pulse` and `assets.improvement` raise the error that names an unresolvable bundle
34
+ directory, and `activity.improveImpact` names it in `errors.proposals`, as `proposals.list` raises it. Searching and showing record no usage events and build no index. Reads write nothing to a bundle, config
31
35
  or database.
32
36
 
33
37
  A `limit` input is a positive integer capped at 200.
@@ -139,15 +143,31 @@ an `improveRuns` entry above. An unknown id throws `NotFoundError` (`IMPROVE_RUN
139
143
 
140
144
  The `health` part of `activity.overview` on its own, with the same `probe` parameter. A host calls it with `probe` set to run all checks.
141
145
 
146
+ ## `activity.reportUsage`
147
+
148
+ No input. AKM Desktop's server calls it once at start. Sends the Desktop daily usage report when it is due (at most
149
+ once per UTC day, not when `usage.report` is `false`) and returns `true` when the server accepted it. It never throws
150
+ and never waits on the network for longer than a few seconds. What is sent is listed in
151
+ [Data and Telemetry](data-and-telemetry.md#daily-usage-report).
152
+
142
153
  ## `activity.taskHistory`
143
154
 
144
155
  Requires `taskId`; optional `since` (default `30d`, same syntax as metrics) and `limit` (default 50, maximum 200).
145
156
  Returns `{ available, totalCount, count, runs }`, newest first. Each run has
146
157
  recorded `status`, `startedAt`, nullable `durationMs`, nullable `trigger` (`schedule` when the OS scheduler started
147
158
  it, `manual` otherwise; `null` on a run recorded before akm stored it, or one that failed before it was dispatched),
148
- and nullable decoded `detail` (`reason`, `error`, `exitCode`, `runId` when recorded). Invalid/missing historical detail stays
149
- unknown. No log paths are returned or files read; these are existing state.db records. `available: false` means
150
- state.db is absent or needs migration, not that this task has never failed.
159
+ nullable `targetKind` (`command`, `workflow`, ...), `targetRef` (the workflow's ref) and `engine` (what ran a command or
160
+ prompt task), and nullable decoded `detail` (`reason`, `error`, `exitCode`, `runId` when recorded). Invalid/missing
161
+ historical detail stays unknown. No log paths are returned or files read; these are existing state.db records.
162
+ `available: false` means state.db is absent or needs migration, not that this task has never failed. The run's output is
163
+ [`activity.taskRunLog`](#activitytaskrunlog).
164
+
165
+ ## `activity.taskRunLog`
166
+
167
+ Requires `taskId` and the run's `startedAt` as `activity.taskHistory` lists them. Returns the run's recorded output from
168
+ `logs.db`, read-only: `{ available: true, truncated, lines: [{ stream, level, line }] }`, oldest line first, at most 500
169
+ lines (`truncated` says there were more). Output is stored already redacted. `{ available: false, reason: "absent" }`
170
+ when there is no `logs.db`; nothing is created or migrated.
151
171
 
152
172
  ## `activity.taskRuns`
153
173
 
@@ -179,7 +199,8 @@ migrated.
179
199
 
180
200
  Optional `since` (default `24h`) and `until` (default now). Every search, show, feedback and curate row of the window
181
201
  from every source, oldest first, as `akm doctor metrics --detail full` lists them (`rows.usage`):
182
- `{ available, window, truncated, events }`. A search writes one summary row (no `ref`, with `resultCount`) and one row
202
+ `{ available, window, truncated, events }`. Each event carries `byPerson`: `true` for the person's own events (the ones
203
+ `akm doctor metrics` and `assets.searchMisses` count), `false` for an agent's, improve's or a task's. A search writes one summary row (no `ref`, with `resultCount`) and one row
183
204
  per hit. An event carries `agent: { harness, session? }` when the agent harness that made it was recorded (from this
184
205
  release; older rows have none). At most 20,000 events; `truncated` says the window held more.
185
206
 
@@ -196,6 +217,7 @@ them, in column form, so 30,000 assets stay a few megabytes:
196
217
  "bundles": ["team-wiki"],
197
218
  "beliefs": ["superseded"],
198
219
  "use": { "since": "2026-08-15T08:00:00.000Z", "source": "user" },
220
+ "feedback": { "since": "2026-08-15T08:00:00.000Z", "source": "user" },
199
221
  "kinds": ["xref", "links_to"],
200
222
  "tags": ["deploy"],
201
223
  "nodes": { "ref": ["team-wiki//knowledge/a"], "type": [0], "bundle": [0], "belief": [-1], "shows": [12],
@@ -216,7 +238,8 @@ events when the operation is called: events of source `user` (people and their a
216
238
  Improve) at or after `use.since`, the start of the usage retention window. It is zero, and the note says so, when no
217
239
  usage history is available. `lastShownAt` is the latest of those shows (UTC), `null` when there is none in the window.
218
240
  `positive` and `negative` count feedback from people inside the retention window, as search ranks by it (a negative
219
- answered by an accepted fix does not count). `modifiedAt` is the file's modification time, `null` when it cannot be
241
+ answered by an accepted fix does not count). `feedback` is `null`, and every count zero, when the state store could not
242
+ be read: zeros then are not measurements, and a reader shows feedback as unavailable. `modifiedAt` is the file's modification time, `null` when it cannot be
220
243
  read; in a Git checkout it is when the file was last written there, not its last commit.
221
244
 
222
245
  `groups` and `duplicates` are computed by `akm index` at the end of each build whose vectors changed, over every
@@ -227,7 +250,7 @@ meaning lie near each other, and an asset sits inside its group's sphere. `dupli
227
250
  into `nodes`) whose stored embeddings have a cosine of at least `threshold` (0.96), most alike first, at most 2,000
228
251
  (`truncated` says there were more); only pairs inside a group are compared. Pairs and places of assets that are not
229
252
  returned (a bundle that is not enabled) are left out. Both are `null` without at least eight embedded assets, and until
230
- an `akm index` of this release has run. `available` is `false`, with a `note`, when there is no index.
253
+ an `akm index` of this release has run, and the `note` says so; a reader shows near-duplicates as unavailable, not as none. `available` is `false`, with a `note`, when there is no index.
231
254
 
232
255
  ## `bundles.list`
233
256
 
@@ -240,6 +263,8 @@ fetched, so `ahead`/`behind` are measured against the remote-tracking branch as
240
263
  "data": {
241
264
  "defaultBundle": "stash",
242
265
  "defaultWriteTarget": null,
266
+ "writeTarget": { "name": "stash", "blocker": null },
267
+ "starter": { "source": "https://github.com/itlackey/akm-stash", "identity": "github:itlackey/akm-stash" },
243
268
  "workingStash": null,
244
269
  "bundles": [
245
270
  {
@@ -247,8 +272,10 @@ fetched, so `ahead`/`behind` are measured against the remote-tracking branch as
247
272
  "kind": "filesystem",
248
273
  "default": true,
249
274
  "source": { "kind": "path", "locator": "/home/me/akm" },
275
+ "identity": null,
250
276
  "path": "/home/me/akm",
251
277
  "writable": true,
278
+ "writeBlocker": null,
252
279
  "version": null,
253
280
  "exists": true,
254
281
  "itemCount": 14,
@@ -258,7 +285,7 @@ fetched, so `ahead`/`behind` are measured against the remote-tracking branch as
258
285
  "upstream": "origin/main",
259
286
  "ahead": 1,
260
287
  "behind": 0,
261
- "dirtyPaths": 0,
288
+ "uncommitted": 0,
262
289
  "lastCommit": { "sha": "7591a50789d4cddc", "time": "2026-10-16T10:46:41-05:00", "subject": "akm save 2026-10-16 10:00:00" }
263
290
  }
264
291
  }
@@ -278,13 +305,26 @@ fetched, so `ahead`/`behind` are measured against the remote-tracking branch as
278
305
 
279
306
  - `kind` is `filesystem`, `git`, `npm` or `website`. `source` describes where the bundle comes from; `path` is its local
280
307
  root (`null` if it has none).
308
+ - `writeBlocker` is `null` when akm would accept a write to the bundle now, and otherwise the sentence the write would
309
+ be refused with (disabled, not writable, an adapter that takes no AKM asset writes, a Git bundle that is not a
310
+ checkout or is detached). It runs the write path's own checks and changes nothing, so a card never disagrees with a
311
+ save.
312
+ - `writeTarget` is where a write goes when no bundle is named, as akm's write path resolves it: `name` is that bundle
313
+ (`null` when none resolves) and `blocker` is the sentence a write would be refused with, or `null`. Clients show this
314
+ and do not combine `defaultWriteTarget` with anything.
315
+ - `identity` names where a bundle comes from, parsed by the code `akm bundle add` uses, so the same repository or package
316
+ has the same identity however its address is written (`github:itlackey/akm-stash` for `github:itlackey/akm-stash`,
317
+ `https://github.com/itlackey/akm-stash.git` and its other spellings). It is `null` for a folder, a website, or an
318
+ address that does not parse. `starter` is the AKM starter bundle: `source` is what `bundle add` takes and `identity`
319
+ is compared for equality with a card's.
281
320
  - The default bundle's card comes first; the rest keep their configured order.
282
321
  - `workingStash` is `{ path, git }` for the directory akm reads besides the configured bundles (`AKM_BUNDLE_DIR`, or the
283
322
  platform stash when no `defaultBundle` is set). `git` has the same shape as a card's `git`. It is `null` when a
284
323
  configured bundle already covers that directory or it cannot be resolved.
285
324
  - `git` is `null` unless the bundle's root is itself a git repository. `upstream`, `ahead` and `behind` are `null` without an
286
- upstream; `branch` is `null` on a detached HEAD; `lastCommit` is `null` for a repository with no commits. `dirtyPaths`
287
- counts paths with uncommitted changes.
325
+ upstream; `branch` is `null` on a detached HEAD; `lastCommit` is `null` for a repository with no commits. `uncommitted` is the
326
+ number of files `bundles.commit` (`akm sync`) would commit now, from the selection the sync itself uses (ignored files,
327
+ nested repositories and work outside the bundle are left out); `null` when git could not list the changes.
288
328
  - `index` mirrors `akm doctor info`'s `indexStats` and `semanticSearch`. `embeddingCoverage` is embeddings over entries
289
329
  (`null` for an empty or missing index). `unavailable` and `unreadable` appear only when `akm doctor info` reports them.
290
330
  - Cards also include `enabled`, the raw `writableSetting`, `settingsSource` and existing source `components`
@@ -302,11 +342,45 @@ refused. Internal symbolic links can be traversed; unavailable links are labelle
302
342
  The result is `{bundle, path, parent, indexAvailable, entries}`.
303
343
  `parent` is null at the root. Each entry has `name`, bundle-relative `path`,
304
344
  `kind` (`directory`, `file`, or `other`), and `assets: [{ref, type}]`,
305
- with optional `symlink` and `unavailable`. Directories sort first, then names.
345
+ with optional `symlink`, `unavailable`, `size` (a file's bytes) and `modified` (ISO time; both absent when the file cannot be read). Directories sort first, then names.
306
346
  Internal links retain their displayed path and their target's indexed assets.
307
347
  Assets come only from exact physical-file rows already in the index; absent
308
- indexes leave them empty. No content is read, recursive scan run, index written,
309
- or source refreshed. Listing does not imply editability.
348
+ indexes leave them empty. No recursive scan is run, index written, or source
349
+ refreshed, and no file's content is listed: the first bytes of a file that is
350
+ neither protected nor managed are probed to tell text from binary, and a protected
351
+ file is never opened.
352
+
353
+ Each entry also carries `actions`, what akm accepts doing to it:
354
+ `{ read, edit, move, copy, retire, delete }`, each `{ "allowed": true }` or
355
+ `{ "allowed": false, "reason": "<sentence>" }`. `move` is rename or move. The
356
+ verdicts run the checks the operations run, so a control shown from one never fails
357
+ after the click:
358
+
359
+ - Reading, editing, moving and deleting a file or folder, and making an untyped file, are plain file operations: they need
360
+ only a bundle that is not read-only, so a writable bundle of any adapter (claude, opencode, ...) can be edited and
361
+ reorganised. A read-only bundle refuses `edit`, `move`, `retire` and `delete` with "Bundle <name> is read-only: akm does
362
+ not write to it, and an update would replace the edit." `retire` (and making a typed asset) is an akm asset write and also
363
+ carries the write path's sentence (`bundles.list`'s `writeBlocker`), so a bundle of another adapter refuses it with
364
+ "Bundle "claude" uses adapter "claude", which does not support AKM asset writes." `read` and `copy` leave a bundle as it is.
365
+ - A listing entry reports `read` and `edit` from probing the first bytes of the file (about 70 ms more than no probe for a
366
+ folder of 5,000 files).
367
+ - An env or secret file, and a folder where akm's directory rules would type a file env or secret, refuse every action: they are shown and
368
+ edited from the protected-file view. `.git/` and `.akm/` refuse every action: "`.git/` is managed by akm."
369
+ - `read` and `edit` need a text file: "This is not a text file." for binary, invalid UTF-8 or a file over 8 MiB, and
370
+ "This file cannot be opened: ..." with the cause when the probe failed. A folder has no text to open.
371
+ - A skill's `SKILL.md` refuses `move` ("A skill moves as its folder."), and its `copy` verdict says `as` the folder it copies instead (`{ "allowed": true, "as": "skills/backup" }`, which `assets.copyEntry` does for the manifest); `retire` refuses a skill, env, secret and
372
+ session asset (the retire guard `documents.retire` applies) and a file that is not an indexed asset.
373
+ - `delete` is for a file that is not an asset and for an empty folder; an asset is retired, not deleted.
374
+
375
+ The result also has `newFile`: `{ "allowed": true, "type": "lesson" }` for the folder shown, where `type` is the type
376
+ akm's directory rules give a new file there (`null`: none, a plain file), or `{ "allowed": false, "reason", "type": null }`
377
+ for a place akm refuses (a nested protected folder, a managed folder, a bundle akm does not write, `skills/` itself). In the top-level
378
+ `env/` and `secrets/` the new file is `{ "allowed": true, "type": "env" }` or `"secret"` with `"through": "protected-editor"`: it is
379
+ made by `sensitive.save`, not `documents.createFile` (which refuses a protected place). `place`
380
+ (`{ "allowed": true }` or `{ "allowed": false, "reason" }`) is whether a folder may be made in the folder shown, or a file or
381
+ folder moved into it: plain file operations, which need only a bundle that is not read-only and a place that is neither
382
+ protected nor managed (so `skills/` takes a folder though it takes no file of its own).
383
+ The plain-file routes of a host must refuse what these verdicts refuse.
310
384
 
311
385
  ## `config.get`
312
386
 
@@ -514,15 +588,18 @@ Accept one pending proposal. `:id` is a proposal id or unambiguous prefix. The i
514
588
  "ref": "stash//lessons/rg",
515
589
  "assetPath": "/home/me/akm/lessons/rg.md",
516
590
  "proposal": { "id": "d6bb7f94-...", "status": "accepted", "ref": "stash//lessons/rg", "...": "summary fields as in proposals.list" },
517
- "commit": { "sha": "9f1c...", "time": "2026-10-16T16:02:11-05:00", "subject": "akm accept: reflect d6bb7f94 stash//lessons/rg", "repo": "/home/me/akm" }
591
+ "commit": { "committed": true, "sha": "9f1c0a4e2b7d..." }
518
592
  }
519
593
  }
520
594
  ```
521
595
 
522
596
  - `data` is `akmProposalAccept`'s result, with `proposal` reduced to the list summary (the prior content kept for
523
- `akm proposal revert` is never returned) and `commit` added.
524
- - `commit` is the commit the accept just made in the bundle's repository, or `null` when the bundle is not a git
525
- repository (or the commit did not happen; a failed commit only warns, as in the CLI).
597
+ `akm proposal revert` is never returned).
598
+ - `commit` is what akm reports the accept's own commit came to: `{ "committed": true, "sha" }`, or
599
+ `{ "committed": false, "reason", "error"? }` with `reason` `not-git` (the bundle is not a Git repository), `ignored`
600
+ (every written path is ignored by `.gitignore`), `nothing-to-commit` or `failed` (with the git `error`). The accept
601
+ stands in every case. Each entry of a batch `proposals.acceptMany` result carries the `commit` of the one commit the
602
+ batch made.
526
603
 
527
604
  ### `proposals.reject`
528
605
 
@@ -618,7 +695,6 @@ Recent commits of the write-target stash (`defaultWriteTarget`, else the default
618
695
  "time": "2026-10-16T10:46:41-05:00",
619
696
  "author": "akm-test",
620
697
  "subject": "akm save 2026-10-16 10:00:00",
621
- "origin": "sync",
622
698
  "paths": ["knowledge/more.md"],
623
699
  "pathCount": 1
624
700
  }
@@ -628,16 +704,6 @@ Recent commits of the write-target stash (`defaultWriteTarget`, else the default
628
704
  ```
629
705
 
630
706
  - `git` is `false` and `commits` empty when the stash is not a git repository.
631
- - `origin` is derived from the subject, which is how akm names its own commits:
632
-
633
- | `origin` | Subject |
634
- | --- | --- |
635
- | `improve-sync` | `akm improve ...` (the pre-run sync and the end-of-run auto-sync) |
636
- | `accept` | `akm accept: ...`, `akm proposal ...` (including `akm proposal drain: N accepted ...`) |
637
- | `remember` | contains `remember` |
638
- | `sync` | `akm save ...`, `akm sync ...` |
639
- | `other` | anything else, such as a hand-made commit |
640
-
641
707
  - `paths` lists at most 50 changed paths; `pathCount` is the real number. `time` is the commit's own committer date with
642
708
  its offset.
643
709
 
@@ -734,6 +800,7 @@ Recent commits of the write-target stash (`defaultWriteTarget`, else the default
734
800
  `{ "redacted": true, "type": "env", "ref": "env/prod", "note": "..." }`, with no `asset`, key names or values.
735
801
  Use `akm env list` for key names.
736
802
 
803
+ `actions` (the verdicts above for the asset's file, `null` when it has no file in a bundle) is part of the response too.
737
804
  The response also supplies `location` (`{bundle, path, parent}` relative to the
738
805
  resolved bundle root, or null), `feedbackRequireReason`, the owning `bundle`, `headings` with existing AKM fragment
739
806
  selectors, and a `links` map for supported relative inline Markdown links. A relative `.md` target must already be
@@ -796,7 +863,11 @@ A proposal that was later reverted is dated by its accept (`acceptedAt`) in `out
796
863
  - `harm`: the log, newest first: `reverted`, `reopened`, `risky-retirement`, `flag-after-change`.
797
864
  - `cost`: per week, model `calls`, `tokens`, `usageCalls` and calls by process.
798
865
  - `changedAssets`: for each accepted change, how often the asset was found and rated in the 28 days before and after
799
- (`complete` is `false` until 28 days have passed since the change).
866
+ (`complete` is `false` until 28 days have passed since the change; `beforeComplete` is `false` when the 28 days before it
867
+ start earlier than the usage rows read, so the before counts are not recorded).
868
+ - `usageSince` and `usageComplete`: where the usage figures (`changedAssets` counts and the `flag-after-change` entries of
869
+ `harm`) start. Usage older than akm keeps (`akm doctor metrics` notes the retention) is purged, so a window longer than
870
+ that is `usageComplete: false` and its usage figures cover only from `usageSince`.
800
871
  - `judgeAndYou`: accepted, rejected and reverted counts by who decided.
801
872
 
802
873
  ## `activity.pulse`
@@ -823,21 +894,26 @@ zero. Missing result counts do not mean zero results. The queries behind `zeroRe
823
894
 
824
895
  `weekly` is the same data by ISO week as a p-chart: per week `week`, `x` (found nothing), `n` (searches), `rate`, and the
825
896
  control limits `lower` and `upper` (centre ± 3 standard errors at that week's own n); `signal` is `true` for a week
826
- outside its limits. A week with no searches has `null` for all three. `centre` is the pooled share.
897
+ outside its limits. A week with no searches has `null` for all three. `partial` is `true` for a week akm has only some of
898
+ the days of (the window opens or ends inside it, or the data starts inside it): it has its `rate`, no limits and no
899
+ `signal`. `centre` is the pooled share of the whole weeks, and `enoughHistory` says whether there are four whole weeks
900
+ with searches: without it `centre` and every limit are `null`. When the state database cannot be read the response is
901
+ `{ "available": false, "reason" }`.
827
902
 
828
903
  ## `assets.searchMisses`
829
904
 
830
905
  User searches that found nothing, grouped by normalised query: `query`, `count`, `days` (distinct UTC days),
831
906
  `lastAt` and `repeated` (`true` when it came up on two or more days). `since` is `30d` by default. The response also carries
832
- `searches` (all user searches in the window) and `foundNothing`.
907
+ `searches` (all user searches in the window) and `foundNothing`. When the state database cannot be read it is
908
+ `{ "available": false, "reason" }`.
833
909
 
834
910
  ## `setup.detect`
835
911
 
836
912
  What first-run setup could use on this computer, read from the file system and `PATH` only: nothing is contacted and
837
913
  nothing is written. It returns `stashDir`, the library directory the config already names, else `~/akm` or another
838
914
  existing candidate, else the default (`AKM_BUNDLE_DIR`, else `~/akm`, or `Documents\akm` on Windows); `harnesses`, the agent
839
- programs found on `PATH` that akm can run work on, each `{platform, path, modelWorkNote}` (akm's words for whether its
840
- model calls on that program can be limited to reading and searching); `enabled`, the platforms the config already
915
+ programs found on `PATH` that akm can run work on, each `{platform, path, modelWorkReadOnly, modelWorkNote}` (`modelWorkReadOnly`: whether akm's model calls on that
916
+ program can be limited to reading and searching; `modelWorkNote`: akm's words for it, for display); `enabled`, the platforms the config already
841
917
  enables; `modelCalls`, where akm's own model calls
842
918
  (improve, judging, extraction) run: `description` in the words of `akm setup`'s summary, and `platform` when they run on
843
919
  a harness (else `null`); `connection`, the name of the connection that takes them when no agent does (`null` when there is
@@ -873,13 +949,23 @@ retry a failed write automatically.
873
949
  | `tasks.disable` | `{task}` → `akm task disable --bundle=<default bundle> -- <task>`: the reverse. |
874
950
  | `backups.prune` | `{olderThan?, dryRun?: true, confirm?: true}` → `akm backups prune [--dry-run \| --yes] [--older-than=<duration>]`. Removes entries under the data directory's `backups/` older than `olderThan` (default `30d`) and keeps the newest entry of each folder. A dry run reports `{dryRun, olderThan, cutoff, count, bytes, folders: [{folder, count, bytes, kept}]}` and removes nothing; a real run returns the same and needs `confirm: true`. |
875
951
  | `bundles.add` | `{source, name?, writable?}` → `akm bundle add`, including source validation. Existing provider restrictions apply; no insecure-transport bypass is exposed. |
952
+ | `bundles.index` | `{}` → `akm index`, the incremental build. A file renamed or moved on disk (`mv`, `git mv`, a file manager, Desktop) is paired with the asset it was and keeps its history, which the write-path refresh of `documents.createFile` and Desktop's saves does not do. The result is `akm index`'s, with `moves` (`{moved: [{from, to}], unpaired}`) when a file was paired or could not be. |
876
953
  | `bundles.update` | `{bundle}` → `akm bundle update -- <bundle>`. Fetches/reindexes only on explicit submission. A rare update requiring destructive confirmation remains refused; `--yes` is never passed silently. |
877
954
  | `bundles.rename` | `{bundle, name, dryRun?: true}` → `akm bundle rename [--dry-run] -- <bundle> <name>`. The result is the CLI's rename plan (`applied` is `false` for a dry run). |
878
955
  | `bundles.remove` | `{bundle, confirm: true}` → `akm bundle remove --yes -- <bundle>`. Managed installs may be deleted; local filesystem source files remain on disk. |
879
956
  | `bundles.setSettings` | `{bundle?, enabled?, writable?, componentWritability?: {existingComponent: boolean}}` → existing schema-walking config setters inside `mutateConfig`. Only changed controls are submitted. Existing validation rejects disabled targets and writable npm/website sources. The default bundle and write target are edited through `config.change`. |
880
957
  | `config.change` | `{set?: {key: string}, unset?: string[]}` → `akm config set` / `unset` on each key, in one validated, atomic write. Values are strings, as on the command line, and are coerced and checked against the schema; literal API keys and `configVersion` are refused. An unset is refused with `TARGET_NOT_UPDATABLE` when the key is inherited from an `extends` base or sits inside a connection or harness entry akm ignores, and an unset with no config file writes nothing (`saved: false`), all as `akm config unset` does. |
881
958
  | `config.changeProjects` | `{set?: {name: project}, unset?: string[]}` → adds, replaces and removes `projects` entries in one validated, atomic write; a rename sets the new name and unsets the old. Each `set` value is a whole project (`paths`, `from`, `filters`, `prefer`, `write`), written exactly as sent (the reader takes a project whole by name, so an inherited project's unchanged fields are written too, and a malformed local entry is replaced), and checked by akm's config schema. `none`, `__proto__`, `constructor`, `prototype` and empty names are refused. An `unset` (so a rename) of a project `config.json` does not hold, inherited or ignored by akm, is refused with `TARGET_NOT_UPDATABLE`. A set is a no-op (`saved: false`, nothing written or backed up) only when `config.json` already holds exactly that entry; one with parts akm ignores is rewritten. Names are not dotted keys, so they may contain a dot, which `config.change` cannot address. Unrelated config and credential references are kept, as for `config.change`. |
882
- | `documents.createKnowledge` | `{bundle, name, path?, content}` → `akm import -` with Markdown on stdin. Uses the existing writable AKM target, name/path validation, frontmatter preservation, index/Git effects, and no `--force`. Existing files are never overwritten. Fails fast with `ASSET_MUTATION_LEASE_HELD` while another writer holds the asset-mutation lease. |
959
+ | `documents.createFile` | `{bundle, folder?, type?, name, content?}` → a new file in `folder` of the bundle (the root when absent; or, with `type` instead of `folder`, the folder akm keeps that type in, `knowledge/` for `knowledge`), for any type, returning `{bundle, file, type, ref, path, stashDir, indexed}` (`type` and `ref` are `null` for a folder with no type). akm types the folder with the indexer's directory rules (`assets.bundleFiles`' `newFile` says the type) and, when `content` is absent, starts the file with the text its type starts with: the workflow template (`akm workflow create`'s), a task as `task add` renders it, the keys the type's validators require (a lesson's `description` and `when_to_use`, a command's `name`), nothing for a script. A folder with no type gets an empty file of the name given. A name with no extension takes the type's (`.md`, `.yml`, `.sh`); a skill is made as `SKILL.md` in its own folder. The write passes the same checks for every type: a writable akm bundle, the name and folder inside the bundle, malformed frontmatter refused, an existing file never overwritten (`RESOURCE_ALREADY_EXISTS`), env, secret and managed (`.git/`, `.akm/`) places refused, the asset-mutation lease (`ASSET_MUTATION_LEASE_HELD`), the Git boundary commit and the index refresh. |
960
+ | `documents.createKnowledge` | `{bundle, name, path?, content}` → `documents.createFile` for the `knowledge/<path>` folder with Markdown content, recording the import as `akm import -` does. Uses the existing writable AKM target, name/path validation, frontmatter preservation, index/Git effects, and no `--force`. Existing files are never overwritten. Fails fast with `ASSET_MUTATION_LEASE_HELD` while another writer holds the asset-mutation lease. |
961
+ | `documents.check` | `{bundle, path, content}` → `{bundle, path, type, findings, warnings, readable, unreadable?}` for text about to be saved at `path` of an akm bundle, without writing it. `findings` and `warnings` are the entries `akm lint` reports for that file (`issue`, `detail`, `line` where the check knows one, `ref`); the file-based lint calls the same function, so the same text in a file lints the same. `readable` says whether akm could still read the asset: `false` with `unreadable: {reason, line?}` for frontmatter that does not parse, a workflow that does not compile or a task that does not validate. `type` is the type the indexer gives the file (`null`: not an asset; nothing is checked). A bundle of another adapter, a path outside the bundle, and protected or managed places are refused. |
962
+ | `documents.frontmatter` | `{bundle, path, content}` → `{bundle, path, type, present, markdown, bodyStart, entries, error?, keys}`: `markdown` says the path is a Markdown file (akm reads frontmatter from it), `bodyStart` the offset in `content` where the body starts (after the closing fence; 0 without frontmatter), the reading is the same in a bundle of any adapter (`type` and `keys` are an akm bundle's); `entries` are the file's frontmatter keys and values in file order as akm's strict YAML reads them (`known` marks a key akm knows for the type); `error` is `{reason, line?}` when the block does not parse (`entries` is then empty); `keys` are the keys akm knows for the type (`key`, `required`, `kind` `text`\|`list`\|`flag`\|`map`, `values` when akm checks a fixed set, `hint`, `stamped` when akm sets it on write). Required means absence is a finding of the check that owns the key: a lesson's `description` and `when_to_use`, a fact's `category`, a command's and an agent's `name` and `type`, a workflow's `steps`, and `updated` for Markdown. |
963
+ | `documents.applyFrontmatter` | `{content, changes: [{key, value}\|{key, remove: true}]}` → `{content, bodyStart}`: the text with each key set or removed in its frontmatter and nothing else changed. A changed key keeps its place, a new key goes before the closing `---`, untouched keys keep their order, quoting, comments and line endings, and the body is not touched. A text with no frontmatter gains a block for the keys set. A change that cannot be made that way (a block that does not parse, a key that is not a plain field name) is refused, never approximated: the host offers the text instead. |
964
+ | `assets.movedLinks` | `{bundle?}` → `{bundles: [{bundle, writable, writeBlocker, links: [{ref, file, from, to}]}], total}`: per akm bundle (a read-only one included), the links that name the old ref of an asset that `akm index` recorded as moved: the asset holding the link (`ref`, `file`), the link as written (`from`) and the ref the asset has now (`to`). It is `akm lint`'s `missing-ref` findings that carry a new ref. Writes nothing. |
965
+ | `assets.copyEntry` | `{bundle, from, toBundle?, folder?, name}` → `{bundle, from, toBundle, to, indexed}`: copies a file or folder to a folder of a bundle (the same or another; the root when `folder` is absent) as a new file wherever the person puts it. Copying a skill's `SKILL.md` copies the skill's folder, with its support files and modes, and `name` names the folder. It adds to a bare copy what `akm clone` adds: the work is staged beside the destination and renamed into place, file links are copied by content, the asset-mutation lease and the Git boundary commit apply, the copy is indexed, and a Markdown asset (or a skill's `SKILL.md`) records the ref it came from in `sources`. Nothing is overwritten (`RESOURCE_ALREADY_EXISTS`); env and secret files and managed folders are refused, and so is a destination in a protected place or a bundle that is read-only. `akm clone` (`documents.copy`) is the CLI's: it places by type in the target's type folder and takes a ref, including a remote one. |
966
+ | `assets.updateMovedLinks` | `{bundle}` → `{bundle, rewritten, files}`: rewrites exactly those links in one writable akm bundle (`akm lint --fix`'s rewrite, and no other fix), under the asset-mutation lease, and refreshes the index for the files it changed. A read-only bundle, or one that is not an akm bundle, is refused. A second call changes nothing. |
967
+ | `bundles.commit` | `{bundle, message?, push?}` → `{bundle, committed, pushed, skipped, output, reason?, commit?}`: `akm sync` for one bundle (the CLI's own function): commits every unignored change inside it, and pushes when it is writable with a remote configured unless `push` is `false`. `commit` is the new commit; when nothing was committed `output` (and `reason`) say why. A bundle that is not a Git working tree is refused. |
968
+ | `sensitive.describe` | `{ref}` or `{bundle, file}` → the env or secret file's `ref`, `type`, `name`, `bundle`, `path`, `revision`, `location` and `actions: {edit, delete}`, each `{ "allowed": true }` or `{ "allowed": false, "reason" }` with the sentence akm's write path refuses with (a read-only bundle, a bundle that takes no env or secret writes). No value is returned; `readValue` is the one result that has it. |
883
969
  | `documents.save` | `{ref, revision, content}` → the existing shared Markdown writer with `force` and the expected raw-content hash. Only indexed writable AKM knowledge/memory documents accepted by `documents.readSource` can be edited. The writer takes the asset-mutation lease and compares the live source with `revision` inside it, immediately before writing. While another writer holds the lease the save fails fast with `ASSET_MUTATION_LEASE_HELD` instead of waiting. A stale revision raises `ASSET_CONTENT_CHANGED` without writing; a source deleted after it was loaded is refused (`ASSET_NOT_FOUND`) rather than recreated. An identical save returns `unchanged: true` without rewriting, reindexing or recording an event. Changed saves retain normal writer validation, indexing and Git effects. |
884
970
  | `documents.retire` | `{ref, revision}` → retires an indexed writable AKM asset the way `akm feedback`'s typed fix applies a change: it mints a retire proposal (source `propose`, no judged pair) and accepts it at once, so the asset follows the ordinary proposal-retire lifecycle. Skill packages, env/secret files and sessions are excluded; memory retirement carries its derived twin. The current raw SHA-256 `revision` is required, and the accept is refused if the bytes changed since. |
885
971
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "akm-cli",
3
- "version": "0.10.261129",
3
+ "version": "0.10.261130-beta.2",
4
4
  "type": "module",
5
5
  "description": "akm (Agent Knowledge Manager) — a portable, local-first capability library for AI agents. Discover, load, share, and improve reusable skills, scripts, workflows, and knowledge across any shell-capable coding agent, including Claude Code, OpenCode, and Cursor.",
6
6
  "keywords": [
@@ -740,6 +740,9 @@
740
740
  "properties": {
741
741
  "capture": {
742
742
  "type": "boolean"
743
+ },
744
+ "report": {
745
+ "type": "boolean"
743
746
  }
744
747
  },
745
748
  "additionalProperties": {}
@@ -2730,6 +2733,9 @@
2730
2733
  "properties": {
2731
2734
  "capture": {
2732
2735
  "type": "boolean"
2736
+ },
2737
+ "report": {
2738
+ "type": "boolean"
2733
2739
  }
2734
2740
  },
2735
2741
  "additionalProperties": {}