motovaultpro/.claude/skills/mvp-debugging-playbook/SKILL.md

---
name: mvp-debugging-playbook
description: Symptom-to-cause triage for MotoVaultPro. Load when debugging any of - numbers display wrong, .toFixed is not a function, values arrive as strings, dates off by one day, unexpected 403 (EMAIL_NOT_VERIFIED, TIER_REQUIRED, Unauthorized), stale data after create/update/delete, deleted record still shows, blank page on load, API calls never fire, bug only on mobile or only on desktop, route unexpectedly public or unprotected, VIN decode timeout or failure, OCR/receipt extraction returns empty fields, migration did not run, missing table or column, container unhealthy, staging deploy failed, health check failing, jest hangs or never exits. Gives the discriminating check and fix pattern for each known failure mode.
---

# MotoVaultPro Debugging Playbook

Known failure modes of this codebase, each with a discriminating check (an observation that separates this cause from lookalikes) and the sanctioned fix pattern. All file paths are repo-relative. All line numbers verified 2026-07-07 and may drift; the "Provenance and maintenance" section at the end has re-verification commands.

**When to use:** you have a symptom (bug report, failing staging deploy, weird API response) and need to know where to look and what the likely cause is.

**When NOT to use — route instead:**
- Investigation smells like a past battle (date bugs, numeric-string bugs, OCR engine behavior, auth races, "why is there no VIN cache") -> read `mvp-failure-archaeology` FIRST so you do not re-fight a settled war or reintroduce a reverted fix.
- You need LogQL recipes, Grafana access, health-check anatomy, or container debugging technique -> `mvp-diagnostics-and-logging`.
- You need to set up an environment or run tests at all -> `mvp-build-and-env`.
- You are deciding how to ship the fix (issue/branch/PR, review rules) -> `mvp-change-control`.
- You need rigorous root-cause methodology or benchmark discipline -> `mvp-proof-and-analysis-toolkit`.
- Deploy/rollback mechanics on staging or prod -> `mvp-run-and-operate`.

**Environment reality (2026-07-07):** development is done by AI sessions; end-to-end verification happens on STAGING via the PR deploy pipeline (every PR push builds images and redeploys staging). There is no fully working local dev loop. CI gates nothing beyond build + boot (canonical statement: `mvp-validation-and-qa` section 1) — do not assume "CI passed" means anything about correctness.

**Owner non-negotiables — never route around them while debugging:**
1. No destructive database operations without a fresh backup. This includes `make clean` (destroys volumes), `scripts/import-database.sh --drop-existing`, schema migrations on staging/prod, and the backend integration tests, which `DROP TABLE ... CASCADE` on the shared dev database (e.g. `backend/src/features/vehicles/tests/integration/vehicles.integration.test.ts:38`).
2. Never hand-edit files on the staging/prod servers — `rsync --delete` on every deploy reverts them. All server changes flow through the repo and workflows.

## First five minutes checklist

Before forming any theory, gather these observations (cross-ref `mvp-diagnostics-and-logging` for the full cookbook):

1. **Health endpoints.** `curl -s https://staging.motovaultpro.com/api/health | jq .` — must be `status: "healthy"` with a `features` array (20 features listed in `backend/src/app.ts`; the staging verify job requires a 13-feature subset, `.gitea/workflows/staging.yaml`).
2. **Container state** (on the server, `/opt/motovaultpro`): `docker compose -f docker-compose.yml -f docker-compose.staging.yml ps` — look for `unhealthy` or restart loops. Container names on staging carry a `-staging` suffix (`mvp-backend-staging`); dev/base names are `mvp-backend`, `mvp-ocr`, etc.
3. **Backend request logs in Grafana** (logs.staging.motovaultpro.com, RFC1918-only access):
   `{container="mvp-backend-staging"} | json | msg="Request processed" | status >= 400`
   Fields available: `level, requestId, method, path, status, duration`. `msg="Request processed"` is the request-log filter key.
