@morit/cli 1.0.0 → 1.1.0

package/assets/docs/troubleshooting.md

@@ -0,0 +1,117 @@
+# 오류 해결
+
+오류를 catch로 숨기기 전에 어느 경계에서 발생했는지 구분합니다.
+
+## 빠른 진단 순서
+
+```text
+source를 읽을 수 있는가
+  → validate가 성공하는가
+  → preview artifact가 생기는가
+  → signed build와 reopen이 성공하는가
+  → API 인증과 목록 조회가 성공하는가
+  → 설치 상태가 active인가
+  → Connection과 권한이 ready인가
+  → capability가 실행되는가
+  → UI가 결과를 렌더링하는가
+```
+
+앞 단계가 실패한 상태에서 다음 단계 오류를 우회하지 않습니다.
+
+## Validate 오류
+
+| 증상 | 확인 항목 |
+|---|---|
+| unknown field | 문서에 없는 key 제거, v1/v2 필드 혼합 여부 |
+| duplicate ID | manifest 배열과 모든 fragment를 함께 검색 |
+| unknown permission | 지원 목록과 Manifest 전역 권한 확인 |
+| capability reference | UI, Slash Command, child dependency 대상 ID 확인 |
+| state/data binding | `initial_state`, `data_sources`, `item` scope 확인 |
+| source entrypoint | 각 `src/*.py`와 `sandbox_python` 1:1 확인 |
+| image asset | `assets/` 경로·확장자·실제 파일 확인 |
+
+진단에 표시된 첫 오류부터 고치고 다시 validate합니다. 허용 필드를 늘리거나 unknown key를 무시하게
+바꾸지 않습니다.
+
+## Preview 오류
+
+preview 전에 validate가 실행됩니다. artifact가 없으면 출력 디렉터리 권한과 source size를 확인합니다.
+preview가 열려도 실제 앱의 typography, navigation, scroll, async state는 별도 검증 대상입니다.
+
+## Build·signature 오류
+
+- output 확장자가 `.mplg`인지 확인합니다.
+- package가 2 MiB, 64 entry 한도 안인지 확인합니다.
+- private key 파일 권한과 publisher identity를 확인합니다.
+- source ZIP을 `.mplg`로 이름만 바꾸지 않았는지 확인합니다.
+- `verify`가 반환한 plugin ID, publisher, version, SHA-256을 기록합니다.
+- trusted publisher에 등록된 key와 embedded public key가 다른 경우 올바른 조직 key로 다시 build합니다.
+
+## 목록 조회와 설치 오류
+
+`Not Found`는 URL 이동으로 해결하지 않습니다. API base URL, 배포 route, 인증 header, 사용자 RLS를
+확인합니다. `401`은 endpoint가 없다는 뜻이 아니라 인증이 필요하다는 뜻입니다.
+
+설치 뒤 목록 조회가 실패했다가 재시도에서 duplicate가 나오면 package file, Installation row,
+default Instance, cache가 하나의 atomic transaction으로 정리되는지 확인합니다. 앱 데이터 삭제만으로
+서버 DB와 외부 저장소는 삭제되지 않습니다. 사용자별 API 목록과 서버 package store를 함께 확인합니다.
+
+정상 duplicate는 같은 plugin ID·publisher·version 정책으로 판단하고 파일명만 사용하지 않습니다.
+
+## Connection 오류
+
+| 상태 | 의미 | 사용자 동작 |
+|---|---|---|
+| `not_configured` | 필수 Connection/Secret 없음 | 계정 연결 또는 Developer Secret 설정 |
+| `unavailable` | provider·암호화·runtime 사용 불가 | 운영 설정 확인 |
+| credential rejected | token 만료·철회 | 한 번 refresh 후 다시 연결 |
+| rate limited | Connector 한도 초과 | 제한된 시간 뒤 재시도 |
+
+token을 로그에 출력해 진단하지 않습니다. 연결 metadata와 공개 오류 코드만 사용합니다.
+
+## Capability 오류
+
+- permission required: Manifest와 capability 권한, 사용자 grant 확인
+- disabled/incompatible: Instance state와 Morit version 확인
+- timeout: capability timeout과 Connector timeout을 비교하고 작업을 작게 나눔
+- retryable network: Connector의 bounded retry만 사용
+- invalid response: `summary`, `data`, `evidence` 형태와 외부 response mapping 확인
+- code worker unavailable: broker/worker health와 lease 확인; Archive process에서 직접 실행하지 않음
+
+Tool 하나의 실패가 AI 요청 전체 실패를 뜻하지 않는 경우 대체 Tool·부분 결과·재연결을 시도하고
+최종 답변에 남은 제한을 설명합니다.
+
+## UI 오류
+
+- 해당 extension만 fallback되고 대화·앱 전체가 계속 동작하는지 확인합니다.
+- 없는 state/data/route를 참조하지 않는지 확인합니다.
+- list/timeline child가 정확히 하나인지 확인합니다.
+- `surface`가 children을 가지는지 확인합니다.
+- `positioned`는 `stack`, `expanded`는 `row`/`column` 안인지 확인합니다.
+- literal image URL 대신 capability result binding을 사용했는지 확인합니다.
+- 원격 이미지가 안 보이면 Manifest와 활성 Instance의 `network` 권한, public HTTPS 여부를 먼저
+  확인합니다. redirect, MIME/magic 불일치, 손상된 파일, 512 KiB 또는 가로·세로 4096 px 초과는
+  Host가 의도적으로 차단합니다. 애니메이션은 최대 128 frame이고 `width × height × frame 수`로
+  계산한 frame 합산 pixel이 16,000,000 이하여야 합니다.
+- 원격 이미지 실패를 앱 직접 fetch나 임의 외부 URL widget으로 우회하지 않습니다.
+- Response UI가 원래 AI 메시지 안의 한 container에 붙는지 확인합니다.
+
+## MCP 오류
+
+Local MCP:
+
+```bash
+node --version
+npx -y @morit/plugin-mcp
+codex mcp list
+```
+
+Remote MCP:
+
+```bash
+curl -i https://morit-api.moring.co/mcp
+```
+
+인증 전 `401`과 `WWW-Authenticate`는 정상 OAuth 시작 신호입니다. `404`는 ingress route, `5xx`는
+MCP service health와 server log를 확인합니다. Codex에서는 `codex mcp login <name>`, Tool 목록에서는
+`morit_sdk_contract`와 `morit_docs_search`를 먼저 확인합니다.

