akm-cli 0.10.261015-beta → 0.10.261016-beta

package/dist/tasks/backends/cron.js

@@ -438,6 +438,15 @@ function readCrontab(exec) {
     const stderr = (result.stderr ?? "").trim();
     if (((result.stdout ?? "").trim() === "" && stderr === "") || /no crontab/i.test(stderr))
         return "";
+    // `crontab` reads the spool through its setgid `crontab` group (setuid root on some distributions). A process
+    // started with no-new-privileges (an agent sandbox, a container, systemd `NoNewPrivileges=`) runs it without that
+    // privilege, and the spool refuses the read. The crontab itself is fine, so say so instead of passing on a bare
+    // `fopen` error. Without no-new-privileges a refusal has another cause and is reported as what it said.
+    if (result.noNewPrivileges && /permission denied/i.test(stderr)) {
+        throw new ConfigError("crontab -l could not read the crontab spool (permission denied). `crontab` reads it through its setgid " +
+            "(or setuid) bit, which this process, started with no-new-privileges (an agent sandbox, a container, " +
+            "systemd NoNewPrivileges=), does not grant; run this from a normal shell to see the installed tasks.", "INVALID_CONFIG_FILE", "Run the command from a normal login shell or terminal, not from a sandboxed process.");
+    }
     throw new ConfigError(`crontab -l failed (exit ${result.status}): ${result.stderr || result.stdout || "no output"}.`, "INVALID_CONFIG_FILE", "The `crontab` binary ran but did not report success; check its output above.");
 }
 function writeCrontab(exec, content) {
@@ -463,6 +472,15 @@ function replaceCrontab(exec, existing, next) {
         throw err;
     }
 }
