@bifos/dooray-cli 0.17.0 → 0.18.0

package/README.md

@@ -32,6 +32,15 @@ dooray setup
 dooray doctor   # 설정이 제대로 됐는지 확인
 ```
 
+개별 값만 바꾸려면 `dooray config set` 을 쓴다. 값 자리에 `-` 를 주면 stdin 에서 읽는다.
+
+```bash
+printf '%s' "$TOKEN" | dooray config set api-key -
+```
+
+토큰을 명령 인자로 넘기면 셸 기록과 프로세스 목록에 남는다. 에이전트가 대신 실행하면 실행 로그에도 남는다.
+stdin 으로 받은 값은 양끝 공백을 지운 뒤 저장하고, 비어 있으면 저장하지 않고 종료 코드 3 으로 끝낸다.
+
 에이전트에서 쓰려면 스킬을 설치한다. Claude Code 가 이 CLI 의 사용법을 알게 된다.
 
 ```bash
@@ -41,6 +50,41 @@ dooray skill status
 
 CLI 를 새 버전으로 올린 뒤에는 `dooray skill update` 를 실행해야 스킬도 갱신된다.
 
+## Dooray 문체 페르소나
+
+`dooray-persona` 스킬은 Dooray에 쌓인 본인 업무 글과 댓글을 모아 개인 업무 문체 문서를 만든다.
+완성한 문서를 AI 에이전트의 규칙으로 연결하면 업무와 댓글 초안을 본인 문체에 맞춰 작성할 수 있다.
+
+이 스킬은 사용자 글을 로컬에서 분석하는 별도 워크플로우이므로 `dooray skill install`의 설치 대상이 아니다.
+저장소를 내려받은 뒤 스킬 디렉터리를 `~/.claude/skills/` 아래에 링크하거나 복사한다.
+
+```bash
+git clone https://github.com/jon890/dooray-cli.git
+cd dooray-cli
+mkdir -p ~/.claude/skills
+ln -s "$PWD/skills/dooray-persona" ~/.claude/skills/dooray-persona
+```
+
+링크 대신 복사해서 사용하려면 마지막 명령을 다음 명령으로 바꾼다.
+
+```bash
+cp -R skills/dooray-persona ~/.claude/skills/
+```
+
+설정 파일은 `~/.claude/dooray-persona.config.json`이며, 최초 실행에서는 후보 프로젝트를 탐색해 대상을 고른 뒤 본인 글을 수집한다.
+인증은 `dooray setup`이 만든 `~/.dooray/config.json`을 읽어 사용하므로 토큰을 따로 입력하지 않는다.
+
+### 터미널에 익숙하지 않은 동료에게 넘기기
+
+`skills/dooray-persona/references/bootstrap.md`에 붙여넣기용 프롬프트가 있다.
+그 블록을 복사해 전달하면 받는 사람은 Claude Code에 한 번 붙여넣는 것으로 CLI 설치, 인증 설정, 스킬 연결, 수집, 문서 생성, 주입까지 진행한다.
+
+받는 사람이 직접 해야 하는 것은 둘이다. Claude Code 설치와 Dooray 개인 인증 토큰 발급이다.
+토큰 발급은 웹 로그인이 필요해 자동화할 수 없고, 프롬프트가 발급 화면 주소까지만 안내한다.
+
+Claude 데스크톱 앱은 사용자 컴퓨터의 파일과 명령을 기본 상태로 다루지 못한다.
+문서는 Claude Code에서 만들고, 완성한 문서를 데스크톱 앱의 프로젝트 지식이나 스타일 설정에 붙여넣어 쓴다.
+
 ## 사용법
 
 설정을 마치면 에이전트에게 한국어로 시키면 된다.

package/dist/index.js

@@ -157,15 +157,62 @@ async function clearMailCredentials() {
   return hadCredentials;
 }
 
