@morit/cli 1.0.0 → 1.1.1

package/assets/docs/remote-mcp.md

@@ -0,0 +1,152 @@
+# 원격 Plugin MCP
+
+Remote Plugin MCP는 파일시스템이 없는 AI client가 Morit 조직의 Cloud Project를 만들고 검증·배포할
+수 있게 하는 OAuth 보호 Streamable HTTP 서비스입니다.
+
+```text
+https://morit-api.moring.co/mcp
+```
+
+인증 전 응답은 `401`과 RFC 9728 protected-resource metadata 위치를 반환합니다. Morit SSO의
+authorization code + PKCE 흐름으로 로그인하며 승인된 scope와 사용자 RLS를 모든 Tool에 적용합니다.
+
+## 연결
+
+Codex:
+
+```bash
+codex mcp add morit-plugin-remote --url https://morit-api.moring.co/mcp
+codex mcp login morit-plugin-remote
+```
+
+Claude Code:
+
+```bash
+claude mcp add --transport http --scope user \
+  morit-plugin-remote https://morit-api.moring.co/mcp
+```
+
+## Tool 목록
+
+### 계약과 문서
+
+| Tool | 목적 |
+|---|---|
+| `morit_sdk_contract` | 현재 SDK/Host capability contract 전체 반환 |
+| `morit_docs_search` | bundled 공식 문서 검색 |
+| `morit_docs_get` | 검색 결과의 Markdown 한 파일 읽기 |
+
+### 조직과 Project
+
+| Tool | 목적 |
+|---|---|
+| `morit_organization_list` | 접근 가능한 조직과 role 조회 |
+| `morit_project_list` | 조직의 Cloud Project 목록 |
+| `morit_project_create` | 표준 source를 가진 Project 생성 |
+| `morit_project_files_get` | 최신 revision과 source snapshot 읽기 |
+| `morit_project_files_put` | revision 보호를 적용한 파일 생성·수정·삭제 |
+| `morit_project_metadata_update` | Marketplace 표시 metadata 변경 |
+| `morit_project_delete` | 활성 Deployment가 없는 Project 삭제 |
+
+### 검증과 artifact
+
+| Tool | 목적 |
+|---|---|
+| `morit_project_validate` | 현재 revision의 source 계약 검사 |
+| `morit_project_preview` | private HTML preview artifact 생성 |
+| `morit_project_source_download` | 편집 가능한 source ZIP 생성 |
+| `morit_build_start` | immutable build/Deployment 시작 |
+| `morit_build_status` | build state와 package artifact 조회 |
+| `morit_artifact_download` | owned artifact의 짧은 수명 download URL 생성 |
+
+### Deployment
+
+| Tool | 목적 |
+|---|---|
+| `morit_deployment_list` | Project의 immutable Deployment history |
+| `morit_deployment_get` | build 결과, hash, logs, visibility 조회 |
+| `morit_deployment_publish` | completed Deployment를 private/public current로 설정 |
+
+### Secret과 Connection
+
+| Tool | 목적 |
+|---|---|
+| `morit_project_secret_list` | Secret ID와 masked metadata 조회 |
+| `morit_project_secret_put` | encrypted Secret 생성·rotation |
+| `morit_project_secret_delete` | 참조되지 않는 Secret 삭제 |
+| `morit_project_connection_list` | OAuth/API Connection 선언 조회 |
+| `morit_project_connection_put` | Connection 생성·수정 |
+| `morit_project_connection_delete` | Connection 선언 삭제 |
+
+Secret Tool은 평문을 반환하지 않습니다. source, log, Tool 응답에 Secret 값을 복사하지 마세요.
+
+## ID와 경로
+
+- organization, Project, Deployment, artifact ID는 `format: uuid`입니다.
+- Manifest plugin ID는 소문자 reverse-domain ID입니다.
+- source path는 상대 POSIX 형식입니다.
+- `..`, 역슬래시, 절대 경로, Windows 예약명, symlink는 거부합니다.
+- `manifest.json`은 삭제할 수 없습니다.
+- 한 파일 512 KiB, source 최대 64개 파일·1 MiB입니다.
+- 한 `files_put` 변경은 최대 64개입니다.
+
+AI가 UUID나 경로를 추측하지 않고 list/create/get 결과를 그대로 다음 Tool에 전달해야 합니다.
+
+## Revision과 파일 변경
+
+```json
+{
+  "project_id": "00000000-0000-4000-8000-000000000000",
+  "revision": 3,
+  "files": {
+    "ui/home.json": "{...}\n",
+    "ui/old.json": null
+  }
+}
+```
+
+`null`은 파일 삭제입니다. revision이 오래되면 전체 요청을 거부하고 최신 source를 반환하므로
+`files_get` → 변경 병합 → `files_put`을 반복합니다. conflict를 `force`로 숨기지 않습니다.
+
+이미지 asset과 child `.mplg`는 검증된 binary envelope로만 JSON 경계를 지나며 최종 source ZIP과
+package에서는 원래 바이트로 복원됩니다.
+
+## Build와 다운로드
+
+```text
+morit_build_start
+  → job_id와 deployment_id
+morit_build_status 반복
+  → completed + artifact_id + size + sha256
+morit_deployment_get
+  → exact artifact hash와 visibility
+morit_artifact_download
+  → 짧은 수명 URL
+```
+
+같은 요청을 재시도할 때 새 build가 생성될 수 있으므로 반환된 ID를 섞지 않습니다. status가
+`failed`이면 logs의 공개 진단을 source에 반영하고 새 build를 시작합니다. `processing`을 완료로
+간주하지 않습니다.
+
+## Protocol compatibility
+
+서비스는 직접 `tools/list`/`tools/call`을 보내는 최신 handshake-free client와
+initialize → initialized → Tool 호출 방식의 client를 모두 지원합니다. `MCP-Protocol-Version`과
+`Mcp-Method`/`Mcp-Name` 같은 routing header는 서버가 협상한 값과 맞춰야 합니다. 지원 protocol
+date는 서비스 응답을 사용하며 client가 임의로 고정하지 않습니다.
+
+## 복구
+
+| 오류 | 대응 |
+|---|---|
+| `401` | OAuth metadata를 따라 로그인 |
+| scope 부족 | 필요한 scope를 사용자에게 명시하고 재승인 |
+| Project 없음 | 현재 조직과 Project ID 확인 |
+| revision conflict | 최신 source를 읽고 병합 |
+| validation 오류 | 반환된 정확한 field/reference 진단 수정 |
+| build timeout | status로 기존 build 확인 후 필요한 경우 새 build |
+| artifact 만료 | 같은 artifact ID로 새 download URL 발급 |
+| Secret 참조 중 | Connection 참조를 먼저 정리 |
+
+로컬 파일을 직접 편집해야 하면 [Local MCP](sdk-and-mcp.md)를 사용합니다. Remote 서비스에 local
+absolute path나 publisher private key를 전달하지 않습니다.

