feat: preview → main (v0.2.0)

feat: preview → main (v0.2.0)

Author: phucbm

.claude/CLAUDE.md

@@ -25,10 +25,10 @@ When asked to "edit local api repo" → work in `../api`. "edit local mcp repo"
 - Storybook: `pnpm storybook` → http://localhost:4000
 
 ## Core principles
-1. **Vercel deployment** — SSR/SSG via Vercel. Dynamic routes allowed. Data fetched at build time where possible.
-2. **Local-first** — wallet data in IndexedDB via Dexie.js. No server accounts.
-3. **Vietnamese-first** — UI/content targets Vietnamese users. Technical terms stay English.
-4. **SEO-first** — every public page has JSON-LD, OG metadata, sitemap entries.
+1. **Vercel deployment** - SSR/SSG via Vercel. Dynamic routes allowed. Data fetched at build time where possible.
+2. **Local-first** - wallet data in IndexedDB via Dexie.js. No server accounts.
+3. **Vietnamese-first** - UI/content targets Vietnamese users. Technical terms stay English.
+4. **SEO-first** - every public page has JSON-LD, OG metadata, sitemap entries.
 
 ## ISR revalidation (required for all marketing pages)
 
@@ -38,7 +38,7 @@ Every `app/(marketing)/**/page.tsx` that calls any API fetch **must** export:
 export const revalidate = 3600;
 ```
 
-Without this, pages are pure dynamic SSR — every request hits the API live. On Vercel, a slow or cold API response causes a function timeout → error page. With `revalidate`, Vercel pre-renders at build time and serves cached HTML, revalidating in the background. Reload-fixes-it is the symptom of a missing `revalidate`.
+Without this, pages are pure dynamic SSR - every request hits the API live. On Vercel, a slow or cold API response causes a function timeout → error page. With `revalidate`, Vercel pre-renders at build time and serves cached HTML, revalidating in the background. Reload-fixes-it is the symptom of a missing `revalidate`.
 
 ## Breadcrumbs
 
@@ -65,8 +65,8 @@ Pages currently missing breadcrumbs (add when touching): `dieu-khoan`, `docs`, `
 See `@.claude/docs/layout.md` for container conventions and CSS/typography rules.
 
 ## API authentication
-- Always use `apiFetch()` from `lib/api.ts` — auto-injects `X-OpenWallet-Key` header.
-- Never use `NEXT_PUBLIC_` prefix for `OPENWALLET_API_KEY` — server-only build secret.
+- Always use `apiFetch()` from `lib/api.ts` - auto-injects `X-OpenWallet-Key` header.
+- Never use `NEXT_PUBLIC_` prefix for `OPENWALLET_API_KEY` - server-only build secret.
 - Never use raw `fetch()` for API calls. Pass only path: `apiFetch('/api/v1/cards')`.
 
 ## Blog content rules
@@ -76,44 +76,44 @@ See `@.claude/docs/layout.md` for container conventions and CSS/typography rules
 - **Images**: `/public/images/posts/<slug>/<filename>.webp`
 
 ## Writing rules
-- **No em dashes (—):** Never use em dashes in any page content or metadata. Replace with a comma, colon, parentheses, or restructure the sentence. Em dashes are a visible AI writing signal.
+- **No em dashes (-):** Never use em dashes in any page content or metadata. Replace with a comma, colon, parentheses, or restructure the sentence. Em dashes are a visible AI writing signal.
 - **Tone for public pages:** Professional and honest, not corporate or casual. Use "chúng tôi" consistently. Avoid overly informal phrasing.
 
 ## Feature gate status
 
-### Wallet app (`/app/*`) — FROZEN
+### Wallet app (`/app/*`) - FROZEN
 - Routes return 404 unless `WALLET_ENABLED=true` env var is set.
 - Gate is in `app/app/layout.tsx` (server component) → calls `notFound()`.
 - Shell code lives in `app/app/app-shell.tsx` (client component, untouched).
