feat(paid-plans): entitlement contract, sync key management, and denial recovery

BENCHMARKS.md

@@ -94,14 +94,14 @@ interpretation and do not count as additional benchmark-quality gains.
 ### Public numeric evidence registry
 
 Every exact public aggregate retained below comes from the checked-in, public-safe
-[`offline-fixtures-receipt-diagnostics-20261109.json`](docs/benchmark-evidence/offline-fixtures-receipt-diagnostics-20261109.json) artifact. Its
+[`offline-fixtures-paid-plans-20261109.json`](docs/benchmark-evidence/offline-fixtures-paid-plans-20261109.json) artifact. Its
 SHA-256 is
-`d13497f0a36fe53ca7871597d8acfbc878348a1f6985ebae4714b4e0bee4985e`, also recorded in the
+`d787cc2a6af8de86442b56833b0fdd5654b548779403b5a03c48bc9e7ef4f760`, also recorded in the
 adjacent `.sha256` file. The artifact contains no raw questions, answers, prompts, customer data,
 or per-record content fingerprints.
 
 The fixture-suite digest is
-`c1b3f2ca3dc80047737eaa47730a7859a902a1111b6c7bf2291f5f9ad5fd9bf9`. The artifact defines
+`e21c9c051759461632b90244d1a92aed1969a38a94ecb60a74dd21c15c800324`. The artifact defines
 the digest algorithm and records the SHA-256 of every suite and dataset file. Each evidence ID
 also binds its exact command through `sha256(UTF-8 exact command)`:
 
@@ -134,7 +134,7 @@ retrieval-quality improvement. It does not qualify browser behavior, hosted serv
 external models, or provider billing. The registered artifact was produced with:
 
 ```bash
-python -m scripts.export_offline_evidence --output docs/benchmark-evidence/offline-fixtures-receipt-diagnostics-20261109.json
+python -m scripts.export_offline_evidence --output docs/benchmark-evidence/offline-fixtures-paid-plans-20261109.json
 ```
 
 The earlier release-review predecessors,
@@ -203,13 +203,13 @@ grounded checks in separate panels; provider billing and MCP transport are not m
 the SVG and matching PNG with:
 
 ```bash
-python scripts/render_benchmark_report.py --report docs/benchmark-evidence/offline-fixtures-receipt-diagnostics-20261109.json --output docs/images/context-efficiency.svg --png-output docs/images/context-efficiency.png
+python scripts/render_benchmark_report.py --report docs/benchmark-evidence/offline-fixtures-paid-plans-20261109.json --output docs/images/context-efficiency.svg --png-output docs/images/context-efficiency.png
 ```
 
 The companion examples are also generated from that artifact with:
 
 ```bash
-python -m scripts.render_benchmark_examples --report docs/benchmark-evidence/offline-fixtures-receipt-diagnostics-20261109.json --output docs/images/evidence-backed-agent-examples.svg --png-output docs/images/evidence-backed-agent-examples.png
+python -m scripts.render_benchmark_examples --report docs/benchmark-evidence/offline-fixtures-paid-plans-20261109.json --output docs/images/evidence-backed-agent-examples.svg --png-output docs/images/evidence-backed-agent-examples.png
 ```
 The historical-to-executable mapping is in
 [`docs/BENCHMARK_CHANGE_COVERAGE.md`](docs/BENCHMARK_CHANGE_COVERAGE.md).

CHANGELOG.md

@@ -5,6 +5,9 @@ All notable changes to Engraphis are documented here. Format loosely follows
 
 ## [Unreleased]
 
+- Add one checked-in entitlement contract as the read-only plan→feature mirror, and fail the
+  release gate when it drifts from the private hosted contract. Local workspace export stays
+  free; a server grant this build cannot render is reported instead of silently dropped.
 - Classify encrypted-database open failures (`database_damaged`, `database_busy`,
   `database_unavailable`, `key_rejected`, `driver_missing`, and key-file codes) so a damaged or
   locked SQLCipher file is no longer reported as a wrong key, and surface the exact condition in

