chore: auto-commit before merge (loop primary)

2026-02-16 14:36:25 +00:00
parent 9276955fa8
commit aca57714e4
23 changed files with 1859 additions and 513 deletions
@@ -0,0 +1,64 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Commands
+
+```bash
+npm run dev              # Vite dev server (localhost:5173)
+npm run build            # TypeScript compile + Vite production build
+npm run preview          # Preview production build locally
+npm run lint             # ESLint
+npm run typecheck        # TypeScript checks (no emit)
+npm run generate-embeddings  # Regenerate semantic search embeddings (src/data/embeddings.json)
+```
+
+**Validation gate (run before any PR):** `npm run lint && npm run typecheck && npm run build`
+
+No automated test framework — lint, typecheck, and build are the quality gates. For UI changes, verify manually (responsive behavior, accessibility, keyboard navigation).
+
+## Architecture
+
+**Interactive CV/portfolio** with a PMR (patient medical record) interface aesthetic. Three-phase UX: terminal boot → ECG heartbeat → dashboard.
+
+### App lifecycle (`src/App.tsx`)
+Phase orchestrator managing: BootSequence → ECGAnimation → LoginScreen → DashboardLayout
+
+### Data flow
+- **Canonical source:** `src/data/timeline.ts` — all career + education entities live here
+- **Derived data:** `constellation.ts` builds D3 graph data from timeline; `consultations.ts` re-exports for legacy consumers; `tags.ts` derived from skills; `kpis.ts` standalone
+- **Types:** `src/types/pmr.ts` has all domain types (Consultation, TimelineEntity, ConstellationNode, etc.)
+
+### Key subsystems
+
+| Subsystem | Entry point | Notes |
+|-----------|-------------|-------|
+| Dashboard | `DashboardLayout.tsx` | Orchestrates tiles, constellation, timeline, detail panel |
+| Career Constellation | `CareerConstellation.tsx` | D3 force simulation; roles as clusters, skills as nodes; hover/click/tap/keyboard |
+| Detail Panel | `DetailPanelContext.tsx` + `DetailPanel.tsx` | Right-side slide-out; context-aware views per entity type |
+| Semantic Search | `lib/semantic-search.ts` + `lib/embedding-model.ts` | Pre-computed embeddings + local Xenova transformer model in browser |
+| Command Palette | `CommandPalette.tsx` | Ctrl+K; fuzzy (Fuse.js) + semantic search |
+| Chat Widget | `ChatWidget.tsx` + `lib/llm.ts` | Gemini/OpenRouter LLM integration; requires `.env` API keys |
+| Accessibility | `AccessibilityContext.tsx` | Focus management, reduced motion, ARIA |
+
+### D3 integration pattern
+`CareerConstellation.tsx` manages D3 force simulation imperatively via refs. Highlight state tracked with refs (not React state) to avoid unnecessary re-renders. Touch: tap to pin, background tap to clear. Keyboard: Tab through nodes, Enter/Space activate, Escape reset.
+
+## Conventions
+
+- **TypeScript strict mode** — `noUnusedLocals`, `noUnusedParameters` enforced
+- **Path alias:** `@/*` → `src/*` (configured in vite.config.ts + tsconfig.json)
+- **Components:** PascalCase (`DashboardLayout.tsx`); Hooks: `useCamelCase`; Utilities: kebab-case (`semantic-search.ts`)
+- **Styling:** Tailwind utility classes + inline `CSSProperties` for dynamic/theme values
+- **Animations:** Framer Motion; respects `prefers-reduced-motion`
+- **Commits:** Conventional Commit prefixes (`feat:`, `chore:`, `fix:`) + optional story IDs
+
+## Design tokens
+
+- **Primary:** Teal `#00897B` / **Accent:** Coral `#FF6B6B`
+- **PMR palette:** GP system-inspired greens, teals, greys (defined in `tailwind.config.js`)
+- **Font tokens (CSS custom properties):**
+  - `--font-ui`: Elvaro Grotesque (dashboard UI)
+  - `--font-geist-mono`: Geist Mono / Fira Code fallback (canonical mono token)
+  - `--font-primary` / `--font-secondary`: Plus Jakarta Sans / Inter Tight
+- **Breakpoints:** xs 480, sm 640, md 768, lg 1024, xl 1280