fix(auth): harden shared-context isolation and config safety

docs/codebase-summary.md

@@ -1,8 +1,8 @@
 # CCS Codebase Summary
 
-Last Updated: 2026-02-04
+Last Updated: 2026-02-24
 
-Comprehensive overview of the modularized CCS codebase structure following the Phase 9 modularization effort (Settings, Analytics, Auth Monitor splits + Test Infrastructure), v7.1 Remote CLIProxy feature, v7.2 Kiro + GitHub Copilot (ghcp) OAuth providers, v7.14 Hybrid Quota Management, and v7.34 Image Analysis Hook.
+Comprehensive overview of the modularized CCS codebase structure following the Phase 9 modularization effort (Settings, Analytics, Auth Monitor splits + Test Infrastructure), v7.1 Remote CLIProxy feature, v7.2 Kiro + GitHub Copilot (ghcp) OAuth providers, v7.14 Hybrid Quota Management, v7.34 Image Analysis Hook, and account-context validation hardening.
 
 ## Repository Structure
 
@@ -201,6 +201,19 @@ src/
 | Services | `web-server/`, `api/` | HTTP server, API services |
 | Utilities | `utils/`, `management/` | Helpers, diagnostics |
 
+### Account Context Metadata Flow
+
+- Source fields: `accounts.<name>.context_mode` and `accounts.<name>.context_group` in `~/.ccs/config.yaml`.
+- Runtime policy resolver: `src/auth/account-context.ts`.
+- Metadata storage normalization: `src/auth/profile-registry.ts`.
+- API write validation: `PUT /api/config` in `src/web-server/routes/config-routes.ts`.
+- Rules:
+  - mode is isolation-first (`isolated` default, `shared` opt-in)
+  - shared mode requires non-empty valid `context_group`
+  - `context_group` is normalized (trim + lowercase + whitespace collapse to `-`)
+  - API route rejects `context_group` when mode is not `shared`
+  - registry normalization drops malformed persisted `context_group` values
+
 ### Target Adapter Module
 
 The targets module provides an extensible interface for dispatching profiles to different CLI implementations.

docs/dashboard-auth-cli.md

@@ -1,6 +1,6 @@
 # Dashboard Authentication CLI
 
-Last Updated: 2026-02-04
+Last Updated: 2026-02-24
 
 CLI commands for managing CCS dashboard authentication.
 
@@ -10,6 +10,35 @@ The CCS dashboard (`ccs config`) can be protected with username/password authent
 
 Authentication is **disabled by default** for backward compatibility. Use the CLI to configure and enable it.
 
+## Account Context Modes (Related Feature)
+
+Dashboard auth and account context metadata are separate:
+
+- `dashboard_auth`: protects dashboard access with username/password
+- `accounts.<name>.context_mode/context_group`: controls isolated vs shared account context
+
+Account context is isolation-first:
+
+| Mode | Default | Requirement |
+|------|---------|-------------|
+| `isolated` | Yes | No `context_group` required |
+| `shared` | No (opt-in) | Valid non-empty `context_group` |
+
+`context_group` normalization and validation:
+
+- trim + lowercase + collapse internal whitespace to `-`
+- allowed characters: lowercase letters, numbers, `_`, `-`
+- must start with a letter
+- max length: 64
+- shared mode requires non-empty value after normalization
+
+`PUT /api/config` behavior for account context:
+
+- rejects invalid unified payloads
+- rejects explicit `context_mode: shared` with invalid/empty `context_group`
+- normalizes valid shared `context_group` before save
+- rejects `context_group` when mode is not `shared`
+
 ## Commands
 
 ### `ccs config auth setup`
@@ -162,6 +191,10 @@ export CCS_DASHBOARD_PASSWORD_HASH='$2b$10$...'
 
 Check `session_timeout_hours` in config. Default is 24 hours.
 
+### "Invalid ... context_group ..."
+
+This error comes from `PUT /api/config` when an account explicitly sets shared mode with an invalid group. Use a canonical group value (for example: `team-alpha`).
+
 ## See Also
 
 - [Dashboard Auth Feature](https://ccs.kaitran.ca/features/dashboard-auth) - Full documentation