pm-cli Documentation

This directory is the public documentation home for pm-cli. It is organized for progressive disclosure: read the smallest page that answers the current question, then follow links only when more detail is needed.

Optional CLI Guide Router

pm guide is provided by the optional guide-shell package. Install it when local in-CLI documentation routing is useful:

pm package install guide-shell --project
pm guide
pm guide quickstart
pm guide commands --depth standard
pm guide sdk --depth deep --format markdown
pm guide release --json

Read Path

Reader	First page	Then read
New user	Quickstart	Command Reference
New maintainer	Onboarding	Agent Guide, Testing, Releasing
Coding agent	Agent Guide	Configuration, then command help
Maintainer	Contributing	Testing, Releasing, Architecture
Package author	Packages and Extensions	SDK, starter extension
Codex or ChatGPT plugin implementer	Codex Plugin	Native ChatGPT and Codex Plugin Implementation Plan
Codex user	Codex Plugin	Agent Guide, then Command Reference
Claude Code user	Claude Code Plugin	Agent Guide, then Command Reference
Machine client	`pm contracts --json`	CLI Scripting Contract, Command Reference, optionally `pm install guide-shell --project && pm guide commands`

Documentation Map

Quickstart - install, initialize, create, claim, link, test, close.
Onboarding - first-two-hours maintainer and contributor setup.
Agent Guide - canonical agent loop, tracker linking, and token-minimal command choices.
Agent Read and Test Receipts - JSON help provenance, linked-test persistence, and history diff continuation.
Command Reference - command families with examples and when to use each family.
Context and Operations Namespaces - native navigation, diagnostics, event streams, and compatibility aliases.
CLI Scripting Contract - exit codes, flat mutation receipts versus read envelopes, stdout/stderr boundaries, stable JSON fields, uniform OR filters, and shell composition recipes.
Configuration - settings, storage formats, output, search, validation, and environment variables.
Semantic Batching and Retrieval Quality - independent request bounds, execution receipts, and per-query quality floors.
Testing - sandbox-safe local tests and linked-test orchestration.
Completion Portability and Bounded Replication Checks - literal Bash choices across versions and locales, and semantic Git diff collection.
Build and Release Acceptance - complete-build leases and cross-platform registry installation controls.
Security Governance - vulnerability reporting, review discipline, property fuzzing, and OpenSSF limitations.
Architecture - contributor internals: storage, mutation flow, search, extensions, and command contracts.
Noun–Verb CLI Grammar - accepted command architecture, exhaustive destination census, hidden aliases, and the surface-growth gate.
SDK Primitive Inventory - SDK-first migration map and private-import ratchet for CLI/MCP layering.
Package SDK Contract Conformance - authoritative public types, typeof module derivation, and the first-party parity gate.
SDK Action and Boundary Conformance - derived CLI/SDK/MCP action vocabulary, public-import ratchets, intent budget diagnostics, and package-runner proof.
MCP 2026-07-28 Protocol Decision - stateless request metadata, discovery, result envelopes, explicit legacy boundary, and migration policy.
Progressive Tool Discovery - opt-in bounded MCP catalogs, public SDK ranking and pagination, canonical results, and compatibility isolation.
MCP 2026-07-28 Conformance Matrix - official revision changes mapped to canonical owners and executable evidence.
MCP Interaction and Task SDK - public MRTR continuation, cache/schema validation, and durable task-store contracts.
MCP Skills and Apps - negotiated draft workflow discovery, stable interactive views, digests, provenance, accessibility, and trust boundaries.
MCP Remote Transport, Authorization, and Migration - Streamable HTTP operation, subscriptions, OAuth and trace boundaries, threat model, and deprecated-feature ratchet.
SDK Artifact Output Contracts - clean stdout/file exporter channels, bounded receipts, binary-safe delivery, and shared NDJSON terminal framing.
Context Relevance and Packing - shared CLI/SDK signals, derived-store provenance, ranking explanations, and token budgets.
Next-work Selection Budgets - bounded executable recommendations, omission receipts, and graded 10k/100k context verification.
Context Algorithm Portfolio - stable proposal slugs, historical aliases, individual owners, cognitive compositions, and experiment gates.
Output Projection and Omission Contracts - explicit withheld-field receipts, mode-paired row keys, and completion resolver outcomes.
Output Token Accounting - opt-in CLI/MCP byte attribution, bounded receipt overhead, and release-level tokens-per-task baselines.
SDK Context Platform - task-oriented entry point for authoritative reads, ranking, package workflows, diagnostics, recovery, and verification.
Self-Describing Context Contracts - intent-scoped reads, semantic flag invocation metadata, visibility parity, and generated error vocabulary.
Generated Agent Capability Routing - contract-derived command families shared by help, guide, skills, completion, MCP, and extensions.
Generated Refusal Closure Census - complete error-catalog join to executable refusal evidence and explicit uncovered obligations.
Universal Read Output Contracts - cross-command include, amount, cost, and encoding controls for CLI, SDK, MCP, and packages.
Diagnostic Output Contracts - action-first error budgets, deterministic degradation, SDK projection, and executable refusal assurance.
History Algorithms and Detached Attestations - named record digests, portable exact-byte proofs, and read-only verification.
History-derived Governance Repair - verified closure timestamps and typed issue-code lineage.
History Maintenance and Recovery - native history commands, permanent aliases, shared SDK transforms, and transactional recovery.
Agent Recovery and Guidance - policy refusal evidence, canonical help, and managed instruction freshness.
Declarative Workflow Policies - portable lifecycle requirements, independent approvals, and completeness reports.
Mutation Integrity - shared CLI/SDK/MCP author, secret, append-only disposition, and stale-work guardrails.
Agent Provenance ADR Amendment - extensible model, effort, role, and host provenance with privacy and compatibility boundaries.
SDK Agent Session and Episode Context - inherited role/topic context, cross-process episode identity, and deterministic history grouping.
SDK Agent Environments - calibrated observations, total verdicts, isolated episodes, and an executable public-SDK environment.
Improvement Ledger and History Analytics - audited quantitative observations, live provenance coverage, and bounded observational fleet outcomes.
Project Assurance Primitives - SDK-owned measurements, assertions, lifecycle gates, cost receipts, and durable verdict history shared by CLI and MCP.
Planning Measurements - lifecycle coverage, set-membership aggregation, and derived deadline constraints.
Defect Recurrence and Boundary Evidence - captured external samples, structured defect-escape evidence, incremental change-risk indexing, and executable recovery-producer census.
Recurrence and Executable Recovery Contracts - terminal-item recurrence, duplicate-intake routing, capability-aware reindex recovery, and target-aware generated test guidance.
Trustworthy Context and Evidence Contracts - full-record assurance, graph composition, boolean health rows, lossless linked-test removal, and role-labelled recovery.
Context Integrity Contracts - sparse-read identity, closed extension manifests, lossless remote docs, direction-locked graph impact, and cross-version history epochs.
Context Integrity and Recovery Primitives - lossless metadata, write-time link receipts, executed-test evidence, external blockers, npm receipts, history capabilities, and truthful recovery.
SDK Evidence Traceability and Integrity - reverse source-to-item lookup, atomic evidence replacement, no-op history, linked-test collision classification, and telemetry drain receipts.
SDK Context and Evidence Contracts - material omission receipts, scoped preflight activation, truthful merge preference, claim-race classification, and versioned history hashes.
Reproducible Workspaces and Snapshots - deterministic SDK recipes and content-addressed authoritative tracker restore points.
Workspace Position and Lifecycle Roles - role-safe custom workflows plus one bounded merge-fence, receipt, history-drift, and next-action SDK read.
Portable Corpus Shapes - versioned SDK populations for realistic benchmarks, evaluations, and package tests.
Agent UX Contracts - ordering-cycle advisories, graph count units, collision safety, compact context, ownership wording, and recovery behavior.
Packages and Extensions - package install workflows, runtime extension lifecycle, and API reference.
Extension Lifecycle Contracts - source identity, durable migrations, and scoped preflight ownership.
Extension Author Contracts - the stability guarantees and contract surface package authors build against.
SDK - public import surfaces and typed authoring examples.
SDK execution and recovery contracts: schema-driven scheduling, handoff, and command recovery.
Multi-Branch Merge Safety - semantic tracker merge drivers, post-merge integrity gates, delete/modify policy, and recovery-receipt retention.
Codex Plugin - native MCP plugin install, tools, skills, and safety notes.
Native ChatGPT and Codex Plugin Implementation Plan - official-source research, current-state audit, target architectures, security, testing, and phased remediation plan.
Claude Code Plugin - native Claude Code plugin architecture and install flow.
CLI Simplification Migration - root discovery (--pm-path), recovery bundles, and clear/unset semantics for automation maintainers.
Releasing - maintainer release checklist and failure handling.
starter extension - compact extension scaffold reference.

