diff --git a/.cursor/rules/00-project.mdc b/.cursor/rules/00-project.mdc index e77e3d5..2f8e290 100644 --- a/.cursor/rules/00-project.mdc +++ b/.cursor/rules/00-project.mdc @@ -10,3 +10,5 @@ Golden rules: - Validate all input with Zod (strict). Never leak secrets or stack traces to clients. - staging and production are isolated (Neon branch, Worker env, R2 bucket per env). Never mix secrets. - Don't add anything you can't explain in the follow-up interview. +- When rubric-relevant work ships, update `SUBMISSION.md`, spec mapping, and checklists in the same change (see `.cursor/rules/111-submission-docs.mdc`). +- New routes and async UI must follow page-load motion rules (see `.cursor/rules/31-page-load-motion.mdc`) — animated skeletons, `AnimatedOutlet`, no abrupt pop-in. diff --git a/.cursor/rules/110-docs.mdc b/.cursor/rules/110-docs.mdc index 96bd55d..3c60140 100644 --- a/.cursor/rules/110-docs.mdc +++ b/.cursor/rules/110-docs.mdc @@ -4,3 +4,10 @@ globs: "**/*.md" --- - Keep the README's five graded sections accurate to the code (perf, media, scale, security, prod). - Record decisions as ADRs in docs/adr. Document every public surface. Wrong docs are worse than none. +- Reviewer-facing docs (`SUBMISSION.md`, checklists, spec mapping): see **111-submission-docs** — sync with [docs/HOMEWORK-SPEC.md](../../docs/HOMEWORK-SPEC.md) when rubric-relevant work ships; professional yet personable tone for 501. +- Game mode “how to play” copy: see **32-game-guides** — single source `apps/web/src/content/game-guides.ts` + [docs/GAME-GUIDES.md](../../docs/GAME-GUIDES.md). +- Form field tooltips: see **33-field-tooltips** — `field-tooltips.ts` + [docs/FIELD-TOOLTIPS.md](../../docs/FIELD-TOOLTIPS.md). +- Auth / JWT / API keys: see **34-auth** — [docs/AUTH.md](../../docs/AUTH.md). +- Scale / cache / rate limits: see **35-scale** — [docs/SCALE.md](../../docs/SCALE.md). +- Testing / contracts / visual: see **36-quality-dx**. +- PWA / i18n / scorecard / analytics / API docs: see **37-tier7-extras** — [docs/EXTRAS.md](../../docs/EXTRAS.md). diff --git a/.cursor/rules/111-submission-docs.mdc b/.cursor/rules/111-submission-docs.mdc new file mode 100644 index 0000000..73e79e1 --- /dev/null +++ b/.cursor/rules/111-submission-docs.mdc @@ -0,0 +1,67 @@ +--- +description: Keep SUBMISSION.md and reviewer-facing docs aligned with the 501 homework spec +globs: "SUBMISSION.md,README.md,docs/checklists/**,docs/HOMEWORK-SPEC.md,docs/INTERVIEW.md,docs/ROADMAP.md" +--- +# Submission & reviewer-facing documentation + +Write for engineers at **501 Entertainment** who build venue-facing hub products (live games, hospitality UX). Tone: **professional, clear, and personable** — confident without hype; honest about trade-offs. + +## Spec is the checklist + +Before editing submission docs, read [docs/HOMEWORK-SPEC.md](../../docs/HOMEWORK-SPEC.md) and [docs/checklists/01-homework-rubric.md](../../docs/checklists/01-homework-rubric.md). Every claim in SUBMISSION.md must map to a rubric row or a defensible extra. + +**Brief must stay reflected:** +- Session dashboard: ID, players + scores, player photo, status, responsive UI, editable scores, real-time updates +- Match history: list → detail → video playback +- API: `GET/POST/PATCH /sessions`, `GET /sessions/:id`, database-backed +- README graded topics: perf, media, scale, security, production mitigations (with pointers to `docs/`) + +## Files to update together + +| File | Role | +| --- | --- | +| `SUBMISSION.md` | Primary hand-in cover sheet — links, brief coverage, extras, doc index | +| `README.md` | Graded written answers + stack; keep claims accurate to code | +| `docs/HOMEWORK-SPEC.md` | Spec mapping table when implementation status changes | +| `docs/checklists/01-homework-rubric.md` | Tick rubric items when closed | +| `docs/checklists/02-pre-submission.md` | Deploy URLs, secrets, smoke-test steps | +| `docs/checklists/03-known-gaps.md` | Resolve or honestly document remaining gaps | +| `docs/ROADMAP.md` | Status snapshot when a tier completes | +| `docs/INTERVIEW.md` | 90s tour talking points when UX/architecture shifts | + +Update these **in the same change** when you ship rubric-relevant features, change deploy URLs, or close known gaps. + +## SUBMISSION.md structure + +Keep it scannable (reviewers skim first): + +1. **Opening** — one paragraph: what Oche is, stack in plain terms, why it fits the brief (venue live scores + history + video). +2. **Live links** — staging, production, API (only URLs you have verified). +3. **Brief coverage** — bullet list mirroring the homework spec sections; use ✓ only when deployed and tested. +4. **README answers** — one line per graded topic + link to README / `docs/`. +5. **Notable extras** — RLS, WebSockets, env isolation, etc.; tie each to something 501 cares about (security, formats, scale). +6. **Doc index** — pointer to `docs/README.md`, roadmaps, checklists. + +Do **not** duplicate full README essays in SUBMISSION.md — summarise and link. + +## Tone guide (501-facing) + +**Do** +- Use neutral project voice or sparing first person (“I chose Cloudflare Workers for…”) when explaining a decision. +- Acknowledge their domain: competitive socialising, live venue sessions, operator dashboards. +- State what is **deployed vs local-only**; note staging vs production isolation. +- When something is partial, say so briefly and point to `03-known-gaps.md` or the interview talking point. + +**Don't** +- Marketing superlatives, emoji, or generic cover-letter filler. +- Oversell features that README, gaps, or code contradict. +- Raw stack dumps with no tie-back to the brief. +- Blame the toolchain; frame Windows/PowerShell fixes as DX choices you documented. + +**Example opener** + +> Oche is a Game Session Dashboard for your Cloud Developer take-home: a React SPA with live scores, match history with video, and a Hono API on Cloudflare with Neon Postgres. Staging and production are isolated; row-level security enforces per-owner data access throughout. + +## After edits + +Run `npm run rules:sync` if `.cursor/rules` changed. If README graded claims changed, verify `npm run check` still passes. diff --git a/.cursor/rules/20-frontend-react.mdc b/.cursor/rules/20-frontend-react.mdc index a907a3f..40362fb 100644 --- a/.cursor/rules/20-frontend-react.mdc +++ b/.cursor/rules/20-frontend-react.mdc @@ -6,3 +6,4 @@ globs: "apps/web/**/*.{ts,tsx}" - Route components are lazy-loaded (code splitting). No global store. - Live updates via the `useLiveSession` WebSocket hook; polling is the documented fallback. - API base URL comes from `import.meta.env.VITE_API_BASE` (per-env). +- Form inputs: use `TextField` / `SelectField` / `FileField` with required `tooltip` — see **33-field-tooltips**. diff --git a/.cursor/rules/30-styling.mdc b/.cursor/rules/30-styling.mdc index e8b2e7b..401bf75 100644 --- a/.cursor/rules/30-styling.mdc +++ b/.cursor/rules/30-styling.mdc @@ -1,8 +1,33 @@ --- -description: Styling — Tailwind v4 + shadcn only +description: Styling — Tailwind v4 + shadcn + Oche motion system globs: "apps/web/**/*.{ts,tsx,css}" --- -- Tailwind utilities + shadcn/ui components only. No ad-hoc CSS files. -- Theme tokens live once in `src/index.css` (`@theme`). Identity = "live scoreboard": - deep slate canvas, chalk text, single `--color-oche` accent, condensed tabular `.score` numerals. -- Don't ship default-looking shadcn; keep the deliberate accent + spacing rhythm. +# Visual identity +- Tailwind utilities + shadcn/ui components only. Theme tokens live in `src/index.css` (`@theme`). +- Identity = "live scoreboard": deep slate canvas, chalk text, single `--color-oche` accent, condensed tabular `.score` numerals. +- Don't ship default-looking shadcn; keep deliberate accent + spacing rhythm. + +# Motion philosophy (interview polish) +Every interactive surface should feel **modern, smooth, and subtly captivating** — never flashy or distracting. + +**Page loads & route entry:** see **31-page-load-motion** — skeletons + slide entrances mandatory; no bare "Loading…" text. + +## Principles +- **Press feedback:** every `