fix(site,docs): round-4 buyer-review defects

README.md

@@ -79,10 +79,10 @@ echoed on every persisted-panel success envelope and every typed error
 [docs/methodology.md](docs/methodology.md).
 
 **Zero-config inside any MCP host that speaks sampling** (Claude Desktop,
-Claude Code, Cursor, Windsurf) — drop the config in and run a panel with **no
-API key set**. The host runs the model on your behalf, using its own
-subscription. Bring your own provider key when you want reproducibility,
-ensembles, or larger panels. Personas and instruments are plain YAML; every
+Claude Code, Cursor, Windsurf) — drop the config in and run `run_prompt` and
+small `run_quick_poll` calls (up to 3 personas) with **no API key set**. The
+host runs the model on your behalf, using its own subscription. Full panels,
+ensembles, and reproducible model pins need your own provider key. Personas and instruments are plain YAML; every
 response is schema-validated with per-turn cost telemetry.
 
 ## Why
@@ -142,8 +142,9 @@ run without one.
 Read `synthesis.recommendation` for the headline call, `synthesis.disagreements`
 for dissent, and `rounds[].results[]` for the per-panelist transcript. See
 [docs/response-contract.md](docs/response-contract.md) for the full v1.0.0
-envelope (note: `panel_verdict` fields like `convergence` and `flags[]` are
-defined but not yet emitted on the success path — see the note in the lede).
+envelope (as of v1.0.6, `panel_verdict` — `headline`, `convergence`,
+`dissent_count`, `flags[]` — is emitted on the success path of the MCP panel
+tools; see the note in the lede for the sampling-mode/ensemble exceptions).
 
 **Structured polling is the agent default.** For pick-one, Likert,
 confidence, and tagged-themes questions, pass a bounded
