docs(agent-ui): legacy baseline 문서를 정규화한다

agent-ui/README.md

@@ -0,0 +1,28 @@
+---
+ui_doc_type: readme
+surface_type: ops-dev
+---
+
+# agent-ui
+
+이 디렉터리는 AI agent와 사람이 NomadCode UI 의도, 화면 구조, 와이어프레임, 반복 구성요소를 동기화하기 위한 작업 문맥 저장소다.
+
+## 대상
+
+- 1차 대상: ops/dev UI
+- 현재 기준: Flutter-first NomadCode workbench와 workspace management surface
+- 확장 후보: product UI layer, provider console slot, visual frame source
+
+## 구조
+
+- `definition/`: 현재 UI 정의 source of truth
+- `frame/`: visual source가 있는 view의 wireframe 연결
+- `USER_REVIEW.md`: 사용자 판단이 필요한 활성 질문
+- `archive/user-review/`: 해결된 사용자 리뷰 로그
+
+## 기본 규칙
+
+- 현재 기준은 `definition/**`에 둔다.
+- visual wireframe은 visual source가 있을 때만 `frame/**`에 둔다.
+- `.excalidraw` 파일만으로 UI 기준을 확정하지 않는다.
+- `definition/archive/**`와 `archive/user-review/**`는 과거 기록이며 일반 작업에서 읽지 않는다.

agent-ui/archive/user-review/.gitkeep

@@ -0,0 +1 @@
+

agent-ui/definition/archive/components/.gitkeep

@@ -0,0 +1 @@
+

agent-ui/definition/archive/views/.gitkeep

@@ -0,0 +1 @@
+

agent-ui/definition/components/activity-rail/index.md

@@ -0,0 +1,69 @@
+---
+ui_doc_type: component
+component_id: activity-rail
+status: 구현됨
+source_evidence:
+  - type: code
+    path: apps/client/lib/src/app/nomadcode_workbench_shell.dart
+    notes: _WorkbenchActivityRail과 _RailButton 구현.
+  - type: docs
+    path: apps/client/README.md
+    notes: right-side activity rail과 IOP entry 위치 설명.
+  - type: user
+    path: null
+    notes: agent-ui 생성 요청.
+---
+
+# Activity Rail
+
+Component ID: `activity-rail`
+
+Status: `구현됨`
+
+## Source Evidence
+
+| Type | Path | Notes |
+|------|------|-------|
+| code | `apps/client/lib/src/app/nomadcode_workbench_shell.dart` | _WorkbenchActivityRail과 _RailButton 구현. |
+| docs | `apps/client/README.md` | right-side activity rail과 IOP entry 위치 설명. |
+| user | 없음 | agent-ui 생성 요청. |
+
+## Purpose
+
+Workbench 우측에서 Agent dock toggle과 주요 product section 전환을 제공한다.
+
+## Used By
+
+- `workbench-shell`: `workbench-shell.activity-rail`
+
+## Anatomy
+
+- Agent toggle button
+- Product section buttons: Workspace, Workflow, Terminal, Review, Web Context
+- Bottom utility buttons: Settings, IOP
+- Tooltip labels
+- Selected visual state
+
+## Variants
+
+- default: 60px fixed-width rail
+
+## States
+
+- default
+- selected
+- agent-open
+- loading: 없음
+- empty: 없음
+- error: 없음
+- disabled: 없음
+
+## Rules
+
+- Agent button은 section selection과 별도 상태를 갖는다.
+- section button 선택 시 중앙 content를 전환하고 Agent dock을 닫는다.
+- IOP entry는 rail 하단에 유지한다.
+
+## Decision History
+
+- 2026-06-24: workbench shell의 구현된 activity rail을 component로 등록했다.

agent-ui/definition/components/agent-dock-panel/index.md

