akm-cli 0.9.0 → 0.9.1-beta.2

package/dist/workflows/runtime/runs.js

@@ -17,14 +17,22 @@ import { compileResolveFreezeWorkflow } from "../ir/freeze.js";
 import { materializeWorkflowParameterFlags, validateWorkflowParams } from "../ir/params.js";
 import { canonicalPlanJson, computePlanHash } from "../ir/plan-hash.js";
 import { decodeWorkflowPlanV3, WORKFLOW_IR_VERSION } from "../ir/schema.js";
+import { clip, utf8Bytes, WORKFLOW_EVIDENCE_TRUNCATION_PREVIEW_CHARS, WORKFLOW_MAX_EVIDENCE_JSON_BYTES, WORKFLOW_UNIT_DIAGNOSTIC_CLIP, } from "../resource-limits.js";
 import { validateStepSummary } from "../validate-summary.js";
 import { resolveAgentIdentity } from "./agent-identity.js";
 import { evaluateCheckin } from "./checkin.js";
 import { assertWorkflowSpineMatchesPlan, classifyWorkflowRunPlan, frozenStepRows, requireExecutableWorkflowPlan, } from "./plan-classifier.js";
 import { evaluateStaleUnits } from "./unit-checkin.js";
 import { canonicalizeWorkflowRefInput, loadWorkflowAsset, resolveWorkflowEntryId } from "./workflow-asset-loader.js";
-/** Clip bound for a unit's `result_json` on the `--units` diagnostic surface. */
-const UNIT_DIAGNOSTIC_CLIP = 2000;
+/**
+ * Membership test for the journaled `runner` column, which is an untyped string.
+ * The `Record<IrRuntimeKind, …>` is exhaustiveness-checked, so a new runtime
+ * kind cannot be added to the union without being accepted here too.
+ */
+const IR_RUNTIME_KINDS = { llm: true, agent: true, sdk: true, exec: true };
+function runtimeKindOf(runner) {
+    return runner !== null && Object.hasOwn(IR_RUNTIME_KINDS, runner) ? runner : null;
+}
 function toUnitDiagnostic(row, stale, plannedEngine) {
     let diagnostic = null;
     if (row.result_json !== null) {
@@ -40,7 +48,7 @@ function toUnitDiagnostic(row, stale, plannedEngine) {
         catch {
             /* leave the raw journaled text */
         }
-        diagnostic = text.length > UNIT_DIAGNOSTIC_CLIP ? `${text.slice(0, UNIT_DIAGNOSTIC_CLIP)}…` : text;
+        diagnostic = clip(text, WORKFLOW_UNIT_DIAGNOSTIC_CLIP);
     }
     return {
         unitId: row.unit_id,
@@ -60,7 +68,7 @@ function toUnitDiagnostic(row, stale, plannedEngine) {
         claimHolder: row.claim_holder,
         claimExpiresAt: row.claim_expires_at,
         engine: row.engine ?? null,
-        runtimeKind: row.engine && (row.runner === "llm" || row.runner === "agent" || row.runner === "sdk") ? row.runner : null,
+        runtimeKind: runtimeKindOf(row.runner),
         platform: plannedEngine?.kind === "agent" ? plannedEngine.platform : null,
     };
 }
@@ -350,6 +358,116 @@ export async function abandonWorkflowRun(runId) {
         return detail;
     });
 }
