akm-cli 0.7.5 → 0.8.0-rc.6

package/dist/llm/index-passes.js

@@ -1,35 +1,21 @@
-/**
- * Per-pass LLM config resolution for `akm index`.
- *
- * Locked v1 contract (#208):
- * - There is exactly one provider/model configuration: `akm.llm`.
- * - Every LLM-using pass inside `akm index` defaults to that block.
- * - A pass can be opted out individually with `index.<passName>.llm = false`.
- * - Any attempt to supply provider/model fields under `index.<passName>` is
- *   rejected at config-load time by `parseIndexConfig` in
- *   {@link ../core/config.ts} (`ConfigError("INVALID_CONFIG_FILE")`).
- *
- * Passes plug in by calling {@link resolveIndexPassLLM} with their pass
- * name (e.g. `"memory"` for #201's memory-inference pass, `"graph"` for
- * #207's graph-extraction pass). They do not read `config.llm` directly.
- * This keeps the config surface small and the wiring uniform.
- */
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+import { getDefaultLlmConfig, getIndexPassConfig } from "../core/config";
 /**
  * Resolve the {@link LlmConnectionConfig} a single index pass should use, or
  * `undefined` when the pass should run without an LLM.
  *
  * Returns `undefined` if any of:
- * - No top-level `akm.llm` block is configured.
+ * - No default LLM profile is configured.
  * - The pass is explicitly opted out (`index.<passName>.llm === false`).
- *
- * Otherwise returns the shared `akm.llm` config. There is no per-pass
- * provider override; that decision is locked by §9 of the v1 spec.
  */
 export function resolveIndexPassLLM(passName, config) {
-    if (!config.llm)
+    const llm = getDefaultLlmConfig(config);
+    if (!llm)
         return undefined;
-    const passConfig = config.index?.[passName];
+    const passConfig = getIndexPassConfig(config.index, passName);
     if (passConfig?.llm === false)
         return undefined;
-    return config.llm;
+    return llm;
 }

package/dist/llm/memory-infer.js

@@ -1,3 +1,6 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
 /**
  * LLM helper for the `akm index` memory-inference pass (#201).
  *
@@ -18,32 +21,14 @@
 import { toErrorMessage } from "../core/common";
 import { warn } from "../core/warn";
 import { chatCompletion, parseEmbeddedJsonResponse } from "./client";
+import { tryLlmFeature } from "./feature-gate";
 /** Hard cap on body chars sent to the model — pragmatic and matches `runLlmEnrich`. */
 const MAX_BODY_CHARS = 4000;
 const SYSTEM_PROMPT = "You compress a developer memory into one high-signal derived memory for later retrieval. " +
     "Return only valid JSON. No prose outside the JSON object. No markdown fences.";