@@ -0,0 +1,71 @@
+---
+ui_doc_type: component
+component_id: agent-dock-panel
+status: 구현됨
+source_evidence:
+  - type: code
+    path: apps/client/lib/src/app/nomadcode_workbench_shell.dart
+    notes: _AgentDockPanel이 agent_shell package의 AgentShell을 mount한다.
+  - type: docs
+    path: README.md
+    notes: Agent dock은 공통 agent_shell package를 사용한다는 제품 경계.
+  - type: docs
+    path: apps/client/README.md
+    notes: Agent dock panel attached to the right rail 설명.
+  - type: user
+    path: null
+    notes: agent-ui 생성 요청.
+---
+
+# Agent Dock Panel
+
+Component ID: `agent-dock-panel`
+
+Status: `구현됨`
+
+## Source Evidence
+
+| Type | Path | Notes |
+|------|------|-------|
+| code | `apps/client/lib/src/app/nomadcode_workbench_shell.dart` | _AgentDockPanel이 agent_shell package의 AgentShell을 mount한다. |
+| docs | `README.md` | Agent dock은 공통 agent_shell package를 사용한다는 제품 경계. |
+| docs | `apps/client/README.md` | Agent dock panel attached to the right rail 설명. |
+| user | 없음 | agent-ui 생성 요청. |
+
+## Purpose
+
+Workbench 우측 rail에 붙는 agent interaction surface를 제공한다. NomadCode-specific workflow logic은 shell 밖의 product section이나 future integration에서 다루고, dock 자체는 `agent_shell` 기반 공통 대화 표면으로 유지한다.
+
+## Used By
+
+- `workbench-shell`: `workbench-shell.agent-dock`
+
+## Anatomy
+
+- Right-side bordered panel
+- `AgentShell`
+- Initial assistant message
+- Input placeholder
+
+## Variants
+
+- default: desktop attached panel
+- compact: width가 좁으면 center content를 숨기고 dock width를 우선한다.
+
+## States
+
+- default
+- closed: rail state로만 표현되며 panel은 render되지 않는다.
+- loading: AgentShell 내부 정책을 따른다.
+- empty: initial message가 기본으로 존재한다.
+- error: AgentShell 내부 정책을 따른다.
+- disabled: 없음
+
+## Rules
+
+- dock open/closed 상태는 workbench shell이 소유한다.
+- `agent_shell` package에 NomadCode-specific workflow, web context, IOP product logic을 넣지 않는다.
+
+## Decision History
+
+- 2026-06-24: 구현된 Agent dock panel을 component로 등록했다.

agent-ui/definition/components/index.md

@@ -0,0 +1,31 @@
+---
+ui_doc_type: components-index
+components:
+  - workbench-titlebar
+  - activity-rail
+  - agent-dock-panel
+  - workspace-list
+  - workspace-task-list
+  - status-chip
+  - proto-socket-diagnostics
+---
+
+# Component Definitions
+
+## Component List
+
+| Component ID | Status | Evidence | Description |
+|--------------|--------|----------|-------------|
+| `workbench-titlebar` | 구현됨 | `apps/client/lib/src/app/nomadcode_workbench_shell.dart` | Console brand mark, title, current section label을 표시하는 shell 상단 바. |
+| `activity-rail` | 구현됨 | `apps/client/lib/src/app/nomadcode_workbench_shell.dart` | Agent toggle과 product section 전환을 담당하는 우측 icon rail. |
+| `agent-dock-panel` | 구현됨 | `apps/client/lib/src/app/nomadcode_workbench_shell.dart` | 우측 rail에 붙는 AgentShell 기반 agent dock. |
+| `workspace-list` | 구현됨 | `apps/client/lib/src/features/workspaces/presentation/workspace_home_page.dart` | ProjectWorkspace 목록과 선택 상태를 표시하는 리스트. |
+| `workspace-task-list` | 구현됨 | `apps/client/lib/src/features/workspaces/presentation/workspace_home_page.dart` | Mock 또는 proto-socket task service에서 온 active task rows와 loading/empty/error 상태. |
+| `status-chip` | 구현됨 | `apps/client/lib/src/features/workspaces/presentation/workspace_home_page.dart` | Project/task status를 compact pill로 표시하는 상태 요소. |
+| `proto-socket-diagnostics` | 구현됨 | `apps/client/lib/src/features/workspaces/presentation/workspace_home_page.dart` | Proto-socket lifecycle diagnostics를 chip 묶음으로 표시하는 진단 영역. |
+
+## Rules
+
+- component 정의는 구현 API가 아니라 UI 사용 규칙을 다룬다.
+- view별 변형이 필요하면 `<component-id>/<variant>.md` 또는 하위 디렉터리를 사용한다.
+- 실제 구현체 이름과 다를 수 있지만, view 정의서에서 참조하는 component id는 이 목록에 있어야 한다.

agent-ui/definition/components/proto-socket-diagnostics/index.md

