# CLI Specification

The CLI is designed for CI use: deterministic outputs, stable exit codes, and JSON artifacts for tooling.

## Common flags (all commands)

This is the *target* contract; v0 currently implements a subset per-command.

* `--spec <dir>`: Spec root directory (default: `spec/`).
* `--input <path>`: Markdown file or directory (where applicable).
* `--out <dir>`: Output directory (default: `out/`).
* `--profile <name>`: One of: `web_pdf`, `print_pdf`, `dense_tech`, `memo`, `slide_deck` (where applicable).
* `--strict`: Use strict thresholds in `spec/quality_gates.yaml` (QA/report).
* `--format <json|sarif|text>`: Lint output format.
* `--fail-on <must|should|warn>`: Lowest severity that fails `lint` (default: `must`).
* `--degraded-ok`: Allow degraded mode without failing (lint/render-html).
* `--version`: Print tool version and exit.

## Command: `validate-spec`

Purpose:

* Validate YAML/JSON spec files and (when present) rule NDJSON batches.

Outputs:

* `out/spec-validation.json`

Exit codes:

* `0`: ok
* `4`: config/schema error
* `5`: internal error

## Command: `report`

Purpose:

* Produce a consolidated report (coverage + indexes status).

Outputs:

* `out/coverage-report.json`
* `out/coverage-summary.md`

Exit codes:

* `0`: report built
* `2`: coverage floor violated (only when rule batches exist)
* `4`: config/schema error
* `5`: internal error

## Command: `lint`

Purpose:

* Parse Markdown into a minimal block AST (headings, paragraphs, lists, code fences, tables).
* Emit deterministic diagnostics and a manual checklist derived from the registry.

Outputs:

* `out/lint-report.json`
* `out/manual-checklist.md`
* `out/manual-checklist.json`
* `out/degraded-mode-report.json` (only when degraded mode triggers)
* `out/lint-report.sarif` (only when `--format sarif`)
* `out/fix-suggestions.json` (only when `--fix --fix-mode suggest`)
* `out/fixed/*.md` (only when `--fix --fix-mode rewrite`)

Exit codes:

* `0`: ok
* `2`: lint failed (fail-on threshold exceeded, or degraded mode without `--degraded-ok`)
* `4`: config error

## Command: `render-html`

Purpose:

* Render Markdown to deterministic HTML and CSS based on a profile.

Outputs:

* `out/render.html`
* `out/render.css`
* `out/typeset-report.json`
* `out/degraded-mode-report.json` (only when degraded mode triggers)

Exit codes:

* `0`: ok
* `2`: degraded mode without `--degraded-ok`
* `4`: config error

## Command: `render-pdf`

Purpose:

* Render Markdown to PDF using the first available engine (playwright/chromium/wkhtmltopdf/weasyprint).

Outputs:

* `out/render.html`
* `out/render.css`
* `out/typeset-report.json`
* `out/render-log.json`
* `out/render.pdf` (only when rendering succeeds)

Exit codes:

* `0`: ok
* `3`: renderer missing or engine error (see `out/render-log.json`)
* `4`: config error

## Command: `qa`

Purpose:

* Run deterministic post-render QA checks (HTML analysis v0) and enforce numeric gates from `spec/quality_gates.yaml`.

Outputs:

* `out/layout-report.json`
* `out/qa-report.json`

Exit codes:

* `0`: gates pass
* `2`: gates fail
* `4`: config error / missing `out/render.html`