@clack-platform/cli 0.3.2 → 0.3.3

package/README.md

@@ -149,7 +149,7 @@ pnpm check          # typecheck → 스키마 동기화 확인 → 테스트 →
 npm pack --dry-run
 ```
 
-`pnpm check`는 나란히 체크아웃한 클랙 모노레포가 있으면(`CLACK_MONOREPO_DIR`, 기본 `../clack`) MCP 입력 스키마 일치도 함께 확인하고, 없으면 건너뛴다. 배포 전 로컬에서 이 확인을 강제하려면 `pnpm check:release`를 쓴다. `scripts/sync-vendor-types.mjs [--check]`는 `src/vendor/` 아래 복사해 둔 클랙 공개 타입·계약 파일을 같은 방식으로 모노레포와 동기화한다.
+`pnpm check`는 나란히 체크아웃한 클랙 모노레포가 있으면(`CLACK_MONOREPO_DIR`, 기본 `../clack`) MCP 입력 스키마 일치도 함께 확인하고, 없으면 건너뛴다. 배포 전 로컬에서 이 확인을 강제하려면 `pnpm check:release`를 쓴다(스키마 일치 엄격 검사와 `src/vendor/` 사본 `sync-vendor-types.mjs --check`를 함께 실행한다). `scripts/sync-vendor-types.mjs [--check]`는 `src/vendor/` 아래 복사해 둔 클랙 공개 타입·계약 파일을 같은 방식으로 모노레포와 동기화한다.
 
 GitHub Actions는 Linux·macOS·Windows × Node 20·22에서 `pnpm check`와 패키지 설치 스모크를 실행한다(`.github/workflows/ci.yml`). 배포는 `v0.1.0` 형태의 버전 태그를 push하면 `.github/workflows/publish.yml`이 태그와 `package.json` 버전 일치를 확인한 뒤 GitHub Actions의 OIDC 신뢰 게시로 npm에 공개한다.
 
@@ -181,11 +181,14 @@ clack content preview --env dev <콘텐츠-UUID> <버전-UUID>
 
 ZIP에 `clack.content.json` 또는 `.clack/`가 있으면 업로드 전에 선언·경로·크기와 프로필 파일 대응을 확인하고 표준 오류에 경고합니다. 선언이 없는 기존 정적 ZIP도 계속 업로드할 수 있습니다. 경고는 업로드를 막지 않으며 서버의 최종 검증·심사 결과를 대신하지 않습니다. 전송 없이 확인하려면 `content upload ... --dry-run`을 사용하세요.
 
-`content update`는 제목·설명·종류·썸네일·메타데이터·태그를 서버 PATCH와 같은 규칙으로 수정합니다(`--title`, `--description`, `--kind`, `--thumbnail-id <썸네일 작업 ID|none>`, `--metadata-mode single|localized`, `--metadata-lang ko|en|none`, `--localized-metadata '<JSON>'|none`, `--tags 쉼표목록`). 지정한 필드만 바뀌고 `--tags`·`--localized-metadata`는 통째 교체됩니다. 단일 메타데이터 모드에서는 제목을 비우면 「제목 없는 콘텐츠」로 표시되고, 언어별(`localized`) 모드에서는 빈 제목을 서버가 거부합니다(400). 썸네일 작업 ID는 `POST /v4/creator/thumbnails` 등으로 발급하며 CLI에는 썸네일 업로드 명령이 없어 보통 `none`(기본 이미지로 되돌리기)만 씁니다. 언어별 메타데이터·태그는 서버 게이트가 켜진 환경에서만 쓸 수 있습니다. 인트로 저장은 개인 액세스 토큰으로 할 수 없어 크리에이터 센터에서만 합니다.
+`content update`는 제목·설명·종류·썸네일·메타데이터·태그를 서버 PATCH와 같은 규칙으로 수정합니다(`--title`, `--description`, `--kind`, `--thumbnail-id <썸네일 작업 ID|none>`, `--metadata-mode single|localized`, `--metadata-lang ko|en|none`, `--localized-metadata '<JSON>'|none`, `--tags 쉼표목록`). 지정한 필드만 바뀌고 `--tags`·`--localized-metadata`는 통째 교체됩니다. 단일 메타데이터 모드에서는 제목을 비우면 「제목 없는 콘텐츠」로 표시되고, 언어별(`localized`) 모드에서는 빈 제목을 서버가 거부합니다(400). CLI 0.3.3부터 `content thumbnail <파일>`로 본인 썸네일 작업 ID를 발급합니다. `--content <콘텐츠-UUID>`를 함께 주면 업로드 후 연결까지 수행합니다. `create`·`update`의 `--thumbnail-file <파일>`도 같은 경로를 사용하며 `--thumbnail-id`와 함께 지정할 수 없습니다. 일반 `clack upload`의 CDN URL은 썸네일 작업 ID가 아닙니다. 서버 `content config`의 `thumbnail_upload` 형식·용량·픽셀 조건을 조회하고 업로드합니다. `--dry-run`은 설정 GET과 로컬 검사만 수행합니다. 연결 실패는 오류의 `recovery.thumbnail_id`와 재연결 명령을 제공하므로 상태를 확인한 뒤 ID를 재사용하고 이미지를 다시 올리지 마세요. 언어별 메타데이터·태그는 서버 게이트가 켜진 환경에서만 쓸 수 있습니다. 인트로 저장은 개인 액세스 토큰으로 할 수 없어 크리에이터 센터에서만 합니다.
 
 `content info-version <콘텐츠-UUID> <버전-UUID>`는 승인·반려된 버전의 번들을 재사용해 바뀐 콘텐츠 정보만 담은 새 초안 버전을 만듭니다(새로 만들면 201, 같은 정보의 미게시 버전(초안·심사 중·승인 미게시)이 있으면 200이며 응답의 `created`로 구분). 새 버전은 앱 확인과 심사를 다시 받아야 합니다. 서버 게이트가 꺼진 환경에서는 `CONTENT_INFO_VERSION_DISABLED`(409)가 반환되며 `clack content config`의 `info_version.enabled`로 확인할 수 있습니다.
 
 ```bash