@@ -0,0 +1,78 @@
+---
+ui_doc_type: component
+component_id: proto-socket-diagnostics
+status: 구현됨
+source_evidence:
+  - type: code
+    path: apps/client/lib/src/features/workspaces/presentation/workspace_home_page.dart
+    notes: _buildProtoSocketDiagnosticsSection과 _buildDiagnosticsChip 구현.
+  - type: code
+    path: apps/client/lib/src/integrations/proto_socket/proto_socket_lifecycle.dart
+    notes: ProtoSocketLifecycle diagnostics stream과 state model.
+  - type: docs
+    path: README.md
+    notes: proto-socket client-core 통신과 PROTO_SOCKET 환경 경계 설명.
+  - type: user
+    path: null
+    notes: agent-ui 생성 요청.
+---
+
+# Proto-Socket Diagnostics
+
+Component ID: `proto-socket-diagnostics`
+
+Status: `구현됨`
+
+## Source Evidence
+
+| Type | Path | Notes |
+|------|------|-------|
+| code | `apps/client/lib/src/features/workspaces/presentation/workspace_home_page.dart` | _buildProtoSocketDiagnosticsSection과 _buildDiagnosticsChip 구현. |
+| code | `apps/client/lib/src/integrations/proto_socket/proto_socket_lifecycle.dart` | ProtoSocketLifecycle diagnostics stream과 state model. |
+| docs | `README.md` | proto-socket client-core 통신과 PROTO_SOCKET 환경 경계 설명. |
+| user | 없음 | agent-ui 생성 요청. |
+
+## Purpose
+
+Workspace screen에서 proto-socket 연결 상태와 최근 envelope diagnostics를 non-secret chip 묶음으로 보여준다.
+
+## Used By
+
+- `workspace-home`: `workspace-home.proto-socket-diagnostics`
+
+## Anatomy
+
+- Section heading
+- Diagnostics container
+- State chip
+- Connection id chip
+- Protocol version chip
+- Channel chip
+- Action chip
+- Error code chip
+- Timestamp chip
+
+## Variants
+
+- default: lifecycle이 제공된 workspace detail 안에서 표시
+
+## States
+
+- disconnected
+- connecting
+- connected
+- failed
+- loading: diagnostics stream initial data 사용
+- empty: diagnostics value가 없으면 `n/a` 또는 `none`을 표시한다.
+- error: error code가 있으면 red accent를 사용한다.
+- disabled: lifecycle이 없으면 component를 render하지 않는다.
+
+## Rules
+
+- lifecycle이 없으면 빈 widget으로 빠진다.
+- raw transport exception이나 secret endpoint detail은 표시하지 않는다.
+- state color는 disconnected, connecting, connected, failed에 맞춰 구분한다.
+
+## Decision History
+
+- 2026-06-24: 구현된 proto-socket diagnostics section을 component로 등록했다.

agent-ui/definition/components/status-chip/index.md

@@ -0,0 +1,71 @@
+---
+ui_doc_type: component
+component_id: status-chip
+status: 구현됨
+source_evidence:
+  - type: code
+    path: apps/client/lib/src/features/workspaces/presentation/workspace_home_page.dart
+    notes: _buildStatusChip과 workspace detail status pill 구현.
+  - type: code
+    path: apps/client/lib/src/features/workspaces/domain/project_workspace.dart
+    notes: ProjectStatus enum.
+  - type: user
+    path: null
+    notes: agent-ui 생성 요청.
+---
+
+# Status Chip
+
+Component ID: `status-chip`
+
+Status: `구현됨`
+
+## Source Evidence
+
+| Type | Path | Notes |
+|------|------|-------|
+| code | `apps/client/lib/src/features/workspaces/presentation/workspace_home_page.dart` | _buildStatusChip과 workspace detail status pill 구현. |
+| code | `apps/client/lib/src/features/workspaces/domain/project_workspace.dart` | ProjectStatus enum. |
+| user | 없음 | agent-ui 생성 요청. |
+
+## Purpose
+
+Project 또는 task status를 작은 pill 형태로 압축해 보여준다.
+
+## Used By
+
+- `workspace-home`: `workspace-home.workspace-details`
+- `workspace-home`: `workspace-home.active-tasks`
+
+## Anatomy
+
+- Compact container
+- Status text
+- Accent color background
+
+## Variants
+
+- project-status: active 또는 paused workspace status pill
+- task-status: arbitrary task status text
+
+## States
+
+- default
+- active
+- paused
+- running
+- 알 수 없는 task status
+- loading: 없음
+- empty: 없음
+- error: status value가 error이면 task row status text로 표시된다.
+- disabled: 없음
+
+## Rules
+
+- project status는 enum value를 uppercase로 표시한다.
+- task status는 service에서 온 status string을 그대로 표시한다.
+- status chip은 status 의미를 변경하지 않고 시각적으로만 강조한다.
+
+## Decision History
+
+- 2026-06-24: workspace와 task 상태 표현을 component로 등록했다.

