akm-cli 0.10.261015-beta → 0.10.261016-beta

package/CHANGELOG.md

@@ -6,6 +6,79 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.10.261016] - 2026-10-27
+
+### Added
+
+- `akm show` returns a Markdown document's outline as `toc` (#1259): one
+  `{ level, text, slug, startLine }` entry per heading, at every `--detail`
+  level. `akm show <ref> --detail brief` is the outline without the body, and
+  every `slug` selects its section with `akm show <ref>#<slug>`, repeated
+  headings included. The outline is read from the file the section is cut
+  from. Fragment shows, non-Markdown assets and documents with no headings
+  carry no `toc`. The knowledge `action`, `akm show --help`, the unmatched
+  fragment error, `akm hints` and the OpenCode runtime's `akm_show` tool (which
+  takes `detail: "brief"`) now point agents at the outline first, then the
+  sections they need.
+
+### Changed
+
+- The Release workflow waits for CI on the commit it publishes, up to 25 minutes,
+  instead of failing when that run has not finished, so Release can be dispatched
+  right after the release commit is pushed. It still fails when CI failed or was
+  cancelled, and only the newest push or manual CI run counts: a pull request's
+  run tests a merge and, on a draft, skips the upgrade rehearsal.
+  `tests/release-check.sh` no longer repeats the upgrade rehearsal that CI runs on
+  the same commit.
+- `bun run check:ci` runs the pre-push check the way CI does (in a Docker
+  container with the Bun and Node versions `ci.yml` pins, a clean frozen install,
+  `CI=true` and four test shards); `.github/CONTRIBUTING.md` says when to run it.
+
+### Fixed
+
+- Two processes fetching the OpenCode binary akm's own runtime runs (or the local
+  embedder's ONNX Runtime files) into an empty cache at once no longer rename
+  their copies over each other (#1266). Each downloaded the package and renamed
+  its file into place, which unlinks a binary the other process is already
+  running (it then fails to start it again). One fetch now runs per cache
+  directory at a time, under a `fetch.lock` file in it (a dead holder's lock is
+  reclaimed); a process that finds the files in place once it holds the lock
+  downloads nothing, and a rename never replaces a file that is already whole.
+- `akm health`'s `plugin-version` advisory no longer reports a Claude Code
+  plugin on the `next` channel as stale against the 0.9 stable release. It read
+  the newest version with a semver rule that skips every prerelease. It now reads
+  the channel the marketplace clone follows: on `next`, the release tag on that
+  branch's head; on the default branch, the newest stable tag; on a marketplace
+  added at a tag, that tag.
+- When `crontab -l` cannot read the crontab spool (permission denied) in a
+  process started with no-new-privileges (an agent sandbox, a container, systemd
+  `NoNewPrivileges=`), akm says why: `crontab` reads the spool through its setgid
+  (or setuid) bit, which such a process does not grant. `akm health` and
+  `akm task` commands run from such a process used to repeat a bare
+  `fopen: Permission denied`. A refusal without no-new-privileges is reported as
+  before.
+- `akm health`'s `opencode-plugin-version` advisory reads the OpenCode 1 plugin
+  cache of the spec the global OpenCode config names (#1265). It read only
+  `packages/akm-opencode`, but OpenCode 1 caches each spec in its own folder, so
+  a host with `"plugin": ["akm-opencode@next"]` (cached in
+  `packages/akm-opencode@next`) showed no row at all. It now reads the one folder
+  of the spec under `plugin`: a bare name is `akm-opencode@latest`, as
+  `akm upgrade` reads it, and `akm-opencode@next` is its own folder. A version
+  pin (`akm-opencode@<version>`) is reported as pinned, with no staleness
+  verdict. With no entry, or no folder for it, the check reads
+  `packages/akm-opencode` as before; other cached specs are not scanned.
+
+### Security
+
+- Zod moves from 3.25.76 to 4.6.7 (`zod` `^4.6.6`), closing GHSA-mrhx-c7xc-m3w5 /
+  CVE-2023-54404 (high): Zod before 4.6.6 can exhaust memory validating a large array,
+  and no Zod 3 release has the fix. akm validates its config files with Zod. Visible
+  changes: an integer above 2^53 - 1 in a config file is now rejected; validation
+  messages are Zod 4's (an unknown enum value reads `Invalid option: expected one of ...`);
+  `schemas/akm-config.json` is generated with `z.toJSONSchema` (the `zod-to-json-schema`
+  dev dependency is gone): `additionalProperties: true` is written `{}` (the same), integers
+  state the new `maximum: 9007199254740991`, and every map states its `propertyNames`.
+
 ## [0.10.261015] - 2026-10-27
 
 ### Changed

package/STABILITY.md

@@ -201,7 +201,8 @@ enumeration of the whole `proposal` noun group.
   - `#fragment` is **input-only** and never stored. On markdown-document items
     the core resolves it as a section selector — `akm show <ref>#<heading-slug>`
     returns that one section, no fragment returns the whole item, and an
-    unmatched fragment lists the available slugs. Elsewhere it is an
+    unmatched fragment lists the available slugs. A whole document's `show`
+    carries `toc`, every heading with the slug that selects it. Elsewhere it is an
     adapter-owned selector opaque to the core. See
     [`docs/architecture/specs/ref.md`](https://github.com/itlackey/akm/blob/main/docs/architecture/specs/ref.md).
   - **Refs in prose** must be fully qualified (`bundle//conceptId`) or a native

package/dist/assets/hints/cli-hints-full.md

@@ -49,7 +49,9 @@ akm curate "review architecture" --type workflow # Restrict to one asset type
 ## Show
 
 Display an asset by ref from the local index and materialized bundle files only.
-On a markdown document `#fragment` selects one section by heading slug.
+On a markdown document `#fragment` selects one section by heading slug. For a
+large document, `akm show <ref> --detail brief` returns its outline (`toc`, no
+body); then `akm show <ref>#<slug>` reads only the sections you need.
 
 ```sh
 akm show scripts/deploy.sh                    # Show script (returns run command)
@@ -57,9 +59,9 @@ akm show skills/code-review                   # Show skill (returns full content
 akm show commands/release                     # Show command (returns template)
 akm show agents/architect                     # Show agent (returns system prompt)
 akm show workflows/ship-release               # Show parsed workflow steps
-akm show knowledge/guide                      # Whole document
+akm show knowledge/guide                      # Whole document, plus its `toc`
+akm show knowledge/guide --detail brief       # Outline only: `toc` (level, text, slug, startLine), no body
 akm show knowledge/guide#auth                 # Just the "Auth" section
-akm show knowledge/guide#nope                 # Lists the available fragment slugs
 akm show knowledge/my-doc                     # Show materialized local content
 ```
 
@@ -69,7 +71,7 @@ akm show knowledge/my-doc                     # Show materialized local content
 | skill | `content` (full SKILL.md) |
 | command | `template`, `description`, `parameters` |
 | agent | `prompt`, `description`, `modelHint` |
-| knowledge | `content` (whole document, or one section via `#fragment`) |
+| knowledge | `content` (whole document, or one section via `#fragment`); `toc` (each heading's `slug`) on a whole document |
 | workflow | `workflowTitle`, `workflowParameters`, `steps` |
 | memory | `content` (recalled context) |
 | env | `keys` (key names only — values and comment text never returned) |

package/dist/assets/hints/cli-hints-short.md

@@ -6,7 +6,7 @@ You have access to a searchable library of scripts, skills, commands, agents, kn
 
 For any task, follow this loop:
 1. `akm curate "<task>"` — find the best matching asset
-2. `akm show <ref>` — read the schema (field names and structure)
+2. `akm show <ref>` — read the schema (field names and structure). For a large document, `akm show <ref> --detail brief` returns its outline (`toc`, no body); then `akm show <ref>#<slug>` reads only the sections you need.
 3. Edit the workspace file using schema field names + task-specific values from your README
 4. `akm feedback <ref> --positive` — record that the asset helped (it raises its ranking and does not trigger a rewrite). Record negative feedback only when the asset's content is wrong or stale, and say what is wrong and what it should say. `akm feedback <ref> --negative --reason "<what is wrong and what should change>"` flags it: the next improve run may repair its description, title or `when_to_use` from your reason, but not its text. A note that simply did not fit your task is not negative feedback: record nothing for it. Once you have verified the correct fact, add the exact fix: `--replace "<exact current text>" --with "<corrected text>" --source "<URL, command or file>"`. A note that is outdated can be marked with `--outdated`, or `--superseded-by <ref>` when another note replaces it. A failed akm command (e.g. `akm show` erroring) is not feedback on the asset — don't record it.
 
@@ -27,6 +27,8 @@ akm search "<query>" --type workflow          # Filter to workflow assets
 akm search "memories/projectA/"               # List a subtree (conceptId prefix; trailing slash required)
 akm search "<query>" --from all               # Also search registries
 akm show <ref>                                # View asset details
+akm show <ref> --detail brief                 # Outline only: a document's `toc` (each heading's slug), no body
+akm show <ref>#<slug>                         # One section of a document
 akm help <command>                            # Show a command's options and subcommands
 akm workflow run <ref>                        # Start a new run and execute it
 akm remember "Deployment needs VPN access"    # Record a memory in your bundle
@@ -58,7 +60,7 @@ akm search "<query>" --from registry          # Search all registries (registry
 | skill | Instructions to follow (read the full content) |
 | command | A prompt template with placeholders to fill in |
 | agent | A system prompt with model and tool hints |
-| knowledge | A reference doc (append `#<heading-slug>` to the ref to read one section) |
+| knowledge | A reference doc; `toc` lists its sections and `<ref>#<slug>` reads one |
 | workflow | Parsed steps plus workflow-specific execution commands |
 | memory | Recalled context (read the content for background information) |
 | env | A `.env` file of configuration an app loads together (many vars; sensitive or not — all protected); key names only. Inject with `akm env run <ref> -- <cmd>` (the agent-safe path — values stay on disk). |

package/dist/assets/opencode/akm-plugin.js

@@ -6,11 +6,11 @@
 // it in the inline config's `plugins` list (src/integrations/harnesses/opencode/runtime/). It runs inside OpenCode, so
 // it imports no package: only Node's own child_process, to call back into akm.
 //
-//   - akm's three read tools, each a run of the akm that started OpenCode, with `--detail agent --format json`. akm
-//     passes the argv that runs it in `AKM_OPENCODE_CLI`, a JSON array: the executable alone for a compiled akm, the
-//     runtime and the script for one run as a script (Node and `dist/akm`, say), so no shebang or shell is needed on
-//     any platform. The run's environment is the call's, so a stamped run's reads (`AKM_EVENT_SOURCE`) are recorded as
-//     that run's.
+//   - akm's three read tools, each a run of the akm that started OpenCode, with `--detail agent --format json`
+//     (`--detail brief` when akm_show asks for a document's outline). akm passes the argv that runs it in
+//     `AKM_OPENCODE_CLI`, a JSON array: the executable alone for a compiled akm, the runtime and the script for one
+//     run as a script (Node and `dist/akm`, say), so no shebang or shell is needed on any platform. The run's
+//     environment is the call's, so a stamped run's reads (`AKM_EVENT_SOURCE`) are recorded as that run's.
 //   - The environment of the commands the agent runs: the variables akm set for the OpenCode process (its roots and
 //     its OpenCode settings) are put back to what akm runs in, or removed, so the agent's shell sees the environment a
 //     harness's child would.
@@ -59,8 +59,16 @@ const TOOLS = [
     name: "akm_show",
     command: "show",
     positional: "ref",
-    description: "Read one akm asset by its ref, as returned by akm_curate or akm_search.",
-    input: { type: "object", properties: { ref: { type: "string" } }, required: ["ref"] },
+    description:
+      'Read one akm asset by its ref, as returned by akm_curate or akm_search. For a large document, call it with detail "brief" for its outline (toc, no body), then with ref#<slug> for only the sections you need.',
+    input: {
+      type: "object",
+      properties: {
+        ref: { type: "string" },
+        detail: { type: "string", enum: ["brief"], description: "brief: the outline (toc) without the body" },
+      },
+      required: ["ref"],
+    },
   },
 ];
 
@@ -78,7 +86,7 @@ function cliArguments(tool, input) {
     ...(type && tool.positional !== "ref" ? ["--type", type] : []),
     ...(limit && tool.positional !== "ref" ? ["--limit", limit] : []),
     "--detail",
-    "agent",
+    tool.positional === "ref" && input?.detail === "brief" ? "brief" : "agent",
     "--format",
     "json",
   ];

package/dist/assets/prompts/workflow-unit-preamble.md

@@ -9,7 +9,9 @@ Ground rules for this unit:
 
 1. Pull knowledge on demand instead of guessing: `akm search '<query>'` to find
    relevant assets, `akm show <ref>` to read one, `akm curate '<query>'` to let
-   akm select the best match. Only pull what this unit actually needs.
+   akm select the best match. Only pull what this unit actually needs: for a
+   large document, `akm show <ref> --detail brief` returns its outline (`toc`,
+   no body), then `akm show <ref>#<slug>` reads one section.
 2. Environment values and secrets are provided through your process
    environment when the workflow declares them. Never print secret values to
    stdout or embed them in your answer. If you need an env file path, use

package/dist/commands/health/plugin-staleness.js

@@ -35,7 +35,7 @@
  * local marketplace clone is not proof of what is newest upstream — the
  * incident above involved a clone that hadn't seen the fix's tag at all — so
  * the only way to ever detect drift is to ask the remote what tags exist.
- * That query is a `git ls-remote --tags` (lists refs; fetches nothing,
+ * That query is a `git ls-remote --symref` (lists refs; fetches nothing,
  * writes nothing) with a short timeout, and any failure (offline, no
  * remote, timeout) degrades to "installed version reported, no staleness
  * claim" rather than a false positive or a hang. Like `cli-version`, this
@@ -54,7 +54,8 @@ import os from "node:os";
 import path from "node:path";
 import { OPENCODE_V1, OPENCODE_V2, readPackageVersion, } from "../../integrations/harnesses/opencode/plugin-layout.js";
 import { opencodeCacheDir } from "../../integrations/harnesses/opencode/roots.js";
-import { isExactSemver, isSemverRange, maxSatisfying, satisfiesRange } from "../../registry/semver.js";
+import { highestVersion, isExactSemver, isPrerelease, isSemverRange, satisfiesRange } from "../../registry/semver.js";
+import { openCodeConfigSpec } from "../sources/plugin-upgrade.js";
 /**
  * Root directory holding Claude Code's plugin cache + marketplace clones.
  * Resolved per call (not memoized) so `AKM_CLAUDE_PLUGINS_DIR` can be set
@@ -78,12 +79,26 @@ function defaultOpencodeCacheRoot() {
 }
 const OPENCODE_PLUGIN_LOCATIONS = [
     {
-        // OpenCode 1: <cache>/packages/akm-opencode/node_modules/akm-cli (the folder read since this check began).
+        // OpenCode 1: <cache>/packages/<spec>/node_modules/akm-cli, the one spec the global config names (#1265).
         flavor: OPENCODE_V1,
         advisory: "opencode-plugin-version",
         label: "OpenCode's",
         remedy: "update the OpenCode plugin",
-        folders: (cacheRoot) => [{ folder: path.join(cacheRoot, OPENCODE_V1.cacheFolder(OPENCODE_V1.pkg)) }],
+        folders: (cacheRoot) => {
+            // OpenCode caches each spec in its own folder, and a bare name is its `@latest`, as `akm upgrade` reads it. With
+            // no config entry, or no folder for the spec, the bare `packages/akm-opencode` is read, as this check always has.
+            const { pkg } = OPENCODE_V1;
+            const bare = { folder: path.join(cacheRoot, OPENCODE_V1.cacheFolder(pkg)) };
+            const named = openCodeConfigSpec(OPENCODE_V1)?.spec;
+            if (named === undefined)
+                return [bare];
+            const spec = named === pkg ? `${pkg}@latest` : named;
+            const folder = path.join(cacheRoot, OPENCODE_V1.cacheFolder(spec));
+            if (!fs.existsSync(folder))
+                return [bare];
+            const version = spec.slice(pkg.length + 1);
+            return [{ spec, folder, ...(isExactSemver(version) ? { pinned: version } : {}) }];
+        },
     },
     {
         // OpenCode 2: <cache>/npm/akm-opencode-v2@<spec>/<epoch-ms>/node_modules/akm-cli, newest build per spec.
@@ -110,11 +125,11 @@ const OPENCODE_PLUGIN_LOCATIONS = [
  */
 function findBundledAkm(plugin, cacheRoot) {
     const found = [];
-    for (const { spec, folder } of plugin.folders(cacheRoot)) {
+    for (const { spec, pinned, folder } of plugin.folders(cacheRoot)) {
         const nodeModules = plugin.flavor.nodeModulesDir(folder);
         const version = nodeModules && readPackageVersion(path.join(nodeModules, "akm-cli", "package.json"));
         if (version !== undefined)
-            found.push(spec ? { spec, version } : { version });
+            found.push({ ...(spec ? { spec } : {}), ...(pinned ? { pinned } : {}), version });
     }
     return found;
 }
@@ -122,6 +137,17 @@ function buildOpencodeBundledAdvisory(plugin, bundled, cliVersion) {
     const bundledVersion = bundled.version;
     const stale = bundledVersion !== cliVersion;
     const where = bundled.spec ? ` (${bundled.spec})` : "";
+    if (bundled.pinned) {
+        // The config chose this build: there is nothing to update it to, so no staleness verdict.
+        return {
+            name: plugin.advisory,
+            kind: "deterministic",
+            status: "pass",
+            confidence: "high",
+            message: `${plugin.label} plugin is pinned to v${bundled.pinned}${where}; its bundled akm-cli is v${bundledVersion}, and a pinned plugin is not compared with the running CLI v${cliVersion}.`,
+            evidence: { bundledVersion, cliVersion, spec: bundled.spec, pinnedVersion: bundled.pinned },
+        };
+    }
     return {
         name: plugin.advisory,
         kind: "deterministic",
@@ -161,7 +187,7 @@ function detectInstalledPlugins(pluginsRoot) {
         }
         if (versions.length === 0)
             continue;
-        const latest = maxSatisfying(versions, "*") ?? versions.sort().at(-1);
+        const latest = highestVersion(versions);
         if (!latest)
             continue;
         const versionDir = path.join(pluginDir, latest);
@@ -204,16 +230,31 @@ function readVersionRange(pluginDir) {
 }
 const LS_REMOTE_TIMEOUT_MS = 5_000;
 /**
- * `git ls-remote --tags origin` against the marketplace clone's configured
- * remote — lists refs only, fetches no objects, writes no local refs.
- * Returns `undefined` (never throws) when the directory is not a git
- * checkout, has no `origin` remote, or the command fails/times out (e.g.
- * offline) — all "cannot determine availability", not "up to date".
+ * `git ls-remote --symref origin` against the marketplace clone's configured remote (lists refs only, fetches no
+ * objects, writes no local refs), read for the channel the clone follows:
+ *
+ * - **The remote's default branch** (stable): every stable release tag; the newest is the highest of them.
+ * - **Any other branch** (a channel such as `next`): the release tags on that branch's head. A channel branch is
+ *   reset to each build it publishes, so its head IS the newest build of the channel, whatever semver order says
+ *   about other tags (retired build schemes can sort above current builds).
+ * - **No branch** (a marketplace added at a tag ref, which Claude Code clones detached): the release tag the clone
+ *   is pinned to. A pinned marketplace never offers anything newer, so `claude plugin update` could not act on a
+ *   newer tag elsewhere. A detached clone at an untagged commit reads like the default branch.
+ *
+ * Returns `undefined` (never throws) when the directory is not a git checkout, has no `origin` remote, or the
+ * command fails/times out (e.g. offline): all "cannot determine availability", not "up to date". A channel head
+ * with no release tag returns `[]`, which reads the same way.
  */
 const realListRemoteTags = (marketplaceDir) => {
     let result;
+    let branch;
     try {
-        result = spawnSync("git", ["-C", marketplaceDir, "ls-remote", "--tags", "origin"], {
+        branch =
+            spawnSync("git", ["-C", marketplaceDir, "branch", "--show-current"], {
+                encoding: "utf8",
+                timeout: LS_REMOTE_TIMEOUT_MS,
+            }).stdout?.trim() ?? "";
+        result = spawnSync("git", ["-C", marketplaceDir, "ls-remote", "--symref", "origin"], {
             encoding: "utf8",
             timeout: LS_REMOTE_TIMEOUT_MS,
         });
@@ -223,16 +264,39 @@ const realListRemoteTags = (marketplaceDir) => {
     }
     if (result.status !== 0 || !result.stdout)
         return undefined;
-    const tags = result.stdout
+    const refs = result.stdout
         .split("\n")
         .map((line) => line.trim())
         .filter(Boolean)
-        .map((line) => line.split("\t")[1])
-        .filter((ref) => typeof ref === "string" && ref.startsWith("refs/tags/"))
-        .map((ref) => ref.replace(/^refs\/tags\//, "").replace(/\^\{\}$/, ""))
-        .map((tag) => tag.replace(/^v/, ""))
-        .filter(isExactSemver);
-    return [...new Set(tags)];
+        .map((line) => line.split("\t"));
+    const defaultBranch = refs
+        .find(([value, name]) => name === "HEAD" && value?.startsWith("ref: refs/heads/"))?.[0]
+        ?.replace(/^ref: refs\/heads\//, "");
+    const tags = refs
+        .filter(([, name]) => typeof name === "string" && name.startsWith("refs/tags/"))
+        .map(([sha, name]) => ({
+        sha: sha,
+        version: name
+            .replace(/^refs\/tags\//, "")
+            .replace(/\^\{\}$/, "")
+            .replace(/^v/, ""),
+    }))
+        .filter((tag) => isExactSemver(tag.version));
+    const tagsAt = (sha) => [
+        ...new Set(tags.filter((tag) => tag.sha === sha).map((tag) => tag.version)),
+    ];
+    const onChannelBranch = branch !== "" && defaultBranch !== undefined && branch !== defaultBranch;
+    if (onChannelBranch)
+        return tagsAt(refs.find(([, name]) => name === `refs/heads/${branch}`)?.[0]);
+    if (branch === "") {
+        const pinned = tagsAt(spawnSync("git", ["-C", marketplaceDir, "rev-parse", "HEAD"], {
+            encoding: "utf8",
+            timeout: LS_REMOTE_TIMEOUT_MS,
+        }).stdout?.trim());
+        if (pinned.length > 0)
+            return pinned;
+    }
+    return [...new Set(tags.map((tag) => tag.version).filter((version) => !isPrerelease(version)))];
 };
 /**
  * Build one `plugin-version` advisory per detected `akm` harness plugin,
@@ -263,14 +327,14 @@ function buildAdvisory(plugin, cliVersion, pluginsRoot, listRemoteTags, probe) {
     let availableVersion;
     try {
         const tags = probe && fs.existsSync(marketplaceDir) ? listRemoteTags(marketplaceDir) : undefined;
-        availableVersion = tags && tags.length > 0 ? maxSatisfying(tags, "*") : undefined;
+        availableVersion = tags && tags.length > 0 ? highestVersion(tags) : undefined;
     }
     catch {
         availableVersion = undefined;
     }
     const stale = availableVersion !== undefined &&
         plugin.version !== availableVersion &&
-        maxSatisfying([plugin.version, availableVersion], "*") === availableVersion;
+        highestVersion([plugin.version, availableVersion]) === availableVersion;
     // Point 3: does the plugin's own declared range admit the running CLI?
     const versionRange = readVersionRange(plugin.pluginDir);
     const rangeKnown = versionRange !== undefined && isSemverRange(versionRange);

package/dist/commands/read/search-cli.js

@@ -177,7 +177,7 @@ function rejectExtraShowPositionals(positionals, ref) {
     if (extra.length === 0)
         return;
     throw new UsageError(`akm show takes a single ref, but got ${extra.map((token) => `"${token}"`).join(" ")} after "${ref}". ` +
-        `Use \`akm show ${ref}#<heading-slug>\` to read one section, or \`akm show ${ref}\` for the whole item.`, "INVALID_FLAG_VALUE", "An unmatched #fragment lists the available slugs.");
+        `Use \`akm show ${ref}#<heading-slug>\` to read one section, or \`akm show ${ref}\` for the whole item.`, "INVALID_FLAG_VALUE", `Run \`akm show ${ref} --detail brief\` for the document's outline (\`toc\`, no body).`);
 }
 export const showCommand = defineJsonCommand({
     meta: {
@@ -187,7 +187,7 @@ export const showCommand = defineJsonCommand({
     args: {
         ref: {
             type: "positional",
-            description: "Asset ref ([bundle//]conceptId[#fragment]). On a markdown document `#fragment` selects one section by heading slug, and an unmatched fragment lists the available slugs. Example: `akm show knowledge/guide.md#auth`.",
+            description: "Asset ref ([bundle//]conceptId[#fragment]). On a markdown document `#fragment` selects one section by heading slug; `--detail brief` returns the outline (`toc`, each heading's slug) without the body. Example: `akm show knowledge/guide.md#auth`.",
             required: true,
         },
         filter: {

package/dist/commands/read/show.js

@@ -20,7 +20,7 @@ import { recognizeMatch } from "../../core/adapter/recognize-match.js";
 import { assetPathForName, stashDirFor } from "../../core/asset/asset-placement.js";
 import { makeBundleRef, parseBundleRef } from "../../core/asset/asset-ref.js";
 import { parseFrontmatter } from "../../core/asset/frontmatter.js";
-import { extractSection, markdownFragmentSlugs } from "../../core/asset/markdown.js";
+import { extractSection, markdownFragmentSlugs, markdownToc } from "../../core/asset/markdown.js";
 import { buildMarkdownLeadContext, fragmentForSelector, MARKDOWN_FRAGMENT_CONTEXT_DEFAULT_MAX_CHARS, } from "../../core/asset/markdown-fragments.js";
 import { displayRef, displayRefForConceptId, typeNameFromConceptId } from "../../core/asset/resolve-ref.js";
 import { META_DIR, parseMetaRef, readMetaFile } from "../../core/asset/stash-meta.js";
@@ -297,8 +297,10 @@ export async function showLocal(input) {
     const indexedFragmentContent = opaqueFragmentSelector ? indexedFragment?.content : undefined;
     const indexedRenderer = rendererForIndexedEntry(indexedEntry, fileCtx);
     let response;
+    let markdown = false;
     try {
         if (indexedRenderer === null) {
+            markdown = path.extname(assetPath).toLowerCase() === ".md";
             response = buildIndexedProjectionResponse(indexedEntry, assetPath, parsed.fragment, indexedFragmentContent);
         }
         else {
@@ -315,8 +317,9 @@ export async function showLocal(input) {
             const renderDefaultBundle = config.defaultBundle ?? (source?.isDefault === true ? renderBundle : undefined);
             const renderCtx = buildRenderContext(fileCtx, match, allSourceDirs, renderBundle, renderDefaultBundle);
             response = renderer.buildShowResponse(renderCtx);
+            markdown = match.renderer.endsWith("-md");
             if (parsed.fragment !== undefined) {
-                if (!match.renderer.endsWith("-md")) {
+                if (!markdown) {
                     warn(`Fragment "#${parsed.fragment}" was ignored: ${makeBundleRef(parsed.bundle, parsed.conceptId)} is not a Markdown document, so heading fragments do not apply. Showing the whole asset.`);
                 }
                 else {
@@ -324,6 +327,13 @@ export async function showLocal(input) {
                 }
             }
         }
+        // The outline is read from the bytes `#<slug>` resolves against, so every
+        // listed slug selects its section even when the index is stale.
+        if (markdown && parsed.fragment === undefined) {
+            const toc = markdownToc(fileCtx.content());
+            if (toc.length > 0)
+                response.toc = toc;
+        }
     }
     catch (error) {
         throwIndexedPathNotFound(error, input.ref);
@@ -598,6 +608,7 @@ function applyMarkdownResponsePayload(response, content) {
     else
         response.content = content;
 }
+const SHOW_OUTLINE_HINT = "Run `akm show <ref> --detail brief` for the document's outline (`toc`, no body), then `akm show <ref>#<slug>` for one section.";
 function requireMarkdownSection(content, fragment, name) {
     const section = extractSection(content, fragment);
     if (section)
@@ -609,7 +620,7 @@ function requireMarkdownSection(content, fragment, name) {
     }
     const available = markdownFragmentSlugs(content);
     throw new NotFoundError(`Fragment "#${fragment}" not found in ${name}.` +
-        (available.length > 0 ? ` Available fragments: ${available.map((slug) => `#${slug}`).join(", ")}.` : ""));
+        (available.length > 0 ? ` Available fragments: ${available.map((slug) => `#${slug}`).join(", ")}.` : ""), "ASSET_NOT_FOUND", SHOW_OUTLINE_HINT);
 }
 /**
  * Build a reduced brief response from a full ShowResponse.
@@ -625,6 +636,7 @@ function buildBriefResponse(full, assetPath) {
         ...(summary.ref ? { ref: summary.ref } : {}),
         ...(summary.description ? { description: summary.description } : {}),
         ...(summary.action ? { action: summary.action } : {}),
+        ...(full.toc ? { toc: full.toc } : {}),
         ...(summary.run ? { run: summary.run } : {}),
         ...(summary.origin !== undefined ? { origin: summary.origin } : {}),
         ...(full.editable !== undefined ? { editable: full.editable } : {}),

package/dist/core/asset/markdown.js

@@ -16,6 +16,15 @@ export function markdownHeadingSlug(heading) {
 export function markdownFragmentSlugs(content) {
     return uniqueHeadingSlugs(parseMarkdownToc(content).headings).filter(Boolean);
 }
+/**
+ * The headings `extractSection` can select, with the slug it resolves each by.
+ * A heading with no sluggable text has no selector, so it is left out.
+ */
+export function markdownToc(content) {
+    const headings = parseMarkdownToc(content).headings;
+    const slugs = uniqueHeadingSlugs(headings);
+    return headings.flatMap((heading, index) => slugs[index] ? [{ level: heading.level, text: heading.text, slug: slugs[index], startLine: heading.line }] : []);
+}
 /** One slug per heading, in order; a heading with no sluggable text gets "". */
 export function uniqueHeadingSlugs(headings) {
     const used = new Set();

package/dist/core/config/config-walker.js

@@ -27,7 +27,7 @@ import { hasRegistryUrlCredentials, REGISTRY_CREDENTIALS_UNSUPPORTED } from "../
 import { warnOnce } from "../warn.js";
 import { AkmConfigBaseSchema, listTopLevelConfigKeys } from "./config-schema.js";
 import { deepMergeConfig } from "./deep-merge.js";
-import { isEnvReference } from "./schema/primitives.js";
+import { isEnvReference, OpaqueFieldSchema } from "./schema/primitives.js";
 /**
  * Parse a dotted path into segments. Empty segments are rejected. Bracket
  * notation (e.g. `sources[0]`) is NOT supported — arrays are set as JSON.
@@ -46,33 +46,39 @@ function parsePath(dotted) {
 function unwrap(schema) {
     let current = schema;
     while (true) {
-        if (current instanceof z.ZodOptional) {
-            current = current._def.innerType;
-        }
-        else if (current instanceof z.ZodDefault) {
-            current = current._def.innerType;
-        }
-        else if (current instanceof z.ZodNullable) {
-            current = current._def.innerType;
-        }
-        else if (current instanceof z.ZodCatch) {
+        if (current instanceof z.ZodOptional ||
+            current instanceof z.ZodDefault ||
+            current instanceof z.ZodNullable ||
             // `.catch(...)` wraps an inner schema with a fallback value.
-            current = current._def.innerType;
+            current instanceof z.ZodCatch ||
+            current instanceof z.ZodReadonly) {
+            current = current.def.innerType;
         }
-        else if (current instanceof z.ZodEffects) {
-            // `.refine()` / `.superRefine()` / `.transform()` / `.preprocess()` —
-            // descend into the inner schema (`schema` for refine/transform, `out`
-            // for preprocess — both are exposed at `_def.schema`).
-            current = current._def.schema;
-        }
-        else if (current instanceof z.ZodReadonly) {
-            current = current._def.innerType;
+        else if (current instanceof z.ZodPipe) {
+            // `.transform()` pipes the schema into a transform and `z.preprocess()` pipes a transform into it:
+            // descend into the side that is a schema. (`.refine()` and `.superRefine()` wrap nothing.)
+            const { in: input, out } = current.def;
+            current = (input instanceof z.ZodTransform ? out : input);
         }
         else {
             return current;
         }
     }
 }
+/**
+ * The schema of the keys an object takes without naming them (`index.<passName>`,
+ * a connection's request fields), or `undefined` when its extra keys are not
+ * ones akm defines. `.passthrough()` gives an object an `unknown` catchall, so
+ * only `OpaqueFieldSchema` itself says "any key, contents left to the endpoint".
+ */
+function namedCatchall(object) {
+    const catchall = object.def.catchall;
+    if (catchall === undefined || catchall instanceof z.ZodNever)
+        return undefined;
+    if (catchall instanceof z.ZodUnknown && catchall !== OpaqueFieldSchema)
+        return undefined;
+    return catchall;
+}
 /** True for a schema that accepts any value (`z.unknown()`): its contents are not keys akm defines. */
 export function isOpaqueSchema(schema) {
     return unwrap(schema) instanceof z.ZodUnknown;
@@ -91,13 +97,10 @@ export function resolveSchemaAt(path, config, raw) {
             const next = schema.shape[segment];
             if (!next) {
                 // Catchall (e.g. index.<passName>) — descend into the catchall schema.
-                const catchall = schema._def.catchall;
-                if (catchall && !(catchall instanceof z.ZodNever)) {
-                    schema = catchall;
-                }
-                else {
+                const catchall = namedCatchall(schema);
+                if (!catchall)
                     return undefined;
-                }
+                schema = catchall;
             }
             else {
                 schema = next;
@@ -106,13 +109,13 @@ export function resolveSchemaAt(path, config, raw) {
         else if (schema instanceof z.ZodRecord) {
             // Named records (connections, harnesses, improve.strategies, sources, etc.)
             // accept any string key — descend into the value schema.
-            schema = schema._def.valueType;
+            schema = schema.def.valueType;
         }
         else if (schema instanceof z.ZodUnion) {
-            const option = selectUnionObjectOption(schema._def.options, segment, existing, index === path.length - 1 ? raw : undefined);
+            const option = selectUnionObjectOption(schema.options, segment, existing, index === path.length - 1 ? raw : undefined);
             if (!option)
                 return undefined;
-            schema = (option.shape[segment] ?? option._def.catchall);
+            schema = (option.shape[segment] ?? namedCatchall(option));
         }
         else {
             // Cannot descend into a non-object schema.
@@ -145,7 +148,7 @@ function selectUnionObjectOption(candidates, segment, existing, raw) {
     }
     return (options.find((option) => segment in option.shape) ??
         // A model entry such as `{ model, reasoning_effort }` holds request fields the object does not name.
-        options.find((option) => !(option._def.catchall instanceof z.ZodNever)));
+        options.find((option) => namedCatchall(option) !== undefined));
 }
 /**
  * Get the value at the dotted path from a config-shaped object. Returns
@@ -350,7 +353,7 @@ function coerceForSchema(schema, raw, key) {
         return raw;
     }
     if (target instanceof z.ZodLiteral) {
-        return typeof target._def.value === "string" ? raw : target._def.value;
+        return typeof target.value === "string" ? raw : target.value;
     }
     if (target instanceof z.ZodArray || target instanceof z.ZodObject || target instanceof z.ZodRecord) {
         if (raw === "" || raw === "null")
@@ -366,7 +369,7 @@ function coerceForSchema(schema, raw, key) {
     if (target instanceof z.ZodUnion) {
         // Try each option in order. Use the first that the schema accepts after
         // coercion. Falls through to JSON parsing if all fail.
-        const options = target._def.options;
+        const options = target.options;
         let lastErr;
         for (const opt of options) {
             try {