-const USER_PROMPT_PREFIX = `Compress the memory below into one concise, information-dense derived memory.
-
-Rules:
-- Output ONLY a JSON object with exactly these keys: {"title": string, "description": string, "tags": string[], "searchHints": string[], "content": string}.
-- ` +
-    '"title"' +
-    ` is a short, descriptive title for the derived memory.
-- ` +
-    '"description"' +
-    ` is one sentence explaining why this derived memory matters.
-- ` +
-    '"tags"' +
-    ` contains 3-8 specific keywords.
-- ` +
-    '"searchHints"' +
-    ` contains 3-6 natural-language retrieval phrases.
-- ` +
-    '"content"' +
-    ` must be compact markdown that preserves the reusable insight, root cause, fix, constraints, and applicability conditions when present.
-- Prefer 2-4 short sections with informative headings over long prose.
-- Omit timestamps, verification-only metrics, pleasantries, and session-specific chatter unless they are essential to applying the insight later.
-- Preserve technical specifics (names, versions, identifiers, selectors, file paths, config keys) verbatim.
+const USER_PROMPT_PREFIX = `Compress the memory below into one derived memory. Output ONLY JSON:
+{"title":"short title string","description":"one sentence summary string","tags":["tag1","tag2"],"searchHints":["search phrase 1","search phrase 2"],"content":"2-3 sentence compressed body preserving key facts verbatim"}
+Rules: be specific, no vague generalizations, preserve key facts (names/versions/paths/config keys verbatim), merge related points, 3-8 tags, 3-6 searchHints. The content field must be a plain string with 2-3 sentences.
 
 Memory:
 `;
@@ -51,67 +36,63 @@ Memory:
  * Compress a single memory body into one derived memory via the configured LLM.
  *
  * Returns `undefined` on any failure (timeout, invalid JSON, empty response).
- * Errors
- * are logged via `warn()` but never thrown — a failed split for one memory
+ * Errors are logged via `warn()` but never thrown — a failed split for one memory
  * must not abort the rest of the index pass.
+ *
+ * Routes through `tryLlmFeature("memory_inference", ...)` so the feature gate
+ * and onFallback hook are honoured uniformly (Fix C5).
  */
-export async function compressMemoryToDerivedMemory(llmConfig, body, signal) {
+export async function compressMemoryToDerivedMemory(llmConfig, body, signal, akmConfig, onFallback) {
     const trimmedBody = body.trim();
     if (!trimmedBody)
         return undefined;
     const userPrompt = `${USER_PROMPT_PREFIX}${trimmedBody.slice(0, MAX_BODY_CHARS)}`;
-    let timeoutHandle;
-    try {
-        const raw = await Promise.race([
-            chatCompletion(llmConfig, [
+    return tryLlmFeature("memory_inference", akmConfig, async () => {
+        try {
+            const raw = await chatCompletion(llmConfig, [
                 { role: "system", content: SYSTEM_PROMPT },
                 { role: "user", content: userPrompt },
             ], {
-                maxTokens: llmConfig.maxTokens ?? 4096,
                 temperature: 0.1,
-                timeoutMs: llmConfig.timeoutMs ?? 120_000,
+                timeoutMs: llmConfig.timeoutMs,
                 signal,
-            }),
-            new Promise((_, reject) => {
-                timeoutHandle = setTimeout(() => reject(new Error("memory inference timed out")), llmConfig.timeoutMs ?? 120_000);
-            }),
-        ]);
-        if (!raw)
-            return undefined;
-        const parsed = parseEmbeddedJsonResponse(raw);
-        if (!parsed) {
-            warn("memory inference: invalid JSON response from LLM; skipping memory.");
-            return undefined;
+            });
+            if (!raw)
+                return undefined;
+            const parsed = parseEmbeddedJsonResponse(raw);
+            if (!parsed) {
+                warn("memory inference: invalid JSON response from LLM; skipping memory.");
+                return undefined;
+            }
+            const title = typeof parsed.title === "string" ? parsed.title.trim() : "";
+            const description = typeof parsed.description === "string" ? parsed.description.trim() : "";
+            const content = typeof parsed.content === "string" ? parsed.content.trim() : "";
+            const tags = Array.isArray(parsed.tags)
+                ? parsed.tags
+                    .filter((t) => typeof t === "string")
+                    .map((t) => t.trim())
+                    .filter(Boolean)
+                    .slice(0, 8)
+                : [];
+            const searchHints = Array.isArray(parsed.searchHints)
+                ? parsed.searchHints
+                    .filter((h) => typeof h === "string")
+                    .map((h) => h.trim())
+                    .filter(Boolean)
+                    .slice(0, 6)
+                : [];
+            if (!title || !description || !content || tags.length === 0 || searchHints.length === 0) {
+                warn("memory inference: incomplete derived memory payload from LLM; skipping memory.");
+                return undefined;
+            }
+            return { title, description, tags, searchHints, content };
         }
-        const title = typeof parsed.title === "string" ? parsed.title.trim() : "";
-        const description = typeof parsed.description === "string" ? parsed.description.trim() : "";
-        const content = typeof parsed.content === "string" ? parsed.content.trim() : "";
-        const tags = Array.isArray(parsed.tags)
-            ? parsed.tags
-                .filter((t) => typeof t === "string")
-                .map((t) => t.trim())
-                .filter(Boolean)
-                .slice(0, 8)
-            : [];
-        const searchHints = Array.isArray(parsed.searchHints)
-            ? parsed.searchHints
-                .filter((h) => typeof h === "string")
-                .map((h) => h.trim())
-                .filter(Boolean)
-                .slice(0, 6)
-            : [];
-        if (!title || !description || !content || tags.length === 0 || searchHints.length === 0) {
-            warn("memory inference: incomplete derived memory payload from LLM; skipping memory.");
+        catch (err) {
+            warn(`memory inference failed: ${toErrorMessage(err)}`);
             return undefined;
         }
-        return { title, description, tags, searchHints, content };
-    }
-    catch (err) {
-        warn(`memory inference failed: ${toErrorMessage(err)}`);
-        return undefined;
-    }
-    finally {
-        if (timeoutHandle !== undefined)
-            clearTimeout(timeoutHandle);
-    }
+    }, undefined, {
+        timeoutMs: llmConfig.timeoutMs,
+        onFallback,
+    });
 }

package/dist/llm/metadata-enhance.js

@@ -1,25 +1,28 @@
-/**
- * LLM-driven metadata enhancement for stash entries.
- *
- * Split out of `llm.ts` so the higher-level workflow (prompting the LLM to
- * improve descriptions/tags/searchHints) lives separately from the low-level
- * transport client in `client.ts`.
- */
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import { chatCompletion, parseJsonResponse } from "./client";
+import { tryLlmFeature } from "./feature-gate";
 const SYSTEM_PROMPT = `You are a metadata generator for a developer asset registry. Given a script/skill/command/agent entry, generate improved metadata. Respond with ONLY valid JSON, no markdown fencing.`;
 /**
  * Use an LLM to enhance a stash entry's metadata: improve description,
  * generate searchHints, and suggest tags.
+ *
+ * When `akmConfig` is provided, routes through
+ * `tryLlmFeature("metadata_enhance", ...)` so the feature gate is honoured and
+ * errors are swallowed to `{}`. When `akmConfig` is `undefined` the gate is
+ * bypassed entirely — the LLM call runs unconditionally and errors propagate to
+ * the caller (pre-gate behaviour, used by direct callers such as tests).
  */
-export async function enhanceMetadata(config, entry, fileContent, signal) {
+export async function enhanceMetadata(config, entry, fileContent, signal, akmConfig) {
     const contextParts = [`Name: ${entry.name}`, `Type: ${entry.type}`];
     if (entry.description)
         contextParts.push(`Current description: ${entry.description}`);
     if (entry.tags?.length)
         contextParts.push(`Current tags: ${entry.tags.join(", ")}`);
     if (fileContent) {
-        // Limit content to first 2000 chars to stay within token limits
-        const truncated = fileContent.length > 2000 ? `${fileContent.slice(0, 2000)}\n... (truncated)` : fileContent;
+        // Limit content to first 4000 chars to stay within token limits (matches other modules)
+        const truncated = fileContent.length > 4000 ? `${fileContent.slice(0, 4000)}\n... (truncated)` : fileContent;
         contextParts.push(`File content:\n${truncated}`);
     }
     const userPrompt = `${contextParts.join("\n")}
