ShelfGap Buyer Lens

ShelfGap is a deterministic buyer-choice simulator inside ChatGPT. It compares one merchant offer with user-supplied alternatives across explicit buyer profiles, explains why the merchant wins or loses, and tests the smallest merchant-controlled change worth trying next.

The public app is read-only. It does not crawl marketplaces, require marketplace credentials, mutate listings, or predict sales.

Why it exists

ShelfGap started on a family trip through Warsaw and Krakow. We speak Turkish and English, but unfamiliar Polish labels, delivery promises, and seller signals still made confident comparison difficult. We did what people already do: we asked ChatGPT. We did not want another app or account just to choose an offer.

Then we recognized the same decision from the merchant side. People we know run online stores without writing code or using command-line tools. They still need to answer one practical question: why did the buyer choose the other offer? ChatGPT is already an interface they know, so ShelfGap brings the analysis there.

• Buyer: "Which offer fits me?"
• Merchant: "Why did they choose the other one?"

ShelfGap sits between those questions.

What it does

The core distinction is that the product and the offer are different things. The same product can win through one seller and lose through another because buyers evaluate the product together with shipping cost, delivery time, warranty, returns, seller trust, and checkout convenience.

For each buyer context, ShelfGap:

• applies hard requirements before preference scoring;
• ranks the merchant, exact-product resellers, and direct alternatives;
• exposes the score components and evidence gaps behind the choice;
• distinguishes a product win from a merchant-offer win;
• recommends a small, controllable merchant test;
• recomputes the result after approved what-if changes.

Missing evidence remains unknown: it is never silently treated as false or assumed true. Results are simulated choices for the supplied buyer contexts, not conversion, revenue, demand, or market-share forecasts.

OpenAI Build Week 2026

• Category: Work & Productivity
• Devpost: ShelfGap Buyer Lens
• Demo video: ShelfGap: Buyer Intelligence Inside ChatGPT
• Live judge path: shelfgap.onurkeskin.com/demo
• Build brief: shelfgap.onurkeskin.com/architecture
• Test requirements: no account, API key, marketplace credential, or rebuild
• Sample: deterministic fictional Northstar 750 market, with an asserted 1/4 merchant-win baseline and 3/4 result after the three approved actions

The repository was created during the Build Week submission period. The ready-to-paste project copy, video plan, and final owner checks are in docs/HACKATHON_SUBMISSION.md, docs/DEMO_SCRIPT.md, and docs/HACKATHON_CHECKLIST.md.

Public MCP tools

• shelfgap.analyze_offers validates supplied offer and buyer-profile facts, then computes eligibility, weighted fit, rank, choice gaps, and next-test recommendations.
• shelfgap.simulate_offer_changes applies explicit what-if changes to the merchant offer and returns a deterministic before/after comparison.
• shelfgap.load_sample loads the fictional Northstar bottle market so a new user can inspect a complete result before supplying data.

All three tools are read-only, non-destructive, and return a compact Buyer Lens widget. The widget consumes the actual tool result instead of relying on a hard-coded product.

Language behavior

ShelfGap 1.1 supports English and Turkish MCP results and widget labels. Every tool accepts an optional responseLocale BCP 47 tag for the current prompt language; it takes precedence over the Apps SDK _meta["openai/locale"] client locale (tr-TR maps to tr). The server echoes the matched locale in result.locale and falls back to English for unsupported or missing locales. ChatGPT is instructed to explain the result in the language of the user's current prompt, including languages that are not yet natively localized by ShelfGap.

Scoring model

ShelfGap evaluates hard eligibility before ranking. Eligible offers rank ahead of uncertain offers, and uncertain offers rank ahead of ineligible offers. Within those groups, the engine scores:

• verified feature fit;
• effective delivered cost;
• delivery fit;
• seller and authenticity trust;
• warranty and return policy;
• checkout, membership, and pickup convenience.

Unknown required evidence creates uncertainty. A privately known merchant attribute is not treated as public until an explicit what-if change exposes it.

Local setup

Supported local platforms: macOS or Linux with Node.js 22+, pnpm 11, and a Chromium-compatible Playwright runtime. Docker is optional.

corepack enable
pnpm install --frozen-lockfile
pnpm check
pnpm test:e2e
pnpm test:mcp

Run the website and MCP server through Docker Compose:

docker compose up --build

Local routes:

• Website: http://localhost:8080/
• Sample workspace: http://localhost:8080/demo
• Health: http://localhost:8080/healthz
• MCP endpoint: http://localhost:8080/mcp
• MCP health: http://localhost:8080/mcp/healthz

The sample data is versioned in packages/fixtures and requires no external service. The deterministic contract is asserted in packages/core/test/demo-contract.test.ts.

The optional URL metadata extractor is disabled by default. It is not part of the public ShelfGap app and must only be enabled in a private deployment for URLs the user is authorized to analyze.

Hosted app

• Website: https://shelfgap.onurkeskin.com/
• Live sample: https://shelfgap.onurkeskin.com/demo
• Build brief: https://shelfgap.onurkeskin.com/architecture
• MCP: https://shelfgap.onurkeskin.com/mcp
• Privacy: https://shelfgap.onurkeskin.com/privacy
• Terms: https://shelfgap.onurkeskin.com/terms
• Support: https://shelfgap.onurkeskin.com/support

The public ChatGPT plugin publishing path is separate from the hackathon and intentionally deferred. Developer-mode connection remains available through docs/MCP_INSTALLATION.md, but judges do not need it to test the product.

Safety boundaries

• No user accounts, OAuth flow, application database, analytics SDK, marketplace login, or OpenAI API key.
• Tool payloads are processed in memory and are not written to application storage.
• Claims, prices, policies, and buyer requirements are supplied inputs; ShelfGap does not independently verify them.
• Results are scenario comparisons, not conversion, demand, revenue, or market-share forecasts.
• Structured tool schemas bound string length, offer count, buyer count, and per-call analysis work.
• MCP request bodies, JSON-RPC batches, concurrent streams, and stream lifetimes are bounded by application controls; the deployment edge also enforces rate and in-flight limits without buffering streaming responses.
• The production web build pins patched Next.js and React releases and disables the unused image optimizer.

GPT-5.6 and Codex

ShelfGap uses two deliberately separate layers:

• GPT-5.6 owns the conversation. It selects and calls the read-only MCP tool, explains the structured result, and responds in the language of the user's prompt.
• The TypeScript engine owns the decision. Eligibility, arithmetic, ranking, choice gaps, and what-if simulations are deterministic pure logic. The model does not calculate scores or invent uplift.

Codex built the implementation from the supplied product handoff: monorepo, contracts, scoring engine, website, MCP app, Buyer Lens widget, tests, Docker deployment, localization, production verification, and submission preparation. The collaboration log records what was delegated, what required correction, and which decisions remained human-owned in docs/CODEX_COLLABORATION.md.