MANIFEST.in

@@ -4,6 +4,7 @@ global-exclude *.pyo
 recursive-include engraphis/dashboard_assets *.html *.css *.js *.png *.ico
 recursive-include engraphis/dashboard_assets/vendor *
 include engraphis/commercial_manifest.json
+include engraphis/entitlement_contract.json
 recursive-include integrations/commandcode *.py
 recursive-include scripts/templates *.svg
 include LICENSE NOTICE README.md CHANGELOG.md BENCHMARKS.md

README.md

@@ -91,7 +91,7 @@ Pro is $10/month or $100/year for one owner. Team is $20/seat/month or $200/seat
 The current registered artifact contains three deterministic offline fixture runs. It separates context size, retrieval quality, and grounded decision checks; these small fixtures do not establish general task performance.
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/Coding-Dev-Tools/engraphis/99af3855bd6b685cbac4a4489b44b3c374129053/docs/images/context-efficiency.svg" alt="Three registered offline fixtures: structure-aware chunking reduced mean retrieved context from 740.3 to 214.3 tokens per question (71.1%, 18 questions); the serialized JSON-shape proxy fell from 24,590 to 11,138 tokens across 26 payload samples and 260 recalls. Candidate and packed retrieval quality (Recall@5, Hit@5, and answer-token recall) are shown separately (each 1.000). Grounded checks show 5/5 answerable queries grounded and 6/6 abstention queries rejected, including a 1/1 quarantined-evidence probe; 11/11 decisions were correct. MCP transport and provider billing were not measured. Artifact SHA-256 prefix d13497f0a36f; see the benchmark guide for the full checksum." width="100%">
+  <img src="https://raw.githubusercontent.com/Coding-Dev-Tools/engraphis/99af3855bd6b685cbac4a4489b44b3c374129053/docs/images/context-efficiency.svg" alt="Three registered offline fixtures: structure-aware chunking reduced mean retrieved context from 740.3 to 214.3 tokens per question (71.1%, 18 questions); the serialized JSON-shape proxy fell from 24,590 to 11,138 tokens across 26 payload samples and 260 recalls. Candidate and packed retrieval quality (Recall@5, Hit@5, and answer-token recall) are shown separately (each 1.000). Grounded checks show 5/5 answerable queries grounded and 6/6 abstention queries rejected, including a 1/1 quarantined-evidence probe; 11/11 decisions were correct. MCP transport and provider billing were not measured. Artifact SHA-256 prefix d787cc2a6af8; see the benchmark guide for the full checksum." width="100%">
   <br>
   <sup>Three offline fixtures separate context reduction, candidate and packed retrieval quality, and grounded behavior. The chart shows the artifact checksum prefix; see the benchmark guide for the full checksum and reproduction steps.</sup>
 </p>

docs/LICENSING.md

@@ -52,6 +52,17 @@ a private repository. Public clients communicate with those services through aut
 versioned protocols. This boundary protects new commercial implementation work; it does not
 change the Apache license or prevent a fork from modifying code already released here.
 
+## Entitlement presentation mirror
+
+`engraphis/entitlement_contract.json` is a checked-in, read-only mirror of the private
+control plane's plan→feature contract. It tells the dashboard which plan advertises a
+capability and which copy to show when one is unavailable. It is not an entitlement:
+`engraphis/entitlements.py` cannot authorize an operation, mint a credential, or unlock a
+route. Every paid operation is still authorized by the hosted service, and a server grant
+this build does not recognize is reported as unrecognized rather than inferred or silently
+dropped. The release gate compares the mirror with the private contract, so a capability that
+exists only server-side fails CI instead of disappearing from a paying customer's dashboard.
+
 ## Trial, grace, and recovery
 
 The server-issued trial lasts **7 active days for Pro or 14 active days for Team**. Grace is a

