feat: update docs for token efficient usage

.ai/CLAUDE.md

@@ -0,0 +1,11 @@
+# .ai/
+
+AI context and workflow configuration for Claude Code.
+
+## Files
+
+| File | What | When to read |
+| ---- | ---- | ------------ |
+| `context.json` | Architecture metadata, feature registry | Understanding system structure |
+| `workflow-contract.json` | Sprint workflow, issue lifecycle | Issue/PR workflow, labels |
+| `WORKFLOW-PROMPTS.md` | Workflow prompt templates | Workflow automation |

.claude/CLAUDE.md

@@ -1,4 +1,16 @@
-# .claude/ Index
+# .claude/
+
+## Subdirectories
+
+| Directory | What | When to read |
+| --------- | ---- | ------------ |
+| `role-agents/` | Developer, TW, QR, Debugger agents | Delegating execution |
+| `agents/` | Domain agents (Feature, Frontend, Platform, Quality) | Domain-specific work |
+| `skills/` | Reusable skills | Complex multi-step workflows |
+| `output-styles/` | Output formatting templates | Customizing agent output |
+| `tdd-guard/` | TDD enforcement utilities | Test-driven development |
+
+## Quick Reference
 
 | Path | What | When |
 |------|------|------|
@@ -10,5 +22,6 @@
 | `skills/codebase-analysis/` | Systematic investigation | Unfamiliar areas |
 | `skills/doc-sync/` | Documentation sync | After refactors |
 | `skills/incoherence/` | Detect doc/code drift | Periodic audits |
+| `skills/prompt-engineer/` | Prompt optimization | Improving AI prompts |
 | `agents/` | Domain agents (Feature, Frontend, Platform, Quality) | Domain-specific work |
 | `.ai/workflow-contract.json` | Sprint process, skill integration | Issue workflow |

.claude/agents/CLAUDE.md

@@ -0,0 +1,11 @@
+# agents/
+
+## Files
+
+| File | What | When to read |
+| ---- | ---- | ------------ |
+| `README.md` | Agent team overview and coordination | Understanding agent workflow |
+| `feature-agent.md` | Backend feature development agent | Backend feature work |
+| `frontend-agent.md` | React/mobile-first UI agent | Frontend component work |
+| `platform-agent.md` | Platform services agent | Platform microservice work |
+| `quality-agent.md` | Final validation agent | Pre-merge quality checks |

.claude/role-agents/CLAUDE.md

@@ -0,0 +1,10 @@
+# role-agents/
+
+## Files
+
+| File | What | When to read |
+| ---- | ---- | ------------ |
+| `developer.md` | Developer role agent | Code implementation tasks |
+| `technical-writer.md` | Technical writer agent | Documentation tasks |
+| `quality-reviewer.md` | Quality reviewer with RULE 0/1/2 | Code review, quality gates |
+| `debugger.md` | Debugging specialist agent | Bug investigation, troubleshooting |

.claude/skills/CLAUDE.md

@@ -0,0 +1,13 @@
+# skills/
+
+## Subdirectories
+
+| Directory | What | When to read |
+| --------- | ---- | ------------ |
+| `planner/` | Planning workflow with resource sync | Complex features (3+ files) |
+| `problem-analysis/` | Structured problem decomposition | Uncertain approach, debugging |
+| `decision-critic/` | Decision stress-testing | Architectural choices, tradeoffs |
+| `codebase-analysis/` | Systematic codebase investigation | Unfamiliar areas, audits |
+| `doc-sync/` | CLAUDE.md/README.md synchronization | After refactors, periodic audits |
+| `incoherence/` | Detect doc/code drift | Documentation inconsistencies |
+| `prompt-engineer/` | Prompt optimization techniques | Improving AI prompts |

.claude/skills/doc-sync/CLAUDE.md

@@ -0,0 +1,14 @@
+# skills/doc-sync/
+
+## Files
+
+| File | What | When to read |
+| ---- | ---- | ------------ |
+| `README.md` | Skill overview and usage examples | Understanding when to use doc-sync |
+| `SKILL.md` | Complete skill workflow definition | Executing the doc-sync skill |
+
+## Subdirectories
+
+| Directory | What | When to read |
+| --------- | ---- | ------------ |
+| `references/` | Trigger pattern examples | Writing good CLAUDE.md triggers |

.gitea/ISSUE_TEMPLATE/feature.yml