agent-ui/definition/components/workbench-titlebar/index.md

@@ -0,0 +1,65 @@
+---
+ui_doc_type: component
+component_id: workbench-titlebar
+status: 구현됨
+source_evidence:
+  - type: code
+    path: apps/client/lib/src/app/nomadcode_workbench_shell.dart
+    notes: _WorkbenchTitleBar 구현.
+  - type: docs
+    path: apps/client/README.md
+    notes: Workbench shell의 top titlebar 설명.
+  - type: user
+    path: null
+    notes: agent-ui 생성 요청.
+---
+
+# Workbench Titlebar
+
+Component ID: `workbench-titlebar`
+
+Status: `구현됨`
+
+## Source Evidence
+
+| Type | Path | Notes |
+|------|------|-------|
+| code | `apps/client/lib/src/app/nomadcode_workbench_shell.dart` | _WorkbenchTitleBar 구현. |
+| docs | `apps/client/README.md` | Workbench shell의 top titlebar 설명. |
+| user | 없음 | agent-ui 생성 요청. |
+
+## Purpose
+
+Workbench 최상단에서 NomadCode Console identity와 현재 선택 section label을 표시한다.
+
+## Used By
+
+- `workbench-shell`: `workbench-shell.titlebar`
+
+## Anatomy
+
+- Brand mark icon container
+- `NomadCode Console` title
+- Divider
+- Current section label
+
+## Variants
+
+- default: full width titlebar
+
+## States
+
+- default
+- loading: 없음
+- empty: section label이 없으면 빈 label 대신 현재 enum label을 사용한다.
+- error: 없음
+- disabled: 없음
+
+## Rules
+
+- 현재 section label은 `NomadWorkbenchSection`에서 파생한다.
+- titlebar는 navigation control을 직접 갖지 않는다.
+
+## Decision History
+
+- 2026-06-24: workbench shell의 구현된 titlebar를 component로 등록했다.

agent-ui/definition/components/workspace-list/index.md

@@ -0,0 +1,70 @@
+---
+ui_doc_type: component
+component_id: workspace-list
+status: 구현됨
+source_evidence:
+  - type: code
+    path: apps/client/lib/src/features/workspaces/presentation/workspace_home_page.dart
+    notes: _buildWorkspaceList 구현.
+  - type: code
+    path: apps/client/lib/src/features/workspaces/domain/project_workspace.dart
+    notes: ProjectWorkspace model과 mockProjectWorkspaces seed.
+  - type: user
+    path: null
+    notes: agent-ui 생성 요청.
+---
+
+# Workspace List
+
+Component ID: `workspace-list`
+
+Status: `구현됨`
+
+## Source Evidence
+
+| Type | Path | Notes |
+|------|------|-------|
+| code | `apps/client/lib/src/features/workspaces/presentation/workspace_home_page.dart` | _buildWorkspaceList 구현. |
+| code | `apps/client/lib/src/features/workspaces/domain/project_workspace.dart` | ProjectWorkspace model과 mockProjectWorkspaces seed. |
+| user | 없음 | agent-ui 생성 요청. |
+
+## Purpose
+
+사용 가능한 project workspace를 카드 목록으로 보여주고, 현재 선택 workspace를 명확하게 표시한다.
+
+## Used By
+
+- `workspace-home`: `workspace-home.workspace-list`
+
+## Anatomy
+
+- Workspace card
+- Status icon
+- Workspace name
+- Description
+- Task count badge
+- Selected border/background state
+
+## Variants
+
+- default: large-screen left panel list
+- stacked: small-screen top list
+
+## States
+
+- default
+- selected
+- loading: 없음
+- empty: mock workspace seed가 비어 있으면 list가 비어 있다.
+- error: 없음
+- disabled: 없음
+
+## Rules
+
+- 선택 상태는 ProjectWorkspace id로 판별한다.
+- task count가 0이면 task count badge를 표시하지 않는다.
+- active workspace는 code icon과 cyan accent를 사용하고 paused workspace는 pause icon과 amber accent를 사용한다.
+
+## Decision History
+
+- 2026-06-24: 구현된 workspace list를 component로 등록했다.

agent-ui/definition/components/workspace-task-list/index.md

