akm-cli 0.9.0-rc.0 → 0.9.0-rc.13

package/docs/reference/README.md

@@ -0,0 +1,12 @@
+# Reference
+
+Authoritative reference documentation for the akm CLI and its data.
+
+- [CLI](cli.md) -- All `akm` commands and flags
+- [Configuration](configuration.md) -- Engines, strategies, bundles, and settings
+- [Workflows](workflows.md) -- Unified Markdown workflow schema, run state, and native orchestration engine
+- [Registry](registry.md) -- Registries, search, hosting, and managing sources
+- [Wiki Snapshot Fetchers](wiki-snapshot-fetchers.md) -- The pluggable fetcher API for URL-based knowledge reads
+- [Data & Telemetry](data-and-telemetry.md) -- Exactly what akm reads and writes on your machine (no remote telemetry)
+- [akm-eval](akm-eval.md) -- Standalone toolkit for measuring whether `akm improve` is working
+- [Roadmap](roadmap.md) -- High-level focus for the 0.9 and 1.0 releases

package/docs/reference/data-and-telemetry.md

@@ -0,0 +1,333 @@
+# AKM Data & Telemetry
+
+AKM stores your data locally on your machine and has **no telemetry**: it does not send usage data, analytics, or crash reports to Anthropic or to the AKM project, and it has no servers of its own that receive your data. It does, however, make network requests to the endpoints **you** configure — your LLM/embedding provider, the registries and source hosts you install from, and GitHub for upgrades — and those endpoints necessarily receive whatever those requests contain. This document describes exactly what AKM reads, writes, and sends.
+
+## No Telemetry
+
+AKM does not:
+- Send usage data, events, or crash reports to Anthropic or the AKM project
+- Contact any AKM-operated analytics or telemetry endpoint at runtime
+- Include any analytics SDK or beacon
+- Collect your email, name, or any personally-identifying information for the project's benefit
+
+AKM adds no network destinations of its own. The requests it *does* make all go to endpoints you chose or invoked, and those third parties receive whatever the request contains:
+
+1. **Your configured LLM/embedding provider** (e.g. Anthropic, OpenAI, a local Ollama, or any OpenAI-compatible endpoint) receives the prompts and asset content sent for reflect/propose/distill/embedding when you enable those features. If you point AKM at Anthropic, Anthropic receives those requests.
+2. **Registry metadata and stash packages** from sources you explicitly configure (GitHub, npm, git remotes, websites) — those hosts receive the fetch/clone/crawl requests, and website sources receive requests for the pages you crawl.
+3. **`akm upgrade`** — fetches the latest release from GitHub releases (GitHub sees the request).
+4. **`akm setup`** — a single DNS lookup for `github.com` to decide whether to skip network-dependent steps (Ollama detection, remote embedding probes) when offline. No HTTP request is made by this probe; if it succeeds, akm proceeds with the network-dependent steps you already configured.
+
+In every case the receiving endpoint is one you configured or invoked; the data leaving your machine is the data you directed AKM to send there.
+
+---
+
+## Local On-Disk Surface
+
+AKM writes to these locations on your machine. All paths follow [XDG Base Directory](https://specifications.freedesktop.org/basedir-spec/latest/) conventions on Linux/macOS and Windows conventions on Windows.
+
+### Config Directory (`$XDG_CONFIG_HOME/akm` or `~/.config/akm/`)
+
+| Path | Contents | Safe to delete? |
+|---|---|---|
+| `config.json` | Your AKM configuration: engines, improve strategies, bundles (stash sources), and experimental opt-ins — see [Configuration](configuration.md) | **No** — deleting resets all settings |
+
+Override: set `AKM_CONFIG_DIR` or `XDG_CONFIG_HOME`.
+
+### Data Directory (`$XDG_DATA_HOME/akm` or `~/.local/share/akm/`)
+
+| Path | Contents | Safe to delete? |
+|---|---|---|
+| `index.db` | Search index for all your stash assets (FTS5 + metadata) | Yes — rebuilds via `akm index --full` |
+| `state.db` | Events, local usage telemetry, proposals, task history, improve run results, and workflow run state/history (the former `workflow.db` was folded in during the 0.9.0 cutover) | **No** — deletes event/usage logs, proposal queue, improve history, and workflow run history |
+| `logs.db` | Structured, high-volume task/run log lines (`{ts, task_id, run_id, stream, level, line}`), joined to `state.db`'s `task_history` rows by `task_id@started_at`. Kept separate from `state.db` because log lines are append-only and freely purgeable, unlike durable state | Yes — log lines are regenerable per run; deleting loses historical run output only |
+| `akm.lock` | Inter-process write lock | Yes — recreated automatically |
+| `akm.lock.lck` | Lock write sentinel | Yes — recreated automatically |
+
+Override: set `AKM_DATA_DIR` or `XDG_DATA_HOME`.
+
+### Cache Directory (`$XDG_CACHE_HOME/akm` or `~/.cache/akm/`)
+
+Everything in the cache is regenerable. It is safe to delete the entire cache directory; AKM will recreate what it needs on next use.
+
+| Path | Contents | Safe to delete? |
+|---|---|---|
+| `config-backups/config-<timestamp>.json` | Pre-save config snapshots (5 retained; owner-only permissions — file `0600`, dir `0700`, since 08-F4) | Yes |
+| `config-backups/config.latest.json` | Latest backup alias (owner-only `0600`) | Yes |
+| `registry/` | Downloaded registry tarballs (stash packages from npm, GitHub, etc.) | Yes — re-downloaded on next `akm bundle add` or `akm bundle update` |
+| `registry-index/` | Legacy per-URL JSON cache (v0.7 artifact) | Yes — fully replaced by `index.db` in 0.8.0 |
+| `semantic-status.json` | Semantic index build status marker | Yes |
+| `bin/` | Downloaded AKM binary cache (used by `akm upgrade`) | Yes |
+| `tasks/logs/` | Scheduled task log files | Yes — ephemeral logs |
+| `tasks/history/` | Legacy task history JSONL (v0.7 migration artifact) | Yes |
+
+Override: set `AKM_CACHE_DIR` or `XDG_CACHE_HOME`.
+
+### Stash Directory (`~/akm/` by default, or user-configured)
+
+| Path | Contents | Safe to delete? |
+|---|---|---|
+| `<stash>/` | All your asset files: agents, skills, commands, knowledge, instructions, workflows, scripts, memories, env files, secrets, lessons, tasks, sessions, facts, plus any bundle-adapter-owned content (e.g. `llm-wiki` bundle roots — not an AKM `PLACEMENT_SPECS` type) | **No** — this is YOUR data |
+| `<stash>/.akm/` | Hidden AKM metadata (v0.7 proposals, legacy runs) | Caution — check for pending proposals first |
+
+Override: set `AKM_BUNDLE_DIR`, or configure `bundles`/`defaultBundle` in `config.json` (the top-level `stashDir` key from 0.8 is retired and rejected in 0.9 — see [Configuration](configuration.md#bundles-and-write-target)).
+
+---
+
+## What Is Stored in `state.db`
+
+`state.db` holds four categories of non-regenerable data:
+
+### 1. Events Table
+
+An append-only log of every mutating action you perform with AKM. Events are stored locally for self-improvement (the improve loop uses them to surface usage patterns) and for inspection via `akm log`.
+
+**What is recorded:**
+- `event_type` — what action was taken (see full list below)
+- `ts` — ISO-8601 UTC timestamp
+- `ref` — the asset ref affected (e.g. `skills/code-review`), if applicable
+- `metadata` — structured payload specific to the event type (e.g. query text for `search`, score for `feedback`)
+
+**What is NOT recorded:**
+- File contents
+- LLM prompts or responses
+- API keys or secrets (config is not stored in events)
+- Personal information
+
+**Retention:** Events older than 90 days are purged automatically when `akm improve` runs its maintenance pass. The window is `improve.eventRetentionDays` (default `90`; set `0` to disable), enforced by `purgeOldEvents()`.
+
+**Full event type list.** `EventType` (`src/core/events.ts`) is an open
+string union — new types can be added without a schema bump — so this is
+the set of types the code actually emits at HEAD (verified against every
+`appendEvent(...)` call site, 2026-07-27), grouped by area:
+
+*Asset lifecycle*
+
+| Event type | When emitted | Key metadata fields |
+|---|---|---|
+| `add` | `akm bundle add <source>` | `ref`, `provider` |
+| `remove` | `akm bundle remove <source>` | `ref` |
+| `update` | `akm bundle update [source]` | `ref` |
+| `remember` | `akm remember <text>` | `ref` |
+| `import` | `akm import <file>` | `ref` |
+| `rekey` | `scripts/rekey-asset-ref.ts` moved at least one row onto a renamed asset's new ref — nothing is emitted on a no-op re-run | `ref` (the new ref); metadata `{from, to, changed}` (row counts only) |
+
+*Search, retrieval, sync*
+
+| Event type | When emitted | Key metadata fields |
+|---|---|---|
+| `search` | `akm search <query>` | `query`, `source`, `signal` |
+| `curate` | `akm curate <prompt>` | `query`, `source` |
+| `show` | `akm show <ref>` | `ref`, `type`, `name` |
+| `select` | `akm show` after a search returning the same ref | `ref`, `entryId` |
+| `feedback` | `akm feedback <ref>` | `signal` (positive/negative) |
+| `sync` | `akm sync` (renamed from `save` in 0.9.0; historical rows keep `save`, and `akm log --type save`/`--type sync` are synonyms on read) | `ref` |
+| `stash_synced` | `akm improve`'s internal auto-sync pass (the `sync.push` feature), **distinct from** the `akm sync` command above | `committed`, `pushed`, `skipped`, `reason` |
+| `env_access` | `akm env run <name> -- <command>` (audit trail: key **names** only, values never recorded) | `ref`, `keys` |
+| `secret_access` | `akm secret run <ref> <VAR> -- <command>` (audit trail: var **name** only, value never recorded) | `ref`, `var` |
+
+*Proposals*
+
+| Event type | When emitted | Key metadata fields |
+|---|---|---|
+| `promoted` | `akm proposal accept <id>` | `ref` |
+| `rejected` | `akm proposal reject <id>` | `ref` |
+| `proposal_reverted` | `akm proposal revert <id>` (undoes a previously-accepted proposal, restores prior content) | `ref` |
+| `proposal_expired` | A pending proposal aged past the retention window and was auto-expired | `ref` |
+| `proposal_expiration_pass` | Summary emitted once per `akm improve` maintenance run after per-proposal `proposal_expired` events | expiry counts |
+| `proposal_orphan_purge` | Stale proposals whose target asset no longer exists on disk, pruned by improve maintenance | `checked`, `rejected` |
+| `proposal_creation_rejected` | `createProposal()` validation failed before write | `ref`, `reason`, `source` |
+| `triage_drained` | `akm proposal drain` run summary | `promoted`, `rejected`, `deferredByReason`, `skippedByCap`, `policy`, `applyMode` |
+| `triage_deferred` | `akm proposal drain` left items unresolved after the (optional) judgment tier | `deferred`, `deferredByReason`, `reason` |
+
+*`akm improve` pipeline*
+
+| Event type | When emitted | Key metadata fields |
+|---|---|---|
+| `improve_invoked` | Start of an `akm improve` run | `ref` (scope); `strategy`, `scope`, `dryRun`, `eligibleCount` |
+| `improve_completed` | `akm improve` run finished | run stats |
+| `improve_failed` | `akm improve` run errored | error |
+| `improve_skipped` | Asset skipped by cooldown or budget | `ref`, `reason` |
+| `improve_lock_recovered` | Stale improve lock cleared at startup | |
+| `improve_review_needed` | `akm feedback` pushed a high-utility asset's utility below the review threshold — a review-needed escalation is recorded (not a proposal, so it can't accidentally overwrite the asset) | `ref`, `previousUtility`, `nextUtility` |
+| `reflect_invoked` | Start of reflect phase in `akm improve` | `ref`, engine |
+| `reflect_completed` | Reflect phase produced a proposal | `ref` |
+| `improve_reflect_outcome` | Per-asset reflect result | `ref`, `ok`, `durationMs`, `reason` |
+| `propose_invoked` | `akm proposal new` | `ref` |
+| `distill_invoked` | Distill phase inside the `akm improve`/`akm proposal new` pipeline. **`akm distill` is not a CLI command** — there is no standalone verb by that name | `ref`, outcome |
+| `consolidate_completed` | `akm improve`'s consolidate pass processed at least one memory | `ref` (`memories/_consolidation`) |
+| `extract_invoked` | `akm proposal extract --type <harness>` / `--auto`, or improve-stage session extraction | `outcome`, `sessionId`, `harness` |
+| `extract_triaged` | The pre-LLM extract triage gate evaluated at least one session | `evaluated`, `passed`, `triagedOut`, `sourceRun` (aggregated) |
+| `schema_repair_invoked` | The schema-repair pass inside `akm improve` (`runSchemaRepairPass`) attempts to patch missing frontmatter on an asset that failed schema validation. **There is no `akm lint --repair` flag** — `lint` has `--fix`/`--auto-fix`, unrelated to this event | `ref`, outcome |
+| `proactive_selected` | The proactive-maintenance selector runs (once per `akm improve` run) | `count`, `dueTotal`, `neverReflected` (aggregated) |
+| `improve_replay_selected` | Bounded replay-budget selection ran | `count`, `budget`, `convergedSkipped`, `candidatePool` (aggregated) |
+| `improve_salience_first_run` | First improve run with no pre-existing salience baseline to compare against | `candidateCount`, `note` |
+| `improve_salience_rank_change` | Stash-wide rank-change report, from the second improve run onward | `stashSize`, `totalChanged`, `forgettingCandidates`, `topDrops` |
+| `outcome_proxy_inverted` | Proxy-adequacy tripwire: `outcome_score` correlates *negatively* with accepted-change rate (corr < −0.3) | `correlation`, `n` |
+| `outcome_proxy_dead` | Proxy-adequacy tripwire: `outcome_score` is statistically unrelated to accepted-change rate (\|corr\| < 0.1, n ≥ 500) | `correlation`, `n` |
+| `collapse_detector_alert` | The collapse/churn detector trips an alert rule during an improve cycle | `kind` (collapse-recall\|collapse-entropy\|collapse-shrink\|churn\|merge-floor), `detail`, `metrics`, `canarySetId`, `runId` |
+| `events_purged` | Old events deleted by improve maintenance (90-day default retention) | `purgedCount`, `retentionDays` |
+| `improve_runs_purged` | Old `improve_runs` rows deleted by improve maintenance (same retention window as events) | `purgedCount`, `retentionDays` |
+| `improve_cycle_metrics_purged` | Old `improve_cycle_metrics` rows (365-day retention) deleted by improve maintenance | `purgedCount`, `retentionDays` |
+| `task_logs_purged` | Old scheduled-task log files purged by improve maintenance | |
+
+*Workflows*
+
+| Event type | When emitted | Key metadata fields |
+|---|---|---|
+| `workflow_started` | `akm workflow start <ref>` | `ref`, `runId` |
+| `workflow_step_completed` | `akm workflow complete` (genuine `completed` transition only; `completeWorkflowStep`, `src/workflows/runtime/runs.ts`) | `ref`, `runId`, `stepId`, `status` |
+| `workflow_step_updated` | `akm workflow complete` (non-`completed` transitions: `failed`/`skipped`/`blocked`) | `ref`, `runId`, `stepId`, `status` |
+| `workflow_finished` | `akm workflow complete`, when that step completion brings the run to a terminal status | `ref`, `runId` |
+| `workflow_abandoned` | `akm workflow abandon` | `runId` only — never the workflow title |
+| `workflow_unit_started` | A workflow-engine unit dispatch begins (native `akm workflow run` or the `brief`/`report` driver protocol — both require `experimental.workflowEngine`, see [Workflows](workflows.md#enabling-the-workflow-engine-opt-in-in-090)) | ids/status only — never unit instructions or results |
+| `workflow_unit_finished` | A workflow-engine unit terminates | ids/status/tokens only — never unit instructions or results |
+
+*LLM usage and health*
+
+| Event type | When emitted | Key metadata fields |
+|---|---|---|
+| `llm_usage` | Per-attempt LLM call usage telemetry (#576) | model provenance, terminal outcome, duration, optional token usage |
+| `llm_usage_summary` | The owning LLM telemetry sink's terminal-record count marker | `expectedTerminalRecords` |
+| `health_probe` | `akm health`'s state.db round-trip write/read probe. **Not durably retained**: the row is inserted then deleted within the same connection once the round trip is confirmed, so the net effect on the `events` table is always zero rows | n/a (ephemeral) |
+
+### 2. Usage Events Table
+
+`usage_events` is the local analytical record behind utility ranking,
+retrieval-demand counts, GRR, and real-query eval generation (0.9.0: its CLI
+read surface, `akm history`, was removed — the table itself and everything
+below still applies). It stores
+search/curate queries, per-entry search impressions, explicit show/curate
+engagement, feedback signals, stable refs, and timestamps. It never leaves the
+machine unless you explicitly copy the database or send derived content to a
+configured endpoint.
+
+Successful `search`, `curate`, and `show` commands record usage by default.
+Pass `--no-track-usage` to any of those commands to leave local usage events
+and ranking signals unchanged.
+
+Every runtime writer stamps provenance as `user`, `improve`, `task`, `audit`, or
+`unknown`. Direct interactive CLI traffic defaults to `user`; internal improve,
+scheduled-task, and eval subprocesses preserve their stamp across nested
+search/curate/show/remember/agent reads. Omitted or invalid writer provenance is
+`unknown`, and pre-provenance rows rescued at the 0.9 cutover are also
+`unknown`. Only exact `source='user'` rows contribute demand, utility, GRR, or
+real-query labels.
+
+Per-entry `search`, `curate`, and `show` rows carry a local-only
+`metadata.downstreamAttribution` object. Version 1 uses `control: true` for
+current traffic where neither memory inference nor graph extraction applies;
+rows without the version marker are historical/unattributed. Attributed rows
+use `control: false` and may contain:
+
+- `memoryInference`: `direct` when the emitted ref is an inferred child, or
+  `surface` when derived description/tags were actually present in the emitted
+  search or selected curate output. Brief output and internally replaced
+  descriptions are controls, not surface attribution.
+- `graphExtraction`: the positive graph-ranking contribution that was actually
+  applied after the shared contributor cap, plus `bodyHash` and
+  `extractionRunId` when available. It is absent when `graph-ranking` is
+  ablated. The number is a ranking-input contribution, not proof that graph
+  changed final rank, selection, or outcome; score saturation and competing
+  contributors can leave ordering unchanged.
+
+Attribution metadata contains fully-qualified refs and graph identifiers, never
+asset bodies or provenance content. It is not added to `search`, `curate`, or
+`show` result payloads; there is no CLI surface that reads it back (0.9.0:
+`akm history` was removed). The full index still applies its existing
+higher-priority-wins `(type, entry.name)` dedup across sources: attribution
+source-qualifies every indexed row but does not invent a lower-priority row for
+an identity that production indexing omitted.
+
+### 3. Proposals Table
+
+The proposal queue: pending, accepted, and rejected improvement proposals for your stash assets. Generated by `akm improve`, `akm proposal new`, and related proposal-producing flows.
+
+Contents:
+- Proposal UUID (primary key)
+- Target asset ref
+- Status (pending/accepted/rejected)
+- Source (which process generated it — e.g. `reflect`, `distill`)
+- Full proposal content (Markdown text)
+- Created/updated timestamps
+
+### 4. Task History Table
+
+A record of scheduled task runs (from `akm task`):
+- Task ID, status, start/end times
+- Log file path (the log content stays in `$CACHE/tasks/logs/`)
+
+---
+
+## How to Inspect and Clear Local Data
+
+### Inspect events
+
+```sh
+# List recent events
+akm log
+
+# Filter by type
+akm log --type search --limit 20
+
+# Filter by asset ref
+akm log --ref skills/code-review
+```
+
+### Inspect proposals
+
+```sh
+# List pending proposals
+akm proposal list
+
+# Show a specific proposal
+akm proposal show <id>
+```
+
+### Clear specific data
+
+```sh
+# Delete the search index (safe — rebuilds with akm index --full)
+rm ~/.local/share/akm/index.db
+
+# Delete all cached registry downloads
+rm -rf ~/.cache/akm/registry/
+
+# Delete config backups
+rm -rf ~/.cache/akm/config-backups/
+
+# Delete the events log from state.db (non-reversible)
+# There is no akm CLI command to do this directly (`akm log` only exposes
+# `list`/`tail`, no delete/purge verb). Use SQLite directly:
+sqlite3 ~/.local/share/akm/state.db "DELETE FROM events;"
+
+# Delete all proposals
+sqlite3 ~/.local/share/akm/state.db "DELETE FROM proposals;"
+```
+
+### Start completely fresh (nuclear reset)
+
+```sh
+rm -f ~/.config/akm/config.json
+rm -rf ~/.local/share/akm/
+rm -rf ~/.cache/akm/
+# Your stash files in ~/akm/ are NOT touched by the above.
+```
+
+---
+
+## Environment Variable Overrides
+
+You can redirect any AKM directory to a custom path:
+
+| Variable | Overrides |
+|---|---|
+| `AKM_CONFIG_DIR` | Config directory (`~/.config/akm/`) |
+| `AKM_DATA_DIR` | Data directory (`~/.local/share/akm/`) |
+| `AKM_SQLITE_JOURNAL_MODE` | SQLite journal mode: `WAL` (default), `DELETE`, or `TRUNCATE`. Use `DELETE`/`TRUNCATE` on network filesystems (NFS/SMB) where WAL is impossible. When left at the `WAL` default, akm auto-detects a network FS for the data dir and falls back to `DELETE`. |
+| `AKM_STATE_DIR` | State directory (`~/.local/state/akm/`) |
+| `AKM_CACHE_DIR` | Cache directory (`~/.cache/akm/`) |
+| `AKM_BUNDLE_DIR` | Default stash directory (`~/akm/`) |
+| `XDG_CONFIG_HOME` | XDG base — akm appends `/akm` |
+| `XDG_DATA_HOME` | XDG base — akm appends `/akm` |
+| `XDG_STATE_HOME` | XDG base — akm appends `/akm` |
+| `XDG_CACHE_HOME` | XDG base — akm appends `/akm` |

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "akm-cli",
-  "version": "0.9.0-rc.0",
+  "version": "0.9.0-rc.13",
   "type": "module",
-  "description": "akm (Agent Knowledge Management) — A package manager for AI agent skills, commands, tools, and knowledge. Works with Claude Code, OpenCode, Cursor, and any AI coding assistant.",
+  "description": "akm (Agent Knowledge Manager) — A knowledge toolkit for AI agents: capture, curate, search, and share skills, commands, tools, and knowledge. Works with Claude Code, OpenCode, Cursor, and any AI coding assistant.",
   "keywords": [
     "akm",
     "agent-knowledge-management",
@@ -43,48 +43,54 @@
     "LICENSE",
     "docs/migration/release-notes",
     "docs/migration/v0.7-to-v0.8.md",
-    "docs/data-and-telemetry.md"
+    "docs/migration/v0.8-to-v0.9.md",
+    "docs/reference/data-and-telemetry.md",
+    "schemas"
   ],
   "bin": {
     "akm": "dist/akm",
-    "akm-migrate-storage": "dist/akm-migrate-storage"
+    "akm-migrate": "dist/akm-migrate"
   },
   "scripts": {
-    "preinstall": "node -e \"var ua=process.env.npm_config_user_agent||'';var v=(process.versions.node||'0').split('.').map(function(n){return parseInt(n,10)||0});var ok=v[0]>20||(v[0]===20&&(v[1]>12||(v[1]===12&&v[2]>=0)));if(process.versions.bun||ua.startsWith('bun/')||process.env.BUN_INSTALL||ok){process.exit(0)}console.error('\\n  ERROR: akm-cli requires the Bun runtime (https://bun.sh), Node.js >= 20.12, or the prebuilt binary.\\n  Install options:\\n    1. Bun:    curl -fsSL https://bun.sh/install | bash  &&  bun install -g akm-cli\\n    2. Node:   upgrade to Node.js 20.12 or newer (https://nodejs.org)\\n    3. Binary: curl -fsSL https://github.com/itlackey/akm/releases/latest/download/install.sh | bash\\n');process.exit(1)\"",
+    "preinstall": "node -e \"var v=(process.versions.node||'0').split('.').map(function(n){return parseInt(n,10)||0});var ok=v[0]>=22;if(ok){process.exit(0)}console.error('\\n  ERROR: the akm-cli npm package requires Node.js >= 22.\\n  A working Bun >= 1.0 on PATH is optional and preferred for akm and akm-migrate.\\n  Upgrade Node.js (https://nodejs.org), or install the runtime-free standalone binary:\\n    curl -fsSL https://github.com/itlackey/akm/releases/latest/download/install.sh | bash\\n');process.exit(1)\"",
     "build": "rm -rf dist && bun scripts/gen-config-schema.ts &&bun run tsc --project ./tsconfig.build.json && bun scripts/copy-assets.ts && bun scripts/fix-esm-extensions.ts",
     "check": "bun run lint && bunx tsc --noEmit && bun run test:unit && bun run test:integration",
     "check:fast": "bun run lint && bunx tsc --noEmit && bun run test:unit",
-    "check:changed": "bun test tests/output-baseline.test.ts tests/integration/e2e.test.ts tests/stash-search.test.ts && bun run lint && bunx tsc --noEmit",
+    "check:changed": "bun run lint && bunx tsc --noEmit && bun test tests/integration/output-baseline.test.ts tests/integration/registry-search.test.ts tests/integration/show-argv-entrypoint.test.ts tests/output-shapes-unit.test.ts",
     "sweep:tmp": "bun scripts/sweep-test-tmp.ts",
     "test": "bash scripts/test-unit.sh",
     "test:unit": "bash scripts/test-unit.sh",
-    "test:integration": "bun run sweep:tmp && bun test --timeout=30000 ./tests/integration",
+    "test:integration": "bash scripts/test-integration.sh",
     "test:node-smoke": "bun scripts/node-smoke.ts",
     "test:node-compat": "AKM_NODE_COMPAT_TESTS=1 bun test --timeout=120000 tests/integration/node-compat.test.ts",
     "test:time": "bun scripts/test-timing-report.ts",
     "lint:isolation": "bun scripts/lint-tests-isolation.ts",
+    "lint:doc-examples": "bun scripts/lint-doc-examples.ts",
     "lint:devto-posts": "bun scripts/lint-devto-posts.ts",
     "lint:devto-posts:fix": "bun scripts/lint-devto-posts.ts --fix",
     "publish:devto": "npx -y @sinedied/devto-cli push \"docs/posts/**/*.md\" --token \"$DEVTO_TOKEN\" --repo \"$GITHUB_REPOSITORY\" --branch \"${GITHUB_REF_NAME:-main}\" --reconcile",
     "release:check": "./tests/release-check.sh",
-    "lint": "bunx biome check src/ tests/ && bun scripts/lint-tests-isolation.ts && bun scripts/lint-license-headers.ts && bun scripts/lint-runtime-boundary.ts && bun scripts/lint-repository-sql.ts && bun scripts/gen-config-schema.ts --check",
+    "lint": "bunx biome check src/ tests/ scripts/ && bun scripts/lint-tests-isolation.ts && bun scripts/lint-license-headers.ts && bun scripts/lint-runtime-boundary.ts && bun scripts/lint-write-source-chokepoint.ts && bun scripts/lint-process-argv.ts && bun scripts/lint-repository-sql.ts && bun scripts/lint-goldens-presence.ts && bun scripts/lint-golden-captured-at-head.ts && bun scripts/lint-test-ref-literals.ts && bun scripts/lint-shipped-assets.ts && bun scripts/lint-doc-examples.ts && bun scripts/gen-config-schema.ts --check",
     "lint:runtime-boundary": "bun scripts/lint-runtime-boundary.ts",
     "lint:tests-isolation": "bun scripts/lint-tests-isolation.ts",
-    "lint:fix": "bunx biome check --write src/ tests/",
-    "format": "bunx biome format --write src/ tests/",
+    "lint:fix": "bunx biome check --write src/ tests/ scripts/",
+    "format": "bunx biome format --write src/ tests/ scripts/",
     "prepublishOnly": "cp .github/README.npm.md README.md && bun run build",
-    "postpublish": "git checkout -- README.md"
+    "postpublish": "git checkout -- README.md",
+    "build:install": "bun scripts/package-install.ts install-global",
+    "test:package": "bun scripts/package-install.ts test-package"
   },
   "publishConfig": {
     "access": "public"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.14",
-    "@types/better-sqlite3": "^7.6.11",
     "@types/node": "^22.19.17",
     "@types/semver": "^7.5.8",
     "bun-types": "^1.3.13",
-    "typescript": "^5.9.3"
+    "cmd-shim": "9.0.2",
+    "typescript": "^5.9.3",
+    "zod-to-json-schema": "^3.23.0"
   },
   "optionalDependencies": {
     "@huggingface/transformers": "^4.2.0",
@@ -92,8 +98,7 @@
     "sqlite-vec": "^0.1.9"
   },
   "engines": {
-    "bun": ">=1.0.0",
-    "node": ">=20.12.0"
+    "node": ">=22"
   },
   "dependencies": {
     "@clack/prompts": "^1.3.0",
@@ -102,7 +107,6 @@
     "dotenv": "^17.4.2",
     "semver": "^7.6.0",
     "yaml": "^2.8.4",
-    "zod": "^3.23.0",
-    "zod-to-json-schema": "^3.23.0"
+    "zod": "^3.23.0"
   }
 }

package/schemas/akm-asset-envelope.json

@@ -0,0 +1,93 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://itlackey.github.io/akm/schemas/akm-asset-envelope.json",
+  "title": "AKM Markdown Asset Envelope",
+  "description": "The common frontmatter envelope every AKM markdown asset type carries: type/description/tags/when_to_use/xrefs/updated/timestamp, plus the OKF v0.2 machine-stamped families (generated/verified/provenance/status/stale_after). Per-type schemas (e.g. akm-workflow.json) $ref these definitions individually into their own top-level `properties` so `additionalProperties: false` still sees them declared locally (JSON Schema does not merge `allOf` siblings' properties for that check). This file has no `properties`/`required` of its own — it is a definitions-only library.",
+  "definitions": {
+    "type": {
+      "type": "string",
+      "minLength": 1,
+      "description": "The asset's type token (e.g. \"workflow\"). Drives recognition alongside directory residence."
+    },
+    "description": {
+      "type": "string",
+      "description": "Human-readable summary of the asset."
+    },
+    "tags": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "description": "Free-form search/classification tags."
+    },
+    "when_to_use": {
+      "type": "string",
+      "description": "Guidance on when this asset should be applied/selected."
+    },
+    "xrefs": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "description": "Canonical asset refs this asset cross-references. Ref canonicality is checked by semantic validation, not this schema."
+    },
+    "updated": {
+      "type": "string",
+      "description": "Last-updated timestamp (author-maintained)."
+    },
+    "timestamp": {
+      "type": "string",
+      "description": "Legacy creation/authoring timestamp, pre-dating OKF v0.2's `generated:`."
+    },
+    "actorStamp": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["by"],
+      "properties": {
+        "by": { "type": "string", "minLength": 1 },
+        "at": { "type": "string" }
+      },
+      "description": "One OKF v0.2 actor stamp: who (by) and, usually, when (at)."
+    },
+    "generated": {
+      "$ref": "#/definitions/actorStamp",
+      "description": "OKF v0.2 machine-stamped authorship — the replacement for the legacy `timestamp` key."
+    },
+    "verified": {
+      "anyOf": [
+        { "$ref": "#/definitions/actorStamp" },
+        { "type": "array", "items": { "$ref": "#/definitions/actorStamp" } }
+      ],
+      "description": "OKF v0.2 machine-stamped verification(s). A bare mapping or a list of them; independent confirmations accumulate."
+    },
+    "provenanceSource": {
+      "type": "object",
+      "required": ["resource"],
+      "additionalProperties": true,
+      "properties": {
+        "resource": { "type": "string", "minLength": 1 },
+        "id": { "type": "string" },
+        "title": { "type": "string" },
+        "author": { "type": "string" },
+        "usage_count": { "type": "number" },
+        "last_modified": { "type": "string" }
+      }
+    },
+    "provenance": {
+      "type": "object",
+      "additionalProperties": true,
+      "properties": {
+        "sources": {
+          "type": "array",
+          "items": { "$ref": "#/definitions/provenanceSource" }
+        }
+      },
+      "description": "Namespaced OKF v0.2 provenance (kept nested because a bare top-level `sources:` collides with the AKM-native wiki citation-string convention)."
+    },
+    "status": {
+      "enum": ["draft", "stable", "deprecated"],
+      "description": "OKF v0.2 lifecycle status."
+    },
+    "stale_after": {
+      "type": "string",
+      "minLength": 1,
+      "description": "OKF v0.2 staleness horizon (a date or duration, author-maintained)."
+    }
+  }
+}