D1: chartr serve command shape

[Teagan42]

Part of #2

D1 — chartr serve command shape

Labels: wayfinder:grilling status:closed
Blocked by: R1 (closed)
Blocks: D6, D8

Resolution

R1 established cmd/chartr is already the headless HTTP entrypoint. This ticket's remaining scope was the container-side config surface. Spec fragment:

• Command surface: no new subcommand. Container invokes existing ./chartr binary.
• Env-var contract (small Go change in cmd/chartr): read CHARTR_ADDR and CHARTR_DATA_DIR as fallbacks before flag defaults, so precedence is flag > env > compiled default. Flag defaults unchanged for bare-metal users (127.0.0.1:8787, existing -data-dir default).
• Default in-container bind: image sets CHARTR_ADDR=0.0.0.0:8787 and CHARTR_DATA_DIR=/data in the Dockerfile ENV; no flags in ENTRYPOINT, so operators can override either purely via compose env without rewriting the command line.
• Exposure warning (internal/server/exposure.go): silence when CHARTR_IN_CONTAINER=1 (image sets this env). Warning stays sharp for bare-metal 0.0.0.0 misconfig; reverse-proxy guidance lives in docs, not repeated on every startup.
• Health endpoint: existing GET /api/health (per R1) is the Docker HEALTHCHECK target. No new endpoint needed.
• Logging: existing stdout logging is docker logs-suitable; no change specified here.
• Host-gate / origin allowlist: deferred to a new research ticket — R1 named internal/server/origins.go and hostgate.go but didn't detail semantics. Spawning R2 — Host-gate & origin allowlist semantics to inventory before committing to a CHARTR_ALLOWED_HOSTS-style env.

Downstream impact:

• D6 (Dockerfile) now has the concrete ENV block and entrypoint shape it needs, pending R2's finding.
• D8 (compose + docs) can proceed on env-driven config; may need a small addendum from R2 for allowlist envs.

Question

Assuming R1 confirms a new (or renamed) headless serve mode is needed, decide its shape:

• Subcommand vs. flag on the root command (chartr serve vs. chartr --serve)?
• Default bind address and port (localhost:? — a chartr-idiomatic choice, not a collision with common dev ports).
• Configuration surface: env vars (CHARTR_ADDR, CHARTR_STATE_DIR, …) vs. flags vs. config file — and precedence.
• Health/readiness endpoint: required for v1? Path and payload if so.
• Logging: stdout structured logs suitable for docker logs; log-level flag/env.
• Interaction with the existing webview command — do they share a serving core, or is serve a distinct entrypoint?

Deliverable: a short spec fragment describing the command surface, defaults, and env-var contract.