docs(faq): real numbers in the cost Q&A

[FiscalMindset]

Upgrades the existing 'Is there a cost?' FAQ entry to answer 'isn't hitting an enclave every time expensive?' honestly: measured ~20 tokens/op, ~1,000 free uses on testnet, frequency×value framing, and release-once-reuse. Links to the README Cost section.

Co-authored-by: algsoch algsoch@gmail.com

---

Summary by cubic

Updates the “Is there a cost?” FAQ with real numbers and clear guidance, directly answering “Isn’t hitting an enclave every time expensive?”.

Specifies ~20 tokens per operation, the ~20k-token signup grant (~1,000 free testnet uses), the frequency × value framing, when to use release() for reuse (one op for N calls), how to check balance with blindfold credit and blindfold doctor, and links to the README Cost section.

^{Written for commit 588a758. Summary will update on new commits.}

[qodo-code-review]

PR Summary by Qodo

docs(faq): quantify enclave op costs and explain release-once-reuse

📝 Documentation 🕐 10-20 Minutes

AI Description

• Expand the FAQ cost answer with measured per-op token usage and testnet free-use estimate.
• Add guidance for evaluating cost via frequency × value, with security tradeoff framing.
• Document cost levers (release-once-reuse, selective sealing, proxy usage) and link README Cost.

Diagram

graph TD
  A["FAQ.md"] --> B["Cost Q&A"] --> C["Guidance"] --> D["README.md#Cost"]
  B --> E["Blindfold CLI"] --> F["T3 enclave credits"]
  C --> G["release()-cache pattern"]

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Add a small cost table or examples

• ➕ Makes the ~20 tokens/op claim easier to contextualize (e.g., ops/day → tokens/month).
• ➕ Reduces ambiguity around what counts as an 'operation' (use vs proxy forward).
• ➖ More likely to go stale if pricing/metering semantics evolve.
• ➖ Adds more maintenance burden to FAQ vs keeping detail centralized in README.

2. Introduce a CLI estimator command (e.g., `blindfold cost estimate`)

• ➕ Provides personalized cost projections without users doing mental math.
• ➕ Keeps docs shorter while still being actionable.
• ➖ Requires product/code work and ongoing correctness across networks/pricing tiers.
• ➖ Overkill for a docs-only improvement focused on answering a common objection.

Recommendation: The PR’s approach (give a measured per-op number, provide a free-use testnet anchor, and explain frequency×value plus release-once-reuse) is the right docs-first answer. If reviewers want one enhancement, consider adding a minimal 1–2 line example (e.g., "100 uses/day ≈ 2,000 tokens/day") while keeping the full, changeable breakdown in README.md#Cost.

Files changed (1) +4 / -2

Documentation (1) +4 / -2

FAQ.mdRewrite cost FAQ with measured tokens/op and mitigation strategies +4/-2

Rewrite cost FAQ with measured tokens/op and mitigation strategies

• Expands the cost FAQ to address per-enclave-use metering, including a measured ~20 tokens/op figure and a testnet free-uses estimate. Adds framing (frequency × value) and practical levers (release-once-reuse, selective sealing, proxy usage), plus a link to the README Cost section and relevant CLI commands.

FAQ.md

[gitar-bot]

Important

You are using the Gitar free plan. Upgrade to unlock code review, CI analysis, auto-apply, custom automations, and more.

_Gitar

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (2) 📘 Rule violations (0) 📜 Skill insights (0)

Context used

✅ Compliance rules (platform): 5 rules

✅ Skills: blindfold

1. Plaintext caching risk 🐞 Bug ⛨ Security

Description

FAQ.md recommends caching plaintext returned by release() (“release-once-reuse”) to reduce
per-call enclave ops, but it omits the explicit security trade-off that the secret now resides
in-process for that cache window. Readers may over-cache and unintentionally weaken the “agent never
had the key” posture.

Code

FAQ.md[220]

+Whether that's "expensive" is **frequency × value**: for the high-value keys Blindfold is built for (deploy tokens, payment/admin creds, keys you hand to autonomous agents), ~20 tokens per use is a rounding error next to a breach. For a low-value key hit thousands of times a second, use **release-once-reuse** — `release()` hands the plaintext to your process, so you cache it for a burst and pay **one op for N calls** instead of N ops. Also: **seal selectively** (only what would hurt if leaked) and use the **proxy where the guarantee is worth it**. See the [Cost section in the README](README.md#cost) for the full breakdown.

Evidence

The FAQ now encourages caching plaintext from release() without the explicit trade-off warning
that exists in both the README cost section and the release() implementation comments, increasing
the risk that readers follow the optimization without understanding the security implications.

FAQ.md[217-220]
README.md[490-518]
packages/blindfold/src/release.ts[1-15]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
The FAQ’s “release-once-reuse” guidance encourages caching plaintext returned by `release()` but doesn’t explicitly warn that this increases plaintext residency in the application process, which is a deliberate security trade-off.

### Issue Context
The project already documents this trade-off elsewhere (README cost section + `release()` source-level security note), but the new FAQ text currently reads as purely a cost optimization.

### Fix Focus Areas
- FAQ.md[217-220]

### Suggested change
Add a short parenthetical immediately after the “release-once-reuse” sentence, e.g.:
- note that caching keeps the secret in your process memory for that window,
- recommend keeping the cache scope/lifetime minimal,
- remind not to log/persist the plaintext,
- optionally link to README Cost section for the trade-off wording.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. Tokens/credits ambiguity 🐞 Bug ⚙ Maintainability

Description

FAQ.md describes cost in “tokens” but also uses “out-of-credit” wording, while other docs and the
CLI use both “tokens” and “credits” without clearly stating they’re the same balance/unit. This
inconsistency can confuse users about what blindfold credit reports and what resource they need to
top up.

Code

FAQ.md[218]

+Fair question. Every *use* of a key is a metered Terminal 3 enclave op — unlike reading a plaintext env var (free but leakable). But it's small: measured live, **~20 tokens per operation** (a `use`/release or a proxy forward). The self-serve `signup` grant (~20,000 tokens) is **~1,000 uses**, free, on testnet. `blindfold credit` shows your balance; `blindfold doctor` flags an out-of-credit tenant explicitly.

Evidence

Repo docs and CLI output show both terms in the same user journeys: README installation text says
“credits,” README cost section says “tokens,” and the blindfold credit command prints “tokens”
while describing “credit/credits,” so the FAQ’s mixed wording can be ambiguous without an explicit
equivalence statement.

FAQ.md[217-218]
README.md[133-143]
README.md[490-499]
usage.md[67-68]
packages/blindfold/bin/cmd-enclave.ts[23-48]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
Terminology around metered units fluctuates between “tokens” and “credits” in user-facing docs and CLI output. The updated FAQ leans on “tokens” while still saying “out-of-credit,” which can read like two separate things.

### Issue Context
- README uses both terms in different sections.
- The CLI `blindfold credit` output shows “tokens” while the UI/title/top-up text says “credit/credits.”

### Fix Focus Areas
- FAQ.md[217-218]

### Suggested change
Add a one-liner in the FAQ clarifying equivalence, e.g. “Terminal 3 calls these metered units tokens (aka credits); `blindfold credit` shows this balance.”
Optionally, standardize on one term across docs in a follow-up PR.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

[qodo-code-review]

1. Plaintext caching risk 🐞 Bug ⛨ Security

FAQ.md recommends caching plaintext returned by release() (“release-once-reuse”) to reduce
per-call enclave ops, but it omits the explicit security trade-off that the secret now resides
in-process for that cache window. Readers may over-cache and unintentionally weaken the “agent never
had the key” posture.

Agent Prompt

### Issue description
The FAQ’s “release-once-reuse” guidance encourages caching plaintext returned by `release()` but doesn’t explicitly warn that this increases plaintext residency in the application process, which is a deliberate security trade-off.

### Issue Context
The project already documents this trade-off elsewhere (README cost section + `release()` source-level security note), but the new FAQ text currently reads as purely a cost optimization.

### Fix Focus Areas
- FAQ.md[217-220]

### Suggested change
Add a short parenthetical immediately after the “release-once-reuse” sentence, e.g.:
- note that caching keeps the secret in your process memory for that window,
- recommend keeping the cache scope/lifetime minimal,
- remind not to log/persist the plaintext,
- optionally link to README Cost section for the trade-off wording.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

[qodo-code-review]

2. Tokens/credits ambiguity 🐞 Bug ⚙ Maintainability

FAQ.md describes cost in “tokens” but also uses “out-of-credit” wording, while other docs and the
CLI use both “tokens” and “credits” without clearly stating they’re the same balance/unit. This
inconsistency can confuse users about what blindfold credit reports and what resource they need to
top up.

Agent Prompt

### Issue description
Terminology around metered units fluctuates between “tokens” and “credits” in user-facing docs and CLI output. The updated FAQ leans on “tokens” while still saying “out-of-credit,” which can read like two separate things.

### Issue Context
- README uses both terms in different sections.
- The CLI `blindfold credit` output shows “tokens” while the UI/title/top-up text says “credit/credits.”

### Fix Focus Areas
- FAQ.md[217-218]

### Suggested change
Add a one-liner in the FAQ clarifying equivalence, e.g. “Terminal 3 calls these metered units tokens (aka credits); `blindfold credit` shows this balance.”
Optionally, standardize on one term across docs in a follow-up PR.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools