docs: document validation edge cases, promote/rollback scope, actor resolution, and env vars

[cursor]

Summary

Documentation-only PR triggered by the recent push to main (commit 9f849fd). Addresses knowledge gaps identified by reviewing the source against the existing docs.

Docs added/updated

docs/http-api.md

• POST /v1/events validation rules: documents that an empty events array returns HTTP 422 (Pydantic validation), not 400. Clarifies that api_version values other than "v1" — empty string, null, wrong case ("V1"), unknown strings — all return HTTP 400 with a specific message ("Unsupported api_version for POST /v1/events: <value> (only 'v1' is accepted)."). Documents that inserted counts only newly written rows (duplicates silently skipped). Adds 422 to the Errors table.
• POST /v1/diff errors: adds "inconsistent agent_id within one side's run events" as a 400 source.

docs/operations-and-policy.md

• New subsection: "compute_diff vs. promote_release / rollback_release: filter scope" — explains that promote and rollback query events by environment only (no tenant_id or task_id filter), while compute_diff supports all three. Advises operators to use release diff first when tenant-scoped evaluation is needed.
• Expanded "cross-agent diffs" subsection — documents the ValueError raised when events for one side span multiple agent_id values ("Each side of the diff must have a single consistent agent_id among run events."), explains the cause (incorrectly tagged ingest), and gives the fix.
• Common errors table — adds the mixed-agent_id error with cause and fix.

docs/cli.md

• flightdeck init caveat — clarifies that init is the one exception to the "all commands require flightdeck.yaml" rule: it creates the file without calling load_config.
• New "Actor resolution" section — documents that CLI audit records derive actor from USER (Unix/macOS), then USERNAME (Windows), falling back to "unknown". Notes that the HTTP API accepts an explicit actor field (default "http").

DEVELOPMENT.md

• New "Environment variables" reference table covering: FLIGHTDECK_LOCAL_API_TOKEN, FLIGHTDECK_USE_SYSTEM_TEMP, USER/USERNAME, VITE_FLIGHTDECK_LOCAL_API_TOKEN, VITE_DEV_PROXY_TARGET, and TMPDIR/TEMP/TMP.

Codepaths covered

• src/flightdeck/server/routes/ingest.py — IngestEventsRequest validation, api_version check
• src/flightdeck/ledger.py — diff_releases agent_id invariant
• src/flightdeck/operations.py — _evaluate_promotion_or_rollback event query scope
• src/flightdeck/cli/main.py — actor_name(), init command

Knowledge gaps addressed

1. HTTP 422 vs 400 on ingest: operators who send [] or use wrong api_version casing got opaque errors with no docs to explain the distinction.
2. Promote/rollback filter scope: not obvious from docs that --tenant/--task flags on release diff have no equivalent in release promote, making tenant-specific safety analysis a multi-step workflow.
3. Mixed agent_id in events: a silent data quality issue that surfaces as a confusing ValueError with no previous mention in docs.
4. Actor provenance: audit consumers querying release_actions would see "unknown" or a username with no explanation of how those values are set.
5. Environment variable catalogue: scattered across several docs; now consolidated in one table for easy reference.