@@ -0,0 +1,70 @@
+---
+ui_doc_type: component
+component_id: workspace-task-list
+status: 구현됨
+source_evidence:
+  - type: code
+    path: apps/client/lib/src/features/workspaces/presentation/workspace_home_page.dart
+    notes: _buildTaskSection, _buildMockTaskSection, _buildTaskRow, _buildEmptyTasks, _buildTaskError 구현.
+  - type: code
+    path: apps/client/lib/src/features/workspaces/domain/workspace_task.dart
+    notes: WorkspaceTask row model.
+  - type: user
+    path: null
+    notes: agent-ui 생성 요청.
+---
+
+# Workspace Task List
+
+Component ID: `workspace-task-list`
+
+Status: `구현됨`
+
+## Source Evidence
+
+| Type | Path | Notes |
+|------|------|-------|
+| code | `apps/client/lib/src/features/workspaces/presentation/workspace_home_page.dart` | _buildTaskSection, _buildMockTaskSection, _buildTaskRow, _buildEmptyTasks, _buildTaskError 구현. |
+| code | `apps/client/lib/src/features/workspaces/domain/workspace_task.dart` | WorkspaceTask row model. |
+| user | 없음 | agent-ui 생성 요청. |
+
+## Purpose
+
+선택 workspace의 active task 목록을 표시한다. service boundary가 없으면 mock row를 보여주고, service boundary가 있으면 deterministic loading, empty, error state를 표시한다.
+
+## Used By
+
+- `workspace-home`: `workspace-home.active-tasks`
+
+## Anatomy
+
+- Section body
+- Task row icon
+- Task title
+- Status chip
+- Empty state row
+- Error state row with Retry
+- Loading progress
+
+## Variants
+
+- mock: `loadTasks`가 없을 때 project task count 기반 rows
+- service-backed: `loadTasks`가 있을 때 FutureBuilder 기반 rows
+
+## States
+
+- default
+- loading
+- empty
+- error
+- disabled: 없음
+
+## Rules
+
+- loader가 없으면 mock task section을 사용한다.
+- loader가 있으면 task future의 loading, error, empty, data state를 그대로 반영한다.
+- error state는 raw exception이나 secret transport detail을 노출하지 않는다.
+
+## Decision History
+
+- 2026-06-24: 구현된 workspace task list를 component로 등록했다.

agent-ui/definition/index.md

@@ -0,0 +1,63 @@
+---
+ui_doc_type: definition-index
+surface_type: ops-dev
+source_evidence:
+  - type: code
+    path: apps/client/lib/src/app/nomadcode_workbench_shell.dart
+    notes: Workbench shell, titlebar, activity rail, Agent dock, section switching, optional IOP slot 구현 근거.
+  - type: code
+    path: apps/client/lib/src/features/workspaces/presentation/workspace_home_page.dart
+    notes: Workspace list, detail pane, task states, proto-socket diagnostics 구현 근거.
+  - type: docs
+    path: README.md
+    notes: NomadCode 제품 경계와 Flutter app source of truth 설명.
+  - type: docs
+    path: apps/client/README.md
+    notes: Workbench shell, Agent dock, IOP slot, WorkspaceHomePage mount 기준.
+  - type: user
+    path: null
+    notes: agent-ui 생성 요청.
+---
+
+# UI Definition
+
+## Purpose
+
+NomadCode의 현재 Flutter client UI를 agent와 사람이 같은 기준으로 읽을 수 있게 정리한다. 초기 기준은 구현 코드가 확인된 workbench shell과 workspace home surface이며, provider slot과 product UX 확장은 후속 정의 후보로 둔다.
+
+## Surface Type
+
+- Type: ops-dev
+- Notes: product UI layer가 필요해지면 brand, content, assets, tokens, motion, provider console composition을 별도 갱신으로 추가한다.
+
+## Source Evidence
+
+| Type | Path | Notes |
+|------|------|-------|
+| code | `apps/client/lib/src/app/nomadcode_workbench_shell.dart` | Workbench shell, titlebar, activity rail, Agent dock, section switching, optional IOP slot 구현 근거. |
+| code | `apps/client/lib/src/features/workspaces/presentation/workspace_home_page.dart` | Workspace list, detail pane, task states, proto-socket diagnostics 구현 근거. |
+| docs | `README.md` | NomadCode 제품 경계와 Flutter app source of truth 설명. |
+| docs | `apps/client/README.md` | Workbench shell, Agent dock, IOP slot, WorkspaceHomePage mount 기준. |
+| user | 없음 | agent-ui 생성 요청. |
+
+## Structure
+
+- `views/`: 화면 또는 업무 단위 정의
+- `components/`: 반복 UI 구성요소 정의
+- `archive/`: 현재 기준이 아닌 과거 정의/결정 로그
+
+## Reading Rules
+
+- 현재 UI 동기화는 이 디렉터리의 활성 문서를 기준으로 한다.
+- `archive/**`는 과거 비교, 복원, 특정 근거 확인 요청이 있을 때만 읽는다.
+
+## Sync Rules
+
+- frame-view가 있으면 view region id와 frame region id는 동일해야 한다.
+- view에서 참조한 component id는 `components/` 아래에 정의되어야 한다.
+- frame은 definition을 대체하지 않는다.
+- `구현됨`, `계획`, `가정`, `불명확` 상태를 섞어 쓰지 않는다.
+
+## Decision History
+
+- 2026-06-24: Flutter 구현 근거를 기준으로 `code-first` agent-ui 초안을 생성했다.

