akm-cli 0.10.261129 → 0.10.261130-beta.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (114) hide show
  1. package/CHANGELOG.md +58 -0
  2. package/STABILITY.md +11 -0
  3. package/dist/assets/hints/cli-hints-full.md +1 -1
  4. package/dist/assets/hints/cli-hints-short.md +1 -0
  5. package/dist/assets/stash-skeleton/facts/conventions/assets/rule.md +1 -1
  6. package/dist/cli/usage-report.js +184 -0
  7. package/dist/cli/usage.js +24 -7
  8. package/dist/cli.js +8 -2
  9. package/dist/commands/completions.js +5 -4
  10. package/dist/commands/health/checks.js +18 -4
  11. package/dist/commands/health/connections-and-harnesses-check.js +1 -0
  12. package/dist/commands/health/egress.js +1 -2
  13. package/dist/commands/health/plugin-staleness.js +75 -159
  14. package/dist/commands/health/scheduler-binary.js +7 -2
  15. package/dist/commands/health/semantic-search-check.js +7 -6
  16. package/dist/commands/health/version-drift.js +2 -0
  17. package/dist/commands/improve/extract.js +2 -2
  18. package/dist/commands/improve/preparation.js +6 -1
  19. package/dist/commands/lint/base-linter.js +90 -48
  20. package/dist/commands/lint/index.js +128 -185
  21. package/dist/commands/lint/moved-refs.js +69 -0
  22. package/dist/commands/lint/scope.js +41 -0
  23. package/dist/commands/metrics/collect.js +25 -2
  24. package/dist/commands/metrics/report-view.js +11 -2
  25. package/dist/commands/proposal/proposal.js +7 -2
  26. package/dist/commands/proposal/repository.js +16 -11
  27. package/dist/commands/read/rules.js +142 -0
  28. package/dist/commands/read/search-cli.js +5 -5
  29. package/dist/commands/read/search.js +1 -1
  30. package/dist/commands/sources/plugin-upgrade.js +139 -71
  31. package/dist/commands/sources/source-clone.js +4 -4
  32. package/dist/commands/sources/sources-cli.js +3 -20
  33. package/dist/commands/sources/sync.js +24 -0
  34. package/dist/commands/tasks/tasks.js +1 -1
  35. package/dist/core/adapter/adapters/akm-adapter.js +32 -23
  36. package/dist/core/adapter/adapters/akm-lint.js +55 -61
  37. package/dist/core/adapter/adapters/akm-workflow-adapter.js +10 -14
  38. package/dist/core/adapter/adapters/llm-wiki-adapter.js +6 -17
  39. package/dist/core/adapter/adapters/okf-adapter.js +5 -9
  40. package/dist/core/adapter/adapters/shared.js +52 -200
  41. package/dist/core/adapter/adapters/tool-dir-shared.js +3 -2
  42. package/dist/core/adapter/adapters/website-snapshot-adapter.js +4 -4
  43. package/dist/core/adapter/validate-context.js +7 -11
  44. package/dist/core/asset/asset-placement.js +29 -0
  45. package/dist/core/asset/frontmatter-edit.js +124 -0
  46. package/dist/core/asset/lint-text.js +18 -2
  47. package/dist/core/asset/llm-wiki-root.js +30 -0
  48. package/dist/core/asset/ref-rewrite.js +39 -0
  49. package/dist/core/asset/type-keys.js +59 -0
  50. package/dist/core/config/schema/local-state.js +5 -1
  51. package/dist/core/config/schema/output.js +4 -4
  52. package/dist/core/config/schema/search.js +4 -0
  53. package/dist/core/write-source.js +75 -25
  54. package/dist/indexer/index-written-assets.js +16 -8
  55. package/dist/indexer/indexer.js +68 -19
  56. package/dist/indexer/legacy-refs.js +1 -26
  57. package/dist/indexer/links/declared-links.js +13 -11
  58. package/dist/indexer/ref-moves.js +75 -0
  59. package/dist/indexer/search/db-search.js +3 -2
  60. package/dist/indexer/walk/place-rules.js +25 -0
  61. package/dist/indexer/walk/walker.js +5 -1
  62. package/dist/integrations/session-logs/pre-filter.js +1 -0
  63. package/dist/output/context.js +6 -2
  64. package/dist/output/shapes/passthrough.js +1 -0
  65. package/dist/output/text/rules.js +14 -0
  66. package/dist/output/text.js +2 -0
  67. package/dist/scripts/akm-migrate-node.js +4651 -3584
  68. package/dist/scripts/akm-migrate.js +4650 -3584
  69. package/dist/setup/registry-stash-loader.js +4 -2
  70. package/dist/sources/providers/git-stash.js +13 -5
  71. package/dist/storage/repositories/index-entries-repository.js +8 -3
  72. package/dist/storage/repositories/index-llm-cache-repository.js +4 -0
  73. package/dist/workspace/activity.js +69 -8
  74. package/dist/workspace/asset-improve.js +9 -5
  75. package/dist/workspace/assets.js +33 -19
  76. package/dist/workspace/bundle-files.js +39 -2
  77. package/dist/workspace/bundles.js +53 -3
  78. package/dist/workspace/check-text.js +121 -0
  79. package/dist/workspace/config.js +3 -0
  80. package/dist/workspace/copy-entry.js +129 -0
  81. package/dist/workspace/derive.js +13 -4
  82. package/dist/workspace/documents.js +11 -16
  83. package/dist/workspace/file-actions.js +130 -0
  84. package/dist/workspace/frontmatter.js +41 -0
  85. package/dist/workspace/git-read.js +42 -27
  86. package/dist/workspace/graph.js +11 -2
  87. package/dist/workspace/impact.js +14 -5
  88. package/dist/workspace/metrics.js +1 -1
  89. package/dist/workspace/misses.js +8 -3
  90. package/dist/workspace/moved-links.js +57 -0
  91. package/dist/workspace/new-file.js +141 -0
  92. package/dist/workspace/proposals.js +12 -38
  93. package/dist/workspace/pulse.js +16 -9
  94. package/dist/workspace/readers.js +14 -0
  95. package/dist/workspace/sensitive.js +12 -6
  96. package/dist/workspace/setup.js +2 -1
  97. package/dist/workspace/stats.js +4 -0
  98. package/dist/workspace.d.ts +100 -1
  99. package/docs/architecture/adapters.md +15 -0
  100. package/docs/architecture/internals/health-advisories.md +13 -8
  101. package/docs/architecture/internals/indexing.md +1 -0
  102. package/docs/architecture/internals/storage-locations.md +3 -3
  103. package/docs/architecture/persisted-data-compat.md +2 -0
  104. package/docs/architecture/specs/ref.md +27 -13
  105. package/docs/guides/author-bundles.md +13 -12
  106. package/docs/integration/bundling-akm.md +3 -0
  107. package/docs/maintainers/implementation-details.md +1 -1
  108. package/docs/reference/api.md +3 -3
  109. package/docs/reference/cli.md +143 -35
  110. package/docs/reference/configuration.md +2 -1
  111. package/docs/reference/data-and-telemetry.md +49 -10
  112. package/docs/reference/workspace.md +122 -36
  113. package/package.json +1 -1
  114. package/schemas/akm-config.json +6 -0
