akm-cli 0.10.261130-beta.1 → 0.10.261130-beta.3

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 (98) hide show
  1. package/CHANGELOG.md +54 -0
  2. package/STABILITY.md +10 -0
  3. package/dist/cli/usage-report.js +184 -0
  4. package/dist/cli/usage.js +24 -7
  5. package/dist/cli.js +5 -1
  6. package/dist/commands/completions.js +5 -4
  7. package/dist/commands/health/checks.js +18 -4
  8. package/dist/commands/health/connections-and-harnesses-check.js +1 -0
  9. package/dist/commands/health/plugin-staleness.js +75 -159
  10. package/dist/commands/health/scheduler-binary.js +7 -2
  11. package/dist/commands/health/semantic-search-check.js +7 -6
  12. package/dist/commands/health/version-drift.js +2 -0
  13. package/dist/commands/improve/extract.js +2 -2
  14. package/dist/commands/improve/preparation.js +6 -1
  15. package/dist/commands/lint/base-linter.js +90 -48
  16. package/dist/commands/lint/index.js +128 -185
  17. package/dist/commands/lint/moved-refs.js +69 -0
  18. package/dist/commands/lint/scope.js +41 -0
  19. package/dist/commands/proposal/proposal.js +7 -2
  20. package/dist/commands/proposal/repository.js +16 -11
  21. package/dist/commands/sources/plugin-upgrade.js +143 -76
  22. package/dist/commands/sources/source-clone.js +4 -4
  23. package/dist/commands/sources/sources-cli.js +3 -20
  24. package/dist/commands/sources/sync.js +24 -0
  25. package/dist/commands/tasks/tasks.js +1 -1
  26. package/dist/core/adapter/adapters/akm-adapter.js +32 -23
  27. package/dist/core/adapter/adapters/akm-lint.js +55 -61
  28. package/dist/core/adapter/adapters/akm-workflow-adapter.js +10 -14
  29. package/dist/core/adapter/adapters/llm-wiki-adapter.js +6 -17
  30. package/dist/core/adapter/adapters/okf-adapter.js +5 -9
  31. package/dist/core/adapter/adapters/shared.js +52 -200
  32. package/dist/core/adapter/adapters/tool-dir-shared.js +3 -2
  33. package/dist/core/adapter/adapters/website-snapshot-adapter.js +4 -4
  34. package/dist/core/adapter/validate-context.js +7 -11
  35. package/dist/core/asset/asset-placement.js +29 -0
  36. package/dist/core/asset/frontmatter-edit.js +124 -0
  37. package/dist/core/asset/lint-text.js +18 -2
  38. package/dist/core/asset/llm-wiki-root.js +30 -0
  39. package/dist/core/asset/ref-rewrite.js +39 -0
  40. package/dist/core/asset/type-keys.js +59 -0
  41. package/dist/core/config/schema/local-state.js +5 -1
  42. package/dist/core/config/schema/output.js +4 -4
  43. package/dist/core/config/schema/search.js +4 -0
  44. package/dist/core/write-source.js +75 -25
  45. package/dist/indexer/index-written-assets.js +16 -8
  46. package/dist/indexer/indexer.js +68 -19
  47. package/dist/indexer/legacy-refs.js +1 -26
  48. package/dist/indexer/links/declared-links.js +13 -11
  49. package/dist/indexer/ref-moves.js +75 -0
  50. package/dist/indexer/search/db-search.js +2 -1
  51. package/dist/indexer/walk/place-rules.js +25 -0
  52. package/dist/indexer/walk/walker.js +5 -1
  53. package/dist/output/context.js +6 -2
  54. package/dist/scripts/akm-migrate-node.js +4639 -3596
  55. package/dist/scripts/akm-migrate.js +4638 -3596
  56. package/dist/setup/registry-stash-loader.js +4 -2
  57. package/dist/sources/providers/git-stash.js +13 -5
  58. package/dist/storage/repositories/index-entries-repository.js +8 -3
  59. package/dist/storage/repositories/index-llm-cache-repository.js +4 -0
  60. package/dist/workspace/activity.js +69 -8
  61. package/dist/workspace/asset-improve.js +9 -5
  62. package/dist/workspace/assets.js +33 -19
  63. package/dist/workspace/bundle-files.js +39 -2
  64. package/dist/workspace/bundles.js +53 -3
  65. package/dist/workspace/check-text.js +121 -0
  66. package/dist/workspace/config.js +3 -0
  67. package/dist/workspace/copy-entry.js +129 -0
  68. package/dist/workspace/derive.js +13 -4
  69. package/dist/workspace/documents.js +11 -16
  70. package/dist/workspace/file-actions.js +130 -0
  71. package/dist/workspace/frontmatter.js +41 -0
  72. package/dist/workspace/git-read.js +42 -27
  73. package/dist/workspace/graph.js +11 -2
  74. package/dist/workspace/impact.js +14 -5
  75. package/dist/workspace/misses.js +8 -3
  76. package/dist/workspace/moved-links.js +57 -0
  77. package/dist/workspace/new-file.js +141 -0
  78. package/dist/workspace/proposals.js +12 -38
  79. package/dist/workspace/pulse.js +16 -9
  80. package/dist/workspace/readers.js +14 -0
  81. package/dist/workspace/sensitive.js +12 -6
  82. package/dist/workspace/setup.js +2 -1
  83. package/dist/workspace/stats.js +4 -0
  84. package/dist/workspace.d.ts +100 -1
  85. package/docs/architecture/adapters.md +15 -0
  86. package/docs/architecture/internals/health-advisories.md +13 -8
  87. package/docs/architecture/internals/indexing.md +1 -0
  88. package/docs/architecture/persisted-data-compat.md +2 -0
  89. package/docs/architecture/specs/ref.md +27 -13
  90. package/docs/integration/bundling-akm.md +3 -0
  91. package/docs/maintainers/implementation-details.md +1 -1
  92. package/docs/reference/api.md +3 -3
  93. package/docs/reference/cli.md +89 -19
  94. package/docs/reference/configuration.md +2 -1
  95. package/docs/reference/data-and-telemetry.md +47 -9
  96. package/docs/reference/workspace.md +122 -36
  97. package/package.json +1 -1
  98. package/schemas/akm-config.json +6 -0
