docs(agent-ui): 레거시 기준선을 정합화한다

agent-ui/README.md

@@ -0,0 +1,27 @@
+---
+ui_doc_type: readme
+surface_type: ops-dev
+---
+
+# agent-ui
+
+이 디렉터리는 AppSok의 ops/dev UI 의도, 화면 구조, 반복 구성요소를 사람과 agent가 같은 기준으로 읽기 위한 작업 문맥 저장소다.
+
+## 대상
+
+- 1차 대상: Flutter macOS ops/dev UI
+- 확장 후보: 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/**`는 과거 기록이며 일반 작업에서 읽지 않는다.

agent-ui/definition/components/adb-diagnostics/index.md

@@ -0,0 +1,72 @@
+---
+ui_doc_type: component
+component_id: adb-diagnostics
+status: 구현됨
+source_evidence:
+  - type: code
+    path: lib/src/features/settings/settings_page.dart
+    notes: "_AdbDiagnosticsSection, _DiagRows, _DiagRow"
+  - type: docs
+    path: README.md
+    notes: "ADB 실행과 USB device 접근 scope"
+  - type: user
+    path: null
+    notes: "agent-ui 생성 요청"
+---
+
+# ADB Diagnostics
+
+Component ID: `adb-diagnostics`
+
+Status: `구현됨`
+
+## Source Evidence
+
+| Type | Path | Notes |
+|------|------|-------|
+| code | `lib/src/features/settings/settings_page.dart` | `_AdbDiagnosticsSection`, `_DiagRows`, `_DiagRow` |
+| docs | `README.md` | ADB 실행과 USB device 접근 scope |
+| user | 없음 | agent-ui 생성 요청 |
+
+## Purpose
+
+현재 ADB runtime source, executable path, server port, version, version error, SHA-256 요약을 설정 화면에서 확인한다.
+
+## Used By
+
+- `settings`: `settings.adb-diagnostics`
+
+## Anatomy
+
+- diagnostics title label
+- loading/refresh icon
+- source row
+- path row
+- server port row
+- optional version row
+- optional version error row
+- optional hash row
+
+## Variants
+
+- default: diagnostics rows 표시
+- loading: hourglass icon
+- empty: 진단 정보 없음
+- error: 진단 로드 실패
+
+## States
+
+- default
+- loading
+- empty
+- error
+- disabled
+
+## Rules
+
+- path/version/hash 값은 길어질 수 있으므로 한 줄 ellipsis를 사용한다.
+- version error row는 error color로 표시한다.
+
+## Decision History
+
+- 2026-06-25: ADB runtime diagnostics rows를 component로 기록했다.

agent-ui/definition/components/build-row/index.md

@@ -0,0 +1,68 @@
+---
+ui_doc_type: component
+component_id: build-row
+status: 구현됨
+source_evidence:
+  - type: code
+    path: lib/src/features/builds/builds_page.dart
+    notes: "_BuildRow, _StateBadge, _BuildStatus"
+  - type: docs
+    path: README.md
+    notes: "Jenkins build/artifact 조회 scope"
+  - type: user
+    path: null
+    notes: "agent-ui 생성 요청"
+---
+
+# Build Row
+
+Component ID: `build-row`
+
+Status: `구현됨`
+
+## Source Evidence
+
+| Type | Path | Notes |
+|------|------|-------|
+| code | `lib/src/features/builds/builds_page.dart` | `_BuildRow`, `_StateBadge`, `_BuildStatus` |
+| docs | `README.md` | Jenkins build/artifact 조회 scope |
+| user | 없음 | agent-ui 생성 요청 |
+
+## Purpose
+
+Jenkins build 하나의 결과 상태와 install에 필요한 metadata를 목록에서 스캔 가능하게 표시한다.
+
+## Used By
+
+- `builds`: `builds.build-search`
+- `builds`: `builds.build-list`
+
+## Anatomy
+
+- result state badge
+- requestedBy label
+- build number, branch, flavor, startedAt, APK file summary
+- selected radio icon
+
+## Variants
+
+- default: unselected row
+- selected: primary outline과 checked icon
+- status: build list empty/error/permission 안내
+
+## States
+
+- default
+- loading
+- empty
+- error
+- disabled
+
+## Rules
+
+- build row는 선택 가능한 Material/InkWell 카드로 유지한다.
+- build metadata는 길어질 수 있으므로 한 줄 또는 두 줄 ellipsis를 허용한다.
+
+## Decision History
+
+- 2026-06-25: Jenkins build 목록 row와 상태 badge를 component로 기록했다.

agent-ui/definition/components/device-tile/index.md

@@ -0,0 +1,71 @@
+---
+ui_doc_type: component
+component_id: device-tile
+status: 구현됨
+source_evidence:
+  - type: code
+    path: lib/src/features/devices/devices_page.dart
+    notes: "_DeviceTile, _DeviceStateChip, _CompactIconButton"
+  - type: docs
+    path: README.md
+    notes: "Android device 목록 조회 scope"
+  - type: user
+    path: null
+    notes: "agent-ui 생성 요청"
+---
+
+# Device Tile
+
+Component ID: `device-tile`
+
+Status: `구현됨`
+
+## Source Evidence
+
+| Type | Path | Notes |
+|------|------|-------|
+| code | `lib/src/features/devices/devices_page.dart` | `_DeviceTile`, `_DeviceStateChip`, `_CompactIconButton` |
+| docs | `README.md` | Android device 목록 조회 scope |
+| user | 없음 | agent-ui 생성 요청 |
+
+## Purpose
+
+Android device 하나의 readiness, serial, metadata, logcat/install actions를 grid card 안에서 표시한다.
+
+## Used By
+
+- `devices`: `devices.device-grid`
+
+## Anatomy
+
+- phone icon tinted by state
+- display name
+- serial
+- product/device metadata
+- state message
+- state chip
+- logcat icon action
+- install icon action
+
+## Variants
+
+- ready: logcat 가능, pending install이 있으면 설치 가능
+- attention: offline/unauthorized 등 조치 필요
+- installing: install icon이 hourglass로 표시
+
+## States
+
+- default
+- loading: installing action 상태
+- empty: 해당 없음
+- error: device state message/chip으로 표현
+- disabled
+
+## Rules
+
+- install action은 pending install, installer, ready device, not installing 조건을 모두 만족해야 활성화한다.
+- logcat action은 ready device와 callback이 있을 때만 활성화한다.
+
+## Decision History
+
+- 2026-06-25: ADB device grid item을 component로 기록했다.

agent-ui/definition/components/index.md

@@ -0,0 +1,37 @@
+---
+ui_doc_type: components-index
+components:
+  - shell-navigation
+  - status-pill
+  - job-list
+  - build-row
+  - install-cta
+  - device-tile
+  - install-banner
+  - logcat-viewer
+  - jenkins-credential-panel
+  - adb-diagnostics
+---
+
+# Component Definitions
+
+## Component List
+
+| Component ID | Status | Evidence | Description |
+|--------------|--------|----------|-------------|
+| `shell-navigation` | 구현됨 | `lib/src/features/app_shell.dart` | AppSok brand header와 NavigationRail page 전환 |
+| `status-pill` | 구현됨 | `lib/src/features/app_shell.dart` | Jenkins/ADB 대기 상태를 top bar에 압축 표시 |
+| `job-list` | 구현됨 | `lib/src/features/builds/builds_page.dart` | Jenkins job 검색과 job row 목록 |
+| `build-row` | 구현됨 | `lib/src/features/builds/builds_page.dart` | build metadata, result badge, selected state 표시 |
+| `install-cta` | 구현됨 | `lib/src/features/builds/builds_page.dart` | APK download, progress, retry, install handoff CTA |
+| `device-tile` | 구현됨 | `lib/src/features/devices/devices_page.dart` | device 상태, metadata, logcat/install action 카드 |
+| `install-banner` | 구현됨 | `lib/src/features/devices/devices_page.dart` | pending install과 현재 설치 결과 banner |
+| `logcat-viewer` | 구현됨 | `lib/src/features/console/console_page.dart` | dark log viewer와 level-colored log line 표시 |
+| `jenkins-credential-panel` | 구현됨 | `lib/src/features/settings/settings_page.dart` | Jenkins URL, job, credential action, save/clear result 표시 |
+| `adb-diagnostics` | 구현됨 | `lib/src/features/settings/settings_page.dart` | ADB runtime source/path/version/hash 진단 row |
+
+## Rules
+
+- component 정의는 구현 API가 아니라 UI 사용 규칙을 다룬다.
+- view별 변형이 필요하면 `<component-id>/<variant>.md` 또는 하위 디렉터리를 사용한다.
+- 실제 구현체 이름과 다를 수 있지만, view 정의서에서 참조하는 component id는 이 목록에 있어야 한다.

agent-ui/definition/components/install-banner/index.md

@@ -0,0 +1,72 @@
+---
+ui_doc_type: component
+component_id: install-banner
+status: 구현됨
+source_evidence:
+  - type: code
+    path: lib/src/features/devices/devices_page.dart
+    notes: "_PendingInstallBanner와 _InstallResultBanner"
+  - type: docs
+    path: README.md
+    notes: "APK 설치와 결과 확인 scope"
+  - type: user
+    path: null
+    notes: "agent-ui 생성 요청"
+---
+
+# Install Banner
+
+Component ID: `install-banner`
+
+Status: `구현됨`
+
+## Source Evidence
+
+| Type | Path | Notes |
+|------|------|-------|
+| code | `lib/src/features/devices/devices_page.dart` | `_PendingInstallBanner`와 `_InstallResultBanner` |
+| docs | `README.md` | APK 설치와 결과 확인 scope |
+| user | 없음 | agent-ui 생성 요청 |
+
+## Purpose
+
+디바이스 화면 상단에서 pending install과 현재 설치 결과를 즉시 확인하고 필요한 후속 action을 제공한다.
+
+## Used By
+
+- `devices`: `devices.pending-install`
+- `devices`: `devices.install-result`
+
+## Anatomy
+
+- state icon
+- artifact filename
+- build/job/size/path metadata
+- cancel action
+- success/error title and label
+- masked output summary
+- copy report action
+- clear action
+
+## Variants
+
+- pending-install: 설치 대기 APK 표시
+- install-result-success: 성공 결과 표시
+- install-result-failure: 실패 결과와 exit code/output 표시
+
+## States
+
+- default
+- loading: install 진행 중 cancel disabled
+- empty: banner 없음
+- error
+- disabled
+
+## Rules
+
+- pending install path와 output은 길어질 수 있으므로 ellipsis 처리한다.
+- 복사 리포트는 masked report만 사용한다.
+
+## Decision History
+
+- 2026-06-25: pending install/result banner를 component로 기록했다.

agent-ui/definition/components/install-cta/index.md

@@ -0,0 +1,69 @@
+---
+ui_doc_type: component
+component_id: install-cta
+status: 구현됨
+source_evidence:
+  - type: code
+    path: lib/src/features/builds/builds_page.dart
+    notes: "_InstallCta와 _DownloadState"
+  - type: docs
+    path: README.md
+    notes: "APK 다운로드 및 adb install handoff scope"
+  - type: user
+    path: null
+    notes: "agent-ui 생성 요청"
+---
+
+# Install CTA
+
+Component ID: `install-cta`
+
+Status: `구현됨`
+
+## Source Evidence
+
+| Type | Path | Notes |
+|------|------|-------|
+| code | `lib/src/features/builds/builds_page.dart` | `_InstallCta`와 `_DownloadState` |
+| docs | `README.md` | APK 다운로드 및 `adb install` handoff scope |
+| user | 없음 | agent-ui 생성 요청 |
+
+## Purpose
+
+선택한 APK artifact를 다운로드/stage하고 디바이스 설치 흐름으로 넘긴다.
+
+## Used By
+
+- `builds`: `builds.install-cta`
+
+## Anatomy
+
+- state icon
+- title/status label
+- artifact/build metadata
+- download progress label and linear progress
+- cancel/retry/install button
+
+## Variants
+
+- idle: 설치 준비 또는 다운로드 취소됨
+- downloading: received/total bytes와 cancel action
+- verified: staged APK path와 install action
+- failed: error message와 retry action
+
+## States
+
+- default
+- loading
+- empty: 해당 없음
+- error
+- disabled
+
+## Rules
+
+- downloader/stager가 있으면 먼저 다운로드를 수행하고, 검증된 staged APK만 install handoff에 넘긴다.
+- 다운로드 실패 메시지는 한 줄로 줄이고 retry action을 유지한다.
+
+## Decision History
+
+- 2026-06-25: APK download/install handoff CTA를 component로 기록했다.

agent-ui/definition/components/jenkins-credential-panel/index.md

@@ -0,0 +1,76 @@
+---
+ui_doc_type: component
+component_id: jenkins-credential-panel
+status: 구현됨
+source_evidence:
+  - type: code
+    path: lib/src/features/settings/settings_page.dart
+    notes: "Jenkins card와 _WebLoginSection"
+  - type: docs
+    path: agent-roadmap/phase/security-distribution/milestones/auth-broker-evaluation.md
+    notes: "사용자별 token과 WebView token 자동화 검토 맥락"
+  - type: user
+    path: null
+    notes: "agent-ui 생성 요청"
+---
+
+# Jenkins Credential Panel
+
+Component ID: `jenkins-credential-panel`
+
+Status: `구현됨`
+
+## Source Evidence
+
+| Type | Path | Notes |
+|------|------|-------|
+| code | `lib/src/features/settings/settings_page.dart` | Jenkins card와 `_WebLoginSection` |
+| docs | `agent-roadmap/phase/security-distribution/milestones/auth-broker-evaluation.md` | 사용자별 token과 WebView token 자동화 검토 맥락 |
+| user | 없음 | agent-ui 생성 요청 |
+
+## Purpose
+
+Jenkins base URL과 credential lifecycle action을 한 카드 안에서 관리한다.
+
+## Used By
+
+- `settings`: `settings.jenkins-card`
+- `settings`: `settings.web-login-controls`
+
+## Anatomy
+
+- Jenkins section title
+- Base URL field with validation
+- default job field
+- auth mode segmented control
+- Web Login button
+- Credential 삭제 button
+- loading indicators
+- token/login/clear success labels
+- error labels
+
+## Variants
+
+- default: Web Login mode
+- busy: login/token save/session clear 진행 중
+- error: login/token save/session clear error
+- saved: token 저장 완료
+- cleared: credential 삭제 완료
+
+## States
+
+- default
+- loading
+- empty
+- error
+- disabled
+
+## Rules
+
+- Web Login action은 base URL이 valid http/https이고 busy 상태가 아닐 때만 활성화한다.
+- credential 삭제는 session clearer가 있고 busy 상태가 아닐 때만 활성화한다.
+- token 값이나 credential 원문은 UI definition이나 tracked 문서에 기록하지 않는다.
+
+## Decision History
+
+- 2026-06-25: Jenkins credential 카드와 Web Login controls를 component로 기록했다.

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

@@ -0,0 +1,69 @@
+---
+ui_doc_type: component
+component_id: job-list
+status: 구현됨
+source_evidence:
+  - type: code
+    path: lib/src/features/builds/builds_page.dart
+    notes: "_buildJobList, _JobRow, _JobStatus"
+  - type: docs
+    path: README.md
+    notes: "Jenkins job/build/artifact 조회 scope"
+  - type: user
+    path: null
+    notes: "agent-ui 생성 요청"
+---
+
+# Job List
+
+Component ID: `job-list`
+
+Status: `구현됨`
+
+## Source Evidence
+
+| Type | Path | Notes |
+|------|------|-------|
+| code | `lib/src/features/builds/builds_page.dart` | `_buildJobList`, `_JobRow`, `_JobStatus` |
+| docs | `README.md` | Jenkins job/build/artifact 조회 scope |
+| user | 없음 | agent-ui 생성 요청 |
+
+## Purpose
+
+Jenkins job/folder 후보를 검색하고 선택하게 한다.
+
+## Used By
+
+- `builds`: `builds.job-search`
+- `builds`: `builds.job-list`
+
+## Anatomy
+
+- search TextField
+- job/folder icon
+- job name
+- optional fullName
+- chevron affordance
+- status empty/error/permission view
+
+## Variants
+
+- default: loaded job list
+- status: connection, empty, forbidden, failure 상태 안내
+
+## States
+
+- default
+- loading
+- empty
+- error
+- disabled
+
+## Rules
+
+- 검색은 job name, fullName, URL 문자열을 대상으로 한다.
+- credential이 없을 때는 list 대신 연결 상태 안내를 우선 표시한다.
+
+## Decision History
+
+- 2026-06-25: Jenkins job selector를 component로 기록했다.

agent-ui/definition/components/logcat-viewer/index.md

@@ -0,0 +1,67 @@
+---
+ui_doc_type: component
+component_id: logcat-viewer
+status: 구현됨
+source_evidence:
+  - type: code
+    path: lib/src/features/console/console_page.dart
+    notes: "dark DecoratedBox log output, _LogcatLevel color mapping"
+  - type: docs
+    path: README.md
+    notes: "adb logcat 콘솔 뷰어 scope"
+  - type: user
+    path: null
+    notes: "agent-ui 생성 요청"
+---
+
+# Logcat Viewer
+
+Component ID: `logcat-viewer`
+
+Status: `구현됨`
+
+## Source Evidence
+
+| Type | Path | Notes |
+|------|------|-------|
+| code | `lib/src/features/console/console_page.dart` | dark `DecoratedBox` log output, `_LogcatLevel` color mapping |
+| docs | `README.md` | `adb logcat` 콘솔 뷰어 scope |
+| user | 없음 | agent-ui 생성 요청 |
+
+## Purpose
+
+logcat line을 고정폭 글꼴과 level별 색상으로 보여주고, 긴 stream을 스크롤 가능한 목록으로 유지한다.
+
+## Used By
+
+- `console`: `console.log-output`
+
+## Anatomy
+
+- dark rounded output surface
+- loading/error center state
+- scrollable log line list
+- level-based text color
+
+## Variants
+
+- live: stream line list
+- loading: session 시작 indicator
+- error: error message
+
+## States
+
+- default
+- loading
+- empty
+- error
+- disabled
+
+## Rules
+
+- log line은 Menlo 계열 monospace와 13px 기준으로 표시한다.
+- error/fatal line은 error color 계열로 표시한다.
+
+## Decision History
+
+- 2026-06-25: logcat 출력 surface를 component로 기록했다.

agent-ui/definition/components/shell-navigation/index.md

@@ -0,0 +1,63 @@
+---
+ui_doc_type: component
+component_id: shell-navigation
+status: 구현됨
+source_evidence:
+  - type: code
+    path: lib/src/features/app_shell.dart
+    notes: "_BrandHeader와 NavigationRail destination mapping"
+  - type: docs
+    path: README.md
+    notes: "Current Scaffold feature 목록"
+  - type: user
+    path: null
+    notes: "agent-ui 생성 요청"
+---
+
+# Shell Navigation
+
+Component ID: `shell-navigation`
+
+Status: `구현됨`
+
+## Source Evidence
+
+| Type | Path | Notes |
+|------|------|-------|
+| code | `lib/src/features/app_shell.dart` | `_BrandHeader`와 `NavigationRail` destination mapping |
+| docs | `README.md` | Current Scaffold feature 목록 |
+| user | 없음 | agent-ui 생성 요청 |
+
+## Purpose
+
+AppSok brand와 네 개의 primary destination을 항상 보이게 제공한다.
+
+## Used By
+
+- `app-shell`: `app-shell.nav`
+
+## Anatomy
+
+- AppSok icon mark
+- AppSok title과 `Jenkins to USB` subtitle
+- extended NavigationRail
+- destination icon, selected icon, label
+
+## Variants
+
+- default: desktop/macOS sidebar width 196
+
+## States
+
+- default
+- selected
+- disabled: 없음
+
+## Rules
+
+- destination은 shell이 소유한 `_pages` 순서를 따른다.
+- label은 현재 화면의 top bar title과 동일해야 한다.
+
+## Decision History
+
+- 2026-06-25: shell NavigationRail을 공통 component로 기록했다.

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

@@ -0,0 +1,65 @@
+---
+ui_doc_type: component
+component_id: status-pill
+status: 구현됨
+source_evidence:
+  - type: code
+    path: lib/src/features/app_shell.dart
+    notes: "_TopBar와 _StatusPill"
+  - type: docs
+    path: agent-ops/rules/project/rules.md
+    notes: "Jenkins credential과 ADB runtime이 주요 외부 상태"
+  - type: user
+    path: null
+    notes: "agent-ui 생성 요청"
+---
+
+# Status Pill
+
+Component ID: `status-pill`
+
+Status: `구현됨`
+
+## Source Evidence
+
+| Type | Path | Notes |
+|------|------|-------|
+| code | `lib/src/features/app_shell.dart` | `_TopBar`와 `_StatusPill` |
+| docs | `agent-ops/rules/project/rules.md` | Jenkins credential과 ADB runtime이 주요 외부 상태 |
+| user | 없음 | agent-ui 생성 요청 |
+
+## Purpose
+
+Jenkins와 ADB 같은 외부 연결 상태를 top bar에서 짧게 표시한다.
+
+## Used By
+
+- `app-shell`: `app-shell.top-bar`
+
+## Anatomy
+
+- tooltip icon
+- short label
+- outlined white container
+
+## Variants
+
+- jenkins: key icon, `Jenkins 대기`
+- adb: USB icon, `ADB 대기`
+
+## States
+
+- default
+- loading: 현재 별도 구현 없음
+- empty: 대기 상태
+- error: 현재 별도 구현 없음
+- disabled: 없음
+
+## Rules
+
+- label은 한 줄 ellipsis 없이 pill 안에 들어갈 만큼 짧아야 한다.
+- tooltip은 label보다 구체적인 상태 설명을 제공한다.
+
+## Decision History
+
+- 2026-06-25: top bar 상태 pill을 공통 component로 기록했다.

agent-ui/definition/index.md

@@ -0,0 +1,83 @@
+---
+ui_doc_type: definition-index
+surface_type: ops-dev
+source_evidence:
+  - type: code
+    path: lib/src/features/app_shell.dart
+    notes: "NavigationRail 기반 shell과 builds/devices/console/settings page 연결"
+  - type: code
+    path: lib/src/features/builds/builds_page.dart
+    notes: "Jenkins job/build 탐색과 APK download/install handoff UI"
+  - type: code
+    path: lib/src/features/devices/devices_page.dart
+    notes: "ADB device grid, pending install, install result UI"
+  - type: code
+    path: lib/src/features/console/console_page.dart
+    notes: "logcat filter, level segmented control, log viewer UI"
+  - type: code
+    path: lib/src/features/settings/settings_page.dart
+    notes: "Jenkins credential, Web Login, ADB diagnostics UI"
+  - type: code
+    path: lib/src/features/settings/jenkins_web_login_page.dart
+    notes: "fullscreen Jenkins WebView login dialog"
+  - type: docs
+    path: README.md
+    notes: "Jenkins artifact, ADB install, logcat, deep link scope"
+  - type: docs
+    path: agent-ops/rules/project/rules.md
+    notes: "Flutter macOS 앱 구조와 feature/service 분리 기준"
+  - type: docs
+    path: agent-roadmap/phase/security-distribution/milestones/auth-broker-evaluation.md
+    notes: "Jenkins WebView token 자동화와 credential 수명주기 검토 맥락"
+  - type: user
+    path: null
+    notes: "agent-ui 생성 요청"
+---
+
+# UI Definition
+
+## Purpose
+
+AppSok의 현재 Flutter macOS 화면 구조를 코드 근거와 동기화한다. 이 정의는 Jenkins artifact 탐색, APK 설치 handoff, ADB device 관리, logcat 확인, Jenkins/ADB 설정을 다루는 ops/dev UI 기준이다.
+
+## Surface Type
+
+- Type: ops-dev
+- Notes: 현재는 내부 개발/운영 도구 UI 기준이다. product UI 레이어가 필요해지면 브랜드/콘텐츠/asset/tokens/motion 문서를 추가한다.
+
+## Source Evidence
+
+| Type | Path | Notes |
+|------|------|-------|
+| code | `lib/src/features/app_shell.dart` | NavigationRail 기반 shell과 builds/devices/console/settings page 연결 |
+| code | `lib/src/features/builds/builds_page.dart` | Jenkins job/build 탐색과 APK download/install handoff UI |
+| code | `lib/src/features/devices/devices_page.dart` | ADB device grid, pending install, install result UI |
+| code | `lib/src/features/console/console_page.dart` | logcat filter, level segmented control, log viewer UI |
+| code | `lib/src/features/settings/settings_page.dart` | Jenkins credential, Web Login, ADB diagnostics UI |
+| code | `lib/src/features/settings/jenkins_web_login_page.dart` | fullscreen Jenkins WebView login dialog |
+| docs | `README.md` | Jenkins artifact, ADB install, logcat, deep link scope |
+| docs | `agent-ops/rules/project/rules.md` | Flutter macOS 앱 구조와 feature/service 분리 기준 |
+| docs | `agent-roadmap/phase/security-distribution/milestones/auth-broker-evaluation.md` | Jenkins WebView token 자동화와 credential 수명주기 검토 맥락 |
+| 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-25: 기존 Flutter UI 코드와 README/로드맵 근거를 바탕으로 `code-first` agent-ui 초안을 생성했다.

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

@@ -0,0 +1,88 @@
+---
+ui_doc_type: view
+view_id: app-shell
+status: 구현됨
+frame: null
+source_evidence:
+  - type: code
+    path: lib/src/features/app_shell.dart
+    notes: "AppSokShell, _BrandHeader, _TopBar, _StatusPill, _pages"
+  - type: docs
+    path: README.md
+    notes: "Current Scaffold feature 목록"
+  - type: user
+    path: null
+    notes: "agent-ui 생성 요청"
+regions:
+  - app-shell.nav
+  - app-shell.top-bar
+  - app-shell.content
+---
+
+# App Shell
+
+View ID: `app-shell`
+
+Frame:
+- 없음
+
+Status: `구현됨`
+
+## Source Evidence
+
+| Type | Path | Notes |
+|------|------|-------|
+| code | `lib/src/features/app_shell.dart` | `AppSokShell`, `_BrandHeader`, `_TopBar`, `_StatusPill`, `_pages` |
+| docs | `README.md` | Current Scaffold feature 목록 |
+| user | 없음 | agent-ui 생성 요청 |
+
+## Purpose
+
+AppSok의 primary navigation과 현재 feature page를 호스팅한다. shell은 pending install handoff, console target device, install result 같은 cross-page 상태를 소유한다.
+
+## Primary Users
+
+- Android artifact를 Mac에서 설치하고 확인하는 개발자 또는 QA 담당자
+
+## Primary Tasks
+
+- 빌드, 디바이스, 콘솔, 설정 화면으로 전환한다.
+- Jenkins/ADB 상태를 top bar에서 확인한다.
+- 빌드 화면에서 준비한 APK를 디바이스 화면으로 넘긴다.
+
+## Information Priority
+
+1. 현재 선택된 feature page의 제목과 업무 영역
+2. NavigationRail의 AppSok brand 및 주요 화면 목록
+3. Jenkins/ADB 상태 pill
+
+## Regions
+
+| Region ID | Purpose | Component | Priority | Notes |
+|-----------|---------|-----------|----------|-------|
+| `app-shell.nav` | AppSok brand와 네 개의 primary destination 제공 | `shell-navigation` | high | `빌드`, `디바이스`, `콘솔`, `설정` |
+| `app-shell.top-bar` | 현재 page title과 Jenkins/ADB status 표시 | `status-pill` | medium | 현재 구현은 대기 상태 pill 두 개를 고정 표시 |
+| `app-shell.content` | 선택된 feature page 렌더링 | 없음 | high | `_pages[_selectedIndex].child` |
+
+## Actions
+
+| Action ID | Trigger | Result | Guard |
+|-----------|---------|--------|-------|
+| `app-shell.select-page` | NavigationRail destination 선택 | 선택 page를 content region에 표시 | 없음 |
+| `app-shell.handoff-install` | build artifact 설치 요청 | pending install 상태를 만들고 `devices`로 이동 | staged APK가 있음 |
+| `app-shell.open-console` | device tile의 logcat action | console target device를 설정하고 `console`로 이동 | device가 ready |
+
+## States
+
+- loading: child page가 자체 loading state를 표시한다.
+- empty: child page가 자체 empty state를 표시한다.
+- error: child page가 자체 error state를 표시한다.
+- permission-denied: Jenkins credential 문제는 `builds`와 `settings`에서 표시한다.
+
+## Open Questions
+
+- 없음
+
+## Decision History
+
+- 2026-06-25: `AppSokShell` 구현을 shell view 기준으로 기록했다.

agent-ui/definition/views/builds/index.md

@@ -0,0 +1,100 @@
+---
+ui_doc_type: view
+view_id: builds
+status: 구현됨
+frame: null
+source_evidence:
+  - type: code
+    path: lib/src/features/builds/builds_page.dart
+    notes: "BuildsPage, _JobSelected, _JobRow, _BuildRow, _InstallCta"
+  - type: docs
+    path: README.md
+    notes: "Jenkins job/build/artifact 조회 scope"
+  - type: user
+    path: null
+    notes: "agent-ui 생성 요청"
+regions:
+  - builds.connection-state
+  - builds.job-search
+  - builds.job-list
+  - builds.build-search
+  - builds.build-list
+  - builds.install-cta
+---
+
+# Builds
+
+View ID: `builds`
+
+Frame:
+- 없음
+
+Status: `구현됨`
+
+## Source Evidence
+
+| Type | Path | Notes |
+|------|------|-------|
+| code | `lib/src/features/builds/builds_page.dart` | `BuildsPage`, `_JobSelected`, `_JobRow`, `_BuildRow`, `_InstallCta` |
+| docs | `README.md` | Jenkins job/build/artifact 조회 scope |
+| user | 없음 | agent-ui 생성 요청 |
+
+## Purpose
+
+Jenkins job을 검색하고 build 목록에서 APK artifact를 골라 download/stage한 뒤 디바이스 설치 흐름으로 넘긴다.
+
+## Primary Users
+
+- 특정 Jenkins build artifact를 Mac에 내려받아 Android device에 설치하려는 개발자 또는 QA 담당자
+
+## Primary Tasks
+
+- Jenkins job을 검색하고 선택한다.
+- 선택한 job의 build를 검색하고 선택한다.
+- APK artifact를 다운로드하거나 설치 handoff를 시작한다.
+
+## Information Priority
+
+1. Jenkins credential/connection 상태 또는 job/build 목록
+2. build result, branch/flavor/requestedBy/artifact metadata
+3. selected build의 download/install CTA 상태
+
+## Regions
+
+| Region ID | Purpose | Component | Priority | Notes |
+|-----------|---------|-----------|----------|-------|
+| `builds.connection-state` | credential 없음, 재로그인, 네트워크/서버 실패, 권한 없음 상태 표시 | 없음 | high | `_JobStatus`, `_BuildStatus` |
+| `builds.job-search` | Jenkins job 검색 입력 | `job-list` | high | `job-search-field` |
+| `builds.job-list` | job/folder 목록과 selection affordance | `job-list` | high | `_JobRow` |
+| `builds.build-search` | 선택 job 안의 build 검색 입력 | `build-row` | medium | `build-search-field` |
+| `builds.build-list` | build row 목록과 선택 상태 표시 | `build-row` | high | `_BuildRow`, `_StateBadge` |
+| `builds.install-cta` | APK download/progress/retry/install handoff | `install-cta` | high | `_InstallCta` |
+
+## Actions
+
+| Action ID | Trigger | Result | Guard |
+|-----------|---------|--------|-------|
+| `builds.filter-jobs` | Job 검색 입력 변경 | job list를 name/fullName/url 기준으로 필터링 | job loader loaded |
+| `builds.select-job` | job row 클릭 | build list mode로 전환 | job 선택 가능 |
+| `builds.back-to-jobs` | 목록으로 icon button | job selector mode로 복귀 | 선택 job 있음 |
+| `builds.filter-builds` | Build 검색 입력 변경 | build list를 metadata 기준으로 필터링 | build loader loaded |
+| `builds.select-build` | build row 클릭 | selected build와 install CTA 표시 | APK artifact 있음 |
+| `builds.download-artifact` | 다운로드 button | artifact download/stage 진행률 표시 | downloader/stager 있음 |
+| `builds.cancel-download` | 취소 button | download를 취소 상태로 전환 | downloading |
+| `builds.retry-download` | 재시도 button | failed download를 다시 시작 | failed |
+| `builds.request-install` | 설치 button | pending install을 shell로 전달하고 devices로 이동 | staged APK 있음 |
+
+## States
+
+- loading: job/build loader 실행 중 `CircularProgressIndicator`를 표시한다.
+- empty: 접근 가능한 job 없음, APK artifact 없음, 검색 결과 없음.
+- error: Jenkins 조회 실패, download 실패, 네트워크/서버 실패.
+- permission-denied: Jenkins 인증 필요, 재로그인 필요, job/build 접근 권한 없음.
+
+## Open Questions
+
+- 없음
+
+## Decision History
+
+- 2026-06-25: Jenkins job/build 탐색과 install CTA를 `builds` view로 기록했다.

agent-ui/definition/views/console/index.md

@@ -0,0 +1,94 @@
+---
+ui_doc_type: view
+view_id: console
+status: 구현됨
+frame: null
+source_evidence:
+  - type: code
+    path: lib/src/features/console/console_page.dart
+    notes: "ConsolePage, logcat filter controls, _LogcatLevelFilter, log viewer"
+  - type: docs
+    path: README.md
+    notes: "adb logcat 콘솔 뷰어 scope"
+  - type: user
+    path: null
+    notes: "agent-ui 생성 요청"
+regions:
+  - console.device-context
+  - console.filter-controls
+  - console.stream-actions
+  - console.log-output
+---
+
+# Console
+
+View ID: `console`
+
+Frame:
+- 없음
+
+Status: `구현됨`
+
+## Source Evidence
+
+| Type | Path | Notes |
+|------|------|-------|
+| code | `lib/src/features/console/console_page.dart` | `ConsolePage`, logcat filter controls, `_LogcatLevelFilter`, log viewer |
+| docs | `README.md` | `adb logcat` 콘솔 뷰어 scope |
+| user | 없음 | agent-ui 생성 요청 |
+
+## Purpose
+
+선택된 Android device의 logcat stream을 보고, text/level filter와 pause/clear/copy action으로 설치 후 문제를 빠르게 확인한다.
+
+## Primary Users
+
+- 설치 후 앱 실행 로그를 확인하는 개발자 또는 QA 담당자
+
+## Primary Tasks
+
+- device 선택 여부를 확인한다.
+- 패키지, 태그, 텍스트 기준으로 log line을 필터링한다.
+- ALL/DEBUG/INFO/WARN/ERROR level을 선택한다.
+- log stream을 일시정지/재개, 지우기, 복사한다.
+
+## Information Priority
+
+1. 현재 선택 device 또는 device 미선택 상태
+2. filter/level/action controls
+3. dark log output region과 error/loading state
+
+## Regions
+
+| Region ID | Purpose | Component | Priority | Notes |
+|-----------|---------|-----------|----------|-------|
+| `console.device-context` | 현재 device displayName/serial 또는 미선택 상태 표시 | 없음 | medium | `console-selected-device-label`, `console-no-device-label` |
+| `console.filter-controls` | text filter와 level segmented control | 없음 | high | filter TextField, `_LogcatLevelFilter` |
+| `console.stream-actions` | pause/resume, clear, copy visible logs | 없음 | high | icon button group |
+| `console.log-output` | level-colored log line list | `logcat-viewer` | high | dark `DecoratedBox` 안의 `ListView.builder` |
+
+## Actions
+
+| Action ID | Trigger | Result | Guard |
+|-----------|---------|--------|-------|
+| `console.filter-text` | filter TextField 변경 | visible log lines를 text 기준으로 필터링 | 없음 |
+| `console.clear-filter` | suffix close icon | filter text 초기화 | 없음 |
+| `console.filter-level` | level segmented control 선택 | selected level 이상/해당 log 표시 | 없음 |
+| `console.pause-toggle` | pause/play icon | stream 반영을 일시정지 또는 재개 | 없음 |
+| `console.clear-logs` | delete icon | 현재 log lines 제거 | 없음 |
+| `console.copy-visible-logs` | copy icon | visible log lines를 clipboard로 복사 | live logs 있음 |
+
+## States
+
+- loading: logcat session 시작 중 indicator를 표시한다.
+- empty: device가 없거나 log line이 없으면 빈 log viewer 상태가 된다.
+- error: logcat starter error를 log output 중앙에 표시한다.
+- permission-denied: device 접근 문제는 error state로 표시한다.
+
+## Open Questions
+
+- 없음
+
+## Decision History
+
+- 2026-06-25: logcat 제어와 출력 영역을 `console` view로 기록했다.

agent-ui/definition/views/devices/index.md

@@ -0,0 +1,95 @@
+---
+ui_doc_type: view
+view_id: devices
+status: 구현됨
+frame: null
+source_evidence:
+  - type: code
+    path: lib/src/features/devices/devices_page.dart
+    notes: "DevicesPage, _DeviceTile, _PendingInstallBanner, _InstallResultBanner"
+  - type: docs
+    path: README.md
+    notes: "Android device 목록 조회와 adb install scope"
+  - type: user
+    path: null
+    notes: "agent-ui 생성 요청"
+regions:
+  - devices.pending-install
+  - devices.install-result
+  - devices.filter-bar
+  - devices.device-grid
+---
+
+# Devices
+
+View ID: `devices`
+
+Frame:
+- 없음
+
+Status: `구현됨`
+
+## Source Evidence
+
+| Type | Path | Notes |
+|------|------|-------|
+| code | `lib/src/features/devices/devices_page.dart` | `DevicesPage`, `_DeviceTile`, `_PendingInstallBanner`, `_InstallResultBanner` |
+| docs | `README.md` | Android device 목록 조회와 `adb install` scope |
+| user | 없음 | agent-ui 생성 요청 |
+
+## Purpose
+
+USB로 연결된 Android device를 상태별로 확인하고, 빌드 화면에서 넘어온 pending APK를 ready device에 설치한다. 최근 설치 결과와 masked report copy action도 제공한다.
+
+## Primary Users
+
+- 설치 대상 Android device를 선택하고 설치 결과를 확인하는 개발자 또는 QA 담당자
+
+## Primary Tasks
+
+- device 목록을 새로고침하고 ready/attention 상태로 필터링한다.
+- pending APK를 ready device에 설치한다.
+- 설치 성공/실패 결과를 확인하고 리포트를 복사한다.
+- 특정 device의 logcat을 console 화면에서 연다.
+
+## Information Priority
+
+1. pending install 또는 현재 설치 결과 banner
+2. ready/attention filter와 refresh action
+3. device tile grid의 readiness, serial, metadata, install/logcat action
+
+## Regions
+
+| Region ID | Purpose | Component | Priority | Notes |
+|-----------|---------|-----------|----------|-------|
+| `devices.pending-install` | 설치 대기 APK와 취소 action 표시 | `install-banner` | high | `pending-install-banner` |
+| `devices.install-result` | 현재 설치 결과, masked output, copy/clear action 표시 | `install-banner` | high | `install-result-banner` |
+| `devices.filter-bar` | 전체/준비됨/대기 filter와 새로고침 | 없음 | medium | `SegmentedButton`, `device-refresh-button` |
+| `devices.device-grid` | device tile grid와 install/logcat action | `device-tile` | high | `GridView.builder` |
+
+## Actions
+
+| Action ID | Trigger | Result | Guard |
+|-----------|---------|--------|-------|
+| `devices.change-filter` | SegmentedButton 선택 | 전체/준비됨/대기 device 목록을 표시 | 없음 |
+| `devices.refresh` | 새로고침 button | ADB device loader 재실행 | loading 중이 아님 |
+| `devices.cancel-pending-install` | pending banner close button | pending APK cleanup 요청 | install 진행 중이 아님 |
+| `devices.install` | device tile 설치 icon | selected device에 pending APK 설치 | pending install 있음, device ready, installer 있음 |
+| `devices.open-logcat` | device tile logcat icon | console view로 이동하고 device를 선택 | device ready |
+| `devices.copy-install-report` | 설치 결과 copy icon | masked report를 clipboard로 복사 | install result 있음 |
+| `devices.clear-install-result` | 설치 결과 close icon | 현재 install result banner 제거 | install result 있음 |
+
+## States
+
+- loading: device refresh 중 linear progress와 empty grid loading indicator를 표시한다.
+- empty: device가 없으면 empty view를 표시한다.
+- error: ADB device load error와 retry action을 표시한다.
+- permission-denied: ADB 권한/상태 문제는 device state chip과 error로 표현한다.
+
+## Open Questions
+
+- 없음
+
+## Decision History
+
+- 2026-06-25: ADB device grid와 install handoff 상태를 `devices` view로 기록했다.

agent-ui/definition/views/index.md

@@ -0,0 +1,48 @@
+---
+ui_doc_type: views-index
+views:
+  - app-shell
+  - builds
+  - devices
+  - console
+  - settings
+  - jenkins-web-login
+---
+
+# View Definitions
+
+## View Tree
+
+| View ID | Status | Evidence | Description |
+|---------|--------|----------|-------------|
+| `app-shell` | 구현됨 | `lib/src/features/app_shell.dart` | AppSok 브랜드, NavigationRail, top bar, 현재 page host |
+| `builds` | 구현됨 | `lib/src/features/builds/builds_page.dart` | Jenkins job/build 탐색과 APK download/install handoff |
+| `devices` | 구현됨 | `lib/src/features/devices/devices_page.dart` | ADB device 목록, pending install 실행, 설치 결과 표시 |
+| `console` | 구현됨 | `lib/src/features/console/console_page.dart` | 선택 device의 logcat 스트림 확인과 필터링 |
+| `settings` | 구현됨 | `lib/src/features/settings/settings_page.dart` | Jenkins credential/Web Login, ADB path, diagnostics 설정 |
+| `jenkins-web-login` | 구현됨 | `lib/src/features/settings/jenkins_web_login_page.dart` | Jenkins 로그인 WebView와 token bridge 진행 상태 |
+
+## Navigation
+
+- `app-shell` -> `builds`: NavigationRail `빌드`
+- `app-shell` -> `devices`: NavigationRail `디바이스`
+- `app-shell` -> `console`: NavigationRail `콘솔`, 또는 device tile `logcat` action
+- `app-shell` -> `settings`: NavigationRail `설정`
+- `settings` -> `jenkins-web-login`: Web Login action이 fullscreen dialog를 연다.
+- `builds` -> `devices`: APK download/stage 완료 후 install handoff가 pending install 상태로 전환한다.
+
+## Common States
+
+- loading: Jenkins job/build, ADB device, logcat, diagnostics, WebView load 중 표시
+- empty: 접근 가능한 job 없음, APK artifact 없음, device 없음, 검색 결과 없음
+- error: Jenkins 조회 실패, ADB load 실패, logcat error, token 저장/삭제 실패, WebView error
+- permission-denied: Jenkins 권한 없음 또는 재로그인 필요
+
+## Common Permissions
+
+- Jenkins credential: `builds`의 job/build 조회와 artifact download에 필요하다.
+- ADB runtime: `devices` refresh/install, `console` logcat, `settings` diagnostics에 필요하다.
+
+## Open Questions
+
+- 없음

agent-ui/definition/views/jenkins-web-login/index.md

@@ -0,0 +1,88 @@
+---
+ui_doc_type: view
+view_id: jenkins-web-login
+status: 구현됨
+frame: null
+source_evidence:
+  - type: code
+    path: lib/src/features/settings/jenkins_web_login_page.dart
+    notes: "JenkinsWebLoginPage, AppBar, WebViewWidget, error overlay"
+  - type: docs
+    path: agent-roadmap/phase/security-distribution/milestones/auth-broker-evaluation.md
+    notes: "WebView 로그인 후 token 자동 발급 후보 검토"
+  - type: user
+    path: null
+    notes: "agent-ui 생성 요청"
+regions:
+  - jenkins-web-login.app-bar
+  - jenkins-web-login.webview
+  - jenkins-web-login.error-overlay
+---
+
+# Jenkins Web Login
+
+View ID: `jenkins-web-login`
+
+Frame:
+- 없음
+
+Status: `구현됨`
+
+## Source Evidence
+
+| Type | Path | Notes |
+|------|------|-------|
+| code | `lib/src/features/settings/jenkins_web_login_page.dart` | `JenkinsWebLoginPage`, `AppBar`, `WebViewWidget`, error overlay |
+| docs | `agent-roadmap/phase/security-distribution/milestones/auth-broker-evaluation.md` | WebView 로그인 후 token 자동 발급 후보 검토 |
+| user | 없음 | agent-ui 생성 요청 |
+
+## Purpose
+
+Jenkins 로그인 페이지를 fullscreen WebView로 열고, 로그인 확인 및 API token bridge를 진행한다.
+
+## Primary Users
+
+- Jenkins credential을 앱에 저장하기 위해 Web Login을 수행하는 사용자
+
+## Primary Tasks
+
+- Jenkins 로그인 WebView에서 인증을 완료한다.
+- 로딩/token issue 진행 상태를 확인한다.
+- 오류 발생 시 reload를 시도하거나 dialog를 닫는다.
+
+## Information Priority
+
+1. Jenkins 로그인 WebView
+2. AppBar title/close action과 loading/token issue indicator
+3. error overlay와 retry action
+
+## Regions
+
+| Region ID | Purpose | Component | Priority | Notes |
+|-----------|---------|-----------|----------|-------|
+| `jenkins-web-login.app-bar` | dialog title, close action, loading indicator | 없음 | high | `Jenkins 로그인` |
+| `jenkins-web-login.webview` | Jenkins login page 표시와 JS bridge 실행 | 없음 | high | `WebViewWidget` |
+| `jenkins-web-login.error-overlay` | page/probe/token 오류와 retry action | 없음 | high | `_errorMessage`가 있을 때 표시 |
+
+## Actions
+
+| Action ID | Trigger | Result | Guard |
+|-----------|---------|--------|-------|
+| `jenkins-web-login.close` | AppBar close icon | dialog 종료 | 없음 |
+| `jenkins-web-login.reload` | 다시 시도 button | error message를 지우고 WebView reload | error message 있음 |
+| `jenkins-web-login.complete-token` | 내부 token bridge 성공 | result를 settings page로 반환 | Jenkins user/token 확인 완료 |
+
+## States
+
+- loading: page load 또는 token issue 중 AppBar indicator를 표시한다.
+- empty: 해당 없음.
+- error: error overlay와 다시 시도 action을 표시한다.
+- permission-denied: Jenkins 로그인 실패/anonymous 상태는 error 또는 WebView 인증 화면으로 남는다.
+
+## Open Questions
+
+- 없음
+
+## Decision History
+
+- 2026-06-25: fullscreen Jenkins WebView login dialog를 별도 view로 기록했다.

agent-ui/definition/views/settings/index.md

@@ -0,0 +1,97 @@
+---
+ui_doc_type: view
+view_id: settings
+status: 구현됨
+frame: null
+source_evidence:
+  - type: code
+    path: lib/src/features/settings/settings_page.dart
+    notes: "SettingsPage, _WebLoginSection, _AdbDiagnosticsSection"
+  - type: docs
+    path: README.md
+    notes: "사용자별 Jenkins API token 저장과 ADB 설정 scope"
+  - type: docs
+    path: agent-roadmap/phase/security-distribution/milestones/auth-broker-evaluation.md
+    notes: "WebView token 자동 발급과 credential 정책 검토 맥락"
+  - type: user
+    path: null
+    notes: "agent-ui 생성 요청"
+regions:
+  - settings.jenkins-card
+  - settings.web-login-controls
+  - settings.adb-card
+  - settings.adb-diagnostics
+---
+
+# Settings
+
+View ID: `settings`
+
+Frame:
+- 없음
+
+Status: `구현됨`
+
+## Source Evidence
+
+| Type | Path | Notes |
+|------|------|-------|
+| code | `lib/src/features/settings/settings_page.dart` | `SettingsPage`, `_WebLoginSection`, `_AdbDiagnosticsSection` |
+| docs | `README.md` | 사용자별 Jenkins API token 저장과 ADB 설정 scope |
+| docs | `agent-roadmap/phase/security-distribution/milestones/auth-broker-evaluation.md` | WebView token 자동 발급과 credential 정책 검토 맥락 |
+| user | 없음 | agent-ui 생성 요청 |
+
+## Purpose
+
+Jenkins base URL과 credential 흐름, ADB path/update option, ADB runtime diagnostics를 관리한다.
+
+## Primary Users
+
+- Jenkins credential과 ADB runtime 상태를 준비하는 개발자 또는 QA 담당자
+
+## Primary Tasks
+
+- Jenkins base URL을 입력하고 Web Login을 시작한다.
+- token 저장/credential 삭제 결과를 확인한다.
+- ADB path와 설치 전 update option을 확인한다.
+- ADB runtime source/path/version/hash diagnostics를 새로고침한다.
+
+## Information Priority
+
+1. Jenkins URL validation과 Web Login/Credential 삭제 actions
+2. token 저장/삭제 결과와 오류 feedback
+3. ADB path/update option과 diagnostics rows
+
+## Regions
+
+| Region ID | Purpose | Component | Priority | Notes |
+|-----------|---------|-----------|----------|-------|
+| `settings.jenkins-card` | Jenkins base URL, default job, auth mode selector 표시 | `jenkins-credential-panel` | high | Base URL validation 포함 |
+| `settings.web-login-controls` | Web Login, Credential 삭제, 저장/삭제 결과 feedback | `jenkins-credential-panel` | high | `_WebLoginSection` |
+| `settings.adb-card` | adb path field, 찾기 button, install update switch | 없음 | medium | 현재 일부 control은 placeholder action |
+| `settings.adb-diagnostics` | ADB runtime diagnostics row와 refresh action | `adb-diagnostics` | medium | diagnostics loader가 있을 때 표시 |
+
+## Actions
+
+| Action ID | Trigger | Result | Guard |
+|-----------|---------|--------|-------|
+| `settings.edit-base-url` | Base URL 입력 | URL validation error 표시 여부 갱신 | 없음 |
+| `settings.open-web-login` | Web Login button | Jenkins Web Login dialog 시작 | base URL이 유효하고 busy 아님 |
+| `settings.clear-credential` | Credential 삭제 button | 저장된 session 삭제 시도 | clearer 있음, busy 아님 |
+| `settings.refresh-adb-diagnostics` | diagnostics refresh icon | ADB runtime diagnostics reload | diagnostics loader 있음 |
+| `settings.pick-adb-path` | 찾기 button | 현재 구현은 placeholder | 없음 |
+
+## States
+
+- loading: Web Login, token 저장, session 삭제, diagnostics loading 상태를 indicator로 표시한다.
+- empty: diagnostics 없음 또는 optional diagnostics loader 없음.
+- error: URL validation error, 로그인 오류, token 저장 실패, credential 삭제 실패, diagnostics load 실패.
+- permission-denied: Jenkins 재인증 필요 상태는 `builds`에서 사용자를 설정으로 유도한다.
+
+## Open Questions
+
+- 없음
+
+## Decision History
+
+- 2026-06-25: Jenkins credential과 ADB diagnostics UI를 `settings` view로 기록했다.

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가 없으므로 view별 frame 문서는 만들지 않는다.
+- `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와 동일해야 한다.