connectbase-client 3.43.0 → 3.45.0

package/CHANGELOG.md

@@ -3,6 +3,38 @@
 본 SDK 의 모든 주요 변경사항을 [Keep a Changelog](https://keepachangelog.com/ko/1.1.0/) 형식으로 기록합니다.
 버전은 [Semantic Versioning](https://semver.org/lang/ko/) 을 따릅니다.
 
+## [3.44.0] - 2026-07-03
+
+### Added — CLI 비대화형 init + SDK 문서 수명주기 정비
+
+AI 에이전트(Claude Code 등)가 `init` 을 직접 실행할 수 있도록 비대화형 모드를 추가하고,
+`.claude/docs/` 문서의 신선도/정리 체계를 도입했다.
+
+- **비대화형 init**: `connectbase init --yes --secret-key cb_sk_...` — 프롬프트 없이 진행.
+  비TTY 환경에서 `--yes` 없이 실행하면 hang 대신 필요한 플래그를 안내하고 즉시 종료.
+  `--app <앱ID>`/`--storage <스토리지ID>`/`--deploy-dir <dir>` 로 명시 지정, `--yes` 는
+  프로젝트 이름과 같은 앱/스토리지가 있으면 재사용(반복 실행에 멱등). Secret Key 는
+  `CONNECTBASE_SECRET_KEY` 환경변수로도 전달 가능.
+- **Public Key 스프롤 방지**: `.connectbaserc` 에 `appId` 를 저장하고, 같은 앱을 다시 init
+  하면 기존 Public Key 를 재사용 (이전에는 실행마다 새 키 발급).
+- **문서 생성 스탬프 + 매니페스트**: `.claude/docs/` 파일에 생성 CLI 버전/날짜 스탬프를 넣고
+  `.connectbase-manifest.json` 으로 추적 — 콘텐츠 해시로 신선도 비교, 서버에서 사라진 문서
+  자동 정리(레거시 fullstack 파일 포함), `deploy` 성공 후 변경이 있을 때만 조용히 자동 갱신
+  (`--skip-docs` 로 생략 가능).
+- **CLAUDE.md @import**: 참조 블록이 `@.claude/docs/project-rules.md` import 로 규칙을 매
+  세션 자동 로드. MCP 미연결 시 `npx connectbase mcp` 안내 지시 포함. `mcp` 명령도 비대화형
+  지원(`--secret-key`/env/.connectbaserc 자동 사용).
+
+### Changed / Security
+
+- **키를 쿼리스트링에 싣지 않음**: 문서 다운로드가 `public_key` 쿼리 파라미터를 더 이상
+  전송하지 않는다 (서버 측 키 치환은 플레이스홀더 불일치로 오래전부터 무동작 — 액세스 로그에
+  키가 남는 위험만 있었음). `update` 의 secretKey fallback 도 제거.
+- 모든 CLI 요청에 `User-Agent: connectbase-cli/<version>` 명시.
+- `detectBuildDir`: Next.js 는 `output: 'export'` 미설정 시 경고 안내.
+- 버전 비교가 prerelease(`-beta.1`) 형식에서 NaN 이 되던 문제 수정.
+- `.gitignore` 항목 추가가 부분 문자열 오탐으로 건너뛰던 문제 수정 (라인 단위 정확 매칭).
+
 ## [3.43.0] - 2026-07-02
 
 ### Added — `--dev` 배포도 대용량 바이너리 지원

package/dist/cli.js

@@ -429,7 +429,10 @@ async function offloadLargeBinaries(baseStorageUrl, headers, diff, _envLabel, ti
   const presignFiles = largeBinaries.map((f) => ({
     path: f.path,
     size: Buffer.from(f.content, "base64").length,
-    mime_type: guessMimeType(f.path)
+    mime_type: guessMimeType(f.path),
+    // 신형 서버: hash 제공 시 content-addressed blob 키({id}/blobs/{hash})로 presign 되고,
+    // 동일 blob 이 이미 있으면 already_exists 로 업로드를 생략할 수 있다. 구버전 서버는 무시.
+    hash: f.hash
   }));
   let presigned;
   try {
@@ -445,22 +448,30 @@ async function offloadLargeBinaries(baseStorageUrl, headers, diff, _envLabel, ti
     warn(`\uB300\uC6A9\uB7C9 \uC5D0\uC14B\uC740 \uD30C\uC77C \uC2A4\uD1A0\uB9AC\uC9C0(${colors.cyan}cb.storage${colors.reset})\uC5D0 \uC62C\uB9AC\uACE0 URL \uB85C \uCC38\uC870\uD558\uAC70\uB098, \uC11C\uBC84 \uC5C5\uB370\uC774\uD2B8 \uD6C4 \uB2E4\uC2DC \uC2DC\uB3C4\uD558\uC138\uC694.`);
     process.exit(1);
   }
-  const urlByPath = new Map(presigned.map((p) => [p.path, p.upload_url]));
+  const entryByPath = new Map(presigned.map((p) => [p.path, p]));
   info(`\uB300\uC6A9\uB7C9 \uBC14\uC774\uB108\uB9AC ${largeBinaries.length}\uAC1C\uB97C Object Storage \uB85C \uC9C1\uC811 \uC5C5\uB85C\uB4DC\uD569\uB2C8\uB2E4...`);
   for (const f of largeBinaries) {
-    const uploadUrl = urlByPath.get(f.path);
-    if (!uploadUrl) {
-      error(`presign \uC751\uB2F5\uC5D0 \uC5C5\uB85C\uB4DC URL \uC774 \uC5C6\uC2B5\uB2C8\uB2E4: ${f.path}`);
+    const entry = entryByPath.get(f.path);
+    if (!entry) {
+      error(`presign \uC751\uB2F5\uC5D0 \uD56D\uBAA9\uC774 \uC5C6\uC2B5\uB2C8\uB2E4: ${f.path}`);
       process.exit(1);
     }
     const bytes = Buffer.from(f.content, "base64");
-    try {
-      await putToPresignedUrl(uploadUrl, bytes, guessMimeType(f.path), timeoutMs);
-    } catch (err) {
-      error(`\uC5C5\uB85C\uB4DC \uC2E4\uD328 (${f.path}): ${err instanceof Error ? err.message : err}`);
-      process.exit(1);
+    if (entry.already_exists) {
+      success(`\uC5C5\uB85C\uB4DC \uC0DD\uB7B5(\uAE30\uC874 blob \uC7AC\uC0AC\uC6A9): ${f.path} (${formatSize(bytes.length)})`);
+    } else {
+      if (!entry.upload_url) {
+        error(`presign \uC751\uB2F5\uC5D0 \uC5C5\uB85C\uB4DC URL \uC774 \uC5C6\uC2B5\uB2C8\uB2E4: ${f.path}`);
+        process.exit(1);
+      }
+      try {
+        await putToPresignedUrl(entry.upload_url, bytes, guessMimeType(f.path), timeoutMs);
+      } catch (err) {
+        error(`\uC5C5\uB85C\uB4DC \uC2E4\uD328 (${f.path}): ${err instanceof Error ? err.message : err}`);
+        process.exit(1);
+      }
+      success(`\uC9C1\uC811 \uC5C5\uB85C\uB4DC: ${f.path} (${formatSize(bytes.length)})`);
     }
-    success(`\uC9C1\uC811 \uC5C5\uB85C\uB4DC: ${f.path} (${formatSize(bytes.length)})`);
     f.pre_uploaded = true;
     f.size = bytes.length;
     f.content = "";
@@ -525,6 +536,8 @@ async function makeRequest(url, method, headers, body, reqOpts = {}) {
       family: 4,
       autoSelectFamily: false,
       headers: {
+        // 명시적 UA: 관측성 + WAF 봇 휴리스틱(비브라우저 UA 차단 규칙)과의 충돌 방지
+        "User-Agent": `connectbase-cli/${VERSION}`,
         ...headers,
         "Content-Type": "application/json",
         ...bodyBuffer ? { "Content-Length": bodyBuffer.length } : {}
@@ -741,8 +754,25 @@ async function fullDeploy(baseStorageUrl, headers, files, envLabel, endpoint, ti
 }
 function handleDeployResponse(response, envLabel) {
   if (response.status >= 200 && response.status < 300) {
-    success(`${envLabel} \uBC30\uD3EC \uC644\uB8CC!`);
     const data = response.data;
+    const dep = data?.deployment ?? null;
+    if (dep?.deployment_id) {
+      if (dep.promoted) {
+        success(`${envLabel} \uBC30\uD3EC \uC644\uB8CC! (release #${dep.seq})`);
+        if (dep.production_url) log(`
+${colors.cyan}Production: ${dep.production_url}${colors.reset}`);
+        if (dep.qa_url) log(`${colors.dim}QA:         ${dep.qa_url}${colors.reset}
+`);
+      } else {
+        success(`QA \uD658\uACBD\uC5D0 \uBC30\uD3EC\uB418\uC5C8\uC2B5\uB2C8\uB2E4 (release #${dep.seq}) \u2014 production \uC740 \uC544\uC9C1 \uC774\uC804 \uBC84\uC804\uC785\uB2C8\uB2E4`);
+        if (dep.qa_url) log(`
+${colors.yellow}QA URL:  ${dep.qa_url}${colors.reset}`);
+        log(`${colors.dim}\uAC80\uC99D \uD6C4 \uBC18\uC601: ${colors.cyan}npx connectbase promote${colors.reset}
+`);
+      }
+      return;
+    }
+    success(`${envLabel} \uBC30\uD3EC \uC644\uB8CC!`);
     if (data?.dev_url) {
       log(`
 ${colors.yellow}Dev URL: ${data.dev_url}${colors.reset}
@@ -759,6 +789,64 @@ ${colors.cyan}URL: ${data.url}${colors.reset}
     process.exit(1);
   }
 }
+async function promote(config, deploymentId) {
+  const baseStorageUrl = `${config.baseUrl}/v1/public/storages/webs/${config.storageId}`;
+  const headers = { "X-Public-Key": config.publicKey };
+  info(deploymentId ? `release ${deploymentId} \uB97C production \uC73C\uB85C \uC2B9\uACA9\uD569\uB2C8\uB2E4...` : "\uCD5C\uC2E0 \uBC30\uD3EC\uB97C production \uC73C\uB85C \uC2B9\uACA9\uD569\uB2C8\uB2E4...");
+  const body = JSON.stringify(deploymentId ? { deployment_id: deploymentId } : {});
+  const res = await makeRequest(`${baseStorageUrl}/promote`, "POST", headers, body);
+  if (res.status === 404 && !res.data?.error) {
+    error("\uC11C\uBC84\uAC00 promote \uB97C \uC9C0\uC6D0\uD558\uC9C0 \uC54A\uC2B5\uB2C8\uB2E4 (\uAD6C\uBC84\uC804 \uC11C\uBC84) \u2014 \uC11C\uBC84 \uC5C5\uB370\uC774\uD2B8 \uD6C4 \uB2E4\uC2DC \uC2DC\uB3C4\uD558\uC138\uC694");
+    process.exit(1);
+  }
+  if (res.status < 200 || res.status >= 300) {
+    const data2 = res.data;
+    const msg = typeof data2 === "object" && data2 !== null ? data2.error || data2.message || JSON.stringify(data2) : `HTTP ${res.status}`;
+    error(`promote \uC2E4\uD328: ${msg}`);
+    process.exit(1);
+  }
+  const data = res.data;
+  success(`production \uC2B9\uACA9 \uC644\uB8CC! (release #${data.seq})`);
+  if (data.production_url) {
+    log(`
+${colors.cyan}Production: ${data.production_url}${colors.reset}
+`);
+  }
+}
+async function listReleases(config) {
+  const baseStorageUrl = `${config.baseUrl}/v1/public/storages/webs/${config.storageId}`;
+  const headers = { "X-Public-Key": config.publicKey };
+  const res = await makeRequest(`${baseStorageUrl}/deployments`, "GET", headers);
+  if (res.status < 200 || res.status >= 300) {
+    const data2 = res.data;
+    const msg = typeof data2 === "object" && data2 !== null ? data2.error || data2.message || JSON.stringify(data2) : `HTTP ${res.status}`;
+    error(`\uBC30\uD3EC \uC774\uB825 \uC870\uD68C \uC2E4\uD328: ${msg}`);
+    process.exit(1);
+  }
+  const data = res.data;
+  if (!data.deployments || data.deployments.length === 0) {
+    info("\uBC30\uD3EC \uC774\uB825\uC774 \uC5C6\uC2B5\uB2C8\uB2E4. \uBA3C\uC800 deploy \uD558\uC138\uC694.");
+    return;
+  }
+  log(`
+${colors.cyan}\uBC30\uD3EC \uC774\uB825${colors.reset} (promote_mode: ${data.promote_mode || "auto"}, \uCD1D ${data.total}\uAC1C)
+`);
+  for (const d of data.deployments) {
+    const markers = [];
+    if (d.is_production) markers.push(`${colors.green}production${colors.reset}`);
+    if (d.is_qa) markers.push(`${colors.yellow}qa${colors.reset}`);
+    const marker = markers.length > 0 ? ` \u2190 ${markers.join(", ")}` : "";
+    const statusColor = d.status === "ready" ? colors.green : d.status === "failed" ? colors.red : colors.yellow;
+    log(
+      `  #${String(d.seq).padEnd(4)} ${statusColor}${d.status.padEnd(9)}${colors.reset} ${String(d.file_count).padStart(4)}\uAC1C ${formatSize(d.total_size).padStart(9)}  ${d.created_at}  ${colors.dim}${d.id}${colors.reset}${marker}`
+    );
+  }
+  log("");
+  if (data.production_url) log(`${colors.cyan}Production: ${data.production_url}${colors.reset}`);
+  if (data.qa_url) log(`${colors.yellow}QA:         ${data.qa_url}${colors.reset}`);
+  log(`${colors.dim}\uB864\uBC31: npx connectbase promote <deployment_id>${colors.reset}
+`);
+}
 function prompt(question) {
   const rl = readline.createInterface({
     input: process.stdin,
@@ -905,7 +993,7 @@ ${colors.cyan}\uBE0C\uB77C\uC6B0\uC800\uC5D0\uC11C \uB85C\uADF8\uC778\uD558\uC13
   error("\uC778\uC99D \uC2DC\uAC04\uC774 \uCD08\uACFC\uB418\uC5C8\uC2B5\uB2C8\uB2E4. \uB2E4\uC2DC \uC2DC\uB3C4\uD574\uC8FC\uC138\uC694.");
   process.exit(1);
 }
-async function init() {
+async function init(config = {}, opts = {}) {
   log(`
 ${colors.cyan}Connect Base \uD504\uB85C\uC81D\uD2B8 \uCD08\uAE30\uD654${colors.reset}
 `);
@@ -916,49 +1004,104 @@ ${colors.cyan}Connect Base \uD504\uB85C\uC81D\uD2B8 \uCD08\uAE30\uD654${colors.r
     info(`MCP/\uBB38\uC11C\uB294 \uD504\uB85C\uC81D\uD2B8 \uB8E8\uD2B8\uC5D0, \uBC30\uD3EC \uC124\uC815\uC740 \uD604\uC7AC \uB514\uB809\uD1A0\uB9AC\uC5D0 \uC0DD\uC131\uB429\uB2C8\uB2E4
 `);
   }
+  const nonInteractive = opts.yes === true;
+  if (!process.stdin.isTTY && !nonInteractive) {
+    error("\uBE44\uB300\uD654\uD615 \uD658\uACBD\uC785\uB2C8\uB2E4. --yes \uD50C\uB798\uADF8\uC640 \uD568\uAED8 \uD544\uC694\uD55C \uAC12\uC744 \uC9C0\uC815\uD558\uC138\uC694");
+    log(`${colors.dim}\uC608: npx connectbase init --yes --secret-key cb_sk_... [--app <\uC571ID>] [--storage <\uC2A4\uD1A0\uB9AC\uC9C0ID>] [--deploy-dir ./dist]${colors.reset}`);
+    log(`${colors.dim}Secret Key\uB294 CONNECTBASE_SECRET_KEY \uD658\uACBD\uBCC0\uC218\uB85C\uB3C4 \uC804\uB2EC\uD560 \uC218 \uC788\uC2B5\uB2C8\uB2E4${colors.reset}`);
+    process.exit(1);
+  }
   const rcPath = path2.join(cwd, ".connectbaserc");
+  let existingRc = {};
   if (fs2.existsSync(rcPath)) {
-    const overwrite = await prompt(`${colors.yellow}\u26A0${colors.reset} .connectbaserc\uAC00 \uC774\uBBF8 \uC874\uC7AC\uD569\uB2C8\uB2E4. \uB36E\uC5B4\uC4F0\uC2DC\uACA0\uC2B5\uB2C8\uAE4C? (y/N): `);
-    if (overwrite.toLowerCase() !== "y") {
-      info("\uCD08\uAE30\uD654\uAC00 \uCDE8\uC18C\uB418\uC5C8\uC2B5\uB2C8\uB2E4");
-      return;
+    try {
+      existingRc = JSON.parse(fs2.readFileSync(rcPath, "utf-8"));
+    } catch {
+    }
+    if (nonInteractive) {
+      if (!opts.force) {
+        error(".connectbaserc\uAC00 \uC774\uBBF8 \uC874\uC7AC\uD569\uB2C8\uB2E4. \uB36E\uC5B4\uC4F0\uB824\uBA74 --force\uB97C \uD568\uAED8 \uC0AC\uC6A9\uD558\uC138\uC694");
+        process.exit(1);
+      }
+    } else {
+      const overwrite = await prompt(`${colors.yellow}\u26A0${colors.reset} .connectbaserc\uAC00 \uC774\uBBF8 \uC874\uC7AC\uD569\uB2C8\uB2E4. \uB36E\uC5B4\uC4F0\uC2DC\uACA0\uC2B5\uB2C8\uAE4C? (y/N): `);
+      if (overwrite.toLowerCase() !== "y") {
+        info("\uCD08\uAE30\uD654\uAC00 \uCDE8\uC18C\uB418\uC5C8\uC2B5\uB2C8\uB2E4");
+        return;
+      }
     }
   }
-  log(`
-${colors.dim}\uC778\uC99D \uBC29\uC2DD\uC744 \uC120\uD0DD\uD558\uC138\uC694:${colors.reset}`);
-  log(`  ${colors.cyan}1${colors.reset}) Secret Key \uC9C1\uC811 \uC785\uB825 (cb_sk_...)`);
-  log(`  ${colors.cyan}2${colors.reset}) \uBE0C\uB77C\uC6B0\uC800 \uB85C\uADF8\uC778\uC73C\uB85C \uC790\uB3D9 \uBC1C\uAE09
-`);
-  const authChoice = await prompt(`${colors.blue}?${colors.reset} \uC120\uD0DD (1/2): `);
-  let secretKey = "";
-  if (authChoice === "2") {
-    try {
-      secretKey = await browserAuthFlow();
-    } catch (err) {
-      error(`\uB124\uD2B8\uC6CC\uD06C \uC624\uB958: ${err instanceof Error ? err.message : err}`);
-      info("\uC778\uD130\uB137 \uC5F0\uACB0\uC744 \uD655\uC778\uD558\uAC70\uB098, Secret Key \uC9C1\uC811 \uC785\uB825(\uC635\uC158 1)\uC744 \uC2DC\uB3C4\uD558\uC138\uC694");
+  let secretKey = config.secretKey || "";
+  if (secretKey) {
+    if (!secretKey.startsWith("cb_sk_")) {
+      error("\uC720\uD6A8\uD558\uC9C0 \uC54A\uC740 \uD0A4 \uD615\uC2DD\uC785\uB2C8\uB2E4. cb_sk_\uB85C \uC2DC\uC791\uD558\uB294 Secret Key\uB97C \uC9C0\uC815\uD558\uC138\uC694");
       process.exit(1);
     }
+    info("Secret Key \uD655\uC778\uB428 (\uD50C\uB798\uADF8/\uD658\uACBD\uBCC0\uC218/.connectbaserc)");
+  } else if (nonInteractive) {
+    error("Secret Key\uAC00 \uD544\uC694\uD569\uB2C8\uB2E4: --secret-key cb_sk_... \uB610\uB294 CONNECTBASE_SECRET_KEY \uD658\uACBD\uBCC0\uC218");
+    process.exit(1);
   } else {
-    log(`${colors.dim}Secret Key (cb_sk_): \uCF58\uC194 > \uD504\uB85C\uD544 > \uC2DC\uD06C\uB9BF \uD0A4 \uD0ED\uC5D0\uC11C \uBC1C\uAE09${colors.reset}
+    log(`
+${colors.dim}\uC778\uC99D \uBC29\uC2DD\uC744 \uC120\uD0DD\uD558\uC138\uC694:${colors.reset}`);
+    log(`  ${colors.cyan}1${colors.reset}) Secret Key \uC9C1\uC811 \uC785\uB825 (cb_sk_...)`);
+    log(`  ${colors.cyan}2${colors.reset}) \uBE0C\uB77C\uC6B0\uC800 \uB85C\uADF8\uC778\uC73C\uB85C \uC790\uB3D9 \uBC1C\uAE09
 `);
-    secretKey = await promptSecret(`${colors.blue}?${colors.reset} Secret Key: `);
-    if (!secretKey) {
-      error("Secret Key\uB294 \uD544\uC218\uC785\uB2C8\uB2E4");
-      process.exit(1);
-    }
-    if (secretKey.startsWith("cb_pk_")) {
-      error("Public Key\uAC00 \uC544\uB2CC Secret Key(cb_sk_)\uB97C \uC785\uB825\uD558\uC138\uC694");
-      info("Secret Key\uB294 \uCF58\uC194 > \uD504\uB85C\uD544 > \uC2DC\uD06C\uB9BF \uD0A4 \uD0ED\uC5D0\uC11C \uC0DD\uC131\uD560 \uC218 \uC788\uC2B5\uB2C8\uB2E4");
-      process.exit(1);
-    }
-    if (!secretKey.startsWith("cb_sk_")) {
-      error("\uC720\uD6A8\uD558\uC9C0 \uC54A\uC740 \uD0A4 \uD615\uC2DD\uC785\uB2C8\uB2E4. cb_sk_\uB85C \uC2DC\uC791\uD558\uB294 Secret Key\uB97C \uC785\uB825\uD558\uC138\uC694");
-      process.exit(1);
+    const authChoice = await prompt(`${colors.blue}?${colors.reset} \uC120\uD0DD (1/2): `);
+    if (authChoice === "2") {
+      try {
+        secretKey = await browserAuthFlow();
+      } catch (err) {
+        error(`\uB124\uD2B8\uC6CC\uD06C \uC624\uB958: ${err instanceof Error ? err.message : err}`);
+        info("\uC778\uD130\uB137 \uC5F0\uACB0\uC744 \uD655\uC778\uD558\uAC70\uB098, Secret Key \uC9C1\uC811 \uC785\uB825(\uC635\uC158 1)\uC744 \uC2DC\uB3C4\uD558\uC138\uC694");
+        process.exit(1);
+      }
+    } else {
+      log(`${colors.dim}Secret Key (cb_sk_): \uCF58\uC194 > \uD504\uB85C\uD544 > \uC2DC\uD06C\uB9BF \uD0A4 \uD0ED\uC5D0\uC11C \uBC1C\uAE09${colors.reset}
+`);
+      secretKey = await promptSecret(`${colors.blue}?${colors.reset} Secret Key: `);
+      if (!secretKey) {
+        error("Secret Key\uB294 \uD544\uC218\uC785\uB2C8\uB2E4");
+        process.exit(1);
+      }
+      if (secretKey.startsWith("cb_pk_")) {
+        error("Public Key\uAC00 \uC544\uB2CC Secret Key(cb_sk_)\uB97C \uC785\uB825\uD558\uC138\uC694");
+        info("Secret Key\uB294 \uCF58\uC194 > \uD504\uB85C\uD544 > \uC2DC\uD06C\uB9BF \uD0A4 \uD0ED\uC5D0\uC11C \uC0DD\uC131\uD560 \uC218 \uC788\uC2B5\uB2C8\uB2E4");
+        process.exit(1);
+      }
+      if (!secretKey.startsWith("cb_sk_")) {
+        error("\uC720\uD6A8\uD558\uC9C0 \uC54A\uC740 \uD0A4 \uD615\uC2DD\uC785\uB2C8\uB2E4. cb_sk_\uB85C \uC2DC\uC791\uD558\uB294 Secret Key\uB97C \uC785\uB825\uD558\uC138\uC694");
+        process.exit(1);
+      }
     }
   }
   let appId = "";
   let publicKey = "";
+  const projectName = path2.basename(cwd);
+  const reuseKeyIfSameApp = (selectedAppId) => {
+    if (existingRc.appId === selectedAppId && existingRc.publicKey?.startsWith("cb_pk_")) {
+      publicKey = existingRc.publicKey;
+      success("\uAE30\uC874 Public Key \uC7AC\uC0AC\uC6A9 (.connectbaserc)");
+      return true;
+    }
+    return false;
+  };
+  const issuePublicKey = async (targetAppId) => {
+    info("Public Key \uC0DD\uC131 \uC911...");
+    const newKeyRes = await makeRequest(
+      `${DEFAULT_BASE_URL}/v1/public/cli/apps/${targetAppId}/public-keys`,
+      "POST",
+      { "X-Public-Key": secretKey },
+      JSON.stringify({})
+    );
+    if (newKeyRes.status === 201) {
+      const keyData = newKeyRes.data;
+      publicKey = keyData.key;
+      success("Public Key \uBC1C\uAE09 \uC644\uB8CC");
+    } else {
+      warn("Public Key \uC790\uB3D9 \uC0DD\uC131 \uC2E4\uD328. \uC218\uB3D9\uC73C\uB85C \uC0DD\uC131\uD558\uC138\uC694");
+    }
+  };
   try {
     info("\uC571 \uBAA9\uB85D \uC870\uD68C \uC911...");
     const appsRes = await makeRequest(
@@ -975,7 +1118,23 @@ ${colors.dim}\uC778\uC99D \uBC29\uC2DD\uC744 \uC120\uD0DD\uD558\uC138\uC694:${co
     }
     const appsData = appsRes.data;
     const apps = appsData.apps || [];
-    if (apps.length > 0) {
+    if (opts.appId) {
+      const found = apps.find((a) => a.id === opts.appId);
+      if (!found) {
+        error(`\uC9C0\uC815\uD55C \uC571\uC744 \uCC3E\uC744 \uC218 \uC5C6\uC2B5\uB2C8\uB2E4: ${opts.appId}`);
+        process.exit(1);
+      }
+      appId = found.id;
+      success(`\uC120\uD0DD\uB428: ${found.name}`);
+      if (!reuseKeyIfSameApp(appId)) await issuePublicKey(appId);
+    } else if (nonInteractive) {
+      const found = apps.find((a) => a.name === projectName);
+      if (found) {
+        appId = found.id;
+        success(`\uAE30\uC874 \uC571 \uC7AC\uC0AC\uC6A9: ${found.name}`);
+        if (!reuseKeyIfSameApp(appId)) await issuePublicKey(appId);
+      }
+    } else if (apps.length > 0) {
       log(`
 ${colors.dim}\uB0B4 \uC571 \uBAA9\uB85D:${colors.reset}`);
       apps.forEach((a, i) => {
@@ -989,25 +1148,11 @@ ${colors.blue}?${colors.reset} \uC120\uD0DD (\uBC88\uD638): `);
       if (num > 0 && num <= apps.length) {
         appId = apps[num - 1].id;
         success(`\uC120\uD0DD\uB428: ${apps[num - 1].name}`);
-        info("Public Key \uC0DD\uC131 \uC911...");
-        const newKeyRes = await makeRequest(
-          `${DEFAULT_BASE_URL}/v1/public/cli/apps/${appId}/public-keys`,
-          "POST",
-          { "X-Public-Key": secretKey },
-          JSON.stringify({})
-        );
-        if (newKeyRes.status === 201) {
-          const keyData = newKeyRes.data;
-          publicKey = keyData.key;
-          success("Public Key \uBC1C\uAE09 \uC644\uB8CC");
-        } else {
-          warn("Public Key \uC790\uB3D9 \uC0DD\uC131 \uC2E4\uD328. \uC218\uB3D9\uC73C\uB85C \uC0DD\uC131\uD558\uC138\uC694");
-        }
+        if (!reuseKeyIfSameApp(appId)) await issuePublicKey(appId);
       }
     }
     if (!appId) {
-      const projectName = path2.basename(cwd);
-      const appName = await prompt(`${colors.blue}?${colors.reset} \uC571 \uC774\uB984 (${projectName}): `) || projectName;
+      const appName = nonInteractive ? projectName : await prompt(`${colors.blue}?${colors.reset} \uC571 \uC774\uB984 (${projectName}): `) || projectName;
       info("\uC571 \uC0DD\uC131 \uC911...");
       const createRes = await makeRequest(
         `${DEFAULT_BASE_URL}/v1/public/cli/apps`,
@@ -1034,6 +1179,10 @@ ${colors.blue}?${colors.reset} \uC120\uD0DD (\uBC88\uD638): `);
     }
   } catch (err) {
     error(`\uB124\uD2B8\uC6CC\uD06C \uC624\uB958: ${err instanceof Error ? err.message : err}`);
+    if (nonInteractive) {
+      info("\uB124\uD2B8\uC6CC\uD06C \uBCF5\uAD6C \uD6C4 \uB2E4\uC2DC \uC2DC\uB3C4\uD558\uAC70\uB098, \uCF58\uC194\uC5D0\uC11C \uBC1C\uAE09\uD55C \uAC12\uC73C\uB85C .connectbaserc\uB97C \uC9C1\uC811 \uC791\uC131\uD558\uC138\uC694");
+      process.exit(1);
+    }
     log(`${colors.dim}\uC218\uB3D9\uC73C\uB85C \uC785\uB825\uD558\uC138\uC694${colors.reset}`);
     appId = await prompt(`${colors.blue}?${colors.reset} App ID: `);
     publicKey = await prompt(`${colors.blue}?${colors.reset} Public Key (cb_pk_): `);
@@ -1048,77 +1197,92 @@ ${colors.blue}?${colors.reset} \uC120\uD0DD (\uBC88\uD638): `);
   }
   const publicKeyForSdk = publicKey;
   let storageId = "";
-  try {
-    info("\uC6F9 \uC2A4\uD1A0\uB9AC\uC9C0 \uC870\uD68C \uC911...");
-    const listRes = await makeRequest(
-      `${DEFAULT_BASE_URL}/v1/public/storages/webs`,
-      "GET",
-      { "X-Public-Key": publicKeyForSdk }
-    );
-    if (listRes.status === 200) {
-      const listData = listRes.data;
-      const storages = listData.storages || [];
-      if (storages.length > 0) {
-        log(`
+  if (opts.storageId) {
+    storageId = opts.storageId;
+    success(`\uC6F9 \uC2A4\uD1A0\uB9AC\uC9C0 \uC9C0\uC815\uB428: ${storageId}`);
+  } else {
+    try {
+      info("\uC6F9 \uC2A4\uD1A0\uB9AC\uC9C0 \uC870\uD68C \uC911...");
+      const listRes = await makeRequest(
+        `${DEFAULT_BASE_URL}/v1/public/storages/webs`,
+        "GET",
+        { "X-Public-Key": publicKeyForSdk }
+      );
+      if (listRes.status === 200) {
+        const listData = listRes.data;
+        const storages = listData.storages || [];
+        if (nonInteractive) {
+          const found = storages.find((s) => s.name === projectName);
+          if (found) {
+            storageId = found.id;
+            success(`\uAE30\uC874 \uC6F9 \uC2A4\uD1A0\uB9AC\uC9C0 \uC7AC\uC0AC\uC6A9: ${found.name}`);
+          }
+        } else if (storages.length > 0) {
+          log(`
 ${colors.dim}\uAE30\uC874 \uC6F9 \uC2A4\uD1A0\uB9AC\uC9C0:${colors.reset}`);
-        storages.forEach((s, i) => {
-          log(`  ${colors.cyan}${i + 1}${colors.reset}) ${s.name} (${colors.dim}${s.id}${colors.reset})`);
-        });
-        log(`  ${colors.cyan}0${colors.reset}) \uC0C8\uB85C \uC0DD\uC131`);
-        const choice = await prompt(`
+          storages.forEach((s, i) => {
+            log(`  ${colors.cyan}${i + 1}${colors.reset}) ${s.name} (${colors.dim}${s.id}${colors.reset})`);
+          });
+          log(`  ${colors.cyan}0${colors.reset}) \uC0C8\uB85C \uC0DD\uC131`);
+          const choice = await prompt(`
 ${colors.blue}?${colors.reset} \uC120\uD0DD (\uBC88\uD638): `);
-        const num = parseInt(choice, 10);
-        if (num > 0 && num <= storages.length) {
-          storageId = storages[num - 1].id;
-          success(`\uC120\uD0DD\uB428: ${storages[num - 1].name}`);
+          const num = parseInt(choice, 10);
+          if (num > 0 && num <= storages.length) {
+            storageId = storages[num - 1].id;
+            success(`\uC120\uD0DD\uB428: ${storages[num - 1].name}`);
+          }
         }
+        if (!storageId) {
+          const name = nonInteractive ? projectName : await prompt(`${colors.blue}?${colors.reset} \uC2A4\uD1A0\uB9AC\uC9C0 \uC774\uB984 (${projectName}): `) || projectName;
+          info("\uC6F9 \uC2A4\uD1A0\uB9AC\uC9C0 \uC0DD\uC131 \uC911...");
+          const createRes = await makeRequest(
+            `${DEFAULT_BASE_URL}/v1/public/storages/webs`,
+            "POST",
+            { "X-Public-Key": publicKeyForSdk },
+            JSON.stringify({ name })
+          );
+          if (createRes.status !== 200) {
+            const data = createRes.data;
+            error(`\uC0DD\uC131 \uC2E4\uD328: ${data?.error || data?.message || `HTTP ${createRes.status}`}`);
+            process.exit(1);
+          }
+          const createData = createRes.data;
+          storageId = createData.storage_web_id;
+          success(`\uC6F9 \uC2A4\uD1A0\uB9AC\uC9C0 \uC0DD\uC131 \uC644\uB8CC: ${createData.name}`);
+        }
+      } else {
+        throw new Error(`HTTP ${listRes.status}`);
       }
+    } catch (err) {
+      error(`\uB124\uD2B8\uC6CC\uD06C \uC624\uB958: ${err instanceof Error ? err.message : err}`);
+      if (nonInteractive) {
+        info("\uB124\uD2B8\uC6CC\uD06C \uBCF5\uAD6C \uD6C4 \uB2E4\uC2DC \uC2DC\uB3C4\uD558\uAC70\uB098, --storage <\uC2A4\uD1A0\uB9AC\uC9C0ID>\uC640 \uD568\uAED8 \uC2E4\uD589\uD558\uC138\uC694");
+        process.exit(1);
+      }
+      log(`${colors.dim}\uC218\uB3D9\uC73C\uB85C Storage ID\uB97C \uC785\uB825\uD558\uC138\uC694${colors.reset}`);
+      storageId = await prompt(`${colors.blue}?${colors.reset} Storage ID: `);
       if (!storageId) {
-        const projectName = path2.basename(cwd);
-        const name = await prompt(`${colors.blue}?${colors.reset} \uC2A4\uD1A0\uB9AC\uC9C0 \uC774\uB984 (${projectName}): `) || projectName;
-        info("\uC6F9 \uC2A4\uD1A0\uB9AC\uC9C0 \uC0DD\uC131 \uC911...");
-        const createRes = await makeRequest(
-          `${DEFAULT_BASE_URL}/v1/public/storages/webs`,
-          "POST",
-          { "X-Public-Key": publicKeyForSdk },
-          JSON.stringify({ name })
-        );
-        if (createRes.status !== 200) {
-          const data = createRes.data;
-          error(`\uC0DD\uC131 \uC2E4\uD328: ${data?.error || data?.message || `HTTP ${createRes.status}`}`);
-          process.exit(1);
-        }
-        const createData = createRes.data;
-        storageId = createData.storage_web_id;
-        success(`\uC6F9 \uC2A4\uD1A0\uB9AC\uC9C0 \uC0DD\uC131 \uC644\uB8CC: ${createData.name}`);
+        error("Storage ID\uB294 \uD544\uC218\uC785\uB2C8\uB2E4");
+        process.exit(1);
       }
-    } else {
-      throw new Error(`HTTP ${listRes.status}`);
-    }
-  } catch (err) {
-    error(`\uB124\uD2B8\uC6CC\uD06C \uC624\uB958: ${err instanceof Error ? err.message : err}`);
-    log(`${colors.dim}\uC218\uB3D9\uC73C\uB85C Storage ID\uB97C \uC785\uB825\uD558\uC138\uC694${colors.reset}`);
-    storageId = await prompt(`${colors.blue}?${colors.reset} Storage ID: `);
-    if (!storageId) {
-      error("Storage ID\uB294 \uD544\uC218\uC785\uB2C8\uB2E4");
-      process.exit(1);
     }
   }
-  const defaultDir = detectBuildDir();
-  const deployDir = await prompt(`${colors.blue}?${colors.reset} \uBC30\uD3EC \uB514\uB809\uD1A0\uB9AC (${defaultDir}): `) || defaultDir;
-  const config = {
+  const defaultDir = opts.deployDir || detectBuildDir();
+  const deployDir = nonInteractive ? defaultDir : await prompt(`${colors.blue}?${colors.reset} \uBC30\uD3EC \uB514\uB809\uD1A0\uB9AC (${defaultDir}): `) || defaultDir;
+  const rcData = {
+    appId,
     publicKey: publicKey || "",
     storageId,
     deployDir
   };
   if (secretKey) {
-    config.secretKey = secretKey;
+    rcData.secretKey = secretKey;
   }
-  fs2.writeFileSync(rcPath, JSON.stringify(config, null, 2) + "\n");
+  fs2.writeFileSync(rcPath, JSON.stringify(rcData, null, 2) + "\n");
   success(".connectbaserc \uC0DD\uC131 \uC644\uB8CC");
   addToGitignore(".connectbaserc");
   addDeployScript(deployDir);
-  await setupClaudeCode(publicKeyForSdk, secretKey, projectRoot);
+  await setupClaudeCode(secretKey, projectRoot);
   log(`
 ${colors.green}\uCD08\uAE30\uD654 \uC644\uB8CC!${colors.reset}
 `);
@@ -1132,9 +1296,20 @@ function detectBuildDir() {
   if (fs2.existsSync(path2.join(process.cwd(), "dist"))) return "./dist";
   if (fs2.existsSync(path2.join(process.cwd(), "build"))) return "./build";
   if (fs2.existsSync(path2.join(process.cwd(), "out"))) return "./out";
-  if (fs2.existsSync(path2.join(process.cwd(), ".next"))) return "./out";
+  const nextConfig = ["next.config.js", "next.config.mjs", "next.config.ts"].map((f) => path2.join(process.cwd(), f)).find((f) => fs2.existsSync(f));
+  if (nextConfig || fs2.existsSync(path2.join(process.cwd(), ".next"))) {
+    if (nextConfig) {
+      try {
+        const src = fs2.readFileSync(nextConfig, "utf-8");
+        if (!/output\s*:\s*['"]export['"]/.test(src)) {
+          warn(`Next.js \uAC10\uC9C0: \uC815\uC801 \uBC30\uD3EC\uD558\uB824\uBA74 ${path2.basename(nextConfig)}\uC5D0 output: 'export' \uC124\uC815\uC774 \uD544\uC694\uD569\uB2C8\uB2E4`);
+        }
+      } catch {
+      }
+    }
+    return "./out";
+  }
   if (fs2.existsSync(path2.join(process.cwd(), "vite.config.ts")) || fs2.existsSync(path2.join(process.cwd(), "vite.config.js"))) return "./dist";
-  if (fs2.existsSync(path2.join(process.cwd(), "next.config.js")) || fs2.existsSync(path2.join(process.cwd(), "next.config.mjs"))) return "./out";
   return "./dist";
 }
 function addToGitignore(entry, basePath) {
@@ -1142,7 +1317,8 @@ function addToGitignore(entry, basePath) {
   const gitignorePath = path2.join(dir, ".gitignore");
   if (fs2.existsSync(gitignorePath)) {
     const content = fs2.readFileSync(gitignorePath, "utf-8");
-    if (!content.includes(entry)) {
+    const lines = content.split(/\r?\n/).map((l) => l.trim());
+    if (!lines.includes(entry)) {
       fs2.appendFileSync(gitignorePath, `
 # Connect Base
 ${entry}
@@ -1223,13 +1399,66 @@ function detectMonorepo(gitRoot) {
   }
   return result;
 }
-async function downloadDocs(publicKey, templates, baseDir) {
+var DOCS_MANIFEST_FILE = ".connectbase-manifest.json";
+function readDocsManifest(docsDir) {
+  try {
+    const parsed = JSON.parse(fs2.readFileSync(path2.join(docsDir, DOCS_MANIFEST_FILE), "utf-8"));
+    if (parsed && Array.isArray(parsed.files)) return parsed;
+  } catch {
+  }
+  return null;
+}
+var LEGACY_DOC_FILES = [
+  "intro.md",
+  "mcp-workflow.md",
+  "sdk-basic.md",
+  "sdk-database.md",
+  "sdk-storage.md",
+  "sdk-realtime.md",
+  "sdk-auth.md",
+  "sdk-payment.md",
+  "example.md",
+  "mcp-config.md",
+  "mcp-tools.md",
+  "resources.md",
+  "sdk-game.md",
+  "sdk-push.md",
+  "sdk-video.md",
+  "sdk-ads.md",
+  "sdk-ai.md",
+  "sdk-error-tracker.md",
+  "sdk-webrtc.md",
+  "sdk-subscription.md",
+  "sdk-functions.md",
+  "sdk-webhooks.md",
+  "deploy-guide.md",
+  "app-packaging.md",
+  "best-practices.md",
+  "code-analysis.md",
+  "sdk-queue.md",
+  "sdk-knowledge.md",
+  "sdk-workflow.md",
+  "sdk-tunnel.md",
+  "sdk-native.md",
+  "sdk-analytics.md",
+  "sdk-domain.md",
+  "sdk-public-key.md",
+  "sdk-invoice.md",
+  "web-performance.md",
+  "sdk-analytics-advanced.md",
+  "sdk-endpoint.md",
+  "sdk-web-search.md",
+  "sdk-oauth-provider.md",
+  "sdk-oauth-integration.md"
+];
+async function downloadDocs(baseDir, opts = {}) {
+  const quiet = opts.quiet === true;
   if (!baseDir) {
     baseDir = getProjectRoot();
   }
   const gitRoot = getGitRoot() || baseDir;
   const monorepo = detectMonorepo(gitRoot);
-  if (monorepo.type !== "none") {
+  if (!quiet && monorepo.type !== "none") {
     info(`\uBAA8\uB178\uB808\uD3EC \uAC10\uC9C0: ${monorepo.type} (\uB8E8\uD2B8: ${gitRoot})`);
     if (monorepo.isSubPackage) {
       info(`\uD604\uC7AC \uC11C\uBE0C \uD328\uD0A4\uC9C0: ${monorepo.subPackageName || path2.basename(process.cwd())}`);
@@ -1240,14 +1469,10 @@ async function downloadDocs(publicKey, templates, baseDir) {
   if (!fs2.existsSync(docsDir)) {
     fs2.mkdirSync(docsDir, { recursive: true });
   }
-  if (!templates) {
-    templates = ["rules"];
-  }
-  info("SDK \uAC1C\uBC1C \uAC00\uC774\uB4DC \uB2E4\uC6B4\uB85C\uB4DC \uC911...");
+  if (!quiet) info("SDK \uAC1C\uBC1C \uAC00\uC774\uB4DC \uB2E4\uC6B4\uB85C\uB4DC \uC911...");
   try {
-    const templateParam = templates.join(",");
     const res = await makeRequest(
-      `${DEFAULT_BASE_URL}/v1/storages/webs/claude-md?template=${encodeURIComponent(templateParam)}&format=sections&public_key=${encodeURIComponent(publicKey)}`,
+      `${DEFAULT_BASE_URL}/v1/storages/webs/claude-md?template=rules&format=sections`,
       "GET",
       {}
     );
@@ -1256,18 +1481,59 @@ async function downloadDocs(publicKey, templates, baseDir) {
     }
     const data = typeof res.data === "string" ? JSON.parse(res.data) : res.data;
     const sections = data.sections || [];
+    const hasher = crypto.createHash("sha256");
+    const newFiles = [];
     for (const section of sections) {
-      const filePath = path2.join(docsDir, section.filename);
-      fs2.writeFileSync(filePath, section.content);
+      const safeName = path2.basename(section.filename);
+      newFiles.push(safeName);
+      hasher.update(safeName).update("\0").update(section.content).update("\0");
+    }
+    const contentHash = hasher.digest("hex");
+    const prevManifest = readDocsManifest(docsDir);
+    const allPresent = newFiles.every((f) => fs2.existsSync(path2.join(docsDir, f)));
+    if (prevManifest && prevManifest.contentHash === contentHash && allPresent) {
+      if (!quiet) success("SDK \uBB38\uC11C\uAC00 \uC774\uBBF8 \uCD5C\uC2E0\uC785\uB2C8\uB2E4");
+      updateRootClaudeMd(rootClaudeMd, quiet);
+      if (monorepo.isSubPackage) {
+        createSubPackageClaudeMd(path2.join(process.cwd(), "CLAUDE.md"), gitRoot, quiet);
+      }
+      return "unchanged";
     }
-    success(`${gitRoot}/.claude/docs/ \uC5D0 ${sections.length}\uAC1C \uBB38\uC11C \uC800\uC7A5 \uC644\uB8CC`);
-    updateRootClaudeMd(rootClaudeMd);
+    const stamp = `<!-- generated by connectbase-cli v${VERSION} (${(/* @__PURE__ */ new Date()).toISOString().slice(0, 10)}) \u2014 \uC790\uB3D9 \uC0DD\uC131 \uD30C\uC77C\uC785\uB2C8\uB2E4. \uC9C1\uC811 \uC218\uC815\uD558\uC9C0 \uB9D0\uACE0 'npx connectbase update'\uB85C \uAC31\uC2E0\uD558\uC138\uC694 -->
+
+`;
+    for (const section of sections) {
+      const safeName = path2.basename(section.filename);
+      fs2.writeFileSync(path2.join(docsDir, safeName), stamp + section.content);
+    }
+    const staleCandidates = prevManifest ? prevManifest.files.map((f) => path2.basename(f)) : LEGACY_DOC_FILES;
+    for (const old of staleCandidates) {
+      if (newFiles.includes(old)) continue;
+      const oldPath = path2.join(docsDir, old);
+      if (fs2.existsSync(oldPath)) {
+        try {
+          fs2.unlinkSync(oldPath);
+          if (!quiet) info(`\uC2A4\uD14C\uC77C \uBB38\uC11C \uC0AD\uC81C: ${old}`);
+        } catch {
+        }
+      }
+    }
+    const manifest = {
+      cliVersion: VERSION,
+      updatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      contentHash,
+      files: newFiles
+    };
+    fs2.writeFileSync(path2.join(docsDir, DOCS_MANIFEST_FILE), JSON.stringify(manifest, null, 2) + "\n");
+    if (!quiet) success(`${gitRoot}/.claude/docs/ \uC5D0 ${sections.length}\uAC1C \uBB38\uC11C \uC800\uC7A5 \uC644\uB8CC`);
+    updateRootClaudeMd(rootClaudeMd, quiet);
     if (monorepo.isSubPackage) {
-      const subClaudeMd = path2.join(process.cwd(), "CLAUDE.md");
-      createSubPackageClaudeMd(subClaudeMd, gitRoot);
+      createSubPackageClaudeMd(path2.join(process.cwd(), "CLAUDE.md"), gitRoot, quiet);
     }
-    log(`${colors.dim}\u203B SDK \uBB38\uC11C\uB294 MCP search_sdk_docs\uB85C \uAC80\uC0C9\uD558\uC138\uC694${colors.reset}`);
+    if (!quiet) log(`${colors.dim}\u203B SDK \uBB38\uC11C\uB294 MCP search_sdk_docs\uB85C \uAC80\uC0C9\uD558\uC138\uC694${colors.reset}`);
+    return "updated";
   } catch {
+    if (quiet) return "failed";
     warn("SDK \uAC00\uC774\uB4DC \uB2E4\uC6B4\uB85C\uB4DC \uC2E4\uD328, \uAE30\uBCF8 \uBB38\uC11C\uB97C \uC0DD\uC131\uD569\uB2C8\uB2E4");
     const fallbackContent = `# ConnectBase \uD504\uB85C\uC81D\uD2B8
 
@@ -1282,9 +1548,10 @@ async function downloadDocs(publicKey, templates, baseDir) {
       createSubPackageClaudeMd(subClaudeMd, gitRoot);
     }
     success(`.claude/docs/ \uC0DD\uC131 \uC644\uB8CC (\uAE30\uBCF8)`);
+    return "failed";
   }
 }
-function updateRootClaudeMd(claudeMdPath) {
+function updateRootClaudeMd(claudeMdPath, quiet = false) {
   const startMarker = "<!-- CONNECTBASE_START -->";
   const endMarker = "<!-- CONNECTBASE_END -->";
   const sdkBlock = `${startMarker}
@@ -1292,11 +1559,13 @@ function updateRootClaudeMd(claudeMdPath) {
 
 \uC774 \uD504\uB85C\uC81D\uD2B8\uB294 **ConnectBase**\uB97C \uBC31\uC5D4\uB4DC\uB85C \uC0AC\uC6A9\uD569\uB2C8\uB2E4.
 
-### AI \uD544\uB3C5 \u2014 \uCF54\uB529 \uC804 \uBC18\uB4DC\uC2DC \uC218\uD589
+@.claude/docs/project-rules.md
 
-1. \`.claude/docs/project-rules.md\`\uB97C **Read tool\uB85C \uC77D\uC73C\uC138\uC694** (\uAE30\uB2A5 \uB9E4\uD551\uD45C, \uBCF4\uC548 \uADDC\uCE59, \uC5D0\uB7EC \uAC00\uC774\uB4DC)
-2. \`search_sdk_docs("\uD0A4\uC6CC\uB4DC")\`\uB85C \uAD6C\uD604 \uBC29\uBC95\uC744 \uAC80\uC0C9\uD558\uC138\uC694
-3. \uAC80\uC0C9 \uACB0\uACFC\uC758 \uCF54\uB4DC \uD328\uD134\uC744 \uB530\uB77C \uAD6C\uD604\uD558\uC138\uC694
+### AI \uD544\uC218 \uC6CC\uD06C\uD50C\uB85C\uC6B0
+
+1. \uC704\uC5D0 import\uB41C project-rules.md\uC758 \uAE30\uB2A5 \uB9E4\uD551\uD45C\xB7\uBCF4\uC548 \uADDC\uCE59\uC744 \uB530\uB974\uC138\uC694
+2. \uCF54\uB4DC\uB97C \uC791\uC131\uD558\uAE30 \uC804 \`search_sdk_docs("\uD0A4\uC6CC\uB4DC")\`\uB85C SDK \uAD6C\uD604 \uBC29\uBC95\uC744 \uAC80\uC0C9\uD558\uACE0, \uAC80\uC0C9 \uACB0\uACFC\uC758 \uCF54\uB4DC \uD328\uD134\uC744 \uADF8\uB300\uB85C \uB530\uB974\uC138\uC694
+3. \`search_sdk_docs\` \uB3C4\uAD6C\uAC00 \uBCF4\uC774\uC9C0 \uC54A\uC73C\uBA74 MCP\uAC00 \uC5F0\uACB0\uB418\uC9C0 \uC54A\uC740 \uC0C1\uD0DC\uC785\uB2C8\uB2E4 \u2014 \uC0AC\uC6A9\uC790\uC5D0\uAC8C \`npx connectbase mcp\` \uC2E4\uD589\uC744 \uC548\uB0B4\uD558\uC138\uC694 (Secret Key \uD544\uC694)
 ${endMarker}`;
   if (fs2.existsSync(claudeMdPath)) {
     let content = fs2.readFileSync(claudeMdPath, "utf-8");
@@ -1308,16 +1577,16 @@ ${endMarker}`;
       content = sdkBlock + "\n\n" + content.trimStart();
     }
     fs2.writeFileSync(claudeMdPath, content);
-    info("CLAUDE.md\uC5D0 ConnectBase \uCC38\uC870 \uC5C5\uB370\uC774\uD2B8 \uC644\uB8CC");
+    if (!quiet) info("CLAUDE.md\uC5D0 ConnectBase \uCC38\uC870 \uC5C5\uB370\uC774\uD2B8 \uC644\uB8CC");
   } else {
     fs2.writeFileSync(claudeMdPath, `# \uD504\uB85C\uC81D\uD2B8
 
 ${sdkBlock}
 `);
-    success("CLAUDE.md \uC0DD\uC131 \uC644\uB8CC");
+    if (!quiet) success("CLAUDE.md \uC0DD\uC131 \uC644\uB8CC");
   }
 }
-function createSubPackageClaudeMd(subClaudeMdPath, gitRoot) {
+function createSubPackageClaudeMd(subClaudeMdPath, gitRoot, quiet = false) {
   const startMarker = "<!-- CONNECTBASE_SUB_START -->";
   const endMarker = "<!-- CONNECTBASE_SUB_END -->";
   const relPath = path2.relative(path2.dirname(subClaudeMdPath), gitRoot);
@@ -1328,9 +1597,9 @@ function createSubPackageClaudeMd(subClaudeMdPath, gitRoot) {
 
 ### AI \uD544\uB3C5
 
-1. \uD504\uB85C\uC81D\uD2B8 \uB8E8\uD2B8\uC758 \`${relPath}/.claude/docs/project-rules.md\`\uB97C **Read tool\uB85C \uC77D\uC73C\uC138\uC694**
-2. \`search_sdk_docs("\uD0A4\uC6CC\uB4DC")\`\uB85C SDK \uAD6C\uD604 \uBC29\uBC95\uC744 \uAC80\uC0C9\uD558\uC138\uC694
-3. \uD504\uB85C\uC81D\uD2B8 \uB8E8\uD2B8\uC758 \`${relPath}/CLAUDE.md\`\uB3C4 \uCC38\uACE0\uD558\uC138\uC694
+1. \uD504\uB85C\uC81D\uD2B8 \uB8E8\uD2B8\uC758 \`${relPath}/.claude/docs/project-rules.md\`\uC758 \uAE30\uB2A5 \uB9E4\uD551\uD45C\xB7\uBCF4\uC548 \uADDC\uCE59\uC744 \uB530\uB974\uC138\uC694
+2. \uCF54\uB4DC\uB97C \uC791\uC131\uD558\uAE30 \uC804 \`search_sdk_docs("\uD0A4\uC6CC\uB4DC")\`\uB85C SDK \uAD6C\uD604 \uBC29\uBC95\uC744 \uAC80\uC0C9\uD558\uC138\uC694
+3. \`search_sdk_docs\` \uB3C4\uAD6C\uAC00 \uBCF4\uC774\uC9C0 \uC54A\uC73C\uBA74 \uC0AC\uC6A9\uC790\uC5D0\uAC8C \`npx connectbase mcp\` \uC2E4\uD589\uC744 \uC548\uB0B4\uD558\uC138\uC694
 ${endMarker}`;
   if (fs2.existsSync(subClaudeMdPath)) {
     let content = fs2.readFileSync(subClaudeMdPath, "utf-8");
@@ -1350,7 +1619,7 @@ ${endMarker}`;
 ${subBlock}
 `);
   }
-  success(`\uC11C\uBE0C \uD328\uD0A4\uC9C0 CLAUDE.md \uC0DD\uC131 \uC644\uB8CC: ${subClaudeMdPath}`);
+  if (!quiet) success(`\uC11C\uBE0C \uD328\uD0A4\uC9C0 CLAUDE.md \uC0DD\uC131 \uC644\uB8CC: ${subClaudeMdPath}`);
 }
 async function setupMcp(secretKey) {
   const gitRoot = getGitRoot();
@@ -1364,6 +1633,13 @@ async function setupMcp(secretKey) {
   }
   const mcpConfigPath = path2.join(root, ".mcp.json");
   if (!secretKey) {
+    if (!process.stdin.isTTY) {
+      error("Secret Key\uAC00 \uD544\uC694\uD569\uB2C8\uB2E4 (\uBE44\uB300\uD654\uD615 \uD658\uACBD)");
+      log(`${colors.dim}\uB2E4\uC74C \uC911 \uD558\uB098\uB85C \uD0A4\uB97C \uC804\uB2EC\uD558\uC138\uC694:${colors.reset}`);
+      log(`  ${colors.cyan}npx connectbase mcp --secret-key cb_sk_...${colors.reset}`);
+      log(`  ${colors.cyan}CONNECTBASE_SECRET_KEY=cb_sk_... npx connectbase mcp${colors.reset}`);
+      process.exit(1);
+    }
     log(`
 ${colors.dim}\uC778\uC99D \uBC29\uC2DD\uC744 \uC120\uD0DD\uD558\uC138\uC694:${colors.reset}`);
     log(`  ${colors.cyan}1${colors.reset}) Secret Key \uC9C1\uC811 \uC785\uB825 (cb_sk_...)`);
@@ -1427,9 +1703,9 @@ ${colors.dim}\uC778\uC99D \uBC29\uC2DD\uC744 \uC120\uD0DD\uD558\uC138\uC694:${co
   log(`
 ${colors.dim}Claude Code\uC5D0\uC11C ConnectBase MCP \uB3C4\uAD6C\uB97C \uC0AC\uC6A9\uD560 \uC218 \uC788\uC2B5\uB2C8\uB2E4.${colors.reset}`);
 }
-async function setupClaudeCode(publicKey, secretKey, projectRoot) {
+async function setupClaudeCode(secretKey, projectRoot) {
   const root = projectRoot || getProjectRoot();
-  await downloadDocs(publicKey, void 0, root);
+  await downloadDocs(root);
   await setupMcp(secretKey);
 }
 async function fetchLatestVersion(packageName) {
@@ -1448,13 +1724,18 @@ async function fetchLatestVersion(packageName) {
   return null;
 }
 function compareVersions(a, b) {
-  const pa = a.split(".").map(Number);
-  const pb = b.split(".").map(Number);
+  const [aMain, aPre] = a.split("-", 2);
+  const [bMain, bPre] = b.split("-", 2);
+  const pa = aMain.split(".").map(Number);
+  const pb = bMain.split(".").map(Number);
   for (let i = 0; i < 3; i++) {
     const diff = (pa[i] || 0) - (pb[i] || 0);
     if (diff !== 0) return diff > 0 ? 1 : -1;
   }
-  return 0;
+  if (aPre === bPre) return 0;
+  if (!aPre) return 1;
+  if (!bPre) return -1;
+  return aPre < bPre ? -1 : aPre > bPre ? 1 : 0;
 }
 function findSubPackagesWithConfig(gitRoot) {
   const results = [];
@@ -1526,36 +1807,7 @@ ${colors.cyan}ConnectBase Update${colors.reset}
   if (!opts.skipDocs) {
     log("");
     info("SDK \uBB38\uC11C \uC5C5\uB370\uC774\uD2B8 \uC911...");
-    let docsKey = config.publicKey || config.secretKey;
-    if (!docsKey) {
-      const rootRcPath = path2.join(projectRoot, ".connectbaserc");
-      if (fs2.existsSync(rootRcPath)) {
-        try {
-          const rc = JSON.parse(fs2.readFileSync(rootRcPath, "utf-8"));
-          docsKey = rc.publicKey || rc.secretKey;
-        } catch {
-        }
-      }
-    }
-    if (!docsKey && monorepo.type !== "none") {
-      const subPackages = findSubPackagesWithConfig(projectRoot);
-      for (const sp of subPackages) {
-        try {
-          const rc = JSON.parse(fs2.readFileSync(path2.join(sp, ".connectbaserc"), "utf-8"));
-          if (rc.publicKey || rc.secretKey) {
-            docsKey = rc.publicKey || rc.secretKey;
-            break;
-          }
-        } catch {
-        }
-      }
-    }
-    if (docsKey) {
-      await downloadDocs(docsKey, void 0, projectRoot);
-    } else {
-      warn("Public Key\uB97C \uCC3E\uC744 \uC218 \uC5C6\uC5B4 \uBB38\uC11C \uC5C5\uB370\uC774\uD2B8\uB97C \uAC74\uB108\uB701\uB2C8\uB2E4");
-      info(".connectbaserc \uD30C\uC77C\uC774\uB098 --public-key \uC635\uC158\uC73C\uB85C \uD0A4\uB97C \uC9C0\uC815\uD558\uC138\uC694");
-    }
+    await downloadDocs(projectRoot);
   }
   if (!opts.skipMcp) {
     log("");
@@ -2620,6 +2872,9 @@ ${colors.yellow}\uBA85\uB839\uC5B4:${colors.reset}
   docs                  SDK \uBB38\uC11C \uB2E4\uC6B4\uB85C\uB4DC/\uC5C5\uB370\uC774\uD2B8 (\uBAA8\uB178\uB808\uD3EC \uC790\uB3D9 \uAC10\uC9C0)
   mcp                   MCP \uC11C\uBC84 \uC124\uC815 (.mcp.json \uC0DD\uC131/\uC5C5\uB370\uC774\uD2B8, \uBAA8\uB178\uB808\uD3EC \uC790\uB3D9 \uAC10\uC9C0)
   deploy <directory>    \uC6F9 \uC2A4\uD1A0\uB9AC\uC9C0\uC5D0 \uD30C\uC77C \uBC30\uD3EC (--dev: Dev \uD658\uACBD)
+                        promote_mode=manual \uC774\uBA74 QA \uD658\uACBD\uC5D0\uB9CC \uBC30\uD3EC\uB429\uB2C8\uB2E4
+  promote [releaseId]   QA \uAC80\uC99D \uD6C4 production \uBC18\uC601 (\uBBF8\uC9C0\uC815: \uCD5C\uC2E0 \uBC30\uD3EC, \uACFC\uAC70 id: \uB864\uBC31)
+  releases              \uBC30\uD3EC \uC774\uB825 \uC870\uD68C (release \uBC88\uD638/\uC0C1\uD0DC/production\xB7QA \uD3EC\uC778\uD130)
   tunnel <port>         \uB85C\uCEEC \uC11C\uBE44\uC2A4\uB97C \uC778\uD130\uB137\uC5D0 \uB178\uCD9C
 
 ${colors.yellow}\uCF54\uB4DC \uBD84\uC11D (MCP \uD1B5\uD574 \uC0AC\uC6A9):${colors.reset}
@@ -2642,8 +2897,12 @@ ${colors.yellow}\uC635\uC158:${colors.reset}
   --label <name>        Endpoint binding \uC790\uB3D9 \uB4F1\uB85D (tunnel \uC804\uC6A9) \u2014 SDK \uC758 cb.endpoint.call(label) \uD638\uCD9C \uAC00\uB2A5
   --description <text>  Endpoint binding \uC124\uBA85 (--label \uB3D9\uBC18 \uC2DC\uB9CC)
   -d, --dev             Dev \uD658\uACBD\uC5D0 \uBC30\uD3EC (deploy \uC804\uC6A9)
+  -y, --yes             \uBE44\uB300\uD654\uD615 \uCD08\uAE30\uD654 \u2014 \uD504\uB86C\uD504\uD2B8 \uC5C6\uC774 \uAE30\uBCF8\uAC12/\uD50C\uB798\uADF8\uB85C \uC9C4\uD589 (init \uC804\uC6A9, CI/AI \uC5D0\uC774\uC804\uD2B8\uC6A9)
+  -a, --app <id>        \uAE30\uC874 \uC571 ID \uC9C0\uC815 (init \uC804\uC6A9)
+  --secret-key <key>    Secret Key (cb_sk_) \uC9C0\uC815 (init/mcp)
+  --deploy-dir <dir>    \uBC30\uD3EC \uB514\uB809\uD1A0\uB9AC \uC9C0\uC815 (init \uC804\uC6A9, \uAE30\uBCF8: \uC790\uB3D9 \uAC10\uC9C0)
   --check               \uBC84\uC804\uB9CC \uD655\uC778 (update \uC804\uC6A9)
-  --skip-docs           \uBB38\uC11C \uC5C5\uB370\uC774\uD2B8 \uAC74\uB108\uB6F0\uAE30 (update \uC804\uC6A9)
+  --skip-docs           \uBB38\uC11C \uC5C5\uB370\uC774\uD2B8 \uAC74\uB108\uB6F0\uAE30 (update/deploy)
   --skip-mcp            MCP \uC5C5\uB370\uC774\uD2B8 \uAC74\uB108\uB6F0\uAE30 (update \uC804\uC6A9)
   --setup-root          \uBAA8\uB178\uB808\uD3EC \uB8E8\uD2B8\uC5D0 \uD3B8\uC758 \uC2A4\uD06C\uB9BD\uD2B8 \uCD94\uAC00 (update \uC804\uC6A9)
   (docs, mcp, update\uB294 \uBAA8\uB178\uB808\uD3EC\uB97C \uC790\uB3D9 \uAC10\uC9C0\uD558\uC5EC \uD504\uB85C\uC81D\uD2B8 \uB8E8\uD2B8\uC5D0 \uC0DD\uC131)
@@ -2654,6 +2913,9 @@ ${colors.yellow}\uBE60\uB978 \uC2DC\uC791:${colors.reset}
   ${colors.dim}# 1. \uCD08\uAE30\uD654 (\uCD5C\uCD08 1\uD68C)${colors.reset}
   npx connectbase init
 
+  ${colors.dim}# 1-1. \uBE44\uB300\uD654\uD615 \uCD08\uAE30\uD654 (CI/AI \uC5D0\uC774\uC804\uD2B8)${colors.reset}
+  npx connectbase init --yes --secret-key cb_sk_...
+
   ${colors.dim}# 2. SDK \uC804\uCCB4 \uC5C5\uB370\uC774\uD2B8 (\uBC84\uC804 \uCCB4\uD06C + \uBB38\uC11C + MCP)${colors.reset}
   npx connectbase update
 
@@ -2669,7 +2931,12 @@ ${colors.yellow}\uBE60\uB978 \uC2DC\uC791:${colors.reset}
   ${colors.dim}# 4. Prod \uBC30\uD3EC${colors.reset}
   npm run deploy
 
-  ${colors.dim}# 4. Dev \uD658\uACBD \uBC30\uD3EC (\uB0B4\uBD80 QA\uC6A9)${colors.reset}
+  ${colors.dim}# 4-1. QA \uC6CC\uD06C\uD50C\uB85C\uC6B0 (\uCF58\uC194\uC5D0\uC11C promote_mode=manual \uC124\uC815 \uC2DC)${colors.reset}
+  npx connectbase deploy ./dist   ${colors.dim}# QA \uD658\uACBD\uC5D0\uB9CC \uBC30\uD3EC${colors.reset}
+  npx connectbase releases        ${colors.dim}# \uBC30\uD3EC \uC774\uB825 \uD655\uC778${colors.reset}
+  npx connectbase promote         ${colors.dim}# QA \uAC80\uC99D \uD6C4 production \uBC18\uC601${colors.reset}
+
+  ${colors.dim}# 4-2. Dev \uD658\uACBD \uBC30\uD3EC (\uB0B4\uBD80 \uD655\uC778\uC6A9)${colors.reset}
   npx connectbase deploy ./dist --dev
 
   ${colors.dim}# 5. \uD130\uB110 (\uAE30\uBCF8)${colors.reset}
@@ -2724,6 +2991,10 @@ function parseArgs(args) {
       result.options.appId = args[++i];
     } else if (arg === "--force") {
       result.options.force = "true";
+    } else if (arg === "-y" || arg === "--yes") {
+      result.options.yes = "true";
+    } else if (arg === "--deploy-dir") {
+      result.options.deployDir = args[++i];
     } else if (arg === "--public") {
       result.options.public = "true";
     } else if (arg === "--show-token") {
@@ -2771,7 +3042,13 @@ async function main() {
     baseUrl: parsed.options.baseUrl || fileConfig.baseUrl || DEFAULT_BASE_URL
   };
   if (parsed.command === "init") {
-    await init();
+    await init(config, {
+      yes: parsed.options.yes === "true",
+      force: parsed.options.force === "true",
+      appId: parsed.options.appId,
+      storageId: parsed.options.storageId,
+      deployDir: parsed.options.deployDir
+    });
   } else if (parsed.command === "update") {
     await update(config, {
       checkOnly: parsed.options.check === "true",
@@ -2780,9 +3057,9 @@ async function main() {
       setupRoot: parsed.options.setupRoot === "true"
     });
   } else if (parsed.command === "docs") {
-    await downloadDocs(config.publicKey || "");
+    await downloadDocs();
   } else if (parsed.command === "mcp") {
-    await setupMcp();
+    await setupMcp(config.secretKey);
   } else if (parsed.command === "deploy") {
     const directory = parsed.args[0] || fileConfig.deployDir || ".";
     if (!config.publicKey) {
@@ -2801,6 +3078,32 @@ async function main() {
       else warn(`--timeout \uAC12\uC774 \uC720\uD6A8\uD558\uC9C0 \uC54A\uC544 \uBB34\uC2DC\uB429\uB2C8\uB2E4: ${parsed.options.timeout}`);
     }
     await deploy(directory, config, isDev, deployOpts);
+    if (parsed.options.skipDocs !== "true") {
+      try {
+        const docsRoot = getGitRoot() || getProjectRoot();
+        if (fs2.existsSync(path2.join(docsRoot, ".claude", "docs", DOCS_MANIFEST_FILE))) {
+          const refreshed = await downloadDocs(docsRoot, { quiet: true });
+          if (refreshed === "updated") {
+            info("SDK \uBB38\uC11C\uAC00 \uC0C8 \uBC84\uC804\uC73C\uB85C \uAC31\uC2E0\uB418\uC5C8\uC2B5\uB2C8\uB2E4 (.claude/docs/)");
+          }
+        }
+      } catch {
+      }
+    }
+  } else if (parsed.command === "promote" || parsed.command === "releases") {
+    if (!config.publicKey) {
+      error('Public Key\uAC00 \uD544\uC694\uD569\uB2C8\uB2E4. "npx connectbase init"\uC73C\uB85C \uC124\uC815\uD558\uAC70\uB098 -k \uC635\uC158\uC744 \uC0AC\uC6A9\uD558\uC138\uC694');
+      process.exit(1);
+    }
+    if (!config.storageId) {
+      error('\uC2A4\uD1A0\uB9AC\uC9C0 ID\uAC00 \uD544\uC694\uD569\uB2C8\uB2E4. "npx connectbase init"\uC73C\uB85C \uC124\uC815\uD558\uAC70\uB098 -s \uC635\uC158\uC744 \uC0AC\uC6A9\uD558\uC138\uC694');
+      process.exit(1);
+    }
+    if (parsed.command === "promote") {
+      await promote(config, parsed.args[0]);
+    } else {
+      await listReleases(config);
+    }
   } else if (parsed.command === "tunnel") {
     const portStr = parsed.args[0];
     if (!portStr) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "connectbase-client",
-  "version": "3.43.0",
+  "version": "3.45.0",
   "description": "Connect Base JavaScript/TypeScript SDK for browser and Node.js",
   "repository": {
     "type": "git",