akm-cli 0.0.16 → 0.0.17

package/README.md

@@ -1,23 +1,26 @@
-# akm — the Agent-i-Kit Manager
+# akm -- the Agent-i-Kit Manager
 
 [![npm version](https://img.shields.io/npm/v/akm-cli)](https://www.npmjs.com/package/akm-cli)
 [![CI](https://github.com/itlackey/agentikit/actions/workflows/ci.yml/badge.svg)](https://github.com/itlackey/agentikit/actions/workflows/ci.yml)
 [![license](https://img.shields.io/npm/l/akm-cli)](LICENSE)
 
-A package manager for AI agent capabilities — tools, skills, commands, agents,
-knowledge, and scripts — that works with any AI coding assistant that can run
+A package manager for AI agent capabilities -- scripts, skills, commands,
+agents, and knowledge -- that works with any AI coding assistant that can run
 shell commands.
 
-You build up useful scripts, prompts, and agent configs. `akm` (the Agent-i-Kit
-Manager) lets you organize them into a searchable **stash**, share them as
-installable **kits**, and give any model a way to discover and use them. No
-plugins required — just CLI output any tool-calling model can read.
+`akm` organizes reusable scripts, prompts, and agent configs into a searchable
+**stash**, shares them as installable **kits** via **registries**, and gives
+any model a way to discover and use them. No plugins required -- just CLI
+output any tool-calling model can read.
 
 ## Requirements
 
 `akm` requires [Bun](https://bun.sh) v1.0+ as its runtime. It uses Bun-specific
 APIs (`bun:sqlite`) that are **not available in Node.js**.
 
+> **Don't want Bun?** Use the [standalone binary](#standalone-binary) instead -- it
+> bundles everything and has no runtime dependencies.
+
 ## Quick Start
 
 ```sh
@@ -30,6 +33,9 @@ akm init
 # Add a kit from GitHub
 akm add github:owner/repo
 
+# Clone an asset to a specific directory
+akm clone script:deploy.sh --dest ./project/.claude
+
 # Search for assets
 akm search "deploy"
 
@@ -37,17 +43,14 @@ akm search "deploy"
 akm show script:deploy.sh
 ```
 
-> **Don't want Bun?** Use the [standalone binary](#standalone-binary) instead — it
-> bundles everything and has no runtime dependencies.
-
 ## Using With Any AI Agent
 
 `akm` is platform agnostic. Any model that can execute shell commands can search
 your stash and use what it finds. The workflow is three commands:
 
-1. `akm search "what you need"` — find relevant assets (returns JSON by default)
-2. `akm show <ref>` — get the details (run command, instructions, prompt, etc.)
-3. Use the asset — execute the `run` command, follow the skill instructions, fill in the template
+1. `akm search "what you need"` -- find relevant assets (returns JSON by default)
+2. `akm show <ref>` -- get the details (run command, instructions, prompt, etc.)
+3. Use the asset -- execute the `run` command, follow the skill instructions, fill in the template
 
 ### Drop-in prompt snippet
 
@@ -55,50 +58,23 @@ Add this to your `AGENTS.md`, `CLAUDE.md`, `.github/copilot-instructions.md`, sy
 file to give your agent access to your stash without any additional setup:
 
 ~~~markdown
+## Resources & Capabilities
 
-You have access to a searchable library of tools, skills, commands, agents,
-and knowledge documents via `akm`. Use it to find and
-use capabilities before writing something from scratch.
-
-**Finding assets:**
-```sh
-akm search "<query>"              # Search by keyword
-akm search "<query>" --type tool  # Filter by type (tool, skill, command, agent, knowledge, script)
-akm search "<query>" --source <source>  # Filter by source (e.g., "local", "registry", "both")
-```
-
-Search returns brief JSON by default. Local hits include a `ref` handle you
-pass directly to `akm show`.
-
-**Using assets:**
-```sh
-akm show <ref>                    # Get full asset details
-```
-
-What you get back depends on the asset type:
-- **script** — A `run` command you can execute directly
-- **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 (use `toc` or `section "..."` to navigate)
-
-Always search the stash first when you need a capability. Prefer existing
-assets over writing new code.
-
-Use `akm -h` for more options and details on searching and using assets.
+You have access to a searchable library of scripts, skills, commands, agents, and knowledge documents via the `akm` CLI. Use it to find and use capabilities before writing something from scratch. Always search the stash first when you need a capability.
 
+Use `akm -h` for more information about searching and using assets.
 ~~~
 
 That's it. No plugin, no SDK, no integration code. The model reads the JSON
-output from `akm` and acts on it.
+output from `akm` and acts on it. If you would like more detailed instructions, check out the example [AGENTS.md](docs/AGENTS.md)
 
 ### Platform plugins (optional)
 
 For tighter integration, plugins are available for some platforms. These add
 native tool bindings so the agent doesn't need to shell out, but they're
-purely optional — the CLI works everywhere.
+purely optional -- the CLI works everywhere.
 
-**OpenCode** — Add the [OpenCode plugin](https://github.com/itlackey/agentikit-plugins?tab=readme-ov-file#akm-opencode) to your `opencode.json`:
+**OpenCode** -- Add the [OpenCode plugin](https://github.com/itlackey/akm-plugins?tab=readme-ov-file#opencode) to your `opencode.json`:
 
 ```json
 {
@@ -106,58 +82,42 @@ purely optional — the CLI works everywhere.
 }
 ```
 
-**Claude Code** — Add the prompt snippet above to your `CLAUDE.md` or
+**Claude Code** -- Add the prompt snippet above to your `CLAUDE.md` or
 project instructions. Claude Code can run `akm` commands directly.
 
-**Everything else** — If your agent can run shell commands, it can use `akm`.
-Add the prompt snippet to whatever instruction mechanism your platform uses.
+**Everything else** -- If your agent can run shell commands, it can use `akm`.
+Add the prompt snippet above or in [AGENTS.md](docs/AGENTS.md) to whatever instruction/rules mechanism your platform uses.
 
-## What's In a Kit?
+## The Stash
 
-A kit is a directory of assets you can share and install. There's no required
-structure — `akm` classifies assets by **file extension and content**, not by
-directory name. A `.sh` file is a script whether it lives in `scripts/`,
-`deploy/`, or at the root. A `.md` file with `tools` in its frontmatter is an
-agent definition wherever you put it.
+Your stash is the local library where assets live. It combines three sources
+in priority order:
 
-That said, using these directory names as an opt-in convention improves
-indexing confidence:
+1. **Primary stash** -- Your personal assets (`AKM_STASH_DIR`), created by `akm init`
+2. **Search paths** -- Additional directories (team shares, project dirs, etc.)
+3. **Installed kits** -- Kits from npm, GitHub, or git via `akm add` (cache-managed)
 
-```text
-my-kit/
-  scripts/        # Executable scripts (.sh, .ts, .js, .py, .rb, .go, etc.)
-  skills/         # Skill definitions (directories with SKILL.md)
-  commands/       # Slash commands (.md with $ARGUMENTS or agent frontmatter)
-  agents/         # Agent definitions (.md with model/tools frontmatter)
-  knowledge/      # Reference documents (.md)
-```
+The first match wins, so local assets always override installed ones. Use
+`akm clone` to fork an installed asset into your stash for editing.
 
-### Asset types
+## Registries
 
-| Type | What it is | What the agent gets |
-| --- | --- | --- |
-| **script** | An executable script | A `run` command with auto-detected interpreter, plus optional `setup` and `cwd` |
-| **skill** | A set of instructions | Step-by-step guidance the agent follows |
-| **command** | A prompt template | A template with placeholders to fill in |
-| **agent** | An agent definition | A system prompt, model hint, and tool policy |
-| **knowledge** | A reference document | Navigable content with TOC and section views |
+Registries are indexes of available kits. akm ships with the official
+[akm-registry](https://github.com/itlackey/akm-registry) pre-configured.
 
-Assets are referenced by type and name (e.g. `script:deploy.sh`,
-`knowledge:api-guide`). In practice, agents should treat the `ref` returned
-by search as an opaque handle and pass it back to `akm show`. See
-[Concepts](docs/concepts.md) and [Ref Format](docs/ref.md).
+```sh
+# Search the official registry
+akm registry search "code review"
 
-## The Stash
+# Add a third-party registry
+akm registry add https://example.com/registry/index.json --name team
 
-Your stash is the local library where assets live. It combines three sources
-in priority order:
-
-1. **Primary stash** — Your personal assets (`AKM_STASH_DIR`), created by `akm init`
-2. **Search paths** — Additional directories (team shares, project dirs, etc.)
-3. **Installed kits** — Kits from npm, GitHub, or git via `akm add` (cache-managed)
+# List configured registries
+akm registry list
+```
 
-The first match wins, so local assets always override installed ones. Use
-`akm clone` to fork an installed asset into your stash for editing.
+See the [Registry docs](docs/registry.md) for hosting your own registry,
+the v2 index format with asset-level metadata, and more.
 
 ## Searching and Showing Assets
 
@@ -165,7 +125,7 @@ Search returns brief JSON by default. Use `--detail normal` or `--detail full`
 when you want origin, tags, or explainability metadata:
 
 ```sh
-akm search "docker" --type tool
+akm search "docker" --type script
 ```
 
 ```json
@@ -184,7 +144,7 @@ akm search "docker" --type tool
 Show returns everything the agent needs to act:
 
 ```sh
-akm show tool:docker-build.sh
+akm show script:docker-build.sh
 ```
 
 ```json
@@ -193,9 +153,9 @@ akm show tool:docker-build.sh
   "name": "docker-build.sh",
   "origin": null,
   "action": "Execute the run command below",
-  "run": "bash /path/to/tools/docker-build.sh",
+  "run": "bash /path/to/scripts/docker-build.sh",
   "setup": "bun install",
-  "cwd": "/path/to/tools"
+  "cwd": "/path/to/scripts"
 }
 ```
 
@@ -217,19 +177,13 @@ akm add git+https://gitlab.com/org/kit      # Any git repo
 akm add ./path/to/local/kit                 # Local directory
 ```
 
-Search the registry for community kits:
-
-```sh
-akm search "code review" --source registry
-```
-
 Manage installed kits:
 
 ```sh
 akm list                        # Show installed kits with status
 akm update --all                # Update all (reports version changes)
 akm remove owner/repo           # Remove and reindex
-akm clone tool:deploy.sh        # Fork an asset into your stash for editing
+akm clone script:deploy.sh      # Fork an asset into your stash for editing
 ```
 
 ### Publishing your own kit
@@ -256,7 +210,7 @@ bun install -g akm-cli
 
 ### Standalone binary
 
-The standalone binary bundles everything and has **no runtime dependencies** —
+The standalone binary bundles everything and has **no runtime dependencies** --
 no Bun, no Node.js.
 
 ```sh
@@ -280,20 +234,17 @@ akm upgrade --check   # Check for updates without installing
 
 | Doc | Description |
 | --- | --- |
-| [Concepts](docs/concepts.md) | Asset types, classification, stash sources, metadata |
+| [Getting Started](docs/getting-started.md) | Quick setup guide |
 | [CLI Reference](docs/cli.md) | All `akm` commands and flags |
-| [Kit Maker's Guide](docs/kit-makers.md) | Build and share a kit on GitHub, npm, or a network share |
-| [Registry](docs/registry.md) | Finding, installing, and publishing kits |
-| [Search](docs/search.md) | Hybrid search architecture and scoring |
-| [Indexing](docs/indexing.md) | How the search index is built |
-| [Filesystem](docs/filesystem.md) | Directory layout and `.stash.json` schema |
 | [Configuration](docs/configuration.md) | Providers, settings, and Ollama setup |
-| [Ref Format](docs/ref.md) | Opaque asset handles returned by `search` and consumed by `show` |
+| [Concepts](docs/concepts.md) | Asset types, classification, stash sources, metadata |
+| [Kit Maker's Guide](docs/kit-makers.md) | Build and share a kit on GitHub, npm, or a network share |
+| [Registry](docs/registry.md) | Registries, search, and managing kits |
 
 ## Status
 
-`akm` is approaching v1.0. The core CLI, stash model, and registry are stable
-and in daily use. Feedback, issues, and PRs welcome — especially around
+`akm` is approaching v1.0. The core CLI, stash model, and registry are generally stable
+and in daily use. Feedback, issues, and PRs welcome -- especially around
 real-world usage patterns and integrations with different AI coding assistants.
 
 ## License

package/dist/asset-spec.js

@@ -1,6 +1,5 @@
 import path from "node:path";
 import { toPosix } from "./common";
-export const SCRIPT_EXTENSIONS = new Set([".sh", ".ts", ".js", ".ps1", ".cmd", ".bat"]);
 const markdownSpec = {
     isRelevantFile: (fileName) => path.extname(fileName).toLowerCase() === ".md",
     toCanonicalName: (typeRoot, filePath) => {
@@ -14,9 +13,14 @@ const markdownSpec = {
         return path.join(typeRoot, withExt);
     },
 };
-/** Extended set of script extensions for the script asset type */
-export const SCRIPT_EXTENSIONS_BROAD = new Set([
-    ...SCRIPT_EXTENSIONS,
+/** All recognized script extensions for the script asset type */
+export const SCRIPT_EXTENSIONS = new Set([
+    ".sh",
+    ".ts",
+    ".js",
+    ".ps1",
+    ".cmd",
+    ".bat",
     ".py",
     ".rb",
     ".go",
@@ -29,15 +33,11 @@ export const SCRIPT_EXTENSIONS_BROAD = new Set([
     ".kts",
 ]);
 const scriptSpec = {
-    isRelevantFile: (fileName) => SCRIPT_EXTENSIONS_BROAD.has(path.extname(fileName).toLowerCase()),
+    isRelevantFile: (fileName) => SCRIPT_EXTENSIONS.has(path.extname(fileName).toLowerCase()),
     toCanonicalName: (typeRoot, filePath) => toPosix(path.relative(typeRoot, filePath)),
     toAssetPath: (typeRoot, name) => path.join(typeRoot, name),
 };
 export const ASSET_SPECS = {
-    // "tool" is a transparent alias for "script". It uses the same spec
-    // (broad script extensions) but retains its own stashDir ("tools") so
-    // files in tools/ are still discovered.
-    tool: { stashDir: "tools", ...scriptSpec },
     skill: {
         stashDir: "skills",
         isRelevantFile: (fileName) => fileName === "SKILL.md",