@morit/cli 1.0.0 → 1.1.1

package/README.md

@@ -1,26 +1,61 @@
 # @morit/cli
 
-Official Morit Developer CLI. It owns the shared Plugin SDK, local/Cloud project
-linking, authenticated synchronization, builds, and deployments. The separate
-`@morit/plugin-mcp` package exposes these capabilities to AI clients over MCP.
+Morit Plugin의 공식 개발 CLI입니다. 프로젝트 scaffold, Cloud 연결·동기화, 계약 검증, Ed25519
+서명 package build, immutable Deployment 배포를 같은 SDK로 처리합니다.
+
+## 빠른 시작
+
+Node.js 20.12 이상에서 실행합니다.
 
 ```powershell
-npx @morit/cli login
-npx @morit/cli plugin setup . --id com.example.plugin --name Example --publisher example
-npx @morit/cli plugin add .
-npx @morit/cli plugin validate .
-npx @morit/cli plugin build .
-npx @morit/cli plugin deploy . --visibility private
+npx -y @morit/cli login
+npx -y @morit/cli plugin setup . --id com.example.study --name "Study" --publisher example
+npx -y @morit/cli plugin add .
+npx -y @morit/cli plugin validate .
+npx -y @morit/cli plugin build .
+npx -y @morit/cli plugin deploy . --visibility private
 ```
 
-`morit login` uses a browser device flow. Windows credentials are protected with
-DPAPI, macOS uses Keychain, and Linux uses Secret Service through `secret-tool`.
-CI can supply `MORIT_ACCESS_TOKEN` without writing it to disk.
+CLI에 별도 `plugin preview` 명령은 없습니다. UI preview는 `@morit/cli/sdk`의
+`previewProjectDirectory`, `@morit/plugin-mcp`의 `morit_project_preview`, 또는 저장소 도구인
+`python tools/morit_plugin.py preview <directory>`를 사용합니다.
+
+전체 명령은 `npx -y @morit/cli --help`에서 확인하고 자동화에서는 `--json`을 사용합니다.
+
+## 프로젝트와 인증
+
+`morit login`은 브라우저 device flow를 사용합니다. Windows는 DPAPI, macOS는 Keychain,
+Linux는 Secret Service를 통해 credential을 보호합니다. CI는 파일에 저장하지 않고
+`MORIT_ACCESS_TOKEN`을 전달할 수 있습니다.
+
+Cloud 연결 정보는 프로젝트 root의 `morit-plugin.json`에 기록됩니다. 이 파일에는 Project UUID와
+revision만 들어가며 credential이나 Secret 평문은 포함되지 않습니다. Project source와 `.mplg`도
+Secret identifier만 선언하고 실제 값은 Morit Cloud Project Secrets에 저장합니다.
+
+동기화는 revision 충돌을 검사합니다.
+
+```powershell
+npx -y @morit/cli plugin sync .          # local → Cloud
+npx -y @morit/cli plugin sync . --pull   # Cloud → local
+```
+
+`--force` pull은 로컬 변경을 교체하므로 변경 내용을 확인한 뒤 명시적으로 사용합니다.
+
+## SDK와 문서
+
+Node SDK는 `@morit/cli/sdk` export에서 같은 contract, validator, preview, build 기능을 제공합니다.
+배포 package의 `assets/plugin_contract.json`과 `assets/docs/`에는 빌드 시점의 공통 계약과 공식
+개발 문서가 함께 들어갑니다. 문서는 `assets/docs/README.md`의 실제 개발 순서를 따라 읽습니다.
+
+Plugin MCP 설정과 Local/Remote Tool 흐름은 bundled `assets/docs/sdk-and-mcp.md`, manifest와 UI
+계약은 `assets/docs/manifest.md`, `assets/docs/ui-runtime-v2.md`를 참고하세요.
+
+## 파일과 보안 경계
 
-The local link is stored in `morit-plugin.json`; it contains project identifiers
-and a revision only, never credentials. Project source and `.mplg` files also
-contain secret identifiers only. Values belong in Morit Cloud Project Secrets.
+PNG/JPEG/WebP/GIF asset과 직접 `children/*.mplg` dependency는 JSON Cloud 경계를 건널 때만
+검증된 binary envelope로 변환되며 pull, source ZIP, 최종 `.mplg`에서는 원본 바이트가 유지됩니다.
+그 밖의 source는 UTF-8 text입니다.
 