package/assets/docs/ui-extensions.md

@@ -0,0 +1,70 @@
+# UI extension point
+
+UI extension은 Host의 노출 위치와 Runtime config를 연결합니다.
+
+```json
+{
+  "id": "school_life.home",
+  "point": "screen",
+  "title": "학교 생활",
+  "order": 10,
+  "permissions": ["network", "storage"],
+  "config": {
+    "ui_schema": 2,
+    "view": {"type": "text", "props": {"text": "오늘 학교 생활"}}
+  }
+}
+```
+
+## point 선택
+
+| point | 노출 위치 | 사용 기준 |
+|---|---|---|
+| `screen` | 독립 플러그인 화면 | 목록·상세·편집 등 주 작업 |
+| `surface` | 기존 일반 surface | 기존 패키지 호환; 새 화면은 `screen` 권장 |
+| `menu` | 홈 플러그인 메뉴 | 독립 화면으로 가는 보조 진입점 |
+| `action` | 홈 extension 영역 | 짧은 즉시 행동 또는 작은 embedded UI |
+| `card` | 홈 extension 영역 | 상태·진행·다음 행동 요약 |
+| `settings` | 플러그인 상세의 설정 영역 | 사용자 설정과 Connection 진입 |
+| `workspace` | Morit AI 작업 공간 선택기 | 대화와 함께 쓰는 독립 작업 surface |
+| `response` | capability를 실행한 AI 메시지 내부 | 읽기 중심 결과와 후속 행동 |
+
+일반 Tool/Skill은 자동으로 `workspace`가 되지 않습니다. AI 작업 공간 UI가 필요할 때만 별도
+`workspace` extension을 선언합니다. Slash Command와 Tool discovery도 별도 계약입니다.
+
+## Home placement
+
+Runtime v2의 `card`와 `action`은 고유 section을 만들 수 있습니다.
+
+```json
+{
+  "placement": {
+    "section_id": "school_life.home",
+    "section_title": "학교 생활",
+    "section_order": 15,
+    "layout": "grid",
+    "show_header": true
+  }
+}
+```
+
+`layout`은 `stack`, `horizontal`, `grid`입니다. 같은 플러그인에서 같은 `section_id`를 사용한
+extension은 함께 배치됩니다. 다른 플러그인의 ID와 겹치지 않게 package namespace를 붙입니다.
+`placement`는 `card`와 `action`에서만 사용할 수 있습니다.
+
+## 권한과 action
+
+UI `permissions`는 Manifest 전역 권한의 부분집합입니다. 화면이 참조하는 capability도 자신의 권한을
+따로 가집니다. UI가 표시됐다는 사실만으로 capability 권한이 허용되는 것은 아닙니다. `invoke`는
+enabled, generation, granted permission, timeout을 Host 실행 경계에서 다시 확인합니다.
+
+## Runtime v1 호환
+
+`ui_schema`가 없는 기존 extension은 `sections`, `actions`, `form`, shorthand `capability`/`label`을
+사용하는 Runtime v1으로 읽힙니다. v1은 기존 설치 호환용입니다. 새 서비스형 화면에는 state,
+data source, navigation, theme, Response UI를 함께 사용할 수 있는 Runtime v2를 사용합니다.
+
+Runtime v1 action style은 `primary` 또는 `secondary`이고, form field는 `text`, `integer`,
+`select`만 지원합니다. v1 JSON에 v2 필드를 섞으면 오류입니다.
+
+다음은 [UI Runtime v2 레퍼런스](ui-runtime-v2.md)입니다.

