@kensaurus/skills 0.0.0-stage → 2.0.0

package/skills/plan-gtm/references/benchmarks-2026.md

@@ -0,0 +1,183 @@
+# GTM benchmarks and sources (verified 2026-09-17)
+
+Shared by `plan-gtm`, `plan-pricing`, `enhance-onboarding`,
+`enhance-web-conversion`, `enhance-lifecycle-email`, `enhance-growth-loops`,
+`docs-launch-kit`, `docs-comparison-pages`, `audit-registry-listing`,
+`iterate-gtm-weekly`. Quote a number only with its row here; if a row is
+missing, write **unmeasured** or **no benchmark** in the plan.
+
+## Free-to-paid by model
+
+ChartMogul × Growth Unhinged (Kyle Poyar) × ProductLed, ~200 self-serve
+products, Jan 2026. Conversion measured within 6 months of signup.
+
+| Model | Good (p50) | Great (p75) | Notes |
+|---|---|---|---|
+| Freemium (gated) | 3–5% | 8–12% | 26% of products lead with it |
+| Freemium, ungated (try before account) | 7–9% | 8–12% | 7% of products; adoption play |
+| Free trial, no card | 4–6% | 10–15% | 57% of products; 14-day modal (62%) |
+| Free trial, card required | 25–35% | 50–60% | 20% of trials; ~5× no-card; ~65% fewer signups |
+| Reverse trial | 4–6% | 8–12% | 7% of products; **not statistically distinct** |
+| Interactive demo (dummy data) | — | — | 7% of products |
+
+Median across all models **8%**; 20% of trial products convert under 2.5%,
+23% above 25%. Per 1,000 visitors: freemium ≈ 90 signups → 5 paid; no-card
+trial 45 → 4; card trial 35 → 11. One dual-CTA change (free plan *or*
+14-day card trial) lifted premium trial starts 26%. PQL-driven conversion
+runs ~3× the 9% average; only 24–34% of PLG companies track PQLs/activation.
+
+- https://www.growthunhinged.com/p/free-to-paid-conversion-report
+- https://chartmogul.com/reports/saas-conversion-report/
+- https://www.growthunhinged.com/p/how-to-improve-free-to-paid-conversion
+- https://productled.com/blog/product-led-growth-benchmarks
+- https://userpilot.com/blog/saas-average-conversion-rate/ (First Page Sage and
+  GrowthSpree report higher B2B bands: opt-in 14–18%, opt-out 44–49%)
+
+## Activation, time-to-value, retention
+
+| Metric | Number | Source |
+|---|---|---|
+| B2B SaaS activation, average / median | 37.5% / 37% (n=62) | Userpilot 2025 |
+| PLG vs sales-led activation | 34.6% vs 41.6% | Userpilot 2025 |
+| Activation by vertical | AI/ML 54.8% · dev tools ~40% · MarTech 24% · FinTech 5% | Userpilot 2025 |
+| Activation median, all products / SaaS | 25% / 30%; good = p60, great = p80 | Lenny × Timen, 500+ products |
+| Time-to-value, average / median | 1 d 12 h / 1 d 2 h; top quartile < 5 min | Userpilot 2025 |
+| TTV > 24 h | activation collapses below 25% | Userpilot analysis |
+| Day-1 activation, top products / median | 21% / 5% | Amplitude 2025 (2,600+ cos) |
+| Day-7 return of a new cohort | ≥ 7% = top quartile | Amplitude 2025 |
+| Month-3 loss of new users, median product | 96% | Amplitude 2025 |
+| Valid activation event | ≥ 2× retention for users who hit it | Lenny × Timen |
+| Onboarding checklist completion | 19–20% avg; engaged users finish ~5 items | Chameleon 2025 (550M interactions) |
+| Tour completion | click-triggered 67% vs timer 31%; 3–4 steps 72–74%, 7+ steps 16% | Chameleon 2025 |
+| Embedded guidance vs modal | +20% engagement | Chameleon 2025 |
+| Personalization | 65% collect signup data, 18% use it | Chameleon 2025 |
+
+- https://userpilot.com/saas-product-metrics/
+- https://www.lennysnewsletter.com/p/what-is-a-good-activation-rate
+- https://www.linkedin.com/posts/elenaverna_growth-data-activity-7377023750262644736-buVc
+- https://www.chameleon.io/benchmark-report
+- https://www.reforge.com/guides/analyze-activation (Setup → Aha → Habit)
+- https://posthog.com/product-engineers/activation-metrics (pick the event combo that best predicts 3-month retention)
+
+## Pricing and packaging
+
+- Hybrid (seat + usage) pricing 27% → 41% of B2B SaaS in 2025; seat-only
+  21% → 15%; 29% sell AI credits, 33% plan to. AI-native companies 4× more
+  likely to price on outcomes. — https://www.growthunhinged.com/p/2025-state-of-b2b-monetization
+- Annual discount norm 15–25%; state it as "2 months free", not "save 17%".
+  Hiding the enterprise price removes the anchor and hurts middle-tier
+  conversion — show "from $X". — https://productphilosophy.com/articles/pricing-page-conversion-architecture-twelve-elements
+- Three tiers good-better-best, recommended middle, higher tier on the right
+  as anchor, same CTA verb on every column, "No credit card required" under
+  the button when true. — https://kompassify.com/blog/pricing-page-best-practices
+- Underpricing attracts the curious, not the committed: one indie raise
+  £9 → £19 moved month-3 retention 42% → 67%. — https://www.indiehackers.com/post/i-underpriced-my-saas-for-4-months-and-it-almost-broke-me-not-the-way-you-think-a0ae21a1e6
+
+## Pricing research and value metric
+
+- Order of methods: Van Westendorp (acceptable range; directional) →
+  Gabor-Granger (revenue-maximizing point on one tier) → MaxDiff (rank
+  features for tier placement) → conjoint (price bundles). —
+  https://thesaaslibrary.com/pricing-research-methods-saas-founders/
+- Value metric = the unit the price attaches to; "subscription vs usage" is
+  a payment cadence question, not the metric. A good metric is understandable
+  by the buyer, estimable before signing, and diverges from cost. 41% of
+  software buyers cite unpredictable cost as the primary objection to
+  usage pricing (2025 survey). — https://softwarepricing.com/blog/value-metric-decision/
+- Score candidates on value connection, fairness/familiarity, predictability,
+  scalability, billability; simulate on historical accounts. —
+  https://www.pacepricing.com/blog/the-ultimate-guide-to-value-metrics-for-b2b-saas-pricing-monetization ·
+  https://enablism.com/resources/value-metrics-for-b2b-pricing/ ·
+  https://www.getmonetizely.com/articles/how-to-choose-the-right-saas-pricing-metric-with-value-metric-examples
+
+## Lifecycle email
+
+- Behavior-triggered sequences vs calendar drips: vendor-reported ~3–4× the
+  click-through and up to ~30% higher conversion (Userpilot, Customer.io,
+  Bessemer citations); no independent primary study — treat as direction. —
+  https://www.digitalapplied.com/blog/saas-customer-onboarding-email-sequence-2026-crm-playbook ·
+  https://ustechautomations.com/resources/blog/automate-saas-free-trial-onboarding-activation-2026
+- Timers are the fallback for users with no signal; exit the sequence the
+  moment the goal event fires; split expiry messaging by activated vs
+  stalled. — https://www.getfluxly.com/blog/lifecycle-email-automation-saas
+- 70–85% of trial-to-paid conversions happen in the second half of the
+  trial; sequences that stop on day 7 of 14 under-perform. Cadence:
+  activation push days 1–3, value reinforcement 4–10, conversion CTA 11–14. —
+  https://www.growthspreeofficial.com/blogs/b2b-saas-trial-to-paid-conversion-rate-benchmarks-2026-by-trial-type-acv-length-credit-card
+- Users without the core activation action inside 48 h carry the highest
+  churn probability — the day-2 nudge is the highest-leverage single email. —
+  https://ustechautomations.com/resources/blog/automate-saas-free-trial-onboarding-activation-2026
+
+## Open-source monetization
+
+- Managed cloud carries 48–73% of revenue at MongoDB, Confluent, Elastic; the
+  cloud line grows faster than the company. GitLab open-core: 23% growth,
+  117% NRR (Q1 FY27). Open-core self-host → paid conversion ~0.5–2%.
+- Relicensing (Elastic, Redis) cost contributors to permanent forks and
+  gained no visible revenue; both reversed. A license is a distribution
+  decision; monetization is who runs the software.
+- AGPL + commercial dual license is the proven open-core shape; some buyers
+  (Google) ban AGPL outright. BSL / FSL are source-available, not OSI.
+- https://www.saasmag.com/open-source-saas-monetization-license-product/
+- https://ossalt.com/guides/open-core-vs-source-available-business-models-2026
+- https://finitestate.io/blog/the-complete-guide-to-open-source-licenses
+- https://fsl.software/
+
+## Distribution
+
+| Channel | Number | Source |
+|---|---|---|
+| Show HN front page (dev tool) | 5–30k visits, 50–400 signups, < 5% conv; #1 ≈ 300k daily uniques | Causo Hub 2026 |
+| Show HN clearing 10 points | 62% (2022) → 11% (2025) | DoDataThings analysis |
+| Show HN timing | 12–17 UTC, Tue–Thu; ~+200 GitHub stars vs off-peak | DoDataThings analysis |
+| Product Hunt featured rate | 60–98% (2020–23) → ~10% | awesome-directories 2025; PH newsletter |
+| Product Hunt B2B visit→signup | 1–2% | Causo Hub 2026 |
+| Comparison pages in a pSEO test | 28% of pages → 78% of clicks, 6 of 7 leads | nicodigital, 162 pages |
+| llms.txt | Google: zero effect on Search / AI Overviews (2026-06-15); AI crawlers rarely fetch it; coding assistants do read it on docs sites | digitalapplied 2026 |
+| AI citations | third-party publishers earn 6.5× more citations than owned domains | geoaura 2026 |
+| SaaS referral rate / referred conversion | 4.75% avg / 7.86%, top quartile 12%+ | bloop.plus |
+| "Powered by" badge | 0.5–3% conversion, ~100% exposure; value-before-signup lifts referred conversion 2–5× | nativeviralloop |
+| Warm invites (user-sent, named recipient) | 10–25% accept → signup | nativeviralloop |
+
+- https://hub.causo.ai/guides/show-hn-launch-playbook-technical-founders-2026
+- https://hub.causo.ai/guides/product-hunt-vs-hacker-news-vs-betalist-2026
+- https://dodatathings.dev/blog/launch-platform-roi-the-math-nobody-shares
+- https://news.ycombinator.com/showhn.html (rules: runnable thing, no signup wall, no vote solicitation)
+- https://awesome-directories.com/blog/product-hunt-launch-guide-2025-algorithm-changes/
+- https://www.producthunt.com/newsletters/archive/33951-the-roundup-is-product-hunt-dead
+- https://www.nicodigital.com/technical-seo/programmatic-seo-experiment-162-pages/
+- https://developers.google.com/search/docs/essentials/spam-policies (scaled content abuse covers AI-generated pages)
+- https://www.digitalapplied.com/blog/google-llms-txt-no-seo-value-lighthouse-audit-2026
+- https://nativeviralloop.com/knowledge/viral-loop-metrics.html
+- https://www.reforge.com/blog/growth-loops
+
+## Positioning and messaging
+
+- Dunford order: competitive alternatives (incl. spreadsheets / do nothing)
+  → unique attributes → value themes with proof → who cares most → market
+  category → optional trend. — https://www.aprildunford.com/post/a-quickstart-guide-to-positioning
+- Five-second test with ICP respondents: what is it, for whom, what outcome;
+  "doppelganger" check with the logo removed. — https://www.electriccopy.tech/blog/how-to-test-messaging-on-a-budget
+- North-star: classify the game (attention / transaction / productivity),
+  define the value moment as a time-bound behavior, confirm it leads revenue
+  and retention, pick 3–5 inputs with owners. — https://amplitude.com/blog/product-north-star-metric
+- PQA (account fit + usage) says *when*; PQL (economic buyer present) says
+  *whom*. — https://www.elenaverna.com/p/elenas-2024-b2b-product-led-sales
+
+## Failure modes (why GTM plans die)
+
+CB Insights, 431 VC-backed shutdowns since 2023: 43% poor product-market fit,
+29% timing, 19% unit economics; 18% pricing, 14% marketing.
+
+1. Building before validating — no ICP interviews.
+2. Generic hero — fails the five-second test; written for investors.
+3. Underpricing "to reduce friction".
+4. No distribution hypothesis — "first-time founders focus on product, second-time on distribution".
+5. Activation untracked (~66%) or defined as payment.
+6. AI-generated content at scale — Google spam policy; HN removes AI-written posts.
+7. Launching once instead of per release.
+8. Reverse trial or AI credits as a fix — neither shows a conversion lift.
+
+- https://www.cbinsights.com/research/report/startup-failure-reasons-top/
+- https://github.com/dovzhikova/developer-tools-gtm-checklist
+- https://gtm-labs.co/open-source-go-to-market (README first 10 lines = hero)

