@morit/cli 1.0.0 → 1.1.1

package/assets/docs/manifest.md

@@ -0,0 +1,208 @@
+# Manifest 레퍼런스
+
+`manifest.json`은 UTF-8 JSON 객체입니다. Host는 schema 1과 2를 읽으며 새 프로젝트는 schema 2를
+사용합니다. 알 수 없는 필드는 무시하지 않고 오류로 처리합니다.
+
+## 전체 형태
+
+```json
+{
+  "schema_version": 2,
+  "id": "com.example.notes",
+  "name": "Notes",
+  "icon": "assets/icon.png",
+  "short_description": "연결된 노트를 검색합니다.",
+  "description": "내 노트 계정을 연결해 검색하고 요약합니다.",
+  "category": "productivity",
+  "keywords": ["notes", "search"],
+  "developer": {"name": "Example", "url": "https://example.com"},
+  "homepage_url": "https://example.com/notes",
+  "privacy_policy_url": "https://example.com/privacy",
+  "publisher": "example",
+  "version": "1.0.0",
+  "min_morit_version": "1.7.6",
+  "max_morit_version": "1.999.999",
+  "permissions": ["network", "credentials"],
+  "capabilities": [
+    {
+      "id": "com.example.notes.echo",
+      "kind": "tool",
+      "title": "입력 확인",
+      "description": "입력한 검색어를 확인합니다.",
+      "permissions": [],
+      "runtime": {"adapter": "text_template", "template": "검색어: {query}"}
+    }
+  ],
+  "ui_extensions": [],
+  "credentials": [],
+  "slash_commands": [],
+  "connectors": [],
+  "dependencies": [],
+  "required_secrets": [],
+  "data_policy": "purge"
+}
+```
+
+`icon`을 선언했다면 `assets/icon.png` 파일도 실제 프로젝트에 있어야 합니다. 준비 전에는 필드를
+생략하고 존재하지 않는 asset 경로를 넣지 않습니다.
+
+## 신원과 표시 정보
+
+| 필드 | 규칙 |
+|---|---|
+| `id` | 소문자 reverse-domain ID, 예: `com.example.notes` |
+| `name` | 1~80자 |
+| `publisher` | 2~120자의 영문·숫자·점·밑줄·하이픈 |
+| `version` | semantic version |
+| `min_morit_version`, `max_morit_version` | semantic version, 둘 다 필수 |
+| `icon` | 패키지의 PNG/JPEG/WebP `assets/` 경로 |
+| `short_description` | 최대 160자 |
+| `description` | 최대 4,000자 |
+| `category` | 소문자로 시작하는 2~40자 ID |
+| `keywords` | 최대 12개의 고유한 1~40자 문자열 |
+| URL 필드 | 사용자 정보가 없는 공개 HTTPS URL |
+
+`cloud_project_id`는 Cloud 기능을 쓸 때 Developer Project가 채우는 UUID입니다. 프로젝트 source에
+직접 추측해 넣지 않습니다. `required_secrets` 또는 `cloud_connection_id`를 사용하는 Connector가
+있으면 이 값이 필요합니다.
+
+## 권한과 데이터 정책
+
+Manifest `permissions`는 플러그인이 요청할 수 있는 최대 범위입니다. 각 capability와 UI extension은
+그중 자신에게 필요한 일부만 다시 선언합니다.
+
+`data_policy`는 삭제 시 플러그인 storage 처리 방식을 정합니다.
+
+- `purge`: 설치와 함께 저장한 플러그인 데이터를 삭제
+- `retain`: 재설치를 위해 일반 storage를 유지
+
+credential, OAuth state, pending notification은 두 정책과 무관하게 보안 수명주기에 따라 정리됩니다.
+
+## Capability
+
+```json
+{
+  "id": "com.example.notes.search",
+  "kind": "tool",
+  "title": "노트 검색",
+  "description": "연결한 계정의 노트를 검색합니다.",
+  "permissions": ["network", "credentials"],
+  "timeout_seconds": 10,
+  "runtime": {
+    "adapter": "http_json",
+    "connector_id": "notes_api"
+  }
+}
+```
+
+`kind`는 `tool`, `skill`, `provider`, `background`, `notification` 중 하나입니다. 최대 64개이며
+timeout은 0.1~30초입니다. capability 권한은 Manifest 권한의 부분집합이어야 합니다. `tool`과
+`skill`은 실행 가능한 runtime adapter가 필수입니다. Search `provider`는
+`runtime.role: "search"`와 adapter가 필요합니다.
+
+## UI extension
+
+```json
+{
+  "id": "com.example.notes.screen",
+  "point": "screen",
+  "title": "내 노트",
+  "order": 10,
+  "permissions": ["network", "credentials"],
+  "config": {
+    "ui_schema": 2,
+    "view": {"type": "text", "props": {"text": "노트를 검색하세요."}}
+  }
+}
+```
+
+최대 64개입니다. `point`는 `screen`, `surface`, `menu`, `action`, `card`, `settings`,
+`workspace`, `response` 중 하나입니다. 상세 선택 기준은 [UI extension point](ui-extensions.md),
+config 계약은 [UI Runtime v2](ui-runtime-v2.md)를 참고하세요.
+
+## Credential과 Connector
+
+Credential은 사용자별 비밀 값의 종류를 선언합니다.
+
+```json
+{
+  "id": "notes_account",
+  "label": "Notes 계정",
+  "description": "노트를 읽는 OAuth 연결",
+  "kind": "oauth_access_token",
+  "required": true,
+  "oauth_provider": "notion",
+  "allow_multiple": true
+}
+```
+
+`kind`는 `api_token` 또는 `oauth_access_token`입니다. credential이 하나라도 있으면 Manifest에
+`credentials` 권한이 필요합니다. `allow_multiple`의 기본값은 `true`이며 Instance마다 연결을
+따로 관리합니다.
+
+Connector는 endpoint, credential, timeout, retry, rate limit을 capability에서 분리합니다.
+
+```json
+{
+  "id": "notes_api",
+  "kind": "oauth",
+  "label": "Notes API",
+  "description": "공식 API 연결",
+  "credential_id": "notes_account",
+  "cloud_connection_id": "notion",
+  "timeout_seconds": 10,
+  "retry": {"max_attempts": 3},
+  "rate_limit": {"requests": 60, "period_seconds": 60}
+}
+```
+
+`kind`는 `https`, `oauth`, `api_key`, `mcp`입니다. 공개 endpoint를 직접 지정할 때는 HTTPS만
+허용합니다. timeout은 0.1~30초, retry는 1~4회, rate-limit 기간은 1~3,600초입니다. OAuth는
+credential이 필수이고 API key는 사용자 credential이나 선언된 Cloud secret 중 하나가 필요합니다.
+
+Cloud Secret을 쓰려면 먼저 `required_secrets`에 대문자 환경 ID를 선언합니다.
+
+```json
+{
+  "id": "EXAMPLE_API_KEY",
+  "label": "Example API key",
+  "description": "서버 간 요청에 사용합니다.",
+  "required": true
+}
+```
+
+## Dependency와 child package
+
+```json
+{
+  "id": "notes",
+  "plugin_id": "com.example.notes_core",
+  "required": true,
+  "min_version": "1.0.0",
+  "max_version": "1.999.999",
+  "package_path": "children/notes-core.mplg",
+  "exposed_capabilities": ["com.example.notes_core.search"]
+}
+```
+
+`package_path`가 있으면 정확히 대응하는 signed child `.mplg`가 패키지에 있어야 합니다. 부모는
+`child_plugin` adapter와 `exposed_capabilities`에 적힌 capability만 호출할 수 있습니다. 부모와
+자식은 Instance, settings, credential, storage를 공유하지 않습니다.
+
+## Slash Command
+
+```json
+{
+  "id": "com.example.notes.command",
+  "command": "notes",
+  "title": "노트 검색",
+  "description": "연결한 노트를 검색합니다.",
+  "capability": "com.example.notes.search",
+  "argument_template": {"limit": 10}
+}
+```
+
+최대 32개입니다. `command`는 `/` 없이 소문자·숫자로 시작하는 1~32자이며 `_`, `-`를 사용할 수
+있습니다. 대상은 같은 플러그인의 `tool` 또는 `skill`이어야 합니다.
+
+다음은 [Instance와 Connector 모델](instances-and-connectors.md)입니다.

