docs(state): record phase 7 context session

.planning/STATE.md

@@ -3,11 +3,11 @@ gsd_state_version: 1.0
 milestone: v1.0
 milestone_name: milestone
 status: completed
-stopped_at: Completed 06-03-PLAN.md
+stopped_at: Phase 7 context gathered
-last_updated: "2026-03-25T16:41:32.580Z"
+last_updated: "2026-03-25T21:52:25.174Z"
 last_activity: 2026-03-23 — Completed 03-02 onboarding wizard, Slack OAuth, BYO API keys
 progress:
-  total_phases: 6
+  total_phases: 7
   completed_phases: 6
   total_plans: 25
   completed_plans: 25
@@ -183,6 +183,6 @@ None — all phases complete.
 
 ## Session Continuity
 
-Last session: 2026-03-25T16:37:36.187Z
+Last session: 2026-03-25T21:52:25.171Z
-Stopped at: Completed 06-03-PLAN.md
+Stopped at: Phase 7 context gathered
-Resume file: None
+Resume file: .planning/phases/07-multilanguage/07-CONTEXT.md

.planning/phases/07-multilanguage/07-CONTEXT.md

@@ -0,0 +1,96 @@
+# Phase 7: Multilanguage - Context
+
+**Gathered:** 2026-03-25
+**Status:** Ready for planning
+
+<domain>
+## Phase Boundary
+
+Full English, Spanish, and Portuguese support across the entire platform. Two surfaces: portal UI localization (all pages, labels, buttons, errors, templates, emails) and AI Employee language handling (auto-detect and respond in user's language). Extensible architecture so future languages require only translation files.
+
+</domain>
+
+<decisions>
+## Implementation Decisions
+
+### Language Switcher
+- Default language: auto-detect from browser locale (e.g., es-MX → Spanish, pt-BR → Portuguese)
+- Switcher location: sidebar bottom, near user avatar — always accessible
+- Language preference: saved to portal_users table in DB — follows user across devices
+- Login page: has its own language switcher (uses browser locale before auth, cookie for pre-auth persistence)
+- Supported languages for v1: en (English), es (Spanish), pt (Portuguese)
+
+### AI Employee Language Handling
+- Auto-detect from each incoming message — agent responds in the same language the user writes in
+- Applies across ALL channels: Slack, WhatsApp, Web Chat — consistent behavior everywhere
+- Fluid switching: agent follows each individual message's language, not locked to first message
+- Implementation: system prompt instruction to detect and mirror the user's language
+- No per-agent language config in v1 — auto-detect is the only mode
+
+### Translation Scope
+- **Portal UI**: All pages, labels, buttons, navigation, placeholders, tooltips — fully translated
+- **Agent templates**: Names, descriptions, and personas translated in all 3 languages (DB seed data includes translations)
+- **Wizard steps**: All 5 wizard steps and review page fully translated
+- **Onboarding flow**: All 3 onboarding steps translated
+- **Error messages**: Validation text and error messages localized on the frontend
+- **Invitation emails**: Sent in the language the inviting admin is currently using
+- **System notifications**: Localized to match user's language preference
+
+### Claude's Discretion
+- i18n library choice (next-intl, next-i18next, or built-in Next.js i18n)
+- Translation file format (JSON, TypeScript, etc.)
+- Backend error message strategy (frontend-only translation recommended — cleaner separation)
+- How template translations are stored in DB (JSON column vs separate translations table)
+- RTL support (not needed for en/es/pt but architecture should not block it)
+- Date/number formatting per locale
+
+</decisions>
+
+<specifics>
+## Specific Ideas
+
+- The language switcher should show flag icons or language abbreviations (EN / ES / PT) — instantly recognizable
+- Templates in Spanish and Portuguese should feel native, not machine-translated — proper business terminology for each locale
+- The system prompt language instruction should be concise: "Respond in the same language the user writes in. You support English, Spanish, and Portuguese."
+
+</specifics>
+
+<code_context>
+## Existing Code Insights
+
+### Reusable Assets
+- `packages/portal/app/layout.tsx` — Root layout where i18n provider would wrap the app
+- `packages/portal/components/nav.tsx` — Sidebar where language switcher goes (near user section)
+- `packages/portal/components/session-sync.tsx` — Could sync language preference alongside RBAC headers
+- `packages/shared/shared/models/auth.py:PortalUser` — Needs `language` field (en/es/pt)
+- `packages/shared/shared/prompts/system_prompt_builder.py` — Needs language instruction appended
+- `packages/portal/lib/system-prompt-builder.ts` — TypeScript mirror, same change
+- `packages/shared/shared/email.py` — Email sender needs to use translated templates
+- `migrations/versions/007_agent_templates.py` — Template seed data needs translated versions
+
+### Established Patterns
+- Portal uses Tailwind v4, shadcn/ui, DM Sans font (all support Latin character sets for en/es/pt)
+- Auth.js v5 JWT carries user claims — could include `language` claim
+- Agent templates stored as DB seed data — translations could go in same table or separate
+- All UI strings are currently hardcoded in TSX — need extraction to translation files
+
+### Integration Points
+- Every portal page and component needs string extraction
+- Agent Designer form labels need translation
+- Template gallery card content needs translation
+- Chat interface messages (system UI, not agent responses) need translation
+- Error messages from API (currently English) — frontend should translate display text
+
+</code_context>
+
+<deferred>
+## Deferred Ideas
+
+None — discussion stayed within phase scope
+
+</deferred>
+
+---
+
+*Phase: 07-multilanguage*
+*Context gathered: 2026-03-25*