docs(agent-ui): 기준선 문서를 정합화한다

2026-06-25 10:49:40 +09:00 · 2026-06-25 10:49:40 +09:00 · b301153afb
commit b301153afb
parent 5726ac06b4
16 changed files with 669 additions and 0 deletions
--- a/agent-ui/README.md
+++ b/agent-ui/README.md
@ -0,0 +1,28 @@
+---
+ui_doc_type: readme
+surface_type: ops-dev
+---
+
+# agent-ui
+
+이 디렉터리는 AI agent와 사람이 ALT 운영 UI의 의도, 화면 구조, 반복 구성요소, wireframe 근거를 동기화하기 위한 작업 문맥 저장소다.
+
+## 대상
+
+- 1차 대상: ALT ops/dev UI
+- 현재 구현 표면: Flutter client의 workbench shell과 dashboard scaffold
+- 확장 후보: product UI 레이어는 요청될 때 brand, content, assets, tokens, motion 문서로 추가한다.
+
+## 구조
+
+- `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/**`는 과거 기록이며 일반 작업에서 읽지 않는다.
--- a/agent-ui/USER_REVIEW.md
+++ b/agent-ui/USER_REVIEW.md
@ -0,0 +1,23 @@
+---
+ui_doc_type: user-review
+status: open
+---
+
+# agent-ui 사용자 리뷰
+
+이 문서는 agent가 확정할 수 없는 UI 결정을 사용자에게 넘기기 위한 활성 리뷰 문서다.
+해결된 항목은 `agent-ui/archive/user-review/user_review_N.log`로 이동할 수 있다.
+
+## Review Items
+
+- [ ] [UIR-001] 현재 placeholder로 구현된 Markets, Backtests, Portfolio, Research, Settings section을 지금 별도 view 정의로 승격할지 결정한다.
+  - Source Skill: validate-agent-ui
+  - Stage: document-consistency
+  - Blocking Step: code-sync
+  - Context: `agent-ui/definition/views/alt-workbench/index.md`, `apps/client/lib/src/app/alt_workbench_shell.dart`
+  - Options: `alt-workbench`의 center region 안에 placeholder 상태로 유지 / 각 section을 `definition/views/<section>/index.md`로 분리
+  - Needed For: 실제 operator surface wireframe 또는 화면별 acceptance 기준 작성
+
+## Notes
+
+- 현재 scaffold는 실제 route와 shell 구현이 확인된 `alt-workbench`, dashboard body가 확인된 `dashboard`만 활성 view로 만든다.
--- a/agent-ui/archive/user-review/.gitkeep
+++ b/agent-ui/archive/user-review/.gitkeep
@ -0,0 +1 @@
+
--- a/agent-ui/definition/archive/components/.gitkeep
+++ b/agent-ui/definition/archive/components/.gitkeep
@ -0,0 +1 @@
+
--- a/agent-ui/definition/archive/views/.gitkeep
+++ b/agent-ui/definition/archive/views/.gitkeep
@ -0,0 +1 @@
+
--- a/agent-ui/definition/components/activity-rail/index.md
+++ b/agent-ui/definition/components/activity-rail/index.md
@ -0,0 +1,56 @@
+---
+ui_doc_type: component
+component_id: activity-rail
+status: 구현됨
+source_evidence:
+  - type: code
+    path: apps/client/lib/src/app/alt_workbench_shell.dart
+    notes: _AltActivityRail과 _RailButton이 Agent toggle 및 section switching button을 렌더링한다.
+---
+
+# Activity Rail
+
+Component ID: `activity-rail`
+
+Status: `구현됨`
+
+## Source Evidence
+
+| Type | Path | Notes |
+|------|------|-------|
+| code | `apps/client/lib/src/app/alt_workbench_shell.dart` | `_AltActivityRail`과 `_RailButton`이 Agent toggle 및 section switching button을 렌더링한다. |
+
+## Purpose
+
+ALT Console 오른쪽에서 Agent dock toggle과 workbench section 전환을 제공한다.
+
+## Used By
+
+- `alt-workbench`: `alt-workbench.activity-rail`
+
+## Anatomy
+
+- Agent toggle button
+- section buttons: Dashboard, Markets, Backtests, Portfolio, Research, Settings
+- selected state styling
+- tooltip labels
+
+## Variants
+
+- default: 60px right rail
+
+## States
+
+- default
+- selected
+- agent-open
+
+## Rules
+
+- Agent button은 Agent dock open 상태를 반영한다.
+- section button을 선택하면 selected section이 바뀌고 Agent dock은 닫힌다.
+- tooltip은 각 icon button의 의미를 제공한다.
+
+## Decision History
+
+- 2026-06-25: `_AltActivityRail` 구현 근거로 component 정의를 생성했다.
--- a/agent-ui/definition/components/agent-dock/index.md
+++ b/agent-ui/definition/components/agent-dock/index.md
@ -0,0 +1,60 @@
+---
+ui_doc_type: component
+component_id: agent-dock
+status: 구현됨
+source_evidence:
+  - type: code
+    path: apps/client/lib/src/app/alt_workbench_shell.dart
+    notes: _AltAgentDock이 agent_shell package의 AgentShell을 mount한다.
+  - type: docs
+    path: apps/client/README.md
+    notes: 오른쪽 Agent dock은 sibling agent_shell package를 product-neutral chat/agent surface로 사용한다고 설명한다.
+---
+
+# Agent Dock
+
+Component ID: `agent-dock`
+
+Status: `구현됨`
+
+## Source Evidence
+
+| Type | Path | Notes |
+|------|------|-------|
+| code | `apps/client/lib/src/app/alt_workbench_shell.dart` | `_AltAgentDock`이 `agent_shell` package의 `AgentShell`을 mount한다. |
+| docs | `apps/client/README.md` | 오른쪽 Agent dock은 sibling `agent_shell` package를 product-neutral chat/agent surface로 사용한다고 설명한다. |
+
+## Purpose
+
+ALT Console 안에서 agent 대화 표면을 오른쪽 dock으로 제공한다.
+
+## Used By
+
+- `alt-workbench`: `alt-workbench.agent-dock`
+
+## Anatomy
+
+- dock container
+- initial assistant message
+- `AgentShell`
+- input placeholder
+
+## Variants
+
+- default: desktop right dock
+- compact: viewport width가 좁으면 center content 대신 dock width를 우선한다.
+
+## States
+
+- default
+- open
+- compact
+
+## Rules
+
+- dock은 activity rail의 Agent action으로 열고 닫는다.
+- 현재 agent message는 scaffold intro 수준이며, ALT tool/API 연결 여부를 확정하지 않는다.
+
+## Decision History
+
+- 2026-06-25: `_AltAgentDock` 구현 근거로 component 정의를 생성했다.
--- a/agent-ui/definition/components/index.md
+++ b/agent-ui/definition/components/index.md
@ -0,0 +1,27 @@
+---
+ui_doc_type: components-index
+components:
+  - workbench-title-bar
+  - activity-rail
+  - agent-dock
+  - placeholder-panel
+  - status-panel
+---
+
+# Component Definitions
+
+## Component List
+
+| Component ID | Status | Evidence | Description |
+|--------------|--------|----------|-------------|
+| `workbench-title-bar` | 구현됨 | `apps/client/lib/src/app/alt_workbench_shell.dart` | ALT Console identity와 현재 section label을 표시하는 top bar |
+| `activity-rail` | 구현됨 | `apps/client/lib/src/app/alt_workbench_shell.dart` | Agent toggle과 section switching을 담당하는 right rail |
+| `agent-dock` | 구현됨 | `apps/client/lib/src/app/alt_workbench_shell.dart`, `apps/client/README.md` | `agent_shell` package를 mount하는 right dock |
+| `placeholder-panel` | 구현됨 | `apps/client/lib/src/app/alt_workbench_shell.dart` | 아직 실제 surface가 없는 section의 placeholder content |
+| `status-panel` | 구현됨 | `apps/client/lib/src/features/dashboard/presentation/dashboard_screen.dart` | dashboard 상태 정보를 icon, title, value로 표시하는 panel |
+
+## Rules
+
+- component 정의는 구현 API가 아니라 UI 사용 규칙을 다룬다.
+- view별 변형이 필요하면 `<component-id>/<variant>.md` 또는 하위 디렉터리를 사용한다.
+- 실제 구현체 이름과 다를 수 있지만, view 정의서에서 참조하는 component id는 이 목록에 있어야 한다.
--- a/agent-ui/definition/components/placeholder-panel/index.md
+++ b/agent-ui/definition/components/placeholder-panel/index.md
@ -0,0 +1,61 @@
+---
+ui_doc_type: component
+component_id: placeholder-panel
+status: 구현됨
+source_evidence:
+  - type: code
+    path: apps/client/lib/src/app/alt_workbench_shell.dart
+    notes: _AltPlaceholder가 준비되지 않은 Markets, Backtests, Portfolio, Research, Settings section content를 표시한다.
+  - type: docs
+    path: README.md
+    notes: 실제 quant 운영 기능은 API/worker/domain headless 경계 안정화 뒤 중앙 section에 mount한다고 설명한다.
+---
+
+# Placeholder Panel
+
+Component ID: `placeholder-panel`
+
+Status: `구현됨`
+
+## Source Evidence
+
+| Type | Path | Notes |
+|------|------|-------|
+| code | `apps/client/lib/src/app/alt_workbench_shell.dart` | `_AltPlaceholder`가 준비되지 않은 Markets, Backtests, Portfolio, Research, Settings section content를 표시한다. |
+| docs | `README.md` | 실제 quant 운영 기능은 API/worker/domain headless 경계 안정화 뒤 중앙 section에 mount한다고 설명한다. |
+
+## Purpose
+
+아직 headless 경계가 준비되지 않은 운영 section에 대해 의도와 future mount point를 표시한다.
+
+## Used By
+
+- `alt-workbench`: `alt-workbench.center`
+
+## Anatomy
+
+- icon
+- title
+- subtitle
+
+## Variants
+
+- markets
+- backtests
+- portfolio
+- research
+- settings
+
+## States
+
+- default
+- empty
+
+## Rules
+
+- placeholder는 실제 운영 기능이 구현된 것처럼 설명하지 않는다.
+- section이 실제 operator surface로 승격되면 별도 view 정의 또는 해당 view의 region으로 갱신한다.
+
+## Decision History
+
+- 2026-06-25: `_AltPlaceholder` 구현 근거로 component 정의를 생성했다.
--- a/agent-ui/definition/components/status-panel/index.md
+++ b/agent-ui/definition/components/status-panel/index.md
@ -0,0 +1,56 @@
+---
+ui_doc_type: component
+component_id: status-panel
+status: 구현됨
+source_evidence:
+  - type: code
+    path: apps/client/lib/src/features/dashboard/presentation/dashboard_screen.dart
+    notes: _StatusPanel이 icon, title, value 형태의 dashboard status row를 렌더링한다.
+---
+
+# Status Panel
+
+Component ID: `status-panel`
+
+Status: `구현됨`
+
+## Source Evidence
+
+| Type | Path | Notes |
+|------|------|-------|
+| code | `apps/client/lib/src/features/dashboard/presentation/dashboard_screen.dart` | `_StatusPanel`이 icon, title, value 형태의 dashboard status row를 렌더링한다. |
+
+## Purpose
+
+dashboard에서 pipeline과 socket contract 같은 상태 요약을 일관된 row panel로 보여준다.
+
+## Used By
+
+- `dashboard`: `dashboard.pipeline-status`
+- `dashboard`: `dashboard.socket-status`
+
+## Anatomy
+
+- status icon
+- title
+- value
+- bordered panel container
+
+## Variants
+
+- default: icon, title, value
+
+## States
+
+- default
+- loading
+- error
+
+## Rules
+
+- value는 upstream controller 또는 scaffold 상태를 짧은 operator-facing text로 보여준다.
+- 상태 원천이 없는 항목은 실제 데이터처럼 보이지 않게 scaffold value를 명시한다.
+
+## Decision History
+
+- 2026-06-25: `_StatusPanel` 구현 근거로 component 정의를 생성했다.
--- a/agent-ui/definition/components/workbench-title-bar/index.md
+++ b/agent-ui/definition/components/workbench-title-bar/index.md
@ -0,0 +1,52 @@
+---
+ui_doc_type: component
+component_id: workbench-title-bar
+status: 구현됨
+source_evidence:
+  - type: code
+    path: apps/client/lib/src/app/alt_workbench_shell.dart
+    notes: _AltTitleBar가 ALT Console identity와 section label을 렌더링한다.
+---
+
+# Workbench Title Bar
+
+Component ID: `workbench-title-bar`
+
+Status: `구현됨`
+
+## Source Evidence
+
+| Type | Path | Notes |
+|------|------|-------|
+| code | `apps/client/lib/src/app/alt_workbench_shell.dart` | `_AltTitleBar`가 ALT Console identity와 section label을 렌더링한다. |
+
+## Purpose
+
+ALT Console의 현재 context를 고정된 상단 영역에서 표시한다.
+
+## Used By
+
+- `alt-workbench`: `alt-workbench.title-bar`
+
+## Anatomy
+
+- brand icon
+- `ALT Console` label
+- current section label
+
+## Variants
+
+- default: root workbench 상단 titlebar
+
+## States
+
+- default
+
+## Rules
+
+- 현재 section label은 `AltWorkbenchSection` 선택 상태와 일치해야 한다.
+- 긴 section label은 한 줄 ellipsis로 처리한다.
+
+## Decision History
+
+- 2026-06-25: `_AltTitleBar` 구현 근거로 component 정의를 생성했다.
--- a/agent-ui/definition/index.md
+++ b/agent-ui/definition/index.md
@ -0,0 +1,67 @@
+---
+ui_doc_type: definition-index
+surface_type: ops-dev
+source_evidence:
+  - type: code
+    path: apps/client/lib/src/app/router.dart
+    notes: Root route가 AltWorkbenchShell과 DashboardScreen을 mount한다.
+  - type: code
+    path: apps/client/lib/src/app/alt_workbench_shell.dart
+    notes: top titlebar, right activity rail, center content switching, Agent dock, placeholder sections가 구현되어 있다.
+  - type: code
+    path: apps/client/lib/src/features/dashboard/presentation/dashboard_screen.dart
+    notes: dashboard body와 status panel scaffold가 구현되어 있다.
+  - type: docs
+    path: README.md
+    notes: Flutter client workbench scaffold와 headless-first 운영 UI 게이트를 설명한다.
+  - type: docs
+    path: apps/client/README.md
+    notes: Workbench Shell 구조와 실제 operator screen 추가 전 API/core readiness 조건을 설명한다.
+  - type: user
+    path: null
+    notes: 사용자가 agent-ui 생성을 요청했다.
+---
+
+# UI Definition
+
+## Purpose
+
+ALT Flutter client의 ops/dev workbench UI를 agent와 사람이 같은 기준으로 읽을 수 있게 정의한다. 현재 정의는 구현된 shell, dashboard scaffold, 반복 구성요소를 기준으로 하며, 실제 quant 운영 화면은 API/worker/domain headless 경계가 준비된 뒤 확장한다.
+
+## Surface Type
+
+- Type: ops-dev
+- Notes: product UI 레이어는 현재 생성하지 않는다. ALT의 quant workspace 맥락에서는 운영자가 상태, 작업 큐, 백테스트, market data, agent dock을 반복적으로 확인하는 콘솔 표면을 1차 대상으로 둔다.
+
+## Source Evidence
+
+| Type | Path | Notes |
+|------|------|-------|
+| code | `apps/client/lib/src/app/router.dart` | `/` route가 `AltWorkbenchShell`과 `DashboardScreen`을 mount한다. |
+| code | `apps/client/lib/src/app/alt_workbench_shell.dart` | titlebar, activity rail, center content switching, Agent dock, placeholder sections가 구현되어 있다. |
+| code | `apps/client/lib/src/features/dashboard/presentation/dashboard_screen.dart` | dashboard body와 status panel scaffold가 구현되어 있다. |
+| docs | `README.md` | Flutter client workbench scaffold와 headless-first 운영 UI 게이트를 설명한다. |
+| docs | `apps/client/README.md` | Workbench Shell 구조와 operator screen 추가 전 readiness 조건을 설명한다. |
+| 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을 대체하지 않는다.
+- `implemented`, `planned`, `assumed`, `unknown` 상태를 섞어 쓰지 않는다.
+
+## Decision History
+
+- 2026-06-25: 기존 Flutter code와 README 근거를 기준으로 `code-first` agent-ui scaffold를 생성했다.
--- a/agent-ui/definition/views/alt-workbench/index.md
+++ b/agent-ui/definition/views/alt-workbench/index.md
@ -0,0 +1,91 @@
+---
+ui_doc_type: view
+view_id: alt-workbench
+status: 구현됨
+frame: null
+source_evidence:
+  - type: code
+    path: apps/client/lib/src/app/router.dart
+    notes: Root route가 AltWorkbenchShell을 root view로 mount한다.
+  - type: code
+    path: apps/client/lib/src/app/alt_workbench_shell.dart
+    notes: titlebar, activity rail, center content switching, Agent dock, placeholder sections가 구현되어 있다.
+  - type: docs
+    path: apps/client/README.md
+    notes: Workbench Shell은 top titlebar, right activity rail, center content, right Agent dock 패턴이라고 설명한다.
+regions:
+  - alt-workbench.title-bar
+  - alt-workbench.center
+  - alt-workbench.activity-rail
+  - alt-workbench.agent-dock
+---
+
+# Alt Workbench
+
+View ID: `alt-workbench`
+
+Frame:
+- 없음
+
+Status: `구현됨`
+
+## Source Evidence
+
+| Type | Path | Notes |
+|------|------|-------|
+| code | `apps/client/lib/src/app/router.dart` | `/` route가 `AltWorkbenchShell`을 root view로 mount한다. |
+| code | `apps/client/lib/src/app/alt_workbench_shell.dart` | titlebar, activity rail, center content switching, Agent dock, placeholder sections가 구현되어 있다. |
+| docs | `apps/client/README.md` | Workbench Shell은 top titlebar, right activity rail, center content, right Agent dock 패턴이라고 설명한다. |
+
+## Purpose
+
+ALT 운영자가 dashboard, market data, backtest, portfolio, research, settings 후보 영역과 Agent dock을 한 콘솔에서 오갈 수 있는 root workbench다.
+
+## Primary Users
+
+- ALT operator
+- 개발 중 headless API/worker 상태를 확인하는 maintainer
+
+## Primary Tasks
+
+- 현재 선택된 운영 section의 content 확인
+- 오른쪽 activity rail로 section 전환
+- Agent dock을 열어 보조 대화 표면 확인
+- API/core readiness 전에는 placeholder 상태와 scaffold 경계를 확인
+
+## Information Priority
+
+1. 현재 선택된 section과 center content
+2. Agent dock 열림 상태와 activity rail의 section affordance
+3. titlebar의 ALT Console context
+
+## Regions
+
+| Region ID | Purpose | Component | Priority | Notes |
+|-----------|---------|-----------|----------|-------|
+| `alt-workbench.title-bar` | ALT Console identity와 현재 section label 표시 | `workbench-title-bar` | high | 상단 고정 영역 |
+| `alt-workbench.center` | dashboard 또는 placeholder section content 표시 | `placeholder-panel` | high | dashboard는 별도 `dashboard` view로 정의한다. 나머지 section은 UIR-001 결정 전까지 placeholder로 둔다. |
+| `alt-workbench.activity-rail` | Agent toggle과 section switching controls 제공 | `activity-rail` | high | 오른쪽 rail, compact Agent dock 상태에서는 center content 숨김 |
+| `alt-workbench.agent-dock` | `agent_shell` 기반 agent chat surface 표시 | `agent-dock` | medium | 사용자가 rail의 Agent action을 선택하면 열린다. |
+
+## Actions
+
+| Action ID | Trigger | Result | Guard |
+|-----------|---------|--------|-------|
+| `alt-workbench.select-section` | activity rail section button | center content가 선택 section으로 전환되고 Agent dock은 닫힌다. | operator |
+| `alt-workbench.toggle-agent` | Agent rail button | Agent dock open/closed 상태를 전환한다. | operator |
+
+## States
+
+- loading: shell 자체에는 별도 loading state가 없다. center content가 담당한다.
+- empty: section content가 준비되지 않으면 placeholder panel을 표시한다.
+- error: shell 자체 error state는 아직 정의되지 않았다.
+- permission-denied: 권한 모델이 도입되면 rail action 또는 center content에서 처리한다.
+
+## Open Questions
+
+- [UIR-001] Markets, Backtests, Portfolio, Research, Settings placeholder를 별도 view 정의로 승격할지 결정해야 한다.
+
+## Decision History
+
+- 2026-06-25: `/` route와 `AltWorkbenchShell` 구현 근거로 root workbench view를 생성했다.
--- a/agent-ui/definition/views/dashboard/index.md
+++ b/agent-ui/definition/views/dashboard/index.md
@ -0,0 +1,87 @@
+---
+ui_doc_type: view
+view_id: dashboard
+status: 구현됨
+frame: null
+source_evidence:
+  - type: code
+    path: apps/client/lib/src/features/dashboard/presentation/dashboard_screen.dart
+    notes: DashboardScreen, _DashboardBody, _StatusPanel이 구현되어 있다.
+  - type: code
+    path: apps/client/lib/src/app/router.dart
+    notes: Root route에서 DashboardScreen(showAppBar false, showNavigation false)을 workbench center content로 전달한다.
+  - type: docs
+    path: README.md
+    notes: apps/client는 workbench scaffold를 포함하고 실제 quant 운영 기능은 headless 경계 안정화 뒤 mount한다고 설명한다.
+regions:
+  - dashboard.body
+  - dashboard.pipeline-status
+  - dashboard.socket-status
+---
+
+# Dashboard
+
+View ID: `dashboard`
+
+Frame:
+- 없음
+
+Status: `구현됨`
+
+## Source Evidence
+
+| Type | Path | Notes |
+|------|------|-------|
+| code | `apps/client/lib/src/features/dashboard/presentation/dashboard_screen.dart` | `DashboardScreen`, `_DashboardBody`, `_StatusPanel`이 구현되어 있다. |
+| code | `apps/client/lib/src/app/router.dart` | `/` route에서 `DashboardScreen(showAppBar: false, showNavigation: false)`을 workbench center content로 전달한다. |
+| docs | `README.md` | `apps/client`는 workbench scaffold를 포함하고 실제 quant 운영 기능은 headless 경계 안정화 뒤 mount한다고 설명한다. |
+
+## Purpose
+
+ALT Console의 기본 center content로, Korea Daily Pipeline scaffold 상태와 socket contract 연결 상태를 operator에게 보여준다.
+
+## Primary Users
+
+- ALT operator
+- socket/API scaffold 상태를 확인하는 maintainer
+
+## Primary Tasks
+
+- pipeline scaffold 상태 확인
+- socket connection 상태 확인
+- workbench shell 안에서 dashboard content가 정상 mount되는지 확인
+
+## Information Priority
+
+1. Backtests heading과 dashboard context
+2. Korea Daily Pipeline status
+3. Socket Contract status
+
+## Regions
+
+| Region ID | Purpose | Component | Priority | Notes |
+|-----------|---------|-----------|----------|-------|
+| `dashboard.body` | dashboard list layout와 heading 표시 | 없음 | high | 현재는 `ListView` 기반 scaffold |
+| `dashboard.pipeline-status` | Korea Daily Pipeline scaffold 상태 표시 | `status-panel` | high | value는 `Scaffold`로 고정 |
+| `dashboard.socket-status` | socket connection 상태 표시 | `status-panel` | high | Riverpod controller 상태를 text로 매핑 |
+
+## Actions
+
+| Action ID | Trigger | Result | Guard |
+|-----------|---------|--------|-------|
+| `dashboard.observe-status` | view mount | pipeline과 socket status panel을 표시한다. | operator |
+
+## States
+
+- loading: socket status가 `Connecting`이면 연결 진행 상태를 표시한다.
+- empty: pipeline/backtest data list는 아직 없다.
+- error: socket status가 `Error`이면 status panel value로 표시한다.
+- permission-denied: 권한 모델이 아직 없다.
+
+## Open Questions
+
+- 없음
+
+## Decision History
+
+- 2026-06-25: `DashboardScreen` 구현 근거로 dashboard view를 생성했다.
--- a/agent-ui/definition/views/index.md
+++ b/agent-ui/definition/views/index.md
@ -0,0 +1,35 @@
+---
+ui_doc_type: views-index
+views:
+  - alt-workbench
+  - dashboard
+---
+
+# View Definitions
+
+## View Tree
+
+| View ID | Status | Evidence | Description |
+|---------|--------|----------|-------------|
+| `alt-workbench` | 구현됨 | `apps/client/lib/src/app/router.dart`, `apps/client/lib/src/app/alt_workbench_shell.dart` | ALT Console shell, center section switching, right activity rail, Agent dock을 포함하는 root workbench view |
+| `dashboard` | 구현됨 | `apps/client/lib/src/features/dashboard/presentation/dashboard_screen.dart` | 현재 center content에 mount되는 dashboard scaffold와 socket/pipeline status panel |
+
+## Navigation
+
+- `alt-workbench` -> `dashboard`: `/` route의 기본 center content
+- `alt-workbench` -> placeholder sections: activity rail section 선택. 현재는 별도 view 정의가 아니라 `alt-workbench.center`의 placeholder content로 취급한다.
+
+## Common States
+
+- loading
+- empty
+- error
+- permission-denied
+
+## Common Permissions
+
+- operator: ALT Console view와 scaffold 상태 확인
+
+## Open Questions
+
+- [UIR-001] placeholder sections를 별도 view로 승격할지 결정해야 한다.
--- a/agent-ui/frame/index.md
+++ b/agent-ui/frame/index.md
@ -0,0 +1,23 @@
+---
+ui_doc_type: frame-index
+frames: []
+---
+
+# UI Frames
+
+## Purpose
+
+이 디렉터리는 visual source가 있는 view의 wireframe과 definition 연결 정보를 보관한다.
+
+## Frame Sources
+
+- 현재 visual source가 없으므로 `frame/views/<view-id>/` 문서를 만들지 않는다.
+- `views/<view-id>/index.md`: visual source가 있는 view의 frame 연결 문서
+- `views/<view-id>/wire.excalidraw`: 선택 visual source
+
+## Rules
+
+- frame은 definition을 대체하지 않는다.
+- visual source가 있으면 대응되는 frame index에 기록한다.
+- visual source가 없으면 `views/<view-id>/`를 만들지 않는다.
+- frame-view가 있으면 frame region id는 definition region id와 동일해야 한다.