+/** Whether this process has Linux's no-new-privileges flag, which every child (`crontab` included) inherits. */
+function hasNoNewPrivileges() {
+    try {
+        return /^NoNewPrivs:\s*1$/m.test(fs.readFileSync("/proc/self/status", "utf8"));
+    }
+    catch {
+        return false;
+    }
+}
 function defaultCronExec() {
     const run = (args, input) => {
         const r = spawnSync("crontab", args, { encoding: "utf8", ...(input !== undefined ? { input } : {}) });
@@ -471,6 +489,7 @@ function defaultCronExec() {
             stdout: r.stdout ?? "",
             stderr: r.stderr ?? "",
             enoent: r.error?.code === "ENOENT",
+            noNewPrivileges: r.status !== 0 && hasNoNewPrivileges(),
         };
     };
     return {

package/docs/architecture/internals/health-advisories.md

@@ -37,7 +37,7 @@ changes.
 | `index-state-generation` | Durable usage links in `state.db` disagree with the current searchable index generation, which an interrupted cross-database update leaves behind. | Stop concurrent writers, then run `akm index --full` to relink state to the current index. |
 | `cli-version` | (#950) Compares the installed akm-cli version against the latest GitHub release (the same source `akm upgrade` trusts). `--probe`-gated: `unknown` "not probed" with `--no-probe`; offline/rate-limited also degrades to `unknown`, never a false `warn`. | Run `akm upgrade` when a newer release is reported. An `unknown` result carries no staleness claim either way — check manually if it matters. |
 | `scheduler-binary` | (#953) Reads the scheduler's recorded akm invocation for the installed tasks (the same binding `task sync`/`task doctor` already read — no crontab/launchd/schtasks text parsing) and runs it with `--version`, compared against the running CLI's version. `--probe`-gated: `unknown` "not probed" with `--no-probe`. `unknown` when no scheduled task is installed or the recorded binary cannot be executed. | A `warn` names both versions — upgrading akm through a different installer than the one active at the last `task sync` left the schedule pointed at the old binary; run `akm task sync` to rebind it. |
-| `plugin-version` / `opencode-plugin-version` | (itlackey/akm#832,) `plugin-version` reports each installed Claude Code harness plugin's version and its declared `AKM_VERSION_RANGE` admission of the running CLI. `opencode-plugin-version` does the same for the OpenCode plugin's own bundled `akm-cli` (read from its `package.json`, never executed) — it runs in-process and shares the host's databases, so its lag matters the same way. `plugin-version`'s newest-tag lookup is `--probe`-gated: with `--no-probe` its row is `unknown` ("not probed") and only the local range check still runs. `opencode-plugin-version` reads local files only and is never gated. | A `warn` names the stale/out-of-range plugin and the update command (`claude plugin update <ref>` for the Claude plugin; update the OpenCode plugin for the bundled copy). |
+| `plugin-version` / `opencode-plugin-version` | (itlackey/akm#832,) `plugin-version` reports each installed Claude Code harness plugin's version and its declared `AKM_VERSION_RANGE` admission of the running CLI. `opencode-plugin-version` does the same for the OpenCode plugin's own bundled `akm-cli` (read from its `package.json`, never executed) — it runs in-process and shares the host's databases, so its lag matters the same way. OpenCode 1 caches each spec in its own folder, so `opencode-plugin-version` reads the one folder of the spec the global OpenCode config names under `plugin` (`akm-opencode`, read as `akm-opencode@latest`, or `akm-opencode@next`), and for `akm-opencode@<version>` reports the plugin as pinned with no staleness verdict; with no entry, or no folder for it, it reads `packages/akm-opencode`, and it never scans the other cached specs. The newest version is read on the channel the marketplace clone follows: on the remote's default branch the newest stable tag, on any other branch (such as `next`) the release tag on that branch's head, and on a clone pinned to a tag that tag. `plugin-version`'s newest-tag lookup is `--probe`-gated: with `--no-probe` its row is `unknown` ("not probed") and only the local range check still runs. `opencode-plugin-version` reads local files only and is never gated. | A `warn` names the stale/out-of-range plugin and the update command (`claude plugin update <ref>` for the Claude plugin; update the OpenCode plugin for the bundled copy). |
 
 ## Connections, harnesses and the work on them
 

package/docs/architecture/specs/ref.md

@@ -132,8 +132,9 @@ runs collapsed to `-`, trimmed) and match the fragment against those slugs;
 fall back to a case-insensitive match against raw heading text. The selected
 region runs from that heading to the next heading of the same or higher level.
 A fragment that matches no heading is an error that **lists the available
-fragment slugs** — that error is the discovery mechanism, replacing the removed
-`toc` view mode.
+fragment slugs**. The outline itself is `akm show <ref> --detail brief`, whose
+`toc` lists every heading with the slug that selects it; it replaces the
+removed `toc` view mode.
 
 **Every other item kind — adapter-owned selector.** When one item exposes
 multiple exports the adapter MAY append a stable fragment
@@ -157,7 +158,7 @@ is removed. It was a second argv parser (`normalizeShowArgv` rewrote
 | --- | --- |
 | `akm show X section "Auth"` | `akm show X#auth` |
 | `akm show X full` | `akm show X` (no fragment = whole item) |
-| `akm show X toc` | `akm show X#<unmatched>` lists available fragment slugs |
+| `akm show X toc` | `akm show X --detail brief` (its `toc` field) |
 | `akm show X lines 10 30` | removed — every response carries `path`; slice the file |
 | `akm show X frontmatter` | removed — if a raw-YAML projection proves necessary it returns as a `--shape` value, the designated projection axis |
 

package/docs/architecture/testing/testing-workflow.md

@@ -406,9 +406,9 @@ For a local release gate without Docker, use:
 ./tests/release-check.sh --skip-docker
 ```
 
-That script checks the packaged artifact: bin targets, the migrator, package
-acceptance, and the upgrade rehearsal against the packed tarball. Lint, the
-typecheck and the test suites are `bun run check`.
+That script checks the packaged artifact: bin targets, the migrator and package
+acceptance. Lint, the typecheck and the test suites are `bun run check`; the
+upgrade rehearsal runs in CI.
 
 The Release workflow runs Gated CI (real embeddings, Docker, and the
 Linux/macOS/Windows schedulers) on the commit it publishes and requires CI to
@@ -521,17 +521,16 @@ throws naming the fix instead. Env overrides:
   resolving the highest published stable version below the candidate's
   `package.json` version.
 - `AKM_CANDIDATE_TARBALL=<path>` — use an already-packed candidate tarball
-  (`tests/release-check.sh` passes `$PACKAGE_CANDIDATE`) instead of running
-  `npm pack` on the working tree (which requires `dist/cli.js` — run
-  `bun run build` first).
+  instead of running `npm pack` on the working tree (which requires
+  `dist/cli.js` — run `bun run build` first).
 
 Fetched previous-release tarballs are cached under
 `${TMPDIR:-/tmp}/akm-upgrade-rehearsal/previous-release/<version>/` so repeat
 runs do not re-hit the network. It is wired into CI as the `upgrade-rehearsal`
 job (`.github/workflows/ci.yml`), which runs on pushes to `main` and release
 branches, on manual runs and on every commit of a pull request that is ready
-for review (a draft pull request skips it until it is marked ready), and into
-`tests/release-check.sh` right after packing the release candidate.
+for review (a draft pull request skips it until it is marked ready). The Release
+workflow requires that CI run to pass on the commit it publishes.
 
 ## Coverage Gap Guide
 

package/docs/guides/discover-and-load.md

@@ -73,14 +73,21 @@ lookup to one installed bundle when a conceptId is ambiguous across bundles.
 
 ## 4. Load a document section
 
-Knowledge docs and other markdown assets can be large. Append `#fragment` to
-a ref to return one section by heading slug instead of the whole document:
+Knowledge docs and other markdown assets can be large. Read the outline first,
+then only the sections you need. `--detail brief` returns the document's `toc`
+without the body, and appending `#<slug>` to a ref returns one section:
 
 ```sh
+akm show knowledge/api-guide --detail brief
+# → {"toc": [{"level": 2, "text": "Authentication", "slug": "authentication", "startLine": 12}, ...], ...}
 akm show knowledge/api-guide#authentication
 # → just the "Authentication" section, not the full document
 ```
 
+Every `slug` in `toc` selects its section, including repeated headings, which
+get `-1`, `-2`, ... suffixes. A whole-document show carries the same `toc`
+next to the body.
+
 Search can also return an opaque `#akm-fragment-...` selector for a bounded
 piece of a long document. The exact selector remains the default. For memories
 whose opening context helps interpret a later matching turn, opt into bounded
@@ -96,8 +103,9 @@ reports `contextTruncated` in JSON. The response also distinguishes canonical
 `parentRef` from `selectedRef` and includes fragment position, line bounds,
 neighbors, and separate fragment/parent size estimates.
 
-An unmatched fragment lists the available slugs instead of erroring, so a
-guess that misses still tells you what to try next.
+An unmatched fragment is an error that lists the available slugs, so a guess
+that misses still tells you what to try next; `--detail brief` is the way to
+see them without guessing.
 
 ## 5. Record the outcome
 

package/docs/guides/getting-started.md

@@ -198,8 +198,9 @@ akm show <ref>            # e.g. akm show workflows/deploy
 
 **Success check:** structured JSON with everything an agent needs to use the
 asset — a `run` command plus optional `cwd` and `setup` for scripts, a
-`prompt` payload for agents, or the document `content` for knowledge (append
-`#<heading-slug>` to a ref for one section).
+`prompt` payload for agents, or the document `content` for knowledge (with
+`--detail brief`, just its outline `toc`; append `#<slug>` to a ref for one
+section).
 
 AKM retrieves every supported capability type. It directly orchestrates
 defined execution surfaces such as workflows, agent dispatch, tasks, and

package/docs/guides/use-with-any-agent.md

@@ -52,7 +52,10 @@ akm feedback workflows/deploy-to-prod --positive --reason "Completed without iss
 
 **Get refs from search.** Agents should call `akm search --detail agent` or
 `akm curate` to discover refs — not guess them. The `ref` field in search
-results is the stable token to pass to `akm show`. Feedback closes the loop.
+results is the stable token to pass to `akm show`. For a long document,
+`akm show <ref> --detail brief` returns its outline (`toc`, no body), and
+`akm show <ref>#<slug>` then loads only the sections the task needs. Feedback
+closes the loop.
 Record `--negative` only when the asset's content is wrong or stale; a note that
 simply did not fit the task is not negative feedback, so record nothing for it.
 `akm feedback <ref> --negative --reason "<what is wrong and what should change>"`

package/docs/maintainers/release-checklist.md

@@ -19,7 +19,8 @@ next):
    the `package.json` version (`tests/workflow-release.test.ts`).
 3. Add a migration note if the release needs one (see
    [CONTRIBUTING](https://github.com/itlackey/akm/blob/main/.github/CONTRIBUTING.md#shipping-a-release--migration-notes)).
-4. Commit `release: <version>`, push it to the branch, and let CI run on it.
+4. Commit `release: <version>`, push it to the branch and dispatch the release
+   (next section); the workflow waits for CI on that commit.
 
 ## 2. Release akm
 
@@ -31,13 +32,19 @@ The Release workflow, on the pushed commit:
 
 1. runs Gated CI: semantic search with real embeddings, the Docker install
    matrix, and the native schedulers on Linux, macOS and Windows;
-2. requires CI to have passed on the same commit (it does not run lint, the
-   typecheck or the test suites again);
-3. runs `tests/release-check.sh --skip-docker`: the packaged artifact's bin
-   targets and migrator, package acceptance, and the upgrade rehearsal against
-   the packed tarball;
-4. builds the package and standalone binaries, publishes to npm (`latest` for
-   a stable version, `next` for a prerelease) and creates the GitHub release.
+2. runs `tests/release-check.sh --skip-docker`: the packaged artifact's bin
+   targets and migrator, and package acceptance;
+3. builds the package and standalone binaries;
+4. requires CI to pass on the same commit, waiting up to 25 minutes for the run
+   to finish: the newest push or manual run counts, a pull request's does not
+   (it does not run lint, the typecheck, the test suites or the upgrade
+   rehearsal again);
+5. publishes to npm (`latest` for a stable version, `next` for a prerelease)
+   and creates the GitHub release.
+
+Push nothing else to the branch until the Release finishes: a push cancels the
+release commit's CI run (`ci.yml` cancels an in-progress run on the same ref),
+and the Release then fails.
 
 If a job fails on a flake, rerun the failed jobs. If the fix needs a code
 change, commit it and release that commit. npm can take several minutes to show

package/docs/reference/cli.md

@@ -435,6 +435,10 @@ to each connection's endpoint, one probe per distinct endpoint, checks the
 installed akm-cli version against the latest GitHub release (`cli-version`),
 runs the scheduler's recorded akm binary with `--version` to check it
 against the running CLI (`scheduler-binary`).
+The `plugin-version` advisory compares the installed Claude Code plugin with the
+channel its marketplace clone follows: the newest stable tag on the remote's
+default branch, the release tag on the branch head for another branch such as
+`next`, and the pinned tag for a marketplace added at a tag.
 
 Primary result fields:
 
@@ -822,7 +826,10 @@ contends with a full `akm index` rebuild in progress.
 
 Display an asset by ref. On a markdown document `#fragment` selects one
 section by heading slug (falling back to case-insensitive heading text); an
-unmatched fragment lists the available slugs.
+unmatched fragment lists the available slugs. For a large document, read the
+outline first and then only the sections you need: `akm show <ref> --detail
+brief` returns the document's `toc` without the body, and `akm show
+<ref>#<slug>` returns one section.
 
 ```sh
 akm show scripts/deploy.sh
@@ -830,7 +837,8 @@ akm show skills/code-review
 akm show agents/architect
 akm show commands/release
 akm show workflows/ship-release
-akm show knowledge/guide                 # the whole document
+akm show knowledge/guide                 # the whole document, plus its toc
+akm show knowledge/guide --detail brief  # the outline (toc), no body
 akm show knowledge/guide#authentication  # just that section
 akm show '<search-result-ref>' --context lead --max-tokens 800
 akm show knowledge/guide#nope            # lists the available fragment slugs
@@ -879,6 +887,17 @@ reduced metadata-first view without `content`/`template`/`prompt`;
 including `ref`/`path`/`editable`, plus the optional fragment metadata
 described below.
 
+`toc` is the outline of a whole Markdown document (knowledge, and every other
+Markdown asset whose `#fragment` selects a section): one
+`{ "level", "text", "slug", "startLine" }` entry per heading, in order, at every
+`--detail` level, `brief` and `agent` included. `slug` is exactly what
+`<ref>#<slug>` selects, duplicate headings included (`notes`, `notes-1`, ...),
+and `startLine` is the heading's 1-based line in the file. It is read from the
+same file the section is cut from, so it never lists a slug the show cannot
+resolve. It is omitted for non-Markdown assets, for documents with no headings,
+and for a fragment show (`<ref>#<slug>`). `--format text` prints it as a
+`toc:` block.
+
 `links` lists the asset's declared links, grouped by kind: `outgoing` (the
 assets its own `xrefs:`, `supersededBy:`, `contradictedBy:`,
 `currentBeliefRefs:`, wiki `sources:`, `.derived` parent, page links, or
@@ -944,7 +963,7 @@ Returns type-specific payloads:
 | skill | `content` (full SKILL.md) |
 | command | `template`, `description` |
 | agent | `prompt`, `description`, `modelHint` |
-| knowledge | `content` — the whole document, or one section via `#fragment` |
+| knowledge | `content` — the whole document, or one section via `#fragment`; `toc` on a whole document |
 | workflow | `workflowTitle`, `workflowParameters`, `steps` (each step's `orchestration` summary names its `engine` (the connection or harness it runs on) and model, or — for an [exec step](https://github.com/itlackey/akm/blob/main/docs/reference/workflow-schema.md#what-akm-show-reports-for-an-exec-step) — its `exec.command` and no engine at all) |
 | memory | `content` |
 | env | `keys` (key names only — values and comment text never returned) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akm-cli",
-  "version": "0.10.261015-beta",
+  "version": "0.10.261016-beta",
   "type": "module",
   "description": "akm (Agent Knowledge Manager) — a portable, local-first capability library for AI agents. Discover, load, share, and improve reusable skills, scripts, workflows, and knowledge across any shell-capable coding agent, including Claude Code, OpenCode, and Cursor.",
   "keywords": [
@@ -75,6 +75,7 @@
     "check": "bun run lint && bunx tsc --noEmit && bun run test:unit && bun run test:integration",
     "check:fast": "bun run lint && bunx tsc --noEmit && bun run test:unit",
     "check:changed": "bun run lint && bunx tsc --noEmit && bun test tests/integration/output-baseline.test.ts tests/integration/registry/registry-search.test.ts tests/integration/show-argv-entrypoint.test.ts tests/output-shapes-unit.test.ts",
+    "check:ci": "bash scripts/check-like-ci.sh",
     "sweep:tmp": "bun scripts/sweep-test-tmp.ts",
     "test": "bash scripts/test-unit.sh",
     "test:unit": "bash scripts/test-unit.sh",
@@ -103,8 +104,7 @@
     "ajv": "8.20.0",
     "bun-types": "^1.3.13",
     "cmd-shim": "9.0.2",
-    "typescript": "^5.9.3",
-    "zod-to-json-schema": "^3.23.0"
+    "typescript": "^5.9.3"
   },
   "optionalDependencies": {
     "better-sqlite3": "13.0.3",
@@ -124,6 +124,6 @@
     "semver": "^7.6.0",
     "turndown": "^7.2.4",
     "yaml": "^2.8.4",
-    "zod": "^3.23.0"
+    "zod": "^4.6.6"
   }
 }