-Binary PNG/JPEG/WebP/GIF assets and direct `children/*.mplg` dependencies are
-encoded only while crossing the JSON Cloud boundary and are restored byte for
-byte on pull, source ZIP, and build. Other source remains strict UTF-8.
+build는 manifest와 source 구조를 검증하고 package에 검증용 public key와 signature를 포함합니다.
+publisher private key, OS credential, Secret 평문은 source, source ZIP, package, CLI JSON 응답에
+포함하지 않습니다.

package/assets/docs/README.md

@@ -0,0 +1,105 @@
+# Morit Plugin 개발 문서
+
+이 문서는 아이디어를 실제 설치 가능한 `.mplg`로 만드는 순서대로 구성되어 있습니다. 플러그인은
+실행 코드를 앱에 직접 주입하지 않습니다. Manifest와 JSON fragment로 기능·화면·권한을 선언하고,
+Morit Host가 서명과 계약을 확인한 뒤 공용 런타임으로 실행합니다.
+
+## 가장 짧은 개발 경로
+
+```text
+요구사항 정리
+  → 프로젝트 생성
+  → manifest와 기능 fragment 작성
+  → 화면·상태·내비게이션 작성
+  → 권한·설정·알림 연결
+  → validate
+  → preview
+  → build
+  → verify
+  → 실제 앱 설치·실사용 테스트
+  → deploy
+```
+
+공식 CLI를 사용하는 기본 명령은 다음과 같습니다.
+
+```bash
+npx -y @morit/cli plugin setup . \
+  --id com.example.study \
+  --name "Study" \
+  --publisher example
+npx -y @morit/cli plugin validate .
+npx -y @morit/cli plugin build .
+npx -y @morit/cli login
+npx -y @morit/cli plugin add .
+npx -y @morit/cli plugin deploy . --visibility private
+```
+
+화면 preview는 Local/Remote Plugin MCP의 `morit_project_preview` 또는 저장소 도구
+`python tools/morit_plugin.py preview <project>`를 사용합니다. preview HTML은 구조를 점검하는
+보조 수단이며, 실제 Host 렌더링과 사용자 흐름은 앱에서 따로 확인해야 합니다.
+
+## 개발 순서별 인덱스
+
+### 1. 시작과 개발 흐름
+
+1. [시작하기와 개발 흐름](getting-started.md) — 개발 방식 선택, 첫 프로젝트, 완료 조건
+2. [앱에서 플러그인 만들기](app-builder.md) — 단순 Tool을 앱 Builder로 만드는 범위
+
+### 2. 프로젝트와 계약
+
+3. [프로젝트 구조와 fragment](project-structure.md) — 디렉터리, 병합 규칙, 패키지 포함 파일
+4. [Manifest 레퍼런스](manifest.md) — ID, 버전, capability, connector, dependency
+5. [Instance, Connector, 복합 패키지](instances-and-connectors.md) — 사용자별 실행 단위와 계정 연결
+
+### 3. 화면과 사용자 경험
+
+6. [화면, 레이아웃, 내비게이션](screens-layout-navigation.md) — 화면 역할과 이동 구조
+7. [기본·커스텀 컴포넌트](components.md) — 각 node의 목적, 속성, 제약
+8. [토큰, 크기, 색, 여백, 반응형](design-tokens-responsive.md) — Material 3 기반 시각 규칙
+9. [화면 분리와 정보 계층](information-hierarchy.md) — 한 화면에 정보를 몰지 않는 설계
+10. [UI extension point](ui-extensions.md) — Host의 어느 위치에 UI를 노출할지 선택
+11. [UI Runtime v2 레퍼런스](ui-runtime-v2.md) — data, state, binding, event 계약
+12. [Response UI와 Agent Timeline](ai-response-and-timeline.md) — AI 메시지 안의 결과 UI
+
+### 4. 기능, 데이터, 사용자 제어
+
+13. [Tool, Skill, Search, Slash Command](tool-and-skill.md) — capability와 runtime adapter
+14. [권한, 설정, 저장소, 알림](permissions-and-data.md) — 최소 권한과 Host action
+15. [외부 서비스 인증과 Cloud Secrets](authentication.md) — OAuth, API key, 비밀 값 경계
+16. [AI Skill과 파일 산출물](ai-skill-and-docx-workflow.md) — 실제 파일을 반환하는 완료 흐름
+
+### 5. 플랫폼
+
+17. [Android, iOS, Desktop 호환](platform-compatibility.md) — 현재 지원 범위와 이식 원칙
+
+### 6. 검증과 배포
+
+18. [공식 CLI 개발 흐름](local-cli.md) — setup, sync, build, deploy
+19. [패키징과 테스트](packaging-and-testing.md) — 서명, 무결성, 테스트 층
+20. [오류 해결](troubleshooting.md) — validate, preview, build, 설치, 실행 오류 구분
+21. [예제 검증 방법과 확인 경계](verification.md) — 자동·live·실기기 검증의 차이
+
+### 7. SDK, MCP, API
+
+22. [CLI와 AI 에이전트 MCP](sdk-and-mcp.md) — Codex·Claude 등 로컬/원격 연결
+23. [원격 Plugin MCP](remote-mcp.md) — Cloud Project를 다루는 Tool 계약
+24. [수명주기와 HTTP API](lifecycle-and-api.md) — Host API와 설치·실행 상태
+
+### 8. 실제 예제
+
+25. [학교 생활 플러그인](examples-school-life.md) — 공개 NEIS를 사용하는 학생용 경험
+26. [학교 생활 개인정보 처리](school-life-privacy.md) — 저장·전송·삭제 범위
+27. [Notion 플러그인](examples-notion.md) — OAuth Connection과 실제 문서 검색
+
+## 문서가 배포되는 위치
+
+`docs/plugin_docs`가 문서 콘텐츠의 공통 원본입니다. 같은 파일이 다음 위치에 복사되거나 빌드 시
+포함됩니다.
+
+- `@morit/cli`: npm 패키지의 `assets/docs`
+- Local MCP `@morit/plugin-mcp`: npm 패키지의 `assets/docs`
+- Remote MCP: 서비스 이미지의 `/app/docs/plugin_docs`
+- `developers.moring.co`: `docs-index.json`의 순서와 경로로 생성한 MDX
+
+네 배포 위치는 같은 계약과 예제를 제공하며, 문서의 JSON은 공식 CLI와 Host 계약으로 지속
+검증합니다. 각 경로에서 별도 규격을 정의하지 않습니다.