-- `WalletNavButton` component exists but is not used anywhere — do not add it to nav.
+- `WalletNavButton` component exists but is not used anywhere - do not add it to nav.
 - Do not delete wallet code. May revive later. ROI currently too low vs competitors.
 - `public/robots.txt` has `Disallow: /app`. Keep this.
 
 ### Chat (`/chat`, `openwallet-chat`)
-- **Chat button hidden** — `ChatToggleButton` removed from `components/layout/header.tsx` (both desktop + mobile). Do not re-add unless explicitly requested.
+- **Chat button hidden** - `ChatToggleButton` removed from `components/layout/header.tsx` (both desktop + mobile). Do not re-add unless explicitly requested.
 - Not ready for public release. Needs evals + system prompt iteration first.
-- See `evals/` folder for eval harness.
+- **Full chat docs (arch, logging, Langfuse, evals, dev plan):** `.claude/docs/chat.md`
 
 ### `so-sanh-404-redirect`
 - Active. Handles legacy `/card-battle/X-vs-Y` URLs → redirects to `/card-battle?compare=X,Y`.
 - Lives in `components/layout/so-sanh-404-redirect.tsx`, used in `app/not-found.tsx`. Do not remove.
 
 ## Card ranking
 
-**Architecture SSOT: `../api/.claude/docs/card-recommendation-architecture.md`** — authoritative doc for intent model, intent groups, ranking rules, and data quality requirements. Read this before touching any ranking or recommendation code.
+**Architecture SSOT: `../api/.claude/docs/card-recommendation-architecture.md`** - authoritative doc for intent model, intent groups, ranking rules, and data quality requirements. Read this before touching any ranking or recommendation code.
 
 **Ranking logic lives in the API repo.** The web repo only consumes results:
-- `lib/cashback-calc.ts` — cashback estimation (mirrors API logic for display)
-- `lib/card-ranker.ts` — sort order only (cashback desc → annual_fee asc → network_popularity asc)
-- `components/marketing/card-ranking-table.tsx` — UI with spend selector
-- `components/marketing/recommendation-finder.tsx` — macro→micro→atomic intent selector + `POST /api/ranking` proxy
+- `lib/cashback-calc.ts` - cashback estimation (mirrors API logic for display)
+- `lib/card-ranker.ts` - sort order only (cashback desc → annual_fee asc → network_popularity asc)
+- `components/marketing/card-ranking-table.tsx` - UI with spend selector
+- `components/marketing/recommendation-finder.tsx` - macro→micro→atomic intent selector + `POST /api/ranking` proxy
 
 ## Meta-rules
 1. Before any task: check `.claude/commands/` for a relevant command file.
 2. After creating a command: add it to the commands table below.
 3. After non-trivial task: check if `.claude/docs/learnings/` needs a new note.
-4. **Question-only mode:** If the message starts with `question:` or `answer me:`, only answer — do NOT edit any files or run any commands.
-5. **Changelog:** After card data or feature changes, add entry to `content/changelog.mdx`. Use `/add-changelog`. Card/feature scope only — no UI or page structure changes. See `.claude/docs/changelog.md` for purpose, rules, tone, and format guide.
+4. **Question-only mode:** If the message starts with `question:` or `answer me:`, only answer - do NOT edit any files or run any commands.
+5. **Changelog:** After card data or feature changes, add entry to `content/changelog.mdx`. Use `/add-changelog`. Card/feature scope only - no UI or page structure changes. See `.claude/docs/changelog.md` for purpose, rules, tone, and format guide.
 
 ## Custom commands
 
@@ -128,8 +128,10 @@ See `@.claude/docs/layout.md` for container conventions and CSS/typography rules
 | `/add-ow-ui` | `commands/add-ow-ui.md` | Move component to `ow-ui/`, rename to `Ow*`, create story, report usages |
 | `/commit-all` | `commands/commit-all.md` | Stage + commit all changes in logical groups with conventional commit messages |
 | `/sync-api-types` | `commands/sync-api-types.md` | Regenerate types from API schema, diff changes, scan codebase, suggest updates |
+| `/edit-system-prompt` | `commands/edit-system-prompt.md` | Edit Owie's system prompt, enforce invariants, push to Langfuse |
 
 @.claude/docs/architecture.md
 @.claude/docs/layout.md
 @.claude/docs/DESIGN.md
 @.claude/docs/design-system.md
+@.claude/docs/chat.md

.claude/commands/add-changelog.md

@@ -21,7 +21,7 @@ Only `title` and `date` are required.
 
 ## Content
 
-Write the body in Markdown below the frontmatter. Keep it concise — 1–3 short paragraphs.
+Write the body in Markdown below the frontmatter. Keep it concise - 1–3 short paragraphs.
 
 - Describe what changed and why
 - Link to relevant pages if applicable

.claude/commands/add-ow-ui.md

@@ -24,7 +24,7 @@ If user passes a name (e.g. `chip`), search `components/` for the file. Multiple
 
 - Move file to `components/ow-ui/`
 - Rename file to `ow-<name>.tsx` if not already (e.g. `chip.tsx` → `ow-chip.tsx`)
-- Rename the exported function to `Ow<Name>` (PascalCase with `Ow` prefix) — e.g. `Chip` → `OwChip`
+- Rename the exported function to `Ow<Name>` (PascalCase with `Ow` prefix) - e.g. `Chip` → `OwChip`
 - Add `ow-<name>` CSS class to the wrapper element's `className` if not already present (per component conventions)
 - Update all imports across the codebase to the new path + new export name
 
@@ -42,8 +42,8 @@ Before writing the component, apply **design-system.md §6**:
 - Interactive styles: `[&:is(button,a)]:cursor-pointer [&:is(button,a)]:hover:bg-primary/10`
 
 **B) Component owns its internal content** (logo + text, icon + label, avatar + name) → use `href` prop:
-- `href?: string` — renders `<Link href>` when provided, `<span>` otherwise
-- Do NOT use `asChild` — Slot requires single child and will throw when component renders multiple internal elements
+- `href?: string` - renders `<Link href>` when provided, `<span>` otherwise
+- Do NOT use `asChild` - Slot requires single child and will throw when component renders multiple internal elements
 
 ### 4. Props discipline
 
@@ -57,7 +57,7 @@ Before writing the component, apply **design-system.md §6**:
 
 Create `components/ow-ui/ow-<name>.stories.tsx` following the structure and rules in `commands/create-story.md`.
 
-Title: `'OW UI/OwName'` — use `'Card UI/OwName'` for card-related components.
+Title: `'OW UI/OwName'` - use `'Card UI/OwName'` for card-related components.
 
 ### 6. Report usages
 

.claude/commands/commit-all.md

@@ -16,7 +16,7 @@ List every modified, deleted, and untracked file. Do NOT stage anything yet.
 
 ### 2. Group files logically
 
-Analyze the files and group them by **semantic intent** — what changed together for the same reason. Each group becomes one commit.
+Analyze the files and group them by **semantic intent** - what changed together for the same reason. Each group becomes one commit.
 
 Grouping heuristics (in priority order):
 - Same feature/component → one commit
@@ -38,9 +38,9 @@ Order commits so each builds on the previous. General order:
 
 For each group, in order:
 
-1. `git add <specific files>` — never `git add .` or `git add -A`
+1. `git add <specific files>` - never `git add .` or `git add -A`
 2. Craft commit message:
-   - Subject: `<type>(<scope>): <what changed>` — ≤50 chars, imperative, lowercase after colon
+   - Subject: `<type>(<scope>): <what changed>` - ≤50 chars, imperative, lowercase after colon
    - Body: only when the **why** is non-obvious. One short line max.
    - Types: `feat` `fix` `refactor` `style` `chore` `docs` `test` `perf` `build` `ci`
    - Scope: filename stem, component name, or area (e.g. `ow-logo`, `storybook`, `header`)
