ragarciaruben 1.20.7

package/.planning/PROJECT.md

@@ -0,0 +1,61 @@
+# [Project Name]
+
+## What This Is
+
+[Current accurate description — 2-3 sentences. What does this product do and who is it for?
+Update whenever the reality of the product drifts from this description.]
+
+## Core Value
+
+[The ONE thing that matters most. If everything else fails, this must work.
+One sentence that drives prioritization when tradeoffs arise.]
+
+## Requirements
+
+### Validated
+
+<!-- Shipped and confirmed valuable. Move items here from Active once validated in production. -->
+
+*(None yet — ship to validate)*
+
+### Active
+
+<!-- Current scope. These are what we are building toward right now. -->
+
+- [ ] [Requirement 1]
+- [ ] [Requirement 2]
+- [ ] [Requirement 3]
+
+### Out of Scope
+
+<!-- Explicit boundaries. Include reasoning to prevent re-adding. -->
+
+- [Exclusion 1] — [why excluded]
+- [Exclusion 2] — [why excluded]
+
+## Context
+
+[Background information that informs implementation:
+- Technical environment or ecosystem
+- Relevant prior work or existing architecture decisions
+- Known constraints inherited from existing systems
+- User research or feedback themes
+- Known issues to address]
+
+## Constraints
+
+- **[Type]**: [What] — [Why]
+- **[Type]**: [What] — [Why]
+
+*Common types: Tech Stack, Timeline, Budget, Dependencies, Compatibility, Performance, Security, Compliance*
+
+## Key Decisions
+
+<!-- Decisions that constrain future work. Add throughout project lifecycle. -->
+
+| Decision | Rationale | Outcome |
+|----------|-----------|---------|
+| [Choice] | [Why] | [✓ Good / ⚠️ Revisit / — Pending] |
+
+---
+*Last updated: [date] after [trigger]*

package/.planning/REQUIREMENTS.md

@@ -0,0 +1,70 @@
+# Requirements: [Project Name]
+
+**Defined:** [date]
+**Core Value:** [from PROJECT.md — one sentence]
+
+---
+
+## v1 Requirements
+
+Requirements for initial release. Each has a unique ID and maps to a roadmap phase.
+
+### [Category 1 — e.g., Authentication]
+
+- [ ] **AUTH-01**: [Description of what the user can do]
+- [ ] **AUTH-02**: [Description]
+- [ ] **AUTH-03**: [Description]
+
+### [Category 2 — e.g., Core Feature]
+
+- [ ] **CORE-01**: [Description]
+- [ ] **CORE-02**: [Description]
+- [ ] **CORE-03**: [Description]
+
+### [Category 3]
+
+- [ ] **[CAT]-01**: [Description]
+- [ ] **[CAT]-02**: [Description]
+
+---
+
+## v2 Requirements
+
+Deferred to future release. Tracked here to prevent scope creep contaminating v1.
+
+### [Category]
+
+- **[CAT]-01**: [Description]
+- **[CAT]-02**: [Description]
+
+---
+
+## Out of Scope
+
+Explicitly excluded. Documented to prevent re-adding.
+
+| Feature | Reason |
+|---------|--------|
+| [Feature] | [Why excluded] |
+| [Feature] | [Why excluded] |
+
+---
+
+## Traceability
+
+Which phases cover which requirements. Updated during roadmap creation.
+
+| Requirement ID | Description (brief) | Phase | Status |
+|----------------|---------------------|-------|--------|
+| AUTH-01 | [Brief] | Phase 1 | Pending |
+| AUTH-02 | [Brief] | Phase 1 | Pending |
+| CORE-01 | [Brief] | Phase 2 | Pending |
+
+**Coverage:**
+- v1 requirements: [X] total
+- Mapped to phases: [Y]
+- Unmapped (need phase assignment): [Z] ⚠️
+
+---
+*Requirements defined: [date]*
+*Last updated: [date] after [trigger]*

