akm-cli 0.9.0-rc.8 → 0.9.0

package/README.md

@@ -1,20 +1,27 @@
-# akm -- Agent Knowledge Management
+# akm -- Agent Knowledge Manager
 
-> **akm** (Agent Knowledge Management) -- A package manager for AI agent skills, commands, tools, and knowledge.
+> **akm** (Agent Knowledge Manager) -- A knowledge toolkit for AI agents.
 
 [![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,
+`akm` is a knowledge toolkit for AI agent capabilities -- scripts, skills, commands,
+agents, knowledge, instructions, memories, workflows, env files, secrets, lessons,
+tasks, sessions, and facts. It can discover and install bundles from npm, git, local
+directories, and configured registries. It works with any AI coding assistant that can run shell commands,
 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,12 +31,6 @@ 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.
@@ -45,16 +46,41 @@ binaries are runtime-free.
 
 ```sh
 akm setup                         # Guided setup: configure, initialize, and index
-akm add github:owner/repo         # Add a stash from GitHub
+akm task doctor                    # Verify scheduler and installed runtime
+akm bundle add github:owner/repo         # Add a bundle from GitHub
 akm search "deploy"               # Find assets across all sources
 akm show scripts/deploy.sh        # View details and run command
 ```
 
+Non-interactive setup never activates schedules.
+
+## Schedule Tasks Safely
+
+```sh
+akm setup                 # Review definitions, schedules, and enabled state
+# Confirm scheduler activation only after reviewing the complete task summary.
+akm task doctor           # Verify backend, runtime, task state, and warnings
+```
+
+Setup shows the complete task review — both the general-purpose core
+templates and the maintainer-oriented improve cadence — before asking one
+explicit question about changing task files and the OS scheduler. Only
+confirmation prepares the definitions and syncs the scheduler. Declining, or
+running setup non-interactively, leaves both unchanged. A scheduled entry
+captures the installed akm runtime used during activation. Ordinary
+`akm task sync` preserves that runtime; after moving or replacing the
+installation, use `akm task sync --rebind` explicitly to migrate or repair
+scheduler entries, then run `akm task doctor` again.
+
+Rerunning setup preserves existing scheduler bindings. If setup changes the AKM
+storage path, or the installed runtime path changes, run
+`akm task sync --rebind` explicitly.
+
 ## 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.
+- **One command to search your knowledge** -- Local assets are searched by default. Add `--from registry` or `--from all` for configured registry results; [skills.sh](https://skills.sh) participates only when enabled.
+- **Install bundles 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.
 
@@ -66,22 +92,22 @@ 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
+## Install Bundles 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
+akm bundle add @scope/pkg                          # npm
+akm bundle add github:owner/repo#v1.2.3            # GitHub with tag
+akm bundle add git+https://gitlab.com/org/repo     # Any git repo
+akm bundle add ./path/to/local/dir                 # Local directory
 ```
 
-Manage stashes with `akm list`, `akm update --all`, and `akm remove`.
+Manage bundles with `akm bundle list`, `akm bundle update --all`, and `akm bundle remove`.
 
-## Publish Your Own Stash
+## Publish Your Own Bundle
 
 1. Organize your assets into a directory
 2. Add `"akm"` to `keywords` in `package.json`
@@ -95,7 +121,7 @@ Full docs, CLI reference, and guides are available on [GitHub](https://github.co
 - [Getting Started](https://github.com/itlackey/akm/blob/main/docs/guides/getting-started.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 Maker's Guide](https://github.com/itlackey/akm/blob/main/docs/guides/stash-makers.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