@@ -56,7 +56,7 @@ After all commits, output a table:
 
 ## Rules
 
-- Never use `git add .` or `git add -A` — add files explicitly by name
+- Never use `git add .` or `git add -A` - add files explicitly by name
 - Never skip `--no-verify` unless user explicitly asks
 - Never commit files that look like secrets (`.env`, credentials)
 - If a file's intent is ambiguous, ask before grouping

.claude/commands/create-story.md

@@ -4,11 +4,11 @@ Create a `.stories.tsx` file for a component. The user will pass a component pat
 
 ## Steps
 
-1. **Find the component** — if user passes just a name (e.g. `card-image`), search `components/` for the file. If multiple matches, ask which one.
+1. **Find the component** - if user passes just a name (e.g. `card-image`), search `components/` for the file. If multiple matches, ask which one.
 
-2. **Read the component** — understand its props interface, variants, required vs optional props.
+2. **Read the component** - understand its props interface, variants, required vs optional props.
 
-3. **Generate the story file** — create `<same-dir>/<filename>.stories.tsx` following the structure below.
+3. **Generate the story file** - create `<same-dir>/<filename>.stories.tsx` following the structure below.
 
 ## Story structure
 
@@ -72,7 +72,7 @@ export const VariantB: Story = {
 
 | Situation | Use |
 |-----------|-----|
-| Props are boolean / enum / string | `args` — Controls work |
+| Props are boolean / enum / string | `args` - Controls work |
 | Props are objects, ReactNode, or asChild pattern | `render: () =>` |
 | Overview story (always) | `render: () =>` |
 | Component has no props | `render: () => <ComponentName />` |
@@ -97,13 +97,13 @@ Map folder → Storybook group:
 
 ## Story rules
 
-- `Overview` is always the **first export** — autodocs renders it as the Primary hero at top
-- `includePrimary={false}` is set globally in `.storybook/preview.tsx` — no double render
+- `Overview` is always the **first export** - autodocs renders it as the Primary hero at top
+- `includePrimary={false}` is set globally in `.storybook/preview.tsx` - no double render
 - Use realistic Vietnamese data in args (card names, bank names, Vietnamese text)
 - Cover key visual states: default, empty/null props, active/inactive, loading (if shimmer exists)
 - If component requires API data or complex objects, import type from the relevant `lib/api-types.ts` or mock a minimal object
-- Never mock Next.js router — `@storybook/nextjs-vite` handles it automatically
-- Never mock `apiFetch` — if component fetches data, note it in a comment and use a static prop version if available
+- Never mock Next.js router - `@storybook/nextjs-vite` handles it automatically
+- Never mock `apiFetch` - if component fetches data, note it in a comment and use a static prop version if available
 
 ## After creating
 

.claude/commands/edit-system-prompt.md

@@ -0,0 +1,62 @@
+# Edit Owie's system prompt
+
+Edit `lib/chat/system-prompt.ts` then push to Langfuse as new production version.
+
+## Invariants - NEVER change without explicit user instruction
+
+These rules are load-bearing. Breaking them silently breaks product behavior or trust:
+
+1. **Owie persona** - name is "Owie", role is OpenWallet.vn card advisor. Warm + professional tone.
+2. **CT address** - always address user as "CT". Keep explanation when asked.
+3. **Vietnamese default** - respond in Vietnamese unless user writes in another language.
+4. **Tool-before-answer** - NEVER fabricate cashback rates, fees, or interest rates. Always call a tool first.
+5. **Scope refusal template** - use exact Vietnamese refusal template for off-topic questions. Do not soften or remove.
+6. **Card links** - only link cards via `/the/<slug>` using tool-retrieved slugs. Never invent slugs.
+7. **No `#` headings** - response format rule. Only `##` and below.
+8. **Tool routing logic (Cat A/B/C)** - the tool call sequences are precise. Do not collapse or reorder steps.
+
+## Steps
+
+### 1. Understand the change request
+- What category: persona, scope, tool rules, response format, language?
+- Does it conflict with any invariant above? If yes, ask for explicit confirmation before proceeding.
+
+### 2. Edit the prompt
+File: `lib/chat/system-prompt.ts` → `SYSTEM_PROMPT` const.
+
+Prompt writing rules:
+- **Persona first** - name/role/tone at top
+- **Positive over negative** - "do X" beats "don't do Y" where possible
+- **Concrete over vague** - add examples for new rules, not just descriptions
+- **No contradictions** - new rules must not conflict with existing ones; later rule wins but inconsistently
+- **Tool rules last** - LLMs read top-heavy; scope/persona matters most at top
+
+### 3. Sync the fallback
+`buildSystemPrompt()` in same file uses `SYSTEM_PROMPT` as base - no separate edit needed. But if `pageContext` injection logic changes, update the `if (pageContext.type === ...)` blocks too.
+
+### 4. Check evals coverage
+- Does the change affect any of the 13 eval test cases in `evals/`?
+- If new behavior added: note it needs a new eval case (don't write it now unless asked).
+
+### 5. Push to Langfuse
+**STOP - do NOT run the push command automatically. Show the diff and ask for confirmation first.**
+
+After editing, show the user what changed, then ask: "Push to Langfuse as version N?"
+
+Only run after explicit user approval:
+```bash
+pnpm push:prompt
+```
+- Pushes `SYSTEM_PROMPT` const to Langfuse as new `production` version
+- Live within 60s (cache TTL in `fetchSystemPrompt()`)
+- Confirm output shows `✓ Pushed version N`
+- **Note:** `STATIC_LISTS` (persona/merchant lists injected by `buildSystemPrompt()`) are NOT pushed - they are always injected at runtime from local constants. Langfuse only stores the base prompt text.
+
+### 6. Verify
+- Check Langfuse UI or wait 60s and test via `/chat`
+- Hardcoded fallback in `lib/chat/system-prompt.ts` is the source of truth for the push script - they stay in sync automatically
+
+## What NOT to change via this command
+- `buildSystemPrompt()` function signature or `pageContext` types - that's a code change, not a prompt change
+- `push-prompt.ts` script - separate concern
+- Eval test cases - use eval workflow instead

.claude/commands/generate-images.md

@@ -42,15 +42,15 @@ Write prompts in **English** for Gemini image generation.
 - Avoid tables inside images (use only when data density requires it, non-cover only)
 
 ### Bank brand colors
-- **Vietcombank** — `#006633` (dark green)
-- **BIDV** — `#003087` (dark blue) + red accent
-- **VietinBank** — `#c8102e` (red) + navy
-- **Techcombank** — `#e30613` (bright red)
-- **MB Bank** — `#004f9f` (teal/navy)
-- **VPBank** — `#00a650` (green) + orange (issues Amex)
-- **Shinhan Bank** — `#003b8e` (blue, also issues Amex)
-- **ACB** — `#0066b2` (blue)
-- **TPBank** — `#6b21a8` (purple)
+- **Vietcombank** - `#006633` (dark green)
+- **BIDV** - `#003087` (dark blue) + red accent
+- **VietinBank** - `#c8102e` (red) + navy
+- **Techcombank** - `#e30613` (bright red)
+- **MB Bank** - `#004f9f` (teal/navy)
+- **VPBank** - `#00a650` (green) + orange (issues Amex)
+- **Shinhan Bank** - `#003b8e` (blue, also issues Amex)
+- **ACB** - `#0066b2` (blue)
+- **TPBank** - `#6b21a8` (purple)
 
 ### General prompt rules
 - Specify visual style: "flat illustration", "minimalist", "isometric"