akm-cli 0.10.261015-beta → 0.10.261017-beta

package/CHANGELOG.md

@@ -6,6 +6,168 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.10.261017] - 2026-10-27
+
+### Changed
+
+- `akm search` finds knowledge whose answer sits in fenced code (#1260). The
+  `content` search projection now keeps the identifiers of fenced code (names,
+  CLI flags, config keys, paths, dotted references such as `process.env.CI`)
+  and still drops their literal values (quoted strings, assignment values, URLs,
+  long token-like strings). On akm-eval's code-lookup set nDCG@10 rose from
+  0.530 to 0.764 (keyword) and 0.494 to 0.614 (semantic); the library set
+  improved slightly and the prose-only books set is unchanged. Search results
+  carry no `content`, so what search hands an agent is the same size. Fragments,
+  fragment ids and `akm show` are unchanged. The next `akm index` (including the
+  one `akm upgrade` runs) re-projects every directory once and re-embeds only
+  the entries whose embedded text changed; no `--full` needed.
+
+### Fixed
+
+- The first `akm index` after upgrading re-embeds only the entries whose
+  embedded text changed (follow-up to #1260). The fenced-code identifiers now in
+  the search text come after the prose, past the first `embedding.maxInputTokens`
+  (default 512, about 2,048 characters) that are embedded, so a longer document
+  keeps its vector and only its keyword row is rewritten. The index prints how
+  many entries it is embedding (`Embedding 3,712 changed entries (15,050
+  unchanged)`), and `akm upgrade` shows that line and the rest of the index's
+  progress instead of waiting silently.
+- Documentation sentences that were false on 0.10 are corrected (review of
+  #1273, #1251 follow-up). `asset-types.md` lists every way an env or secret
+  value reaches a process. `classification.md` says that `akm`, `okf`, `claude`,
+  `opencode` and `generic-files` reserve `index.md` and `log.md` at every depth
+  and `llm-wiki` reserves `schema.md`, `index.md` and `log.md` only at the wiki
+  root (`adapters.md` agrees), and that a `.yml` under `workflows/` is typed
+  `workflow`, then skipped at index time. `ref.md`, `workflow-engine.md` (no
+  isolated units; a plan from a newer akm is refused unread) and `workflows.md`
+  say 0.10. `configuration.md` and the stash skeleton's `backlinks.md` no longer
+  call `content` the lowest-weight search field: BM25 weighs the five fields
+  equally. The skeleton's `organization.md` no longer calls the name the
+  highest-weighted field or promises repo-match, tag-match or per-project
+  ranking boosts, which search does not have. `persisted-data-compat.md` has its
+  downgrade warning for retire proposals back. A bare `akm proposal drain`
+  follows the apply mode of `improve.strategy` (`default`, which promotes,
+  unless set); the `--promote` help text, `cli.md` and the improve guide said it
+  queues (whether it should is #1274). The feedback pages and
+  `akm feedback --help` say that in keyword-only search one vote moves a hit
+  one place whatever the keyword margin, and that with embeddings it breaks
+  only near-ties, where they said feedback does not override relevance. The
+  `AKM_REGISTRY_URL` rows say it replaces the configured registries in every
+  registry search. The migration guide and the 0.10.0 release notes name the
+  full refs `akm env` and `akm secret` now require, the removed
+  `akm search --assets`, the end of the index's bundle refresh, the retired
+  `secret://` and `${secret:NAME}`, the `--belief current` default, the
+  Codex and Aider flags akm no longer passes, 0.9 retire proposals, the
+  `akm health` warning where local embeddings are not offered, the dropped JSON
+  fields, the workflow redaction scope, and (in the notes) the frontmatter date
+  keys, symlinked and trimmed secrets, the SIGINT-first stop and the Claude Code
+  and Codex plugin branches, and no longer list `GET /api/config` as a breaking
+  change (`akm ui` is new in 0.10). The fixture READMEs match the code.
+- **`akm bundle rename` keeps the bundle's recorded feedback** (#1250). It rewrote
+  proposals, task history and workflow refs but left `usage_events` under the old
+  prefix, so after a rename no feedback counted in search ranking for any asset
+  in the bundle, improve stopped reading its feedback, and the next `akm index`
+  cut the events off from their entries. It now moves the bundle's
+  `usage_events`, `events`, `improve_ledger`, `asset_salience` and
+  `asset_outcome` rows to the new name too, and matches the old name
+  case-sensitively, so renaming `team` no longer moves or overwrites the rows of
+  a bundle named `Team`.
+- A negative whose exact fix was applied no longer keeps demoting the corrected
+  asset in `akm search` and `akm curate` (#1249). A negative recorded with
+  `--replace`/`--with`, `--superseded-by` or `--outdated` stops counting against
+  the asset once its fix is accepted, the same "already acted on" rule
+  `akm improve` uses; reverting the fix with `akm proposal revert` makes the
+  negative count again. A fix the accept refused, and every negative without a
+  fix, still lower the asset's ranking.
+- **The architecture and CLI reference pages now say that feedback reorders search hits
+  (#1251).** They said a hit's `score` was its fused score and that nothing else changed the
+  order. They now say that after fusion the score is multiplied by
+  `1 + 0.03 × (ln(1 + positives) − ln(1 + negatives))` over the user's recorded feedback for
+  the asset, the list is re-sorted (equal scores by fully qualified ref), and
+  one-hit-per-file and identical-content deduplication then drop entries without reordering
+  it. They also say filters drop ineligible entries from each candidate list before its 100
+  candidates are taken, not from the fused list afterwards. The storage, indexing, registry
+  and improve-guide pages no longer say that search ranking reads the utility score: improve
+  and `akm metrics` read it, search does not.
+- `AKM_REGISTRY_URL` now takes effect in `akm search` and `akm curate` with
+  `--from registry` or `--from all` (#1275). The variable is meant to replace the
+  configured registries, but search always passed the configured list, which
+  won, so a mirror or CI override was never read and your `registries` were
+  queried instead. When it is set, only its comma-separated URLs are searched.
+
+## [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
@@ -1485,6 +1647,17 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
   schema rejection: one retry without the schema, remembered for the connection. `gpt-oss:120b` through the lab
   gateway needed `supportsJsonSchema: false` set by hand. Other 5xx answers keep the transient-retry path. (#1150)
 
+## [0.9.32] - 2026-10-13
+
+A patch release: `akm feedback` no longer reports success for feedback it could not store.
+
+### Fixed
+
+- **`akm feedback` fails when it cannot record the feedback.** When `state.db` was read-only to the process, as it is
+  inside an agent sandbox that only allows writes in the workspace, the feedback row was silently dropped and the
+  command still printed `"ok": true`. It now fails with a `DATA_DIR_NOT_WRITABLE` config error (exit 78) and records
+  nothing, so an agent knows its feedback was lost. Add akm's data directory to the sandbox's writable paths.
+
 ## [0.9.31] - 2026-10-09
 
 A patch release: concurrent config writes no longer lose a change, OpenAI's reasoning models work as `llm`

package/README.md

@@ -69,14 +69,12 @@ 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 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.
+- **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. Edits land as diffable proposals: the default improve strategy accepts the ones its quality judge passed, the rest wait for you to accept or reject, and any accept can be reverted. 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. Workflows are Experimental.
 
-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. It
-complements MCP and assistant-native skills rather than replacing them.
+Search and show only return content; running a workflow, task, script, or
+agent is a separate command. akm complements MCP and assistant-native skills
+rather than replacing them.
 
 ## Agent Integration
 
@@ -90,7 +88,7 @@ knowledge, instructions, memories, workflows, env files, secrets, lessons, tasks
 sessions, and facts via the `akm` CLI. Use `akm -h` for details.
 ```
 
-Or generate it directly: `akm help agents >> AGENTS.md`
+Or generate it directly: `akm hints --detail brief >> AGENTS.md`
 
 ## Documentation
 
@@ -99,8 +97,8 @@ Full docs, CLI reference, and guides are at **[akm.fwdslsh.dev](https://akm.fwds
 - [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/)
+- [Tasks Reference](https://akm.fwdslsh.dev/docs/reference/tasks/)
+- [Migration guides](https://akm.fwdslsh.dev/docs/migration/README/)
 - [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/)

package/SECURITY.md

@@ -2,108 +2,16 @@
 
 ## Supported versions
 
-Security fixes are made on the latest minor release line of `akm-cli`. The
-0.x line is pre-1.0 — please upgrade promptly when a fix lands.
-
 | Version | Supported |
 | --- | --- |
-| 0.9.x | ✅ active |
-| 0.8.x | ❌ no longer maintained |
-| < 0.8 | ❌ no longer maintained |
+| 0.10.x | Yes |
+| Older | No |
 
 ## Reporting a vulnerability
 
-Please report security issues **privately** via GitHub Security Advisories:
-
-- https://github.com/itlackey/akm/security/advisories/new
-
-If GitHub Security Advisories is unavailable, email `itlackey@gmail.com`
-with the word `SECURITY` in the subject. Please include reproduction steps,
-the impacted akm version, and your operating environment.
-
-We will acknowledge receipt within 72 hours and aim to ship a fix or a
-mitigation guidance within two weeks, depending on severity.
-
-## Threat model
-
-`akm` is a local CLI that reads and writes user files, executes user-authored
-shell commands (via scripts, workflows, and agent dispatch), and talks to
-explicitly configured external services (LLM endpoints, git remotes, npm,
-HTTP sources). It does **not** ship telemetry, send data to anyone by
-default, or open network listeners. See
-[`docs/reference/data-and-telemetry.md`](docs/reference/data-and-telemetry.md) for the on-disk
-inventory.
-
-Several akm surfaces execute user-controlled code or data with the full
-permissions of the akm process. These are documented design decisions, not
-bugs, but you should be aware of them:
-
-### Workflows execute shell commands with full environment access
-
-Workflow steps run in your shell with your PATH and your environment
-variables — including any secrets you have exported or loaded via
-`akm env run` / `akm secret run`. **Only add workflow sources you trust.** See
-[`docs/guides/run-workflows.md` — "Security: workflow sources are executed
-code"](docs/guides/run-workflows.md#security-workflow-sources-are-executed-code)
-for the full discussion.
-
-### Scripts execute shell commands
-
-`akm show scripts/<name>` returns a `run:` command line the user (or an
-integrating agent) then executes. The same trust model applies: scripts you
-install from third-party stashes are third-party code.
-
-### Agents and commands embed user-authored prompts
-
-`akm show agents/<name>` and `akm show commands/<name>` return prompt
-templates and system prompts that an LLM will execute. A malicious stash
-maintainer could write a system prompt that instructs the LLM to read
-sensitive files in your working tree and exfiltrate them via the LLM
-response. Audit the prompt body the same way you'd audit a script.
-
-### Installing a stash means trusting its code
-
-Installing a stash is not a data-only operation: **`<stashDir>/scripts/wiki-fetchers/*.{ts,js,mjs}` is imported and EXECUTED during `akm index`** (when a website-snapshot source in that stash is synced), with no gate, no prompt, and no allowlist. Every file in that directory is dynamically `import()`ed, and only *after* the module has fully evaluated does akm check that its default export looks like a fetcher (`{ name, matches, fetch }`) — module-level code (anything outside the exported functions) runs unconditionally before that check ever happens, and a file that fails the check still ran. There is no sandboxing: a wiki-fetcher script executes with the full permissions of the akm process, exactly like the scripts and workflow steps documented above.
-
-This is a deliberate design decision (owner ruling), not an oversight, and it will not change without a separate decision to add a gate. **If you install a stash from a source you do not trust, you are trusting its code to run on your machine at index time** — audit `scripts/wiki-fetchers/` the same way you would audit any other executable you're about to run, before installing.
-
-The built-in YouTube snapshot fetcher (`src/sources/snapshot-fetchers/youtube.ts`) deliberately **impersonates the YouTube Android app's InnerTube client** (`clientName: "ANDROID"`, a spoofed `clientVersion`) when calling YouTube's private `youtubei/v1/player` endpoint, because the public web client's caption URLs are Proof-of-Origin-Token gated and return empty bodies. This is known, intentional behavior needed to fetch captions at all, not a bug — documented here so it isn't mistaken for one.
-
-### Environment and secret assets are plaintext on disk
-
-`env` and `secret` assets are owner-permissioned plaintext under `<stash>/env/`
-and `<stash>/secrets/`. They are protected against other local users by
-filesystem permissions but are not encrypted at rest. Do not commit these
-files to source control. Normal `akm env` and `akm secret` output never echoes
-values; materialize values only at the command boundary with `akm env run`
-or `akm secret run`.
-
-The knowledge graph extracted from your assets (entities/relations) lives
-only in `$DATA/index.db` and is surfaced as aggregate counts via `akm health`
-(`--report` for the full breakdown) — there is no export command that writes
-graph content to an arbitrary path.
-
-### Improve / propose send asset content to the configured LLM
-
-`akm improve` (whose strategies run processes such as reflect, distill, and
-consolidate) and `akm proposal new` can send asset frontmatter and body to the
-connection (or harness) selected by the command, strategy, or current defaults.
-Connections live under `connections.<name>` in `~/.config/akm/config.json`,
-with their keys in the environment or in `~/.config/akm/credentials.json`. If you
-configure a third-party LLM, your asset content goes to that third party, and a
-harness you enable (Claude Code, Codex, ...) sends it wherever it is configured
-to. Use a local endpoint (for example, `http://localhost:11434/v1` via Ollama)
-for assets containing secrets or private notes.
-
-## Known non-issues
+Report security issues privately through GitHub Security Advisories:
+<https://github.com/itlackey/akm/security/advisories/new>
 
-- **The `akm-cli` npm package requires Node.js >= 22 as its bootstrap.** A
-  working Bun >= 1.0 is preferred for execution when it is also on `PATH`; old,
-  unusable, or absent Bun installations fall back to Node.js. Bun does not
-  remove the package's Node.js requirement. Standalone binaries are
-  runtime-free. This is a compatibility limitation, not a security risk.
-- **Workflows can read any file the akm process can read.** This is not a
-  bug — see "Threat model" above.
-- **Installing `akm-cli` runs no install script.** Neither `akm-cli` nor any
-  package it depends on declares one. The Node.js version is checked when akm
-  starts, not when it installs.
+If that is unavailable, email `itlackey@gmail.com` with `SECURITY` in the
+subject. Include reproduction steps, the akm version, and your operating
+environment.