+// src/utils/body-input.ts
+var import_promises2 = require("fs/promises");
+async function readBodyInput(opts) {
+  if (opts.body != null && opts.bodyFile != null) {
+    throw new DoorayCliError(
+      "--body\uC640 --body-file\uC740 \uD568\uAED8 \uC0AC\uC6A9\uD560 \uC218 \uC5C6\uC2B5\uB2C8\uB2E4.",
+      EXIT_PARAM_ERROR
+    );
+  }
+  if (opts.bodyFile) {
+    if (opts.bodyFile === "-") return readStdin();
+    return (0, import_promises2.readFile)(opts.bodyFile, "utf-8");
+  }
+  if (opts.body === "-") return readStdin();
+  return opts.body ?? "";
+}
+async function readBodyInputOrNull(opts) {
+  if (opts.body == null && opts.bodyFile == null) return null;
+  return readBodyInput(opts);
+}
+async function readStdin() {
+  if (process.stdin.isTTY) {
+    throw new DoorayCliError(
+      "stdin\uC5D0\uC11C \uC77D\uC73C\uB824\uBA74 \uD30C\uC774\uD504\uB85C \uB370\uC774\uD130\uB97C \uC804\uB2EC\uD574\uC8FC\uC138\uC694.",
+      EXIT_PARAM_ERROR
+    );
+  }
+  const chunks = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(chunk);
+  }
+  return Buffer.concat(chunks).toString("utf-8");
+}
+
+// src/utils/config-value.ts
+async function resolveConfigValue(raw, read = readStdin) {
+  if (raw !== "-") return raw;
+  const value = (await read()).trim();
+  if (value === "") {
+    throw new DoorayCliError(
+      "stdin \uC73C\uB85C \uBC1B\uC740 \uAC12\uC774 \uBE44\uC5B4 \uC788\uC2B5\uB2C8\uB2E4.",
+      EXIT_PARAM_ERROR
+    );
+  }
+  return value;
+}
+
 // src/commands/config.ts
 function maskApiKey(key) {
   if (key.length <= 8) return "****";
   return key.slice(0, 4) + "****" + key.slice(-4);
 }
 var configCommand = new import_commander.Command("config").description("CLI \uC124\uC815 \uAD00\uB9AC");
