Summary

Addresses Floom CLI developer-experience feedback (tickets 6b210a25, af6f3190), items 1-3 implemented, item 4 written up as a proposal below (not implemented — out of scope for this PR).

• [HIGH] Run-proxy docs/template gap: added a first-class composio-proxy golden template (floom workers templates get composio-proxy) with a working run.py that reads connections.json, POSTs to {WORKEROS_API_URL}/runs/{FLOOM_RUN_ID}/composio-execute/{slug} with the X-Floom-Run-Token header, and declares connections: [{app: gmail, allowed_tools: [...]}] in worker.yml. The pattern mirrors the real dogfooded workers/gmail_inbox_manager/run.py. floom workers contract (both --json and human-readable output) now documents the run-proxy contract: injected env vars, connections.json shape, request method/URL/header/body, and a pointer to the new template. Also exempted the three runner-injected env vars (WORKEROS_API_URL, FLOOM_RUN_ID, WORKEROS_RUN_TOKEN) from the "undeclared secret" validator, since worker authors never declare them.
• [HIGH] Scaffold vs validator disagreement: added 3 validated use_cases entries to all four golden templates (python-script, gmail-summary-agent, approval-script, composio-proxy) so floom init output is self-consistent with floom workers validate. Note: on current main (cb3a071f7), use_cases is optional both client-side (validateWorkerContractShape) and server-side (WorkerContract.validate_use_cases), so the literal "use_cases must contain 3 to 5 items" failure could not be reproduced from a fresh floom init today — templates without the field simply skip that check. This PR still adds use_cases to every template since (a) it matches the field already present in real production workers like gmail_inbox_manager, and (b) it is the explicit deliverable requested (3-5 placeholder use_cases, correct schema_version 0.3 exec block). Added a regression test (apps/mcp/test/init-validate-roundtrip.test.js) that round-trips every template through init -> workers validate and asserts zero errors, so any future drift between the two commands fails CI immediately.
• [MED] CLI cold-start: docs-only, no publish config changes. Added a callout in apps/mcp/README.md and the root README.md pointing agents/automation at npm i -g @floomhq/floom@latest instead of repeated npx -y @floomhq/floom@latest. Added a soft (non-blocking) floom doctor check that detects npx-cache invocation and hints at the global install.

Item 4 proposal (not implemented): short human-friendly IDs

Investigated feasibility of replacing raw UUIDs in worker/run URLs with short IDs.

What I found in apps/web/app:

• runs/[id], run/[id], and workers/[id] all resolve params.id directly against the UUID primary key — no short-ID layer today.
• No literal support/[id] route exists in this repo; support tickets, if UUID-exposing, likely live in a separate system outside floomhq/floom and are out of scope for this proposal.
• A human-friendly precedent already exists: apps/web/app/[handle]/[workerSlug]/page.tsx resolves public worker pages via @{workspace.handle}/{worker.public_slug} instead of a UUID, decoding params.handle/params.workerSlug and looking up the record by that composite key.

Proposed approach:

1. Add a short, sortable, collision-resistant display ID (e.g. base32/base62 Crockford-style, ~8 chars, similar to Stripe's run_xxxxxxxx or Linear's FLM-1042) as a generated, indexed, non-primary column on runs and workers at insert time. Keep the UUID as the real primary key and foreign-key target everywhere else — this avoids touching any existing FK relationships or the run-proxy contract (FLOOM_RUN_ID stays a UUID internally).
2. Add a lookup-by-either resolver in the [id] route handlers: try the short ID first (cheap indexed lookup), fall back to UUID for old/bookmarked links so nothing breaks.
3. Update outbound link generation (notifications, CLI workers get/runs get output, dashboard nav) to prefer the short ID once populated; UUID remains valid indefinitely for backward compatibility.
4. Backfill: generate short IDs for existing rows in a single migration; no user-facing downtime since UUID resolution keeps working throughout.

Sizing: touches apps/api (migration + resolver), apps/web (route handlers + link generation ~3-4 files), and apps/mcp (output formatting for workers get/runs get, optional). Estimate: medium — a few days, not a one-line change — so left as this written proposal rather than implemented here, per the task's guidance to write up large item-4 changes instead of shipping them.

Test plan

• npm run build (tsc) — clean, zero errors
• npm test — 171/171 passing (including new init-validate-roundtrip.test.js)
• Manual round-trip: all 4 templates (python-script, gmail-summary-agent, approval-script, composio-proxy) pass floom init --template <id> -> floom workers validate with valid: true, errors: []
• floom workers contract --json includes the new run_proxy key; human-readable output prints the new "Run-proxy (Composio/Gmail) contract" section
• floom workers templates get composio-proxy --json round-trips worker_yml + run_py

🤖 Generated with Claude Code