package/.planning/ROADMAP.md

@@ -0,0 +1,75 @@
+# Roadmap: [Project Name]
+
+## Overview
+
+[One paragraph describing the development journey from current state to v1 delivery. Mention the key phases and what each delivers.]
+
+---
+
+## Phase List
+
+- [ ] **Phase 1: [Name]** — [One-line description of what this delivers]
+- [ ] **Phase 2: [Name]** — [One-line description]
+- [ ] **Phase 3: [Name]** — [One-line description]
+- [ ] **Phase 4: [Name]** — [One-line description]
+
+*Integer phases = planned milestone work. Decimal phases (e.g., 2.1) = urgent insertions between planned phases.*
+
+---
+
+## Phase Details
+
+### Phase 1: [Name]
+
+**Goal**: [What this phase delivers — user-observable outcome]
+**Depends on**: Nothing (first phase)
+**Requirements covered**: [AUTH-01, AUTH-02, CORE-01]
+**Success Criteria** (what must be TRUE when done):
+  1. [Observable behavior or test result]
+  2. [Observable behavior or test result]
+  3. [Observable behavior or test result]
+
+Plans:
+- [ ] 01-01: [Brief description of first plan]
+- [ ] 01-02: [Brief description of second plan]
+- [ ] 01-03: [Brief description of third plan]
+
+---
+
+### Phase 2: [Name]
+
+**Goal**: [What this phase delivers]
+**Depends on**: Phase 1
+**Requirements covered**: [CORE-02, CORE-03]
+**Success Criteria** (what must be TRUE when done):
+  1. [Observable behavior]
+  2. [Observable behavior]
+
+Plans:
+- [ ] 02-01: [Brief description]
+- [ ] 02-02: [Brief description]
+
+---
+
+### Phase 3: [Name]
+
+**Goal**: [What this phase delivers]
+**Depends on**: Phase 2
+**Requirements covered**: [REQ-XX, REQ-XX]
+**Success Criteria** (what must be TRUE when done):
+  1. [Observable behavior]
+  2. [Observable behavior]
+
+Plans:
+- [ ] 03-01: [Brief description]
+- [ ] 03-02: [Brief description]
+
+---
+
+## Completed Phases
+
+*(Move phases here with completion date when done)*
+
+---
+*Roadmap created: [date]*
+*Last updated: [date] after [trigger]*

package/.planning/STATE.md

@@ -0,0 +1,75 @@
+# Project State
+
+<!-- This is the living memory of the project. Keep it under 100 lines.
+     Update after every session and after each plan completion. -->
+
+## Project Reference
+
+See: `.planning/PROJECT.md` (updated [date])
+
+**Core value:** [One-liner from PROJECT.md Core Value section]
+**Current focus:** [Current phase name and number]
+
+---
+
+## Current Position
+
+```
+Phase:        [X] of [Y] — [Phase Name]
+Plan:         [A] of [B] in current phase
+Status:       [Ready to plan / Planning / Ready to execute / In progress / Phase complete]
+Last activity: [YYYY-MM-DD] — [What happened]
+
+Progress: [░░░░░░░░░░] 0%
+```
+
+---
+
+## Performance Metrics
+
+**Velocity:**
+- Total plans completed: [N]
+- Total execution time: [X.X] hours
+
+**By Phase:**
+
+| Phase | Plans | Time | Avg/Plan |
+|-------|-------|------|----------|
+| — | — | — | — |
+
+---
+
+## Accumulated Context
+
+### Key Decisions (recent)
+
+<!-- Detailed decisions live in PROJECT.md Key Decisions table.
+     List here only decisions affecting current/next work. -->
+
+- [Phase X]: [Decision summary and its implication]
+
+### Blockers / Concerns
+
+<!-- Issues that affect future work -->
+
+*(None)*
+
+### Pending Ideas
+
+<!-- Captured during sessions but deferred -->
+
+*(None)*
+
+---
+
+## Session Continuity
+
+```
+Last session:  [YYYY-MM-DD HH:MM]
+Stopped at:    [Description of last completed action]
+Resume file:   [.planning/continue-here.md OR None]
+Next action:   [Exact next step to take]
+```
+
+---
+*Updated: [date] after [trigger]*