package/assets/docs/packaging-and-testing.md

@@ -0,0 +1,115 @@
+# 패키징과 테스트
+
+## `.mplg` 형식
+
+`.mplg`는 content type `application/vnd.morit.plugin+zip`인 deterministic ZIP입니다. 최대 2 MiB,
+entry 최대 64개이며 다음 안전 검사를 통과해야 합니다.
+
+- 중복 entry 없음
+- 절대 경로, `..`, 역슬래시, symlink 없음
+- 허용된 source·asset·child package만 포함
+- compiled manifest가 package 파일과 일치
+- 모든 entry digest를 포함한 embedded Ed25519 signature 유효
+
+정상 signature 검증을 제거하거나 ZIP 검사 오류를 숨겨 설치하지 않습니다.
+
+## 기본 자동 서명
+
+공식 Node CLI build는 publisher별 key를 안전한 로컬 디렉터리에 만들고 자동 서명한 뒤 결과를 다시
+검증합니다.
+
+```bash
+npx -y @morit/cli plugin build . --output ./dist/plugin.mplg
+```
+
+`.mplg`에는 public key와 signature만 들어갑니다. trusted publisher 등록은 선택 사항이지만 등록된
+publisher key가 있으면 embedded key와 일치해야 합니다.
+
+저장소 Python pipeline에서 조직의 고정 key를 사용할 때는 다음과 같습니다.
+
+```bash
+python tools/morit_plugin.py package . \
+  --private-key /secure/example.ed25519 \
+  --output ./dist/plugin.mplg
+python tools/morit_plugin.py verify ./dist/plugin.mplg
+```
+
+`build --unsigned`는 별도 signing pipeline의 중간 파일을 만들 때만 사용합니다. unsigned package는
+설치할 수 없으며 사용자에게 최종 `.mplg`로 제공하지 않습니다.
+
+```bash
+python tools/morit_plugin.py build . --unsigned --output ./dist/unsigned.mplg
+python tools/morit_plugin.py sign ./dist/unsigned.mplg \
+  --private-key /secure/example.ed25519 \
+  --output ./dist/plugin.mplg
+python tools/morit_plugin.py verify ./dist/plugin.mplg
+```
+
+## Source ZIP과 package
+
+Source ZIP은 편집 가능한 전체 프로젝트이고 `.mplg`는 설치에 필요한 compiled subset입니다.
+
+| 산출물 | 용도 | 비밀 값 |
+|---|---|---|
+| `*-source.zip` | 리뷰·다른 환경에서 편집 | 포함 금지 |
+| `*.mplg` | 앱 설치·Deployment | private key/secret 포함 금지 |
+| `*-preview.html` | 구조 보조 점검 | 실행 코드 포함 금지 |
+
+서로 다른 artifact를 같은 확장자나 MIME으로 제공하지 않습니다.
+
+## 테스트 층
+
+### 1. Source 계약
+
+```bash
+npx -y @morit/cli plugin validate .
+```
+
+Manifest 필드, fragment 병합, 권한 부분집합, capability/runtime, UI tree·binding·route, Credential·
+Connector, source entrypoint, dependency를 검사합니다.
+
+### 2. Preview
+
+```bash
+python tools/morit_plugin.py preview . --output ./dist/preview.html
+```
+
+정보 구조와 compiled manifest를 점검합니다. 실제 Flutter renderer 성공을 대신하지 않습니다.
+
+### 3. Package reopen
+
+```bash
+npx -y @morit/cli plugin build . --output ./dist/plugin.mplg
+python tools/morit_plugin.py verify ./dist/plugin.mplg
+```
+
+크기, SHA-256, entry, manifest, publisher, embedded signature를 확인합니다.
+
+### 4. Backend/API
+
+테스트 계정으로 설치 → 목록 → 활성화 → permission/settings → Connection → capability → 삭제 순서를
+실행합니다. 위험한 ZIP, 위조 signature, 등록된 publisher key 불일치, 잘못된 manifest를 각각 차단하고
+실패 뒤 부분 DB row와 package file이 남지 않는지 확인합니다.
+
+### 5. 앱 실사용
+
+- 앱 데이터 삭제 후 첫 설치
+- Marketplace 조회·새로고침·재시도
+- local file 설치
+- 활성화와 권한 허용·거부
+- 화면 loading·empty·error·retry
+- 동일 package 재설치와 version update
+- OAuth 여러 Connection과 재연결
+- notification 실제 표시
+- 삭제와 재설치
+
+### 6. 회귀 검사
+
+SDK, Python Host, Local MCP, Remote MCP가 같은 contract를 반환하고 같은 fixture를 허용·거부하는지
+확인합니다. 문서 예제 JSON도 source 검증 과정에서 실행해 구현과 함께 변경합니다.
+
+## 실패 시 원칙
+
+validate, build, upload, DB install 단계 중 하나가 실패하면 성공 메시지나 artifact 링크를 반환하지
+않습니다. 설치는 임시 package 검증 후 DB와 파일을 commit하고, 중간 실패 시 둘 다 정리합니다.
+구체 오류 분류는 [오류 해결](troubleshooting.md)을 참고하세요.

