akm-cli 0.10.261129 → 0.10.261130-beta.1
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 +8 -0
- package/STABILITY.md +1 -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.js +3 -1
- package/dist/commands/health/egress.js +1 -2
- package/dist/commands/metrics/collect.js +25 -2
- package/dist/commands/metrics/report-view.js +11 -2
- 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/indexer/search/db-search.js +1 -1
- package/dist/integrations/session-logs/pre-filter.js +1 -0
- 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 +26 -2
- package/dist/scripts/akm-migrate.js +26 -2
- package/dist/workspace/metrics.js +1 -1
- package/docs/architecture/internals/storage-locations.md +3 -3
- package/docs/guides/author-bundles.md +13 -12
- package/docs/reference/cli.md +58 -18
- package/docs/reference/data-and-telemetry.md +2 -1
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -6,6 +6,14 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
|
|
|
6
6
|
|
|
7
7
|
## [Unreleased]
|
|
8
8
|
|
|
9
|
+
### Added
|
|
10
|
+
|
|
11
|
+
- `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.
|
|
12
|
+
|
|
13
|
+
### Changed
|
|
14
|
+
|
|
15
|
+
- 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.
|
|
16
|
+
|
|
9
17
|
## [0.10.261129] - 2026-11-16
|
|
10
18
|
|
|
11
19
|
### Added
|
package/STABILITY.md
CHANGED
|
@@ -42,6 +42,7 @@ check the [migration guide](docs/migration/v0.10-to-v0.11.md) for availability.
|
|
|
42
42
|
| `akm search` | Stable | `--include-proposed` and `--include-sessions` are Deprecated, removed in 0.11: use `--include quality=proposed` and `--include type=<excluded-type>`; `type=` also takes a custom type listed in `search.defaultExcludeTypes` (read from the config file only, not from `extends` layers). `--by-usage` is Deprecated, removed in 0.11: use `akm doctor metrics assets` (first in 0.10.261120; same filters and result fields). |
|
|
43
43
|
| `akm curate` | Stable | `--max-tokens` aliases the existing `--pack` budget and output. Both are opt-in; the unbudgeted default stays unchanged. Conflicting explicit budgets are rejected. `--pack` and the unpacked default are Deprecated, removed in 0.11 when curate returns bounded packed context by default. |
|
|
44
44
|
| `akm show` | Stable | `--outline` and `--lead` are additive aliases. `--max-tokens` bounds body fields (after any frontmatter) on whole/exact/lead reads and reports estimation/truncation; legacy unbudgeted output is unchanged. `--outline` with `--lead` or a budget, `--detail brief` with `--lead`, and `--detail brief` with `--max-tokens` and no lead context are usage errors; `--detail brief --context lead [--max-chars|--max-tokens]` keeps working as in 0.10.261118. `--context`, `--max-chars` and `--detail` are Deprecated, removed in 0.11 (exact reads become the default). |
|
|
45
|
+
| `akm rules` | Experimental | First in 0.10.261130. Prints the rules that apply here, in full, read from the files of the project's bundles (`--from`, else the project's `from`, else the default bundle and the project's write bundle); `--project`, `--from` and `--filter` as in search. Records one `rules` usage event per call. The flags, the `{ project?, bundles, rules }` JSON shape and the `rules` metrics section may change in any release. |
|
|
45
46
|
| `akm remember` | Stable | `--source`, `--description`, and `--expires` work independently of tags. Capture and enrichment processes are unchanged. `--auto`, `--enrich` and `--show-similar` are Deprecated, removed in 0.11 with no replacement flag; they print a notice since 0.10.261120. |
|
|
46
47
|
| `akm import` | Stable | Additive `--asset-ref` and `--type task` modes, first in 0.10.261119; existing document inputs unchanged. `--type task` writes `scheduler.enabled` deliberately, to keep a stale scheduler row from activating the new task. |
|
|
47
48
|
| `akm sync` | Stable | |
|
|
@@ -15,7 +15,7 @@ akm search "<query>" --limit 10 # Limit results
|
|
|
15
15
|
akm search "<query>" --detail full # Include scores, paths, timing
|
|
16
16
|
akm search "memories/projectA/" # Enumerate a subtree (conceptId prefix; trailing slash required)
|
|
17
17
|
akm search "knowledge/" # List every knowledge item
|
|
18
|
-
akm
|
|
18
|
+
akm rules # The rules that apply here, in full (project's first, then shared)
|
|
19
19
|
akm doctor metrics assets --detail normal # Assets shown most in the project
|
|
20
20
|
akm search "team-catalog//" # List every item in one bundle
|
|
21
21
|
```
|
|
@@ -10,6 +10,7 @@ akm curate "<task>" --max-tokens 4000 # Same hits' content as one bundle of at m
|
|
|
10
10
|
akm search "<query>" # Local sources (or the project's `from`); --type <t> filters
|
|
11
11
|
akm search "<query>" --from all # Also search registries
|
|
12
12
|
akm show <ref> # Read an asset
|
|
13
|
+
akm rules # The rules that apply here, in full
|
|
13
14
|
akm run <ref> # Run an agent, command, task or workflow asset
|
|
14
15
|
akm doctor # Health checks; `doctor metrics|info|log` report
|
|
15
16
|
akm help <command> # A command's options
|
|
@@ -13,7 +13,7 @@ updated: 2026-11-08
|
|
|
13
13
|
|
|
14
14
|
# Rule authoring conventions
|
|
15
15
|
|
|
16
|
-
A rule is a short bullet list of things an agent must do for a project. The AKM agent plugins load the applicable rules at session start and after compaction, so every line costs context on every task.
|
|
16
|
+
A rule is a short bullet list of things an agent must do for a project. The AKM agent plugins load the applicable rules (`akm rules`) at session start and after compaction, so every line costs context on every task. Rules load only from the default bundle, the project's write bundle or the bundles in its `from`, so put a team's shared rules in a bundle the project lists.
|
|
17
17
|
|
|
18
18
|
- One rule per bullet, imperative, checkable ("Run the focused tests for changed behavior"). No background or rationale; put that in knowledge.
|
|
19
19
|
- Keep a file to a handful of bullets and one topic. Split by topic (`rules/acme/testing.md`), not by length.
|
package/dist/cli.js
CHANGED
|
@@ -96,6 +96,7 @@ import { modelsCommand } from "./commands/models-cli.js";
|
|
|
96
96
|
import { doctorLogCommand, logCommand } from "./commands/observability-cli.js";
|
|
97
97
|
import { proposalCommand } from "./commands/proposal/proposal-cli.js";
|
|
98
98
|
import { rememberCommand } from "./commands/read/remember-cli.js";
|
|
99
|
+
import { rulesCommand } from "./commands/read/rules.js";
|
|
99
100
|
import { curateCommand, searchCommand, showCommand } from "./commands/read/search-cli.js";
|
|
100
101
|
import { registryCommand } from "./commands/registry-cli.js";
|
|
101
102
|
import { runAssetCommand } from "./commands/run-cli.js";
|
|
@@ -604,6 +605,7 @@ const commands = {
|
|
|
604
605
|
search: searchCommand,
|
|
605
606
|
curate: curateCommand,
|
|
606
607
|
show: showCommand,
|
|
608
|
+
rules: rulesCommand,
|
|
607
609
|
run: runAssetCommand,
|
|
608
610
|
workflow: workflowCommand,
|
|
609
611
|
remember: rememberCommand,
|
|
@@ -926,7 +928,7 @@ function buildUsageParentForPath(path) {
|
|
|
926
928
|
const HELP_SECTIONS = [
|
|
927
929
|
{
|
|
928
930
|
title: "AGENT LOOP",
|
|
929
|
-
commands: ["curate", "search", "show", "feedback", "remember"],
|
|
931
|
+
commands: ["curate", "search", "show", "rules", "feedback", "remember"],
|
|
930
932
|
},
|
|
931
933
|
{
|
|
932
934
|
title: "ASSETS",
|
|
@@ -5,8 +5,7 @@
|
|
|
5
5
|
* `egress-endpoints` advisory for `akm health` (meta-review 08, surfaces 3/9):
|
|
6
6
|
* the remote-destination list, for eyeball diff. A pure projection over the
|
|
7
7
|
* effective config (no process.env reads); silent when nothing remote is
|
|
8
|
-
* configured, matching the `
|
|
9
|
-
* advisories' pattern.
|
|
8
|
+
* configured, matching the `binary-config-skew` advisory's pattern.
|
|
10
9
|
*/
|
|
11
10
|
import { redactCredentialPatterns } from "../../core/redaction.js";
|
|
12
11
|
import { formatRegistryUrl } from "../../core/registry-url.js";
|
|
@@ -48,7 +48,7 @@ export const DEFAULT_EVENT_RETENTION_DAYS = 90;
|
|
|
48
48
|
*/
|
|
49
49
|
export function retentionNotes(args) {
|
|
50
50
|
const stores = [
|
|
51
|
-
{ store: "usage_events (search, show, curate and
|
|
51
|
+
{ store: "usage_events (search, show, curate, feedback and rules rows)", days: args.usageRetentionDays },
|
|
52
52
|
{ store: "events (selects, LLM calls and index runs)", days: args.eventRetentionDays },
|
|
53
53
|
];
|
|
54
54
|
const notes = [];
|
|
@@ -95,6 +95,10 @@ export function toUsageRow(row) {
|
|
|
95
95
|
const tags = Array.isArray(metadata.tags)
|
|
96
96
|
? metadata.tags.filter((tag) => typeof tag === "string")
|
|
97
97
|
: undefined;
|
|
98
|
+
const refs = Array.isArray(metadata.refs)
|
|
99
|
+
? metadata.refs.filter((ref) => typeof ref === "string")
|
|
100
|
+
: undefined;
|
|
101
|
+
const chars = finiteNumber(metadata.chars);
|
|
98
102
|
const agent = metadata.agent;
|
|
99
103
|
const harness = typeof agent?.harness === "string" && agent.harness ? agent.harness : undefined;
|
|
100
104
|
const session = typeof agent?.session === "string" && agent.session ? agent.session : undefined;
|
|
@@ -110,6 +114,7 @@ export function toUsageRow(row) {
|
|
|
110
114
|
...(totalMs !== undefined ? { totalMs } : {}),
|
|
111
115
|
...(reason !== undefined ? { reason } : {}),
|
|
112
116
|
...(tags && tags.length > 0 ? { tags } : {}),
|
|
117
|
+
...(row.event_type === "rules" ? { rules: { refs: refs ?? [], chars: chars ?? 0 } } : {}),
|
|
113
118
|
...(harness ? { agent: { harness, ...(session ? { session } : {}) } } : {}),
|
|
114
119
|
};
|
|
115
120
|
}
|
|
@@ -193,7 +198,7 @@ function buildUsage(input, rows) {
|
|
|
193
198
|
const days = new Map();
|
|
194
199
|
const bump = (at, field) => {
|
|
195
200
|
const day = at.slice(0, 10);
|
|
196
|
-
const entry = days.get(day) ?? { day, search: 0, show: 0, curate: 0, feedback: 0 };
|
|
201
|
+
const entry = days.get(day) ?? { day, search: 0, show: 0, curate: 0, feedback: 0, rules: 0 };
|
|
197
202
|
entry[field] += 1;
|
|
198
203
|
days.set(day, entry);
|
|
199
204
|
};
|
|
@@ -219,6 +224,7 @@ function buildUsage(input, rows) {
|
|
|
219
224
|
let zeroResultSearches = 0;
|
|
220
225
|
let shows = 0;
|
|
221
226
|
let curates = 0;
|
|
227
|
+
const ruleLoads = { loads: 0, rules: 0, chars: 0, byRule: new Map() };
|
|
222
228
|
for (const row of rows) {
|
|
223
229
|
bySource[row.source] = (bySource[row.source] ?? 0) + 1;
|
|
224
230
|
if (row.eventType === "search") {
|
|
@@ -270,6 +276,14 @@ function buildUsage(input, rows) {
|
|
|
270
276
|
touch(entry, row.at);
|
|
271
277
|
}
|
|
272
278
|
}
|
|
279
|
+
else if (row.eventType === "rules") {
|
|
280
|
+
ruleLoads.loads += 1;
|
|
281
|
+
bump(row.at, "rules");
|
|
282
|
+
for (const ref of row.rules?.refs ?? [])
|
|
283
|
+
ruleLoads.byRule.set(ref, (ruleLoads.byRule.get(ref) ?? 0) + 1);
|
|
284
|
+
ruleLoads.rules += row.rules?.refs.length ?? 0;
|
|
285
|
+
ruleLoads.chars += row.rules?.chars ?? 0;
|
|
286
|
+
}
|
|
273
287
|
else if (row.eventType === "feedback") {
|
|
274
288
|
// Signed rows only, so the daily series and the totals count the same rows.
|
|
275
289
|
if (row.signal === undefined)
|
|
@@ -305,6 +319,15 @@ function buildUsage(input, rows) {
|
|
|
305
319
|
distinctQueries: queries.size,
|
|
306
320
|
},
|
|
307
321
|
selectsPerSearch: searchesWithHits > 0 ? input.selects.length / searchesWithHits : null,
|
|
322
|
+
rules: {
|
|
323
|
+
loads: ruleLoads.loads,
|
|
324
|
+
meanRules: mean(ruleLoads.loads > 0 ? [ruleLoads.rules / ruleLoads.loads] : []),
|
|
325
|
+
meanChars: mean(ruleLoads.loads > 0 ? [ruleLoads.chars / ruleLoads.loads] : []),
|
|
326
|
+
byRule: [...ruleLoads.byRule.entries()]
|
|
327
|
+
.map(([ref, loads]) => ({ ref, loads }))
|
|
328
|
+
.sort((a, b) => b.loads - a.loads || a.ref.localeCompare(b.ref))
|
|
329
|
+
.slice(0, input.top),
|
|
330
|
+
},
|
|
308
331
|
searchMedianMs: median(searchMs),
|
|
309
332
|
daily: [...days.values()].sort((a, b) => a.day.localeCompare(b.day)),
|
|
310
333
|
topAssets: [...assets.values()]
|
|
@@ -54,6 +54,9 @@ export function buildMetricsView(r, detail) {
|
|
|
54
54
|
["shows", int(usage.totals.shows)],
|
|
55
55
|
["curates", int(usage.totals.curates)],
|
|
56
56
|
["selects", int(usage.totals.selects)],
|
|
57
|
+
["rule loads", int(usage.rules.loads)],
|
|
58
|
+
["rules per load", fixed(usage.rules.meanRules, 1)],
|
|
59
|
+
["characters per load", fixed(usage.rules.meanChars, 0)],
|
|
57
60
|
["searches with hits", int(usage.totals.searchesWithHits)],
|
|
58
61
|
["selects per search with hits", fixed(usage.selectsPerSearch, 2)],
|
|
59
62
|
[
|
|
@@ -79,6 +82,12 @@ export function buildMetricsView(r, detail) {
|
|
|
79
82
|
dash(a.lastUsedAt),
|
|
80
83
|
]),
|
|
81
84
|
},
|
|
85
|
+
{
|
|
86
|
+
title: "Rule loads",
|
|
87
|
+
headers: ["ref", "loads"],
|
|
88
|
+
rows: cut(usage.rules.byRule).map((rule) => [rule.ref, int(rule.loads)]),
|
|
89
|
+
hideWhenEmpty: true,
|
|
90
|
+
},
|
|
82
91
|
{
|
|
83
92
|
title: "Top queries",
|
|
84
93
|
headers: ["query", "count", "avg results", "last"],
|
|
@@ -91,10 +100,10 @@ export function buildMetricsView(r, detail) {
|
|
|
91
100
|
},
|
|
92
101
|
{
|
|
93
102
|
title: "Daily",
|
|
94
|
-
headers: ["day", "search", "show", "curate", "feedback"],
|
|
103
|
+
headers: ["day", "search", "show", "curate", "feedback", "rules"],
|
|
95
104
|
rows: brief
|
|
96
105
|
? []
|
|
97
|
-
: usage.daily.map((d) => [d.day, int(d.search), int(d.show), int(d.curate), int(d.feedback)]),
|
|
106
|
+
: usage.daily.map((d) => [d.day, int(d.search), int(d.show), int(d.curate), int(d.feedback), int(d.rules)]),
|
|
98
107
|
hideWhenEmpty: true,
|
|
99
108
|
},
|
|
100
109
|
],
|
|
@@ -0,0 +1,142 @@
|
|
|
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
|
+
* `akm rules`: the rules that apply here, in full. Read from the files of the
|
|
6
|
+
* bundles the selection names (never the index), recognized by the same adapter
|
|
7
|
+
* and filtered by the same project and scope functions search uses, so it works
|
|
8
|
+
* with no index and a new rule applies at once. Records one `rules` usage event.
|
|
9
|
+
*/
|
|
10
|
+
import path from "node:path";
|
|
11
|
+
import { getStringArg, PROJECT_ARG } from "../../cli/parse-args.js";
|
|
12
|
+
import { defineJsonCommand, output, parseAllFlagValues } from "../../cli/shared.js";
|
|
13
|
+
import { akmAdapter } from "../../core/adapter/adapters/akm-adapter.js";
|
|
14
|
+
import { parseFrontmatter } from "../../core/asset/frontmatter.js";
|
|
15
|
+
import { displayRefForConceptId } from "../../core/asset/resolve-ref.js";
|
|
16
|
+
import { compareCodePoints } from "../../core/common.js";
|
|
17
|
+
import { loadConfig } from "../../core/config/config.js";
|
|
18
|
+
import { resolveProject } from "../../core/projects.js";
|
|
19
|
+
import { withStateDbTelemetry } from "../../core/state-db.js";
|
|
20
|
+
import { warnOnce } from "../../core/warn.js";
|
|
21
|
+
import { deriveInstallations } from "../../indexer/installations.js";
|
|
22
|
+
import { isProposedQuality, scopeMatchesFilters } from "../../indexer/passes/metadata.js";
|
|
23
|
+
import { resolveReadSources } from "../../indexer/read-preflight.js";
|
|
24
|
+
import { drainDirDocuments } from "../../indexer/scan/drain-dir.js";
|
|
25
|
+
import { appliesUnder } from "../../indexer/search/db-search.js";
|
|
26
|
+
import { insertUsageEvent, resolveUsageEventSource } from "../../indexer/usage/usage-events.js";
|
|
27
|
+
import { buildFileContext } from "../../indexer/walk/file-context.js";
|
|
28
|
+
import { walkedFiles, walkStash } from "../../indexer/walk/walker.js";
|
|
29
|
+
import { registerMdRenderer } from "../../output/render-registry.js";
|
|
30
|
+
import { formatRulesText } from "../../output/text/rules.js";
|
|
31
|
+
import { TELEMETRY_BUSY_TIMEOUT_MS } from "../../storage/repositories/index-db.js";
|
|
32
|
+
import { assertNamedSourceExists, narrowSourcesToName, normalizeScopeFilters, parseScopeFilterFlags, parseSearchSource, } from "./search.js";
|
|
33
|
+
import { fromValues, projectContext, scopeFilterArg, stampedProject, withProjectDefaults } from "./search-cli.js";
|
|
34
|
+
/** `--from` values that select a search scope, not a bundle: they do not apply to rules. */
|
|
35
|
+
const SCOPE_KEYWORDS = ["local", "registry", "all"];
|
|
36
|
+
/** The bundle names in a `--from` value; scope keywords are ignored with one warning. `undefined`: none left. */
|
|
37
|
+
function bundleNames(from) {
|
|
38
|
+
if (from === undefined)
|
|
39
|
+
return undefined;
|
|
40
|
+
const parsed = parseSearchSource(from);
|
|
41
|
+
const given = Array.isArray(parsed) ? parsed : [parsed];
|
|
42
|
+
const names = given.filter((name) => !SCOPE_KEYWORDS.includes(name));
|
|
43
|
+
if (names.length < given.length) {
|
|
44
|
+
warnOnce("rules:from-keyword", "`akm rules` reads named bundles: --from local, registry and all are ignored.");
|
|
45
|
+
}
|
|
46
|
+
return names.length > 0 ? names : undefined;
|
|
47
|
+
}
|
|
48
|
+
export function akmRules(input) {
|
|
49
|
+
const config = loadConfig();
|
|
50
|
+
const project = resolveProject(config, { project: input.project, cwd: input.cwd });
|
|
51
|
+
const { filters, view } = withProjectDefaults(project, {
|
|
52
|
+
source: input.from,
|
|
53
|
+
filters: parseScopeFilterFlags(input.filters ?? [], "--filter"),
|
|
54
|
+
});
|
|
55
|
+
const names = bundleNames(input.from) ?? bundleNames(project?.from);
|
|
56
|
+
for (const name of names ?? [])
|
|
57
|
+
assertNamedSourceExists(config, name);
|
|
58
|
+
const sources = resolveReadSources(undefined, config).sources;
|
|
59
|
+
const wanted = names
|
|
60
|
+
? names.flatMap((name) => narrowSourcesToName(sources, [name]))
|
|
61
|
+
: [
|
|
62
|
+
...sources.filter((source) => source.isDefault),
|
|
63
|
+
...(project?.write.bundle ? narrowSourcesToName(sources, [project.write.bundle]) : []),
|
|
64
|
+
];
|
|
65
|
+
const installations = deriveInstallations(sources);
|
|
66
|
+
const scope = normalizeScopeFilters(filters);
|
|
67
|
+
const context = projectContext(project, filters);
|
|
68
|
+
const bundles = [];
|
|
69
|
+
const found = [];
|
|
70
|
+
for (const source of new Set(wanted)) {
|
|
71
|
+
const component = installations[sources.indexOf(source)]?.components[0];
|
|
72
|
+
if (!component || component.adapter !== "akm" || source.unresolved)
|
|
73
|
+
continue;
|
|
74
|
+
bundles.push(component.id);
|
|
75
|
+
const files = walkedFiles(component.root, walkStash(path.join(component.root, "rules"), "rule").flatMap((group) => group.files));
|
|
76
|
+
for (const file of files) {
|
|
77
|
+
const ctx = buildFileContext(component.root, file);
|
|
78
|
+
const drained = drainDirDocuments(akmAdapter, component, [ctx]);
|
|
79
|
+
const entry = drained.entries[0];
|
|
80
|
+
const conceptId = drained.conceptIdByFile.get(ctx.absPath);
|
|
81
|
+
if (entry?.type !== "rule" || conceptId === undefined)
|
|
82
|
+
continue;
|
|
83
|
+
if (isProposedQuality(entry.quality) || !appliesUnder(entry, context))
|
|
84
|
+
continue;
|
|
85
|
+
if (scope && !scopeMatchesFilters(entry, scope))
|
|
86
|
+
continue;
|
|
87
|
+
const named = entry.frontmatter?.project;
|
|
88
|
+
found.push({
|
|
89
|
+
ref: displayRefForConceptId(conceptId, component.id, config.defaultBundle ?? (source.isDefault ? component.id : undefined)),
|
|
90
|
+
durableRef: `${component.id}//${conceptId}`,
|
|
91
|
+
...(entry.description ? { description: entry.description } : {}),
|
|
92
|
+
...(named?.length ? { project: named.length === 1 ? named[0] : named } : {}),
|
|
93
|
+
content: parseFrontmatter(ctx.content()).content.trim(),
|
|
94
|
+
shared: !named?.length,
|
|
95
|
+
});
|
|
96
|
+
}
|
|
97
|
+
}
|
|
98
|
+
found.sort((a, b) => Number(a.shared) - Number(b.shared) || compareCodePoints(a.ref, b.ref));
|
|
99
|
+
const rules = found.map(({ shared: _shared, durableRef: _durableRef, ...rule }) => rule);
|
|
100
|
+
recordRulesUsage({
|
|
101
|
+
project: stampedProject(project),
|
|
102
|
+
bundles,
|
|
103
|
+
refs: found.map((rule) => rule.durableRef),
|
|
104
|
+
chars: found.reduce((sum, rule) => sum + rule.content.length, 0),
|
|
105
|
+
eventSource: input.eventSource ?? resolveUsageEventSource(),
|
|
106
|
+
});
|
|
107
|
+
return { schemaVersion: 1, ...(view ? { project: view } : {}), bundles, rules };
|
|
108
|
+
}
|
|
109
|
+
/** One `rules` usage event per call: what was loaded, not a search or a show. */
|
|
110
|
+
function recordRulesUsage(load) {
|
|
111
|
+
const { eventSource, ...metadata } = load;
|
|
112
|
+
try {
|
|
113
|
+
withStateDbTelemetry((stateDb) => {
|
|
114
|
+
insertUsageEvent(stateDb, { event_type: "rules", metadata: JSON.stringify(metadata), source: eventSource });
|
|
115
|
+
}, TELEMETRY_BUSY_TIMEOUT_MS);
|
|
116
|
+
}
|
|
117
|
+
catch {
|
|
118
|
+
/* telemetry is fire-and-forget */
|
|
119
|
+
}
|
|
120
|
+
}
|
|
121
|
+
export const rulesCommand = defineJsonCommand({
|
|
122
|
+
meta: {
|
|
123
|
+
name: "rules",
|
|
124
|
+
description: "The rules that apply here, in full: the project's and the shared ones, read from the files of the project's bundles (its `from`, else the default bundle and its write bundle)",
|
|
125
|
+
},
|
|
126
|
+
args: {
|
|
127
|
+
from: {
|
|
128
|
+
type: "string",
|
|
129
|
+
description: "Bundle name (repeatable); default: the project's from, else the default bundle",
|
|
130
|
+
},
|
|
131
|
+
filter: scopeFilterArg,
|
|
132
|
+
...PROJECT_ARG,
|
|
133
|
+
},
|
|
134
|
+
async run({ args }) {
|
|
135
|
+
output("rules", akmRules({
|
|
136
|
+
from: fromValues(args.from),
|
|
137
|
+
filters: parseAllFlagValues("--filter"),
|
|
138
|
+
project: getStringArg(args, "project"),
|
|
139
|
+
}));
|
|
140
|
+
},
|
|
141
|
+
});
|
|
142
|
+
registerMdRenderer("rules", (result) => formatRulesText(result));
|
|
@@ -28,7 +28,7 @@ import { deliverRendered } from "../../output/stdout.js";
|
|
|
28
28
|
import { akmCurate, packCuratedHits } from "./curate.js";
|
|
29
29
|
import { akmSearch, parseBeliefFilterMode, parseScopeFilterFlags, parseSearchSource } from "./search.js";
|
|
30
30
|
import { akmShowUnified } from "./show.js";
|
|
31
|
-
const scopeFilterArg = {
|
|
31
|
+
export const scopeFilterArg = {
|
|
32
32
|
type: "string",
|
|
33
33
|
description: "Frontmatter key=value filter (repeatable); a repeated key matches any value, different keys must all match",
|
|
34
34
|
};
|
|
@@ -151,12 +151,12 @@ export const doctorMetricsAssetsCommand = defineJsonCommand({
|
|
|
151
151
|
},
|
|
152
152
|
});
|
|
153
153
|
/** The value a project's writes carry as `project`: what its rules and usage are matched against. */
|
|
154
|
-
function stampedProject(project) {
|
|
154
|
+
export function stampedProject(project) {
|
|
155
155
|
const value = project?.write.metadata.project;
|
|
156
156
|
return value === undefined ? undefined : String(value);
|
|
157
157
|
}
|
|
158
158
|
/** The project a search or curate runs under; a `project` filter in force has already decided eligibility. */
|
|
159
|
-
function projectContext(project, filters) {
|
|
159
|
+
export function projectContext(project, filters) {
|
|
160
160
|
return {
|
|
161
161
|
name: stampedProject(project),
|
|
162
162
|
...(filters && Object.hasOwn(filters, "project") ? { byFilter: true } : {}),
|
|
@@ -167,7 +167,7 @@ function projectContext(project, filters) {
|
|
|
167
167
|
* project's value for that kind, and a kind neither gave stays at today's default.
|
|
168
168
|
* `view` is the project as applied: the same effective values, for the response to report.
|
|
169
169
|
*/
|
|
170
|
-
function withProjectDefaults(project, explicit) {
|
|
170
|
+
export function withProjectDefaults(project, explicit) {
|
|
171
171
|
const include = explicit.include ?? project?.include;
|
|
172
172
|
const from = explicit.source ?? project?.from;
|
|
173
173
|
const filters = explicit.filters ?? project?.filters;
|
|
@@ -181,7 +181,7 @@ function withProjectDefaults(project, explicit) {
|
|
|
181
181
|
};
|
|
182
182
|
}
|
|
183
183
|
/** `--from` is repeatable; citty keeps only the last value, so read every occurrence from argv. */
|
|
184
|
-
function fromValues(parsed) {
|
|
184
|
+
export function fromValues(parsed) {
|
|
185
185
|
const all = parseAllFlagValues("--from");
|
|
186
186
|
return all.length > 1 ? all : parsed;
|
|
187
187
|
}
|
|
@@ -324,7 +324,7 @@ function logSearchEvent(rawQuery, response, mode = "keyword", eventSource = "use
|
|
|
324
324
|
* source entry's `name`, or an exact path). Throws INVALID_SOURCE_VALUE with
|
|
325
325
|
* the known names before any stash access can fail differently.
|
|
326
326
|
*/
|
|
327
|
-
function assertNamedSourceExists(config, namedSourceName) {
|
|
327
|
+
export function assertNamedSourceExists(config, namedSourceName) {
|
|
328
328
|
const configSources = getSources(config);
|
|
329
329
|
const foundInConfig = configSources.find((source) => source.name === namedSourceName || source.path === namedSourceName);
|
|
330
330
|
if (foundInConfig?.enabled === false) {
|
|
@@ -441,7 +441,7 @@ function rankByUsage(items, project) {
|
|
|
441
441
|
.sort((a, b) => (shown.get(b.itemRef) ?? 0) - (shown.get(a.itemRef) ?? 0) || a.itemRef.localeCompare(b.itemRef));
|
|
442
442
|
}
|
|
443
443
|
/** Whether an asset applies under the project: it names it or no project, unless the selection's filter decided. */
|
|
444
|
-
function appliesUnder(entry, project) {
|
|
444
|
+
export function appliesUnder(entry, project) {
|
|
445
445
|
return project.byFilter === true || appliesToProject(entry, project.name);
|
|
446
446
|
}
|
|
447
447
|
/** The day an entry is dated by: when it was observed, else when it was last updated. */
|
|
@@ -0,0 +1,14 @@
|
|
|
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
|
+
import { withProjectLine } from "../../core/projects.js";
|
|
5
|
+
/** The project line when one applies, then each rule under its ref. */
|
|
6
|
+
export function formatRulesText(result) {
|
|
7
|
+
const body = result.rules.length === 0
|
|
8
|
+
? "No rules apply here."
|
|
9
|
+
: result.rules.map((rule) => `## ${rule.ref}\n\n${rule.content}`).join("\n\n");
|
|
10
|
+
return withProjectLine(body, result.project);
|
|
11
|
+
}
|
|
12
|
+
export const rulesFormatters = [
|
|
13
|
+
{ command: "rules", handler: (r) => formatRulesText(r) },
|
|
14
|
+
];
|
package/dist/output/text.js
CHANGED
|
@@ -28,6 +28,7 @@ import { getTextFormatterHandler, registerTextFormatters } from "./text/registry
|
|
|
28
28
|
import { registryCommandFormatters } from "./text/registry-commands.js";
|
|
29
29
|
import { rememberFormatters } from "./text/remember.js";
|
|
30
30
|
import { removeFormatters } from "./text/remove.js";
|
|
31
|
+
import { rulesFormatters } from "./text/rules.js";
|
|
31
32
|
import { searchFormatters } from "./text/search.js";
|
|
32
33
|
import { showFormatters } from "./text/show.js";
|
|
33
34
|
import { syncFormatters } from "./text/sync.js";
|
|
@@ -48,6 +49,7 @@ const BUILT_IN_TEXT_FORMATTERS = [
|
|
|
48
49
|
...showFormatters,
|
|
49
50
|
...searchFormatters,
|
|
50
51
|
...curateFormatters,
|
|
52
|
+
...rulesFormatters,
|
|
51
53
|
...workflowFormatters,
|
|
52
54
|
...listFormatters,
|
|
53
55
|
...addFormatters,
|
|
@@ -70554,6 +70554,7 @@ var PASSTHROUGH_COMMANDS = [
|
|
|
70554
70554
|
"registry-remove",
|
|
70555
70555
|
"remember",
|
|
70556
70556
|
"remove",
|
|
70557
|
+
"rules",
|
|
70557
70558
|
"secret-remove",
|
|
70558
70559
|
"secret-set",
|
|
70559
70560
|
"setup",
|
|
@@ -72725,6 +72726,9 @@ function buildMetricsView(r, detail) {
|
|
|
72725
72726
|
["shows", int2(usage.totals.shows)],
|
|
72726
72727
|
["curates", int2(usage.totals.curates)],
|
|
72727
72728
|
["selects", int2(usage.totals.selects)],
|
|
72729
|
+
["rule loads", int2(usage.rules.loads)],
|
|
72730
|
+
["rules per load", fixed(usage.rules.meanRules, 1)],
|
|
72731
|
+
["characters per load", fixed(usage.rules.meanChars, 0)],
|
|
72728
72732
|
["searches with hits", int2(usage.totals.searchesWithHits)],
|
|
72729
72733
|
["selects per search with hits", fixed(usage.selectsPerSearch, 2)],
|
|
72730
72734
|
[
|
|
@@ -72750,6 +72754,12 @@ function buildMetricsView(r, detail) {
|
|
|
72750
72754
|
dash(a.lastUsedAt)
|
|
72751
72755
|
])
|
|
72752
72756
|
},
|
|
72757
|
+
{
|
|
72758
|
+
title: "Rule loads",
|
|
72759
|
+
headers: ["ref", "loads"],
|
|
72760
|
+
rows: cut(usage.rules.byRule).map((rule) => [rule.ref, int2(rule.loads)]),
|
|
72761
|
+
hideWhenEmpty: true
|
|
72762
|
+
},
|
|
72753
72763
|
{
|
|
72754
72764
|
title: "Top queries",
|
|
72755
72765
|
headers: ["query", "count", "avg results", "last"],
|
|
@@ -72762,8 +72772,8 @@ function buildMetricsView(r, detail) {
|
|
|
72762
72772
|
},
|
|
72763
72773
|
{
|
|
72764
72774
|
title: "Daily",
|
|
72765
|
-
headers: ["day", "search", "show", "curate", "feedback"],
|
|
72766
|
-
rows: brief ? [] : usage.daily.map((d) => [d.day, int2(d.search), int2(d.show), int2(d.curate), int2(d.feedback)]),
|
|
72775
|
+
headers: ["day", "search", "show", "curate", "feedback", "rules"],
|
|
72776
|
+
rows: brief ? [] : usage.daily.map((d) => [d.day, int2(d.search), int2(d.show), int2(d.curate), int2(d.feedback), int2(d.rules)]),
|
|
72767
72777
|
hideWhenEmpty: true
|
|
72768
72778
|
}
|
|
72769
72779
|
]
|
|
@@ -73066,6 +73076,19 @@ var rememberFormatters = [
|
|
|
73066
73076
|
// src/output/text/remove.ts
|
|
73067
73077
|
var removeFormatters = [{ command: "remove", handler: (r) => formatRemovePlain(r) }];
|
|
73068
73078
|
|
|
73079
|
+
// src/output/text/rules.ts
|
|
73080
|
+
function formatRulesText(result) {
|
|
73081
|
+
const body = result.rules.length === 0 ? "No rules apply here." : result.rules.map((rule) => `## ${rule.ref}
|
|
73082
|
+
|
|
73083
|
+
${rule.content}`).join(`
|
|
73084
|
+
|
|
73085
|
+
`);
|
|
73086
|
+
return withProjectLine(body, result.project);
|
|
73087
|
+
}
|
|
73088
|
+
var rulesFormatters = [
|
|
73089
|
+
{ command: "rules", handler: (r) => formatRulesText(r) }
|
|
73090
|
+
];
|
|
73091
|
+
|
|
73069
73092
|
// src/output/text/search.ts
|
|
73070
73093
|
var searchFormatters = [
|
|
73071
73094
|
{
|
|
@@ -73108,6 +73131,7 @@ var BUILT_IN_TEXT_FORMATTERS = [
|
|
|
73108
73131
|
...showFormatters,
|
|
73109
73132
|
...searchFormatters,
|
|
73110
73133
|
...curateFormatters,
|
|
73134
|
+
...rulesFormatters,
|
|
73111
73135
|
...workflowFormatters,
|
|
73112
73136
|
...listFormatters,
|
|
73113
73137
|
...addFormatters,
|
|
@@ -70552,6 +70552,7 @@ var PASSTHROUGH_COMMANDS = [
|
|
|
70552
70552
|
"registry-remove",
|
|
70553
70553
|
"remember",
|
|
70554
70554
|
"remove",
|
|
70555
|
+
"rules",
|
|
70555
70556
|
"secret-remove",
|
|
70556
70557
|
"secret-set",
|
|
70557
70558
|
"setup",
|
|
@@ -72723,6 +72724,9 @@ function buildMetricsView(r, detail) {
|
|
|
72723
72724
|
["shows", int2(usage.totals.shows)],
|
|
72724
72725
|
["curates", int2(usage.totals.curates)],
|
|
72725
72726
|
["selects", int2(usage.totals.selects)],
|
|
72727
|
+
["rule loads", int2(usage.rules.loads)],
|
|
72728
|
+
["rules per load", fixed(usage.rules.meanRules, 1)],
|
|
72729
|
+
["characters per load", fixed(usage.rules.meanChars, 0)],
|
|
72726
72730
|
["searches with hits", int2(usage.totals.searchesWithHits)],
|
|
72727
72731
|
["selects per search with hits", fixed(usage.selectsPerSearch, 2)],
|
|
72728
72732
|
[
|
|
@@ -72748,6 +72752,12 @@ function buildMetricsView(r, detail) {
|
|
|
72748
72752
|
dash(a.lastUsedAt)
|
|
72749
72753
|
])
|
|
72750
72754
|
},
|
|
72755
|
+
{
|
|
72756
|
+
title: "Rule loads",
|
|
72757
|
+
headers: ["ref", "loads"],
|
|
72758
|
+
rows: cut(usage.rules.byRule).map((rule) => [rule.ref, int2(rule.loads)]),
|
|
72759
|
+
hideWhenEmpty: true
|
|
72760
|
+
},
|
|
72751
72761
|
{
|
|
72752
72762
|
title: "Top queries",
|
|
72753
72763
|
headers: ["query", "count", "avg results", "last"],
|
|
@@ -72760,8 +72770,8 @@ function buildMetricsView(r, detail) {
|
|
|
72760
72770
|
},
|
|
72761
72771
|
{
|
|
72762
72772
|
title: "Daily",
|
|
72763
|
-
headers: ["day", "search", "show", "curate", "feedback"],
|
|
72764
|
-
rows: brief ? [] : usage.daily.map((d) => [d.day, int2(d.search), int2(d.show), int2(d.curate), int2(d.feedback)]),
|
|
72773
|
+
headers: ["day", "search", "show", "curate", "feedback", "rules"],
|
|
72774
|
+
rows: brief ? [] : usage.daily.map((d) => [d.day, int2(d.search), int2(d.show), int2(d.curate), int2(d.feedback), int2(d.rules)]),
|
|
72765
72775
|
hideWhenEmpty: true
|
|
72766
72776
|
}
|
|
72767
72777
|
]
|
|
@@ -73064,6 +73074,19 @@ var rememberFormatters = [
|
|
|
73064
73074
|
// src/output/text/remove.ts
|
|
73065
73075
|
var removeFormatters = [{ command: "remove", handler: (r) => formatRemovePlain(r) }];
|
|
73066
73076
|
|
|
73077
|
+
// src/output/text/rules.ts
|
|
73078
|
+
function formatRulesText(result) {
|
|
73079
|
+
const body = result.rules.length === 0 ? "No rules apply here." : result.rules.map((rule) => `## ${rule.ref}
|
|
73080
|
+
|
|
73081
|
+
${rule.content}`).join(`
|
|
73082
|
+
|
|
73083
|
+
`);
|
|
73084
|
+
return withProjectLine(body, result.project);
|
|
73085
|
+
}
|
|
73086
|
+
var rulesFormatters = [
|
|
73087
|
+
{ command: "rules", handler: (r) => formatRulesText(r) }
|
|
73088
|
+
];
|
|
73089
|
+
|
|
73067
73090
|
// src/output/text/search.ts
|
|
73068
73091
|
var searchFormatters = [
|
|
73069
73092
|
{
|
|
@@ -73106,6 +73129,7 @@ var BUILT_IN_TEXT_FORMATTERS = [
|
|
|
73106
73129
|
...showFormatters,
|
|
73107
73130
|
...searchFormatters,
|
|
73108
73131
|
...curateFormatters,
|
|
73132
|
+
...rulesFormatters,
|
|
73109
73133
|
...workflowFormatters,
|
|
73110
73134
|
...listFormatters,
|
|
73111
73135
|
...addFormatters,
|
|
@@ -57,5 +57,5 @@ export function proposalBacklog(proposals, now) {
|
|
|
57
57
|
}
|
|
58
58
|
/** Activity per UTC day with the empty days inside the data's coverage filled in and partial days marked. */
|
|
59
59
|
export function filledActivity(daily, window) {
|
|
60
|
-
return zeroFill(daily, (day) => ({ day, search: 0, show: 0, curate: 0, feedback: 0 }), window);
|
|
60
|
+
return zeroFill(daily, (day) => ({ day, search: 0, show: 0, curate: 0, feedback: 0, rules: 0 }), window);
|
|
61
61
|
}
|
|
@@ -276,18 +276,18 @@ Unique index `idx_task_history_run` on `(task_id, started_at)`; indexes on
|
|
|
276
276
|
|
|
277
277
|
#### `usage_events`
|
|
278
278
|
|
|
279
|
-
Search, show, curate, and
|
|
279
|
+
Search, show, curate, feedback, and rules telemetry. It lives in `state.db` so
|
|
280
280
|
rebuilding `index.db` does not discard it.
|
|
281
281
|
|
|
282
282
|
| Column | Type | Notes |
|
|
283
283
|
|---|---|---|
|
|
284
284
|
| `id` | INTEGER PRIMARY KEY AUTOINCREMENT | |
|
|
285
|
-
| `event_type` | TEXT NOT NULL | `search`, `show`, `curate`, `feedback` |
|
|
285
|
+
| `event_type` | TEXT NOT NULL | `search`, `show`, `curate`, `feedback`, `rules` |
|
|
286
286
|
| `query` | TEXT | The search or curate query; NULL for show and feedback |
|
|
287
287
|
| `entry_id` | INTEGER | `index.db` entry id; re-linked after a rebuild. Null at write time on search, curate and nested command/persona read events, which record only `entry_ref`; the next index fills it from `entry_ref`. Utility scores aggregate by `entry_ref`. Deleting an entry also deletes its events that carry no `entry_id` yet, matched by `entry_ref` |
|
|
288
288
|
| `entry_ref` | TEXT | Stable ref string |
|
|
289
289
|
| `signal` | TEXT | `positive` or `negative` for feedback |
|
|
290
|
-
| `metadata` | TEXT | JSON. A `show` event carries `project` (the project in force when it ran; absent on events recorded before project attribution and when none applied), which `akm doctor metrics assets` counts by |
|
|
290
|
+
| `metadata` | TEXT | JSON. A `show` event carries `project` (the project in force when it ran; absent on events recorded before project attribution and when none applied), which `akm doctor metrics assets` counts by. A `rules` event (one per `akm rules` call, no `entry_ref`) carries `project`, `bundles`, `refs` (durable refs) and `chars` |
|
|
291
291
|
| `source` | TEXT NOT NULL DEFAULT 'user' | `user`, `improve`, `task`, `audit`, `unknown` (`AKM_EVENT_SOURCE` sets it for child processes) |
|
|
292
292
|
| `created_at` | TEXT NOT NULL | |
|
|
293
293
|
|
|
@@ -259,8 +259,8 @@ by ref.
|
|
|
259
259
|
|
|
260
260
|
`rules/` holds the short rules an agent should follow for a project: a Markdown file
|
|
261
261
|
per topic, nested folders allowed, each a bullet list of imperative, checkable lines.
|
|
262
|
-
Rules are standing context: the AKM agent plugins load the applicable ones at
|
|
263
|
-
start and after compaction, so keep them to a handful of lines.
|
|
262
|
+
Rules are standing context: the AKM agent plugins load the applicable ones (`akm rules`) at
|
|
263
|
+
session start and after compaction, so keep them to a handful of lines.
|
|
264
264
|
|
|
265
265
|
```markdown
|
|
266
266
|
---
|
|
@@ -282,16 +282,17 @@ or when it has none (shared); with no project in force only shared rules apply.
|
|
|
282
282
|
project's rules are never returned while a project is selected. If the project's own `filters`
|
|
283
283
|
constrain `project`, that filter decides instead. Only the bundle's top-level `rules/` folder
|
|
284
284
|
holds rules. After adding `rules/` to a bundle that already has files there, run
|
|
285
|
-
`akm index --full` so
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
285
|
+
`akm index --full` so search retypes them; `akm rules` reads the files and needs no index.
|
|
286
|
+
|
|
287
|
+
`akm rules` prints the rules that apply, in full: the project's first, then shared ones. It
|
|
288
|
+
reads the files, so a new rule applies at once and no index is needed. A rule is an
|
|
289
|
+
instruction the agent obeys, so only the bundles you named supply them: with a project, its
|
|
290
|
+
`from` list, else the default bundle and the project's `write.bundle`; with no project, the
|
|
291
|
+
default bundle. A bundle you installed from a registry or a git URL supplies rules only if it
|
|
292
|
+
is the default bundle or you list it in the project's `from`. A rule with `quality: proposed`
|
|
293
|
+
does not load until it is accepted. The plugins run `akm rules` at session start and after
|
|
294
|
+
compaction; an agent without a plugin runs it too. In search and curate, rules are still
|
|
295
|
+
ordinary hits that follow `--from`, `--filter` and disabled-bundle selection.
|
|
295
296
|
|
|
296
297
|
## Bundle Structure Tips
|
|
297
298
|
|
package/docs/reference/cli.md
CHANGED
|
@@ -747,7 +747,7 @@ Deprecated; use `akm doctor metrics`; removed in 0.11.
|
|
|
747
747
|
**Experimental** (see [STABILITY.md](../../STABILITY.md)): the report, its JSON shape and the
|
|
748
748
|
dashboard may change in any release.
|
|
749
749
|
|
|
750
|
-
Report what akm has recorded locally: asset usage (search, show, curate),
|
|
750
|
+
Report what akm has recorded locally: asset usage (search, show, curate, rule loads),
|
|
751
751
|
feedback, derived utility, LLM tokens, task runs, proposal
|
|
752
752
|
flow, workflow token spend, and index runs. Read-only, and every number comes
|
|
753
753
|
from `state.db` or `index.db`; nothing is collected that was not already
|
|
@@ -773,7 +773,7 @@ Result sections (`schemaVersion: 1`):
|
|
|
773
773
|
| Field | Description |
|
|
774
774
|
| --- | --- |
|
|
775
775
|
| `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 |
|
|
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 (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
777
|
| `feedback` | Positive and negative totals, per-asset valence, per-tag counts, and the most recent negatives with their reasons |
|
|
778
778
|
| `utility` | A ten-bucket histogram of `utility_scores`, the lowest and highest assets, and how many indexed entries were never used |
|
|
779
779
|
| `outcomes` | The assets with the lowest `outcome_score` |
|
|
@@ -2164,17 +2164,56 @@ folder deeper down (`docs/rules/`) is not. A rule applies when its frontmatter `
|
|
|
2164
2164
|
equals the value the project in force writes as `project` (its `write.metadata.project`,
|
|
2165
2165
|
default its name) or it has none (shared); with no project, only shared rules apply. If the
|
|
2166
2166
|
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
|
-
|
|
2167
|
+
skipped. In search and curate, rules are ordinary hits: nothing is added to a page for them,
|
|
2168
|
+
and they follow `--from`, `--filter`, `--since`/`--until`, disabled bundles and `--belief`
|
|
2169
|
+
like any asset. A rule of another project is never returned while a project is selected, by
|
|
2170
|
+
any search or curate, including `--type rule`.
|
|
2171
|
+
|
|
2172
|
+
A session loads its rules with [`akm rules`](#rules), not with search. The AKM agent plugins
|
|
2173
|
+
run it at session start and after compaction; an agent without a plugin runs the same command.
|
|
2174
|
+
|
|
2175
|
+
### rules
|
|
2176
|
+
|
|
2177
|
+
Print the rules that apply here, in full: the project's rules first, then shared ones, each
|
|
2178
|
+
group by ref.
|
|
2179
|
+
|
|
2180
|
+
```sh
|
|
2181
|
+
akm rules
|
|
2182
|
+
akm rules --project acme
|
|
2183
|
+
akm rules --project none --from team
|
|
2184
|
+
akm rules --filter team=platform --format text
|
|
2185
|
+
```
|
|
2186
|
+
|
|
2187
|
+
| Flag | Default | Description |
|
|
2188
|
+
| --- | --- | --- |
|
|
2189
|
+
| `--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 |
|
|
2190
|
+
| `--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 |
|
|
2191
|
+
| `--filter <key>=<value>` | the project's `filters` | Repeatable frontmatter filter with the matching of `akm search --filter`, replacing the project's `filters` |
|
|
2192
|
+
|
|
2193
|
+
**Which bundles supply rules.** A rule is an instruction the agent obeys, so only bundles you
|
|
2194
|
+
named supply them. With `--from`, those bundles; else the project's `from`; else, with a
|
|
2195
|
+
project, the default bundle and the project's `write.bundle`; with no project, the default
|
|
2196
|
+
bundle. A bundle installed from a registry or a git URL supplies rules only when it is the
|
|
2197
|
+
default bundle or you name it in `from`. A disabled bundle is never read.
|
|
2198
|
+
|
|
2199
|
+
**Which rules.** Files the index walker types as `rule` in those bundles (a Markdown file in
|
|
2200
|
+
the top-level `rules/` folder, `README.md` excepted), read from the files: no index is needed,
|
|
2201
|
+
a rule written a second ago applies, and a locked or rebuilding index changes nothing. A rule
|
|
2202
|
+
with `quality: proposed` is never returned. The project match is the one above and the
|
|
2203
|
+
filters match as in search. There is no query, limit, `--include` or `--prefer`, and nothing
|
|
2204
|
+
is cut.
|
|
2205
|
+
|
|
2206
|
+
**Output.** JSON: `{ project?, bundles, rules: [{ ref, description, project?, content }] }`.
|
|
2207
|
+
`project` is the project as applied (as in search), present only when one applies; `bundles`
|
|
2208
|
+
are the bundle ids read, in order; `ref` is the ref search prints, so `akm show <ref>` reads
|
|
2209
|
+
it; `project` on a rule is the project it names (absent when shared); `content` is the body
|
|
2210
|
+
without frontmatter. `text` and `md` print the project line, then each rule under its ref
|
|
2211
|
+
(`No rules apply here.` when none).
|
|
2212
|
+
|
|
2213
|
+
**Usage.** One `rules` usage event per call, never a `search` or `show` event, with the
|
|
2214
|
+
project in force, the bundles read, the refs returned and the total characters of their
|
|
2215
|
+
`content`. `akm metrics` reports rule loads, rules and characters per load, and loads per
|
|
2216
|
+
rule under usage. A call moves no search count, ranking or utility score.
|
|
2178
2217
|
|
|
2179
2218
|
#### Usage list (`--by-usage`)
|
|
2180
2219
|
|
|
@@ -2184,7 +2223,7 @@ listing: it also returns `README` and scripts under `rules/` and stops at 20.
|
|
|
2184
2223
|
most shown first. It applies the project's `from`, `filters` and your flags like any search, takes no
|
|
2185
2224
|
query (one given is ignored with a warning) and no `--from registry|all` (warned; local is
|
|
2186
2225
|
used), orders by use instead of `--prefer`, records no usage event, and leaves rules out
|
|
2187
|
-
(
|
|
2226
|
+
(`akm rules` lists them). Assets that were never shown are not listed, so with no
|
|
2188
2227
|
history the list is empty. What counts: `akm show` events of `source: user` in the last 90
|
|
2189
2228
|
days (the usage retention); only `akm show` counts, not nested command or persona reads. Search and
|
|
2190
2229
|
curate results are impressions and do not count. Each `akm show` records the project in force
|
|
@@ -2198,10 +2237,11 @@ session-start hook, an automatic rule read) run with `AKM_EVENT_SOURCE` set to `
|
|
|
2198
2237
|
|
|
2199
2238
|
**Plugin recipe.** With the project resolved: `akm doctor metrics assets --detail normal
|
|
2200
2239
|
[--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
|
-
|
|
2240
|
+
bundle with no selection: `--project none --from <defaultBundle>`, where `<defaultBundle>` is
|
|
2241
|
+
`akm config get defaultBundle`. If none is configured there is no bundle to name (neither
|
|
2242
|
+
`--from <name>` nor `--from <path>` accepts the primary stash), so pass `--project none`
|
|
2243
|
+
without `--from`; every enabled bundle is then read. Rules come from `akm rules`, not from
|
|
2244
|
+
this list.
|
|
2205
2245
|
|
|
2206
2246
|
### remember
|
|
2207
2247
|
|
|
@@ -147,7 +147,8 @@ regenerable. akm also writes into it:
|
|
|
147
147
|
and a small metadata payload; search events include the query text and the
|
|
148
148
|
refs returned. `akm env run`, a workflow unit's `env:` binding and
|
|
149
149
|
`akm secret run` record the names of the keys injected, not their values.
|
|
150
|
-
- **Usage records**: queries, search impressions, show/curate engagement
|
|
150
|
+
- **Usage records**: queries, search impressions, show/curate engagement, rule loads
|
|
151
|
+
(`akm rules`: the refs and characters loaded) and
|
|
151
152
|
feedback. They feed utility scores and `akm doctor metrics`, and the feedback recorded
|
|
152
153
|
as the user adjusts search ranking. Each record is stamped with its source
|
|
153
154
|
(`user`, `improve`, `task`, `audit` or `unknown`); only `user` records count.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "akm-cli",
|
|
3
|
-
"version": "0.10.
|
|
3
|
+
"version": "0.10.261130-beta.1",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"description": "akm (Agent Knowledge Manager) — a portable, local-first capability library for AI agents. Discover, load, share, and improve reusable skills, scripts, workflows, and knowledge across any shell-capable coding agent, including Claude Code, OpenCode, and Cursor.",
|
|
6
6
|
"keywords": [
|