akm-cli 0.9.29 → 0.9.31

package/docs/README.md

@@ -6,16 +6,17 @@ start here, then follow links out to the guides, reference, and architecture
 pages as you need more depth. Each subdirectory also has its own README
 indexing everything inside it.
 
-Full per-directory indexes: [Guides](https://github.com/itlackey/akm/blob/main/docs/guides/README.md),
-[Reference](reference/README.md), [Agents](https://github.com/itlackey/akm/blob/main/docs/agents/README.md),
-[Architecture](https://github.com/itlackey/akm/blob/main/docs/architecture/README.md), [Migration](migration/README.md).
+Full per-directory indexes: [Guides](guides/README.md),
+[Reference](reference/README.md), [Agents](agents/README.md),
+[Architecture](architecture/README.md), [Maintainers](maintainers/README.md),
+[Migration](migration/README.md), [Posts](posts/README.md).
 
 ## Start
 
-- [Product Surface](https://github.com/itlackey/akm/blob/main/docs/product-surface.md) -- Every feature and its status
-- [Getting Started](https://github.com/itlackey/akm/blob/main/docs/guides/getting-started.md) -- Install akm, connect a source, and pull a curated shortlist in five to seven minutes
-- [Concepts](https://github.com/itlackey/akm/blob/main/docs/guides/concepts.md) -- Capabilities, bundles, adapters, asset types, and refs -- the mental model in one page
-- [Agent Install Guide](https://github.com/itlackey/akm/blob/main/docs/agents/agent-install.md) -- Step-by-step automated (non-interactive) install for agents
+- [Product Surface](product-surface.md) -- Every feature and its status
+- [Getting Started](guides/getting-started.md) -- Install akm, connect a source, and pull a curated shortlist in five to seven minutes
+- [Concepts](guides/concepts.md) -- Capabilities, bundles, adapters, asset types, and refs -- the mental model in one page
+- [Agent Install Guide](agents/agent-install.md) -- Step-by-step automated (non-interactive) install for agents
 - `akm help agents` (short guide by default; `akm help agents --full` for the complete guide) -- The CLI reference agents load to use akm; always the embedded corpus at `src/assets/hints/cli-hints-{full,short}.md`
 
 ## Use
@@ -23,34 +24,34 @@ Full per-directory indexes: [Guides](https://github.com/itlackey/akm/blob/main/d
 One library for every agent: connect what you already have, load only what
 the task needs, and capture what you learn along the way.
 
-- [Use AKM With Any Agent](https://github.com/itlackey/akm/blob/main/docs/guides/use-with-any-agent.md) -- Wire akm into Claude Code, OpenCode, Cursor, and other coding assistants with a three-line system prompt block
-- [Discover and Load](https://github.com/itlackey/akm/blob/main/docs/guides/discover-and-load.md) -- Search, curate a shortlist, and load exactly the ref a task needs
-- [Bundles](https://github.com/itlackey/akm/blob/main/docs/guides/bundles.md) -- Connect local dirs, git repos, npm packages, and websites; browse the registry
-- [Capture Knowledge](https://github.com/itlackey/akm/blob/main/docs/guides/capture-knowledge.md) -- `akm remember`, `akm import`, and how captured material becomes available to every agent
-- [Wikis](https://github.com/itlackey/akm/blob/main/docs/guides/wikis.md) -- Multi-wiki knowledge bases (Karpathy-style)
-- [Environment & Secrets](https://github.com/itlackey/akm/blob/main/docs/reference/env-and-secrets.md) -- `akm env` and `akm secret`: exact operations, file modes, and the security guarantee
-- [Run Workflows](https://github.com/itlackey/akm/blob/main/docs/guides/run-workflows.md) -- Start or continue a run, check on it, resume it, or abandon it
-- [Scheduling](https://github.com/itlackey/akm/blob/main/docs/guides/scheduling.md) -- Run akm tasks through the OS scheduler (cron / launchd / schtasks) safely
+- [Use AKM With Any Agent](guides/use-with-any-agent.md) -- Wire akm into Claude Code, OpenCode, Cursor, and other coding assistants with a three-line system prompt block
+- [Discover and Load](guides/discover-and-load.md) -- Search, curate a shortlist, and load exactly the ref a task needs
+- [Bundles](guides/bundles.md) -- Connect local dirs, git repos, npm packages, and websites; browse the registry
+- [Capture Knowledge](guides/capture-knowledge.md) -- `akm remember`, `akm import`, and how captured material becomes available to every agent
+- [Wikis](guides/wikis.md) -- Multi-wiki knowledge bases (Karpathy-style)
+- [Environment & Secrets](reference/env-and-secrets.md) -- `akm env` and `akm secret`: exact operations, file modes, and the security guarantee
+- [Run Workflows](guides/run-workflows.md) -- Start or continue a run, check on it, resume it, or abandon it
+- [Scheduling](guides/scheduling.md) -- Run akm tasks through the OS scheduler (cron / launchd / schtasks) safely
 - [Migrate to 0.9.2](migration/v0.9.1-to-v0.9.2.md) -- Convert task-v2 sources safely and understand workflow resume compatibility
-- [Improve the Library](https://github.com/itlackey/akm/blob/main/docs/guides/improve-the-library.md) -- Feedback, history, and proposals -- how evidence turns into reviewable changes
-- Recipes: [Turn a Website into a Searchable Bundle](https://github.com/itlackey/akm/blob/main/docs/guides/recipes/website-source.md), [Headless Install](https://github.com/itlackey/akm/blob/main/docs/guides/recipes/headless-install.md)
+- [Improve the Library](guides/improve-the-library.md) -- Feedback, history, and proposals -- how evidence turns into reviewable changes
+- Recipes: [Turn a Website into a Searchable Bundle](guides/recipes/website-source.md), [Headless Install](guides/recipes/headless-install.md)
 
 ## Build and operate
 
 Package complete capabilities and turn knowledge into repeatable work.
 
-- [Bundle Author's Guide](https://github.com/itlackey/akm/blob/main/docs/guides/author-bundles.md) -- Build a bundle, make it discoverable, and share it so others can install it with `akm bundle add`
-- [Author's Guide: Writing Workflows](https://github.com/itlackey/akm/blob/main/docs/guides/author-workflows.md) -- Write and test a workflow definition, from a minimal example to gates and outputs
-- [Claude Code workflows vs. akm workflows](https://github.com/itlackey/akm/blob/main/docs/guides/claude-code-vs-akm-workflows.md) -- Short decision guide for choosing between a session-native workflow and an akm workflow ([full technical comparison](https://github.com/itlackey/akm/blob/main/docs/architecture/comparisons/claude-code-vs-akm-workflows-full.md))
+- [Bundle Author's Guide](guides/author-bundles.md) -- Build a bundle, make it discoverable, and share it so others can install it with `akm bundle add`
+- [Author's Guide: Writing Workflows](guides/author-workflows.md) -- Write and test a workflow definition, from a minimal example to gates and outputs
+- [Claude Code workflows vs. akm workflows](guides/claude-code-vs-akm-workflows.md) -- Short decision guide for choosing between a session-native workflow and an akm workflow ([full technical comparison](architecture/comparisons/claude-code-vs-akm-workflows-full.md))
 - [Bundling akm](integration/bundling-akm.md) -- Ship akm inside your own product: the pin/migrate/health boot contract, plan JSON shapes, and exit codes for bundlers
 
 ### Maintainers
 
 Working on akm itself, not just using it.
 
-- [Maintainer Docs](https://github.com/itlackey/akm/blob/main/docs/maintainers/README.md) -- Start here: local development, measuring improvement, and the curate contract
-- [Local Development](https://github.com/itlackey/akm/blob/main/docs/maintainers/local-development.md) -- Dogfooding akm while editing its own source
-- [Curate Workmap](https://github.com/itlackey/akm/blob/main/docs/maintainers/curate-workmap.md) -- The current `akm curate` contract and the highest-value next fixes
+- [Maintainer Docs](maintainers/README.md) -- Start here: local development, measuring improvement, and the curate contract
+- [Local Development](maintainers/local-development.md) -- Dogfooding akm while editing its own source
+- [Curate Workmap](maintainers/curate-workmap.md) -- The current `akm curate` contract and the highest-value next fixes
 
 ## Look up details
 
@@ -58,24 +59,24 @@ Working on akm itself, not just using it.
 - [Configuration](reference/configuration.md) -- Engines, strategies, bundles, and settings
 - [Supported Formats](reference/supported-formats.md) -- Every bundle format akm recognizes, its detection marker, and current read/write support
 - [Tasks](reference/tasks.md) -- Task-v3 files, targets, triggers, and fail-closed migration
-- [Asset Types](https://github.com/itlackey/akm/blob/main/docs/reference/asset-types.md) -- The capability taxonomy, directory conventions, and per-type examples
-- [Refs](https://github.com/itlackey/akm/blob/main/docs/reference/refs.md) -- The ref grammar `akm search` emits and `akm show` consumes
-- [Memory](https://github.com/itlackey/akm/blob/main/docs/reference/memory.md) -- The `memory` asset type: capture, belief states, and derived memories
+- [Asset Types](reference/asset-types.md) -- The capability taxonomy, directory conventions, and per-type examples
+- [Refs](reference/refs.md) -- The ref grammar `akm search` emits and `akm show` consumes
+- [Memory](reference/memory.md) -- The `memory` asset type: capture, belief states, and derived memories
 - [Workflow Schema](reference/workflow-schema.md) -- Authoritative frontmatter/body syntax for a workflow asset
 - [Workflows (overview)](reference/workflows.md) -- Short map across the workflow schema, engine, and how-to guides
-- [Registry](https://github.com/itlackey/akm/blob/main/docs/reference/registry.md) -- Registries, search, hosting, and managing sources
-- [Website Sources](https://github.com/itlackey/akm/blob/main/docs/reference/website-sources.md) -- The pluggable fetcher API for URL-based knowledge reads
+- [Registry](reference/registry.md) -- Registries, search, hosting, and managing sources
+- [Website Sources](reference/website-sources.md) -- The pluggable fetcher API for URL-based knowledge reads
 - [Data & Telemetry](reference/data-and-telemetry.md) -- Exactly what akm reads and writes on your machine (no remote telemetry)
-- [Architecture](https://github.com/itlackey/akm/blob/main/docs/architecture/architecture.md) -- How akm's bundles, cache, index, and registries fit together
-- [Core Principles](https://github.com/itlackey/akm/blob/main/docs/architecture/akm-core-principles.md) -- Design principles and constraints
-- [Adapters](https://github.com/itlackey/akm/blob/main/docs/architecture/adapters.md) -- How akm picks an adapter, indexes, validates, and writes into a bundle
-- [The Workflow Engine](https://github.com/itlackey/akm/blob/main/docs/architecture/workflow-engine.md) -- How a frozen plan is stored, dispatched, and resumed without replaying completed units
-- [The Improvement Loop](https://github.com/itlackey/akm/blob/main/docs/architecture/improvement.md) -- How a feedback signal becomes a ranking change, and how evidence becomes a proposal
-- [Runtime Boundary Design](https://github.com/itlackey/akm/blob/main/docs/architecture/runtime-boundary-design.md) -- Isolating `bun:sqlite`/`Bun.*` from the core
-- [Architecture Decision History](https://github.com/itlackey/akm/blob/main/docs/architecture/akm-architecture-decision-history.md) -- ADR-style record of the major architecture rulings
-- [Specs](https://github.com/itlackey/akm/blob/main/docs/architecture/README.md#specs-specs) -- Normative specifications (bundle/adapter model, ref grammar, bundle conventions)
-- [Internals](https://github.com/itlackey/akm/blob/main/docs/architecture/README.md#internals-internals) -- Current-truth subsystem references (storage, search, indexing, improve, health)
-- [Testing](https://github.com/itlackey/akm/blob/main/docs/architecture/README.md#testing-testing) -- Testing workflow and pre-release checklist
+- [Architecture Overview](architecture/architecture.md) -- How akm's bundles, cache, index, and registries fit together
+- [Core Principles](architecture/akm-core-principles.md) -- Design principles and constraints
+- [Adapters](architecture/adapters.md) -- How akm picks an adapter, indexes, validates, and writes into a bundle
+- [The Workflow Engine](architecture/workflow-engine.md) -- How a frozen plan is stored, dispatched, and resumed without replaying completed units
+- [The Improvement Loop](architecture/improvement.md) -- How a feedback signal becomes a ranking change, and how evidence becomes a proposal
+- [Runtime Boundary Design](architecture/runtime-boundary-design.md) -- Isolating `bun:sqlite`/`Bun.*` from the core
+- [Architecture Decision History](architecture/akm-architecture-decision-history.md) -- ADR-style record of the major architecture rulings
+- [Specs](architecture/README.md#specs-specs) -- Normative specifications (bundle/adapter model, ref grammar, bundle conventions)
+- [Internals](architecture/README.md#internals-internals) -- Current-truth subsystem references (storage, search, indexing, improve, health)
+- [Testing](architecture/README.md#testing-testing) -- Testing workflow and pre-release checklist
 - [Migration](migration/README.md) -- Upgrade guides and per-release migration notes
 - [Roadmap](https://github.com/itlackey/akm/blob/main/ROADMAP.md) -- High-level focus for the releases from here through 1.0
 
@@ -85,14 +86,14 @@ AKM retrieves every supported capability type. It directly orchestrates
 defined execution surfaces such as workflows, agent dispatch, tasks, and
 guarded subprocess injection. It does not blindly execute arbitrary indexed
 content merely because that content appears in search results. See
-[Core Principles](https://github.com/itlackey/akm/blob/main/docs/architecture/akm-core-principles.md) for the full boundary,
-and [The Improvement Loop](https://github.com/itlackey/akm/blob/main/docs/architecture/improvement.md) for how that boundary
+[Core Principles](architecture/akm-core-principles.md) for the full boundary,
+and [The Improvement Loop](architecture/improvement.md) for how that boundary
 applies to akm's own self-generated changes.
 
 ## Posts
 
 Source articles for the dev.to publishing pipeline (historical record). See
-[docs/posts/README.md](https://github.com/itlackey/akm/blob/main/docs/posts/README.md).
+[posts index](posts/README.md).
 
 ## Official Ecosystem Repositories
 

package/docs/agents/README.md

@@ -0,0 +1,15 @@
+# Agents
+
+Documentation for wiring AI agents into akm.
+
+Run `akm hints` for the complete CLI reference agents should load into a
+system prompt, or `akm help agents` for the compact guide.
+(the short form is the default; pass `--full` for the complete guide). It always prints the embedded
+corpus at `src/assets/hints/cli-hints-full.md` / `cli-hints-short.md` --
+browse those files directly if you want to read the reference without running
+the CLI. There used to be a separate `docs/agents/AGENTS.md` /
+`AGENTS.full.md` pair here; it fed nothing at runtime after R-006 and kept
+re-diverging from the embedded copy with no test to catch it, so it was
+deleted and its still-true unique content was merged into the embedded files.
+
+- [Agent Install Guide](agent-install.md) -- Short redirect covering the install shape (binary, `akm setup --yes`, a source, an index, `akm help agents`); for the exact no-prompts command sequence, see the [headless install recipe](../guides/recipes/headless-install.md)

package/docs/agents/agent-install.md

@@ -0,0 +1,14 @@
+# Agent Install Guide
+
+`akm` is a portable capability library agents install and configure without
+interactive prompts: install the binary, run `akm setup --yes`, add a source,
+build the index, then expose `akm help agents` output to the agent so it
+knows how to search and load bundle content. Configuration lives in
+top-level keys validated against the config schema, and semantic search can
+run on local embeddings or a remote endpoint depending on what the host
+supports.
+
+For the exact command sequence — install, setup, semantic-search
+configuration, adding sources, indexing, verification, and installing agent
+guidance into `AGENTS.md` — see the
+[headless install recipe](../guides/recipes/headless-install.md).

package/docs/architecture/README.md

@@ -0,0 +1,67 @@
+# Architecture Index
+
+How akm is built: system overview, normative specs, decision history, and
+subsystem internals.
+
+- [Architecture](architecture.md) -- How akm's bundles, cache, index, and registries fit together
+- [Core Principles](akm-core-principles.md) -- Design principles and constraints
+- [Adapters](adapters.md) -- The `BundleAdapter` contract: what a bundle's files *are*, how they're indexed, linted, and written
+- [Architecture: The Workflow Engine](workflow-engine.md) -- How a workflow compiles to a frozen plan, persists run/unit state, dispatches work, and resumes without replaying completed steps
+- [Architecture: The Improvement Loop](improvement.md) -- Purpose and boundary of the improvement loop
+- [Runtime Boundary Design](runtime-boundary-design.md) -- Isolating `bun:sqlite`/`Bun.*` from the core
+- [Architecture Decision History](akm-architecture-decision-history.md) -- ADR-style record of the major architecture rulings
+
+## Specs (`specs/`)
+
+Normative specifications and binding conventions.
+
+- [OKF format support](specs/okf-support.md) -- OKF is a first-class format supported through the built-in `okf` adapter
+- [0.9.0 surface decisions](specs/0.9.0-decisions.md) -- The decision record (D1-D12) behind the 0.9.0 breaking changes
+- [Bundle & Adapter Spec (0.9.0)](specs/akm-0.9.0-bundle-adapter-spec.md) -- Normative spec for bundles, adapters, and bundle recognition
+- [Ref Grammar Decision (0.9.0)](specs/akm-0.9.0-ref-grammar-decision.md) -- The `[bundle//]conceptId` ref grammar
+- [Ref Format](specs/ref.md) -- Wire format for asset references
+- [Format-Neutral Bundle Workspace Spec](specs/akm-format-neutral-bundle-workspace-spec.md) -- The format-neutral workspace model
+- [Agent, Command, Engine, and Model Resolution](specs/agent-command-engine-model-design.md) -- Approved target semantics for native agent/command bundles, configuration cascading, model maps, and dispatch
+- [0.9.2 Agent/Command/Task/Workflow Implementation Plan](../plans/0.9.2-agent-command-workflow-plan.md) -- Sequenced work packages, [GitHub milestone tracker](https://github.com/itlackey/akm/issues/801), migration rules, support boundaries, and release evidence for the coherent execution MVP
+- [Fact Asset Type](specs/fact-asset-type.md) -- The `fact` asset type
+- [Bundle Conventions Code Spec](specs/stash-conventions-code-spec.md) -- Code-level bundle conventions
+- [Bundle Organization Conventions](specs/stash-organization-conventions.md) -- How a bundle is laid out
+- [DI Seams Plan](specs/di-seams-plan.md) -- Dependency-injection seams used by the test suite
+- [Improve Collapse/Churn Detector](specs/improve-collapse-churn-detector-design.md) -- Longitudinal collapse/churn detection design (§6.3 is the operator runbook referenced by `akm health`)
+
+Historical review registers (0.9.0 release-review audit trail, kept for provenance, not normative going forward):
+
+- [0.9.0 Docs–Code Drift Register](specs/0.9.0-docs-code-drift-register.md) -- Ruled record of places documentation and code disagreed, and open-intent questions (Q-01..Q-19)
+- [0.9.0 Public API Issue Backlog](specs/0.9.0-public-api-issue-backlog.md) -- Implementation-only findings from the CLI surface review
+- [0.9.0 Release Surface Review](specs/0.9.0-release-surface-review.md) -- Reconciled action list from the end-to-end user-facing surface sweep
+
+## Internals (`internals/`)
+
+Current-truth subsystem references.
+
+- [Storage Locations](internals/storage-locations.md) -- Authoritative inventory of every on-disk read/write path
+- [Search](internals/search.md) -- Hybrid search architecture and scoring
+- [Indexing](internals/indexing.md) -- How the search index is built
+- [Classification](internals/classification.md) -- Matcher and renderer behavior
+- [Improve Workflow](internals/improve-workflow.md) -- `akm improve` command surface and pipeline reference
+- [Health Advisories](internals/health-advisories.md) -- `akm health` advisory-to-action map for operators
+- [Registry Network Boundary](internals/registry-network-boundary.md) -- Outbound registry request inventory, destination policy, redirects, and DNS guarantees
+- [Functional Contract Patterns](internals/functional-contract-patterns.md) -- Quick reference for contributor pipelines and small process contracts
+- [Fresh-Host Rebuild Runbook](internals/fresh-host-rebuild-runbook.md) -- Rebuild an akm install on a new machine
+- [Persisted-Data Compatibility Contract](persisted-data-compat.md) -- What a reader owes data an earlier release wrote, per persisted format
+
+## Reviews (`reviews/`)
+
+Point-in-time architecture reviews of a specific subsystem question.
+
+- [Runtime secret resolution for in-process source fetchers](reviews/env-secret-access.md) -- Why secret reads are injected as a `SecretResolver` capability instead of imported inside the fetcher subgraph
+
+## Comparisons (`comparisons/`)
+
+- [Workflow architecture: Claude Code workflows vs. akm workflows](comparisons/claude-code-vs-akm-workflows-full.md) -- Full technical comparison of the Claude Code `Workflow` tool and akm workflows; see [the short vendor-neutral guide](../guides/claude-code-vs-akm-workflows.md) for the decision-level version
+
+## Testing (`testing/`)
+
+- [Testing Workflow](testing/testing-workflow.md) -- End-to-end, Docker, deployment, and upgrade validation, plus the coverage gap guide
+- [Manual Testing Checklist](testing/manual-testing-checklist.md) -- Pre-release manual QA checklist
+- [OKF v0.2 Conformance Re-Evaluation Runbook](testing/okf-v0.2-conformance-runbook.md) -- Acceptance procedure to re-run after changing adapters, indexing, refs, writes, or lint behavior

package/docs/architecture/adapters.md

@@ -0,0 +1,272 @@
+# Adapters
+
+A **`BundleAdapter`** (`src/core/adapter/bundle-adapter.ts`) is the code that
+decides what a bundle's files *are*, how they're indexed, how `akm lint`
+validates them, and where a new item would be placed. 0.9.0 ships 11
+built-in adapters — one per format in
+[Supported Formats](../reference/supported-formats.md). This page is the
+write-path and internals reference; that page is the compatibility table.
+
+For read-only native tool bundles, recognition is runtime translation, not
+conversion: the adapter projects native files into AKM's index/runtime shapes
+while the source file remains authoritative. AKM does not synchronize native
+formats, maintain translated canonical copies, or write agent/command assets
+back through the Claude/OpenCode adapters. See
+[Agent, Command, Engine, and Model Resolution](specs/agent-command-engine-model-design.md).
+
+> **Stability note.** The adapter set, bundle-recognition rules, and the
+> `bundles` config shape are still evolving — see [STABILITY.md](../../STABILITY.md).
+
+---
+
+## Probe order
+
+Each bundle root is owned by exactly **one** adapter, decided once at
+install/index time:
+
+1. If the bundle's config entry sets `components.<id>.adapter` explicitly,
+   that adapter wins — no detection runs.
+2. Otherwise, every built-in adapter's `looksLikeRoot(root)` probe runs in a
+   **fixed order**, most-specific markers first. The first probe that
+   returns `true` claims the root.
+3. If no probe fires, the bundle falls back to the `akm` adapter.
+
+The order is pinned by `BUILTIN_ADAPTERS` (`src/core/adapter/adapters/index.ts`)
+and enforced by the conformance suite's ordered-owner matrix — it, not any
+prose spec listing, is authoritative:
+
+```text
+website-snapshot   -- root manifest.json {url, fetchedAt}
+agent-skills       -- a <name>/SKILL.md package at the bundle root
+claude             -- root CLAUDE.md + commands/|agents/|skills/
+opencode           -- opencode.json(c), or root AGENTS.md + a tool dir
+dotenv             -- every top-level dir is env/ and/or secrets/
+akm-workflow       -- a top-level .md with explicit type: workflow
+akm-task           -- a top-level valid task source v4 .yml (schedule optional)
+llm-wiki           -- root schema.md + pages/
+akm                -- .stash marker, or 2+ native subdirs, or fallback
+okf                -- root index.md, or any .md with frontmatter type
+generic-files      -- never auto-selected; explicit config only
+```
+
+The rationale for the ordering:
+
+- The three loosest probes — `llm-wiki`, `akm`, and `okf` — stay **last**.
+  Native AKM evidence wins before OKF because AKM Markdown is an OKF
+  superset; the `akm` probe is strict enough not to claim an OKF bundle
+  merely because it contains one familiar directory name.
+- `akm.looksLikeRoot` fires on any root carrying a bundle-subdir-named
+  directory — which includes a `.claude`/`.opencode` tool dir (`commands/`,
+  `agents/`, `skills/`) and a dotenv bundle (`env/`, `secrets/`). So
+  `claude`/`opencode`/`dotenv` come **ahead of** `akm`; their tighter markers
+  claim those roots first, and `akm` still wins its own workspace root
+  (which those tighter probes reject).
+- `website-snapshot`, `agent-skills`, `akm-workflow`, and `akm-task` carry
+  disjoint, specific markers that fire on none of the other roots, so they
+  sit at the front for clarity.
+- `generic-files` is explicit-config-only — its `looksLikeRoot` never fires —
+  so it's last and can never shadow anything.
+
+---
+
+## `BundleAdapter` interface contract
+
+Transcribed from `src/core/adapter/bundle-adapter.ts`:
+
+```ts
+interface BundleAdapter {
+  readonly id: string;
+  readonly version: string;              // feeds incrementality + fingerprints
+  readonly extensions: readonly string[]; // longest-match stripping + collision priority
+
+  // REQUIRED — single-file recognition primitive.
+  recognize(c: BundleComponent, file: FileContext): IndexDocument | null;
+
+  // OPTIONAL — full-component scan for non-per-file layouts (website
+  // snapshots, llm-wiki multi-file semantics). Absent -> the core walk
+  // (git-aware, symlink-safe, skip-dirs) drives recognize() per file.
+  index?(inst: BundleInstallation, c: BundleComponent): AsyncIterable<IndexDocument>;
+
+  // OPTIONAL — item-scoped incrementality. Default: identity (one file = one item).
+  affectedItems?(c: BundleComponent, changedPaths: string[]): string[];
+
+  // REQUIRED — native validation (change-transaction pre-commit + lint --fix).
+  // Adapters MUST NOT write and MUST NOT read the live filesystem: ctx serves
+  // a run snapshot with pending changes overlaid, plus a read-only
+  // resolveRef for link/xref existence.
+  validate(c: BundleComponent, changes: FileChange[], ctx: ValidateContext): Promise<Diagnostic[]>;
+
+  // OPTIONAL — the CLOSED-FORM set of existing-file placements/read aliases
+  // that could own `conceptId`, used for first-owner arbitration without
+  // reading authored bytes or walking the bundle.
+  readCandidates?(c: BundleComponent, conceptId: string): Array<{ path: string; conceptId: string }>;
+
+  // OPTIONAL — placement / discovery.
+  placeNew?(c: BundleComponent, conceptId: string): string;   // where a new item would live
+  directoryList?(c: BundleComponent): string[];               // owned dirs; feeds git exact-path staging
+  looksLikeRoot?(root: string): boolean;                      // install-time probe
+}
+```
+
+`recognize` and `validate` are required on every adapter; `index`,
+`affectedItems`, `readCandidates`, `placeNew`, `directoryList`, and
+`looksLikeRoot` are optional capability methods. An adapter overriding `index()` must keep
+`recognize()` coherent with it (conformance: `index()` == fold of
+`recognize()` over the core walk) or declare component-level
+incrementality.
+
+`readCandidates` is intentionally distinct from both `extensions` and
+`placeNew`: extensions are non-exhaustive walk hints, while placement is a
+write-normalization policy. Read candidates preserve canonical directory
+manifests (for example `skills/<name>/SKILL.md`) so lookup, index-backed show, and workflow runtime share one
+physical-owner decision. Each candidate carries its canonical concept identity,
+so a byte-denying ownership probe never has to infer identity from the query.
+Path-derived recognition (`toCanonicalName`/`toAssetPath`, `src/core/asset/asset-placement.ts`)
+is a deterministic function of a file's path, so its inverse — every physical
+spelling that could own one conceptId — is computable in CLOSED FORM (#857):
+the canonical placement under the type's own bundle subdir, the loose
+off-canonical placement (an authored path elsewhere in the bundle, keyed off
+its full path relative to the bundle root instead of the type subdir — this
+is what `readCandidates` returns for it), and any type-specific duality (for
+example `env`'s `.env`/`<name>.env` spellings for the "default" alias).
+`readCandidates` enumerates the complete closed-form set directly from the
+conceptId; no bundle walk is needed, so no scan bound applies. The shared
+authority (`src/indexer/lookup/adapter-concept-owner.ts`) still probes every
+candidate with a byte-denying `FileContext` before trusting it, so an
+adapter returning a candidate the file does not actually own is harmless —
+it is simply filtered out.
+
+The core walk — the live indexer's per-dir walk, drained by
+`drainDirDocuments` — is one implementation carrying the security policy
+(symlink-safety, skip-dirs, git-awareness); adapters never reimplement it.
+
+Cross-component ref existence is a **core** base check, not an adapter
+concern.
+
+---
+
+## `placeNew()` wiring status
+
+The interface declares `placeNew()` as an optional capability method, and 9
+of the 11 built-in adapters already implement it — all but `okf` and
+`website-snapshot` (`claude` and `opencode` inherit theirs from the shared
+tool-dir factory). **Nothing in the write path calls it yet**: AKM-native
+writes still resolve through AKM's own flat type→directory placement table
+(`src/core/asset/asset-placement.ts`'s `PLACEMENT_SPECS`), not through the
+owning adapter's `placeNew()`.
+
+Placement for every existing bundle is already correct today — this is a
+deliberately sequenced routing change, not unfinished behavior. It's
+scoped out of 0.9.0 by
+[D12](../architecture/specs/0.9.0-decisions.md#d12--bundleadapterplacenew-stays-unwired-until-010)
+and deferred to 0.10; nothing user-visible changes in 0.10 for this alone.
+See [STABILITY.md](../../STABILITY.md) ("On the horizon") for the
+up-to-date status if this changes.
+
+---
+
+## Write allowlists
+
+`placeNew()` wiring is a separate question from **which bundles AKM-native
+write commands are allowed to touch at all** — that's decided today by a
+small allowlist check, `assertAkmAssetWrite` (`src/core/write-source.ts`),
+run before any write command touches the filesystem. It compares the target
+bundle's detected (or configured) adapter id against an allowlist and throws
+a `UsageError` on a miss.
+
+The default allowlist is `["akm"]`. Two command families widen it explicitly:
+
+| Command | Allowlist adds |
+| --- | --- |
+| `akm env create` / `env remove` / `secret set` | `dotenv` |
+| `akm workflow create` | `akm-workflow` |
+
+Every other adapter — including every adapter that already implements
+`placeNew()` (`agent-skills`, `claude`, `opencode`, `akm-task`,
+`generic-files`) — is rejected by every AKM-native write command in 0.9.0.
+`akm task add` in particular uses the *default* allowlist (`akm` only), so a
+standalone `akm-task` bundle is read-only through AKM-native write commands
+even though `akm-task`'s own `placeNew()` is implemented.
+
+Reading, searching, and `akm lint` are unaffected by this allowlist — only
+creating, editing, or deleting through AKM's own commands is restricted.
+"Read-only" in [Supported Formats](../reference/supported-formats.md) means
+this write-command restriction, not a filesystem permission.
+
+This allowlist boundary is also where AKM's [execution
+boundary](../guides/concepts.md) principle shows up on the write side: AKM
+retrieves and validates every supported format, but it only lets its own
+write commands mutate a narrow, explicitly-declared set of targets — it
+does not widen write access to a format just because that format's adapter
+happens to expose a `placeNew()` implementation.
+
+---
+
+## Task adapter
+
+The native and standalone `akm-task` paths delegate to the authoritative task
+source parser, `parseTaskSource`, which accepts only `version: 4` (task
+source v4). A task source v4 document declares exactly one executable
+selector (`uses` or `run`), but its scheduling is OPTIONAL — a document with
+no `schedule:` is valid and runnable manually. A `version: 3` or `version: 2`
+document is no longer read by `src` at all: it fails closed with
+`TASK_SCHEMA_VERSION_UNSUPPORTED`, naming `akm migrate` as the path forward.
+See [Tasks](../reference/tasks.md) for the public source contract and the
+migration path.
+
+---
+
+## Implementation caveats
+
+A few adapter-specific behaviors are easy to assume differently from how
+they actually work:
+
+- **`agent-skills` recognition/validation are decoupled.** The per-change
+  half of `validate()` only inspects changes that resolve to an actual
+  `SKILL.md`, so an invalid skill is still indexed as `skill` (with its raw,
+  invalid name projected) and its field violations surface only for files
+  that exist. `missing-skill-md` is the exception and runs as a separate
+  directory pass over `ValidateContext.list`: a **top-level** directory that
+  holds files but no `SKILL.md` anywhere within three levels is flagged. A
+  package's own resource dirs (`pdf-processing/reference/`) are part of the
+  item, not candidate packages, and are never considered.
+- **`claude`/`opencode` share one codec** (`tool-dir-shared.ts`) and differ
+  only in instruction filename and adapter/component ids. Both accept only
+  the canonical plural tool directories.
+- **`dotenv` redaction is a hard, adapter-level contract.** No frontmatter
+  `type:` override can bypass it: `env` entries surface only key names,
+  `secret` entries surface only the file name, never content. A `.env`
+  file placed under `secrets/` is a secret (name-only), not an env group —
+  the directory gate wins over the `.env` suffix.
+- **Task adapters share one task source parser.** A standalone `akm-task`
+  bundle and task files owned by the native `akm` adapter both route through
+  `parseTaskSource`, which accepts only `version: 4` (task source v4) — a
+  `version: 3` or `version: 2` document fails closed with
+  `TASK_SCHEMA_VERSION_UNSUPPORTED` and is never indexed, validated, or run.
+  Task source v4 requires exactly one `uses` or `run` executable selector,
+  but its `schedule:` is OPTIONAL. It recognizes `akm/command`, `commands/`,
+  `workflows/`, and `scripts/` targets, refuses the github-action `uses:`
+  variant entirely (removed in v4 — no equivalent spelling), and refuses
+  agent/task refs and unsupported actions. `.yaml` is a collection hint only:
+  recognition still gates on `.yml`, so the near miss is diagnosed but never
+  indexed or scheduled. See the [Tasks reference](../reference/tasks.md).
+- **`llm-wiki`, `akm`, and `okf` all reserve `index.md`/`log.md`** as
+  structural files — never indexed as concepts, never valid write targets —
+  at any depth.
+- **`okf`'s lenient wording is not a lenient gate.** `missing-type` and
+  broken-link findings are labelled `info:`/`warning:` in the diagnostic
+  text, but diagnostics carry no severity field: `akm lint` funnels every
+  finding into one `flagged` list, and `--fail-on-flagged` fails on any
+  non-empty list.
+- **`generic-files` is the only adapter with no auto-detection at all.**
+  `looksLikeRoot` always returns `false`; a bundle only gets this adapter
+  through an explicit `components.<id>.adapter: "generic-files"` override.
+
+---
+
+## See also
+
+- [Supported Formats](../reference/supported-formats.md) — the compatibility table this page's internals back
+- [Asset Types](../reference/asset-types.md) — the `akm` adapter's 14 native asset types
+- [Concepts](../guides/concepts.md) — the retrieval loop and execution boundary these adapters serve
+- [Architecture](architecture.md) — sources, refs, the search pipeline, and the write-source chokepoint