<!-- task=m-embeddable-iop-console-workbench/01_console_api plan=0 tag=API -->

# Plan - API

## 이 파일을 읽는 구현 에이전트에게

`CODE_REVIEW-cloud-G06.md`의 구현 에이전트 소유 섹션을 채우는 것이 구현의 마지막 단계다. 구현 후 검증을 실행하고 실제 출력, 계획 대비 변경 사항, 주요 설계 결정을 기록한 뒤 active 파일을 그대로 두고 리뷰 준비를 보고한다. 사용자 결정, 사용자 소유 외부 환경, scope 충돌 없이는 안전하게 진행할 수 없을 때만 review stub의 `사용자 리뷰 요청`을 근거와 함께 채우고 멈춘다. 명령 재실행이나 산출물 수집으로 해소 가능한 evidence 공백은 사용자 리뷰 요청이 아니다.

## 배경

현재 `iop_console`은 shell과 agent panel을 export하지만 endpoint/auth/theme/navigation 주입, IOP capability pack, Execution/Logs 표시 경로가 public contract로 정리되지 않았다. 이 작업은 package 쪽 API와 테스트만 세워 후속 client integration이 같은 contract를 쓰게 한다. Roadmap Task 체크는 후속 `02+01_client_integration`에서 통합 검증 후 처리한다.

## 사용자 리뷰 요청 흐름

구현 중 차단이 생기면 active `CODE_REVIEW-cloud-G06.md`의 `사용자 리뷰 요청` 섹션을 `agent-ops/skills/common/_templates/implementation-user-review-request-section.md` 형식으로 채운다. code-review가 정당성을 확인하고 실제 `USER_REVIEW.md` 작성 여부를 결정한다.

## 분석 결과

### 읽은 파일

- `agent-roadmap/current.md`
- `agent-roadmap/phase/control-plane-portal-ops/PHASE.md`
- `agent-roadmap/phase/control-plane-portal-ops/milestones/embeddable-iop-console-workbench.md`
- `agent-ops/rules/project/domain/client/rules.md`
- `agent-ops/rules/project/domain/testing/rules.md`
- `agent-test/local/rules.md`
- `agent-test/local/client-smoke.md`
- `packages/flutter/iop_console/lib/iop_console.dart`
- `packages/flutter/iop_console/lib/src/iop_console_shell.dart`
- `packages/flutter/iop_console/lib/src/iop_agent_panel.dart`
- `packages/flutter/iop_console/pubspec.yaml`
- `packages/flutter/iop_console/test/iop_console_shell_test.dart`
- `apps/client/lib/main.dart`
- `apps/client/test/widget_test.dart`
- `apps/client/pubspec.yaml`
- `agent-ops/skills/common/_templates/implementation-user-review-request-section.md`

### 테스트 환경 규칙

- test_env: `local`
- env rules: `agent-test/local/rules.md` present/read.
- matched profile: `agent-test/local/client-smoke.md` present/read.
- 적용 명령: `cd packages/flutter/iop_console && flutter test`; public API/widget 구조 변경이므로 package test가 필수다.
- fallback: 없음.

### 테스트 커버리지 공백

- Public config/capability API: 현재 test 없음. 새 package widget/unit test로 normal/default/boundary를 추가해야 한다.
- Execution/Logs section route: 현재 enum/rail에 없음. 새 package widget test가 rail 전환과 placeholder 또는 injected widget 표시를 확인해야 한다.
- Host injection ownership: 현재 `IopConsoleShell`은 section widget만 받는다. 새 test가 config/theme/navigation callback을 package API로 주입 가능함을 확인해야 한다.

### 심볼 참조

- 제거/rename 예정 symbol: 없음.
- 추가 예정 symbol: `IopConsoleConfig`, `IopConsoleThemeAdapter` 또는 동등 타입, `IopConsoleNavigation`, `IopCapability`, `IopCapabilityPack`, `IopConsoleOverview` 또는 동등 public widget. 기존 call site는 `apps/client/lib/main.dart:195`의 `IopConsoleShell` mount와 package tests다.

### 분할 판단

- split decision policy를 먼저 평가했다.
- 공유 task group: `m-embeddable-iop-console-workbench`
- `01_console_api`: package public API, package tests. dependency 없음.
- `02+01_client_integration`: apps/client 적용, roadmap target check. predecessor `01_console_api`의 `complete.log` 필요. 현재 predecessor는 새 active sibling으로 계획되며 아직 complete.log가 없다.
- API/foundation과 app call-site rollout이 분리되고, package test와 app test가 다른 risk profile이므로 split이 필요하다.

### 범위 결정 근거

- `apps/control-plane/**`, protobuf, Go service는 제외한다. 이 작업은 UI package API contract만 다룬다.
- NomadCode product shell, WebView/workflow UX는 Milestone 범위 제외라 구현하지 않는다.
- 실제 Control Plane 상태 조회 API는 후속 Control Plane/Client Milestone 범위로 남기고, 여기서는 host가 주입하는 config/status/capability surface만 만든다.

### 빌드 등급

- build lane: `cloud-G06`; review lane: `cloud-G06`.
- 공개 API와 후속 app integration에 영향을 주지만 Flutter package 내부 중심이고 테스트 명령이 명확하다.

## 구현 체크리스트

- [ ] `iop_console` public config/navigation/theme/capability 타입과 export를 추가한다.
- [ ] `IopConsoleShell`에 Execution/Logs section과 host injection contract를 추가하고 기존 callers의 기본 동작을 유지한다.
- [ ] package tests로 public API, Execution/Logs route, narrow/wide stability를 검증한다.
- [ ] `cd packages/flutter/iop_console && flutter test`를 실행한다.
- [ ] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.