package/assets/docs/school-life-privacy.md

@@ -0,0 +1,49 @@
+# 학교 생활 플러그인 개인정보 처리 안내
+
+최종 수정일: 2026-08-13
+
+학교 생활 플러그인은 학생이 선택한 학교, 학년, 반을 기준으로 시간표·급식·학사일정을
+보여 주고 기기 안에서 알림과 아침 브리핑을 구성합니다. 플러그인 설치 전에 아래 데이터
+사용 범위를 확인할 수 있으며, 설치 후 설정에서 언제든 초기화하거나 삭제할 수 있습니다.
+
+## 사용하는 정보
+
+- 사용자가 직접 선택한 학교 코드, 교육청 코드, 학년, 반
+- 알레르기 필터, 알림 사용 여부와 알림 시간
+- 중복 알림을 막기 위한 마지막 실행 날짜
+- 교육부 NEIS 공개 API가 제공하는 시간표, 급식, 학사일정
+
+이 플러그인은 이름, 주민등록번호, 학생 번호, 성적, 연락처, 계정 비밀번호를 요청하거나
+수집하지 않습니다. 별도의 OAuth 계정이나 API key도 요구하지 않습니다.
+
+## 처리 목적과 저장 위치
+
+학교·학년·반 설정은 사용자가 요청한 학교 정보를 반복 입력하지 않도록 해당 Morit
+사용자의 Plugin Instance 저장소에만 보관합니다. 조회한 공개 학교 정보는 화면 표시와
+알림 생성에만 사용합니다. 다른 사용자나 다른 Instance와 공유하지 않습니다.
+
+외부 요청은 선언된 NEIS HTTPS endpoint로만 제한되며 Morit의 SSRF filtering proxy를
+통과합니다. 플러그인 코드에는 운영 credential이나 사용자 token이 포함되지 않습니다.
+
+## 보관과 삭제
+
+Manifest의 data policy는 `purge`입니다. 사용자가 Plugin Instance 또는 플러그인을
+삭제하면 해당 Instance의 설정, 조회 cache, 알림 상태를 함께 삭제합니다. 앱 데이터
+초기화 후 서버에 남은 개인 Plugin Instance도 계정의 플러그인 관리 화면에서 삭제할 수
+있습니다.
+
+## 권한
+
+- 네트워크: NEIS 공개 학교 정보 조회
+- 저장소: 학교·학년·반과 사용자 설정 저장
+- 알림: 사용자가 켠 경우 다음 학교 일정과 아침 브리핑 알림 예약
+- 백그라운드: 사용자가 켠 경우 공개 학교 정보 갱신과 브리핑 준비
+
+권한이 꺼져 있거나 네트워크가 실패하면 해당 기능만 사용할 수 없다는 상태를 표시하며,
+오류를 숨기거나 임의의 학교 정보를 생성하지 않습니다.
+
+## 문의와 변경
+
+플러그인 기능과 구현은 [학교 생활 예제 문서](examples-school-life.md)에서 확인할 수
+있습니다. 처리 항목이나 외부 제공 범위가 바뀌면 새 Plugin version과 이 문서를 함께
+갱신하며, 권한이 추가되는 경우 사용자가 설치 전에 다시 확인할 수 있게 표시합니다.

