docs: audit guide/ + compat-matrix for drift (closes #149)

[scttfrdmn]

Summary

calque#149 asked for a design pass on user-facing docs. That pass happened (a design comment on the issue proposed docs/guide/{getting-started,which-verb,cli-reference,troubleshooting,README}.md), and separately those files were actually written — but the issue was never closed and the content was never independently fact-checked against the current CLI/parser source.

This PR is that audit. It is not new documentation — it verifies every concrete claim in the existing guide docs (and the compat-matrix) against cmd/calque/*.go, tools/pyast/pyast.py, and internal/parse/parse.go, and fixes what had drifted.

Discrepancies found and fixed

• docs/guide/cli-reference.md (calque real flags table):

  • Missing --allow-card-swap entirely — a real flag added for calque#178's GPU card-swap feature. Added its row.
  • --instance's default was documented as a literal g6.2xlarge. The actual default in main.go's parseRealArgs is "", which resolves to g6.2xlarge unless --allow-card-swap substituted a different card (in which case an instance for that card is picked automatically). Corrected the row.

• docs/modal-compatibility-matrix.md (§H Scheduling):

  • The modal.Cron(...)/modal.Period(...) object-form rows said "⬜ Not recognized as a distinct construct" — stale. tools/pyast/pyast.py's _schedule_marker and internal/parse/parse.go's decodeScheduleMarker already recognize both structurally (calque#91), landing them in the same "recorded but NOT honored" (🟨) bucket as the bare-string schedule= row directly above — just not executed (no scheduler exists in the spike). Rewrote both rows, the schedule= row's cross-reference, the backlog item Warm worker: spored (Go) supervises long-lived Python runner (§6) #12, and the provenance note to match.

Verified as already accurate (no changes needed)

• getting-started.md's IAM policy JSON, resource-tagging (calque:run-id/calque:managed/calque:command), and per-bucket role-reuse claims — checked against internal/plan/iam.go and internal/plan/spawn.go.
• which-verb.md's flag cross-references (--function, --entrypoint, --pip, --secret, etc.) — checked against main.go/realrun.go.
• troubleshooting.md's bug citations (IAM instance profile, uv venv binary path, AL2023 missing git, fleet-mode field-dropping) — checked against internal/exec/bootstrap.go and internal/pool/pool_test.go.
• Every other flag in cli-reference.md (run, smoke, ramp, pool create/scale/delete/status/list, spawn-run, session checkout/checkin/status/list) — checked flag-by-flag against every flag.NewFlagSet call across cmd/calque/*.go.
• Cross-links: root README.md → docs/guide/{which-verb,cli-reference}.md, docs/README.md → docs/guide/README.md, examples/README.md → docs/guide/getting-started.md — all already present.

Deliberately deferred, not fixed here

calque#149's own design comment proposed auto-generating cli-reference.md from flag.FlagSet introspection instead of hand-writing it (to prevent this exact class of drift going forward). That's a real, separate idea — tracked as its own smaller follow-up issue, not a blocker to closing #149, since the hand-written content has now been verified accurate.

Test plan

• uvx ruff check . — all checks passed (docs-only change, no Python touched).
• No new relative markdown links added — nothing for markdown-links/lychee to newly validate.
• CI green on this PR (see checks).