package/assets/docs/ui-runtime-v2.md

@@ -0,0 +1,273 @@
+# UI Runtime v2 레퍼런스
+
+UI Runtime v2는 서명된 `.mplg`가 화면, 상태, data source, action을 JSON으로 선언하는 Host-rendered
+계약입니다. Flutter/Dart, JavaScript, HTML, CSS, WebView, native code를 UI로 실행하지 않습니다.
+
+## Config 구조
+
+```json
+{
+  "ui_schema": 2,
+  "icon": "calendar",
+  "description": "오늘과 이번 주 학교 생활을 확인합니다.",
+  "theme": {
+    "density": "standard",
+    "radius": 18,
+    "spacing": 12
+  },
+  "app_bar": {
+    "title": "학교 생활",
+    "subtitle": "{{data.today.summary}}",
+    "pinned": true,
+    "actions": [
+      {
+        "id": "settings",
+        "label": "설정",
+        "icon": "settings",
+        "show_as": "overflow",
+        "action": {"type": "navigate", "target": "school_life.settings"}
+      }
+    ]
+  },
+  "navigation": {
+    "type": "adaptive",
+    "selected_state_key": "section",
+    "persist": true,
+    "label_behavior": "selected",
+    "items": [
+      {
+        "id": "today",
+        "label": "오늘",
+        "icon": "calendar",
+        "value": "today",
+        "action": {"type": "set_state", "values": {"section": "today"}}
+      },
+      {
+        "id": "week",
+        "label": "이번 주",
+        "icon": "clock",
+        "value": "week",
+        "action": {"type": "navigate", "target": "school_life.week"}
+      }
+    ]
+  },
+  "initial_state": {"section": "today"},
+  "data_sources": [
+    {
+      "id": "today",
+      "capability": "school_life.today",
+      "trigger": "load",
+      "query": null,
+      "arguments": {},
+      "refresh_seconds": 300
+    }
+  ],
+  "view": {
+    "type": "column",
+    "props": {"spacing": 12},
+    "children": [
+      {"type": "text", "props": {"text": "{{data.today.summary}}", "style": "heading"}}
+    ]
+  }
+}
+```
+
+허용 config 필드는 `ui_schema`, `icon`, `description`, `placement`, `app_bar`, `navigation`,
+`theme`, `initial_state`, `data_sources`, `view`입니다.
+
+## 트리와 크기 제한
+
+- tree 최대 160 node, depth 12(root가 depth 0), node당 child 최대 32개
+- data source 최대 8개
+- state key 최대 32개
+- config JSON 최대 32 KiB
+- 자동 refresh 30~86,400초
+- 한 extension의 app bar action 최대 6개
+- navigation item 2~8개
+- binding 깊이 최대 12 segment
+- JSON binding 값 깊이 최대 8, 배열·객체 항목 최대 64개
+
+`positioned`, `scroll`, `padding`, `center`, `expanded`, `badge`는 child를 정확히 하나만 가집니다.
+`surface`는 child가 하나 이상이어야 합니다. `positioned`는 `stack`의 직접 child이고 `left`, `top`,
+`right`, `bottom` 중 하나 이상을 지정해야 합니다. `expanded`는 `row` 또는 `column`의 직접
+child입니다.
+
+크기 prop은 0~4096, position offset은 -4096~4096, spacing과 inset은 0~128입니다.
+`border_width` 0~8, `border_radius` 0~64, `elevation` 0~24, `opacity` 0~1,
+`aspect_ratio` 0.1~20, `flex` 1~24를 사용합니다. `padding`과 `margin`의 정확한 입력 형태와
+theme 색상 역할은 [토큰과 반응형](design-tokens-responsive.md)에 있습니다.
+
+## State
+
+`initial_state`가 허용 state key와 초기값을 선언합니다. key는 영문자로 시작하고 영문·숫자·밑줄을
+사용하는 최대 64자입니다.
+
+```json
+{
+  "initial_state": {"period": "today", "notifications": true}
+}
+```
+
+`field`, `select`, `switch`, navigation selection, `set_state`는 여기에 선언된 key만 변경합니다.
+`persist: true`는 Instance settings의 extension 전용 namespace에 저장합니다. credential과 민감한
+사용자 데이터는 state에 저장하지 않습니다.
+
+## Data source와 binding
+
+```json
+{
+  "id": "schedule",
+  "capability": "school_life.schedule",
+  "trigger": "load",
+  "query": "{{state.period}}",
+  "arguments": {"period": "{{state.period}}"},
+  "refresh_seconds": 300
+}
+```
+
+`trigger`는 `load` 또는 `manual`입니다. 결과는 다음 namespace로 읽습니다.
+
+```text
+data.<source_id>.completed
+data.<source_id>.summary
+data.<source_id>.data.<field>
+```
+
+반복 template 안에서는 `item.<field>`를 사용합니다. 문자열 전체가 binding 하나면 원래 JSON type을
+arguments에 전달하고, 다른 글자와 섞으면 텍스트 template이 됩니다.
+
+```json
+{"limit": "{{state.limit}}"}
+```
+
+```json
+{"label": "{{state.period}} 일정"}
+```
+
+### Capability 결과 이미지
+
+`image`와 `avatar`의 `url`은 literal URL이 아니라 capability 결과를 가리키는 전체
+`{{data.<source>...}}` 또는 `{{item...}}` binding입니다. Manifest가 `network`를 요청하고 활성
+Instance가 `network`를 grant한 경우에만 표시할 수 있습니다.
+
+Host renderer는 해석된 URL을 앱에서 직접 fetch하지 않고 인증된
+`POST /v1/plugin-instances/{instance_id}/ui-images:fetch`를 사용합니다. 요청 body는 다음과 같습니다.
+
+```json
+{"url": "https://images.example.edu/today.png"}
+```
+
+Host proxy는 공개 HTTPS와 SSRF 정책을 적용하고 redirect를 따르지 않습니다. PNG/JPEG/GIF/WebP만
+허용하며 응답 MIME type, magic byte, 실제 이미지 포맷이 모두 일치해야 합니다. 응답 본문은 최대
+512 KiB, 가로·세로는 각각 최대 4096 px입니다. 정적 이미지는 1 frame, 애니메이션은 최대 128
+frame이며 `width × height × frame 수`로 계산한 frame 합산 pixel은 최대 16,000,000입니다. 검증
+실패는 해당 이미지 fallback으로 격리하며 원본 URL이나 실패 응답을 직접 렌더링하지 않습니다.
+
+## App bar
+
+`app_bar`는 Host 화면 chrome을 구성합니다. tree 안에 앱 바를 다시 만들지 않습니다.
+
+| 필드 | 규칙 |
+|---|---|
+| `title` | 필수, binding 가능, 최대 120자 |
+| `subtitle` | 선택, binding 가능, 최대 160자 |
+| `center_title`, `pinned` | boolean |
+| `leading` | action item 하나 |
+| `actions` | 최대 6개 |
+
+action item은 `id`, `label`, 선택적 `icon`, `show_as`, 필수 `action`을 가집니다. `show_as`는
+`auto`, `always`, `overflow`입니다. overflow에는 드문 행동을 두고 주요 행동은 화면 본문에 둡니다.
+
+## Navigation
+
+`navigation.type`은 `tabs`, `bar`, `rail`, `drawer`, `adaptive`입니다. 각 item은 `id`, `label`,
+선택적 `icon`, `selected_icon`, `value`, 필수 `action`을 가집니다.
+
+`selected_state_key`를 사용하면 해당 key가 `initial_state`에 있어야 하고 모든 item에 `value`가
+필요합니다. `label_behavior`는 `auto`, `always`, `selected`, `never`입니다. `rail_breakpoint`는
+480~1600입니다.
+
+## Component tree
+
+지원 node:
+
+```text
+column row wrap grid stack positioned scroll padding center expanded
+surface card section text icon image avatar badge divider spacer
+button chip metric progress list timeline calendar chart
+form dialog sheet field select switch empty
+```
+
+각 node의 목적과 props는 [컴포넌트 레퍼런스](components.md), 색·크기 범위는
+[토큰과 반응형](design-tokens-responsive.md)을 참고하세요.
+
+## Action
+
+### Capability 실행
+
+```json
+{
+  "type": "invoke",
+  "capability": "school_life.lookup",
+  "query": "{{state.query}}",
+  "arguments": {"limit": 10},
+  "store": "results"
+}
+```
+
+`store`는 선언된 data source ID이며 성공 결과로 해당 source를 교체합니다.
+
+### State와 refresh
+
+```json
+{"type": "set_state", "values": {"period": "tomorrow"}, "persist": true}
+```
+
+```json
+{"type": "refresh", "source": "schedule"}
+```
+
+### Navigation
+
+```json
+{
+  "type": "navigate",
+  "target": "school_life.details",
+  "transition": "platform",
+  "replace": false
+}
+```
+
+`transition`은 `platform`, `fade`, `slide`, `none`입니다. `replace: true`는 현재 route를 뒤로가기
+stack에서 교체합니다. 같은 manifest의 UI extension ID만 target이 될 수 있습니다.
+
+```json
+{"type": "back"}
+```
+
+## 조건부 표시
+
+```json
+{
+  "visible_when": {
+    "path": "data.schedule.data.items",
+    "exists": true
+  }
+}
+```
+
+`equals`, `not_equals`, `exists` 중 정확히 하나를 사용합니다. 조건은 state·data·현재 `item` 값만
+읽고 임의 expression을 실행하지 않습니다.
+
+## 로딩과 오류 복구
+
+Host는 source별 실행을 격리하고 중복 실행을 합칩니다. 화면이 background로 가면 자동 refresh를
+멈추고 다시 foreground가 될 때 최신 source를 확인합니다. 갱신 실패 시 기존 정상 데이터가 있으면
+유지하고, 첫 로드도 실패한 경우에만 해당 영역에 retry 상태를 표시합니다. package generation이나
+화면이 바뀐 뒤 도착한 오래된 응답은 버립니다.
+
+## Response UI
+
+`point: "response"`도 같은 `theme`, `app_bar`, `navigation`, data/state/node/action 계약을
+재사용합니다. 단, 결과는 capability를 실행한 AI 메시지의 한 response container 안에 렌더링됩니다.
+표현 세부는 [Response UI와 Agent Timeline](ai-response-and-timeline.md)을 참고하세요.

