akm-cli 0.9.0-rc.9 → 0.9.1-beta.1

package/README.md

@@ -1,20 +1,28 @@
-# akm -- Agent Knowledge Management
+# akm -- Agent Knowledge Manager
 
-> **akm** (Agent Knowledge Management) -- A package manager for AI agent skills, commands, tools, and knowledge.
+> Give every coding agent the capabilities your team has already built.
 
 [![npm version](https://img.shields.io/npm/v/akm-cli)](https://www.npmjs.com/package/akm-cli)
 [![npm downloads](https://img.shields.io/npm/dm/akm-cli)](https://www.npmjs.com/package/akm-cli)
 [![license](https://img.shields.io/github/license/itlackey/akm)](https://github.com/itlackey/akm/blob/main/LICENSE)
 
-`akm` is a package manager for AI agent capabilities -- scripts, skills, commands,
-agents, knowledge, memories, workflows, wikis, env files, secrets, lessons, and
-scheduled tasks. It works with any AI coding assistant that can run shell commands,
-including [Claude Code](https://claude.ai/code),
+**akm** is a portable capability library for AI agents. Build your agent
+library once. Use it from any shell-capable coding agent. It indexes existing
+agent assets in place, loads only what a task needs, packages capabilities
+into shareable bundles, improves the library through reviewable proposals,
+and runs durable workflows -- locally and without tying the library to one
+assistant, including [Claude Code](https://claude.ai/code),
 [OpenCode](https://opencode.ai), [Cursor](https://cursor.com), and more.
 
 ## Install
 
-**Option 1 — Prebuilt binary (recommended, no runtime required):**
+**Option 1 — npm package (recommended; requires [Node.js](https://nodejs.org) >= 22):**
+
+```sh
+npm install -g akm-cli
+```
+
+**Option 2 — Prebuilt binary (no runtime required):**
 
 ```sh
 # Linux / macOS
@@ -24,39 +32,37 @@ curl -fsSL https://github.com/itlackey/akm/releases/latest/download/install.sh |
 irm https://github.com/itlackey/akm/releases/latest/download/install.ps1 | iex
 ```
 
-**Option 2 — npm package (requires [Node.js](https://nodejs.org) >= 22):**
-
-```sh
-npm install -g akm-cli
-```
-
 Upgrade in place with `akm upgrade`.
 
 The npm package always uses Node.js to bootstrap its cross-platform command.
 If a working [Bun](https://bun.sh) >= 1.0 is also on `PATH`, the launcher
-prefers Bun for execution; old, unusable, or absent Bun installations fall back
-to Node.js. Node.js remains required for the npm package. The standalone
+prefers Bun for execution; old, unusable, or absent Bun installations fall
+back to Node.js. Node.js remains required for the npm package. The standalone
 binaries are runtime-free.
 
-> The old `vault` asset type was removed in 0.9.0; use `env` for whole `.env`
-> groups and `secret` for standalone sensitive values.
-
 ## Quick Start
 
 ```sh
-akm setup                         # Guided setup: configure, initialize, and index
-akm add github:owner/repo         # Add a stash from GitHub
-akm search "deploy"               # Find assets across all sources
-akm show scripts/deploy.sh        # View details and run command
+akm setup                          # Guided setup: configure, initialize, and index
+akm bundle add github:owner/repo   # Add a bundle from GitHub
+akm index                          # Index sources into the library
+akm search "deploy"                # Find assets across all sources
+akm show scripts/deploy.sh         # View details and run command
 ```
 
 ## Why akm?
 
-- **Works with any AI agent** -- No plugins or SDKs required. Any model that can run shell commands can use `akm`.
-- **One command to search everything** -- Local stash, registries, and community skills from [skills.sh](https://skills.sh) in a single query.
-- **Install stashes from anywhere** -- npm, GitHub, GitLab, local directories.
-- **Semantic search** -- Optional local embeddings (via Ollama or HuggingFace) for finding assets by meaning, not just keywords.
-- **Private registries** -- Host your own registry for team or enterprise use.
+- **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.
+- **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
+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.
 
 ## Agent Integration
 
@@ -66,36 +72,21 @@ Add this to your `AGENTS.md`, `CLAUDE.md`, or system prompt:
 ## Resources & Capabilities
 
 You have access to a searchable library of scripts, skills, commands, agents,
-knowledge, memories, workflows, wikis, env files, secrets, lessons, and scheduled tasks
-via the `akm` CLI. Use `akm -h` for details.
+knowledge, instructions, memories, workflows, env files, secrets, lessons, tasks,
+sessions, and facts via the `akm` CLI. Use `akm -h` for details.
 ```
 
-## Install Stashes from Anywhere
-
-```sh
-akm add @scope/my-stash                     # npm
-akm add github:owner/repo#v1.2.3            # GitHub with tag
-akm add git+https://gitlab.com/org/stash    # Any git repo
-akm add ./path/to/local/stash               # Local directory
-```
-
-Manage stashes with `akm list`, `akm update --all`, and `akm remove`.
-
-## Publish Your Own Stash
-
-1. Organize your assets into a directory
-2. Add `"akm"` to `keywords` in `package.json`
-3. Optionally add `akm.include` in `package.json` to control what gets installed
-4. Publish to npm or push to GitHub
+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):
 
 - [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)
 - [Configuration](https://github.com/itlackey/akm/blob/main/docs/reference/configuration.md)
-- [Stash Maker's Guide](https://github.com/itlackey/akm/blob/main/docs/guides/stash-makers.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)
 
 ## License

package/SECURITY.md

@@ -61,6 +61,14 @@ 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/`
@@ -70,10 +78,15 @@ 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`,
 `akm secret run`, or `akm secret path`.
 
+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 propose` can send asset frontmatter and body to the
+consolidate) and `akm proposal new` can send asset frontmatter and body to the
 named LLM engine selected by the command, strategy, or current defaults. LLM
 connections live under
 `engines.<name>` in `~/.config/akm/config.json`. If you configure a third-party