feat: Prometheus /metrics + TypeScript SDK + docs revamp

CHANGELOG.md

@@ -8,6 +8,7 @@ This project follows [Semantic Versioning](https://semver.org/). From **v1.0.0**
 
 ### Added
 
+- **`GET /metrics`:** Prometheus text exposition format scrape endpoint (no new dependencies). Same Bearer / loopback gate as `GET /v1/metrics`. Configure Prometheus with `metrics_path: /metrics` and `bearer_token: <FLIGHTDECK_LOCAL_API_TOKEN>` (when token is set). Metrics: `flightdeck_releases_total`, `flightdeck_run_events_total`, `flightdeck_promoted_pointers_total`, `flightdeck_actions_total`, `flightdeck_actions_by_type{action=...}`, `flightdeck_pricing_tables_total`, `flightdeck_schema_version`.
 - **Identity passthrough → audit actor:** HTTP mutating routes (`POST /v1/promote*`, `POST /v1/rollback`) now read **`X-FlightDeck-Actor`** (first) and **`X-Forwarded-User`** (second) before falling back to the body `actor` field. Lets a reverse-proxy / SSO layer stamp the audit ledger authoritatively. Trust model documented in **`SECURITY.md`** and **`docs/http-api.md`**.
 - **`flightdeck workspace info [--json]`** — one-screen snapshot of workspace path, database backend, schema version, ledger counters (releases / promoted / actions / run events), configuration (policy, pricing catalog, approval mode), and webhook count. JSON mode for CI / chatops pipelines.
 - **`flightdeck version [--json]`** — explicit version subcommand alongside the existing `--version` flag; `--json` emits `{"name":"flightdeck-ai","version":"1.3.0"}` for scripts and dashboards.
@@ -236,11 +237,11 @@ This project follows [Semantic Versioning](https://semver.org/). From **v1.0.0**
 
 ### Added
 
-- **[docs/cli.md](https://github.com/flightdeckdev/flightdeck/blob/main/docs/cli.md)**: CLI reference (synopsis, flags, exit codes, pointers to quickstart examples).
+- **[docs/cli.md](https://flightdeckdev.github.io/flightdeck/cli/)**: CLI reference (synopsis, flags, exit codes, pointers to quickstart examples).
 - **`scripts/quickstart_smoke.py`**: cross-platform quickstart smoke (**no bash**): temp workspace, Python placeholder substitution, **`release verify`**, **`doctor`**.
 - **CI:** run quickstart smoke on **Ubuntu** and **Windows** matrix jobs (alongside pytest and schema drift).
 - **Tests:** `tests/test_quickstart_smoke.py` exercises the smoke script.
-- **0.8 milestone planning** (CLI + CI): archived under **`docs/reviews/`** in development clones; shipped CLI narrative is **[docs/cli.md](https://github.com/flightdeckdev/flightdeck/blob/main/docs/cli.md)** on the canonical repo; this tree ships **`scripts/quickstart_smoke.py`** / **`flightdeck-quickstart-verify`** (see **Unreleased**).
+- **0.8 milestone planning** (CLI + CI): archived under **`docs/reviews/`** in development clones; shipped CLI narrative is **[docs/cli.md](https://flightdeckdev.github.io/flightdeck/cli/)** on the canonical repo; this tree ships **`scripts/quickstart_smoke.py`** / **`flightdeck-quickstart-verify`** (see **Unreleased**).
 
 ### Changed
 

docs/cli.md

@@ -8,6 +8,83 @@ For the on-disk formats the CLI reads and writes see
 [release-artifact.md](release-artifact.md). For the HTTP API exposed by `flightdeck
 serve` see [http-api.md](http-api.md).
 
+## Common patterns
+
+Copy-paste recipes for the most frequent workflows. Full flag reference follows below.
+
+### Pattern 1: Register, ingest, and diff in one shell session
+
+The core loop from scratch — useful when you already have event JSONL files ready:
+
+```bash
+flightdeck init
+BASELINE=$(flightdeck release register ./baseline-release)
+CANDIDATE=$(flightdeck release register ./candidate-release)
+
+# Substitute the placeholder release IDs in your JSONL files, then ingest:
+sed "s/__BASELINE_RELEASE_ID__/${BASELINE}/g" baseline-events.jsonl > /tmp/be.jsonl
+sed "s/__CANDIDATE_RELEASE_ID__/${CANDIDATE}/g" candidate-events.jsonl > /tmp/ce.jsonl
+flightdeck runs ingest /tmp/be.jsonl
+flightdeck runs ingest /tmp/ce.jsonl
+
+flightdeck release diff "$BASELINE" "$CANDIDATE" --window 7d
+```
+
+### Pattern 2: Policy-gated CI step
+
+Exit 1 when policy fails — wire this as a blocking CI step:
+
+```bash
+flightdeck release diff "$BASELINE" "$CANDIDATE" --window 7d --fail-on-policy
+# Exit 0 → policy passed; Exit 1 → blocked (diff output already printed)
+```
+
+For JSON output suitable for `jq` parsing in CI:
+
+```bash
+flightdeck release diff "$BASELINE" "$CANDIDATE" --window 7d \
+  --fail-on-policy --output json | jq '.policy.passed'
+```
+
+See `examples/ci/ledger_gate.py` for the complete cross-platform CI pattern and
+`examples/ci/github-actions/` for GitHub Actions workflow templates.
+
+### Pattern 3: Weekly health check
+
+Run on a schedule to confirm the ledger is intact and pricing tables are not stale:
+
+```bash
+flightdeck doctor
+flightdeck pricing check --max-age-days 90 --fail
+```
+
+`doctor` exits 0 when all schema, pointer, and sequence checks pass. `pricing check` exits 1
+when any bundled table is older than `--max-age-days` and `--fail` is set. Together they make
+a clean recurring health probe.
+
+### Pattern 4: Setting up outbound webhooks for Slack
+
+Get a Slack notify on every promote or rollback:
+
+```bash
+# Register the webhook (prints the secret once — save it)
+flightdeck webhook add \
+  --url https://your-adapter.example.com/flightdeck \
+  --event promote.succeeded \
+  --event rollback.succeeded \
+  --event promote.blocked \
+  --description "Slack #releases"
+
+# Test delivery before going live
+flightdeck webhook test <webhook_id>
+```
+
+FlightDeck sends HMAC-signed `POST` requests; most chat tools need a thin adapter to reshape
+the payload. See [SDK integrations — Slack](sdk-integrations.md#slack) for a ready-made
+Cloudflare Worker example.
+
+---
+
 ## Global flags
 
 | Flag | Description |