akm docs

AKM CLI and product surface recommendations

Release plan from the CLI review and the review of release/0.11.0 at 4b44628eb. Checked items are implemented on this branch; the first released version remains to be recorded in the migration guide.

The first additive doctor entry points are also implemented: doctor mirrors health, and doctor metrics, info, log, and judge reuse their existing handlers. Improve-run reporting and the remaining doctor consolidation are still planned.

0.10.x is the target for every compatible fix and additive replacement, including usage metrics; 0.11 removes the deprecated surface and makes incompatible default/result changes. Keep existing commands, flags, config keys, output contracts, and input interpretation working throughout 0.10.x. Introduce replacement behavior through new explicit inputs first; do not hide a breaking change inside an addition. STABILITY.md records the scheduled removals, and the migration guide records first supporting versions.

Doctor boundary: All reporting, health, metrics, and developer diagnostics belong under akm doctor in 0.11, with focused subcommands for distinct jobs. This power-user surface can evolve faster than the normal CLI; ordinary operation results, lifecycle status, and previews such as --dry-run remain with their commands.

Learning boundary: In both 0.10.x and 0.11, simplify improve and related automation/learning interfaces without changing their internals, effective defaults, or behavior. Preserve process selection/order, prompts, model requests, eligibility, judgment, acceptance, writes, publication, and evaluation history; CLI/config changes must feed the existing implementations equivalent inputs. This supersedes the earlier proposals to replace the strategy engine, make improvement proposal-only, unify autonomy policies, or change what setup --learning off disables.

Compatible changes and preparation

CLI cuts and refactors

Show argument review

All declared show arguments and shared flags were checked in the current 0.10 tree and the reviewed 0.11 snapshot. Proposed names below are migration targets, not installed syntax.

Argument Recommendation and reason
<ref>[#fragment] [0.10.x / 0.11] Keep one ref, returning its full body or exact selected section by default. A read should not need a verbosity preset to return the requested content.
--context exact|lead [0.10.x add; 0.11 remove old mode] Add --lead for the document introduction on a Markdown fragment; exact remains the default. A single optional behavior does not need a two-value mode.
--max-tokens [0.10.x fix; retain in 0.11] Apply the budget independently to whole documents, exact fragments, and lead-plus-fragment reads; disclose estimation and truncation. Context size is a useful control regardless of presentation.
--max-chars [0.11] Remove in favor of the token budget. Two mutually exclusive size units add little value to an agent-facing read command.
--detail brief [0.10.x add; 0.11 remove old mode] Add --outline, returning heading titles/slugs without the body. Finding a section is a concrete operation, not a verbosity level.
Other --detail modes, including 0.10's agent projection [0.11] Remove in favor of one consistent result with content, ref, and useful metadata. Scripts and agents should not need different result shapes for the same read.
--project [0.10.x / 0.11] Retain explicit usage attribution, including none, and clarify that it does not filter or change content. Wrappers reading outside a project's working directory still need correct attribution.
--format [0.11] Retain JSON and text only, with the same content-selection behavior. Structured consumption and direct reading cover show's normal uses.
--output [0.11] Remove; use shell redirection. Writing stdout to a file does not need another show option.
Shared --config [0.10.x add; retain in 0.11] Offer the normal installation/config selector without changing existing path resolution when omitted. Explicit reads must still resolve against the intended installation.
--quiet / -q, --verbose [0.10.x retain; 0.11 conflict error] Keep shared stderr controls and reject simultaneous use in 0.11. Diagnostics should neither change the returned content nor compete with each other.
--help / -h [0.10.x] Add concise whole-asset, fragment, outline, and bounded-read examples as replacements land. These examples explain the complete content-selection surface before migration.

Learning configuration cleanup

Command and argument usage metrics

Implementation: doctor metrics usage and the local cli_usage_* tables of metrics.db are available in the working tree; first published version is pending. Resolved run dispatch wiring is tracked with the additive run implementation. The CLI reference documents the schema, retention, export deduplication and observation limits.

Release fixes and completion