@morit/cli 1.4.0 → 1.5.0

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

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

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

@@ -1,95 +0,0 @@
-# 화면, 레이아웃, 내비게이션
-
-플러그인 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

@@ -1,199 +0,0 @@
-# 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 |
-
-두 연결은 SDK 1.7.12의 `@morit/cli`와 Host Plugin contract를 사용합니다. 계약에는 mode별 Plugin
-Theme, Local Storage/AI access, 표준 Storage Tool, UI binding, A2UI Response catalog와 safe
-preview가 포함됩니다. 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(light/dark 확인)
-→ 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 전에 완료했다고 보고하지 않습니다.
-
-PNG/JPEG/GIF/WebP icon·UI asset과 `children/*.mplg`는
-`morit-base64-v1:<canonical-base64>` 문자열로 `files_put`할 수 있습니다. text 경로에 envelope를
-쓰거나 이미지 확장자와 magic byte가 다르면 Local/Remote MCP가 거부합니다. `files_get`도 같은
-envelope를 반환하므로 수정하지 않은 바이트는 그대로 다음 revision에 유지합니다.
-
-Storage 기능을 생성할 때는 먼저 `morit_sdk_contract`의 `permissions`, `storage_tools`,
-`storage_ai_access`, `storage_limits`를 읽고 Manifest `storage`와 UI data source를 함께 작성합니다.
-AI가 쓰는 namespace는 `ai_access: read_write`와 `ai_storage` 권한을 모두 선언합니다. MCP는 package
-runtime 데이터를 읽는 우회 경로가 아니며 개발 source와 artifact만 다룹니다.
-
-Response extension을 생성할 때는 `ai_response`와 `ui_runtime` 계약을 함께 읽습니다. MCP 에이전트는
-`point: "response"`, Runtime v2, `a2ui.version/description/schema`, 실제 capability data source를 한
-단위로 작성해야 합니다. AI가 결과 JSON을 만들게 하지 말고 schema에는 표시 가능한 최소 데이터와
-empty 조건을 명시합니다. validate가 schema·권한·version을 거부하면 파일을 우회 패키징하지 않습니다.
-
-## 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

@@ -1,188 +0,0 @@
-# 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.12의 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만 발견합니다. 제목과 설명은 모델이 언제 이
-기능을 선택할지 판단할 수 있게 동작과 입력을 구체적으로 씁니다.
-
-Slash Command나 UI extension은 선택적 진입점일 뿐 discovery 조건이 아닙니다. 활성 Plugin의 모든
-`tool`·`skill`은 매 AI turn의 actor-scoped capability catalog에 자동 포함됩니다. 설치·업데이트·
-enable/disable·권한 변경·Connection 생성/수정/삭제·OAuth 완료·삭제 뒤 Host는 Instance route cache를
-즉시 비워 다음 turn과 실행이 새 generation을 사용하게 합니다.
-
-```json
-{
-  "id": "school_life.today",
-  "kind": "tool",
-  "title": "오늘 학교 생활 조회",
-  "description": "연결한 학교의 오늘 시간표, 급식, 학사일정을 조회합니다.",
-  "permissions": ["network", "storage"],
-  "timeout_seconds": 10,
-  "input_schema": {
-    "type": "object",
-    "properties": {"date": {"type": "string"}},
-    "additionalProperties": false
-  },
-  "output_schema": {
-    "type": "object",
-    "properties": {"timetable": {"type": "array", "items": {"type": "object"}}},
-    "required": ["timetable"]
-  },
-  "runtime": {"adapter": "neis_school", "operation": "overview"}
-}
-```
-
-`input_schema`/`output_schema`는 root `object`인 안전한 JSON Schema 부분집합입니다. AI Tool,
-UI data source·invoke, Host 실행과 결과 binding이 같은 schema를 사용합니다. CLI/MCP validate는
-필수 필드·타입·범위와 `data.<source>.data...` 경로를 package build 전에 검사합니다.
-실행 시 schema와 다른 외부 응답은 정상 결과로 변환하지 않고 해당 capability 오류로
-격리합니다.
-
-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·재연결·부분 결과를 선택할 수 있도록 공개 오류를
-구체적으로 유지합니다.
-
-실행 준비 상태의 대표 code는 `EXTENSION_NOT_FOUND`, `EXTENSION_PERMISSION_DENIED`,
-`EXTENSION_CONNECTION_REQUIRED`, `EXTENSION_DISABLED`, `EXTENSION_VERSION_MISMATCH`,
-`EXTENSION_DEPENDENCY_REQUIRED`입니다. 빈 Tool 목록이나 일반 실패 문구로 합치지 마세요.
-
-권한과 알림은 [권한, 설정, 저장소, 알림](permissions-and-data.md)을 참고하세요.

package/assets/docs/troubleshooting.md

@@ -1,121 +0,0 @@
-# 오류 해결
-
-오류를 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에 붙는지 확인합니다.
-- Response UI가 안 보이면 `config.a2ui.version`이 `v0.9`인지, schema가 실제 완료 데이터와 맞는지,
-  response의 data source가 실행 capability를 가리키는지, Instance 권한이 승인됐는지 확인합니다.
-- 빈 데이터·무관한 답변·중복 결과·Tool 실패에서 Response UI가 생기지 않는 것은 정상입니다. AI가
-  catalog 항목을 선택하지 않은 경우에도 서버가 임의 fallback UI를 만들지 않고 텍스트만 남깁니다.
-
-## 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`를 먼저 확인합니다.