docs(readme): Cost — when to use the enclave

[FiscalMindset]

Adds a mid-README 💸 Cost section answering the honest 'isn't this expensive?' question:

• Real, measured numbers: ~20 tokens per enclave op (a use/release or proxy forward); the ~20k signup grant ≈ 1,000 uses, free on testnet.
• frequency × value fit table (ideal for high-value agent keys; use the pattern below for high-volume).
• Three cost levers: release-once-reuse, seal selectively, proxy where it matters.

Placed after the integration sections, before the CLI reference; TOC link + #cost anchor added.

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

---

Summary by cubic

Adds a "Cost — when to use the enclave" section to the README with measured cost (~20 tokens per op), fit guidance, free testnet grant (~20k tokens ≈ 1,000 uses), and three levers to reduce spend (release once/reuse, seal selectively, proxy where it matters).
Placed after the integrations section, with a TOC link and a #cost anchor.

^{Written for commit 2c52814. Summary will update on new commits.}

[qodo-code-review]

PR Summary by Qodo

docs(readme): Add Cost section with measured token usage guidance

📝 Documentation 🕐 Less than 10 minutes

AI Description

• Add a mid-README Cost section with measured per-operation token usage (~20 tokens).
• Provide frequency × value guidance and a quick fit table for when to use the enclave.
• Add three practical cost levers (release/reuse, selective sealing, targeted proxying) and a TOC
 link.

High-Level Assessment

The chosen approach (a mid-README Cost section with a stable #cost anchor, concrete numbers, and decision guidance) is the most discoverable place to answer pricing concerns without adding product/config complexity. Alternatives like a separate pricing doc or FAQ would be harder to find and would fragment onboarding.

Files changed (1) +41 / -0

Documentation (1) +41 / -0

README.mdAdd “💸 Cost — when to use the enclave” section and TOC link +41/-0

Add “💸 Cost — when to use the enclave” section and TOC link

• Adds a new Cost section (with a #cost anchor) explaining measured token costs (~20 tokens/op), a frequency×value fit table, and three practical levers to reduce spend (release-and-reuse, selective sealing, proxy selectively). Updates the README table of contents to link to the new section and places it between integrations and the CLI reference.

README.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 (1) 📘 Rule violations (0) 📜 Skill insights (0)

Context used

✅ Compliance rules (platform): 5 rules

✅ Skills: blindfold

1. Token/credit ambiguity 🐞 Bug ⚙ Maintainability

Description

The new Cost section calls the signup grant “~20,000 tokens” while the Installation section
describes the same grant as “~20,000 credits,” leaving it unclear whether these are synonyms or
different units. This can confuse users comparing the cost math with the balance shown by `blindfold
credit`.

Code

README.md[R497-499]

+**How small?** Measured live: **~20 tokens per operation** (a `use`/release or a
+proxy forward). The self-serve `signup` grant (~20,000 tokens) is roughly
+**1,000 secret-uses**, free, on testnet.

Evidence

The README currently refers to the same self-serve testnet grant using two different unit names
(“credits” vs “tokens”), while CLI docs describe the balance as “token/credit,” indicating the
README should standardize or define the term to avoid ambiguity.

README.md[127-135]
README.md[492-500]
docs/AGENTS.md[83-93]

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 README uses inconsistent terminology for the same signup grant amount: it’s described as “credits” in one place and “tokens” in another. This makes the pricing/balance units ambiguous.

## Issue Context
Other docs/CLI help text uses combined wording (“token/credit”), suggesting these terms may be synonymous, but the README should be explicit and consistent.

## Fix Focus Areas
- README.md[127-135]
- README.md[492-500]
- docs/AGENTS.md[83-93]

## Suggested fix
Pick one term and use it consistently throughout README (and ideally match the CLI wording), e.g.:
- Change both places to “tokens (credits)” if both terms are in use, **or**
- Standardize on “tokens” everywhere (including the earlier “~20,000 credits” mention), **or**
- Standardize on “credits” everywhere and adjust the new Cost section accordingly.

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

---

[qodo-code-review]

1. Token/credit ambiguity 🐞 Bug ⚙ Maintainability

The new Cost section calls the signup grant “~20,000 tokens” while the Installation section
describes the same grant as “~20,000 credits,” leaving it unclear whether these are synonyms or
different units. This can confuse users comparing the cost math with the balance shown by `blindfold
credit`.

Agent Prompt

## Issue description
The README uses inconsistent terminology for the same signup grant amount: it’s described as “credits” in one place and “tokens” in another. This makes the pricing/balance units ambiguous.

## Issue Context
Other docs/CLI help text uses combined wording (“token/credit”), suggesting these terms may be synonymous, but the README should be explicit and consistent.

## Fix Focus Areas
- README.md[127-135]
- README.md[492-500]
- docs/AGENTS.md[83-93]

## Suggested fix
Pick one term and use it consistently throughout README (and ideally match the CLI wording), e.g.:
- Change both places to “tokens (credits)” if both terms are in use, **or**
- Standardize on “tokens” everywhere (including the earlier “~20,000 credits” mention), **or**
- Standardize on “credits” everywhere and adjust the new Cost section accordingly.

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