akm-cli 0.9.30 → 0.10.261001-beta

package/dist/workflows/runtime/run-plan.js

@@ -5,9 +5,10 @@
  * Reading a run row's frozen plan: the ONE plan decoder and its tolerant
  * row-level wrapper.
  *
- * {@link decodeWorkflowPlan} accepts every plan shape a release has stored —
- * irVersion 4 and 5 (with their `sourceReadSet` and host-identity fields) as
- * well as the current one — and keeps keys it does not know rather than
+ * {@link decodeWorkflowPlan} accepts every plan shape a release at or above
+ * the 0.9.15 floor has stored — irVersion 5 (with its `sourceReadSet` and
+ * host-identity fields, which 0.9.15 and 0.9.16 wrote) as well as the current
+ * one — and keeps keys it does not know rather than
  * refusing them. It rejects only a plan it cannot run: no steps, a unit with
  * no frozen target, a request that does not decode. `plan_ir_version` and
  * `plan_hash` are informational columns: neither gates execution. A plan that
@@ -62,30 +63,17 @@ export function frozenStepRows(plan) {
             ? step.root.kind === "map"
                 ? step.root.template.instructions
                 : step.root.instructions
-            : routeInstructions(step.route),
+            : "",
         completionJson: step.gate.criteria.length > 0 ? JSON.stringify(step.gate.criteria) : null,
         sequenceIndex: step.sequenceIndex,
     }));
 }