@@ -1,70 +0,0 @@
-name: "Feature"
-about: "New capability or enhancement"
-title: "[Feature]: "
-labels:
-  - "type/feature"
-  - "status/backlog"
-body:
-  - type: markdown
-    attributes:
-      value: |
-        Use this for a new feature or enhancement. Keep scope tight and include clear acceptance criteria.
-
-  - type: textarea
-    id: problem
-    attributes:
-      label: "Problem / user need"
-      description: "What problem are we solving, and for whom?"
-      placeholder: "As a user, I want..., so that..."
-    validations:
-      required: true
-
-  - type: textarea
-    id: solution
-    attributes:
-      label: "Proposed solution"
-      description: "Describe the expected behavior at a high level."
-      placeholder: "When the user does X, the system should..."
-    validations:
-      required: true
-
-  - type: textarea
-    id: non_goals
-    attributes:
-      label: "Non-goals / out of scope"
-      description: "What are we explicitly not doing in this feature?"
-      placeholder: "- Not doing...\n- Not doing..."
-    validations:
-      required: false
-
-  - type: textarea
-    id: acceptance
-    attributes:
-      label: "Acceptance criteria"
-      description: "Concrete checks for ‘done’. Prefer bullets and testable statements."
-      placeholder: |
-        - [ ] ...
-        - [ ] ...
-        - [ ] ...
-    validations:
-      required: true
-
-  - type: textarea
-    id: notes
-    attributes:
-      label: "Implementation notes (optional)"
-      description: "Links, APIs, file paths, edge cases."
-    validations:
-      required: false
-
-  - type: textarea
-    id: test_plan
-    attributes:
-      label: "Test plan"
-      description: "How will we verify? Include commands or steps."
-      placeholder: |
-        - Unit:
-        - Integration:
-        - Manual:
-    validations:
-      required: true

CLAUDE.md

@@ -1,3 +1,47 @@
+# MotoVaultPro
+
+Single-tenant vehicle management application with 5-container architecture (Traefik, Frontend, Backend, PostgreSQL, Redis).
+
+## Files
+
+| File | What | When to read |
+| ---- | ---- | ------------ |
+| `Makefile` | Build, test, deploy commands | Running any make command |
+| `docker-compose.yml` | Development container orchestration | Local development setup |
+| `package.json` | Root workspace dependencies | Dependency management |
+| `README.md` | Project overview | First-time setup |
+
+## Subdirectories
+
+| Directory | What | When to read |
+| --------- | ---- | ------------ |
+| `backend/` | Fastify API server with feature capsules | Backend development |
+| `frontend/` | React/Vite SPA with MUI | Frontend development |
+| `docs/` | Project documentation hub | Architecture, APIs, testing |
+| `config/` | Configuration files (Traefik, monitoring) | Infrastructure setup |
+| `scripts/` | Utility scripts (backup, deploy) | Automation tasks |
+| `.ai/` | AI context and workflow contracts | AI-assisted development |
+| `.claude/` | Claude Code agents and skills | Delegating to agents, using skills |
+| `.gitea/` | Gitea workflows and templates | CI/CD, issue templates |
+| `ansible/` | Ansible deployment playbooks | Server provisioning |
+
+## Build
+
+```bash
+make setup    # First-time setup (builds containers, runs migrations)
+make rebuild  # Rebuild containers after changes
+```
+
+## Test
+
+```bash
+npm test             # Run all tests
+npm run lint         # Linting
+npm run type-check   # TypeScript validation
+```
+
+---
+
 # Development Partnership Guidelines
 
 ## Core Development Principles

backend/CLAUDE.md

@@ -0,0 +1,18 @@
+# backend/
+
+## Files
+
+| File | What | When to read |
+| ---- | ---- | ------------ |
+| `README.md` | Backend quickstart and commands | Getting started with backend development |
+| `package.json` | Dependencies and npm scripts | Adding dependencies, understanding build |
+| `tsconfig.json` | TypeScript configuration | Compiler settings, path aliases |
+| `jest.config.ts` | Jest test configuration | Test setup, coverage settings |
+| `Dockerfile` | Container build definition | Docker builds, deployment |
+
+## Subdirectories
+
+| Directory | What | When to read |
+| --------- | ---- | ------------ |
+| `src/` | Application source code | Any backend development |
+| `scripts/` | Utility scripts | Database scripts, automation |

backend/src/CLAUDE.md

@@ -0,0 +1,18 @@
+# backend/src/
+
+## Files
+
+| File | What | When to read |
+| ---- | ---- | ------------ |
+| `app.ts` | Fastify application setup and routes | Route registration, middleware setup |
+| `index.ts` | Application entry point | Server startup, initialization |
+
+## Subdirectories
+
+| Directory | What | When to read |
+| --------- | ---- | ------------ |
+| `features/` | Feature capsules (self-contained modules) | Feature development, API endpoints |
+| `core/` | Shared infrastructure (auth, config, logging) | Cross-cutting concerns, plugins |
+| `_system/` | System utilities (migrations, CLI, schema) | Database migrations, schema generation |
+| `shared-minimal/` | Minimal shared utilities | Shared type utilities |
+| `scripts/` | Backend-specific scripts | Utility scripts |

backend/src/core/CLAUDE.md

