viepilot 2.23.0 → 2.45.2

package/workflows/brainstorm.md

@@ -32,6 +32,180 @@ If the user writes in a different language during the session, that takes preced
 If `~/.viepilot/config.json` is absent, default to `en` — do not fail.
 </step>
 
+<step name="persona_domain_pack">
+## 0B. Persona Domain Pack Integration (ENH-073)
+
+At session start, before presenting topics, run:
+```bash
+node "$HOME/.claude/viepilot/bin/vp-tools.cjs" persona auto-switch
+node "$HOME/.claude/viepilot/bin/vp-tools.cjs" persona context
+```
+
+Store the result as `PERSONA_CONTEXT`. If command unavailable or errors → `PERSONA_CONTEXT = null`, continue silently.
+
+**If `PERSONA_CONTEXT` is available:**
+1. Read `persona.domain` — load corresponding `lib/domain-packs/{domain}.json`
+   - If domain is array (merged persona): load all packs and union their fields
+2. Apply to topic list:
+   - Prepend `extra_topics` not already in template (injected before session topics)
+   - Reorder template topics by `topic_priority` (matching topics float to top)
+   - Remove topics whose id is in `persona.brainstorm.topic_skip`
+3. When phase discussion begins: suggest `phase_template.phases` from domain pack as default ordering
+4. When Architect Design Mode activates: add domain pack `architect_pages` to workspace
+5. If `persona.confidence < 0.6`: add inline note "(persona auto-detected, may be inaccurate — run /vp-persona to refine)" — not a blocking prompt
+
+**Persona context is silently injected into the session — no banner, no AUQ.**
+</step>
+
+<step name="detect_embedded_domain">
+## 0C. Detect Embedded Domain (ENH-071)
+
+Scan the user's **initial message** (and, on `--continue`, the prior session content) for embedded trigger keywords.
+
+**MCU family keywords**: `STM32`, `ESP32`, `ESP8266`, `nRF52`, `nRF5`, `AVR`, `PIC`, `RISC-V`, `Cortex-M`, `RP2040`, `MSP430`, `SAM`, `SAMD`, `LPC`, `GD32`, `CH32`
+
+**Concept keywords**: `firmware`, `bare-metal`, `microcontroller`, `embedded`, `GPIO`, `interrupt`, `HAL`, `bootloader`, `RTOS`, `FreeRTOS`, `Zephyr`, `ThreadX`, `ChibiOS`, `RT-Thread`, `linker`, `peripheral`, `UART`, `SPI`, `I2C`, `CAN`, `watchdog`, `flash memory`, `memory map`, `ISR`, `DMA`, `PWM`, `ADC`, `DAC`, `MCU`, `SoC`
+
+**Activation rule**: `≥2` keyword matches (across both lists) → set `embedded_domain: true`
+
+**Manual override**: `--domain embedded` flag → set `embedded_domain: true` unconditionally, regardless of keyword count.
+
+**On first activation** — show one-time banner (then suppress for rest of session):
+
+```
+🔌 Embedded Domain Mode activated
+   Hardware topology, pin map, memory layout, RTOS scheduler,
+   protocol matrix, and power budget pages will be added to the
+   Architect workspace when relevant keywords are detected.
+   UI Direction web-UI suggestions are suppressed
+   (hardware display keywords route to hw-topology instead).
+```
+
+**Embedded topic injections** (activate when `embedded_domain: true`):
+- MCU/Toolchain sub-topic probes → added to tech-stack section (§ Gap 2)
+- RTOS/Scheduling topic → added after architecture/components (§ Gap 3)
+- Power Budget topic → triggered by battery/sleep/power keywords (§ Gap 7)
+- Safety/Compliance topic → triggered by safety/watchdog/SIL/ASIL keywords (§ Gap 10)
+- Firmware Phase Template → offered at phase assignment step (§ Gap 9)
+
+---
+
+### Embedded Topic Probes (ENH-071)
+
+#### MCU/Toolchain Sub-Topic (Gap 2)
+When `embedded_domain: true`, after general tech-stack questions, inject:
+
+```
+🔌 Embedded Toolchain — let's capture your hardware/toolchain choices:
+
+1. MCU/SoC family?
+   (STM32 / ESP32 / nRF52 / RISC-V / AVR / RP2040 / SAM / other)
+2. Toolchain?
+   (GCC-ARM / Clang / IAR Embedded Workbench / Keil MDK / other)
+3. Build system?
+   (CMake / Make / PlatformIO / West (Zephyr) / Arduino / other)
+4. Debug interface?
+   (SWD / JTAG / UART-bootloader / ESP ROM bootloader / other)
+5. Flasher/debugger tool?
+   (OpenOCD / J-Link / ST-Link / Black Magic Probe / esptool / other)
+6. SDK/HAL?
+   (STM32 HAL+LL / ESP-IDF / nRF5 SDK / Zephyr west / Arduino framework / vendor BSP / custom)
+```
+
+→ Store responses in `notes.md ## embedded_toolchain` YAML section.
+
+#### RTOS/Scheduling Topic (Gap 3)
+When `embedded_domain: true`, add as a brainstorm topic after architecture/components:
+
+```
+🔌 RTOS & Scheduling — describe your execution model:
+
+1. Execution model?
+   (bare-metal super-loop / bare-metal interrupt-driven / RTOS)
+2. If RTOS: which one?
+   (FreeRTOS / Zephyr / ThreadX (Azure RTOS) / RT-Thread / ChibiOS / other)
+3. Tasks/threads needed?
+   (for each: name, period or event-driven, priority 1–10, estimated stack KB)
+4. ISR table?
+   (interrupt source, handler function, priority level 0=highest)
+5. Shared resource protection?
+   (mutex / semaphore / critical section / taskENTER_CRITICAL / spinlock)
+6. Hard real-time constraints?
+   (any response-time budget in µs or ms?)
+```
+
+→ Store in `notes.md ## rtos_config` YAML section.
+
+#### Power Budget Topic (Gap 7)
+**Trigger**: battery / sleep / power / current / µA / mAh / Standby / Stop / Shutdown / Hibernate / IoT / LoRa keywords in session AND `embedded_domain: true`
+
+```
+🔋 Power Budget — capture power management requirements:
+
+1. Power supply?
+   (battery: chemistry + capacity mAh / USB / DC adapter / energy harvesting)
+2. Active mode target current? (mA)
+3. Sleep strategy: which MCU sleep mode?
+   (Stop / Standby / Shutdown / Hibernate / vendor-specific)
+4. Which peripherals stay active during sleep?
+   (RTC / LoRa / BLE / ADC / none)
+5. Wake-up sources?
+   (RTC timer / GPIO interrupt / UART wakeup / WDT)
+6. Target battery lifetime? (hours / days / months)
+```
+
+→ Store in `notes.md ## power_budget` YAML section.
+
+#### Safety/Compliance Topic (Gap 10)
+**Trigger**: safety / watchdog / fault / SIL / ASIL / IEC / ISO 26262 / DO-178 / EN 50128 / safety-critical keywords in session
+
+```
+🛡️ Safety & Compliance — capture safety requirements:
+
+1. Safety standard?
+   (IEC 61508 SIL 1–4 / ISO 26262 ASIL A–D / DO-178C / EN 50128 / none)
+2. Watchdog configuration?
+   (IWDG / WWDG / timeout value ms / pet strategy)
+3. Stack overflow detection?
+   (MPU / FreeRTOS stack check / canary / none)
+4. Fault handler strategy?
+   (HardFault / MemManage / BusFault → reset / safe state / log + continue)
+5. Safe state definition?
+   (what is the safe fallback on error detection?)
+6. Diagnostic coverage requirements? (if applicable)
+```
+
+→ Store in `notes.md ## safety_config` YAML section.
+
+#### Firmware Phase Ordering Template (Gap 9)
+When `embedded_domain: true`, at the **Phase Assignment** step, offer the standard firmware phase template before free-form phase entry:
+
+```
+🔌 Firmware Phase Template — suggested ordering for embedded projects
+(customize: remove, merge, or rename phases as needed):
+
+Phase 1: Board Bring-Up
+  (clock config, GPIO init, UART console, LED blink, JTAG/SWD verify)
+Phase 2: Driver Layer
+  (all peripheral drivers from hw-topology: SPI, I2C, UART, CAN, ADC, PWM, etc.)
+Phase 3: RTOS Configuration
+  (task creation, queues, semaphores, heap sizing, stack overflow detection)
+Phase 4: Middleware & Protocols
+  (MQTT/BLE/LoRa stack, filesystem/NVS, OTA bootloader, custom protocols)
+Phase 5: Application Logic
+  (state machines, business logic, data processing, sensor fusion)
+Phase 6: Integration & System Test
+  (hardware-in-the-loop, timing verification, stress test, power measurement)
+Phase 7: OTA & Production
+  (bootloader signing, provisioning flow, factory test jig, final firmware)
+
+1. Use this template (customize as needed)
+2. Enter phases manually
+```
+
+→ Store phases in `notes.md ## phases` with `domain: embedded` tag.
+</step>
+
 <step name="detect_sessions">
 ## 1. Detect Previous Sessions
 
