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.
- package/CHANGELOG.md +58 -0
- package/STABILITY.md +11 -0
- package/dist/assets/hints/cli-hints-full.md +1 -1
- package/dist/assets/hints/cli-hints-short.md +1 -0
- package/dist/assets/stash-skeleton/facts/conventions/assets/rule.md +1 -1
- package/dist/cli/usage-report.js +184 -0
- package/dist/cli/usage.js +24 -7
- package/dist/cli.js +8 -2
- package/dist/commands/completions.js +5 -4
- package/dist/commands/health/checks.js +18 -4
- package/dist/commands/health/connections-and-harnesses-check.js +1 -0
- package/dist/commands/health/egress.js +1 -2
- package/dist/commands/health/plugin-staleness.js +75 -159
- package/dist/commands/health/scheduler-binary.js +7 -2
- package/dist/commands/health/semantic-search-check.js +7 -6
- package/dist/commands/health/version-drift.js +2 -0
- package/dist/commands/improve/extract.js +2 -2
- package/dist/commands/improve/preparation.js +6 -1
- package/dist/commands/lint/base-linter.js +90 -48
- package/dist/commands/lint/index.js +128 -185
- package/dist/commands/lint/moved-refs.js +69 -0
- package/dist/commands/lint/scope.js +41 -0
- package/dist/commands/metrics/collect.js +25 -2
- package/dist/commands/metrics/report-view.js +11 -2
- package/dist/commands/proposal/proposal.js +7 -2
- package/dist/commands/proposal/repository.js +16 -11
- package/dist/commands/read/rules.js +142 -0
- package/dist/commands/read/search-cli.js +5 -5
- package/dist/commands/read/search.js +1 -1
- package/dist/commands/sources/plugin-upgrade.js +139 -71
- package/dist/commands/sources/source-clone.js +4 -4
- package/dist/commands/sources/sources-cli.js +3 -20
- package/dist/commands/sources/sync.js +24 -0
- package/dist/commands/tasks/tasks.js +1 -1
- package/dist/core/adapter/adapters/akm-adapter.js +32 -23
- package/dist/core/adapter/adapters/akm-lint.js +55 -61
- package/dist/core/adapter/adapters/akm-workflow-adapter.js +10 -14
- package/dist/core/adapter/adapters/llm-wiki-adapter.js +6 -17
- package/dist/core/adapter/adapters/okf-adapter.js +5 -9
- package/dist/core/adapter/adapters/shared.js +52 -200
- package/dist/core/adapter/adapters/tool-dir-shared.js +3 -2
- package/dist/core/adapter/adapters/website-snapshot-adapter.js +4 -4
- package/dist/core/adapter/validate-context.js +7 -11
- package/dist/core/asset/asset-placement.js +29 -0
- package/dist/core/asset/frontmatter-edit.js +124 -0
- package/dist/core/asset/lint-text.js +18 -2
- package/dist/core/asset/llm-wiki-root.js +30 -0
- package/dist/core/asset/ref-rewrite.js +39 -0
- package/dist/core/asset/type-keys.js +59 -0
- package/dist/core/config/schema/local-state.js +5 -1
- package/dist/core/config/schema/output.js +4 -4
- package/dist/core/config/schema/search.js +4 -0
- package/dist/core/write-source.js +75 -25
- package/dist/indexer/index-written-assets.js +16 -8
- package/dist/indexer/indexer.js +68 -19
- package/dist/indexer/legacy-refs.js +1 -26
- package/dist/indexer/links/declared-links.js +13 -11
- package/dist/indexer/ref-moves.js +75 -0
- package/dist/indexer/search/db-search.js +3 -2
- package/dist/indexer/walk/place-rules.js +25 -0
- package/dist/indexer/walk/walker.js +5 -1
- package/dist/integrations/session-logs/pre-filter.js +1 -0
- package/dist/output/context.js +6 -2
- package/dist/output/shapes/passthrough.js +1 -0
- package/dist/output/text/rules.js +14 -0
- package/dist/output/text.js +2 -0
- package/dist/scripts/akm-migrate-node.js +4651 -3584
- package/dist/scripts/akm-migrate.js +4650 -3584
- package/dist/setup/registry-stash-loader.js +4 -2
- package/dist/sources/providers/git-stash.js +13 -5
- package/dist/storage/repositories/index-entries-repository.js +8 -3
- package/dist/storage/repositories/index-llm-cache-repository.js +4 -0
- package/dist/workspace/activity.js +69 -8
- package/dist/workspace/asset-improve.js +9 -5
- package/dist/workspace/assets.js +33 -19
- package/dist/workspace/bundle-files.js +39 -2
- package/dist/workspace/bundles.js +53 -3
- package/dist/workspace/check-text.js +121 -0
- package/dist/workspace/config.js +3 -0
- package/dist/workspace/copy-entry.js +129 -0
- package/dist/workspace/derive.js +13 -4
- package/dist/workspace/documents.js +11 -16
- package/dist/workspace/file-actions.js +130 -0
- package/dist/workspace/frontmatter.js +41 -0
- package/dist/workspace/git-read.js +42 -27
- package/dist/workspace/graph.js +11 -2
- package/dist/workspace/impact.js +14 -5
- package/dist/workspace/metrics.js +1 -1
- package/dist/workspace/misses.js +8 -3
- package/dist/workspace/moved-links.js +57 -0
- package/dist/workspace/new-file.js +141 -0
- package/dist/workspace/proposals.js +12 -38
- package/dist/workspace/pulse.js +16 -9
- package/dist/workspace/readers.js +14 -0
- package/dist/workspace/sensitive.js +12 -6
- package/dist/workspace/setup.js +2 -1
- package/dist/workspace/stats.js +4 -0
- package/dist/workspace.d.ts +100 -1
- package/docs/architecture/adapters.md +15 -0
- package/docs/architecture/internals/health-advisories.md +13 -8
- package/docs/architecture/internals/indexing.md +1 -0
- package/docs/architecture/internals/storage-locations.md +3 -3
- package/docs/architecture/persisted-data-compat.md +2 -0
- package/docs/architecture/specs/ref.md +27 -13
- package/docs/guides/author-bundles.md +13 -12
- package/docs/integration/bundling-akm.md +3 -0
- package/docs/maintainers/implementation-details.md +1 -1
- package/docs/reference/api.md +3 -3
- package/docs/reference/cli.md +143 -35
- package/docs/reference/configuration.md +2 -1
- package/docs/reference/data-and-telemetry.md +49 -10
- package/docs/reference/workspace.md +122 -36
- package/package.json +1 -1
- 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
|
|
29
|
-
behind-on-migrations `state.db`
|
|
30
|
-
|
|
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
|
-
|
|
149
|
-
|
|
150
|
-
|
|
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 }`.
|
|
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). `
|
|
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
|
-
"
|
|
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. `
|
|
287
|
-
|
|
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 `
|
|
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
|
|
309
|
-
|
|
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": { "
|
|
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)
|
|
524
|
-
- `commit` is
|
|
525
|
-
|
|
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. `
|
|
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
|
|
840
|
-
|
|
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.
|
|
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.
|
|
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": [
|
package/schemas/akm-config.json
CHANGED
|
@@ -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": {}
|