4. **Errors across all containers:** `{container=~"mvp-.*"} | json | level="error"`.
5. **OCR container logs** if the symptom involves VIN/receipts/manuals: `docker logs --tail 200 mvp-ocr-staging` on staging (dev/base name is `mvp-ocr`; prod also uses the un-suffixed `mvp-ocr` — the blue-green overlay defines no OCR variant, it is a single shared instance there).
6. **Frontend errors: browser devtools console only.** Frontend logs never reach Loki.
7. **Did a deploy just happen?** Every PR push redeploys staging with brief full downtime; mid-deploy 502s are expected noise.

Then, before touching code: state a hypothesis that predicts a specific observation, and check the triage table below.

## Triage table

| # | Symptom | Likely cause | Jump to |
|---|---------|--------------|---------|
| 1 | Numbers wrong, `.toFixed is not a function`, values are strings | pg NUMERIC returned as string; mapper missed coercion | 1 |
| 2 | Dates off by one day | One of the three UTC traps reintroduced | 2 |
| 3 | Unexpected 403 | EMAIL_NOT_VERIFIED vs TIER_REQUIRED vs ownership | 3 |
| 4 | Stale data after mutation; deleted record still visible | Redis cache invalidation miss | 4 |
| 5 | Blank page; API calls never fire on load | Auth-gate race / bypassed apiClient | 5 |
| 6 | Bug only on mobile (or page missing on mobile) | 768px app fork; a registration-checklist step missed | 6 |
| 7 | Route unexpectedly public / unguarded | Missing per-route preHandler; tier guard fails open | 7 |
| 8 | VIN decode failure or timeout | Gemini path: timeout stack, event-loop blocking, SDK drift | 8 |
| 9 | OCR/receipt extraction returns empty fields | Silent Gemini fallback; Vision monthly cap; engine config | 9 |
| 10 | Migration did not run; missing table/column | Not in MIGRATION_ORDER, or image not rebuilt | 10 |
| 11 | Container unhealthy; staging deploy failed | Health-check anatomy; start_period; verify job | 11 |
| 12 | Jest hangs locally / frontend jest crashes | Open pg/redis handles; broken tdd-guard reporter config | 12 |

### 1. Numbers display wrong / `.toFixed` crashes / values are strings