@@ -0,0 +1,20 @@
+# backend/src/core/
+
+## Files
+
+| File | What | When to read |
+| ---- | ---- | ------------ |
+| `README.md` | Core module index with code examples | Understanding core infrastructure |
+
+## Subdirectories
+
+| Directory | What | When to read |
+| --------- | ---- | ------------ |
+| `auth/` | Authentication utilities | JWT handling, user context |
+| `config/` | Configuration loading (env, database, redis) | Environment setup, connection pools |
+| `logging/` | Winston structured logging | Log configuration, debugging |
+| `middleware/` | Fastify middleware | Request processing, user extraction |
+| `plugins/` | Fastify plugins (auth, error, logging) | Plugin registration, hooks |
+| `scheduler/` | Job scheduling infrastructure | Scheduled tasks, cron jobs |
+| `storage/` | Storage abstraction and adapters | File storage, S3/filesystem |
+| `user-preferences/` | User preferences data and migrations | User settings storage |

backend/src/features/CLAUDE.md

@@ -0,0 +1,22 @@
+# backend/src/features/
+
+Feature capsule directory. Each feature is 100% self-contained with api/, domain/, data/, migrations/, tests/.
+
+## Subdirectories
+
+| Directory | What | When to read |
+| --------- | ---- | ------------ |
+| `admin/` | Admin role management, catalog CRUD | Admin functionality, user oversight |
+| `auth/` | Authentication endpoints | Login, logout, session management |
+| `backup/` | Database backup and restore | Backup jobs, data export/import |
+| `documents/` | Document storage and management | File uploads, document handling |
+| `fuel-logs/` | Fuel consumption tracking | Fuel log CRUD, statistics |
+| `maintenance/` | Maintenance record management | Service records, reminders |
+| `notifications/` | Email and push notifications | Alert system, email templates |
+| `onboarding/` | User onboarding flow | First-time user setup |
+| `platform/` | Vehicle data and VIN decoding | Make/model lookup, VIN validation |
+| `stations/` | Gas station search and favorites | Google Maps integration, station data |
+| `user-export/` | User data export | GDPR compliance, data portability |
+| `user-preferences/` | User preference management | User settings API |
+| `user-profile/` | User profile management | Profile CRUD, avatar handling |
+| `vehicles/` | Vehicle management | Vehicle CRUD, fleet operations |

config/CLAUDE.md

@@ -0,0 +1,13 @@
+# config/
+
+Configuration files for the 5-container architecture.
+
+## Subdirectories
+
+| Directory | What | When to read |
+| --------- | ---- | ------------ |
+| `app/` | Application configuration | App-specific settings |
+| `deployment/` | Deployment configuration | Deploy scripts, environment configs |
+| `monitoring/` | Monitoring and alerts | Prometheus, alerting rules |
+| `shared/` | Shared configuration | Cross-service settings |
+| `traefik/` | Traefik reverse proxy config | Routing, SSL, middleware |

docs/CLAUDE.md

@@ -0,0 +1,28 @@
+# docs/
+
+## Files
+
+| File | What | When to read |
+| ---- | ---- | ------------ |
+| `README.md` | Documentation hub and navigation | Starting point for any docs |
+| `PLATFORM-SERVICES.md` | 5-container architecture overview | Understanding system topology |
+| `ARCHITECTURE-OVERVIEW.md` | Detailed architecture documentation | Deep dive into system design |
+| `DATABASE-SCHEMA.md` | Database table definitions | Schema changes, data modeling |
+| `DATABASE-MIGRATION.md` | Migration procedures | Running or writing migrations |
+| `VEHICLES-API.md` | Vehicles API specification | Vehicle-related API work |
+| `ADMIN.md` | Admin feature documentation | Admin role management, catalog CRUD |
+| `TESTING.md` | Testing strategy and commands | Writing or running tests |
+| `E2E-TESTING.md` | End-to-end testing guide | Cypress E2E test setup |
+| `SECURITY.md` | Security guidelines | Security considerations |
+| `CICD-DEPLOY.md` | CI/CD and deployment | Pipeline configuration, deployments |
+| `BUILD-SERVER-SETUP.md` | Build server setup | Infrastructure setup |
+| `AUDIT.md` | Audit documentation | Security audits, compliance |
+| `MVP-COLOR-SCHEME.md` | Color scheme reference | UI styling decisions |
+| `UX-DEBUGGING.md` | UX debugging techniques | Debugging UI issues |
+| `PROMPTS.md` | AI prompt templates | AI-assisted development |
+
+## Subdirectories
+
+| Directory | What | When to read |
+| --------- | ---- | ------------ |
+| `changes/` | Change logs and migration notes | Understanding historical changes |

frontend/CLAUDE.md

