From 2c52814f24f0bfa72924e9426d03b9243dab0930 Mon Sep 17 00:00:00 2001
From: FiscalMindset <254638087+FiscalMindset@users.noreply.github.com>
Date: Mon, 13 Jul 2026 02:02:53 +0530
Subject: [PATCH] =?UTF-8?q?docs(readme):=20add=20'Cost=20=E2=80=94=20when?=
 =?UTF-8?q?=20to=20use=20the=20enclave'=20section?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Address the natural 'isn't this expensive?' question with real, measured
numbers (~20 tokens per enclave op) and honest guidance: frequency×value fit,
plus the three cost levers (release-once-reuse, seal selectively, proxy where it
matters). Placed mid-README (after integrations, before the CLI reference) with
a TOC link + anchor.

Co-authored-by: algsoch <algsoch@gmail.com>
---
 README.md | 41 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 41 insertions(+)

diff --git a/README.md b/README.md
index f1ffb08..56ca53b 100644
--- a/README.md
+++ b/README.md
@@ -79,6 +79,7 @@ npm i -g @fiscalmindset/blindfold && blindfold signup --email you@example.com
 [🧪 Proof — the demo](#proof-of-blindness--the-side-by-side-demo)<br/>
 [🔌 Integration styles](#two-integration-styles)<br/>
 [🧩 Supported integrations](#supported-integrations)<br/>
+[💸 Cost — when to use it](#cost)<br/>
 [⌨️ CLI at a glance](#cli-at-a-glance)<br/>
 [🤖 Agent skill](#agent-skill--let-your-coding-agent-seal-keys-for-you)
 
@@ -484,6 +485,46 @@ impact writeup: [`integration-stack.md`](integration-stack.md).
 
 ---
 
+<a id="cost"></a>
+
+## 💸 Cost — when to use the enclave (and when not to)
+
+Every time a key is *used*, it's a metered Terminal 3 enclave operation — a real
+(tiny) cost, unlike reading a plaintext env var. That's the trade-off of
+confidential compute: an `env` var is free but leakable; an enclave-substituted
+key costs a fraction but **can't leak**.
+
+**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.
+
+Whether that's cheap depends on **frequency × value**:
+
+| Key | Fit |
+|---|---|
+| Deploy tokens, Stripe/payment keys, admin creds, keys handed to **autonomous agents** — used occasionally, catastrophic if leaked | ✅ **Ideal** — the cost is a rounding error next to a breach |
+| A key hit **thousands of times a second**, low value per call | ⚠️ Per-call enclave cost adds up — use the pattern below |
+
+**Three levers to keep it cheap:**
+
+1. **Release once, reuse.** `release()` hands the plaintext to *your* process —
+   cache it for a burst/session and pay **one op for N calls** instead of N ops.
+   *(Trade-off: the key sits in your memory for that window — your choice, per
+   workload.)*
+2. **Seal selectively.** Only route the keys that would hurt if leaked through
+   the enclave; leave low-value, high-frequency traffic alone.
+3. **Proxy where it matters.** The per-call proxy gives the strongest guarantee —
+   spend the ~20 tokens where the guarantee is worth it, and release-and-reuse
+   where volume dominates.
+
+**Bottom line:** for the high-value secrets Blindfold is built for — the ones you
+hand to AI agents — ~20 tokens per use is trivial insurance against a leak that
+could cost thousands. It's not meant to wrap every low-value call at massive
+scale; for that, release-and-reuse collapses the cost. And on testnet, you build
+for free.
+
+---
+
 ## CLI at a glance
 
 ```bash