**Likely cause.** The pg driver returns PostgreSQL `NUMERIC`/`DECIMAL` (type OID 1700) as JavaScript strings. The only global type-parser override in `backend/src/core/config/database.ts` is for `DATE` (OID 1082, line 12) — there is deliberately NO global numeric override. Every repository mapper must coerce numerics manually with `Number()`/`parseFloat()`. This has caused 5 historical incidents (#47, #49, #239, #241, #244); it is statistically the most likely bug when adding or changing any repository method.

**Discriminating check.** Hit the API and inspect the JSON type: a numeric field arriving as `"42.50"` (string) instead of `42.5` is this bug. Or in the failing frontend code, `typeof value === 'string'` where a number is expected.

```bash
grep -n "parseFloat\|Number(" backend/src/features/<feature>/data/<feature>.repository.ts
```

**Fix pattern.** Coerce in the repository mapper (`mapRow()` or equivalent), never in the frontend and never by returning raw rows. Beware the fuel-logs exception: `mapEnhancedRow` in `backend/src/features/fuel-logs/data/fuel-logs.repository.ts` deliberately returns coerced snake_case rows and the service's `toEnhancedResponse` does the camelCase mapping — do not "normalize" this without reading `mvp-failure-archaeology` (incident #47 -> #244 chain). Do NOT add a global OID 1700 parser as a drive-by fix; that is an architectural decision (see `mvp-architecture-contract`).

### 2. Dates off by one day

**Likely cause.** One of three settled UTC traps has been reintroduced:
(a) backend: removing/bypassing the DATE parser override `types.setTypeParser(1082, ...)` in `backend/src/core/config/database.ts:12` — pg would return DATE as a local-midnight `Date` object that shifts a day under `toISOString()`;
(b) frontend: `new Date("YYYY-MM-DD")` parses as UTC midnight, then `toLocaleDateString()` shifts a day back west of UTC;
(c) OCR/backend: `toISOString().split('T')[0]` on a Date built from a date-only value.

**Discriminating check.** Trace where the value first deviates: check the raw API response (should be a plain `"YYYY-MM-DD"` string for DATE columns). If the API string is right, the bug is frontend display; if wrong, backend/OCR.

**Fix pattern (the settled rule — do not innovate).** DATE columns flow as plain `YYYY-MM-DD` strings end to end; the full handling rules (dayjs display, lexicographic sort, when `new Date` is legitimate) are canonical in `mvp-vehicle-domain-reference` section 3. See `mvp-failure-archaeology` (four fixes in one day, 2026-03-23) before touching any date code.

### 3. Unexpected 403 responses

Three distinct producers — identify which by the response body:

| Body | Producer | Where |
|------|----------|-------|
| `code: "EMAIL_NOT_VERIFIED"` | Auth plugin email-verification guard | `backend/src/core/plugins/auth.plugin.ts` (~line 231); exempt route prefixes `/api/auth/`, `/api/onboarding/`, `/api/health`, `/health` (lines 18-23) |
| `error: "TIER_REQUIRED"` with `requiredTier`/`currentTier` | Tier gating (two parallel mechanisms) | `backend/src/core/plugins/tier-guard.plugin.ts` (~line 93) or `backend/src/core/middleware/require-tier.ts` (~line 50) |
| Generic 403, message containing "Unauthorized" | Ownership failure string-matched in the controller | e.g. `backend/src/features/fuel-logs/api/fuel-logs.controller.ts` — controllers catch and map `error.message.includes('not found')` -> 404, `includes('Unauthorized')` -> 403, else 500. There are no typed error classes. |

**Discriminating checks.**
- EMAIL_NOT_VERIFIED: does the user's Auth0 account show verified? Guard runs on every authenticated route not in the exempt list.
- TIER_REQUIRED: is the route tier-gated? (Current key catalog and limits: `mvp-config-and-secrets` section 3.) What is `user_profiles.subscription_tier`?
- Ownership: does the row's `user_id` match the caller's internal UUID? Note `request.userContext.userId` is the internal `user_profiles` UUID, NOT the Auth0 `sub`.

**Fix pattern.** For ownership bugs, check the service's ownership comparison and that the correct user UUID reached it. When adding error paths, match the existing string-matching contract exactly ("not found", "Unauthorized") or the controller will map your error to 500.

### 4. Stale data after mutation

**Likely cause.** Redis cache invalidation miss. Cache facts: keys prefixed `mvp:` (`backend/src/core/config/redis.ts:22`); fuel-logs caches per `{userId}:{unitSystem}` with TTL 300s (`fuel-logs.service.ts:18`); platform dropdown caches TTL 6h (`backend/src/features/platform/domain/platform-cache.service.ts`). Cache errors are swallowed (cacheService returns null on failure) — a broken Redis never 500s, it just serves stale or uncached.

**KNOWN LIVE BUG.** `deleteFuelLog` invalidates only the `imperial` cache keys, so a metric-preference user sees deleted fuel logs for up to 300s. If you are debugging "deleted log still shows" for a metric user, this is it — the full record (file:line evidence and status) is canonical in `mvp-launch-readiness` section 1, gap 4; file/fix the bug rather than hunting elsewhere.

**Discriminating check.** Does the stale window self-heal at the TTL (300s fuel-logs, 6h platform)? If yes, invalidation miss. Inspect keys directly:

```bash
docker exec mvp-redis redis-cli --scan --pattern 'mvp:fuel-logs:*'
```

**Fix pattern.** Invalidate BOTH unit systems (or `deletePattern`) on every mutation path; check create/update/delete all invalidate symmetrically.

### 5. Blank page / API calls never fire on load

**Likely cause.** Auth-gate race. All axios calls through the shared `apiClient` (`frontend/src/core/api/client.ts`) are queued until Auth0 init completes (`frontend/src/core/auth/auth-gate.ts`; `setAuthReady` flipped by `Auth0Provider`). Historical incidents: blank Stations page (2025-11), dashboard auth-gate (#45), mobile login IndexedDB/callback saga (#188/#190).

**Discriminating check.** Devtools Network tab: are the requests pending/queued (never sent) or sent and failing? Queued-forever means auth never initialized — check console for Auth0 errors. Sent-and-401 pre-auth means something bypassed `apiClient` (raw `axios`/`fetch` import).

**Fix pattern.** Always use `apiClient` from `core/api/client.ts` — never raw axios. Do not add data fetches that race Auth0 init. Also settled: URL-sync effects in `App.tsx` must skip `/callback`, `/signup`, `/verify-email` (child effects fire before parent effects; stripping `?code=&state=` breaks Auth0 login).

### 6. Mobile-only bugs / page missing on mobile

**Likely cause.** The app hard-forks at `window.innerWidth <= 768` plus a UA regex in `frontend/src/App.tsx` (~lines 360-398). Desktop renders react-router `<Routes>`; mobile renders a Zustand-driven screen switcher (`useNavigationStore().activeScreen`, NO react-router). A page can work perfectly on desktop and be entirely absent on mobile.

**Discriminating check.** Shrink the window below 768px (or use device emulation). Then walk the CANONICAL registration checklist in `mvp-architecture-contract` invariant 2.7 (7 steps: desktop route, `MobileScreen` union, both nav maps, lazy import, mobile render block, navigation entry point) and find the missing step.

**Fix pattern.** Complete every step of that checklist — a screen registered in the maps but missing its lazy import or a navigation entry point is silently unreachable. Note the breakpoint systems are NOT uniform: app fork = 768px, MUI component checks = `sm` (600) / `md` (900). Mobile+desktop is a hard project requirement — verify both on staging.

### 7. Route unexpectedly public or unguarded

**Likely cause.** Auth is per-route: every protected route must list `preHandler: [fastify.authenticate]` explicitly — there is NO global auth hook. Intentional exceptions exist (webhooks, signup, health, `/auth/verify`, feature-tiers config): the canonical list lives in the header comment of `.claude/skills/mvp-diagnostics-and-logging/scripts/check-route-auth.sh` — check a suspect route against it before "fixing" a deliberately public endpoint. Forgetting the preHandler ships an open route, and CI will not catch it.

**Compounding traps (all verified):**
- The tier guard FAILS OPEN on unknown feature keys: `canAccessFeature` in `backend/src/core/config/feature-tiers.ts` (~lines 57-61) returns `true` for unregistered keys. A typo in a `featureKey` silently ungates a plugin-guarded route.
- Two parallel tier mechanisms exist with different failure behavior — the middleware 500s on unknown keys, the plugin decorator fails open (mechanics canonical in `mvp-config-and-secrets` section 3).
- `backend/src/features/backup/api/backup.routes.ts` uses untyped `(fastify as any).requireAdmin` 16 times (from line 32); a misspelled guard there compiles clean and ships an unguarded admin endpoint. Do not copy that file as a route template.

**Discriminating check.** `curl` the route with no Authorization header — a 200 on a should-be-protected route confirms. Audit:

```bash
grep -L "authenticate" backend/src/features/*/api/*.routes.ts
grep -rn "featureKey" backend/src/features/*/api/*.routes.ts   # then match each key against FEATURE_TIERS
```

**Fix pattern.** Add the explicit preHandler; verify the featureKey exists in `FEATURE_TIERS`; prefer the typed `fastify.requireAdmin`/`fastify.requireTier` decorators.

### 8. VIN decode failures / timeouts

**The chain:** frontend `POST /vehicles/decode-vin` (axios timeout 120s, `frontend/src/features/vehicles/api/vehicles.api.ts:90`) -> `vehicles.controller.ts` (maps OCR 503/422 -> 502, timeout/abort -> 504) -> `backend/src/features/ocr/external/ocr-client.ts` (`OCR_TIMEOUT_MS = 120000`, line 9, hardcoded) -> Python OCR container `POST /decode/vin` -> Gemini with Google Search grounding.

**Likely causes, in order:**
1. **Timeout race:** frontend 120s == backend-client 120s with no headroom, and there is NO service-side timeout on the Gemini call itself. Search-grounded decodes have been observed >60s.
2. **Event-loop blocking:** `ocr/app/routers/decode.py` calls the synchronous `_gemini_engine.decode_vin(vin)` inside an `async def` handler — a slow call blocks the whole uvicorn event loop including `/health`. The OCR healthcheck (docker-compose.yml: interval 5s, timeout 5s, retries 3) can then mark the container unhealthy and Docker can restart it MID-REQUEST.
3. **SDK drift:** `google-genai>=1.0.0` is unpinned in `ocr/requirements.txt`; new config params have broken staging before (pydantic validation error from `AutomaticFunctionCallingConfig` — reverted; never re-add AFC config).

**Discriminating check.** `docker logs mvp-ocr-staging` (on staging; base/prod name `mvp-ocr`) around the failure time. Diagnostic raw-JSON logging exists: `gemini_engine.py` logs `"Gemini decoded VIN %s (confidence=...) raw=%s"` (~line 401) with the full raw Gemini response. A container restart in `docker ps` uptime plus a 504 upstream = the healthcheck-kill scenario. A pydantic ValidationError in logs = SDK drift.

**Fix pattern.** Do not "fix" by raising the frontend timeout again (already raised 30->60->120s; the fix is service-side). Settled: there is NO VIN decode cache by design (deleted after race/staleness bugs — see `mvp-failure-archaeology`); do not re-add one. Model year is computed deterministically from VIN positions 7/10, never trusted from the LLM.

### 9. OCR / receipt extraction returns empty results

**Likely cause.** In `ocr/app/extractors/maintenance_receipt_extractor.py` (~lines 129-133), any Gemini failure is caught and silently falls back to OCR-only with `gemini_fields = {}` — the user sees "no fields extracted" with no error. Also check:
- **Vision monthly cap:** `VISION_MONTHLY_LIMIT` is 1000 requests/month; compose sets `OCR_PRIMARY_ENGINE: google_vision`, `OCR_FALLBACK_ENGINE: paddleocr` (docker-compose.yml ~lines 201-206, overriding the code defaults in `ocr/app/config.py`). Cap exhaustion degrades to PaddleOCR quality.
- **Model config:** compose deploys `GEMINI_MODEL: gemini-3-flash-preview` (line 210) — a preview model; the code default is `gemini-2.5-flash`. Extraction-quality regressions can be model-side.
- Email-ingestion amplification: unconfident classification runs BOTH fuel and maintenance OCR endpoints per attachment, burning the Vision cap faster.

**Discriminating check.** `docker logs mvp-ocr-staging | grep -i "Gemini extraction failed"` (base/prod container name is `mvp-ocr`) — the fallback logs a warning with the exception. WIF/auth failures log "Gemini authentication failed". Verify effective engine config: `docker exec mvp-ocr-staging env | grep -E "OCR_|GEMINI|VISION"`.

**Fix pattern.** Fix the upstream Gemini/auth failure; do not paper over with confidence-threshold tweaks. The WIF credential chain (Auth0 M2M -> `google-wif-config.json` at `/run/secrets/`) is duplicated in `gemini_engine.py` AND `maintenance_receipt_extractor.py` `_get_client()` — auth fixes must be applied in both.

### 10. Migration did not run / missing table or column

**Likely cause.** Migrations are feature-owned SQL run in the hard-coded `MIGRATION_ORDER` array in `backend/src/_system/migrations/run-all.ts` (line 17). A new feature's `migrations/` directory is SILENTLY skipped unless the feature is appended to that array. Migrations run automatically on backend container start (`backend/Dockerfile:84`: `node dist/_system/migrations/run-all.js && npm start`), which means they are packaged into the image — a migration added to source requires an IMAGE REBUILD and redeploy to run on staging/prod.

**Discriminating check.**

```bash
grep -n "features/<your-feature>" backend/src/_system/migrations/run-all.ts   # is it in MIGRATION_ORDER?
docker exec mvp-postgres psql -U postgres -d motovaultpro -c "SELECT * FROM _migrations ORDER BY executed_at DESC LIMIT 20;"
docker logs mvp-backend 2>&1 | grep -i migrat
```

(Adjust container names/DB credentials per environment; on staging they carry `-staging`.)

**Fix pattern.** Append to `MIGRATION_ORDER` respecting dependencies (`update_updated_at_column()` is defined in `features/vehicles`, which must run first; `core/identity-migration` runs last). NON-NEGOTIABLE: schema migrations on staging/prod require a fresh backup first (`scripts/ci/maintenance-migrate.sh backup`, or `make db-backup`).

### 11. Container unhealthy / staging deploy failed

**Health-check anatomy (docker-compose.yml, verified):** backend has `start_period: 180s` (line 159) specifically because auto-migrations run on start — a backend "starting" for 2 minutes is normal, not a failure. OCR: interval 5s / timeout 5s / start_period 15s (and see symptom 8 for why OCR can flap under load). The `verify-staging` job waits up to 4 minutes (48x5s) for Docker health, then curls `https://staging.motovaultpro.com/api/health` and requires `status=healthy` plus a 13-feature required list (`.gitea/workflows/staging.yaml`, `REQUIRED_FEATURES`).

**Discriminating check, in order:**
1. Which job failed? Build failure = code/Dockerfile problem. Deploy failure = server-side (disk, secrets). Verify failure = app boot problem.
2. `docker inspect --format '{{json .State.Health}}' mvp-backend-staging | jq .` — see the actual failing probe output.
3. `docker logs mvp-backend-staging --tail 100` — migration errors are the most common boot killer.
4. Disk: `df -h /` on the staging runner — the 29G root fills with per-commit images; a full disk fails builds and deploys in confusing ways (`docker system df`; a daily prune cron exists out-of-band).
5. Missing secret trap: Docker bind-mounting a missing secret file creates a DIRECTORY; the workflows contain `rm -rf` cleanup for exactly this. An empty directory where a secret file should be breaks the consumer at read time.

**Fix pattern.** Fix in the repo and redeploy via the workflow. Never hand-edit on the server (non-negotiable; rsync --delete reverts it). Full deploy/rollback procedure: `mvp-run-and-operate`.

### 12. Jest hangs locally / frontend jest broken

**Backend:** `cd backend && npm test` runs tests and then never exits — pg pool and ioredis connect eagerly at module import (`backend/src/core/config/database.ts`, `redis.ts` — `new Redis(...)` with no `lazyConnect`) and `backend/jest.config.js` sets no `forceExit`. Run:

```bash
cd backend && npx jest --forceExit                # or: npm test -- --forceExit
```

Also remember: backend INTEGRATION tests `DROP TABLE ... CASCADE` on the database they point at — never aim them at a database you care about without a fresh backup (non-negotiable).

**Frontend:** `cd frontend && npm test` is broken on the host: `frontend/jest.config.ts` registers the `tdd-guard-jest` reporter (line 31) with a hardcoded `projectRoot: '/home/egullickson/motovaultpro'` (line 33) — a Linux path that does not exist on this macOS checkout. Discriminating check: the failure mentions tdd-guard or that path. A verified working fallback exists — `npx jest --reporters=default` — with its traps and the known-red baseline documented in `mvp-build-and-env` section 2 (the single home for frontend-jest mechanics). Note there is no in-container run either (nginx-only image, tests dockerignored); end-to-end verification is still staging (see `mvp-validation-and-qa`).

## Discriminating-experiment discipline

Cheap rules that prevent the historical "fix symptoms until root cause found" chains (the mobile-login saga took 9 commits; the Tesseract VIN saga took 12 in one day):

1. **Predict before you look.** Write the hypothesis as "if X is the cause, then I will observe exactly Y at Z" — then look. If you find yourself explaining an observation after the fact, it did not discriminate. Full protocol: `mvp-proof-and-analysis-toolkit`.
2. **One variable per experiment.** Especially on staging, where every PR push redeploys the whole stack: change one thing, push, observe. Two changes per push means an ambiguous result.
3. **Locate the first deviation, not the last symptom.** Trace the value/request through the chain (DB -> repository mapper -> service -> controller -> API JSON -> frontend) and find the FIRST point it is wrong. Most historical band-aids (frontend `Number()` wrappers, timeout bumps) patched the last symptom.
4. **Distrust green CI.** CI runs zero tests and zero lint; "CI passed" only means images built and staging booted. Evidence standards: `mvp-validation-and-qa`.
5. **Check the archaeology first.** If the bug involves dates, numeric strings, VIN caching, auth races, Stripe IDs, or OCR engines, someone already fought it. `mvp-failure-archaeology` lists the settled outcomes and the reverts you must not resurrect.

## Provenance and maintenance

Authored 2026-07-07 by direct repo inspection; discovery-report claims were independently re-verified against code. Line numbers drift — re-verify before relying on them:

| Volatile fact | Re-verification command |
|---------------|------------------------|
| DATE-only parser override (OID 1082), no NUMERIC override | `grep -n "setTypeParser" backend/src/core/config/database.ts` |
| deleteFuelLog imperial-only invalidation (live bug) | `grep -n "invalidateCaches" backend/src/features/fuel-logs/domain/fuel-logs.service.ts` |
| Cache prefix `mvp:`, fuel-logs TTL 300s, platform TTL 6h | `grep -n "prefix" backend/src/core/config/redis.ts; grep -n "cacheTTL" backend/src/features/fuel-logs/domain/fuel-logs.service.ts; grep -n "6 \* 3600" backend/src/features/platform/domain/platform-cache.service.ts` |
| EMAIL_NOT_VERIFIED guard + exempt routes | `grep -n "EMAIL_NOT_VERIFIED\|VERIFICATION_EXEMPT" backend/src/core/plugins/auth.plugin.ts` |
| Tier guard fails open on unknown keys | `grep -n -A3 "fail open" backend/src/core/config/feature-tiers.ts` |
| Controller string-matched error mapping | `grep -n "includes('not found')\|includes('Unauthorized')" backend/src/features/fuel-logs/api/fuel-logs.controller.ts` |
| Untyped requireAdmin in backup routes | `grep -c "(fastify as any).requireAdmin" backend/src/features/backup/api/backup.routes.ts` |
| 120s timeouts (frontend + backend OCR client) | `grep -n "OCR_TIMEOUT_MS" backend/src/features/ocr/external/ocr-client.ts; grep -n "timeout" frontend/src/features/vehicles/api/vehicles.api.ts` |
| Sync Gemini call in async decode handler | `grep -n "decode_vin(vin)" ocr/app/routers/decode.py` |
| Gemini raw-JSON diagnostic logging | `grep -n "raw=%s" ocr/app/engines/gemini_engine.py` |
| Silent empty-fields fallback | `grep -n -B1 "gemini_fields = {}" ocr/app/extractors/maintenance_receipt_extractor.py` |
| Compose OCR engine/model config | `grep -n "OCR_PRIMARY_ENGINE\|GEMINI_MODEL\|VISION_MONTHLY_LIMIT" docker-compose.yml` |
| MIGRATION_ORDER + migrate-on-start | `grep -n "MIGRATION_ORDER" backend/src/_system/migrations/run-all.ts; grep -n "run-all" backend/Dockerfile` |
| Backend start_period 180s; OCR healthcheck 5s/5s | `grep -n "start_period" docker-compose.yml` |
| 13-feature staging verify list | `grep -n "REQUIRED_FEATURES" .gitea/workflows/staging.yaml` |
| 768px fork + page-registration checklist (canonical: `mvp-architecture-contract` 2.7) | `grep -n "innerWidth <= 768" frontend/src/App.tsx; grep -n "routeToScreen\|screenToRoute" frontend/src/core/store/navigation.ts` |
| Auth-gate request queue | `grep -n "authReady\|queueRequest" frontend/src/core/api/client.ts` |
| Frontend jest hardcoded projectRoot | `grep -n "projectRoot" frontend/jest.config.ts` |
| Integration tests DROP TABLE CASCADE | `grep -rn "DROP TABLE" backend/src/features/*/tests/integration/` |