@@ -350,8 +350,8 @@ akm index --skip-if-locked # for scheduled/opportunistic runs: skip (exit 0) in
350
350
  ```
351
351
 
352
352
  Returns stats: `totalEntries`, `generatedMetadata`, `directoriesScanned`,
353
- `directoriesSkipped`, `verification`, optional `warnings`, and `timing`
354
- breakdown in milliseconds. Use `--verbose` to print the indexing mode,
353
+ `directoriesSkipped`, `verification`, optional `warnings`, optional `moves`, and
354
+ `timing` breakdown in milliseconds. Use `--verbose` to print the indexing mode,
355
355
  semantic-search settings, and phase-by-phase progress to stderr while the
356
356
  index is being built. Malformed workflow assets are skipped with file-path
357
357
  warnings instead of aborting the full run. `verification.embeddingRuntime` is
@@ -370,6 +370,25 @@ per-batch `Embedded N/M entries.` line stays out of non-verbose stderr (it
370
370
  fires after every committed batch) — pass `--verbose` for that level of
371
371
  detail.
372
372
 
373
+ **A file renamed or moved on disk is the same asset.** Move or rename a file or a
374
+ folder with `mv`, `git mv` or a file manager; there is no move command. When the
375
+ index next runs (full or incremental), an entry whose file is gone while a new file
376
+ in the same bundle or another indexed bundle has the same content is paired with
377
+ it: its row is re-keyed in place, so its vector, links and utility stay, and the
378
+ state.db rows keyed by its old ref (usage, feedback, proposals, events, improve
379
+ ledger, salience, outcome, task and workflow history) and its cached model results
380
+ move to the new ref. Search utility is unchanged by the move and nothing is
381
+ embedded again. When several vanished or new files share a content hash, the ones
382
+ whose file names match one to one are paired; anything still ambiguous is not
383
+ paired and is indexed as new (its history stays with the old ref), and a warning
384
+ names the old refs. A file that was also edited is a new asset. The result's
385
+ `moves` is `{ moved: [{ from, to }], unpaired }` (the refs as `bundle//conceptId`),
386
+ present only when a file was paired or could not be; each move is recorded as a
387
+ `moved` event on the new ref with `{ from }`, which `akm lint` reads to report
388
+ links to the old ref (the events table keeps 90 days). A failure to carry the
389
+ history over is a warning in the result, not silence. Links to the old ref in other
390
+ assets are not rewritten here: see [lint](#lint).
391
+
373
392
  **`--clean` flag:** After indexing completes, verifies every indexed entry's source
374
393
  file still exists on disk. Removes any entries whose file is missing (for local
375
394
  bundle sources only; remote entries are skipped). Returns a `clean` block in the
@@ -637,14 +656,15 @@ GitHub's latest release, and for a prerelease install also npm's `next` tag, as
637
656
  runs the scheduler's recorded akm binary with `--version` to check it
638
657
  against the running CLI (`scheduler-binary`).
639
658
  The `plugin-version` advisory compares the installed Claude Code plugin with the
640
- channel its marketplace clone follows: the newest stable tag on the remote's
641
- default branch, the release tag on the branch head for another branch such as
642
- `next`, and the pinned tag for a marketplace added at a tag. It also compares
659
+ newest build on the channel the registered marketplace follows, read the way
660
+ `akm upgrade --check` reads it (the version the branch's catalog offers, from the
661
+ source and `ref` Claude registered; a marketplace pinned to a tag offers nothing
662
+ newer). It also compares
643
663
  the `akm-cli` the plugin's `package.json` pins (the copy its hooks run, which
644
664
  shares the host's databases) with the running CLI, and says which side is older.
645
665
  `codex-plugin-version` does the same for a Codex install from the `akm-plugins`
646
666
  marketplace (the version from `codex plugin list`, the newest release on the
647
- `ref` its marketplace entry follows, and the `akm-cli` in that version's plugin
667
+ `ref` and source its marketplace entry registers, and the `akm-cli` in that version's plugin
648
668
  cache under `$CODEX_HOME/plugins/cache/akm-plugins/akm/`, compared with the
649
669
  running CLI), and `opencode-plugin-version` /
650
670
  `opencode-v2-plugin-version` compare the `akm-cli` bundled in the OpenCode plugin
@@ -653,6 +673,10 @@ the config loads with the running CLI. A plugin ahead of the CLI is fixed by
653
673
  newer build; a lookup that could not reach the marketplace is `unknown` and
654
674
  says so.
655
675
 
676
+ Every check result with status `unknown` also carries a `reason` saying why there is no result: `off` (the feature is
677
+ turned off), `not-probed` (the probe was not asked for), `blocked` (the check could not run or could not decide) or
678
+ `idle` (nothing has happened yet).
679
+
656
680
  Primary result fields:
657
681
 
658
682
  | Field | Description |
@@ -747,7 +771,7 @@ Deprecated; use `akm doctor metrics`; removed in 0.11.
747
771
  **Experimental** (see [STABILITY.md](../../STABILITY.md)): the report, its JSON shape and the
748
772
  dashboard may change in any release.
749
773
 
750
- Report what akm has recorded locally: asset usage (search, show, curate),
774
+ Report what akm has recorded locally: asset usage (search, show, curate, rule loads),
751
775
  feedback, derived utility, LLM tokens, task runs, proposal
752
776
  flow, workflow token spend, and index runs. Read-only, and every number comes
753
777
  from `state.db` or `index.db`; nothing is collected that was not already
@@ -773,7 +797,7 @@ Result sections (`schemaVersion: 1`):
773
797
  | Field | Description |
774
798
  | --- | --- |
775
799
  | `window`, `filters` | The resolved window and the usage source counted |
776
- | `usage` | Search, show, curate and select totals, `searchesWithHits` and `selectsPerSearch` (selects divided by searches that returned a hit: a plain ratio that can exceed 1, not a conversion percentage; selects are deduped per search id and ref, and kept only when they followed a search from the counted source, except legacy selects with no source, which count for every source), `searchMedianMs` (over searches with `totalMs >= 0`), a daily series, top assets, top and zero-result queries, and rows by source |
800
+ | `usage` | Search, show, curate and select totals, `searchesWithHits` and `selectsPerSearch` (selects divided by searches that returned a hit: a plain ratio that can exceed 1, not a conversion percentage; selects are deduped per search id and ref, and kept only when they followed a search from the counted source, except legacy selects with no source, which count for every source), `searchMedianMs` (over searches with `totalMs >= 0`), a daily series (with `rules`, the `akm rules` loads per day), `rules` (`loads`, the mean `meanRules` and `meanChars` per load, and `byRule`, loads per rule), top assets, top and zero-result queries, and rows by source |
777
801
  | `feedback` | Positive and negative totals, per-asset valence, per-tag counts, and the most recent negatives with their reasons |
778
802
  | `utility` | A ten-bucket histogram of `utility_scores`, the lowest and highest assets, and how many indexed entries were never used |
779
803
  | `outcomes` | The assets with the lowest `outcome_score` |
@@ -1852,11 +1876,18 @@ marketplaces at every start.
1852
1876
  The result gains a `plugins` array, one entry per harness:
1853
1877
  `{ "harness": "claude-code" | "codex" | "opencode" | "opencode-v2", "outcome": ..., "from"?, "to"?, "message"? }`.
1854
1878
  `outcome` is `updated`, `current`, `skipped`, `deferred` or `failed`; under
1855
- `--check` it can also be `pending` or `unknown`. `--check` does not fetch the
1856
- Claude Code or Codex marketplaces, so for them it reports `unknown` (whether a
1857
- newer build exists needs a fetch it does not do) rather than guessing; for
1858
- OpenCode it compares the cached version with npm, so it reports `pending` when
1859
- an update is due. A `failed` plugin makes `akm upgrade` exit `1` (not
1879
+ `--check` it can also be `pending` or `unknown`. `--check` writes nothing. For
1880
+ Claude Code and Codex it reads the akm build the channel in force offers, the same
1881
+ read the real switch makes and `akm health` makes: the catalog and plugin manifest
1882
+ of the channel's branch of the marketplace the harness has registered, read from a
1883
+ blobless clone with nothing checked out in a temporary folder. The channel is
1884
+ the `--channel` asked for, else the one the marketplace follows. It reports
1885
+ `pending`, with that build as `to`, when it is newer than the installed one, else
1886
+ `current`; with `--channel`, a plugin whose channel has nothing newer (or whose
1887
+ build cannot be read) is `current` and stays, as the switch itself leaves it. A
1888
+ plain check whose marketplace cannot be read reports `unknown`, with the reason in
1889
+ `message`. For OpenCode it compares the cached version with npm, so it reports
1890
+ `pending` when an update is due. A `failed` plugin makes `akm upgrade` exit `1` (not
1860
1891
  `--check`). On an up-to-date machine the text output prints nothing for
1861
1892
  plugins.
1862
1893
 
@@ -2164,17 +2195,56 @@ folder deeper down (`docs/rules/`) is not. A rule applies when its frontmatter `
2164
2195
  equals the value the project in force writes as `project` (its `write.metadata.project`,
2165
2196
  default its name) or it has none (shared); with no project, only shared rules apply. If the
2166
2197
  selection's own `project` filter is in force, that filter decides and the comparison is
2167
- skipped. Rules are ordinary search hits: nothing is added to a page for them. They follow
2168
- `--from`, `--filter`, `--since`/`--until`, disabled bundles and `--belief` like any asset. A
2169
- rule of another project is never returned while a project is selected, by any search or
2170
- curate, including `--type rule`. The AKM agent plugins load the applicable rules at session
2171
- start and after compaction; an agent without a plugin lists them with the command below.
2172
-
2173
- **Listing contract (for plugins):** `akm search "" --type rule --limit 200 --detail normal`
2174
- returns exactly the applicable rules (honouring `--project`, the working directory, `--from`
2175
- and the other selection), with `ref` and `description`; read each with `akm show <ref>`. A
2176
- result of exactly 200 means the list was cut. `akm search "rules/"` is a plain path
2177
- listing: it also returns `README` and scripts under `rules/` and stops at 20.
2198
+ skipped. In search and curate, rules are ordinary hits: nothing is added to a page for them,
2199
+ and they follow `--from`, `--filter`, `--since`/`--until`, disabled bundles and `--belief`
2200
+ like any asset. A rule of another project is never returned while a project is selected, by
2201
+ any search or curate, including `--type rule`.
2202
+
2203
+ A session loads its rules with [`akm rules`](#rules), not with search. The AKM agent plugins
2204
+ run it at session start and after compaction; an agent without a plugin runs the same command.
2205
+
2206
+ ### rules
2207
+
2208
+ Print the rules that apply here, in full: the project's rules first, then shared ones, each
2209
+ group by ref.
2210
+
2211
+ ```sh
2212
+ akm rules
2213
+ akm rules --project acme
2214
+ akm rules --project none --from team
2215
+ akm rules --filter team=platform --format text
2216
+ ```
2217
+
2218
+ | Flag | Default | Description |
2219
+ | --- | --- | --- |
2220
+ | `--project <name\|none>` | the project whose path contains the working directory | The project to use instead (`none`: no project); an unknown name is a usage error |
2221
+ | `--from <bundle>` | the project's `from` | Bundle name (repeatable), replacing the project's `from`. `local`, `registry` and `all` do not apply to rules: they are ignored with one warning and the default below is read. A disabled or unknown bundle is a usage error |
2222
+ | `--filter <key>=<value>` | the project's `filters` | Repeatable frontmatter filter with the matching of `akm search --filter`, replacing the project's `filters` |
2223
+
2224
+ **Which bundles supply rules.** A rule is an instruction the agent obeys, so only bundles you
2225
+ named supply them. With `--from`, those bundles; else the project's `from`; else, with a
2226
+ project, the default bundle and the project's `write.bundle`; with no project, the default
2227
+ bundle. A bundle installed from a registry or a git URL supplies rules only when it is the
2228
+ default bundle or you name it in `from`. A disabled bundle is never read.
2229
+
2230
+ **Which rules.** Files the index walker types as `rule` in those bundles (a Markdown file in
2231
+ the top-level `rules/` folder, `README.md` excepted), read from the files: no index is needed,
2232
+ a rule written a second ago applies, and a locked or rebuilding index changes nothing. A rule
2233
+ with `quality: proposed` is never returned. The project match is the one above and the
2234
+ filters match as in search. There is no query, limit, `--include` or `--prefer`, and nothing
2235
+ is cut.
2236
+
2237
+ **Output.** JSON: `{ project?, bundles, rules: [{ ref, description, project?, content }] }`.
2238
+ `project` is the project as applied (as in search), present only when one applies; `bundles`
2239
+ are the bundle ids read, in order; `ref` is the ref search prints, so `akm show <ref>` reads
2240
+ it; `project` on a rule is the project it names (absent when shared); `content` is the body
2241
+ without frontmatter. `text` and `md` print the project line, then each rule under its ref
2242
+ (`No rules apply here.` when none).
2243
+
2244
+ **Usage.** One `rules` usage event per call, never a `search` or `show` event, with the
2245
+ project in force, the bundles read, the refs returned and the total characters of their
2246
+ `content`. `akm metrics` reports rule loads, rules and characters per load, and loads per
2247
+ rule under usage. A call moves no search count, ranking or utility score.
2178
2248
 
2179
2249
  #### Usage list (`--by-usage`)
2180
2250
 
@@ -2184,7 +2254,7 @@ listing: it also returns `README` and scripts under `rules/` and stops at 20.
2184
2254
  most shown first. It applies the project's `from`, `filters` and your flags like any search, takes no
2185
2255
  query (one given is ignored with a warning) and no `--from registry|all` (warned; local is
2186
2256
  used), orders by use instead of `--prefer`, records no usage event, and leaves rules out
2187
- (they have their own listing). Assets that were never shown are not listed, so with no
2257
+ (`akm rules` lists them). Assets that were never shown are not listed, so with no
2188
2258
  history the list is empty. What counts: `akm show` events of `source: user` in the last 90
2189
2259
  days (the usage retention); only `akm show` counts, not nested command or persona reads. Search and
2190
2260
  curate results are impressions and do not count. Each `akm show` records the project in force
@@ -2198,10 +2268,11 @@ session-start hook, an automatic rule read) run with `AKM_EVENT_SOURCE` set to `
2198
2268
 
2199
2269
  **Plugin recipe.** With the project resolved: `akm doctor metrics assets --detail normal
2200
2270
  [--project <p>]`, run in the session directory. With no project resolved, read the default
2201
- bundle with no selection: `--project none --from <defaultBundle>` on both the rules listing
2202
- and `doctor metrics assets`, where `<defaultBundle>` is `akm config get defaultBundle`. If none is
2203
- configured there is no bundle to name (neither `--from <name>` nor `--from <path>` accepts the
2204
- primary stash), so pass `--project none` without `--from`; every enabled bundle is then read.
2271
+ bundle with no selection: `--project none --from <defaultBundle>`, where `<defaultBundle>` is
2272
+ `akm config get defaultBundle`. If none is configured there is no bundle to name (neither
2273
+ `--from <name>` nor `--from <path>` accepts the primary stash), so pass `--project none`
2274
+ without `--from`; every enabled bundle is then read. Rules come from `akm rules`, not from
2275
+ this list.
2205
2276
 
2206
2277
  ### remember
2207
2278
 
@@ -3314,7 +3385,7 @@ child's exact status when one exists.
3314
3385
 
3315
3386
  ### lint
3316
3387
 
3317
- Scan bundle markdown files for structural issues: unquoted colons, missing
3388
+ Scan the Markdown assets of a bundle for structural issues: unquoted colons, missing
3318
3389
  `updated` field, orphaned stubs, placeholder stubs, missing `name`/`type`,
3319
3390
  stale paths, and broken refs — in body text and in
3320
3391
  `refs`/`xrefs`/`supersededBy`/`contradictedBy` frontmatter. A belief edge
@@ -3327,6 +3398,40 @@ and compiles Markdown workflows; errors surface as
3327
3398
  `invalid-workflow-structure` findings (0.9.0: this is the only
3328
3399
  structural-validation surface now that `akm workflow validate` is gone).
3329
3400
 
3401
+ In an akm bundle the files are the ones the indexer would index and each file's type
3402
+ is the type the indexer gives it, so a file under a wiki folder, a loose folder or the
3403
+ bundle root is linted with its type's checks, not only the files under the type
3404
+ folders. The walk is the indexer's: dot-directories, `node_modules`, git-ignored files
3405
+ and a root `.scratch/` are not linted. Nothing under `env/` or `secrets/` is read. A file inside an LLM Wiki
3406
+ (a folder with `schema.md` and `pages/`, the llm-wiki adapter's own probe) is written by the wiki's own process, not
3407
+ authored as an akm asset, so `missing-updated` and `missing-name-or-type` do not apply to it; every other check does.
3408
+ Types that search leaves out by default stay out unless `--type` names them, and the
3409
+ bundle's `lint.skip` globs apply.
3410
+
3411
+ A bundle of another adapter is checked through that adapter's `validate`, and the
3412
+ checks every file gets (`unquoted-colon`, `missing-updated`, `stale-path`,
3413
+ `missing-ref`, `redacted-content`) are the same ones, with the same exemptions
3414
+ (skills, LLM Wikis, `lint.skip`), as in an akm bundle. An adapter can leave a rule out
3415
+ for its own files: `okf` and `website-snapshot` do not apply `missing-updated`. The
3416
+ checks of a type that has its own (a command's and an agent's `name` and `type`, a
3417
+ fact's `category`, a task's source, a memory stub, a workflow stub) are one table both
3418
+ routes read.
3419
+
3420
+ A ref an asset declares in frontmatter (`xrefs`, `supersededBy`, `contradictedBy`,
3421
+ `currentBeliefRefs`, `sources`, and `refs`) is checked whatever folder it points
3422
+ into, read as the index reads it: a wiki page's `raw/x.md` and `wiki:<name>/pages/x`
3423
+ are relative to its wiki. A word in prose is a ref only when it looks like one
3424
+ (`bundle//concept`), as before.
3425
+
3426
+ A link to a ref that `akm index` recorded as moved (see [index](#index)) is a
3427
+ `missing-ref` finding that carries `movedFrom` (the link as written) and `movedTo`
3428
+ (the ref the asset has now, as `bundle//conceptId`). `--fix` rewrites that link in
3429
+ frontmatter and prose, outside code fences, keeping its spelling (a bare link stays
3430
+ bare unless the asset moved to another bundle); a second run changes nothing. A
3431
+ `missing-ref` with no recorded move is reported as before and never rewritten. A qualified ref
3432
+ (`bundle//concept`) is looked up in the bundle it names, so one whose concept exists only in another bundle is a
3433
+ `missing-ref`; an unqualified ref is looked up in every bundle.
3434
+
3330
3435
  ```sh
3331
3436
  akm lint # Report findings; exits 0 regardless
3332
3437
  akm lint memories/note.md # Lint one file (a file in a bundle takes its type from its location)
@@ -3341,10 +3446,10 @@ akm lint --rule stale-path # List one rule's findings, grouped by asset
3341
3446
 
3342
3447
  | Argument or flag | Description |
3343
3448
  | --- | --- |
3344
- | `<file>` | Optional. Lint just this file with the rules the bundle lint applies to it, and return the same result with the counts for that file only (first in 0.10.261122). A file inside a bundle (a configured one, or the root given with `--dir`) gets its type from where it sits, as the bundle lint decides it. A file outside every bundle needs `--type` (`agents`, `commands`, `memories`, `skills`, `workflows`, `lessons`, `tasks`, `knowledge`, `facts`). Checks that need other files, such as broken refs and orphaned stubs, run only for a file inside a bundle; outside one only the file's own rules run. A `--type` that disagrees with the file's location, a missing path, a directory (use `--dir`) and `--prune-dangling-edges` are usage errors (exit 2). `--fix` changes only this file. |
3345
- | `--fix` (alias `--auto-fix`) | Apply auto-fixes in place. Refused with a usage error when the target bundle is configured `writable: false`. |
3449
+ | `<file>` | Optional. Lint just this file with the rules the bundle lint applies to it, and return the same result with the counts for that file only (first in 0.10.261122). A file inside a bundle (a configured one, or the root given with `--dir`) gets its type from where it sits, as the bundle lint decides it. A file outside every bundle needs `--type` (`agents`, `commands`, `memories`, `skills`, `workflows`, `lessons`, `tasks`, `knowledge`, `facts`, `instructions`, `rules`, `sessions`), as a type name (`rule`) or its folder name (`rules`). Checks that need other files, such as broken refs and orphaned stubs, run only for a file inside a bundle; outside one only the file's own rules run. A `--type` that disagrees with the file's location, a missing path, a directory (use `--dir`) and `--prune-dangling-edges` are usage errors (exit 2). `--fix` changes only this file. |
3450
+ | `--fix` (alias `--auto-fix`) | Apply auto-fixes in place, including the rewrite of links to moved refs. Refused with a usage error when the target bundle is configured `writable: false`. |
3346
3451
  | `--dir` | Override the bundle root directory (default: from config) |
3347
- | `--type` | Only lint assets of this type (e.g. `workflows`, `tasks`, `memories`). **akm bundles only** — every other adapter validates the whole bundle and warns on stderr that the flag had no effect. |
3452
+ | `--type` | Only lint assets of this type, by type name or folder name (e.g. `workflow` or `workflows`, `task`, `memory` or `memories`); a bundle lint leaves out the types search leaves out by default (`search.defaultExcludeTypes`, default `session`) unless `--type` names one. **akm bundles only** — every other adapter validates the whole bundle and warns on stderr that the flag had no effect. |
3348
3453
  | `--rule` | List this rule's findings grouped by asset: the asset ref and file, then each finding with its line, path, reason, nearest existing directory and line text. Combines with `--type`. A listing: it cannot combine with `--fix` or `--prune-dangling-edges`. An unknown rule name warns and shows every rule. |
3349
3454
  | `--fail-on-flagged` | Exit non-zero when `summary.flagged > 0`. Default: exit 0 regardless of findings. |
3350
3455
  | `--prune-dangling-edges` | Opt-in repair (#884): drop `supersededBy`/`contradictedBy` entries whose target has neither a file nor a prune tombstone. **Not** implied by `--fix` — it edits well-formed files to delete a belief-graph claim, so review a plain `akm lint` report first. Clears the same `writable: false` gate `--fix` does. |
@@ -3992,7 +4097,10 @@ for a drain) and the body has one `<proposal-id-8> <generator> <ref>` line per
3992
4097
  proposal. A retirement's archived copy and tombstone, and the source memory a
3993
4098
  consolidate promotion retires, are part of the same commit. The commit is local:
3994
4099
  `akm sync`, or the end-of-run sync of `akm improve`, pushes it. A commit that
3995
- fails warns and the accept stands.
4100
+ fails warns and the accept stands. The accept's result (each entry of a batch)
4101
+ carries `commit`: `{ "committed": true, "sha" }`, or `{ "committed": false,
4102
+ "reason", "error"? }` with `reason` `not-git`, `ignored` (every written path is
4103
+ ignored by `.gitignore`), `nothing-to-commit` or `failed` (with git's `error`).
3996
4104
 
3997
4105
  #### proposal reject
3998
4106
 
@@ -4481,7 +4589,7 @@ key; never sum snapshots or add detail counts to aggregate counts. Detailed rows
4481
4589
  are a subset of the aggregates. A report includes its own unfinished attempt.
4482
4590
 
4483
4591
  Collection is enabled at CLI entry, before the full configuration is read (only `usage.capture` is read, from the selected config file, and a missing or broken file leaves capture on), with no network
4484
- transmission and no sampling. `AKM_EVENT_SOURCE=user|agent|task|improve|audit` supplies
4592
+ transmission of its own and no sampling (the separate [daily usage report](data-and-telemetry.md#daily-usage-report) sends totals). `AKM_EVENT_SOURCE=user|agent|task|improve|audit` supplies
4485
4593
  known provenance and wins. Without it the source is `agent` when an agent harness
4486
4594
  is detected from the environment (the way usage events detect it), else `unknown`;
4487
4595
  nothing is inferred from a terminal. When a harness is detected, rows and aggregates
@@ -902,12 +902,13 @@ the key is ignored, and enables nothing; `akm migrate apply` drops it.
902
902
 
903
903
  ## Usage
904
904
 
905
- `usage` configures the local-only CLI usage counts (see
905
+ `usage` configures the local-only CLI usage counts and the daily usage report (see
906
906
  [Data and Telemetry](data-and-telemetry.md#cli-usage-counts)):
907
907
 
908
908
  | Key | Purpose |
909
909
  | --- | --- |
910
910
  | `usage.capture` | Whether akm records counts of its own commands in `metrics.db`. **Defaults to `true`**; `false` turns the recording off. Read from the config file itself (the one `--config` or `AKM_CONFIG_FILE` selects) before the rest of the config loads, so a missing or broken file leaves it on. `--read-only` records nothing either way. |
911
+ | `usage.report` | Whether akm sends its [daily usage report](data-and-telemetry.md#daily-usage-report) (the CLI's and AKM Desktop's). **Defaults to `true`**; `false` sends nothing. Read from the effective config, so `false` in a config you `extends` turns it off unless a nearer layer sets it to `true`. A config that cannot be loaded sends nothing. The CLI also sends nothing under `--read-only` or when `usage.capture` is `false`. |
911
912
 
912
913
  ## Bundles and write target
913
914
 
@@ -1,10 +1,11 @@
1
1
  # Data and Telemetry
2
2
 
3
- akm keeps your data on your machine. It sends no analytics or crash reports.
4
- It records [local-only counts of its own commands](#cli-usage-counts), which
5
- never leave your machine. It makes network requests only to the endpoints you configure or the commands
6
- you run, listed below. This page covers what akm sends, and what it stores and
7
- where.
3
+ akm keeps your data on your machine. It sends no crash reports. It records
4
+ [local-only counts of its own commands](#cli-usage-counts) and, at most once a
5
+ day per surface, sends an [anonymous usage report](#daily-usage-report) built
6
+ from them. Apart from that report it makes network requests only to the
7
+ endpoints you configure or the commands you run, listed below. This page covers
8
+ what akm sends, and what it stores and where.
8
9
 
9
10
  ## Network destinations
10
11
 
@@ -43,8 +44,10 @@ where.
43
44
  - **`akm doctor`**, unless you pass `--no-probe`, sends a reachability probe to
44
45
  each connection's endpoint, runs each harness's `--version`, calls
45
46
  `api.github.com` to compare your version with the latest release, and runs
46
- `git ls-remote --symref` against the remote of an installed Claude plugin
47
- marketplace clone.
47
+ a blobless, no-checkout `git clone` of the channel's branch of the
48
+ Claude and Codex plugin marketplace source the harness registered, to read the
49
+ catalog and plugin manifest (`akm upgrade --check` makes the same read); a
50
+ marketplace pinned to a tag is not read.
48
51
  - **`akm sync`** and the syncs `akm improve` runs before and after a run fetch
49
52
  from and push bundle content to the git remote you configured.
50
53
  - **`akm improve` dead-link checks** send `HEAD` requests to the URLs found in
@@ -147,7 +150,8 @@ regenerable. akm also writes into it:
147
150
  and a small metadata payload; search events include the query text and the
148
151
  refs returned. `akm env run`, a workflow unit's `env:` binding and
149
152
  `akm secret run` record the names of the keys injected, not their values.
150
- - **Usage records**: queries, search impressions, show/curate engagement and
153
+ - **Usage records**: queries, search impressions, show/curate engagement, rule loads
154
+ (`akm rules`: the refs and characters loaded) and
151
155
  feedback. They feed utility scores and `akm doctor metrics`, and the feedback recorded
152
156
  as the user adjusts search ranking. Each record is stamped with its source
153
157
  (`user`, `improve`, `task`, `audit` or `unknown`); only `user` records count.
@@ -201,8 +205,9 @@ are purged on `akm index`. Read these with `akm doctor log`, `akm doctor metrics
201
205
 
202
206
  ## CLI usage counts
203
207
 
204
- akm records how its own commands are used, on your machine only. Nothing is
205
- sent anywhere, and it is outside learning, feedback and ranking.
208
+ akm records how its own commands are used, on your machine. The counts are
209
+ outside learning, feedback and ranking; the only thing sent from them is the
210
+ [daily usage report](#daily-usage-report), as totals.
206
211
 
207
212
  - **Where:** the `cli_usage_*` tables of `metrics.db` in the data directory.
208
213
  - **What is recorded** for every command, including `--help`, `--version` and
@@ -224,6 +229,40 @@ sent anywhere, and it is outside learning, feedback and ranking.
224
229
  - It never changes a command's output or exit code: an unwritable, locked or
225
230
  corrupt `metrics.db` is skipped silently.
226
231
 
232
+ ## Daily usage report
233
+
234
+ On by default. akm sends one event a day per surface, the CLI and AKM Desktop,
235
+ to a self-hosted [Aptabase](https://aptabase.com) at `https://reporting.fwdslsh.dev`.
236
+ It is sent after a command finishes (at most one command a day pays a request, with a
237
+ 1.5 second limit) or, for Desktop, in the background when its server starts. A failed send
238
+ is not retried that day, and nothing is ever printed or changed in a command's result.
239
+ A fresh data directory sends nothing until its next UTC day.
240
+
241
+ - **CLI event (`cli_daily`):** `period_days` (complete UTC days since the last
242
+ report, up to yesterday; `0` for the first report), `commands`, `failures`,
243
+ `src_user`, `src_agent`, `src_task`, `src_improve` (commands by who ran them),
244
+ and `cmd_<command>` (the number of runs of each top-level command, only those
245
+ run). It is built from the counts above, so it has no argument values.
246
+ - **Desktop event (`desktop_daily`):** the library sizes below.
247
+ - **Library sizes, in both:** `bundles` (enabled bundles in the config), `assets`
248
+ (indexed assets), `assets_<type>` for each of akm's own asset types (skill,
249
+ command, and so on) and `assets_other` for every other type, which a bundle or
250
+ you named, so its name is never sent. They are left out when there is no
251
+ readable index; the report never builds or changes the index.
252
+ - **System fields, in both:** `osName` (Linux, macOS or Windows), `osVersion`,
253
+ `locale`, `engineName` and `engineVersion` (`bun` or `node`), `appVersion`
254
+ (the akm version), `sdkVersion` (`akm@<version>`), `isDebug: false`, a random
255
+ per-event session id and the time.
256
+ - **Never sent:** queries, refs, paths, bundle names, argument values, secrets,
257
+ the random instance id, or any asset content.
258
+ - **What the server keeps:** Aptabase keeps the event and derives country, region
259
+ and city from the request's IP address; it does not store the IP address.
260
+ - **Turning it off:** `akm config set usage.report false` (the config key
261
+ `usage.report`), or the **Usage reports** switch in AKM Desktop's settings. The switch follows
262
+ `extends`: `false` in a base config turns it off unless a nearer layer sets it
263
+ to `true`, and a config that cannot be loaded sends nothing. `--read-only` and `usage.capture: false` also send nothing from
264
+ the CLI. Runs in CI (the `CI` variable) or under `bun test` never send.
265
+
227
266
  ## Inspect and clear
228
267
 
229
268
  ```sh