package/skills/plan-input-validation/SKILL.md

@@ -0,0 +1,179 @@
+---
+name: plan-input-validation
+description: >
+  Plan-only trust-boundary audit for missing validation, injection, XSS, and
+  forged requests across forms, APIs, and webhooks. Use when "validate my
+  inputs", "is my app injection-safe?", "check my forms", or "can someone
+  forge requests?".
+license: MIT
+effort: high
+---
+
+# Input-Validation & Trust-Boundary Audit + Hardening Plan
+
+**Degree of freedom: HIGH** — map trust boundaries, score gaps, emit a plan.
+Stay **plan-only**. No Zod, sanitizers, or webhook edits until approved.
+
+## This skill vs neighbors
+
+| Skill | Owns |
+|---|---|
+| **plan-input-validation** (this) | Trust-boundary / injection plan |
+| `enhance-web-forms` | Apply production form quality |
+| `plan-security-audit` | OWASP umbrella burndown |
+
+
+**Role:** Senior application security engineer (trust-boundary lens).
+
+**Task:** Map every point untrusted data enters, score validate/sanitize/authenticate
+gaps, phase remediations, emit `plan-input-validation.md`. **Audit & plan only — no
+code changes until each phase is approved.**
+
+**Walk every boundary. Find what's trusted that shouldn't be. Change nothing until approved.**
+
+## How to reason (every plan item)
+
+1. **Propose** — schema, sanitize, signature verify, or allowlist
+2. **Risk** — forgeable money/data, stored XSS, or injection
+3. **Keep-working** — boundaries that already validate + authenticate
+4. **Phase** — Forgeable paths → XSS → Schema pass → Uploads (do not execute)
+
+## Worked example
+
+> **Propose:** verify the Stripe webhook with `constructEvent` on the raw body; reject empty secrets; return 400 on bad signatures.
+> **Risk:** empty-signing-secret bypass — anyone can forge `invoice.paid` and credit quota.
+> **Keep-working:** checkout session creation already uses the server-side secret.
+> **Phase:** Phase 1 — Forgeable money/data paths.
+> **Note:** origin proof ≠ safe to interpolate into SQL/HTML.
+
+AI agents write code that works on the inputs you showed them. Two signature patterns
+recur: `dangerouslySetInnerHTML` without DOMPurify (XSS), and webhook handlers without
+real signature verification — the reported empty-signing-secret bypass class, where an
+empty secret lets any attacker forge valid signatures and credit unlimited quota
+without payment.
+
+This skill is the **audit-and-plan** half. Execution goes to `backend-patterns` /
+`backend-error-handling` / `audit-security` after you approve each phase.
+
+---
+
+## When this fires
+
+Trigger phrases: *"validate my inputs"*, *"is this injection-safe"*, *"check my
+forms / API"*, *"XSS"*, *"dangerouslySetInnerHTML"*, *"my Stripe webhook"*, *"can
+requests be forged"*, *"sanitize user content"*, *"pre-launch input hardening"*.
+
+Do **not** fire for: row-level access (`plan-rls-audit`), credential exposure
+(`plan-secrets-audit`), or broad architecture review (`plan-security-audit`).
+This skill owns the *boundary where untrusted data enters*.
+
+---
+
+## The four boundary classes  [HIGH freedom]
+
+### 1 · Form & API input
+- **No schema validation** — bodies/params/query without Zod (or equivalent).
+- **Type-coerced trust** — `Number(req.body.amount)` with no bounds.
+- **Missing field-level checks** — email format, length caps, enum membership.
+- **Mass assignment** — spreading `req.body` into DB insert/update (`role`,
+  `is_admin`, `credits`).
+- **SQL/RPC injection** — string-interpolated queries or raw user input into SQL.
+
+### 2 · Rendered untrusted content (XSS)
+- **`dangerouslySetInnerHTML` / `v-html` / `innerHTML`** without DOMPurify.
+- **URL/attribute injection** — `javascript:` URIs, unvalidated redirects.
+- **Stored XSS** — content saved now, rendered raw later.
+
+### 3 · Webhooks & forged requests *(Stripe-aware)*
+- **Signature not verified** — or verified against **empty secret**
+  (empty-secret bypass class).
+- **Raw-body mistake** — `JSON.stringify(req.body)` instead of raw bytes.
+- **No idempotency** — Stripe at-least-once retries double-process.
+- **Cross-gateway trust** — fulfilling without checking callback source.
+- **Missing timestamp tolerance** — replay window open.
+- **Returns 500 not 400** on bad signature → infinite Stripe retries.
+
+### 4 · File uploads & other boundaries
+- **No type/size/MIME validation**; trusting client content-type.
+- **Path traversal** in filenames; **SSRF** in user-supplied URLs.
+- **Concurrency** — read-modify-write races without DB constraints.
+
+---
+
+## Procedure  [HIGH freedom — plan only]
+
+1. **Map boundaries.** Enumerate every untrusted entry point. Skip absent ones.
+2. **Test each.** For every boundary: validated? sanitized? authenticated?
+3. **Score.** Severity = reachability × impact.
+4. **Phase** into shippable groups mapped to execution skills.
+5. **Emit `plan-input-validation.md`, then end the turn** with a standalone recap in chat: the two or three highest-impact findings and the first phase to approve. The file is the deliverable — write it before the recap. **Do not edit code.**
+
+---
+
+## Guardrails
+
+- **Plan only.** No Zod schemas, sanitizers, or webhook config changes.
+- **Validate at the boundary, not after.**
+- **Signature ≠ safety.** Origin proof ≠ safe to interpolate into SQL/HTML.
+- **Don't trust the client copy.** Browser-only checks are UX, not security.
+- **Stack-specific raw-body note.** Call out Next.js + Stripe raw-body requirement.
+- **Minimal quoting** of source.
+
+## Self-critique before the burndown  [LOW freedom — do not skip]
+
+1. **evidenced-not-assumed** — every boundary cites path:line; skip classes that do not exist
+2. **plan-only** — no Zod schemas, DOMPurify, or webhook config
+3. **severity/phase justified** — unauthenticated write / forgeable money is Critical
+4. **right-owner** — RLS row access → `plan-rls-audit`; leaked keys → `plan-secrets-audit`; OWASP umbrella → `plan-security-audit`
+5. **no-false-safety** — browser-only checks are UX; signature ≠ sanitization; empty webhook secret is a bypass
+
+---
+
+## Report template — `plan-input-validation.md`
+
+```markdown
+# Input-Validation & Trust-Boundary Audit — <repo>
+
+_Audit-only. Nothing changes until each phase is approved._
+
+## Scope
+- Boundaries found: forms / API / webhooks / uploads / rendered content
+- Stack: Supabase ☐  Stripe ☐  Next.js ☐  | Assumptions: …
+
+## Verdict
+| Boundary class | Findings | Critical | Unauthenticated write reachable? |
+|----------------|----------|----------|----------------------------------|
+| Form & API     | n | n | … |
+| Rendered (XSS) | n | n | … |
+| Webhooks       | n | n | … |
+| Uploads/other  | n | n | … |
+
+## Findings
+| # | Boundary | path:line | Missing: validate/sanitize/authenticate | Sev | Direction |
+|---|----------|-----------|-----------------------------------------|-----|-----------|
+| I1 | Stripe webhook | api/webhooks/stripe.ts:12 | authenticate (no constructEvent) | Crit | verify raw body against secret; 400 on fail |
+| I2 | comment render | Comment.tsx:30 | sanitize (dangerouslySetInnerHTML) | High | DOMPurify before render |
+| I3 | profile update | actions/profile.ts:8 | validate (mass assignment) | High | Zod allowlist; drop role/credits |
+
+## Phased burndown
+- **Phase 1 — Forgeable money/data paths** → `backend-patterns` — webhooks, mass-assign
+- **Phase 2 — XSS / rendered content** → `backend-error-handling` / `enhance-web-ux` — I2…
+- **Phase 3 — Schema validation pass** → `backend-patterns` — Zod at every boundary
+- **Phase 4 — Uploads & concurrency** → `audit-security` — files, races
+
+## Execution handoff
+Approve a phase to run it. Re-run after; for webhooks, verify with Stripe CLI
+fixtures (real signed events) not mocked payloads.
+```
+
+---
+
+## Chains with
+
+- **Security spine** — entry layer (**this skill**); data access: `plan-rls-audit`;
+  credentials: `plan-secrets-audit`.
+- **Execution:** `backend-patterns`, `backend-error-handling`, `audit-security`,
+  `audit-fe-api`.
+- **Verify:** `test-red-team` + Stripe CLI signed webhook fixtures.
+
+> Planned at high effort; executed at the default effort under the approved-plan execution rule (`approved-plan-execution.mdc`), which forbids reward hacking and feature deletion on any model. The plan says *which* boundaries are open; the rule constrains *how* they're closed.