agent-ui/definition/views/index.md

@@ -0,0 +1,36 @@
+---
+ui_doc_type: views-index
+views:
+  - workbench-shell
+  - workspace-home
+---
+
+# View Definitions
+
+## View Tree
+
+| View ID | Status | Evidence | Description |
+|---------|--------|----------|-------------|
+| `workbench-shell` | 구현됨 | `apps/client/lib/src/app/nomadcode_workbench_shell.dart` | NomadCode Console의 상단 titlebar, 우측 activity rail, 중앙 section, Agent dock을 조립하는 앱 shell. |
+| `workspace-home` | 구현됨 | `apps/client/lib/src/features/workspaces/presentation/workspace_home_page.dart` | Project workspace 목록, 선택된 workspace detail, active task, proto-socket diagnostics를 보여주는 기본 workspace 화면. |
+
+## Navigation
+
+- `workbench-shell` -> `workspace-home`: activity rail에서 Workspace section이 선택되거나 기본 section으로 진입한다.
+- `workbench-shell` -> `workbench-shell`: Workflow, Terminal, Review, Web Context, Settings, IOP section 선택은 현재 shell 내부 placeholder 또는 optional slot으로 전환된다.
+- `workspace-home` -> external code-server workspace: `Open Workspace` action이 `WorkspaceLauncher` boundary를 통해 code-server entry를 연다.
+
+## Common States
+
+- loading
+- empty
+- error
+- permission-denied
+
+## Common Permissions
+
+- 없음: 현재 Flutter scaffold에는 view-level permission guard가 구현되어 있지 않다.
+
+## Open Questions
+
+- 없음

agent-ui/definition/views/workbench-shell/index.md