## [API-1] Package Contract

### 문제

`IopConsoleShell`은 section widget만 받으며 endpoint/auth/theme/navigation/capability contract가 없다. 관련 위치: `packages/flutter/iop_console/lib/src/iop_console_shell.dart:15`, `packages/flutter/iop_console/lib/src/iop_agent_panel.dart:4`, `packages/flutter/iop_console/lib/iop_console.dart:1`.

### 해결 방법

`packages/flutter/iop_console/lib/src/` 아래에 public contract 파일을 추가하고 export한다. 최소 타입은 config, navigation callback, theme adapter, capability item/pack이다.

Before:

```dart
// packages/flutter/iop_console/lib/iop_console.dart:1
export 'src/iop_agent_panel.dart';
export 'src/iop_console_shell.dart';
```

After:

```dart
export 'src/iop_agent_panel.dart';
export 'src/iop_console_contract.dart';
export 'src/iop_console_shell.dart';
```

### 수정 파일 및 체크리스트

- [ ] `packages/flutter/iop_console/lib/src/iop_console_contract.dart` 추가.
- [ ] `packages/flutter/iop_console/lib/iop_console.dart` export 추가.
- [ ] `packages/flutter/iop_console/lib/src/iop_agent_panel.dart`가 capability pack을 선택적으로 표시하거나 받을 수 있게 한다.

### 테스트 작성

`packages/flutter/iop_console/test/iop_console_shell_test.dart`에 public config/capability 타입을 import/instantiate하는 test를 추가한다.

### 중간 검증

```bash
cd packages/flutter/iop_console && flutter test
```

기대: 모든 package test 통과.

## [API-2] Shell Sections And Injection

### 문제

`IopConsoleSection`에는 Execution/Logs가 없고 `settings` placeholder만 endpoint preferences를 암시한다. 관련 위치: `packages/flutter/iop_console/lib/src/iop_console_shell.dart:5`, `packages/flutter/iop_console/lib/src/iop_console_shell.dart:101`.

### 해결 방법

`executionLogs` 또는 동등 section을 추가하고 rail에 icon/button을 넣는다. `IopConsoleShell`은 `config`, `themeAdapter`, `onNavigate`, `executionLogs`, `capabilities`를 선택적으로 받으며 기본 placeholder는 기존 UI 톤을 유지한다.

Before:

```dart
// packages/flutter/iop_console/lib/src/iop_console_shell.dart:5
enum IopConsoleSection {
  overview,
  edges,
  nodes,
  runtime,
  maintenance,
  agent,
  settings,
}
```

After:

```dart
enum IopConsoleSection {
  overview,
  edges,
  nodes,
  runtime,
  executionLogs,
  maintenance,
  agent,
  settings,
}
```

### 수정 파일 및 체크리스트

- [ ] `packages/flutter/iop_console/lib/src/iop_console_shell.dart` section enum/rail/switch 갱신.
- [ ] `IopConsoleShell` constructor에 optional injection params 추가.
- [ ] 기존 `overview`, `agent`, section widget injection call sites를 깨지 않게 기본값 유지.

### 테스트 작성

`packages/flutter/iop_console/test/iop_console_shell_test.dart`에 Execution/Logs rail tap test와 injected widget 표시 test를 추가한다.

### 중간 검증

```bash
cd packages/flutter/iop_console && flutter test
```

기대: 모든 package test 통과.

## [API-3] Reusable Overview Surface

### 문제

Control Plane wire overview는 `apps/client/lib/main.dart:201`의 private host widget에만 있다. package consumer가 재사용할 overview widget이 없다.

### 해결 방법

`IopConsoleOverview` 또는 동등 public widget을 package에 추가한다. 이 widget은 config와 status 문자열/refresh callback을 받고, 실제 wire connection 소유권은 host에 남긴다.

### 수정 파일 및 체크리스트

- [ ] `packages/flutter/iop_console/lib/src/iop_console_overview.dart` 추가.
- [ ] `packages/flutter/iop_console/lib/iop_console.dart` export 추가.
- [ ] overview widget은 Control Plane client를 import하지 않는다.

### 테스트 작성

Package test에서 HTTP/Wire endpoint, status text, callback button이 표시되는지 확인한다.

### 중간 검증

```bash
cd packages/flutter/iop_console && flutter test
```

기대: 모든 package test 통과.

## 수정 파일 요약

| 파일 | 항목 |
|------|------|
| `packages/flutter/iop_console/lib/iop_console.dart` | API-1, API-3 |
| `packages/flutter/iop_console/lib/src/iop_console_contract.dart` | API-1 |
| `packages/flutter/iop_console/lib/src/iop_console_shell.dart` | API-2 |
| `packages/flutter/iop_console/lib/src/iop_console_overview.dart` | API-3 |
| `packages/flutter/iop_console/lib/src/iop_agent_panel.dart` | API-1 |
| `packages/flutter/iop_console/test/iop_console_shell_test.dart` | API-1, API-2, API-3 |

## 최종 검증

```bash
cd packages/flutter/iop_console && flutter test
```

기대: `All tests passed!`

모든 코드 변경 완료 후 반드시 `CODE_REVIEW-*-G??.md`의 구현 에이전트 소유 섹션을 채운다. 이 파일 작성이 구현의 마지막 단계다.