@@ -80,6 +254,86 @@ If the user chooses to continue:
 5. If the session already has a **`## Phases`** section: briefly summarize existing phases; all subsequent updates must **merge** into that section (no silent deletion) unless the user explicitly requests narrowing/expanding scope.
 </step>
 
+<step name="upgrade_gap_detection">
+### Step 3B: Upgrade Gap Detection (ENH-067)
+
+**Runs immediately after step 3 (Load Context) when user is continuing an existing session.**
+
+#### Trigger conditions — ALL must be true:
+- Session `workflow_version` is absent **OR** older than current ViePilot version
+- Session `upgrade_supplement_version` is absent **OR** older than current ViePilot version
+- (Prevents re-surfacing already-supplemented topics on subsequent opens)
+
+Resolve current ViePilot version: `node bin/vp-tools.cjs info` → `version` field.
+
+#### Gap computation — version threshold table:
+
+| Introduced in | Topic | Detection heuristic (false-positive guard) |
+|--------------|-------|---------------------------------------------|
+| v2.32.0 | Topic 6: Admin & Governance (ENH-063) | session has no `## Admin` section AND no `admin:` YAML block |
+| v2.33.0 | Topic 7: Content Management (ENH-065) | session has no `## Content` section AND no `content_types:` YAML block |
+| v2.34.0 | Topic 8: User Data Management (ENH-066) | session has no `## User Data` section AND no `profile_fields:` YAML block |
+
+Always cross-check: even if the version threshold says a topic should be missing, confirm it
+is actually absent from the session file before listing it as a gap. This avoids false positives
+for users who added content manually or partially covered the topic under a different heading.
+
+#### Upgrade banner
+
+**Claude Code (terminal) — REQUIRED:**
+```
+question: "🔄 Upgrade gap detected — session was created with ViePilot v{old}, current is v{new}.\nMissing topics: {comma-separated list}. Discuss these gaps now?"
+header: "Upgrade"
+options:
+  - label: "Yes — discuss now (Recommended)"
+    description: "Run Q&A for missing topics inline; append ## Upgrade supplement to session"
+  - label: "Remind me at /save"
+    description: "Continue session normally; re-surface gap at /save"
+  - label: "Skip"
+    description: "Ignore gaps for this session"
+```
+
+**Text fallback (Cursor / Codex / other):**
+```
+🔄 Upgrade gap detected (v{old} → v{new})
+Missing topics: {list}
+
+1. Discuss gaps now (Recommended)
+2. Remind me at /save
+3. Skip
+```
+
+#### On "Yes — discuss now"
+
+Run only the Q&A sub-questions for each missing topic (re-use the relevant topic block from
+**Topics Template** in step 4). After completing Q&A for all missing topics, append the results
+to the session file under a clearly delimited section:
+
+```markdown
+## Upgrade supplement (v{old} → v{new})
+*Added {YYYY-MM-DD} after upgrading ViePilot to v{new}*
+
+### Topic 6: Admin & Governance [include only if this topic was missing]
+{Q&A results using Admin & Governance topic format}
+
+### Topic 7: Content Management [include only if this topic was missing]
+{Q&A results using Content Management topic format}
+
+### Topic 8: User Data Management [include only if this topic was missing]
+{Q&A results using User Data Management topic format}
+```
+
+After appending:
+1. Set `upgrade_supplement_version: "{current}"` in the session's `## Session Info` block
+2. Suggest: "Supplement complete — run `/vp-crystallize --upgrade` to patch your project artifacts"
+
+#### On "Remind at /save"
+Store the pending gap list. Re-surface the same AUQ at `/save` before writing the session file.
+
+#### On "Skip"
+Proceed normally. Do **not** set `upgrade_supplement_version` — gap will re-surface on next open.
+</step>
+
 <step name="brainstorm_mode">
 ## 4. Brainstorm Mode
 
@@ -117,7 +371,54 @@ Suggested topics to brainstorm:
    - Monitoring
    - Scaling
 
-6. **Phase assignment (ENH-030):** during brainstorm, each feature/capability is assigned to a specific **phase** — Phase 1, Phase 2, Phase 3... Do not use MVP/Post-MVP/Future tiers. If the user has not stated a phase, ask: “Which phase would you like to assign this feature to?”
+6. **Admin & Governance**
+   - Who are the admin personas? (super-admin, org-admin, ops team, support agent)
+   - User & Role management? (invite users, deactivate, RBAC/ABAC, permission matrix)
+   - Monitoring dashboard? (system health, error rates, latency, active users, SLA targets)
+   - Audit log requirements? (which actions must be tracked? retention period? compliance?)
+   - Billing & subscription management? (plans, invoices, upgrade/downgrade, payment history)
+   - Rate limiting / quota per tier? (API call limits, storage quotas, feature limits)
+   - Feature flags / runtime configuration? (kill switches, A/B toggles, env settings)
+   - Reporting & data export? (business metrics, usage analytics, CSV/Excel export)
+   - Notification management? (email/push templates, delivery log, unsubscribe management)
+
+7. **Admin Entity Management** (ENH-068)
+   - Which DB entities / domain objects need admin CRUD interfaces? (e.g., products, orders, categories, tenants, campaigns, bookings…)
+   - For each entity: which operations are needed? (Create / Read / Update / Delete / List)
+   - **List view** requirements: columns displayed, default sort, pagination style (offset vs. cursor), search & filter fields, range filters (date, price), multi-select filters
+   - **Bulk actions**: bulk delete, bulk status change, bulk export — which entities need these?
+   - **Create/Edit form**: required vs. optional fields, validation rules, nested relation fields (e.g., product → category), rich text / file upload fields, inline vs. separate page, auto-save / draft mode needed?
+   - **Delete semantics**: hard delete vs. soft delete (`is_deleted` / `deleted_at`); cascade rules for related records; restore / undelete capability needed?
+   - **Import / Export**: CSV/XLSX import for bulk seeding (e.g., product catalog); export filtered data from list views to CSV/XLSX/JSON; import validation error reporting
+   - **Audit trail per entity**: which entities need change history (actor + timestamp + field diff)? Separate audit table vs. event-sourced approach; surfaced in admin UI or log-only?
+   - **Admin ownership scoping**: are entities scoped per tenant/org (multi-tenant)? Can org_admin see only their org's data while super_admin sees all?
+   - **Read-only vs. editable entities**: which entities are system-generated (read-only in admin) vs. admin/user-generated (editable)?
+
+8. **Content Management**
+   - What types of content exist in this system? (articles, products, pages, media, courses, listings, FAQs...)
+   - Who creates content? (admin only, verified users, any user, API import)
+   - Content lifecycle? (draft → review → published → archived)
+   - Rich text or structured fields? (WYSIWYG, markdown, JSON schema, headless CMS API)
+   - Media management? (image upload, video, file attachments, CDN, storage limits per plan)
+   - Taxonomy & organization? (categories, tags, collections, folders, hierarchical tree)
+   - Multi-language / localization? (which locales, translation workflow, fallback strategy)
+   - Search & filtering? (full-text search, faceted filters, sort options, relevance tuning)
+   - Content versioning / history? (rollback, diff view, scheduled publish, expiry)
+   - SEO fields? (slug, meta title, meta description, OG image, canonical URL, sitemap)
+
+9. **User Data Management**
+   - What user data does the system store? (profile, preferences, history, uploads)
+   - Profile management? (edit name/avatar/email/password, delete account)
+   - Notification preferences? (email, push, SMS — per channel and frequency)
+   - Privacy & data controls? (view my data, export data, right-to-erasure / GDPR delete)
+   - Activity history? (login history, action log, what user can see about themselves)
+   - Connected accounts / integrations? (OAuth providers, third-party app connections, revoke access)
+   - Session & device management? (active sessions list, sign out all devices)
+   - Two-factor authentication? (TOTP, SMS, backup codes)
+   - Consent management? (cookie consent, marketing opt-in, terms acceptance log)
+   - Data retention policy? (how long data is kept, anonymization after deletion)
+
+10. **Phase assignment (ENH-030):** during brainstorm, each feature/capability is assigned to a specific **phase** — Phase 1, Phase 2, Phase 3... Do not use MVP/Post-MVP/Future tiers. If the user has not stated a phase, ask: “Which phase would you like to assign this feature to?”
 
 ### Interactive Q&A
 For each topic:
@@ -127,6 +428,46 @@ For each topic:
 4. Suggest alternatives if needed
 5. Record decisions
 
+### Mid-session Structured Choice Rule (BUG-022)
+
+When presenting a decision with **≥2 discrete named options** during Q&A (e.g. "Hero first
+or Features section?", "lean into multi-adapter or persona angle?", any numbered choice set),
+use adapter-aware prompts:
+
+> **Claude Code (terminal) — REQUIRED:** Call `AskUserQuestion`. AUQ spec:
+>   - question: "{The direction/decision question}"
+>   - header: "{short label, ≤12 chars}"
+>   - options: one entry per discrete choice (2–4 options per AUQ call)
+>   - multiSelect: false (unless user explicitly wants multi-select)
+> **Cursor / Codex / Antigravity / Copilot:** present as plain numbered list.
+
+**Exempt from AUQ** (remain plain conversational text):
+- Open-ended questions with no discrete choices ("Anything else you'd like to add?")
+- Follow-up clarification questions ("Tell me more about X")
+- Questions where the expected answer is a free-form description
+
+**AUQ per decision, not per topic:** One AUQ call per structured decision point.
+Do not bundle multiple unrelated decisions into a single AUQ call.
+
+### Mid-session Transition Prompt Rule (BUG-023)
+
+When the AI offers **session-flow choices** at a section or topic boundary — after presenting
+a table, completing an analysis, or finishing a discussion topic — use adapter-aware prompts:
+
+> **Claude Code (terminal) — REQUIRED:** Call `AskUserQuestion`. Canonical AUQ spec:
+>   - question: "What would you like to do next?"
+>   - header: "Next step"
+>   - options (vary by context; always ≥2):
+>     - label: "Save session → /vp-crystallize", description: "Generate implementation specs"
+>     - label: "Update UI Direction artifacts", description: "Update index.html/notes.md now"
+>     - label: "Continue discussing", description: "Explore another section or topic"
+>   - multiSelect: false
+> **Cursor / Codex / Antigravity / Copilot:** present as plain numbered list.
+
+**Scope:** session-FLOW control choices only — distinct from BUG-022 (Q&A content/direction
+decisions during Q&A). Triggered when offering: save/crystallize, update artifacts, or
+continue/discuss more. NOT triggered for content questions about what to build or design.
+
 ### Landing Page Deep-Dive (activated contextually)
 If the user is brainstorming a landing page / homepage / marketing page:
 
@@ -182,6 +523,118 @@ If the user is brainstorming a project with UI/UX or requests a visual design:
    - Update HTML/CSS direction directly
    - Record decision + rationale in `notes.md` (single source of truth for design intent)
 
+### Design Token Extraction (ENH-076)
+
+**Trigger:** UI Direction Mode active (`--ui` flag) OR ≥2 design keywords detected in session:
+`color` / `font` / `brand` / `spacing` / `typography` / `palette` / `theme` / `style`
+
+**Extraction process:**
+During Q&A, AI tracks design decisions and maps them to a TOKEN_MAP:
+- Color mentions → `tokens.colors.*` (primary, surface, accent, error, success, warning)
+- Font/typeface mentions → `tokens.typography.fontFamily`, `fontSize`
+- Size/scale/rhythm mentions → `tokens.spacing.base`, `tokens.spacing.scale`
+- Roundness/corner mentions → `tokens.rounded.*` (sm/md/lg/full)
+
+**Output — `.viepilot/ui-direction/{session-id}/design.md`** (Design.MD v1 spec):
+```yaml
+---
+name: "{project-name}"
+description: "{one-line brand description from session}"
+colors:
+  primary: "{hex}"
+  surface: "{hex}"
+  accent: "{hex}"
+typography:
+  fontFamily: "{font}, sans-serif"
+  fontSize:
+    base: 16
+spacing:
+  base: 8
+  scale: [4, 8, 16, 24, 32, 48]
+rounded:
+  sm: 4px
+  md: 8px
+---
+
+## Overview
+{Brand personality extracted from session}
+
+## Colors
+{Color rationale from session decisions}
+
+## Typography
+{Font rationale from session decisions}
+```
+
+**notes.md section added** (append to session notes.md):
+```yaml
+## design_tokens
+colors:
+  primary: "{hex}"
+typography:
+  fontFamily: "{font}"
+spacing_base: 8
+design_md_path: .viepilot/ui-direction/{session-id}/design.md
+design_md_generated: true
+```
+
+**After generation:** Show inline summary:
+```
+🎨 Design.MD generated: primary={hex} | font={font} | spacing={n}px
+   Path: .viepilot/ui-direction/{session-id}/design.md
+```
+
+**Incremental updates:** If user refines a color or font later in the session, update
+`design.md` and `notes.md ## design_tokens` in place (same as how `index.html` is updated
+incrementally as design decisions evolve).
+
+### Skill Registry Integration (FEAT-020)
+
+**Trigger**: UI Direction Mode is active (at least one HTML file being generated or updated).
+
+**Step — Load registry:**
+```bash
+node ~/.claude/viepilot/bin/vp-tools.cjs get-registry 2>/dev/null \
+  || node ~/.cursor/viepilot/bin/vp-tools.cjs get-registry 2>/dev/null \
+  || cat ~/.viepilot/skill-registry.json 2>/dev/null
+```
+Parse JSON output → extract `skills[]`.
+If output is `null` or command fails: skip silently — no warning, no prompt
+
+**Step — Match skills to UI signals:**
+Map brainstorm UI signal keywords to capability tags:
+
+| UI Signal keywords | Capability match |
+|-------------------|-----------------|
+| `component`, `layout`, `screen`, `page`, `UI`, `UX` | `ui-generation`, `component-design` |
+| `responsive`, `mobile`, `grid` | `responsive-layout` |
+| `design`, `theme`, `color`, `typography` | `design-system`, `design-tokens` |
+| `form`, `button`, `input`, `modal` | `component-design` |
+
+For each registered skill: if `skill.capabilities` intersects matched capability tags → skill is **active**.
+
+**Step — Silent apply:**
+- For each active skill: prepend `skill.best_practices[]` to the context used for HTML generation
+- **No banner, no prompt, no mention to user** — best practices blend into generated output
+- This is background-only, like Background UI Extraction (ENH-026)
+
+**Step — Record in notes.md:**
+After the session's first UI artifact is generated (or updated), append to `notes.md`:
+
+```yaml
+## skills_used
+- id: frontend-design
+  version: null
+  trigger: ui-generation signal
+  applied_at: brainstorm-session
+  best_practices_applied:
+    - Mobile-first
+    - Design tokens
+```
+
+If `## skills_used` already exists: merge (add new skills, update applied_at).
+If no skills matched or registry absent: omit `## skills_used` section.
+
 **Required hook (multi-page only)**
 
 When the `pages/` directory exists or any `pages/*.html` is added / renamed / removed:
@@ -196,6 +649,84 @@ When the `pages/` directory exists or any `pages/*.html` is added / renamed / re
    - adjustments according to product objectives
 4. Keep the prototype at a directional description level; do not force production-ready code at the brainstorm stage.
 
+### Recommended Breakdown Ordering (ENH-061)
+
+For sessions that produce both system architecture and UI/UX artifacts, follow this sequence to ensure complete idea→architect+UI breakdown:
+
+```
+Step 1: Free idea collection
+  → Explore the problem space; no structure required yet
+
+Step 2: Scope lock + Phase assignment  (existing)
+  → Assign all features to Phase 1 / Phase 2 / Phase 3...
+  → Fill ## Phases in session draft
+
+Step 2B: Workspace Mode Selection  (BUG-018)
+  → After scope lock, before any design workspace is created
+  → AUQ: Both / Architect only / UI Direction only / Neither
+
+Step 3: Feature → Coverage mapping  (ENH-061)
+  → For each Phase 1 feature: name the architect component AND UI screen
+  → Output: ## Coverage matrix in notes.md
+
+Step 4: Architect Design  (existing — only when Step 2B selects Both or Architect only)
+  → Fill architect workspace per coverage matrix
+  → Use /vp-brainstorm --architect or let heuristics fire
+
+Step 5: Architect → UI sync  (ENH-061 — arch_to_ui_sync)
+  → After architect edits: check which architectural decisions impact UI screens
+  → Prompt user to update UI Direction accordingly
+
+Step 6: UI Direction  (existing — only when Step 2B selects Both or UI Direction only)
+  → Fill UI workspace per coverage matrix + arch feedback
+  → Use /vp-brainstorm --ui or proactive 🎨 banner
+
+Step 7: Completeness gate  (ENH-061)
+  → Validate: every Phase 1 feature has ≥1 coverage (architect OR UI)
+  → Warn on any feature with no coverage in both modes
+
+Step 8: /save → /vp-crystallize  (existing)
+```
+
+> **Note**: Steps 3–7 are optional for simple or early-stage sessions. The flow is recommended when a session produces both Architect Design and UI Direction artifacts.
+
+### Step 2B: Workspace Mode Selection (BUG-018)
+
+Runs **after scope lock** (`## Phases` in session draft is populated) and **before any design workspace is created**.
+
+> **Claude Code (terminal) — REQUIRED:** Call `AskUserQuestion` tool:
+> - question: `"Scope locked. Which design workspaces would you like to activate for this session?"`
+> - header: `"Workspaces"`
+> - options:
+>   - `{ label: "Both Architect + UI Direction (Recommended)", description: "Full coverage: architecture HTML workspace + UI prototype direction per ENH-061 Breakdown Ordering" }`
+>   - `{ label: "Architect Design only (🏗️)", description: "System architecture, data-flow, ERD, APIs, decisions HTML workspace" }`
+>   - `{ label: "UI Direction only (🎨)", description: "HTML prototype direction for screens/pages" }`
+>   - `{ label: "Neither — text-only", description: "Continue as text brainstorm, activate workspaces manually later with --architect or --ui" }`
+> - multiSelect: false
+>
+> **Text fallback (Cursor/Codex/Copilot/Antigravity):**
+> ```
+> Scope locked. Which design workspaces would you like to activate?
+> 1. Both Architect + UI Direction (Recommended) — full coverage per ENH-061
+> 2. Architect Design only (🏗️) — HTML architecture workspace
+> 3. UI Direction only (🎨) — HTML prototype direction
+> 4. Neither — text-only, activate manually later
+> ```
+
+**On selection:**
+- **"Both"**: activate Architect Mode (Step 4) → arch_to_ui_sync (Step 5) → UI Direction (Step 6) — in that order
+- **"Architect Design only"**: activate Architect Mode (Step 4), skip Step 6
+- **"UI Direction only"**: skip Architect (Step 4), activate UI Direction (Step 6) directly
+- **"Neither"**: skip both Steps 4 and 6; user can activate later with `--architect` / `--ui` flag
+
+**Guard rule (BUG-018 fix):**
+- Architect auto-activate heuristic (≥3 components / ≥1 stack mention) **MUST NOT fire independently** once Step 2B runs.
+- If heuristic fires **before** scope lock: save the signal, defer prompt until Step 2B.
+- If user selects **"Neither"** or **"UI Direction only"** at Step 2B: suppress Architect auto-activate for the remainder of this session.
+- If user selects **"Architect Design only"** or **"Both"**: heuristic is redundant — workspace activates per selection, no second prompt.
+
+---
+
 ### Architect Design Mode (FEAT-011)
 
 Brainstorm system architecture with live HTML generation — a visual workspace for the user to review, edit, and present before running `/vp-crystallize`.
@@ -240,6 +771,9 @@ Activate Architect Design Mode so I can create an HTML visualization?
   sequence-diagram.html   # Per-scenario sequences (sequenceDiagram) — ENH-029
   deployment.html         # Infra, environments, CI/CD pipeline — ENH-029
   apis.html               # Service API listing & design decisions — ENH-029
+  admin.html              # Admin & governance capabilities — actor flow, role hierarchy, key operations, audit schema (ENH-063)
+  content.html            # Content types, lifecycle state machine, creator roles, taxonomy, media/SEO schema (ENH-065)
+  user-data.html          # User-owned data controls — profile fields, privacy rights, session management, 2FA, consent schema (ENH-066)
   style.css               # Shared: dark/light CSS vars, .updated highlight, Mermaid container, responsive nav
   notes.md                # Machine-readable YAML (see schema below)
 ```
@@ -263,6 +797,367 @@ Activate Architect Design Mode so I can create an HTML visualization?
 | `architecture.html` | Component structure + C4 system context + external integrations |
 | `deployment.html` | Infrastructure, environments, ops concerns, CI/CD pipeline |
 | `apis.html` | API endpoint design, HTTP methods, request/response contracts |
+| `admin.html` | Admin personas, role hierarchy, key admin operations (CRUD users, billing management, audit log schema), access control model |
+| `entity-mgmt.html` | Admin entity CRUD matrix: entity name, admin ops (C/R/U/D), soft delete flag, bulk actions, audit trail, multi-tenant scope; import/export summary table (ENH-068) |
+| `content.html` | Content types, lifecycle states, creator permission matrix, taxonomy tree, media storage config, SEO field schema |
+| `user-data.html` | User-owned data: profile field list, privacy rights matrix (export/erasure), connected OAuth providers, session/device management, 2FA config, consent log schema |
+| `design.html` | Design system visual reference: color swatches grid, typography scale table, spacing grid, border-radius samples, component token table (ENH-076) |
+
+**design.html trigger:** Architect Mode active AND (`design.md` present in session dir OR `## design_tokens` in `notes.md`).
+
+**design.html content sections:**
+
+1. **Color Palette** — swatch grid: colored square + hex value + semantic label, grouped as Brand (primary/accent) | Neutral (surface/muted) | Semantic (error/success/warning)
+2. **Typography Scale** — table: Level | Font Family | Size | Weight | Line Height | Example text (H1 → H2 → H3 → Body → Caption → Code)
+3. **Spacing Grid** — visual row of boxes with increasing widths (4px, 8px, 16px, 24px, 32px, 48px), labeled spacing-1 through spacing-12
+4. **Shape / Border Radius** — 4 visual boxes showing sharp/subtle/rounded/pill radii with CSS var labels (`--rounded-sm` → `--rounded-full`)
+5. **Component Tokens** — table: Component | Token | Value (rendered only if `components:` section exists in design.md)
+
+**Sync rule:** When `notes.md ## design_tokens` is updated (e.g. via new UI direction keywords), regenerate `design.html` sections — same incremental update pattern as other Architect pages.
+
+**Hub nav:** Add `<a href="design.html">🎨 Design System</a>` to `index.html` nav when `design.html` is created. Update `## Pages inventory` in `notes.md`.
+
+**Format:** Pure HTML + inline `<style>`, no external CSS/JS dependencies — consistent with all other Architect workspace pages.
+
+#### Admin & Governance Detection (ENH-063)
+
+**Trigger keywords** (case-insensitive, Vietnamese or English):
+> `admin`, `administrator`, `back-office`, `quản trị`, `quản lý người dùng`, `user management`, `role`, `permission`, `phân quyền`, `monitor`, `monitoring`, `giám sát`, `audit log`, `audit trail`, `nhật ký`, `billing`, `subscription`, `gói cước`, `thanh toán`, `rate limit`, `quota`, `feature flag`, `feature toggle`, `report`, `reporting`, `báo cáo`, `analytics`, `phân tích`, `SLA`, `compliance`, `GDPR`, `SOC2`, `alert`, `cảnh báo`, `health check`, `observability`
+
+**Early-session detection:**
+At session start, scan initial message for admin keywords. If **≥1 keyword** found → show proactive banner:
+
+> **Adapter-aware prompt:**
+> **Claude Code (terminal) — REQUIRED:** Call `AskUserQuestion` tool. AUQ spec:
+>   - question: "I noticed your project may involve admin or governance capabilities. Should we discuss Admin & Governance (Topic 6)?"
+>   - header: "Admin & Governance"
+>   - options: [{ label: "Yes — explore admin panel, user management, monitoring, audit logs", description: "Recommended for multi-user/SaaS projects" }, { label: "Not needed — single-user or admin-free project", description: "" }, { label: "Later — add to notes, continue current topic", description: "" }]
+>
+> **Text fallback:**
+> ```
+> 🔐 I noticed your project may involve admin or governance capabilities.
+> Should we discuss Admin & Governance (Topic 6)?
+>
+> 1. Yes — explore admin panel, user management, monitoring, audit logs (Recommended for multi-user/SaaS)
+> 2. Not needed — single-user or admin-free project
+> 3. Later — add to notes, continue current topic
+> ```
+
+**During-session detection:**
+When **≥2 unique admin keywords** detected → surface confirmation:
+
+> **Claude Code (terminal) — REQUIRED:** Call `AskUserQuestion`:
+>   - question: "Admin/governance signals detected in this session. Would you like to cover Admin & Governance (Topic 6)?"
+>   - options: [{ label: "Yes — switch to / add admin topic", description: "" }, { label: "Note in background (no topic switch)", description: "" }, { label: "Skip for this session", description: "" }]
+>
+> **Text fallback:** `🔐 Admin/governance signals detected. Cover Admin & Governance (Topic 6)? 1. Yes 2. Note in background 3. Skip`
+
+**Admin coverage gate before /save:**
+Before writing session file, check:
+- Project has multi-user signals (`role`, `team`, `organization`) OR
+- SaaS/paid product signals (`subscription`, `billing`, `plan`) OR
+- Compliance signals (`audit`, `GDPR`, `SOC2`)
+
+If ANY detected AND `## admin` YAML section not present in notes.md:
+
+> **Text fallback:**
+> ```
+> ⚠️ Admin gap detected: project has multi-user/SaaS/compliance signals but Admin & Governance was not covered.
+> 1. Add admin topic now (go to Topic 6)
+> 2. Add note to backlog (".viepilot/requests/ENH-admin-tbd.md")
+> 3. Dismiss — skip admin for this session
+> ```
+> (Non-blocking — user can dismiss)
+
+**admin.html trigger:** admin keyword detected in session AND Architect Mode is active → create/update `admin.html`.
+
+#### Content Management Detection (ENH-065)
+
+**Trigger keywords** (case-insensitive, Vietnamese or English):
+> `article`, `blog`, `post`, `product`, `catalog`, `listing`, `page`, `landing page`, `content`, `nội dung`, `bài viết`, `sản phẩm`, `danh mục`, `CMS`, `headless`, `media`, `upload`, `image`, `video`, `category`, `tag`, `taxonomy`, `search`, `SEO`, `slug`, `WYSIWYG`, `markdown`, `template`, `course`, `lesson`, `knowledge base`, `FAQ`, `documentation`, `docs`
+
+**Early-session detection:**
+At session start, scan initial message for content keywords. If **≥1 keyword** found → show proactive banner:
+
+> **Adapter-aware prompt:**
+> **Claude Code (terminal) — REQUIRED:** Call `AskUserQuestion` tool. AUQ spec:
+>   - question: "I noticed your project may involve content management capabilities. Should we discuss Content Management (Topic 7)?"
+>   - header: "Content Mgmt"
+>   - options: [{ label: "Yes — explore content types, lifecycle, media, search, SEO", description: "Recommended for blogs, eCommerce, SaaS, LMS, marketplace" }, { label: "Not needed — no content layer in this project", description: "" }, { label: "Later — add to notes, continue current topic", description: "" }]
+>
+> **Text fallback:**
+> ```
+> 🗂️ I noticed your project may involve content management capabilities.
+> Should we discuss Content Management (Topic 7)?
+>
+> 1. Yes — explore content types, lifecycle, media, search, SEO (Recommended for blogs, eCommerce, SaaS, LMS, marketplace)
+> 2. Not needed — no content layer in this project
+> 3. Later — add to notes, continue current topic
+> ```
+
+**During-session detection:**
+When **≥2 unique content keywords** detected → surface confirmation:
+
+> **Claude Code (terminal) — REQUIRED:** Call `AskUserQuestion`:
+>   - question: "Content management signals detected in this session. Would you like to cover Content Management (Topic 7)?"
+>   - options: [{ label: "Yes — switch to / add content topic", description: "" }, { label: "Note in background (no topic switch)", description: "" }, { label: "Skip for this session", description: "" }]
+>
+> **Text fallback:** `🗂️ Content management signals detected. Cover Content Management (Topic 7)? 1. Yes 2. Note in background 3. Skip`
+
+**Content coverage gate before /save:**
+Before writing session file, check:
+- Project has content-type signals (`article`, `product`, `post`, `page`, `listing`, `course`) OR
+- Media signals (`upload`, `image`, `video`, `media`, `CDN`) OR
+- SEO/search signals (`SEO`, `slug`, `search`, `facets`)
+
+If ANY detected AND `## content` YAML section not present in notes.md:
+
+> **Text fallback:**
+> ```
+> ⚠️ Content gap detected: project has content-type/media/SEO signals but Content Management was not covered.
+> 1. Add content topic now (go to Topic 7)
+> 2. Add note to backlog (".viepilot/requests/ENH-content-tbd.md")
+> 3. Dismiss — skip content management for this session
+> ```
+> (Non-blocking — user can dismiss)
+
+**content.html trigger:** content keyword detected in session AND Architect Mode is active → create/update `content.html`.
+
+#### User Data Management Detection (ENH-066)
+
+**Trigger keywords** (case-insensitive, Vietnamese or English):
+> `profile`, `account`, `settings`, `preferences`, `notification`, `privacy`, `GDPR`, `data export`, `delete account`, `logout`, `session`, `device`, `2FA`, `two-factor`, `OAuth`, `login history`, `user data`, `personal data`, `tài khoản`, `hồ sơ`, `cài đặt`, `thông báo`, `quyền riêng tư`, `lịch sử`, `xóa tài khoản`, `đăng xuất`, `consent`, `cookie`
+
+**Early-session detection:**
+At session start, scan initial message for user data keywords. If **≥1 keyword** found → show proactive banner:
+
+> **Adapter-aware prompt:**
+> **Claude Code (terminal) — REQUIRED:** Call `AskUserQuestion` tool. AUQ spec:
+>   - question: "I noticed your project may involve user data management capabilities. Should we discuss User Data Management (Topic 8)?"
+>   - header: "User Data"
+>   - options: [{ label: "Yes — explore profile, privacy controls, 2FA, sessions", description: "Recommended for B2C apps, SaaS, apps with GDPR requirements" }, { label: "Not needed — no user data layer in this project", description: "" }, { label: "Later — add to notes, continue current topic", description: "" }]
+>
+> **Text fallback:**
+> ```
+> 👤 I noticed your project may involve user data management capabilities.
+> Should we discuss User Data Management (Topic 8)?
+>
+> 1. Yes — explore profile, privacy controls, 2FA, sessions (Recommended for B2C apps, SaaS, GDPR)
+> 2. Not needed — no user data layer in this project
+> 3. Later — add to notes, continue current topic
+> ```
+
+**During-session detection:**
+When **≥2 unique user data keywords** detected → surface confirmation:
+
+> **Claude Code (terminal) — REQUIRED:** Call `AskUserQuestion`:
+>   - question: "User data management signals detected in this session. Would you like to cover User Data Management (Topic 8)?"
+>   - options: [{ label: "Yes — switch to / add user data topic", description: "" }, { label: "Note in background (no topic switch)", description: "" }, { label: "Skip for this session", description: "" }]
+>
+> **Text fallback:** `👤 User data management signals detected. Cover User Data Management (Topic 8)? 1. Yes 2. Note in background 3. Skip`
+
+**User data coverage gate before /save:**
+Before writing session file, check:
+- Project has user-account signals (`profile`, `account`, `settings`, `login`) OR
+- Privacy signals (`GDPR`, `privacy`, `data export`, `delete account`) OR
+- Auth/session signals (`2FA`, `session`, `OAuth`, `connected accounts`)
+
+If ANY detected AND `## user_data` YAML section not present in notes.md:
+
+> **Text fallback:**
+> ```
+> ⚠️ User data gap detected: project has user-account/privacy/auth signals but User Data Management was not covered.
+> 1. Add user data topic now (go to Topic 8)
+> 2. Add note to backlog (".viepilot/requests/ENH-user-data-tbd.md")
+> 3. Dismiss — skip user data management for this session
+> ```
+> (Non-blocking — user can dismiss)
+
+**user-data.html trigger:** user data keyword detected in session AND Architect Mode is active → create/update `user-data.html`.
+
+#### Admin Entity Management Detection (ENH-068)
+
+**Trigger keywords** (case-insensitive, Vietnamese or English):
+> `CRUD`, `entity`, `table`, `manage`, `list view`, `admin panel`, `data management`, `import`, `export`, `bulk`, `soft delete`, `audit trail`, `quản lý dữ liệu`, `bảng dữ liệu`, `danh sách`, `thêm sửa xóa`
+
+**Early-session detection:**
+At session start, scan initial message for entity management keywords. If **≥1 keyword** found → show proactive banner:
+
+> **Adapter-aware prompt:**
+> **Claude Code (terminal) — REQUIRED:** Call `AskUserQuestion` tool. AUQ spec:
+>   - question: "I noticed your project may involve admin data management. Should we discuss Admin Entity Management (Topic 7)?"
+>   - header: "Entity Mgmt"
+>   - options: [{ label: "Yes — explore CRUD, list views, bulk ops, import/export, audit trail", description: "Recommended for projects with DB entities managed via admin panel" }, { label: "Not needed — no admin CRUD interface in this project", description: "" }, { label: "Later — add to notes, continue current topic", description: "" }]
+>
+> **Text fallback:**
+> ```
+> 🗄️ I noticed your project may involve admin data management.
+> Should we discuss Admin Entity Management (Topic 7)?
+>
+> 1. Yes — explore CRUD, list views, bulk ops, import/export, audit trail (Recommended)
+> 2. Not needed — no admin CRUD interface in this project
+> 3. Later — add to notes, continue current topic
+> ```
+
+**During-session detection:**
+Maintain a running count of unique entity management keywords encountered during the session.
+At ≥2 unique keywords → show soft prompt at next topic boundary (same format as above).
+Does not interrupt mid-topic conversation.
+
+**Coverage gate before /save:**
+
+If `## erd` YAML is present in architect `notes.md` OR `erd.html` is in the workspace
+AND session has no `## Admin Entity Management` / `## entity_mgmt` coverage:
+
+> **Claude Code (terminal):** AUQ:
+>   - question: "🗄️ Entity management gap — your project has DB entities defined but admin CRUD coverage was not discussed. Add now?"
+>   - options: [{ label: "Add entity management topic now", description: "Go to Topic 7" }, { label: "Add note to backlog", description: "Log as .viepilot/requests/ENH-entity-mgmt-tbd.md" }, { label: "Dismiss", description: "Skip entity management for this session" }]
+>
+> **Text fallback:**
+> ```
+> 🗄️ Entity management gap — your project has DB entities but no admin CRUD coverage defined.
+> 1. Add entity management topic now (go to Topic 7)
+> 2. Add note to backlog (".viepilot/requests/ENH-entity-mgmt-tbd.md")
+> 3. Dismiss — skip entity management for this session
+> ```
+> (Non-blocking — user can dismiss)
+
+**entity-mgmt.html trigger:** entity management keyword detected in session AND Architect Mode is active → create/update `entity-mgmt.html`.
+
+---
+
+#### Embedded Domain Architect Pages (ENH-071 Gaps 1, 4, 5, 8)
+
+All 6 pages below are only created when **`embedded_domain: true`** AND Architect Mode is active. Each page follows the standard workspace pattern: create HTML in `.viepilot/architect/{session-id}/`, link in `index.html` nav under an **Embedded** section, update `## Pages inventory` in `notes.md`.
+
+---
+
+##### `hw-topology.html` — Hardware Topology (Gap 1)
+
+**Trigger**: Always created when `embedded_domain: true` AND Architect Mode activates.
+
+**Content**:
+- Mermaid `graph TD` block diagram: MCU node connected to external ICs/sensors/actuators via labeled bus arrows (bus type + speed on arrow label)
+- Component table: Part | Type | Interface | Bus Speed | Notes
+- Power rails table: Rail | Source | Voltage | Max current (mA)
+
+**notes.md YAML section**:
+```yaml
+## hw_topology
+mcu:
+  family: ""        # e.g. STM32F4, ESP32-S3
+  core: ""          # e.g. Cortex-M4 @168MHz
+  flash_kb: 0
+  ram_kb: 0
+peripherals: []     # on-chip peripherals: [{ name, type, instance }]
+external_ics: []    # [{ name, type, interface, bus_speed, notes }]
+buses: []           # [{ type: SPI|I2C|UART|CAN|USB, speed, devices: [] }]
+power_rails: []     # [{ rail, source, voltage_v, max_ma }]
+```
+
+---
+
+##### `pin-map.html` — GPIO/Pin Assignment (Gap 4)
+
+**Trigger**: GPIO / pin / pinout / assignment / alternate function keywords AND `embedded_domain: true` OR when `hw-topology.html` is created (auto-companion).
+
+**Content**:
+- Pin assignment table: Pin# | GPIO Name | Alt Function | Peripheral | Direction (IN/OUT/AF) | Pull (Up/Down/None) | Voltage Level | Notes
+- Conflict detection: if two rows share the same GPIO name with conflicting functions → highlight row in red and note conflict
+
+**notes.md YAML section**:
+```yaml
+## pin_map
+pins: []        # [{ pin_num, gpio_name, function, peripheral, direction, pull, voltage_v, notes }]
+conflicts: []   # auto-detected: [{ gpio_name, conflicting_functions: [] }]
+```
+
+---
+
+##### `memory-layout.html` — Memory Partitioning (Gap 5)
+
+**Trigger**: flash / RAM / memory / linker / bootloader / OTA / partition / NVS / EEPROM keywords AND `embedded_domain: true`.
+
+**Content**:
+- Flash regions table: Region | Start Address | Size (KB) | Usage | Notes
+- RAM regions table: Region | Start Address | Size (KB) | Usage | Notes
+- Linker constraint notes: stack size, heap size, section alignment, placement constraints
+- OTA layout diagram (simple text diagram) when OTA mentioned
+
+**notes.md YAML section**:
+```yaml
+## memory_layout
+flash_total_kb: 0
+ram_total_kb: 0
+flash_regions: []   # [{ name, start_hex, size_kb, usage, notes }]
+ram_regions: []     # [{ name, start_hex, size_kb, usage, notes }]
+linker_notes: ""
+```
+
+---
+
+##### `protocol-matrix.html` — Communication Protocol Matrix (Gap 8)
+
+**Trigger**: CAN / I2C / SPI / UART / RS-485 / BLE / Wi-Fi / LoRa / LoRaWAN / MQTT / Modbus / CANopen / USB / Zigbee keywords AND `embedded_domain: true`.
+
+**Content** (distinct from `apis.html` which covers HTTP REST):
+- Bus protocol table: Protocol | Role (master/slave/both) | Speed | Topology | Connected Devices | Notes
+- Wireless/external table: Protocol | Role | Endpoint/Broker | QoS/Notes
+- Note at top: "Embedded bus & wireless protocols — see `apis.html` for HTTP REST endpoints (if applicable)"
+
+**notes.md YAML section**:
+```yaml
+## protocols
+bus_protocols: []   # [{ name, role, speed, topology, devices: [], notes }]
+wireless: []        # [{ protocol, role, endpoint, notes }]
+```
+
+**Coexistence rule**: If the project also has a cloud API (HTTP/REST), both `protocol-matrix.html` AND `apis.html` exist in the workspace — they are separate artifacts.
+
+---
+
+##### `rtos-scheduler.html` — RTOS & Task Scheduler (Gap 3 visual)
+
+**Trigger**: RTOS / FreeRTOS / Zephyr / ThreadX / task / scheduler / semaphore / queue / ISR / interrupt priority keywords AND `embedded_domain: true`.
+
+**Content**:
+- Task table: Task Name | Priority | Period or Event | Stack KB | State | Notes
+- ISR table: Interrupt Source | Handler Function | Priority | Shared Resources | Notes
+- Mermaid `stateDiagram-v2` for key task state transitions (only if ≤5 tasks — omit if larger)
+- Shared resource matrix: Resource | Protected by | Tasks using it
+
+**notes.md**: uses `## rtos_config` section written by Task 106.1 probes (no new section — extends same YAML).
+
+---
+
+##### `power-budget.html` — Power Budget (Gap 7 visual)
+
+**Trigger**: battery / sleep / power / current / µA / mAh / Standby / Stop / Shutdown / Hibernate / LoRa / IoT keywords AND `embedded_domain: true`.
+
+**Content**:
+- Power modes table: Mode | MCU state | Active peripherals | Typical current (µA/mA) | Wake-up sources
+- Battery life estimate: Duty cycle % | Avg current (mA) | Capacity (mAh) | Runtime (days) formula
+- Power rail summary (linked from `hw-topology` if available)
+
+**notes.md**: uses `## power_budget` section written by Task 106.1 probes (no new section — extends same YAML).
+
+---
+
+#### Embedded Workspace Layout (ENH-071)
+
+When `embedded_domain: true` and Architect Mode is active, the `index.html` hub includes an **Embedded** nav section after the standard pages:
+
+```html
+<!-- Embedded section (only shown when embedded_domain: true) -->
+<a href="hw-topology.html">🔌 HW Topology</a>
+<a href="pin-map.html">📌 Pin Map</a>
+<a href="memory-layout.html">🗺️ Memory Layout</a>
+<a href="protocol-matrix.html">📡 Protocol Matrix</a>
+<a href="rtos-scheduler.html">⏱️ RTOS Scheduler</a>
+<a href="power-budget.html">🔋 Power Budget</a>
+```
+
+Pages are only linked when they have been created (missing pages are omitted from nav).
 
 #### Sequence trigger keywords (ENH-029)
 When the user mentions: `scenario`, `step by step`, `login flow`, `checkout flow`, `detailed interaction`, `sequence`, `interaction diagram` → update `sequence-diagram.html` + update `notes.md ## sequences` section.
@@ -400,6 +1295,104 @@ design_decisions:
     choice: "{JWT / Session / OAuth2 / API Key}"
     rationale: "{rationale}"
 
+## admin
+admin_personas:
+  - id: super_admin
+    capabilities: [user_management, billing, system_config, audit_log_view]
+  - id: org_admin
+    capabilities: [invite_users, role_assign, reporting]
+capabilities:
+  - id: user_management
+    required: yes
+    phase: 2
+    notes: invite, deactivate, RBAC
+  - id: audit_log
+    required: yes
+    phase: 3
+    notes: all write ops, 90-day retention
+  - id: monitoring_dashboard
+    required: optional
+    phase: 3
+    notes: error rate, latency, active users
+  - id: billing_management
+    required: no
+    phase: ~
+    notes: not in scope
+
+## content
+content_types:
+  - id: article
+    created_by: [admin, author]
+    lifecycle: [draft, review, published, archived]
+    fields: [title, body_rich_text, slug, tags, seo_meta]
+    phase: 2
+  - id: product
+    created_by: [admin]
+    lifecycle: [draft, published, discontinued]
+    fields: [name, description, price, images, category]
+    phase: 1
+media:
+  storage: S3  # S3 | GCS | Azure Blob | local
+  cdn: CloudFront
+  types: [image, pdf]
+  max_size_mb: 10
+localization:
+  locales: [en]
+  fallback: en
+search:
+  engine: postgres_fts  # postgres_fts | Elasticsearch | Algolia | Typesense
+  full_text: yes
+  facets: [category, tags]
+
+## user_data
+profile_fields:
+  - name
+  - email
+  - avatar_url
+  - timezone
+  - locale
+settings_categories:
+  - id: notifications
+    channels: [email, push, in_app]
+    frequency: [immediately, daily_digest, weekly]
+  - id: privacy
+    fields: [data_visibility, analytics_opt_out]
+privacy_rights:
+  data_export: yes
+  right_to_erasure: yes
+  data_retention_days: 730
+connected_accounts:
+  - provider: google
+    scope: [email, profile]
+  - provider: github
+    scope: [read:user, user:email]
+session_management:
+  multi_session: yes
+  show_active_devices: yes
+  force_logout_all: yes
+two_factor:
+  totp: yes
+  sms: no
+  backup_codes: yes
+
+## entity_mgmt
+entities:
+  - name: product
+    admin_crud: [create, read, update, delete]
+    soft_delete: yes
+    bulk_actions: [export, status_change]
+    audit_trail: yes
+    scoped_by: org
+  - name: order
+    admin_crud: [read, update]
+    soft_delete: no
+    bulk_actions: [export]
+    audit_trail: yes
+    scoped_by: org
+import_export:
+  csv_import: [product]
+  csv_export: [product, order, user]
+
 ## architect_sync
 - synced_at: "{ISO datetime}"
   source_session: "{ui-direction session-id}"
@@ -420,9 +1413,45 @@ When the assistant detects any keyword (case-insensitive, Vietnamese or English)
 
 > `màu`, `màu sắc`, `color`, `layout`, `màn hình`, `screen`, `page`, `trang`, `button`, `nút`, `form`, `biểu mẫu`, `mobile`, `responsive`, `giao diện`, `UI`, `UX`, `design`, `dashboard`, `sidebar`, `header`, `footer`, `modal`, `popup`, `icon`, `theme`, `typography`, `font`, `spacing`, `grid`, `card`, `component`, `hero`, `banner`
 
+#### Embedded Domain UI Suppression (ENH-071 Gap 6)
+
+**Before adding any keyword to the UI buffer**, check if `embedded_domain: true`.
+
+If `embedded_domain: true` AND keyword is a display/screen word (`display`, `screen`, `LCD`, `OLED`, `TFT`, `touch`):
+
+1. Check for **hardware context counter-keywords** in the same message or nearby context:
+   - Hardware indicators: `GPIO`, `SPI`, `I2C`, `driver`, `framebuffer`, `ILI9341`, `SSD1306`, `ST7789`, `HX8357`, `RA8875`, `E-Ink`, `EPD`, `7-segment`, `LVGL`, `u8g2`, `resolution`, `pixel`, `backlight`, `contrast`, `init sequence`
+
+2. **If hardware context confirmed**:
+   - Do NOT add to `ui_idea_buffer[]`
+   - Add as peripheral to `hw_topology_buffer[]` instead: `{ type: "display", interface: "SPI/I2C/parallel", part: "{detected_part_if_any}" }`
+   - Log silently: "Display keyword suppressed from UI Direction → added to hw-topology peripherals"
+
+3. **If ambiguous** (no hardware counter-keywords, could be web dashboard):
+   - Add to `ui_idea_buffer[]` normally with note: `"context: may be hardware display — verify"`
+
+4. **Early-session UI Direction banner (ENH-060) suppression**:
+   - If `embedded_domain: true` AND all accumulated display signals have hardware context → **suppress** the `🎨 UI Direction Mode?` banner entirely
+   - Replace with a one-time note: `"Hardware displays detected — will appear in hw-topology page"`
+   - If signals are mixed (some hardware, some ambiguous) → show banner but prepend: `"⚠️ Embedded context detected — confirm if this is a web/mobile UI or hardware display"`
+
+#### Early-session detection (ENH-060)
+At the very start of a brainstorm session, scan the user's **initial message** for UI/UX signal keywords. If **≥1 keyword** is found AND `embedded_domain` is NOT active, show the proactive activation banner **immediately** (before topic selection):
+
+```
+🎨 I noticed your project involves UI/UX design.
+Would you like to activate UI Direction Mode? I can generate an HTML prototype direction alongside our brainstorm.
+
+1. Yes — activate UI Direction Mode (create .viepilot/ui-direction/{session-id}/)
+2. Save ideas to notes only (background, no HTML yet)
+3. No — continue brainstorm without UI Direction
+```
+
+This mirrors **Architect Design Mode** which proactively banners when system architecture heuristics fire.
+
 #### Threshold & accumulation rule
 - **Count unique keyword occurrences** during the ongoing session.
-- When **≥3 unique signal occurrences** are reached: begin **silent accumulation** — record UI ideas into a `ui_idea_buffer[]` in the session context.
+- When **≥1 signal occurrence** is detected: begin **silent accumulation** — record UI ideas into a `ui_idea_buffer[]` in the session context.
 - **Non-blocking**: does not interrupt the main conversation, does not ask for user confirmation immediately.
 - Each buffer entry records: keyword trigger, utterance context (short summary ≤20 words).
 
@@ -430,19 +1459,19 @@ When the assistant detects any keyword (case-insensitive, Vietnamese or English)
 Display a confirmation dialogue when any of the following conditions occur:
 - (a) **Topic ends** — user types `/topic` to switch to a new topic or says "next"
 - (b) **User types `/save` or `/review`**
-- (c) **≥5 signals accumulated** in the buffer
+- (c) **≥2 unique signals accumulated** in the buffer
 
 #### Confirmation dialogue template
 ```
-💡 I detected some UI ideas in this session:
+🎨 I noticed UI/UX design ideas in this session:
 - {idea 1 extracted from buffer}
 - {idea 2 extracted from buffer}
 ...
 
-What would you like to do?
-1. Save to .viepilot/ui-direction/{session-id}/notes.md (background extraction)
-2. Save + activate UI Direction Mode to generate HTML direction
-3. Discard and continue brainstorming
+Would you like to activate UI Direction Mode?
+1. Save to .viepilot/ui-direction/{session-id}/notes.md (background, no HTML yet)
+2. Save + activate UI Direction Mode (create .viepilot/ui-direction/{session-id}/, generate HTML direction)
+3. No — discard and continue brainstorming
 ```
 
 **Option 1**: Write `## Background extracted ideas` to `.viepilot/ui-direction/{session-id}/notes.md` (create file/directory if not yet present). Clear buffer. Continue.
@@ -604,6 +1633,8 @@ Before writing the session file, validate phase assignment completeness:
 CHECK 1: Does session draft contain a non-empty ## Phases section?
 CHECK 2: Does Phase 1 have at least one feature/capability assigned?
 CHECK 3: Are there any features listed outside a phase (unassigned)?
+CHECK 4 (ENH-061): If both Architect workspace AND UI Direction workspace are active —
+         does ## Coverage in notes.md have any Phase 1 feature with "none yet" in BOTH columns?
 ```
 
 **Gate condition:**
@@ -625,8 +1656,40 @@ CHECK 3: Are there any features listed outside a phase (unassigned)?
   > ⚠️ Exploratory session — no phase assignments yet.
   > Run /vp-brainstorm to continue and assign features to phases before /vp-crystallize.
   ```
+- If CHECK 4 fires (both workspaces active + uncovered Phase 1 features): **non-blocking warning**:
+  ```
+  ⚠️  Coverage gap detected — these Phase 1 features have no Architect or UI coverage:
+  - {feature name}
+  Consider running /sync-ui or adding these features to a workspace before /vp-crystallize.
+  Proceed with save? (yes / skip coverage for now)
+  ```
 - If brownfield stub session (`IS_BROWNFIELD=true`): **skip this gate** — brownfield stubs intentionally have no phases.
-- If all checks pass → proceed to file write below.
+- If all checks pass → proceed to Feature → Coverage Mapping check, then file write.
+
+### Feature → Coverage Mapping (ENH-061)
+
+**Trigger**: After phase assignment checks pass and before file write. Runs when the session has BOTH Architect workspace AND UI Direction workspace active, or when `## Coverage` already exists in notes.md.
+
+For each feature/capability listed under **Phase 1** in the session draft, identify:
+- **Architect coverage**: which architect page handles this? (`architecture`, `data-flow`, `erd`, `apis`, `tech-stack`, `decisions`, `user-use-cases`, `sequence-diagram`, `deployment`, or `none yet`)
+- **UI coverage**: which UI screen/page handles this? (page slug, `index.html`, or `none yet`)
+
+Output a `## Coverage` section in `notes.md`:
+
+```markdown
+## Coverage
+| Feature | Architect page | UI screen |
+|---------|---------------|-----------|
+| User authentication | architecture, apis | login.html, register.html |
+| Dashboard overview | data-flow | dashboard.html |
+| Notification system | architecture | none yet |
+```
+
+**Warning rules (non-blocking)**:
+- If a Phase 1 feature has `none yet` in **both** columns:
+  `⚠️ Feature "{name}" has no coverage in Architect or UI Direction. Consider adding it to a workspace before /vp-crystallize.`
+- If Architect workspace exists but coverage matrix is empty: suggest running coverage mapping.
+- User can dismiss with "skip coverage" or "fill in later" — does **not** block save.
 
 Create/update file: `docs/brainstorm/session-{YYYY-MM-DD}.md`
 
@@ -637,6 +1700,12 @@ Create/update file: `docs/brainstorm/session-{YYYY-MM-DD}.md`
 - **Date**: {full date}
 - **Participants**: User, Claude
 - **Status**: In Progress | Completed
+- **workflow_version**: {viepilot_semver}
+- **upgrade_supplement_version**: {viepilot_semver_after_supplement | ""}
+
+<!-- workflow_version: set from `node bin/vp-tools.cjs info` → version field at session create/save time.       -->
+<!-- upgrade_supplement_version: empty on first save; set to current version after gap-detection supplement      -->
+<!--   completes (ENH-067 idempotency guard — prevents re-surfacing already-supplemented topics on next open). -->
 
 ## Phases
 
@@ -742,6 +1811,99 @@ git push
 ```
 </step>
 
+<step name="arch_to_ui_sync">
+## 6C. Architect → UI Direction Sync (ENH-061)
+
+Bridges the gap from **Architect Design** → **UI Direction** — the reverse of `architect_delta_sync` (ENH-034, which syncs UI → Architect).
+
+When the architect workspace is updated (any page edit during the session), scan the changed content for decisions that carry **UI implications**:
+
+### Architectural decisions that trigger UI updates
+
+| Architect signal | UI implication to check |
+|-----------------|------------------------|
+| Async / event-driven flow | Loading states, optimistic updates, error handling screens |
+| API pagination | Pagination component, empty state, scroll-to-load |
+| Auth roles / permissions | Conditional UI rendering, role-specific screens |
+| Rate limiting / quota | Warning banners, upgrade prompts, disabled states |
+| Real-time → polling fallback | Refresh indicators, stale data warnings |
+| File size / type constraints | Upload validation, error messages, progress indicators |
+| Third-party OAuth / SSO | Redirect flow, consent screen, token expiry handling |
+| Error codes from APIs | Error state screens, retry affordances |
+| Data constraints (max length, required fields) | Form validation UI, helper text |
+
+### Trigger conditions
+`arch_to_ui_sync` fires when:
+- The user edits any architect workspace page during an active brainstorm session that also has a UI Direction workspace
+- User types `/sync-ui` (manual trigger, parallel to `/sync-arch`)
+- After `/review-arch` if changes were applied
+
+### Output format
+```
+🎨 Architect → UI sync — detected implications:
+
+From `data-flow.html` (async notification queue):
+  → UI may need: notification badge with unread count, real-time update indicator, empty state
+  → Affected screens: dashboard.html (not yet modeled in UI Direction)
+
+Update UI Direction to reflect these decisions?
+1. Yes — open UI Direction and address these screens/states now
+2. Note it in notes.md (## arch_to_ui_sync) for later
+3. Skip — already handled
+```
+
+### Manual command
+`/sync-ui` — manually trigger arch_to_ui_sync from the current architect session state. If no UI Direction workspace is active, suggest activating it first.
+
+When `/sync-ui` is used and no implications are found:
+`✓ No UI Direction implications detected from current architect changes.`
+
+### notes.md record
+Append to `notes.md` when action is taken:
+```yaml
+## arch_to_ui_sync
+- architect_page: data-flow.html
+  decision: async notification queue
+  ui_implication: unread count badge, empty state, real-time update indicator
+  status: noted | addressed | skipped
+  date: {YYYY-MM-DD}
+```
+
+### Cross-workspace HUB links (ENH-064)
+
+When BOTH architect AND ui-direction workspaces are active in the same session:
+After `arch_to_ui_sync` completes (or when both workspaces first become active together):
+
+**Update Architect `index.html`** — add to nav/header section:
+```html
+<div class="cross-workspace-link">
+  <a href="../../ui-direction/{session-id}/index.html" target="_blank">
+    🎨 View UI Direction workspace
+  </a>
+</div>
+```
+
+**Update UI Direction `index.html`** — add to nav/header section:
+```html
+<div class="cross-workspace-link">
+  <a href="../../architect/{session-id}/index.html" target="_blank">
+    🏗️ View Architect workspace
+  </a>
+</div>
+```
+
+**Trigger conditions:**
+- After arch_to_ui_sync fires (ENH-061)
+- When BUG-018 Step 2B selection is "Both" and both workspaces are created
+- Manual: user types `/sync-links`
+
+**Relative path calculation:**
+- From `.viepilot/architect/{session-id}/index.html` → `../../ui-direction/{session-id}/index.html`
+- From `.viepilot/ui-direction/{session-id}/index.html` → `../../architect/{session-id}/index.html`
+- Use the same `{session-id}` (same date YYYY-MM-DD) for cross-linking.
+
+</step>
+
 <step name="architect_delta_sync">
 ## 6B. Architect Delta Sync (ENH-034)
 
@@ -899,6 +2061,7 @@ User can use the following commands during a brainstorm session:
 - `/research ui` — alias of `/research-ui`
 - `/review-arch` — Architect Mode: output summary table of decisions + open_questions from `notes.md`, confirm before continuing (FEAT-011)
 - `/sync-arch` — Architect Delta Sync (ENH-034): manually trigger architect HTML sync from current UI brainstorm session; scans session for architect gaps → updates relevant architect workspace pages
+- `/sync-ui` — Architect → UI Direction Sync (ENH-061): manually trigger arch_to_ui_sync; scans architect workspace for decisions that carry UI implications and prompts UI Direction updates
 - `/hooks-install` — Install the brainstorm staleness hook (FEAT-012): runs `vp-tools hooks install`; one-time setup per machine; auto-marks stale architect items after each AI response
 </commands>