agentikit 0.0.8 → 0.0.12

package/README.md

@@ -1,183 +1,201 @@
-# agentikit
+# Agent-i-Kit
 
-Agentikit is a CLI tool and library for managing a stash of extension assets for AI coding assistants. It lets you **search** and **show** tools, skills, commands, and agents from a stash directory.
+Agent-i-Kit gives AI coding agents a shared library of capabilities they can
+search and use. You organize tools, skills, commands, agents, knowledge, and
+scripts into a **stash**, and agents discover what they need through
+`akm` (Agent Kit Manager).
 
-The CLI is called **akm** (Agentikit Manager).
+## What Is a Kit?
 
-## Installation
+A kit is a shareable package of assets. Any directory with asset
+subdirectories is a valid kit:
 
-### npm / bun
+```text
+my-kit/
+  tools/          # Executable scripts (.sh, .ts, .js)
+  skills/         # Skill definitions (directories with SKILL.md)
+  commands/       # Slash commands (.md)
+  agents/         # Agent definitions (.md)
+  knowledge/      # Reference documents (.md)
+  scripts/        # General scripts (.py, .rb, .go, etc.)
+```
+
+Kits can be published to npm or hosted on GitHub. Tag them with `akm` or
+`agentikit` so others can discover them through registry search.
+
+## What Is a Stash?
+
+The stash is your local library of assets. It combines three sources:
+
+1. **Working stash** -- Your personal assets (`AKM_STASH_DIR`). Read-write.
+2. **Mounted dirs** -- Shared team directories. Read-only.
+3. **Installed kits** -- Kits from npm or GitHub via `akm add`. Read-only.
+
+When you search or open an asset, the working stash takes priority. This
+means you can install a kit and override individual assets by cloning them
+into your working stash.
+
+## Quick Start
 
 ```sh
+# Install
 npm install -g agentikit
-# or
-bun add -g agentikit
-```
 
-### Standalone binary
+# Initialize your stash
+akm init
+
+# Search for assets
+akm search "deploy"
+
+# Show an asset
+akm show tool:deploy.sh
+
+# Install a kit from npm
+akm add @scope/my-kit
 
-Use the install scripts for a copy/paste install:
+# Search installed and registry kits
+akm search "lint" --source both
+```
+
+### Standalone Binary
 
 ```sh
 # macOS / Linux
 curl -fsSL https://raw.githubusercontent.com/itlackey/agentikit/main/install.sh | bash
-# pin a release tag)
-curl -fsSL https://raw.githubusercontent.com/itlackey/agentikit/main/install.sh | bash -s -- v1.2.3
 
-# PowerShell (Windows)
+# Windows (PowerShell)
 irm https://raw.githubusercontent.com/itlackey/agentikit/main/install.ps1 -OutFile install.ps1; ./install.ps1
 ```
 
-The shell installer verifies the downloaded binary against release `checksums.txt` before installing it.
-
-## Stash model
+## Searching and Showing Assets
 
-Set a stash path via `AGENTIKIT_STASH_DIR`, or run `akm init` to create one automatically.
+Search returns scored results with metadata explaining why each hit matched:
 
 ```sh
-export AGENTIKIT_STASH_DIR=/abs/path/to/your-stash
+akm search "docker" --type tool
 ```
 
-Expected stash layout:
-
-```
-$AGENTIKIT_STASH_DIR/
-├── tools/      # recursive files (.sh, .ts, .js, .ps1, .cmd, .bat)
-├── skills/     # skill directories containing SKILL.md
-├── commands/   # markdown files
-├── agents/     # markdown files
-└── knowledge/  # markdown files
+```json
+{
+  "hits": [
+    {
+      "name": "docker-build",
+      "type": "tool",
+      "description": "Build and push Docker images",
+      "openRef": "tool:docker-build.sh",
+      "score": 0.92,
+      "whyMatched": "matched name tokens, fts bm25 relevance"
+    }
+  ]
+}
 ```
 
-## CLI usage
+Use `openRef` from search results to show the full asset:
 
 ```sh
-akm init                 # Initialize stash directory and set AGENTIKIT_STASH_DIR
-akm index [--full]       # Build search index (incremental by default)
-akm search [query]       # Search the stash
-akm show <type:name>     # Read a stash asset by ref
+akm show tool:docker-build.sh
 ```
 
