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
package/docs/reference/cli.md
CHANGED
|
@@ -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`,
|
|
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
|
-
|
|
641
|
-
|
|
642
|
-
|
|
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
|
|
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`
|
|
1856
|
-
Claude Code
|
|
1857
|
-
|
|
1858
|
-
|
|
1859
|
-
|
|
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.
|
|
2168
|
-
`--from`, `--filter`, `--since`/`--until`, disabled bundles and `--belief`
|
|
2169
|
-
rule of another project is never returned while a project is selected, by
|
|
2170
|
-
curate, including `--type rule`.
|
|
2171
|
-
|
|
2172
|
-
|
|
2173
|
-
|
|
2174
|
-
|
|
2175
|
-
|
|
2176
|
-
|
|
2177
|
-
|
|
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
|
-
(
|
|
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
|
|
2202
|
-
|
|
2203
|
-
|
|
2204
|
-
|
|
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
|
|
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`, `
|
|
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
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
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
|
-
|
|
47
|
-
marketplace
|
|
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
|
|
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
|
|
205
|
-
|
|
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
|