docs/SYNC.md

@@ -86,27 +86,35 @@ owner-private `~/.engraphis/config.env`, then restart the local dashboard. The S
 only whether the key is valid and the local encryption dependency is installed, never the key
 itself. A read-only pull still needs the same key to decrypt received bundles.
 
+The dashboard can also generate the key in place: **Settings → Cloud Sync → Create sync key**.
+It is written once to `~/.engraphis/sync.e2ee_key` (owner-only, mode `0600`), shown exactly once
+for you to store, and never returned by the status endpoint again. An operator-provisioned
+`ENGRAPHIS_SYNC_E2EE_KEY` always takes precedence and cannot be replaced from the dashboard.
+Rotation is explicit and warns that data synced under the previous key is unreadable until every
+device uses the new one. This path is for a trusted local device; a headless deployment should
+still provision the key through its secrets manager.
+
 ```bash
-python -c "import base64, secrets; print(base64.urlsafe_b64encode(secrets.token_bytes(32)).decode().rstrip('='))"
-```
-
-Treat the command output as a secret: use a trusted terminal without transcript or log capture,
-store it in your secret manager, and never paste it into the Cloud portal or a support request.
-Before the first upload, keep a separate secure backup and confirm you can retrieve it. If the
-key is lost, previously synced encrypted bundles cannot be decrypted; Engraphis Cloud cannot
-restore it.
-
-For the first device, add a single `ENGRAPHIS_SYNC_E2EE_KEY=<your key>` assignment to its
-owner-private `~/.engraphis/config.env` with a trusted editor, retaining any existing settings.
-Use the path named by `ENGRAPHIS_ENV_FILE` instead when that override is configured. A secrets
-manager may inject the same process variable instead of using the file. Restart the dashboard,
-then check **Settings → Cloud Sync**: Connection must show **Connected**, Encryption key
-**Valid**, and Sync readiness **Ready** before **Sync now** is enabled. If encryption support is
-missing, install `engraphis[cloud-sync]` in the dashboard's Python environment and restart.
-On each additional device, provision the *same* backed-up key through your secure channel;
-generating a different key will make earlier encrypted bundles unreadable there.
-
-The dashboard's **Sync now** action invokes the same customer protocol. The public package does
+python -c "import base64, secrets; print(base64.urlsafe_b64encode(secrets.token_bytes(32)).decode().rstrip('='))"
+```
+
+Treat the command output as a secret: use a trusted terminal without transcript or log capture,
+store it in your secret manager, and never paste it into the Cloud portal or a support request.
+Before the first upload, keep a separate secure backup and confirm you can retrieve it. If the
+key is lost, previously synced encrypted bundles cannot be decrypted; Engraphis Cloud cannot
+restore it.
+
+For the first device, add a single `ENGRAPHIS_SYNC_E2EE_KEY=<your key>` assignment to its
+owner-private `~/.engraphis/config.env` with a trusted editor, retaining any existing settings.
+Use the path named by `ENGRAPHIS_ENV_FILE` instead when that override is configured. A secrets
+manager may inject the same process variable instead of using the file. Restart the dashboard,
+then check **Settings → Cloud Sync**: Connection must show **Connected**, Encryption key
+**Valid**, and Sync readiness **Ready** before **Sync now** is enabled. If encryption support is
+missing, install `engraphis[cloud-sync]` in the dashboard's Python environment and restart.
+On each additional device, provision the *same* backed-up key through your secure channel;
+generating a different key will make earlier encrypted bundles unreadable there.
+
+The dashboard's **Sync now** action invokes the same customer protocol. The public package does
 not run a local auto-sync loop or ship a cron/Task Scheduler wrapper. Hosted automation belongs
 to the private service. A round with any incomplete workspace is a failure, even when other peers
 were applied successfully: the bounded report retains those good-peer totals, labels the result