@@ -0,0 +1,101 @@
+---
+ui_doc_type: view
+view_id: workbench-shell
+status: 구현됨
+frame: null
+source_evidence:
+  - type: code
+    path: apps/client/lib/src/app/nomadcode_workbench_shell.dart
+    notes: NomadCodeWorkbenchShell, _WorkbenchTitleBar, _WorkbenchActivityRail, _AgentDockPanel, section placeholder 구현.
+  - type: code
+    path: apps/client/lib/src/app/nomadcode_client_app.dart
+    notes: MaterialApp home에서 WorkspaceHomePage를 workbench shell에 mount하는 조립 근거.
+  - type: docs
+    path: apps/client/README.md
+    notes: Workbench shell, Agent dock, IOP slot composition 설명.
+  - type: docs
+    path: README.md
+    notes: 제품 경계의 workbench shell, Agent dock, IOP slot 설명.
+  - type: user
+    path: null
+    notes: agent-ui 생성 요청.
+regions:
+  - workbench-shell.titlebar
+  - workbench-shell.center
+  - workbench-shell.activity-rail
+  - workbench-shell.agent-dock
+  - workbench-shell.iop-slot
+---
+
+# Workbench Shell
+
+View ID: `workbench-shell`
+
+Frame:
+- 없음
+
+Status: `구현됨`
+
+## Source Evidence
+
+| Type | Path | Notes |
+|------|------|-------|
+| code | `apps/client/lib/src/app/nomadcode_workbench_shell.dart` | NomadCodeWorkbenchShell, _WorkbenchTitleBar, _WorkbenchActivityRail, _AgentDockPanel, section placeholder 구현. |
+| code | `apps/client/lib/src/app/nomadcode_client_app.dart` | MaterialApp home에서 WorkspaceHomePage를 workbench shell에 mount하는 조립 근거. |
+| docs | `apps/client/README.md` | Workbench shell, Agent dock, IOP slot composition 설명. |
+| docs | `README.md` | 제품 경계의 workbench shell, Agent dock, IOP slot 설명. |
+| user | 없음 | agent-ui 생성 요청. |
+
+## Purpose
+
+NomadCode Console의 최상위 작업 표면이다. 상단 titlebar, 중앙 product section, 우측 activity rail, 우측 Agent dock, optional IOP content slot을 하나의 workbench로 조립한다.
+
+## Primary Users
+
+- NomadCode로 개발 workspace와 agent 작업 상태를 오가는 사용자
+- provider console 또는 IOP slot을 함께 열어보는 운영 사용자
+
+## Primary Tasks
+
+- Workspace, Workflow, Terminal, Review, Web Context, Settings, IOP section 사이를 전환한다.
+- 우측 Agent dock을 열고 닫는다.
+- optional IOP content가 제공되면 IOP section에 mount한다.
+
+## Information Priority
+
+1. 현재 선택된 workbench section과 중앙 content
+2. Agent dock 열림 상태와 우측 rail navigation
+3. IOP/provider slot availability
+
+## Regions
+
+| Region ID | Purpose | Component | Priority | Notes |
+|-----------|---------|-----------|----------|-------|
+| `workbench-shell.titlebar` | Console brand, 현재 section label 표시 | `workbench-titlebar` | high | `_WorkbenchTitleBar` 구현. |
+| `workbench-shell.center` | 선택된 product section content 표시 | 없음 | high | Workspace는 `WorkspaceHomePage`, 나머지 section은 placeholder 또는 slot. |
+| `workbench-shell.activity-rail` | Agent toggle과 section navigation | `activity-rail` | high | 우측 고정 rail. |
+| `workbench-shell.agent-dock` | AgentShell 기반 대화/작업 dock | `agent-dock-panel` | medium | compact width에서는 center content를 숨기고 dock을 우선 표시. |
+| `workbench-shell.iop-slot` | optional IOP console content mount | 없음 | medium | `iopContent`가 없으면 IOP placeholder를 표시한다. |
+
+## Actions
+
+| Action ID | Trigger | Result | Guard |
+|-----------|---------|--------|-------|
+| `workbench-shell.select-section` | activity rail section button | 중앙 content를 선택 section으로 전환하고 Agent dock을 닫는다. | 없음 |
+| `workbench-shell.toggle-agent` | Agent rail button | Agent dock open/closed 상태를 전환한다. | 없음 |
+| `workbench-shell.mount-iop-slot` | `iopContent` widget 제공 | IOP section에 외부 IOP console content를 표시한다. | IOP package/widget은 optional boundary로 유지한다. |
+
+## States
+
+- loading: shell 자체 loading state는 없다.
+- empty: section content가 아직 없으면 `_WorkbenchPlaceholder`를 표시한다.
+- error: shell 자체 error state는 없다.
+- permission-denied: view-level permission guard는 구현되어 있지 않다.
+
+## Open Questions
+
+- 없음
+
+## Decision History
+
+- 2026-06-24: 구현된 Flutter workbench shell을 `구현됨` view로 등록했다.

agent-ui/definition/views/workspace-home/index.md