package/.planning/codebase/ARCHITECTURE.md

@@ -0,0 +1,76 @@
+# Architecture
+
+<!-- Generated by /map-codebase. Describes conceptual code organization.
+     Update when architectural patterns change significantly.
+     Consumed by: plan-phase (API/backend/refactor work), execute-phase (layer boundaries). -->
+
+## System Overview
+
+[2-3 sentences describing what this system does architecturally and how its major parts relate.]
+
+## Architectural Style
+
+[e.g., Layered monolith / Microservices / Event-driven / Hexagonal / MVC / CQRS]
+
+**Why:** [Rationale for this choice]
+
+## Layers / Components
+
+```
+[Diagram or list of layers, e.g.:]
+
+┌─────────────────────────────────┐
+│  Presentation Layer             │  src/routes/, src/controllers/
+│  (HTTP handlers, input parsing) │
+├─────────────────────────────────┤
+│  Business Logic Layer           │  src/services/
+│  (Domain logic, orchestration)  │
+├─────────────────────────────────┤
+│  Data Access Layer              │  src/repositories/, src/models/
+│  (DB queries, ORM, caching)     │
+├─────────────────────────────────┤
+│  Infrastructure Layer           │  src/config/, src/middleware/
+│  (Auth, logging, external SDKs) │
+└─────────────────────────────────┘
+```
+
+## Data Flow
+
+[How a typical request flows through the system — trace 1-2 key paths]
+
+**Example: User creates resource**
+```
+POST /api/resource
+  → src/middleware/auth.ts (validate JWT)
+  → src/routes/resource.ts (parse + validate body)
+  → src/controllers/resource.controller.ts (orchestrate)
+  → src/services/resource.service.ts (business logic)
+  → src/repositories/resource.repository.ts (DB query)
+  → src/models/resource.model.ts (ORM entity)
+```
+
+## Key Abstractions
+
+| Abstraction | File(s) | Purpose |
+|-------------|---------|---------|
+| [Name] | `src/[path]` | [What it does] |
+| [Name] | `src/[path]` | [What it does] |
+
+## Entry Points
+
+| Entry Point | File | Purpose |
+|-------------|------|---------|
+| HTTP server | `src/main.ts` | [Description] |
+| Worker / Queue | `src/worker.ts` | [Description] |
+| CLI | `src/cli/index.ts` | [Description] |
+
+## Cross-Cutting Concerns
+
+- **Error handling:** [How errors propagate — e.g., "All service errors are Error subclasses, caught by `src/middleware/error.ts`"]
+- **Logging:** [Library and pattern — e.g., "winston, structured JSON, request ID propagated via AsyncLocalStorage"]
+- **Authentication:** [Strategy — e.g., "JWT validated in `src/middleware/auth.ts`, user attached to `req.user`"]
+- **Validation:** [Where and how — e.g., "Zod schemas in `src/schemas/`, validated at route layer"]
+
+---
+*Generated: [date]*
+*Last updated: [date] after [trigger]*

package/.planning/codebase/CONCERNS.md