@@ -0,0 +1,24 @@
+# frontend/
+
+## Files
+
+| File | What | When to read |
+| ---- | ---- | ------------ |
+| `README.md` | Frontend quickstart and patterns | Getting started with frontend development |
+| `package.json` | Dependencies and npm scripts | Adding dependencies, understanding build |
+| `tsconfig.json` | TypeScript configuration | Compiler settings, path aliases |
+| `vite.config.ts` | Vite build configuration | Build optimization, plugins |
+| `jest.config.ts` | Jest test configuration | Test setup |
+| `tailwind.config.js` | Tailwind CSS configuration | Styling, theme customization |
+| `Dockerfile` | Container build definition | Docker builds, deployment |
+
+## Subdirectories
+
+| Directory | What | When to read |
+| --------- | ---- | ------------ |
+| `src/` | Application source code | Any frontend development |
+| `public/` | Static assets (images, docs) | Adding static files |
+| `cypress/` | E2E test definitions | End-to-end testing |
+| `docs/` | Frontend-specific documentation | Frontend patterns, guidelines |
+| `test/` | Test utilities and mocks | Test setup, mock data |
+| `scripts/` | Frontend utility scripts | Automation scripts |

frontend/src/CLAUDE.md

@@ -0,0 +1,20 @@
+# frontend/src/
+
+## Files
+
+| File | What | When to read |
+| ---- | ---- | ------------ |
+| `App.tsx` | Root component with routing | Route configuration, layout structure |
+| `main.tsx` | Application entry point | Provider setup, initialization |
+| `index.css` | Global styles | Base styling, CSS imports |
+| `vite-env.d.ts` | Vite type definitions | TypeScript environment types |
+
+## Subdirectories
+
+| Directory | What | When to read |
+| --------- | ---- | ------------ |
+| `features/` | Feature modules (pages, components, hooks) | Feature development |
+| `core/` | Shared infrastructure (auth, api, store) | Cross-cutting concerns |
+| `components/` | Root-level shared components | App-wide UI components |
+| `pages/` | Page-level components | Page structure, routing targets |
+| `shared-minimal/` | Minimal shared UI (skeletons, theme) | Reusable UI primitives |

frontend/src/core/CLAUDE.md

@@ -0,0 +1,17 @@
+# frontend/src/core/
+
+## Subdirectories
+
+| Directory | What | When to read |
+| --------- | ---- | ------------ |
+| `api/` | API client and request handling | HTTP calls, error handling |
+| `auth/` | Auth0 provider and auth hooks | Authentication setup, user context |
+| `config/` | Runtime configuration | Environment-specific settings |
+| `debug/` | Debug utilities | Development helpers |
+| `error-boundaries/` | React error boundaries | Error handling UI |
+| `hooks/` | Shared React hooks | Reusable hook patterns |
+| `query/` | React Query configuration | Server state management |
+| `store/` | Zustand state management | Client state, global stores |
+| `sync/` | Data synchronization | Offline support, sync logic |
+| `units/` | Unit conversion utilities | Measurement formatting |
+| `utils/` | General utilities | Helper functions |

frontend/src/features/CLAUDE.md

@@ -0,0 +1,19 @@
+# frontend/src/features/
+
+Feature module directory. Each feature contains pages/, components/, hooks/, api/, types/.
+
+## Subdirectories
+
+| Directory | What | When to read |
+| --------- | ---- | ------------ |
+| `admin/` | Admin panel and catalog management | Admin UI, user management |
+| `auth/` | Authentication pages and components | Login, logout, auth flows |
+| `dashboard/` | Dashboard and fleet overview | Home page, summary widgets |
+| `documents/` | Document management UI | File upload, document viewer |
+| `fuel-logs/` | Fuel log tracking UI | Fuel entry forms, statistics |
+| `maintenance/` | Maintenance record UI | Service tracking, reminders |
+| `notifications/` | Notification display | Alert UI, notification center |
+| `onboarding/` | Onboarding wizard | First-time user experience |
+| `settings/` | User settings pages | Preferences, account settings |
+| `stations/` | Gas station finder UI | Station search, favorites, map |
+| `vehicles/` | Vehicle management UI | Vehicle list, details, forms |

scripts/CLAUDE.md

@@ -0,0 +1,17 @@
+# scripts/
+
+## Files
+
+| File | What | When to read |
+| ---- | ---- | ------------ |
+| `config-validator.sh` | Validate configuration files | Pre-deploy validation |
+| `export-database.sh` | Export database to backup | Database backup operations |
+| `import-database.sh` | Import database from backup | Database restore operations |
+| `inject-secrets.sh` | Inject secrets into config | Secret management |
+| `rollback.sh` | Rollback deployment | Emergency rollback procedures |
+
+## Subdirectories
+
+| Directory | What | When to read |
+| --------- | ---- | ------------ |
+| `ci/` | CI/CD scripts | Pipeline automation, build scripts |