+clack content thumbnail --env dev ./cover.png --content <콘텐츠-UUID> --json
+clack content update --env dev <콘텐츠-UUID> --thumbnail-file ./cover.webp
+clack content create --env dev --title "내 작품" --policy-version 2026-09-22 --thumbnail-file ./cover.png
 clack content update --env dev <콘텐츠-UUID> --title "새 제목" --tags 여행,사진
 clack content info-version --env dev <콘텐츠-UUID> <버전-UUID>
 ```

package/dist/cli.js

@@ -7,16 +7,18 @@ import { z as z2 } from "zod";
 
 // src/core/errors.ts
 var CliError = class extends Error {
-  constructor(message, code = "VALIDATION_ERROR", status = 400, retryAfter) {
+  constructor(message, code = "VALIDATION_ERROR", status = 400, retryAfter, recovery) {
     super(message);
     this.code = code;
     this.status = status;
     this.retryAfter = retryAfter;
+    this.recovery = recovery;
     this.name = "CliError";
   }
   code;
   status;
   retryAfter;
+  recovery;
   get exitCode() {
     if (this.code === "USER_API_UNAVAILABLE") return 8;
     if (this.status === 401) return 3;
@@ -184,7 +186,7 @@ function redact(value2) {
 // package.json
 var package_default = {
   name: "@clack-platform/cli",
-  version: "0.3.2",
+  version: "0.3.3",
   description: "\uD074\uB799 \uACC4\uC815\uC758 \uC0C1\uD488\xB7\uCF58\uD150\uCE20\xB7\uD504\uB85C\uD544\uC744 \uAD00\uB9AC\uD558\uB294 CLI",
   type: "module",
   bin: {
@@ -223,7 +225,7 @@ var package_default = {
     test: "node scripts/test.mjs",
     build: "tsup src/cli.ts --format esm --target node20 --clean",
     check: "pnpm typecheck && node scripts/check-schema-sync.mjs && pnpm test && pnpm build",
-    "check:release": "pnpm typecheck && node scripts/check-schema-sync.mjs --strict && pnpm test && pnpm build",
+    "check:release": "pnpm typecheck && node scripts/check-schema-sync.mjs --strict && node scripts/sync-vendor-types.mjs --check && pnpm test && pnpm build",
     prepack: "pnpm build"
   },
   dependencies: {
@@ -635,8 +637,8 @@ async function authoringRequest(client, raw, surface = "cli") {
   if (input.action === "tool") return client.request("GET", `${path}/tools/${input.call_id}`);
   if (input.action === "fill-status") return client.request("GET", `${path}/fill/${input.job_id}`);
   if (input.action === "upload") {
-    const stat3 = await lstat2(input.file);
-    if (!stat3.isFile() || stat3.isSymbolicLink() || stat3.size > 4 * 1024 * 1024 || !stat3.size) throw new CliError("\uC774\uBBF8\uC9C0\uB294 \uC77C\uBC18 \uD30C\uC77C\uC774\uBA70 4 MiB \uC774\uD558\uC5EC\uC57C \uD569\uB2C8\uB2E4.");
+    const stat4 = await lstat2(input.file);
+    if (!stat4.isFile() || stat4.isSymbolicLink() || stat4.size > 4 * 1024 * 1024 || !stat4.size) throw new CliError("\uC774\uBBF8\uC9C0\uB294 \uC77C\uBC18 \uD30C\uC77C\uC774\uBA70 4 MiB \uC774\uD558\uC5EC\uC57C \uD569\uB2C8\uB2E4.");
     const bytes2 = await readFile2(input.file);
     const body2 = new FormData();
     body2.append("field", input.field);
@@ -726,8 +728,8 @@ var ConfigStore = class {
   async read(name2) {
     const path = join(this.directory, name2);
     try {
-      const stat3 = await lstat3(path);
-      if (!stat3.isFile() || stat3.isSymbolicLink()) throw new CliError("\uC124\uC815 \uD30C\uC77C\uC740 \uC77C\uBC18 \uD30C\uC77C\uC774\uC5B4\uC57C \uD569\uB2C8\uB2E4.", "CONFIG_UNSAFE");
+      const stat4 = await lstat3(path);
+      if (!stat4.isFile() || stat4.isSymbolicLink()) throw new CliError("\uC124\uC815 \uD30C\uC77C\uC740 \uC77C\uBC18 \uD30C\uC77C\uC774\uC5B4\uC57C \uD569\uB2C8\uB2E4.", "CONFIG_UNSAFE");
       if ((name2 === "credentials.json" || name2 === "device-request.json") && process.platform !== "win32") await chmod(path, 384);
       const body = JSON.parse(await readFile3(path, "utf8"));
       if (!body || typeof body !== "object" || !("profiles" in body) || !body.profiles || typeof body.profiles !== "object" || Array.isArray(body.profiles)) throw new Error("\uD615\uC2DD");
@@ -2045,22 +2047,87 @@ import { Option as Option2 } from "commander";
 
 // src/lib/platform-mcp.ts
 import { createInterface } from "readline";
-import { z as z10 } from "zod";
+import { z as z11 } from "zod";
 
 // src/commands/skill.ts
 import { spawn } from "child_process";
 import { existsSync } from "fs";
 import { writeFile as writeFile2 } from "fs/promises";
 import { createRequire } from "module";
-import { join as join3, resolve as resolve8 } from "path";
-import { z as z9 } from "zod";
+import { join as join3, resolve as resolve9 } from "path";
+import { z as z10 } from "zod";
+
+// src/lib/content-thumbnail.ts
+import { readFile as readFile8, stat as stat2 } from "fs/promises";
+import { basename as basename3, resolve as resolve6 } from "path";
+import { imageSize as imageSize2 } from "image-size";
+import { z as z8 } from "zod";
+var policySchema = z8.object({
+  thumbnail_upload_enabled: z8.boolean(),
+  thumbnail_upload: z8.object({
+    max_upload_bytes: z8.number().int().positive(),
+    max_input_pixels: z8.number().int().positive(),
+    formats: z8.array(z8.enum(["image/png", "image/jpeg", "image/webp"])).min(1)
+  })
+});
+var thumbnailSchema = z8.object({ id: z8.uuid(), status: z8.literal("succeeded"), image_url: z8.url() });
+async function prepareContentThumbnail(ctx, source) {
+  const response = await ctx.api.request("GET", "/v4/creator/config", { auth: false });
+  const result = policySchema.safeParse(response.data);
+  if (!result.success) throw new CliError("\uC11C\uBC84 \uC378\uB124\uC77C \uC5C5\uB85C\uB4DC \uC124\uC815\uC774 \uD544\uC694\uD569\uB2C8\uB2E4. \uC11C\uBC84 \uC5C5\uB370\uC774\uD2B8 \uD6C4 \uB2E4\uC2DC \uC2DC\uB3C4\uD558\uC138\uC694.", "THUMBNAIL_CONFIG_REQUIRED", 409);
+  if (!result.data.thumbnail_upload_enabled) throw new CliError("\uC774 \uD658\uACBD\uC5D0\uC11C\uB294 \uC378\uB124\uC77C \uC5C5\uB85C\uB4DC\uB97C \uC0AC\uC6A9\uD560 \uC218 \uC5C6\uC2B5\uB2C8\uB2E4. content config\uB85C \uAE30\uB2A5 \uC0C1\uD0DC\uB97C \uD655\uC778\uD558\uC138\uC694.", "THUMBNAIL_UPLOAD_DISABLED", 503);
+  const policy = result.data.thumbnail_upload;
+  const path = resolve6(source);
+  const info = await stat2(path).catch(() => {
+    throw new CliError("\uC378\uB124\uC77C \uD30C\uC77C\uC744 \uCC3E\uC744 \uC218 \uC5C6\uC2B5\uB2C8\uB2E4.", "THUMBNAIL_FILE_NOT_FOUND", 400);
+  });
+  if (!info.isFile() || !info.size) throw new CliError("\uBE44\uC5B4 \uC788\uC9C0 \uC54A\uC740 \uB85C\uCEEC \uC774\uBBF8\uC9C0 \uD30C\uC77C\uC744 \uC9C0\uC815\uD558\uC138\uC694.", "THUMBNAIL_EMPTY_FILE", 400);
+  if (info.size > policy.max_upload_bytes) throw new CliError(`\uC378\uB124\uC77C\uC740 ${policy.max_upload_bytes}\uBC14\uC774\uD2B8 \uC774\uD558\uC5EC\uC57C \uD569\uB2C8\uB2E4.`, "THUMBNAIL_TOO_LARGE", 413);
+  const bytes2 = await readFile8(path).catch(() => {
+    throw new CliError("\uC378\uB124\uC77C \uD30C\uC77C\uC744 \uC77D\uC744 \uAD8C\uD55C\uC774 \uD544\uC694\uD569\uB2C8\uB2E4.", "THUMBNAIL_FILE_UNREADABLE", 400);
+  });
+  if (!bytes2.length || bytes2.length > policy.max_upload_bytes) throw new CliError("\uC77D\uB294 \uB3D9\uC548 \uC378\uB124\uC77C \uD06C\uAE30\uAC00 \uBC14\uB00C\uC5C8\uC2B5\uB2C8\uB2E4. \uD30C\uC77C\uC744 \uB2E4\uC2DC \uD655\uC778\uD558\uC138\uC694.", "THUMBNAIL_TOO_LARGE", 413);
+  let mime;
+  try {
+    const image2 = imageSize2(bytes2);
+    mime = { png: "image/png", jpg: "image/jpeg", webp: "image/webp" }[image2.type ?? ""] ?? "";
+    if (!policy.formats.includes(mime) || !image2.width || !image2.height || image2.width * image2.height > policy.max_input_pixels) throw new Error();
+  } catch {
+    throw new CliError("\uC11C\uBC84\uAC00 \uC9C0\uC6D0\uD558\uB294 PNG\xB7JPEG\xB7WebP \uC774\uBBF8\uC9C0\uC640 \uC720\uD6A8\uD55C \uD06C\uAE30\uAC00 \uD544\uC694\uD569\uB2C8\uB2E4. \uC190\uC0C1\uB41C \uD30C\uC77C\uC740 \uB2E4\uC2DC \uC800\uC7A5\uD558\uC138\uC694.", "THUMBNAIL_INVALID_IMAGE", 422);
+  }
+  return { path, bytes: bytes2, mime };
+}
+async function uploadContentThumbnail(ctx, image2) {
+  const body = new FormData();
+  body.append("file", new Blob([new Uint8Array(image2.bytes)], { type: image2.mime }), basename3(image2.path));
+  const response = await ctx.api.request("POST", "/v4/creator/thumbnails", { body });
+  const parsed = thumbnailSchema.safeParse(response.data);
+  if (!parsed.success) throw new CliError("\uC644\uB8CC\uB41C \uC378\uB124\uC77C \uC791\uC5C5 ID\uB97C \uC751\uB2F5\uC5D0\uC11C \uD655\uC778\uD560 \uC218 \uC5C6\uC2B5\uB2C8\uB2E4. \uC790\uB3D9 \uC7AC\uC5C5\uB85C\uB4DC\uD558\uC9C0 \uB9C8\uC138\uC694.", "INVALID_RESPONSE", 502);
+  return { data: parsed.data, time_contract: response.time_contract };
+}
+function thumbnailLinkFailure(ctx, cause, thumbnailId, contentId, creation) {
+  const failure = asCliError(cause);
+  const quote = (value2) => `'${value2.replaceAll("'", "'\\''")}'`;
+  const prefix = `clack --base-url ${quote(ctx.api.settings.baseUrl)}${ctx.options.profile ? ` --profile ${quote(ctx.options.profile)}` : ""}`;
+  const createArgs = ["title", "description", "kind", "policy_version"].flatMap((key) => creation?.[key] === void 0 ? [] : [`--${key.replaceAll("_", "-")} ${quote(String(creation[key]))}`]).join(" ");
+  const command = contentId ? `${prefix} content update ${contentId} --thumbnail-id ${thumbnailId}` : `${prefix} content create ${createArgs} --thumbnail-id ${thumbnailId}`;
+  const verify = contentId ? `${prefix} content status ${contentId}` : `${prefix} content list`;
+  return new CliError(
+    `${failure.message}
+\uC378\uB124\uC77C \uC5C5\uB85C\uB4DC\uB294 \uC644\uB8CC\uB410\uC2B5\uB2C8\uB2E4 (ID: ${thumbnailId}). ${verify}\uB85C \uC800\uC7A5 \uC5EC\uBD80\uB97C \uD655\uC778\uD55C \uB4A4 ${command}\uB85C \uC5F0\uACB0\uD558\uC138\uC694.`,
+    failure.code,
+    failure.status,
+    failure.retryAfter,
+    { thumbnail_id: thumbnailId, ...contentId ? { content_id: contentId } : {}, verification_command: verify, retry_command: command }
+  );
+}
 
 // src/commands/content.ts
 import { createHash as createHash2 } from "crypto";
-import { readFile as readFile8, stat as stat2 } from "fs/promises";
-import { basename as basename3, extname, resolve as resolve6 } from "path";
+import { readFile as readFile9, stat as stat3 } from "fs/promises";
+import { basename as basename4, extname, resolve as resolve7 } from "path";
 import { Option } from "commander";
-import { z as z8 } from "zod";
+import { z as z9 } from "zod";
 
 // src/lib/content-package.ts
 import { unzipSync } from "fflate";
@@ -2192,28 +2259,29 @@ function inspectContentPackage(bytes2) {
 
 // src/commands/content.ts
 var MAX_BYTES = 30 * 1024 * 1024;
-var uuid = (value2) => parse(z8.uuid(), value2);
-var createSchema = z8.object({
-  title: z8.string().trim().min(1).max(120),
-  description: z8.string().trim().max(2e3).default(""),
-  kind: z8.enum(["html", "gallery", "slideshow", "video"]).default("html"),
-  policy_version: z8.literal("2026-09-22")
+var uuid = (value2) => parse(z9.uuid(), value2);
+var createSchema = z9.object({
+  title: z9.string().trim().min(1).max(120),
+  description: z9.string().trim().max(2e3).default(""),
+  kind: z9.enum(["html", "gallery", "slideshow", "video"]).default("html"),
+  policy_version: z9.literal("2026-09-22"),
+  thumbnail_id: z9.uuid().nullable().optional()
 }).strict();
 var METADATA_LANGS = ["ko", "en"];
 var TAG_PATTERN = /^[\p{L}\p{M}\p{N}_]{1,30}$/u;
-var localizedEntry = z8.object({
-  title: z8.string().trim().max(120),
-  description: z8.string().trim().max(2e3).optional()
+var localizedEntry = z9.object({
+  title: z9.string().trim().max(120),
+  description: z9.string().trim().max(2e3).optional()
 }).strict();
-var updateSchema = z8.object({
-  title: z8.string().trim().max(120).optional(),
-  description: z8.string().trim().max(2e3).optional(),
-  kind: z8.enum(["html", "gallery", "slideshow", "video"]).optional(),
-  thumbnail_id: z8.uuid().nullable().optional(),
-  metadata_mode: z8.enum(["single", "localized"]).optional(),
-  metadata_lang: z8.enum(METADATA_LANGS).nullable().optional(),
-  localized_metadata: z8.partialRecord(z8.enum(METADATA_LANGS), localizedEntry).nullable().optional(),
-  tags: z8.array(z8.string().max(64)).max(50).optional()
+var updateSchema = z9.object({
+  title: z9.string().trim().max(120).optional(),
+  description: z9.string().trim().max(2e3).optional(),
+  kind: z9.enum(["html", "gallery", "slideshow", "video"]).optional(),
+  thumbnail_id: z9.uuid().nullable().optional(),
+  metadata_mode: z9.enum(["single", "localized"]).optional(),
+  metadata_lang: z9.enum(METADATA_LANGS).nullable().optional(),
+  localized_metadata: z9.partialRecord(z9.enum(METADATA_LANGS), localizedEntry).nullable().optional(),
+  tags: z9.array(z9.string().max(64)).max(50).optional()
 }).strict().superRefine((value2, ctx) => {
   const issue = (message) => ctx.addIssue({ code: "custom", message });
   if (!Object.values(value2).some((entry) => entry !== void 0)) issue("\uBCC0\uACBD\uD560 \uD544\uB4DC\uB97C \uD558\uB098 \uC774\uC0C1 \uC9C0\uC815\uD558\uC138\uC694.");
@@ -2249,14 +2317,14 @@ function jsonOption(name2, value2) {
   }
 }
 async function prepareContentFile(source) {
-  const file = resolve6(source);
+  const file = resolve7(source);
   const extension = extname(file).toLowerCase();
   if (![".html", ".htm", ".zip"].includes(extension)) throw new CliError("HTML \uB610\uB294 ZIP \uD30C\uC77C\uC744 \uC9C0\uC815\uD558\uC138\uC694.");
   let bytes2;
   try {
-    const info = await stat2(file);
+    const info = await stat3(file);
     if (!info.isFile() || info.size === 0 || info.size > MAX_BYTES) throw new Error();
-    bytes2 = await readFile8(file);
+    bytes2 = await readFile9(file);
     if (!bytes2.length || bytes2.length > MAX_BYTES) throw new Error();
   } catch {
     throw new CliError("30 MiB \uC774\uD558\uC758 \uBE44\uC5B4 \uC788\uC9C0 \uC54A\uC740 \uD30C\uC77C\uC744 \uC77D\uC744 \uC218 \uC788\uC5B4\uC57C \uD569\uB2C8\uB2E4.");
@@ -2265,7 +2333,7 @@ async function prepareContentFile(source) {
     bytes: bytes2,
     warnings: extension === ".zip" ? inspectContentPackage(bytes2) : [],
     metadata: {
-      filename: basename3(file),
+      filename: basename4(file),
       content_type: extension === ".zip" ? "application/zip" : "text/html",
       byte_size: bytes2.length,
       sha256: createHash2("sha256").update(bytes2).digest("hex")
@@ -2300,8 +2368,25 @@ async function putContentFile(session2, bytes2, fetcher = fetch) {
     throw new CliError("\uD30C\uC77C \uC5C5\uB85C\uB4DC\uC5D0 \uC2E4\uD328\uD588\uC2B5\uB2C8\uB2E4. \uC0C8 \uC5C5\uB85C\uB4DC\uB97C \uC2DC\uC791\uD558\uC138\uC694.", "CONTENT_UPLOAD_FAILED", 0);
   }
 }
+async function saveWithThumbnail(ctx, method, path, body, file, contentId) {
+  if (!file) {
+    await mutate(ctx, method, path, body);
+    return;
+  }
+  const image2 = await prepareContentThumbnail(ctx, file);
+  if (ctx.options.dryRun) {
+    ctx.output({ dry_run: true, method, path, body: { ...body, thumbnail_id: "<\uC5C5\uB85C\uB4DC \uD6C4 \uBC1C\uAE09>" }, thumbnail: { file: image2.path, byte_size: image2.bytes.length } });
+    return;
+  }
+  const uploaded = await uploadContentThumbnail(ctx, image2);
+  try {
+    ctx.output(await ctx.api.request(method, path, { body: { ...body, thumbnail_id: uploaded.data.id } }));
+  } catch (failure) {
+    throw thumbnailLinkFailure(ctx, failure, uploaded.data.id, contentId, method === "POST" ? body : void 0);
+  }
+}
 var SERVER_KEY_CENTER_ONLY = "\uC11C\uBC84 \uD0A4 \uBC1C\uAE09\xB7\uD68C\uC804\uC740 \uD06C\uB9AC\uC5D0\uC774\uD130 \uC13C\uD130(\uB0B4 \uCF58\uD150\uCE20 \u2192 \uC11C\uBC84 \uD0A4)\uC5D0\uC11C\uB9CC \uD560 \uC218 \uC788\uC2B5\uB2C8\uB2E4. CLI\xB7MCP\uC758 \uAC1C\uC778 \uC561\uC138\uC2A4 \uD1A0\uD070\uC73C\uB85C\uB294 \uC11C\uBC84 \uD0A4 \uC870\uD68C\xB7\uD3D0\uAE30\uB9CC \uD560 \uC218 \uC788\uC2B5\uB2C8\uB2E4.";
-var collection = z8.string().regex(/^[A-Za-z0-9_-]{1,64}$/, "\uC774\uB984\uC740 \uC601\uC22B\uC790\xB7\uBC11\uC904\xB7\uBD99\uC784\uD45C 64\uC790 \uC774\uD558\uC5EC\uC57C \uD569\uB2C8\uB2E4.");
+var collection = z9.string().regex(/^[A-Za-z0-9_-]{1,64}$/, "\uC774\uB984\uC740 \uC601\uC22B\uC790\xB7\uBC11\uC904\xB7\uBD99\uC784\uD45C 64\uC790 \uC774\uD558\uC5EC\uC57C \uD569\uB2C8\uB2E4.");
 var documentKey = collection;
 var keyId = (value2) => {
   const id2 = String(value2);
@@ -2313,22 +2398,41 @@ function registerContentCommands(program2, runtime2) {
   runtime2.action(content.command("config").description("\uCF58\uD150\uCE20 \uAE30\uB2A5 \uC81C\uACF5 \uC5EC\uBD80\xB7\uC124\uC815 \uC870\uD68C (\uB85C\uADF8\uC778 \uBD88\uD544\uC694)"), async (ctx) => ctx.output(await ctx.api.request("GET", "/v4/creator/config", { auth: false })));
   runtime2.action(content.command("list").description("\uB0B4 \uCF58\uD150\uCE20 \uBAA9\uB85D (creator-content:read)"), async (ctx) => ctx.output(await ctx.api.request("GET", "/v4/creator/contents")));
   runtime2.action(content.command("status <id>").description("\uCF58\uD150\uCE20\uC640 \uBC84\uC804\uBCC4 \uC5C5\uB85C\uB4DC\xB7\uC2EC\uC0AC\xB7\uACF5\uAC1C \uC0C1\uD0DC (creator-content:read)"), async (ctx, [id2]) => ctx.output(await ctx.api.request("GET", `/v4/creator/contents/${uuid(id2)}`)));
-  runtime2.action(content.command("create").description("\uCF58\uD150\uCE20 \uCD08\uC548 \uB4F1\uB85D (creator-content:write)").requiredOption("--title <text>", "\uC81C\uBAA9").option("--description <text>", "\uC124\uBA85", "").option("--kind <kind>", "html|gallery|slideshow|video", "html").requiredOption("--policy-version <version>", "\uB3D9\uC758\uD55C \uCF58\uD150\uCE20 \uC81C\uACF5 \uC815\uCC45 \uBC84\uC804"), async (ctx, _args, opts) => {
-    const body = parse(createSchema, { title: opts.title, description: opts.description, kind: opts.kind, policy_version: opts.policyVersion });
-    await mutate(ctx, "POST", "/v4/creator/contents", body);
+  runtime2.action(content.command("create").description("\uCF58\uD150\uCE20 \uCD08\uC548 \uB4F1\uB85D (creator-content:write)").requiredOption("--title <text>", "\uC81C\uBAA9").option("--description <text>", "\uC124\uBA85", "").option("--kind <kind>", "html|gallery|slideshow|video", "html").requiredOption("--policy-version <version>", "\uB3D9\uC758\uD55C \uCF58\uD150\uCE20 \uC81C\uACF5 \uC815\uCC45 \uBC84\uC804").addOption(new Option("--thumbnail-file <file>", "\uB85C\uCEEC \uC378\uB124\uC77C \uC774\uBBF8\uC9C0 \uC5C5\uB85C\uB4DC \uD6C4 \uC5F0\uACB0").conflicts("thumbnailId")).addOption(new Option("--thumbnail-id <uuid|none>", "\uBC1C\uAE09\uBC1B\uC740 \uC378\uB124\uC77C ID \uB610\uB294 \uAE30\uBCF8 \uC774\uBBF8\uC9C0").conflicts("thumbnailFile")), async (ctx, _args, opts) => {
+    const body = parse(createSchema, { title: opts.title, description: opts.description, kind: opts.kind, policy_version: opts.policyVersion, thumbnail_id: opts.thumbnailId === void 0 ? void 0 : opts.thumbnailId === "none" ? null : opts.thumbnailId });
+    await saveWithThumbnail(ctx, "POST", "/v4/creator/contents", body, opts.thumbnailFile);
   });
-  runtime2.action(content.command("update <id>").description("\uCF58\uD150\uCE20 \uC815\uBCF4(\uC81C\uBAA9\xB7\uC124\uBA85\xB7\uC885\uB958\xB7\uC378\uB124\uC77C\xB7\uBA54\uD0C0\uB370\uC774\uD130\xB7\uD0DC\uADF8) \uC218\uC815 (creator-content:write)").option("--title <text>", "\uC81C\uBAA9 (120\uC790 \uC774\uD558, \uBE48 \uAC12\uC774\uBA74 \uC81C\uBAA9 \uC5C6\uC74C)").option("--description <text>", "\uC124\uBA85 (2000\uC790 \uC774\uD558)").addOption(new Option("--kind <kind>", "\uCF58\uD150\uCE20 \uC885\uB958").choices(["html", "gallery", "slideshow", "video"])).option("--thumbnail-id <uuid|none>", "\uC378\uB124\uC77C \uC791\uC5C5 ID, none\uC774\uBA74 \uAE30\uBCF8 \uC774\uBBF8\uC9C0\uB85C \uB418\uB3CC\uB9BC").addOption(new Option("--metadata-mode <mode>", "\uBA54\uD0C0\uB370\uC774\uD130 \uC785\uB825 \uBC29\uC2DD").choices(["single", "localized"])).option("--metadata-lang <ko|en|none>", "\uB300\uD45C \uC5B8\uC5B4").option("--localized-metadata <json|none>", `\uB300\uD45C \uC5B8\uC5B4 \uC678 \uC5B8\uC5B4\uBCC4 \uC81C\uBAA9\xB7\uC124\uBA85 JSON, \uC608: '{"en":{"title":"Title","description":"About"}}'`).option("--tags <list>", "\uD574\uC2DC\uD0DC\uADF8\uB97C \uC27C\uD45C\uB85C \uAD6C\uBD84\uD574 \uD1B5\uC9F8 \uAD50\uCCB4, \uBE48 \uBB38\uC790\uC5F4\uC774\uBA74 \uBAA8\uB450 \uC0AD\uC81C"), async (ctx, [id2], opts) => {
+  runtime2.action(content.command("update <id>").description("\uCF58\uD150\uCE20 \uC815\uBCF4(\uC81C\uBAA9\xB7\uC124\uBA85\xB7\uC885\uB958\xB7\uC378\uB124\uC77C\xB7\uBA54\uD0C0\uB370\uC774\uD130\xB7\uD0DC\uADF8) \uC218\uC815 (creator-content:write)").option("--title <text>", "\uC81C\uBAA9 (120\uC790 \uC774\uD558, \uBE48 \uAC12\uC774\uBA74 \uC81C\uBAA9 \uC5C6\uC74C)").option("--description <text>", "\uC124\uBA85 (2000\uC790 \uC774\uD558)").addOption(new Option("--kind <kind>", "\uCF58\uD150\uCE20 \uC885\uB958").choices(["html", "gallery", "slideshow", "video"])).addOption(new Option("--thumbnail-id <uuid|none>", "\uC378\uB124\uC77C \uC791\uC5C5 ID, none\uC774\uBA74 \uAE30\uBCF8 \uC774\uBBF8\uC9C0\uB85C \uB418\uB3CC\uB9BC").conflicts("thumbnailFile")).addOption(new Option("--thumbnail-file <file>", "\uB85C\uCEEC \uC378\uB124\uC77C \uC774\uBBF8\uC9C0 \uC5C5\uB85C\uB4DC \uD6C4 \uC5F0\uACB0").conflicts("thumbnailId")).addOption(new Option("--metadata-mode <mode>", "\uBA54\uD0C0\uB370\uC774\uD130 \uC785\uB825 \uBC29\uC2DD").choices(["single", "localized"])).option("--metadata-lang <ko|en|none>", "\uB300\uD45C \uC5B8\uC5B4").option("--localized-metadata <json|none>", `\uB300\uD45C \uC5B8\uC5B4 \uC678 \uC5B8\uC5B4\uBCC4 \uC81C\uBAA9\xB7\uC124\uBA85 JSON, \uC608: '{"en":{"title":"Title","description":"About"}}'`).option("--tags <list>", "\uD574\uC2DC\uD0DC\uADF8\uB97C \uC27C\uD45C\uB85C \uAD6C\uBD84\uD574 \uD1B5\uC9F8 \uAD50\uCCB4, \uBE48 \uBB38\uC790\uC5F4\uC774\uBA74 \uBAA8\uB450 \uC0AD\uC81C"), async (ctx, [id2], opts) => {
     const body = parse(updateSchema, {
       title: opts.title,
       description: opts.description,
       kind: opts.kind,
-      thumbnail_id: opts.thumbnailId === void 0 ? void 0 : opts.thumbnailId === "none" ? null : opts.thumbnailId,
+      thumbnail_id: opts.thumbnailFile ? null : opts.thumbnailId === void 0 ? void 0 : opts.thumbnailId === "none" ? null : opts.thumbnailId,
       metadata_mode: opts.metadataMode,
       metadata_lang: opts.metadataLang === void 0 ? void 0 : opts.metadataLang === "none" ? null : opts.metadataLang,
       localized_metadata: opts.localizedMetadata === void 0 ? void 0 : jsonOption("--localized-metadata", opts.localizedMetadata),
       tags: opts.tags === void 0 ? void 0 : csv(opts.tags)
     });
-    await mutate(ctx, "PATCH", `/v4/creator/contents/${uuid(id2)}`, body);
+    await saveWithThumbnail(ctx, "PATCH", `/v4/creator/contents/${uuid(id2)}`, body, opts.thumbnailFile, uuid(id2));
+  });
+  runtime2.action(content.command("thumbnail <file>").description("\uB85C\uCEEC \uC378\uB124\uC77C \uC5C5\uB85C\uB4DC\uC640 \uC120\uD0DD\uC801 \uCF58\uD150\uCE20 \uC5F0\uACB0 (creator-content:write)").option("--content <uuid>", "\uC5C5\uB85C\uB4DC \uD6C4 \uC774 \uCF58\uD150\uCE20\uC5D0 \uC5F0\uACB0"), async (ctx, [file], opts) => {
+    const contentId = opts.content === void 0 ? void 0 : uuid(opts.content);
+    const image2 = await prepareContentThumbnail(ctx, file);
+    if (ctx.options.dryRun) {
+      ctx.output({ dry_run: true, path: "/v4/creator/thumbnails", file: image2.path, byte_size: image2.bytes.length, ...contentId ? { content_id: contentId } : {} });
+      return;
+    }
+    const uploaded = await uploadContentThumbnail(ctx, image2);
+    if (!contentId) {
+      ctx.output(uploaded);
+      return;
+    }
+    try {
+      const result = await ctx.api.request("PATCH", `/v4/creator/contents/${contentId}`, { body: { thumbnail_id: uploaded.data.id } });
+      ctx.output({ ...result, thumbnail: uploaded.data });
+    } catch (failure) {
+      throw thumbnailLinkFailure(ctx, failure, uploaded.data.id, contentId);
+    }
   });
   runtime2.action(content.command("upload <id> <file>").description("HTML/ZIP \uC5C5\uB85C\uB4DC\uB85C \uC0C8 \uBE44\uACF5\uAC1C \uBC84\uC804 \uC0DD\uC131 (creator-content:write)").addOption(new Option("--header <mode>", "\uD5E4\uB354 \uD45C\uC2DC").choices(["fixed", "scroll_hide", "translucent_scroll_hide", "floating_close", "floating_close_safe_area"])).addOption(new Option("--color <scheme>", "\uD5E4\uB354 \uC0C9\uC0C1").choices(["light", "dark"])), async (ctx, [id2, file], opts) => {
     const path = `/v4/creator/contents/${uuid(id2)}`;
@@ -2434,15 +2538,52 @@ function dataRootField(schema, name2) {
   }
   return field2;
 }
-function inspectEditorSemantics(skill, data, fail2) {
+var SEMANTICS_NOTES = {
+  // 스킬 에디터 선언
+  editor_document_permissions: () => "\uC5D0\uB514\uD130\uC5D0\uB294 document.read\uC640 document.write \uAD8C\uD55C\uC774 \uBAA8\uB450 \uD544\uC694\uD569\uB2C8\uB2E4.",
+  ai_suggest_needs_ai_fill: () => "ai.suggest \uAD8C\uD55C\uC5D0\uB294 authoring.ai_fill.enabled\uAC00 \uD544\uC694\uD569\uB2C8\uB2E4.",
+  image_permission_needs_tool: () => "tools.image.generate \uAD8C\uD55C\uC5D0\uB294 authoring.tools\uC758 image.generate \uC120\uC5B8\uC774 \uD544\uC694\uD569\uB2C8\uB2E4.",
+  editor_slot_aspect: () => "\uC5D0\uB514\uD130 \uC2A4\uD0AC\uC740 \uC2AC\uB86F \uBE44\uC728(aspect: slot)\uC744 \uC4F8 \uC218 \uC5C6\uC2B5\uB2C8\uB2E4. \uC790\uC0B0 \uB178\uB4DC\uC758 x-clack-asset.aspect\uB97C \uC4F0\uC138\uC694.",
+  asset_limits_missing: () => "\uC790\uC0B0 \uB178\uB4DC\uAC00 \uC788\uB294 \uB370\uC774\uD130 \uC2A4\uD0A4\uB9C8\uC5D0\uB294 output.data.assets \uD55C\uB3C4\uAC00 \uD544\uC694\uD569\uB2C8\uB2E4.",
+  asset_limits_unused: () => "\uC790\uC0B0 \uB178\uB4DC\uAC00 \uC5C6\uB294\uB370 \uC790\uC0B0 \uD55C\uB3C4\uB97C \uC120\uC5B8\uD588\uC2B5\uB2C8\uB2E4.",
+  image_permission_no_asset: () => "\uC774\uBBF8\uC9C0\uB97C \uB123\uC744 \uC790\uC0B0 \uB178\uB4DC\uAC00 \uC5C6\uC2B5\uB2C8\uB2E4.",
+  ai_suggest_no_node: () => "x-clack-ai.suggest\uAC00 \uCF1C\uC9C4 \uB178\uB4DC\uAC00 \uC5C6\uC2B5\uB2C8\uB2E4.",
+  metadata_text_key: () => "\uACF5\uAC1C \uBB38\uC790\uC5F4 \uB8E8\uD2B8 \uD0A4\uB97C \uAC00\uB9AC\uCF1C\uC57C \uD569\uB2C8\uB2E4.",
+  metadata_asset_key: () => "\uACF5\uAC1C \uC790\uC0B0 \uB8E8\uD2B8 \uD0A4\uB97C \uAC00\uB9AC\uCF1C\uC57C \uD569\uB2C8\uB2E4(\uC778\uB371\uC2A4 \uD45C\uAE30 \uBD88\uAC00).",
+  // 콘텐츠 인트로
+  intro_image_not_slot: () => "\uC778\uD2B8\uB85C \uC774\uBBF8\uC9C0\uB294 output.asset_slots\uC758 \uD544\uB4DC\uB9CC \uC4F8 \uC218 \uC788\uC2B5\uB2C8\uB2E4.",
+  intro_images_over: ({ max }) => `\uC778\uD2B8\uB85C \uC774\uBBF8\uC9C0\uB294 \uC2AC\uB86F \uCD5C\uB300 \uC7A5\uC218 \uD569\uACC4\uAC00 ${max}\uC7A5 \uC774\uD558\uC5EC\uC57C \uD569\uB2C8\uB2E4.`,
+  intro_text_field: () => "\uACF5\uAC1C \uBB38\uC790\uC5F4(text\xB7textarea) \uD3FC \uD544\uB4DC\uB97C \uAC00\uB9AC\uCF1C\uC57C \uD569\uB2C8\uB2E4.",
+  intro_text_too_long: ({ max }) => `\uAC00\uB9AC\uD0A4\uB294 \uD3FC \uD544\uB4DC\uC758 \uCD5C\uB300 \uAE38\uC774\uAC00 ${max}\uC790 \uC774\uD558\uC5EC\uC57C \uD569\uB2C8\uB2E4.`,
+  intro_section_field: () => "\uC18C\uAC1C \uC139\uC158\uC740 \uACF5\uAC1C \uBB38\uC790\uC5F4(text\xB7textarea) \uD3FC \uD544\uB4DC\uB9CC \uAC00\uB9AC\uD0AC \uC218 \uC788\uC2B5\uB2C8\uB2E4.",
+  intro_section_too_long: () => "\uC18C\uAC1C \uC139\uC158\uC758 \uCD5C\uB300 \uAE38\uC774\uB294 2,000\uC790\uC785\uB2C8\uB2E4.",
+  intro_sections_total: () => "\uC18C\uAC1C \uC139\uC158\uC758 \uCD5C\uB300 \uAE38\uC774 \uD569\uACC4\uB294 6,000\uC790\uC785\uB2C8\uB2E4.",
+  intro_fallback_field: () => "\uBB38\uC790\uC5F4(text\xB7textarea) \uD3FC \uD544\uB4DC\uB9CC \uC790\uB3D9 \uAD6C\uC131\uC5D0 \uC4F8 \uC218 \uC788\uC2B5\uB2C8\uB2E4.",
+  intro_fallback_too_long: ({ max }) => `\uC790\uB3D9 \uAD6C\uC131 \uCD5C\uB300 \uAE38\uC774(\uB77C\uBCA8 \uD3EC\uD568)\uAC00 ${max}\uC790\uB97C \uB118\uC2B5\uB2C8\uB2E4.`,
+  // 도구·이미지 슬롯
+  tool_duplicate: () => "\uB3C4\uAD6C \uC774\uB984\uC744 \uC911\uBCF5 \uC120\uC5B8\uD560 \uC218 \uC5C6\uC2B5\uB2C8\uB2E4.",
+  tool_batch_over_calls: () => "\uC77C\uAD04 \uC0DD\uC131 \uC218\uB294 \uC138\uC158 \uD638\uCD9C \uC218\uB97C \uB118\uC744 \uC218 \uC5C6\uC2B5\uB2C8\uB2E4.",
+  slot_field_duplicate: () => "\uC2AC\uB86F \uD544\uB4DC\uB294 \uC911\uBCF5\uD560 \uC218 \uC5C6\uC2B5\uB2C8\uB2E4.",
+  slot_multiple_range: () => "\uB2E4\uC911 \uC2AC\uB86F \uCD5C\uC18C \uC218\uB294 \uCD5C\uB300 \uC218\uBCF4\uB2E4 \uD074 \uC218 \uC5C6\uC2B5\uB2C8\uB2E4.",
+  slot_path_duplicate: () => "\uC2AC\uB86F \uD30C\uC77C \uACBD\uB85C\uB294 \uC911\uBCF5\uD560 \uC218 \uC5C6\uC2B5\uB2C8\uB2E4.",
+  slot_widget_mismatch: () => "\uC2AC\uB86F\uACFC \uC774\uBBF8\uC9C0 \uC704\uC82F \uC885\uB958\uAC00 \uC77C\uCE58\uD574\uC57C \uD569\uB2C8\uB2E4.",
+  // 폼 필드 참조
+  form_field_missing: () => "\uC120\uC5B8\uD55C \uD3FC \uD544\uB4DC\uAC00 \uC5C6\uC2B5\uB2C8\uB2E4.",
+  slot_index_invalid: () => "\uB2E4\uC911 \uC774\uBBF8\uC9C0 \uC2AC\uB86F\uC758 \uC720\uD6A8\uD55C \uC778\uB371\uC2A4\uAC00 \uD544\uC694\uD569\uB2C8\uB2E4.",
+  content_ref_declaration: () => "content_ref\uC5D0\uB294 \uBB38\uC790\uC5F4\uACFC x-clack-source \uC120\uC5B8\uC774 \uD544\uC694\uD569\uB2C8\uB2E4.",
+  content_ref_import_chain: () => "\uB2E4\uB978 content_ref \uD544\uB4DC\uB85C \uAC00\uC838\uC62C \uC218 \uC5C6\uC2B5\uB2C8\uB2E4.",
+  source_without_content_ref: () => "x-clack-source\uB294 content_ref\uC5D0\uB9CC \uC120\uC5B8\uD569\uB2C8\uB2E4.",
+  image_list_declaration: () => "image_list\uC5D0\uB294 \uAC1D\uCCB4 \uBC30\uC5F4\uACFC \uC790\uC0B0 \uC120\uC5B8\uC774 \uD544\uC694\uD569\uB2C8\uB2E4."
+};
+function inspectEditorSemantics(skill, data, fail) {
   const editor = skill.authoring?.editor;
   if (!editor) return;
   const permissions = new Set(editor.permissions ?? []);
-  if (!permissions.has("document.read") || !permissions.has("document.write")) fail2("/authoring/editor/permissions", "\uC5D0\uB514\uD130\uC5D0\uB294 document.read\uC640 document.write \uAD8C\uD55C\uC774 \uBAA8\uB450 \uD544\uC694\uD569\uB2C8\uB2E4.");
-  if (permissions.has("ai.suggest") && skill.authoring?.ai_fill?.enabled !== true) fail2("/authoring/editor/permissions", "ai.suggest \uAD8C\uD55C\uC5D0\uB294 authoring.ai_fill.enabled\uAC00 \uD544\uC694\uD569\uB2C8\uB2E4.");
+  if (!permissions.has("document.read") || !permissions.has("document.write")) fail("/authoring/editor/permissions", "editor_document_permissions");
+  if (permissions.has("ai.suggest") && skill.authoring?.ai_fill?.enabled !== true) fail("/authoring/editor/permissions", "ai_suggest_needs_ai_fill");
   const imageTool = (skill.authoring?.tools ?? []).find((tool) => tool.tool === "image.generate");
-  if (permissions.has("tools.image.generate") && !imageTool) fail2("/authoring/editor/permissions", "tools.image.generate \uAD8C\uD55C\uC5D0\uB294 authoring.tools\uC758 image.generate \uC120\uC5B8\uC774 \uD544\uC694\uD569\uB2C8\uB2E4.");
-  if (imageTool?.aspect === "slot") fail2("/authoring/tools", "\uC5D0\uB514\uD130 \uC2A4\uD0AC\uC740 \uC2AC\uB86F \uBE44\uC728(aspect: slot)\uC744 \uC4F8 \uC218 \uC5C6\uC2B5\uB2C8\uB2E4. \uC790\uC0B0 \uB178\uB4DC\uC758 x-clack-asset.aspect\uB97C \uC4F0\uC138\uC694.");
+  if (permissions.has("tools.image.generate") && !imageTool) fail("/authoring/editor/permissions", "image_permission_needs_tool");
+  if (imageTool?.aspect === "slot") fail("/authoring/tools", "editor_slot_aspect");
   if (!data) return;
   let assets = 0;
   let suggest = 0;
@@ -2450,20 +2591,20 @@ function inspectEditorSemantics(skill, data, fail2) {
     if (node["x-clack-asset"]) assets++;
     if (node["x-clack-ai"]?.suggest === true) suggest++;
   });
-  if (assets > 0 && !skill.output?.data?.assets) fail2("/output/data/assets", "\uC790\uC0B0 \uB178\uB4DC\uAC00 \uC788\uB294 \uB370\uC774\uD130 \uC2A4\uD0A4\uB9C8\uC5D0\uB294 output.data.assets \uD55C\uB3C4\uAC00 \uD544\uC694\uD569\uB2C8\uB2E4.");
-  if (assets === 0 && skill.output?.data?.assets) fail2("/output/data/assets", "\uC790\uC0B0 \uB178\uB4DC\uAC00 \uC5C6\uB294\uB370 \uC790\uC0B0 \uD55C\uB3C4\uB97C \uC120\uC5B8\uD588\uC2B5\uB2C8\uB2E4.");
-  if (assets === 0 && permissions.has("tools.image.generate")) fail2("/authoring/editor/permissions", "\uC774\uBBF8\uC9C0\uB97C \uB123\uC744 \uC790\uC0B0 \uB178\uB4DC\uAC00 \uC5C6\uC2B5\uB2C8\uB2E4.");
-  if (suggest === 0 && permissions.has("ai.suggest")) fail2("/authoring/editor/permissions", "x-clack-ai.suggest\uAC00 \uCF1C\uC9C4 \uB178\uB4DC\uAC00 \uC5C6\uC2B5\uB2C8\uB2E4.");
+  if (assets > 0 && !skill.output?.data?.assets) fail("/output/data/assets", "asset_limits_missing");
+  if (assets === 0 && skill.output?.data?.assets) fail("/output/data/assets", "asset_limits_unused");
+  if (assets === 0 && permissions.has("tools.image.generate")) fail("/authoring/editor/permissions", "image_permission_no_asset");
+  if (suggest === 0 && permissions.has("ai.suggest")) fail("/authoring/editor/permissions", "ai_suggest_no_node");
   const metadata = skill.output?.metadata ?? {};
   for (const key of ["title", "description"]) {
     if (metadata[key] === void 0) continue;
     const field2 = dataRootField(data, metadata[key]);
-    if (!field2 || field2.type !== "string" || field2["x-clack-asset"] || field2["x-clack-visibility"] !== "public") fail2(`/output/metadata/${key}`, "\uACF5\uAC1C \uBB38\uC790\uC5F4 \uB8E8\uD2B8 \uD0A4\uB97C \uAC00\uB9AC\uCF1C\uC57C \uD569\uB2C8\uB2E4.");
+    if (!field2 || field2.type !== "string" || field2["x-clack-asset"] || field2["x-clack-visibility"] !== "public") fail(`/output/metadata/${key}`, "metadata_text_key");
   }
   for (const key of ["thumbnail", "thumbnail_fallback"]) {
     if (metadata[key] === void 0) continue;
     const field2 = dataRootField(data, metadata[key]);
-    if (!field2 || !field2["x-clack-asset"] || field2["x-clack-visibility"] !== "public") fail2(`/output/metadata/${key}`, "\uACF5\uAC1C \uC790\uC0B0 \uB8E8\uD2B8 \uD0A4\uB97C \uAC00\uB9AC\uCF1C\uC57C \uD569\uB2C8\uB2E4(\uC778\uB371\uC2A4 \uD45C\uAE30 \uBD88\uAC00).");
+    if (!field2 || !field2["x-clack-asset"] || field2["x-clack-visibility"] !== "public") fail(`/output/metadata/${key}`, "metadata_asset_key");
   }
 }
 var INTRO_MAX_IMAGES = 8;
@@ -2480,19 +2621,19 @@ function introFieldLabelMaxLength(name2, field2) {
   }
   return Math.max(...lengths);
 }
-function inspectIntroSemantics(skill, form, slots, fail2) {
+function inspectIntroSemantics(skill, form, slots, fail) {
   const intro = skill.output?.intro;
   if (!intro) return;
   let images = 0;
   for (const name2 of intro.images ?? []) {
     const slot = slots.find((entry) => entry.field === name2);
     if (!slot) {
-      fail2("/output/intro/images", "\uC778\uD2B8\uB85C \uC774\uBBF8\uC9C0\uB294 output.asset_slots\uC758 \uD544\uB4DC\uB9CC \uC4F8 \uC218 \uC788\uC2B5\uB2C8\uB2E4.");
+      fail("/output/intro/images", "intro_image_not_slot");
       continue;
     }
     images += slot.multiple ? slot.multiple.max : 1;
   }
-  if (images > INTRO_MAX_IMAGES) fail2("/output/intro/images", `\uC778\uD2B8\uB85C \uC774\uBBF8\uC9C0\uB294 \uC2AC\uB86F \uCD5C\uB300 \uC7A5\uC218 \uD569\uACC4\uAC00 ${INTRO_MAX_IMAGES}\uC7A5 \uC774\uD558\uC5EC\uC57C \uD569\uB2C8\uB2E4.`);
+  if (images > INTRO_MAX_IMAGES) fail("/output/intro/images", "intro_images_over", { max: INTRO_MAX_IMAGES });
   if (!form) return;
   const properties = form.properties ?? {};
   const textField = (name2) => {
@@ -2502,64 +2643,64 @@ function inspectIntroSemantics(skill, form, slots, fail2) {
   for (const [key, max] of [["creator_comment", INTRO_CREATOR_COMMENT_MAX], ["description", INTRO_DESCRIPTION_MAX]]) {
     if (intro[key] === void 0) continue;
     const field2 = textField(intro[key]);
-    if (!field2 || field2["x-clack-visibility"] !== "public") fail2(`/output/intro/${key}`, "\uACF5\uAC1C \uBB38\uC790\uC5F4(text\xB7textarea) \uD3FC \uD544\uB4DC\uB97C \uAC00\uB9AC\uCF1C\uC57C \uD569\uB2C8\uB2E4.");
-    else if (field2.maxLength > max) fail2(`/output/intro/${key}`, `\uAC00\uB9AC\uD0A4\uB294 \uD3FC \uD544\uB4DC\uC758 \uCD5C\uB300 \uAE38\uC774\uAC00 ${max}\uC790 \uC774\uD558\uC5EC\uC57C \uD569\uB2C8\uB2E4.`);
+    if (!field2 || field2["x-clack-visibility"] !== "public") fail(`/output/intro/${key}`, "intro_text_field");
+    else if (field2.maxLength > max) fail(`/output/intro/${key}`, "intro_text_too_long", { max });
   }
   let sectionLength = 0;
   for (const [key, name2] of Object.entries(intro.sections ?? {})) {
     const field2 = textField(name2);
-    if (!field2 || field2["x-clack-visibility"] !== "public") fail2(`/output/intro/sections/${key}`, "\uC18C\uAC1C \uC139\uC158\uC740 \uACF5\uAC1C \uBB38\uC790\uC5F4(text\xB7textarea) \uD3FC \uD544\uB4DC\uB9CC \uAC00\uB9AC\uD0AC \uC218 \uC788\uC2B5\uB2C8\uB2E4.");
+    if (!field2 || field2["x-clack-visibility"] !== "public") fail(`/output/intro/sections/${key}`, "intro_section_field");
     else {
-      if (field2.maxLength > 2e3) fail2(`/output/intro/sections/${key}`, "\uC18C\uAC1C \uC139\uC158\uC758 \uCD5C\uB300 \uAE38\uC774\uB294 2,000\uC790\uC785\uB2C8\uB2E4.");
+      if (field2.maxLength > 2e3) fail(`/output/intro/sections/${key}`, "intro_section_too_long");
       sectionLength += field2.maxLength;
     }
   }
-  if (sectionLength > 6e3) fail2("/output/intro/sections", "\uC18C\uAC1C \uC139\uC158\uC758 \uCD5C\uB300 \uAE38\uC774 \uD569\uACC4\uB294 6,000\uC790\uC785\uB2C8\uB2E4.");
+  if (sectionLength > 6e3) fail("/output/intro/sections", "intro_sections_total");
   const fallback = intro.description_fallback ?? [];
   let composed = 0;
   for (const name2 of fallback) {
     const field2 = textField(name2);
     if (!field2) {
-      fail2("/output/intro/description_fallback", "\uBB38\uC790\uC5F4(text\xB7textarea) \uD3FC \uD544\uB4DC\uB9CC \uC790\uB3D9 \uAD6C\uC131\uC5D0 \uC4F8 \uC218 \uC788\uC2B5\uB2C8\uB2E4.");
+      fail("/output/intro/description_fallback", "intro_fallback_field");
       continue;
     }
     composed += introFieldLabelMaxLength(name2, field2) + 1 + field2.maxLength;
   }
   composed += Math.max(0, fallback.length - 1) * 2;
-  if (composed > INTRO_DESCRIPTION_MAX) fail2("/output/intro/description_fallback", `\uC790\uB3D9 \uAD6C\uC131 \uCD5C\uB300 \uAE38\uC774(\uB77C\uBCA8 \uD3EC\uD568)\uAC00 ${INTRO_DESCRIPTION_MAX}\uC790\uB97C \uB118\uC2B5\uB2C8\uB2E4.`);
+  if (composed > INTRO_DESCRIPTION_MAX) fail("/output/intro/description_fallback", "intro_fallback_too_long", { max: INTRO_DESCRIPTION_MAX });
 }
 function inspectAuthoringSemantics(skill, form, data) {
   const errors = [];
-  const fail2 = (path, message) => errors.push({ path, message });
-  inspectEditorSemantics(skill, data, fail2);
+  const fail = (path, code, args) => errors.push({ path, message: SEMANTICS_NOTES[code](args ?? {}), code, ...args ? { args } : {} });
+  inspectEditorSemantics(skill, data, fail);
   const tools = skill.authoring?.tools ?? [];
-  if (new Set(tools.map((tool) => tool.tool)).size !== tools.length) fail2("/authoring/tools", "\uB3C4\uAD6C \uC774\uB984\uC744 \uC911\uBCF5 \uC120\uC5B8\uD560 \uC218 \uC5C6\uC2B5\uB2C8\uB2E4.");
-  for (const tool of tools) if (tool.batch_max > tool.max_calls) fail2("/authoring/tools", "\uC77C\uAD04 \uC0DD\uC131 \uC218\uB294 \uC138\uC158 \uD638\uCD9C \uC218\uB97C \uB118\uC744 \uC218 \uC5C6\uC2B5\uB2C8\uB2E4.");
+  if (new Set(tools.map((tool) => tool.tool)).size !== tools.length) fail("/authoring/tools", "tool_duplicate");
+  for (const tool of tools) if (tool.batch_max > tool.max_calls) fail("/authoring/tools", "tool_batch_over_calls");
   const slots = skill.output?.asset_slots ?? [];
   const paths = /* @__PURE__ */ new Set();
   const fields3 = /* @__PURE__ */ new Set();
   for (const slot of slots) {
-    if (fields3.has(slot.field)) fail2("/output/asset_slots", "\uC2AC\uB86F \uD544\uB4DC\uB294 \uC911\uBCF5\uD560 \uC218 \uC5C6\uC2B5\uB2C8\uB2E4.");
+    if (fields3.has(slot.field)) fail("/output/asset_slots", "slot_field_duplicate");
     fields3.add(slot.field);
-    if (slot.multiple && slot.multiple.min > slot.multiple.max) fail2("/output/asset_slots", "\uB2E4\uC911 \uC2AC\uB86F \uCD5C\uC18C \uC218\uB294 \uCD5C\uB300 \uC218\uBCF4\uB2E4 \uD074 \uC218 \uC5C6\uC2B5\uB2C8\uB2E4.");
+    if (slot.multiple && slot.multiple.min > slot.multiple.max) fail("/output/asset_slots", "slot_multiple_range");
     for (let index = 0; index < (slot.multiple?.max ?? 1); index++) {
       const path = slot.multiple ? slot.multiple.path.replace("{n}", String(index)) : slot.path;
-      if (paths.has(path)) fail2("/output/asset_slots", "\uC2AC\uB86F \uD30C\uC77C \uACBD\uB85C\uB294 \uC911\uBCF5\uD560 \uC218 \uC5C6\uC2B5\uB2C8\uB2E4.");
+      if (paths.has(path)) fail("/output/asset_slots", "slot_path_duplicate");
       paths.add(path);
     }
   }
-  inspectIntroSemantics(skill, form, slots, fail2);
+  inspectIntroSemantics(skill, form, slots, fail);
   if (!form) return errors;
   const properties = form.properties ?? {};
   const exists = (expression, path) => {
     const match = /^([a-z][a-z0-9_-]*)(?:\[(\d+)\])?$/.exec(expression);
     if (!match || !Object.hasOwn(properties, match[1])) {
-      fail2(path, "\uC120\uC5B8\uD55C \uD3FC \uD544\uB4DC\uAC00 \uC5C6\uC2B5\uB2C8\uB2E4.");
+      fail(path, "form_field_missing");
       return;
     }
     if (match[2] !== void 0) {
       const slot = slots.find((value2) => value2.field === match[1]);
-      if (!slot?.multiple || Number(match[2]) >= slot.multiple.max) fail2(path, "\uB2E4\uC911 \uC774\uBBF8\uC9C0 \uC2AC\uB86F\uC758 \uC720\uD6A8\uD55C \uC778\uB371\uC2A4\uAC00 \uD544\uC694\uD569\uB2C8\uB2E4.");
+      if (!slot?.multiple || Number(match[2]) >= slot.multiple.max) fail(path, "slot_index_invalid");
     }
   };
   const entity = skill.output?.entity_map;
@@ -2569,17 +2710,17 @@ function inspectAuthoringSemantics(skill, form, data) {
   }
   for (const slot of slots) {
     const node = properties[slot.field];
-    if (!node || node["x-clack-widget"] !== (slot.multiple ? "image_list" : "image")) fail2("/output/asset_slots", "\uC2AC\uB86F\uACFC \uC774\uBBF8\uC9C0 \uC704\uC82F \uC885\uB958\uAC00 \uC77C\uCE58\uD574\uC57C \uD569\uB2C8\uB2E4.");
+    if (!node || node["x-clack-widget"] !== (slot.multiple ? "image_list" : "image")) fail("/output/asset_slots", "slot_widget_mismatch");
   }
   for (const [name2, node] of Object.entries(properties)) {
     if (node["x-clack-widget"] === "content_ref") {
-      if (node.type !== "string" || !node["x-clack-source"]) fail2(`/properties/${name2}`, "content_ref\uC5D0\uB294 \uBB38\uC790\uC5F4\uACFC x-clack-source \uC120\uC5B8\uC774 \uD544\uC694\uD569\uB2C8\uB2E4.");
+      if (node.type !== "string" || !node["x-clack-source"]) fail(`/properties/${name2}`, "content_ref_declaration");
       for (const target of Object.keys(node["x-clack-source"]?.import ?? {})) {
         exists(target, `/properties/${name2}/x-clack-source/import`);
-        if (properties[target]?.["x-clack-widget"] === "content_ref") fail2(`/properties/${name2}`, "\uB2E4\uB978 content_ref \uD544\uB4DC\uB85C \uAC00\uC838\uC62C \uC218 \uC5C6\uC2B5\uB2C8\uB2E4.");
+        if (properties[target]?.["x-clack-widget"] === "content_ref") fail(`/properties/${name2}`, "content_ref_import_chain");
       }
-    } else if (node["x-clack-source"]) fail2(`/properties/${name2}`, "x-clack-source\uB294 content_ref\uC5D0\uB9CC \uC120\uC5B8\uD569\uB2C8\uB2E4.");
-    if (node["x-clack-widget"] === "image_list" && (node.type !== "array" || node.items?.type !== "object" || !node["x-clack-asset"])) fail2(`/properties/${name2}`, "image_list\uC5D0\uB294 \uAC1D\uCCB4 \uBC30\uC5F4\uACFC \uC790\uC0B0 \uC120\uC5B8\uC774 \uD544\uC694\uD569\uB2C8\uB2E4.");
+    } else if (node["x-clack-source"]) fail(`/properties/${name2}`, "source_without_content_ref");
+    if (node["x-clack-widget"] === "image_list" && (node.type !== "array" || node.items?.type !== "object" || !node["x-clack-asset"])) fail(`/properties/${name2}`, "image_list_declaration");
   }
   return errors;
 }
@@ -2588,7 +2729,7 @@ function inspectAuthoringSemantics(skill, form, data) {
 import { createHash as createHash4 } from "crypto";
 import { lstat as lstat4, open as open3, readdir } from "fs/promises";
 import { constants } from "fs";
-import { basename as basename4, extname as extname2, join as join2, resolve as resolve7 } from "path";
+import { basename as basename5, extname as extname2, join as join2, resolve as resolve8 } from "path";
 import { Ajv2020 as Ajv20202 } from "ajv/dist/2020.js";
 import { unzipSync as unzipSync2, zipSync } from "fflate";
 import { parseDocument } from "yaml";
@@ -2599,7 +2740,6 @@ import { Ajv2020 } from "ajv/dist/2020.js";
 
 // src/vendor/clack-api-v4-contracts/output-data-inspect.mjs
 var bytes = (value2) => Buffer.byteLength(JSON.stringify(value2), "utf8");
-var fail = (path, message) => ({ path, message });
 var OUTPUT_DATA_LIMITS = { schema_bytes: 65536, depth: 6, properties: 400, public_bytes: 262144, private_bytes: 65536, ui_state_bytes: 262144 };
 var SCALAR_TYPES = /* @__PURE__ */ new Set(["string", "integer", "number", "boolean"]);
 var SCALAR_KEYS = {
@@ -2611,84 +2751,115 @@ var SCALAR_KEYS = {
   boolean: []
 };
 var TYPED_KEYS = new Set(Object.values(SCALAR_KEYS).flat());
+var RANGE_LABELS = { length: "\uAE38\uC774", items: "\uD56D\uBAA9 \uC218", value: "\uAC12" };
+var OUTPUT_DATA_NOTES = {
+  schema_too_large: () => "\uB370\uC774\uD130 \uC2A4\uD0A4\uB9C8\uB294 64 KiB \uC774\uD558\uC774\uC5B4\uC57C \uD569\uB2C8\uB2E4.",
+  root_required_undeclared: ({ key }) => `\uC120\uC5B8\uD558\uC9C0 \uC54A\uC740 \uB8E8\uD2B8 \uD0A4 ${key}\uC785\uB2C8\uB2E4.`,
+  public_root_key_missing: () => "\uACF5\uAC1C \uB8E8\uD2B8 \uD0A4\uAC00 \uD558\uB098 \uC774\uC0C1 \uD544\uC694\uD569\uB2C8\uB2E4.",
+  ref_cycle: () => "\uC21C\uD658 \uCC38\uC870\uB294 \uD5C8\uC6A9\uD558\uC9C0 \uC54A\uC2B5\uB2C8\uB2E4.",
+  ref_not_local: () => "\uB85C\uCEEC $defs \uCC38\uC870\uB9CC \uD5C8\uC6A9\uD569\uB2C8\uB2E4.",
+  depth_over: () => "\uB370\uC774\uD130 \uBB38\uC11C \uAE4A\uC774\uB294 \uB8E8\uD2B8 \uC544\uB798 6 \uC774\uD558\uC774\uC5B4\uC57C \uD569\uB2C8\uB2E4.",
+  ref_extra_keys: () => "$ref\uC5D0\uB294 \uC124\uBA85 \uD0A4\uB9CC \uD568\uAED8 \uB458 \uC218 \uC788\uC2B5\uB2C8\uB2E4.",
+  one_of_discriminator_missing: () => "oneOf\uC5D0\uB294 x-clack-discriminator\uAC00 \uD544\uC694\uD569\uB2C8\uB2E4.",
+  one_of_typed_keys: () => "oneOf \uB178\uB4DC\uC5D0\uB294 \uD615\uC2DD \uD0A4\uB97C \uD568\uAED8 \uB458 \uC218 \uC5C6\uC2B5\uB2C8\uB2E4.",
+  one_of_branch_shape: () => "\uAC01 oneOf \uBD84\uAE30\uB294 \uD310\uBCC4\uC790 \uBB38\uC790\uC5F4 const\uB97C \uD544\uC218\uB85C \uAC00\uC9C4 \uAC1D\uCCB4\uC5EC\uC57C \uD569\uB2C8\uB2E4.",
+  discriminator_duplicate: ({ value: value2 }) => `\uD310\uBCC4\uC790 \uAC12 ${value2}\uC774 \uC911\uBCF5\uB429\uB2C8\uB2E4.`,
+  discriminator_misplaced: () => "x-clack-discriminator\uB294 oneOf\uC5D0\uB9CC \uB461\uB2C8\uB2E4.",
+  type_missing: () => "type\uC774 \uD544\uC694\uD569\uB2C8\uB2E4.",
+  key_not_for_type: ({ type }) => `${type}\uC5D0 \uC4F8 \uC218 \uC5C6\uB294 \uD0A4\uC785\uB2C8\uB2E4.`,
+  range_invalid: ({ range }) => `${RANGE_LABELS[range]} \uBC94\uC704\uAC00 \uC798\uBABB\uB418\uC5C8\uC2B5\uB2C8\uB2E4.`,
+  string_max_length_missing: () => "\uBB38\uC790\uC5F4 maxLength\uAC00 \uD544\uC694\uD569\uB2C8\uB2E4.",
+  array_items_missing: () => "\uBC30\uC5F4\uC5D0\uB294 items\uC640 maxItems\uAC00 \uD544\uC694\uD569\uB2C8\uB2E4.",
+  unique_items_not_scalar: () => "uniqueItems\uB294 \uC2A4\uCE7C\uB77C \uBC30\uC5F4\uC5D0\uB9CC \uC4F8 \uC218 \uC788\uC2B5\uB2C8\uB2E4.",
+  object_shape: () => "\uAC1D\uCCB4\uC5D0\uB294 properties\uC640 additionalProperties: false\uAC00 \uD544\uC694\uD569\uB2C8\uB2E4.",
+  required_undeclared: ({ key }) => `\uC120\uC5B8\uD558\uC9C0 \uC54A\uC740 \uD0A4 ${key}\uC744 required\uC5D0 \uB450\uC5C8\uC2B5\uB2C8\uB2E4.`,
+  enum_type_mismatch: () => "enum \uAC12\uC758 \uD615\uC2DD\uC774 type\uACFC \uB2E4\uB985\uB2C8\uB2E4.",
+  asset_node_shape: () => "\uC790\uC0B0 \uB178\uB4DC\uB294 {type:string, format:uuid, maxLength:36}\uC774\uC5B4\uC57C \uD569\uB2C8\uB2E4.",
+  asset_in_private: () => "\uBE44\uACF5\uAC1C \uD0A4\uC5D0\uB294 \uC790\uC0B0\uC744 \uB458 \uC218 \uC5C6\uC2B5\uB2C8\uB2E4.",
+  format_not_string: () => "format\uC740 \uBB38\uC790\uC5F4\uC5D0\uB9CC \uC501\uB2C8\uB2E4.",
+  ai_suggest_private: () => "AI \uC81C\uC548\uC740 \uACF5\uAC1C \uD0A4\uC5D0\uB9CC \uCF24 \uC218 \uC788\uC2B5\uB2C8\uB2E4.",
+  properties_over: () => "\uB370\uC774\uD130 \uC2A4\uD0A4\uB9C8 \uC18D\uC131\uC740 400\uAC1C \uC774\uD558\uC774\uC5B4\uC57C \uD569\uB2C8\uB2E4.",
+  ai_suggest_has_asset: () => "AI \uC81C\uC548 \uD558\uC704 \uD2B8\uB9AC\uC5D0 \uC790\uC0B0 \uB178\uB4DC\uB97C \uB458 \uC218 \uC5C6\uC2B5\uB2C8\uB2E4."
+};
 function inspectOutputData(schema) {
   const errors = [];
-  if (bytes(schema) > OUTPUT_DATA_LIMITS.schema_bytes) errors.push(fail("/", "\uB370\uC774\uD130 \uC2A4\uD0A4\uB9C8\uB294 64 KiB \uC774\uD558\uC774\uC5B4\uC57C \uD569\uB2C8\uB2E4."));
-  for (const name2 of schema.required ?? []) if (!Object.hasOwn(schema.properties, name2)) errors.push(fail("/required", `\uC120\uC5B8\uD558\uC9C0 \uC54A\uC740 \uB8E8\uD2B8 \uD0A4 ${name2}\uC785\uB2C8\uB2E4.`));
-  if (!Object.values(schema.properties).some((field2) => field2["x-clack-visibility"] === "public")) errors.push(fail("/properties", "\uACF5\uAC1C \uB8E8\uD2B8 \uD0A4\uAC00 \uD558\uB098 \uC774\uC0C1 \uD544\uC694\uD569\uB2C8\uB2E4."));
+  const note = (path, code, args) => errors.push({ path, message: OUTPUT_DATA_NOTES[code](args ?? {}), code, ...args ? { args } : {} });
+  if (bytes(schema) > OUTPUT_DATA_LIMITS.schema_bytes) note("/", "schema_too_large");
+  for (const name2 of schema.required ?? []) if (!Object.hasOwn(schema.properties, name2)) note("/required", "root_required_undeclared", { key: name2 });
+  if (!Object.values(schema.properties).some((field2) => field2["x-clack-visibility"] === "public")) note("/properties", "public_root_key_missing");
   const defs = schema.$defs ?? {};
-  const resolve9 = (node) => typeof node?.$ref === "string" ? defs[node.$ref.slice("#/$defs/".length)] : node;
+  const resolve10 = (node) => typeof node?.$ref === "string" ? defs[node.$ref.slice("#/$defs/".length)] : node;
   let properties = 0;
   const suggestRoots = [];
   const assetPointers = [];
   walkDataSchema(schema, (node, info) => {
     const at = info.pointer || "/";
     if (info.cycle) {
-      errors.push(fail(at, "\uC21C\uD658 \uCC38\uC870\uB294 \uD5C8\uC6A9\uD558\uC9C0 \uC54A\uC2B5\uB2C8\uB2E4."));
+      note(at, "ref_cycle");
       return;
     }
     if (info.unresolved) {
-      errors.push(fail(at, "\uB85C\uCEEC $defs \uCC38\uC870\uB9CC \uD5C8\uC6A9\uD569\uB2C8\uB2E4."));
+      note(at, "ref_not_local");
       return;
     }
-    if (info.depth > OUTPUT_DATA_LIMITS.depth) errors.push(fail(at, "\uB370\uC774\uD130 \uBB38\uC11C \uAE4A\uC774\uB294 \uB8E8\uD2B8 \uC544\uB798 6 \uC774\uD558\uC774\uC5B4\uC57C \uD569\uB2C8\uB2E4."));
+    if (info.depth > OUTPUT_DATA_LIMITS.depth) note(at, "depth_over");
     if (info.depth === 0) return;
     if (typeof node.$ref === "string") {
-      if (Object.keys(node).some((key) => !["$ref", "title", "description", "x-clack-i18n", "x-clack-visibility"].includes(key))) errors.push(fail(at, "$ref\uC5D0\uB294 \uC124\uBA85 \uD0A4\uB9CC \uD568\uAED8 \uB458 \uC218 \uC788\uC2B5\uB2C8\uB2E4."));
+      if (Object.keys(node).some((key) => !["$ref", "title", "description", "x-clack-i18n", "x-clack-visibility"].includes(key))) note(at, "ref_extra_keys");
       return;
     }
     if (!info.branch) properties++;
     if (Array.isArray(node.oneOf)) {
       const discriminator = node["x-clack-discriminator"];
-      if (!discriminator) errors.push(fail(at, "oneOf\uC5D0\uB294 x-clack-discriminator\uAC00 \uD544\uC694\uD569\uB2C8\uB2E4."));
-      if (node.type || node.properties || node.items || node.enum || Object.hasOwn(node, "const")) errors.push(fail(at, "oneOf \uB178\uB4DC\uC5D0\uB294 \uD615\uC2DD \uD0A4\uB97C \uD568\uAED8 \uB458 \uC218 \uC5C6\uC2B5\uB2C8\uB2E4."));
+      if (!discriminator) note(at, "one_of_discriminator_missing");
+      if (node.type || node.properties || node.items || node.enum || Object.hasOwn(node, "const")) note(at, "one_of_typed_keys");
       const seen = /* @__PURE__ */ new Set();
       for (const raw of node.oneOf) {
-        const branch = resolve9(raw);
+        const branch = resolve10(raw);
         const tag = branch?.properties?.[discriminator];
         if (branch?.type !== "object" || typeof tag?.const !== "string" || tag.type !== "string" || !(branch.required ?? []).includes(discriminator)) {
-          errors.push(fail(at, "\uAC01 oneOf \uBD84\uAE30\uB294 \uD310\uBCC4\uC790 \uBB38\uC790\uC5F4 const\uB97C \uD544\uC218\uB85C \uAC00\uC9C4 \uAC1D\uCCB4\uC5EC\uC57C \uD569\uB2C8\uB2E4."));
-        } else if (seen.has(tag.const)) errors.push(fail(at, `\uD310\uBCC4\uC790 \uAC12 ${tag.const}\uC774 \uC911\uBCF5\uB429\uB2C8\uB2E4.`));
+          note(at, "one_of_branch_shape");
+        } else if (seen.has(tag.const)) note(at, "discriminator_duplicate", { value: tag.const });
         else seen.add(tag.const);
       }
       return;
     }
-    if (node["x-clack-discriminator"] !== void 0) errors.push(fail(at, "x-clack-discriminator\uB294 oneOf\uC5D0\uB9CC \uB461\uB2C8\uB2E4."));
+    if (node["x-clack-discriminator"] !== void 0) note(at, "discriminator_misplaced");
     if (!node.type) {
-      errors.push(fail(at, "type\uC774 \uD544\uC694\uD569\uB2C8\uB2E4."));
+      note(at, "type_missing");
       return;
     }
-    for (const key of Object.keys(node)) if (TYPED_KEYS.has(key) && !SCALAR_KEYS[node.type].includes(key)) errors.push(fail(`${at}/${key}`, `${node.type}\uC5D0 \uC4F8 \uC218 \uC5C6\uB294 \uD0A4\uC785\uB2C8\uB2E4.`));
-    const range = (low, high, label) => {
-      if (typeof node[low] === "number" && typeof node[high] === "number" && node[low] > node[high]) errors.push(fail(at, `${label} \uBC94\uC704\uAC00 \uC798\uBABB\uB418\uC5C8\uC2B5\uB2C8\uB2E4.`));
+    for (const key of Object.keys(node)) if (TYPED_KEYS.has(key) && !SCALAR_KEYS[node.type].includes(key)) note(`${at}/${key}`, "key_not_for_type", { type: node.type });
+    const range = (low, high, kind) => {
+      if (typeof node[low] === "number" && typeof node[high] === "number" && node[low] > node[high]) note(at, "range_invalid", { range: kind });
     };
-    range("minLength", "maxLength", "\uAE38\uC774");
-    range("minItems", "maxItems", "\uD56D\uBAA9 \uC218");
-    range("minimum", "maximum", "\uAC12");
-    if (node.type === "string" && typeof node.maxLength !== "number") errors.push(fail(at, "\uBB38\uC790\uC5F4 maxLength\uAC00 \uD544\uC694\uD569\uB2C8\uB2E4."));
-    if (node.type === "array" && (!node.items || typeof node.maxItems !== "number")) errors.push(fail(at, "\uBC30\uC5F4\uC5D0\uB294 items\uC640 maxItems\uAC00 \uD544\uC694\uD569\uB2C8\uB2E4."));
+    range("minLength", "maxLength", "length");
+    range("minItems", "maxItems", "items");
+    range("minimum", "maximum", "value");
+    if (node.type === "string" && typeof node.maxLength !== "number") note(at, "string_max_length_missing");
+    if (node.type === "array" && (!node.items || typeof node.maxItems !== "number")) note(at, "array_items_missing");
     if (node.type === "array" && node.uniqueItems === true) {
       let items = node.items;
-      for (let hops = 0; typeof items?.$ref === "string" && hops < 64; hops++) items = resolve9(items);
-      if (!items || Array.isArray(items.oneOf) || !SCALAR_TYPES.has(items.type)) errors.push(fail(`${at}/uniqueItems`, "uniqueItems\uB294 \uC2A4\uCE7C\uB77C \uBC30\uC5F4\uC5D0\uB9CC \uC4F8 \uC218 \uC788\uC2B5\uB2C8\uB2E4."));
+      for (let hops = 0; typeof items?.$ref === "string" && hops < 64; hops++) items = resolve10(items);
+      if (!items || Array.isArray(items.oneOf) || !SCALAR_TYPES.has(items.type)) note(`${at}/uniqueItems`, "unique_items_not_scalar");
     }
     if (node.type === "object") {
-      if (node.additionalProperties !== false || !node.properties || !Object.keys(node.properties).length) errors.push(fail(at, "\uAC1D\uCCB4\uC5D0\uB294 properties\uC640 additionalProperties: false\uAC00 \uD544\uC694\uD569\uB2C8\uB2E4."));
-      for (const name2 of node.required ?? []) if (!Object.hasOwn(node.properties ?? {}, name2)) errors.push(fail(at, `\uC120\uC5B8\uD558\uC9C0 \uC54A\uC740 \uD0A4 ${name2}\uC744 required\uC5D0 \uB450\uC5C8\uC2B5\uB2C8\uB2E4.`));
+      if (node.additionalProperties !== false || !node.properties || !Object.keys(node.properties).length) note(at, "object_shape");
+      for (const name2 of node.required ?? []) if (!Object.hasOwn(node.properties ?? {}, name2)) note(at, "required_undeclared", { key: name2 });
     }
-    for (const value2 of node.enum ?? []) if (typeof value2 !== (node.type === "integer" ? "number" : node.type)) errors.push(fail(at, "enum \uAC12\uC758 \uD615\uC2DD\uC774 type\uACFC \uB2E4\uB985\uB2C8\uB2E4."));
+    for (const value2 of node.enum ?? []) if (typeof value2 !== (node.type === "integer" ? "number" : node.type)) note(at, "enum_type_mismatch");
     if (node["x-clack-asset"]) {
       assetPointers.push(at);
-      if (node.type !== "string" || node.format !== "uuid" || node.maxLength !== 36 || node.enum) errors.push(fail(at, "\uC790\uC0B0 \uB178\uB4DC\uB294 {type:string, format:uuid, maxLength:36}\uC774\uC5B4\uC57C \uD569\uB2C8\uB2E4."));
-      if (info.visibility === "private") errors.push(fail(at, "\uBE44\uACF5\uAC1C \uD0A4\uC5D0\uB294 \uC790\uC0B0\uC744 \uB458 \uC218 \uC5C6\uC2B5\uB2C8\uB2E4."));
-    } else if (node.format === "uuid" && node.type !== "string") errors.push(fail(at, "format\uC740 \uBB38\uC790\uC5F4\uC5D0\uB9CC \uC501\uB2C8\uB2E4."));
+      if (node.type !== "string" || node.format !== "uuid" || node.maxLength !== 36 || node.enum) note(at, "asset_node_shape");
+      if (info.visibility === "private") note(at, "asset_in_private");
+    } else if (node.format === "uuid" && node.type !== "string") note(at, "format_not_string");
     if (node["x-clack-ai"]?.suggest === true) {
-      if (info.visibility !== "public") errors.push(fail(at, "AI \uC81C\uC548\uC740 \uACF5\uAC1C \uD0A4\uC5D0\uB9CC \uCF24 \uC218 \uC788\uC2B5\uB2C8\uB2E4."));
+      if (info.visibility !== "public") note(at, "ai_suggest_private");
       suggestRoots.push(at);
     }
   });
-  if (properties > OUTPUT_DATA_LIMITS.properties) errors.push(fail("/", "\uB370\uC774\uD130 \uC2A4\uD0A4\uB9C8 \uC18D\uC131\uC740 400\uAC1C \uC774\uD558\uC774\uC5B4\uC57C \uD569\uB2C8\uB2E4."));
-  for (const root of suggestRoots) if (assetPointers.some((asset) => asset === root || asset.startsWith(`${root}/`))) errors.push(fail(root, "AI \uC81C\uC548 \uD558\uC704 \uD2B8\uB9AC\uC5D0 \uC790\uC0B0 \uB178\uB4DC\uB97C \uB458 \uC218 \uC5C6\uC2B5\uB2C8\uB2E4."));
+  if (properties > OUTPUT_DATA_LIMITS.properties) note("/", "properties_over");
+  for (const root of suggestRoots) if (assetPointers.some((asset) => asset === root || asset.startsWith(`${root}/`))) note(root, "ai_suggest_has_asset");
   return errors;
 }
 var ZWJ_AFTER = new RegExp("\\p{Extended_Pictographic}", "u");
@@ -5426,7 +5597,7 @@ function fillEditorHash(files) {
   return new TextEncoder().encode(next);
 }
 async function prepareSkillPackage(source, options2 = {}) {
-  const path = resolve7(source);
+  const path = resolve8(source);
   let info;
   try {
     info = await lstat4(path);
@@ -5451,34 +5622,34 @@ async function prepareSkillPackage(source, options2 = {}) {
   else return invalid2("\uC2A4\uD0AC \uB514\uB809\uD130\uB9AC \uB610\uB294 ZIP \uD30C\uC77C\uC744 \uC9C0\uC815\uD558\uC138\uC694.");
   const inspected = inspectZip(
     bytes2,
-    info.isDirectory() ? basename4(path) : void 0,
+    info.isDirectory() ? basename5(path) : void 0,
     info.isDirectory() && !options2.fillEditorHash ? "warn" : "error"
   );
   return { bytes: bytes2, sha256: hash(bytes2), ...inspected, ...filledManifest ? { filled_manifest: filledManifest } : {} };
 }
 
 // src/commands/skill.ts
-var uuid2 = z9.uuid();
-var createdSchema = z9.object({ id: uuid2, slug: z9.string(), type: z9.string() });
-var uploadSchema = z9.object({
+var uuid2 = z10.uuid();
+var createdSchema = z10.object({ id: uuid2, slug: z10.string(), type: z10.string() });
+var uploadSchema = z10.object({
   version_id: uuid2,
-  upload_url: z9.url(),
-  headers: z9.record(z9.string(), z9.string()),
-  expires_at: z9.string(),
-  max_upload_bytes: z9.number().int().positive()
+  upload_url: z10.url(),
+  headers: z10.record(z10.string(), z10.string()),
+  expires_at: z10.string(),
+  max_upload_bytes: z10.number().int().positive()
 });
-var versionSchema = z9.object({ id: uuid2, skill_id: uuid2, version: z9.string(), review_status: z9.string() });
-var skillSlug = z9.string().regex(/^[a-z][a-z0-9-]{0,63}$/);
-var semver = z9.string().regex(/^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-[0-9A-Za-z.-]+)?$/);
-var category = z9.enum(["character_chat", "quiz", "worldbuilding", "gallery", "story", "agent_tool"]);
-var visibility = z9.enum(["private", "unlisted", "public"]);
-var managedVersionSchema = z9.object({
+var versionSchema = z10.object({ id: uuid2, skill_id: uuid2, version: z10.string(), review_status: z10.string() });
+var skillSlug = z10.string().regex(/^[a-z][a-z0-9-]{0,63}$/);
+var semver = z10.string().regex(/^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-[0-9A-Za-z.-]+)?$/);
+var category = z10.enum(["character_chat", "quiz", "worldbuilding", "gallery", "story", "agent_tool"]);
+var visibility = z10.enum(["private", "unlisted", "public"]);
+var managedVersionSchema = z10.object({
   id: uuid2,
   skill_id: uuid2,
-  version: z9.string(),
-  review_status: z9.string(),
-  release_status: z9.string(),
-  package_hash: z9.string().nullable()
+  version: z10.string(),
+  review_status: z10.string(),
+  release_status: z10.string(),
+  package_hash: z10.string().nullable()
 });
 function serverData(schema, value2) {
   const parsed = schema.safeParse(value2);
@@ -5578,7 +5749,7 @@ ${hint}`, error2.code, error2.status, error2.retryAfter);
 function registerSkillCommands(program2, runtime2) {
   const skill = program2.command("skill").description("\uC2A4\uD0AC \uD328\uD0A4\uC9C0 \uAC80\uC0AC\xB7\uC5C5\uB85C\uB4DC\xB7\uC2EC\uC0AC\xB7\uAC8C\uC2DC (skill:read\xB7write\xB7publish)");
   runtime2.action(skill.command("list").description("\uC2A4\uD0AC \uBAA9\uB85D \uAC80\uC0C9 (skill:read)").option("-q, --query <text>", "\uC2A4\uD0AC \uC774\uB984 \uAC80\uC0C9").option("--category <category>", "\uBD84\uB958").option("--entity <entity>", "\uC0B0\uCD9C\uBB3C \uC5D4\uD2F0\uD2F0(character)").option("--type <type>", "\uC2A4\uD0AC \uC720\uD615(template|instruction|tool)").option("--official <value>", "\uACF5\uC2DD \uC2A4\uD0AC\uB9CC true \uB610\uB294 false").option("--cursor <id>", "\uB2E4\uC74C \uD398\uC774\uC9C0 UUID").option("--all", "\uBAA8\uB4E0 \uD398\uC774\uC9C0 \uC870\uD68C"), async (ctx, _args, opts) => {
-    const query = opts.query === void 0 ? void 0 : z9.string().trim().min(1).max(100).safeParse(opts.query);
+    const query = opts.query === void 0 ? void 0 : z10.string().trim().min(1).max(100).safeParse(opts.query);
     if (query && !query.success) throw new CliError("\uAC80\uC0C9\uC5B4\uB294 1~100\uC790\uC5EC\uC57C \uD569\uB2C8\uB2E4.");
     const selectedCategory = opts.category === void 0 ? void 0 : category.safeParse(opts.category);
     if (selectedCategory && !selectedCategory.success) throw new CliError("\uC2A4\uD0AC \uBD84\uB958\uB97C \uD655\uC778\uD558\uC138\uC694.");
@@ -5653,11 +5824,11 @@ function registerSkillCommands(program2, runtime2) {
   runtime2.action(skill.command("pack [dir]").description("\uC2A4\uD0AC \uD328\uD0A4\uC9C0 ZIP \uB9CC\uB4E4\uAE30 (\uB85C\uADF8\uC778 \uBD88\uD544\uC694, \uC5D0\uB514\uD130 \uC2A4\uD0AC\uC740 authoring.editor.sha256\uC744 \uCC44\uC6C0)").option("-o, --out <file>", "ZIP \uC800\uC7A5 \uACBD\uB85C (\uAE30\uBCF8: <\uC774\uB984>-<\uBC84\uC804>.zip)").option("--write-manifest", "\uCC44\uC6B4 sha256\uC744 \uB514\uB809\uD130\uB9AC\uC758 clack.skill.json\uC5D0\uB3C4 \uAE30\uB85D"), async (ctx, [dir], opts) => {
     const source = dir ?? ".";
     const prepared = await prepareSkillPackage(source, { fillEditorHash: true });
-    const out = resolve8(opts.out ?? `${prepared.manifest.name}-${prepared.manifest.version}.zip`);
+    const out = resolve9(opts.out ?? `${prepared.manifest.name}-${prepared.manifest.version}.zip`);
     const writeManifest = Boolean(opts.writeManifest && prepared.filled_manifest);
     if (!ctx.options.dryRun) {
       await writeFile2(out, prepared.bytes);
-      if (writeManifest) await writeFile2(join3(resolve8(source), "clack.skill.json"), prepared.filled_manifest);
+      if (writeManifest) await writeFile2(join3(resolve9(source), "clack.skill.json"), prepared.filled_manifest);
     }
     ctx.output({
       ...ctx.options.dryRun ? { dry_run: true } : {},
@@ -5687,7 +5858,7 @@ ${SDK_LOCATION_HELP}
       ]) {
         if (value2 === void 0) continue;
         if ((flag === "host-port" || flag === "editor-port") && !/^\d{2,5}$/.test(value2)) throw new CliError("\uD3EC\uD2B8\uB294 \uC22B\uC790\uC5EC\uC57C \uD569\uB2C8\uB2E4.");
-        args.push(`--${flag}`, flag.endsWith("port") ? value2 : resolve8(value2));
+        args.push(`--${flag}`, flag.endsWith("port") ? value2 : resolve9(value2));
       }
       const sdkDir = resolveSdkDir(opts.sdkDir);
       const serve = join3(sdkDir, "mock-host/serve.mjs");
@@ -5695,10 +5866,10 @@ ${SDK_LOCATION_HELP}
         ctx.output({ dry_run: true, sdk_dir: sdkDir, command: ["node", serve, ...args] });
         return;
       }
-      await new Promise((done, fail2) => {
+      await new Promise((done, fail) => {
         const child = spawn(process.execPath, [serve, ...args], { stdio: "inherit" });
-        child.on("error", () => fail2(new CliError("\uBAA8\uC758 \uD638\uC2A4\uD2B8\uB97C \uC2E4\uD589\uD558\uC9C0 \uBABB\uD588\uC2B5\uB2C8\uB2E4.", "SKILL_EDITOR_DEV_FAILED")));
-        child.on("exit", (code) => code ? fail2(new CliError(`\uBAA8\uC758 \uD638\uC2A4\uD2B8\uAC00 \uC885\uB8CC\uB418\uC5C8\uC2B5\uB2C8\uB2E4(\uCF54\uB4DC ${code}). SDK\uC5D0\uC11C pnpm build\uB97C \uBA3C\uC800 \uC2E4\uD589\uD588\uB294\uC9C0 \uD655\uC778\uD558\uC138\uC694.`, "SKILL_EDITOR_DEV_FAILED")) : done());
+        child.on("error", () => fail(new CliError("\uBAA8\uC758 \uD638\uC2A4\uD2B8\uB97C \uC2E4\uD589\uD558\uC9C0 \uBABB\uD588\uC2B5\uB2C8\uB2E4.", "SKILL_EDITOR_DEV_FAILED")));
+        child.on("exit", (code) => code ? fail(new CliError(`\uBAA8\uC758 \uD638\uC2A4\uD2B8\uAC00 \uC885\uB8CC\uB418\uC5C8\uC2B5\uB2C8\uB2E4(\uCF54\uB4DC ${code}). SDK\uC5D0\uC11C pnpm build\uB97C \uBA3C\uC800 \uC2E4\uD589\uD588\uB294\uC9C0 \uD655\uC778\uD558\uC138\uC694.`, "SKILL_EDITOR_DEV_FAILED")) : done());
       });
     }
   );
@@ -5827,14 +5998,14 @@ function editorReport(prepared) {
 var SDK_LOCATION_HELP = "SDK\uB294 \uC544\uC9C1 npm\uC5D0 \uACF5\uAC1C\uB418\uC9C0 \uC54A\uC544 CLI\uC5D0 \uD3EC\uD568\uB418\uC9C0 \uC54A\uC2B5\uB2C8\uB2E4. SDK \uC18C\uC2A4 \uB514\uB809\uD130\uB9AC(\uD074\uB799 \uB0B4\uBD80 \uC791\uC5C5\uC790\uB294 \uB0B4\uBD80 \uC800\uC7A5\uC18C\uC758 clack-skill-editor-sdk)\uC5D0\uC11C pnpm install && pnpm build\uB97C \uC2E4\uD589\uD55C \uB4A4 --sdk-dir <SDK \uB514\uB809\uD130\uB9AC>, CLACK_SKILL_EDITOR_SDK_DIR=<SDK \uB514\uB809\uD130\uB9AC>, CLACK_MONOREPO_DIR=<\uB0B4\uBD80 \uC800\uC7A5\uC18C> \uC911 \uD558\uB098\uB85C \uC704\uCE58\uB97C \uC9C0\uC815\uD558\uC138\uC694.";
 function resolveSdkDir(option) {
   const candidates = [];
-  if (option) candidates.push(resolve8(option));
+  if (option) candidates.push(resolve9(option));
   else {
-    if (process.env.CLACK_SKILL_EDITOR_SDK_DIR) candidates.push(resolve8(process.env.CLACK_SKILL_EDITOR_SDK_DIR));
+    if (process.env.CLACK_SKILL_EDITOR_SDK_DIR) candidates.push(resolve9(process.env.CLACK_SKILL_EDITOR_SDK_DIR));
     try {
-      candidates.push(resolve8(createRequire(join3(process.cwd(), "noop.js")).resolve("@clack/skill-editor-sdk/package.json"), ".."));
+      candidates.push(resolve9(createRequire(join3(process.cwd(), "noop.js")).resolve("@clack/skill-editor-sdk/package.json"), ".."));
     } catch {
     }
-    if (process.env.CLACK_MONOREPO_DIR) candidates.push(resolve8(process.env.CLACK_MONOREPO_DIR, "clack-skill-editor-sdk"));
+    if (process.env.CLACK_MONOREPO_DIR) candidates.push(resolve9(process.env.CLACK_MONOREPO_DIR, "clack-skill-editor-sdk"));
   }
   const found = candidates.find((dir) => existsSync(join3(dir, "mock-host/serve.mjs")));
   if (!found) throw new CliError(`\uC2A4\uD0AC \uC5D0\uB514\uD130 SDK(@clack/skill-editor-sdk)\uB97C \uCC3E\uC744 \uC218 \uC5C6\uC2B5\uB2C8\uB2E4. ${SDK_LOCATION_HELP}`, "SKILL_EDITOR_SDK_NOT_FOUND");
@@ -5850,24 +6021,24 @@ function skillVersionIds(skillId, versionId) {
 // src/lib/platform-mcp.ts
 var protocolVersions = /* @__PURE__ */ new Set(["2024-11-05", "2025-03-26", "2025-06-18", "2025-11-25"]);
 var maxLineBytes = 1024 * 1024;
-var collectionKey = z10.string().regex(/^[A-Za-z0-9_-]{1,64}$/);
+var collectionKey = z11.string().regex(/^[A-Za-z0-9_-]{1,64}$/);
 var patSchemas = {
-  skillList: z10.object({ q: z10.string().trim().min(1).max(100).optional() }).strict(),
-  skillGet: z10.object({ slug: z10.string().regex(/^[a-z][a-z0-9-]{0,63}$/) }).strict(),
-  skillPush: z10.object({ dir: z10.string().min(1).max(4096).optional(), skill_id: z10.uuid().optional() }).strict(),
-  skillVersionRef: z10.object({ skill_id: z10.uuid(), version_id: z10.uuid() }).strict(),
-  skillSubmit: z10.object({ skill_id: z10.uuid(), version_id: z10.uuid(), confirm: z10.boolean().optional() }).strict(),
-  skillRelease: z10.object({
-    skill_id: z10.uuid(),
-    version_id: z10.uuid(),
-    visibility: z10.enum(["private", "unlisted", "public"]),
-    confirm: z10.boolean().optional()
+  skillList: z11.object({ q: z11.string().trim().min(1).max(100).optional() }).strict(),
+  skillGet: z11.object({ slug: z11.string().regex(/^[a-z][a-z0-9-]{0,63}$/) }).strict(),
+  skillPush: z11.object({ dir: z11.string().min(1).max(4096).optional(), skill_id: z11.uuid().optional() }).strict(),
+  skillVersionRef: z11.object({ skill_id: z11.uuid(), version_id: z11.uuid() }).strict(),
+  skillSubmit: z11.object({ skill_id: z11.uuid(), version_id: z11.uuid(), confirm: z11.boolean().optional() }).strict(),
+  skillRelease: z11.object({
+    skill_id: z11.uuid(),
+    version_id: z11.uuid(),
+    visibility: z11.enum(["private", "unlisted", "public"]),
+    confirm: z11.boolean().optional()
   }).strict(),
-  contentPublish: z10.object({ content_id: z10.uuid(), version_id: z10.uuid(), confirm: z10.boolean().optional() }).strict(),
-  sharedCollections: z10.object({ content_id: z10.uuid() }).strict(),
-  sharedList: z10.object({ content_id: z10.uuid(), collection: collectionKey, limit: z10.number().int().min(1).max(100).optional() }).strict(),
-  sharedDocument: z10.object({ content_id: z10.uuid(), collection: collectionKey, key: collectionKey }).strict(),
-  sharedModerate: z10.object({ content_id: z10.uuid(), collection: collectionKey, key: collectionKey, confirm: z10.boolean().optional() }).strict()
+  contentPublish: z11.object({ content_id: z11.uuid(), version_id: z11.uuid(), confirm: z11.boolean().optional() }).strict(),
+  sharedCollections: z11.object({ content_id: z11.uuid() }).strict(),
+  sharedList: z11.object({ content_id: z11.uuid(), collection: collectionKey, limit: z11.number().int().min(1).max(100).optional() }).strict(),
+  sharedDocument: z11.object({ content_id: z11.uuid(), collection: collectionKey, key: collectionKey }).strict(),
+  sharedModerate: z11.object({ content_id: z11.uuid(), collection: collectionKey, key: collectionKey, confirm: z11.boolean().optional() }).strict()
 };
 var patToolNames = /* @__PURE__ */ new Set([
   "platform_authoring",
@@ -5897,120 +6068,120 @@ function parsePat(schema, input, label) {
   return parsed.data;
 }
 var toolDefinitions = [
-  { name: "platform_authoring", description: "\uACF5\uAC1C \uC2A4\uD0AC \uC81C\uC791 \uC138\uC158\xB7\uD3FC\xB7\uC790\uC0B0\xB7\uC774\uBBF8\uC9C0 \uC0DD\uC131\xB7\uD328\uD0A4\uC9D5\xB7\uC644\uB8CC\xB7\uD3EC\uAE30\uB97C \uCC98\uB9AC\uD569\uB2C8\uB2E4. complete/abandon\uC740 \uD3FC \uC138\uC158 \uC804\uC6A9\uC774\uBA70 complete\uB294 \uD604\uC7AC revision \uD328\uD0A4\uC9D5, abandon\uC740 confirm:true\uAC00 \uD544\uC694\uD569\uB2C8\uB2E4. \uC5D0\uB514\uD130\xB7\uC9C0\uCE68\uD615\uC740 \uC13C\uD130\uC5D0\uC11C \uC791\uC5C5\uD569\uB2C8\uB2E4. \uC774\uBBF8\uC9C0 \uC0DD\uC131\uC5D0\uB294 \uACAC\uC801 \uC2B9\uC778 \uAC00\uACA9\uACFC \uBA71\uB4F1\uC131 \uD0A4\uAC00 \uD544\uC694\uD569\uB2C8\uB2E4. creator-content:write \uAD8C\uD55C\uC774 \uD544\uC694\uD569\uB2C8\uB2E4.", inputSchema: { type: "object", ...z10.toJSONSchema(authoringInput) }, annotations: { readOnlyHint: false, destructiveHint: true } },
+  { name: "platform_authoring", description: "\uACF5\uAC1C \uC2A4\uD0AC \uC81C\uC791 \uC138\uC158\xB7\uD3FC\xB7\uC790\uC0B0\xB7\uC774\uBBF8\uC9C0 \uC0DD\uC131\xB7\uD328\uD0A4\uC9D5\xB7\uC644\uB8CC\xB7\uD3EC\uAE30\uB97C \uCC98\uB9AC\uD569\uB2C8\uB2E4. complete/abandon\uC740 \uD3FC \uC138\uC158 \uC804\uC6A9\uC774\uBA70 complete\uB294 \uD604\uC7AC revision \uD328\uD0A4\uC9D5, abandon\uC740 confirm:true\uAC00 \uD544\uC694\uD569\uB2C8\uB2E4. \uC5D0\uB514\uD130\xB7\uC9C0\uCE68\uD615\uC740 \uC13C\uD130\uC5D0\uC11C \uC791\uC5C5\uD569\uB2C8\uB2E4. \uC774\uBBF8\uC9C0 \uC0DD\uC131\uC5D0\uB294 \uACAC\uC801 \uC2B9\uC778 \uAC00\uACA9\uACFC \uBA71\uB4F1\uC131 \uD0A4\uAC00 \uD544\uC694\uD569\uB2C8\uB2E4. creator-content:write \uAD8C\uD55C\uC774 \uD544\uC694\uD569\uB2C8\uB2E4.", inputSchema: { type: "object", ...z11.toJSONSchema(authoringInput) }, annotations: { readOnlyHint: false, destructiveHint: true } },
   {
     name: "platform_usage_get",
     description: "\uC11C\uBC84 \uD0A4\uAC00 \uC18D\uD55C \uCF58\uD150\uCE20\uC758 \uD50C\uB7AB\uD3FC \uC0AC\uC6A9\uB7C9\uC744 \uC870\uD68C\uD569\uB2C8\uB2E4.",
-    inputSchema: z10.toJSONSchema(platformReadSchemas.usage),
+    inputSchema: z11.toJSONSchema(platformReadSchemas.usage),
     annotations: { readOnlyHint: true, destructiveHint: false }
   },
   {
     name: "platform_server_data_get",
     description: "\uC11C\uBC84 \uD0A4\uB85C \uCF58\uD150\uCE20 \uB370\uC774\uD130 \uBB38\uC11C\uB97C \uC870\uD68C\uD569\uB2C8\uB2E4. data:read \uAD8C\uD55C\uC774 \uD544\uC694\uD569\uB2C8\uB2E4.",
-    inputSchema: z10.toJSONSchema(platformReadSchemas.get),
+    inputSchema: z11.toJSONSchema(platformReadSchemas.get),
     annotations: { readOnlyHint: true, destructiveHint: false }
   },
   {
     name: "platform_server_data_list",
     description: "\uC11C\uBC84 \uD0A4\uB85C \uCF58\uD150\uCE20 \uB370\uC774\uD130 \uBB38\uC11C \uBAA9\uB85D\uC744 \uC870\uD68C\uD569\uB2C8\uB2E4. data:read \uAD8C\uD55C\uC774 \uD544\uC694\uD569\uB2C8\uB2E4.",
-    inputSchema: z10.toJSONSchema(platformReadSchemas.list),
+    inputSchema: z11.toJSONSchema(platformReadSchemas.list),
     annotations: { readOnlyHint: true, destructiveHint: false }
   },
   {
     name: "platform_server_data_leaderboard",
     description: "\uC11C\uBC84 \uD0A4\uB85C \uACF5\uC720 \uB370\uC774\uD130 \uC21C\uC704\uB97C \uC870\uD68C\uD569\uB2C8\uB2E4. data:read \uAD8C\uD55C\uC774 \uD544\uC694\uD569\uB2C8\uB2E4.",
-    inputSchema: z10.toJSONSchema(platformReadSchemas.leaderboard),
+    inputSchema: z11.toJSONSchema(platformReadSchemas.leaderboard),
     annotations: { readOnlyHint: true, destructiveHint: false }
   },
   {
     name: "platform_server_data_put",
     description: "\uC11C\uBC84 \uD0A4\uB85C \uB2E8\uC77C \uBB38\uC11C \uC804\uCCB4\uB97C \uC800\uC7A5\uD569\uB2C8\uB2E4. \uAC1C\uC815 \uBC88\uD638 \uB610\uB294 \uBD80\uC7AC \uC870\uAC74\uACFC confirm:true\uAC00 \uD544\uC694\uD569\uB2C8\uB2E4.",
-    inputSchema: z10.toJSONSchema(platformReadSchemas.put),
+    inputSchema: z11.toJSONSchema(platformReadSchemas.put),
     annotations: { readOnlyHint: false, destructiveHint: true }
   },
   {
     name: "platform_server_data_patch",
     description: "\uC11C\uBC84 \uD0A4\uB85C \uB2E8\uC77C \uBB38\uC11C\uB97C \uBCD1\uD569 \uC218\uC815\uD569\uB2C8\uB2E4. \uAC1C\uC815 \uBC88\uD638\uC640 confirm:true\uAC00 \uD544\uC694\uD569\uB2C8\uB2E4.",
-    inputSchema: z10.toJSONSchema(platformReadSchemas.patch),
+    inputSchema: z11.toJSONSchema(platformReadSchemas.patch),
     annotations: { readOnlyHint: false, destructiveHint: true }
   },
   {
     name: "platform_server_data_delete",
     description: "\uC11C\uBC84 \uD0A4\uB85C \uB2E8\uC77C \uBB38\uC11C\uB97C \uC0AD\uC81C\uD558\uAC70\uB098 \uC228\uAE41\uB2C8\uB2E4. confirm:true\uAC00 \uD544\uC694\uD569\uB2C8\uB2E4.",
-    inputSchema: z10.toJSONSchema(platformReadSchemas.delete),
+    inputSchema: z11.toJSONSchema(platformReadSchemas.delete),
     annotations: { readOnlyHint: false, destructiveHint: true }
   },
   // 아래는 개인 액세스 토큰(CLACK_TOKEN, pat_)으로 동작하는 개인 도구다. 서버 키 도구와 인증 평면이 다르다.
   {
     name: "platform_skill_list",
     description: "\uACF5\uAC1C \uC2A4\uD0AC \uBAA9\uB85D\uC744 \uC774\uB984\uC73C\uB85C \uAC80\uC0C9\uD569\uB2C8\uB2E4. skill:read \uAD8C\uD55C\uC774 \uD544\uC694\uD569\uB2C8\uB2E4.",
-    inputSchema: z10.toJSONSchema(patSchemas.skillList),
+    inputSchema: z11.toJSONSchema(patSchemas.skillList),
     annotations: { readOnlyHint: true, destructiveHint: false }
   },
   {
     name: "platform_skill_get",
     description: "\uC2A4\uD0AC \uC0C1\uC138\uB97C \uC774\uB984(slug)\uC73C\uB85C \uC870\uD68C\uD569\uB2C8\uB2E4. skill:read \uAD8C\uD55C\uC774 \uD544\uC694\uD569\uB2C8\uB2E4.",
-    inputSchema: z10.toJSONSchema(patSchemas.skillGet),
+    inputSchema: z11.toJSONSchema(patSchemas.skillGet),
     annotations: { readOnlyHint: true, destructiveHint: false }
   },
   {
     name: "platform_skill_push",
     description: "\uB85C\uCEEC \uC2A4\uD0AC \uB514\uB809\uD130\uB9AC\uB97C \uAC80\uC99D\uD558\uACE0 \uC0C8 \uBC84\uC804\uC73C\uB85C \uC5C5\uB85C\uB4DC\uD569\uB2C8\uB2E4. dir\uC744 \uC0DD\uB7B5\uD558\uBA74 \uD604\uC7AC \uB514\uB809\uD130\uB9AC\uB97C \uC0AC\uC6A9\uD569\uB2C8\uB2E4. skill:write \uAD8C\uD55C\uC774 \uD544\uC694\uD569\uB2C8\uB2E4.",
-    inputSchema: z10.toJSONSchema(patSchemas.skillPush),
+    inputSchema: z11.toJSONSchema(patSchemas.skillPush),
     annotations: { readOnlyHint: false, destructiveHint: false }
   },
   {
     name: "platform_skill_status",
     description: "\uB0B4 \uC2A4\uD0AC \uBC84\uC804\uC758 \uC2EC\uC0AC\xB7\uAC8C\uC2DC \uC0C1\uD0DC\uB97C \uC870\uD68C\uD569\uB2C8\uB2E4. skill:read \uAD8C\uD55C\uC774 \uD544\uC694\uD569\uB2C8\uB2E4.",
-    inputSchema: z10.toJSONSchema(patSchemas.skillVersionRef),
+    inputSchema: z11.toJSONSchema(patSchemas.skillVersionRef),
     annotations: { readOnlyHint: true, destructiveHint: false }
   },
   {
     name: "platform_skill_submit",
     description: "\uAC80\uC99D \uC644\uB8CC\uD55C \uC2A4\uD0AC \uBC84\uC804\uC744 \uC2EC\uC0AC\uC5D0 \uC81C\uCD9C\uD569\uB2C8\uB2E4. skill:write\uC640 skill:publish \uAD8C\uD55C(\uB458 \uB2E4)\uACFC confirm:true\uAC00 \uD544\uC694\uD569\uB2C8\uB2E4.",
-    inputSchema: z10.toJSONSchema(patSchemas.skillSubmit),
+    inputSchema: z11.toJSONSchema(patSchemas.skillSubmit),
     annotations: { readOnlyHint: false, destructiveHint: true }
   },
   {
     name: "platform_skill_release",
     description: "\uC2B9\uC778\uB41C \uC2A4\uD0AC \uBC84\uC804\uC744 \uACF5\uAC1C \uBC94\uC704\uB85C \uAC8C\uC2DC\uD569\uB2C8\uB2E4. skill:publish \uAD8C\uD55C\uACFC confirm:true\uAC00 \uD544\uC694\uD569\uB2C8\uB2E4.",
-    inputSchema: z10.toJSONSchema(patSchemas.skillRelease),
+    inputSchema: z11.toJSONSchema(patSchemas.skillRelease),
     annotations: { readOnlyHint: false, destructiveHint: true }
   },
   {
     name: "platform_content_publish",
     description: "\uC2B9\uC778\uB41C \uB0B4 HTML \uCF58\uD150\uCE20 \uBC84\uC804\uC744 \uACF5\uAC1C\uD569\uB2C8\uB2E4. creator-content:publish \uAD8C\uD55C\uACFC confirm:true\uAC00 \uD544\uC694\uD569\uB2C8\uB2E4.",
-    inputSchema: z10.toJSONSchema(patSchemas.contentPublish),
+    inputSchema: z11.toJSONSchema(patSchemas.contentPublish),
     annotations: { readOnlyHint: false, destructiveHint: true }
   },
   {
     name: "platform_shared_collections_list",
     description: "\uB0B4 \uCF58\uD150\uCE20\uC758 \uC774\uC6A9\uC790 \uACF5\uAC1C(shared) \uBB38\uC11C \uCEEC\uB809\uC158 \uC774\uB984\uC744 \uC870\uD68C\uD569\uB2C8\uB2E4. platform:read \uAD8C\uD55C\uC774 \uD544\uC694\uD569\uB2C8\uB2E4.",
-    inputSchema: z10.toJSONSchema(patSchemas.sharedCollections),
+    inputSchema: z11.toJSONSchema(patSchemas.sharedCollections),
     annotations: { readOnlyHint: true, destructiveHint: false }
   },
   {
     name: "platform_shared_documents_list",
     description: "\uB0B4 \uCF58\uD150\uCE20\uC758 \uACF5\uC720 \uBB38\uC11C \uBAA9\uB85D\uC744 \uC870\uD68C\uD569\uB2C8\uB2E4. platform:read \uAD8C\uD55C\uC774 \uD544\uC694\uD569\uB2C8\uB2E4.",
-    inputSchema: z10.toJSONSchema(patSchemas.sharedList),
+    inputSchema: z11.toJSONSchema(patSchemas.sharedList),
     annotations: { readOnlyHint: true, destructiveHint: false }
   },
   {
     name: "platform_shared_document_get",
     description: "\uB0B4 \uCF58\uD150\uCE20\uC758 \uACF5\uC720 \uBB38\uC11C \uD558\uB098\uB97C \uC870\uD68C\uD569\uB2C8\uB2E4. platform:read \uAD8C\uD55C\uC774 \uD544\uC694\uD569\uB2C8\uB2E4.",
-    inputSchema: z10.toJSONSchema(patSchemas.sharedDocument),
+    inputSchema: z11.toJSONSchema(patSchemas.sharedDocument),
     annotations: { readOnlyHint: true, destructiveHint: false }
   },
   {
     name: "platform_shared_document_hide",
     description: "\uC774\uC6A9\uC790\uAC00 \uC4F4 \uACF5\uC720 \uBB38\uC11C\uB97C \uC228\uAE41\uB2C8\uB2E4. platform:write \uAD8C\uD55C\uACFC confirm:true\uAC00 \uD544\uC694\uD569\uB2C8\uB2E4.",
-    inputSchema: z10.toJSONSchema(patSchemas.sharedModerate),
+    inputSchema: z11.toJSONSchema(patSchemas.sharedModerate),
     annotations: { readOnlyHint: false, destructiveHint: true }
   },
   {
     name: "platform_shared_document_delete",
     description: "\uC774\uC6A9\uC790\uAC00 \uC4F4 \uACF5\uC720 \uBB38\uC11C\uB97C \uC601\uAD6C \uC0AD\uC81C\uD569\uB2C8\uB2E4. platform:write \uAD8C\uD55C\uACFC confirm:true\uAC00 \uD544\uC694\uD569\uB2C8\uB2E4.",
-    inputSchema: z10.toJSONSchema(patSchemas.sharedModerate),
+    inputSchema: z11.toJSONSchema(patSchemas.sharedModerate),
     annotations: { readOnlyHint: false, destructiveHint: true }
   }
 ];
@@ -6251,14 +6422,14 @@ function registerIntegrationCommands(program2, runtime2) {
 
 // src/commands/page.ts
 import { Option as Option3 } from "commander";
-import { z as z11 } from "zod";
-var uuid3 = (value2) => parse(z11.uuid(), value2);
-var revision3 = (value2) => parse(z11.coerce.number().int().nonnegative().max(4294967295), value2);
+import { z as z12 } from "zod";
+var uuid3 = (value2) => parse(z12.uuid(), value2);
+var revision3 = (value2) => parse(z12.coerce.number().int().nonnegative().max(4294967295), value2);
 var base = "/v4/creator/custom-pages";
-var presentationSchema = z11.object({
-  schema_version: z11.literal(1),
-  header_mode: z11.enum(["fixed", "scroll_hide", "translucent_scroll_hide", "floating_close", "floating_close_safe_area"]),
-  color_scheme: z11.enum(["light", "dark"])
+var presentationSchema = z12.object({
+  schema_version: z12.literal(1),
+  header_mode: z12.enum(["fixed", "scroll_hide", "translucent_scroll_hide", "floating_close", "floating_close_safe_area"]),
+  color_scheme: z12.enum(["light", "dark"])
 }).strict();
 function registerPageCommands(program2, runtime2) {
   const page = program2.command("page").description("\uC138\uACC4\uAD00\xB7\uB0B4 \uACF5\uAC1C \uD648 HTML \uAFB8\uBBF8\uAE30 (custom-page:read\xB7write\xB7publish)");
@@ -6266,7 +6437,7 @@ function registerPageCommands(program2, runtime2) {
   runtime2.action(page.command("status <id>").description("\uD398\uC774\uC9C0\uC640 \uBC84\uC804\xB7\uC218\uC815 \uBC88\uD638 \uC0C1\uD0DC (custom-page:read)"), async (ctx, [id2]) => ctx.output(await ctx.api.request("GET", `${base}/${uuid3(id2)}`)));
   runtime2.action(page.command("create").description("\uAFB8\uBC00 \uD398\uC774\uC9C0 \uB4F1\uB85D (custom-page:write)").addOption(new Option3("--target <type>", "\uAFB8\uBC00 \uB300\uC0C1").choices(["profile", "space"]).makeOptionMandatory()).option("--space-id <uuid>", "\uC138\uACC4\uAD00 ID").requiredOption("--policy-version <version>", "\uB3D9\uC758\uD55C \uCF58\uD150\uCE20 \uC81C\uACF5 \uC815\uCC45 \uBC84\uC804"), async (ctx, _args, opts) => {
     if (opts.target === "profile" && opts.spaceId) throw new CliError("\uB0B4 \uACF5\uAC1C \uD648\uC5D0\uB294 \uC138\uACC4\uAD00 ID\uB97C \uC9C0\uC815\uD558\uC9C0 \uC54A\uC2B5\uB2C8\uB2E4.");
-    const policy = parse(z11.literal("2026-09-22"), opts.policyVersion);
+    const policy = parse(z12.literal("2026-09-22"), opts.policyVersion);
     await mutate(ctx, "POST", base, { target_type: opts.target, ...opts.target === "space" ? { space_id: uuid3(opts.spaceId) } : {}, policy_version: policy });
   });
   runtime2.action(page.command("upload <id> <file>").description("HTML/ZIP \uC5C5\uB85C\uB4DC\uB85C \uC0C8 \uBE44\uACF5\uAC1C \uBC84\uC804 \uC0DD\uC131 (custom-page:write)").addOption(new Option3("--header <mode>", "\uD5E4\uB354 \uD45C\uC2DC").choices(["fixed", "scroll_hide", "translucent_scroll_hide", "floating_close", "floating_close_safe_area"]).default("fixed")).addOption(new Option3("--color <scheme>", "\uD5E4\uB354 \uC0C9\uC0C1").choices(["light", "dark"]).default("light")), async (ctx, [id2, file], opts) => {
@@ -6331,7 +6502,8 @@ try {
       status: failure.status,
       code: failure.code,
       message: failure.message,
-      ...failure.retryAfter ? { retry_after: failure.retryAfter } : {}
+      ...failure.retryAfter ? { retry_after: failure.retryAfter } : {},
+      ...failure.recovery ? { recovery: failure.recovery } : {}
     });
     const json2 = program.opts().json || process.argv.includes("--json") || await store.resolve(program.opts(), true).then((value2) => value2.options.json).catch(() => false);
     if (json2) process.stdout.write(JSON.stringify(envelope) + "\n");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clack-platform/cli",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "description": "클랙 계정의 상품·콘텐츠·프로필을 관리하는 CLI",
   "type": "module",
   "bin": {
@@ -39,7 +39,7 @@
     "test": "node scripts/test.mjs",
     "build": "tsup src/cli.ts --format esm --target node20 --clean",
     "check": "pnpm typecheck && node scripts/check-schema-sync.mjs && pnpm test && pnpm build",
-    "check:release": "pnpm typecheck && node scripts/check-schema-sync.mjs --strict && pnpm test && pnpm build",
+    "check:release": "pnpm typecheck && node scripts/check-schema-sync.mjs --strict && node scripts/sync-vendor-types.mjs --check && pnpm test && pnpm build",
     "prepack": "pnpm build"
   },
   "dependencies": {