feat: update docs for token efficient usage

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 |