# Status Setup Specification

## Overview

A fullscreen configuration interface for customizing the status area layout. Users can arrange widgets across multiple rows, preview changes in real-time, and persist their configuration.

## Command

```
/config status-setup
```

Alias: `/status-setup`

Opens fullscreen status configuration mode using the existing UI design system and config widget framework.

## UI Layout

```
+==============================================================================+
|  STATUS SETUP                                                    Ctrl+S save |
+==============================================================================+
|                                                                              |
|  LIVE PREVIEW                                                                |
|  +------------------------------------------------------------------------+  |
|  | cwd ~/dev/kollabor  | * Ready | glm-4.7 @ api.z.ai | 5 msg | 1.2K tok |  |
|  | ⌁ default-agent     | skill1  | skill2  | +3 skills                   |  |
|  +------------------------------------------------------------------------+  |
|                                                                              |
|  ROWS                                                            visible: 2  |
|  +------------------------------------------------------------------------+  |
|  | > Row 1: [cwd] [status] [model] [stats] [+]                            |  |
|  |   Row 2: [agent] [skills] [+]                                          |  |
|  |   Row 3: [+]                                            (hidden)       |  |
|  |   Row 4: [+]                                            (hidden)       |  |
|  |   ---                                                                  |  |
|  |   + Add row (up to 6)                                                  |  |
|  +------------------------------------------------------------------------+  |
|                                                                              |
|  WIDGETS                                                                     |
|  +------------------------------------------------------------------------+  |
|  |  (select a row and press Enter, then [+] to add widgets)               |  |
|  +------------------------------------------------------------------------+  |
|                                                                              |
+------------------------------------------------------------------------------+
|  arrows: navigate | Enter: select | Esc: back/exit | Ctrl+S: save            |
+------------------------------------------------------------------------------+
```

## Navigation Model

### Level 1: Row Selection

When entering status-setup, cursor is on Row 1.

```
Controls:
  Up/Down     Move between rows
  Enter       Enter row edit mode (Level 2)
  Esc         Exit status-setup (prompts to save if changed)
  Ctrl+S      Save configuration
```

Visual state:
```
  > Row 1: [cwd] [status] [model] [stats] [+]      <-- cursor here (highlighted)
    Row 2: [agent] [skills] [+]
    Row 3: [+]                         (hidden)
    Row 4: [+]                         (hidden)
```

### Level 2: Widget Selection (within a row)

After pressing Enter on a row, cursor moves to first widget in that row.

```
Controls:
  Left/Right  Move between widgets in row
  Enter       On widget: show widget options (Level 3)
              On [+]: enter widget picker (Level 4)
  Esc         Return to row selection (Level 1)
```

Visual state:
```
  Row 1: [[cwd]] [status] [model] [stats] [+]
          ^^^^^
          cursor on this widget (highlighted)
```

### Level 3: Widget Options

After pressing Enter on an existing widget.

```
+---------------------------+
|  Widget: cwd              |
+---------------------------+
|  > Delete                 |
|    Configure...           |  (if widget has options)
|    Move left              |
|    Move right             |
+---------------------------+
```

```
Controls:
  Up/Down     Navigate options
  Enter       Execute selected option
  Esc         Cancel, return to widget selection (Level 2)
```

### Level 4: Widget Picker

After pressing Enter on [+] button.

```
+==============================================================================+
|  ADD WIDGET TO ROW 1                                             Esc: cancel |
+==============================================================================+
|                                                                              |
|  PREVIEW                                                                     |
|  +------------------------------------------------------------------------+  |
|  |  ~/dev/kollabor-cli                                                    |  |
|  +------------------------------------------------------------------------+  |
|                                                                              |
|  AVAILABLE WIDGETS                                                           |
|  +--------------------------------+  +------------------------------------+  |
|  |  CORE                          |  |  PLUGINS                           |  |
|  |  > cwd          current dir    |  |    tmux         session count      |  |
|  |    profile      LLM profile    |  |    git-branch   current branch     |  |
|  |    model        model name     |  |    bg-tasks     background tasks   |  |
|  |    endpoint     API endpoint   |  |    memory       memory usage       |  |
|  |    status       Ready/Working  |  |                                    |  |
|  |    stats        msg/token cnt  |  |                                    |  |
|  |    agent        active agent   |  |                                    |  |
|  |    skills       active skills  |  |                                    |  |
|  |    tasks        task info      |  |                                    |  |
|  +--------------------------------+  +------------------------------------+  |
|                                                                              |
+------------------------------------------------------------------------------+
|  Up/Down: browse | Enter: add widget | Tab: switch column | Esc: cancel      |
+------------------------------------------------------------------------------+
```