package/assets/docs/screens-layout-navigation.md

@@ -0,0 +1,95 @@
+# 화면, 레이아웃, 내비게이션
+
+플러그인 UI는 “어디에 나타나는가”를 정하는 extension point와 “무엇을 그리는가”를 정하는 Runtime
+tree로 나뉩니다. 먼저 사용자 흐름을 화면 단위로 나눈 뒤 각 화면의 JSON을 작성하세요.
+
+## 화면 역할부터 정하기
+
+| 사용자 목적 | extension point | 권장 내용 |
+|---|---|---|
+| 홈에서 상태를 빠르게 확인 | `card` | 핵심 상태 1~3개와 명확한 다음 행동 |
+| 홈에서 즉시 실행 | `action` | 짧은 라벨의 단일 행동 |
+| 플러그인의 주 작업 | `screen` | 목록, 상세, 편집 등 독립 화면 |
+| 홈 메뉴 진입점 | `menu` | 자주 찾지만 상시 노출할 필요 없는 화면 |
+| 플러그인 설정 | `settings` | 권한, 알림, 표시 옵션, 계정 진입 |
+| AI와 함께 작업 | `workspace` | 대화 맥락과 함께 보는 도구 화면 |
+| AI 실행 결과 | `response` | 해당 AI 메시지에 붙는 읽기 중심 결과 |
+
+`surface`는 기존 패키지 호환용 일반 화면 point입니다. 새 독립 화면에는 역할이 더 명확한
+`screen`을 사용합니다.
+
+## 권장 화면 흐름
+
+```text
+Home card/action
+  → Overview screen
+      ├─ List/filter state
+      ├─ Detail screen
+      └─ Edit dialog 또는 sheet
+
+Plugin detail
+  → Settings screen
+      ├─ Account connections
+      ├─ Notifications
+      └─ Display preferences
+```
+
+첫 화면은 사용자가 현재 상태와 다음 행동을 5초 안에 파악할 수 있어야 합니다. 원시 JSON,
+capability ID, package ID, 디버그 상태는 사용자 화면에 두지 않습니다.
+
+## 레이아웃 선택
+
+- `column`: 기본 읽기 흐름. 모바일에서 가장 안전한 시작점입니다.
+- `row`: 짧은 상태와 행동을 나란히 놓을 때 사용합니다. 좁은 폭에서는 `stack_at`으로 세로 전환합니다.
+- `wrap`: chip이나 짧은 필터처럼 항목 너비가 다른 반복 요소에 사용합니다.
+- `grid`: 같은 중요도의 카드·metric을 반복할 때 사용합니다. `min_item_width`로 열 수를 줄입니다.
+- `section`: 제목이 있는 정보 그룹입니다. 한 화면에 section이 너무 많아지면 화면을 분리합니다.
+- `card`: 배경과 경계가 필요한 독립 정보나 누를 수 있는 요약에 사용합니다.
+
+중첩 card와 section을 장식 목적으로 반복하지 마세요. 부모 하나로 관계가 설명되면 추가 surface는
+정보 계층을 흐립니다.
+
+## 내비게이션
+
+같은 플러그인의 다른 UI extension으로 이동할 때 `navigate`를 사용합니다.
+
+```json
+{
+  "type": "button",
+  "props": {"label": "전체 시간표 보기", "style": "tonal"},
+  "action": {"type": "navigate", "target": "school_life.week"}
+}
+```
+
+`target`은 같은 manifest에 선언된 UI extension ID여야 합니다. 현재 화면을 닫고 이전 Host 화면으로
+돌아갈 때는 `back`을 사용합니다.
+
+```json
+{"type": "back"}
+```
+
+탭처럼 보여야 하는 단순 필터는 새 화면을 만들지 말고 `chip`과 `set_state`로 처리합니다. 반대로
+목록과 상세처럼 제목, 스크롤 위치, 뒤로가기 의미가 달라지는 정보는 별도 `screen`으로 나눕니다.
+
+## 상단 메뉴와 설정
+
+Host가 화면 제목, 뒤로가기, 플러그인 메뉴를 담당합니다. JSON tree에서 별도 앱 바를 흉내 내지
+않습니다. 화면의 overflow 메뉴는 해당 화면에서 자주 쓰지 않는 보조 행동만 담습니다. 계정 연결은
+settings 화면의 Connection 관리로 제공하며 동일 패키지 root Instance를 복제하는 “계정 추가”
+동작을 만들지 않습니다.
+
+## 상태별 화면
+
+한 data source에는 적어도 다음 상태를 고려합니다.
+
+| 상태 | 화면 동작 |
+|---|---|
+| 첫 로딩 | 기존 레이아웃 크기를 유지하는 진행 표시 |
+| 데이터 없음 | 무엇이 비었는지와 시작 행동을 설명하는 `empty` |
+| 재시도 가능 오류 | 원인 요약과 `refresh` 행동 |
+| 권한·연결 필요 | 필요한 권한/계정과 설정 진입 |
+| 갱신 실패 + 기존 데이터 | 기존 내용을 유지하고 작은 상태 안내 |
+
+전체 화면을 한 data source의 오류로 교체하지 않습니다. 오류는 영향을 받은 section에 격리합니다.
+
+다음은 [기본·커스텀 컴포넌트](components.md)입니다.

