akm AGENTS.md

AKM Repo Notes

Workflow

• Runtime and tooling are Bun-first. Use bun install.
• CI runs bun run check, which is bun run lint && bunx tsc --noEmit && bun run test:unit && bun run test:integration.
• Before committing, run bunx biome check --write src/ tests/. Repo guidance prefers the write-capable Biome pass, not just bun run lint.
• Build with bun run build. It compiles src/** only into dist/; dist/tests should never appear.
• Prefer focused verification with bun test tests/<file>.test.ts. bun run check:changed runs a small set of output/contract suites (output-baseline, registry-search, show-argv-entrypoint, output-shapes-unit) plus bun run lint and bunx tsc --noEmit.

Architecture

• This is a CLI-only package. There is no public API, no barrel exports, and no exports map. src/cli.ts is the thin dispatcher; command implementations live under src/commands/, mostly in per-family directories (src/commands/read/, src/commands/improve/, src/commands/sources/, src/commands/env/, src/commands/tasks/, src/commands/agent/, src/commands/proposal/, src/commands/health/, src/commands/lint/), with a handful of standalone *-cli.ts files (e.g. config-cli.ts, workflow-cli.ts, migrate-cli.ts, registry-cli.ts) still at the top level.
• If you touch providers, refs, search/show behavior, config, or output shaping, read docs/architecture/architecture.md first. tests/contracts/ pins active contracts and is meant to catch contract drift.
• Supported source providers are locked to filesystem, git, website, and npm. Do not add context-hub; do not reintroduce openviking.
• SourceProvider is exactly { name, kind, path, sync? }. All providers materialize files to local disk.
• Asset refs are [bundle//]conceptId[#fragment], where conceptId is subdir-qualified within its bundle (e.g. skills/code-review, memories/vpn-note, knowledge/api-guide, env/prod). Durable state stores the fully-qualified bundle//conceptId; the short bundle-omitted form is input sugar resolved against defaultBundle, then the remaining bundles in installation-priority order. Source locators like github:owner/repo are for akm bundle add, not for asset addressing. The old [origin//]type:name grammar is gone (the frozen migrator in scripts/akm-migrate/migrate/ is the only place it survives).
• show is local-index only: resolve through the FTS index, then read from disk. No per-provider show exists.
• Registry results are opt-in, stay separate from normal stash hits, and live in registryHits, never hits.
• All write-target branching by source.kind belongs in src/core/write-source.ts.
• Write-target resolution order is --target -> defaultWriteTarget -> working stash (defaultBundle); there is no fallback to the first writable source.
• writable defaults to true on filesystem and false on git / website / npm; writable: true on website or npm is rejected at config load.