-### search
-
-Search the stash for extension assets.
-
-```sh
-akm search "deploy" --type tool --limit 10
+```json
+{
+  "type": "tool",
+  "name": "docker-build.sh",
+  "runCmd": "cd \"/path/to/tools\" && bash \"/path/to/tools/docker-build.sh\"",
+  "kind": "bash"
+}
 ```
 
-- `query`: case-insensitive substring over stable names (relative paths)
-- `--type`: `tool | skill | command | agent | knowledge | any` (default: `any`)
-- `--limit`: defaults to `20`
-
-Returns typed hits with `openRef`, score/explainability details (`score`, `whyMatched`), and, for tools, execution-ready `runCmd`.
-
-### show
-
-Show a hit using `openRef` from search results.
+For knowledge assets, views let you navigate large documents:
 
 ```sh
-akm show skill:code-review
-akm show knowledge:guide.md --view toc
-akm show knowledge:guide.md --view section --heading "Getting Started"
-akm show knowledge:guide.md --view lines --start 10 --end 30
+akm show knowledge:api-guide.md --view toc
+akm show knowledge:api-guide.md --view section --heading "Authentication"
 ```
 
-Returns full payload by type:
+## Using With AI Agents
 
-- `skill` — full `SKILL.md` content
-- `command` — full markdown body as `template` (+ best-effort `description`)
-- `agent` — full markdown body as `prompt` (+ best-effort `description`, `toolPolicy`, `modelHint`)
-- `tool` — `runCmd`/`kind` (the agent uses the host's shell to execute `runCmd`)
-- `knowledge` — content with optional view modes (`full`, `toc`, `frontmatter`, `section`, `lines`)
+Agent-i-Kit is designed to be called by AI coding agents. The agent searches
+for capabilities, reads the results, and acts on them.
 
-## Library API
+### OpenCode
 
-Agentikit also exports its core functions for use as a library:
+In an OpenCode project, add akm as a tool in your configuration. The agent
+can then search the stash and run tools directly:
 
-```ts
-import { agentikitSearch, agentikitShow, agentikitInit, agentikitIndex } from "agentikit"
+```text
+Search the stash for deployment tools, then run the best match.
 ```
 
-- `agentikitSearch({ query, type?, limit? })` — search the stash
-- `agentikitShow({ ref, view? })` — show a stash asset
-- `agentikitInit()` — initialize stash directory
-- `agentikitIndex()` — build/rebuild search index
+The agent calls `akm search "deploy" --type tool`, picks the top result,
+reads its `runCmd` from `akm show`, and executes it.
 
-## Configuration
+### Claude Code
 
-Agentikit stores configuration in `config.json` inside the stash directory.
+Add akm commands as tools or reference them from your CLAUDE.md:
 
-```sh
-akm config                    # Show current config
-akm config --set key=value    # Update a config key
-```
-
-### Embedding connection
+```markdown
+## Available Tools
 
-By default, agentikit uses the local `@xenova/transformers` library for embeddings. You can configure an OpenAI-compatible embedding endpoint instead:
-
-```sh
-akm config --set 'embedding={"endpoint":"http://localhost:11434/v1/embeddings","model":"nomic-embed-text"}'
+Use `akm search <query>` to find tools, skills, and commands in the stash.
+Use `akm show <ref>` to read asset details before using them.
 ```
 
-To clear the custom embedding config and revert to local embeddings:
+### Any Agent
 
-```sh
-akm config --set 'embedding=null'
-```
-
-### LLM connection
+The JSON output from `akm search` and `akm show` is designed for machine
+consumption. Any agent that can run shell commands can use akm:
 
-When configured, agentikit uses an OpenAI-compatible LLM to generate richer metadata (descriptions, intents, tags) during indexing:
+1. `akm search "what you need"` -- Find relevant assets
+2. `akm show <openRef>` -- Get the details
+3. Use the asset (run the `runCmd`, follow the skill instructions, etc.)
 
-```sh
-akm config --set 'llm={"endpoint":"http://localhost:11434/v1/chat/completions","model":"llama3.2"}'
-```
+## Installing Kits
 
-To clear:
+Install kits from npm, GitHub, or local directories:
 
 ```sh
-akm config --set 'llm=null'
+akm add @scope/my-kit              # npm package
+akm add github:owner/repo          # GitHub repo
+akm add ./path/to/local/kit        # Local git directory
 ```
 
-### Using a local Ollama instance
-
-[Ollama](https://ollama.com) provides local models with an OpenAI-compatible API. After installing Ollama and pulling your models:
+Search the registry to discover kits:
 
 ```sh