@@ -30,24 +33,34 @@ Generate improved metadata for this ${entry.type}. Return JSON with these fields
 - "tags": an array of 3-8 relevant keyword tags
 
 Return ONLY the JSON object, no explanation.`;
-    const raw = await chatCompletion(config, [
-        { role: "system", content: SYSTEM_PROMPT },
-        { role: "user", content: userPrompt },
-    ], { signal });
-    const parsed = parseJsonResponse(raw);
-    if (!parsed)
-        return {};
-    const result = {};
-    if (typeof parsed.description === "string" && parsed.description) {
-        result.description = parsed.description;
-    }
-    if (Array.isArray(parsed.searchHints)) {
-        result.searchHints = parsed.searchHints
-            .filter((s) => typeof s === "string" && s.trim().length > 0)
-            .slice(0, 8);
-    }
-    if (Array.isArray(parsed.tags)) {
-        result.tags = parsed.tags.filter((s) => typeof s === "string" && s.trim().length > 0).slice(0, 10);
+    const runLlm = async () => {
+        const raw = await chatCompletion(config, [
+            { role: "system", content: SYSTEM_PROMPT },
+            { role: "user", content: userPrompt },
+        ], { signal });
+        const parsed = parseJsonResponse(raw);
+        if (!parsed)
+            return {};
+        const result = {};
+        if (typeof parsed.description === "string" && parsed.description) {
+            result.description = parsed.description;
+        }
+        if (Array.isArray(parsed.searchHints)) {
+            result.searchHints = parsed.searchHints
+                .filter((s) => typeof s === "string" && s.trim().length > 0)
+                .slice(0, 8);
+        }
+        if (Array.isArray(parsed.tags)) {
+            result.tags = parsed.tags.filter((s) => typeof s === "string" && s.trim().length > 0).slice(0, 10);
+        }
+        return result;
+    };
+    // When no akmConfig is provided, bypass the feature gate entirely: run the
+    // LLM call directly and let errors propagate to the caller (pre-gate
+    // behaviour). When akmConfig is present, honour the feature flag and swallow
+    // errors to {} via tryLlmFeature.
+    if (akmConfig === undefined) {
+        return runLlm();
     }
-    return result;
+    return tryLlmFeature("metadata_enhance", akmConfig, runLlm, {}, { timeoutMs: config.timeoutMs });
 }

package/dist/llm/prompts/graph-extract-user-prompt.md

@@ -0,0 +1,35 @@
+Extract entities and relations from the asset body below.
+
+Rules:
+- Output ONLY a JSON object: {"entities": ["Entity One", ...], "relations": [{"from": "A", "to": "B", "type": "uses"}, ...]}.
+- Entities are short, canonical noun phrases (project names, services, tools, people, file/dir names, technical concepts).
+- Relations connect two entities that both appear in the entities array.
+- "type" is a short verb phrase (e.g. "uses", "depends on", "owns", "documents"). Optional; omit when unsure.
+- Drop pleasantries, meta-commentary, and timestamps.
+- Limit to at most {{MAX_ENTITIES}} entities and {{MAX_RELATIONS}} relations per asset.
+- Return {"entities": [], "relations": []} if the body has no extractable graph content.
+- DO NOT return markdown code blocks, ONLY valid JSON objects.
+
+Examples:
+
+Input:
+## Deployment Notes
+The auth-service uses PostgreSQL for user sessions. It depends on the redis-cache
+for rate limiting. The terraform-provisioner deploys everything to the prod cluster.
+Owner: @alice.
+
+Output:
+{"entities":["auth-service","PostgreSQL","redis-cache","terraform-provisioner","prod cluster","@alice"],"relations":[{"from":"auth-service","to":"PostgreSQL","type":"uses"},{"from":"auth-service","to":"redis-cache","type":"depends on"},{"from":"terraform-provisioner","to":"prod cluster","type":"deploys"},{"from":"terraform-provisioner","to":"auth-service","type":"deploys"},{"from":"@alice","to":"auth-service","type":"owns"}]}
+
+Input:
+## Meeting: API Redesign
+Discussed moving from REST to GraphQL. The frontend team will use Apollo Client.
+Backend needs to implement resolvers. Timeline: Q2.
+
+Output:
+{"entities":["REST","GraphQL","Apollo Client","frontend team","backend","resolvers","Q2"],"relations":[{"from":"frontend team","to":"Apollo Client","type":"uses"},{"from":"backend","to":"resolvers","type":"implements"},{"from":"frontend team","to":"GraphQL","type":"migrates to"}]}
+
+===============
+
+Request:
+

package/dist/output/cli-hints-full.md

@@ -0,0 +1,281 @@
+# akm CLI — Full Reference
+
+You have access to a searchable library of scripts, skills, commands, agents, knowledge documents, workflows, wikis, and memories via `akm`. Search your sources first before writing something from scratch.
+
+## Search
+
+```sh
+akm search "<query>"                          # Search all sources
+akm curate "<task>"                          # Curate the best matches for a task
+akm search "<query>" --type workflow          # Filter by asset type
+akm search "<query>" --source both            # Also search registries
+akm search "<query>" --source registry        # Search registries only
+akm search "<query>" --limit 10               # Limit results
+akm search "<query>" --detail full            # Include scores, paths, timing
+```
+
+| Flag | Values | Default |
+| --- | --- | --- |
+| `--type` | `skill`, `command`, `agent`, `knowledge`, `workflow`, `script`, `memory`, `vault`, `wiki`, `any` | `any` |
+| `--source` | `stash`, `registry`, `both` | `stash` |
+| `--limit` | number | `20` |
+| `--format` | `json`, `jsonl`, `text`, `yaml` | `json` |
+| `--detail` | `brief`, `normal`, `full`, `summary`, `agent` | `brief` |
+| `--for-agent` | boolean (deprecated — use `--detail agent`) | `false` |
+
+## Curate
+
+Combine search + follow-up hints into a dense summary for a task or prompt.
+
+```sh
+akm curate "plan a release"                   # Pick top matches across asset types
+akm curate "deploy a Bun app" --limit 3       # Keep the summary shorter
+akm curate "review architecture" --type workflow # Restrict to one asset type
+```
+
+## Show
+
+Display an asset by ref. Knowledge assets support view modes as positional arguments.
+
+```sh
+akm show script:deploy.sh                     # Show script (returns run command)
+akm show skill:code-review                    # Show skill (returns full content)
+akm show command:release                      # Show command (returns template)
+akm show agent:architect                      # Show agent (returns system prompt)
+akm show workflow:ship-release                # Show parsed workflow steps
+akm show knowledge:guide toc                  # Table of contents
+akm show knowledge:guide section "Auth"       # Specific section
+akm show knowledge:guide lines 10 30          # Line range
+akm show knowledge:my-doc                    # Show content (local or remote)
+```
+
+| Type | Key fields returned |
+| --- | --- |
+| script | `run`, `setup`, `cwd` |
+| skill | `content` (full SKILL.md) |
+| command | `template`, `description`, `parameters` |
+| agent | `prompt`, `description`, `modelHint`, `toolPolicy` |
+| knowledge | `content` (with view modes: `full`, `toc`, `frontmatter`, `section`, `lines`) |
+| workflow | `workflowTitle`, `workflowParameters`, `steps` |
+| memory | `content` (recalled context) |
+| vault | `keys`, `comments` |
+| wiki | `content` (same view modes as knowledge). For any wiki task, run `akm wiki list`. To ingest sources, `akm wiki ingest <name>` dispatches the configured agent (defaults.agent or `--profile`) to execute the ingest workflow. |
+
+## Capture Knowledge While You Work
+
+```sh
+akm remember "Deployment needs VPN access"     # Record a memory in your stash
+akm remember --name release-retro < notes.md   # Save multiline memory from stdin
+akm remember "note" --target my-other-stash    # Route write to a named writable stash source
+akm import ./docs/auth-flow.md                 # Import a file as knowledge
+akm import - --name scratch-notes < notes.md   # Import stdin as a knowledge doc
+akm import https://example.com/docs/auth       # Fetch one URL and import it as knowledge
+akm import ./doc.md --target my-other-stash    # Route import to a named writable stash source
+akm workflow create ship-release               # Create a workflow asset in the stash
+akm workflow validate workflows/foo.md         # Validate a workflow file or ref; lists every error
+akm workflow next workflow:ship-release        # Start or resume the next workflow step
+akm feedback skill:code-review --positive      # Record that an asset helped
+akm feedback agent:reviewer --negative         # Record that an asset missed the mark
+akm feedback memory:deployment-notes --positive # Works for memories too
+akm feedback vault:prod --positive             # Records vault feedback without surfacing values
+```
+
+Use `akm feedback` whenever an asset materially helps or fails so future search
+ranking can learn from actual usage.
+
+## Wikis
+
+Multi-wiki knowledge bases (Karpathy-style). A stash-owned wiki lives at
+`<stashDir>/wikis/<name>/`; external directories or repos can also be registered
+as first-class wikis. akm owns lifecycle + raw-slug + lint + index regeneration
+for stash-owned wikis; page edits use your native Read/Write/Edit tools.
+
+```sh
+akm wiki list                                  # List wikis (name, pages, raws, last-modified)
+akm wiki create research                       # Scaffold a new wiki
+akm wiki register ics-docs ~/code/ics-documentation # Register an external wiki
+akm wiki show research                         # Path, description, counts, last 3 log entries
+akm wiki pages research                        # Page refs + descriptions (excludes schema/index/log; includes raw/)
+akm wiki search research "attention"           # Scoped search (equivalent to --type wiki --wiki research)
+akm wiki stash research ./paper.md             # Copy source into raw/<slug>.md (never overwrites)
+akm wiki stash research https://example.com/paper # Fetch one URL into raw/<slug>.md
+akm wiki stash research ./paper.md --target my-stash # Route write to a named writable stash source
+echo "..." | akm wiki stash research -         # stdin form
+akm wiki lint research                         # Structural checks: orphans, broken xrefs, uncited raws, stale index
+akm wiki ingest research                       # Dispatch defaults.agent to run the ingest workflow on this wiki
+akm wiki ingest research --profile claude --model sonnet  # Override profile and model
+akm wiki ingest research --timeout-ms 600000   # Override agent CLI timeout (default: profile setting)
+akm wiki remove research --force               # Delete pages/schema/index/log; preserves raw/
+akm wiki remove research --force --with-sources # Full nuke, including raw/
+```
+
+**For any wiki task, start with `akm wiki list`. Then `akm wiki ingest <name>`
+dispatches the configured agent (defaults.agent or `--profile`) to execute
+the wiki's ingest workflow end-to-end — schema read, source dedup, search,
+page create/update, log entry, lint, reindex.** Wiki pages are also addressable as
+`wiki:<name>/<page-path>` and show up in stash-wide `akm search` as
+`type: wiki`. Files under `raw/` and the wiki root infrastructure files
+`schema.md`, `index.md`, and `log.md` are not indexed and do not appear in
+search results. No `--llm` anywhere — akm never reasons about page content.
+
+## Vaults
+
+Encrypted-at-rest key/value stores for secrets. Each vault is a `.env`-format
+file at `<stashDir>/vaults/<name>.env`.
+
+```sh
+akm vault create prod                         # Create a new vault
+akm vault set prod DB_URL postgres://...      # Set a key (or KEY=VALUE combined form)
+akm vault set prod DB_URL=postgres://...      # Combined KEY=VALUE form also works
+akm vault unset prod DB_URL                   # Remove a key
+akm vault list                                # List all vaults across all stashes with key names
+akm vault path vault:prod                     # Print the vault file path for shell loading
+akm vault run vault:prod -- env               # Run one command with all vault vars injected
+akm vault run vault:prod/DB_URL -- printenv DB_URL # Inject one key for one command
+```
+
+## Workflows
+
+Step-based workflows stored as `<stashDir>/workflows/<name>.md`.
+
+Ref-based workflow commands are scoped to the current project/worktree/directory,
+so one active run does not block unrelated directories from starting the same
+workflow. Direct run-id commands still target the exact run.
+
+```sh
+akm workflow template                         # Print a starter workflow template
+akm workflow create ship-release             # Scaffold a new workflow asset
+akm workflow start workflow:ship-release     # Start a new run in the current scope
+akm workflow next workflow:ship-release      # Advance to the next step (or auto-start) in the current scope
+akm workflow complete <run-id>               # Mark a step complete and advance
+akm workflow status <run-id>                 # Show the exact run by id
+akm workflow resume <run-id>                 # Resume a blocked or failed run
+akm workflow list                            # List workflow runs in the current scope
+```
+
+## Clone
+
+Copy an asset to the working stash or a custom destination for editing.
+
+```sh
+akm clone <ref>                               # Clone to working stash
+akm clone <ref> --name new-name               # Rename on clone
+akm clone <ref> --dest ./project/.claude       # Clone to custom location
+akm clone <ref> --force                       # Overwrite existing
+akm clone "npm:@scope/pkg//script:deploy.sh"  # Clone from remote package
+```
+
+When `--dest` is provided, `akm init` is not required first.
+
+## Save
+
+Commit local changes in a git-backed stash. Behaviour adapts automatically:
+
+- **Not a git repo** — no-op (silent skip)
+- **Git repo, no remote** — stage and commit only (the default stash always falls here)
+- **Git repo, has remote, not writable** — stage and commit only
+- **Git repo, has remote, `writable: true`** — stage, commit, and push
+
+```sh
+akm save                                      # Save primary stash (timestamp message)
+akm save -m "Add deploy skill"               # Save with explicit message
+akm save my-skills                            # Save a named writable git stash
+akm save my-skills -m "Update patterns"      # Save named stash with message
+```
+
+The `--writable` flag on `akm add` opts a remote git stash into push-on-save:
+
+```sh
+akm add git@github.com:org/skills.git --provider git --name my-skills --writable
+```
+
+## Add & Manage Sources
+
+```sh
+akm add <ref>                                 # Add a source
+akm add @scope/stash                            # From npm (managed)
+akm add owner/repo                            # From GitHub (managed)
+akm add ./path/to/local/stash                   # Local directory
+akm add git@github.com:org/repo.git --provider git --name my-skills --writable
+akm enable skills.sh                          # Enable the skills.sh registry
+akm disable skills.sh                         # Disable the skills.sh registry
+akm list                                      # List all sources
+akm list --kind managed                       # List managed sources only
+akm remove <target>                           # Remove by id, ref, path, or name
+akm update --all                              # Update all managed sources
+akm update <target> --force                   # Force re-download
+```
+
+## Registries
+
+```sh
+akm registry list                             # List configured registries
+akm registry add <url>                        # Add a registry
+akm registry add <url> --name my-team         # Add with label
+akm registry add <url> --provider skills-sh   # Specify provider type
+akm registry remove <url-or-name>             # Remove a registry
+akm registry search "<query>"                 # Search all registries
+akm registry search "<query>" --assets        # Include asset-level results
+akm registry build-index                      # Build the default cache-backed index.json
+akm registry build-index --out dist/index.json # Build to a custom path
+```
+
+## Configuration
+
+```sh
+akm config list                               # Show current config
+akm config get <key>                          # Read a value
+akm config set <key> <value>                  # Set a value
+akm config unset <key>                        # Remove a key
+akm config path --all                         # Show all config paths
+```
+
+## Other Commands
+
+```sh
+akm init                                      # Initialize working stash
+akm index                                     # Rebuild search index (metadata enrichment when configured)
+akm index --full                              # Full reindex (metadata enrichment when configured)
+akm list                                      # List all sources
+akm upgrade                                   # Upgrade akm using its install method
+akm upgrade --check                           # Check for updates
+akm help migrate 0.6.0                        # Print migration notes for a release (or: latest)
+akm hints                                     # Print this reference
+akm completions                               # Print bash completion script
+akm completions --install                     # Install completions
+```
+
+## Proposals & Improvement (0.8.0+)
+
+```sh
+akm improve <ref>                              # Propose improvement for an asset
+akm proposals                                  # List pending proposals
+akm show proposal <id>                         # Render the proposal body
+akm diff <ref-or-id>                           # Diff by ref, UUID, or 8-char prefix (proposal positional optional)
+akm diff skill:akm-dream                       # Diff by asset ref
+akm accept 7c115132                            # Accept by UUID prefix
+akm accept <id> --target team-stash            # Accept to a named writable stash source
+akm reject skill:my-skill --reason "not ready" # Reject by asset ref
+akm reject <id> --reason "..."                 # Archive with a reason
+```
+
+Per-task `timeoutMs`: task markdown frontmatter may set `timeoutMs: null` to
+disable the agent kill timer for long-running local-model tasks, or a number
+(milliseconds) to override `config.agent.timeoutMs` for that task only.
+
+## Output Control
+
+All commands accept `--format` and `--detail` flags:
+
+- `--format json` (default) — structured JSON
+- `--format jsonl` — one JSON object per line (streaming-friendly)
+- `--format text` — human-readable plain text
+- `--format yaml` — YAML output
+- `--detail brief` (default) — compact output
+- `--detail normal` — adds tags, refs, origins
+- `--detail full` — includes scores, paths, timing, debug info
+- `--detail summary` — metadata only (no content/template/prompt), under 200 tokens
+- `--detail agent` — agent-optimized output: strips non-actionable fields
+- `--for-agent` — deprecated alias for `--detail agent`
+
+Run `akm -h` or `akm <command> -h` for per-command help.