-configCommand.command("set").description("\uC124\uC815 \uAC12 \uC800\uC7A5").argument("<key>", "\uC124\uC815 \uD0A4 (api-key, base-url)").argument("<value>", "\uC124\uC815 \uAC12").action(async (key, value) => {
+configCommand.command("set").description("\uC124\uC815 \uAC12 \uC800\uC7A5").argument("<key>", "\uC124\uC815 \uD0A4 (api-key, base-url)").argument("<value>", "\uC124\uC815 \uAC12 (`-` \uC774\uBA74 stdin \uC5D0\uC11C \uC77D\uC74C)").action(async (key, value) => {
   try {
-    await setConfigValue(key, value);
+    await setConfigValue(key, await resolveConfigValue(value));
     console.log(import_chalk.default.green(`\u2713 ${key} \uC124\uC815 \uC644\uB8CC`));
   } catch (err) {
     if (err instanceof DoorayCliError) {
@@ -205,7 +252,7 @@ var import_commander2 = require("commander");
 var import_chalk2 = __toESM(require("chalk"));
 
 // src/cache/store.ts
-var import_promises2 = require("fs/promises");
+var import_promises3 = require("fs/promises");
 var import_node_path2 = require("path");
 var import_node_os2 = require("os");
 var CACHE_DIR = (0, import_node_path2.join)((0, import_node_os2.homedir)(), ".dooray", "cache");
@@ -220,11 +267,11 @@ var MEMBER_GROUPS_DIR = (0, import_node_path2.join)(CACHE_DIR, "member-groups");
 var WIKIS_PATH = (0, import_node_path2.join)(CACHE_DIR, "wikis.json");
 var TEMPLATES_DIR = (0, import_node_path2.join)(CACHE_DIR, "templates");
 async function ensureDir2(dir) {
-  await (0, import_promises2.mkdir)(dir, { recursive: true });
+  await (0, import_promises3.mkdir)(dir, { recursive: true });
 }
 async function readJson(path6) {
   try {
-    const raw = await (0, import_promises2.readFile)(path6, "utf-8");
+    const raw = await (0, import_promises3.readFile)(path6, "utf-8");
     return JSON.parse(raw);
   } catch {
     return null;
@@ -233,7 +280,7 @@ async function readJson(path6) {
 async function writeJson(path6, data) {
   const dir = (0, import_node_path2.dirname)(path6);
   await ensureDir2(dir);
-  await (0, import_promises2.writeFile)(path6, JSON.stringify(data, null, 2) + "\n");
+  await (0, import_promises3.writeFile)(path6, JSON.stringify(data, null, 2) + "\n");
 }
 function isExpired(updatedAt, ttlMs) {
   if (!updatedAt) return true;
@@ -322,7 +369,7 @@ async function setWikis(items) {
 }
 async function clearCache() {
   try {
-    await (0, import_promises2.rm)(CACHE_DIR, { recursive: true, force: true });
+    await (0, import_promises3.rm)(CACHE_DIR, { recursive: true, force: true });
   } catch {
   }
 }
@@ -331,31 +378,31 @@ async function getCacheStats() {
   const projectCount = projects?.data.length ?? 0;
   let memberProjectCount = 0;
   try {
-    const files = await (0, import_promises2.readdir)(MEMBERS_DIR);
+    const files = await (0, import_promises3.readdir)(MEMBERS_DIR);
     memberProjectCount = files.filter((f) => f.endsWith(".json")).length;
   } catch {
   }
   let workflowProjectCount = 0;
   try {
-    const files = await (0, import_promises2.readdir)(WORKFLOWS_DIR);
+    const files = await (0, import_promises3.readdir)(WORKFLOWS_DIR);
     workflowProjectCount = files.filter((f) => f.endsWith(".json")).length;
   } catch {
   }
   let tagProjectCount = 0;
   try {
-    const files = await (0, import_promises2.readdir)(TAGS_DIR);
+    const files = await (0, import_promises3.readdir)(TAGS_DIR);
     tagProjectCount = files.filter((f) => f.endsWith(".json")).length;
   } catch {
   }
   let milestoneProjectCount = 0;
   try {
-    const files = await (0, import_promises2.readdir)(MILESTONES_DIR);
+    const files = await (0, import_promises3.readdir)(MILESTONES_DIR);
     milestoneProjectCount = files.filter((f) => f.endsWith(".json")).length;
   } catch {
   }
   let memberGroupProjectCount = 0;
   try {
-    const files = await (0, import_promises2.readdir)(MEMBER_GROUPS_DIR);
+    const files = await (0, import_promises3.readdir)(MEMBER_GROUPS_DIR);
     memberGroupProjectCount = files.filter((f) => f.endsWith(".json")).length;
   } catch {
   }
@@ -378,14 +425,14 @@ cacheCommand.command("refresh").description("\uCE90\uC2DC \uAC31\uC2E0 (API \uD0
 var import_commander3 = require("commander");
 var import_chalk3 = __toESM(require("chalk"));
 var import_path = __toESM(require("path"));
-var import_promises4 = __toESM(require("fs/promises"));
+var import_promises5 = __toESM(require("fs/promises"));
 
 // src/skill/context.ts
 var import_node_path3 = __toESM(require("path"));
 var import_node_os3 = require("os");
 
 // src/version.ts
-var CLI_VERSION = true ? "0.17.0" : "0.0.0-dev";
+var CLI_VERSION = true ? "0.18.0" : "0.0.0-dev";
 
 // src/skill/context.ts
 function resolveSkillDataRoot(homeDir, xdgDataHome = process.env.XDG_DATA_HOME) {
@@ -925,7 +972,7 @@ async function installSkill(context, options = {}) {
 
 // src/api/client.ts
 var import_ky = __toESM(require("ky"));
-var import_promises3 = require("fs/promises");
+var import_promises4 = require("fs/promises");
 var import_node_path6 = require("path");
 
 // src/utils/dooray-message.ts
@@ -937,6 +984,87 @@ function normalizeDoorayMessage(raw) {
   }
 }
 
+// src/api/rate-limiter.ts
+var DEFAULT_BURST_CAPACITY = 20;
+var DEFAULT_REPLENISH_RATE = 5;
+function defaultSleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function parseRateLimitHeaders(headers) {
+  const read = (name) => {
+    const raw = headers.get(name);
+    if (raw == null) return void 0;
+    const value = Number(raw);
+    return Number.isFinite(value) && value >= 0 ? value : void 0;
+  };
+  return {
+    remaining: read("x-ratelimit-remaining"),
+    burstCapacity: read("x-ratelimit-burst-capacity"),
+    replenishRate: read("x-ratelimit-replenish-rate")
+  };
+}
+function createTokenBucket(options = {}) {
+  const now2 = options.now ?? (() => Date.now());
+  const sleep = options.sleep ?? defaultSleep;
+  const positiveOr = (value, fallback) => value != null && value > 0 ? value : fallback;
+  let capacity = positiveOr(options.capacity, DEFAULT_BURST_CAPACITY);
+  let replenishRate = positiveOr(options.replenishRate, DEFAULT_REPLENISH_RATE);
+  let tokens = capacity;
+  let updatedAt = now2();
+  let queue = Promise.resolve();
+  function projected(at) {
+    const elapsed = Math.max(0, at - updatedAt);
+    return Math.min(capacity, tokens + elapsed / 1e3 * replenishRate);
+  }
+  function refill() {
+    const at = now2();
+    if (at <= updatedAt) return;
+    tokens = projected(at);
+    updatedAt = at;
+  }
+  async function take() {
+    for (; ; ) {
+      refill();
+      if (tokens >= 1) {
+        tokens -= 1;
+        return;
+      }
+      const waitMs = Math.max((1 - tokens) / replenishRate * 1e3, 10);
+      await sleep(waitMs);
+    }
+  }
+  return {
+    acquire() {
+      const next = queue.then(take);
+      queue = next.then(
+        () => void 0,
+        () => void 0
+      );
+      return next;
+    },
+    sync(snapshot) {
+      if (snapshot.burstCapacity != null && snapshot.burstCapacity > 0) {
+        capacity = snapshot.burstCapacity;
+      }
+      if (snapshot.replenishRate != null && snapshot.replenishRate > 0) {
+        replenishRate = snapshot.replenishRate;
+      }
+      if (snapshot.remaining != null) {
+        refill();
+        tokens = Math.min(tokens, Math.min(snapshot.remaining, capacity));
+        updatedAt = now2();
+      }
+    },
+    drain() {
+      tokens = 0;
+      updatedAt = now2();
+    },
+    get available() {
+      return projected(now2());
+    }
+  };
+}
+
 // src/api/client.ts
 function joinIds(ids) {
   return ids && ids.length > 0 ? ids.join(",") : void 0;
@@ -968,10 +1096,42 @@ var DoorayApiClient = class {
   constructor(apiKey, baseUrl) {
     this.authHeader = `dooray-api ${apiKey}`;
     this.baseUrl = baseUrl.endsWith("/") ? baseUrl : `${baseUrl}/`;
+    const bucket = createTokenBucket();
     this.api = import_ky.default.create({
       prefix: baseUrl,
       headers: {
         Authorization: this.authHeader
+      },
+      // 429 는 재시도할 가치가 있지만, 동시 요청이 한꺼번에 재시도하면 같은 결과가 반복된다.
+      // jitter 로 재시도 시점을 흩고, 아래 훅이 재시도분도 버킷을 거치게 한다.
+      retry: {
+        limit: 3,
+        statusCodes: [408, 413, 429, 500, 502, 503, 504],
+        backoffLimit: 8e3,
+        jitter: true
+      },
+      hooks: {
+        // 훅 순서는 실측했다 — beforeRequest → afterResponse → beforeRetry → afterResponse.
+        // beforeRequest 는 첫 요청에만 돌고 재시도에는 돌지 않으므로,
+        // beforeRetry 에서도 토큰을 받아야 재시도가 버킷을 우회하지 않는다.
+        beforeRequest: [
+          async () => {
+            await bucket.acquire();
+          }
+        ],
+        beforeRetry: [
+          async ({ error }) => {
+            if (error instanceof import_ky.HTTPError && error.response.status === 429) {
+              bucket.drain();
+            }
+            await bucket.acquire();
+          }
+        ],
+        afterResponse: [
+          ({ response }) => {
+            bucket.sync(parseRateLimitHeaders(response.headers));
+          }
+        ]
       }
     });
   }
@@ -1345,7 +1505,7 @@ var DoorayApiClient = class {
   async uploadPostFile(projectId, postId, filePath) {
     try {
       const fileName = (0, import_node_path6.basename)(filePath);
-      const fileBuffer = await (0, import_promises3.readFile)(filePath);
+      const fileBuffer = await (0, import_promises4.readFile)(filePath);
       const formData = new FormData();
       formData.append("file", new Blob([fileBuffer]), fileName);
       const url = `${this.baseUrl}project/v1/projects/${projectId}/posts/${postId}/files`;
@@ -1390,7 +1550,7 @@ var DoorayApiClient = class {
   async uploadWikiPageFile(wikiId, pageId, filePath, type) {
     try {
       const fileName = (0, import_node_path6.basename)(filePath);
-      const fileBuffer = await (0, import_promises3.readFile)(filePath);
+      const fileBuffer = await (0, import_promises4.readFile)(filePath);
       const buildFormData = () => {
         const fd = new FormData();
         fd.append("type", type);
@@ -1651,7 +1811,7 @@ var doctorCommand = new import_commander3.Command("doctor").description("\uC124\
     process.env.HOME ?? process.env.USERPROFILE ?? "",
     ".claude"
   );
-  const claudeDirExists = await import_promises4.default.access(claudeDir).then(() => true).catch(() => false);
+  const claudeDirExists = await import_promises5.default.access(claudeDir).then(() => true).catch(() => false);
   if (claudeDirExists) {
     console.log(import_chalk3.default.bold("\n\u{1F527} Claude Code \uC2A4\uD0AC\n"));
     const skillStatus = await inspectSkill(createSkillManagerContext());
@@ -1673,7 +1833,7 @@ var doctorCommand = new import_commander3.Command("doctor").description("\uC124\
 var import_commander4 = require("commander");
 var import_chalk4 = __toESM(require("chalk"));
 var import_path2 = __toESM(require("path"));
-var import_promises5 = __toESM(require("fs/promises"));
+var import_promises6 = __toESM(require("fs/promises"));
 var setupCommand = new import_commander4.Command("setup").description("\uB300\uD654\uD615 \uCD08\uAE30 \uC124\uC815 \uB9C8\uBC95\uC0AC").action(async () => {
   const { input: input2, select, password, confirm: confirm2 } = await import("@inquirer/prompts");
   const existing = await getConfig();
@@ -1750,7 +1910,7 @@ var setupCommand = new import_commander4.Command("setup").description("\uB300\uD
       process.env.HOME ?? process.env.USERPROFILE ?? "",
       ".claude"
     );
-    const claudeDirExists = await import_promises5.default.access(claudeDir).then(() => true).catch(() => false);
+    const claudeDirExists = await import_promises6.default.access(claudeDir).then(() => true).catch(() => false);
     if (claudeDirExists) {
       const isNpx = /_npx[/\\]/.test(__dirname) || /\.npm[/\\]_npx/.test(__dirname) || /npx-/.test(__dirname);
       if (isNpx) {
@@ -2992,7 +3152,7 @@ async function resolvePostRef(client, ref) {
 
 // src/editor/index.ts
 var import_node_child_process = require("child_process");
-var import_promises6 = __toESM(require("fs/promises"));
+var import_promises7 = __toESM(require("fs/promises"));
 var import_tmp = __toESM(require("tmp"));
 var import_js_yaml = require("js-yaml");
 function openInEditor(content) {
@@ -3006,7 +3166,7 @@ function openInEditor(content) {
   const tmpFile = import_tmp.default.fileSync({ prefix: "dooray-", postfix: ".md" });
   return new Promise(async (resolve, reject) => {
     try {
-      await import_promises6.default.writeFile(tmpFile.name, content, "utf-8");
+      await import_promises7.default.writeFile(tmpFile.name, content, "utf-8");
       const child = (0, import_node_child_process.spawn)(editor2, [tmpFile.name], {
         stdio: "inherit"
       });
@@ -3022,7 +3182,7 @@ function openInEditor(content) {
               EXIT_PARAM_ERROR
             );
           }
-          const result = await import_promises6.default.readFile(tmpFile.name, "utf-8");
+          const result = await import_promises7.default.readFile(tmpFile.name, "utf-8");
           resolve(result);
         } catch (e) {
           reject(e);
@@ -3115,40 +3275,6 @@ function parseWikiFrontmatter(content) {
   };
 }
 
-// src/utils/body-input.ts
-var import_promises7 = require("fs/promises");
-async function readBodyInput(opts) {
-  if (opts.body != null && opts.bodyFile != null) {
-    throw new DoorayCliError(
-      "--body\uC640 --body-file\uC740 \uD568\uAED8 \uC0AC\uC6A9\uD560 \uC218 \uC5C6\uC2B5\uB2C8\uB2E4.",
-      EXIT_PARAM_ERROR
-    );
-  }
-  if (opts.bodyFile) {
-    if (opts.bodyFile === "-") return readStdin();
-    return (0, import_promises7.readFile)(opts.bodyFile, "utf-8");
-  }
-  if (opts.body === "-") return readStdin();
-  return opts.body ?? "";
-}
-async function readBodyInputOrNull(opts) {
-  if (opts.body == null && opts.bodyFile == null) return null;
-  return readBodyInput(opts);
-}
-async function readStdin() {
-  if (process.stdin.isTTY) {
-    throw new DoorayCliError(
-      "stdin\uC5D0\uC11C \uC77D\uC73C\uB824\uBA74 \uD30C\uC774\uD504\uB85C \uB370\uC774\uD130\uB97C \uC804\uB2EC\uD574\uC8FC\uC138\uC694.",
-      EXIT_PARAM_ERROR
-    );
-  }
-  const chunks = [];
-  for await (const chunk of process.stdin) {
-    chunks.push(chunk);
-  }
-  return Buffer.concat(chunks).toString("utf-8");
-}
-
 // src/utils/attachment-check.ts
 var import_node_readline = __toESM(require("readline"));
 function extractAttachmentReferences(body) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bifos/dooray-cli",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "CLI tool for Dooray project management — AI agent & terminal friendly",
   "keywords": [
     "dooray",
@@ -22,7 +22,7 @@
   },
   "files": [
     "dist",
-    "skills",
+    "skills/dooray-cli",
     "README.md"
   ],
   "engines": {

package/skills/dooray-cli/SKILL.md

@@ -41,6 +41,7 @@ NHN Dooray REST API 를 래핑한 CLI 다. 이 파일은 라우터이므로, 작
 - 조회는 `--json` 으로 먼저 실행해 응답 구조를 확인한 뒤 쓰기 명령으로 넘어간다
 - 쓰기 명령은 대상 ID 를 명시하고, 지원하면 `--dry-run` 으로 먼저 확인한다
 - 이름 기반 조회(멤버·그룹·워크플로우·태그)는 부분일치를 지원한다. 모호하면 에러와 후보 목록이 나오므로 임의로 고르지 말고 사용자에게 확인한다
+- 멤버를 이름으로 찾는 것은 그 프로젝트의 멤버로 한정된다. 비멤버는 이메일이나 memberId 로 지정한다 — [post.md](references/post.md)
 - 실패하면 [common.md](references/common.md) 의 에러 처리 표와 대조한다
 
 ## 파일 명령의 `--json` 스키마

package/skills/dooray-cli/references/common.md

@@ -22,6 +22,15 @@ dooray config set api-key <YOUR_API_TOKEN>   # https://{org}.dooray.com/setting/
 dooray doctor                                 # 설정 검증
 ```
 
+값 자리에 `-` 를 주면 stdin 에서 읽는다. 토큰을 명령 인자로 넘기지 않을 때 쓴다.
+
+```bash
+printf '%s' "$TOKEN" | dooray config set api-key -
+```
+
+인자로 넘긴 값은 셸 기록과 프로세스 목록에 남는다.
+stdin 값은 양끝 공백을 지운 뒤 저장하고, 비어 있으면 저장하지 않고 종료 코드 3 으로 끝낸다.
+
 ## Claude Code 스킬 관리
 
 ```bash

package/skills/dooray-cli/references/mention-link.md

@@ -61,6 +61,17 @@ title 속성도 없다.
 title 은 workflow class 다 — `registered` / `working` / `closed` / `backlog`.
 클릭하면 브라우저가 아니라 Dooray 앱 안에서 이동하며 workflow 상태가 함께 보인다.
 
+**표시 텍스트의 대괄호는 엔티티로 바꾼다.** `[` 는 `[`, `]` 는 `]` 다.
+제목에 모듈명을 대괄호로 붙이는 팀이 많은데, 조회한 `subject` 를 그대로 넣으면 링크 문법과 충돌해 깨진다.
+
+| 입력 | 결과 |
+| --- | --- |
+| `[my-project/524 [MOD] 한도 분리](dooray://...)` | 링크 깨짐 |
+| `[my-project/524 [MOD] 한도 분리](dooray://...)` | 정상 |
+
+치환 대상은 표시 텍스트뿐이고 URL 은 해당 없다.
+`--link-task` 옵션을 쓰면 CLI 가 알아서 치환하므로 손으로 조립할 때만 신경 쓴다.
+
 ### 위키 페이지
 
 ```markdown
@@ -68,13 +79,31 @@ title 은 workflow class 다 — `registered` / `working` / `closed` / `backlog`
 ```
 
 업무 링크와 같은 구조이고 경로만 `pages/{pageId}` 로 다르다. title 은 페이지 상태다.
+표시 텍스트의 대괄호 치환도 업무 링크와 같다.
 
 ### ID 를 얻는 곳
 
 | ID | 얻는 방법 |
 | --- | --- |
 | `orgId` | `~/.dooray/cache/me.json` 의 `data.orgId` |
-| `memberId` | `dooray member search <name>` 또는 `dooray member get <id>` |
+| `memberId` | 응답에 있으면 그 값을 쓴다 (아래 참조). 없을 때만 `dooray member search <name>` |
 | `groupId` | `dooray project groups <project>` |
 | `postId` | `dooray post get <project> <number> --json` 의 `id` |
 | `pageId` | `dooray wiki page get <project> <page-id> --json` 의 `id` |
+
+### 답장 대상은 이름으로 찾지 않는다
+
+답장할 상대의 ID 는 이미 조회 응답 안에 있다. 검색할 필요가 없다.
+
+| 대상 | 응답의 위치 |
+| --- | --- |
+| 업무 작성자 | `post get ... --json` 의 `users.from.member.organizationMemberId` |
+| 댓글 작성자 | `post comment list ... --json` 의 `creator.member.organizationMemberId` |
+
+이 값을 쓰면 표시 이름이 한자든 영문이든 닉네임이든 항상 정확하다.
+
+**검색 결과가 1건이어도 확정 근거로 삼지 않는다.**
+표시 이름이 한자로 되어 있으면 한글 이름 검색에 원 작성자가 아예 안 잡히고, 표기가 비슷한 **다른 사람만** 걸린다.
+후보가 여럿이면 모호하다는 신호라도 있지만, 하나뿐이면 오히려 확신하게 되는 것이 함정이다.
+
+이름 검색은 대상이 응답에 없을 때만 쓰고, 그때도 이메일이나 사번으로 교차 확인한다.

package/skills/dooray-cli/references/post.md

@@ -130,6 +130,20 @@ dooray post edit --id "$POST_ID" --cc "$MEMBER_ID"
 - 이메일 형태 → exact 매칭
 - 그 외 → 이름 부분일치
 
+**이름은 그 프로젝트의 멤버만 찾는다.** 이메일과 memberId 는 조직 전체에서 찾는다.
+
+그래서 프로젝트 멤버가 아닌 사람을 이름으로 지정하면 실패한다.
+
+```bash
+dooray post create <project> --to 홍길동                  # 프로젝트 멤버가 아니면 실패
+dooray post create <project> --to user@example.com        # 통과
+```
+
+에러에 붙는 "사용 가능한 멤버 (N/M)" 은 CLI 의 조회 한계가 아니라 **그 프로젝트의 멤버 목록**이다.
+일부만 가져온 것으로 오해하기 쉬운 표기다.
+
+대상이 그 프로젝트 멤버인지 확실하지 않으면 처음부터 이메일을 쓴다. 이메일은 `dooray member search <이름>` 으로 찾는다.
+
 ## 부모 업무 지정
 
 ```bash