docs

ash documentation

A map of this directory. For the project pitch and verb-surface overview see the top-level README.md; for the live, authoritative per-verb schema run ash help (never duplicated in markdown).

Getting started — adoption/

• adoption/install.md — install via Homebrew or from source.
• adoption/claude-code.md — wire ashmcp into Claude Code.
• adoption/claude-desktop.md — wire ashmcp into Claude Desktop.
• adoption/codex.md — wire ashmcp into OpenAI's Codex CLI.
• adoption/cursor.md — wire ashmcp into Cursor.
• ../claude-plugin/ — the Claude Code skill that steers an agent toward ash verbs.
• adoption/migration-from-hook.md — moving from the PreToolUse hook to MCP.

Reference — how ash works

• configuration.md — ash.toml: jail, git backend, runner, ledger retention.
• PreToolUse.md — the ash hook deny/redirect behavior.
• architecture/layers.md — the four-tier vocabulary (protocol / verb library / dispatch / clients).
• agent-guidance.md — the doc surfaces that drive ash usage and how they are maintained.
• optimization-tiers.md — the framework for deciding what to optimize.
• ledger-cleanup.md — ledger retention and cleanup.

Design notes — rationale for shipped subsystems

• bench.md, bench-2.md — the ash bench measurement framework.
• report.md — ash report ledger synthesis.
• replay.md — ash replay, the ledger as a regression suite.
• streaming.md — the streaming (Chunk/Final) protocol.
• cache-shape.md — the cache-aware response envelope (ASH-108).
• path-prefixes.md — path-prefix token optimization (ASH-71).
• mcp/design-decisions.md — the ashmcp adapter.
• vocab/design.md — the vocab inventory generator.
• library-audit.md — the dependency-reuse audit (ASH-103).

Measurements — empirical results

• performance-baselines.md — latency baselines and where the time goes.
• encoding-results.md — measured token costs and the encoding decisions they drove.
• cli-tokens.md — token-efficiency evaluation of the CLI surface.
• cache-prefix-measurement.md, cache-telemetry.md — prompt-cache validation.
• mcp/wire-cost.md — CLI vs MCP wire cost.
• lsp-pilot-validation.md — the lang/LSP pilot evaluation (ASH-141).

Generated artifacts — checked in, regenerated by make

• vocab/inventory.md, vocab/inventory.json — every stable agent-facing string (make vocab).
• mcp/tools.json — the MCP tool schema (make schema).

Historical & speculative

• value-assessment/ — a point-in-time go/no-go evaluation (May 2026); see its README.
• revolutionary-directions.md — an ideas document, not a roadmap.