package/assets/docs/sdk-and-mcp.md

@@ -0,0 +1,182 @@
+# CLI와 AI 에이전트 MCP
+
+Morit은 두 MCP 연결을 제공합니다.
+
+| 연결 | 실행 위치 | 적합한 작업 |
+|---|---|---|
+| Local `@morit/plugin-mcp` | 개발자 PC의 stdio process | 로컬 파일 직접 편집, 빠른 preview/build |
+| Remote `https://morit-api.moring.co/mcp` | Morit Cloud Streamable HTTP | 파일시스템 없는 AI client, 조직 Project·Secret·Deployment |
+
+두 연결은 `@morit/cli`와 Host의 같은 Plugin contract를 사용합니다. Local source에 접근할 필요가
+없으면 Remote를, 현재 저장소 파일을 직접 고쳐야 하면 Local을 선택합니다.
+
+## 준비
+
+```bash
+node --version
+npx -y @morit/cli login
+```
+
+Node.js 20.12 이상이 필요합니다. Local MCP의 Cloud Tool을 쓸 때만 CLI 로그인이 필요합니다.
+MCP 설정이나 Project source에 access token을 직접 넣지 않습니다.
+
+## Codex에 Local MCP 추가
+
+```bash
+codex mcp add morit-plugin-local -- npx -y @morit/plugin-mcp
+codex mcp list
+```
+
+특정 workspace만 허용하려면 환경변수로 절대 경로를 전달합니다.
+
+```bash
+codex mcp add morit-plugin-local \
+  --env MORIT_PLUGIN_WORKSPACE=/absolute/development/path \
+  -- npx -y @morit/plugin-mcp
+```
+
+Codex CLI/IDE/Desktop의 현재 MCP 설정 방식은
+[공식 OpenAI MCP 문서](https://learn.chatgpt.com/docs/extend/mcp?surface=cli)를 참고하세요. Codex
+TUI에서는 `/mcp`로 활성 서버를 확인합니다.
+
+## Codex에 Remote MCP 추가
+
+```bash
+codex mcp add morit-plugin-remote --url https://morit-api.moring.co/mcp
+codex mcp login morit-plugin-remote
+codex mcp list
+```
+
+브라우저에서 Morit 계정으로 로그인하고 조직과 scope를 승인합니다. static bearer token을 config에
+넣지 않습니다.
+
+## Claude Code
+
+Local stdio:
+
+```bash
+claude mcp add --scope user morit-plugin-local -- npx -y @morit/plugin-mcp
+```
+
+Remote Streamable HTTP:
+
+```bash
+claude mcp add --transport http --scope user \
+  morit-plugin-remote https://morit-api.moring.co/mcp
+```
+
+클라이언트가 OAuth를 요청하면 Morit SSO 승인을 완료한 뒤 Tool 목록을 새로고침합니다. Claude
+Web/Desktop에서는 Custom Connector에 같은 Remote URL을 등록합니다. Local stdio는 로컬 process를
+실행할 수 있는 client에서만 사용할 수 있습니다.
+
+## ChatGPT와 기타 Remote MCP client
+
+ChatGPT에서 custom MCP app을 사용할 수 있는 계정·workspace라면 Apps의 custom connector 생성
+화면에 다음 URL을 입력하고 Morit OAuth를 승인합니다.
+
+```text
+https://morit-api.moring.co/mcp
+```
+
+ChatGPT Web은 개발자 PC의 stdio process나 Codex `config.toml`을 읽지 않으므로 Local MCP 대신
+Remote MCP를 사용합니다. 조직 계정은 관리자가 custom app과 필요한 read/write scope를 허용해야
+할 수 있습니다. Tool이 변경된 뒤에는 connector의 Tool schema를 새로고침하고 새 대화에서
+확인합니다.
+
+stdio MCP를 지원하는 다른 desktop agent의 일반적인 설정은 다음 형태입니다. 실제 설정 파일 위치와
+key 이름은 해당 client 문서를 따릅니다.
+
+```json
+{
+  "mcpServers": {
+    "morit-plugin-local": {
+      "command": "npx",
+      "args": ["-y", "@morit/plugin-mcp"],
+      "env": {
+        "MORIT_PLUGIN_WORKSPACE": "/absolute/development/path"
+      }
+    }
+  }
+}
+```
+
+Remote를 지원하는 client에는 command나 server Secret 대신 endpoint와 OAuth만 설정합니다. 연결 뒤
+Tool 목록에서 `morit_sdk_contract`, `morit_docs_search`, `morit_project_create`가 보이는지 확인합니다.
+[OpenAI의 Apps 안내](https://help.openai.com/en/articles/11487775-connectors-in-chatgpt)에서 현재 계정과
+workspace의 custom app 지원 범위를 확인할 수 있습니다.
+
+## Local MCP 작업 순서
+
+```text
+morit_sdk_contract
+→ morit_docs_search / morit_docs_get
+→ morit_project_create 또는 morit_project_open
+→ morit_project_files_get
+→ morit_project_files_put
+→ morit_project_validate
+→ UI가 있으면 morit_project_preview
+→ morit_build_start / morit_build_status
+→ morit_artifact_download
+```
+
+주요 Local Tool:
+
+- 계약·문서: `morit_sdk_contract`, `morit_docs_search`, `morit_docs_get`
+- local project: `morit_project_create`, `morit_project_open`, `morit_project_files_get`,
+  `morit_project_files_put`
+- 산출물: `morit_project_validate`, `morit_project_preview`, `morit_project_source_download`,
+  `morit_build_start`, `morit_build_status`, `morit_artifact_download`
+- Cloud 상태·Project: `morit_cloud_status`, `morit_cloud_project_list`, `morit_cloud_project_get`,
+  `morit_cloud_project_add`, `morit_cloud_project_sync`, `morit_cloud_project_delete`
+- Cloud Deployment: `morit_cloud_deployment_start`, `morit_cloud_deployment_list`,
+  `morit_cloud_deployment_get`, `morit_cloud_deployment_publish`
+- Cloud Secret: `morit_cloud_secret_list`, `morit_cloud_secret_put`, `morit_cloud_secret_delete`
+- Cloud Connection: `morit_cloud_connection_list`, `morit_cloud_connection_put`,
+  `morit_cloud_connection_delete`
+
+MCP가 반환한 project ID, revision, artifact ID를 다음 호출에 그대로 사용합니다. 경로를 추측하거나
+build 전에 완료했다고 보고하지 않습니다.
+
+## Remote MCP 작업 순서
+
+```text
+morit_organization_list
+→ morit_project_create 또는 morit_project_list
+→ morit_project_files_get
+→ morit_project_files_put(revision 포함)
+→ morit_project_validate
+→ morit_project_preview
+→ morit_build_start
+→ morit_build_status
+→ morit_deployment_get
+→ morit_artifact_download
+```
+
+Secret과 Connection은 build 전에 별도 Tool로 설정합니다. Secret 조회는 ID와 masked metadata만
+반환하며 평문 값을 다시 읽을 수 없습니다.
+
+## 에이전트 완료 규칙
+
+AI 에이전트는 다음을 모두 확인한 뒤 완료를 보고합니다.
+
+- source를 다시 읽고 요청한 파일이 존재함
+- 최신 revision으로 validate 성공
+- UI가 있으면 preview artifact 생성
+- build state가 completed
+- `.mplg` artifact ID, 크기, SHA-256, MIME 확인
+- 다운로드한 package가 다시 열리고 signature가 유효함
+- 배포 요청이면 고유 Deployment와 visibility 확인
+
+## 연결 문제
+
+| 증상 | 확인 |
+|---|---|
+| Local server가 보이지 않음 | Node 버전, `npx -y @morit/plugin-mcp`, client restart |
+| workspace 밖 경로 거부 | `MORIT_PLUGIN_WORKSPACE`와 project 상대 경로 |
+| Remote `401` | 정상 OAuth 시작 여부, `codex mcp login` |
+| Remote `404` | `/mcp` ingress route |
+| contract parse 오류 | server가 전체 JSON stdout을 반환하는지, stderr 혼합 여부 |
+| revision conflict | `files_get`으로 최신 revision을 읽고 변경을 합침 |
+| artifact 없음 | build status가 completed인지 확인 |
+
+Remote Tool의 전체 필드는 [원격 Plugin MCP](remote-mcp.md)에 있습니다.

package/assets/docs/tool-and-skill.md

@@ -0,0 +1,163 @@
+# Tool, Skill, Search, Slash Command
+
+Capability는 사용자가 실행할 수 있는 한 가지 작업과 그 실행 경계를 선언합니다. UI에서 버튼을
+누르거나 AI가 Tool을 선택해도 같은 capability가 실행됩니다.
+
+## Capability kind
+
+| kind | 목적 | 실행 방식 |
+|---|---|---|
+| `tool` | 명시적인 한 번의 작업 | UI, AI, Slash Command |
+| `skill` | 여러 입력을 해석하는 작업 | AI, UI, Slash Command |
+| `provider` | AI 검색 후보 제공 | Search discovery |
+| `background` | 일정 간격의 자동 작업 | Host scheduler |
+| `notification` | 알림 생성·취소 작업 | UI, AI 또는 background |
+
+`tool`과 `skill`은 runtime adapter가 필수입니다. `provider`는
+`runtime.role: "search"`가 필요합니다. background runtime을 선언하면
+`interval_minutes`는 15~10,080입니다.
+
+## Runtime adapter
+
+| adapter | 용도 | 주요 설정·권한 |
+|---|---|---|
+| `text_stats` | 텍스트 통계 | 별도 권한 없음 |
+| `text_template` | 제한된 텍스트 template | `template` 최대 2,000자 |
+| `settings_search` | Instance settings의 검색 항목 | Search Provider용 |
+| `notification_template` | 검증된 알림 Host action 생성 | `notifications` |
+| `calendar_store` | 일정 저장·조회·reminder | `storage`, reminder는 `notifications` |
+| `http_json` | 공개 HTTPS JSON API | `network`, credential 사용 시 `credentials` |
+| `mcp_http` | Remote MCP Tool 호출 | `network`, 선택적 `credentials` |
+| `child_plugin` | dependency capability 호출 | 노출된 dependency와 capability |
+| `neis_school` | 학교 검색·시간표·급식·일정 | `network`, `storage`; reminder는 `notifications` |
+| `sandbox_python` | 격리된 Python 데이터 작업 | signed package와 고급 worker |
+
+## 선언형 adapter 예
+
+### Text template
+
+```json
+{
+  "adapter": "text_template",
+  "template": "요청을 다음 형식으로 정리합니다: {query}"
+}
+```
+
+복잡한 표현식이나 코드를 template에 넣지 않습니다.
+
+### Calendar store
+
+```json
+{
+  "adapter": "calendar_store",
+  "operation": "reminder",
+  "namespace": "study.schedule"
+}
+```
+
+일반 저장에는 `storage`, 알림 예약에는 `storage`와 `notifications`가 모두 필요합니다.
+
+### HTTP JSON
+
+```json
+{
+  "adapter": "http_json",
+  "connector_id": "notes_api",
+  "method": "POST",
+  "request_body": {"query": "{query}"},
+  "response": {"summary_path": "message", "data_path": "data"}
+}
+```
+
+GET과 POST만 지원하며 redirect를 따라가지 않습니다. endpoint는 공개 HTTPS이고 SSRF 보호 경계를
+통과합니다. bearer token은 Host가 Connection에서 주입하며 fragment에 직접 쓰지 않습니다.
+
+### Remote MCP
+
+Morit Host 1.7.6의 plugin outbound MCP adapter는 `mcp_http`입니다. 개발자용 Local/Remote Plugin
+MCP 서버와 이름이 비슷하지만, 설치된 플러그인이 선언한 외부 MCP Tool을 Host 경계에서 호출하는
+runtime입니다.
+
+```json
+{
+  "adapter": "mcp_http",
+  "connector_id": "research_mcp",
+  "tool_name": "search",
+  "protocol_version": "2025-11-25",
+  "argument_template": {"query": "{query}"}
+}
+```
+
+Host가 initialize → initialized → `tools/call` session을 관리합니다. credential이 거부되면 지원되는
+연결에서 한 번 갱신한 뒤 새 session으로 재시도합니다. MCP의 `isError: true`는 성공 결과로 바꾸지
+않습니다.
+
+### Sandbox Python
+
+```json
+{
+  "adapter": "sandbox_python",
+  "entrypoint": "src/analyze.py"
+}
+```
+
+entrypoint는 package 상대 POSIX 경로이고 각 `src/*.py` 파일과 정확히 1:1이어야 합니다. 코드는
+Archive API process에서 실행하지 않고 별도 rootless Docker + gVisor worker와 lease-fenced broker를
+거칩니다. 결과는 다음 객체여야 합니다.
+
+```json
+{
+  "summary": "분석을 완료했습니다.",
+  "data": {},
+  "evidence": []
+}
+```
+
+`summary` 없이 sandbox 경로나 내부 로그만 반환하면 완료된 결과가 아닙니다.
+
+## UI와 AI 노출
+
+AI는 enabled 상태이고 사용자에게 허용된 capability만 발견합니다. 제목과 설명은 모델이 언제 이
+기능을 선택할지 판단할 수 있게 동작과 입력을 구체적으로 씁니다.
+
+```json
+{
+  "id": "school_life.today",
+  "kind": "tool",
+  "title": "오늘 학교 생활 조회",
+  "description": "연결한 학교의 오늘 시간표, 급식, 학사일정을 조회합니다.",
+  "permissions": ["network", "storage"],
+  "timeout_seconds": 10,
+  "runtime": {"adapter": "neis_school", "operation": "overview"}
+}
+```
+
+UI `invoke`가 capability를 참조할 때도 enabled, generation, permission, timeout을 다시 확인합니다.
+UI에 capability ID를 사용자용 라벨로 표시하지 않습니다.
+
+## Slash Command
+
+Slash Command는 같은 package의 `tool` 또는 `skill`에 고정된 진입점입니다.
+
+```json
+{
+  "id": "school_life.today_command",
+  "command": "school",
+  "title": "오늘 학교 생활",
+  "description": "오늘 시간표와 급식을 확인합니다.",
+  "capability": "school_life.today",
+  "argument_template": {}
+}
+```
+
+Slash Command를 선언하지 않아도 Tool discovery는 유지됩니다. 여러 command가 같은 이름을 사용할 수
+없고 `/`는 `command` 값에 포함하지 않습니다.
+
+## 실패와 복구
+
+Capability는 권한 부족, 연결 필요, timeout, retryable network 오류, 잘못된 응답을 구분합니다.
+retry는 Connector에 선언한 bounded 정책만 사용합니다. Tool 하나가 실패했다고 AI 요청 전체를
+즉시 포기하지 말고, 오케스트레이터가 대체 Tool·재연결·부분 결과를 선택할 수 있도록 공개 오류를
+구체적으로 유지합니다.
+
+권한과 알림은 [권한, 설정, 저장소, 알림](permissions-and-data.md)을 참고하세요.