feat(web): persist game state across page refreshes with resume dialog

- solitaire_wasm: add SolitaireGame::serialize() and from_saved() so JS
  can round-trip the full GameState through localStorage as JSON
- game.js: save {gameState, elapsedSecs, drawThree} to localStorage
  (key: fs_game_save) on every render(); clear the save on win
- game.js: on bootstrap, check for a saved game and show a resume
  dialog if one exists; Resume restores state + timer, New Game discards
  the save and starts fresh with a random seed
- game.html: add #resume-overlay markup (same pattern as win-overlay)
- game.css: add styles for the resume dialog and its secondary button

localStorage failures (private-browsing quota) are silently ignored so
they never block gameplay.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

.claude-flow/.gitignore

@@ -0,0 +1,7 @@
+# Claude Flow runtime files
+data/
+logs/
+sessions/
+neural/
+*.log
+*.tmp

.claude-flow/CAPABILITIES.md

@@ -0,0 +1,403 @@
+# RuFlo V3 - Complete Capabilities Reference
+> Generated: 2026-05-19T00:18:20.864Z
+> Full documentation: https://github.com/ruvnet/claude-flow
+
+## 📋 Table of Contents
+
+1. [Overview](#overview)
+2. [Swarm Orchestration](#swarm-orchestration)
+3. [Available Agents (60+)](#available-agents)
+4. [CLI Commands (26 Commands, 140+ Subcommands)](#cli-commands)
+5. [Hooks System (27 Hooks + 12 Workers)](#hooks-system)
+6. [Memory & Intelligence (RuVector)](#memory--intelligence)
+7. [Hive-Mind Consensus](#hive-mind-consensus)
+8. [Performance Targets](#performance-targets)
+9. [Integration Ecosystem](#integration-ecosystem)
+
+---
+
+## Overview
+
+RuFlo V3 is a domain-driven design architecture for multi-agent AI coordination with:
+
+- **15-Agent Swarm Coordination** with hierarchical and mesh topologies
+- **HNSW Vector Search** - 150x-12,500x faster pattern retrieval
+- **SONA Neural Learning** - Self-optimizing with <0.05ms adaptation
+- **Byzantine Fault Tolerance** - Queen-led consensus mechanisms
+- **MCP Server Integration** - Model Context Protocol support
+
+### Current Configuration
+| Setting | Value |
+|---------|-------|
+| Topology | hierarchical-mesh |
+| Max Agents | 15 |
+| Memory Backend | hybrid |
+| HNSW Indexing | Enabled |
+| Neural Learning | Enabled |
+| LearningBridge | Enabled (SONA + ReasoningBank) |
+| Knowledge Graph | Enabled (PageRank + Communities) |
+| Agent Scopes | Enabled (project/local/user) |
+
+---
+
+## Swarm Orchestration
+
+### Topologies
+| Topology | Description | Best For |
+|----------|-------------|----------|
+| `hierarchical` | Queen controls workers directly | Anti-drift, tight control |
+| `mesh` | Fully connected peer network | Distributed tasks |
+| `hierarchical-mesh` | V3 hybrid (recommended) | 10+ agents |
+| `ring` | Circular communication | Sequential workflows |
+| `star` | Central coordinator | Simple coordination |
+| `adaptive` | Dynamic based on load | Variable workloads |
+
+### Strategies
+- `balanced` - Even distribution across agents
+- `specialized` - Clear roles, no overlap (anti-drift)
+- `adaptive` - Dynamic task routing
+
+### Quick Commands
+```bash
+# Initialize swarm
+npx @claude-flow/cli@latest swarm init --topology hierarchical --max-agents 8 --strategy specialized
+
+# Check status
+npx @claude-flow/cli@latest swarm status
+
+# Monitor activity
+npx @claude-flow/cli@latest swarm monitor
+```
+
+---
+
+## Available Agents
+
+### Core Development (5)
+`coder`, `reviewer`, `tester`, `planner`, `researcher`
+
+### V3 Specialized (4)
+`security-architect`, `security-auditor`, `memory-specialist`, `performance-engineer`
+
+### Swarm Coordination (5)
+`hierarchical-coordinator`, `mesh-coordinator`, `adaptive-coordinator`, `collective-intelligence-coordinator`, `swarm-memory-manager`
+
+### Consensus & Distributed (7)
+`byzantine-coordinator`, `raft-manager`, `gossip-coordinator`, `consensus-builder`, `crdt-synchronizer`, `quorum-manager`, `security-manager`
+
+### Performance & Optimization (5)
+`perf-analyzer`, `performance-benchmarker`, `task-orchestrator`, `memory-coordinator`, `smart-agent`
+
+### GitHub & Repository (9)
+`github-modes`, `pr-manager`, `code-review-swarm`, `issue-tracker`, `release-manager`, `workflow-automation`, `project-board-sync`, `repo-architect`, `multi-repo-swarm`
+
+### SPARC Methodology (6)
+`sparc-coord`, `sparc-coder`, `specification`, `pseudocode`, `architecture`, `refinement`
+
+### Specialized Development (8)
+`backend-dev`, `mobile-dev`, `ml-developer`, `cicd-engineer`, `api-docs`, `system-architect`, `code-analyzer`, `base-template-generator`
+
+### Testing & Validation (2)
+`tdd-london-swarm`, `production-validator`
+
+### Agent Routing by Task
+| Task Type | Recommended Agents | Topology |
+|-----------|-------------------|----------|
+| Bug Fix | researcher, coder, tester | mesh |
+| New Feature | coordinator, architect, coder, tester, reviewer | hierarchical |
+| Refactoring | architect, coder, reviewer | mesh |
+| Performance | researcher, perf-engineer, coder | hierarchical |
+| Security | security-architect, auditor, reviewer | hierarchical |
+| Docs | researcher, api-docs | mesh |
+
+---
+
+## CLI Commands
+
+### Core Commands (12)
+| Command | Subcommands | Description |
+|---------|-------------|-------------|
+| `init` | 4 | Project initialization |
+| `agent` | 8 | Agent lifecycle management |
+| `swarm` | 6 | Multi-agent coordination |
+| `memory` | 11 | AgentDB with HNSW search |
+| `mcp` | 9 | MCP server management |
+| `task` | 6 | Task assignment |
+| `session` | 7 | Session persistence |
+| `config` | 7 | Configuration |
+| `status` | 3 | System monitoring |
+| `workflow` | 6 | Workflow templates |
+| `hooks` | 17 | Self-learning hooks |
+| `hive-mind` | 6 | Consensus coordination |
+
+### Advanced Commands (14)
+| Command | Subcommands | Description |
+|---------|-------------|-------------|
+| `daemon` | 5 | Background workers |
+| `neural` | 5 | Pattern training |
+| `security` | 6 | Security scanning |
+| `performance` | 5 | Profiling & benchmarks |
+| `providers` | 5 | AI provider config |
+| `plugins` | 5 | Plugin management |
+| `deployment` | 5 | Deploy management |
+| `embeddings` | 4 | Vector embeddings |
+| `claims` | 4 | Authorization |
+| `migrate` | 5 | V2→V3 migration |
+| `process` | 4 | Process management |
+| `doctor` | 1 | Health diagnostics |
+| `completions` | 4 | Shell completions |
+
+### Example Commands
+```bash
+# Initialize
+npx @claude-flow/cli@latest init --wizard
+
+# Spawn agent
+npx @claude-flow/cli@latest agent spawn -t coder --name my-coder
+
+# Memory operations
+npx @claude-flow/cli@latest memory store --key "pattern" --value "data" --namespace patterns
+npx @claude-flow/cli@latest memory search --query "authentication"
+
+# Diagnostics
+npx @claude-flow/cli@latest doctor --fix
+```
+
+---
+
+## Hooks System
+
+### 27 Available Hooks
+
+#### Core Hooks (6)
+| Hook | Description |
+|------|-------------|
+| `pre-edit` | Context before file edits |
+| `post-edit` | Record edit outcomes |
+| `pre-command` | Risk assessment |
+| `post-command` | Command metrics |
+| `pre-task` | Task start + agent suggestions |
+| `post-task` | Task completion learning |
+
+#### Session Hooks (4)
+| Hook | Description |
+|------|-------------|
+| `session-start` | Start/restore session |
+| `session-end` | Persist state |
+| `session-restore` | Restore previous |
+| `notify` | Cross-agent notifications |
+
+#### Intelligence Hooks (5)
+| Hook | Description |
+|------|-------------|
+| `route` | Optimal agent routing |
+| `explain` | Routing decisions |
+| `pretrain` | Bootstrap intelligence |
+| `build-agents` | Generate configs |
+| `transfer` | Pattern transfer |
+
+#### Coverage Hooks (3)
+| Hook | Description |
+|------|-------------|
+| `coverage-route` | Coverage-based routing |
+| `coverage-suggest` | Improvement suggestions |
+| `coverage-gaps` | Gap analysis |
+
+### 12 Background Workers
+| Worker | Priority | Purpose |
+|--------|----------|---------|
+| `ultralearn` | normal | Deep knowledge |
+| `optimize` | high | Performance |
+| `consolidate` | low | Memory consolidation |
+| `predict` | normal | Predictive preload |
+| `audit` | critical | Security |
+| `map` | normal | Codebase mapping |
+| `preload` | low | Resource preload |
+| `deepdive` | normal | Deep analysis |
+| `document` | normal | Auto-docs |
+| `refactor` | normal | Suggestions |
+| `benchmark` | normal | Benchmarking |
+| `testgaps` | normal | Coverage gaps |
+
+---
+
+## Memory & Intelligence
+
+### RuVector Intelligence System
+- **SONA**: Self-Optimizing Neural Architecture (<0.05ms)
+- **MoE**: Mixture of Experts routing
+- **HNSW**: 150x-12,500x faster search
+- **EWC++**: Prevents catastrophic forgetting
+- **Flash Attention**: 2.49x-7.47x speedup
+- **Int8 Quantization**: 3.92x memory reduction
+
+### 4-Step Intelligence Pipeline
+1. **RETRIEVE** - HNSW pattern search
+2. **JUDGE** - Success/failure verdicts
+3. **DISTILL** - LoRA learning extraction
+4. **CONSOLIDATE** - EWC++ preservation
+
+### Self-Learning Memory (ADR-049)
+
+| Component | Status | Description |
+|-----------|--------|-------------|
+| **LearningBridge** | ✅ Enabled | Connects insights to SONA/ReasoningBank neural pipeline |
+| **MemoryGraph** | ✅ Enabled | PageRank knowledge graph + community detection |
+| **AgentMemoryScope** | ✅ Enabled | 3-scope agent memory (project/local/user) |
+
+**LearningBridge** - Insights trigger learning trajectories. Confidence evolves: +0.03 on access, -0.005/hour decay. Consolidation runs the JUDGE/DISTILL/CONSOLIDATE pipeline.
+
+**MemoryGraph** - Builds a knowledge graph from entry references. PageRank identifies influential insights. Communities group related knowledge. Graph-aware ranking blends vector + structural scores.
+
+**AgentMemoryScope** - Maps Claude Code 3-scope directories:
+- `project`: `<gitRoot>/.claude/agent-memory/<agent>/`
+- `local`: `<gitRoot>/.claude/agent-memory-local/<agent>/`
+- `user`: `~/.claude/agent-memory/<agent>/`
+
+High-confidence insights (>0.8) can transfer between agents.
+
+### Memory Commands
+```bash
+# Store pattern
+npx @claude-flow/cli@latest memory store --key "name" --value "data" --namespace patterns
+
+# Semantic search
+npx @claude-flow/cli@latest memory search --query "authentication"
+
+# List entries
+npx @claude-flow/cli@latest memory list --namespace patterns
+
+# Initialize database
+npx @claude-flow/cli@latest memory init --force
+```
+
+---
+
+## Hive-Mind Consensus
+
+### Queen Types
+| Type | Role |
+|------|------|
+| Strategic Queen | Long-term planning |
+| Tactical Queen | Execution coordination |
+| Adaptive Queen | Dynamic optimization |
+
+### Worker Types (8)
+`researcher`, `coder`, `analyst`, `tester`, `architect`, `reviewer`, `optimizer`, `documenter`
+
+### Consensus Mechanisms
+| Mechanism | Fault Tolerance | Use Case |
+|-----------|-----------------|----------|
+| `byzantine` | f < n/3 faulty | Adversarial |
+| `raft` | f < n/2 failed | Leader-based |
+| `gossip` | Eventually consistent | Large scale |
+| `crdt` | Conflict-free | Distributed |
+| `quorum` | Configurable | Flexible |
+
+### Hive-Mind Commands
+```bash
+# Initialize
+npx @claude-flow/cli@latest hive-mind init --queen-type strategic
+
+# Status
+npx @claude-flow/cli@latest hive-mind status
+
+# Spawn workers
+npx @claude-flow/cli@latest hive-mind spawn --count 5 --type worker
+
+# Consensus
+npx @claude-flow/cli@latest hive-mind consensus --propose "task"
+```
+
+---
+
+## Performance Targets
+
+| Metric | Target | Status |
+|--------|--------|--------|
+| HNSW Search | 150x-12,500x faster | ✅ Implemented |
+| Memory Reduction | 50-75% | ✅ Implemented (3.92x) |
+| SONA Integration | Pattern learning | ✅ Implemented |
+| Flash Attention | 2.49x-7.47x | 🔄 In Progress |
+| MCP Response | <100ms | ✅ Achieved |
+| CLI Startup | <500ms | ✅ Achieved |
+| SONA Adaptation | <0.05ms | 🔄 In Progress |
+| Graph Build (1k) | <200ms | ✅ 2.78ms (71.9x headroom) |
+| PageRank (1k) | <100ms | ✅ 12.21ms (8.2x headroom) |
+| Insight Recording | <5ms/each | ✅ 0.12ms (41x headroom) |
+| Consolidation | <500ms | ✅ 0.26ms (1,955x headroom) |
+| Knowledge Transfer | <100ms | ✅ 1.25ms (80x headroom) |
+
+---
+
+## Integration Ecosystem
+
+### Integrated Packages
+| Package | Version | Purpose |
+|---------|---------|---------|
+| agentic-flow | 3.0.0-alpha.1 | Core coordination + ReasoningBank + Router |
+| agentdb | 3.0.0-alpha.10 | Vector database + 8 controllers |
+| @ruvector/attention | 0.1.3 | Flash attention |
+| @ruvector/sona | 0.1.5 | Neural learning |
+
+### Optional Integrations
+| Package | Command |
+|---------|---------|
+| ruv-swarm | `npx ruv-swarm mcp start` |
+| flow-nexus | `npx flow-nexus@latest mcp start` |
+| agentic-jujutsu | `npx agentic-jujutsu@latest` |
+
+### MCP Server Setup
+```bash
+# Add Ruflo MCP
+claude mcp add ruflo -- npx -y ruflo@latest
+
+# Optional servers
+claude mcp add ruv-swarm -- npx -y ruv-swarm mcp start
+claude mcp add flow-nexus -- npx -y flow-nexus@latest mcp start
+```
+
+---
+
+## Quick Reference
+
+### Essential Commands
+```bash
+# Setup
+npx ruflo@latest init --wizard
+npx ruflo@latest daemon start
+npx ruflo@latest doctor --fix
+
+# Swarm
+npx ruflo@latest swarm init --topology hierarchical --max-agents 8
+npx ruflo@latest swarm status
+
+# Agents
+npx ruflo@latest agent spawn -t coder
+npx ruflo@latest agent list
+
+# Memory
+npx ruflo@latest memory search --query "patterns"
+
+# Hooks
+npx ruflo@latest hooks pre-task --description "task"
+npx ruflo@latest hooks worker dispatch --trigger optimize
+```
+
+### File Structure
+```
+.claude-flow/
+├── config.yaml      # Runtime configuration
+├── CAPABILITIES.md  # This file
+├── data/            # Memory storage
+├── logs/            # Operation logs
+├── sessions/        # Session state
+├── hooks/           # Custom hooks
+├── agents/          # Agent configs
+└── workflows/       # Workflow templates
+```
+
+---
+
+**Full Documentation**: https://github.com/ruvnet/claude-flow
+**Issues**: https://github.com/ruvnet/claude-flow/issues

.claude-flow/config.yaml

@@ -0,0 +1,43 @@
+# RuFlo V3 Runtime Configuration
+# Generated: 2026-05-19T00:18:20.863Z
+
+version: "3.0.0"
+
+swarm:
+  topology: hierarchical-mesh
+  maxAgents: 15
+  autoScale: true
+  coordinationStrategy: consensus
+
+memory:
+  backend: hybrid
+  enableHNSW: true
+  persistPath: .claude-flow/data
+  cacheSize: 100
+  # ADR-049: Self-Learning Memory
+  learningBridge:
+    enabled: true
+    sonaMode: balanced
+    confidenceDecayRate: 0.005
+    accessBoostAmount: 0.03
+    consolidationThreshold: 10
+  memoryGraph:
+    enabled: true
+    pageRankDamping: 0.85
+    maxNodes: 5000
+    similarityThreshold: 0.8
+  agentScopes:
+    enabled: true
+    defaultScope: project
+
+neural:
+  enabled: true
+  modelPath: .claude-flow/neural
+
+hooks:
+  enabled: true
+  autoExecute: true
+
+mcp:
+  autoStart: false
+  port: 3000

.claude-flow/metrics/learning.json

@@ -0,0 +1,17 @@
+{
+  "initialized": "2026-05-19T00:18:20.864Z",
+  "routing": {
+    "accuracy": 0,
+    "decisions": 0
+  },
+  "patterns": {
+    "shortTerm": 0,
+    "longTerm": 0,
+    "quality": 0
+  },
+  "sessions": {
+    "total": 0,
+    "current": null
+  },
+  "_note": "Intelligence grows as you use Ruflo"
+}

.claude-flow/metrics/swarm-activity.json

@@ -0,0 +1,18 @@
+{
+  "timestamp": "2026-05-19T00:18:20.864Z",
+  "processes": {
+    "agentic_flow": 0,
+    "mcp_server": 0,
+    "estimated_agents": 0
+  },
+  "swarm": {
+    "active": false,
+    "agent_count": 0,
+    "coordination_active": false
+  },
+  "integration": {
+    "agentic_flow_active": false,
+    "mcp_active": false
+  },
+  "_initialized": true
+}

.claude-flow/metrics/v3-progress.json

@@ -0,0 +1,26 @@
+{
+  "version": "3.0.0",
+  "initialized": "2026-05-19T00:18:20.864Z",
+  "domains": {
+    "completed": 0,
+    "total": 5,
+    "status": "INITIALIZING"
+  },
+  "ddd": {
+    "progress": 0,
+    "modules": 0,
+    "totalFiles": 0,
+    "totalLines": 0
+  },
+  "swarm": {
+    "activeAgents": 0,
+    "maxAgents": 15,
+    "topology": "hierarchical-mesh"
+  },
+  "learning": {
+    "status": "READY",
+    "patternsLearned": 0,
+    "sessionsCompleted": 0
+  },
+  "_note": "Metrics will update as you use Ruflo. Run: npx ruflo@latest daemon start"
+}

.claude-flow/security/audit-status.json

@@ -0,0 +1,8 @@
+{
+  "initialized": "2026-05-19T00:18:20.864Z",
+  "status": "PENDING",
+  "cvesFixed": 0,
+  "totalCves": 3,
+  "lastScan": null,
+  "_note": "Run: npx @claude-flow/cli@latest security scan"
+}

.gitea/workflows/android-release.yml

@@ -0,0 +1,120 @@
+name: Android Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: 'Release tag (e.g. v0.36.2)'
+        required: true
+        default: 'v0.36.2'
+
+env:
+  APK_OUT: target/release/apk/ferrous-solitaire.apk
+  GITEA_URL: https://git.aleshym.co
+  REPO: funman300/Ferrous-Solitaire
+
+jobs:
+  build-apk:
+    runs-on: ubuntu-latest
+    container:
+      image: git.aleshym.co/funman300/android-builder:latest
+      credentials:
+        username: ${{ gitea.actor }}
+        password: ${{ secrets.CI_TOKEN }}
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Cache Cargo registry
+        uses: actions/cache@v4
+        with:
+          path: |
+            /usr/local/cargo/registry/index
+            /usr/local/cargo/registry/cache
+            /usr/local/cargo/git/db
+          key: cargo-registry-android-${{ hashFiles('**/Cargo.lock') }}
+          restore-keys: cargo-registry-android-
+
+      - name: Cache sccache
+        uses: actions/cache@v4
+        with:
+          path: /root/.cache/sccache
+          key: sccache-android-aarch64-${{ hashFiles('**/Cargo.lock') }}
+          restore-keys: sccache-android-aarch64-
+
+      - name: Get tag name
+        id: tag
+        run: |
+          if [ -n "${{ github.event.inputs.tag }}" ]; then
+            echo "name=${{ github.event.inputs.tag }}" >> "$GITHUB_OUTPUT"
+          else
+            echo "name=${GITHUB_REF#refs/tags/}" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Decode release keystore
+        run: echo "${{ secrets.RELEASE_KEYSTORE_B64 }}" | base64 -d > release.jks
+
+      - name: Build release APK
+        env:
+          PROFILE: release
+          ABIS: arm64-v8a
+          KEYSTORE: ./release.jks
+          KEYSTORE_PASS: ${{ secrets.RELEASE_KEYSTORE_PASS }}
+          KEY_ALIAS: release
+          KEY_PASS: ${{ secrets.RELEASE_KEYSTORE_PASS }}
+          VERSION_NAME: ${{ steps.tag.outputs.name }}
+          RUSTC_WRAPPER: sccache
+          SCCACHE_DIR: /root/.cache/sccache
+        run: bash scripts/build_android_apk.sh
+
+      - name: sccache stats
+        if: always()
+        run: sccache --show-stats
+
+      - name: Create or get Gitea release
+        id: release
+        run: |
+          TAG="${{ steps.tag.outputs.name }}"
+          BASE="${{ env.GITEA_URL }}/api/v1/repos/${{ env.REPO }}"
+          AUTH="Authorization: token ${{ secrets.CI_TOKEN }}"
+
+          ID=$(curl -sf -H "$AUTH" "$BASE/releases/tags/$TAG" \
+               | python3 -c "import sys,json; print(json.load(sys.stdin).get('id',''))" \
+               2>/dev/null || true)
+
+          if [ -z "$ID" ]; then
+            ID=$(curl -sf -X POST \
+                 -H "$AUTH" -H "Content-Type: application/json" \
+                 "$BASE/releases" \
+                 -d "{
+                   \"tag_name\": \"$TAG\",
+                   \"name\": \"$TAG\",
+                   \"body\": \"## Android release $TAG\n\n**Install / update with Obtainium** — add this source URL:\n\`\`\`\nhttps://git.aleshym.co/funman300/Ferrous-Solitaire\n\`\`\`\n\nOr download \`ferrous-solitaire.apk\` below and sideload it directly.\",
+                   \"draft\": false,
+                   \"prerelease\": false
+                 }" \
+                 | python3 -c "import sys,json; print(json.load(sys.stdin)['id'])")
+          fi
+          echo "id=$ID" >> "$GITHUB_OUTPUT"
+
+      - name: Upload APK to release
+        run: |
+          BASE="${{ env.GITEA_URL }}/api/v1/repos/${{ env.REPO }}"
+          AUTH="Authorization: token ${{ secrets.CI_TOKEN }}"
+          RELEASE_ID="${{ steps.release.outputs.id }}"
+
+          # Remove any existing APK assets so re-runs don't accumulate duplicates.
+          curl -sf -H "$AUTH" "$BASE/releases/$RELEASE_ID/assets" \
+            | python3 -c "import sys,json; [print(a['id']) for a in json.load(sys.stdin) if a['name'].endswith('.apk')]" \
+            | while read AID; do
+                curl -sf -X DELETE -H "$AUTH" "$BASE/releases/$RELEASE_ID/assets/$AID"
+              done
+
+          curl -sf -X POST \
+            -H "$AUTH" \
+            -F "attachment=@${{ env.APK_OUT }};type=application/vnd.android.package-archive" \
+            "$BASE/releases/$RELEASE_ID/assets"

.gitea/workflows/builder-image.yml

@@ -0,0 +1,41 @@
+name: Build Android Builder Image
+
+on:
+  push:
+    branches: [master]
+    paths:
+      - 'docker/android-builder.Dockerfile'
+      - '.gitea/workflows/builder-image.yml'
+
+env:
+  IMAGE: git.aleshym.co/funman300/android-builder
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Log in to Gitea registry
+        uses: docker/login-action@v3
+        with:
+          registry: git.aleshym.co
+          username: ${{ gitea.actor }}
+          password: ${{ secrets.CI_TOKEN }}
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+        with:
+          driver-opts: network=host
+
+      - name: Build and push
+        uses: docker/build-push-action@v5
+        with:
+          context: .
+          file: docker/android-builder.Dockerfile
+          push: true
+          tags: ${{ env.IMAGE }}:latest
+          cache-from: type=registry,ref=${{ env.IMAGE }}:buildcache
+          cache-to: type=registry,ref=${{ env.IMAGE }}:buildcache,mode=max

.gitea/workflows/docker-build.yml

@@ -0,0 +1,78 @@
+name: Build and Deploy
+
+on:
+  push:
+    branches: [master]
+    paths:
+      - 'solitaire_server/**'
+      - 'solitaire_sync/**'
+      - 'solitaire_core/**'
+      - 'Cargo.toml'
+      - 'Cargo.lock'
+      - '.gitea/workflows/docker-build.yml'
+
+env:
+  REGISTRY: git.aleshym.co
+  IMAGE: git.aleshym.co/funman300/solitaire-server
+
+jobs:
+  build-and-push:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          # Need full history so we can push the tag-update commit back.
+          fetch-depth: 0
+          token: ${{ secrets.CI_TOKEN }}
+
+      - name: Set image tag
+        id: meta
+        run: echo "sha=${GITHUB_SHA::8}" >> "$GITHUB_OUTPUT"
+
+      - name: Log in to Gitea registry
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ gitea.actor }}
+          password: ${{ secrets.CI_TOKEN }}
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+        with:
+          driver-opts: network=host
+
+      - name: Build and push
+        uses: docker/build-push-action@v5
+        with:
+          context: .
+          file: solitaire_server/Dockerfile
+          push: true
+          tags: |
+            ${{ env.IMAGE }}:${{ steps.meta.outputs.sha }}
+            ${{ env.IMAGE }}:latest
+          cache-from: type=registry,ref=${{ env.IMAGE }}:buildcache
+          cache-to: type=registry,ref=${{ env.IMAGE }}:buildcache,mode=max
+
+      - name: Install kustomize
+        run: |
+          curl -sL https://github.com/kubernetes-sigs/kustomize/releases/download/kustomize%2Fv5.4.3/kustomize_v5.4.3_linux_amd64.tar.gz | tar xz
+          sudo mv kustomize /usr/local/bin/kustomize
+
+      - name: Pin image tag in deploy manifests
+        run: |
+          cd deploy
+          kustomize edit set image solitaire-server=${{ env.IMAGE }}:${{ steps.meta.outputs.sha }}
+
+      - name: Commit and push updated kustomization
+        run: |
+          git config user.email "ci@gitea.local"
+          git config user.name "Gitea CI"
+          git add deploy/kustomization.yaml
+          git diff --cached --quiet && exit 0  # nothing to commit — skip push
+          git commit -m "chore(deploy): bump image to ${{ steps.meta.outputs.sha }} [skip ci]"
+          for i in 1 2 3; do
+            git pull --rebase origin master && git push && break
+            sleep 5
+          done

.github/workflows/ci.yml

@@ -1,88 +0,0 @@
-name: CI
-
-on:
-  push:
-    branches: [master]
-  pull_request:
-    branches: [master]
-
-env:
-  CARGO_TERM_COLOR: always
-  RUSTFLAGS: "-D warnings"
-
-jobs:
-  test:
-    name: Test & Lint
-    runs-on: ubuntu-latest
-
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Install Rust stable
-        uses: dtolnay/rust-toolchain@stable
-        with:
-          components: clippy
-
-      - name: Install Linux audio/display dependencies
-        run: |
-          sudo apt-get update -qq
-          sudo apt-get install -y --no-install-recommends \
-            libasound2-dev \
-            libudev-dev \
-            libwayland-dev \
-            libxkbcommon-dev
-
-      - name: Cache cargo registry and build artifacts
-        uses: actions/cache@v4
-        with:
-          path: |
-            ~/.cargo/registry
-            ~/.cargo/git
-            target
-          key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }}
-          restore-keys: |
-            ${{ runner.os }}-cargo-
-
-      - name: Clippy (all crates, zero warnings)
-        run: cargo clippy --workspace -- -D warnings
-
-      - name: Test (headless crates only — no display required)
-        run: |
-          cargo test -p solitaire_core
-          cargo test -p solitaire_sync
-          cargo test -p solitaire_data
-          cargo test -p solitaire_server
-
-  build:
-    name: Release Build
-    runs-on: ubuntu-latest
-    needs: test
-
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Install Rust stable
-        uses: dtolnay/rust-toolchain@stable
-
-      - name: Install Linux audio/display dependencies
-        run: |
-          sudo apt-get update -qq
-          sudo apt-get install -y --no-install-recommends \
-            libasound2-dev \
-            libudev-dev \
-            libwayland-dev \
-            libxkbcommon-dev
-
-      - name: Cache cargo registry and build artifacts
-        uses: actions/cache@v4
-        with:
-          path: |
-            ~/.cargo/registry
-            ~/.cargo/git
-            target
-          key: ${{ runner.os }}-cargo-release-${{ hashFiles('**/Cargo.lock') }}
-          restore-keys: |
-            ${{ runner.os }}-cargo-release-
-
-      - name: Build release binaries
-        run: cargo build --workspace --release

.gitignore

@@ -7,3 +7,21 @@
 *.tmp
 data/
 .claude/
+
+# ruflo runtime state
+agentdb.rvf
+agentdb.rvf.lock
+
+# IDE project files
+.idea/
+
+# Android signing keystores — never commit
+*.jks
+*.jks.bak
+*.jks.bak*
+*.keystore
+
+# Kubernetes secrets — apply manually, never commit
+deploy/matomo-secret.yaml
+deploy/*-secret.yaml
+deploy/*-auth-secret.yaml

.mcp.json

@@ -0,0 +1,22 @@
+{
+  "mcpServers": {
+    "ruflo": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "ruflo@latest",
+        "mcp",
+        "start"
+      ],
+      "env": {
+        "npm_config_update_notifier": "false",
+        "CLAUDE_FLOW_MODE": "v3",
+        "CLAUDE_FLOW_HOOKS_ENABLED": "true",
+        "CLAUDE_FLOW_TOPOLOGY": "hierarchical-mesh",
+        "CLAUDE_FLOW_MAX_AGENTS": "15",
+        "CLAUDE_FLOW_MEMORY_BACKEND": "hybrid"
+      },
+      "autoStart": false
+    }
+  }
+}

.sqlx/query-06c945e50567c6801f1346d436cdc86a82a4e13dd45d8286295ba37cdbdc045e.json

@@ -0,0 +1,20 @@
+{
+  "db_name": "SQLite",
+  "query": "SELECT username FROM users WHERE id = ?",
+  "describe": {
+    "columns": [
+      {
+        "name": "username",
+        "ordinal": 0,
+        "type_info": "Text"
+      }
+    ],
+    "parameters": {
+      "Right": 1
+    },
+    "nullable": [
+      false
+    ]
+  },
+  "hash": "06c945e50567c6801f1346d436cdc86a82a4e13dd45d8286295ba37cdbdc045e"
+}

.sqlx/query-0e199cafab7e71b0c7f28ede85a622e38649d2fe5a73a5c715f2319f5450f729.json

@@ -0,0 +1,12 @@
+{
+  "db_name": "SQLite",
+  "query": "UPDATE leaderboard\n               SET best_score      = ?,\n                   best_time_secs  = ?,\n                   recorded_at     = ?\n               WHERE user_id = ?\n                 AND (\n                     best_score IS NULL\n                     OR ? > best_score\n                     OR (? = best_score AND (best_time_secs IS NULL OR ? < best_time_secs))\n                 )",
+  "describe": {
+    "columns": [],
+    "parameters": {
+      "Right": 7
+    },
+    "nullable": []
+  },
+  "hash": "0e199cafab7e71b0c7f28ede85a622e38649d2fe5a73a5c715f2319f5450f729"
+}

.sqlx/query-15d08e02b102147bc74848ec3692b99edbf4c33078191f0132991ee94d4507b1.json

@@ -0,0 +1,12 @@
+{
+  "db_name": "SQLite",
+  "query": "UPDATE users SET avatar_url = ? WHERE id = ?",
+  "describe": {
+    "columns": [],
+    "parameters": {
+      "Right": 2
+    },
+    "nullable": []
+  },
+  "hash": "15d08e02b102147bc74848ec3692b99edbf4c33078191f0132991ee94d4507b1"
+}

.sqlx/query-168e205e3eb832b78d085b48281a1bae74d5a0e64c4c793c18a6400605bacf76.json

@@ -0,0 +1,12 @@
+{
+  "db_name": "SQLite",
+  "query": "DELETE FROM refresh_tokens WHERE jti = ?",
+  "describe": {
+    "columns": [],
+    "parameters": {
+      "Right": 1
+    },
+    "nullable": []
+  },
+  "hash": "168e205e3eb832b78d085b48281a1bae74d5a0e64c4c793c18a6400605bacf76"
+}

.sqlx/query-2b814989a6632ca930ae1e895f97a7fc3389c91d1d2abf6900a21fb0d6e94ef3.json

@@ -1,6 +1,6 @@
 {
   "db_name": "SQLite",
-  "query": "SELECT l.display_name, l.best_score, l.best_time_secs, l.recorded_at\n           FROM leaderboard l\n           JOIN users u ON u.id = l.user_id\n           WHERE u.leaderboard_opt_in = 1\n           ORDER BY\n               CASE WHEN l.best_score IS NULL THEN 1 ELSE 0 END ASC,\n               l.best_score DESC,\n               CASE WHEN l.best_time_secs IS NULL THEN 1 ELSE 0 END ASC,\n               l.best_time_secs ASC",
+  "query": "SELECT l.display_name, l.best_score, l.best_time_secs, l.recorded_at\n           FROM leaderboard l\n           JOIN users u ON u.id = l.user_id\n           WHERE u.leaderboard_opt_in = 1\n           ORDER BY\n               CASE WHEN l.best_score IS NULL THEN 1 ELSE 0 END ASC,\n               l.best_score DESC,\n               CASE WHEN l.best_time_secs IS NULL THEN 1 ELSE 0 END ASC,\n               l.best_time_secs ASC\n           LIMIT 100",
   "describe": {
     "columns": [
       {
@@ -34,5 +34,5 @@
       false
     ]
   },
-  "hash": "57c93a6acd7eea44d00412e62f0d3fed7ffbe4cd759353d29f38a8eb37f69112"
+  "hash": "2b814989a6632ca930ae1e895f97a7fc3389c91d1d2abf6900a21fb0d6e94ef3"
 }

.sqlx/query-40db0910531d4418d4d58d31f0f8ea3894248406cc016020a6e211ed66da91c0.json

@@ -0,0 +1,12 @@
+{
+  "db_name": "SQLite",
+  "query": "DELETE FROM refresh_tokens WHERE user_id = ?",
+  "describe": {
+    "columns": [],
+    "parameters": {
+      "Right": 1
+    },
+    "nullable": []
+  },
+  "hash": "40db0910531d4418d4d58d31f0f8ea3894248406cc016020a6e211ed66da91c0"
+}

.sqlx/query-893c45c27854ba15ea611e8254ef980ced21dc64e6ca95fde56af513f86ffa46.json

@@ -0,0 +1,20 @@
+{
+  "db_name": "SQLite",
+  "query": "SELECT jti FROM refresh_tokens WHERE jti = ?",
+  "describe": {
+    "columns": [
+      {
+        "name": "jti",
+        "ordinal": 0,
+        "type_info": "Text"
+      }
+    ],
+    "parameters": {
+      "Right": 1
+    },
+    "nullable": [
+      true
+    ]
+  },
+  "hash": "893c45c27854ba15ea611e8254ef980ced21dc64e6ca95fde56af513f86ffa46"
+}

.sqlx/query-c9ee5c64ca547f0c730379919a642bd649cbf81fc1804159101a70efabf08b33.json

@@ -0,0 +1,12 @@
+{
+  "db_name": "SQLite",
+  "query": "INSERT INTO refresh_tokens (jti, user_id, expires_at) VALUES (?, ?, ?)",
+  "describe": {
+    "columns": [],
+    "parameters": {
+      "Right": 3
+    },
+    "nullable": []
+  },
+  "hash": "c9ee5c64ca547f0c730379919a642bd649cbf81fc1804159101a70efabf08b33"
+}

.sqlx/query-e4eb622073cbdf868ec1568a6bdb132e962480b0530d542102c05aa9e901463b.json

@@ -0,0 +1,12 @@
+{
+  "db_name": "SQLite",
+  "query": "UPDATE users SET password_hash = ? WHERE id = ?",
+  "describe": {
+    "columns": [],
+    "parameters": {
+      "Right": 2
+    },
+    "nullable": []
+  },
+  "hash": "e4eb622073cbdf868ec1568a6bdb132e962480b0530d542102c05aa9e901463b"
+}

.sqlx/query-ef7af925a8715c329dcafca5257c691e6bca31755eb5f54be47114f21fc04c8c.json

@@ -0,0 +1,12 @@
+{
+  "db_name": "SQLite",
+  "query": "DELETE FROM refresh_tokens WHERE expires_at < ?",
+  "describe": {
+    "columns": [],
+    "parameters": {
+      "Right": 1
+    },
+    "nullable": []
+  },
+  "hash": "ef7af925a8715c329dcafca5257c691e6bca31755eb5f54be47114f21fc04c8c"
+}

.sqlx/query-fae33e7159b43c756131b1545360dcb0250988b43550881e3f0a336d9516dd45.json

@@ -0,0 +1,26 @@
+{
+  "db_name": "SQLite",
+  "query": "SELECT username, avatar_url FROM users WHERE id = ?",
+  "describe": {
+    "columns": [
+      {
+        "name": "username",
+        "ordinal": 0,
+        "type_info": "Text"
+      },
+      {
+        "name": "avatar_url",
+        "ordinal": 1,
+        "type_info": "Text"
+      }
+    ],
+    "parameters": {
+      "Right": 1
+    },
+    "nullable": [
+      false,
+      true
+    ]
+  },
+  "hash": "fae33e7159b43c756131b1545360dcb0250988b43550881e3f0a336d9516dd45"
+}

ARCHITECTURE.md

@@ -1,9 +1,9 @@
-# Solitaire Quest — Architecture Document
+# Ferrous Solitaire — Architecture Document
 
-> **Version:** 1.1  
+> **Version:** 1.3  
 > **Language:** Rust (Edition 2024)  
 > **Engine:** Bevy (latest stable)  
-> **Last Updated:** 2026-04-29
+> **Last Updated:** 2026-05-12
 
 ---
 
@@ -34,7 +34,7 @@
 
 ## 1. Project Overview
 
-Solitaire Quest is a cross-platform Klondike Solitaire game written in Rust, targeting macOS, Windows, and Linux desktops. It features a full progression system with XP, levels, achievements, daily challenges, and an optional self-hosted sync server so statistics and progress are available across all of a player's devices.
+Ferrous Solitaire is a cross-platform Klondike Solitaire game written in Rust, targeting macOS, Windows, and Linux desktops. It features a full progression system with XP, levels, achievements, daily challenges, and an optional self-hosted sync server so statistics and progress are available across all of a player's devices.
 
 ### Sync Backend by Platform
 
@@ -43,6 +43,7 @@ Solitaire Quest is a cross-platform Klondike Solitaire game written in Rust, tar
 | macOS | Self-hosted server | Full feature set |
 | Windows | Self-hosted server | Full feature set |
 | Linux | Self-hosted server | Full feature set |
+| Android | Self-hosted server | Touch input; safe-area insets via JNI; `cargo-apk` build |
 
 ### Design Principles
 
@@ -57,7 +58,7 @@ Pure-core, no-panics-in-game-logic, and UI-first-interaction constraints are enf
 ## 2. Workspace Structure
 
 ```
-solitaire_quest/
+ferrous_solitaire/
 │
 ├── Cargo.toml                  # Workspace manifest
 ├── .env.example                # Server environment variable template
@@ -86,6 +87,7 @@ solitaire_quest/
 ├── solitaire_data/             # Persistence, sync client, settings
 ├── solitaire_engine/           # Bevy ECS systems, components, plugins
 ├── solitaire_server/           # Self-hosted sync server (Axum + SQLite)
+├── solitaire_wasm/             # WebAssembly bindings — browser-side replay player
 └── solitaire_app/              # Main binary entry point
 ```
 
@@ -160,6 +162,20 @@ Owns:
 - Daily challenge seed generation
 - Leaderboard management
 
+### `solitaire_wasm`
+**Dependencies:** `solitaire_core`, `serde`, `serde_json`, `chrono`, `wasm-bindgen`, `serde-wasm-bindgen`.
+
+WebAssembly bindings for browser-side replay playback. Compiled to `cdylib` via `wasm-pack build`; the output lives in `solitaire_server/web/pkg/` and is served statically by the server.
+
+Intentionally **does not** depend on `solitaire_data` (which pulls in `dirs`, `keyring`, `reqwest`, and other non-WASM crates). Instead it defines a minimal `Replay` mirror with the same serde shape as `solitaire_data::Replay` — the JSON wire format is the compatibility contract.
+
+Owns:
+- `ReplayPlayer` — WASM-exported state machine; steps through a replay's `Vec<ReplayMove>` against a live `GameState`
+- `StateSnapshot` — JS-facing pile snapshot returned by each `step()` call
+- `ReplayMove` / `Replay` mirrors — same serde shape as `solitaire_data` v2 equivalents
+
+Because `ReplayPlayer` uses the same `solitaire_core::GameState` as the desktop client, the two implementations cannot drift: the same seed + move list produces identical pile state at every step on both platforms.
+
 ### `solitaire_app`
 **Dependencies:** `bevy`, `solitaire_engine`.
 
@@ -261,6 +277,8 @@ The "Shortcut" column lists optional keyboard accelerators. Every action in this
 | `HomePlugin` | M | Main-menu overlay with keyboard shortcut reference |
 | `ProfilePlugin` | P | Player profile overlay: level, XP, achievements, sync status |
 | `SettingsPlugin` | O | Settings panel: audio, draw mode, theme, sync, cosmetics |
+| `ThemePlugin` | — | Owns `ActiveTheme` resource; registers the `CardTheme` SVG asset loader; rasterises themes once per (theme, target size) at load time and caches the resulting `Image`; handles the embedded default theme and user themes from `user_theme_dir()` |
+| `SyncSetupPlugin` | — | Sync setup modal (URL / username / password fields, "Log In" / "Register" buttons); account deletion confirm modal; re-auth trigger when `SyncError::Auth` is returned by a pull |
 | `LeaderboardPlugin` | L | Leaderboard overlay |
 | `HelpPlugin` | H | Help / controls overlay |
 | `PausePlugin` | Esc | Pause and resume |
@@ -305,6 +323,12 @@ struct FontResource(Handle<Font>);
 struct BackgroundImageSet {
     handles: Vec<Handle<Image>>,    // indices 0–4 match selected_background setting
 }
+
+// OS-reserved edge insets (physical px); zero on desktop
+struct SafeAreaInsets { top: f32, bottom: f32, left: f32, right: f32 }
+
+// Whether the HUD band is visible (auto-hide chrome feature)
+enum HudVisibility { Visible, Hidden }
 ```
 
 ### Key Bevy Events
@@ -342,12 +366,12 @@ Minimum window: 800×600. At this size cards are small but usable.
 
 ### Local Storage
 
-All files stored under `dirs::data_dir() / "solitaire_quest"/`:
+All files stored under `dirs::data_dir() / "ferrous_solitaire"/`:
 
 ```
-~/.local/share/solitaire_quest/   (Linux)
+~/.local/share/ferrous_solitaire/   (Linux)
-~/Library/Application Support/solitaire_quest/   (macOS)
+~/Library/Application Support/ferrous_solitaire/   (macOS)
-%APPDATA%\solitaire_quest\   (Windows)
+%APPDATA%\ferrous_solitaire\   (Windows)
 │
 ├── stats.json          # StatsSnapshot
 ├── progress.json       # PlayerProgress (XP, level, unlocks, daily challenge)
@@ -365,10 +389,22 @@ All sync backends implement a single trait in `solitaire_data`. The `SyncPlugin`
 ```rust
 #[async_trait]
 pub trait SyncProvider: Send + Sync {
+    // Required — must be implemented by every backend:
     async fn pull(&self) -> Result<SyncPayload, SyncError>;
     async fn push(&self, payload: &SyncPayload) -> Result<SyncResponse, SyncError>;
     fn backend_name(&self) -> &'static str;
     fn is_authenticated(&self) -> bool;
+
+    // Optional — all have default no-op / empty implementations:
+    async fn mirror_achievement(&self, _id: &str) -> Result<(), SyncError>;
+    async fn fetch_leaderboard(&self) -> Result<Vec<LeaderboardEntry>, SyncError>;
+    async fn fetch_daily_challenge(&self) -> Result<Option<ChallengeGoal>, SyncError>;
+    async fn opt_in_leaderboard(&self, _display_name: &str) -> Result<(), SyncError>;
+    async fn opt_out_leaderboard(&self) -> Result<(), SyncError>;
+    async fn delete_account(&self) -> Result<(), SyncError>;
+    // Returns the shareable web URL on success; defaults to Err(UnsupportedPlatform)
+    // so LocalOnlyProvider silently no-ops the push-on-win path.
+    async fn push_replay(&self, _replay: &Replay) -> Result<String, SyncError>;
 }
 ```
 
@@ -390,7 +426,7 @@ pub enum SyncBackend {
         url: String,
         username: String,
         // JWT access + refresh tokens stored in OS keychain
-        // key: "solitaire_quest_server_{username}"
+        // key: "ferrous_solitaire_server_{username}"
     },
 }
 ```
@@ -454,6 +490,24 @@ CREATE TABLE leaderboard (
     recorded_at     TEXT NOT NULL,
     PRIMARY KEY (user_id)
 );
+
+-- migrations/002_replays.sql
+
+CREATE TABLE IF NOT EXISTS replays (
+    id              TEXT PRIMARY KEY,                      -- UUID v4 minted server-side
+    user_id         TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+    seed            INTEGER NOT NULL,
+    draw_mode       TEXT NOT NULL,                          -- "DrawOne" | "DrawThree"
+    mode            TEXT NOT NULL,                          -- "Classic" | "Zen" | "Challenge" | "TimeAttack"
+    time_seconds    INTEGER NOT NULL,
+    final_score     INTEGER NOT NULL,
+    recorded_at     TEXT NOT NULL,                          -- replay-side date (YYYY-MM-DD)
+    received_at     TEXT NOT NULL,                          -- server insert timestamp (ISO 8601)
+    replay_json     TEXT NOT NULL                           -- full Replay serialisation
+);
+
+CREATE INDEX IF NOT EXISTS replays_received_at_idx ON replays(received_at DESC);
+CREATE INDEX IF NOT EXISTS replays_user_id_idx     ON replays(user_id);
 ```
 
 ### Request Lifecycle
@@ -579,12 +633,25 @@ pub struct AchievementRecord {
 
 pub struct Settings {
     pub draw_mode: DrawMode,
-    pub sfx_volume: f32,           // 0.0–1.0
+    pub sfx_volume: f32,                       // 0.0–1.0
     pub music_volume: f32,
     pub animation_speed: AnimSpeed,
     pub theme: Theme,
-    pub sync_backend: SyncBackend, // Local | SolitaireServer
+    pub sync_backend: SyncBackend,             // Local | SolitaireServer
+    pub selected_card_back: usize,             // index into PlayerProgress::unlocked_card_backs
+    pub selected_background: usize,            // index into PlayerProgress::unlocked_backgrounds
     pub first_run_complete: bool,
+    pub color_blind_mode: bool,                // blue tint on red suits
+    pub high_contrast_mode: bool,              // boosted luminance for low-vision users
+    pub reduce_motion_mode: bool,              // WCAG reduce-motion — snaps instead of slides
+    pub window_geometry: Option<WindowGeometry>, // persisted size + position; None on first run
+}
+
+pub struct WindowGeometry {
+    pub width:  u32,   // logical pixels
+    pub height: u32,
+    pub x:      i32,   // physical pixels, top-left corner
+    pub y:      i32,
 }
 ```
 
@@ -600,7 +667,7 @@ All endpoints are under the base URL configured by the user (e.g., `https://soli
 |---|---|---|---|---|
 | POST | `/api/auth/register` | None | `{username, password}` | `{access_token, refresh_token}` |
 | POST | `/api/auth/login` | None | `{username, password}` | `{access_token, refresh_token}` |
-| POST | `/api/auth/refresh` | None | `{refresh_token}` | `{access_token}` |
+| POST | `/api/auth/refresh` | None | `{refresh_token}` | `{access_token, refresh_token}` (rotated) |
 
 ### Sync
 
@@ -617,6 +684,21 @@ All endpoints are under the base URL configured by the user (e.g., `https://soli
 | GET | `/api/leaderboard` | Bearer JWT | — | `Vec<LeaderboardEntry>` |
 | POST | `/api/leaderboard/opt-in` | Bearer JWT | — | `{ok: true}` |
 
+### Replays
+
+| Method | Path | Auth | Body | Response |
+|---|---|---|---|---|
+| POST | `/api/replays` | Bearer JWT | Replay JSON | `{id, share_url}` |
+| GET | `/api/replays/recent` | None | — (`?limit=N`) | `Vec<ReplaySummary>` |
+| GET | `/api/replays/:id` | None | — | Full Replay JSON |
+
+### Web Replay Player
+
+| Method | Path | Auth | Notes |
+|---|---|---|---|
+| GET | `/replays/:id` | None | Serves `web/index.html`; JS fetches `/api/replays/:id` and steps through via the `solitaire_wasm` WASM module |
+| GET | `/web/*` | None | Static assets served via `ServeDir` from `solitaire_server/web/` (includes `web/pkg/` with wasm-bindgen output) |
+
 ### Account Management
 
 | Method | Path | Auth | Body | Response |
@@ -825,7 +907,7 @@ All sound effect WAV files are embedded at compile time via `include_bytes!()` i
 | macOS | Primary | Self-hosted server | x86_64 + Apple Silicon (universal binary via `cargo-lipo`) |
 | Windows | Primary | Self-hosted server | x86_64, MSVC toolchain |
 | Linux | Primary | Self-hosted server | x86_64, tested on Ubuntu 22.04+ and Fedora 39+ |
-| Android | Stretch | Self-hosted server | `cargo-mobile2`, touch input |
+| Android | Active | Self-hosted server | `cargo-apk`; touch + long-press + double-tap; safe-area JNI; portrait layout |
 | iOS | Stretch | Self-hosted server | `cargo-mobile2`, touch input |
 
 Minimum Bevy window size enforced: 800×600. Desktop windows are freely resizable; layout recomputes on `WindowResized`.
@@ -898,8 +980,8 @@ Add `--features bevy/dynamic_linking` during development to dramatically reduce
 ### Docker Compose (Recommended)
 
 ```bash
-git clone https://github.com/yourname/solitaire_quest
+git clone https://github.com/yourname/ferrous_solitaire
-cd solitaire_quest
+cd ferrous_solitaire
 cp .env.example .env
 # Edit .env — set JWT_SECRET and SERVER_PORT
 docker compose up -d
@@ -945,6 +1027,7 @@ Migrations run automatically on startup via `sqlx::migrate!()`.
 | Password storage | bcrypt, cost factor 12 — never stored in plaintext |
 | Token security | JWTs signed with HS256, stored in OS keychain via `keyring` crate |
 | Token expiry | Access: 24h, Refresh: 30d |
+| Refresh token rotation | Each `/api/auth/refresh` call consumes the incoming refresh token (deletes its jti row) and issues a new one. Reuse of a consumed token returns 401. Expired rows are pruned inline. |
 | Brute force | `tower-governor`: 10 req/min per IP on `/api/auth/*` |
 | Payload abuse | 1MB max request body, enforced by Axum middleware |
 | Data deletion | `DELETE /api/account` removes all rows via `ON DELETE CASCADE` |

CLAUDE.md

@@ -1,6 +1,6 @@
 # CLAUDE.md
 
-version: unified-3.0
+version: unified-4.0
 
 ---
 
@@ -29,8 +29,9 @@ solitaire_sync/    # Shared API + merge logic
 solitaire_data/    # Persistence + sync client
 solitaire_engine/  # Bevy ECS + UI + gameplay orchestration
 solitaire_server/  # Axum backend (optional sync layer)
+solitaire_wasm/    # WASM bindings for browser-side replay player
 solitaire_app/     # Entry binary
-assets/            # Runtime assets (except audio)
+assets/            # Runtime assets (except audio + default theme)
 ```
 
 ---
@@ -72,12 +73,16 @@ These override all other instructions.
 
 * NO `unwrap()`
 * NO `panic!()` in runtime/game logic
-* All state transitions:
+* Core game state mutations MUST return:
 
 ```rust id="err_model"
 Result<T, MoveError>
 ```
 
+* Engine / UI state changes follow ECS patterns (Resources, Events) —
+  they do not return `MoveError`
+* Use `thiserror`-derived types for any new error enums outside `solitaire_core`
+
 ---
 
 ## 2.4 Threading Rules
@@ -126,10 +131,15 @@ trait SyncProvider
 ## 3.1 ECS Design
 
 * systems = single responsibility
-* communication = Events only
+* cross-system communication = Events (fire-and-forget triggers)
-* shared state = Resources only
+* persistent shared state = Resources (polled every frame or on change)
 * per-entity state = Components only
 
+Events and Resources are both valid communication paths — use Events when
+the receiver needs to react once; use Resources when the receiver polls
+or when multiple systems read the same value (e.g. `SafeAreaInsets`,
+`HudVisibility`, `LayoutResource`).
+
 ---
 
 ## 3.2 Game State Authority
@@ -149,11 +159,22 @@ Every player action MUST:
 Keyboard shortcuts are:
 → optional accelerators only
 
+**Exception — UI chrome gestures:**
+Tap-to-toggle visibility of UI chrome (e.g. auto-hiding HUD band) is
+permitted without a visible button. The gesture MUST:
+* affect only chrome visibility, never game state
+* restore chrome automatically when any modal opens
+* be purely additive (game remains fully playable with chrome always visible)
+
 ---
 
 ## 3.4 Layout System
 
 * recompute on `WindowResized`
+* recompute on `SafeAreaInsets` changed
+* recompute on `HudVisibility` changed
+* `compute_layout` MUST accept `hud_visible: bool`; pass `HUD_BAND_HEIGHT`
+  when `true`, `0.0` when `false`
 * no fixed resolution assumptions
 
 ---
@@ -178,11 +199,18 @@ Includes:
 
 ## 4.2 Embedded Assets
 
-Only audio:
+Embed via `include_bytes!()` only when ALL of the following are true:
 
-```text id="audio_rule"
+* the asset is small (< 500 KB uncompressed)
-include_bytes!()
+* it changes rarely (not user-customisable)
-```
+* a missing file would be a hard crash, not a graceful degradation
+
+Currently embedded:
+* **Audio** — all `.wav` files in `audio_plugin.rs`
+* **Default card theme** — shipped via `embedded://` scheme in `ThemePlugin`
+
+Do NOT embed card face PNGs, background images, or user fonts —
+these are loaded via `AssetServer` so art can be swapped without recompile.
 
 ---
 
@@ -210,7 +238,9 @@ Must degrade gracefully under `MinimalPlugins`.
 ## 5.2 Public API Rules
 
 * prefer `Into<T>` over concrete types
-* all public items require doc comments
+* publicly exported functions, traits, and non-trivial types require doc comments
+* simple marker components, newtype wrappers, and internal `pub` items
+  used only within the same crate are exempt from doc comment requirements
 
 ---
 
@@ -276,11 +306,13 @@ NEVER commit otherwise
 
 Claude must request confirmation before:
 
-* adding dependencies
+* adding dependencies to `solitaire_core` or `solitaire_sync`
-* modifying `solitaire_sync`
+  (engine/server crates may add deps without confirmation)
-* changing DB schema
+* modifying `solitaire_sync` types or the `SyncProvider` trait
+* changing DB schema (migrations are append-only)
 * introducing `unsafe`
-* changing merge strategy
+* changing the merge strategy in `solitaire_sync::merge`
+* changing the `SyncPayload` wire format (breaking change for existing servers)
 
 ---
 
@@ -304,10 +336,29 @@ Core is always the source of truth.
 
 Must always be handled explicitly:
 
+**All platforms**
 * Bevy `Time` uses `f32`
 * `sqlx::migrate!()` path is crate-relative
 * `dirs::data_dir()` may return `None`
-* Linux may lack keyring backend
+* Linux may lack keyring backend — handle `keyring::Error` gracefully
+
+**Android (active target — not stretch)**
+* Safe-area insets arrive in frames 1–3 via JNI polling, not at startup;
+  UI that depends on them must handle the zero-inset initial state
+* Physical pixels ≠ logical pixels: `SafeAreaInsets` values are physical
+  (from `WindowInsets` API); divide by `window.scale_factor()` before
+  passing to Bevy `Val::Px`
+* `adb shell input tap` uses physical pixel coordinates
+* FiraMono (bundled font) covers: ASCII, card suits U+2660–2666,
+  Arrows U+2190–21FF. It does NOT cover Geometric Shapes (U+25xx) —
+  those render as missing-glyph rectangles on Android
+* The gesture/navigation bar at the bottom (≈132px physical on common
+  devices) is inside the Bevy viewport; use `SafeAreaInsets.bottom` to
+  avoid placing interactive elements in that zone
+* `HUD_BAND_HEIGHT` is 112px on Android vs 64px on desktop;
+  layout constants are `#[cfg(target_os = "android")]` gated
+* JNI calls must use `attach_current_thread_permanently` — not
+  `attach_current_thread` — to avoid detach-on-drop panics
 
 ---
 
@@ -318,6 +369,12 @@ Must always be handled explicitly:
 * blocking async calls in ECS
 * insecure credential storage
 * bypassing core logic layer
+* hardcoded pixel coordinates in layout — always derive from `compute_layout`
+* Unicode Geometric Shapes block (U+25xx) in UI text — not in FiraMono
+* spawning a second `ModalScrim` while one already exists without first
+  dismissing the existing one (use `scrims.is_empty()` guard)
+* reading `SafeAreaInsets` physical values directly into `Val::Px` without
+  dividing by `window.scale_factor()`
 
 ---
 
@@ -345,9 +402,74 @@ If unclear:
 | Both combined   | full system understanding |
 
 ---
-# 14. Context Injection System (AUTOMATIC SCOPE FILTER)
+# 14. Modal System Conventions
 
-## 14.1 Purpose
+All full-screen overlay panels MUST use the `spawn_modal` / `ModalScrim` pattern
+from `solitaire_engine::ui_modal`.
+
+## 14.1 Spawn pattern
+
+```rust
+let scrim = spawn_modal(commands, MyScreenMarker, Z_MODAL_PANEL, |card| {
+    spawn_modal_header(card, "Title", font_res);
+    // ... body nodes ...
+    spawn_modal_actions(card, |actions| {
+        spawn_modal_button(actions, MyCloseButton, "Done", None,
+                           ButtonVariant::Primary, font_res);
+    });
+});
+// Optional: allow clicking the scrim outside the card to dismiss
+commands.entity(scrim).insert(ScrimDismissible);
+```
+
+## 14.2 Guard rule
+
+Before spawning a new modal, check `scrims: Query<(), With<ModalScrim>>`
+and return early if `!scrims.is_empty()` — unless the new modal is
+explicitly replacing the current one (despawn first, then spawn).
+
+## 14.3 Safe area
+
+Every `ModalScrim` automatically receives `padding.bottom` equal to the
+logical gesture-bar height via `apply_safe_area_to_modal_scrims` in
+`SafeAreaInsetsPlugin`. Do not manually add bottom padding to scrim nodes.
+
+## 14.4 Z-ordering
+
+Use `Z_MODAL_PANEL` from `ui_theme` for all modal scrims. Do not use
+raw `z_index` values — they drift and cause ordering bugs.
+
+---
+
+# 15. Android Build & Verification
+
+## 15.1 Build command
+
+```bash
+cargo apk build --package solitaire_app --lib
+adb install -r target/debug/apk/ferrous-solitaire.apk
+```
+
+## 15.2 Coordinate system reminder
+
+Device physical: 1080×2400. Bevy logical: 900×2000. Scale factor: 1.20.
+`adb shell input tap X Y` takes PHYSICAL coordinates.
+To convert from what you see on screen (logical): multiply by 1.20.
+
+## 15.3 Android-specific test checklist
+
+Before shipping any Android build:
+- [ ] Safe area insets arrive and shift HUD correctly (check after 3s)
+- [ ] All modal Done buttons are above the gesture bar
+- [ ] No Geometric Shapes glyphs in UI text
+- [ ] HUD band does not overlap the top status bar
+- [ ] Touch drag-and-drop works on all pile types
+
+---
+
+# 16. Context Injection System (AUTOMATIC SCOPE FILTER)
+
+## 16.1 Purpose
 
 Before generating any response, Claude MUST construct a **minimal relevant context set**.
 
@@ -360,7 +482,7 @@ This prevents:
 
 ---
 
-## 14.2 Input Classification Step (MANDATORY)
+## 16.2 Input Classification Step (MANDATORY)
 
 Every request MUST be classified into exactly one task type:
 
@@ -381,13 +503,13 @@ If uncertain → ask clarification.
 
 ---
 
-## 14.3 Context Selection Engine
+## 16.3 Context Selection Engine
 
 After classification, Claude MUST include ONLY the relevant sections below.
 
 ---
 
-## 14.4 Context Map (CORE RULESET)
+## 16.4 Context Map (CORE RULESET)
 
 ### feature
 
@@ -495,7 +617,7 @@ Include:
 
 ---
 
-## 14.5 Context Compression Rules
+## 16.5 Context Compression Rules
 
 Claude MUST obey:
 
@@ -506,7 +628,7 @@ Claude MUST obey:
 
 ---
 
-## 14.6 Context Priority Order
+## 16.6 Context Priority Order
 
 When space is limited:
 
@@ -517,7 +639,7 @@ When space is limited:
 
 ---
 
-## 14.7 “No Context Pollution” Rule
+## 16.7 “No Context Pollution” Rule
 
 Claude must NOT include:
 
@@ -529,7 +651,7 @@ Claude must NOT include:
 
 ---
 
-## 14.8 Self-Check Before Execution
+## 16.8 Self-Check Before Execution
 
 Before writing code, Claude MUST verify:
 
@@ -542,7 +664,7 @@ If any fail → revise context selection.
 
 ---
 
-## 14.9 Injection Output Format (Internal Model)
+## 16.9 Injection Output Format (Internal Model)
 
 Claude should behave as if it constructed:
 
@@ -560,7 +682,7 @@ Claude should behave as if it constructed:
 
 ---
 
-## 14.10 Relationship to ARCHITECTURE.md
+## 16.10 Relationship to ARCHITECTURE.md
 
 * ARCHITECTURE.md = source of truth
 * CLAUDE.md = execution constraints

CLAUDE_PROMPT_PACK.md

@@ -1,497 +0,0 @@
-# CLAUDE_PROMPT_PACK.md
-
-version: 1.0
-
----
-
-# 0. GLOBAL INSTRUCTION (prepend to every prompt)
-
-```
-You must follow CLAUDE_SPEC.md strictly.
-
-Rules:
-- Do not expand scope beyond what is defined
-- Do not refactor unrelated code
-- Do not introduce new dependencies
-- Prefer minimal, surgical changes
-- Use existing patterns in the codebase
-- Return minimal diffs or changed functions only
-
-Before writing code:
-1. List relevant constraints from CLAUDE_SPEC.md
-2. Identify risks
-3. Then implement
-```
-
----
-
-# 1. FEATURE IMPLEMENTATION
-
-```
-# TASK: Feature Implementation
-
-feature: "<name>"
-
-goal:
-"<clear outcome>"
-
-scope:
-crates: []
-systems: []
-files: []
-
-non_goals:
-- ""
-
-constraints:
-- must follow CLAUDE_SPEC.md
-- event-driven architecture required
-- no blocking operations
-- no cross-crate leakage
-
-acceptance_criteria:
-- ""
-- ""
-
-edge_cases:
-- ""
-
----
-
-## Required Patterns
-
-Use this pattern for systems:
-<PASTE EXISTING SYSTEM SNIPPET HERE>
-
----
-
-## Output Format
-
-intent:
-plan:
-constraints_used:
-risks:
-
-code_changes:
-(minimal diffs only)
-
-notes:
-```
-
----
-
-# 2. BUGFIX
-
-```
-# TASK: Bug Fix
-
-bug_description:
-"<what is broken>"
-
-expected_behavior:
-"<correct behavior>"
-
-root_cause_hint (optional):
-""
-
-scope:
-crates: []
-files: []
-
-constraints:
-- minimal fix only
-- no refactors unless required
-- must add regression protection if applicable
-
----
-
-## Requirements
-
-1. Identify root cause
-2. Fix it minimally
-3. Preserve all invariants
-4. Do not change unrelated logic
-
----
-
-## Output Format
-
-analysis:
-root_cause:
-fix_strategy:
-
-code_changes:
-(minimal diff)
-
-regression_test (only if high-value):
-
-notes:
-```
-
----
-
-# 3. REFACTOR
-
-```
-# TASK: Refactor
-
-target:
-"<what is being improved>"
-
-goal:
-"<what improves>"
-
-scope:
-crates: []
-files: []
-
-non_goals:
-- no behavior changes
-- no new features
-
-constraints:
-- must preserve behavior exactly
-- must respect crate boundaries
-- must not duplicate logic
-
----
-
-## Refactor Type
-
-- [ ] simplify logic
-- [ ] reduce duplication
-- [ ] improve readability
-- [ ] performance (non-invasive)
-
----
-
-## Output Format
-
-analysis:
-issues_found:
-
-refactor_plan:
-
-code_changes:
-(diff only)
-
-verification:
-- behavior unchanged: yes/no
-- invariants preserved: yes/no
-
-notes:
-```
-
----
-
-# 4. SYSTEM DESIGN (NEW FEATURE)
-
-```
-# TASK: System Design
-
-feature:
-"<name>"
-
-goal:
-"<what problem it solves>"
-
-constraints:
-- must fit existing architecture
-- must follow plugin + event model
-- must not violate crate boundaries
-
----
-
-## Required Output
-
-design:
-
-components:
-- plugins:
-- systems:
-- events:
-- resources:
-
-data_flow:
-(step-by-step)
-
-integration_points:
-- where it connects to existing systems
-
-risks:
-- ""
-
-tradeoffs:
-- ""
-
----
-
-## DO NOT
-
-- write full implementation
-- modify unrelated systems
-```
-
----
-
-# 5. NEW BEVY SYSTEM
-
-```
-# TASK: Add Bevy System
-
-system_name:
-""
-
-trigger:
-(event or condition)
-
-reads:
-[Resources]
-
-writes:
-[Resources]
-
-emits:
-[Events]
-
-constraints:
-- must be event-driven
-- must not directly mutate unrelated state
-- must be single responsibility
-
----
-
-## Output Format
-
-system_signature:
-
-implementation:
-(code only)
-
-notes:
-```
-
----
-
-# 6. CORE LOGIC FUNCTION (solitaire_core)
-
-```
-# TASK: Core Logic Implementation
-
-function:
-"<name>"
-
-goal:
-"<what it does>"
-
-rules:
-- no IO
-- no async
-- no Bevy
-- deterministic
-
-invariants:
-- ""
-- ""
-
-errors:
-- ""
-
----
-
-## Output Format
-
-constraints_checked:
-
-implementation:
-(code only)
-
-edge_case_handling:
-
-notes:
-```
-
----
-
-# 7. SYNC / MERGE LOGIC
-
-```
-# TASK: Sync Logic
-
-goal:
-"<what is being merged or synced>"
-
-constraints:
-- must be deterministic
-- must be idempotent
-- must be lossless
-- must not delete data
-
-rules:
-- counters → max
-- times → min
-- collections → union
-
----
-
-## Output Format
-
-analysis:
-
-merge_logic:
-
-code_changes:
-
-invariants_verified:
-- deterministic
-- idempotent
-- lossless
-
-notes:
-```
-
----
-
-# 8. PERFORMANCE OPTIMIZATION
-
-```
-# TASK: Optimization
-
-target:
-"<what is slow>"
-
-constraints:CLAUDE_WORKFLOW.md
-- no behavior change
-- no architecture change
-- minimal code changes
-
----
-
-## Output Format
-
-analysis:
-bottleneck:
-
-optimization_strategy:
-
-code_changes:
-
-impact_estimate:
-
-notes:
-```
-
----
-
-# 9. TEST GENERATION (STRICT MODE)
-
-```
-# TASK: Test Generation
-
-target:
-"<function/system>"
-
-reason:
-- bugfix | complex logic | invariant protection
-
-constraints:
-- no redundant tests
-- must test real behavior
-- must fail if logic breaks
-
----
-
-## Output Format
-
-test_cases:
-- ""
-
-test_code:
-
-notes:
-```
-
----
-
-# 10. DEBUGGING / INVESTIGATION
-
-```
-# TASK: Debug
-
-problem:
-"<symptom>"
-
-context:
-"<relevant code or system>"
-
----
-
-## Required Steps
-
-1. List possible causes
-2. Narrow down most likely
-3. Suggest verification steps
-4. Provide minimal fix
-
----
-
-## Output Format
-
-hypotheses:
-
-most_likely:
-
-verification_steps:
-
-fix:
-
-notes:
-```
-
----
-
-# 11. HARD CONSTRAINT OVERRIDE (RARE)
-
-```
-# TASK: Exception Handling
-
-reason:
-"<why constraints must be bent>"
-
-requested_exception:
-"<rule being broken>"
-
-justification:
-"<why unavoidable>"
-
----
-
-## Output Format
-
-analysis:
-
-alternatives_considered:
-
-final_decision:
-
-risk:
-```
-
----
-
-# 12. STOP CONDITIONS (always append)
-
-```
-Stop when:
-- acceptance criteria are met
-- code is minimal and correct
-
-Do NOT:
-- expand scope
-- refactor unrelated code
-- optimize prematurely
-```
-
----
-
-# END

CLAUDE_SPEC.md

@@ -1,292 +0,0 @@
-# CLAUDE_SPEC.md
-
-version: 1.0
-
----
-
-## 0. Global Rules
-
-(Core determinism, panic policy, and event-driven engine constraints live in CLAUDE.md §2.1, §2.3, §3.1. Listed here only when they add information CLAUDE.md doesn't carry.)
-
-rules:
-
-* id: single_source_of_truth
-  description: "GameStateResource is the only mutable game state in runtime"
-
-* id: sync_is_additive
-  description: "Remote data must never destructively overwrite local data"
-
----
-
-## 1. Crate Graph
-
-crates:
-solitaire_core:
-depends_on: [rand, serde, chrono]
-forbidden_deps: [bevy, reqwest, tokio, std::fs]
-
-solitaire_sync:
-depends_on: [serde, serde_json, uuid, chrono]
-role: "shared_types"
-
-solitaire_data:
-depends_on: [solitaire_core, solitaire_sync, reqwest, tokio, keyring]
-role: "persistence_and_sync"
-
-solitaire_engine:
-depends_on: [bevy, kira, solitaire_core, solitaire_data]
-role: "runtime_engine"
-
-solitaire_server:
-depends_on: [solitaire_sync, axum, sqlx, jsonwebtoken]
-role: "backend"
-
-solitaire_app:
-depends_on: [solitaire_engine]
-role: "entrypoint"
-
----
-
-## 2. Data Ownership
-
-ownership:
-GameState:
-owner: solitaire_core
-mutable_in: solitaire_engine
-access_pattern: "via GameStateResource only"
-
-StatsSnapshot:
-owner: solitaire_data
-
-PlayerProgress:
-owner: solitaire_data
-
-AchievementRecord:
-owner: solitaire_data
-
-SyncPayload:
-owner: solitaire_sync
-
----
-
-## 3. State Transitions
-
-state_machine:
-GameState:
-transitions:
-- action: move_cards
-returns: Result<GameState, MoveError>
-
-```
-  - action: draw
-    returns: Result<GameState, MoveError>
-
-  - action: undo
-    returns: Result<GameState, MoveError>
-
-invariants:
-  - "52 cards always exist"
-  - "no duplicate card IDs"
-  - "all cards belong to exactly one pile"
-```
-
----
-
-## 4. Event System
-
-events:
-
-input:
-- MoveRequestEvent
-- DrawRequestEvent
-- UndoRequestEvent
-- NewGameRequestEvent
-
-state:
-- StateChangedEvent
-- GameWonEvent
-
-meta:
-- AchievementUnlockedEvent
-- SyncCompleteEvent
-
-rules:
-
-* "Input events trigger core logic"
-* "Core logic emits state events"
-* "UI reacts to state events only"
-
----
-
-## 5. Sync Contract
-
-sync:
-
-provider_trait:
-methods:
-- pull() -> SyncPayload
-- push(payload) -> SyncResponse
-
-guarantees:
-- "non-blocking during gameplay"
-- "blocking allowed on exit only"
-
-merge:
-rules:
-counters: "max"
-best_times: "min"
-collections: "union"
-achievements: "never removed"
-
-```
-properties:
-  - deterministic
-  - idempotent
-  - lossless
-```
-
----
-
-## 6. Persistence
-
-storage:
-
-format: json
-
-files:
-- stats.json
-- progress.json
-- achievements.json
-- settings.json
-- game_state.json
-
-guarantees:
-- atomic_write: true
-- crash_safe: true
-
----
-
-## 7. Engine Rules
-
-engine:
-
-mutation_rules:
-- "Only GameLogicSystem mutates GameState"
-- "UI systems are read-only"
-
-threading:
-- "sync runs on AsyncComputeTaskPool"
-- "main thread must never block"
-
-plugins:
-pattern: "feature_isolation"
-communication: "events"
-
----
-
-## 8. Server Contract
-
-server:
-
-auth:
-method: jwt
-access_expiry: 24h
-refresh_expiry: 30d
-
-endpoints:
-- POST /api/auth/register
-- POST /api/auth/login
-- GET /api/sync/pull
-- POST /api/sync/push
-
-limits:
-payload_max: 1MB
-rate_limit: "10 req/min auth routes"
-
----
-
-## 9. Achievement System
-
-achievements:
-
-definition_location: solitaire_core
-state_location: solitaire_data
-
-types:
-- condition_based
-- event_driven
-
-rule:
-- "achievements cannot be revoked"
-
----
-
-## 10. Testing Rules
-
-testing:
-
-philosophy:
-- "test real failures"
-- "avoid redundant tests"
-
-required_coverage:
-solitaire_core:
-- move_validation
-- undo_integrity
-- win_detection
-
-```
-solitaire_sync:
-  - merge_correctness
-  - idempotency
-```
-
----
-
-## 11. Prohibited Patterns
-
-(See CLAUDE.md §11 for the canonical forbidden-patterns list.)
-
----
-
-## 12. Extension Points
-
-extensibility:
-
-sync_backends:
-pattern: "implement SyncProvider"
-
-game_modes:
-location: solitaire_core::GameMode
-
-plugins:
-rule: "new feature = new plugin"
-
----
-
-## 13. Validation Checklist (for Claude)
-
-validation:
-
-* check: "crate dependency rules respected"
-* check: "no panics in core"
-* check: "events used for cross-system communication"
-* check: "GameState mutations centralized"
-* check: "merge function properties preserved"
-* check: "no blocking operations in main loop"
-
----
-
-## 14. Mental Model
-
-model:
-
-layers:
-- core
-- engine
-- data
-- server
-
-flow:
-- input -> engine -> core -> engine -> ui
-- data <-> sync <-> server

CLAUDE_WORKFLOW.md

@@ -1,335 +0,0 @@
-# CLAUDE_WORKFLOW.md
-
-version: 1.0
-
----
-
-## 0. Overview
-
-This workflow defines a **two-agent system**:
-
-* **Builder Agent** → writes and modifies code
-* **Guardian Agent** → enforces architecture + rejects invalid changes
-
-No code is considered valid unless it passes Guardian validation.
-
----
-
-## 1. Agent Roles
-
-### 1.1 Builder Agent
-
-role: "code_generation"
-
-responsibilities:
-
-* implement features
-* refactor code
-* generate tests (only when justified)
-* follow CLAUDE_SPEC.md
-
-constraints:
-
-* cannot bypass validation
-* must declare intent before writing code
-
-output_contract:
-must_produce:
-- change_summary
-- files_modified
-- reasoning (short)
-- code_diff
-
----
-
-### 1.2 Guardian Agent
-
-role: "architecture_enforcement"
-
-responsibilities:
-
-* validate against CLAUDE_SPEC.md
-* detect violations
-* reject or approve changes
-* suggest minimal fixes (not full rewrites)
-
-constraints:
-
-* no feature implementation
-* no large rewrites
-* must be deterministic
-
-output_contract:
-must_produce:
-- status: APPROVED | REJECTED
-- violations[]
-- required_fixes[]
-- optional_improvements[]
-
----
-
-## 2. Workflow Pipeline
-
-```text
-User Request
-    ↓
-Builder Agent (proposal + code)
-    ↓
-Guardian Agent (validation)
-    ↓
-IF approved → commit
-IF rejected → feedback → Builder retry
-```
-
----
-
-## 3. Builder Protocol
-
-### Step 1 — Intent Declaration
-
-Builder MUST start with:
-
-```yaml
-intent:
-  feature: "<name>"
-  crates_touched: []
-  systems_affected: []
-  risk_level: low|medium|high
-```
-
----
-
-### Step 2 — Plan
-
-```yaml
-plan:
-  - step: "..."
-  - step: "..."
-```
-
----
-
-### Step 3 — Implementation
-
-* Only modify declared crates
-* Follow ownership rules
-* Use events for cross-system communication
-
----
-
-### Step 4 — Output
-
-```yaml
-change_summary: "..."
-
-files_modified:
-  - path: ...
-    change: "..."
-
-violations_self_check:
-  - none | list
-
-notes: "short reasoning"
-```
-
----
-
-## 4. Guardian Protocol
-
-### Step 1 — Spec Validation
-
-Check against:
-
-* crate boundaries
-* mutation rules
-* event system usage
-* sync guarantees
-* forbidden patterns
-
----
-
-### Step 2 — Invariant Validation
-
-Must verify:
-
-* GameState invariants preserved
-* no new panic paths
-* no blocking calls in engine
-* merge properties unchanged
-
----
-
-### Step 3 — Output Decision
-
-#### APPROVED
-
-```yaml
-status: APPROVED
-
-notes:
-  - "no violations"
-```
-
----
-
-#### REJECTED
-
-```yaml
-status: REJECTED
-
-violations:
-  - id: core_purity_violation
-    file: "solitaire_core/src/..."
-    reason: "uses std::fs"
-
-required_fixes:
-  - "move IO to solitaire_data"
-
-optional_improvements:
-  - "simplify event naming"
-```
-
----
-
-## 5. Enforcement Rules
-
-### Hard Fail (automatic rejection)
-
-* core crate uses IO / Bevy / network
-* GameState mutated outside GameLogicSystem
-* blocking async on main thread
-* duplicate logic across crates
-* merge function altered incorrectly
-
----
-
-### Soft Fail (allowed but flagged)
-
-* unnecessary complexity
-* redundant tests
-* minor architectural drift
-
----
-
-## 6. Iteration Loop
-
-Max attempts per task: **3**
-
-```text
-Attempt 1 → Reject → Fix
-Attempt 2 → Reject → Fix
-Attempt 3 → Final decision
-```
-
-If still failing:
-→ escalate to user
-
----
-
-## 7. Diff Strategy
-
-Builder MUST produce:
-
-* minimal diffs
-* no unrelated refactors
-* no formatting-only changes
-
----
-
-## 8. Test Strategy Integration
-
-Builder rules:
-
-* only add tests if:
-
-  * fixing a bug
-  * protecting complex logic
-  * validating invariants
-
-Guardian rejects:
-
-* redundant tests
-* no-op tests
-
----
-
-## 9. Optional Extensions
-
-### 9.1 Third Agent (Optimizer)
-
-role: performance + cleanup
-
-runs AFTER approval:
-
-* reduce allocations
-* simplify logic
-* improve ECS scheduling
-
----
-
-### 9.2 CI Integration
-
-Pipeline:
-
-```text
-Builder → Guardian → cargo check → clippy → tests
-```
-
-Guardian runs BEFORE compilation to catch structural issues early.
-
----
-
-## 10. Example Interaction
-
-### Builder
-
-```yaml
-intent:
-  feature: "undo stack limit fix"
-  crates_touched: [solitaire_core]
-  risk_level: low
-```
-
-```yaml
-change_summary: "limit undo stack to 64 entries"
-
-files_modified:
-  - solitaire_core/src/game_state.rs
-
-notes: "prevents unbounded memory growth"
-```
-
----
-
-### Guardian
-
-```yaml
-status: APPROVED
-
-notes:
-  - "respects core constraints"
-  - "no invariant violations"
-```
-
----
-
-## 11. Mental Model
-
-* Builder = **creative**
-* Guardian = **strict**
-
-Builder explores
-Guardian enforces
-
-Neither replaces the other.
-
----
-
-## 12. Success Criteria
-
-System is working if:
-
-* architectural violations go to ~0
-* code stays consistent across features
-* refactors become safe
-* complexity grows sub-linearly

CREDITS.md

@@ -1,6 +1,6 @@
 # Credits
 
-Solitaire Quest is MIT-licensed (see [LICENSE](LICENSE)). It is built on top of
+Ferrous Solitaire is MIT-licensed (see [LICENSE](LICENSE)). It is built on top of
 the work of many open-source projects and a small handful of third-party
 assets. This file lists every component that ships in the binary or in the
 `assets/` directory.
@@ -43,7 +43,7 @@ copyleft code is statically linked into the game binary.
 | File(s) | Source | License |
 |---|---|---|
 | `solitaire_engine/assets/themes/default/{suit}_{rank}.svg` (52 SVGs) | [hayeah/playing-cards-assets](https://github.com/hayeah/playing-cards-assets) | MIT |
-| `solitaire_engine/assets/themes/default/back.svg` | Original — Solitaire Quest | MIT (this project) |
+| `solitaire_engine/assets/themes/default/back.svg` | Original — Ferrous Solitaire | MIT (this project) |
 | `assets/cards/faces/{RANK}{SUIT}.png` (52 PNGs) | Pre-rendered from the same `playing-cards-assets` SVGs | MIT (passed through from hayeah) |
 | `assets/cards/backs/back_0.png` – `back_4.png` | Original — generated by `solitaire_assetgen::gen_art` | MIT (this project) |
 
@@ -107,6 +107,6 @@ Audio files are MIT-licensed alongside the rest of this project.
   backs, every audio file) are original work covered by this project's MIT
   license.
 
-If you redistribute Solitaire Quest, you must ship this `CREDITS.md` and the
+If you redistribute Ferrous Solitaire, you must ship this `CREDITS.md` and the
 `LICENSE` file alongside the binary so the MIT (project + hayeah card art)
 and OFL (FiraMono) notices remain visible to end users.

Cargo.lock

@@ -126,6 +126,19 @@ dependencies = [
  "subtle",
 ]
 
+[[package]]
+name = "ahash"
+version = "0.8.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5a15f179cd60c4584b8a8c596927aadc462e27f2ca70c04e0071964a73ba7a75"
+dependencies = [
+ "cfg-if",
+ "getrandom 0.3.4",
+ "once_cell",
+ "version_check",
+ "zerocopy",
+]
+
 [[package]]
 name = "aho-corasick"
 version = "1.1.4"
@@ -719,7 +732,7 @@ dependencies = [
  "cfg-if",
  "console_error_panic_hook",
  "ctrlc",
- "downcast-rs",
+ "downcast-rs 2.0.2",
  "log",
  "thiserror 2.0.18",
  "variadics_please",
@@ -753,7 +766,7 @@ dependencies = [
  "crossbeam-channel",
  "derive_more",
  "disqualified",
- "downcast-rs",
+ "downcast-rs 2.0.2",
  "either",
  "futures-io",
  "futures-lite",
@@ -801,7 +814,7 @@ dependencies = [
  "bevy_utils",
  "bevy_window",
  "derive_more",
- "downcast-rs",
+ "downcast-rs 2.0.2",
  "serde",
  "smallvec",
  "thiserror 2.0.18",
@@ -1200,7 +1213,7 @@ dependencies = [
  "bevy_utils",
  "derive_more",
  "disqualified",
- "downcast-rs",
+ "downcast-rs 2.0.2",
  "erased-serde",
  "foldhash 0.2.0",
  "glam 0.30.10",
@@ -1259,7 +1272,7 @@ dependencies = [
  "bitflags 2.11.1",
  "bytemuck",
  "derive_more",
- "downcast-rs",
+ "downcast-rs 2.0.2",
  "encase",
  "fixedbitset",
  "glam 0.30.10",
@@ -1854,6 +1867,18 @@ dependencies = [
  "thiserror 1.0.69",
 ]
 
+[[package]]
+name = "calloop-wayland-source"
+version = "0.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "95a66a987056935f7efce4ab5668920b5d0dac4a7c99991a67395f13702ddd20"
+dependencies = [
+ "calloop",
+ "rustix 0.38.44",
+ "wayland-backend",
+ "wayland-client",
+]
+
 [[package]]
 name = "cbc"
 version = "0.1.2"
@@ -2709,6 +2734,12 @@ version = "0.15.7"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "1aaf95b3e5c8f23aa320147307562d361db0ae0d51242340f558153b4eb2439b"
 
+[[package]]
+name = "downcast-rs"
+version = "1.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "75b325c5dbd37f80359721ad39aca5a29fb04c89279657cffdda8736d0c0b9d2"
+
 [[package]]
 name = "downcast-rs"
 version = "2.0.2"
@@ -4003,9 +4034,14 @@ checksum = "85ab80394333c02fe689eaf900ab500fbd0c2213da414687ebf995a65d5a6104"
 dependencies = [
  "bytemuck",
  "byteorder-lite",
+ "color_quant",
+ "gif",
+ "image-webp",
  "moxcms",
  "num-traits",
  "png 0.18.1",
+ "zune-core",
+ "zune-jpeg",
 ]
 
 [[package]]
@@ -5792,6 +5828,15 @@ version = "2.0.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "a993555f31e5a609f617c12db6250dedcac1b0a85076912c436e6fc9b2c8e6a3"
 
+[[package]]
+name = "quick-xml"
+version = "0.39.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "958f21e8e7ceb5a1aa7fa87fab28e7c75976e0bfe7e23ff069e0a260f894067d"
+dependencies = [
+ "memchr",
+]
+
 [[package]]
 name = "quinn"
 version = "0.11.9"
@@ -6165,7 +6210,7 @@ dependencies = [
  "pico-args",
  "rgb",
  "svgtypes",
- "tiny-skia",
+ "tiny-skia 0.12.0",
  "usvg",
  "zune-jpeg",
 ]
@@ -6502,6 +6547,19 @@ version = "1.2.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "94143f37725109f92c262ed2cf5e59bce7498c01bcc1502d7b9afe439a4e9f49"
 
+[[package]]
+name = "sctk-adwaita"
+version = "0.10.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b6277f0217056f77f1d8f49f2950ac6c278c0d607c45f5ee99328d792ede24ec"
+dependencies = [
+ "ab_glyph",
+ "log",
+ "memmap2",
+ "smithay-client-toolkit",
+ "tiny-skia 0.11.4",
+]
+
 [[package]]
 name = "sec1"
 version = "0.7.3"
@@ -6846,6 +6904,31 @@ dependencies = [
  "serde",
 ]
 
+[[package]]
+name = "smithay-client-toolkit"
+version = "0.19.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3457dea1f0eb631b4034d61d4d8c32074caa6cd1ab2d59f2327bd8461e2c0016"
+dependencies = [
+ "bitflags 2.11.1",
+ "calloop",
+ "calloop-wayland-source",
+ "cursor-icon",
+ "libc",
+ "log",
+ "memmap2",
+ "rustix 0.38.44",
+ "thiserror 1.0.69",
+ "wayland-backend",
+ "wayland-client",
+ "wayland-csd-frame",
+ "wayland-cursor",
+ "wayland-protocols",
+ "wayland-protocols-wlr",
+ "wayland-scanner",
+ "xkeysym",
+]
+
 [[package]]
 name = "smol_str"
 version = "0.2.2"
@@ -6879,6 +6962,8 @@ dependencies = [
  "keyring",
  "solitaire_data",
  "solitaire_engine",
+ "tiny-skia 0.12.0",
+ "winit",
 ]
 
 [[package]]
@@ -6887,6 +6972,8 @@ version = "0.1.0"
 dependencies = [
  "ab_glyph",
  "png 0.17.16",
+ "solitaire_core",
+ "solitaire_data",
 ]
 
 [[package]]
@@ -6904,8 +6991,10 @@ version = "0.1.0"
 dependencies = [
  "async-trait",
  "axum",
+ "bevy",
  "chrono",
  "dirs",
+ "jni 0.21.1",
  "jsonwebtoken",
  "keyring-core",
  "reqwest",
@@ -6929,16 +7018,20 @@ dependencies = [
  "bevy",
  "chrono",
  "dirs",
+ "image",
+ "jni 0.21.1",
  "kira",
+ "reqwest",
  "resvg",
  "ron",
  "serde",
+ "serde_json",
  "solitaire_core",
  "solitaire_data",
  "solitaire_sync",
  "tempfile",
  "thiserror 2.0.18",
- "tiny-skia",
+ "tiny-skia 0.12.0",
  "tokio",
  "usvg",
  "uuid",
@@ -7525,7 +7618,7 @@ dependencies = [
  "crc32fast",
  "crossbeam-channel",
  "datasketches",
- "downcast-rs",
+ "downcast-rs 2.0.2",
  "fastdivide",
  "fnv",
  "fs4",
@@ -7577,7 +7670,7 @@ version = "0.7.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "c57166f5bcfd478f370ab8445afb4678dce44801fa5ce5c451aaf8595583c5dc"
 dependencies = [
- "downcast-rs",
+ "downcast-rs 2.0.2",
  "fastdivide",
  "itertools 0.14.0",
  "serde",
@@ -7765,6 +7858,20 @@ dependencies = [
  "time-core",
 ]
 
+[[package]]
+name = "tiny-skia"
+version = "0.11.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "83d13394d44dae3207b52a326c0c85a8bf87f1541f23b0d143811088497b09ab"
+dependencies = [
+ "arrayref",
+ "arrayvec",
+ "bytemuck",
+ "cfg-if",
+ "log",
+ "tiny-skia-path 0.11.4",
+]
+
 [[package]]
 name = "tiny-skia"
 version = "0.12.0"
@@ -7777,7 +7884,18 @@ dependencies = [
  "cfg-if",
  "log",
  "png 0.18.1",
- "tiny-skia-path",
+ "tiny-skia-path 0.12.0",
+]
+
+[[package]]
+name = "tiny-skia-path"
+version = "0.11.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9c9e7fc0c2e86a30b117d0462aa261b72b7a99b7ebd7deb3a14ceda95c5bdc93"
+dependencies = [
+ "arrayref",
+ "bytemuck",
+ "strict-num",
 ]
 
 [[package]]
@@ -8548,7 +8666,7 @@ dependencies = [
  "siphasher",
  "strict-num",
  "svgtypes",
- "tiny-skia-path",
+ "tiny-skia-path 0.12.0",
  "ttf-parser",
  "unicode-bidi",
  "unicode-script",
@@ -8754,6 +8872,114 @@ dependencies = [
  "semver",
 ]
 
+[[package]]
+name = "wayland-backend"
+version = "0.3.15"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2857dd20b54e916ec7253b3d6b4d5c4d7d4ca2c33c2e11c6c76a99bd8744755d"
+dependencies = [
+ "cc",
+ "downcast-rs 1.2.1",
+ "rustix 1.1.4",
+ "scoped-tls",
+ "smallvec",
+ "wayland-sys",
+]
+
+[[package]]
+name = "wayland-client"
+version = "0.31.14"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "645c7c96bb74690c3189b5c9cb4ca1627062bb23693a4fad9d8c3de958260144"
+dependencies = [
+ "bitflags 2.11.1",
+ "rustix 1.1.4",
+ "wayland-backend",
+ "wayland-scanner",
+]
+
+[[package]]
+name = "wayland-csd-frame"
+version = "0.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "625c5029dbd43d25e6aa9615e88b829a5cad13b2819c4ae129fdbb7c31ab4c7e"
+dependencies = [
+ "bitflags 2.11.1",
+ "cursor-icon",
+ "wayland-backend",
+]
+
+[[package]]
+name = "wayland-cursor"
+version = "0.31.14"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4a52d18780be9b1314328a3de5f930b73d2200112e3849ca6cb11822793fb34d"
+dependencies = [
+ "rustix 1.1.4",
+ "wayland-client",
+ "xcursor",
+]
+
+[[package]]
+name = "wayland-protocols"
+version = "0.32.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "563a85523cade2429938e790815fd7319062103b9f4a2dc806e9b53b95982d8f"
+dependencies = [
+ "bitflags 2.11.1",
+ "wayland-backend",
+ "wayland-client",
+ "wayland-scanner",
+]
+
+[[package]]
+name = "wayland-protocols-plasma"
+version = "0.3.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2b6d8cf1eb2c1c31ed1f5643c88a6e53538129d4af80030c8cabd1f9fa884d91"
+dependencies = [
+ "bitflags 2.11.1",
+ "wayland-backend",
+ "wayland-client",
+ "wayland-protocols",
+ "wayland-scanner",
+]
+
+[[package]]
+name = "wayland-protocols-wlr"
+version = "0.3.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "eb04e52f7836d7c7976c78ca0250d61e33873c34156a2a1fc9474828ec268234"
+dependencies = [
+ "bitflags 2.11.1",
+ "wayland-backend",
+ "wayland-client",
+ "wayland-protocols",
+ "wayland-scanner",
+]
+
+[[package]]
+name = "wayland-scanner"
+version = "0.31.10"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9c324a910fd86ebdc364a3e61ec1f11737d3b1d6c273c0239ee8ff4bc0d24b4a"
+dependencies = [
+ "proc-macro2",
+ "quick-xml",
+ "quote",
+]
+
+[[package]]
+name = "wayland-sys"
+version = "0.31.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d8eab23fefc9e41f8e841df4a9c707e8a8c4ed26e944ef69297184de2785e3be"
+dependencies = [
+ "dlib",
+ "log",
+ "pkg-config",
+]
+
 [[package]]
 name = "web-sys"
 version = "0.3.97"
@@ -9569,6 +9795,7 @@ version = "0.30.13"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "a6755fa58a9f8350bd1e472d4c3fcc25f824ec358933bba33306d0b63df5978d"
 dependencies = [
+ "ahash",
  "android-activity",
  "atomic-waker",
  "bitflags 2.11.1",
@@ -9583,6 +9810,7 @@ dependencies = [
  "dpi",
  "js-sys",
  "libc",
+ "memmap2",
  "ndk",
  "objc2 0.5.2",
  "objc2-app-kit 0.2.2",
@@ -9594,11 +9822,17 @@ dependencies = [
  "raw-window-handle",
  "redox_syscall 0.4.1",
  "rustix 0.38.44",
+ "sctk-adwaita",
+ "smithay-client-toolkit",
  "smol_str",
  "tracing",
  "unicode-segmentation",
  "wasm-bindgen",
  "wasm-bindgen-futures",
+ "wayland-backend",
+ "wayland-client",
+ "wayland-protocols",
+ "wayland-protocols-plasma",
  "web-sys",
  "web-time",
  "windows-sys 0.52.0",
@@ -9766,6 +10000,12 @@ version = "0.13.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "ea6fc2961e4ef194dcbfe56bb845534d0dc8098940c7e5c012a258bfec6701bd"
 
+[[package]]
+name = "xcursor"
+version = "0.3.10"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bec9e4a500ca8864c5b47b8b482a73d62e4237670e5b5f1d6b9e3cae50f28f2b"
+
 [[package]]
 name = "xkbcommon-dl"
 version = "0.4.2"

Cargo.toml

@@ -31,6 +31,7 @@ keyring     = "4"
 keyring-core = "1"
 reqwest     = { version = "0.13", features = ["json", "rustls", "rustls-native-certs"], default-features = false }
 arboard     = { version = "3", default-features = false }
+jni         = { version = "0.21", default-features = false }
 
 solitaire_core   = { path = "solitaire_core" }
 solitaire_sync   = { path = "solitaire_sync" }
@@ -54,12 +55,24 @@ bevy = { version = "0.18", default-features = false, features = [
     "bevy_window",
     "custom_cursor",
     "reflect_auto_register",
-    # default_platform (desktop subset; no android/wayland/webgl/gilrs/sysinfo)
+    # default_platform (desktop subset)
     "std",
     "bevy_winit",
     "default_font",
     "multi_threaded",
+    # winit prefers Wayland when WAYLAND_DISPLAY is set on the
+    # session and falls through to X11 otherwise. Without `wayland`,
+    # winit-on-Wayland-session falls back to XWayland which renders
+    # the game in an X11 frame inside the Wayland compositor.
+    "wayland",
     "x11",
+    # Android: NativeActivity glue. The feature is target-gated inside
+    # bevy_internal — desktop builds compile it out, so leaving it on
+    # the always-on list is harmless on Linux/macOS/Windows. Pairs with
+    # cargo-apk's NativeActivity wrapper (cargo-apk 0.10+ uses this by
+    # default). Switch to `android-game-activity` later if we want
+    # AndroidX GameActivity for Google Play Games integration.
+    "android-native-activity",
     # common_api
     "bevy_color",
     "bevy_image",
@@ -97,6 +110,9 @@ ron = "0.12"
 # only `deflate` is needed because the importer rejects other
 # compression methods anyway (see Phase 7 spec).
 zip = { version = "8.6", default-features = false, features = ["deflate"] }
+# Image decoding for avatar bytes received from the server.
+# Features mirror what Bevy already enables via bevy_image.
+image = { version = "0.25", default-features = false, features = ["png", "jpeg", "webp", "gif"] }
 
 # Importer-only test dependency: tests build zip archives in a
 # scratch directory so they don't pollute the real user themes path

README.md

@@ -1,4 +1,4 @@
-# Solitaire Quest
+# Ferrous Solitaire
 
 A cross-platform Klondike Solitaire game written in Rust, with a card-theme
 system, full progression (XP / levels / achievements / daily challenges), and
@@ -31,6 +31,23 @@ optional self-hosted sync so your stats follow you across machines.
 - **Color-blind mode** — blue tint on red-suit cards alongside the suit
   glyph
 
+## Android Install
+
+### Obtainium (recommended — automatic updates)
+
+1. Install [Obtainium](https://github.com/ImranR98/Obtainium/releases) on your device
+2. Tap the badge below on your Android device — the source type is pre-configured, no manual selection needed:
+
+   [<img src="https://raw.githubusercontent.com/ImranR98/Obtainium/main/assets/graphics/badge_obtainium.png" alt="Get it on Obtainium" height="40">](https://apps.obtainium.imranr.dev/redirect?r=obtainium://app/%7B%22id%22%3A%22com.ferrousapp.solitaire%22%2C%22url%22%3A%22https%3A//git.aleshym.co/funman300/Ferrous-Solitaire%22%2C%22author%22%3A%22funman300%22%2C%22name%22%3A%22Ferrous%20Solitaire%22%2C%22installedVersion%22%3Anull%2C%22latestVersion%22%3Anull%2C%22apkUrls%22%3A%22%5B%5D%22%2C%22preferredApkIndex%22%3A0%2C%22additionalSettings%22%3A%22%7B%7D%22%2C%22lastUpdateCheck%22%3Anull%2C%22pinned%22%3Afalse%2C%22categories%22%3A%5B%5D%2C%22releaseDate%22%3Anull%2C%22changeLog%22%3Anull%2C%22overrideSource%22%3A%22Codeberg%22%2C%22allowIdChange%22%3Afalse%2C%22otherAssetUrls%22%3A%22%5B%5D%22%7D)
+
+3. Tap **Install** to download the current release — Obtainium will notify you when updates are available.
+
+### Direct APK
+
+Download the latest `ferrous-solitaire.apk` from the
+[Releases](https://git.aleshym.co/funman300/Ferrous-Solitaire/releases) page,
+enable **Install from unknown sources** in your device settings, and open the file.
+
 ## Building
 
 **Prerequisites**

README_SERVER.md

@@ -1,4 +1,4 @@
-# Solitaire Quest — Self-Hosting Guide
+# Ferrous Solitaire — Self-Hosting Guide
 
 ## Prerequisites
 
@@ -42,3 +42,29 @@ git pull
 docker compose build
 docker compose up -d
 ```
+
+
+## Admin — Password Reset
+
+If a player loses access to their account, the server binary includes a
+built-in password reset command. Run it on the host (or inside the container)
+with `DATABASE_URL` pointing at your database:
+
+```bash
+# Interactive (prompts for the new password):
+DATABASE_URL=sqlite://./data/solitaire.db \
+  ./solitaire_server --reset-password <username>
+
+# Non-interactive (piped from a script or password manager):
+echo "new_password" | \
+  DATABASE_URL=sqlite://./data/solitaire.db \
+    ./solitaire_server --reset-password <username>
+
+# Inside a running Docker container:
+docker compose exec server sh -c \
+  'echo "new_password" | ./solitaire_server --reset-password alice'
+```
+
+On success the user's `password_hash` is updated and **all active refresh
+tokens are deleted**, so every open session must log in again with the new
+password. `JWT_SECRET` does not need to be set for this command.

SESSION_HANDOFF.md

@@ -1,179 +1,130 @@
-# Solitaire Quest — Session Handoff
+# Ferrous Solitaire — Session Handoff
 
-**Last updated:** 2026-05-06 (post-v0.18.0 draft) — 24 commits since
+**Last updated:** 2026-05-18 — Three leaderboard bugs fixed, tagged v0.35.1. All commits on origin/master.
-the v0.17.0 tag bundle the launch-experience round (Restore prompt +
-auto-show Home / mode picker), the MSSC-style Home picker rework
-(header chips, draw-mode chips, picture-tile mode cards, Today's
-Event callout, glyph fixes), the last solver hot path moving onto
-`AsyncComputeTaskPool`, "Won before" HUD chip, "Copy share link"
-Stats button, the `N` keybinding finally routing through the real
-Confirm/Cancel modal, Esc-on-modal layering fixes, and the
-unified-3.0 Claude rule set (CLAUDE.md / CLAUDE_SPEC.md /
-CLAUDE_WORKFLOW.md / CLAUDE_PROMPT_PACK.md). Test-discipline prune
-removed 43 low-value tests in the same window.
 
-## Status at pause
+---
 
-- **HEAD on origin:** `v0.17.0-24-gc497c31` (24 ahead of v0.17.0,
+## Current state
-  not yet tagged).
-- **Working tree:** clean.
-- **Build:** `cargo clippy --workspace --all-targets -- -D warnings`
-  clean (verified this session).
-- **Tests:** **1166 passing / 0 failing** across the workspace
-  (verified this session). The first run flaked once on
-  `solitaire_engine::game_plugin::tests::auto_save_writes_after_30_seconds`
-  — a one-frame `app.update()` test that depends on `time.delta_secs()`
-  on an otherwise-fresh `App`. Reproduced clean on the second run;
-  passes in isolation. Worth tightening if it flakes again, but
-  not blocking the v0.18.0 cut.
-- **Tags on origin:** `v0.9.0` through `v0.17.0`.
-- **CHANGELOG:** v0.18.0 entry drafted in `[Unreleased]`'s slot —
-  ready for tag once build + tests are reverified.
 
-## Where we are
+- **HEAD on origin/master:** `8f86d66` (fix: three leaderboard bugs)
+- **Latest tag:** `v0.35.1`
+- **Working tree:** clean
+- **Build:** `cargo clippy --workspace -- -D warnings` clean
+- **Tests:** 1277 passing / 0 failing across the workspace
 
-v0.17.0's punch list had four candidates (A–D); two of the three
+---
-non-packaging items shipped in this round:
 
-- **B — "Won previously" HUD indicator:** shipped in `bdac754`.
+## What shipped since the last handoff (v0.23.0 → v0.35.1)
-- **C — Replay sharing:** shipped in `540869c` ("Copy share link"
-  Stats button + clipboard via `arboard`, in-memory `LastSharedReplayUrl`).
 
-Item **A** (solver-on-`AsyncComputeTaskPool`) shipped *partially* in
+### v0.34.0 — Android polish + code-quality sweep (2026-05-16/17)
-`d489e7a` — the winnable-only seed-selection path is now async with
-cancel-on-replace. The hint path (`H` key,
-`try_solve_with_first_move` / `try_solve_from_state`) is still
-synchronous. The proven `PendingNewGameSeed` template is the
-template for the hint port.
 
-Item **D** (desktop packaging) is unchanged — still gated on
+| Commit | Summary |
-artwork + signing certs from the player.
+|--------|---------|
+| `9623bde` | Wire FiraMono to Android corner label; CardImageSet load tests |
+| `980312c` | Fix wrong bottom-right suit symbol on JS/QS/KS card assets |
+| `04e99a8` | Correct Android waste fan overlap and resume layout desync |
+| `3bb3ddb` | Eliminate panics, fix dismiss hit-test scope, guard home respawn |
+| `f8f1f26` | Adaptive drop zones, touch event correctness, modal lifecycle guards |
+| `1eb4043` | Auth-guard avatar serving; atomic write; user_id assertion in merge |
+| `69c6e88` | Deterministic pile serialization, undo skip, url-encode bytes, merge_at |
+| `aa7b0f6` | Gate frame-hot ECS systems on resource changes (perf) |
+| `6727126` | Consolidate APP_DIR_NAME; add `#[must_use]` on pure fns |
+| `a4dfb0c` | Differentiate leaderboard opt-in vs opt-out error toasts (M-12) |
+| `7fc98f8` | WASM: state() and step() return Result, errors throw JS exceptions (CR-6) |
+| `ffed6b2` | Share Tokio runtime across all network tasks (M-16) |
+| `fa84152` | Correct Android help hint label `→` to `!` (M-17) |
+| `18d7937` | Derive Copy for DrawMode; drop redundant .clone() calls (M-18) |
+| `132fea9` | Use saturating_add for move_count increments (M-19) |
+| `0ecc1a9` | Add missing derives to AchievementContext (M-20) |
+| `2301cc6` | Align android_keystore temp extension with cleanup glob (M-21) |
+| `2e52f54` | Enforce 32-char display_name limit at sync client boundary (M-22) |
+| `c8878d6` | Fix stale FOCUS_RING colour comment (M-23) |
+| `4aafc0a` | Name HUD popover Z-layers; replace raw Z arithmetic (M-24) |
 
-The launch experience is also substantially different from v0.17.0:
+### v0.35.0 — Accessibility + sync reliability (2026-05-18)
-on first launch with a saved game the player now sees the Restore
-prompt; on every launch (after splash + restore resolution) they see
-the auto-show Home / mode picker.
 
-### Design direction (unchanged)
+| Commit | Summary |
+|--------|---------|
+| `eb6c93f` | Silence B0004 by adding Transform to ModalScrim |
+| `6f5cebd` | Fire WarningToastEvent on sync pull failure (was InfoToastEvent) |
+| `87aec5b` | Gate all decorative motion animations under `reduce_motion_mode` |
 
-- **Tone:** Balatro — chunky readable type, theatrical hierarchy,
+`reduce_motion_mode` now gates: score pulse, score floater, streak flourish
-  satisfying micro-interactions.
+(hud_plugin), card-shake on rejected move, foundation completion flourish
-- **Palette:** Midnight Purple base + Balatro yellow primary + warm
+(feedback_anim_plugin). Pattern: gate at the trigger/start system, never at
-  magenta secondary.
+the tick system — if the component isn't inserted, the tick path never runs.
-- See `~/.claude/projects/-home-manage-Rusty-Solitare/memory/project_ux_overhaul_2026-04.md`
-  (machine-local).
 
-### Canonical remote
+### v0.35.1 — Leaderboard bug fixes (2026-05-18)
 
-`github.com/funman300/Rusty_Solitaire` is the canonical repo.
+| Commit | Summary |
-Always push there.
+|--------|---------|
+| `8f86d66` | Fix three leaderboard bugs: wrong toast type, stale label, name not synced |
 
-## v0.18.0 (drafted 2026-05-06, not yet tagged)
+Three bugs fixed:
 
-| Area | Commit | What landed |
+1. **Wrong toast type on error** — `poll_opt_in_task` / `poll_opt_out_task` error
-|---|---|---|
+   branches now fire `WarningToastEvent` instead of `InfoToastEvent`.
-| Restore prompt | `3c7a0eb` + `f863d85` | Welcome-back modal on launch when an in-progress save exists; save preserved across exits while the prompt is unanswered. |
+
-| Async winnable-only seeds | `d489e7a` | `PendingNewGameSeed` resource + `poll_pending_new_game_seed` running `.before(GameMutation)`. Fixes the worst-case 6 s UI stall on a New Game click. Cancel-on-replace contract covered by tests. |
+2. **Display name not pushed to server on change** — `Settings` gains
-| Won-before HUD chip | `bdac754` | Reads `ReplayHistoryResource`; lights `✓ Won before` on tier-2 row when current `(seed, draw_mode, mode)` is in history. |
+   `leaderboard_opted_in: bool` (serde-defaulted `false`). Set `true`/`false` when
-| Copy share link | `540869c` | `arboard` clipboard + new Stats button + `SyncProvider::push_replay` returning the share URL. In-memory only; per-session sharing. |
+   opt-in/out tasks succeed and persisted to `settings.json`. `handle_display_name_confirm`
-| MSSC Home picker | `ae40a1d`, `b73d246`, `9fe650f`, `40d6e0a`, `c30b04e`, `d065d49` | Header stats strip (clickable → Profile), draw-mode chips, per-mode score/streak chips, Today's Event callout on Daily, picture-tile 2-up grid with FiraMono-covered glyphs (♣ ◆ ○ ▲ →). |
+   now spawns an `opt_in_leaderboard` task when already opted in — the server's upsert
-| Auto-show Home | `dd63261`, `b7c3a49`, `c497c31` | Auto-shows after splash; gated on Restore prompt; freezes timers (elapsed + Time Attack) while up. |
+   endpoint updates only `display_name` without re-opting-in.
-| `N` opens real modal | `93660c2` | Removes the "Press N again" double-tap; routes through `ConfirmNewGameScreen`. `Shift+N` retains the bypass. |
+
-| Win Summary keyboard | `17e0737` | Enter dismisses + starts a fresh deal. |
+3. **"Public name" label stale after name change** — `LeaderboardPublicNameText` marker
-| Esc-on-modal fixes | `08b006f`, `d48b948`, `9aa0dd2` | Esc no longer opens Pause underneath the modal it just closed; Home maps Esc to Cancel; Restore maps Esc to Continue; topmost-modal-wins when Profile stacks on Home. |
+   component added to the label node. `update_leaderboard_public_name_label` system
-| Layout fixes | `a4bc063`, `cc63532` | Settings rows full-width with label-spacer-cluster; popover rows excluded from action-bar auto-fade. |
+   rewrites the text each frame the panel is open; O(0) cost when panel is closed.
-| Empty-state copy | `56e2e6f` | Leaderboard / Achievements onboarding hints; volume hotkeys emit toast feedback. |
+
-| Test prune | `a49a340` | −43 low-value tests; future briefs request behaviour contracts only. |
+5 new regression tests cover all three bugs.
-| Docs unified-3.0 | `f2f30c8` | Adopts CLAUDE.md / CLAUDE_SPEC.md / CLAUDE_WORKFLOW.md / CLAUDE_PROMPT_PACK.md; trims duplicated rule passages. |
+
+---
 
 ## Open punch list
 
-### Carried forward from v0.17.0
+### 1. CHANGELOG documentation debt
 
-- **Solver-on-`AsyncComputeTaskPool` for the H-key hint** —
+CHANGELOG.md currently ends at v0.33.0. Entries for v0.34.0, v0.35.0, and v0.35.1
-  remaining synchronous solver hot path. The seed-selection port
+are missing. Low priority (git log is authoritative) but worth closing before the
-  in `d489e7a` is the template: `PendingHintTask` resource, polling
+next release.
-  system running `.before(GameMutation)`, cancel-on-replace, fall
-  back to the heuristic on inconclusive. Diff should stay scoped
-  to `input_plugin.rs` plus a small `pending_hint.rs`.
-- **Desktop packaging** per `ARCHITECTURE.md §17`. Arch PKGBUILD
-  exists in `/home/manage/solitaire-quest-pkgbuild/` (separate
-  repo). Pending: app icon, macOS `.icns` + notarisation cert,
-  Windows `.ico` + Authenticode cert, AppImage recipe.
 
-### New this round
+### 2. Android APK launch verification (Option A)
 
-- **Persistent share link.** `LastSharedReplayUrl` is in-memory only
+Physical device test: install the latest APK on a real Android device (not AVD),
-  — the player must share within the session of the win. If
+confirm:
-  cross-session sharing turns into a real ask, persist alongside
+- App launches without crash
-  the rolling replay history.
+- Safe area insets arrive and shift HUD correctly after ~3 frames
-- **Per-mode artwork.** Picture tiles use Unicode glyphs as
+- All modal Done buttons are above the gesture bar
-  placeholders chosen from FiraMono's actual coverage. When real
+- Drag-and-drop works on all pile types
-  artwork lands, swap each tile's `Text` node for an `Image` node
+- Leaderboard panel opens and the "Public name" label updates correctly after
-  — tile layout, focus order, click handling, and chip rendering
+  using "Set Name"
-  are unchanged.
 
-### Process notes (from this round)
+This has never been gated in CI. AVD `adb shell input tap` doesn't deliver real
+touch events, so physical-device smoke testing is the only gate.
 
-- **Test inflation pattern (resolved this round):** older agent
+### 3. Matomo analytics wiring
-  briefs reflexively asked for ≥3 tests per feature, producing 43
-  low-value coverage entries on stdlib/serde-derive mechanics. Going
-  forward, ask for tests that pin behaviour contracts or
-  regressions on real bugs only. See
-  `feedback_test_discipline.md` in auto-memory.
-- **Solver async refactor sequencing (worked this round):** rather
-  than porting the whole solver-on-main-thread surface in one PR
-  (the rollback case from before v0.17.0), the
-  `PendingNewGameSeed` work shipped one well-bounded path with two
-  tests covering the happy path and cancel-on-replace. The hint
-  port should follow the same shape.
 
-## Resume prompt
+`Settings` has `analytics_enabled: bool` and `matomo_url: Option<String>` but no
+engine code consumes them — the analytics toggle in Settings is a no-op. If
+analytics are ever needed, the Matomo HTTP Tracking API client needs to be written
+and wired to `GameStateResource` events.
 
-```
+---
-You are a senior Rust + Bevy developer working on Solitaire Quest.
-Working directory: <Rusty_Solitaire clone path on this machine>.
-Branch: master. Direction is OPEN — v0.18.0 has been drafted but
-not tagged: 24 commits past v0.17.0 cover the launch-experience
-round, MSSC Home picker, async winnable-only seeds, Won-before
-HUD, Copy share link, N-key flow rework, Esc-layering fixes, and
-the unified-3.0 Claude rule set.
 
-State: HEAD at v0.17.0-24-gc497c31. Working tree clean.
+## Architectural notes for next session
-CHANGELOG.md has the v0.18.0 entry slotted under [Unreleased].
 
-READ FIRST (in order, before doing anything):
+- **Reduce-motion pattern:** always gate in the `start_*` / `detect_*` system
-  1. SESSION_HANDOFF.md  — this file
+  (the trigger), not the `tick_*` system. If the component is never inserted, the
-  2. CHANGELOG.md        — v0.18.0 draft entry
+  tick path never runs. See `hud_plugin.rs::detect_score_change` and
-  3. CLAUDE.md           — unified-3.0 rule set
+  `feedback_anim_plugin.rs::start_shake_anim` for the canonical pattern.
-  4. CLAUDE_SPEC.md      — formal architecture spec
-  5. ARCHITECTURE.md     — crate responsibilities + data flow
-  6. ~/.claude/projects/<this-project>/memory/MEMORY.md
-                         — saved feedback / project context
-                           (machine-local; may be missing on a
-                           fresh machine)
 
-DECISION TO ASK THE PLAYER FIRST:
+- **Leaderboard server upsert:** `POST /api/leaderboard/opt-in` is idempotent —
-  A. Tag v0.18.0 — promote `[Unreleased]` to `[0.18.0]` (already
+  calling it when already opted in just updates `display_name`. Safe to call from
-     done in this session's draft), reverify build + clippy +
+  `handle_display_name_confirm` without tracking a separate "needs update" flag.
-     tests, tag, push. Mechanical close-out.
-  B. Solver-on-AsyncComputeTaskPool for the H-key hint, using the
-     `d489e7a` seed-selection port as template. Last synchronous
-     solver hot path. Smallest delta on the open punch list.
-  C. Desktop packaging — needs artwork + signing certs from the
-     player; can't be driven by the agent alone.
-  D. Persistent share link — store the URL alongside replay
-     history so cross-session sharing works.
 
-WORKFLOW NOTES:
+- **`Messages<T>` API (Bevy 0.18.1):** write with
-  - Commits use:
+  `resource_mut::<Messages<T>>().write(value)`; read in tests with
-      git -c user.name=funman300 -c user.email=root@vscode.infinity \
+  `msgs.get_cursor()` + `cursor.read(msgs).next()`.
-          commit -m "..."
-  - When attributing playtester feedback in commits/docs, use
-    "Quat" not "Rhys" (saved feedback memory).
-  - Sub-agents stage + verify only; orchestrator commits.
-  - Every commit must pass build / clippy / test before pushing.
-  - Push to GitHub (origin) — that is the canonical remote.
 
-OPEN AT THE START: ask which of A–D. Don't pick unilaterally.
+- **Test input-state pitfall:** `MinimalPlugins` has no input-tick system, so
-```
+  `ButtonInput::just_pressed` state persists across frames unless explicitly cleared
+  with `input.release(key); input.clear()` between updates.

argocd/application.yaml

@@ -0,0 +1,28 @@
+apiVersion: argoproj.io/v1alpha1
+kind: Application
+metadata:
+  name: solitaire-server
+  namespace: argocd
+spec:
+  project: default
+  source:
+    repoURL: https://git.aleshym.co/funman300/Ferrous-Solitaire.git
+    targetRevision: master
+    path: deploy
+  destination:
+    server: https://kubernetes.default.svc
+    namespace: solitaire
+  # Secrets are applied manually and must not be pruned by ArgoCD.
+  ignoreDifferences:
+    - group: ""
+      kind: Secret
+      name: matomo-secret
+      namespace: solitaire
+      jsonPointers:
+        - /data
+  syncPolicy:
+    automated:
+      prune: true
+      selfHeal: true
+    syncOptions:
+      - CreateNamespace=true