akm-cli 0.10.261016-beta → 0.10.261017-beta

package/dist/storage/repositories/workflow-runs-repository.js

@@ -440,23 +440,25 @@ export class WorkflowRunsRepository {
  * finishes or abandons them — the rename lists them rather than touching them).
  */
 export function countWorkflowRunRefsForRename(db, oldBundleId) {
-    const like = `${escapeLikePattern(oldBundleId)}//%`;
-    const refs = db.prepare(`SELECT COUNT(*) AS n FROM workflow_runs WHERE workflow_ref LIKE ? ESCAPE '\\'`).get(like).n;
+    const prefix = `${oldBundleId}//`;
+    const refs = db
+        .prepare(`SELECT COUNT(*) AS n FROM workflow_runs WHERE substr(workflow_ref, 1, length(?)) = ?`)
+        .get(prefix, prefix).n;
     const active = db
-        .prepare(`SELECT id, workflow_ref AS workflowRef, status FROM workflow_runs WHERE workflow_ref LIKE ? ESCAPE '\\' AND status IN ('active', 'blocked') ORDER BY updated_at DESC, created_at DESC`)
-        .all(like);
+        .prepare(`SELECT id, workflow_ref AS workflowRef, status FROM workflow_runs WHERE substr(workflow_ref, 1, length(?)) = ? AND status IN ('active', 'blocked') ORDER BY updated_at DESC, created_at DESC`)
+        .all(prefix, prefix);
     return { refs, active };
 }
 /**
  * Rewrite every `workflow_runs.workflow_ref` naming `oldBundleId` to
  * `newBundleId` (`akm bundle rename`). A legacy unqualified ref is not matched
- * by the `LIKE` prefix and is left alone. Returns the number of rows rewritten.
+ * by the `<old>//` prefix and is left alone. Returns the number of rows rewritten.
  */
 export function renameWorkflowRunRefs(db, oldBundleId, newBundleId) {
-    const prefix = `${escapeLikePattern(oldBundleId)}//`;
+    const prefix = `${oldBundleId}//`;
     return Number(db
-        .prepare(`UPDATE workflow_runs SET workflow_ref = ? || substr(workflow_ref, length(?) + 1) WHERE workflow_ref LIKE ? ESCAPE '\\'`)
-        .run(newBundleId, oldBundleId, `${prefix}%`).changes);
+        .prepare(`UPDATE workflow_runs SET workflow_ref = ? || substr(workflow_ref, length(?) + 1) WHERE substr(workflow_ref, 1, length(?)) = ?`)
+        .run(newBundleId, oldBundleId, prefix, prefix).changes);
 }
 /**
  * Run `fn` against a {@link WorkflowRunsRepository} bound to state.db

package/docs/README.md

@@ -1,12 +1,8 @@
 # Documentation
 
 AKM is a portable capability library for AI agents: one library for every
-agent. This hub is organized by what you're trying to do, not by directory —
-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](guides/README.md),
+agent. This hub is organized by what you're trying to do. Each subdirectory
+also has its own README indexing everything inside it: [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).
@@ -14,80 +10,50 @@ Full per-directory indexes: [Guides](guides/README.md),
 ## Start
 
 - [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
+- [Getting Started](guides/getting-started.md) -- Install akm, connect a source, and pull a curated shortlist
+- [Concepts](guides/concepts.md) -- Capabilities, bundles, adapters, and refs: the mental model in one page
+- [Agent Install Guide](agents/agent-install.md) -- Automated, non-interactive install for agents
 - [Upgrade from 0.9 to 0.10](migration/v0.9-to-v0.10.md) -- The current upgrade path: the order to follow, every removed CLI spelling, config key and workflow feature with its replacement, and what a scheduled `akm improve` now does
-- `akm hints` (complete guide by default; `akm hints --detail brief` for the short one) -- The CLI reference agents load to use akm; always the embedded corpus at `src/assets/hints/cli-hints-{full,short}.md`
+- `akm hints` -- The CLI guide agents load (complete by default; `akm hints --detail brief` for the short one)
 
 ## Use
 
-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](guides/use-with-any-agent.md) -- Wire akm into Claude Code, OpenCode, Cursor, and other coding assistants with a three-line system prompt block
+- [Use AKM With Any Agent](guides/use-with-any-agent.md) -- Wire akm into Claude Code, OpenCode, Cursor, and other coding assistants
 - [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
+- [Environment & Secrets](reference/env-and-secrets.md) -- `akm env` and `akm secret`: operations and file modes
 - [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
-- [Improve the Library](guides/improve-the-library.md) -- Feedback, history, and proposals -- how evidence turns into reviewable changes
+- [Scheduling](guides/scheduling.md) -- Run akm tasks through the OS scheduler (cron / launchd / schtasks)
+- [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](guides/author-bundles.md) -- Build a bundle, make it discoverable, and share it so others can install it with `akm bundle add`
+- [Bundle Author's Guide](guides/author-bundles.md) -- Build a bundle, make it discoverable, and share it
 - [Author's Guide: Writing Workflows](guides/author-workflows.md) -- Write and test a workflow definition, from a minimal example to gates and outputs
-- [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](maintainers/README.md) -- Start here: local development, the release checklist, and measuring improvement
-- [Local Development](maintainers/local-development.md) -- Dogfooding akm while editing its own source
+- [Bundling akm](integration/bundling-akm.md) -- Ship akm inside your own product: the pin/migrate/health boot contract, plan JSON shapes, and exit codes
+- [Maintainer Docs](maintainers/README.md) -- Local development and the release checklist
 
 ## Look up details
 
 - [CLI](reference/cli.md) -- All `akm` commands and flags
 - [Configuration](reference/configuration.md) -- Connections, harnesses, 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 source v4 files, targets, triggers, and the explicit `akm migrate apply` conversion of v2 and v3 files
 - [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
+- [Tasks](reference/tasks.md) -- Task source v4 files, targets, triggers, scheduling, and the explicit `akm migrate apply` conversion of v2 and v3 files
+- [Workflow Schema](reference/workflow-schema.md) -- Frontmatter and body syntax for a workflow asset
 - [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 Overview](architecture/architecture.md) -- How akm's bundles, cache, index, and registries fit together
-- [Core Principles](architecture/akm-core-principles.md) -- How the code, tests and docs in this repo are built: the engineering rules and what enforces each
-- [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
-- [Specs](architecture/README.md#specs-specs) -- Normative specifications (ref grammar, OKF support)
-- [Internals](architecture/README.md#internals-internals) -- Current-truth subsystem references (storage, indexing, classification, improve, health)
-- [Testing](architecture/README.md#testing-testing) -- Testing workflow
-- [Migration](migration/README.md) -- The current 0.9 to 0.10 upgrade guide, then the historical guides and per-release notes of earlier releases
-
-## Execution boundary
+- [Website Sources](reference/website-sources.md) -- The fetcher API for crawling and importing URLs
+- [Data & Telemetry](reference/data-and-telemetry.md) -- What akm reads and writes on your machine
+- [Architecture](architecture/architecture.md) -- How akm fits together, and the invariants every command keeps; [Core Principles](architecture/akm-core-principles.md) -- How the code, tests and docs in this repo are built; [the architecture index](architecture/README.md) lists the subsystem references
 
-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
-[The Improvement Loop](architecture/improvement.md) for how that boundary
-applies to akm's own self-generated changes.
+## Migration
 
-## Posts
-
-Source articles for the dev.to publishing pipeline (historical record). See
-[posts index](posts/README.md).
+- [Migration](migration/README.md) -- The current 0.9 to 0.10 upgrade guide, then the historical guides and per-release notes of earlier releases
 
 ## Official Ecosystem Repositories
 
@@ -100,9 +66,7 @@ Source articles for the dev.to publishing pipeline (historical record). See
 ---
 
 New docs, in five lines: keep one current-truth doc per subsystem, don't fork a
-second one. Planning, review, and analysis material lives in the untracked
-`.plans/` directory, never under `docs/` -- promote conclusions into the
-current-truth doc or drop them. Normative specs live in
-`docs/architecture/specs/`. Cite code by symbol and memories by search-terms --
-not line numbers or exact refs, both rot. Nothing in `docs/` may reference
-`.plans/`.
+second one. Plans, reviews, and analysis do not live under `docs/`; promote
+conclusions into the current-truth doc or drop them. Normative specs live in
+`docs/architecture/specs/`. Cite code by symbol, not line number; line numbers
+rot. Check every command you document with `bun run lint:doc-examples`.

package/docs/agents/README.md

@@ -3,13 +3,8 @@
 Documentation for wiring AI agents into akm.
 
 Run `akm hints` for the complete CLI reference agents should load into a
-system prompt, or `akm hints --detail brief` for the compact 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.
+system prompt, or `akm hints --detail brief` for the compact guide. Both print
+the guide embedded in the CLI (`src/assets/hints/cli-hints-full.md` and
+`cli-hints-short.md`), so you can also read those files directly.
 
 - [Agent Install Guide](agent-install.md) -- Short redirect covering the install shape (binary, `akm setup --yes`, a source, an index, `akm hints`); for the exact no-prompts command sequence, see the [headless install recipe](../guides/recipes/headless-install.md)

package/docs/architecture/README.md

@@ -1,32 +1,30 @@
 # Architecture Index
 
-How akm is built: system overview, normative specs, and subsystem internals.
+How akm is built.
 
-- [Architecture](architecture.md) -- How akm's bundles, cache, index, and registries fit together
-- [Core Principles](akm-core-principles.md) -- How the code, tests and docs in this repo are built: the engineering rules and what enforces each
-- [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
-
-## Specs (`specs/`)
+## Overview
 
-Normative specifications and binding conventions.
+- [Architecture](architecture.md) -- How bundles, sources, refs, the index, search and show, writes, registries, and the execution boundary fit together
+- [Core Principles](akm-core-principles.md) -- How the code, tests and docs in this repo are built: the engineering rules and what enforces each
+- [Adapters](adapters.md) -- The `BundleAdapter` contract: how a bundle's files are recognized, indexed, linted, and written
+- [The Workflow Engine](workflow-engine.md) -- How a workflow compiles to a frozen plan, persists run and unit state, dispatches work, and resumes without replaying completed steps
+- [The Improvement Loop](improvement.md) -- How feedback changes ranking and the utility signal, how evidence becomes reviewable proposals, and which writes happen without review
+- [Persisted-Data Compatibility](persisted-data-compat.md) -- What a reader owes data an earlier release wrote, per persisted format
 
-- [OKF format support](specs/okf-support.md) -- OKF is a first-class format supported through the built-in `okf` adapter
-- [Ref Format](specs/ref.md) -- Wire format for asset references
+## Specs
 
-## Internals (`internals/`)
+- [Ref Format](specs/ref.md) -- The `[bundle//]conceptId[#fragment]` ref grammar
+- [OKF Format Support](specs/okf-support.md) -- What the built-in `okf` adapter reads, and how OKF relates to AKM Markdown
 
-Current-truth subsystem references.
+## Internals
 
-- [Storage Locations](internals/storage-locations.md) -- Authoritative inventory of every on-disk read/write path
+- [Storage Locations](internals/storage-locations.md) -- Where akm reads and writes on disk
 - [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
+- [Classification](internals/classification.md) -- How adapters recognize files and pick renderers
+- [Improve Workflow](internals/improve-workflow.md) -- `akm improve` command surface and per-step pipeline reference
+- [Health Advisories](internals/health-advisories.md) -- The `akm health` checks and what to do about each
 - [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
 
-## Testing (`testing/`)
+## Testing
 
-- [Testing Workflow](testing/testing-workflow.md) -- End-to-end, Docker, deployment, and upgrade validation, plus the coverage gap guide
+- [Testing Workflow](testing/testing-workflow.md) -- Test layers, isolation rules, Docker and upgrade validation

package/docs/architecture/adapters.md

@@ -2,7 +2,7 @@
 
 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
+validates them, and where a new item would be placed. akm 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.
@@ -11,8 +11,8 @@ 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. Execution of agent and command
-assets is described in [Architecture: Connections and Harnesses](architecture.md#connections-and-harnesses).
+back through the Claude/OpenCode adapters. Execution of agent and command assets
+is described in [Architecture: Connections and Harnesses](architecture.md#connections-and-harnesses).
 
 > **Stability note.** The adapter set, bundle-recognition rules, and the
 > `bundles` config shape are still evolving — see [STABILITY.md](../../STABILITY.md).
@@ -31,9 +31,9 @@ install/index time:
    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:
+The order is the array order of `BUILTIN_ADAPTERS`
+(`src/core/adapter/adapters/index.ts`), pinned by
+`tests/core/adapter/registry.test.ts`:
 
 ```text
 website-snapshot   -- root manifest.json {url, fetchedAt}
@@ -42,7 +42,7 @@ 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)
+akm-task           -- a top-level task source .yml (v4, or a v2/v3 file awaiting migration)
 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
@@ -91,15 +91,19 @@ interface BundleAdapter {
   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
+  // Adapters do not write and do 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 — runtime translation for executable agent/command assets: returns
+  // the frontmatter-free command or persona source the execution boundary uses.
+  renderExecutionSource?(c: BundleComponent, file: FileContext): AdapterRenderedExecutionSource | null;
+
   // 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 }>;
+  readCandidates?(c: BundleComponent, conceptId: string): AdapterReadCandidate[]; // { path, conceptId }
 
   // OPTIONAL — discovery.
   directoryList?(c: BundleComponent): string[];               // owned dirs; feeds git exact-path staging
@@ -108,7 +112,7 @@ interface BundleAdapter {
 ```
 
 `recognize` and `validate` are required on every adapter; `index`,
-`affectedItems`, `readCandidates`, `directoryList`, and
+`affectedItems`, `renderExecutionSource`, `readCandidates`, `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
@@ -121,7 +125,7 @@ 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):
+spelling that could own one conceptId — is computable in closed form:
 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
@@ -135,8 +139,8 @@ 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.
+`drainDirDocuments` — is one implementation (symlink handling, skipped
+directories, git awareness); adapters do not reimplement it.
 
 Cross-component ref existence is a **core** base check, not an adapter
 concern.
@@ -157,9 +161,9 @@ writable bundles in another layout would need it back: see
 
 ## Write allowlists
 
-Which bundles AKM-native write commands are allowed to touch at all is decided by a
-small allowlist check, `assertAkmAssetWrite` (`src/core/write-source.ts`),
-run before any write command touches the filesystem. It compares the target
+Which bundles AKM-native write commands may touch is decided 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.
 
@@ -180,11 +184,9 @@ 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 it can read it.
+AKM retrieves and validates every supported format, but its own write
+commands mutate only the targets on the allowlist; being able to read a format
+does not add it.
 
 ---
 
@@ -193,10 +195,15 @@ does not widen write access to a format just because it can read it.
 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
+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.
+document is not read: it raises `TASK_SCHEMA_VERSION_UNSUPPORTED`, naming
+`akm migrate apply`, which converts it. The `akm-task` probe still recognizes a
+root of v2/v3 task files so the migrator can find them. Targets are
+`akm/command` and canonical `commands/`, `workflows/`, and `scripts/` refs;
+the github-action `uses:` variant, agent refs, and task refs are refused.
+`.yaml` is a collection hint only: recognition gates on `.yml`, so a `.yaml`
+near miss is diagnosed (`invalid-task-yaml`) but never indexed or scheduled.
 See [Tasks](../reference/tasks.md) for the public source contract and the
 migration path.
 
@@ -219,26 +226,16 @@ they actually work:
 - **`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.
+- **`dotenv` redaction is keyed on the adapter.** A frontmatter `type:` does
+  not change it: `env` entries surface only key names and `secret` entries
+  surface only the file name. A `.env` file placed under `secrets/` is a secret
+  (name-only), not an env group — the directory 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.
+  `parseTaskSource` (see [Task adapter](#task-adapter)).
+- **`akm` and `okf` reserve `index.md`/`log.md`** as structural files — never
+  indexed as concepts, never valid write targets — at any depth. `llm-wiki`
+  reserves `schema.md`, `index.md` and `log.md` only at the wiki root.
 - **`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
@@ -254,5 +251,5 @@ they actually work:
 
 - [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
+- [Concepts](../guides/concepts.md) — the retrieval loop these adapters serve
 - [Architecture](architecture.md) — sources, refs, the search pipeline, and the write-source chokepoint