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-release-1.7.12-20261102.json`](docs/benchmark-evidence/offline-fixtures-release-1.7.12-20261102.json) artifact. Its
+[`offline-fixtures-paid-plans-20261104.json`](docs/benchmark-evidence/offline-fixtures-paid-plans-20261104.json) artifact. Its
 SHA-256 is
-`025183601c5a28a37daf9326a061010244bc9a3f9f7db1e3e6d4f866eaafc660`, also recorded in the
+`cc66984fd3dd78c17addeb979aea0e0bf40ff0f533ebcd683da4b7f532da0055`, 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
-`54422b65475bb0d3e5c4ad0613bbda87dd5e01cb43e15513469b7306446831c9`. The artifact defines
+`93d671089dd360954fce2c97ce1fdd105f87166ba9224e644d61ce15f9857e79`. 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-release-1.7.12-20261102.json
+python -m scripts.export_offline_evidence --output docs/benchmark-evidence/offline-fixtures-paid-plans-20261104.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-release-1.7.12-20261102.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-20261104.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-release-1.7.12-20261102.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-20261104.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,10 @@ 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.
+
 ## [1.7.12] - 2026-11-02
 
 Candidate package version: **1.7.12**. Publication and hosted-service qualification remain separate.

Dockerfile

@@ -1,5 +1,5 @@
 # Engraphis — self-hosted AI memory engine. Local-first; you bring the LLM.
-FROM python:3.11-slim@sha256:b7a9e5f6a93d6d4a31f129bbd4bdee69efccb6ded0fb230d78aafaf37af98377 AS base
+FROM python:3.11.18-slim@sha256:db20d8506e2f15b6db39b40b6015ca46bae855dec6dd326d462cfe79ae972893 AS base
 
 # ENGRAPHIS_HOST is deliberately NOT set here: docker-entrypoint.sh chooses IPv6 for a
 # Railway deployment (which injects RAILWAY_SERVICE_NAME) and 0.0.0.0 for ordinary Docker.

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

@@ -52,7 +52,7 @@ Connect a coding agent over MCP with the [agent setup guide](https://github.com/
 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 025183601c5a; 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 cc66984fd3dd; 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