@@ -307,7 +308,9 @@ arguments to override. Provider keys are read from environment variables
 (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GOOGLE_API_KEY`/`GEMINI_API_KEY`,
 `XAI_API_KEY`) — pass whichever your model requires.
 
-Pin to a specific version (`:0.11.0`) in production rather than `:latest`.
+Pin to a version tag in production rather than `:latest` — either the exact
+release (`:1.5.7`) or the floating major.minor tag (`:1.5`), both published on
+every stable release.
 
 ## Use as a Python Library
 
@@ -1365,6 +1368,14 @@ modes.
 
 | Version | Highlights |
 |---------|-----------|
+| 1.5.x *(current)* | `synthpanel mcp install --host auto` one-liner host registration; four canonical persona packs; deterministic `poll-summary` rollups; MCP auto-picks a fast model for ≥10-persona panels; `results list`/`results show` for the saved-results store; `python -m synthpanel` alias; fail-loud empty attachments and typed `response_schema` enforcement; synthesis routing follows the panel's provider; PyPI Trusted Publishing + auto-tag version-drift guard |
+| 1.4.0 | Explicit `cost_estimated_usd` / `cost_actual_usd` (+ `per_model_breakdown`) on `EnsembleResult`, `ModelRunResult`, and `SynthesisResult` — estimate-vs-bill reconciliation without inspecting raw usage |
+| 1.3.0 | `trafilatura` moved to the `[full]` extra so bare `pip install synthpanel` works on pyodide/Cloudflare Python Workers (no `lxml` C extension required) |
+| 1.2.0 | Pyodide-safe / async-DI surface for `synth_panel.ensemble.synthesize_panel` — drive the judge call through your own async LLM client |
+| 1.1.0 | `synth_panel.ensemble` frozen as the supported public API for the ensemble/deliberation core |
+| 1.0.6 | Cross-town dogfood friction sweep on the v1.0.x line; `panel_verdict` emitted on the MCP success path; release-dogfood protocol codified |
+| 1.0.0 | Frozen MCP contract (`schemas/v1.0.0.json`, `schema_version` echoed on every response and typed error); multimodal attachments (images, URLs, PDFs, inline HTML) with stratified delivery and a URL-fetch security perimeter |
+| 0.12.0 | `--best-model-for TOPIC[:DATASET]` SynthBench-driven model picker, `--submit-to-synthbench`, `synthpanel pack calibrate`, six bundled packs deepened 5 → 15 personas |
 | 0.11.0 | `sp-i2ub` scaled-orchestration epic: panelist-level checkpointing with `--resume <run-id>` and auto-checkpoint on SIGINT/SIGTERM (every K=25 panelists), `--max-cost <USD>` mid-run projected-total cost gate that halts gracefully with valid partial JSON, and valid-partial-JSON discipline on every abort path (rate-exhaustion, SIGINT, cost-gate, panelist failure) with `run_invalid: true` + specific `abort_reason` and exit code 2; 6-bug loudness sweep turning silent failures loud across alias parse, synthesis partial payload, MCP `extend_panel`, condition evaluator, orchestrator follow-up exceptions, and the `test_aliases` fixture; auto-tag now fails loudly on unlabeled release PRs; `pip-audit` ignores CVE-2026-3219 in pip 26.0.1 |
 | 0.10.0 | `synthpanel report` post-hoc Markdown renderer for saved panel results (behind `[report]` extra); inline SynthBench calibration via `panel run --calibrate-against DATASET:QUESTION` with auto-derived `pick_one` schema and `per_question[key].calibration` sub-object wire format; decentralized pack registry — `pack import gh:<user>/<repo>` with `--unverified`, `pack search`, `pack list --registry`, 24h cache + offline fallback; optional `version:` field on persona packs with opt-in shadow warning |
 | 0.9.9 | `--synthesis-strategy=auto` now routes to map-reduce on context overflow instead of hard-failing; OpenRouter alias resolution tightened for sub-1¢ local-table sanity checks; `--personas-merge` warns (or errors via `--personas-merge-on-collision`) on name collisions with bundled packs; version single-sourced from `src/synth_panel/__version__.py` with templated site render |
@@ -1388,10 +1399,10 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, testing, and how t
 
 ## Benchmarked on SynthBench
 
-synthpanel's ability to produce representative synthetic respondents is independently measured by [SynthBench](https://dataviking-tech.github.io/synthbench/), an open benchmark for synthetic survey quality.
+synthpanel's ability to produce representative synthetic respondents is measured by [SynthBench](https://synthbench.org), an open benchmark for synthetic survey quality (a sibling DataViking project, operated by the SynthPanel maintainers).
 
-- **Want proof it works?** Browse the [leaderboard](https://dataviking-tech.github.io/synthbench/leaderboard/) — ensemble blending of 3 models hits SPS 0.90 (90% human parity).
-- **Got a great configuration?** [Submit your scores](https://dataviking-tech.github.io/synthbench/submit/) and compare against baselines.
+- **Want proof it works?** Browse the [leaderboard](https://synthbench.org) — the 3-model ensemble blend scores SPS 0.877 on opinionsqa, 0.858 on subpop, and 0.813 on globalopinionqa (leaderboard generated 2026-07-17; numbers move as the board recomputes).
+- **Got a great configuration?** [Submit your scores](https://synthbench.org) and compare against baselines.
 - **Contributing an adapter?** Heavy PRs with substantial behavior changes benefit from SynthBench results — reviewers can evaluate empirical quality, not just code. See [docs/adapter-guide.md](docs/adapter-guide.md) for the full adapter workflow.
 
 ## License

docs/blog/synthpanel-vs-commercial-alternatives.md

@@ -1,13 +1,14 @@
 # SynthPanel vs Synthetic Users vs FocusPanel.ai — When Open-Source MCP Beats the SaaS
 
-*Published 2026-04-15 · 1,580 words · ~7 min read*
+*Published 2026-04-15 · Updated 2026-07-16 · ~7 min read*
 
 > **TL;DR — SynthPanel is the open-source, LLM-agnostic alternative to commercial
 > synthetic-respondent tools like Synthetic Users, FocusPanel.ai, Delve.ai, and
 > POPJAM. It runs as both a CLI and a 12-tool MCP server you can drop into Claude
 > Code, Cursor, Windsurf, or Zed. Install with `pip install synthpanel[mcp]`.
-> MIT-licensed. Scores 0.90 SPS on the SynthBench human-parity benchmark via
-> 3-model ensembles.**
+> MIT-licensed. Its 3-model ensemble leads the SynthBench leaderboard at
+> SPS 0.86–0.88 (opinionsqa 0.877, subpop 0.858; leaderboard generated
+> 2026-07-17 — numbers move as the board recomputes).**
 
 If you are a researcher, PM, or founder searching for a way to run synthetic
 focus groups with AI personas in 2026, the first five results you are going to
@@ -74,8 +75,9 @@ give you this — they *are* the vendor.
 **Honest model comparison.** Run the same instrument through Claude Sonnet 4.6,
 GPT-4o, and Gemini 2.5 Flash, blend at `--models sonnet:0.34,gpt-4o:0.33,gemini:0.33`,
 and the framework emits per-model distributions *and* the weighted ensemble.
-This is how SynthPanel earns its 0.90 SynthBench score: you cannot get that
-number from any single model alone.
+This is how SynthPanel tops the SynthBench leaderboard: the blended ensemble
+beats every single model on each dataset — by roughly 0.03–0.05 SPS — which
+you cannot get from any single model alone.
 
 ## 3. Why YAML Instruments Matter
 
@@ -186,20 +188,27 @@ like this — commercial or open-source — is over-claiming.
 Use synthetic panels to *pre-screen* and *iterate*. Validate the interesting
 findings with real participants before you publish, launch, or sell.
 
-## 6. Quantitative Proof: SynthBench SPS 0.90
-
-Claims are cheap. SynthPanel was the first harness to publish head-to-head
-results on [SynthBench](https://synthbench.org), an independent open
-benchmark for synthetic-respondent quality. SynthBench computes a
-Synthetic-Parity Score (SPS) — the fraction of responses from a synthetic
-panel that match the distribution of a real-human control group on the same
-instrument.
-
-A 3-model ensemble of SynthPanel personas — blended via
-`synthpanel panel run --models haiku:0.33,gemini:0.33,gpt-4o-mini:0.34 --blend`
-— scores **SPS 0.90 on the current SynthBench leaderboard**. That is 90%
-human parity, measured by an independent third party, on a benchmark whose
-data and scoring code are both open.
+## 6. Quantitative Proof: SynthBench SPS 0.86–0.88
+
+Claims are cheap. SynthPanel publishes head-to-head results on
+[SynthBench](https://synthbench.org), an open, reproducible benchmark for
+synthetic-respondent quality. Its data and scoring code are public — though,
+in the interest of full disclosure, SynthBench is a sibling DataViking project
+operated by the SynthPanel maintainers, not an independent third party.
+SynthBench computes a **Synthetic-Parity Score (SPS)** — how closely a
+synthetic panel's response distribution matches a real-human control group on
+the same instrument.
+
+A 3-model ensemble of SynthPanel personas — the leaderboard's "SynthPanel
+Ensemble (3-model)" entry, an equal-weight blend of Claude Haiku 4.5,
+Gemini 2.5 Flash Lite, and GPT-4o-mini, run via
+`synthpanel panel run --models haiku:0.33,gemini-flash-lite:0.33,gpt-4o-mini:0.34 --blend`
+— leads the current SynthBench leaderboard (generated 2026-07-17) at
+**SPS 0.877** on opinionsqa and **0.858** on subpop (0.813 on
+globalopinionqa). That is roughly 0.03–0.05 above the best single model on
+each dataset, and 0.10–0.11 above the random baseline (~0.71–0.76), on a
+benchmark whose data and scoring code are both open. Leaderboard numbers move
+as the board recomputes — check the live board for the current figures.
 
 Commercial competitors have not, at time of writing, published SPS scores on
 the same benchmark. If they do, the comparison will be apples-to-apples — and

site/blog/synthpanel-vs-commercial-alternatives.html

@@ -9,7 +9,7 @@
     </title>
     <meta
       name="description"
-      content="Open-source alternative to Synthetic Users, FocusPanel.ai, Delve.ai. CLI + MCP server, any LLM, tops the SynthBench leaderboard (SPS ~0.88). MIT-licensed."
+      content="Open-source alternative to Synthetic Users, FocusPanel.ai, Delve.ai. CLI + MCP server, any LLM, tops the SynthBench leaderboard (SPS 0.86–0.88). MIT-licensed."
     />
     <meta
       name="keywords"
@@ -28,7 +28,7 @@
     />
     <meta
       property="og:description"
-      content="Open-source, LLM-agnostic synthetic focus group tool. CLI + MCP server. Tops the SynthBench leaderboard (SPS ~0.88). pip install synthpanel[mcp]."
+      content="Open-source, LLM-agnostic synthetic focus group tool. CLI + MCP server. Tops the SynthBench leaderboard (SPS 0.86–0.88). pip install synthpanel[mcp]."
     />
     <meta
       property="og:url"
@@ -40,6 +40,7 @@
     <meta property="og:image:height" content="630" />
     <meta property="og:image:alt" content="synthpanel — Run synthetic focus groups with any LLM" />
     <meta property="article:published_time" content="2026-04-15" />
+    <meta property="article:modified_time" content="2026-07-16" />
     <meta property="article:author" content="DataViking" />
     <meta property="article:section" content="Positioning" />
     <meta property="article:tag" content="synthetic research" />
@@ -68,8 +69,9 @@
         "@context": "https://schema.org",
         "@type": "TechArticle",
         "headline": "SynthPanel vs Synthetic Users vs FocusPanel.ai — When Open-Source MCP Beats the SaaS",
-        "description": "SynthPanel is the open-source, LLM-agnostic alternative to commercial synthetic-respondent tools. CLI + 12-tool MCP server, MIT-licensed, tops the SynthBench leaderboard (SPS ~0.88 on opinionsqa/subpop).",
+        "description": "SynthPanel is the open-source, LLM-agnostic alternative to commercial synthetic-respondent tools. CLI + 12-tool MCP server, MIT-licensed, tops the SynthBench leaderboard (SPS 0.86–0.88 on opinionsqa/subpop).",
         "datePublished": "2026-04-15",
+        "dateModified": "2026-07-16",
         "author": { "@type": "Organization", "name": "DataViking", "url": "https://dataviking.tech" },
         "publisher": { "@type": "Organization", "name": "synthpanel", "url": "https://synthpanel.dev" },
         "about": [
@@ -133,7 +135,7 @@
       <article>
         <header>
           <p class="mb-4 text-xs font-semibold uppercase tracking-wider text-emerald-300">
-            Positioning · 2026-04-15 · ~7 min read
+            Positioning · 2026-04-15 · Updated 2026-07-16 · ~7 min read
           </p>
           <h1
             class="bg-gradient-to-br from-white to-slate-400 bg-clip-text font-mono text-3xl font-bold leading-tight tracking-tight text-transparent sm:text-4xl"
@@ -161,8 +163,8 @@
             or Zed. Install with
             <code class="rounded bg-slate-900/80 px-1.5 py-0.5 text-emerald-300">pip install synthpanel[mcp]</code>.
             MIT-licensed. Its 3-model ensemble leads the SynthBench leaderboard
-            at <strong>SPS ~0.88</strong> (opinionsqa 0.877, subpop 0.879; snapshot
-            2026-07-13).
+            at <strong>SPS 0.86&ndash;0.88</strong> (opinionsqa 0.877, subpop 0.858;
+            leaderboard generated 2026-07-17).
           </p>
         </aside>
 
@@ -274,7 +276,7 @@ <h2 class="mt-12 text-xl font-semibold text-white sm:text-2xl">
           and the framework emits per-model distributions <em>and</em> the
           weighted ensemble. This is how SynthPanel tops the SynthBench
           leaderboard: the blended ensemble beats every single model on each
-          dataset — by roughly 0.03–0.06 SPS — which you cannot get from any
+          dataset — by roughly 0.03–0.05 SPS — which you cannot get from any
           single model alone.
         </p>
 
@@ -449,7 +451,7 @@ <h2 class="mt-12 text-xl font-semibold text-white sm:text-2xl">
         </p>
 
         <h2 class="mt-12 text-xl font-semibold text-white sm:text-2xl">
-          6. Quantitative Proof: SynthBench SPS ~0.88
+          6. Quantitative Proof: SynthBench SPS 0.86&ndash;0.88
         </h2>
         <p class="mt-4 text-slate-300">
           Claims are cheap. SynthPanel publishes head-to-head results on
@@ -466,13 +468,16 @@ <h2 class="mt-12 text-xl font-semibold text-white sm:text-2xl">
           real-human control group on the same instrument.
         </p>
         <p class="mt-4 text-slate-300">
-          A 3-model ensemble of SynthPanel personas — blended via
-          <code class="rounded bg-slate-900/80 px-1.5 py-0.5 text-emerald-300">synthpanel panel run --models haiku:0.33,gemini:0.33,gpt-4o-mini:0.34 --blend</code>
-          — leads the current SynthBench leaderboard (generated 2026-07-13) at
+          A 3-model ensemble of SynthPanel personas — the leaderboard&rsquo;s
+          &ldquo;SynthPanel Ensemble (3-model)&rdquo; entry, an equal-weight
+          blend of Claude Haiku 4.5, Gemini 2.5 Flash Lite, and GPT-4o-mini,
+          run via
+          <code class="rounded bg-slate-900/80 px-1.5 py-0.5 text-emerald-300">synthpanel panel run --models haiku:0.33,gemini-flash-lite:0.33,gpt-4o-mini:0.34 --blend</code>
+          — leads the current SynthBench leaderboard (generated 2026-07-17) at
           <strong class="text-emerald-300">SPS 0.877</strong> on opinionsqa and
-          <strong class="text-emerald-300">0.879</strong> on subpop (0.813 on
-          globalopinionqa). That is roughly 0.03–0.06 above the best single
-          model on each dataset, and 0.10–0.12 above the random baseline
+          <strong class="text-emerald-300">0.858</strong> on subpop (0.813 on
+          globalopinionqa). That is roughly 0.03–0.05 above the best single
+          model on each dataset, and 0.10–0.11 above the random baseline
           (~0.71–0.76), on a benchmark whose data and scoring code are both
           open. Leaderboard numbers move as the board recomputes — check the
           live board for the current figures.