package/assets/docs/permissions-and-data.md

@@ -0,0 +1,131 @@
+# 권한, 설정, 저장소, 알림
+
+## 권한 목록
+
+| permission | 허용하는 작업 |
+|---|---|
+| `network` | Host가 보호하는 외부 HTTPS/MCP 요청 |
+| `user_data_read` | Morit 사용자 데이터 읽기 |
+| `user_data_write` | Morit 사용자 데이터 변경 |
+| `attachments_read` | 사용자가 선택한 첨부 파일 읽기 |
+| `file_write` | 사용자에게 반환할 파일 artifact 작성 |
+| `ai_tool_call` | AI Tool 실행 경계 사용 |
+| `notifications` | 표시·예약·취소 알림 요청 |
+| `background` | Host scheduler에서 자동 실행 |
+| `account_read` | 필요한 계정 기본 정보 읽기 |
+| `storage` | 플러그인 전용 데이터 저장 |
+| `credentials` | Credential/Connection 사용 |
+
+Manifest는 요청 가능한 최대 권한, capability와 UI extension은 실제 필요한 부분집합을 선언합니다.
+사용자가 허용하지 않은 권한은 runtime에서 다시 차단됩니다. 화면을 볼 수 있다는 사실과 작업 권한은
+동일하지 않습니다.
+
+## Settings
+
+Settings는 default Instance에 저장되는 작은 사용자 환경설정입니다. UI Runtime state를 유지하려면
+`initial_state`에 key를 선언하고 해당 control 또는 `set_state`에 `persist: true`를 사용합니다.
+
+적합한 값:
+
+- 기본 기간, 정렬 방식, 표시 옵션
+- 알림 on/off와 사용자 선택 시간
+- 공개 school code처럼 민감하지 않은 외부 식별자
+
+저장하면 안 되는 값:
+
+- OAuth access/refresh token, API key
+- 파일 원문이나 큰 목록
+- 다른 플러그인의 설정
+- 서버가 검증하지 않은 실행 코드
+
+Settings 전체는 32 KiB 이하입니다. UI state의 client 저장 경계는 더 작을 수 있으므로 화면에 필요한
+최소 key만 유지합니다.
+
+## Plugin storage
+
+`storage`는 사용자·Installation/default Instance namespace로 격리됩니다. package가 업데이트되어도
+같은 Instance의 정상 데이터는 유지할 수 있지만 generation이 바뀐 오래된 실행은 새 상태를 쓰지
+못합니다.
+
+삭제 시 `data_policy`가 일반 storage의 `purge` 또는 `retain`을 정합니다. credential, OAuth state,
+pending Host action은 별도 보안 수명주기를 따르며 일반 storage retention으로 보존하지 않습니다.
+
+## Network
+
+외부 통신은 `http_json`, `mcp_http`, 지원되는 Host adapter를 통과합니다.
+
+- 공개 HTTPS만 허용
+- redirect 비허용
+- DNS/IP와 SSRF 정책 적용
+- Connector timeout 최대 30초
+- retry 최대 4회
+- Instance별 rate limit
+- credential은 Host가 요청 직전에 주입
+
+endpoint, Authorization header, secret을 UI state나 capability 결과에 복사하지 않습니다.
+
+Capability 결과 URL을 `image` 또는 `avatar`에 표시하는 경우에도 같은 권한 경계를 사용합니다.
+Manifest의 `network` 요청과 활성 Instance의 `network` grant가 모두 필요합니다. Flutter 앱은 외부
+이미지를 직접 요청하지 않고 인증된 Host proxy를 호출하며, Host가 public HTTPS·SSRF·redirect·이미지
+형식·512 KiB·4096 px·16 MP 제한을 적용합니다. 선언과 상세 제한은
+[UI Runtime v2](ui-runtime-v2.md), endpoint는 [수명주기와 HTTP API](lifecycle-and-api.md)를
+참고하세요.
+
+## Notification Host action
+
+Capability 결과의 `data.host_actions`는 Host가 서버에서 다시 확인하고 durable outbox에 기록합니다.
+알림을 직접 OS API로 호출하지 않습니다.
+
+```json
+{
+  "type": "schedule_notification",
+  "id": 41001,
+  "key": "school_life:morning:2026-08-14",
+  "title": "내일 학교 일정",
+  "body": "1교시는 수학입니다.",
+  "at_millis": 1786640400000,
+  "category": "reminder",
+  "visibility": "private",
+  "silent": false
+}
+```
+
+지원 type:
+
+- `show_notification`: 즉시 표시
+- `schedule_notification`: `at_millis`에 예약
+- `cancel_notification`: 같은 `id`와 `key` 취소
+
+공통 한도는 `id` 0~2,147,483,647, `key` 최대 240자, `title` 160자, `body` 500자,
+`big_text` 2,000자입니다. `category`는 `general`, `reminder`, `progress`, `status`,
+`visibility`는 `private`, `public`, `secret`입니다. 예약은 현재부터 최대 366일 안입니다.
+
+progress:
+
+```json
+{
+  "current": 3,
+  "max": 10,
+  "indeterminate": false
+}
+```
+
+`max`는 1~1,000,000이고 `current`는 0~max입니다. 진행 알림은 실제 작업 상태와 일치해야 하며 완료된
+뒤 ongoing 상태로 남기지 않습니다.
+
+## Durable delivery
+
+Host는 pending action을 lease한 뒤 플랫폼 gateway에 전달하고 결과를 ACK합니다. 앱이 중단되어도
+lease가 만료되면 재전달할 수 있으므로 `key`를 안정적인 중복 제거 키로 만듭니다. 권한 철회,
+Instance disable/delete, package generation 변경은 해당 owner의 pending action을 폐기합니다.
+
+현재 알림 gateway 실사용 검증은 Android 기준입니다. iOS/Desktop은 같은 Host action 계약 위에
+플랫폼 adapter를 구현해야 합니다. 지원되지 않는 플랫폼에서 알림 실패를 원본 데이터 저장 성공으로
+위장하지 않되, 알림 하나 때문에 읽기 화면 전체를 깨뜨리지 않습니다.
+
+## Background
+
+Background capability는 `background` 권한과 15~10,080분의 `interval_minutes`가 필요합니다.
+Host는 enabled, granted permission, generation, 연결 상태를 확인한 뒤 실행합니다. 앱이 꺼져 있을 때
+정확한 시각 실행을 보장하는 cron으로 설명하지 않습니다. 사용자에게 주기, 마지막 실행, 오류,
+끄기 동작을 settings에서 제공합니다.