-# Pull models
-ollama pull nomic-embed-text
-ollama pull llama3.2
+akm search "code review" --source registry
+```
 
-# Configure agentikit to use Ollama for both embeddings and metadata generation
-akm config --set 'embedding={"endpoint":"http://localhost:11434/v1/embeddings","model":"nomic-embed-text"}'
-akm config --set 'llm={"endpoint":"http://localhost:11434/v1/chat/completions","model":"llama3.2"}'
+Only packages tagged with `akm` or `agentikit` appear in registry results.
+See [docs/registry.md](docs/registry.md) for details.
 
-# Rebuild the index — embeddings use Ollama, metadata is LLM-enhanced
-akm index --full
-```
+## Publishing a Kit
 
-Both `embedding` and `llm` accept an optional `apiKey` field for authenticated endpoints:
+1. Organize your assets into the standard directory structure
+2. Add `"akm"` to `keywords` in `package.json` (for npm) or add the `akm`
+   topic to your GitHub repo
+3. Optionally add an `agentikit.include` array in `package.json` to control
+   which paths are included when installed
 
 ```json
 {
-  "endpoint": "https://api.openai.com/v1/embeddings",
-  "model": "text-embedding-3-small",
-  "apiKey": "sk-..."
+  "name": "@scope/my-kit",
+  "keywords": ["akm"],
+  "agentikit": {
+    "include": ["tools", "skills", "commands"]
+  }
 }
 ```
 
-### Config reference
-
-| Key | Type | Default | Description |
-|-----|------|---------|-------------|
-| `semanticSearch` | `boolean` | `true` | Enable semantic search ranking |
-| `additionalStashDirs` | `string[]` | `[]` | Extra stash directories to search |
-| `embedding` | `object` | not set | OpenAI-compatible embedding endpoint (`endpoint`, `model`, `apiKey?`) |
-| `llm` | `object` | not set | OpenAI-compatible LLM endpoint (`endpoint`, `model`, `apiKey?`) |
-
-## Notes
+## Documentation
 
