Gio2050 · Aug 25, 2026 · Aug 25, 2026
diff --git a/.gitignore b/.gitignore
@@ -50,6 +50,7 @@ ENV/
 .venv
 pip-log.txt
 pip-delete-this-directory.txt
+*.egg-info/
 
 # Jupyter Notebooks
 .ipynb_checkpoints

diff --git a/examples/README.md b/examples/README.md
@@ -13,7 +13,7 @@ This directory contains example data files and configurations for testing and de
 - `receipts.json` - Sample receipt data with participant activities
 - `payouts.json` - Sample payout data for index computation
 - `epoch_budget.json` - Sample AFI emissions budget data
-- `scores_min.json` - Minimal BenchKit scores for testing
+- `merit_scores.synthetic.json` - Synthetic merit scores for the `--scores` path (see "Merit scores (synthetic)" below)
 
 ### Integration Examples
 - `pipeline_demo.sh` - Complete end-to-end pipeline demonstration
@@ -34,18 +34,18 @@ afi-econ-kit simulate --config examples/config.yaml --outdir budget_sim \
   --budget examples/epoch_budget.json
 ```
 
-### 3. Simulation with BenchKit Integration
+### 3. Simulation with Merit Scores (synthetic)
 ```bash
-# Run simulation with merit scores
+# Run simulation with the synthetic merit scores
 afi-econ-kit simulate --config examples/config.yaml --outdir merit_sim \
-  --scores examples/scores_min.json
+  --scores examples/merit_scores.synthetic.json
 ```
 
 ### 4. Full Integration (Budget + Merit)
 ```bash
 # Run simulation with both budget and merit scores
 afi-econ-kit simulate --config examples/config.yaml --outdir full_sim \
-  --budget examples/epoch_budget.json --scores examples/scores_min.json
+  --budget examples/epoch_budget.json --scores examples/merit_scores.synthetic.json
 ```
 
 ### 5. AFI Index Computation
@@ -108,26 +108,27 @@ afi-econ-kit payouts --allocations stage_safety/safety_allocations.json \
 }
 ```
 
-### scores_min.json Format (BenchKit)
+### merit_scores.synthetic.json Format (merit scores, synthetic)
 ```json
 {
-  "participants": {
-    "user_001": {
-      "role": "reputation",
-      "total_score": 85.5,
-      "benchmark_scores": {
-        "latency": 90.0,
-        "throughput": 81.0
-      }
-    }
-  },
+  "reputation": {"score": 0.58},
+  "poi": {"score": 0.55},
+  "poinsight": {"score": 0.60},
+  "n": 20,
   "stamp": {
+    "source": "synthetic",
     "version": "0.1.0",
-    "utc_ts": "2024-01-01T12:00:00Z"
+    "utc_ts": "2026-08-24T00:00:00Z"
   }
 }
 ```
 
+`reputation.score` is required; `poi.score` and `poinsight.score` default to 0.5 when
+absent. Scores are clipped to [0, 1]. `n` is the row count behind the scores and `stamp`
+is passed through unchanged into the simulation's provenance stamp (as `merit_stamp`).
+These are synthetic research inputs -- see "Merit scores (synthetic)" below for what
+they are and are not.
+
 ## Expected Outputs
 
 ### Simulation Outputs
@@ -171,18 +172,24 @@ afi-econ-kit simulate --config config.yaml --outdir integrated_sim \
   --budget ../afi-emissions/budget_out/epoch_budget.json
 ```
 
-### With afi-benchkit
-```bash
-# Generate scores in afi-benchkit
-cd ../afi-benchkit
-afi-benchkit reputation --config config.yaml --out scores_out
+### Merit scores (synthetic)
+
+The `--scores` merit path takes a **synthetic** merit-scores file:
 
-# Use scores in afi-econ-kit
-cd ../afi-econ-kit
+```bash
 afi-econ-kit simulate --config config.yaml --outdir integrated_sim \
-  --scores ../afi-benchkit/scores_out/scores.json
+  --scores examples/merit_scores.synthetic.json
 ```
 