package/assets/docs/platform-compatibility.md

@@ -0,0 +1,62 @@
+# Android, iOS, Desktop 호환
+
+Morit 앱은 현재 Android-first입니다. Plugin UI와 capability 계약은 플랫폼 중립 JSON이지만, 모든
+Host 기능이 모든 플랫폼에서 구현되었다는 뜻은 아닙니다.
+
+## 현재 지원 범위
+
+| 영역 | Android | iOS | Desktop |
+|---|---|---|---|
+| Manifest·서명·설치 계약 | 지원 | Host 구현 필요 | Host 구현 필요 |
+| Material 3 Runtime tree | 지원 | 공용 Flutter renderer 재사용 목표 | 공용 Flutter renderer 재사용 목표 |
+| capability와 Connector 호출 | 지원 | Host 실행 경계 구현 필요 | Host 실행 경계 구현 필요 |
+| 일반 Plugin storage/settings | 지원 | Host 저장 adapter 필요 | Host 저장 adapter 필요 |
+| 알림 예약·표시 | Android gateway 지원 | iOS gateway 필요 | OS별 gateway 필요 |
+| Android 공유·다운로드 네이티브 기능 | 지원 | 동일 동작 아님 | 동일 동작 아님 |
+
+문서나 배포 설명에서 iOS·Desktop을 현재 검증 완료로 표현하지 않습니다. 플랫폼 지원은 실제 앱
+빌드와 기기 테스트 결과로 표시합니다.
+
+## 플랫폼 중립으로 작성하기
+
+- Dart, JavaScript, HTML, WebView, native view를 UI fragment에 넣지 않습니다.
+- 색상 코드와 픽셀 고정 화면 대신 Host token과 반응형 속성을 사용합니다.
+- 파일 경로는 POSIX package 상대 경로만 사용합니다.
+- 외부 앱 실행이나 OS 설정 화면 이동을 capability 성공의 필수 조건으로 만들지 않습니다.
+- notification은 Host action으로 요청하고 플랫폼 채널 이름을 manifest에 넣지 않습니다.
+- touch 전용 표현 대신 “선택”, “열기”, “실행”처럼 입력 장치와 무관한 문구를 씁니다.
+
+## 반응형 입력과 접근성
+
+Android의 좁은 세로 화면을 최소 기준으로 설계하되, 넓은 창에서는 무조건 빈 공간을 채우지
+않습니다. `stack_at`과 `min_item_width`로 구조만 바꾸고 읽는 순서는 유지합니다. 키보드 focus와
+스크린 리더 순서는 JSON children 순서를 따르므로 시각적 배치와 의미 순서를 다르게 만들지 않습니다.
+
+`icon`만 있는 action은 의미를 전달하기 어렵습니다. 주요 행동에는 텍스트 `label`을 제공하고,
+색만으로 상태를 구분하지 않습니다. 시스템 글자 크기가 커져도 핵심 문구와 행동이 잘리지 않도록
+중요 텍스트에 과도한 `max_lines`를 쓰지 않습니다.
+
+## 기능 저하 원칙
+
+특정 플랫폼 adapter가 없을 때 전체 플러그인을 깨뜨리지 않습니다.
+
+- UI는 읽을 수 있는 상태와 지원 범위 안내를 유지합니다.
+- 해당 action만 비활성화하거나 명확한 오류로 종료합니다.
+- capability는 성공으로 위장하지 않습니다.
+- 알림을 만들지 못해도 원본 일정·데이터 저장 결과는 별도로 판단합니다.
+- 재시도가 의미 있는 경우에만 재시도 행동을 제공합니다.
+
+## 출시 전 플랫폼 체크
+
+각 지원 플랫폼에서 다음을 실제로 확인합니다.
+
+1. 설치·업데이트·삭제
+2. 첫 화면, 빈 데이터, 긴 텍스트, 큰 글자 크기
+3. 화면 이동과 뒤로가기/창 닫기
+4. 권한 허용·거부·철회
+5. OAuth 연결·만료·재연결
+6. background와 notification의 실제 전달
+7. 오프라인·timeout·재시도
+8. 키보드와 스크린 리더 순서
+
+실행하지 않은 항목은 “미검증”으로 기록합니다.