Additional SDK, operations, and generated contracts:

Item Read Projections - identity, projections, and read completeness.
MCP Capability Surfaces - negotiated MCP discovery contracts.
PR Review Loop - complete review inventories and feedback acknowledgment.
Lifecycle Commands and Ownership - canonical bulk commands, ownership compositions, and SDK/MCP migration.
SDK Lifecycle - lifecycle primitives and package integration.
SDK Runtime Boundaries - runtime ownership and import boundaries.
Sentry Contract Epochs - diagnostic compatibility and release epochs.
Generated Agent Command Surface - command routing inventory.
Generated Flag Lexicon Budgets - flag vocabulary and budget inventory.

Guide Topic Map

Optional `pm guide` topic	Primary docs
`quickstart`	Quickstart, Command Reference
`commands`	Command Reference, Configuration
`workflows`	Agent Guide, Testing
`sdk`	SDK, SDK context contracts, Architecture
`extensions`, `packages`	Packages and Extensions, starter extension
`skills`	Agent Guide plus `.agents/skills/*`
`harnesses`	Agent Guide plus `.agents/skills/HARNESS_COMPATIBILITY.md`
`release`	Releasing, CHANGELOG

Community files:

Agent Routing Rules

Start with Agent Guide for workflow rules.
Use Command Reference for command families, not exhaustive flag memory.
Use pm <command> --help --json or pm contracts --command <name> --flags-only --json for exact flags.
Use Architecture only when changing internals or debugging behavior.
Use SDK and Packages and Extensions only when authoring or troubleshooting packages/extensions.

Tracker References

Current documentation structure work is tracked through:

pm-u9d0

Legacy documentation baseline references (closed):

pm-3042 (closed)
pm-r9gu (closed)
pm-1sb2 (closed)

When changing docs, link files back to the active item:

pm docs <item-id> --add path=docs/README.md,note="documentation index"
pm comments <item-id> "Docs updated; links and build verified."

Public Boundary

Public docs must not link to ignored local operations artifacts, unpublished evidence logs, credentials, host-specific runbooks, or private service details. Keep those materials local and out of packaged releases.

Maintenance Checklist

Keep links relative and GitHub-compatible.
Keep README short; move detail into focused pages.
Put a short "Agent Quick Context" near the top of deep docs.
Prefer commands that agents can copy exactly.
Use pm item IDs as durable references when docs explain tracked work.
Run pnpm quality:docs-links before closing documentation tasks. Every Markdown page under docs/ must be reachable transitively from this index, and links to heading fragments must resolve. Fenced examples do not create navigation edges.
A deliberately standalone page requires an individual path and nonempty reason in scripts/release/docs-reachability-exceptions.json; stale exceptions fail. This policy is tracked by pm-s4y3z4 and pm-esbt.