docs(design): propose free trial credits at signup

[mmabrouk]

Problem

A new signup lands in the playground, describes their agent, commits it, and then hits a wall: the composer disables and a banner demands an LLM provider API key before their first message sends. The user does the work and gets none of the payoff.

What this PR contains

A full design workspace under docs/design/activation-credits/, in reading order:

• context.md — the situation today, goals, constraints, and a glossary defining every term.
• rfc.md — the decisions requested (D1-D8), including a smallest safe version that strips the hardening items, so scope can be cut deliberately.
• design.md — the full architecture: signup grant record, reservation with atomic charge, server-side funding provenance, and a small in-house inference gateway (the platform key never enters the user-controlled sandbox), composed with the Daytona secret-delivery work (docs(agent-workflows): Plan Daytona secret delivery #5223/[feat] Deliver agent credentials through Daytona Secrets #5277/[docs] Plan durable managed-resource reconciliation #5278).
• research.md — the evidence: current key-gate mechanics, PR [chore] Limit usage of agenta provided keys via credits #2957 prior art, the entitlements engine, measured activation token costs from production traces (~23.6K tokens of harness context per LLM call), model pricing and abuse math, anonymized competitor free-tier patterns, the Daytona-secrets possession-vs-usage analysis, and the gateway build-vs-adopt survey.
• implicit-decisions.md — a register of every requirement that entered the design beyond the original ask (own inference, review-forced, or codebase constraint), each with the cost of striking it. Read this to cut scope.

Review

Mahmoud is the reviewer. An external model review loop was used as a helper during drafting; its accreted requirements are itemized in implicit-decisions.md rather than baked in silently. Do not merge; that call is Mahmoud's.

https://claude.ai/code/session_013PybmGbRaSiFzFtzhCrESm

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
agenta-documentation	Ready	Preview, Comment	Jul 23, 2026 2:30pm

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 8b867cfd-cd9e-4ea3-a1a4-a7030ec4ad3c

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/activation-credits-proposal

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}