package/assets/docs/ai-response-and-timeline.md

@@ -0,0 +1,125 @@
+# Response UI와 Agent Timeline
+
+Response UI는 capability 결과를 AI 메시지 안에서 시각화합니다. 대화 아래의 별도 카드 목록이나
+overflow 메뉴 밑에 떨어뜨리지 않고, 해당 AI 메시지에 속한 하나의 response container 안에
+제목·내용·행동을 함께 렌더링합니다.
+
+## Response extension
+
+```json
+{
+  "id": "school_life.day_response",
+  "point": "response",
+  "title": "오늘 학교 생활",
+  "order": 10,
+  "permissions": [],
+  "config": {
+    "ui_schema": 2,
+    "theme": {"density": "compact"},
+    "data_sources": [
+      {
+        "id": "result",
+        "capability": "school_life.schedule.lookup",
+        "trigger": "manual",
+        "query": "",
+        "arguments": {}
+      }
+    ],
+    "view": {
+      "type": "column",
+      "props": {"spacing": 10},
+      "children": [
+        {
+          "type": "text",
+          "props": {"text": "{{data.result.summary}}", "style": "heading"}
+        },
+        {
+          "type": "timeline",
+          "props": {"source": "data.result.data.timetable", "empty_text": "수업 정보가 없습니다."},
+          "children": [
+            {
+              "type": "text",
+              "props": {"text": "{{item.period}}교시 · {{item.subject}}"}
+            }
+          ]
+        }
+      ]
+    }
+  }
+}
+```
+
+Response point도 일반 Runtime v2와 같은 node, theme, app bar, navigation, binding, action 계약을
+사용합니다. AI가 실행한 capability 결과는 `data` namespace에 주입되므로 같은 결과를 얻기 위해
+화면 mount 시 외부 요청을 반복하지 않습니다. 후속 refresh나 사용자가 누른 action에만 추가
+capability를 호출합니다.
+
+## 한 container의 정보 순서
+
+1. 결과를 설명하는 짧은 제목 또는 summary
+2. 사용자가 요청한 핵심 데이터
+3. 출처·기간·갱신 시점 같은 보조 정보
+4. 필요한 후속 행동 1~2개
+
+복사, 다시 시도, 다운로드 같은 메뉴도 같은 container의 Host chrome에 속합니다. 각 section을
+별도 떠 있는 card로 만들지 않습니다. 긴 결과는 list limit과 상세 화면 이동을 사용합니다.
+
+## 대화 UI를 깨뜨리지 않는 제약
+
+- 메시지 폭을 넘는 고정 width를 사용하지 않습니다.
+- Response 내부에 자체 채팅 입력창을 만들지 않습니다.
+- 무한 높이 목록 대신 요약과 상세 화면 이동을 제공합니다.
+- background refresh가 대화 scroll 위치를 바꾸지 않게 기존 높이와 데이터를 가능한 유지합니다.
+- 렌더링 오류는 해당 Response만 텍스트 fallback으로 바꾸고 대화 전체를 종료하지 않습니다.
+- accessibility 순서는 AI 본문 다음, Response 제목, 내용, 행동 순으로 유지합니다.
+
+## Text fallback
+
+Response UI를 표시할 수 없더라도 AI의 원래 텍스트 답변은 남아야 합니다. capability는 UI 전용
+원시 JSON만 반환하지 말고 사람이 읽을 수 있는 `summary`를 함께 제공합니다. 알 수 없는 node,
+손상된 binding, 이미지 로드 실패는 전체 답변 성공을 숨기지 않습니다.
+
+```json
+{
+  "completed": true,
+  "summary": "오늘은 6교시이며 점심은 카레라이스입니다.",
+  "data": {
+    "timetable": [],
+    "meal": {}
+  },
+  "evidence": []
+}
+```
+
+## Agent Timeline
+
+Agent Timeline은 모델의 숨겨진 추론이 아니라 사용자가 이해할 수 있는 실행 상태만 보여줍니다.
+
+```text
+요청을 확인하고 계획했어요
+  ├─ 학교 정보를 확인했어요
+  ├─ 오늘 시간표를 불러왔어요
+  └─ 결과를 정리했어요
+```
+
+Timeline event에는 도구 이름이나 내부 stack trace 대신 작업 이름, 상태, 필요한 사용자 행동을
+기록합니다. 상태는 대체로 다음과 같습니다.
+
+- 진행 중
+- 완료
+- 재시도 중
+- 사용자 입력 필요
+- 일부 결과로 완료
+- 실패
+
+Tool 하나가 실패했지만 대체 경로로 결과를 만들었다면 전체 timeline을 실패로 표시하지 않습니다.
+실패한 단계와 복구 결과를 함께 설명합니다.
+
+## Code Interpreter 파일
+
+Code Interpreter가 파일을 만들었다면 sandbox 내부 경로만 답변에 남기지 않습니다. 파일은 Host가
+접근 가능한 artifact로 전달되고, AI 답변에는 실제 파일 이름·형식·크기와 다운로드 가능한 링크가
+있어야 합니다. Response UI의 다운로드 action은 동일 artifact를 가리키며 존재하지 않는 경로나
+가짜 링크를 생성하지 않습니다.
+
+파일 생성 완료 조건은 [AI Skill과 파일 산출물](ai-skill-and-docx-workflow.md)에 정리되어 있습니다.

