Rewrite the CLI repository guide

[raghubetina]

Summary\n- orient developers and agents around CLI ownership and repository routes\n- retain the direct stable-package installation and GitHub Publication command boundary\n- replace brittle README prose assertions with route and package checks\n\n## Verification\n-

@firstdraft.com/cli@0.2.0 check
npm run typecheck && npm run lint && npm run format:check && npm test && npm run pack:check && npm run pack:smoke

@firstdraft.com/cli@0.2.0 typecheck
tsc --project jsconfig.json

@firstdraft.com/cli@0.2.0 lint
eslint .

@firstdraft.com/cli@0.2.0 format:check
prettier --check .

Checking formatting...
All matched files use Prettier code style!

@firstdraft.com/cli@0.2.0 test
node scripts/run-tests.js

✔ derives readable lower-snake keys from Unicode names (1.23575ms)
✔ uses a stable digest when no readable ASCII remains (0.430083ms)
✔ bounds long derived keys with a readable prefix and stable digest (0.194834ms)
✔ every generated key lowers to the current iOS identifier component (1.02075ms)
✔ explicit keys retain the complete Foundation Plan schema boundary (0.107ms)
✔ derives a clean display name from explicit keys (0.125167ms)
✔ accepts interoperable nonblank Unicode text (0.095708ms)
✔ derivation rejects invalid direct inputs (0.248625ms)
✔ no arguments show help (1.234083ms)
✔ help uses long and short options (0.314083ms)
✔ version matches the package through long and short options (0.145375ms)
✔ an unknown command returns a non-echoing usage error (0.358417ms)
✔ an unknown option returns a non-echoing usage error (0.261167ms)
✔ recognized root options have deterministic precedence (0.189125ms)
✔ argument parsing does not mutate injected input (0.093875ms)
✔ the executable delegates success and usage errors to the tested runner (176.019291ms)
✔ the executable preserves its status when an output pipe closes (129.503083ms)
✔ parses canonical binary-safe artifact bytes and materializes an exact tree (17.730667ms)
✔ materialization enforces supported permission bits independently of umask (2.365167ms)
✔ rejects noncanonical, duplicate-key, additive, and non-UTF-8 envelopes (0.420042ms)
✔ pins external provenance identities and validates nested metadata (0.614333ms)
✔ requires strict Base64, exact file digests, and the metadata-only manifest digest (0.355167ms)
✔ rejects nonportable paths, unsupported metadata, and noncanonical UUID lists (0.708292ms)
✔ rejects duplicate, case-folded, and file-directory prefix conflicts (0.350458ms)
✔ requires strict manifest byte order (0.140083ms)
✔ preflight never follows an output-parent symlink or accepts an existing target (0.963458ms)
✔ compilation status makes one canonical GET and returns terminal failures successfully (24.193542ms)
✔ compilation status wait pins provenance and follows valid transitions (52.420875ms)
✔ compilation status has a bounded wait and validates exact response shapes (23.344458ms)
✔ compilation download distinguishes Head and Plan provenance without starting work (30.076459ms)
✔ download requires succeeded status and validates historical Head provenance (21.760417ms)
✔ artifact downloads enforce the 128 MiB declared and streamed bound (15.520584ms)
✔ compilation syntax and output preflight fail before network access (16.462208ms)
✔ status and artifact authentication problems are stable (10.863625ms)
✔ documentation routes commands, recovery, and release knowledge (1.898167ms)
✔ documentation entrypoints stay lean and route every public topic (1.45675ms)
✔ local documentation links and fragments resolve (3.363ms)
✔ generate application-key prints the deterministic derived key (4.422334ms)
✔ generate application-key help has no local or network prerequisites (0.312708ms)
✔ generate application-key validates names before producing output (0.452ms)
✔ generate help describes only its local commands (3.04475ms)
✔ generate group returns non-echoing usage errors (0.411791ms)
✔ generate uuid prints one value by default and a requested count (0.315625ms)
✔ generate uuid accepts counts beyond an arbitrary product cap (0.297917ms)
✔ generate uuid uses fresh production UUIDv7 values (0.5325ms)
✔ generate uuid help has no generation prerequisites (0.167875ms)
✔ generate uuid validates count before generating output (0.342208ms)
✔ unexpected UUID generation errors remain loud (0.32825ms)
✔ package metadata preserves the audited runtime boundary (1.104792ms)
✔ ordinary pre-1.0 versions use the approval-gated distribution channel (0.196375ms)
✔ stable release completion requires qualified latest promotion (0.791667ms)
✔ OIDC publication repeats every release source check (0.425125ms)
✔ package metadata defines no installation lifecycle (0.088333ms)
✔ plan compile submits exact bytes, waits for valid analysis, and publishes once (79.821583ms)
✔ plan compile may push unchanged bytes before analysis and Publication (10.353458ms)
✔ plan compile waits past a terminal analysis for the prior graph version (9.134875ms)
✔ plan compile rejects an older Head at the accepted graph version (29.76425ms)
✔ invalid JSON and schema diagnostics stop before analysis or Publication (32.946958ms)
✔ semantic and failed analysis stop before Publication with structured status (20.999083ms)
✔ recurring diagnostics remain repairable and never trigger Publication (22.84575ms)
✔ the final local-byte check stops a stale analyzed Plan before Publication (2.962542ms)
✔ push ambiguity, analysis failures, and rejected reads have distinct errors (86.28475ms)
✔ help and removed local-output syntax have no prerequisites (0.598125ms)
✔ plan help describes the available commands (1.566709ms)
✔ plan init help does not require creation options (23.787583ms)
✔ plan commands return non-echoing usage errors (2.161417ms)
✔ plan init creates exact deterministic local files (50.947458ms)
✔ plan init derives either missing application identity value (62.682125ms)
✔ plan init preserves both explicitly supplied identity values (29.857042ms)
✔ plan init accepts explicit schema-valid keys beyond the derived limit (25.555208ms)
✔ the executable initializes with a production UUIDv7 (88.403042ms)
✔ the nested ignore file hides the complete local directory from Git (269.193292ms)
✔ an existing root gitignore remains byte-for-byte unchanged (23.043416ms)
✔ plan init validates every argument before randomness or filesystem access (1.487041ms)
✔ plan init accepts ordinary astral Unicode in the application name (34.360291ms)
✔ plan init never overwrites an existing local path (17.116041ms)
✔ plan init refuses an existing symlink without following it (6.6215ms)
✔ a second initialization preserves the first Project (36.8625ms)
✔ partial filesystem failures stop immediately without cleanup (1.219667ms)
✔ unexpected programming errors remain loud (0.427666ms)
✔ plan compile invokes Publication and one conditional singleton PUT and polls sequentially (72.394417ms)
✔ progress reports each safe GitHub phase, scheduled retry, and parked retry once (14.463958ms)
✔ progress accepts every coordinated safe reason code (23.06825ms)
✔ a repeated singleton PUT accepts provenance matching local Plan state (19.001625ms)
✔ an ambiguous PUT is reconciled by one safe singleton GET (10.445667ms)
✔ an ambiguous PUT does not adopt a singleton from a different Plan Head (16.258166ms)
✔ an invalid successful PUT response can reconcile to the exact singleton (14.035833ms)
✔ an unresolved ambiguous PUT remains outcome unknown without replaying the mutation (15.163958ms)
✔ help and invalid arguments have no local or network prerequisites (0.739708ms)
✔ local prerequisites reject before publication network access (69.640584ms)
✔ missing and rejected credentials use the stable authentication error (17.803208ms)
✔ validated start rejections are distinct from unknown mutation outcomes (15.238709ms)
✔ validated timeout and server errors reconcile without replaying the PUT (52.0025ms)
✔ polling distinguishes unavailable and invalid status responses (3.216958ms)
✔ polling rejects replacement identities, regressions, and repository mutation (69.160292ms)
✔ the bounded wait reports its last validated status (1.419083ms)
✔ terminal progress distinguishes Compilation outcomes from later GitHub outcomes (18.78675ms)
✔ exact response shapes and coherent terminal projections are required (260.516916ms)
✔ plan push help has no local or network prerequisites (2.507792ms)
✔ the initial push sends exact bytes and saves its origin and ETag (53.467334ms)
✔ the initial push defaults to the First Draft production origin (52.545416ms)
✔ later pushes replay the saved ETag and rotate it opaquely (57.322708ms)
✔ a saved origin may be repeated but never changed (40.915875ms)
✔ an API override must be one valid secure or loopback origin (230.381916ms)
✔ usage errors happen before local or network access (0.375708ms)
✔ HTTP diagnostics and problems leave local state byte-for-byte unchanged (107.635792ms)
✔ server rejection envelopes expose only validated response fields (32.873958ms)
✔ missing credentials and a validated 401 use one stable authentication error (19.354166ms)
✔ a stale update preserves the prior ETag and exact local state (30.247542ms)
✔ an update rejects a create status before changing local state (26.710958ms)
✔ 422 diagnostics must identify the exact submitted bytes (49.514959ms)
✔ unverified HTTP failures have an ambiguous outcome without echoing their body (17.162875ms)
✔ transport failures disclose the ambiguous outcome without leaking errors (16.52625ms)
✔ response stream failures retain the received status without leaking errors (14.944833ms)
✔ success responses are bound to the request before state changes (134.32525ms)
✔ warning diagnostics survive an accepted response (21.176833ms)
✔ success media types are compared case-insensitively (20.791042ms)
✔ a push from an uninitialized directory makes no request (0.555875ms)
✔ local paths are bounded regular files beneath a real directory (101.092667ms)
✔ invalid local state is rejected before exact Plan bytes leave the machine (126.6185ms)
✔ the Plan is never parsed or reserialized locally (17.212917ms)
✔ failed atomic state replacements report the accepted ETag (39.296584ms)
✔ state serialization cannot create a file the CLI refuses to read (19.938666ms)
✔ oversized success responses stop before local state changes (36.638084ms)
✔ streamed oversized responses are cancelled at the byte cap (16.234458ms)
✔ the packaged executable completes a real local HTTP push (144.324458ms)
✔ plan status help has no local or network prerequisites (4.714416ms)
✔ plan status validates arguments before local or network access (0.648334ms)
✔ plan status makes one bounded GET to only the pinned origin (8.958833ms)
✔ additive response fields are ignored rather than leaked or rejected (9.445541ms)
✔ diagnostics preserve each supported optional subject shape (41.135917ms)
✔ plan status exposes the complete canonical GapSet and digest (12.00875ms)
✔ plan status accepts the pinned Service zero-gap canonical digest (19.781333ms)
✔ all validated analysis states are command results rather than transport failures (49.009209ms)
✔ an initialized but unpushed Plan explains the required recovery (6.573125ms)
✔ invalid private state never selects a network destination (72.123375ms)
✔ missing paths and state symlinks are rejected without following them (22.864208ms)
✔ wait polls sequentially until the same analysis becomes valid (9.338166ms)
✔ wait stops on each terminal analysis status without another poll (50.249292ms)
✔ wait stops on its first failed read instead of repairing it speculatively (15.592ms)
✔ wait does not follow a replacement analysis silently (9.086042ms)
✔ wait has a fixed overall deadline and reports the last verified state (16.45925ms)
✔ a response body failure at the wait deadline reports the last verified state (10.810167ms)
✔ validated problem responses are whitelisted for agent recovery (0.955834ms)
✔ missing credentials and a validated 401 use one stable authentication error (0.876542ms)
✔ invalid HTTP responses are non-retryable and never expose their body (40.165875ms)
✔ network, redirect, and response-stream failures advise bounded retries (19.022916ms)
✔ success responses are rejected unless every contract field is valid (121.1385ms)
✔ valid timestamps include offsets, lowercase RFC 3339 markers, and leap seconds (15.002583ms)
✔ plan status has a dedicated 128 MiB declared and streamed response bound (2.133541ms)
✔ the packaged executable polls a real local analysis endpoint (98.681916ms)
✔ release compatibility declares the coordinated CLI contract (1.66975ms)
✔ matches the RFC 9562 Appendix A.6 UUIDv7 vector (0.645041ms)
✔ encodes the inclusive timestamp bounds in network byte order (0.141458ms)
✔ sets the version and variant while preserving the other random bits (0.208667ms)
✔ requests and copies exactly 16 random bytes (0.521459ms)
✔ rejects timestamps outside the unsigned 48-bit integer range (0.451875ms)
✔ rejects random input that is not exactly 16 bytes (0.112792ms)
ℹ tests 158
ℹ suites 0
ℹ pass 158
ℹ fail 0
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 1694.451083

@firstdraft.com/cli@0.2.0 pack:check
node scripts/check-pack.js

@firstdraft.com/cli@0.2.0 pack:smoke
node scripts/smoke-package.js\n- \n- author-context and independent documentation reviews approved