-function routeInstructions(route) {
-    const branches = Object.entries(route.when)
-        .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0))
-        .map(([match, stepId]) => `"${match}" -> ${stepId}`);
-    if (route.defaultStepId !== undefined)
-        branches.push(`default -> ${route.defaultStepId}`);
-    return `Route on ${route.input}: ${branches.join(", ")}.`;
-}
 /** Decode a stored plan (any release's) into the one plan type. */
 export function decodeWorkflowPlan(input, options = {}) {
     const raw = record(input, "plan");
     if (!Array.isArray(raw.steps) || raw.steps.length === 0)
         fail("steps must be a non-empty array");
     const steps = raw.steps.map((value, index) => decodeStep(value, index));
-    if (raw.outputs !== undefined) {
-        for (const [name, entry] of Object.entries(record(raw.outputs, "outputs"))) {
-            string(record(entry, `outputs.${name}`).from, `outputs.${name}.from`);
-        }
-    }
     const sourceHash = typeof raw.sourceHash === "string" ? raw.sourceHash : legacySourceHash(raw.sourceReadSet, options.workflowRef);
     return {
         ...raw,
@@ -109,28 +97,18 @@ function legacySourceHash(readSet, workflowRef) {
 function decodeStep(value, index) {
     const step = record(value, `step ${index}`);
     const stepId = string(step.stepId, `step ${index} stepId`);
-    const route = step.route === undefined ? undefined : decodeRoute(step.route, stepId);
-    const root = step.root === undefined ? undefined : decodeNode(step.root, stepId);
-    if (!root && !route)
-        fail(`step ${stepId} has neither a frozen root nor a route`);
+    if (step.root === undefined)
+        fail(`step ${stepId} has no frozen root`);
+    const root = decodeNode(step.root, stepId);
     return {
         ...step,
         stepId,
         title: typeof step.title === "string" ? step.title : stepId,
         sequenceIndex: index,
-        ...(root ? { root } : {}),
-        ...(route ? { route } : {}),
+        root,
         gate: decodeGate(step.gate, stepId),
     };
 }
-function decodeRoute(value, stepId) {
-    const route = record(value, `step ${stepId} route`);
-    string(route.input, `step ${stepId} route.input`);
-    const when = record(route.when, `step ${stepId} route.when`);
-    for (const target of Object.values(when))
-        string(target, `step ${stepId} route target`);
-    return route;
-}
 function decodeNode(value, stepId) {
     const node = record(value, `step ${stepId} root`);
     if (node.kind !== "map")
@@ -154,7 +132,6 @@ function decodeUnit(node, stepId) {
         id,
         instructions: typeof node.instructions === "string" ? node.instructions : "",
         onError: node.onError === "continue" ? "continue" : "fail",
-        isolation: node.isolation === "worktree" ? "worktree" : "none",
         frozenTarget: decodeTarget(node.frozenTarget, label),
         environment: Array.isArray(node.environment)
             ? node.environment.map((binding, index) => decodeEnvironmentBinding(binding, `${label} environment[${index}]`))
@@ -180,11 +157,7 @@ function decodeGate(value, stepId) {
 function decodeTarget(value, label) {
     const target = record(value, `${label} frozenTarget`);
     const inputBindings = decodeInputBindings(target.inputBindings, label);
-    const gitCommitOid = typeof target.gitCommitOid === "string" ? target.gitCommitOid : undefined;
-    const optional = {
-        ...(gitCommitOid ? { gitCommitOid } : {}),
-        ...(inputBindings ? { inputBindings } : {}),
-    };
+    const optional = inputBindings ? { inputBindings } : {};
     switch (target.kind) {
         case "command":
             return decodeCommandTarget(target, label);
@@ -196,20 +169,6 @@ function decodeTarget(value, label) {
                 cwdIdentity: record(target.cwdIdentity, `${label} cwdIdentity`),
                 ...optional,
             };
-        case "script":
-            return {
-                kind: "script",
-                ref: string(target.ref, `${label} script ref`),
-                contentHash: string(target.contentHash, `${label} contentHash`),
-                exec: decodeExec(target.exec, label),
-                interpreter: string(target.interpreter, `${label} interpreter`),
-                extension: string(target.extension, `${label} extension`),
-                bytesBase64: typeof target.bytesBase64 === "string" ? target.bytesBase64 : fail(`${label} has no script bytes`),
-                byteLength: typeof target.byteLength === "number" ? target.byteLength : 0,
-                cwdIdentity: record(target.cwdIdentity, `${label} cwdIdentity`),
-                materialization: "ephemeral-0700-delete",
-                ...optional,
-            };
         case "child-workflow":
             return {
                 kind: "child-workflow",
@@ -217,7 +176,7 @@ function decodeTarget(value, label) {
                 planHash: string(target.planHash, `${label} planHash`),
                 frozenPlan: decodeWorkflowPlan(target.frozenPlan),
                 contentHash: string(target.contentHash, `${label} contentHash`),
-                via: target.via === "task" ? "task" : "direct",
+                ...(target.via === "task" || target.via === "direct" ? { via: target.via } : {}),
                 ...(typeof target.taskRef === "string" ? { taskRef: target.taskRef } : {}),
                 ...(inputBindings ? { inputBindings } : {}),
             };
@@ -247,7 +206,6 @@ function decodeCommandTarget(target, label) {
         ...(target.cwdIdentity && typeof target.cwdIdentity === "object"
             ? { cwdIdentity: target.cwdIdentity }
             : {}),
-        ...(typeof target.gitCommitOid === "string" ? { gitCommitOid: target.gitCommitOid } : {}),
         ...(inputBindings ? { inputBindings } : {}),
     };
 }

package/dist/workflows/runtime/runs.js

@@ -13,12 +13,11 @@ import { getCurrentWorkflowScopeKey } from "../authoring/scope-key.js";
 import { frozenSummaryJudge } from "../exec/frozen-judge.js";
 import { detectSecretShapedParams } from "../exec/param-secrets.js";
 import { freezeWorkflow } from "../freeze/freeze.js";
-import { materializeWorkflowParameterFlags, validateWorkflowParams } from "../ir/params.js";
+import { applyWorkflowParamDefaults, materializeWorkflowParameterFlags, validateWorkflowParams, } from "../ir/params.js";
 import { canonicalPlanJson, computePlanHash } from "../ir/plan-hash.js";
 import { clip, WORKFLOW_UNIT_DIAGNOSTIC_CLIP } from "../resource-limits.js";
 import { validateStepSummary } from "../validate-summary.js";
 import { resolveAgentIdentity } from "./agent-identity.js";
-import { resolveWorkflowRunOutputs } from "./run-outputs.js";
 import { frozenStepRows, readRunPlan } from "./run-plan.js";
 import { canonicalizeWorkflowRefInput, loadWorkflowAsset, resolveWorkflowEntryId } from "./workflow-asset-loader.js";
 /**
@@ -76,9 +75,7 @@ export async function startWorkflowRun(ref, params = {}, options) {
     if (options?.parameterFlags?.length && Object.keys(params).length > 0) {
         throw new UsageError("Workflow parameters must use either an object or per-parameter flags, not both.");
     }
-    const effectiveParams = options?.parameterFlags?.length
-        ? materializeWorkflowParameterFlags(plan, options.parameterFlags)
-        : params;
+    const effectiveParams = applyWorkflowParamDefaults(plan, options?.parameterFlags?.length ? materializeWorkflowParameterFlags(plan, options.parameterFlags) : params);
     // Non-fatal WARNINGS: untyped-step and undeclared-param advisories surface
     // as `warn()` lines at start (stderr, consistent with the repo's other
     // author-facing warnings) without blocking the run.
@@ -394,10 +391,9 @@ export async function completeWorkflowStep(input) {
     return withWorkflowRunsRepo((repo) => {
         let updatedRun;
         let refreshedSteps = [];
-        let outputWarnings;
         repo.transaction(() => {
             const run = readWorkflowRun(repo, input.runId);
-            const plan = requireRunPlan(run);
+            const _plan = requireRunPlan(run);
             if (run.status !== "active") {
                 throw new UsageError(`Workflow run ${run.id} is ${run.status} and cannot be updated.`);
             }
@@ -428,15 +424,6 @@ export async function completeWorkflowStep(input) {
             });
             refreshedSteps = readWorkflowRunSteps(repo, run.id);
             const state = deriveRunState(refreshedSteps);
-            // Declared outputs resolve inside this transaction once the run
-            // completes; a failure rolls the step completion back whole.
-            let outputsJson; // undefined = untouched, keep the row's existing value
-            if (state.status === "completed" && plan.outputs) {
-                const resolved = resolveWorkflowRunOutputs(plan, refreshedSteps);
-                outputsJson = JSON.stringify(resolved.outputs);
-                repo.setRunOutputs(run.id, outputsJson);
-                outputWarnings = resolved.errors;
-            }
             repo.updateRunState({
                 status: state.status,
                 currentStepId: state.currentStepId,
@@ -450,16 +437,9 @@ export async function completeWorkflowStep(input) {
                 current_step_id: state.currentStepId,
                 updated_at: completedAt,
                 completed_at: state.completedAt,
-                ...(outputsJson !== undefined ? { outputs_json: outputsJson } : {}),
             };
         });
         const detail = buildWorkflowRunDetail(repo, updatedRun, refreshedSteps);
-        if (outputWarnings?.length) {
-            const messages = outputWarnings.map((e) => `Workflow run ${input.runId} declared ${e}`);
-            for (const message of messages)
-                warn(message);
-            detail.warnings = [...(detail.warnings ?? []), ...messages];
-        }
         // #11: emit `workflow_step_completed` ONLY for a genuine `completed`
         // transition; every other non-pending status (failed/skipped/blocked)
         // carries the honest `workflow_step_updated` name. The status is ALWAYS
@@ -680,10 +660,7 @@ function toWorkflowRunSummary(run) {
         agentHarness: run.agent_harness ?? null,
         agentSessionId: run.agent_session_id ?? null,
         planIrVersion: run.plan_ir_version ?? null,
-        // P3b: all three optional and conditionally spread, so every
-        // pre-existing (non-child, no-outputs-declared) run's envelope is
-        // byte-identical.
-        ...(run.outputs_json ? { outputs: parseJsonObject(run.outputs_json) ?? {} } : {}),
+        // Optional and conditionally spread, so a non-child run's envelope is unchanged.
         ...(run.parent_run_id ? { parentRunId: run.parent_run_id } : {}),
         ...(run.parent_unit_id ? { spawnedByUnitId: run.parent_unit_id } : {}),
     };

package/dist/workflows/source-files.js

@@ -4,11 +4,9 @@
 /**
  * Authoritative workflow-source ownership.
  *
- * Markdown and the bounded GitHub-shaped YAML subset are peer authoring
- * formats, but one canonical workflow ref must have exactly one source file.
- * This module is the shared filesystem arbitration point used before indexing,
- * cache reuse, lookup/show, and runtime load/start. It never chooses one
- * extension by priority: two recognized siblings are a hard collision.
+ * One canonical workflow ref must have exactly one source file. This module
+ * is the shared filesystem arbitration point used before indexing, cache
+ * reuse, lookup/show, and runtime load/start.
  */
 import fs from "node:fs";
 import path from "node:path";
@@ -29,7 +27,7 @@ export class WorkflowSourceCollisionError extends WorkflowSourceRejectionError {
     constructor(canonicalName, sourcePaths) {
         const sorted = [...sourcePaths].sort(compareCodePoints);
         super(`Workflow "${canonicalName}" resolves to multiple workflow source files: ${sorted.join(", ")}. ` +
-            "A canonical workflow ref must be owned by exactly one recognized .md or .yml source; remove or rename the duplicate.", "RESOURCE_ALREADY_EXISTS", sorted);
+            "A canonical workflow ref must be owned by exactly one recognized .md source; remove or rename the duplicate.", "RESOURCE_ALREADY_EXISTS", sorted);
         this.name = "WorkflowSourceCollisionError";
         this.canonicalName = canonicalName;
         Object.setPrototypeOf(this, new.target.prototype);
@@ -46,15 +44,15 @@ export class WorkflowSourceIdentityError extends UsageError {
 export class WorkflowSourceNameError extends WorkflowSourceRejectionError {
     constructor(sourcePath, nestedSuffix) {
         super(`Workflow source filename ${sourcePath} has an extensionless stem ending in recognized workflow suffix "${nestedSuffix}". ` +
-            "Nested workflow suffixes are invalid; remove the inner .md or .yml suffix instead of relying on repeated stripping.", "WORKFLOW_SOURCE_INVALID", [sourcePath]);
+            "Nested workflow suffixes are invalid; remove the inner .md suffix instead of relying on repeated stripping.", "WORKFLOW_SOURCE_INVALID", [sourcePath]);
         this.name = "WorkflowSourceNameError";
         Object.setPrototypeOf(this, new.target.prototype);
     }
 }
 export class WorkflowSourceLinkIdentityError extends WorkflowSourceRejectionError {
     constructor(sourcePath, targetPath) {
-        super(`Workflow source ${sourcePath} resolves through a symlink to ${targetPath} with a different source format. ` +
-            "The authored workflow path and resolved source must use the same .md or .yml format.", "WORKFLOW_SOURCE_INVALID", [sourcePath]);
+        super(`Workflow source ${sourcePath} resolves through a symlink to ${targetPath} with a different extension. ` +
+            "The authored workflow path and resolved source must both be .md.", "WORKFLOW_SOURCE_INVALID", [sourcePath]);
         this.name = "WorkflowSourceLinkIdentityError";
         Object.setPrototypeOf(this, new.target.prototype);
     }
@@ -240,13 +238,13 @@ function inspectWorkflowSourceDomain(candidates, canonicalName, realRoot) {
 function pickWorkflowSource(adapterId, canonicalName, sources) {
     if (sources.length <= 1)
         return sources[0];
-    const winner = [...sources].sort((left, right) => left.format === right.format ? 0 : left.format === "markdown" ? -1 : 1)[0];
+    const winner = sources[0];
     const shadowed = sources.filter((source) => source !== winner);
     const displayName = adapterId === "akm" ? `workflows/${canonicalName}` : canonicalName;
-    warnOnce(`workflow-source-collision:${displayName}`, `Workflow "${displayName}" has both a .md and .yml source (${shadowed
+    warnOnce(`workflow-source-collision:${displayName}`, `Workflow "${displayName}" has several sources (${shadowed
         .map((source) => source.relativePath)
-        .join(", ")} shadowed by ${winner?.relativePath}); using the .md source. Remove the shadowed sibling to ` +
-        "silence this warning.");
+        .join(", ")} shadowed by ${winner?.relativePath}); using ${winner?.relativePath}. Remove the shadowed ` +
+        "sibling to silence this warning.");
     return winner;
 }
 function inspectWorkflowSourceCandidate(candidate, canonicalName, realRoot) {
@@ -297,7 +295,6 @@ function inspectWorkflowSourceCandidate(candidate, canonicalName, realRoot) {
             realPath,
             relativePath: candidate.relativePath,
             canonicalName,
-            format: candidate.lowerExtension === ".md" ? "markdown" : "github-yaml",
         },
     };
 }
@@ -321,8 +318,7 @@ export function assertIndexedWorkflowSourceIdentity(ref, indexedPath, authoritat
         throw new WorkflowSourceIdentityError(ref, indexedPath, authoritative.path);
     }
     const indexedExtension = path.extname(indexedPath).toLowerCase();
-    const authoritativeExtension = authoritative.format === "markdown" ? ".md" : ".yml";
-    if (indexedExtension !== authoritativeExtension) {
+    if (indexedExtension !== ".md") {
         throw new WorkflowSourceIdentityError(ref, indexedPath, authoritative.path);
     }
 }

package/dist/workflows/source-semantics.js

@@ -1,12 +1,9 @@
 // This Source Code Form is subject to the terms of the Mozilla Public
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
-/** Semantic checks shared by the workflow grammars (`parser.ts`, `github-yaml.ts`) and freeze. */
+/** Semantic checks for the Markdown workflow grammar (`parser.ts`). */
 import fs from "node:fs";
 import path from "node:path";
-import { parseBuiltinCommandAction } from "../commands/command/builtin-action.js";
-import { classifyTargetRef } from "../execution/target-ref.js";
-import { parseSchedule } from "../tasks/schedule.js";
 export class WorkflowSourceSemanticError extends Error {
     code;
     constructor(code, message) {
@@ -15,36 +12,6 @@ export class WorkflowSourceSemanticError extends Error {
         this.name = "WorkflowSourceSemanticError";
     }
 }
-/** The argv a `run:` string executes under `shell`. */
-export function workflowShellCommand(shell, content) {
-    if (shell === "cmd")
-        return ["cmd", "/d", "/s", "/c", content];
-    if (shell === "pwsh" || shell === "powershell")
-        return [shell, "-Command", content];
-    return [shell, "-c", content];
-}
-export function canonicalizeWorkflowCron(value) {
-    const canonical = value.trim().split(/\s+/).join(" ");
-    if (canonical.startsWith("@") || canonical.split(" ").length !== 5) {
-        throw new WorkflowSourceSemanticError("invalid-cron", "GitHub schedule cron must use exactly five fields.");
-    }
-    try {
-        parseSchedule(canonical, "cron");
-    }
-    catch (cause) {
-        throw new WorkflowSourceSemanticError("invalid-cron", cause instanceof Error ? cause.message : "Invalid cron schedule.");
-    }
-    return canonical;
-}
-export function canonicalizeWorkflowRun(value) {
-    if (value.includes("${{")) {
-        throw new WorkflowSourceSemanticError("unsupported-github-expression", "GitHub expressions and contexts are not supported.");
-    }
-    if (value.includes("\0")) {
-        throw new WorkflowSourceSemanticError("invalid-exec-argv", "Local run may not contain NUL bytes.");
-    }
-    return value;
-}
 export function canonicalizeWorkflowWorkingDirectory(value, workspaceRoot) {
     if (hasControlCharacter(value)) {
         throw new WorkflowSourceSemanticError("working-directory-control-character", "working-directory may not contain NUL or control characters.");
@@ -74,65 +41,6 @@ function hasControlCharacter(value) {
     }
     return false;
 }
-export function classifyWorkflowStepUses(value) {
-    if (value.includes("${{")) {
-        throw new WorkflowSourceSemanticError("unsupported-github-expression", "GitHub expressions are unsupported in uses.");
-    }
-    if (value.length === 0 || value.trim() !== value || /\s/.test(value)) {
-        throw new WorkflowSourceSemanticError("unsupported-uses-target", "uses must be one exact, non-empty executable ref");
-    }
-    if (value === "akm/command")
-        return { kind: "builtin-command", ref: "akm/command" };
-    try {
-        return classifyTargetRef(value);
-    }
-    catch (cause) {
-        throw usesFailure(value, cause);
-    }
-}
-/**
- * Validate AKM's built-in command action at the shared source/decoder boundary.
- *
- * Inline YAML actions are portable templates and therefore use WP4's one
- * authoritative template validator. Markdown prose is explicitly `literal`,
- * while a stored ref remains resolution-owned because its template bytes are
- * not available until the later resolver loads the command asset.
- */
-export function validateWorkflowBuiltinCommand(value, mode) {
-    let action;
-    try {
-        action = parseBuiltinCommandAction(value);
-    }
-    catch (cause) {
-        throw new WorkflowSourceSemanticError("builtin-command-inputs", cause instanceof Error ? cause.message : "Invalid akm/command inputs.");
-    }
-    const expectedMode = action.kind === "stored" ? "stored-ref" : "portable-template";
-    const effectiveMode = mode ?? expectedMode;
-    if (action.kind === "stored") {
-        if (effectiveMode !== "stored-ref") {
-            throw new WorkflowSourceSemanticError("builtin-command-inputs", "Stored akm/command refs require commandMode stored-ref.");
-        }
-        return action;
-    }
-    if (effectiveMode === "stored-ref") {
-        throw new WorkflowSourceSemanticError("builtin-command-inputs", "Inline akm/command content cannot use commandMode stored-ref.");
-    }
-    if (effectiveMode === "literal" && action.arguments !== undefined) {
-        throw new WorkflowSourceSemanticError("builtin-command-inputs", "Literal akm/command content cannot declare arguments because no substitution occurs.");
-    }
-    return action;
-}
-function usesFailure(value, cause) {
-    const message = cause instanceof Error ? cause.message : String(cause);
-    const code = value.startsWith("docker://")
-        ? "docker-action-unsupported"
-        : value.startsWith("./") || value.startsWith("../") || value.startsWith("/")
-            ? "local-action-path-unsupported"
-            : /^(?:[A-Za-z0-9][A-Za-z0-9._-]*\/\/)?agents\//.test(value)
-                ? "non-executable-asset-ref"
-                : "unsupported-uses-target";
-    return new WorkflowSourceSemanticError(code, message);
-}
 function verifyPhysicalContainment(workspaceRoot, relative) {
     let root;
     try {

package/docs/README.md

@@ -6,51 +6,52 @@ 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
-- `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`
+- [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 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`
 
 ## 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)
-- [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 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.
+
+- [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/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 hints` 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).