package/assets/docs/verification.md

@@ -0,0 +1,128 @@
+# 예제 검증 방법과 확인 경계
+
+자동 테스트, 외부 서비스 live test, Android 실기기 확인은 서로 다른 증거입니다. 하나의 성공을
+다른 단계의 성공으로 기록하지 않습니다. 실행 시각, 대상 version, 명령, 종료 코드, artifact
+SHA-256을 함께 남기면 나중에 같은 결과를 재현할 수 있습니다.
+
+## 1. 패키지 무결성
+
+현재 저장소의 예제 artifact는 다음과 같습니다.
+
+| 패키지 | 크기 | SHA-256 |
+|---|---:|---|
+| `school-life-1.4.0.mplg` | 262758 bytes | `f246d3abff4eac85e1a991d8f436c5381b394858843c95d6d4d88620a1b760b7` |
+| `notion-1.1.0.mplg` | 3044 bytes | `eba57c440b305343c5cf917259e30e50b322272cfadb0ed64d39ecfc47539c4e` |
+
+```powershell
+python tools/morit_plugin.py verify `
+  examples/plugins/school-life/dist/school-life-1.4.0.mplg
+python tools/morit_plugin.py verify `
+  examples/plugins/notion/dist/notion-1.1.0.mplg
+Get-FileHash -Algorithm SHA256 @(
+  'examples/plugins/school-life/dist/school-life-1.4.0.mplg',
+  'examples/plugins/notion/dist/notion-1.1.0.mplg'
+)
+```
+
+`verify`는 ZIP 안전성, canonical payload, embedded Ed25519 public key와 signature를 검사합니다.
+검증 결과에 publisher key가 포함되어 있어야 하며, trusted publisher 사전 등록 여부와 무관하게
+서명 자체가 유효해야 합니다. Host의 신뢰 정책은 설치·실행 단계에서 별도로 적용됩니다.
+
+문서의 hash는 source나 build 규칙이 바뀌면 달라집니다. 새 artifact를 만들었으면 위 명령으로
+실제 파일을 다시 계산한 뒤 문서와 배포 metadata를 함께 갱신합니다.
+
+## 2. 자동 회귀 테스트
+
+저장소 root에서 다음 검사를 먼저 실행합니다.
+
+```powershell
+npx -y @morit/cli plugin validate .\examples\plugins\school-life
+npx -y @morit/cli plugin validate .\examples\plugins\notion
+python -m unittest discover -s backend/archive_processing -p "test_*.py"
+python -m unittest discover -s backend/plugin_mcp -p "test_*.py"
+dart analyze
+flutter test
+```
+
+관련 backend 테스트는 정상 package 설치·복원·삭제, actor 격리, permission/readiness gate,
+Connection OAuth state와 replay 차단, credential 암호화·갱신·해제, host-action outbox,
+Slash·Search·Tool routing, UI/Response 계약을 검사합니다. transport fixture 테스트는 외부 서비스가
+응답하지 않아도 request/response parser 계약을 확인하지만 실제 사용자 계정의 성공을 증명하지는
+않습니다.
+
+## 3. Backend live E2E
+
+`tools/plugin_live_e2e.py`는 임시 Supabase 사용자를 만들고 공개 API를 호출합니다. 관리자 key를
+사용하므로 승인된 운영자 환경에서만 실행하며 Secret, OAuth code, access token을 로그에 남기지
+않습니다.
+
+```powershell
+$env:MORIT_E2E_ENV = 'C:\secure\morit-backend.env'
+$env:MORIT_E2E_API = 'https://morit-api.moring.co'
+$env:MORIT_SCHOOL_PLUGIN = 'examples/plugins/school-life/dist/school-life-1.4.0.mplg'
+$env:MORIT_NOTION_PLUGIN = 'examples/plugins/notion/dist/notion-1.1.0.mplg'
+
+# 실제 Notion 승인을 할 때만 0보다 큰 값을 사용합니다.
+$env:MORIT_E2E_WAIT_NOTION_OAUTH_SECONDS = '300'
+$env:MORIT_E2E_NOTION_QUERY = 'Morit 프로젝트'
+$env:MORIT_E2E_NOTION_PAGE_QUERY = 'Morit 프로젝트 안내'
+$env:MORIT_E2E_NOTION_DATA_SOURCE_QUERY = 'Morit 작업 목록'
+
+python tools/plugin_live_e2e.py
+```
+
+live E2E에서 확인할 핵심 순서는 다음과 같습니다.
+
+1. 신규 사용자의 설치·Instance 목록이 비어 있고 traversal package가 부분 상태 없이 차단됨
+2. 학교와 Notion package를 함께 설치하면 각 설치의 기본 Instance가 정확히 하나 생성됨
+3. 권한 승인 전 capability가 노출되지 않고, 승인 후 학교 Tool·Search·Slash·background가 등록됨
+4. 실제 NEIS 조회, 검색, 알림 outbox lease/ACK, 재시작 후 registry 복원이 동작함
+5. Notion 승인 시 기본 Instance의 Connection이 활성화되고 실제 page/data source를 읽음
+6. Connection 삭제 후 credential을 다시 쓰지 않으며 capability가 즉시 제거됨
+7. disable/delete/purge 뒤 cache, 설정, credential, pending action이 남지 않음
+
+같은 외부 서비스를 여러 계정으로 쓰는 경우 설치나 root Instance를 복제하지 않습니다. 하나의
+기본 Instance 아래 여러 Connection을 만들고 `allow_multiple` 정책과 계정별 격리를 검사합니다.
+
+스크립트 결과는 다음처럼 해석합니다.
+
+| 출력 | 종료 코드 | 의미 |
+|---|---:|---|
+| `backend_live_plugin_e2e=passed` | 0 | 요청한 외부 단계까지 모두 확인 |
+| `backend_live_plugin_e2e=partial reasons=...` | 2 | 일부 외부 승인·재시작 단계가 빠짐 |
+| `backend_live_plugin_e2e=failed ...` | 1 | 구현·배포·API 검증 실패 |
+
+Notion 사용자 승인을 생략했거나 운영 process 재시작 명령을 주지 않은 실행은 `partial`입니다.
+`state=completed`나 검색 결과 수만으로 page/data source 본문 조회 성공을 추정하지 않습니다.
+
+## 4. Android 실기기 확인
+
+Backend live test는 앱 화면과 Android 알림을 누르지 않습니다. release APK를 실제 기기에 설치해
+다음을 별도로 확인합니다.
+
+1. `.mplg` 파일 선택 후 설치·권한·초기 설정 흐름
+2. 학교 후보 선택, 오늘·주간·급식 화면과 빈 상태·오류 상태
+3. Notion 공식 승인, Connection 추가·전환·해제와 실제 page/data source 표시
+4. AI 자연어·Slash·Search와 해당 AI 메시지 안의 Response UI
+5. 알림 권한 승인 후 실제 알림 표시
+6. 강제 종료·재실행 뒤 설치·연결·화면 상태 복원
+7. 비활성화·삭제 뒤 화면·capability·알림 제거
+
+실기기에서 확인하지 않은 항목은 자동 테스트가 통과했더라도 `미검증`으로 남깁니다.
+
+## 5. 결과 기록 형식
+
+```text
+시각(KST):
+source revision:
+Plugin/Host version:
+실행 명령과 종료 코드:
+artifact 경로·크기·SHA-256:
+자동 테스트:
+live E2E:
+Android/iOS/Desktop 실기기:
+생략 또는 실패한 단계와 이유:
+```
+
+성공 기록에는 실행하지 않은 항목을 넣지 않습니다. iOS·Desktop은 현재 Host 지원 범위를 먼저
+확인하고, 지원이 확정되지 않은 플랫폼을 Android 결과로 대신하지 않습니다.