@trading-game/design-intelligence-layer 0.8.5

package/docs/personas/trading-game-player-field-guide.md

@@ -0,0 +1,213 @@
+# trading.game — Player field guide
+
+*Who we're writing for. Not personas — modes. The same person cycles through all three.*
+
+Version 1.0 · 2026
+
+---
+
+## The one thing that ties them all together
+
+> "This isn't gambling dressed up in crypto jargon."
+
+Nobody says this sentence out loud. They think it. Constantly. About their own behaviour.
+
+These players are not degenerate gamblers. They are not reckless. They are people with strong opinions about where things go next — markets, matches, prices, events — who have found platforms that let them back those opinions with real money and get an answer fast.
+
+The self-image they're protecting is: *I have good reads.* Not "I got lucky." Not "I enjoy risk." I. Have. Good. Reads.
+
+Every piece of trading.game copy is either reinforcing that self-image or accidentally destroying it. There is no neutral position. Copy that says "your selection was incorrect" destroys it. Copy that says "market moved at the last second" preserves it. The player in both cases lost. What they do next depends entirely on which sentence they read.
+
+---
+
+## Three modes, one player
+
+### Mode 1 — The Edge Seeker
+
+**The self-image sentence:** *"I have an edge. I've done the research."*
+
+This is the player who genuinely believes their read is information-based. They've watched enough charts, followed enough accounts, tracked enough outcomes to feel like they see things the market hasn't priced in yet. They know the Polymarket stat: during the 2024 US election, prediction markets outperformed every major poll. They know this because it confirms something they already believe about themselves — that paying attention is a competitive advantage.
+
+They approach a trade the way the Polymarket Playbook describes catalyst momentum trading: *"Traders with real-time news feeds can enter positions in the first 30 seconds and exit as late-movers pile in."* That's who they think they are. The early mover. The one who saw it first.
+
+In practice, they're usually the retail trader the article was warning against: *"If you're still betting based on gut feelings and Twitter polls, you're exiting liquidity for algorithmic traders."* But they don't know this. And the product doesn't need to tell them. The product needs to give their read a fast resolution and let reality do the rest.
+
+**What they actually say:**
+
+- *"This level has held three times. I'm not guessing, I'm reading the chart."*
+- *"Everyone's fading this but the data says otherwise. I'm taking the other side."*
+- *"Fed catalyst at 2pm. I had my position in before the headline hit Twitter."*
+- *"4 for 5 this week. My read on this setup is getting cleaner."*
+- *"Down today but the process was right. Bad fill, not a bad read."*
+
+That last line. *Down today but the process was right.* This is the most important sentence in the field guide. It is the cognitive move the brain makes to survive a loss without abandoning the system. It separates someone who goes again from someone who uninstalls. trading.game copy needs to hand them this sentence, or a version of it, every time they bust.
+
+**What they brag about:**
+
+Not money. Timing. *"I got in before the move."* Specifically, the moment of being right before other people realise they're wrong. The 10x hit matters less than the fact that they saw it coming. Screenshots go up on X with the chart annotated: *"Flagged this level two days ago. Look at that."*
+
+**What kills the mode:**
+
+Any framing that suggests randomness. If the resolution feels arbitrary — if the line moves in a way that reads as noise, not signal — they don't just lose, they lose trust in the product. They need the mechanic to feel like it responds to real information, even when the underlying feed is synthetic. The chart has to look like a chart. The resolution has to feel like it followed the logic of the market, even when the market is a GBM simulation.
+
+**Copy that works:**
+
+- *"The chart moved. You called it."*
+- *"Rise. Your read, confirmed."*
+- *"Bust. Vol spiked at the last tick. Happens."*
+- *"Still up 3 this week. Keep reading."*
+
+**Copy that kills it:**
+
+- *"Your selection was incorrect."* (removes agency entirely)
+- *"Play again for another chance to win!"* (it's not a chance, it's a read)
+- *"Lucky break!"* (luck is the opposite of edge)
+
+---
+
+### Mode 2 — The System Runner
+
+**The self-image sentence:** *"I'm not just playing. I have rules."*
+
+This player has a spreadsheet, or thinks they do. They've been on Stake or Rollbit. They know the house edge — they can tell you the exact percentage. They've read about martingale. They've tested martingale. They've busted on martingale twice and now have a modified version that caps at three steps, which they believe has eliminated the downside while preserving the upside.
+
+They are not delusional. They understand probability better than most. What they're doing is building a model — a framework that makes the activity feel like engineering rather than gambling. The model is usually wrong. But the act of having a model is what keeps them going, because it means every session is data, not just outcome.
+
+From the Polyburg psychology research: *"Accountability pressure — when people know they'll be held accountable for their decisions, they engage in more thorough information processing."* This player feels accountable to their own system. The system is the thing. Winning validates the system. Losing exposes a flaw in the current version, which needs to be iterated on. They will be back tomorrow with a tighter ruleset.
+
+**What they actually say:**
+
+- *"I go max 3 martingale steps then flat bet. That's the discipline piece most people skip."*
+- *"Down 400 this session but the month I'm still net positive. Variance is part of any system."*
+- *"Provably fair matters. At least I know the edge is fixed and I'm not getting cheated."*
+- *"My win rate over 80 samples on this setup is 63%. That's not a guess, that's a sample."*
+- *"One more to get back to flat. Just one."*
+
+That last line is not a strategy. It is the sound of the loop engaging. It is the most expensive sentence in crypto gambling. trading.game copy should never be the thing that triggers it — but it should absolutely understand that this is what's running in the background.
+
+**What they brag about:**
+
+Session stats. Monthly net figures. System iteration — *"New rules: max 5 steps, not 7. Adjusted after last week."* The public post that says *"Month review: +340 USDT net, 12 winning sessions, 8 losing. Still refining"* is not a win post. It is a system update. The brag is the discipline, not the number.
+
+Also: multipliers, not amounts. *"Hit 200x on a 0.01 stake"* is the screenshot. The absolute return is irrelevant. The multiplier is the story.
+
+**What kills the mode:**
+
+Loss streaks without narrative. Five busts in a row with no contextual copy leaves the brain with nothing to hold onto. *"BUST. BUST. BUST. BUST. BUST."* feels rigged. Each bust needs one line that gives the loss a shape — *"Tight range. Market didn't move."* / *"Vol index pinned at resistance."* — something that makes the loss legible without assigning blame.
+
+Also: withdrawal friction. This community has long institutional memory around platforms that make it easy to deposit and hard to withdraw. It is the single most common Reddit complaint across Stake, Rollbit, and every Deriv-adjacent product. If trading.game makes withdrawal clean and instant, say so explicitly. The bar is low because the competition set it low.
+
+**Copy that works:**
+
+- *"Bust. Market barely moved. Try a different setup."*
+- *"System running? 3-game streak. Keep the rules tight."*
+- *"Withdrawal confirmed. On its way."* (no friction, no delay copy)
+- *"Your stats. 7 trades. 4 wins. 57%."*
+
+**Copy that kills it:**
+
+- *"WIN BIG"* or jackpot language — strips the system frame immediately
+- Any slot aesthetic — visual language that says *this is a casino* breaks the engineering self-image
+- *"Please try again"* — the word "please" is a tell. It sounds like a machine apologising. Systems don't apologise.
+
+---
+
+### Mode 3 — The Public Predictor
+
+**The self-image sentence:** *"I called it. And I can prove it."*
+
+This player's win only counts if someone witnessed it. The prediction is not complete until it is posted. They run a public record — a spreadsheet linked in their bio, a weekly X post, a pinned Discord message. The number that matters is not their balance. It is their running unit total and their public win rate.
+
+From the Polyburg piece: the prediction market creates *"accountability pressure"* that makes people think more carefully. But for this player, the accountability isn't to the money. It's to the audience. They have built an identity around being demonstrably right over time. A single bad week is a variance event. A bad month is a crisis of identity.
+
+They are in esports prediction communities. Fantasy sports leagues. Kalshi. They liked Polymarket before it got too slow and too liquid — when the edge was in being first to a niche market that the crowd hadn't found yet. They are, in the language of every crypto community they've ever inhabited, *early.*
+
+Being early is not a strategy. It is a personality trait that functions as a brand. *"I was on trading.game before anyone knew about it."* That sentence, said six months from now in a Discord, is the first-mover acquisition flywheel. This is the person who tells people. Write for them and the next hundred come for free.
+
+**What they actually say:**
+
+- *"Week 22: 9-5, +3.1 units. Running total since January: +31.2 units. Screenshot below."*
+- *"I had this market at 70% when Kalshi had it at 55%. Took it. It resolved 100%. That's what reading the room looks like."*
+- *"Everyone was on the favourite. I took the value side. Positive EV call even if it doesn't land."*
+- *"Got in on [platform] when nobody knew about it. Already at level 4."*
+- *"My friends bet for fun. I track my record. There's a difference."*
+- *"Statistically it happens. Still a good bet at those odds."* (loss framing)
+
+That last line is the prediction market version of *"direction was right, timing was off."* It is the self-image protection sentence for someone who thinks in probability. They didn't lose. The low-probability outcome materialised. The decision was still correct given the information available. The market just disagreed this once.
+
+**What they brag about:**
+
+The public record above everything. Long shot calls that landed. Being early to a platform or a market. The specific mechanic of a near-win that they survived — *"55.50, I needed 55.51, I had under, I won."* The granularity of that number is the whole point. It proves they were paying attention.
+
+They share results through the product's own UI. The result card, the streak, the win state — these are designed content. If the screenshot of a trading.game result is ugly or generic, it won't get posted. The result screen is a distribution channel.
+
+**What kills the mode:**
+
+Generic copy on win and loss states. *"Well done!"* means nothing to someone who just called a five-tick streak. The win state should acknowledge the specific mechanic. *"5-tick streak. Vol moved exactly where you said."* is a sentence they will screenshot. *"You won! Claim your reward."* is not.
+
+Also: anything that makes them feel like a beginner. Tutorial prompts, explanatory overlays mid-game, onboarding copy that explains how markets work — all of this is an insult. They know how markets work. They've been tracking them since before trading.game existed.
+
+**Copy that works:**
+
+- *"Called it. +1,250 USDT. 5-tick streak."*
+- *"You were early on that move. Vol 75 confirmed."*
+- *"Streak: 7. Post this."* (literal invitation to share)
+- *"Bust. Still 6 from 9 today. Record stands."*
+
+**Copy that kills it:**
+
+- *"Great job!"* — kindergarten energy
+- *"You're getting the hang of this!"* — implies they didn't already have it
+- Generic push notification: *"A new game is available."* — means nothing to someone building a documented track record
+
+---
+
+## Where the modes bleed together
+
+The same player, in a single session:
+
+Opens the app in Edge Seeker mode — *"I've been watching this vol index all week, I have a read."* Places three trades. Wins two. Third one busts. Drops into System Runner mode — *"Okay, variance. My system long-term is positive. One more."* Wins the fourth. Screenshots it. Posts it in Mode 3 with the caption: *"Back to even. System held."*
+
+That is one person. One session. Three modes.
+
+The copy implication: every state needs to be written to land across all three simultaneously. *"Bust. Market moved at the last tick."* gives Mode 1 a narrative (the market, not their read). Tells Mode 2 the system wasn't broken (external event). Lets Mode 3 post *"Bust but you can see the vol spike at the exact moment, setup was right"* without embarrassment.
+
+One sentence. Three self-images intact. Player goes again.
+
+---
+
+## The near-miss — the mechanic no one talks about
+
+This applies in all three modes.
+
+When the price lands 0.01 from the target — when the dice rolls 55.49 and they needed 55.50 — the brain does not register a loss. It registers *I was right and the resolution was imprecise.* This is neurologically distinct from a clean loss. The near-miss is more motivating than a win, because a win ends the tension. A near-miss keeps it alive.
+
+The animation of the resolution — the line landing one tick short, the number stopping just before the target — is not a UX detail. It is the single most powerful retention mechanic in the product. It should be treated with the same deliberateness as any major feature.
+
+Copy for near-miss states should never say the player was wrong. They almost weren't.
+
+- *"One tick short. The read was right."*
+- *"55.49. You had 55.50. Next one."*
+- *"Close. Vol reversed at the last second."*
+
+---
+
+## What trading.game is selling, in their language
+
+Not their words. Theirs.
+
+| What the product is | What the player calls it |
+|---|---|
+| A synthetic GBM price feed | *"A live market"* |
+| A 50/50 binary outcome | *"My read, tested"* |
+| A house edge of 2% | *"Known edge. Provably fair."* |
+| A 5-tick resolution | *"Fast feedback on the call"* |
+| A streak counter | *"My record"* |
+| A win state | *"Called it"* |
+| A loss state | *"Market moved. Next one."* |
+
+The product doesn't have to lie about what it is. It just has to use the player's language for it. They are not playing a synthetic random number game. They are testing a read against a live market. The first sentence feels like gambling. The second feels like trading.game.
+
+---
+
+*trading.game Player Field Guide — v1.0. Use alongside the Content Style Guide when writing any player-facing copy. These are not character studies — they are the modes the player is in when they read what you write.*

