Skip to content

README.md

Latest commit

 

History

History
66 lines (50 loc) · 3.78 KB

README.md

File metadata and controls

66 lines (50 loc) · 3.78 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.

Task Read first
Local app development Local guide
Codespaces fallback Drawing Board guide
Installation or package contract Root README
Commands, API, or output Command reference
Errors and recovery Errors and recovery
Versioning and publication Release policy and runbook
Dated release observations Release history
Vulnerability reporting Security policy

Authority boundaries

  • README.md owns repository orientation, direct installation, package boundaries, 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, and dist-tags before relying on them operationally; publisher configuration is checked when it changes or fails.
  • 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. Create another page only for 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

Pass Node test options through npm test to focus a run while retaining discovery under test/:

npm test -- --test-name-pattern="publication"

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