Narraitor: Skill for Claude Code

Diagnostics & tooling

1. Purpose

Every claim needs a measurement. This is the toolbox: the exact command per question, and what each diagnostic can and cannot conclude.

2. When to use

Producing evidence for any claim; investigating runtime state; verifying a fix live.

3. When not to use

• Choosing WHAT to verify → narraitor-validation-and-qa / narraitor-debugging-playbook; this skill is the HOW.

4. Inputs required

A running dev server on the correct port for YOUR checkout (lsof -nP -iTCP:3000 -sTCP:LISTEN — worktrees use derived ports).

5. Procedure — the toolbox

AI/API route smokes (curl):

# Route wiring, NO key needed — expect HTTP 400 {"error":"...prompt is required..."}:
curl -s -X POST localhost:3000/api/narrative/generate -H 'Content-Type: application/json' -d '{}' -w '\nHTTP %{http_code}\n'

# Live generation smoke (burns tokens; needs a key — GEMINI_API_KEY in .env.local for the
# server fallback, or pass the BYO header: -H 'x-provider-api-key: <key>'):
curl -s -X POST localhost:3000/api/narrative/generate -H 'Content-Type: application/json' \
  -d '{"prompt":"One sentence of neutral test narration."}' -w '\nHTTP %{http_code}\n'

# Provider key validity vs upstream outage discrimination.
# This route reads the candidate key ONLY from the x-provider-api-key header (no env
# fallback) and returns {"valid":false,"error":"NO_KEY"} immediately if it's absent —
# so you MUST pass the header, or you learn nothing but "the route is wired".
curl -s -X POST localhost:3000/api/ai/validate-provider \
  -H 'Content-Type: application/json' -H 'x-provider-api-key: <candidate-key>' \
  -d '{}' -w '\nHTTP %{http_code}\n'

Interpretation: on narrative/generate — 400 on empty body = route up, handler wired; 200 with generated text = full path live; 5xx/timeout on a valid body = key, upstream, or timeout (generate/choices: 30s server-side via makeGeminiRequest, no retries; the 120s figure is the CLIENT-side aiFetch ceiling and doesn't apply to direct curls). On validate-provider WITH a key header, the JSON error field splits the causes: INVALID_KEY = bad/rejected key, RATE_LIMITED = quota, NETWORK/VALIDATION_FAILED = upstream/other, valid:true = key good. A keyless call returns NO_KEY and proves only that the route responds. NOTE: the {prompt} 400-contract applies to narrative/generate and narrative/choices only; other routes have their own body shapes — read the handler before smoking them.