Imported from keskinonur/shelfgap (AGENTS.md). Install upstream with npx skills add keskinonur/shelfgap. Copyright stays with the author.

ShelfGap repository instructions

Mission

Build ShelfGap, an evidence-backed buyer decision simulator for small e-commerce merchants.

A merchant supplies normalized offer facts and buyer profiles or selects the built-in fictional sample. ShelfGap compares the merchant product and offer against exact-product resellers and alternative products. It evaluates them from several buyer perspectives, explains why the merchant wins or loses, and recommends the smallest feasible merchandising actions that could improve selectability.

The product must never claim guaranteed sales uplift, market share, or the globally lowest price.

Non-negotiable product principles

• Separate Product, Offer, and BuyerContext.
• Treat public listing data as time-sensitive evidence, not permanent truth.
• Mark every extracted value as observed, inferred, or unknown.
• Preserve source URL, evidence snippet, observation timestamp, and confidence.
• Distinguish exact-product offers from alternative products.
• Apply hard buyer requirements before preference scoring.
• Treat an unknown mandatory attribute as uncertain, not false.
• Calculate effective purchase cost from observable price, shipping, fees, and immediately usable discounts.
• Apply membership benefits only when the buyer profile has that active membership.
• Explain every score using visible components.
• Generate recommendations only from computed choice gaps and cited evidence.
• Require merchant approval before any simulated or real change.
• Keep fictional brands and neutral marketplace labels in the built-in demo.
• A more specific category recommendation must remain truthful and taxonomically valid.

Scope discipline

P0:

• Built-in fictional demo with no API key and no network dependency.
• Real user-supplied offer and buyer-profile analysis with no network dependency.
• Four buyer profiles plus a custom profile editor.
• Exact-offer and alternative-product comparisons.
• Deterministic eligibility, scoring, win-rate, gap analysis, and action cards.
• Before/after simulation for approved actions.
• Unit, integration, and one happy-path browser test.
• Clear README and demo instructions.

P1:

• Host-model normalization and evidence-grounded explanation.
• Optional private-deployment URL fetch and JSON-LD/Open Graph extraction for authorized URLs.
• Live web-search-assisted candidate discovery with source evidence.
• Exportable Codex change pack.

P2:

• Embedded Codex SDK application to a controlled demo storefront.
• Marketplace adapters, authentication, persistence, or merchant platform write-back.

Do not implement P2 until all P0 acceptance criteria pass.

Default stack

Use a single TypeScript repository unless an existing scaffold dictates otherwise.

• Next.js App Router
• React
• TypeScript with strict mode
• Tailwind CSS
• Zod
• ChatGPT host model through the MCP app; no backend OpenAI API calls
• Vitest for unit/integration tests
• Playwright for the critical browser flow
• pnpm for package management

Avoid adding a database for the hackathon MVP. Use typed fixtures, server responses, and browser local storage where persistence is helpful.

Use the current stable versions compatible with one another. Do not pin obsolete versions merely because they appear in model memory.

Expected scripts

Ensure package.json exposes these commands:

• pnpm dev
• pnpm build
• pnpm lint
• pnpm typecheck
• pnpm test
• pnpm test:e2e
• pnpm check running lint, typecheck, unit tests, and build

Architecture rules

• Domain logic must live outside React components.
• Scoring and eligibility must be deterministic pure functions.
• OpenAI calls must be isolated behind typed service interfaces.
• External fetching must be isolated behind a safe-fetch adapter.
• UI components consume view models rather than raw model output.
• Validate all model and network data with Zod at boundaries.
• Do not use an LLM to perform arithmetic, currency calculations, eligibility, or final ranking.
• Do not execute model-generated code.
• Keep demo fixtures immutable and versioned.
• Add concise comments only where the reason is not obvious.

OpenAI usage

• The current ChatGPT host model runs in the conversation after the ShelfGap MCP app is enabled.
• The ShelfGap backend must not call the OpenAI Responses API and must not require OPENAI_API_KEY.
• Use structured Zod-backed tool results and host-model instructions for explanation and localization.
• Preserve returned source information and expose it in evidence views.
• Do not present model inference as observed fact.
• Keep deterministic fallback behavior for the sample analysis.

Safe URL fetching

URL extraction is disabled on the public app. For an explicitly enabled private deployment:

• Accept only http: and https:.
• Reject localhost, loopback, link-local, private, multicast, and reserved IP ranges for both IPv4 and IPv6.
• Resolve and re-check every redirect target.
• Limit redirects.
• Enforce a short timeout.
• Limit response bytes.
• Accept HTML and JSON only.
• Do not forward user cookies, authorization headers, or arbitrary headers.
• Do not bypass paywalls, login walls, robots restrictions, or membership controls.
• Surface unsupported pages honestly.

Data and scoring

Implement the contracts in docs/PRODUCT_SPEC.md and docs/ARCHITECTURE.md.

The score must expose:

• feature fit
• effective cost fit
• delivery fit
• trust fit
• returns and warranty fit
• convenience fit

Weights are buyer-profile-specific and must sum to 1. Clamp component scores to 0–100.

Rank:

1. eligible offers
2. uncertain offers
3. ineligible offers

Stable tie-breaking must be deterministic and documented.

UX requirements

• The main path must be understandable in under three minutes.
• The first screen offers the sample workspace and ChatGPT connection path.
• Never require authentication for the sample.
• Show progress by pipeline stage.
• Show product groups separately: same product, direct alternatives, and excluded candidates.
• Show the merchant offer clearly.
• Show evidence and uncertainty beside findings.
• Action cards must contain: finding, exact change, evidence, mechanism, confidence, effort, caveat, and affected buyer scenarios.
• A before/after simulator must state that results are simulated, not predicted conversion.
• Provide loading, empty, unsupported, API failure, and retry states.
• Use responsive desktop-first design.
• Meet basic keyboard navigation and contrast expectations.

Verification protocol

For each milestone:

1. Inspect existing code and documentation first.
2. State the files likely to change.
3. Implement the smallest coherent slice.
4. Run the narrowest relevant tests during development.
5. Run pnpm check before declaring the milestone complete.
6. Run the relevant Playwright path for user-visible behavior.
7. Update docs/PROGRESS.md.
8. Summarize changed files, commands run, results, assumptions, and remaining risks.
9. Do not claim success when a command did not run or failed.

Do not silently weaken tests to make them pass.

Git protocol

• Work in a Git repository.
• Keep commits milestone-scoped.
• Do not rewrite user-authored history.
• Do not commit .env, credentials, generated browser traces, or secrets.
• Before large changes, create a checkpoint commit.
• Use /review or an equivalent review pass before milestone commits.
• Preserve the primary Codex chat for the majority of core work so its session can be submitted as build evidence.

Documentation requirements

Maintain:

• README.md
• docs/PROGRESS.md
• docs/ARCHITECTURE.md
• docs/DECISIONS.md
• docs/CODEX_COLLABORATION.md

The README must explain:

• the problem and audience
• the buyer decision model
• how the ChatGPT host model is used
• how Codex was used
• local setup and test commands
• sample mode
• live-mode limitations
• safety and data caveats
• deployment URL and judging path when available

Stop conditions

Pause and report instead of improvising when:

• an external API requires credentials not present
• a requested integration conflicts with its terms
• a live page cannot be safely or reliably extracted
• a dependency introduces a material security or deployment problem
• a product claim cannot be supported by evidence
• P0 is not passing and the next work is P1 or P2

Make reasonable implementation choices without asking about routine details. Record important assumptions in docs/DECISIONS.md.