package/assets/docs/ai-skill-and-docx-workflow.md

@@ -0,0 +1,83 @@
+# AI Skill과 파일 산출물
+
+Morit Plugin의 `kind: "skill"`과 Codex·Claude 같은 AI 에이전트의 Skill 파일은 이름이 같지만
+역할이 다릅니다.
+
+- Morit Plugin Skill: Host가 설치·권한·timeout 경계에서 실행하는 capability
+- AI 에이전트 Skill: 에이전트가 작업 순서와 도구 사용법을 따르는 지침
+
+에이전트 Skill을 사용해 플러그인을 만들더라도 결과 `.mplg`는 일반 SDK 계약과 동일하게 검증·서명됩니다.
+
+## 파일 작업 완료 순서
+
+문서, 표, 이미지, archive 등 파일을 만드는 capability나 AI 작업은 다음 순서를 지킵니다.
+
+```text
+요청과 입력 조사
+  → 파일 생성·편집
+  → 구조 검증
+  → 가능하면 시각 검증
+  → 원래 parser로 다시 열고 내용 확인
+  → 최종 artifact 저장
+  → 사용자에게 실제 링크와 요약 반환
+```
+
+“작업을 마쳤어요”만 답하거나 sandbox 내부 경로만 남기면 완료가 아닙니다. 존재하지 않는 `.docx`
+경로나 아직 생성하지 않은 artifact를 최종 링크처럼 반환하지 않습니다.
+
+## DOCX 예
+
+DOCX는 Microsoft Open XML ZIP 구조입니다. 단순히 `.docx` 확장자를 붙이지 않습니다.
+
+1. 요청한 목차, 표, 이미지, 스타일을 실제로 작성합니다.
+2. ZIP entry와 `[Content_Types].xml`, document relationship을 확인합니다.
+3. DOCX parser로 다시 열어 문단·표·이미지 수를 확인합니다.
+4. 모든 페이지를 렌더링해 잘림, 빈 페이지, 겹침, 깨진 한글을 확인합니다.
+5. 수정 후 parser와 렌더링을 다시 실행합니다.
+6. 존재하고 0바이트가 아닌 최종 `.docx`만 artifact로 반환합니다.
+
+다른 형식도 동일합니다. PDF는 모든 페이지, spreadsheet는 수식과 셀 type, image는 실제 크기와
+디코딩, ZIP은 entry 경로와 traversal 안전성을 확인합니다.
+
+## Plugin이 파일을 만드는 경우
+
+Plugin은 `file_write` 권한을 요청하고 Host가 제공하는 artifact 경계로 결과를 전달합니다.
+`sandbox_python` 응답의 `summary`, `data`, `evidence`에 존재하지 않는 `sandbox:/...` 링크를 만들지
+않습니다. Host로 복사된 artifact ID나 내부 파일 링크 문법을 사용하고, AI 최종 답변에는 다음을
+포함합니다.
+
+- 파일 이름과 형식
+- 사용자가 요청한 결과 요약
+- 다운로드 또는 앱 내부 미리보기 링크
+- 검증한 항목과 남은 제한
+
+## `.mplg` 산출물
+
+플러그인 개발도 파일 작업입니다.
+
+```text
+source 작성
+  → validate
+  → UI가 있으면 preview
+  → signed build
+  → package reopen·signature verify
+  → 앱 설치·실행
+  → 요청한 경로에 artifact 반환
+```
+
+source ZIP과 `.mplg`는 목적이 다릅니다. source ZIP은 편집용이고 `.mplg`는 설치용입니다. 둘을 같은
+다운로드 이름이나 MIME으로 반환하지 않습니다.
+
+플러그인의 기본 품질 게이트는 `validate → preview → build → verify`입니다. UI가 없는 package는
+preview를 생략할 수 있지만 생략 이유를 결과에 기록합니다.
+
+## 완료 체크
+
+- 요청한 모든 파일이 실제로 존재하는가
+- 파일 크기가 0보다 큰가
+- 확장자와 내부 형식이 일치하는가
+- 원래 parser로 다시 열리는가
+- 모든 페이지/시트/entry를 확인했는가
+- 미리보기와 다운로드가 같은 최종 artifact를 가리키는가
+- sandbox 경로나 secret이 사용자 응답에 남지 않았는가
+- 실패한 Tool이 있다면 복구·대체 결과와 제한을 설명했는가

package/assets/docs/app-builder.md

@@ -0,0 +1,56 @@
+# 앱에서 플러그인 만들기
+
+Plugin Builder는 개발 환경 없이 작은 Tool 또는 Skill을 만드는 경로입니다. Builder도 일반
+`.mplg`를 생성하고 같은 설치·권한·삭제 흐름을 사용하지만, 안전하게 표현할 수 있는 범위를
+의도적으로 제한합니다.
+
+## 지원 범위
+
+| 항목 | 지원 값 |
+|---|---|
+| capability kind | `tool`, `skill` |
+| runtime | `text_stats`, `text_template` |
+| UI 위치 | `card`, `screen`, `settings` 중 최대 3개 |
+| 선택 기능 | Search Provider, Slash Command, background, notification |
+| 권한 | `background`, `notifications` |
+| credential | 최대 4개의 `api_token` 선언(현재 앱 화면은 고급 source 흐름에서 설정) |
+| background 주기 | 15~10,080분 |
+
+Builder는 ID, 이름, 설명, version, capability 제목과 runtime 설정을 입력받아 최소 Manifest와
+Runtime v1 UI를 만듭니다. UI 코드를 생성하거나 외부 코드를 실행하지 않습니다.
+
+## Builder가 적합한 예
+
+- 입력 텍스트의 길이와 단어 수를 계산하는 Tool
+- 정해진 템플릿으로 회의 메모를 정리하는 Skill
+- settings의 작은 정적 목록을 Search Provider로 노출
+- 정해진 문구를 일정 주기로 알리는 개인 알림
+
+## 소스 프로젝트로 전환할 때
+
+다음 중 하나가 필요하면 공식 CLI 프로젝트를 사용합니다.
+
+- Runtime v2의 화면·내비게이션·theme·Response UI
+- 외부 HTTPS API, OAuth, Remote MCP
+- 여러 데이터 source와 동적 목록
+- `sandbox_python` 데이터 처리
+- child package와 dependency
+- Cloud Secret, Connector retry/rate-limit
+- package asset, 이미지, 복수 source file
+
+[시작하기](getting-started.md)의 `@morit/cli plugin setup`으로 프로젝트를 만들고 Builder에서 정한
+ID와 capability 이름을 유지하면 사용자가 기능을 다시 익힐 필요가 없습니다. 기존 설치를 업데이트할
+때는 publisher와 서명 identity, plugin ID, semantic version 순서를 유지해야 합니다.
+
+## 실제 확인
+
+Builder 생성 성공만 확인하지 말고 다음을 앱에서 실행합니다.
+
+1. 생성 직후 설치 목록에 나타나는지
+2. 필요한 권한을 거부했을 때 기능이 실행되지 않는지
+3. Tool/Skill과 Slash Command가 정확한 capability를 호출하는지
+4. background/notification을 켜고 끌 수 있는지
+5. 설정 변경 후 다시 열었을 때 유지되는지
+6. 삭제 후 pending 알림과 credential이 정리되는지
+
+고급 화면 개발은 [화면, 레이아웃, 내비게이션](screens-layout-navigation.md)부터 시작하세요.

