Compare Preview
Proof that the first product step is compare-first, with normalized candidates and visible match reasons.
Proof
Claims mean more when they point back to evidence.
Public claims, AI guidance, and evidence in one place
DealWatch should feel product-ready, but the public story still needs to stay tied to evidence. This page is the shortest route from claim to proof for compare intelligence, AI explanation, recovery guidance, and read-only MCP safe access, not a second full copy of runtime or release truth.
This page proves repo-side surfaces and command entrypoints. It is not a promise that a hosted deployment has already been re-verified end to end.
Live adapter evidence
The proof path points back to the current store surface without freezing a marketing snapshot count into this page.
Runtime evidence
API, worker, and WebUI still belong to the active product contract, and the proof page keeps the command trail visible.
Read-only MCP boundary
Claude Code, Codex, OpenHands, OpenCode, OpenClaw, and similar agent clients can consume this surface today, including the builder starter pack, per-client starter assets, and copyable skill cards, but the exposed MCP/API layer stays intentionally read-only. Maintenance, cleanup, legacy bridge commands, run-now mutations, and maintainer-only browser debug commands stay outside the public tool surface.
Recommendation boundary
The local Compare Preview runtime now ships a deterministic-first recommendation card, but broader or autonomous buy / wait coverage is still not a shipped product fact.
| Claim | Proof surface | Why it matters |
|---|---|---|
| Compare Preview is real | `POST /api/compare/preview`, the Compare Preview WebUI route, and response fields for normalized candidates, scores, and why-like / why-unlike reasons | Public visitors can verify that the first product step is not a mock, a static demo, or a black-box score with no explanation. |
| Watch tasks are product state, not just logs | `POST /api/watch-tasks`, `GET /api/watch-tasks`, and task detail UI | The repository exposes a durable task loop rather than one-off scraping output. |
| Compare context can stay alive after intake | `POST /api/watch-groups`, group detail UI, and winner / spread / decision reason fields | Shows that compare-first is not only a one-time intake trick. The runtime can keep several candidates alive and rerank them over time. |
| Effective price matters | Task detail screenshots and the cashback/effective price loop in the public README | DealWatch is trying to improve decision quality, not only capture raw listed prices. |
| Health and delivery state are first-class runtime signals | Task detail health state, backoff state, delivery lifecycle fields, and the notifications control surface | Shows the runtime is moving from “it ran once” toward “it can be operated over time.” |
| AI explainers are real, but bounded | Compare, watch-group, and recovery AI envelopes built on deterministic evidence anchors such as `decision_explain`, match reasons, `reason`, and `recommended_action` | Public visitors can verify that AI is used for explanation and decision support, not as a black-box replacement for product truth. |
| Read-only MCP safe access is real | `python -m dealwatch.mcp list-tools --json`, `python -m dealwatch.mcp client-starters --json`, `python -m dealwatch.mcp serve --transport stdio`, `GET /api/runtime/builder-starter-pack`, the registered read-only tool list in `src/dealwatch/mcp/server.py`, and the repo-native builder starter pack plus skill cards under `docs/integrations/` | Shows that agent access exists without turning the product into a write-capable automation surface. |
| Recommendation is still deferred | The local Compare Preview runtime now ships a conservative recommendation card grounded in deterministic compare evidence, while broader task/group/MCP expansion still stays gated. | Keeps the public story honest by separating explanation from automatic decision-making. |
| The public site is maintained | GitHub Pages, README entrypoints, releases, discussions, and remote verification scripts | The project feels alive in public instead of looking like a one-time code dump. |
| The public story is guarded | The public-surface verifiers plus the remote GitHub verifier/checklist that watch branch protection, `CodeQL`, workflows, and expected labels | Public promises are less likely to drift away from current repository reality over time without this page pretending to be a live dashboard or the full guard inventory. |
Evidence map
Think of this as a map legend, not a scoreboard. It shows where each public claim should point when you want fresh proof without hard-coding counts into the page.
| Signal | Where to look now | Why it is useful in public |
|---|---|---|
| Live stores | Compare Preview, the README orientation path, and the current repository surface | Shows cross-store comparison is grounded in the live product surface without turning this page into a manually updated scoreboard. |
| Compare-first intake | `POST /api/compare/preview` and the Compare Preview page | Makes the first product step easy to explain: compare first, write later. |
| Compare-aware decision loop | `POST /api/watch-groups`, group detail, winner effective price, price spread, and decision reason | Makes it clear that the product can keep several candidates alive instead of collapsing every comparison into one single-link tracker. |
| Product runtime surfaces | Runtime commands plus the WebUI screenshots on this page | Signals that API, worker, and WebUI are all part of the same product story. |
| AI decision support | Compare Preview, group detail, and recovery inbox AI explanation envelopes layered on top of deterministic evidence | Clarifies that the AI story is about explaining and prioritizing evidence, not replacing the product contract. |
| Read-only MCP safe access | `list-tools`, `client-starters`, `serve --transport stdio`, `get_builder_starter_pack`, and the repo-native builder starter pack plus skill cards under `docs/integrations/` | Makes it clear that agent access exists today, but only as a safe observation window. |
| Recommendation boundary | The local runtime Compare Preview plus compare evidence review now carry the shipped recommendation slice, while README and this proof page keep the broader boundary explicit. | Prevents SEO or AI messaging from overstating what the runtime can decide for the user. |
| Public proof guards | Verifier entrypoints listed below plus the branch-protection, workflow, and label surfaces they compare against current GitHub API facts | Shows the public narrative is audited instead of left to drift over time, without this page freezing a brittle checklist snapshot or guessing about remote state. |
Commands that back the product story
If you want to verify the public surface yourself, these are the shortest commands worth running.
Product runtime
PYTHONPATH=src python -m dealwatch server PYTHONPATH=src python -m dealwatch worker
Product smoke
./scripts/test.sh -q ./scripts/smoke_product_hermetic.sh
Public surface guards
python3 scripts/verify_docs_contract.py python3 scripts/verify_public_surface.py python3 scripts/verify_site_surface.py
Read-only MCP surface
PYTHONPATH=src uv run python -m dealwatch.mcp list-tools --json PYTHONPATH=src uv run python -m dealwatch.mcp serve --transport stdio
Remote GitHub truth
python3 scripts/print_remote_repo_settings_checklist.py python3 scripts/verify_remote_github_state.py GITHUB_TOKEN=... python3 scripts/verify_remote_github_state.py
| Verification boundary | What the repo can really prove | What still needs human or admin review |
|---|---|---|
| Repository and API verifiers | They can verify routes, public pages, current remote repository settings exposed by API, required checks including `CodeQL`, expected labels, and the tracked social-preview asset file. With `GITHUB_TOKEN`, they can also confirm the current code-scanning alert count. | They still cannot prove that GitHub is currently using a manually uploaded social preview image. Without credentials, code-scanning alert state also remains a blind spot that needs GitHub UI review. |
| Interpretation layers | Compare Preview exposes score inputs such as title similarity, brand/size signals, product-key signals, and why-like / why-unlike reasons. | Human or AI-written interpretations of those signals are still advisory. Repository checks do not automatically certify their semantic correctness. |
| Recommendation boundary | The repo can prove AI compare explanation, watch-group explanation, recovery guidance, and read-only MCP safe access are implemented today. | The repo now proves a shipped Compare Preview recommendation slice. It still does not prove broader autonomous buy / wait coverage across task, group, MCP, or static public pages. |
Visual proof
The screenshots exist because the UI and routes are already wired, not because the repo needed decoration. The strongest proof path is the same three-step story the product actually follows.
Task detail evidence
Proof that a run becomes something inspectable: price chart, artifact bundle, cashback context, delivery history, and health/backoff state.
Notification control surface
Proof that the alert loop is configurable and visible, and that notification operations are part of the product surface rather than a hidden mail side effect.