akm-cli 0.9.30 → 0.9.31

package/CHANGELOG.md

@@ -6,6 +6,35 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.9.31] - 2026-10-09
+
+A patch release: concurrent config writes no longer lose a change, OpenAI's reasoning models work as `llm`
+engines, `akm improve --require-engines` probes send API keys, and the npm package's docs links resolve.
+
+### Fixed
+
+- **`akm improve --require-engines` sends each engine's API key with its probe.** The probe used the engine's
+  connection as resolved, where the key is still a symbolic reference that a dispatch reads only when it sends a
+  request, so every keyed endpoint (OpenAI, a gateway that enforces auth) answered 401 and the run stopped with
+  "engine completion path is not reachable". The probe now builds the connection as a dispatch does; a required key
+  that is missing is reported as that engine's failure.
+- **OpenAI's reasoning models (gpt-5.x) work as `llm` engines.** They answer 400 to any `temperature` but the
+  default and to `max_tokens`, so every akm model call failed on them. Like the existing fallback for the
+  thinking-control fields, a 400 that names `temperature` is retried once without it, and one that asks for
+  `max_completion_tokens` is retried with the cap under that name; the connection keeps the working shape for
+  the rest of the process.
+- **Every relative link in the npm package's docs resolves again.** #1118 made `docs/README.md`,
+  `docs/migration/README.md` and `docs/reference/cli.md` link by relative path to guides and pages the package did
+  not ship. npm always ships a folder's `README.md`, so those links were dead for npm users. The package now ships
+  the user-facing `docs/` folders (`agents`, `architecture`, `guides`, `integration`, `maintainers`, `migration`,
+  `posts`, `reference`), `docs/product-surface.md`, the one plan they link to, and `ROADMAP.md`. `docs/plans` stays
+  out. The link check skips link syntax inside code, which is an example, not a link.
+- **Concurrent `akm config set` runs no longer lose each other's changes.** A lock file was created empty and its
+  owner's PID written a moment later; a process that looked in that gap read no PID, took the live lock for an
+  abandoned one and removed it, so two writers ran at once and one change was lost. A lock now appears with its
+  owner's PID already in it. Every akm lock file (config, index writer, scheduler, `akm.lock`, run, extract, secret)
+  is created this way.
+
 ## [0.9.30] - 2026-10-09
 
 A patch release: `akm upgrade` acts only on the `akm-opencode` spec OpenCode's config names.

package/README.md

@@ -55,7 +55,7 @@ akm show scripts/deploy.sh         # View details and run command
 - **One library for every agent** -- Use the same capability library from Claude Code, OpenCode, Cursor, Aider, Windsurf, or any assistant that can run shell commands.
 - **Load only what the task needs** -- Search or curate a shortlist, then load full content by ref. No giant startup prompt is required.
 - **Package complete capabilities** -- Install and share bundles containing skills, scripts, workflows, agents, instructions, memories, and knowledge -- not just prompt snippets.
-- **Improve through evidence, with review** -- Feedback influences retrieval and produces diffable proposals. Changes remain reviewable and target only writable bundles.
+- **Improve through evidence, with review** -- Feedback re-ranks assets right away. A negative report can carry an exact text fix, and `akm improve` repairs metadata; every edit lands as a diffable proposal you accept, reject or revert, and only writable bundles are changed.
 - **Turn knowledge into repeatable work** -- Run persisted workflows with dispatch, gates, retries, budgets, and resume instead of reconstructing a process from prose every session.
 
 akm retrieves every supported capability type. It directly orchestrates
@@ -80,16 +80,16 @@ Or generate it directly: `akm help agents >> AGENTS.md`
 
 ## Documentation
 