package/docs/rules/design-system-consuming-project.mdc

@@ -0,0 +1,208 @@
+---
+description: Enforce correct usage of the @trading-game/design-intelligence-layer npm package. Apply whenever building UI in a project that has the package installed — before writing any component, layout, or styled element.
+globs: ["**/*.tsx", "**/*.jsx", "**/*.ts", "**/*.css"]
+alwaysApply: true
+---
+
+# @trading-game/design-intelligence-layer — AI Agent Usage Rules
+
+## Rule 1 — Check the package before writing any custom UI
+
+**BEFORE** writing any `<div>`, `<button>`, `<span>`, or other element styled with Tailwind classes, you MUST check if a component already exists in `@trading-game/design-intelligence-layer`.
+
+### Available components (check this list first)
+
+Accordion, Alert, AlertDialog, Avatar, AvatarGroup, Badge, Breadcrumb, Button, Calendar, Card, Carousel, Chart, Checkbox, Collapsible, Combobox, Command, ContextMenu, Dialog, Drawer, DropdownMenu, EmptyState, Field, Form, HoverCard, Input, InputGroup, InputOTP, Item, Kbd, Label, Menubar, NativeSelect, NavigationMenu, Pagination, Popover, Progress, RadioGroup, Resizable, ScrollArea, Select, Separator, Sheet, Sidebar, Skeleton, Slider, Spinner, Switch, Table, Tabs, Textarea, Toast/Toaster, Toggle, ToggleGroup, Tooltip
+
+### Decision flow
+
+```
+Does a component exist in the list above?
+  YES → Import it from @trading-game/design-intelligence-layer. Do NOT re-implement it.
+  NO  → STOP. Tell the user:
+        "The [ComponentName] component does not exist in @trading-game/design-intelligence-layer.
+         Options:
+         (a) Build a custom one using design system tokens only
+         (b) Use a different existing component
+         (c) Skip this component"
+        Wait for user to choose. Do NOT proceed without confirmation.
+```
+
+### Correct import pattern
+
+```tsx
+import { Button, Card, Badge } from "@trading-game/design-intelligence-layer"
+```
+
+---
+
+## Rule 2 — Token-only rule (applies to ALL code, including approved custom builds)
+
+### Never use
+
+```
+❌ Hardcoded hex:         #2323FF, #000000, rgba(0,0,0,0.5)
+❌ Raw Tailwind palette:  bg-gray-100, text-zinc-500, text-slate-400, bg-black, bg-white
+❌ Arbitrary color:       bg-[#EEEEEE], text-[rgba(35,35,255,0.1)]
+❌ Raw CSS var:           bg-[var(--border-subtle)]  ← NEVER do this
+❌ hsl(var()) syntax:     hsl(var(--primary))  ← this is Tailwind v3, not v4
+❌ Raw opacity on non-tokens: bg-black/50
+```
+
+### Always use semantic token classes
+
+#### Background tokens
+```
+✅ bg-background          — page background (white #FFFFFF)
+✅ bg-card                — card/panel surface (white #FFFFFF)
+✅ bg-popover             — popover/dropdown surface (white #FFFFFF)
+✅ bg-subtle              — subtle tinted surface (#F5F5F5)
+✅ bg-overlay             — modal/dialog backdrop (black 50%) — ONLY for overlays
+✅ bg-primary             — brand blue #2323FF — CTAs and primary actions
+✅ bg-primary-hover       — darker blue #0B0BD2 — primary button hover
+✅ bg-secondary-hover     — light grey #EEEEEE — outline/secondary button hover
+✅ bg-semantic-win        — green — profit/positive
+✅ bg-semantic-loss       — red — loss/negative
+```
+
+#### Text tokens
+```
+✅ text-on-prominent                — primary text (black #000000)
+✅ text-on-prominent-static-inverse — always white — for text on dark/primary bg
+✅ text-on-subtle                   — secondary text (mid grey)
+✅ text-on-muted                    — low emphasis text (dark grey)
+✅ text-primary                     — brand blue #2323FF
+✅ text-semantic-win                — green — profit/positive
+✅ text-semantic-loss               — red — loss/negative
+```
+
+#### Border tokens
+```
+✅ border-border-subtle    — light grey #EEEEEE — default UI borders, dividers, cards
+✅ border-border-prominent — pure black #000000 — outline variant components
+✅ border-border           — @deprecated alias for border-subtle (still works, prefer border-border-subtle)
+✅ border-input            — input field borders (same value as border-subtle)
+✅ ring-ring               — focus ring (blue #2323FF)
+```
+
+#### Opacity on a token is fine
+```
+✅ bg-primary/20, border-border-subtle/50, ring-ring/10
+```
+
+---
+
+## Rule 3 — Layout utilities are exempt
+
+Structural Tailwind utilities are freely usable without token rules:
+
+```
+✅ flex, grid, gap-4, p-6, m-2, w-full, h-screen, max-w-lg
+✅ z-50, overflow-hidden, opacity-50, transition-all
+✅ col-span-2, items-center, justify-between
+```
+
+Token rules apply **only** to: color (bg, text, border, ring, shadow color), border radius, and font family.
+
+---
+
+## Rule 4 — Do NOT install or configure these separately
+
+```
+❌ Do NOT install lucide-react — it is already bundled in the package
+❌ Do NOT install tailwindcss separately — the package ships its own Tailwind v4 setup
+❌ Do NOT add a tailwind.config.js — configuration is handled by the package
+❌ Do NOT use @apply with hsl(var(--token)) — Tailwind v4 uses CSS variables directly
+❌ Do NOT override font-family manually in CSS — use font-display and font-body utility classes
+```
+
+### Correct CSS setup in the consuming project
+
+```css
+@import "@trading-game/design-intelligence-layer/styles";
+@import "tailwindcss";
+@source "../node_modules/@trading-game/design-intelligence-layer/dist";
+```
+
+### Vite projects — required plugin
+
+If the project uses Vite, `@tailwindcss/vite` MUST be in `vite.config.js`:
+
+```js
+import tailwindcss from '@tailwindcss/vite'
+// plugins: [react(), tailwindcss()]
+```
+
+Without this, Tailwind CSS will not process any styles. Next.js projects do NOT need this.
+
+---
+
+## Rule 5 — Button and Badge variants
+
+### Button variants
+```tsx
+<Button variant="primary" />    // Blue filled — main CTA
+<Button variant="secondary" />  // Black outline, white bg — secondary actions
+<Button variant="tertiary" />   // Text only, underline on hover — minimal
+```
+
+### Badge variants
+```tsx
+// Solid
+<Badge variant="default" />         // Blue solid
+<Badge variant="default-success" /> // Green solid
+<Badge variant="default-fail" />    // Red solid
+
+// Tint
+<Badge variant="fill" />            // Blue tint bg
+<Badge variant="fill-success" />    // Green tint bg
+<Badge variant="fill-fail" />       // Red tint bg
+
+// Outline (black border, hover grey)
+<Badge variant="outline" />
+
+// Ghost (transparent bg)
+<Badge variant="ghost" />
+<Badge variant="ghost-success" />
+<Badge variant="ghost-fail" />
+```
+
+---
+
+## Rule 6 — If in doubt, stop and ask
+
+If you cannot find a token for a value you need, do NOT fall back to a hardcoded value.
+
+Stop and tell the user:
+```
+"I need [value] for [element]. No design token exists for this.
+Should I: (a) use a hardcoded value, or (b) skip this styling?"
+```
+
+Wait for confirmation before proceeding.
+
+---
+
+## Rule 7 — Package version upgrades (stay aligned with the published design system)
+
+When the user asks to **update**, **upgrade**, or **install the latest** `@trading-game/design-intelligence-layer`, or after the dependency version changes in `package.json`:
+
+### How updates actually apply
+
+- If the project **imports components only** from `@trading-game/design-intelligence-layer`, new styles and behavior come from **`node_modules/.../dist`** after **`npm install` / `npm ci` and a dev or production build**. The package is the source of truth — no AI step is required for those imports to change.
+- If the repo **contains copied or forked** files that mirror package components (e.g. a local `components/ui/button.tsx` with full implementation), **`npm install` does not update those files.** They stay stale until someone reconciles them.
+
+### What you MUST do after a design-system version bump
+
+1. **Search for local duplication** — Look for UI files that re-implement package exports (`components/ui/`, `@/components/ui`, etc.). Flag any file that is not a **thin re-export** or **documented wrapper** around the package.
+2. **Reconcile** — Prefer **removing** duplicate implementations and **importing from the package**. If a fork must stay, align it with the **exact** current implementation in the installed package (or tag on GitHub) and document why it diverges (file name + reason).
+3. **Notify on replace** — If you **delete, replace, or substantially overwrite** local component code to match the package, **stop and tell the user clearly**, e.g.  
+   `Aligned [ComponentName] with @trading-game/design-intelligence-layer@[version]. Previous local behavior or classes: [short summary]. Re-apply needs via package variants/props, tokens, or a thin wrapper only if product requires it.`
+4. **Review `className` overrides** — Parent apps often pass `className` on DS components. Old overrides (radius, colors, shadows) can **hide** new defaults (e.g. pill buttons). After upgrade, scan for overrides on DS components and trim or adjust them when they conflict with the new design.
+5. **Refresh Cursor rules** — The package ships `docs/rules/design-system-consuming-project.mdc`. Cursor does **not** read it from `node_modules` automatically. Tell the user to re-copy it (see README **AI Agent Setup → Cursor**) so agent instructions match the release.
+6. **Tailwind** — Confirm `@source` still points at `node_modules/@trading-game/design-intelligence-layer/dist` so Tailwind v4 emits classes from the updated bundle.
+
+### Do not assume
+
+- Do **not** assume `npm update` alone fixed forked files in the app repo.
+- Do **not** silently delete user customizations — always report what was removed or replaced and offer a token-safe way to re-apply if needed.