docs: correct CLAUDE.md CI claims and repoint to the mvp-* skill library

Root CLAUDE.md: state the actual CI pipeline (image builds + staging deploy
+ health checks; no tests, lint, or security scanning), replace root-level
npm commands with per-workspace equivalents, correct the OCR engine
description, rename Sprint Workflow to Issue Workflow (sprints unused), and
replace the retired agent-system references with the skill library entry
points. Remove emoji from Quality Standards per the project's own rule.
.claude/CLAUDE.md: rewrite as a pure index of the current .claude/ contents
with one row per mvp-* skill.

Co-Authored-By: Claude Fable 5 <[email protected]>

CLAUDE.md

@@ -25,12 +25,12 @@ Maintain a constructive approach. Your role is not to argue for the sake of argu
 | --------- | ---- | ------------ |
 | `backend/` | Fastify API server with feature capsules | Backend development |
 | `frontend/` | React/Vite SPA with MUI | Frontend development |
-| `ocr/` | Python OCR microservice (Tesseract) | OCR pipeline, receipt/VIN extraction |
+| `ocr/` | Python OCR microservice (PaddleOCR / Google Cloud Vision engines, Gemini for schedule/VIN extraction) | OCR pipeline, receipt/VIN extraction |
 | `docs/` | Project documentation hub | Architecture, APIs, testing |
 | `config/` | Configuration files (Traefik, logging stack) | Infrastructure setup |
 | `scripts/` | Utility scripts (backup, deploy, CI) | Automation tasks |
 | `.ai/` | AI context and workflow contracts | AI-assisted development |
-| `.claude/` | Claude Code agents and skills | Delegating to agents, using skills |
+| `.claude/` | Claude Code skill library and configuration | Using a skill, checking project conventions |
 | `.gitea/` | Gitea workflows and templates | CI/CD, issue templates |
 | `ansible/` | Ansible deployment playbooks | Server provisioning |
 | `certs/` | TLS certificates | SSL/TLS configuration |
@@ -46,10 +46,14 @@ make rebuild  # Rebuild containers
 
 ## Test
 
+Root `package.json` has no `scripts` block — `npm test` at repo root fails. Run per workspace:
+
 ```bash
-npm test             # Run all tests
-npm run lint         # Linting
-npm run type-check   # TypeScript validation
+cd backend && npm test && npm run lint && npm run type-check
+cd frontend && npm test && npm run lint && npm run type-check
+# lint and type-check across both workspaces without cd:
+make lint
+make type-check
 ```
 
 ---
@@ -104,35 +108,32 @@ All methods returning data to the API must use these mappers - never return raw
 ## Development Workflow (Local + CI/CD)
 
 ### Local Development
+Root `package.json` has no `scripts` block; install and run dev servers per workspace:
 ```bash
-npm install          # Install dependencies
-npm run dev          # Start dev server
-npm test             # Run tests
-npm run lint         # Linting
-npm run type-check   # TypeScript validation
+cd backend  && npm install && npm run dev
+cd frontend && npm install && npm run dev
 ```
+Test/lint/type-check commands: see the Test section above.
 
 ### CI/CD Pipeline (on PR)
-- Container builds and integration tests
-- Mobile/desktop viewport validation
-- Security scanning
+The Gitea pipeline (`.gitea/workflows/staging.yaml`) builds the backend, frontend, and ocr Docker images, deploys them to the shared staging environment, and health-checks the deployment (container health checks plus `/api/health`). It runs no tests, no lint, no type-check, and no security scan. Validation is entirely the author's responsibility before opening a PR — see `.claude/skills/mvp-validation-and-qa/SKILL.md` for the evidence bar and definition of done.
 
-**Flow**: Local dev -> Push to Gitea -> CI/CD runs -> PR review -> Merge
+**Flow**: Local dev -> author self-gates (lint/type-check/tests) -> Push to Gitea -> CI builds images and deploys/health-checks staging -> PR review -> Merge
 
 
 ## Quality Standards
 
 ### Automated Checks Are Mandatory
-**ALL hook issues are BLOCKING - EVERYTHING must be ✅ GREEN!**
+**ALL hook issues are BLOCKING - EVERYTHING must be GREEN!**
 - No errors. No formatting issues. No linting problems. Zero tolerance
 - These are not suggestions. Fix ALL issues before continuing
 
 ### Code Completion Criteria
 Our code is complete when:
-- ✅ All linters pass with zero issues
-- ✅ All tests pass  
-- ✅ Feature works end-to-end
-- ✅ Old code is deleted
+- All linters pass with zero issues
+- All tests pass
+- Feature works end-to-end
+- Old code is deleted
 
 ## AI Collaboration Strategy
 
@@ -165,15 +166,15 @@ Leverage subagents aggressively for better results:
 
 Canonical sources only - avoid duplication:
 - Architecture and metadata: `.ai/context.json`
-- Sprint workflow contract: `.ai/workflow-contract.json`
+- Issue workflow: `.claude/skills/mvp-change-control/SKILL.md`
 - Documentation hub: `docs/README.md`
 - Feature work: `backend/src/features/{feature}/README.md`
 - Platform architecture: `docs/PLATFORM-SERVICES.md`
 - Testing workflow: `docs/TESTING.md`
 
-## Sprint Workflow
+## Issue Workflow
 
-Issues are the source of truth. See `.ai/workflow-contract.json` for complete workflow.
+Issues are the source of truth; work flows directly from issues by priority (sprints and milestones are not used). Full workflow, quality-review taxonomy (RULE 0/1/2), and label discipline: `.claude/skills/mvp-change-control/SKILL.md`.
 
 ### Quick Reference
 - Every PR must link to at least one issue
@@ -183,7 +184,7 @@ Issues are the source of truth. See `.ai/workflow-contract.json` for complete wo
 - Commits: `{type}: {summary} (refs #{index})` (e.g., `feat: add fuel report (refs #42)`)
 
 ### Sub-Issue Decomposition
-Multi-file features (3+ files) must be broken into sub-issues for smaller AI context windows:
+Multi-file changes (3+ files) must be broken into sub-issues for smaller AI context windows:
 - **Sub-issue title**: `{type}: {summary} (#{parent_index})` -- parent index in title
 - **Sub-issue body**: First line `Relates to #{parent_index}`
 - **ONE branch** per parent issue only. Never branch per sub-issue.
@@ -201,24 +202,24 @@ Multi-file features (3+ files) must be broken into sub-issues for smaller AI con
 - **Feature Capsule Organization**: Application features are self-contained modules within the backend
 - **Single-Tenant**: All data belongs to a single user/tenant
 - **User-Scoped Data**: All application data isolated by user_id
-- **Local Dev + CI/CD**: Development locally, container testing in CI/CD pipeline
+- **Local Dev + CI/CD**: Development and testing locally; CI/CD builds images and health-checks the staging deploy (see CI/CD Pipeline section)
 - **Integrated Platform**: Platform capabilities integrated into main backend service
 
 ### Common AI Tasks
 See `Makefile` for authoritative commands and `docs/README.md` for navigation.
 
-## Agent System
+## Skill Library
 
-| Directory | Contents | When to Read |
-|-----------|----------|--------------|
-| `.claude/role-agents/` | Developer, TW, QR, Debugger | Delegating execution |
-| `.claude/role-agents/quality-reviewer.md` | RULE 0/1/2 definitions | Quality review |
-| `.claude/skills/planner/` | Planning workflow | Complex features (3+ files) |
-| `.claude/skills/problem-analysis/` | Problem decomposition | Uncertain approach |
-| `.claude/agents/` | Domain agents | Feature/Frontend/Platform work |
-| `.ai/workflow-contract.json` | Sprint process, skill integration | Issue workflow |
+Reusable domain knowledge lives in `.claude/skills/` as 16 `mvp-*` skills, one directory per topic. Each skill's `SKILL.md` frontmatter `description` states exactly when to load it — full index at `.claude/CLAUDE.md`. Key entry points:
 
-### Quality Rules (see quality-reviewer.md for full definitions)
+| Skill | Use for |
+|-------|---------|
+| `.claude/skills/mvp-change-control/SKILL.md` | Issue/branch/PR workflow, quality-review taxonomy (RULE 0/1/2) |
+| `.claude/skills/mvp-debugging-playbook/SKILL.md` | Triaging a live failure |
+| `.claude/skills/mvp-architecture-contract/SKILL.md` | System invariants (e.g. mobile/desktop screen registration) |
+| `.claude/skills/mvp-validation-and-qa/SKILL.md` | Definition of done, test evidence bar |
+
+### Quality Rules (see `mvp-change-control` for full definitions)
 - **RULE 0 (CRITICAL)**: Production reliability - unhandled errors, security, resource exhaustion
 - **RULE 1 (HIGH)**: Project standards - mobile+desktop, naming, patterns, CI/CD pass
 - **RULE 2 (SHOULD_FIX)**: Structural quality - god objects, duplication, dead code