package/CHANGELOG.md CHANGED
@@ -8,11 +8,65 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
8
8
 
9
9
  ### Added
10
10
 
11
+ - A file or folder renamed or moved on disk is the same asset. `akm index` (full or incremental) pairs an entry whose file is gone with the new file of the same content, in the same bundle or another, and carries its history to the new ref: the index row (vector, links and utility stay, nothing is embedded again), the `state.db` rows keyed by the old ref (usage, feedback, proposals, events, improve ledger, salience, outcome, task and workflow history) and cached model results. Files that share a content hash pair by file name one to one; anything ambiguous is indexed as new and named in a warning, and a file edited as well as moved is a new asset. The result's `moves` (`{ moved: [{ from, to }], unpaired }`) is present when a file was paired or could not be, and each move is recorded as a `moved` event. There is no move command: `mv` or a file manager is the move.
12
+ - `akm lint` reports a link to a moved ref as a `missing-ref` carrying `movedFrom` and `movedTo`, and `--fix` rewrites it (frontmatter and prose, not code fences). A `missing-ref` with no recorded move is reported as before and never rewritten. `akm-cli/workspace`: `assets.movedLinks` lists, per akm bundle, the links that name an old ref, and `assets.updateMovedLinks` rewrites exactly those in one writable bundle (the same lint pass).
13
+ - `akm-cli/workspace`: what may be done to a file or folder. `assets.bundleFiles` entries and `assets.show` carry `actions` (`read`, `edit`, `move` for rename or move, `copy`, `retire`, `delete`), each `{ allowed: true }` or `{ allowed: false, reason }`, computed from the checks the operations run: the read-only sentence for a bundle that is read-only (reading, editing, moving and deleting are plain file operations, so a writable bundle of any adapter still takes them), the write path's adapter sentence for retiring or making a typed asset in a bundle of another adapter, env and secret files, the managed `.git/` and `.akm/` folders, a skill that moves as its folder, a file that is not text (or cannot be opened, with the cause), the retire guard, and an asset that is retired rather than deleted. `assets.bundleFiles` also reports `newFile` for the folder shown.
14
+ - `akm-cli/workspace`: `documents.createFile` makes a new file in a folder of a bundle, for any type. akm types the folder with the indexer's directory rules, starts the file with the text its type starts with (the workflow and task creators' own, or the keys the type's validators require), and writes it through the writer every authored file goes through; a folder with no type gets an empty file of the name given. `documents.createKnowledge` is now a call to it and returns `{ bundle, file, type, ref, path, stashDir, indexed }`.
15
+ - `akm-cli/workspace`: `documents.check` returns the findings `akm lint` reports for text about to be saved at a path of an akm bundle (with lines where the check knows one) and whether akm could still read the asset (frontmatter that parses, a workflow that compiles, a task that validates), without writing anything. `documents.frontmatter` returns a file's frontmatter as keys and values in file order and the keys akm knows for its type with the required ones marked; `documents.applyFrontmatter` applies key changes (set, remove) to a text and leaves the body and every untouched key as written.
16
+ - `akm-cli/workspace`: `bundles.commit` runs `akm sync` for one bundle and returns what it did, and `bundles.list`'s `git` carries `uncommitted`, the files a sync would commit now (not the lines of `git status`; `null` when git could not list them). `akm sync` itself is unchanged.
17
+ - A daily usage report, on by default: at most once a UTC day per surface, the CLI (`cli_daily`) and AKM Desktop (`desktop_daily`, through the new `akm-cli/workspace` `activity.reportUsage`) send anonymous command counts and library sizes (bundles, indexed assets by type) to a self-hosted Aptabase at `reporting.fwdslsh.dev`. Never queries, refs, paths, names or argument values. `akm config set usage.report false` turns it off; `--read-only`, `usage.capture: false`, CI and test runs send nothing, and a failed send is never retried or shown. Experimental. See [Data and Telemetry](docs/reference/data-and-telemetry.md#daily-usage-report).
11
18
  - `akm rules [--project <name>|none] [--from <bundle>]... [--filter <key>=<value>]...` prints the rules that apply here, in full: the project's first, then shared ones, read from the files (no index needed) and recorded as one `rules` usage event per call, never a search or a show. `akm metrics` reports rule loads, rules and characters per load, and loads per rule. Experimental.
19
+ - `akm health` and `akm doctor` JSON: every check whose `status` is `unknown` carries a `reason` that says why it has no result: `off` (the feature is turned off), `not-probed` (the probe was not asked for), `blocked` (the check could not run or could not decide) or `idle` (nothing has happened yet). A check with any other status has none. AKM Desktop groups unknown checks by it instead of reading the message.
20
+ - `akm proposal accept` JSON (and each entry of a multi-id accept) carries `commit`: `{ "committed": true, "sha" }`, or `{ "committed": false, "reason", "error"? }` with `reason` `not-git`, `ignored`, `nothing-to-commit` or `failed`. AKM Desktop's accept receipt prints it, so a failed commit is shown as failed instead of as silence.
21
+ - `akm-cli/workspace` `bundles.list` reports, per bundle, `writeBlocker` (the sentence akm's write path would refuse with, or `null` when a write would be accepted) and `identity` (one name for where the bundle comes from, equal for the same repository however its address is written); and, once, `writeTarget` (where a write goes when no bundle is named, and why none does or why it would be refused) and `starter` (the starter bundle's `source` and `identity`). `assets.projectOverview`'s `writeBundle` reports `writeBlocker` in place of `usable`.
22
+ - `akm-cli/workspace`: `bundles.index` runs the incremental index, which pairs a file renamed or moved on disk with its asset (`moves` in the result); `assets.bundleFiles` also reports `place` (whether a folder may be made in the folder shown or an entry moved into it) and each entry's `size` and `modified`.
23
+ - AKM Desktop's Files view is a file manager. Every file and folder has a menu (right-click, the menu key, a button on each row) with New file, New folder, Rename, Move to…, Copy to…, Retire, Delete and Reveal in file manager, each offered or disabled from akm's verdicts with akm's sentence. Rename is inline, Move to… and Copy to… use a folder picker that is the tree, a drag onto a folder asks once. A move or rename is a plain rename on disk followed by the index, so the asset keeps its usage, feedback and proposal history and the open page follows it; a notice counts the links that still name the old place and one button rewrites them. New names what akm says the folder holds and makes it in the current folder; an empty folder or a file that is no asset is deleted after one confirmation; the list shows size and modified time. Git bundles show akm's uncommitted count and a Commit button.
24
+ - `akm-cli/workspace`: `assets.bundleFiles` `newFile` names an environment file or a secret (`through: "protected-editor"`) in the top-level `env/` and `secrets/`; `documents.check` names a file by its bundle path, not its scratch folder; `documents.frontmatter` returns `markdown` and `bodyStart` (in a bundle of any adapter) and `applyFrontmatter` the new `bodyStart`; `sensitive.describe` returns `actions: {edit, delete}` with akm's sentence in place of `writable`; `documents.createFile` takes a `type` in place of a folder; `assets.copyEntry` copies a file or folder to a chosen folder; `bundles.list`'s `git.dirtyPaths` is removed (`uncommitted` is the count).
25
+ - AKM Desktop shows a file's frontmatter as Properties under the title for every kind and edits it as fields (akm applies each change; unknown keys and the body stay as written, with a Text switch for the whole file). A script reads as code, a task as YAML, Source is the whole file. Save checks the text with akm first: findings are listed beside the editor with their lines, a text akm could not read as the asset stops the save with Save anyway, and the file is then shown as not indexed with akm's reason.
26
+ - `akm-cli/workspace`: `activity.taskHistory` runs carry `targetKind`, `targetRef` and `engine`, and `activity.taskRunLog` returns a task run's recorded output from `logs.db` (read-only; `available: false` when there is none). `setup.detect`'s harnesses carry `modelWorkReadOnly`, whether akm's model calls on that program can be limited to reading and searching. AKM Desktop's task run view shows what the run executed and a Log output section; Setup's "Choose it only if you accept that" follows `modelWorkReadOnly`, not the wording of the note.
27
+ - AKM Desktop's 3D library map is easier to choose from: a point is chosen from anywhere over its drawn disc, whatever the zoom (before, only within a fixed 14 pixels of its middle, which missed a point drawn larger than that), the point under the pointer is ringed, the chosen one is haloed and named by a label that stays over every other mark, and the left and right arrow keys step to the previous or next asset of its group and announce it.
28
+ - AKM Desktop's 3D library map draws three levels of joins from a chosen asset: its joins, theirs and theirs again, each level thinner and more muted than the last (the third dashed) with its assets ringed to match, and a key naming each level with the assets at it. A join is drawn once, at its nearest level; a level shows its 300 most joined assets and the key says how many it left out or could not place on the map. They are the links and near-duplicates `assets.graph` reports; nothing is inferred.
29
+ - AKM Desktop's Activity replay has a 2D / 3D switch (2D by default, the choice kept until the app closes). 3D plays the same events, with the same controls and figures, on the 3D map the Library uses: an asset used so far is in its type's colour, the rest are faint, and the asset an event reads, a search returns or feedback touches is ringed in a colour per kind as it plays. Events on assets with no place on the 3D map, or that the index no longer lists, are counted and said.
12
30
 
13
31
  ### Changed
14
32
 
33
+ - AKM Desktop's move is no longer a copy then a retirement of the original: the copy form, its texts and the old Move form are gone, and a moved asset keeps its identity. "New knowledge" on every folder is replaced by a button named for the folder's type; Environment file and Secret are under "New protected file". An asset page offers Edit page and Retire from akm's verdicts for its file (disabled with akm's reason) instead of from its type, and a read-only bundle's controls are no longer hidden without a reason.
34
+ - The base asset checks (`unquoted-colon`, `missing-updated`, `stale-path`, `missing-ref`, `redacted-content`) and the per-type checks (a command's and an agent's `name` and `type`, a fact's `category`, a task's source, a memory stub, a workflow stub and its compile findings) have one implementation, which the `akm lint` sweep and every adapter's `validate` (the lint of a bundle of another adapter) both run, with the run's own config, so an exemption or a fix to a rule reaches both. For a bundle of another adapter: `redacted-content` and the workflow compile advisories are now reported; a `missing-ref` reads `missing ref: <ref> (resolved to <path>)` (or `(frontmatter <key>; resolved to <path>)`); a ref is looked up as in an akm bundle (a qualified ref in the bundle it names, a retired memory's archive and a moved ref count); and a file inside an LLM Wiki of the bundle is exempt from `missing-updated` and `missing-name-or-type`. A pending change in a `ValidateContext` no longer satisfies a ref in the base checks.
35
+ - `akm lint` checks every ref a file declares in frontmatter (`xrefs`, `supersededBy`, `contradictedBy`, `currentBeliefRefs`, `sources`, `refs`, the keys the index reads as links) whatever folder it points into, and reads it as the index does (a wiki page's `raw/x.md` and `wiki:<name>/pages/x` are relative to its wiki). Before, only a ref that led with an akm type folder was checked, and `currentBeliefRefs` and `sources` were not. A word in prose is a ref only when it looks like one, as before. On a fixture with a wiki of 30 raw snapshots and 20 pages and one note, `missing-ref` findings went from 1 to 12; on an OKF bundle of 10 concepts with 5 dangling `xrefs` they stay at 5.
36
+ - `akm lint` does not apply `missing-updated` or `missing-name-or-type` to a file inside an LLM Wiki (a folder with `schema.md` and `pages/`): a wiki keeps its own schema and is written by the wiki's own process, so its raw snapshots and pages are not authored akm assets. Every other check still runs on them. On a wiki fixture (3 raw snapshots, 3 pages, 1 loose file) the per-rule counts went from `missing-updated` 7, `missing-name-or-type` 1, `missing-ref` 2 to `missing-updated` 1 (the loose file), `missing-ref` 2.
37
+ - `akm lint` of an akm bundle reads the files the indexer would index and types each by the indexer's classification, instead of the files under the type folders: it now reaches Markdown assets under a wiki folder, a loose folder and the bundle root, and no longer reads a dot-directory or a git-ignored file inside a type folder, which the indexer never lists. `env/` and `secrets/` are never read. On a fixture with files under a wiki folder and a loose folder the per-rule counts went from 2 findings (`missing-name-or-type` 1, `missing-updated` 1) to 12 (`missing-updated` 5, `missing-name-or-type` 2, `missing-ref` 2, `stale-path` 1, `unquoted-colon` 1, `redacted-content` 1).
38
+ - `indexWrittenAssets` recognizes a file through the named bundle's own adapter, and Desktop's plain save reports what it returns, not `indexed: true` for a bundle whose index it never refreshed.
39
+ - `akm lint` checks a qualified ref (`bundle//concept`) in the bundle it names, so one whose concept exists only in another bundle is now reported; an unqualified ref is looked up in every bundle as before. On a fixture with one such ref, `missing-ref` findings went from 1 to 2.
40
+ - AKM Desktop's plain-file routes refuse what akm reports as not allowed for the file: they read and wrote `.git/config` and files under `.akm/` before. A save into a read-only bundle is refused with the write path's sentence ("source <name> is not writable") instead of Desktop's own, and a file akm cannot open is refused with its cause (400) instead of failing as a 500.
41
+ - A failure to carry an asset's history to a re-keyed ref during `akm index` is a warning in the index result, not only a line on stderr.
15
42
  - Which bundles supply rules to a session, once the plugins load them with `akm rules`: the project's `from`, else the default bundle and the project's write bundle; with no project, the default bundle. The plugins' search-based listing read the shared rules of every enabled bundle the selection read, so a bundle installed from a registry or a git URL could add a rule to every session. Name such a bundle in the project's `from` to keep loading its rules. Search and curate are unchanged.
43
+ - `akm upgrade --check` reports what an update would do to the Claude Code and Codex plugins: the version it would install on the channel in force (`pending` with `to`), `current`, or the reason the marketplace could not be read. It reads the channel's build from the marketplace the harness registered, with the function the real update uses, so the plan and the update agree. The check now reads that remote; it still changes nothing.
44
+ - `akm health`'s Claude and Codex plugin checks read the newest plugin build the way `akm upgrade --check` does: the catalog of the channel's branch of the source and ref the harness registered, from a blobless, no-checkout clone (about 0.3 MB instead of the whole branch, 54 MB for `next`). The tag listing is gone. Health's "available" version is now the build the channel offers, a failed read says why in the message, a harness with no registered source is `unknown` (reason `blocked`), and a marketplace pinned to a tag is not read and offers nothing newer.
45
+ - AKM Desktop's Software page has one release channel for the CLI and plugins. Check runs `akm upgrade --check --channel <chosen>`, Update runs `akm upgrade --channel <chosen>`, and each plugin shows what akm reports: its version, the channel it follows and what Update would do. The Switch button and the CLI channel Desktop inferred from the version are gone. With no saved choice Desktop uses the channel akm reports for the installed CLI. Update is held only when the CLI itself would move past the engine in the app.
46
+ - AKM Desktop no longer links an improve run to a scheduled task run by task name and a five-minute window: no record ties the two, so the improve run page states the run's own facts only. A task run's history shows what the run executed and its recorded output (below). `akm-cli/workspace` `proposals.accept` and `proposals.acceptMany` carry the accept's `commit` as above in place of the commit read back from the repository's newest subject.
47
+ - AKM Desktop decides whether a bundle can take a write from akm's `writeBlocker`, not from `enabled`, `writable` and the adapter, wherever it offers a destination (copy, move, new file, protected file, project write bundle), and shows akm's sentence for a bundle it cannot use.
48
+
49
+ ### Removed
50
+
51
+ - AKM Desktop's Source history no longer shows a "Made by" badge or filter, and the commit entries of `akm-cli/workspace` `proposals.recentChanges` and `assets.history` no longer carry `origin`: it was judged from the commit subject, so a hand-written "Remember to rotate the key" read as akm's. Each commit shows its own author, date and subject; akm's commit messages are unchanged.
52
+
53
+ ### Fixed
54
+
55
+ - `akm upgrade --channel <channel>` no longer exits 1 when every installed plugin already follows that channel and one update is `deferred` (OpenCode is running) or `skipped`: the entry reports it, as in an upgrade with no `--channel`. It exited 1 on every such run, so AKM Desktop's Update, which always names the channel, failed whenever OpenCode was open. A plugin left on the other channel still makes the switch exit 1. When akm exits 1 without a failed step, AKM Desktop now shows what akm reported as not done (akm's message and each deferred or skipped plugin with its reason) instead of "AKM's upgrade exited with an error."
56
+ - AKM Desktop's asset page says why its usage and proposal read failed instead of only that it is unavailable. The Software page's hold on Update no longer guesses from the shape of a version whether Desktop's channel will offer that release.
57
+ - AKM Desktop's Activity views show what akm reports and say when akm reported nothing. `assets.searchMisses` and `activity.retrievalTrend` return `available: false` with the reason when `state.db` is absent or needs a migration, and the Runs, Usage and search-gap views and the Library map's searches that found nothing say so instead of "No runs recorded" or "No searches"; `activity.overview` names it in `errors.state`. `activity.pulse`, `assets.improvement` and `activity.improveImpact` report an unresolvable bundle directory instead of reading it as no proposals. Needs attention counts every failed task run from akm's full count, not the pulse's three-row preview; the Usage summary calls the proposals counted in its window "updated in this window" instead of "pending"; Repeated search gaps lists the queries akm marks `repeated`.
58
+ - `activity.improveImpact` returns `usageSince`, `usageComplete` and, per changed asset, `beforeComplete`, so a change whose 28 days before are older than the usage akm keeps shows "Not recorded", not 0. `activity.retrievalTrend` marks `partial` weeks and returns `enoughHistory`: no centre or usual range is drawn from fewer than four whole weeks. `activity.events` rows carry `byPerson`; Replay plays the person's events by default so its figures match the Usage tab, offers everyone's, and shows curates apart from searches. The workflow trace header sums tokens from the attempts akm reported and says "tokens not reported" when none did, and units that name no step get no invented status.
59
+ - AKM Desktop's protected-file view names a file akm types `env` or `secret` below the top level of a bundle as one akm manages only at the top level, in `env/` or `secrets/`; it opens, shows and changes nothing there.
60
+ - `akm lint` sweeps and accepts files in `rules/` and `instructions/`, which it had skipped: it now takes its folders from the asset registry instead of its own list. `akm lint rules/x.md` no longer fails with "not under a known asset directory". `--type` takes a type name (`rule`) or its folder name (`rules`), so every value shell completion offers is accepted. Types that search leaves out by default (`search.defaultExcludeTypes`, default `session`) are left out of the sweep unless `--type` names one; a single file is always linted. A file under `env/` or `secrets/` is refused, never read. The `bundlePolicy` migration strips `lint_skip` in the same folders.
61
+ - Usage records `--type` values `task`, `session`, `fact`, `instruction`, `rule`, `any` and folder names such as `memories` instead of `[redacted]`. Shell completion and the output config accept the `--format` and `--detail` values the output module defines.
62
+ - AKM Desktop no longer opens a nested `env/` or `secrets/` file in the plain editor: any file akm types `env` or `secret` is refused by the plain file routes, and a file akm's listing does not report is not opened.
63
+ - AKM Desktop says when it could not read something instead of showing a good state: an absent or unmigrated `state.db` is "unavailable" in Review, the pending badge and the Overview (it read as "All caught up"); a failed `git` read says why (it read as "Clean", "No commits" or "Detached HEAD"); an unreadable `preferences.json` is reported and moved aside on the next save instead of being silently replaced by defaults; the Library map no longer decides that usage is missing from a note's wording.
64
+ - AKM Desktop's embedding coverage counts the current model's vectors against embeddable entries, as akm's readiness check does; the "No model connection configured" item follows akm's learning status; new content goes where akm says it goes; the starter bundle is recognised by its source, not by a name containing `akm-stash`.
65
+ - AKM Desktop's Library map says when akm could not report something instead of drawing it as zero: feedback it could not read is "unavailable" (it read "Disliked 0" and "Liked · disliked 0 · 0"), near-duplicates it has no layout for are "unavailable" (they read "Near-duplicates inside 0"), and an asset with no readable edit time is not classed as unread. `akm-cli/workspace` `assets.graph` adds to its `note` that groups and near-duplicates are not available when the last index stored no layout.
66
+ - AKM Desktop's 3D Library map says how many assets it leaves out: an asset with no group by meaning (not embedded, or added since the last index build) is not a point, and the map now states the count instead of titling itself "every asset".
67
+ - AKM Desktop's Project assets page and Project overview say "Counts unknown" when akm reports no count for a bundle (it cannot be read, or nothing is indexed). The assets page read "0 eligible of 0 indexed" and blamed the project's filters; one presenter now serves both pages.
68
+ - AKM Desktop's setup no longer decides that a plugin "was built for a different akm" by comparing its version with the engine's major and minor. The agent cards show what `akm upgrade --check` reports for that plugin (a tick for `current`, akm's own text for a pending, deferred or failed update, with its engine-skew message), and claim nothing until a check has run.
69
+ - AKM Desktop's new-file editor says "That file name is already used" when akm's error code is `RESOURCE_ALREADY_EXISTS`, not when the message contains "already exists": a reworded message no longer shows akm's raw `--force` sentence, and an unrelated error that says "already exists" is no longer reported as a name collision.
16
70
 
17
71
  ## [0.10.261129] - 2026-11-16
18
72
 
package/STABILITY.md CHANGED
@@ -263,6 +263,16 @@ the collected baseline through the 0.11 storage migration, which keeps it in
263
263
  `metrics.db` in the resolved data directory;
264
264
  the migration guide tracks the data contract, retention, and verification.
265
265
 
266
+ ### Daily usage report (Experimental)
267
+
268
+ 0.10.x also sends one anonymous report a day per surface (the CLI and AKM Desktop, through
269
+ `akm-cli/workspace` `activity.reportUsage`) to a self-hosted Aptabase: command counts from the
270
+ data above and library sizes, never argument values, refs, paths or names. It is on by default and
271
+ `usage.report: false` in the config file turns it off; `--read-only`, `usage.capture: false`, CI and
272
+ test runs send nothing. The key, the event fields and `activity.reportUsage` are Experimental: the
273
+ fields may change between releases, and every change is listed in
274
+ [Data and Telemetry](docs/reference/data-and-telemetry.md#daily-usage-report).
275
+
266
276
  ### Remaining scheduled 0.11 removals and breaking changes
267
277
 
268
278
  The reviewed 0.11 branch already removes implicit
@@ -0,0 +1,184 @@
1
+ // This Source Code Form is subject to the terms of the Mozilla Public
2
+ // License, v. 2.0. If a copy of the MPL was not distributed with this
3
+ // file, You can obtain one at https://mozilla.org/MPL/2.0/.
4
+ /**
5
+ * The daily usage report: at most one event per surface (`cli`, `desktop`) per UTC day, to the owner's self-hosted
6
+ * Aptabase. Counts only: no argument value, ref, path, bundle name or instance id is ever read into it. The
7
+ * fields sent are listed in docs/reference/data-and-telemetry.md. Every failure is swallowed; the report never
8
+ * changes a command's output or exit code.
9
+ */
10
+ import { randomUUID } from "node:crypto";
11
+ import os from "node:os";
12
+ import { loadConfig } from "../core/config/config.js";
13
+ import { peekConfigValue } from "../core/config/peek.js";
14
+ import { getDbPath } from "../core/paths.js";
15
+ import { isKnownType } from "../core/recognition-util.js";
16
+ import { openDatabase } from "../storage/database.js";
17
+ import { getEntryCountByType } from "../storage/repositories/index-entries-repository.js";
18
+ import { pkgVersion } from "../version.js";
19
+ import { openUsage, readUsage } from "./usage.js";
20
+ // The Aptabase app key is write-only and public by design (it ships in every Aptabase SDK). The host is fixed:
21
+ // no environment variable or config key can redirect it.
22
+ const ENDPOINT = "https://reporting.fwdslsh.dev/api/v0/event";
23
+ const APP_KEY = "A-SH-4111202318";
24
+ const SEND_TIMEOUT_MS = 1500;
25
+ const DAY_MS = 86_400_000;
26
+ /** No test run and no CI run reaches the network: `CI`, `bun test` (`NODE_ENV=test`, `BUN_TEST`). */
27
+ function underTestOrCi(env) {
28
+ return Boolean(env.CI) || env.NODE_ENV === "test" || env.BUN_TEST === "1";
29
+ }
30
+ /**
31
+ * Whether the report is on, from the effective config (`extends` layers included): off when any layer sets
32
+ * `usage.report: false` and no nearer layer overrides it. A config that cannot be loaded is "not enabled": akm
33
+ * cannot confirm the person has not opted out, so nothing is sent.
34
+ */
35
+ export function usageReportEnabled() {
36
+ try {
37
+ return loadConfig().usage?.report !== false;
38
+ }
39
+ catch {
40
+ return false;
41
+ }
42
+ }
43
+ function day(at) {
44
+ return at.toISOString().slice(0, 10);
45
+ }
46
+ function addDays(utcDay, days) {
47
+ return day(new Date(Date.parse(`${utcDay}T00:00:00Z`) + days * DAY_MS));
48
+ }
49
+ /**
50
+ * Take today for `surface`: true for exactly one caller per UTC day, across concurrent processes (one atomic
51
+ * upsert). A store created today claims nothing, so a fresh install or sandbox reports from its next UTC day.
52
+ * Returns the previously reported day (undefined before the first report).
53
+ */
54
+ function claimDay(surface, today) {
55
+ const db = openUsage();
56
+ try {
57
+ const started = db.prepare("SELECT value FROM cli_usage_meta WHERE key='collectionStart'").get()?.value;
58
+ if (started === undefined || started.slice(0, 10) >= today)
59
+ return undefined;
60
+ const key = `report.${surface}.last_day`;
61
+ const last = db.prepare("SELECT value FROM cli_usage_meta WHERE key=?").get(key)
62
+ ?.value;
63
+ // Already reported today (every command after the first): a read only, no write lock on the shared store.
64
+ if (last !== undefined && last >= today)
65
+ return undefined;
66
+ const claimed = db
67
+ .prepare("INSERT INTO cli_usage_meta(key,value) VALUES (?,?) ON CONFLICT(key) DO UPDATE SET value=excluded.value WHERE cli_usage_meta.value < excluded.value")
68
+ .run(key, today).changes;
69
+ return claimed ? { last } : undefined;
70
+ }
71
+ finally {
72
+ db.close();
73
+ }
74
+ }
75
+ /** Counts of the complete UTC days after `last` up to yesterday, from the durable aggregates. */
76
+ function cliCounts(last, today) {
77
+ const since = last === undefined ? today : addDays(last, 1);
78
+ const until = addDays(today, -1);
79
+ const props = { period_days: 0, commands: 0, failures: 0 };
80
+ if (since > until)
81
+ return props;
82
+ props.period_days = (Date.parse(`${until}T00:00:00Z`) - Date.parse(`${since}T00:00:00Z`)) / DAY_MS + 1;
83
+ const report = readUsage({ since, until, aggregatesOnly: true });
84
+ for (const row of report.aggregates) {
85
+ const dimensions = row.dimensions;
86
+ const attempts = Number(row.attempts);
87
+ props.commands = (props.commands ?? 0) + attempts;
88
+ props.failures = (props.failures ?? 0) + Number(row.failures);
89
+ if (dimensions.source && ["user", "agent", "task", "improve"].includes(dimensions.source)) {
90
+ const key = `src_${dimensions.source}`;
91
+ props[key] = (props[key] ?? 0) + attempts;
92
+ }
93
+ const name = (dimensions.command?.[0] ?? "").replace(/[^a-z0-9-]/g, "") || "other";
94
+ const key = `cmd_${name}`.slice(0, 40);
95
+ props[key] = (props[key] ?? 0) + attempts;
96
+ }
97
+ for (const key of ["src_user", "src_agent", "src_task", "src_improve"])
98
+ props[key] ??= 0;
99
+ return props;
100
+ }
101
+ /** Enabled bundle count from the config file, and the indexed asset counts (by akm's own types) from the read-only index. Absent when unreadable. */
102
+ function librarySnapshot() {
103
+ const props = {};
104
+ const bundles = peekConfigValue(["bundles"]);
105
+ if (typeof bundles === "object" && bundles !== null) {
106
+ props.bundles = Object.values(bundles).filter((b) => b?.enabled !== false).length;
107
+ }
108
+ try {
109
+ const db = openDatabase(getDbPath(), { readonly: true, create: false });
110
+ try {
111
+ db.exec("PRAGMA busy_timeout=250; PRAGMA query_only=ON;");
112
+ const byType = getEntryCountByType(db);
113
+ props.assets = Object.values(byType).reduce((sum, n) => sum + n, 0);
114
+ // A type outside akm's own set is named by a bundle's adapter or the user: it is counted, never named.
115
+ for (const [type, n] of Object.entries(byType)) {
116
+ const key = isKnownType(type) ? `assets_${type}` : "assets_other";
117
+ props[key] = (props[key] ?? 0) + n;
118
+ }
119
+ }
120
+ finally {
121
+ db.close();
122
+ }
123
+ }
124
+ catch {
125
+ // No index, or one that cannot be read: the snapshot omits the asset counts.
126
+ }
127
+ return props;
128
+ }
129
+ function systemProps(version) {
130
+ const platform = process.platform;
131
+ return {
132
+ isDebug: false,
133
+ locale: Intl.DateTimeFormat().resolvedOptions().locale,
134
+ osName: platform === "linux" ? "Linux" : platform === "darwin" ? "macOS" : platform === "win32" ? "Windows" : platform,
135
+ osVersion: os.release(),
136
+ engineName: process.versions.bun ? "bun" : "node",
137
+ engineVersion: process.versions.bun ?? process.versions.node,
138
+ appVersion: version,
139
+ sdkVersion: `akm@${version}`,
140
+ };
141
+ }
142
+ /** Send the surface's daily event when it is due. Resolves true when the server accepted it; never throws. */
143
+ export async function reportUsageIfDue({ surface, version = pkgVersion }, deps = {}) {
144
+ try {
145
+ const env = deps.env ?? process.env;
146
+ if (underTestOrCi(env) || !usageReportEnabled())
147
+ return false;
148
+ const now = deps.now ?? new Date();
149
+ const today = day(now);
150
+ const claim = claimDay(surface, today);
151
+ if (!claim)
152
+ return false;
153
+ const props = {
154
+ ...(surface === "cli" ? cliCounts(claim.last, today) : {}),
155
+ ...librarySnapshot(),
156
+ };
157
+ const controller = new AbortController();
158
+ const timer = setTimeout(() => controller.abort(), deps.timeoutMs ?? SEND_TIMEOUT_MS);
159
+ try {
160
+ const response = await (deps.fetch ?? fetch)(ENDPOINT, {
161
+ method: "POST",
162
+ headers: { "App-Key": APP_KEY, "Content-Type": "application/json" },
163
+ body: JSON.stringify({
164
+ timestamp: now.toISOString(),
165
+ sessionId: randomUUID(),
166
+ eventName: `${surface}_daily`,
167
+ systemProps: systemProps(version),
168
+ props,
169
+ }),
170
+ signal: controller.signal,
171
+ });
172
+ if (!response.ok)
173
+ return false;
174
+ const body = (await response.json().catch(() => ({})));
175
+ return !body?.error;
176
+ }
177
+ finally {
178
+ clearTimeout(timer);
179
+ }
180
+ }
181
+ catch {
182
+ return false;
183
+ }
184
+ }
package/dist/cli/usage.js CHANGED
@@ -4,10 +4,12 @@
4
4
  import { randomUUID } from "node:crypto";
5
5
  import fs from "node:fs";
6
6
  import path from "node:path";
7
+ import { stashDirNames } from "../core/asset/asset-placement.js";
7
8
  import { peekConfigValue } from "../core/config/peek.js";
8
9
  import { getDataDir } from "../core/paths.js";
9
- import { isKnownType } from "../core/recognition-util.js";
10
+ import { isKnownType, KNOWN_TYPES } from "../core/recognition-util.js";
10
11
  import { hasSignalOwner, observeSignal } from "../core/signal-observers.js";
12
+ import { DETAIL_VALUES, OUTPUT_FORMATS } from "../output/context.js";
11
13
  import { openDatabase } from "../storage/database.js";
12
14
  import { applyStandardPragmas } from "../storage/sqlite-pragmas.js";
13
15
  import { resolveAgentIdentity } from "../workflows/runtime/agent-identity.js";
@@ -15,9 +17,9 @@ import { cittyComparableName, findCittyTopLevelCommandIndex, toAliasArray } from
15
17
  // Enum-like string flags are not enums in citty. Keep this finite allowlist
16
18
  // independent of user data and never infer safety from the supplied value.
17
19
  const SAFE_VALUES = {
18
- format: ["json", "jsonl", "yaml", "text", "md"],
19
- detail: ["agent", "brief", "normal", "full"],
20
- type: ["skill", "agent", "command", "script", "knowledge", "workflow", "env", "secret", "memory", "lesson"],
20
+ format: OUTPUT_FORMATS,
21
+ detail: DETAIL_VALUES,
22
+ type: [...KNOWN_TYPES, "any", ...stashDirNames()],
21
23
  };
22
24
  /** Scan declared identities only. Unknown spellings can themselves contain secrets. */
23
25
  export function describeUsage(root, raw) {
@@ -200,7 +202,7 @@ function usagePath() {
200
202
  // `schema_migrations` ledger, so they use their own `cli_usage_` names and a
201
203
  // version in `cli_usage_meta` (never PRAGMA user_version or schema_migrations).
202
204
  const USAGE_SCHEMA = 1;
203
- function openUsage(filename) {
205
+ export function openUsage(filename = usagePath()) {
204
206
  fs.mkdirSync(path.dirname(filename), { recursive: true });
205
207
  const db = openDatabase(filename);
206
208
  try {
@@ -235,6 +237,18 @@ export function setResolvedUsageAssetType(type, executor) {
235
237
  function captureDisabledByConfig() {
236
238
  return peekConfigValue(["usage", "capture"]) === false;
237
239
  }
240
+ function readOnlyRequested(usage) {
241
+ return usage.arguments.some((a) => a.name === "read-only" && a.explicit && a.value === true);
242
+ }
243
+ /** Whether this invocation records no counts (`--read-only` or `usage.capture: false`), so there is nothing to report. */
244
+ export function usageCaptureOff(root, raw) {
245
+ try {
246
+ return readOnlyRequested(describeUsage(root, raw)) || captureDisabledByConfig();
247
+ }
248
+ catch {
249
+ return true;
250
+ }
251
+ }
238
252
  export function startUsage(root, raw, version) {
239
253
  const started = Date.now();
240
254
  const id = randomUUID();
@@ -254,7 +268,7 @@ export function startUsage(root, raw, version) {
254
268
  const usage = describeUsage(root, raw);
255
269
  // `--read-only` promises no writes, and the config key turns capture off.
256
270
  // Either way nothing is opened, written or finalized.
257
- if (usage.arguments.some((a) => a.name === "read-only" && a.explicit && a.value === true))
271
+ if (readOnlyRequested(usage))
258
272
  return () => { };
259
273
  if (captureDisabledByConfig())
260
274
  return () => { };
@@ -470,7 +484,10 @@ export function readUsage(filter = {}) {
470
484
  unfinished: Number(row.attempts) - Number(row.completed),
471
485
  });
472
486
  }
473
- for (const row of db.prepare("SELECT * FROM cli_usage_invocations ORDER BY ts,id").all()) {
487
+ const detailRows = filter.aggregatesOnly
488
+ ? []
489
+ : db.prepare("SELECT * FROM cli_usage_invocations ORDER BY ts,id").all();
490
+ for (const row of detailRows) {
474
491
  const data = JSON.parse(String(row.data));
475
492
  if (selected({ ...data, day: String(data.ts).slice(0, 10) }))
476
493
  empty.details.push({
package/dist/cli.js CHANGED
@@ -70,7 +70,8 @@ import { warnDeprecatedUse } from "./cli/deprecations.js";
70
70
  import { cittyComparableName, findCittyTopLevelCommandIndex, getParsedInvocation, parseAllFlagValues, resolveHelpMigrateVersionArg, setParsedInvocation, } from "./cli/invocation.js";
71
71
  import { defineGroupCommand, EXIT_CODES, emitJsonError, GLOBAL_OUTPUT_ARGS, output, runWithJsonErrors, withoutHelpHiddenArgs, } from "./cli/shared.js";
72
72
  import { assertKnownFlags, consumeConfigFileFlag } from "./cli/unknown-flags.js";
73
- import { startUsage } from "./cli/usage.js";
73
+ import { startUsage, usageCaptureOff } from "./cli/usage.js";
74
+ import { reportUsageIfDue } from "./cli/usage-report.js";
74
75
  import { agentCommand, lintCommand } from "./commands/agent/contribute-cli.js";
75
76
  import { backupsCommand } from "./commands/backups-cli.js";
76
77
  import { commandCommand } from "./commands/command/command-cli.js";
@@ -1165,6 +1166,9 @@ export async function runCli() {
1165
1166
  // Deliver catchable signals queued during synchronous child execution.
1166
1167
  await new Promise((resolve) => setImmediate(resolve));
1167
1168
  finishUsage();
1169
+ // After the command's own work; never changes output or exit code (see src/cli/usage-report.ts).
1170
+ if (!usageCaptureOff(main, originalArgs))
1171
+ await reportUsageIfDue({ surface: "cli", version: pkgVersion });
1168
1172
  }
1169
1173
  }
1170
1174
  /** Apply `--config <file>` (stripping it from argv) and normalise `AKM_CONFIG_FILE` to an absolute path. */
@@ -4,11 +4,12 @@
4
4
  import fs from "node:fs";
5
5
  import os from "node:os";
6
6
  import path from "node:path";
7
- import { placementTypes } from "../core/asset/asset-placement.js";
7
+ import { documentTypes, placementTypes } from "../core/asset/asset-placement.js";
8
+ import { DETAIL_VALUES, OUTPUT_FORMATS } from "../output/context.js";
8
9
  const FLAG_VALUES = {
9
- "--format": [{ values: ["json", "jsonl", "yaml", "text", "md"] }],
10
- "--detail": [{ values: ["brief", "normal", "full", "agent"] }],
11
- "--type": [{ values: () => [...placementTypes(), "any"] }],
10
+ "--format": [{ values: [...OUTPUT_FORMATS] }],
11
+ "--detail": [{ values: [...DETAIL_VALUES] }],
12
+ "--type": [{ paths: ["akm lint"], values: () => documentTypes() }, { values: () => [...placementTypes(), "any"] }],
12
13
  "--shell": [{ values: ["bash"] }],
13
14
  "--from": [{ paths: ["akm search", "akm curate"], values: ["local", "registry", "all"] }],
14
15
  };
@@ -125,7 +125,9 @@ export const HEALTH_CHECKS = [
125
125
  name: "state-db-round-trip",
126
126
  kind: "deterministic",
127
127
  // A skipped probe proved nothing: it is unknown, not a pass.
128
- status: ctx.probe.skipped ? "unknown" : ctx.probe.ok ? "pass" : "fail",
128
+ ...(ctx.probe.skipped
129
+ ? { status: "unknown", reason: "not-probed" }
130
+ : { status: ctx.probe.ok ? "pass" : "fail" }),
129
131
  confidence: "high",
130
132
  message: ctx.probe.skipped
131
133
  ? "state.db append/read round-trip skipped: this run is read-only."
@@ -244,7 +246,11 @@ export const HEALTH_CHECKS = [
244
246
  return {
245
247
  name: "improve-failures",
246
248
  kind: "deterministic",
247
- status: failedRunIds.length > 0 ? "warn" : interruptedRunIds.length > 0 ? "unknown" : "pass",
249
+ ...(failedRunIds.length > 0
250
+ ? { status: "warn" }
251
+ : interruptedRunIds.length > 0
252
+ ? { status: "unknown", reason: "blocked" }
253
+ : { status: "pass" }),
248
254
  confidence: "high",
249
255
  message: failedRunIds.length > 0 || interruptedRunIds.length > 0
250
256
  ? `${failedRunIds.length} improve run(s) recorded failures since ${ctx.since}.${interruption ? ` ${interruption}` : ""} Inspect \`akm doctor --since ${ctx.since} --group-by run\`.`
@@ -346,7 +352,9 @@ export const HEALTH_CHECKS = [
346
352
  };
347
353
  const totalRows = rows.reduce((sum, row) => sum + row.count, 0);
348
354
  if (totalRows === 0) {
349
- return { ...base, status: "unknown", message: `No extraction recorded in the last ${days} days.` };
355
+ // Extraction is off when the strategy does not enable it; with the config unreadable that is not known.
356
+ const reason = !ctx.proposalQueue ? "blocked" : ctx.proposalQueue.extractEnabled ? "idle" : "off";
357
+ return { ...base, status: "unknown", reason, message: `No extraction recorded in the last ${days} days.` };
350
358
  }
351
359
  // `read_failed` / `exception` land in the ledger as `failed`, not `skipped`.
352
360
  const nothingHarvested = rows.every((row) => ["skipped", "failed", "proposal_write_failed"].includes(row.outcome));
@@ -412,13 +420,19 @@ export const HEALTH_CHECKS = [
412
420
  return {
413
421
  ...base,
414
422
  status: "unknown",
423
+ reason: "blocked",
415
424
  message: "The primary stash or config could not be read; the proposal queue owner was not checked.",
416
425
  };
417
426
  }
418
427
  const { stashDir, extractEnabled, problem } = ctx.proposalQueue;
419
428
  const ranRecently = ctx.sessionExtractionLedger.rows.some((row) => row.count > 0);
420
429
  if (!extractEnabled && !ranRecently) {
421
- return { ...base, status: "unknown", message: "Learning is off, so the proposal queue owner was not checked." };
430
+ return {
431
+ ...base,
432
+ status: "unknown",
433
+ reason: "off",
434
+ message: "Learning is off, so the proposal queue owner was not checked.",
435
+ };
422
436
  }
423
437
  if (!problem)
424
438
  return { ...base, status: "pass", message: `The proposal queue of ${stashDir} has a writable owner.` };
@@ -87,6 +87,7 @@ export function connectionsAndHarnessesCheck(rows, probed, ambiguous) {
87
87
  return {
88
88
  ...base,
89
89
  status: "unknown",
90
+ reason: "off",
90
91
  message: "No connection or harness is configured: model features and agentic work are off. Run `akm setup`.",
91
92
  };
92
93
  }