```
Controls:
  Up/Down     Navigate widget list
  Tab         Switch between Core/Plugins columns
  Enter       Add selected widget to row, return to row edit (Level 2)
  Esc         Cancel, return to row edit (Level 2)
```

As cursor moves through widget list, the PREVIEW panel updates to show what that widget looks like with current data.

## Row Visibility

Rows 1-4 are always present in the editor but can be marked as visible or hidden.

```
  Row 1: [cwd] [status] [+]                          (visible - rendered)
  Row 2: [agent] [+]                                 (visible - rendered)
  Row 3: [+]                              (hidden)   (not rendered)
  Row 4: [+]                              (hidden)   (not rendered)
```

Toggle visibility:
- When cursor is on a row in Level 1, press `v` to toggle visibility
- Or in widget options, add "Hide row" / "Show row" option
- Rows with widgets cannot be hidden (must remove widgets first)

Adding rows beyond 4:
- Navigate past Row 4 to "+ Add row"
- Press Enter to add Row 5 (up to 6 max)
- Rows 5-6 start as hidden until configured

## Widget Sizing

Each widget has a width that can be:
- **Auto**: widget determines its own width based on content
- **Relative**: percentage of row width (e.g., 25%)
- **Fixed**: absolute character count (e.g., 20 chars)

Configure in Level 3 (Widget Options):
```
+---------------------------+
|  Widget: cwd              |
+---------------------------+
|    Delete                 |
|  > Configure...           |
|    Move left              |
|    Move right             |
+---------------------------+

        |
        v (Enter on Configure)

+---------------------------+
|  Configure: cwd           |
+---------------------------+
|  Width:                   |
|  > [x] Auto               |
|    [ ] Relative: [25 ]%   |
|    [ ] Fixed:    [20 ]ch  |
+---------------------------+
```

## Widget Registry

### Core Widgets

| ID | Name | Description | Default Width |
|----|------|-------------|---------------|
| `cwd` | Current Directory | Working directory path | auto |
| `profile` | Profile | Active LLM profile name | auto |
| `model` | Model | Model name | auto |
| `endpoint` | Endpoint | API endpoint hostname | auto |
| `status` | Status | Ready/Working indicator | auto |
| `stats` | Stats | Message count, token count | auto |
| `agent` | Agent | Active agent name | auto |
| `skills` | Skills | Active skills list | auto |
| `tasks` | Tasks | Current task info | auto |
| `clock` | Clock | Current time | fixed 8ch |

### Plugin Widgets

Plugins register widgets via the StatusWidgetRegistry:

```python
class MyPlugin(BasePlugin):
    def register_hooks(self):
        # Register a status widget
        self.status_widget_registry.register(
            id="my-widget",
            name="My Widget",
            description="Shows custom info",
            render_fn=self._render_widget,
            default_width="auto",  # or "25%" or "20ch"
            category="plugins",
        )

    def _render_widget(self, width: int) -> str:
        """Render widget content to fit within width."""
        return "custom content"
```

## Data Model

### Configuration Schema

Stored in `~/.kollabor-cli/config.json` under `status_layout`:

```json
{
  "status_layout": {
    "version": 1,
    "rows": [
      {
        "id": 1,
        "visible": true,
        "widgets": [
          {"id": "cwd", "width": {"type": "relative", "value": 25}},
          {"id": "status", "width": {"type": "auto"}},
          {"id": "model", "width": {"type": "auto"}},
          {"id": "stats", "width": {"type": "relative", "value": 30}}
        ]
      },
      {
        "id": 2,
        "visible": true,
        "widgets": [
          {"id": "agent", "width": {"type": "auto"}},
          {"id": "skills", "width": {"type": "auto"}}
        ]
      },
      {
        "id": 3,
        "visible": false,
        "widgets": []
      },
      {
        "id": 4,
        "visible": false,
        "widgets": []
      }
    ],
    "backup": { ... }  // Previous configuration for restore
  }
}
```

### Default Layout

If no configuration exists:

```json
{
  "rows": [
    {
      "id": 1,
      "visible": true,
      "widgets": [
        {"id": "cwd", "width": {"type": "auto"}},
        {"id": "profile", "width": {"type": "auto"}},
        {"id": "model", "width": {"type": "auto"}},
        {"id": "status", "width": {"type": "auto"}},
        {"id": "stats", "width": {"type": "auto"}}
      ]
    }
  ]
}
```

## Save and Restore

### Saving

- **Ctrl+S**: Explicit save, shows confirmation
- **Exit**: Prompts "Save changes? [Y]es / [N]o / [C]ancel"
- Before saving, current config is copied to `backup`

### Restore

In the status-setup UI, add option:
```
  Row 4: [+]                              (hidden)
  ---
  + Add row (up to 6)
  ---
  [Restore previous layout]              <-- restores from backup
  [Reset to default]                     <-- restores factory default
```

## Implementation Plan

### Phase 1: Widget Registry
- [ ] Create `StatusWidgetRegistry` class
- [ ] Register core widgets with render functions
- [ ] Update `StatusRenderer` to use registry

### Phase 2: Layout Model
- [ ] Define layout data model
- [ ] Add to config schema
- [ ] Create layout manager (load/save/validate)
- [ ] Update `StatusRenderer` to read from layout config

### Phase 3: Status Setup UI
- [ ] Create `/config status-setup` command
- [ ] Build fullscreen modal using existing UI framework
- [ ] Implement Level 1: Row selection
- [ ] Implement Level 2: Widget selection
- [ ] Implement Level 3: Widget options
- [ ] Implement Level 4: Widget picker
- [ ] Real-time preview rendering
- [ ] Save/restore functionality

### Phase 4: Plugin API
- [ ] Document widget registration API
- [ ] Create example plugin widget
- [ ] Add widget discovery from plugins

## File Structure

```
core/
  io/
    status/
      __init__.py
      widget_registry.py      # StatusWidgetRegistry
      layout_manager.py       # Layout load/save/validate
      layout_renderer.py      # Render layout to terminal
      core_widgets.py         # Core widget implementations
  commands/
    config_commands.py        # Add status-setup subcommand
  ui/
    status_setup/
      __init__.py
      setup_modal.py          # Main fullscreen modal
      row_editor.py           # Row selection/editing
      widget_picker.py        # Widget picker panel
      preview_panel.py        # Live preview rendering
```

## Keyboard Reference

| Context | Key | Action |
|---------|-----|--------|
| Row selection | Up/Down | Navigate rows |
| Row selection | Enter | Edit row widgets |
| Row selection | v | Toggle row visibility |
| Row selection | Esc | Exit (prompt save) |
| Row selection | Ctrl+S | Save configuration |
| Widget selection | Left/Right | Navigate widgets |
| Widget selection | Enter | Widget options / Add widget |
| Widget selection | Esc | Back to row selection |
| Widget options | Up/Down | Navigate options |
| Widget options | Enter | Execute option |
| Widget options | Esc | Cancel |
| Widget picker | Up/Down | Browse widgets |
| Widget picker | Tab | Switch Core/Plugins |
| Widget picker | Enter | Add widget |
| Widget picker | Esc | Cancel |

## Visual Design

Uses existing design system components:
- `Box` for panels and borders
- `T()` theme colors
- Highlight color for cursor position
- Dim color for hidden/inactive elements
- `solid()` / `gradient()` for widget backgrounds in preview
