Skip to content

Redesign the README: dashboard walkthrough, verified heuristics and honest status - #4

Merged
operatoruplift merged 4 commits into
mainfrom
claude/readme-redesign
Oct 31, 2026
Merged

operatoruplift merged 4 commits into
mainfrom
claude/readme-redesign

Conversation

@operatoruplift

@operatoruplift operatoruplift commented Oct 30, 2026 •

Copy link
Copy Markdown
Owner

What changed

The README now follows the house style of the allowance pilot, and every claim in it was checked against the code. Several claims in the old README did not hold up:

  • Header: a banner from the real dashboard, three buttons (the demo, the Bazaar demo kept from the old README, the six heuristics), the demo status badge plus stack badges, a one-line promise, the Load → Audit → Rank → Explain → Preview loop, and section links.
  • Screens card: the dashboard before an audit and after Run Audit with an AI Thinking panel open, rendered for light and dark themes. The caption notes that this build uses demo data and that the "Shopify Connected" label is static.
  • How it works: a Store data → Margin engine → Dashboard flow card, the fixed assumptions the math uses, and three cells (deterministic, shows its work, ready for Shopify but not wired to it).
  • The six heuristics: the old table, corrected against marginAnalyzer.ts. The table now has the exact triggers, the per-SKU MEDIUM alerts from heuristic 1, and what each heuristic proposes. On the demo seed they produce 10 cards.
  • Status: HACKATHON, DEMO DATA and API ONLY, each linked to the file that shows it.
  • Run it locally: the old quick start, checks, the environment variables (now in a real .env.example) and a curl example for the discount route. The API routes, the Mermaid diagram (corrected) and the repository layout moved into collapsible sections.

Removed or corrected, and why:

  • The MIT badge and the "License: MIT" section: the repository has no LICENSE file, so the link was dead. If MIT is intended, add the file.
  • "Connects to your live Shopify store" and "We integrated Store 30's live data": every data and analysis route imports src/lib/mockShopifyData.ts, a seed built to trigger all six heuristics.
  • "Vercel Edge" and "in under 50ms, on the edge": the routes do not set an edge runtime, and no timing was measured. The three data routes also add a 400 ms simulated delay.
  • "Click Deploy Fix → Active in Shopify in 2 seconds": executeAction in src/app/page.tsx plays timed log lines, shows a client-built payload and appends "200 OK, Discount code is now live in Shopify" without making any request. The real discountCodeBasicCreate call lives in POST /api/shopify/discount, which nothing in the UI calls.
  • The "Why This Makes Money" table ($12,000+ trapped, $800+/mo, $99/mo pricing, 8:1 ROI, 4.6M+ stores): pitch figures with no source in the repository.

Fixes (separate commits):

  • Added .env.example with SHOPIFY_STORE_URL and SHOPIFY_ACCESS_TOKEN, with comments and no values. Added !.env.example to .gitignore, because the .env* rule would otherwise hide the file.
  • Added description, homepage and repository to package.json. The package name hackathon-1 was left as it is.

All images live in docs/readme/ (five PNGs, about 0.72 MB). They were captured from a local production build (pnpm build, then next start) with the bundled demo data.

Checks

  • pnpm install --frozen-lockfile: installed. pnpm ignored the msw build script, as configured.
  • pnpm exec tsc --noEmit: passed. I re-ran it after the package.json change.
  • pnpm build: passed (Next.js 16.2.1, Turbopack). It produced 11 static pages, including / and /landing, plus 6 dynamic API routes.
  • pnpm lint: failed with 2 errors and 3 warnings, which I did not fix because the fixes change component behavior. Both errors are react-hooks/set-state-in-effect, at src/app/page.tsx:269 and src/components/ui/animated-grid-pattern.tsx:90. The warnings are two missing useCallback dependencies (AUDIT_LOG_LINES, EXEC_LOG_STEPS) and an unused variable at src/app/page.tsx:2228.
  • There is no test suite and no CI workflow.
  • README check: no broken relative links or anchors, alt text on every image, no em or en dashes. I also reviewed a rendered preview in light and dark. The demo and Bazaar links could not be opened from this session, so I kept them as the owner wrote them.