-- Agentikit does not install or copy kit files.
-- Missing or unreadable stash paths return friendly errors.
+| Doc | Description |
+| --- | --- |
+| [Concepts](docs/concepts.md) | Asset types, stash sources, metadata, tool execution |
+| [CLI Reference](docs/cli.md) | All akm commands and flags |
+| [Kit Maker's Guide](docs/kit-makers.md) | How to build and share a kit |
+| [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 |
+| [Library API](docs/api.md) | Using agentikit as a TypeScript/JS library |

package/dist/index.d.ts

@@ -1,7 +1,7 @@
-export { agentikitSearch, agentikitShow } from "./src/stash";
+export { agentikitAdd, agentikitClone, agentikitList, agentikitRemove, agentikitReinstall, agentikitSearch, agentikitShow, agentikitUpdate, resolveStashSources, resolveAllStashDirs, findSourceForPath, } from "./src/stash";
 export { agentikitInit } from "./src/init";
 export type { InitResponse } from "./src/init";
-export type { AgentikitAssetType, AgentikitSearchType, SearchHit, SearchResponse, ShowResponse, KnowledgeView, } from "./src/stash";
+export type { AgentikitAssetType, AgentikitSearchType, AddResponse, LocalSearchHit, RegistrySearchResultHit, SearchSource, SearchHit, SearchResponse, ShowResponse, KnowledgeView, ListResponse, RemoveResponse, ReinstallResponse, UpdateResponse, RegistryListEntry, RegistryInstallStatus, ReinstallResultItem, UpdateResultItem, StashSource, StashSourceKind, CloneOptions, CloneResponse, } from "./src/stash";
 export type { ToolKind } from "./src/tool-runner";
 export { agentikitIndex } from "./src/indexer";
 export type { IndexResponse } from "./src/indexer";
@@ -12,7 +12,17 @@ export { parseMarkdownToc, extractSection, extractLineRange, extractFrontmatterO
 export type { TocHeading, KnowledgeToc } from "./src/markdown";
 export { parseFrontmatter } from "./src/frontmatter";
 export { loadConfig, saveConfig, updateConfig } from "./src/config";
-export type { AgentikitConfig, EmbeddingConnectionConfig, LlmConnectionConfig } from "./src/config";
+export type { AgentikitConfig, EmbeddingConnectionConfig, LlmConnectionConfig, RegistryConfig } from "./src/config";
+export { parseRegistryRef, resolveRegistryArtifact } from "./src/registry-resolve";
+export { searchRegistry } from "./src/registry-search";
+export { installRegistryRef, upsertInstalledRegistryEntry, removeInstalledRegistryEntry, getRegistryCacheRootDir, detectStashRoot, } from "./src/registry-install";
+export type { RegistrySource, ParsedRegistryRef, ParsedNpmRef, ParsedGithubRef, ResolvedRegistryArtifact, RegistryInstalledEntry, RegistryInstallResult, RegistrySearchHit, RegistrySearchResponse, } from "./src/registry-types";
 export { enhanceMetadata, isLlmAvailable } from "./src/llm";
 export { embed, cosineSimilarity, isEmbeddingAvailable } from "./src/embedder";
 export type { EmbeddingVector } from "./src/embedder";
+export type { SearchUsageMode } from "./src/stash-types";
+export type { AssetTypeHandler, ShowInput } from "./src/asset-type-handler";
+export { registerAssetType, getHandler, tryGetHandler, getAllHandlers, getRegisteredTypeNames } from "./src/asset-type-handler";
+export { parseAssetRef, makeAssetRef } from "./src/stash-ref";
+export type { AssetRef } from "./src/stash-ref";
+export { resolveSourcesForOrigin, isRemoteOrigin } from "./src/origin-resolve";

package/dist/index.js

@@ -1,9 +1,15 @@
-export { agentikitSearch, agentikitShow } from "./src/stash";
+export { agentikitAdd, agentikitClone, agentikitList, agentikitRemove, agentikitReinstall, agentikitSearch, agentikitShow, agentikitUpdate, resolveStashSources, resolveAllStashDirs, findSourceForPath, } from "./src/stash";
 export { agentikitInit } from "./src/init";
 export { agentikitIndex } from "./src/indexer";
 export { resolveRg, isRgAvailable, ensureRg } from "./src/ripgrep";
 export { parseMarkdownToc, extractSection, extractLineRange, extractFrontmatterOnly, formatToc } from "./src/markdown";
 export { parseFrontmatter } from "./src/frontmatter";
 export { loadConfig, saveConfig, updateConfig } from "./src/config";
+export { parseRegistryRef, resolveRegistryArtifact } from "./src/registry-resolve";
+export { searchRegistry } from "./src/registry-search";
+export { installRegistryRef, upsertInstalledRegistryEntry, removeInstalledRegistryEntry, getRegistryCacheRootDir, detectStashRoot, } from "./src/registry-install";
 export { enhanceMetadata, isLlmAvailable } from "./src/llm";
 export { embed, cosineSimilarity, isEmbeddingAvailable } from "./src/embedder";
+export { registerAssetType, getHandler, tryGetHandler, getAllHandlers, getRegisteredTypeNames } from "./src/asset-type-handler";
+export { parseAssetRef, makeAssetRef } from "./src/stash-ref";
+export { resolveSourcesForOrigin, isRemoteOrigin } from "./src/origin-resolve";

package/dist/src/asset-spec.d.ts

@@ -6,6 +6,8 @@ export interface AssetSpec {
     toCanonicalName: (typeRoot: string, filePath: string) => string | undefined;
     toAssetPath: (typeRoot: string, name: string) => string;
 }
+/** Extended set of script extensions for the script asset type */
+export declare const SCRIPT_EXTENSIONS_BROAD: Set<string>;
 export declare const ASSET_SPECS: Record<AgentikitAssetType, AssetSpec>;
 export declare const ASSET_TYPES: AgentikitAssetType[];
 export declare const TYPE_DIRS: Record<AgentikitAssetType, string>;

package/dist/src/asset-spec.js

@@ -1,10 +1,17 @@
 import path from "node:path";
+import { toPosix } from "./common";
+import { tryGetHandler } from "./asset-type-handler";
 export const SCRIPT_EXTENSIONS = new Set([".sh", ".ts", ".js", ".ps1", ".cmd", ".bat"]);
 const markdownSpec = {
     isRelevantFile: (fileName) => path.extname(fileName).toLowerCase() === ".md",
     toCanonicalName: (typeRoot, filePath) => toPosix(path.relative(typeRoot, filePath)),
     toAssetPath: (typeRoot, name) => path.join(typeRoot, name),
 };
+/** Extended set of script extensions for the script asset type */
+export const SCRIPT_EXTENSIONS_BROAD = new Set([
+    ...SCRIPT_EXTENSIONS,
+    ".py", ".rb", ".go", ".pl", ".php", ".lua", ".r", ".swift", ".kt", ".kts",
+]);
 export const ASSET_SPECS = {
     tool: {
         stashDir: "tools",
@@ -26,6 +33,12 @@ export const ASSET_SPECS = {
     command: { stashDir: "commands", ...markdownSpec },
     agent: { stashDir: "agents", ...markdownSpec },
     knowledge: { stashDir: "knowledge", ...markdownSpec },
+    script: {
+        stashDir: "scripts",
+        isRelevantFile: (fileName) => SCRIPT_EXTENSIONS_BROAD.has(path.extname(fileName).toLowerCase()),
+        toCanonicalName: (typeRoot, filePath) => toPosix(path.relative(typeRoot, filePath)),
+        toAssetPath: (typeRoot, name) => path.join(typeRoot, name),
+    },
 };
 export const ASSET_TYPES = Object.keys(ASSET_SPECS);
 export const TYPE_DIRS = ASSET_TYPES.reduce((acc, type) => {
@@ -33,14 +46,20 @@ export const TYPE_DIRS = ASSET_TYPES.reduce((acc, type) => {
     return acc;
 }, {});
 export function isRelevantAssetFile(assetType, fileName) {
+    const handler = tryGetHandler(assetType);
+    if (handler)
+        return handler.isRelevantFile(fileName);
     return ASSET_SPECS[assetType].isRelevantFile(fileName);
 }
 export function deriveCanonicalAssetName(assetType, typeRoot, filePath) {
+    const handler = tryGetHandler(assetType);
+    if (handler)
+        return handler.toCanonicalName(typeRoot, filePath);
     return ASSET_SPECS[assetType].toCanonicalName(typeRoot, filePath);
 }
 export function resolveAssetPathFromName(assetType, typeRoot, name) {
+    const handler = tryGetHandler(assetType);
+    if (handler)
+        return handler.toAssetPath(typeRoot, name);
     return ASSET_SPECS[assetType].toAssetPath(typeRoot, name);
 }
-function toPosix(input) {
-    return input.replace(/\\/g, "/");
-}

package/dist/src/asset-type-handler.d.ts

@@ -0,0 +1,27 @@
+import type { StashEntry } from "./metadata";
+import type { LocalSearchHit, ShowResponse, KnowledgeView } from "./stash-types";
+export interface ShowInput {
+    name: string;
+    path: string;
+    content: string;
+    view?: KnowledgeView;
+    stashDirs?: string[];
+}
+export interface AssetTypeHandler {
+    /** The type name, e.g. "tool", "script" */
+    readonly typeName: string;
+    /** Directory inside the stash root, e.g. "tools", "scripts" */
+    readonly stashDir: string;
+    isRelevantFile(fileName: string): boolean;
+    toCanonicalName(typeRoot: string, filePath: string): string | undefined;
+    toAssetPath(typeRoot: string, name: string): string;
+    buildShowResponse(input: ShowInput): ShowResponse;
+    enrichSearchHit?(hit: LocalSearchHit, stashDir: string): void;
+    readonly defaultUsageGuide: string[];
+    extractTypeMetadata?(entry: StashEntry, file: string, ext: string): void;
+}
+export declare function registerAssetType(handler: AssetTypeHandler): void;
+export declare function getHandler(type: string): AssetTypeHandler;
+export declare function tryGetHandler(type: string): AssetTypeHandler | undefined;
+export declare function getAllHandlers(): AssetTypeHandler[];
+export declare function getRegisteredTypeNames(): string[];

package/dist/src/asset-type-handler.js

@@ -0,0 +1,33 @@
+// ── Registry ─────────────────────────────────────────────────────────────────
+const handlers = new Map();
+let handlersInitialized = false;
+function ensureHandlersRegistered() {
+    if (handlersInitialized)
+        return;
+    handlersInitialized = true;
+    // Import handler registrations
+    require("./handlers/index");
+}
+export function registerAssetType(handler) {
+    handlers.set(handler.typeName, handler);
+}
+export function getHandler(type) {
+    ensureHandlersRegistered();
+    const handler = handlers.get(type);
+    if (!handler) {
+        throw new Error(`Unknown asset type: "${type}"`);
+    }
+    return handler;
+}
+export function tryGetHandler(type) {
+    ensureHandlersRegistered();
+    return handlers.get(type);
+}
+export function getAllHandlers() {
+    ensureHandlersRegistered();
+    return Array.from(handlers.values());
+}
+export function getRegisteredTypeNames() {
+    ensureHandlersRegistered();
+    return Array.from(handlers.keys());
+}