diff --git a/.agents/README.md b/.agents/README.md
new file mode 100644
index 000000000..4a9ef6f76
--- /dev/null
+++ b/.agents/README.md
@@ -0,0 +1,31 @@
+# .agents
+
+Cross-tool source of truth for Cuttle's agentic infrastructure. All AI assistants load from here via symlinks.
+
+## What lives here
+
+```
+skills/       # ctl-* skill prompts, each in their own SKILL.md
+agents/       # ctl-* subagent definitions
+docs/         # detailed reference docs (skills index into these)
+tools/        # shared Node.js utilities called by hooks
+```
+
+## How it loads
+
+| Tool | Loads via |
+|------|-----------|
+| Claude Code | `.claude/skills → .agents/skills`, `.claude/agents → .agents/agents` |
+| Gemini CLI | `.gemini/skills → .agents/skills`, `.gemini/agents → .agents/agents` |
+
+`CLAUDE.md → @AGENTS.md` auto-loads the top-level discovery and safety rules every session.
+
+## Skill namespace
+
+All Cuttle skills use the `ctl-` prefix. See `docs/skill-conventions.md` for naming rules.
+
+## Adding a skill
+
+1. Create `skills/ctl-<name>/SKILL.md` with the required frontmatter.
+2. Keep the file under ~500 lines.
+3. If the skill references detailed examples, put those in `docs/` and link from the skill.
diff --git a/.agents/agents/ctl-architecture-reviewer.md b/.agents/agents/ctl-architecture-reviewer.md
new file mode 100644
index 000000000..6816bc4fe
--- /dev/null
+++ b/.agents/agents/ctl-architecture-reviewer.md
@@ -0,0 +1,75 @@
+---
+name: ctl-architecture-reviewer
+description: "Architecture reviewer subagent for Cuttle. Reviews module boundaries, race conditions, store mutation hygiene, and structural patterns. Dispatched by ctl-code-review. Returns a structured findings report."
+model: inherit
+allowed-tools: Read, Grep, Glob, Bash
+---
+
+# Architecture Reviewer
+
+Focused architecture review for Cuttle changes. Called by `ctl-code-review`.
+
+## Scope
+
+- Module boundaries (controllers, helpers, stores, components don't bleed into each other's domains)
+- Race conditions in async controller flows
+- Pinia store mutation hygiene
+- Socket subscription lifecycle (rooms joined/left correctly)
+- Known structural risk areas
+
+## Input
+
+Receive the diff or changed file list from `ctl-code-review`. Read the changed files fully before reviewing.
+
+## Known risk areas to check
+
+### Double API calls / playOneOff pattern
+
+Controller actions that trigger game state changes must lock the game before reading and unlock after. Check:
+- Is `sails.helpers.lockGame` called before any state read?
+- Is `sails.helpers.unlockGame` called in both the success and catch paths?
+- Is there any early return that bypasses unlock?
+
+### rematch.js module-scope state
+
+`api/controllers/game/rematch.js` initializes `game` as `let game` in the outer try block. This is intentional — it allows the catch block to unlock even if assignment failed. Do not flag this pattern as a bug.
+
+### Store mutations outside actions
+
+Pinia state should only be mutated inside store actions (functions returned from `defineStore`). Flag direct mutations via `store.property = value` from outside the store definition.
+
+### Array mutation safety
+
+`splice(-1, 1)` removes the last element. Verify indices are intentional. Look for off-by-one errors in card array manipulations.
+
+### Async consistency
+
+If a controller calls multiple `await` expressions, verify the game lock is held for the entire sequence.
+
+## Review checklist
+
+- [ ] Lock/unlock pattern correct in modified controllers
+- [ ] No early returns that bypass unlock
+- [ ] Store state mutated only via actions
+- [ ] Socket room subscriptions balanced (join/leave)
+- [ ] No module-scope mutable state introduced
+- [ ] Array operations use correct indices
+
+## Output format
+
+```
+## Architecture Review
+
+### Verdict: [PASS / REQUEST CHANGES / DISCUSS]
+
+### Findings
+| Severity | File:Line | Issue | Recommendation |
+|----------|-----------|-------|----------------|
+| Block | api/controllers/game/foo.js:42 | unlock bypassed on early return | add unlock before return |
+| Suggest | src/stores/game.js:120 | direct mutation outside action | move to store action |
+
+### Clean areas
+- [list files with no findings]
+```
+
+Return this report to `ctl-code-review`.
diff --git a/.agents/agents/ctl-docs-reviewer.md b/.agents/agents/ctl-docs-reviewer.md
new file mode 100644
index 000000000..87d57247d
--- /dev/null
+++ b/.agents/agents/ctl-docs-reviewer.md
@@ -0,0 +1,90 @@
+---
+name: ctl-docs-reviewer
+description: "Docs reviewer subagent for Cuttle. Reviews drift between docs/*.md and code, broken links, and AGENTS.md/CLAUDE.md consistency. Dispatched by ctl-code-review. Returns a structured findings report."
+model: inherit
+allowed-tools: Read, Grep, Glob, Bash
+---
+
+# Docs Reviewer
+
+Focused documentation review for Cuttle changes. Called by `ctl-code-review`.
+
+## Scope
+
+- Drift between `docs/*.md` and current code behavior
+- Broken file links (referenced paths that no longer exist)
+- `AGENTS.md` / `CLAUDE.md` / `GEMINI.md` consistency
+- `.agents/docs/` accuracy against current codebase
+- New behavior introduced without doc update
+
+## Input
+
+Receive the diff or changed file list from `ctl-code-review`. Read changed files and any docs that reference the changed areas.
+
+## Checks
+
+### 1. New behavior without doc update
+
+If changed files introduce new patterns (new helper signature, new move type, new Cypress command), check whether the relevant doc has been updated:
+
+```bash
+grep -r "helperName\|newPattern" docs/ .agents/docs/ --include="*.md"
+```
+
+If the pattern is referenced nowhere in docs, flag it as undocumented.
+
+### 2. Broken file links
+
+```bash
+# Find all markdown links
+grep -roh '\[.*\]([^)]*\.js\|[^)]*\.vue\|[^)]*\.md)' docs/ .agents/docs/ AGENTS.md
+```
+
+For each linked path, verify it exists:
+```bash
+ls <linked-path>
+```
+
+### 3. AGENTS.md / CLAUDE.md consistency
+
+- `CLAUDE.md` must contain only `@AGENTS.md` — do not add content directly.
+- `GEMINI.md` must contain only `@AGENTS.md`.
+- Any changes to AGENTS.md must not contradict `.agents/docs/` content.
+
+```bash
+cat CLAUDE.md
+cat GEMINI.md
+```
+
+### 4. `.agents/docs/` accuracy
+
+If a changed controller, helper, or store deviates from the documented pattern in `.agents/docs/sails-patterns.md` or `.agents/docs/vue-patterns.md`, flag the discrepancy.
+
+### 5. Game rules doc vs implementation
+
+If `docs/game-rules.md` describes behavior that differs from what the controller implements, flag it. The implementation is authoritative; the docs should match.
+
+```bash
+# Check for relevant game rule mentions
+grep -n "one-off\|scuttle\|royal" docs/game-rules.md
+```
+
+## Output format
+
+```
+## Docs Review
+
+### Verdict: [PASS / REQUEST CHANGES / SUGGEST]
+
+### Findings
+| Severity | Location | Issue | Recommendation |
+|----------|----------|-------|----------------|
+| Request | docs/CONTRIBUTING.md:88 | references cy.setupGameAsP0() but signature changed | update docs |
+| Suggest | .agents/docs/sails-patterns.md | new helper added but not documented | add to patterns doc |
+| Block | AGENTS.md:45 | broken link to api/helpers/old-helper.js | update or remove link |
+
+### Clean areas
+- [list docs with no findings]
+```
+
+Return this report to `ctl-code-review`.
diff --git a/.agents/agents/ctl-performance-reviewer.md b/.agents/agents/ctl-performance-reviewer.md
new file mode 100644
index 000000000..0cd2c2efe
--- /dev/null
+++ b/.agents/agents/ctl-performance-reviewer.md
@@ -0,0 +1,100 @@
+---
+name: ctl-performance-reviewer
+description: "Performance reviewer subagent for Cuttle. Reviews socket handler cleanup, memory leaks, Pinia store reactivity, and Vite build impact. Dispatched by ctl-code-review. Returns a structured findings report."
+model: inherit
+allowed-tools: Read, Grep, Glob, Bash
+---
+
+# Performance Reviewer
+
+Focused performance review for Cuttle changes. Called by `ctl-code-review`.
+
+## Scope
+
+- Socket listener cleanup (listeners added in setup must be removed in teardown)
+- Memory leaks in Vue components and Pinia stores
+- Pinia store reactivity (unnecessary re-renders from broad reactive state)
+- Vite build impact (large static imports, unoptimized assets)
+- Inefficient database queries (N+1, missing `populate`)
+
+## Input
+
+Receive the diff or changed file list from `ctl-code-review`. Read changed files.
+
+## Checks
+
+### 1. Socket listener cleanup
+
+Vue components that add socket listeners must remove them on unmount:
+
+```js
+// Good
+onMounted(() => { io.socket.on('game', handler); });
+onUnmounted(() => { io.socket.off('game', handler); });
+
+// Flag: listener added but never removed
+```
+
+```bash
+grep -n "io.socket.on\|io.socket.off" <changed files>
+```
+
+### 2. Pinia store — no leaked timers/intervals
+
+```bash
+grep -n "setInterval\|setTimeout" <changed files> --include="*.js"
+```
+
+Timers inside stores or composables must be cleared on component teardown or store cleanup.
+
+### 3. Pinia reactivity granularity
+
+Large `ref({})` objects cause broad re-renders when any nested property changes. Prefer individual `ref()` values for frequently-updated fields.
+
+```bash
+grep -n "ref({" src/stores/*.js
+```
+
+Flag large object refs in hot paths (game state, hand, points).
+
+### 4. Database query efficiency
+
+In Sails controllers, `populate` calls are expensive. Flag:
+- Unnecessary `populate` on fields not used in the response
+- Missing `populate` that causes N+1 (accessing `game.p0.username` without populating `p0`)
+
+```bash
+grep -n "\.populate\|\.find\|\.findOne" <changed files> --include="*.js"
+```
+
+### 5. Vue component re-render scope
+
+Components that subscribe to large portions of the game store will re-render on any game event. Flag components that import the entire `useGameStore` but only use one or two fields.
+
+### 6. Vite build impact
+
+```bash
+# Check for large static imports
+grep -n "import.*from.*node_modules" <changed Vue/JS files>
+```
+
+Flag imports of large libraries where a smaller alternative exists.
+
+## Output format
+
+```
+## Performance Review
+
+### Verdict: [PASS / REQUEST CHANGES / SUGGEST]
+
+### Findings
+| Severity | File:Line | Issue | Recommendation |
+|----------|-----------|-------|----------------|
+| Request | src/plugins/sockets/inGameEvents.js:88 | socket.on without socket.off | add cleanup in onUnmounted |
+| Suggest | src/stores/game.js:95 | large object ref, re-renders broadly | split into granular refs |
+
+### Clean areas
+- [list files with no findings]
+```
+
+Return this report to `ctl-code-review`.
diff --git a/.agents/agents/ctl-security-reviewer.md b/.agents/agents/ctl-security-reviewer.md
new file mode 100644
index 000000000..29bab8cae
--- /dev/null
+++ b/.agents/agents/ctl-security-reviewer.md
@@ -0,0 +1,98 @@
+---
+name: ctl-security-reviewer
+description: "Security reviewer subagent for Cuttle. Reviews CSRF config, session handling, policy chain, XSS vectors, OAuth flow, and hardcoded secrets. Dispatched by ctl-code-review. Returns a structured findings report."
+model: inherit
+allowed-tools: Read, Grep, Glob, Bash
+---
+
+# Security Reviewer
+
+Focused security review for Cuttle changes. Called by `ctl-code-review`.
+
+## Scope
+
+- Authentication and session validation on game-mutating routes
+- Policy chain integrity (`config/policies.js`)
+- Hardcoded secrets or credentials
+- XSS vectors (`v-html` usage, `innerHTML`, unescaped user content)
+- `rejectUnauthorized: false` in TLS/HTTPS config
+- OAuth flow correctness
+- User input validation at API boundaries
+
+## Input
+
+Receive the diff or changed file list from `ctl-code-review`. Read changed files and any touched policy/route files.
+
+## Checks
+
+### 1. Session validation
+
+Every game-mutating controller must:
+- Read user ID from `req.session.usr` — never from `req.body` or `req.params`
+- Validate the user is a player in the game before mutating
+
+```bash
+# Check policy chain for modified routes
+grep -n "changed-route-pattern" config/routes.js
+grep -n "route-action" config/policies.js
+```
+
+### 2. Policy chain completeness
+
+```bash
+cat config/policies.js
+```
+
+Verify that new routes are listed in `config/policies.js` with at least `isLoggedIn`. Unlisted routes default to open access.
+
+### 3. Hardcoded secrets
+
+```bash
+grep -r "password\|secret\|token\|key\|api_key" <changed files> --include="*.{js,vue}" -i
+```
+
+Flag any string literals that look like credentials. Sails config should be used instead.
+
+### 4. XSS vectors
+
+```bash
+grep -r "v-html\|innerHTML\|dangerouslySetInner" <changed files> --include="*.vue"
+```
+
+`v-html` is blocked for user-supplied content. Flag any new `v-html` binding on data from the API or user input.
+
+### 5. TLS configuration
+
+```bash
+grep -r "rejectUnauthorized" config/ --include="*.js"
+```
+
+`rejectUnauthorized: false` must not appear in production config.
+
+### 6. CSRF
+
+Sails.js provides CSRF protection via its built-in middleware. Check that new form-like POST endpoints are not accidentally excluded from CSRF policy.
+
+### 7. Socket room authorization
+
+Players should only be subscribed to their own perspective room (`game_<id>_p0` or `game_<id>_p1`). Verify that `addRoomMembersToRooms` calls correctly map p0→p1 and p1→p0 on rematch (perspectives switch).
+
+## Output format
+
+```
+## Security Review
+
+### Verdict: [PASS / REQUEST CHANGES / BLOCK]
+
+### Findings
+| Severity | File:Line | Issue | Recommendation |
+|----------|-----------|-------|----------------|
+| Block | api/controllers/game/foo.js:15 | userId from req.body | use req.session.usr |
+| Block | config/policies.js | new route missing isLoggedIn | add to policy chain |
+| Request | src/components/Chat.vue:44 | v-html on user message | use text interpolation |
+
+### Clean areas
+- [list files with no findings]
+```
+
+Return this report to `ctl-code-review`.
diff --git a/.agents/docs/commit-format.md b/.agents/docs/commit-format.md
new file mode 100644
index 000000000..5d382d1e1
--- /dev/null
+++ b/.agents/docs/commit-format.md
@@ -0,0 +1,56 @@
+# Commit Format
+
+Cuttle uses [Conventional Commits](https://www.conventionalcommits.org/) with file/area-based scopes.
+
+## Format
+
+```
+<type>(<scope>): <subject>
+```
+
+- Subject: lowercase, imperative, no period.
+- Scope: the file name (no extension) or the feature area affected.
+- Keep subject under 72 characters.
+
+## Types
+
+| Type | When |
+|------|------|
+| `feat` | New user-facing feature |
+| `fix` | Bug fix |
+| `test` | Adding or updating tests |
+| `style` | Visual/style change, no logic |
+| `refactor` | Code restructure, no behavior change |
+| `chore` | Build, deps, tooling, agents infrastructure |
+| `docs` | Documentation only |
+
+## Scopes mined from git log
+
+Common scopes extracted from recent history:
+
+| Scope | Area |
+|-------|------|
+| `GameView` | `src/routes/game/GameView.vue` |
+| `rematch.js` | `api/controllers/game/rematch.js` |
+| `sockets` | Socket event handling |
+| `lock-game` | `api/helpers/lock-game.js` |
+| `announcementData` | `src/routes/home/components/announcementDialog/data/announcementData.js` |
+| `deps` | Dependency updates |
+| `agents` | `.agents/` infrastructure |
+
+For new files, use the file name without extension. For features that span multiple files, use the area name.
+
+## Rules
+
+- Never bump `package.json` version in a commit — CI handles this automatically via version labels.
+- Do not use `git add -A` or `git add .` — stage specific files.
+- Do not use `--no-verify`.
+
+## Examples
+
+```
+feat(GameView): add scuttle animation for seven card plays
+fix(rematch.js): unlock game on forbidden error path
+test(basicMoves.spec.js): add draw-past-limit edge case
+chore(agents): add ctl-discover skill
+```
diff --git a/.agents/docs/doc-format.md b/.agents/docs/doc-format.md
new file mode 100644
index 000000000..eecaa9c55
--- /dev/null
+++ b/.agents/docs/doc-format.md
@@ -0,0 +1,40 @@
+# Doc Format
+
+House style for all docs in this repo, including `docs/*.md`, `.agents/docs/*.md`, and skill files.
+
+## Voice
+
+- Imperative, factual, dry. No marketing language.
+- State what something does, not how great it is.
+- Omit filler phrases: "Note that", "It is worth mentioning", "Please keep in mind".
+
+## Structure
+
+- `#` — document title (one per file).
+- `##` — major section.
+- `###` — sub-section.
+- No level deeper than `###` in most docs; use a list instead.
+
+## Lists
+
+- Flat lists for 3+ parallel items.
+- Use a table when items have 2+ attributes.
+- Keep bullets to one line when possible.
+
+## Code
+
+- Inline code for: file paths, variable names, command fragments, JSON keys.
+- Fenced blocks for: commands the reader runs, file snippets, API responses.
+- Name the language on every fenced block.
+
+## Cross-references
+
+- Link to files by repo-relative path: `[game-domain.md](game-domain.md)`.
+- Link to skills by name: `ctl-discover`.
+- Do not link to line numbers — they rot.
+
+## What to omit
+
+- Do not document uncertainty ("may", "might", "could be"). Verify first, then document the fact.
+- Do not annotate intent ("this is needed because...") — that belongs in commit messages or PRs.
+- Do not repeat information already in `AGENTS.md`; link to it.
diff --git a/.agents/docs/game-domain.md b/.agents/docs/game-domain.md
new file mode 100644
index 000000000..8c48b7898
--- /dev/null
+++ b/.agents/docs/game-domain.md
@@ -0,0 +1,98 @@
+# Game Domain Glossary
+
+Canonical vocabulary for Cuttle. Use these terms in code, tests, and comments. See `docs/game-rules.md` for full rules.
+
+## Players
+
+| Term | Meaning |
+|------|---------|
+| `p0` | Player 0 — the player who was dealt 5 cards and goes first |
+| `p1` | Player 1 — the player who was dealt 6 cards |
+| `pNum` | Player number: `0` or `1` |
+
+In code, player objects are stored on `game.p0` and `game.p1`. The `pNum` is used in move payloads and socket events.
+
+## Cards
+
+### Ranks (integers 1–13)
+
+| Rank | Name | Role |
+|------|------|------|
+| 1 | Ace | One-off: scrap all point cards |
+| 2 | Two | One-off: counter a one-off OR scrap a royal/glasses eight |
+| 3 | Three | One-off: take one card from scrap pile |
+| 4 | Four | One-off: opponent discards two cards |
+| 5 | Five | One-off: discard one, draw up to three |
+| 6 | Six | One-off: scrap all royals and glasses eights |
+| 7 | Seven | One-off: reveal top two deck cards, play one immediately |
+| 8 | Eight | Royal: "Glasses Eight" — opponent plays with hand revealed |
+| 9 | Nine | One-off: return opponent's field card to their hand (frozen one turn) |
+| 10 | Ten | Points only |
+| 11 | Jack | Royal: steal an opponent's point card |
+| 12 | Queen | Royal: protect your other cards from targeting |
+| 13 | King | Royal: reduce points-to-win threshold |
+
+### Suits (integers 0–3)
+
+| Suit | Integer |
+|------|---------|
+| Clubs | 0 (weakest for scuttle tiebreak) |
+| Diamonds | 1 |
+| Hearts | 2 |
+| Spades | 3 (strongest) |
+
+### Card representation in code
+
+```js
+// In game store / API responses
+{ rank: 7, suit: 0 }   // 7 of Clubs
+
+// In GameCard class (src/stores/game.js)
+card.name  // "7♣️"
+
+// In Cypress selectors
+'[data-player-hand-card=7_0]'   // rank_suit
+```
+
+## Locations
+
+| Term | Meaning | Selector location |
+|------|---------|-------------------|
+| `hand` | Cards in a player's hand | `data-player-hand-card` / `data-opponent-hand-card` |
+| `points` | Cards played for points | `data-player-point-card` / `data-opponent-point-card` |
+| `faceCards` | Royals and glasses eights in play | `data-player-face-card` / `data-opponent-face-card` |
+| `scrap` | Scrapped cards pile | — |
+
+## Actions
+
+| Term | API slug | When |
+|------|----------|------|
+| Draw | `draw` | Take top deck card |
+| Play for points | `points` | Play Ace–Ten to own field |
+| Scuttle | `scuttle` | Capture opponent's lower-ranked point card |
+| Play royal/glasses eight | `faceCard` | Play J/Q/K/8 to own field |
+| Play one-off | `untargetedOneOff` or `targetedOneOff` | Play A–7 or 9 to scrap pile |
+| Jack (steal) | `jack` | Play Jack onto opponent's point card |
+| Counter | `counter` | Play Two in response to opponent's one-off |
+| Resolve | `resolve` | Resolve a stacked counter chain |
+
+## Win conditions
+
+- Default: 21+ points wins.
+- With Kings: 1 King → 14pts, 2 Kings → 10pts, 3 Kings → 5pts, 4 Kings → 0pts (instant win on play).
+- Three consecutive passes → stalemate.
+
+## Socket events
+
+Game state is broadcast per-player via `sails.helpers.broadcastGameEvent(gameId, payload)` or `sails.helpers.gameStates.publishGameState()`. The `change` field in the payload identifies the event type (e.g., `'rematch'`, `'newGameForRematch'`).
+
+## Key files
+
+| File | Purpose |
+|------|---------|
+| `utils/MoveType.json` | Enum of all move type strings |
+| `utils/GameStatus.json` | Enum: `CREATED`, `STARTED`, `FINISHED` |
+| `utils/GamePhase.json` | Enum for game phase tracking |
+| `src/stores/game.js` | Pinia store: full game state, socket event handlers |
+| `api/helpers/broadcast-game-event.js` | Broadcasts payload to all game rooms |
+| `docs/game-rules.md` | Complete rules for human reference |
diff --git a/.agents/docs/github.md b/.agents/docs/github.md
new file mode 100644
index 000000000..87d8cd5f2
--- /dev/null
+++ b/.agents/docs/github.md
@@ -0,0 +1,55 @@
+# GitHub Workflow
+
+## Branch naming
+
+From `docs/CONTRIBUTING.md`:
+
+- Features: `feature/[issue-number-or-description]`
+- Bug fixes: `bug/[issue-number-or-description]`
+
+## Pull requests
+
+### Version label (required)
+
+Every PR merged to `main` must have exactly one version label. The label drives the automated version bump via GitHub Actions (`bump-version.yml`):
+
+| Label | Effect |
+|-------|--------|
+| `patch-version` | `x.y.Z → x.y.Z+1` |
+| `minor-version` | `x.y.z → x.Y+1.0` |
+| `major-version` | `x.y.z → X+1.0.0` |
+
+The label is applied by the core team, not the contributor. However, the PR author should suggest the appropriate level in the PR description.
+
+Do not manually bump `package.json` — CI commits the bump after the PR merges.
+
+### PR template
+
+Fill the template completely. Link the PR to its issue with `Closes #N` in the body.
+
+### Draft PRs
+
+CI checks are skipped for draft PRs (the `draft` job exits 1 immediately). Convert to "Ready for review" only when lint and unit tests pass locally.
+
+### Automated version flow
+
+1. PR merges to `main` → "Prepare Version Bump" workflow fires.
+2. "Prepare Version Bump" reads the version label, writes `version.txt` artifact.
+3. "Bump Version" workflow reads artifact, runs `npm version <type>`, commits, tags, pushes to `main`, creates GitHub release.
+
+## Labels
+
+Version labels: `patch-version`, `minor-version`, `major-version`
+
+Other common labels are for categorization (`bug`, `enhancement`, `documentation`). These do not affect versioning.
+
+## `gh` CLI usage
+
+All GitHub operations use the `gh` CLI. Do not add Octokit or other GitHub libraries.
+
+```bash
+gh pr create --title "..." --body "..."
+gh pr list --state open
+gh pr view <number>
+gh label list
+```
diff --git a/.agents/docs/sails-patterns.md b/.agents/docs/sails-patterns.md
new file mode 100644
index 000000000..d34bf5be2
--- /dev/null
+++ b/.agents/docs/sails-patterns.md
@@ -0,0 +1,168 @@
+# Sails.js Patterns
+
+Detailed reference for backend patterns in Cuttle. See `ctl-sails-patterns` skill for quick lookups.
+
+## Controller actions
+
+File: `api/controllers/<area>/<action>.js`
+
+```js
+module.exports = async function (req, res) {
+  let game;
+  try {
+    const { usr: userId } = req.session;
+    let { gameId } = req.params;
+    gameId = Number(gameId);
+    const { someField } = req.body;
+
+    game = await sails.helpers.lockGame(gameId);
+
+    // ... business logic ...
+
+    await sails.helpers.unlockGame(game.lock);
+    return res.ok({ result });
+  } catch (err) {
+    try {
+      await sails.helpers.unlockGame(game.lock);
+    } catch (_) {}
+
+    const message = err.raw?.message ?? err;
+    switch (err?.code) {
+      case CustomErrorType.FORBIDDEN:
+        return res.forbidden({ message });
+      default:
+        return res.serverError({ message });
+    }
+  }
+};
+```
+
+Canonical example: `api/controllers/game/rematch.js`
+
+## Helpers
+
+File: `api/helpers/<name>.js`
+
+```js
+module.exports = {
+  friendlyName: 'Helper name',
+  description: 'What it does',
+  inputs: {
+    gameId: { type: 'number', required: true },
+    payload: { type: 'ref', required: true },
+  },
+  sync: true,  // omit for async helpers
+  fn: ({ gameId, payload }, exits) => {
+    try {
+      // ... logic ...
+      return exits.success(result);
+    } catch (err) {
+      return exits.error(err);
+    }
+  },
+};
+```
+
+Canonical example: `api/helpers/broadcast-game-event.js`
+
+### Calling helpers
+
+Cuttle uses positional calling (not `.with()`):
+
+```js
+// Positional (project convention)
+sails.helpers.broadcastGameEvent(gameId, payload);
+await sails.helpers.lockGame(oldGameId);
+
+// Named (.with()) — valid but not used in this codebase
+await sails.helpers.lockGame.with({ gameId: oldGameId });
+```
+
+For async helpers, `await` the call. For `sync: true` helpers, no `await`.
+
+## Policies
+
+File: `api/policies/<name>.js`
+
+```js
+module.exports = function (req, res, next) {
+  const { session } = req;
+  const userIsValid = session.usr && typeof session.usr === 'number';
+  if (session.loggedIn && userIsValid) {
+    return next();
+  }
+  return res.status(401).json({ message: 'Please log in and try again' });
+};
+```
+
+Canonical example: `api/policies/isLoggedIn.js`
+
+Policy chains are configured in `config/policies.js`. Policies run in order before the controller.
+
+## Models
+
+File: `api/models/<Name>.js`
+
+```js
+module.exports = {
+  attributes: {
+    name: { type: 'string', required: true },
+    status: { type: 'number', defaultsTo: 0 },
+    p0: { model: 'user' },
+    p1: { model: 'user' },
+  },
+  // Lifecycle callbacks (optional)
+  beforeCreate(values, proceed) { return proceed(); },
+};
+```
+
+## Socket broadcasting
+
+Two patterns:
+
+**Symmetric broadcast** (same payload to all rooms):
+```js
+sails.helpers.broadcastGameEvent(gameId, payload);
+// broadcasts to: game_<id>_p0, game_<id>_p1, game_<id>_spectator
+```
+
+**Asymmetric broadcast** (different view per player, hides hidden info):
+```js
+const { p0State, p1State, spectatorState } = await sails.helpers.gameStates.createSocketEvents(game, fullGame);
+sails.sockets.broadcast(`game_${gameId}_p0`, 'game', p0State);
+sails.sockets.broadcast(`game_${gameId}_p1`, 'game', p1State);
+sails.sockets.broadcast(`game_${gameId}_spectator`, 'game', spectatorState);
+```
+
+## Routes
+
+`config/routes.js` maps HTTP verbs + paths to controller actions:
+
+```js
+'POST /api/game/:gameId/move': { action: 'game/play-move' },
+'GET  /api/game/:gameId':      { action: 'game/get-game' },
+```
+
+## Error types
+
+| Class | File | HTTP code |
+|-------|------|-----------|
+| `ForbiddenError` | `api/errors/forbiddenError.js` | 403 |
+| `CustomErrorType` | `api/errors/customErrorType.js` | varies |
+
+```js
+const ForbiddenError = require('../../errors/forbiddenError');
+throw new ForbiddenError('You are not a player in this game!');
+```
+
+## Locking pattern
+
+Games use an advisory lock to prevent concurrent mutations:
+
+```js
+game = await sails.helpers.lockGame(gameId);
+// ... make changes ...
+await sails.helpers.unlockGame(game.lock);
+```
+
+Always unlock in the `catch` block too (swallow the unlock error, then handle the original error).
diff --git a/.agents/docs/skill-conventions.md b/.agents/docs/skill-conventions.md
new file mode 100644
index 000000000..66b45bd2e
--- /dev/null
+++ b/.agents/docs/skill-conventions.md
@@ -0,0 +1,41 @@
+# Skill Conventions
+
+## Naming
+
+- Prefix: `ctl-` for all Cuttle skills.
+- Kebab-case after the prefix: `ctl-game-domain`, `ctl-sails-patterns`.
+- Verb-first for workflow skills: `ctl-git-commit`, `ctl-plan-work`.
+- Noun-first for reference/lookup skills: `ctl-game-domain`, `ctl-test-patterns`.
+
+## File structure
+
+Each skill lives at `skills/ctl-<name>/SKILL.md`.
+
+Required frontmatter:
+
+```yaml
+---
+name: ctl-<name>
+description: "<one sentence — front-load the trigger phrases>"
+model: inherit
+allowed-tools: Read, Grep, Glob, Bash
+---
+```
+
+- `description` is what the dispatcher reads to decide whether to route here. Start with the trigger phrase, not a generic label.
+- `model: inherit` defers to the session model. Override only when the skill requires a specific capability.
+- `allowed-tools` — list only what the skill actually needs.
+
+## Size cap
+
+~500 lines per SKILL.md. If a skill grows past this, move detailed examples to `docs/` and link from the skill with a one-liner.
+
+## Trigger writing
+
+Good: `"Invoke on 'where does X live', 'find existing pattern', 'how do I discover'. Glob/grep recipes for finding code by area."`
+
+Bad: `"Helps with discovery"` — not actionable for a dispatcher.
+
+## Subagent definitions
+
+Reviewer subagents live in `agents/ctl-<name>.md`. Use the same frontmatter shape. Reviewers always output a structured report: verdict, evidence, line references, recommended action.
diff --git a/.agents/docs/testing.md b/.agents/docs/testing.md
new file mode 100644
index 000000000..7bf7204d4
--- /dev/null
+++ b/.agents/docs/testing.md
@@ -0,0 +1,94 @@
+# Testing
+
+Cuttle uses two test frameworks:
+
+- **Cypress** for end-to-end (E2E) tests in `tests/e2e/`
+- **Vitest** for unit tests in `tests/unit/`
+
+## Vitest — dual config
+
+| Script | Config | Scope |
+|--------|--------|-------|
+| `npm run test:unit:client` | `vitest.config.mjs` | `tests/unit/**/*.spec.{js,ts}` (excludes sails) |
+| `npm run test:unit:sails` | `tests/unit/vitest-sails.config.mjs` | `tests/unit/specs/sails/**/*` |
+| `npm run test:unit` | runs both above | full unit suite |
+| `npm run test:agents` | `.agents/tools/vitest.config.mjs` | `.agents/tools/__tests__/**/*.spec.mjs` |
+
+Sails tests require a running Sails instance (setup in `tests/unit/setup-sails.vitest.js`). They run sequentially (`maxWorkers: 1, isolate: false`).
+
+Client tests use `environment: 'node'` and can run in parallel.
+
+## Cypress — E2E helpers
+
+Helpers are in `tests/e2e/support/helpers.js` and `commands.js`.
+
+### `cy.setupGameAsP0()` / `cy.setupGameAsP1()`
+
+Runs in `beforeEach`. Automatically:
+1. Signs up two accounts.
+2. Creates and joins a game as both players.
+3. Readies both players and waits for the game to load.
+
+### `cy.loadGameFixture(fixture)`
+
+Loads a specific game state. All fields are optional.
+
+```js
+cy.loadGameFixture({
+  p0Hand: [Card.ACE_OF_CLUBS, Card.SEVEN_OF_CLUBS],
+  p0Points: [Card.TWO_OF_CLUBS],
+  p0FaceCards: [Card.KING_OF_SPADES],
+  p1Hand: [Card.TEN_OF_CLUBS],
+  p1Points: [Card.SIX_OF_HEARTS],
+  p1FaceCards: [Card.QUEEN_OF_HEARTS],
+  topCard: Card.FIVE_OF_DIAMONDS,
+  secondCard: Card.EIGHT_OF_SPADES,
+  scrap: [Card.TWO_OF_HEARTS],
+});
+```
+
+### `assertGameState(playerNum, fixture)`
+
+Asserts the full game state from a player's perspective. `playerNum` is `0` or `1`.
+
+```js
+assertGameState(0, {
+  p0Hand: [Card.ACE_OF_CLUBS],
+  p0Points: [Card.TWO_OF_CLUBS, Card.SEVEN_OF_CLUBS],
+  ...
+});
+```
+
+## Card data selectors
+
+Format: `data-<player>-<location>-card=<rank>_<suit>`
+
+- `<player>`: `player` (the current player) or `opponent`
+- `<location>`: `hand`, `point`, `face-card`
+- `<rank>`: integer 1–13
+- `<suit>`: integer 0–3 (Clubs=0, Diamonds=1, Hearts=2, Spades=3)
+
+```js
+cy.get('[data-player-hand-card=7_0]').click();       // 7 of Clubs in hand
+cy.get('[data-move-choice=scuttle]').click();        // choose scuttle
+cy.get('[data-opponent-point-card=6_2]').click();    // opponent's 6 of Hearts
+```
+
+## Move data selectors
+
+Format: `data-move-choice=<move-name>`
+
+Move names match the API slug: `points`, `scuttle`, `untargetedOneOff`, `targetedOneOff`, `jack`, `faceCard`, `draw`.
+
+## Test structure
+
+E2E specs are in `tests/e2e/specs/`:
+
+- `in-game/` — in-game moves and interactions
+- `out-of-game/` — lobby, stats, profile
+- `playground/` — development/debug specs
+
+Unit specs are in `tests/unit/specs/`:
+
+- `*.spec.js` — client-side (Vue, Pinia, utilities)
+- `sails/` — server-side Sails.js logic
diff --git a/.agents/docs/vue-patterns.md b/.agents/docs/vue-patterns.md
new file mode 100644
index 000000000..f4295bae3
--- /dev/null
+++ b/.agents/docs/vue-patterns.md
@@ -0,0 +1,135 @@
+# Vue Patterns
+
+Detailed reference for frontend patterns in Cuttle. See `ctl-vue-patterns` skill for quick lookups.
+
+## Component structure
+
+Cuttle uses Vue 3 with `<script setup>` and Vuetify 3.
+
+```vue
+<script setup>
+import { ref, computed } from 'vue';
+import { useGameStore } from '@/stores/game';
+
+const gameStore = useGameStore();
+const localState = ref(null);
+
+const derivedValue = computed(() => gameStore.someField);
+</script>
+
+<template>
+  <v-dialog v-model="isOpen">
+    <v-card>
+      <v-card-title>Title</v-card-title>
+      <v-card-actions>
+        <v-btn @click="handleAction">Action</v-btn>
+      </v-card-actions>
+    </v-card>
+  </v-dialog>
+</template>
+```
+
+## File locations
+
+| Type | Path |
+|------|------|
+| Route entry point | `src/routes/<routeName>/<RouteName>View.vue` |
+| Page-specific components | `src/routes/<routeName>/components/` |
+| Shared components | `src/components/` |
+| Stores | `src/stores/` |
+| Router | `src/router.js` |
+
+## Pinia stores
+
+All stores use the composition API form (not options API):
+
+```js
+import { ref, computed } from 'vue';
+import { defineStore } from 'pinia';
+
+export const useGameStore = defineStore('game', () => {
+  // State
+  const id = ref(null);
+  const status = ref(null);
+
+  // Getters
+  const isStarted = computed(() => status.value === GameStatus.STARTED);
+
+  // Actions
+  function setGame(gameData) {
+    id.value = gameData.id;
+    status.value = gameData.status;
+  }
+
+  return { id, status, isStarted, setGame };
+});
+```
+
+Canonical example: `src/stores/game.js`
+
+### Store discovery
+
+```bash
+grep -r "defineStore" src/stores/
+```
+
+## Imports and aliases
+
+| Alias | Resolves to |
+|-------|-------------|
+| `@` | `src/` |
+| `_` | project root |
+
+```js
+import { useGameStore } from '@/stores/game';
+import MoveType from '../../utils/MoveType.json';  // relative from src/
+import { version } from '_/package.json';           // from root
+```
+
+## Vuetify usage
+
+- Use Vuetify components (`v-btn`, `v-dialog`, `v-card`, `v-list`, etc.) for all UI.
+- Do not write raw HTML buttons or modals.
+- Look at `src/components/BaseDialog.vue` for dialog patterns.
+- Styles use `sass/variables.scss` for design tokens.
+
+## Internationalization
+
+Cuttle uses `vue-i18n`. All user-visible strings go through `$t('key')`:
+
+```vue
+<template>
+  <span>{{ $t('game.draw') }}</span>
+</template>
+```
+
+Translation files are in `src/i18n/`.
+
+## Socket connection
+
+The Sails socket client is initialized in `src/plugins/sails.js` and imported as `io`:
+
+```js
+import { io } from '@/plugins/sails.js';
+```
+
+In-game socket events are handled in `src/plugins/sockets/inGameEvents.js`.
+
+## Router navigation
+
+```js
+import { useRouter } from 'vue-router';
+const router = useRouter();
+router.push({ name: 'game', params: { gameId } });
+```
+
+Route names are defined in `src/router.js`.
+
+## Key constants
+
+| File | Contents |
+|------|---------|
+| `utils/MoveType.json` | Move type strings |
+| `utils/GameStatus.json` | Game status enums |
+| `utils/GamePhase.json` | Game phase enums |
+| `utils/local-storage-utils.js` | LocalStorage key constants |
diff --git a/.agents/skills/ctl-code-review/SKILL.md b/.agents/skills/ctl-code-review/SKILL.md
new file mode 100644
index 000000000..540cec403
--- /dev/null
+++ b/.agents/skills/ctl-code-review/SKILL.md
@@ -0,0 +1,102 @@
+---
+name: ctl-code-review
+description: "Review code changes against Cuttle's discover-plan-execute workflow, safety rules, and AGENTS.md conventions. Use on 'review my changes', 'check this diff', 'review this PR', '/ctl-code-review'. Dispatches to subagents for security, architecture, and performance."
+model: inherit
+allowed-tools: Read, Grep, Glob, Bash, Agent
+---
+
+# Code Review
+
+Compliance review for Cuttle. Checks AGENTS.md rules, then dispatches to specialist subagents.
+
+## Input
+
+Run against staged diff, a branch, or a PR:
+
+```bash
+# Current branch vs main
+git diff main..HEAD
+
+# Specific PR
+gh pr diff <number>
+```
+
+## Phase 1: Automated checks
+
+Before reviewing code, verify the basics passed:
+
+```bash
+npm run lint
+npm run test:unit
+```
+
+If either fails, report which checks failed. Do not proceed with review until they're green.
+
+## Phase 2: AGENTS.md compliance
+
+Check against AGENTS.md:
+
+1. **Discovery first** — Were patterns discovered before code was written? Look for evidence of glob/grep discovery in the PR description or commit messages.
+2. **Safety rules** — No hardcoded secrets. Session validation present on game-mutating routes. Policies applied (`config/policies.js`).
+3. **Pattern consistency** — Controller follows the lock/unlock/catch pattern. Helper follows the `inputs`/`fn`/`exits` structure. Vue SFC uses `<script setup>`.
+4. **No banned patterns** — No `.with()` on Sails helpers. No `v-html` with dynamic content. No `git add -A`.
+5. **Test coverage** — New behavior has E2E or unit test coverage.
+
+## Phase 3: Subagent dispatch
+
+Dispatch to specialist reviewers in parallel:
+
+```
+Agent(ctl-architecture-reviewer): review for module boundaries, race conditions, store mutation hygiene
+Agent(ctl-security-reviewer): review for CSRF, XSS, auth gaps, policy chain
+Agent(ctl-performance-reviewer): review for socket cleanup, Pinia reactivity, memory leaks
+```
+
+Dispatch all three. Collect reports. Do not proceed to Phase 4 until all three return.
+
+## Phase 4: Report
+
+Structure:
+
+```
+## Code Review Report
+
+### Automated Checks
+✅ lint: passed
+✅ test:unit: passed
+
+### AGENTS.md Compliance
+- [PASS/FAIL] Discovery evidence present
+- [PASS/FAIL] Safety rules
+- [PASS/FAIL] Pattern consistency
+- [PASS/FAIL] Test coverage
+
+### Architecture (ctl-architecture-reviewer)
+[findings]
+
+### Security (ctl-security-reviewer)
+[findings]
+
+### Performance (ctl-performance-reviewer)
+[findings]
+
+### Verdict
+[APPROVE / REQUEST CHANGES / NEEDS DISCUSSION]
+
+### Required actions (if any)
+- [specific file:line — what to fix]
+```
+
+## Severity levels
+
+- **Block** — must fix before merge (security, data loss, test failure)
+- **Request** — should fix before merge (pattern violation, missing test)
+- **Suggest** — optional improvement (style, readability)
+
+## Final verification checklist (from AGENTS.md)
+
+- [ ] Implementation matches discovered patterns
+- [ ] No secrets hardcoded; policies correctly applied
+- [ ] Changes align with existing file and project structures
+- [ ] `npm run lint` passes
+- [ ] `npm run test:unit` passes
diff --git a/.agents/skills/ctl-discover/SKILL.md b/.agents/skills/ctl-discover/SKILL.md
new file mode 100644
index 000000000..c7d7bc43c
--- /dev/null
+++ b/.agents/skills/ctl-discover/SKILL.md
@@ -0,0 +1,125 @@
+---
+name: ctl-discover
+description: "Glob/grep recipes for finding existing patterns by area. Use on 'where does X live', 'find existing pattern for', 'how do I discover', 'search for', 'find files'. Returns file paths and brief descriptions before proposing any code."
+model: inherit
+allowed-tools: Read, Grep, Glob, Bash
+---
+
+# Discover
+
+Pattern-first lookup for Cuttle. Always run discovery before proposing code.
+
+## Workflow
+
+1. Identify the area from the request (state, controller, component, test, helper, policy).
+2. Run the recipe for that area.
+3. Report findings: `Found {N} examples of {pattern}: file:line — description`.
+4. Ask "Ready to implement following this pattern?" before writing any code.
+
+## Recipes by area
+
+### State management (Pinia stores)
+
+```bash
+grep -r "defineStore" src/stores/ --include="*.js" -l
+grep -r "defineStore" src/stores/ --include="*.js" -n
+```
+
+Look for: store name, state refs, computed getters, returned actions.
+
+### Frontend components
+
+```bash
+# Shared components
+find src/components -name "*.vue" | head -20
+
+# Route-specific components
+find src/routes -name "*.vue" | head -30
+find src/routes -name "components" -type d
+
+# A specific route's entry point
+ls src/routes/<routeName>/
+```
+
+Pattern: `src/routes/<name>/<Name>View.vue` is the entry point; `src/routes/<name>/components/` holds page-specific components.
+
+### Backend controllers
+
+```bash
+find api/controllers -name "*.js" | head -20
+# For a specific action
+ls api/controllers/game/
+cat api/controllers/game/rematch.js
+```
+
+Pattern: `module.exports = async function(req, res) { ... }` with try/catch + lock/unlock.
+
+### Helpers
+
+```bash
+find api/helpers -name "*.js" | head -20
+grep -r "sails.helpers\." api/controllers/ --include="*.js" -h | sort -u | head -20
+```
+
+### Policies
+
+```bash
+ls api/policies/
+grep -r "api/policies" config/policies.js
+```
+
+### Socket events
+
+```bash
+grep -r "broadcastGameEvent\|publishGameState\|sails.sockets" api/ --include="*.js" -l
+grep -r "on('game'" src/ --include="*.js" -l
+cat api/helpers/broadcast-game-event.js
+```
+
+### E2E tests
+
+```bash
+find tests/e2e/specs -name "*.spec.js" | head -20
+ls tests/e2e/specs/in-game/
+cat tests/e2e/support/helpers.js
+```
+
+### Unit tests
+
+```bash
+find tests/unit/specs -name "*.spec.js" | head -20
+ls tests/unit/specs/sails/
+```
+
+### Routes config
+
+```bash
+grep -n "game\|move\|rematch" config/routes.js | head -20
+```
+
+### Models
+
+```bash
+ls api/models/
+cat api/models/Game.js
+```
+
+## Discovery hierarchy (per AGENTS.md)
+
+1. Existing code (search first)
+2. `docs/*.md` for standards
+3. Config files (`.eslintrc.js`, `vite.config.mjs`)
+
+## Output format
+
+```
+Found {N} examples of {pattern}:
+- {file}:{line} — {brief description}
+- {file}:{line} — {brief description}
+
+Common pattern: {summary}
+
+Ready to implement following this pattern?
+```
+
+Never skip the "Ready to implement?" gate.
diff --git a/.agents/skills/ctl-game-domain/SKILL.md b/.agents/skills/ctl-game-domain/SKILL.md
new file mode 100644
index 000000000..637afbecc
--- /dev/null
+++ b/.agents/skills/ctl-game-domain/SKILL.md
@@ -0,0 +1,108 @@
+---
+name: ctl-game-domain
+description: "Cuttle game vocabulary index. Use on 'what is a one-off', 'what does scuttle mean', 'what rank is a jack', 'suit order', 'how does the seven work', 'p0 vs p1', 'card selector format', or any domain term lookup. Anti-hallucination guard for game-specific logic."
+model: inherit
+allowed-tools: Read, Grep
+---
+
+# Game Domain
+
+Canonical vocabulary for Cuttle. Full details in `.agents/docs/game-domain.md` and `docs/game-rules.md`.
+
+## Players
+
+| Term | Meaning |
+|------|---------|
+| `p0` | Player dealt 5 cards — goes first |
+| `p1` | Player dealt 6 cards |
+| `pNum` | Integer: `0` or `1` |
+
+## Card ranks (1–13)
+
+| Rank | Name | Type | Effect |
+|------|------|------|--------|
+| 1 | Ace | One-off | Scrap all point cards (both players) |
+| 2 | Two | One-off | Counter a one-off OR scrap a royal/glasses eight |
+| 3 | Three | One-off | Take one card from scrap pile to hand |
+| 4 | Four | One-off | Opponent discards 2 cards of their choice |
+| 5 | Five | One-off | Discard 1, draw up to 3 from deck |
+| 6 | Six | One-off | Scrap all royals and glasses eights (both players) |
+| 7 | Seven | One-off | Reveal top 2 deck cards, play one immediately |
+| 8 | Eight | Royal | "Glasses Eight" — opponent plays with hand revealed |
+| 9 | Nine | One-off | Return opponent's field card to hand (frozen 1 turn) |
+| 10 | Ten | Points only | 10 points |
+| 11 | Jack | Royal | Steal an opponent's point card |
+| 12 | Queen | Royal | Protect your other cards from targeting |
+| 13 | King | Royal | Reduce points-to-win threshold |
+
+Number cards (Ace–Ten) score their face value as points when played to the field.
+
+## Card suits (0–3)
+
+| Integer | Suit | Scuttle rank |
+|---------|------|--------------|
+| 0 | Clubs | weakest |
+| 1 | Diamonds | |
+| 2 | Hearts | |
+| 3 | Spades | strongest |
+
+Suit is the tiebreaker for scuttle: you can scuttle a card of the same rank only if your suit is higher.
+
+## Game actions
+
+| Action | API slug | Trigger |
+|--------|----------|---------|
+| Draw | `draw` | Click deck |
+| Play for points | `points` | Select card → click own field |
+| Scuttle | `scuttle` | Select higher card → click opponent's point card |
+| Royal / Glasses Eight | `faceCard` | Select J/Q/K/8 → click own field |
+| One-off (untargeted) | `untargetedOneOff` | Select A/3/4/5/6 → click scrap pile |
+| One-off (targeted) | `targetedOneOff` | Select 2/7/9 → click target |
+| Jack (steal) | `jack` | Select Jack → click opponent's point card |
+| Counter | `counter` | Play Two in response to opponent's one-off |
+| Resolve | `resolve` | Resolve counter chain |
+
+## Card selector format
+
+```
+data-<player>-<location>-card=<rank>_<suit>
+```
+
+| Segment | Values |
+|---------|--------|
+| `<player>` | `player` (current player) or `opponent` |
+| `<location>` | `hand`, `point`, `face-card` |
+| `<rank>` | 1–13 |
+| `<suit>` | 0–3 |
+
+Examples:
+```js
+'[data-player-hand-card=7_0]'       // 7 of Clubs in hand
+'[data-opponent-point-card=6_2]'    // opponent's 6 of Hearts
+'[data-move-choice=scuttle]'        // scuttle move option
+```
+
+## Win conditions
+
+- Default: first to 21+ points.
+- 1 King: 14pts to win. 2 Kings: 10pts. 3 Kings: 5pts. 4 Kings: 0pts (win on play).
+- Three consecutive passes → stalemate.
+
+## Terminology to avoid confusing
+
+| Do not say | Say instead |
+|------------|-------------|
+| "destroy" | "scrap" |
+| "discard pile" | "scrap pile" |
+| "play area" | "field" or "points"/"faceCards" depending on card type |
+| "special cards" | "royals and glasses eights" |
+| "instant effects" | "one-offs" |
+
+## Key source files
+
+- `docs/game-rules.md` — full rules for human reference
+- `.agents/docs/game-domain.md` — extended glossary with code examples
+- `utils/MoveType.json` — all move type strings
+- `utils/GameStatus.json` — game status enum
+- `src/stores/game.js` — GameCard class, card sorting, socket events
+- `api/helpers/broadcast-game-event.js` — socket broadcast pattern
diff --git a/.agents/skills/ctl-git-commit/SKILL.md b/.agents/skills/ctl-git-commit/SKILL.md
new file mode 100644
index 000000000..753bcae63
--- /dev/null
+++ b/.agents/skills/ctl-git-commit/SKILL.md
@@ -0,0 +1,91 @@
+---
+name: ctl-git-commit
+description: "Create a git commit on the current branch using Cuttle's conventional commit format. Use on 'commit', 'save changes', 'create a commit', or when changes are ready to commit. Mines git log for scope, never invents one."
+model: inherit
+allowed-tools: Read, Bash
+---
+
+# Git Commit
+
+Stage and commit changes using Cuttle's conventional commit format.
+
+## Hard rules
+
+- Never `git add -A` or `git add .` — stage specific files only.
+- Never `--no-verify` or any hook bypass.
+- Never bump `package.json` version — CI handles this automatically.
+- Commits on `main` are blocked by the git-guardrails hook. Create a feature branch first.
+
+## Workflow
+
+### 1. Check status
+
+```bash
+git status --porcelain
+git diff --stat
+```
+
+If nothing is staged, show unstaged changes and ask what to stage.
+
+### 2. Mine scope from git log
+
+```bash
+git log --format="%s" --no-merges | grep -oP '^\w+\([^)]+\)' | sort | uniq -c | sort -rn | head -15
+```
+
+Use the most relevant existing scope. Do not invent new scopes unless the change truly belongs to a new area.
+
+### 3. Determine type
+
+| Type | When |
+|------|------|
+| `feat` | New user-facing feature |
+| `fix` | Bug fix |
+| `test` | Adding or updating tests |
+| `style` | Visual/style change, no logic |
+| `refactor` | Code restructure, no behavior change |
+| `chore` | Build, deps, tooling, agents infrastructure |
+| `docs` | Documentation only |
+
+### 4. Format message
+
+```
+<type>(<scope>): <subject>
+```
+
+- Subject: lowercase, imperative, no period.
+- Subject under 72 characters.
+- Body: optional, explains WHY not WHAT.
+
+### 5. Show and confirm
+
+Present the staged files and proposed message. Wait for approval.
+
+### 6. Commit
+
+```bash
+git commit -m "$(cat <<'EOF'
+type(scope): subject
+EOF
+)"
+```
+
+### 7. Hook failure
+
+If the guardrails hook blocks the commit (e.g., committing on `main`), diagnose and fix. Never use `--no-verify`.
+
+## Common scopes (mined from history)
+
+| Scope | Area |
+|-------|------|
+| `GameView` | `src/routes/game/GameView.vue` |
+| `rematch.js` | `api/controllers/game/rematch.js` |
+| `sockets` | Socket event handling |
+| `lock-game` | `api/helpers/lock-game.js` |
+| `announcementData` | Announcement dialog data |
+| `deps` | Dependency updates |
+| `agents` | `.agents/` infrastructure |
+
+## Full reference
+
+`.agents/docs/commit-format.md`
diff --git a/.agents/skills/ctl-github-create-pr/SKILL.md b/.agents/skills/ctl-github-create-pr/SKILL.md
new file mode 100644
index 000000000..977ab57c3
--- /dev/null
+++ b/.agents/skills/ctl-github-create-pr/SKILL.md
@@ -0,0 +1,93 @@
+---
+name: ctl-github-create-pr
+description: "Create a GitHub pull request for Cuttle using gh CLI. Use on 'create PR', 'open a PR', 'make a pull request', '/ctl-github-create-pr'. Surfaces the version label requirement before drafting the PR body."
+model: inherit
+allowed-tools: Read, Bash
+---
+
+# GitHub Create PR
+
+Create a pull request using `gh` CLI following Cuttle's PR conventions.
+
+## Before drafting
+
+### 1. Confirm branch and commits
+
+```bash
+git branch --show-current
+git log main..HEAD --oneline
+git diff main..HEAD --stat
+```
+
+### 2. Ask: Draft or ready for review?
+
+Always ask before creating. Draft PRs skip CI checks. Ready-for-review PRs run the full suite.
+
+### 3. Confirm version label
+
+Every PR requires exactly one version label applied after creation:
+
+| Label | Use when |
+|-------|----------|
+| `patch-version` | Bug fix, docs, chore, style — no new features |
+| `minor-version` | New feature, backward-compatible |
+| `major-version` | Breaking change |
+
+Suggest the appropriate label in the PR description. The core team applies it.
+
+### 4. Check for linked issue
+
+If the branch is named `feature/123` or `bug/123`, add `Closes #123` to the PR body.
+
+## Branch naming
+
+From `docs/CONTRIBUTING.md`:
+- Features: `feature/[issue-number-or-description]`
+- Bug fixes: `bug/[issue-number-or-description]`
+
+## Create the PR
+
+The body must follow `.github/PULL_REQUEST_TEMPLATE.md` exactly:
+
+```bash
+gh pr create \
+  --title "type(scope): subject" \
+  --body "$(cat <<'EOF'
+<!-- Thanks for contributing to Cuttle! 🎉 -->
+
+## Issue number
+
+Resolves #[issue] (or "No linked issue — [reason]" if none)
+
+## Please check the following
+
+- [ ] Do the tests still pass? (see [Run the Tests](https://github.com/cuttle-cards/cuttle/blob/main/docs/setup-development.md#run-the-tests))
+- [ ] Is the code formatted properly? (see [Linting (Formatting)](https://github.com/cuttle-cards/cuttle/blob/main/docs/setup-development.md#linting-formatting))
+- For New Features:
+  - [ ] Have tests been added to cover any new features or fixes?
+  - [ ] Has the documentation been updated accordingly?
+
+## Please describe additional details for testing this change
+
+[Manual testing steps, smoke test instructions, or verification commands]
+EOF
+)"
+```
+
+For draft: add `--draft` flag.
+
+## After creating
+
+1. Note the PR URL.
+2. Remind: a version label must be applied before merge.
+3. Do not push additional commits without mentioning they'll re-trigger CI.
+
+## Checks that must pass before requesting review
+
+- `npm run lint` — zero errors
+- `npm run test:unit` — all green
+- E2E tests pass (CI runs these automatically on non-draft PRs)
+
+## Full reference
+
+`.agents/docs/github.md`
diff --git a/.agents/skills/ctl-plan-work/SKILL.md b/.agents/skills/ctl-plan-work/SKILL.md
new file mode 100644
index 000000000..01eb41852
--- /dev/null
+++ b/.agents/skills/ctl-plan-work/SKILL.md
@@ -0,0 +1,95 @@
+---
+name: ctl-plan-work
+description: "Plan work before implementing, following AGENTS.md discover-plan-execute. Use on 'plan this', 'how should I approach', 'outline the work', 'what files will change', or before any non-trivial implementation. Requires discovery before planning."
+model: inherit
+allowed-tools: Read, Grep, Glob, Bash
+---
+
+# Plan Work
+
+Structure implementation plans following AGENTS.md's discover-plan-execute workflow.
+
+## When to use
+
+Before writing code for any task that touches more than one file or introduces new behavior.
+
+## Phase 1: Discovery
+
+Run `ctl-discover` first. No plan without discovery.
+
+```bash
+# Find similar implementations
+grep -r "relevantPattern" src/ api/ --include="*.{js,vue}" -l
+
+# Check existing patterns in the area
+find api/controllers -name "*.js" | head -10
+find src/routes -name "*.vue" | head -10
+```
+
+Document what you found:
+```
+Found {N} examples of {pattern}:
+- {file}:{line} — {description}
+Common pattern: {summary}
+```
+
+## Phase 2: Plan template
+
+```
+## Plan: {task description}
+
+### Files I'll modify
+- `path/to/file.js` — what changes
+- `path/to/component.vue` — what changes
+
+### New files (if any)
+- `path/to/new-file.js` — purpose
+
+### Patterns I found
+- `file:line` — pattern used as model
+- `file:line` — pattern used as model
+
+### Approach
+1. Step one (with file reference)
+2. Step two
+3. Step three
+
+### Validation
+- [ ] `npm run lint`
+- [ ] `npm run test:unit`
+- [ ] E2E: describe what to test manually
+- [ ] Describe the happy path to verify
+
+Proceed?
+```
+
+## Phase 3: Gate
+
+Do not write a single line of code until the plan is approved. Present the plan, wait for "proceed" or equivalent.
+
+## Rules
+
+- One concern per branch. If discovery reveals an adjacent bug: "Same branch or separate?"
+- Do not expand scope mid-plan. New discoveries → surface them, don't absorb them.
+- Validation steps must be specific (which test, which route, what assertion).
+- The plan is a contract. If implementation diverges, update the plan and re-confirm.
+
+## Discovery-to-plan examples
+
+**Adding a new one-off:**
+1. `ctl-discover` → find existing one-off controller in `api/controllers/game/`
+2. Find the move type in `utils/MoveType.json`
+3. Find the socket broadcast pattern in `api/helpers/broadcast-game-event.js`
+4. Find the Cypress test for a similar one-off in `tests/e2e/specs/in-game/one-offs/`
+5. Plan: new controller, update routes, update store handler, write E2E test
+
+**Adding a Vue dialog:**
+1. `ctl-discover` → find `BaseDialog.vue` and similar dialogs in `src/routes/`
+2. Find i18n key patterns in `src/i18n/`
+3. Find Pinia store actions triggered by the dialog
+4. Plan: new component file, new i18n keys, store action update, test
+
+## Full reference
+
+- `AGENTS.md` — "Communication Patterns" → "Plan Before Execute"
+- `docs/agentic-development.md` — "AI-Powered Workflow"
diff --git a/.agents/skills/ctl-sails-patterns/SKILL.md b/.agents/skills/ctl-sails-patterns/SKILL.md
new file mode 100644
index 000000000..111c0edaa
--- /dev/null
+++ b/.agents/skills/ctl-sails-patterns/SKILL.md
@@ -0,0 +1,177 @@
+---
+name: ctl-sails-patterns
+description: "Sails.js backend patterns for Cuttle. Use on 'write a controller', 'add a helper', 'create a policy', 'add a route', 'sails helper syntax', 'lock game', 'broadcast socket event', or any backend/API question."
+model: inherit
+allowed-tools: Read, Grep, Glob, Bash
+---
+
+# Sails Patterns
+
+Quick reference for Cuttle's Sails.js backend. Full details in `.agents/docs/sails-patterns.md`.
+
+## Before writing any backend code
+
+```bash
+# Find similar controllers
+find api/controllers -name "*.js" | head -20
+
+# Find existing helper calls
+grep -r "sails.helpers\." api/controllers/ --include="*.js" -h | sort -u | head -20
+
+# Check existing helpers
+ls api/helpers/
+
+# Check policy chain
+cat config/policies.js
+```
+
+## Controller template
+
+File: `api/controllers/<area>/<action>.js`
+
+```js
+const GameStatus = require('../../../utils/GameStatus.json');
+const CustomErrorType = require('../../errors/customErrorType');
+const ForbiddenError = require('../../errors/forbiddenError');
+
+module.exports = async function (req, res) {
+  let game;
+  try {
+    const { usr: userId } = req.session;
+    let { gameId } = req.params;
+    gameId = Number(gameId);
+    const { fieldName } = req.body;
+
+    game = await sails.helpers.lockGame(gameId);
+
+    // Validate user is a player
+    const playerIds = [game.p0?.id, game.p1?.id].filter(Boolean);
+    if (!playerIds.includes(userId)) {
+      throw new ForbiddenError('You are not a player in this game!');
+    }
+
+    // ... business logic ...
+
+    await sails.helpers.unlockGame(game.lock);
+    return res.ok({ result });
+  } catch (err) {
+    try { await sails.helpers.unlockGame(game.lock); } catch (_) {}
+    const message = err.raw?.message ?? err;
+    switch (err?.code) {
+      case CustomErrorType.FORBIDDEN: return res.forbidden({ message });
+      default: return res.serverError({ message });
+    }
+  }
+};
+```
+
+Canonical example: `api/controllers/game/rematch.js`
+
+## Helper template
+
+```js
+module.exports = {
+  friendlyName: 'Helper name',
+  description: 'What it does in one sentence',
+  inputs: {
+    gameId: { type: 'number', required: true },
+  },
+  // Add `sync: true` only for synchronous helpers
+  fn: async ({ gameId }, exits) => {
+    try {
+      // ... logic ...
+      return exits.success(result);
+    } catch (err) {
+      return exits.error(err);
+    }
+  },
+};
+```
+
+Canonical example: `api/helpers/broadcast-game-event.js`
+
+### Calling helpers (positional form — project convention)
+
+```js
+// Async
+const game = await sails.helpers.lockGame(gameId);
+await sails.helpers.unlockGame(game.lock);
+
+// Sync
+sails.helpers.broadcastGameEvent(gameId, payload);
+```
+
+Do not use `.with()` — the project uses positional calls consistently.
+
+## Policy template
+
+```js
+module.exports = function (req, res, next) {
+  const { session } = req;
+  const userIsValid = session.usr && typeof session.usr === 'number';
+  if (session.loggedIn && userIsValid) {
+    return next();
+  }
+  return res.status(401).json({ message: 'Please log in and try again' });
+};
+```
+
+Canonical example: `api/policies/isLoggedIn.js`
+
+## Route registration
+
+File: `config/routes.js`
+
+```js
+'POST /api/game/:gameId/rematch': { action: 'game/rematch' },
+'GET  /api/game/:gameId':          { action: 'game/get-game' },
+```
+
+## Socket broadcasting
+
+**Symmetric** (same payload to all rooms):
+```js
+sails.helpers.broadcastGameEvent(gameId, { change: 'eventName', ...data });
+// Broadcasts to: game_<id>_p0, game_<id>_p1, game_<id>_spectator
+```
+
+**Asymmetric** (per-player views — hides opponent's hidden cards):
+```js
+const { p0State, p1State, spectatorState } = await sails.helpers.gameStates
+  .createSocketEvents(game, newFullGame);
+sails.sockets.broadcast(`game_${gameId}_p0`, 'game', p0State);
+sails.sockets.broadcast(`game_${gameId}_p1`, 'game', p1State);
+sails.sockets.broadcast(`game_${gameId}_spectator`, 'game', spectatorState);
+```
+
+Use asymmetric when the new game state includes hidden information (e.g., opponent's hand).
+
+## Locking pattern
+
+Always lock before reading game state, always unlock in catch:
+
+```js
+game = await sails.helpers.lockGame(gameId);
+// make changes
+await sails.helpers.unlockGame(game.lock);
+```
+
+## Error types
+
+```js
+const ForbiddenError = require('../../errors/forbiddenError');
+const CustomErrorType = require('../../errors/customErrorType');
+
+throw new ForbiddenError('message');  // → res.forbidden()
+```
+
+## Security rules
+
+- Every game-mutating route must be protected by `isLoggedIn` policy.
+- Always validate that `req.session.usr` matches a player in the game before mutating.
+- Never trust client-supplied `userId` — always read from `req.session.usr`.
+- No hardcoded secrets; use Sails config.
+
+## Full reference
+
+`.agents/docs/sails-patterns.md`
diff --git a/.agents/skills/ctl-test-patterns/SKILL.md b/.agents/skills/ctl-test-patterns/SKILL.md
new file mode 100644
index 000000000..b5ecbbcd0
--- /dev/null
+++ b/.agents/skills/ctl-test-patterns/SKILL.md
@@ -0,0 +1,176 @@
+---
+name: ctl-test-patterns
+description: "Testing patterns for Cuttle — Cypress E2E and Vitest unit tests. Use on 'write a test', 'add a Cypress spec', 'write a unit test', 'how do I set up a game in tests', 'loadGameFixture', 'assertGameState', 'cy.setupGameAsP0', or any testing question."
+model: inherit
+allowed-tools: Read, Grep, Glob, Bash
+---
+
+# Test Patterns
+
+Quick reference for Cuttle's test infrastructure. Full details in `.agents/docs/testing.md`.
+
+## Before writing tests
+
+```bash
+# Find similar E2E specs
+ls tests/e2e/specs/in-game/
+find tests/e2e/specs -name "*.spec.js" | head -20
+
+# Find similar unit tests
+find tests/unit/specs -name "*.spec.js" | head -10
+
+# Read the test helpers
+cat tests/e2e/support/helpers.js
+grep -n "Cypress.Commands.add" tests/e2e/support/commands.js | head -20
+```
+
+## Cypress E2E — file location
+
+```
+tests/e2e/specs/in-game/        # in-game moves and interactions
+tests/e2e/specs/out-of-game/    # lobby, stats, profile, rankings
+tests/e2e/specs/playground/     # development/debug
+```
+
+## Cypress E2E — basic structure
+
+```js
+describe('Feature name', () => {
+  beforeEach(() => {
+    cy.setupGameAsP0();  // or cy.setupGameAsP1()
+  });
+
+  it('does something', () => {
+    cy.loadGameFixture(0, {
+      p0Hand: [Card.SEVEN_OF_CLUBS],
+      p0Points: [Card.TWO_OF_CLUBS],
+      p1Points: [Card.SIX_OF_HEARTS],
+    });
+
+    cy.get('[data-player-hand-card=7_0]').click();
+    cy.get('[data-move-choice=untargetedOneOff]').click();
+
+    assertGameState(0, {
+      p0Hand: [],
+      p0Points: [Card.TWO_OF_CLUBS],
+      p1Points: [Card.SIX_OF_HEARTS],
+      scrap: [Card.SEVEN_OF_CLUBS],
+    });
+  });
+});
+```
+
+## `cy.setupGameAsP0()` / `cy.setupGameAsP1()`
+
+Run in `beforeEach`. Automatically:
+1. Signs up two accounts
+2. Creates and joins a game
+3. Readies both players and waits for load
+
+## `cy.loadGameFixture(pNum, fixture)`
+
+Sets the game into a specific state. `pNum` is `0` or `1`.
+
+```js
+cy.loadGameFixture(0, {
+  p0Hand: [Card.ACE_OF_CLUBS, Card.SEVEN_OF_CLUBS],
+  p0Points: [Card.TWO_OF_CLUBS, Card.TEN_OF_HEARTS],
+  p0FaceCards: [Card.KING_OF_SPADES],
+  p1Hand: [Card.TEN_OF_CLUBS],
+  p1Points: [Card.SIX_OF_HEARTS],
+  p1FaceCards: [Card.QUEEN_OF_HEARTS],
+  topCard: Card.FIVE_OF_DIAMONDS,
+  secondCard: Card.EIGHT_OF_SPADES,
+  scrap: [Card.TWO_OF_HEARTS],
+});
+```
+
+All fields are optional.
+
+## `assertGameState(pNum, fixture)`
+
+Asserts full game state from a player's perspective. Same shape as `loadGameFixture`.
+
+```js
+assertGameState(0, {
+  p0Points: [Card.TWO_OF_CLUBS, Card.SEVEN_OF_CLUBS],
+  p1Points: [],
+  scrap: [Card.SIX_OF_HEARTS],
+});
+```
+
+## Card data selectors
+
+Format: `data-<player>-<location>-card=<rank>_<suit>`
+
+```js
+'[data-player-hand-card=7_0]'        // 7 of Clubs in player's hand
+'[data-opponent-point-card=6_2]'     // opponent's 6 of Hearts on field
+'[data-player-face-card=13_3]'       // player's King of Spades on field
+'[data-move-choice=scuttle]'         // scuttle move option button
+```
+
+## Move selectors
+
+`[data-move-choice=<slug>]` where slug matches the API endpoint:
+
+`points` · `scuttle` · `faceCard` · `untargetedOneOff` · `targetedOneOff` · `jack` · `counter` · `resolve` · `draw`
+
+## Making opponent moves
+
+```js
+cy.drawCardOpponent();
+cy.playPointsOpponent(Card.TEN_OF_CLUBS);
+cy.playFaceCardOpponent(Card.QUEEN_OF_HEARTS);
+cy.playOneOffOpponent(Card.ACE_OF_CLUBS);
+```
+
+## Vitest unit tests — client
+
+File: `tests/unit/specs/*.spec.js`
+
+Config: `vitest.config.mjs` (root) — `include: ['tests/unit/**/*.spec.{js,ts}']`
+
+```js
+import { beforeEach, describe, it, expect, vi } from 'vitest';
+
+describe('module name', () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('does something', () => {
+    expect(result).toBe(expected);
+  });
+});
+```
+
+## Vitest unit tests — Sails
+
+File: `tests/unit/specs/sails/*.spec.js`
+
+Config: `tests/unit/vitest-sails.config.mjs` — sequential, uses Sails setup file.
+
+Run with: `npm run test:unit:sails`
+
+## Agents tests
+
+File: `.agents/tools/__tests__/*.spec.mjs`
+
+Config: `.agents/tools/vitest.config.mjs`
+
+Run with: `npm run test:agents`
+
+These test pure Node.js logic (no Sails, no Vue). Use ESM imports.
+
+## TDD workflow (from CONTRIBUTING.md)
+
+1. Write or update the test first.
+2. Run `npm run start:server` in background.
+3. Run `npm run e2e:client` (or `e2e:gui` for interactive).
+4. Implement until tests pass.
+5. Run `npm run lint` and `npm run test:unit`.
+
+## Full reference
+
+`.agents/docs/testing.md`
diff --git a/.agents/skills/ctl-vue-patterns/SKILL.md b/.agents/skills/ctl-vue-patterns/SKILL.md
new file mode 100644
index 000000000..ff268b88a
--- /dev/null
+++ b/.agents/skills/ctl-vue-patterns/SKILL.md
@@ -0,0 +1,176 @@
+---
+name: ctl-vue-patterns
+description: "Vue 3 / Pinia / Vuetify frontend patterns for Cuttle. Use on 'write a component', 'add a store', 'Pinia defineStore', 'script setup', 'Vuetify component', 'add a route', 'socket event handler', or any frontend/UI question."
+model: inherit
+allowed-tools: Read, Grep, Glob, Bash
+---
+
+# Vue Patterns
+
+Quick reference for Cuttle's frontend. Full details in `.agents/docs/vue-patterns.md`.
+
+## Before writing any frontend code
+
+```bash
+# Find similar components
+find src/components -name "*.vue" | head -20
+find src/routes -name "*.vue" | head -30
+
+# Find similar stores
+grep -r "defineStore" src/stores/ --include="*.js" -l
+
+# Find existing socket event handlers
+grep -r "handleInGameEvents\|on('game'" src/ --include="*.js" -l
+```
+
+## File locations
+
+| Type | Path |
+|------|------|
+| Route entry | `src/routes/<name>/<Name>View.vue` |
+| Page components | `src/routes/<name>/components/` |
+| Shared components | `src/components/` |
+| Stores | `src/stores/` |
+| Router | `src/router.js` |
+
+## Vue SFC template
+
+```vue
+<script setup>
+import { ref, computed } from 'vue';
+import { useGameStore } from '@/stores/game';
+import { useI18n } from 'vue-i18n';
+
+const { t } = useI18n();
+const gameStore = useGameStore();
+
+const localState = ref(null);
+const derivedValue = computed(() => gameStore.someField);
+
+function handleAction() {
+  // ...
+}
+</script>
+
+<template>
+  <v-dialog v-model="isOpen" max-width="500">
+    <v-card>
+      <v-card-title>{{ t('dialog.title') }}</v-card-title>
+      <v-card-text>Content</v-card-text>
+      <v-card-actions>
+        <v-spacer />
+        <v-btn @click="handleAction">{{ t('common.confirm') }}</v-btn>
+      </v-card-actions>
+    </v-card>
+  </v-dialog>
+</template>
+```
+
+Always use `<script setup>`. Never use Options API.
+
+Canonical example: `src/components/BaseDialog.vue`
+
+## Pinia store template
+
+```js
+import { ref, computed } from 'vue';
+import { defineStore } from 'pinia';
+
+export const useExampleStore = defineStore('example', () => {
+  // State — use ref()
+  const items = ref([]);
+  const loading = ref(false);
+
+  // Getters — use computed()
+  const count = computed(() => items.value.length);
+
+  // Actions — plain functions
+  function addItem(item) {
+    items.value.push(item);
+  }
+
+  return { items, loading, count, addItem };
+});
+```
+
+Canonical example: `src/stores/game.js`
+
+### Importing stores
+
+```js
+import { useGameStore } from '@/stores/game';
+import { useAuthStore } from '@/stores/auth';
+const gameStore = useGameStore();
+```
+
+## Import aliases
+
+| Alias | Resolves to |
+|-------|-------------|
+| `@` | `src/` |
+| `_` | project root |
+
+```js
+import { useGameStore } from '@/stores/game';      // @/... → src/...
+import { version } from '_/package.json';           // _/... → root/...
+import MoveType from '../../utils/MoveType.json';   // relative ok too
+```
+
+## Internationalization
+
+All user-visible strings must use `vue-i18n`:
+
+```vue
+<script setup>
+import { useI18n } from 'vue-i18n';
+const { t } = useI18n();
+</script>
+<template>
+  <span>{{ t('game.draw') }}</span>
+  <v-btn>{{ t('common.confirm') }}</v-btn>
+</template>
+```
+
+Do not hardcode English strings in templates.
+
+## Vuetify components
+
+Use Vuetify for all UI elements. Do not write raw HTML buttons/modals/inputs.
+
+Common components: `v-btn`, `v-card`, `v-dialog`, `v-list`, `v-list-item`, `v-icon`, `v-text-field`, `v-select`, `v-snackbar`, `v-tooltip`.
+
+## Router navigation
+
+```js
+import { useRouter, useRoute } from 'vue-router';
+const router = useRouter();
+const route = useRoute();
+
+// Navigate
+router.push({ name: 'game', params: { gameId: id } });
+
+// Read params
+const gameId = route.params.gameId;
+```
+
+Route names are in `src/router.js`.
+
+## Socket connection
+
+```js
+import { io } from '@/plugins/sails.js';
+// io is already configured — call methods directly
+io.socket.on('game', (data) => { /* handle */ });
+io.socket.get('/api/game', (body, res) => { /* handle */ });
+```
+
+In-game events are handled in `src/plugins/sockets/inGameEvents.js`.
+
+## Security rules
+
+- Never use `v-html` with user-supplied content.
+- Never expose server-only data (session secrets, DB credentials) in frontend code.
+
+## Full reference
+
+`.agents/docs/vue-patterns.md`
diff --git a/.agents/tools/__tests__/git-guardrails.spec.mjs b/.agents/tools/__tests__/git-guardrails.spec.mjs
new file mode 100644
index 000000000..246c105de
--- /dev/null
+++ b/.agents/tools/__tests__/git-guardrails.spec.mjs
@@ -0,0 +1,131 @@
+import { describe, it, expect } from 'vitest';
+import { checkDestructive, isCommitOnMain, isPushOnMain, evaluate } from '../git-guardrails.mjs';
+
+describe('git-guardrails', () => {
+  describe('checkDestructive', () => {
+    it('allows a clean commit command', () => {
+      expect(checkDestructive('git commit -m "fix: thing"')).toBeUndefined();
+    });
+
+    it('allows git log', () => {
+      expect(checkDestructive('git log --oneline -10')).toBeUndefined();
+    });
+
+    it('allows git status', () => {
+      expect(checkDestructive('git status --porcelain')).toBeUndefined();
+    });
+
+    it('blocks git reset --hard', () => {
+      expect(checkDestructive('git reset --hard HEAD')).toMatch(/reset --hard/);
+    });
+
+    it('blocks git reset --hard in a chain', () => {
+      expect(checkDestructive('git fetch origin && git reset --hard origin/main')).toMatch(/reset --hard/);
+    });
+
+    it('blocks git clean -f', () => {
+      expect(checkDestructive('git clean -f')).toMatch(/clean/);
+    });
+
+    it('blocks git clean --force', () => {
+      expect(checkDestructive('git clean --force')).toMatch(/clean/);
+    });
+
+    it('allows git clean -n (dry run)', () => {
+      expect(checkDestructive('git clean -n')).toBeUndefined();
+    });
+
+    it('blocks git push --force', () => {
+      expect(checkDestructive('git push --force')).toMatch(/force/);
+    });
+
+    it('blocks git push -f', () => {
+      expect(checkDestructive('git push origin main -f')).toMatch(/force/);
+    });
+
+    it('allows git push --force-with-lease', () => {
+      expect(checkDestructive('git push --force-with-lease')).toBeUndefined();
+    });
+
+    it('blocks direct push to main', () => {
+      expect(checkDestructive('git push origin main')).toMatch(/main/);
+    });
+
+    it('allows push to feature branch', () => {
+      expect(checkDestructive('git push origin feat/my-feature')).toBeUndefined();
+    });
+
+    it('blocks git checkout .', () => {
+      expect(checkDestructive('git checkout .')).toMatch(/checkout/);
+    });
+
+    it('blocks git checkout main', () => {
+      expect(checkDestructive('git checkout main')).toMatch(/main/);
+    });
+
+    it('allows non-git bash commands', () => {
+      expect(checkDestructive('npm run lint')).toBeUndefined();
+      expect(checkDestructive('ls -la')).toBeUndefined();
+      expect(checkDestructive('find . -name "*.js"')).toBeUndefined();
+    });
+  });
+
+  describe('isCommitOnMain', () => {
+    it('returns true for commit on main', () => {
+      expect(isCommitOnMain('git commit -m "fix: thing"', 'main')).toBe(true);
+    });
+
+    it('returns false for commit on feature branch', () => {
+      expect(isCommitOnMain('git commit -m "fix: thing"', 'feat/my-feature')).toBe(false);
+    });
+
+    it('returns false for non-commit command on main', () => {
+      expect(isCommitOnMain('git log --oneline', 'main')).toBe(false);
+    });
+
+    it('returns false for git -C repo commit (submodule-style)', () => {
+      expect(isCommitOnMain('git -C subdir commit -m "msg"', 'main')).toBe(false);
+    });
+  });
+
+  describe('isPushOnMain', () => {
+    it('returns true for push on main', () => {
+      expect(isPushOnMain('git push origin feat/branch', 'main')).toBe(true);
+    });
+
+    it('returns false for push on feature branch', () => {
+      expect(isPushOnMain('git push origin feat/branch', 'feat/branch')).toBe(false);
+    });
+  });
+
+  describe('evaluate', () => {
+    it('allows clean commit on feature branch', () => {
+      expect(evaluate('git commit -m "fix: thing"', 'feat/my-feature')).toBeUndefined();
+    });
+
+    it('blocks commit on main', () => {
+      expect(evaluate('git commit -m "fix: thing"', 'main')).toMatch(/main/);
+    });
+
+    it('blocks push from main', () => {
+      expect(evaluate('git push origin feat/branch', 'main')).toMatch(/main/);
+    });
+
+    it('blocks destructive commands regardless of branch', () => {
+      expect(evaluate('git reset --hard HEAD', 'feat/my-feature')).toMatch(/reset --hard/);
+    });
+
+    it('denies empty/null command', () => {
+      expect(evaluate('', 'feat/my-feature')).toMatch(/unable to parse/i);
+    });
+
+    it('denies whitespace-only command', () => {
+      expect(evaluate('   ', 'feat/my-feature')).toMatch(/unable to parse/i);
+    });
+
+    it('allows non-git commands on main', () => {
+      expect(evaluate('npm run lint', 'main')).toBeUndefined();
+      expect(evaluate('ls -la', 'main')).toBeUndefined();
+    });
+  });
+});
diff --git a/.agents/tools/git-guardrails.mjs b/.agents/tools/git-guardrails.mjs
new file mode 100644
index 000000000..9a5f3c069
--- /dev/null
+++ b/.agents/tools/git-guardrails.mjs
@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+/**
+ * PreToolUse hook: git guardrails.
+ * Blocks destructive git commands and commits/pushes on main.
+ *
+ * Called via .claude/hooks/git-guardrails.sh shim.
+ * Logic is exported so .agents/tools/__tests__/git-guardrails.spec.mjs can test it directly.
+ */
+
+import { execSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+const deny = (reason) =>
+  JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: 'deny',
+      permissionDecisionReason: reason,
+    },
+  });
+
+const CHAIN_SEP = /\s*(?:&&|\|\||;|\|)\s*/;
+
+const unwrapShell = (cmd) => {
+  const m = cmd.match(/^(?:bash|sh|zsh)\s+-c\s+(['"])([\s\S]*)\1\s*$/);
+  return m ? m[2] : cmd;
+};
+
+const segments = (cmd) =>
+  unwrapShell(cmd)
+    .split(CHAIN_SEP)
+    .map((s) => s.trim())
+    .filter(Boolean);
+
+export const RULES = [
+  {
+    test: (seg) => /^git\s+reset(?:\s|$)/.test(seg) && /\s--hard(?:\s|$)/.test(seg),
+    reason: 'git reset --hard discards all uncommitted changes permanently. Use git stash to preserve them.',
+  },
+  {
+    test: (seg) =>
+      /^git\s+clean(?:\s|$)/.test(seg) && (/\s-[a-zA-Z]*f/.test(seg) || /--force/.test(seg)),
+    reason: 'git clean -f permanently deletes untracked files. List them with git clean -n first.',
+  },
+  {
+    test: (seg) =>
+      /^git\s+push(?:\s|$)/.test(seg) &&
+      /(?:\s|^)(-f|--force)(?:\s|$)/.test(seg) &&
+      !/--force-with-lease/.test(seg),
+    reason: 'git push --force overwrites remote history. Use --force-with-lease instead.',
+  },
+  {
+    test: (seg) => /^git\s+push(?:\s|$)/.test(seg) && /(?:[:\s])main(?:\s|$)/.test(seg),
+    reason: 'Direct push to main is blocked. Open a PR instead.',
+  },
+  {
+    test: (seg) => /^git\s+checkout\s+(?:--\s+)?\.(?:\s|$|["'\\])/.test(seg),
+    reason: 'git checkout . discards all unstaged changes. Restore specific files instead.',
+  },
+  {
+    test: (seg) => /^git\s+checkout\s+main(?:\s|$)/.test(seg),
+    reason: 'Use `git fetch origin` and branch off `origin/main` directly. The user updates local main themselves.',
+  },
+];
+
+export const checkDestructive = (command) => {
+  const segs = segments(command);
+  for (const rule of RULES) {
+    if (segs.some(rule.test)) { return rule.reason; }
+  }
+};
+
+const isBareCommit = (seg) =>
+  /^git\s+commit(?:\s|$)/.test(seg) && !/^git\s+-C\s+\S+\s+commit(?:\s|$)/.test(seg);
+
+const isBarePush = (seg) =>
+  /^git\s+push(?:\s|$)/.test(seg) && !/^git\s+-C\s+\S+\s+push(?:\s|$)/.test(seg);
+
+export const isCommitOnMain = (command, branch) =>
+  branch === 'main' && segments(command).some(isBareCommit);
+
+export const isPushOnMain = (command, branch) =>
+  branch === 'main' && segments(command).some(isBarePush);
+
+export function evaluate(command, branch) {
+  if (typeof command !== 'string' || !command.trim()) {
+    return 'Unable to parse command from tool input; denying for safety.';
+  }
+
+  const reason = checkDestructive(command);
+  if (reason) { return reason; }
+
+  if (isCommitOnMain(command, branch)) {
+    return 'Cannot commit directly on main. Create a feature branch first: git switch -c feat/your-branch';
+  }
+
+  if (isPushOnMain(command, branch)) {
+    return 'Direct push from main is blocked. Push from a feature branch and open a PR.';
+  }
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  try {
+    const { tool_input: { command } = {} } = JSON.parse(readFileSync(0, 'utf8'));
+    const segs = segments(command || '');
+    const needsBranch = segs.some(
+      (s) => /^git\s+commit(?:\s|$)/.test(s) || /^git\s+push(?:\s|$)/.test(s),
+    );
+    const branch = needsBranch
+      ? execSync('git branch --show-current', { encoding: 'utf8' }).trim()
+      : null;
+    const reason = evaluate(command, branch);
+    if (reason) {
+      process.stdout.write(deny(reason));
+    }
+  } catch (e) {
+    process.stderr.write(`[git-guardrails] ${e.message}\n`);
+  }
+}
diff --git a/.agents/tools/vitest.config.mjs b/.agents/tools/vitest.config.mjs
new file mode 100644
index 000000000..05c83cc9a
--- /dev/null
+++ b/.agents/tools/vitest.config.mjs
@@ -0,0 +1,9 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    include: [ '.agents/tools/__tests__/**/*.spec.mjs' ],
+    environment: 'node',
+    globals: true,
+  },
+});
diff --git a/.claude/agents b/.claude/agents
new file mode 120000
index 000000000..4c8a5fc93
--- /dev/null
+++ b/.claude/agents
@@ -0,0 +1 @@
+../.agents/agents
\ No newline at end of file
diff --git a/.claude/hooks/git-guardrails.sh b/.claude/hooks/git-guardrails.sh
new file mode 100755
index 000000000..d1f3d5738
--- /dev/null
+++ b/.claude/hooks/git-guardrails.sh
@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+# Thin shim — delegates to .agents/tools/git-guardrails.mjs.
+# Resolves repo root via git so CWD doesn't matter.
+REPO_ROOT="$(git -C "$CLAUDE_PROJECT_DIR" rev-parse --show-toplevel 2>/dev/null || echo "$CLAUDE_PROJECT_DIR")"
+exec node "$REPO_ROOT/.agents/tools/git-guardrails.mjs"
diff --git a/.claude/settings.json b/.claude/settings.json
new file mode 100644
index 000000000..14927866c
--- /dev/null
+++ b/.claude/settings.json
@@ -0,0 +1,76 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(find *)",
+      "Bash(ls *)",
+      "Bash(ls)",
+      "Bash(grep *)",
+      "Bash(cat *)",
+      "Bash(wc *)",
+      "Bash(echo *)",
+      "Bash(node -e *)",
+      "Bash(node --version*)",
+      "Bash(git status*)",
+      "Bash(git log*)",
+      "Bash(git diff*)",
+      "Bash(git show*)",
+      "Bash(git branch*)",
+      "Bash(git rev-parse*)",
+      "Bash(git remote*)",
+      "Bash(git fetch*)",
+      "Bash(git stash list*)",
+      "Bash(git switch *)",
+      "Bash(git checkout -b *)",
+      "Bash(git add *)",
+      "Bash(git commit *)",
+      "Bash(npm run lint)",
+      "Bash(npm run lint:*)",
+      "Bash(npm run test:unit*)",
+      "Bash(npm run test:agents*)",
+      "Bash(npm run build*)",
+      "Bash(npm run start:*)",
+      "Bash(npm run:*)",
+      "Bash(npm view *)",
+      "Bash(npm info *)",
+      "Bash(gh pr list*)",
+      "Bash(gh pr view*)",
+      "Bash(gh pr diff*)",
+      "Bash(gh pr checks*)",
+      "Bash(gh pr create*)",
+      "Bash(gh issue list*)",
+      "Bash(gh issue view*)",
+      "Bash(gh run list*)",
+      "Bash(gh run view*)",
+      "Bash(gh label list*)",
+      "Bash(gh repo view*)",
+      "Bash(gh api *)",
+      "Bash(gh status*)",
+      "WebSearch",
+      "WebFetch(domain:vitejs.dev)",
+      "WebFetch(domain:vite.dev)",
+      "WebFetch(domain:vitest.dev)",
+      "WebFetch(domain:docs.cypress.io)",
+      "WebFetch(domain:devtools.vuejs.org)",
+      "WebFetch(domain:sailsjs.com)",
+      "WebFetch(domain:vuejs.org)",
+      "WebFetch(domain:pinia.vuejs.org)",
+      "WebFetch(domain:github.com)",
+      "WebFetch(domain:nodejs.org)",
+      "WebFetch(domain:developer.mozilla.org)"
+    ],
+    "deny": []
+  },
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/git-guardrails.sh\""
+          }
+        ]
+      }
+    ]
+  }
+}
diff --git a/.claude/skills b/.claude/skills
new file mode 120000
index 000000000..2b7a412b8
--- /dev/null
+++ b/.claude/skills
@@ -0,0 +1 @@
+../.agents/skills
\ No newline at end of file
diff --git a/.codex/config.toml b/.codex/config.toml
new file mode 100644
index 000000000..d29503652
--- /dev/null
+++ b/.codex/config.toml
@@ -0,0 +1,8 @@
+project_doc_fallback_filenames = ["AGENTS.md"]
+project_doc_max_bytes = 65536
+
+[features]
+hooks = false
+
+[shell_environment_policy]
+inherit = "core"
diff --git a/.gemini/agents b/.gemini/agents
new file mode 120000
index 000000000..4c8a5fc93
--- /dev/null
+++ b/.gemini/agents
@@ -0,0 +1 @@
+../.agents/agents
\ No newline at end of file
diff --git a/.gemini/settings.json b/.gemini/settings.json
new file mode 100644
index 000000000..1e10384ff
--- /dev/null
+++ b/.gemini/settings.json
@@ -0,0 +1,26 @@
+{
+  "context": {
+    "fileName": ["AGENTS.md"]
+  },
+  "experimental": {
+    "enableAgents": true
+  },
+  "general": {
+    "plan": {
+      "enabled": true
+    }
+  },
+  "hooks": {
+    "BeforeTool": [
+      {
+        "matcher": "^run_shell_command$",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$GEMINI_PROJECT_DIR/.agents/tools/git-guardrails.mjs\""
+          }
+        ]
+      }
+    ]
+  }
+}
diff --git a/.gemini/skills b/.gemini/skills
new file mode 120000
index 000000000..2b7a412b8
--- /dev/null
+++ b/.gemini/skills
@@ -0,0 +1 @@
+../.agents/skills
\ No newline at end of file
diff --git a/.gitignore b/.gitignore
index 5e3ad3bf1..7d34794da 100644
--- a/.gitignore
+++ b/.gitignore
@@ -150,7 +150,11 @@ storybook-static
 #
 # Files generated by AI assistants
 ################################################
-.claude*
+# Personal/local AI settings (not committed)
+.claude/settings.local.json
 .cursor*
-.gemini*
+# Track .gemini and .codex config but not local overrides
+.gemini/settings.local.json
+.gemini-clipboard/
+.codex/config.local.toml
 
diff --git a/package.json b/package.json
index 746ea2547..cab6ca64f 100644
--- a/package.json
+++ b/package.json
@@ -89,6 +89,7 @@
     "test:unit:client": "NODE_ENV=development vitest run",
     "test:unit:sails": "NODE_ENV=development vitest run --config tests/unit/vitest-sails.config.mjs",
     "test:unit": "npm run test:unit:client && npm run test:unit:sails",
+    "test:agents": "vitest run --config .agents/tools/vitest.config.mjs",
     "version:patch": "npm version patch",
     "version:minor": "npm version minor",
     "version:major": "npm version major",