feat(onboarding): per-runtime setup prompts, generated from the ingest constants

[vivekchand]

Problem

ClawMetry's users delegate work to coding agents by definition — that is what the product observes. Yet the only setup paths we ship are "run the installer" and "read a doc". There is no artefact aimed at the thing the user actually drives.

Bronto ships a copy-paste prompt per scenario and it is the strongest door on their onboarding screen. Instructive detail: half of their prompt is negative space — "do not use /v1/logs, that path rejects direct JSON with 400 Invalid content provided", "use text/plain;charset=UTF-8, not application/json", "headers all lowercase". They wrote down the mistakes agents actually make, which is what makes the prompt work on the first attempt instead of the fourth.

Their own OpenClaw page then spends a boxed warning on the failure mode: coding agents "mis-substitute secrets (drop characters from the API key, wrap it in extra quotes, or leave the literal placeholder <YOUR_API_KEY> in place)" and "hallucinate config keys, env-var names, CLI flags, or endpoint paths that look plausible but don't exist". A prompt that anticipates those is worth more than one that doesn't.

Scope

1. A generator, not a folder of markdown. Render each prompt from the same constants the server validates against — header names, accepted content types, size caps, the runtime list from entitlements.ALL_RUNTIMES, the endpoint from clawmetry/endpoints.py. A hand-written prompt drifts the first time a header is renamed, and a drifted setup prompt is worse than none: it teaches the agent a wrong answer confidently.
2. Serve it at GET /api/setup-prompt?runtime=<r>&target=<local|cloud>, rendered into the onboarding "Ask your agent" door with a copy button, and printed by clawmetry setup-prompt <runtime>.
3. Write the negative space in. Each prompt states explicitly: the key goes in x-clawmetry-key and nowhere else (not a query param, not Authorization: Bearer); the placeholder must be replaced verbatim; protobuf and json are both accepted so don't "fix" the content type; do not invent config keys — if a key isn't in this prompt it doesn't exist.
4. A verification step inside the prompt. End every prompt with "then confirm: curl <endpoint>/api/onboarding/ingest-status, and report the event count back to the user." An agent that can check its own work fails loudly instead of silently.

Non-goals

Not a general "configure ClawMetry with AI" feature. These are narrow, single-purpose, verifiable prompts for one task: get telemetry flowing.

Acceptance

• Pasting the prompt into Claude Code, Cursor and Codex each produce a working push on the first attempt, tested against a real key — not reviewed by eye.
• Renaming an ingest header in the source breaks a test rather than silently shipping a wrong prompt.
• Every prompt ends with the agent reporting a real event count back.

Depends on the ingest-key issue (the prompt needs a key to reference).

Part of the ingest-gap plan (phase 1, item 4 of 5).

[vivekchand]

Phase 1 issue map — "open the front door"

The gap this closes: an agent is observable only if the daemon runs on the same machine as the agent. These eight issues, in dependency order:

#	Repo	Issue
1	clawmetry	#5679 — scoped ingest key authenticates /v1/* and /api/v1/*
2	clawmetry-cloud	#2344 — name the two trust classes (gates #2343)
3	clawmetry-cloud	#2343 — hosted ingest key + OTLP endpoint
4	clawmetry-pro	#230 — pushed telemetry becomes real sessions; honest control verdicts
5	clawmetry	#5682 — generated docs/INGEST.md + drift test
6	clawmetry	#5681 — per-runtime setup prompts
7	clawmetry	#5680 — "Send your data" onboarding step + live status strip
8	clawmetry-landing	#754 — public endpoint reference; reconcile reach + storage claims

Upstream dependency: clawmetry PR #5676 ships clawmetry/apikeys.py (cmk_ scoped keys, clawmetry key CLI). #5679 extends it with a write scope rather than starting a second key system.

Ordering that matters: #2344 lands before #2343 (a plaintext trust class named before it exists, not after it becomes a P0), and #5682 lands before #754 (the landing page is written from the generated doc, because drift-bot greps repo docs and fails claims the repo denies).

Deliberately out of scope for phase 1 — and mostly out of scope permanently: the 33 AWS / 11 Azure / 17 infra integration pages, generic log parsing (syslog/CEF/GELF), an LLM-authored parser, a search language and dashboard builder, and being a destination for Fluent Bit / Vector / Logstash / the Datadog Agent. Those make ClawMetry a worse log platform and a less distinctive agent platform.

[vivekchand]

Hi @vivekchand! Took a careful look at this one. Here's the plan:

The problem
A first-time user who wants to wire an off-machine agent into ClawMetry has no copy-paste artefact they can hand to that agent — only docs that drift and a silent failure when the agent guesses a wrong header or key placement.

Approach

