Skip to content

README.md

Latest commit

 

History

History
60 lines (46 loc) · 3.51 KB

README.md

File metadata and controls

60 lines (46 loc) · 3.51 KB
Raw

First Draft CLI documentation

Use this page to find the narrowest authoritative document for a task. Runtime source and tests remain the final evidence for implemented behavior; if they contradict a document, surface the contradiction instead of guessing.

If the task concerns... Read first
Public installation, trust, or the shortest current journey Root README
Commands, options, environment variables, API behavior, output, or materialization Command reference
Stable errors, exit codes, retry safety, ambiguous outcomes, or local recovery Errors and recovery
Version policy, release preparation, publication, verification, rollback, or promotion Release policy and runbook
What was observed for an earlier tag, package, or dist-tag Release history
Vulnerability reporting Security policy

Authority boundaries

  • README.md owns public onboarding, the shortest supported journey, current trust claims, and routes.
  • commands.md owns detailed command semantics. Built-in --help, runtime source, and tests own exact executable syntax and behavior.
  • errors.md owns handled-error interpretation and recovery guidance.
  • RELEASING.md owns living release policy and the operator runbook.
  • release-history.md preserves dated release observations. Recheck live tags, package versions, dist-tags, access, and trusted-publisher state before relying on them operationally.
  • The source repository's AGENTS.md routes agent work; it should stay compact rather than duplicate these documents.

Retrieval quality

Start here, then load the one owning document for the task. Follow a cross-link only when the task crosses an authority boundary, such as moving from successful command behavior to failure recovery. Prefer descriptive headings, short paragraphs, command maps, and checklists; create another page only when it has a distinct audience, task, or authority.

The documentation tests keep AGENTS.md at or below 2 KiB, the root README at or below 6 KiB, and this map at or below 4 KiB. They also require every public topic to remain reachable from this map or the root README and verify repository-local links and fragments. The package check separately verifies that every relative link in the packaged Markdown resolves inside that exact package.

Work on the repository

Development uses Node.js 24.18.0 and npm 11.16.0, pinned in .tool-versions. From a fresh checkout:

npm ci --ignore-scripts
npm audit
npm run check

npm run check runs type checking, linting, formatting, tests, the exact package allowlist check, and a packed-package smoke test. To inspect the package manifest without writing a tarball:

npm pack --dry-run --json --ignore-scripts

To reproduce the length-delimited SHA-256 used by external evidence to identify packaged JavaScript runtime inputs (package.json, bin/firstdraft.js, and every .js file under src/), run:

node scripts/runtime-digest.js