akm: Instructions file for Codex

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.
• Treat enabled: false as inert across content reads, writes, indexing, and execution. Explicit bundle lifecycle commands may still update a named disabled bundle without activating it. Never infer the default/trusted bundle from array position; carry bundle identity and default status explicitly.
• scheduler.enabled is this host's list of scheduled refs (bundle//tasks/x) in memory; on disk it is written in the {kind, ref, sourceId} shape 0.9.16 reads (schedulerEnabledOnDisk, src/core/config/config.ts) until no supported release is strict about it. Removing a bundle drops its refs. A config without the list means "keep what is installed": the first task sync/setup/enable/disable/add after an upgrade takes the akm-written native rows as the choice and writes it (enabledRefsFromInstalled, src/tasks/activation-config.ts). An explicit list, empty or not, is never second-guessed. There are no grants, source identities or fire-time checks.
• extends may share portable policy, but host authority stays local: sources/defaults, registries, scheduler/execution/experimental state, credentials, executable argv/workspace, publication policy, and credential-bearing network connections must not be inherited. Bundle-relative chains require physical (realpath) containment.
• Executable asset frontmatter may request a tool subset but cannot set child workspace, environment, or opaque runtime; tool requests are capped by local execution.allowedTools and must be enforceable by the selected lowerer.
• Harnesses are thin, replaceable internals (core principle 10, docs/architecture/akm-core-principles.md) and are registered in one place (core principle 2): each registers once in HARNESS_REGISTRY, and core code imports the registry, not a harness. Don't spread harness-specific code or concepts into akm core.
• Unsafe CLI overrides name one risk. Use --allow-insecure-transport only for plain HTTP and --allow-dangerous-env-keys only for reviewed process-hijacking environment keys; do not add a combined bypass.