# Progressive Disclosure Implementation Plan

This plan details the implementation of progressive disclosure across the SOPHIAClaw macOS app and relevant configuration systems, fulfilling the requirements specified in the Community Edition Todo.

## 1. Data Model & State Changes

We need to add a global "Expert Mode" toggle that will dictate the visibility of advanced configuration options.

- **File to modify:** `apps/macos/Sources/SOPHIAClaw/Models/Phase3Models.swift`
  - Update `GatewayConfiguration` to include `var isExpertModeEnabled: Bool = false`.
- **File to modify:** `apps/macos/Sources/SOPHIAClaw/Core/AppState.swift`
  - Update `loadConfiguration()` and `saveConfiguration()` to persist `isExpertModeEnabled` in `sophiaclaw.json`.
- **File to modify (CLI config):** `src/config/zod-schema.ts`
  - Update the `ui` section of `SophiaClawSchema` to include `expertMode: z.boolean().optional()` so the CLI configuration system matches the application state.

## 2. Settings UI Restructuring

The goal is to hide complex features by default and reveal them only when the "Expert Mode" is enabled.

- **File to modify:** `apps/macos/Sources/SOPHIAClaw/UI/Settings/SettingsView.swift` & `SimplePreferences.swift`
  - **General Tab:**
    - Add a new toggle: `Toggle("Enable Expert Mode", isOn: $state.gatewayConfig.isExpertModeEnabled)`.
    - Add a helpful tooltip: `.help("Shows advanced configuration options, custom secrets, and terminal settings.")`.
  - **Tab Bar Visibility:**
    - Conditionally render the `Advanced` tab in the `TabView` based on `isExpertModeEnabled`.
    - If `!isExpertModeEnabled`, the "Advanced" tab is completely hidden.

  - **Security Tab:**
    - Show standard API Keys (OpenAI, Anthropic, ElevenLabs) by default.
    - Hide the "Environment Secrets" section (custom environment variables like `GATEWAY_TOKEN` or custom presets) behind `if state.gatewayConfig.isExpertModeEnabled { ... }`.
    - Hide "Folder Permissions" (allowed directories) behind the expert mode check.

  - **Governance Tab:**
    - Keep "Explicit Deny List" visible.
    - Hide "Terminal & Shell Permissions" behind expert mode. (Power users need this, but novice users might find shell execution contexts confusing).
    - Hide "Custom User Rules" behind expert mode.

  - **Voice Tab:**
    - Hide detailed "Feedback Sounds" (acknowledgment and capture chimes) and "Testing & Calibration" sections unless expert mode is on.
    - Hide "Voice Stability" sliders for ElevenLabs unless expert mode is enabled.

## 3. Contextual Help System

To improve clarity, we will add inline explanations and "Learn more" links to complex features.

- **Implement a reusable `HelpTooltip` component:**

  ```swift
  struct HelpIcon: View {
      let text: String
      let link: String?

      var body: some View {
          Image(systemName: "info.circle")
              .foregroundColor(.secondary)
              .help(text)
              .onTapGesture {
                  if let link = link, let url = URL(string: link) {
                      NSWorkspace.shared.open(url)
                  }
              }
      }
  }
  ```

- **Apply to Complex Features:**
  - _System Run Settings:_ Add `HelpIcon(text: "Controls which commands require explicit human approval.", link: "https://docs.sophiaclaw.ai/governance")`.
  - _Mobile App Pairing:_ Add a clear "Learn more" link pointing to `https://docs.sophiaclaw.ai/platforms/ios`.
  - _Gateway Binding:_ Next to host/port settings in the Advanced tab, explain Loopback vs. LAN binding.

## 4. CLI Setup Wizard Enhancements

- **File to modify:** `src/commands/configure.wizard.ts`
  - Update the setup wizard. If the user does not pass an `--expert` flag (or standard defaults apply), skip complex configuration prompts like changing the `daemon` port, explicit `web` tool search configurations, or verbose network bindings.
  - Only show these prompts if the user explicitly asks to configure the "Advanced Gateway" section.

## 5. User Testing Strategy

To validate the progressive disclosure design:

1.  **A/B Testing Flow:**
    - Task Group A: Configure API keys and pair mobile app (Expert Mode OFF).
    - Task Group B: Configure API keys, add custom environment variables, and change gateway port (Expert Mode ON).
2.  **Metrics to Track:**
    - Time to complete basic onboarding.
    - Number of support questions related to "where is the API key setting?" vs "what does custom bind host mean?".
3.  **Iteration:** Based on testing, adjust which settings are considered "Advanced" vs "Basic". Ensure the "Enable Expert Mode" toggle is easily discoverable in the General settings.