@@ -0,0 +1,102 @@
+# Concerns & Technical Debt
+
+<!-- Generated by /map-codebase. Documents known issues, tech debt, fragile areas, and risks.
+     Consumed by: plan-phase (refactor/cleanup phases), execute-phase (when touching flagged areas).
+     Update as new issues are found or old ones are resolved. -->
+
+## Health Summary
+
+| Severity | Count | Trend |
+|----------|-------|-------|
+| 🔴 Critical (blocks features / causes bugs) | [N] | [↑ ↓ →] |
+| 🟡 High (significant friction / risk) | [N] | [↑ ↓ →] |
+| 🟢 Medium (nice-to-fix, low urgency) | [N] | [↑ ↓ →] |
+
+*Last assessed: [date]*
+
+---
+
+## 🔴 Critical Issues
+
+### [Issue Name]
+
+- **Location:** `src/path/to/file.ts` (line ~[N])
+- **Impact:** [What breaks or can break — be specific]
+- **Root cause:** [Why this exists]
+- **Fix approach:** [Concrete steps to fix]
+- **Blocking:** [What feature or fix this blocks, if any]
+
+---
+
+## 🟡 High Priority Debt
+
+### [Issue Name]
+
+- **Location:** `src/[path]`
+- **Impact:** [Developer friction / performance / security risk / etc.]
+- **Root cause:** [Why it happened]
+- **Fix approach:** [How to fix]
+- **Effort:** [Small (< 1 day) / Medium (1-3 days) / Large (> 3 days)]
+
+### [Another Issue]
+
+- **Location:** `src/[path]`
+- **Impact:** [Description]
+- **Root cause:** [Description]
+- **Fix approach:** [Description]
+- **Effort:** [Size]
+
+---
+
+## 🟢 Medium Priority Debt
+
+### [Issue Name]
+
+- **Location:** `src/[path]`
+- **Impact:** [Minor friction]
+- **Fix approach:** [Description]
+- **Effort:** [Small]
+
+---
+
+## Known Fragile Areas
+
+<!-- Code that works but is risky to modify. Warn future agents before touching these. -->
+
+| Area | File(s) | Why Fragile | How to Proceed Safely |
+|------|---------|------------|----------------------|
+| [Area name] | `src/[path]` | [Why it's fragile] | [Safe approach] |
+| [Area name] | `src/[path]` | [Why it's fragile] | [Safe approach] |
+
+---
+
+## Security Notes
+
+<!-- Not a full security audit — track known issues and applied mitigations. -->
+
+- **[Issue type]:** [Description and current mitigation]
+- **Dependencies with known CVEs:** Run `npm audit` before each release
+- **Secrets management:** [How secrets are handled — env vars, Vault, Secrets Manager, etc.]
+
+---
+
+## Performance Notes
+
+- **[Bottleneck]:** `src/[path]` — [Description and known workaround]
+- **[N+1 query]:** `src/[path]` — [Where it occurs, impact, fix plan]
+- **Missing caching:** [What should be cached but isn't]
+
+---
+
+## Scaling Limits
+
+[What will break at scale and at what threshold]
+
+| Limit | Current capacity | Breaks at | Fix |
+|-------|-----------------|-----------|-----|
+| [DB connections] | [10 concurrent] | [~100 req/s] | [Connection pooling] |
+| [File uploads] | [Local disk] | [Any horizontal scale] | [Migrate to S3] |
+
+---
+*Generated: [date]*
+*Last updated: [date] after [trigger]*

package/.planning/codebase/CONVENTIONS.md

@@ -0,0 +1,119 @@
+# Coding Conventions
+
+<!-- Generated by /map-codebase. Prescriptive style guide derived from the actual codebase.
+     Consumed by: execute-phase (all work), plan-phase (UI/backend/refactor).
+     Auto-loaded by Copilot when editing source files via conventions.instructions.md. -->
+
+## Language & Formatting
+
+- **Language:** [TypeScript strict mode / Python 3.12+ type-annotated / etc.]
+- **Formatter:** [Prettier / Black / gofmt] — always run before committing
+- **Line length:** [120 chars]
+- **Indentation:** [2 spaces / 4 spaces / tabs]
+- **Semicolons:** [Required / Omitted]
+- **Quotes:** [Single / Double] for strings; [backticks for template literals]
+- **Trailing commas:** [Always / ES5 / Never]
+
+**Key formatter config (`.prettierrc`):**
+```json
+{
+  "semi": true,
+  "singleQuote": true,
+  "tabWidth": 2,
+  "trailingComma": "es5"
+}
+```
+
+## Naming Conventions
+
+| Thing | Convention | Example |
+|-------|-----------|---------|
+| Variables | `camelCase` | `userId`, `isActive` |
+| Functions | `camelCase` | `getUserById()`, `validateEmail()` |
+| Classes | `PascalCase` | `UserService`, `AuthController` |
+| Interfaces | `PascalCase` (no `I` prefix) | `User`, `CreateUserDto` |
+| Types | `PascalCase` | `UserRole`, `ApiResponse<T>` |
+| Constants | `SCREAMING_SNAKE_CASE` | `MAX_RETRY_COUNT`, `DEFAULT_PAGE_SIZE` |
+| Files | `kebab-case.ts` or `camelCase.ts` | [specify your pattern] |
+| Directories | `kebab-case` | `user-service/`, `api-routes/` |
+| Database columns | `snake_case` | `created_at`, `user_id` |
+| Environment variables | `SCREAMING_SNAKE_CASE` | `DATABASE_URL`, `API_SECRET` |
+
+## Import Ordering
+
+Always arrange imports in this order (enforced by ESLint):
+```typescript
+// 1. Node built-ins
+import path from 'path';
+import fs from 'fs';
+
+// 2. External packages
+import express from 'express';
+import { z } from 'zod';
+
+// 3. Internal absolute imports (using path aliases)
+import { UserService } from '@/services/user.service';
+import { db } from '@/config/database';
+
+// 4. Relative imports
+import { validateDto } from '../utils/validate';
+import type { CreateUserDto } from './user.types';
+```
+
+## Error Handling
+
+- **Never swallow errors silently** — always log or rethrow
+- **Use custom error classes** for domain errors:
+  ```typescript
+  // Throw domain errors like:
+  throw new NotFoundError(`User ${id} not found`);
+  throw new ValidationError('Email is required');
+  throw new UnauthorizedError('Invalid token');
+  ```
+- **Async functions:** always use `try/catch` or `.catch()` — never leave Promises unhandled
+- **HTTP errors:** handled centrally by `src/middleware/error.ts` — don't send error responses manually in routes
+
+## Function & Method Patterns
+
+- **Single responsibility:** one function does one thing
+- **Max function length:** ~50 lines — extract if longer
+- **Early returns** over deep nesting:
+  ```typescript
+  // Prefer:
+  if (!user) return null;
+  if (!user.isActive) throw new ForbiddenError('Account inactive');
+  return user;
+
+  // Over:
+  if (user) {
+    if (user.isActive) {
+      return user;
+    } else { ... }
+  } else { ... }
+  ```
+- **Async/await** over raw Promises for readability
+
+## TypeScript Specifics
+
+- **Always annotate function return types** — no implicit `any` returns
+- **Avoid `any`** — use `unknown` and narrow with type guards if needed
+- **Use `readonly`** for properties that should not be mutated
+- **Prefer interfaces** for object shapes; prefer `type` for unions/computed types
+- **Nullability:** use `| null` explicitly, not `| undefined` unless the value can be absent from an object
+
+## Comments
+
+- **Write comments for WHY, not WHAT** — code explains what; comments explain why
+- **Remove commented-out code** before committing
+- **JSDoc** for all exported functions and classes:
+  ```typescript
+  /**
+   * Finds active user by email. Returns null if not found or deactivated.
+   */
+  async function findActiveUser(email: string): Promise<User | null>
+  ```
+- **TODO comments:** include a ticket/issue reference: `// TODO(GH-123): refactor after auth migration`
+
+---
+*Generated: [date]*
+*Last updated: [date] after [trigger]*

package/.planning/codebase/INTEGRATIONS.md

@@ -0,0 +1,114 @@
+# External Integrations
+
+<!-- Generated by /map-codebase. Describes all external services, APIs, and infrastructure dependencies.
+     Consumed by: plan-phase (integration/API phases), execute-phase (when touching external services). -->
+
+## Summary
+
+| Service | Type | SDK / Library | Purpose |
+|---------|------|--------------|---------|
+| [e.g., PostgreSQL] | Database | `prisma` | Primary data store |
+| [e.g., Redis] | Cache | `ioredis` | Session storage, rate limiting |
+| [e.g., Stripe] | Payment API | `stripe` | Subscription billing |
+| [e.g., SendGrid] | Email | `@sendgrid/mail` | Transactional email |
+| [e.g., S3] | Object storage | `@aws-sdk/client-s3` | File uploads |
+| [e.g., Auth0] | Auth provider | `express-openid-connect` | User authentication |
+
+---
+
+## Database
+
+**Type:** [PostgreSQL 15 / MySQL 8 / MongoDB 6 / SQLite]
+**ORM/Client:** [Prisma / Drizzle / TypeORM / Mongoose]
+**Connection config:** `src/config/database.ts`
+
+```typescript
+// Connection pattern
+import { PrismaClient } from '@prisma/client';
+export const db = new PrismaClient();
+```
+
+**Migrations:** [How to run — e.g., `npx prisma migrate dev`]
+**Schema:** `[prisma/schema.prisma / src/models/ / migrations/]`
+
+---
+
+## Authentication Provider
+
+**Provider:** [Auth0 / Clerk / NextAuth / custom JWT]
+**Config file:** `src/config/auth.ts`
+**Middleware:** `src/middleware/auth.ts`
+
+**How auth works:**
+[Describe the auth flow — e.g., "JWT issued by Auth0, validated via JWKS endpoint, user attached to req.user by middleware"]
+
+**Required env vars:**
+```bash
+AUTH_SECRET=
+AUTH_PROVIDER_DOMAIN=
+AUTH_PROVIDER_CLIENT_ID=
+AUTH_PROVIDER_CLIENT_SECRET=
+```
+
+---
+
+## [Payment Service — e.g., Stripe]
+
+**SDK:** `stripe` v[X.X]
+**Client location:** `src/config/stripe.ts`
+
+**Webhooks:** `POST /api/webhooks/stripe` — handled in `src/routes/webhooks/stripe.route.ts`
+
+**Key operations:**
+- Create checkout session: `src/services/billing.service.ts → createCheckoutSession()`
+- Handle subscription events: `src/services/billing.service.ts → handleWebhookEvent()`
+
+**Required env vars:**
+```bash
+STRIPE_SECRET_KEY=
+STRIPE_WEBHOOK_SECRET=
+STRIPE_PRICE_ID_MONTHLY=
+```
+
+---
+
+## [Email Service — e.g., SendGrid / Resend]
+
+**SDK:** `[package]` v[X]
+**Client location:** `src/config/email.ts`
+**Templates:** `src/email-templates/`
+
+**Key operations:**
+- `src/services/email.service.ts → sendWelcomeEmail(user)`
+- `src/services/email.service.ts → sendPasswordReset(user, token)`
+
+**Required env vars:**
+```bash
+EMAIL_API_KEY=
+EMAIL_FROM_ADDRESS=
+EMAIL_FROM_NAME=
+```
+
+---
+
+## [Other External Services]
+
+[Add sections for each external service: S3, Cloudinary, Twilio, OpenAI, etc. Follow the pattern above.]
+
+---
+
+## CI/CD
+
+**Platform:** [GitHub Actions / GitLab CI / CircleCI]
+**Config:** `.github/workflows/`
+
+**Pipelines:**
+| Workflow | Trigger | What it does |
+|----------|---------|-------------|
+| `ci.yml` | Push / PR | Lint, type-check, test |
+| `deploy.yml` | Merge to main | Deploy to [env] |
+| `release.yml` | Tag v* | Build + publish |
+
+---
+*Generated: [date]*
+*Last updated: [date] after [trigger]*