+// ── Step-evidence persistence bound (issue C) ────────────────────────────────
+/**
+ * Marker key stamped on every value this module replaced because it did not fit
+ * in `workflow_run_steps.evidence_json`. It is deliberately ugly and unique so a
+ * truncated value can NEVER be mistaken for real workflow data by a downstream
+ * `steps.<id>.output…` reference, by `akm workflow status`, or by a human
+ * reading the row.
+ */
+export const WORKFLOW_EVIDENCE_TRUNCATED_MARKER = "__akm_evidence_truncated__";
+function truncatedEvidenceValue(json, what, limitBytes, withPreview) {
+    return {
+        [WORKFLOW_EVIDENCE_TRUNCATED_MARKER]: true,
+        reason: `${what} exceeded the ${limitBytes}-byte evidence_json persistence cap and was NOT stored. ` +
+            `The complete value existed only in the live step result; it cannot be recovered from this row. ` +
+            `Reduce the step's fan-out or have it emit a reference (path, id) instead of inline bulk data.`,
+        originalBytes: utf8Bytes(json),
+        limitBytes,
+        ...(withPreview ? { preview: json.slice(0, WORKFLOW_EVIDENCE_TRUNCATION_PREVIEW_CHARS) } : {}),
+    };
+}
+/**
+ * True when `value` is the {@link TruncatedEvidenceValue} envelope persisted in
+ * place of an over-cap evidence entry.
+ *
+ * A LIVE invocation never sees one: the engine threads each step's complete
+ * in-memory evidence to the rest of its own run. A RESUMED invocation rebuilds
+ * the downstream scope from these rows, so `exec/step-work.ts` tests every
+ * whole-value reference with this predicate — otherwise a reference INTO the
+ * envelope reports a generic missing property and a reference AT it silently
+ * hands the envelope to a unit as if it were the artifact.
+ */
+export function isTruncatedEvidence(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        value[WORKFLOW_EVIDENCE_TRUNCATED_MARKER] === true);
+}
+/**
+ * Bound what a step's evidence costs in ONE SQLite row.
+ *
+ * `buildEvidence` (exec/step-work.ts) promotes `evidence.output` UNCLIPPED by
+ * design: gates judge the full promoted artifact and the in-memory
+ * {@link StepExecutionResult} carries it to the caller intact. Nothing bounded
+ * the PERSISTED form, though — a `collect` reducer over a fan-out capped only by
+ * `WORKFLOW_MAX_MAP_EXPANSION` (10 000 units) can serialize to hundreds of
+ * megabytes. This is the write boundary, so the bound lives here rather than in
+ * the shared step-semantics module.
+ *
+ * Over-cap values are REPLACED (largest top-level entry BY UTF-8 BYTES first —
+ * the unit the cap is measured in — until the row fits) with a
+ * {@link TruncatedEvidenceValue} envelope. Nothing is silently shortened: a
+ * consumer either sees the real value or sees an object whose marker key says
+ * the data is gone. `preview` is intentionally not shaped like the original, so
+ * an expression reaching INTO a truncated artifact (`steps.x.output.files`)
+ * cannot quietly resolve against a half-array; a resumed run's reference is
+ * rejected by name through {@link isTruncatedEvidence}.
+ *
+ * Returns the JSON to persist plus the keys that were replaced (empty in the
+ * overwhelmingly common case, where nothing is copied or re-serialized twice).
+ */
+export function clipStepEvidenceForPersistence(evidence, limitBytes = WORKFLOW_MAX_EVIDENCE_JSON_BYTES) {
+    if (!evidence)
+        return { json: null, truncatedKeys: [] };
+    // Throws exactly as the previous inline `JSON.stringify` did on unserializable
+    // evidence — that contract is unchanged. Every stringify below operates on a
+    // subtree of a value already proven serializable here.
+    let json = JSON.stringify(evidence);
+    if (json === undefined)
+        return { json: null, truncatedKeys: [] };
+    let bytes = utf8Bytes(json);
+    if (bytes <= limitBytes)
+        return { json, truncatedKeys: [] };
+    const clipped = { ...evidence };
+    const truncatedKeys = [];
+    // Ordered by UTF-8 BYTES, the unit the cap itself is measured in: ordering by
+    // `json.length` (UTF-16 code units) sacrifices the char-largest key rather
+    // than the byte-largest one, so multibyte-heavy evidence loses extra keys the
+    // cap never required.
+    const bySizeDesc = Object.keys(evidence)
+        .map((key) => {
+        const json = JSON.stringify(evidence[key]) ?? "null";
+        return { key, json, bytes: utf8Bytes(json) };
+    })
+        .sort((a, b) => b.bytes - a.bytes);
+    for (const [index, entry] of bySizeDesc.entries()) {
+        const envelope = truncatedEvidenceValue(entry.json, `Step evidence "${entry.key}"`, limitBytes, true);
+        clipped[entry.key] = envelope;
+        truncatedKeys.push(entry.key);
+        // Track the row size arithmetically from the per-key sizes already computed
+        // for the sort, so a run of replacements costs ONE whole-object
+        // serialization rather than one per replaced key. The total is an ESTIMATE
+        // — a key whose value is `undefined` is charged the `"null"` the sort used
+        // but is OMITTED from the serialized row — so it decides only WHEN to
+        // measure. Whether the row FITS is settled by an exact serialization every
+        // time, the last key included, so an exhausted loop falls through to the
+        // whole-object marker on measurement rather than on drift.
+        bytes += utf8Bytes(JSON.stringify(envelope)) - entry.bytes;
+        if (bytes > limitBytes && index < bySizeDesc.length - 1)
+            continue;
+        json = JSON.stringify(clipped);
+        bytes = utf8Bytes(json);
+        if (bytes <= limitBytes)
+            return { json, truncatedKeys };
+    }
+    // Pathological shape (so many keys that even the envelopes overflow): persist
+    // ONE whole-object marker. Still unambiguous, still bounded.
+    return {
+        json: JSON.stringify(truncatedEvidenceValue(JSON.stringify(evidence), "Step evidence", limitBytes, false)),
+        truncatedKeys: Object.keys(evidence),
+    };
+}
 export async function completeWorkflowStep(input) {
     // Read the step (read-only) up front so the LLM validation gate runs OUTSIDE
     // the write transaction — a slow/hung LLM must never hold a db write lock.
@@ -389,7 +507,13 @@ export async function completeWorkflowStep(input) {
         if (input.signal?.aborted)
             throw interruptionReason(input.signal);
         const judge = input.summaryJudge === undefined
-            ? frozenSummaryJudge(preflight.plan, preflight.stepPlan.gate.judge, input.signal)
+            ? // Manual completion journals no gate row, so there is no `<stepId>.gate:l<loop>`
+                // identity to agree with — but the dispatch still names the REAL run and
+                // step (frozen-judge falls back to the gate node id for the unit id).
+                frozenSummaryJudge(preflight.plan, preflight.stepPlan.gate.judge, input.signal, undefined, {
+                    runId: input.runId,
+                    stepId: input.stepId,
+                })
             : input.summaryJudge;
         if (criteria.length > 0 && !judge) {
             throw new ConfigError(`Workflow run ${input.runId} has completion criteria for step "${input.stepId}" but its frozen plan has no judge. ` +
@@ -441,10 +565,26 @@ export async function completeWorkflowStep(input) {
             if (input.signal?.aborted)
                 throw interruptionReason(input.signal);
             const completedAt = new Date().toISOString();
+            // Bound the single-row cost of the promoted artifact (issue C). The
+            // caller's in-memory evidence object is never mutated — a clipped COPY is
+            // serialized — so the live step result and the gate's artifact judging
+            // keep the complete value. The DOWNSTREAM scope keeps it only because the
+            // engine threads this same in-memory evidence forward (`driveRun` prefers
+            // it over the re-read row): what the clip actually costs is a LATER
+            // invocation, which has nothing but these rows to rebuild the scope from.
+            const persistedEvidence = clipStepEvidenceForPersistence(input.evidence);
+            if (persistedEvidence.truncatedKeys.length > 0) {
+                warn(`Workflow run ${run.id} step "${input.stepId}": evidence exceeded the ` +
+                    `${WORKFLOW_MAX_EVIDENCE_JSON_BYTES}-byte persistence cap; ` +
+                    `${persistedEvidence.truncatedKeys.map((k) => `"${k}"`).join(", ")} ` +
+                    `${persistedEvidence.truncatedKeys.length === 1 ? "was" : "were"} stored as a truncation marker. ` +
+                    `The rest of THIS invocation still reads the complete value, but a run resumed from these rows will ` +
+                    `fail loudly when a later step references this step's output rather than read partial data.`);
+            }
             repo.updateStepCompletion({
                 status: input.status,
                 notes: input.notes?.trim() || null,
-                evidenceJson: input.evidence ? JSON.stringify(input.evidence) : null,
+                evidenceJson: persistedEvidence.json,
                 summary: summary || null,
                 completedAt,
                 runId: run.id,

package/dist/workflows/validate-summary.js

@@ -17,6 +17,21 @@
  */
 import validateSummaryJudgePrompt from "../assets/prompts/validate-summary-judge.md" with { type: "text" };
 import { parseJsonResponse } from "../core/parse.js";
+/**
+ * Parse the judge's raw response into a well-formed verdict, or `undefined`
+ * when the response is malformed (unparseable, or missing a boolean
+ * `complete`). This is the ONE verdict parser: {@link validateStepSummary}
+ * fails closed through it, and the engine's gate wrapper (step-work.ts) uses
+ * the same function to classify a malformed verdict as verifier
+ * INFRASTRUCTURE failure — never an honest rejection that would consume a
+ * gate loop — so the two classifications cannot drift.
+ */
+export function parseJudgeVerdict(raw) {
+    const parsed = parseJsonResponse(raw);
+    if (!parsed || typeof parsed.complete !== "boolean")
+        return undefined;
+    return parsed;
+}
 const JUDGE_SYSTEM = validateSummaryJudgePrompt;
 function buildUserPrompt(input) {
     const criteria = input.completionCriteria.map((c, i) => `${i + 1}. ${c}`).join("\n");
@@ -67,8 +82,8 @@ export async function validateStepSummary(input, judge, signal) {
             feedback: "The verification judge failed. Retry after fixing the verifier configuration or service.",
         };
     }
-    const parsed = parseJsonResponse(raw);
-    if (!parsed || typeof parsed.complete !== "boolean") {
+    const parsed = parseJudgeVerdict(raw);
+    if (!parsed) {
         return {
             complete: false,
             missing: criteria,

package/docs/README.md

@@ -1,61 +1,103 @@
 # Documentation
 
-Each subdirectory has its own README indexing everything inside it.
+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.
 
-## [Guides](https://github.com/itlackey/akm/blob/main/docs/guides/README.md)
+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).
 
-Task-oriented guides for using akm.
+## Start
 
-- [Getting Started](https://github.com/itlackey/akm/blob/main/docs/guides/getting-started.md) -- Quick setup guide
-- [Concepts](https://github.com/itlackey/akm/blob/main/docs/guides/concepts.md) -- Bundles, adapters, asset types, and refs
-- [Stash Maker's Guide](https://github.com/itlackey/akm/blob/main/docs/guides/stash-makers.md) -- Build and share a stash on GitHub, npm, or a network directory
+- [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
+- `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
+
+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)
-- [Local Development](https://github.com/itlackey/akm/blob/main/docs/guides/local-development.md) -- Dogfooding akm while editing its own source
-- [Claude Code workflows vs. akm workflows](https://github.com/itlackey/akm/blob/main/docs/guides/claude-code-vs-akm-workflows.md) -- Comparing the two things that share a name
-- Command tours: [search & discovery](https://github.com/itlackey/akm/blob/main/docs/guides/search-discovery.md), [sources & registries](https://github.com/itlackey/akm/blob/main/docs/guides/sources-registries.md), [knowledge management](https://github.com/itlackey/akm/blob/main/docs/guides/knowledge-management.md), [the improvement loop](https://github.com/itlackey/akm/blob/main/docs/guides/improvement-loop.md), [agent integration](https://github.com/itlackey/akm/blob/main/docs/guides/agent-integration.md)
+- [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
+- [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)
 
-## [Reference](reference/README.md)
+## Build and operate
 
-- [CLI](reference/cli.md) -- All `akm` commands and flags
-- [Configuration](reference/configuration.md) -- Engines, strategies, bundles, and settings
-- [Workflows](reference/workflows.md) -- Unified Markdown workflow schema, run state, and native orchestration engine
-- [Wiki Snapshot Fetchers](https://github.com/itlackey/akm/blob/main/docs/reference/wiki-snapshot-fetchers.md) -- The pluggable fetcher API for URL-based knowledge reads
-- [Registry](https://github.com/itlackey/akm/blob/main/docs/reference/registry.md) -- Registries, search, hosting, and managing sources
-- [Data & Telemetry](reference/data-and-telemetry.md) -- Exactly what akm reads and writes on your machine (no remote telemetry)
-- [akm-eval](https://github.com/itlackey/akm/blob/main/docs/reference/akm-eval.md) -- Standalone toolkit for measuring whether `akm improve` is working
-- [Roadmap](https://github.com/itlackey/akm/blob/main/docs/reference/roadmap.md) -- High-level focus for the 0.9 and 1.0 releases
+Package complete capabilities and turn knowledge into repeatable work.
 
-## [Agents](https://github.com/itlackey/akm/blob/main/docs/agents/README.md)
+- [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))
 
-- `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`
-- [Agent Install Guide](https://github.com/itlackey/akm/blob/main/docs/agents/agent-install.md) -- Step-by-step automated install for agents
-- [Curate Workmap](https://github.com/itlackey/akm/blob/main/docs/agents/curate-workmap.md) -- Read before changing `akm curate` ranking or output
+### Maintainers
 
-## [Architecture](https://github.com/itlackey/akm/blob/main/docs/architecture/README.md)
+Working on akm itself, not just using it.
 
-System overview, normative specs, decision history, and subsystem internals.
+- [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
+- [akm-eval](https://github.com/itlackey/akm/blob/main/docs/maintainers/eval.md) -- Standalone toolkit for measuring whether `akm improve` is working
+- [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
 
+## Look up details
+
+- [CLI](reference/cli.md) -- All `akm` commands and flags
+- [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
+- [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
+- [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
+- [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
-- [Specs](https://github.com/itlackey/akm/blob/main/docs/architecture/README.md#specs-specs) -- Normative specifications (bundle/adapter model, ref grammar, stash conventions)
+- [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
+- [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
 
-## [Migration](migration/README.md)
+## Execution boundary
 
-- [v0.8 -> v0.9 migration guide](migration/v0.8-to-v0.9.md) -- Current-cycle breaking changes
-- [Release notes](migration/release-notes/) -- The short per-release notes `akm help migrate <version>` prints
+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
+applies to akm's own self-generated changes.
 
-## [Posts](https://github.com/itlackey/akm/blob/main/docs/posts/README.md)
+## Posts
 
-Source articles for the dev.to publishing pipeline (historical record).
+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).
 
 ## Official Ecosystem Repositories
 
-- [itlackey/akm-stash](https://github.com/itlackey/akm-stash) -- the official onboarding stash with ready-made assets you can install with `akm bundle add`
+- [itlackey/akm-stash](https://github.com/itlackey/akm-stash) -- the official onboarding bundle with ready-made assets you can install with `akm bundle add`
 - [itlackey/akm-registry](https://github.com/itlackey/akm-registry) -- the official registry index that powers built-in discovery
 - [itlackey/akm-plugins](https://github.com/itlackey/akm-plugins) -- optional integrations for tools like OpenCode
-- [itlackey/akm-bench](https://github.com/itlackey/akm-bench) -- the standalone benchmark and evaluation repo for akm
+- [itlackey/akm-bench](https://github.com/itlackey/akm-bench) -- the standalone benchmark harness for measuring agent performance with akm
+- [itlackey/akm-eval](https://github.com/itlackey/akm-eval) -- the eval framework and tools for akm asset quality (distinct from the in-repo [`scripts/akm-eval/` toolkit](https://github.com/itlackey/akm/blob/main/docs/maintainers/eval.md))
 
 ---
 

package/docs/migration/release-notes/0.9.0.md

@@ -36,7 +36,8 @@ Key operator-facing changes:
   **What this refactor does not (yet) touch: placement.**
   `adapter.placeNew()` is defined on the interface
   (`src/core/adapter/bundle-adapter.ts`) as an optional capability method and
-  already implemented by 8 of the built-in adapters, but nothing in the write
+  already implemented by 9 of the 11 built-in adapters (all but `okf` and
+  `website-snapshot`), but nothing in the write
   path calls it in 0.9.0 — writes still route through AKM's native flat
   type→directory placement table (`stashDirFor` in
   `src/core/asset/asset-placement.ts`). That wiring is deferred to 0.10 as

package/docs/migration/v0.7-to-v0.8.md

@@ -34,7 +34,8 @@ below explains what the script does and what you need to verify afterward.
 - [Verifying the upgrade](#verifying-the-upgrade)
 - [Troubleshooting](#troubleshooting)
 - [Rolling back](#rolling-back)
-- [Config v2 migration (reflect multi-mode)](#config-v2-migration-reflect-multi-mode)
+- [Config 0.8.0 migration (unified profiles)](#config-080-migration-unified-profiles)
+- [Config layer rewrite (late-0.8.x)](#config-layer-rewrite-late-08x)
 - [End-of-run auto-sync for git-backed stashes](#end-of-run-auto-sync-for-git-backed-stashes)
 
 ## Installing 0.8.0

package/docs/migration/v0.8-to-v0.9.md

@@ -749,7 +749,9 @@ change type and ref spelling to the owning adapter's own scheme the first time
 you reindex after upgrading. **No action needed** — the index is a
 regenerable cache and rebuilds itself — but searches or saved refs into those
 bundles may resolve to the new spellings afterwards. Reindex with `akm index`
-right after the cutover so this settles before you rely on saved refs.
+right after the cutover so this settles before you rely on saved refs. See
+[Bundle Types](../reference/bundle-types.md) for the full 11-adapter list,
+detection rules, and what each one reads/writes.
 
 ### 0.8 workflow assets after migration
 

package/docs/reference/README.md

@@ -2,11 +2,18 @@
 
 Authoritative reference documentation for the akm CLI and its data.
 
+- [Bundle Types](bundle-types.md) -- Pointer page: where the bundle-format compatibility table and adapter internals now live
 - [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
+- [Supported Formats](supported-formats.md) -- Formats akm can index, from its own bundle layout to other tools' existing asset directories
+- [Workflow Schema](workflow-schema.md) -- Authoritative reference for a workflow asset's exact frontmatter and body syntax
+- [Workflows](workflows.md) -- Map of the workflow documentation: running, authoring, the schema, and the engine
+- [Memory](https://github.com/itlackey/akm/blob/main/docs/reference/memory.md) -- The `memory` asset type: capture, belief states, and derived memories
+- [Refs](https://github.com/itlackey/akm/blob/main/docs/reference/refs.md) -- The ref grammar `akm search` emits and `akm show` consumes, rename semantics, and namespacing
+- [Asset Types](https://github.com/itlackey/akm/blob/main/docs/reference/asset-types.md) -- The capability taxonomy the native `akm` adapter recognizes, bundle layout, and asset metadata
+- [Environment & Secrets](https://github.com/itlackey/akm/blob/main/docs/reference/env-and-secrets.md) -- `akm env` and `akm secret`, the two protected-value asset types
 - [Registry](https://github.com/itlackey/akm/blob/main/docs/reference/registry.md) -- Registries, search, hosting, and managing sources
-- [Wiki Snapshot Fetchers](https://github.com/itlackey/akm/blob/main/docs/reference/wiki-snapshot-fetchers.md) -- The pluggable fetcher API for URL-based knowledge reads
+- [Website Sources](https://github.com/itlackey/akm/blob/main/docs/reference/website-sources.md) -- The pluggable fetcher API behind `akm import <url>` and other URL-based knowledge reads
 - [Data & Telemetry](data-and-telemetry.md) -- Exactly what akm reads and writes on your machine (no remote telemetry)
-- [akm-eval](https://github.com/itlackey/akm/blob/main/docs/reference/akm-eval.md) -- Standalone toolkit for measuring whether `akm improve` is working
-- [Roadmap](https://github.com/itlackey/akm/blob/main/docs/reference/roadmap.md) -- High-level focus for the 0.9 and 1.0 releases
+
+See also: [akm-eval](https://github.com/itlackey/akm/blob/main/docs/maintainers/eval.md) -- the standalone toolkit for measuring whether `akm improve` is working (maintainer docs), and the repo-root [Roadmap](https://github.com/itlackey/akm/blob/main/ROADMAP.md) -- high-level focus for upcoming releases.

package/docs/reference/bundle-types.md

@@ -0,0 +1,19 @@
+# Bundle Types
+
+This page has moved. AKM's bundle-format documentation is now split in two:
+the public compatibility table lives at
+[Supported Formats](supported-formats.md), and the adapter internals — probe
+order, the `BundleAdapter` interface, `placeNew()` wiring status, and the
+write allowlists — live at
+[Architecture → Adapters](https://github.com/itlackey/akm/blob/main/docs/architecture/adapters.md).
+
+- [Supported Formats](supported-formats.md) — the format-by-format table:
+  what AKM indexes, the auto-detection marker, current read/write support,
+  and typical use, for all 11 built-in formats (`akm` native, `okf`,
+  `llm-wiki`, `claude`, `opencode`, `agent-skills`, `dotenv`,
+  `akm-workflow`, `akm-task`, `website-snapshot`, `generic-files`).
+- [Architecture → Adapters](https://github.com/itlackey/akm/blob/main/docs/architecture/adapters.md) — how AKM picks an
+  adapter for a bundle, the `BundleAdapter` interface contract, the current
+  `placeNew()` wiring status, the write allowlists that actually gate
+  `akm remember`/`import`/`proposal accept`/etc., and per-adapter
+  implementation caveats.