package/assets/docs/authentication.md

@@ -0,0 +1,140 @@
+# 외부 서비스 인증과 Cloud Secrets
+
+플러그인 source와 `.mplg`에는 비밀 값이 들어가지 않습니다. package는 필요한 Credential·Connector·
+Secret ID만 선언하고 실제 값은 사용자 Connection 또는 조직의 Cloud Secret에 저장합니다.
+
+## 선택 기준
+
+| 값의 소유자 | 사용 모델 | 예 |
+|---|---|---|
+| 각 사용자 | Credential + Connection | 개인 Notion OAuth, 개인 API token |
+| Developer 조직 | Cloud Secret | 서버 간 API key, OAuth client secret |
+| 공개 설정 | Connector 또는 manifest | 공개 HTTPS endpoint, provider ID |
+
+사용자 token을 Cloud Secret으로 공유하거나 조직 secret을 Instance settings에 복사하지 않습니다.
+
+## Manifest 선언
+
+OAuth 계정:
+
+```json
+{
+  "credentials": [
+    {
+      "id": "notion_account",
+      "label": "Notion 계정",
+      "description": "공유한 페이지를 읽습니다.",
+      "kind": "oauth_access_token",
+      "required": true,
+      "oauth_provider": "notion",
+      "allow_multiple": true
+    }
+  ],
+  "connectors": [
+    {
+      "id": "notion_cloud",
+      "kind": "oauth",
+      "label": "Notion Cloud",
+      "description": "Notion 공식 OAuth 연결",
+      "credential_id": "notion_account",
+      "cloud_connection_id": "notion"
+    }
+  ]
+}
+```
+
+조직 Secret:
+
+```json
+{
+  "cloud_project_id": "00000000-0000-4000-8000-000000000000",
+  "required_secrets": [
+    {
+      "id": "EXAMPLE_API_KEY",
+      "label": "Example API key",
+      "description": "서버 간 API 호출에 사용합니다.",
+      "required": true
+    }
+  ],
+  "connectors": [
+    {
+      "id": "example_api",
+      "kind": "api_key",
+      "label": "Example API",
+      "description": "조직 API 연결",
+      "cloud_secret_id": "EXAMPLE_API_KEY"
+    }
+  ]
+}
+```
+
+`cloud_project_id`는 Developer Project에 연결할 때 발급된 실제 UUID를 사용합니다.
+
+## Developer Platform 설정
+
+1. 조직을 선택하고 Plugin Project를 엽니다.
+2. Secrets에서 manifest의 `required_secrets.id`와 같은 ID를 등록합니다.
+3. Connections에서 `cloud_connection_id`와 같은 provider 설정을 만듭니다.
+4. OAuth authorize URL, token URL, client ID, client secret, redirect URI를 공급자 문서와 맞춥니다.
+5. 필요한 header/content type과 PKCE 지원 여부를 명시합니다.
+6. source를 sync하고 새 Deployment를 build합니다.
+
+Secret 값은 저장 후 다시 평문으로 표시되거나 source ZIP, MCP 응답, build log에 포함되면 안 됩니다.
+변경은 새 값으로 덮어쓰고 필요한 경우 provider에서 기존 값을 폐기합니다.
+
+## 사용자 연결 흐름
+
+```text
+설치·활성화
+  → 필요한 Connection 없음
+  → 설정에서 “계정 연결”
+  → Host가 state와 redirect를 생성
+  → provider 승인
+  → Host callback에서 state 검증과 token 교환
+  → 암호화 저장
+  → default Instance에 Connection 연결
+```
+
+`allow_multiple: true`이면 같은 default Instance 안에 여러 Connection을 만들고 사용자가 표시 이름으로
+선택합니다. 같은 package root Instance를 복제해 계정을 추가하지 않습니다.
+
+OAuth state와 redirect URI는 필수입니다. PKCE는 공급자 호환 설정에 따라 사용하지만 state 검증을
+대체하지 않습니다. callback이 성공하기 전에 연결 완료로 표시하지 않습니다.
+
+## 실행과 갱신
+
+Capability는 `connector_id`만 참조합니다. Host는 선택된 Connection의 token을 요청 직전에 주입하고
+응답과 로그에서 제거합니다. credential 거부가 명확하고 provider가 refresh를 지원하면 한 번 갱신한
+뒤 전체 요청을 재시도합니다. 반복 실패는 “다시 연결” 상태로 전환합니다.
+
+Connection 상태를 구분합니다.
+
+- `ready`: 필요한 credential과 runtime이 준비됨
+- `not_configured`: 필수 Connection/Secret이 없음
+- `unavailable`: provider, 암호화, dependency, network runtime을 사용할 수 없음
+- 만료·거부: 사용자 재연결 필요
+
+## 연결 해제와 삭제
+
+Instance Connection 삭제는 해당 연결 row의 encrypted credential, 진행 중 OAuth state, 관련 pending
+Host action을 로컬에서 정리하고 generation을 갱신합니다. 이 API를 provider token revoke가
+완료됐다는 증거로 사용하지 않습니다.
+
+기존 default credential 해제 API는 provider에 revocation endpoint가 있으면 먼저 revoke하고 성공한
+경우에만 local credential을 삭제합니다. provider 오류가 나면 암호화된 credential을 유지하고 오류를
+반환하므로 사용자가 다시 시도할 수 있습니다. Plugin 전체 삭제는 remote revoke를 가능한 범위에서
+시도한 뒤 `data_policy: retain`이어도 local credential과 OAuth state를 보존하지 않습니다.
+
+## 운영 점검
+
+- authorize 요청마다 새로운 state가 생성되는가
+- redirect URI가 등록값과 정확히 일치하는가
+- token URL과 content type이 provider 요구와 맞는가
+- client secret과 access token이 로그·MCP·artifact에 없는가
+- 여러 Connection의 token과 표시 이름이 섞이지 않는가
+- token 만료 후 한 번 갱신하고, 실패 시 재연결을 안내하는가
+- Connection 삭제 후 해당 연결의 실행이 즉시 차단되고 local credential이 제거되는가
+- provider revoke가 제품 요구사항이면 공급자 console에서도 token 폐기를 별도로 확인했는가
+- 플러그인 삭제 후 local credential과 OAuth state가 남지 않는가
+
+Notion의 실제 구성은 [Notion 플러그인](examples-notion.md)을 참고하세요.