akm-cli 0.5.0 → 0.6.0-rc1

package/CHANGELOG.md

@@ -6,20 +6,47 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.6.0] - 2026-04-23
+
+### Changed (breaking)
+
+- **Terminology cleanup — clean break from "kit" → "stash"** (#148). Pre-v1, no fallback period.
+  - **Wire format**: `RegistryIndex.kits[]` renamed to `RegistryIndex.stashes[]`. Schema version bumped to **v3** — `akm-cli >= 0.6.0` only parses indexes with `version: 3`. v1/v2 indexes are no longer accepted. Every static-index registry must regenerate its `index.json` with `version: 3` to be readable. The official `akm-registry` ships a regenerated index alongside this release.
+  - **Discovery**: npm packages and GitHub repos are now discovered via the `akm-stash` keyword/topic only. Legacy `akm-kit` and `agentikit` keywords/topics are no longer honored. Publishers must retag.
+  - **Schemas**: `schemas/registry-index.json` and `docs/technical/registry-index.schema.json` updated (`RegistryKit` → `RegistryStash`, `kits` → `stashes`).
+  - **Internal types**: `RegistryKitEntry` → `RegistryStashEntry`, `InstalledKitEntry` → `InstalledStashEntry`, `KitInstallStatus` → `StashInstallStatus`, `KitSource` → `StashSource`. Files `src/kit-include.ts` → `src/stash-include.ts` and `src/installed-kits.ts` → `src/installed-stashes.ts`.
+  - **Asset hit field**: `RegistryAssetSearchHit.kit` → `RegistryAssetSearchHit.stash`.
+  - **Docs**: `docs/kit-makers.md` → `docs/stash-makers.md`. All user-facing "kit" references in docs and the README replaced with "stash".
+  - **Preserved**: the *Agent Kit Manager* tagline, the `akm-cli` npm package name, and the `akm.include` package.json field.
+  - **Migration**: a curated registry author should regenerate their `index.json` (rename `kits` → `stashes`, drop legacy keyword filtering). Publishers should add the `akm-stash` keyword/topic and remove `akm-kit`/`agentikit`.
+- **`akm registry` description**: changed from "Manage kit registries" to "Manage stash registries".
+
 ## [0.5.0] - 2026-04-22
 
 ### Added
 
-- **Multi-wiki support** (#119, #121): new `wiki` asset type with nine CLI verbs under `akm wiki …` (`create`, `list`, `show`, `remove`, `pages`, `search`, `stash`, `lint`, `ingest`). Each wiki lives at `<stashDir>/wikis/<name>/` with `schema.md`, `index.md`, `log.md`, `raw/`, and agent-authored pages. Wiki pages are first-class in stash-wide `akm search`. `akm index` regenerates each wiki's `index.md` as a side effect. See `docs/wikis.md` for the full guide. Design principle: **akm surfaces, the agent writes** — no LLM calls, no network access; akm owns only operations with invariants an agent can't reliably enforce (lifecycle, raw-slug uniqueness, structural lint, index regeneration, workflow discovery).
-- **Workflow asset type** (#118): new `workflow` type with `akm workflow create <name>` and `akm workflow next <ref>` for authoring and stepping through multi-step workflows stored in the stash
-- **Vault asset type** (#117): new `vault` type backed by `.env` files; `akm vault` subcommand with `list`, `show`, `load` (emits a `source` snippet for the current shell); values never appear in structured output
-- **`--trust` flag for installs**: `akm add <source> --trust` performs a one-off trusted install, bypassing the install audit for that source
-- **Writable git stash + `akm save`** (#114): `akm add … --writable` opts a remote git-backed stash into push-on-save; `akm save [name] [-m message]` commits (and pushes when writable + remote is set); default stash is auto-initialized as a git repo; git stash provider now uses `git clone` instead of HTTP tarball download
+- **Multi-wiki support** (#119, #121, #136, #139, #144): new `wiki` asset type with ten CLI verbs under `akm wiki …` (`create`, `register`, `list`, `show`, `remove`, `pages`, `search`, `stash`, `lint`, `ingest`). Each wiki lives at `<stashDir>/wikis/<name>/` with `schema.md`, `index.md`, `log.md`, `raw/`, and agent-authored pages. Wiki pages are first-class in stash-wide `akm search`. `akm index` regenerates each wiki's `index.md` as a side effect and is resilient to malformed workflow assets. Raw sources under `raw/` and the `schema.md` / `index.md` / `log.md` infrastructure files are intentionally excluded from the search index. See `docs/wikis.md` for the full guide. Design principle: **akm surfaces, the agent writes** — no LLM calls, no network access; akm owns only operations with invariants an agent can't reliably enforce (lifecycle, raw-slug uniqueness, structural lint, index regeneration, workflow discovery).
+- **External wiki registration** (#139, #144): `akm wiki register <name> <path-or-repo>` and `akm add --type wiki --name <name> <source>` register an existing directory or git/website repo as a first-class wiki without copying or mutating it; source and wiki search state are refreshed immediately and refs/state are normalized on subsequent indexing.
+- **Workflow asset type** (#118): new `workflow` type with `akm workflow` subcommands `template`, `create`, `start`, `next`, `complete`, `status`, `list`, and `resume` for authoring and stepping through multi-step workflows stored in the stash. Runs snapshot their step list at start so edits to the source workflow do not affect an in-flight run.
+- **Vault asset type** (#117): new `vault` type backed by `.env` files; `akm vault` subcommand with `list`, `show`, `create`, `set`, `unset`, and `load` (emits a `source` snippet for the current shell via a mode-0600 temp file); values never appear in structured output.
+- **`--trust` flag for installs**: `akm add <source> --trust` performs a one-off trusted install, bypassing the install audit for that source. Blocked install errors now include a `hint` pointing to `--trust` as a remediation option.
+- **Writable git stash + `akm save`** (#114): `akm add … --writable` opts a remote git-backed stash into push-on-save; `akm save [name] [-m message]` commits (and pushes when writable + remote is set); default stash is auto-initialized as a git repo; git stash provider now uses `git clone` instead of HTTP tarball download.
+- **`akm help migrate <version>`** (#132): prints the release notes and migration guidance for a given version (accepts `0.5.0`, `v0.5.0`, or `latest`). Pulls the matching section from `CHANGELOG.md` when available and supplements it with embedded migration notes for major releases.
+- **Broader `akm upgrade` coverage** (#132, #134): self-update now detects and upgrades npm, bun, pnpm, and standalone-binary installs (previously binary-only). Runtime assets covered by the upgrade flow were also expanded so newly shipped asset types stay current.
+
+### Fixed
+
+- **0.5.0 QA follow-ups** (#130): fixes across the new wiki, workflow, vault, and save/trust surfaces surfaced during release-candidate QA.
 
 ### Removed (breaking)
 
 - The unreleased single-wiki LLM POC: removes `akm lint` command, `akm import --llm` / `--dry-run` flags, `knowledge.pageKinds` config, and the `ingestKnowledgeSource` / `lintKnowledge` LLM prompts. Users of the POC should migrate to the new `akm wiki …` surface; raw content can be manually moved to `wikis/<name>/raw/`.
 
+### Documentation
+
+- **Technical docs refresh** (#138): stash and search architecture docs updated to match the current implementation.
+- **Wiki configuration guide** (#115): new docs page covering wiki configuration and ingest flow.
+
 ## [0.4.1] - 2026-04-21
 
 ### Added

package/dist/asset-registry.js

@@ -1,13 +1,13 @@
 /**
  * Central registry for asset type renderer and action builder maps.
  *
- * Previously these maps lived in `local-search.ts` and were wired into
- * `asset-spec.ts` via a fragile `_setAssetTypeHooks` deferred callback
- * pattern. If `local-search.ts` was imported after `registerAssetType()`
- * calls, hooks would be silently dropped.
+ * Previously these maps lived in `db-search.ts` (then `local-search.ts`) and
+ * were wired into `asset-spec.ts` via a fragile `_setAssetTypeHooks` deferred
+ * callback pattern. If the search module was imported after
+ * `registerAssetType()` calls, hooks would be silently dropped.
  *
  * This module is a simple singleton that both `asset-spec.ts` and
- * `local-search.ts` import from, eliminating the import-order dependency
+ * `db-search.ts` import from, eliminating the import-order dependency
  * entirely.
  */
 import { buildWorkflowAction } from "./renderers";
@@ -53,3 +53,27 @@ export function registerTypeRenderer(type, rendererName) {
 export function registerActionBuilder(type, builder) {
     ACTION_BUILDERS[type] = builder;
 }
+export const defaultRendererRegistry = {
+    rendererNameFor(type) {
+        return TYPE_TO_RENDERER[type];
+    },
+    actionBuilderFor(type) {
+        return ACTION_BUILDERS[type];
+    },
+};
+/**
+ * Build a registry from explicit maps. Useful for tests that need to assert
+ * rendering behavior without touching the global singletons.
+ */
+export function createRendererRegistry(maps) {
+    const renderers = maps.renderers ?? {};
+    const actionBuilders = maps.actionBuilders ?? {};
+    return {
+        rendererNameFor(type) {
+            return renderers[type];
+        },
+        actionBuilderFor(type) {
+            return actionBuilders[type];
+        },
+    };
+}

package/dist/asset-spec.js

@@ -129,8 +129,6 @@ export const ASSET_SPECS = ASSET_SPECS_INTERNAL;
 export function registerAssetType(type, spec) {
     ASSET_SPECS_INTERNAL[type] = spec;
     TYPE_DIRS[type] = spec.stashDir;
-    ASSET_TYPES.length = 0;
-    ASSET_TYPES.push(...getAssetTypes());
     // Auto-register renderer and action builder if provided in spec
     if (spec.rendererName) {
         registerTypeRenderer(type, spec.rendererName);
@@ -139,11 +137,20 @@ export function registerAssetType(type, spec) {
         registerActionBuilder(type, spec.actionBuilder);
     }
 }
+/**
+ * Remove a previously-registered asset type.
+ *
+ * Primarily used by tests for cleanup after `registerAssetType` calls so
+ * subsequent tests see a pristine type registry. Built-in types should not
+ * normally be deregistered at runtime.
+ */
+export function deregisterAssetType(type) {
+    delete ASSET_SPECS_INTERNAL[type];
+    delete TYPE_DIRS[type];
+}
 export function getAssetTypes() {
     return Object.keys(ASSET_SPECS_INTERNAL);
 }
-/** Warning: mutable array — stale if captured before `registerAssetType()` calls. Prefer `getAssetTypes()`. */
-export const ASSET_TYPES = getAssetTypes();
 export const TYPE_DIRS = Object.fromEntries(Object.entries(ASSET_SPECS_INTERNAL).map(([type, spec]) => [type, spec.stashDir]));
 export function isRelevantAssetFile(assetType, fileName) {
     return ASSET_SPECS[assetType]?.isRelevantFile(fileName) ?? false;
@@ -158,7 +165,7 @@ export function deriveCanonicalAssetNameFromStashRoot(assetType, stashRoot, file
     // When the first segment matches the canonical type dir (e.g. "agents"),
     // use it as the type root so canonical names are relative to it.
     // Otherwise fall back to stashRoot — this preserves the full relative path
-    // as the canonical name, which is correct for installed kits that live
+    // as the canonical name, which is correct for installed stashes that live
     // under custom directories (e.g. "tools/agents/svelte-file-editor").
     const typeRoot = firstSegment === TYPE_DIRS[assetType] ? path.join(stashRoot, firstSegment) : stashRoot;
     return deriveCanonicalAssetName(assetType, typeRoot, filePath);

package/dist/cli-hints.js

@@ -0,0 +1,300 @@
+/**
+ * Embedded "agent CLI hints" rendered by `akm hints` when no other source
+ * is available.
+ *
+ * Extracted from `src/cli.ts` so it does not bloat the CLI module and so
+ * docs/CI tooling can re-use the same constants. Two flavors:
+ * `EMBEDDED_HINTS` (default reference, ~40 lines) and
+ * `EMBEDDED_HINTS_FULL` (`--detail full`, ~250 lines).
+ */
+const EMBEDDED_HINTS = `# akm CLI
+
+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.
+
+## Quick Reference
+
+\`\`\`sh
+akm search "<query>"                          # Search all sources
+akm curate "<task>"                          # Curate the best matches for a task
+akm search "<query>" --type workflow          # Filter to workflow assets
+akm search "<query>" --source both            # Also search registries
+akm show <ref>                                # View asset details
+akm workflow next <ref>                       # Start or resume a workflow
+akm remember "Deployment needs VPN access"    # Record a memory in your stash
+akm import ./notes/release-checklist.md       # Import a knowledge doc into your stash
+akm wiki list                                 # List available wikis
+akm wiki ingest <name>                        # Print the ingest workflow for a wiki
+akm feedback <ref> --positive|--negative      # Record whether an asset helped
+akm add <ref>                                 # Add a source (npm, GitHub, git, local dir)
+akm clone <ref>                               # Copy an asset to the working stash (optional --dest arg to clone to specific location)
+akm save                                      # Commit (and push if writable remote) changes in the primary stash
+akm registry search "<query>"                 # Search all registries
+\`\`\`
+
+## Primary Asset Types
+
+| Type | What \`akm show\` returns |
+| --- | --- |
+| 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) |
+| workflow | Parsed steps plus workflow-specific execution commands |
+| memory | Recalled context (read the content for background information) |
+| vault | Key names only; use vault commands to inspect or load values safely |
+| wiki | A page in a multi-wiki knowledge base. For any wiki task, start with \`akm wiki list\`, then \`akm wiki ingest <name>\` for the workflow. Run \`akm wiki -h\` for the full surface. |
+
+When an asset meaningfully helps or fails, record that with \`akm feedback\` so
+future search ranking can learn from real usage.
+
+Run \`akm -h\` for the full command reference.
+`;
+const EMBEDDED_HINTS_FULL = `# 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\` then \`akm wiki ingest <name>\` for the 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 import ./docs/auth-flow.md                 # Import a file as knowledge
+akm import - --name scratch-notes < notes.md   # Import stdin as a knowledge doc
+akm workflow create ship-release               # Create a workflow asset in the stash
+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
+\`\`\`
+
+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/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)
+echo "..." | akm wiki stash research -         # stdin form
+akm wiki lint research                         # Structural checks: orphans, broken xrefs, uncited raws, stale index
+akm wiki ingest research                       # Print the ingest workflow for this wiki (no action)
+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>\`
+to get the step-by-step workflow.** 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 vault:prod                     # List key names (no values)
+akm vault show vault:prod                     # Same as list (alias)
+akm vault load vault:prod                     # Print export statements to source
+\`\`\`
+
+## Workflows
+
+Step-based workflows stored as \`<stashDir>/workflows/<name>.md\`.
+
+\`\`\`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
+akm workflow next workflow:ship-release      # Advance to the next step (or auto-start)
+akm workflow complete <run-id>               # Mark a step complete and advance
+akm workflow status <run-id>                 # Show current run status
+akm workflow resume <run-id>                 # Resume a blocked or failed run
+akm workflow list                            # List all workflow runs
+\`\`\`
+
+## 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 ./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
+akm index --full                              # Full reindex
+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
+\`\`\`
+
+## 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.
+`;
+export { EMBEDDED_HINTS, EMBEDDED_HINTS_FULL };