package/skills/plan-llm-cost-guardrails/SKILL.md

@@ -0,0 +1,176 @@
+---
+name: plan-llm-cost-guardrails
+description: >
+  Plan-only audit of an LLM app's runaway-cost and quota-abuse exposure. Use
+  when "cap my AI costs", "my LLM bill could blow up", "rate limit my AI",
+  "token budget", "runaway agent loop", or hardening LLM features before
+  launch.
+license: MIT
+effort: high
+---
+
+# LLM Cost-Guardrail Audit + Remediation Plan
+
+**Degree of freedom: HIGH** — inventory call sites, score unbounded
+paths, plan. Stay **plan-only**. No limits or routing changes until approved.
+
+## This skill vs neighbors
+
+| Skill | Owns |
+|---|---|
+| **plan-llm-cost-guardrails** (this) | Token / quota / runaway-loop plan |
+| `audit-langfuse-llm` | Quality and cost traces |
+| `audit-infra-cost` | Hosting / egress bill |
+| `audit-llm-security` | Unbounded consumption as an attack |
+
+## How to reason (every plan item)
+
+1. **Propose** — token cap, kill switch, breaker, or fallback
+2. **Risk** — worst-case spend × who can reach the path
+3. **Keep-working** — call sites that already bound tokens and account usage
+4. **Phase** — caps → breakers → fallback → visibility (do not execute)
+
+## Worked example
+
+> **Propose:** per-user daily token cap + hard daily-spend kill switch on `lib/ai.ts`.
+> **Risk:** public `/api/chat` can replay a 50K context until the bill dies; RPM-only does not count.
+> **Keep-working:** summarizer path already sets `max_tokens`.
+> **Phase:** Phase 1 — caps & kill switch.
+
+**Role:** Senior platform engineer (LLM spend + abuse resistance).
+
+**Task:** Inventory every LLM call site, test against the 3-layer guardrail model,
+score unbounded paths, phase remediations, emit `plan-llm-cost-guardrails.md`.
+**Audit & plan only — no limits or routing changes until approved.**
+
+**Find every path to a runaway bill. Cap it. Change nothing until approved.**
+
+Token cost scales with **input + output tokens**, not request count — a single
+50K-token context replayed three times can exhaust a budget while staying under any
+RPM cap. Vibe-coded AI features ship with no spend cap, no per-user quota, no
+output-token cap, no circuit breaker — compounded by prompt-injection cost amplification
+and forged-webhook quota fraud (the empty-signing-secret bypass class).
+
+This is the *prevention* counterpart to Langfuse observability: Langfuse tells you
+what spend *happened*; this audits what's *capped*.
+
+---
+
+## When this fires
+
+Trigger phrases: *"cap my AI costs"*, *"my LLM bill could explode"*, *"rate limit
+my AI"*, *"token budget"*, *"someone could drain my quota"*, *"runaway agent
+loop"*, *"per-user AI limits"*, *"pre-launch cost hardening"*.
+
+Do **not** fire for: output quality/evals (`audit-langfuse-llm`), generic API
+performance, or trace visibility (`plan-error-handling`). This owns *bounded spend*.
+
+---
+
+## The audit — 3-layer guardrail model  [HIGH freedom]
+
+### Layer 1 · Limits (token-aware, not request-count)
+- **Token-bucket / quota per (user, model)** — any per-identity limit?
+- **Token-based, not just RPM** — prompt-TPM and output-TPM ceilings.
+- **Output-token / context caps** — `max_tokens` (Anthropic),
+  `max_completion_tokens` or `max_output_tokens` (OpenAI); bound worst-case
+  cost; truncate RAG context.
+- **Short + long windows** — per-minute burst *and* per-day/month budget.
+- **Tiered limits** — free vs paid wired to Stripe entitlement.
+
+### Layer 2 · Circuit breakers
+- **Cost-velocity breaker** — spend/min threshold.
+- **Loop / repeat detection** — retry-storms, growing-context loops.
+- **Daily-spend kill switch** — hard cap backstop.
+- **Error-rate breaker** — mostly-failing caller identity.
+
+### Layer 3 · Fallback chain
+- **Primary → cheaper model → cache → graceful 503.**
+- **Semantic cache** before paid calls.
+- **Model routing by complexity** — flag patterns that send every call to the most
+  expensive model tier.
+
+### Cross-cutting
+- **Streaming usage accounting** — read usage from the stream or spend is
+  invisible: OpenAI Chat Completions sends it only with
+  `stream_options.include_usage`; Anthropic sends it in `message_start` and
+  cumulative `message_delta` events.
+- **Retry discipline** — token-aware backoff.
+- **Abuse vectors** — unauthenticated AI endpoints; hand boundary fixes to
+  `plan-input-validation`.
+- **Langfuse cost alerts** — 50/75/90% thresholds; per-user attribution.
+
+---
+
+## Procedure  [HIGH freedom]
+
+1. **Inventory LLM call sites** and public AI endpoints.
+2. **Test each against Layers 1–3.**
+3. **Score** = worst-case spend × reachability.
+4. **Phase** — Layer 1 caps and daily kill switch first.
+5. **Emit `plan-llm-cost-guardrails.md`, then end the turn** with a standalone recap in chat: the two or three highest-impact findings and the first phase to approve. The file is the deliverable — write it before the recap.
+
+---
+
+## Guardrails  [LOW freedom — run exactly]
+
+- **Plan only.** No limits, gateway config, or routing changes.
+- **Spend cap is non-negotiable for launch** — flag absence as at least High.
+- **Token-aware or it doesn't count** — don't credit RPM-only limits.
+- **Bounded blast radius**, not zero runaways.
+- **Cross-hand abuse** to `plan-input-validation`.
+
+## Self-critique before the burndown  [LOW freedom — do not skip]
+
+1. **evidenced-not-assumed** — each unbounded path names a call site, not "we should cap AI"
+2. **plan-only** — no limits, gateway, or routing edits this pass
+3. **phase justified** — Layer 1 caps + daily kill switch before fallback polish
+4. **right-owner** — quality/evals → `audit-langfuse-llm`; unauth AI input → `plan-input-validation`
+5. **no-false-safety** — RPM-only is not a token cap; missing spend cap is at least High
+
+---
+
+## Report template — `plan-llm-cost-guardrails.md`
+
+```markdown
+# LLM Cost-Guardrail Audit — <repo>
+
+_Audit-only. No limits or routing change until each phase is approved._
+
+## Scope
+- LLM call sites: n  | Public AI endpoints: n  | Langfuse present: ☐
+
+## Verdict
+| Layer | Present? | Worst gap |
+|-------|----------|-----------|
+| 1 Limits (token-aware) | partial | unbounded max_tokens |
+| 2 Circuit breakers     | ❌ | no daily kill switch |
+| 3 Fallback chain       | ❌ | limit = hard error |
+
+## Findings
+| # | Call site | Unbounded path | Worst-case | Missing layer | Sev | Direction |
+|---|-----------|----------------|------------|---------------|-----|-----------|
+
+## Phased burndown
+- **Phase 1 — Caps & kill switch** → `backend-patterns`
+- **Phase 2 — Circuit breakers** → `backend-patterns`
+- **Phase 3 — Fallback chain** → `backend-patterns`
+- **Phase 4 — Visibility** → `audit-langfuse-llm` / `backend-observability`
+- **Cross-hand** → `plan-input-validation`
+
+## Execution handoff
+Simulate a runaway in test env after Phase 1; confirm cap holds before bill moves.
+```
+
+---
+
+## Chains with
+
+- **Observability & spend loop** — pairs with `plan-error-handling` (visibility) and
+  `audit-langfuse-llm` (quality); this owns *bounded spend*.
+- **`audit-llm-security`** — LLM10 unbounded consumption is the attack-shaped twin.
+- **`audit-infra-cost`** — hosting/egress, not tokens.
+- **Execution:** `backend-patterns`, `audit-langfuse-llm`, `backend-observability`.
+- **Verify:** sandbox load/abuse test — caps, breakers, fallback trip before spend escapes.
+
+> Planned at high effort; executed at the default effort under the approved-plan execution rule (`approved-plan-execution.mdc`), which forbids reward hacking and feature deletion on any model.