@@ -0,0 +1,102 @@
+---
+ui_doc_type: view
+view_id: workspace-home
+status: 구현됨
+frame: null
+source_evidence:
+  - type: code
+    path: apps/client/lib/src/features/workspaces/presentation/workspace_home_page.dart
+    notes: WorkspaceHomePage, project selection, dual/single pane layout, task states, proto-socket diagnostics 구현.
+  - type: code
+    path: apps/client/lib/src/features/workspaces/domain/project_workspace.dart
+    notes: ProjectWorkspace UI model과 mock workspace seed.
+  - type: code
+    path: apps/client/lib/src/features/workspaces/domain/workspace_task.dart
+    notes: Core task channel 응답을 tolerant하게 파싱하는 task row model.
+  - type: docs
+    path: apps/client/README.md
+    notes: WorkspaceHomePage가 workbench shell 내부에서 app bar를 숨길 수 있다는 mount 기준.
+  - type: user
+    path: null
+    notes: agent-ui 생성 요청.
+regions:
+  - workspace-home.workspace-list
+  - workspace-home.workspace-details
+  - workspace-home.active-tasks
+  - workspace-home.proto-socket-diagnostics
+  - workspace-home.launch-action
+---
+
+# Workspace Home
+
+View ID: `workspace-home`
+
+Frame:
+- 없음
+
+Status: `구현됨`
+
+## Source Evidence
+
+| Type | Path | Notes |
+|------|------|-------|
+| code | `apps/client/lib/src/features/workspaces/presentation/workspace_home_page.dart` | WorkspaceHomePage, project selection, dual/single pane layout, task states, proto-socket diagnostics 구현. |
+| code | `apps/client/lib/src/features/workspaces/domain/project_workspace.dart` | ProjectWorkspace UI model과 mock workspace seed. |
+| code | `apps/client/lib/src/features/workspaces/domain/workspace_task.dart` | Core task channel 응답을 tolerant하게 파싱하는 task row model. |
+| docs | `apps/client/README.md` | WorkspaceHomePage가 workbench shell 내부에서 app bar를 숨길 수 있다는 mount 기준. |
+| user | 없음 | agent-ui 생성 요청. |
+
+## Purpose
+
+프로젝트 workspace 목록과 선택된 workspace의 task 상태를 보여주는 기본 업무 화면이다. 큰 화면에서는 목록과 상세를 나란히 보여주고, 작은 화면에서는 목록과 선택 workspace action을 압축해서 보여준다.
+
+## Primary Users
+
+- 프로젝트별 개발 workspace를 열고 task 상태를 확인하는 사용자
+- proto-socket 연결 상태와 task loading 상태를 확인하는 운영 사용자
+
+## Primary Tasks
+
+- workspace를 선택한다.
+- 선택된 workspace의 설명, status, active tasks를 확인한다.
+- code-server workspace entry를 연다.
+- proto-socket task service가 연결된 경우 task loading, empty, error 상태를 확인하고 재시도한다.
+
+## Information Priority
+
+1. 선택된 workspace와 launch action
+2. workspace description과 status
+3. active tasks와 proto-socket diagnostics
+
+## Regions
+
+| Region ID | Purpose | Component | Priority | Notes |
+|-----------|---------|-----------|----------|-------|
+| `workspace-home.workspace-list` | ProjectWorkspace 목록과 선택 상태 표시 | `workspace-list` | high | large screen에서는 좌측 panel, small screen에서는 상단 list. |
+| `workspace-home.workspace-details` | 선택 workspace 제목, status, description 표시 | `status-chip` | high | 선택 workspace가 없으면 selection empty message 표시. |
+| `workspace-home.active-tasks` | mock 또는 service 기반 active task 표시 | `workspace-task-list` | high | `loadTasks`가 없으면 mock rows, 있으면 FutureBuilder state를 따른다. |
+| `workspace-home.proto-socket-diagnostics` | proto-socket lifecycle diagnostics 표시 | `proto-socket-diagnostics` | medium | lifecycle이 없으면 표시하지 않는다. |
+| `workspace-home.launch-action` | code-server workspace entry 열기 | 없음 | medium | `onLaunchCodeServer` callback이 있을 때 workspace launch를 시도한다. |
+
+## Actions
+
+| Action ID | Trigger | Result | Guard |
+|-----------|---------|--------|-------|
+| `workspace-home.select-project` | workspace card tap | 선택 workspace와 task future를 갱신한다. | 없음 |
+| `workspace-home.launch-workspace` | `Open Workspace` button | `WorkspaceLauncher` boundary로 code-server entry를 연다. | `onLaunchCodeServer` callback 존재 |
+| `workspace-home.reload-tasks` | loader 변경 또는 retry button | 현재 선택 workspace의 task loading을 다시 시작한다. | `loadTasks` callback 존재 |
+
+## States
+
+- loading: `loadTasks` Future가 waiting이면 circular progress를 표시한다.
+- empty: task list가 비어 있거나 mock tasks count가 0이면 idle message를 표시한다.
+- error: task load 실패 시 non-secret error message와 Retry action을 표시한다.
+- permission-denied: view-level permission guard는 구현되어 있지 않다.
+
+## Open Questions
+
+- 없음
+
+## Decision History
+
+- 2026-06-24: 구현된 Flutter WorkspaceHomePage를 `구현됨` view로 등록했다.

agent-ui/frame/index.md

@@ -0,0 +1,21 @@
+---
+ui_doc_type: frame-index
+frames: []
+---
+
+# UI Frames
+
+## Purpose
+
+이 디렉터리는 visual source가 있는 view의 wireframe과 definition 연결 정보를 보관한다.
+
+## Frame Sources
+
+- 없음: 현재 생성 시점에는 visual source가 없다.
+
+## Rules
+
+- frame은 definition을 대체하지 않는다.
+- visual source가 있으면 대응되는 frame index에 기록한다.
+- visual source가 없으면 `views/<view-id>/`를 만들지 않는다.
+- frame-view가 있으면 frame region id는 definition region id와 동일해야 한다.