-Full docs, CLI reference, and guides are available on [GitHub](https://github.com/itlackey/akm):
+Full docs, CLI reference, and guides are at **[akm.fwdslsh.dev](https://akm.fwdslsh.dev/)**:
 
-- [Getting Started](https://github.com/itlackey/akm/blob/main/docs/guides/getting-started.md)
-- [Supported Formats](https://github.com/itlackey/akm/blob/main/docs/reference/supported-formats.md)
-- [CLI Reference](https://github.com/itlackey/akm/blob/main/docs/reference/cli.md)
-- [Task v3 Reference](https://github.com/itlackey/akm/blob/main/docs/reference/tasks.md)
-- [0.9.2 Migration Guide](https://github.com/itlackey/akm/blob/main/docs/migration/v0.9.1-to-v0.9.2.md)
-- [Configuration](https://github.com/itlackey/akm/blob/main/docs/reference/configuration.md)
-- [Bundle Authoring Guide](https://github.com/itlackey/akm/blob/main/docs/guides/author-bundles.md)
-- [Registry](https://github.com/itlackey/akm/blob/main/docs/reference/registry.md)
+- [Getting Started](https://akm.fwdslsh.dev/docs/guides/getting-started/)
+- [Supported Formats](https://akm.fwdslsh.dev/docs/reference/supported-formats/)
+- [CLI Reference](https://akm.fwdslsh.dev/docs/reference/cli/)
+- [Task v3 Reference](https://akm.fwdslsh.dev/docs/reference/tasks/)
+- [0.9.2 Migration Guide](https://akm.fwdslsh.dev/docs/migration/v0.9.1-to-v0.9.2/)
+- [Configuration](https://akm.fwdslsh.dev/docs/reference/configuration/)
+- [Bundle Authoring Guide](https://akm.fwdslsh.dev/docs/guides/author-bundles/)
+- [Registry](https://akm.fwdslsh.dev/docs/reference/registry/)
 
 ## License
 

package/ROADMAP.md

@@ -0,0 +1,112 @@
+# Roadmap
+
+This page outlines the high-level focus for the next two releases.
+
+It is intentionally directional rather than exhaustive. Detailed command,
+schema, and migration behavior still lives in the release notes, the
+migration guides, and [STABILITY.md](STABILITY.md), which classifies
+today's public contract by surface. The internal design specs behind the
+0.9.0 architecture consolidation live under
+[`docs/architecture/specs/`](docs/architecture/specs/).
+
+## 0.8 Foundation
+
+Release `0.8.0` already established much of the product shape that `0.9` and
+`1.0` build on.
+
+- The CLI and config surface were substantially redesigned.
+- `akm improve` became the main self-improvement and maintenance entry point.
+- Task assets, proposal workflows, health reporting, and agent command-building
+  all landed as first-class capabilities.
+- Storage, indexing, graph extraction, and migration paths were tightened to
+  support the v1 contract freeze.
+
+That means the next two releases are less about inventing a new direction and
+more about hardening, simplifying, and freezing what `0.8.0` put in place.
+
+## 0.9
+
+Release `0.9` is the architecture-consolidation release ahead of the `1.0`
+contract freeze. It replaces the flat asset-type registry with a
+**bundle / adapter** model and settles the durable contracts `1.0` will freeze.
+
+- **One canonical ref grammar.** Refs are `[bundle//]conceptId` — a
+  subdir-qualified concept id such as `skills/code-review` or `memories/vpn-note`
+  — replacing the pre-`0.9` `type:name` spelling. Durable state stores the
+  fully-qualified form; the short bundle-omitted form is input sugar. This is a
+  deliberate, one-time break, taken pre-`1.0` while it is still cheap.
+- **Format-neutral bundles.** Installed sources are bundles, each recognized by
+  a built-in adapter (Agent Skills, Claude/OpenCode commands and agents,
+  knowledge, YAML workflows, tasks, env/secret files, scripts, OKF and LLM-wiki
+  knowledge bases) instead of a closed asset-type list.
+- **Storage consolidation.** The durable databases collapse from four to three
+  (`state.db` / `index.db` / a separate `logs.db`); config migrates from the
+  flat `stashDir` / `sources` / `installed` keys to `bundles` / `defaultBundle`.
+  The one-time cutover is journaled and crash-resumable via `akm migrate apply`,
+  with a verified backup taken first.
+- **Debt paydown.** The improve / proposal / workflow internals are decomposed
+  onto one file-change transaction model and an ambient run context, the
+  deprecated `0.8` CLI aliases are removed, and the `vault` asset type is
+  retired in favor of `env` / `secret`.
+
+In short: `0.9` reduces ambiguity, pays down pre-`1.0` debt, and arrives at a
+small, durable core ready for the `1.0` freeze.
+
+### The 0.9.x series
+
+`0.9.x` is a series of refactoring and clean-up releases. The intent is to
+have **all technical debt paid off and all planned breaking changes handled
+before the 0.10.x series begins**. To get there quickly, 0.9.x patch releases
+may include breaking changes (see [STABILITY.md](STABILITY.md)); every
+break ships with a CHANGELOG migration note.
+
+Alongside the bug fixes and compatibility improvements, `0.9.x` also focuses
+on **tuning the improve processes** — reflect, distill, consolidate, memory
+inference, graph extraction, and proactive maintenance — and **settling the
+final design of those features** so the `0.10.0` release starts from a
+finished improve surface rather than one still being reshaped.
+
+## 0.10
+
+The `0.10.x` series is focused on **bug fixes and tuning** on top of the
+debt-free 0.9 core — no new architecture. With the clean-up done, 0.10.x
+attempts to return to the normal semver discipline: breaking changes only in
+major and minor releases, never in patches.
+
+## 0.X
+
+There may be other minor releases between 0.10.x and 1.0.0. The goal is to minimize the number of minor releases after 0.10.x, and they will only be used for addressing breaking changes that are justifiable before the 1.0.0 release.
+
+## 1.0
+
+Release `1.0` is focused on freezing the public contract and shipping the first
+stable ecosystem layer around that core.
+
+- Freeze the supported source model, the `[bundle//]conceptId` ref format,
+  search behavior, and write-target rules — the surfaces
+  [STABILITY.md](STABILITY.md)'s own 1.0 contract-freeze section
+  already names — and settle the surfaces it currently classifies as
+  Evolving or Experimental.
+- Carry the `0.8` agent and improvement workflow forward as a stable,
+  documented product surface rather than a collection of pre-release features.
+- Ship an official akm SDK for building integrations against the stable v1
+  contract instead of reverse-engineering CLI behavior.
+- Ship in-process akm plugins for Claude Code and OpenCode, built on that SDK,
+  so those tools can integrate more deeply without changing the CLI-first core
+  model that akm itself relies on.
+- Keep the CLI as the canonical foundation so the SDK and plugin story extends
+  the existing system rather than forking it into separate integration models.
+
+In short: `1.0` is where akm stops being only a strong CLI and becomes a stable
+platform for both direct use and deeper tool integration.
+
+## Scope Notes
+
+- The CLI remains the foundation in both releases.
+- `0.9` prioritizes hardening over expansion.
+- `1.0` adds the SDK and in-process plugin story on top of a frozen core, not
+  instead of it.
+- The roadmap assumes the `0.8.0` redesign is the baseline; later releases are
+  about stabilizing and extending that baseline, not replacing it.
+- Specific features may move between releases as implementation and testing
+  shake out, but the themes above are the intended direction.

package/dist/commands/improve/improve-cli.js

@@ -16,7 +16,8 @@ import { clearLogFile, setLogFile, warn } from "../../core/warn.js";
 import { resolveWriteTarget } from "../../core/write-source.js";
 import { DEFAULT_LLM_TIMEOUT_MS } from "../../integrations/agent/config.js";
 import { defaultWhich } from "../../integrations/agent/detect.js";
-import { collectEngineCredentialValues } from "../../integrations/agent/engine-resolution.js";
+import { collectEngineCredentialValues, materializeLlmConnection, } from "../../integrations/agent/engine-resolution.js";
+import { llmUseFromRunner, sdkFallbackUseFromRunner } from "../../integrations/agent/runner.js";
 import { probeLlmReachable } from "../../llm/client.js";
 import { getOutputMode } from "../../output/context.js";
 import { deliverRendered } from "../../output/html-render.js";
@@ -81,18 +82,36 @@ function collectRequiredEngineTargets(plan) {
     const runners = Object.entries(plan.processes)
         .flatMap(([processName, process]) => (process.runner ? [[processName, process.runner]] : []))
         .concat(plan.triageJudgment ? [["triage.judgment", plan.triageJudgment]] : []);
-    return runners.map(([processName, runner]) => ({
-        process: processName,
-        engine: runner.engine,
-        ...(runner.kind === "llm" ? { connection: probeConnection(runner) } : { bin: runner.profile.bin }),
-        ...(runner.kind === "sdk" && runner.fallbackConnection
-            ? { connection: probeConnection({ connection: runner.fallbackConnection, timeoutMs: runner.fallbackTimeoutMs }) }
-            : {}),
-    }));
+    return runners.map(([processName, runner]) => {
+        // The runner's own timeout, else the connection's (sdkFallbackUseFromRunner already does this).
+        const use = runner.kind === "llm"
+            ? {
+                ...llmUseFromRunner(runner),
+                timeoutMs: runner.timeoutMs !== undefined ? runner.timeoutMs : (runner.connection.timeoutMs ?? null),
+            }
+            : runner.kind === "sdk"
+                ? sdkFallbackUseFromRunner(runner)
+                : undefined;
+        return {
+            process: processName,
+            engine: runner.engine,
+            ...(runner.kind === "llm" ? {} : { bin: runner.profile.bin }),
+            ...(use ? probeConnection(use) : {}),
+        };
+    });
 }
-/** The resolved engine keeps its request timeout beside the connection (the runtime merges it in); the probe needs it on the connection. */
-function probeConnection(runner) {
-    return runner.timeoutMs !== undefined ? { ...runner.connection, timeoutMs: runner.timeoutMs } : runner.connection;
+/**
+ * The connection the probe sends, built as a dispatch builds it: the runner
+ * keeps its credential symbolic, so the key is read and injected here, or the
+ * probe would go out without one.
+ */
+function probeConnection(use) {
+    try {
+        return { connection: materializeLlmConnection(use) };
+    }
+    catch (err) {
+        return { connection: use.connection, error: err instanceof Error ? err.message : String(err) };
+    }
 }
 /**
  * The bound on `--require-engines`' probe: the connection's own request
@@ -133,6 +152,8 @@ export async function assertRequiredEnginesReachable(plan, probeReachable = (con
         }
         if (!target.connection)
             return { ...target, reach: { reachable: true }, latencyMs: 0 };
+        if (target.error)
+            return { ...target, reach: { reachable: false, error: target.error }, latencyMs: 0 };
         return { ...target, ...(await probeConnectionOnce(target.connection)) };
     }));
     const unreachable = probed.filter((item) => !item.reach.reachable);

package/dist/core/file-lock.js

@@ -51,14 +51,23 @@ function releaseLockRaw(lockPath) {
 }
 /** Create the lock file atomically; `undefined` when another holder already has it. */
 export function tryAcquireLockSync(lockPath, payload) {
+    // Write the payload under a private name, then hard-link it into place: the
+    // link is the exclusive step and the lock never exists without its payload.
+    // A `wx` write creates the file empty and fills it in afterwards; a contender
+    // probing in that gap reads no pid, calls the live lock stale and reclaims it.
+    const tmpPath = `${lockPath}.tmp-${process.pid}-${randomUUID()}`;
+    fs.writeFileSync(tmpPath, payload, { flag: "wx" });
     try {
-        fs.writeFileSync(lockPath, payload, { flag: "wx" });
+        fs.linkSync(tmpPath, lockPath);
     }
     catch (err) {
         if (err.code === "EEXIST")
             return undefined;
         throw err;
     }
+    finally {
+        releaseLockRaw(tmpPath);
+    }
     let snapshot;
     try {
         snapshot = readLockSnapshot(lockPath);

package/dist/llm/client.js

@@ -227,6 +227,12 @@ const jsonSchemaUnsupportedConnections = new Set();
  * `enable_thinking`): a strict hosted API answers 400 `Unknown parameter`.
  */
 const thinkingControlRejectedConnections = new Set();
+/**
+ * And for OpenAI's reasoning models: they answer 400 to any `temperature` but
+ * the default, and to `max_tokens`, naming `max_completion_tokens` instead.
+ */
+const temperatureRejectedConnections = new Set();
+const maxCompletionTokensConnections = new Set();
 function connectionKey(config) {
     return `${config.endpoint}|${config.model}`;
 }
@@ -234,6 +240,8 @@ function connectionKey(config) {
 export function _resetEndpointSupportTrackersForTests() {
     jsonSchemaUnsupportedConnections.clear();
     thinkingControlRejectedConnections.clear();
+    temperatureRejectedConnections.clear();
+    maxCompletionTokensConnections.clear();
 }
 /**
  * Whether this connection has already been proven, this process, not to
@@ -263,6 +271,10 @@ function isRejectedRequest(err) {
 }
 /** A strict API names the field it does not know: `Unknown parameter: 'chat_template_kwargs'.` */
 const THINKING_FIELD_NAMED = /chat_template_kwargs|enable_thinking/;
+/** `Unsupported value: 'temperature' does not support 0 with this model. Only the default (1) value is supported.` */
+const TEMPERATURE_NAMED = /'temperature'/;
+/** `Unsupported parameter: 'max_tokens' is not supported with this model. Use 'max_completion_tokens' instead.` */
+const MAX_TOKENS_REPLACED = /max_completion_tokens/;
 /**
  * A single chat-completion attempt: one HTTP request/response cycle, with an
  * inline fallback-once when a schema was requested and the provider 4xx's
@@ -275,7 +287,10 @@ const THINKING_FIELD_NAMED = /chat_template_kwargs|enable_thinking/;
  *
  * The thinking-control fields get the same treatment (#1045): a 4xx that
  * names `chat_template_kwargs` or `enable_thinking` is answered by one retry
- * without them, which may in turn fall back without the schema.
+ * without them, which may in turn fall back without the schema. A 4xx that
+ * names `temperature`, or asks for `max_completion_tokens`, is answered the
+ * same way: the connection stops sending `temperature`, or sends the token cap
+ * as `max_completion_tokens`, for the rest of the process.
  */
 async function chatCompletionAttempt(config, messages, options, timeoutMs, includeThinking = (options?.enableThinking ?? config.enableThinking) !== undefined &&
     !isThinkingControlKnownRejected(config)) {
@@ -286,6 +301,17 @@ async function chatCompletionAttempt(config, messages, options, timeoutMs, inclu
     catch (err) {
         if (!isRejectedRequest(err))
             throw err;
+        const key = connectionKey(config);
+        if (TEMPERATURE_NAMED.test(err.message) && !temperatureRejectedConnections.has(key)) {
+            warnVerbose(`[akm] LLM rejected temperature (${err.statusCode}); retrying once without it: ${err.message}`);
+            temperatureRejectedConnections.add(key);
+            return chatCompletionAttempt(config, messages, options, timeoutMs, includeThinking);
+        }
+        if (MAX_TOKENS_REPLACED.test(err.message) && !maxCompletionTokensConnections.has(key)) {
+            warnVerbose(`[akm] LLM rejected max_tokens (${err.statusCode}); retrying once with max_completion_tokens: ${err.message}`);
+            maxCompletionTokensConnections.add(key);
+            return chatCompletionAttempt(config, messages, options, timeoutMs, includeThinking);
+        }
         if (includeThinking && THINKING_FIELD_NAMED.test(err.message)) {
             warnVerbose(`[akm] LLM rejected chat_template_kwargs/enable_thinking (${err.statusCode}); retrying once without them: ${err.message}`);
             const fallback = await chatCompletionAttempt(config, messages, options, timeoutMs, false);
@@ -344,11 +370,15 @@ async function chatCompletionAttemptOnce(config, messages, options, timeoutMs, i
         ? {}
         : { chat_template_kwargs: { enable_thinking: resolvedEnableThinking }, enable_thinking: resolvedEnableThinking };
     const reasoningEffortParams = config.reasoningEffort === undefined ? {} : { reasoning_effort: config.reasoningEffort };
+    const key = connectionKey(config);
+    const maxTokensField = maxCompletionTokensConnections.has(key) ? "max_completion_tokens" : "max_tokens";
     const requestBody = JSON.stringify({
         model: config.model,
         messages,
-        temperature: options?.temperature ?? config.temperature ?? 0.3,
-        ...(resolvedMaxTokens !== undefined ? { max_tokens: resolvedMaxTokens } : {}),
+        ...(temperatureRejectedConnections.has(key)
+            ? {}
+            : { temperature: options?.temperature ?? config.temperature ?? 0.3 }),
+        ...(resolvedMaxTokens !== undefined ? { [maxTokensField]: resolvedMaxTokens } : {}),
         ...config.extraParams,
         ...responseFormat,
         ...thinkingParams,

package/dist/scripts/akm-migrate-node.js

@@ -36842,12 +36842,16 @@ function releaseLockRaw(lockPath) {
   } catch {}
 }
 function tryAcquireLockSync(lockPath, payload) {
+  const tmpPath = `${lockPath}.tmp-${process.pid}-${randomUUID()}`;
+  fs7.writeFileSync(tmpPath, payload, { flag: "wx" });
   try {
-    fs7.writeFileSync(lockPath, payload, { flag: "wx" });
+    fs7.linkSync(tmpPath, lockPath);
   } catch (err) {
     if (err.code === "EEXIST")
       return;
     throw err;
+  } finally {
+    releaseLockRaw(tmpPath);
   }
   let snapshot;
   try {

package/dist/scripts/akm-migrate.js

@@ -36170,12 +36170,16 @@ function releaseLockRaw(lockPath) {
   } catch {}
 }
 function tryAcquireLockSync(lockPath, payload) {
+  const tmpPath = `${lockPath}.tmp-${process.pid}-${randomUUID()}`;
+  fs7.writeFileSync(tmpPath, payload, { flag: "wx" });
   try {
-    fs7.writeFileSync(lockPath, payload, { flag: "wx" });
+    fs7.linkSync(tmpPath, lockPath);
   } catch (err) {
     if (err.code === "EEXIST")
       return;
     throw err;
+  } finally {
+    releaseLockRaw(tmpPath);
   }
   let snapshot;
   try {

package/docs/README.md

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

package/docs/agents/README.md

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

package/docs/agents/agent-install.md

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