package/assets/docs/project-structure.md

@@ -0,0 +1,102 @@
+# 프로젝트 구조와 fragment
+
+## 권장 디렉터리
+
+```text
+my-plugin/
+├─ manifest.json
+├─ README.md
+├─ tools/*.json
+├─ skills/*.json
+├─ search/*.json
+├─ notifications/*.json
+├─ background/*.json
+├─ ui/*.json
+├─ credentials/*.json
+├─ slash_commands/*.json
+├─ src/**/*.py
+├─ assets/*.{json,md,txt,png,jpg,jpeg,gif,webp}
+├─ children/*.mplg
+├─ morit-plugin.json
+└─ dist/
+```
+
+`morit-plugin.json`과 `dist/`는 개발 상태와 산출물이므로 설치 패키지의 기능 계약이 아닙니다.
+비밀 값도 두 위치에 저장하지 않습니다.
+
+## fragment 병합 규칙
+
+각 fragment 파일은 UTF-8 JSON 객체 하나입니다. 빌드할 때 파일명을 정렬한 순서로 다음 manifest
+배열에 추가합니다.
+
+| 디렉터리 | 대상 배열 | 자동으로 채우는 값 |
+|---|---|---|
+| `capabilities/` | `capabilities` | 없음 |
+| `tools/` | `capabilities` | `kind: "tool"` |
+| `skills/` | `capabilities` | `kind: "skill"` |
+| `search/` | `capabilities` | `kind: "provider"`, `runtime.role: "search"` |
+| `notifications/` | `capabilities` | `kind: "notification"` |
+| `background/` | `capabilities` | `kind: "background"` |
+| `ui/` | `ui_extensions` | 없음 |
+| `credentials/` | `credentials` | 없음 |
+| `slash_commands/` | `slash_commands` | 없음 |
+
+같은 값이 fragment에 이미 있으면서 자동 값과 다르면 빌드가 실패합니다. manifest 배열과 fragment
+배열은 합쳐지므로 ID는 전체에서 유일해야 합니다.
+
+## source와 패키지에 들어가는 파일
+
+검증은 프로젝트의 안전한 상대 POSIX 경로만 읽습니다. 절대 경로, `..`, 역슬래시, Windows 예약명,
+심볼릭 링크는 사용할 수 없습니다. 프로젝트 전체 한도는 1 MiB, 파일 수는 64개, 파일 하나는
+512 KiB입니다. 최종 `.mplg`는 2 MiB 이하입니다.
+
+빌드가 설치 패키지에 포함하는 항목은 다음뿐입니다.
+
+- fragment를 병합해 만든 `manifest.json`
+- 선택적 `README.md`
+- 선언된 `sandbox_python` entrypoint와 연결된 `src/**/*.py`
+- 허용 확장자의 `assets/`
+- dependency와 정확히 일치하는 `children/*.mplg`
+- `signature.json`
+
+fragment 원본은 compiled manifest에 병합되므로 `.mplg` 안에 중복해 넣지 않습니다. `src/*.py`는
+각각 정확히 한 `sandbox_python` capability가 entrypoint로 선언해야 하며, 선언되지 않은 Python
+파일이나 여러 capability가 공유하는 entrypoint는 거부됩니다.
+
+## 텍스트와 바이너리
+
+JSON, Markdown, 텍스트, Python은 엄격한 UTF-8입니다. PNG/JPEG/WebP/GIF와 child `.mplg`는
+바이너리 그대로 보존됩니다. Cloud sync의 JSON 경계를 지날 때만 바이너리 envelope로 변환되며,
+pull·source ZIP·build 결과에서는 원래 바이트로 복원됩니다.
+
+UI에서 참조하는 package 이미지는 최대 512 KiB이고 가로·세로가 각각 4096 px 이하여야 합니다.
+정적 이미지는 1 frame, GIF/WebP 애니메이션은 최대 128 frame이며 `width × height × frame 수`로
+계산한 frame 합산 pixel은 최대 16,000,000입니다. 확장자·MIME에 대응하는 magic byte와 실제 이미지
+포맷도 일치해야 합니다.
+
+### 웹 프로젝트에서 아이콘 올리기
+
+developers.moring.co의 **플러그인 프로젝트 관리 → 정보 → 앱 아이콘**에서는 PNG, JPEG, WebP
+파일을 직접 선택하거나 끌어 놓을 수 있습니다. 업로드가 완료되면 이미지는
+`assets/plugin-icon.*`에 저장되고 `manifest.icon`도 같은 revision에서 함께 갱신됩니다. 기존에 이
+화면에서 올린 아이콘을 교체하거나 제거할 때도 파일과 manifest가 원자적으로 함께 반영됩니다.
+
+아이콘은 512 KiB 이하, 가로·세로 각각 4096 px 이하, 전체 16,000,000 pixel 이하만 허용됩니다.
+확장자만 바꾼 파일이나 실제 포맷이 다른 이미지는 서버 검증에서 거부됩니다. MCP가 바이너리 파일을
+직접 전송하지 못하더라도 이 화면에서 한 번 올린 아이콘은 프로젝트 source에 포함되므로 이후 MCP,
+CLI pull·build에서도 원래 이미지 바이트와 `manifest.icon` 경로가 그대로 유지됩니다.
+
+## 파일별 책임
+
+- `manifest.json`: 패키지 신원, 버전, 전역 권한, 연결과 데이터 정책
+- capability fragment: AI나 UI가 실행할 한 가지 작업
+- UI fragment: Host가 표시할 화면과 capability 참조
+- credential/connector: 사용자 계정 또는 Cloud 비밀 값과 외부 endpoint의 연결
+- `src/`: 검증되고 격리된 Python 작업만 포함
+- `assets/`: 아이콘·정적 데이터·설명 자료
+- `children/`: 함께 설치할 별도 서명 플러그인
+
+화면 문구, 외부 endpoint, 비밀 값, 사용자 설정을 한 JSON에 섞지 마세요. 바뀌는 주기와 접근 권한이
+다른 정보는 각각 UI, Connector, Secret, settings에 둡니다.
+
+다음은 [Manifest 레퍼런스](manifest.md)입니다.