1. clawmetry/setup_prompt.py — the generator (new module, ~100 lines)
   Pull all ingest constants from one place so the prompt can never drift independently:

   • Header names from clawmetry/sync.py (or the future apikeys.py once feat: build your own UI, a keyed and scoped read API over the q/1 contract #5676 lands) — x-clawmetry-key, x-clawmetry-runtime, x-clawmetry-env
   • Accepted content-types (application/x-protobuf, application/json)
   • Size caps and endpoint paths from clawmetry/endpoints.py (DEFAULT_INGEST_URL) and the OTLP routes in routes/meta.py
   • Runtime names from clawmetry.entitlements.ALL_RUNTIMES (currently 30 entries)
   • Verification curl from GET /api/onboarding/ingest-status (from feat(onboarding): a "Send your data" step with a live ingest status strip #5680)
     Export a single function: render_setup_prompt(runtime: str, target: Literal["local", "cloud"]) -> str.
     Negative-space clauses are baked into the template strings — not parameterised, so they survive a copy-paste audit.

2. routes/onboarding.py:bp_onboarding — new route (~25 lines)

   GET /api/setup-prompt?runtime=<r>&target=<local|cloud>
   

   Validates runtime against ALL_RUNTIMES, returns {"prompt": "...", "runtime": r, "target": t}.
   The cloud target requires a key value; if no x-clawmetry-key header is present it returns {"prompt": "...", "key_required": true} so the UI can prompt for it before rendering.

3. clawmetry/cli.py — setup-prompt subcommand (~30 lines, after feat: build your own UI, a keyed and scoped read API over the q/1 contract #5676 ships apikeys.py)
   Uses argparse (the existing CLI pattern — no click dependency) to add:

   clawmetry setup-prompt <runtime> [--target local|cloud] [--key <key>]
   

   Prints the rendered prompt to stdout and optionally copies to clipboard.

4. Frontend wire-up (clawmetry/static/js/app.js + relevant onboarding tab template)
   Add an "Ask your agent" door to the onboarding screen that calls /api/setup-prompt, renders the prompt in a <pre> block with a copy button. The local variant renders immediately; the cloud variant shows a key-input field first.

5. Tests — tests/test_setup_prompt.py (new file, ~60 lines)

   • test_header_rename_breaks_prompt: monkeypatch the header constant and assert the rendered prompt no longer contains the old name → red-before-green coupling
   • test_local_prompt_has_verification_step: assert every rendered prompt ends with the curl /api/onboarding/ingest-status verification line
   • test_unknown_runtime_raises: assert render_setup_prompt("notaruntime", "local") raises ValueError
   • test_route_200_known_runtime / test_route_400_unknown_runtime: Flask test client against the route

Why this is PLAN_ONLY right now

The issue has three explicit dependencies that need to land first:

• feat: build your own UI, a keyed and scoped read API over the q/1 contract #5676 (clawmetry/apikeys.py + clawmetry key CLI) — the key the cloud prompt references doesn't exist as a first-class object yet
• feat(ingest): let a scoped ingest key authenticate /v1/* and /api/v1/*, so an agent off-box can be observed #5679 (scoped write:ingest key) — the x-clawmetry-key header this prompt teaches an agent to use
• docs(ingest): generate docs/INGEST.md from one ingest contract, with a drift test #5682 (generated docs/INGEST.md) — the prompt's negative-space clauses should be validated against the same constants the doc is generated from, so the coupling test is meaningful

The local-target variant could ship earlier (it needs no key), but splitting delivery here risks teaching an agent a partial API it then mis-applies once the key lands.

Estimated change
~215 lines across 4 files (clawmetry/setup_prompt.py, routes/onboarding.py, clawmetry/cli.py, tests/test_setup_prompt.py), plus a small frontend addition in clawmetry/static/js/app.js.

This one's bigger than I'm comfortable autonomously shipping because it touches the CLI entry point, requires live-key acceptance testing across three IDEs, and the key infrastructure it references isn't in main yet. Leaving the plan here for your review — if you want me to proceed on the dependency-free local-only variant once #5682 lands, comment bot-go and I'll pick it up next run.

---

Generated by Claude Code

[vivekchand]

Checked origin/main (4c192fe6, fetched 2026-09-12): no clawmetry/setup_prompt.py, no routes/onboarding.py-based /api/setup-prompt route, no clawmetry setup-prompt subcommand anywhere on main yet.

This is fully covered by open PR #5684 (feat/ingest-key, stacked on open PR #5676 feat/build-your-own-ui), which explicitly says "Closes #5679, #5682, #5681, #5680" and ships exactly this ask as its commit 3 ("The setup prompt (#5681)"):

• clawmetry setup-prompt <runtime> CLI subcommand and GET /api/setup-prompt, rendered from the same ingest_contract.py constants the server validates against (not hand-written markdown).
• The negative-space clauses this issue asked for (key goes in one header only; placeholder must be replaced; both content-type encodings accepted; undeclared keys don't exist).
• A guard that reads backwards — every x-clawmetry-* token in the rendered prompt must be a declared header — plus the CLI-subcommand-allowlist guard, both described as mutation-tested in the PR body.
• tests/test_setup_prompt.py (17 guards per the PR body), registered in ci.yml.

Not merged as of this check (PR is on branch feat/ingest-key, base feat/build-your-own-ui, mergeable_state: unknown, not merged). Per the task guidance I'm not merging or closing this — leaving it open until #5676 and #5684 land. A human should merge #5676 first, then #5684, at which point this issue can close.

---

Generated by Claude Code