+These scores are research-plane inputs only. The protocol source of analyst merit is
+the CAL-GOV analyst calibration record (`afi.analyst-calibration.v1`) -- **not a
+scalar** -- and any conversion of it into a merit value is **CHAIN-GOV reserved**.
+afi-econ consumes no such value from the protocol; edit the synthetic file to explore
+how merit multipliers move gauge allocations. Proof-of-Intelligence (PoI) and
+Proof-of-Insight (PoInsight) remain reserved protocol reputation primitives
+(CONST-GOV D-CONST-5; CAL-GOV D-CAL-5); the `poi` / `poinsight` keys here are
+synthetic placeholders that stand in for no protocol value.
+
 ## Testing and Validation
 
 All example files are designed to work with the golden test suite:

diff --git a/examples/merit_scores.synthetic.json b/examples/merit_scores.synthetic.json
@@ -0,0 +1,12 @@
+{
+  "reputation": {"score": 0.58},
+  "poi": {"score": 0.55},
+  "poinsight": {"score": 0.60},
+  "n": 20,
+  "stamp": {
+    "source": "synthetic",
+    "version": "0.1.0",
+    "utc_ts": "2026-08-24T00:00:00Z",
+    "note": "Synthetic research input for afi-econ's --scores merit path. The protocol source of analyst merit is the CAL-GOV analyst calibration record (afi.analyst-calibration.v1) -- not a scalar -- and any merit conversion is CHAIN-GOV reserved."
+  }
+}
diff --git a/examples/pipeline_demo.sh b/examples/pipeline_demo.sh
@@ -30,15 +30,15 @@ echo ""
 echo "🏆 Step 3: Simulation with Merit Scores"
 echo "--------------------------------------"
 afi-econ-kit simulate --config config.yaml --outdir demo_pipeline_out/merit \
-  --scores tests/fixtures/scores_min.json
+  --scores examples/merit_scores.synthetic.json
 echo "✅ Merit integration complete"
 
 # Step 4: Full integration
 echo ""
 echo "🔗 Step 4: Full Integration (Budget + Merit)"
 echo "-------------------------------------------"
 afi-econ-kit simulate --config config.yaml --outdir demo_pipeline_out/full \
-  --budget examples/epoch_budget.json --scores tests/fixtures/scores_min.json
+  --budget examples/epoch_budget.json --scores examples/merit_scores.synthetic.json
 echo "✅ Full integration complete"
 
 # Step 5: AFI Index computation

diff --git a/out/econ_breakers.png b/out/econ_breakers.png
diff --git a/out/econ_budget.png b/out/econ_budget.png
diff --git a/out/econ_gauge_shares.png b/out/econ_gauge_shares.png
diff --git a/out/econ_summary.json b/out/econ_summary.json
diff --git a/out_audit/AUDIT.md b/out_audit/AUDIT.md
diff --git a/out_audit/audit_report.json b/out_audit/audit_report.json
diff --git a/out_base/econ_breakers.png b/out_base/econ_breakers.png
diff --git a/out_base/econ_budget.png b/out_base/econ_budget.png
diff --git a/out_base/econ_gauge_shares.png b/out_base/econ_gauge_shares.png
diff --git a/out_base/econ_summary.json b/out_base/econ_summary.json
diff --git a/out_with/econ_breakers.png b/out_with/econ_breakers.png
diff --git a/out_with/econ_budget.png b/out_with/econ_budget.png
diff --git a/out_with/econ_gauge_shares.png b/out_with/econ_gauge_shares.png
diff --git a/out_with/econ_summary.json b/out_with/econ_summary.json
diff --git a/params/gauge_v0.yaml b/params/gauge_v0.yaml
@@ -12,7 +12,9 @@ caps:
 
 policy_merit_blend: 0.5   # 50/50 policy vs. merit
 
-# BenchKit merit weights for role mapping
+# Merit weights for role mapping (applied to merit scores -- synthetic research inputs;
+# the protocol source is the CAL-GOV analyst calibration record, not a scalar, and any
+# merit conversion is CHAIN-GOV reserved)
 bench_merit_weights:
   producers:
     poinsight: 0.7