Observed in the product, not changed

These are product behavior, so they are left for you:

  1. The UI font never loads. src/app/globals.css sets --font-sans: var(--font-sans);, which references itself. The Geist font from layout.tsx is therefore never applied, and the dashboard renders in the browser's default serif (visible in the screenshots). The one-line fix is --font-sans: var(--font-geist-sans);.
  2. Deploy Fix is simulated, as described above. If it should stay a demo, a "simulation" label in the sheet would keep it honest. To make it real, call /api/shopify/discount and show its source field.
  3. The discount mutation applies to the whole store. It sets customerGets.items: { all: true }, so the "Dead Stock Clearance" code covers every product, not just the flagged SKU. The title and code are also interpolated straight into the GraphQL string, so a quote in a product title breaks the mutation. GraphQL variables would fix both.
  4. The audit modal and landing page show scripted claims. The audit log prints "Initializing Prime Intellect compute node", "GPU: A100-80G" and "Ingesting 5,000 Shopify rows", but the analysis is in-process arithmetic over 8 products and 25 orders. The landing page's "50ms analysis time", "Zero Hallucinations" and "8:1 ROI in the first month" are not measured, and the reasoning templates quote hard-coded benchmarks (Narvar, Shopify Plus, "historical A/B data").
  5. Leftover template files. public/ still has the unused create-next-app SVGs (file, globe, next, vercel, window).

Suggested repository settings

These live outside the code, so they are not in this PR:

  • Description (the current one has an em dash and claims "1-click GraphQL execution", which the dashboard only simulates): Margin Protector AI: a Shopify profit-leak audit dashboard with six deterministic margin heuristics and the math behind every fix. Next.js 16, React 19, Tailwind CSS 4.
  • Topics: keep the current ones and add shopify-admin-api and dashboard.
  • Social preview: upload docs/readme/banner.png (2400 × 1200) under Settings → General → Social preview.
  • License: this public repository has no LICENSE file. The old README said MIT; adding the file is your call.

Update: license added

This PR now also adds an MIT LICENSE (Copyright Operator Uplift), the license the owner's other public repositories use (allowance, cold, UI, webview). The README shows a license badge, the footer says what the license covers, and package.json declares it. This is what the original README's MIT badge already claimed, now backed by a real file. This resolves the missing-license note above.

https://claude.ai/code/session_01TZhsuWjATuivuiFYJGpbY5


Generated by Claude Code

- Add a banner, a two-step dashboard walkthrough and a flow card in
  docs/readme, captured from a local production build
- Describe the demo seed, the six heuristics and their fixed assumptions
  as the code implements them
- Say plainly that Deploy Fix is a scripted preview and that only
  POST /api/shopify/discount can reach Shopify, when configured
- Drop the MIT badge and section (there is no LICENSE file), the edge
  runtime and live-store claims, and the unverifiable revenue figures

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01TZhsuWjATuivuiFYJGpbY5
- List SHOPIFY_STORE_URL and SHOPIFY_ACCESS_TOKEN with comments, no values
- Un-ignore .env.example, which the .env* rule would otherwise hide

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01TZhsuWjATuivuiFYJGpbY5
@vercel

vercel Bot commented Oct 30, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
marginprotectorai Ready Ready Preview Oct 31, 2026 1:55am UTC

Request Review

- LICENSE: MIT, Copyright Operator Uplift, the license the owner's
  other public repositories use
- README: a license badge, and the footer now says what it covers
- package.json: the license field, where the repo has one

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01TZhsuWjATuivuiFYJGpbY5
@operatoruplift
operatoruplift merged commit d73d5be into main Oct 31, 2026
2 checks passed

This branch was successfully deployed

1 active deployment
Preview — a1f032eb Deployed Oct 31, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants