rootr-cli 0.26.0 → 0.30.0

package/lib/client.js

@@ -754,6 +754,19 @@ export class RootrClient {
     return [];
   }
 
+  /** List members of a workspace (id, email, name, role). */
+  async listMembers(workspace) {
+    return this.request(`/workspaces/${encodeURIComponent(workspace)}/members`);
+  }
+
+  /** MEMBER-MSG — send a direct notification-style message to another member of this workspace. */
+  async messageMember(workspace, userId, body) {
+    return this.request(`/workspaces/${encodeURIComponent(workspace)}/members/${encodeURIComponent(userId)}/message`, {
+      method: 'POST',
+      body: { body },
+    });
+  }
+
   // ---- Scaffolding ----------------------------------------------------------
 
   /** Plan a scaffold tree from a natural-language intent. No workspace required. */
@@ -970,6 +983,54 @@ export class RootrClient {
     });
   }
 
+  // ---- Custom domains (CUSTOM-DOMAIN) -------------------------------------
+  // 발행한 페이지(PAGE)를 고객 도메인(www.customer.co.kr)으로 연다. 워크스페이스 관리자 이상, 등록·확인은 Team 플랜부터.
+
+  async listCustomDomains(workspace) {
+    return this.request(`/workspaces/${encodeURIComponent(workspace)}/domains`);
+  }
+
+  /** 등록 전에 — 이 도메인의 DNS 를 어디서 관리하는지(가비아·Cloudflare…)와 그 화면 기준 안내. */
+  async detectCustomDomain(workspace, host, provider) {
+    const qs = new URLSearchParams({ host });
+    if (provider) qs.set('provider', provider);
+    return this.request(`/workspaces/${encodeURIComponent(workspace)}/domains/detect?${qs}`);
+  }
+
+  /** hostname(www.회사.co.kr·acme.rootr.site) 또는 subdomain(acme). confirmCharge = 애드온 수량 +1 청구에 사람이 동의함. */
+  async addCustomDomain(workspace, { hostname, subdomain, rootNodeId, provider, confirmCharge } = {}) {
+    return this.request(`/workspaces/${encodeURIComponent(workspace)}/domains`, {
+      method: 'POST',
+      body: { hostname, subdomain, rootNodeId, provider, ...(confirmCharge ? { confirmCharge: true } : {}) },
+    });
+  }
+
+  /** 무료 주소 이름을 쓸 수 있나(acme → acme.rootr.site). */
+  async customSubdomainAvailability(workspace, name) {
+    return this.request(`/workspaces/${encodeURIComponent(workspace)}/domains/subdomain?${new URLSearchParams({ name })}`);
+  }
+
+  async checkCustomDomain(workspace, domainId) {
+    return this.request(`/workspaces/${encodeURIComponent(workspace)}/domains/${encodeURIComponent(domainId)}/check`, {
+      method: 'POST',
+    });
+  }
+
+  async renameCustomDomain(workspace, domainId, { hostname, provider } = {}) {
+    const body = { hostname };
+    if (provider) body.provider = provider;
+    return this.request(`/workspaces/${encodeURIComponent(workspace)}/domains/${encodeURIComponent(domainId)}`, {
+      method: 'PATCH',
+      body,
+    });
+  }
+
+  async removeCustomDomain(workspace, domainId) {
+    return this.request(`/workspaces/${encodeURIComponent(workspace)}/domains/${encodeURIComponent(domainId)}`, {
+      method: 'DELETE',
+    });
+  }
+
   // ---- Webhooks ---------------------------------------------------------
 
   async listWebhooks(workspace) {
@@ -1277,6 +1338,22 @@ export class RootrClient {
     });
   }
 
+  /**
+   * DEDUPE-RULES — 이 행과 같은 값의 행들을 표 규칙대로 처리(dryRun 이면 미리 보기만). `rules` 는 이번만 덮는 dedupeCarry 꼴.
+   */
+  async dedupe(databaseId, rowId, { action, rules, fromRowIds, targetRowId, dryRun } = {}) {
+    const path = `/databases/${encodeURIComponent(databaseId)}/rows/${encodeURIComponent(rowId)}/${dryRun ? 'dedupe-preview' : 'dedupe'}`;
+    return this.request(path, {
+      method: 'POST',
+      body: { ...(action ? { action } : {}), ...(rules ? { rules } : {}), ...(fromRowIds?.length ? { fromRowIds } : {}), ...(targetRowId ? { targetRowId } : {}) },
+    });
+  }
+
+  /** DEDUPE-RULES — 처리 한 번(opId)을 통째로 되돌린다(고친 칸은 전 값으로, 지운 행은 되살린다). */
+  async dedupeUndo(databaseId, opId) {
+    return this.request(`/databases/${encodeURIComponent(databaseId)}/dedupe-ops/${encodeURIComponent(opId)}/undo`, { method: 'POST', body: {} });
+  }
+
   /** VALUE-RULE(P2) — 지금 들어 있는 값 가운데 칸 검사에 안 맞는 것(고치지 않는다). */
   async ruleViolations(databaseId, { limit } = {}) {
     const q = limit ? `?limit=${encodeURIComponent(limit)}` : '';
@@ -1325,7 +1402,7 @@ export class RootrClient {
     });
   }
 
-  /** DEDUPE — `rowId` 행을 `into` 행에 합친다(빈 칸만 채우고 "재지원" 댓글, `rowId` 행은 지운다). */
+  /** DEDUPE — `rowId` 행을 `into` 행에 합친다(빈 칸만 채우고 합친 댓글, `rowId` 행은 지운다). */
   async mergeRows(databaseId, rowId, into) {
     return this.request(`/databases/${encodeURIComponent(databaseId)}/rows/${encodeURIComponent(rowId)}/merge`, {
       method: 'POST',
@@ -1623,6 +1700,20 @@ export class RootrClient {
     return this.request(`/pages/${encodeURIComponent(pageId)}/live-data`);
   }
 
+  // PAGE-ANALYTICS — 방문 기록(켜면 LOG·일별 표·대시보드가 페이지 옆에 선다)
+  async getPageAnalytics(pageId) {
+    return this.request(`/pages/${encodeURIComponent(pageId)}/analytics`);
+  }
+
+  async setPageAnalytics(pageId, { enabled, locale } = {}) {
+    return this.request(`/pages/${encodeURIComponent(pageId)}/analytics`, { method: 'POST', body: { enabled, ...(locale ? { locale } : {}) } });
+  }
+
+  async refreshPageAnalytics(pageId, days) {
+    const q = days ? `?days=${encodeURIComponent(days)}` : '';
+    return this.request(`/pages/${encodeURIComponent(pageId)}/analytics/refresh${q}`, { method: 'POST' });
+  }
+
   // ---- Presentations (slide decks) ----------------------------------------
 
   async createPresentation(workspaceId, { name, parentId, theme, slides, config, icon } = {}) {

package/lib/domain-billing.js

@@ -0,0 +1,52 @@
+/**
+ * CUSTOM-DOMAIN 과금 — 서버의 402(도메인 결제 필요)를 사람이 할 일로 바꾼다. MCP 도구(domains.js)와 CLI(`rootr domain add`)가 같이 쓴다.
+ * 에이전트·CLI 는 결제를 할 수 없다(결제창은 사람이 연다) — 그래서 "어디서 무엇을 누르면 되는지"와 "다시 부르는 법"을 말한다.
+ * `tr(ko, en)` 을 주면 그 언어로, 안 주면 영어(MCP 는 영어 설명을 쓴다).
+ */
+export function domainPaymentHelp(err, tr = (_ko, en) => en) {
+  const code = err?.body?.code;
+  const d = err?.body?.details ?? {};
+  const url = d.billingUrl ?? tr('rootr.io › 설정 › 결제', 'rootr.io → Settings → Billing');
+  const month = d.priceUsd?.month ?? 10;
+  const year = d.priceUsd?.year ?? 96;
+  if (code === 'CUSTOM_DOMAIN_PAYMENT_REQUIRED') {
+    return tr(
+      `결제가 필요합니다: 내 도메인은 1개당 월 $${month}(연 결제 시 월 $${year / 12})입니다. 유료 자리 ${d.slots ?? 0}개 중 ${d.used ?? 0}개를 쓰는 중. ` +
+        `${url} 에서 "도메인 연결"을 시작하거나(또는 페이지 공유 창 › 도메인 연결에서 결제창을 열고) 다시 실행하세요. ` +
+        '결제 없이 쓰려면 무료 주소: --subdomain <이름> (이름.rootr.site)',
+      `Payment needed: own domains cost $${month}/month each ($${year / 12}/month billed yearly). ${d.used ?? 0} of ${d.slots ?? 0} paid slot(s) in use. ` +
+        `Ask the person to open ${url} and start the "Custom domain" add-on (or connect it once from the page's Share → "Connect domain" ` +
+        'window, which opens the checkout), then call again. A free address (subdomain: "name" → name.rootr.site) needs no payment.',
+    );
+  }
+  if (code === 'CUSTOM_DOMAIN_CHARGE_CONFIRM_REQUIRED') {
+    const price = d.interval === 'year' ? `$${year}/year` : `$${month}/month`;
+    return tr(
+      `도메인 연결 애드온이 ${d.quantity ?? '?'}개로 1개 늘어납니다(도메인당 ${price}, 이번 주기는 일할 계산). 동의하면 --confirm-charge 를 붙여 다시 실행하세요.`,
+      `This adds one slot to the existing custom-domain add-on (new quantity ${d.quantity ?? '?'}, ${price} per domain, prorated now). ` +
+        'Tell the person the price; only after they agree, call again with confirmCharge: true.',
+    );
+  }
+  if (code === 'CUSTOM_DOMAIN_PAYMENT_PAST_DUE') {
+    return tr(
+      `도메인 연결 결제가 실패한 상태입니다. ${url} 에서 카드를 먼저 바꾼 뒤 다시 실행하세요.`,
+      `The custom-domain add-on payment failed. Ask the person to update the card at ${url}, then try again.`,
+    );
+  }
+  return null;
+}
+
+/** 목록 위에 붙는 자리 한 줄(사람이 읽는 글). */
+export function slotLine(slots, tr = (_ko, en) => en) {
+  if (!slots) return '';
+  const addon = slots.addon?.active
+    ? tr(
+        ` · 애드온 ${slots.addon.interval === 'year' ? '연' : '월'} 결제${slots.addon.cancelAt ? `(${String(slots.addon.cancelAt).slice(0, 10)} 종료 예약)` : ''}`,
+        ` · add-on billed ${slots.addon.interval === 'year' ? 'yearly' : 'monthly'}${slots.addon.cancelAt ? ` (ends ${String(slots.addon.cancelAt).slice(0, 10)})` : ''}`,
+      )
+    : '';
+  return tr(
+    `내 도메인 ${slots.used}/${slots.total}자리${slots.granted ? `(부여 ${slots.granted})` : ''}${addon} · 무료 주소 ${slots.free?.used ?? 0}/${slots.free?.limit ?? 3} · 가격 월 $${slots.price?.monthUsd ?? 10}(연 $${slots.price?.yearUsd ?? 96})`,
+    `own domains ${slots.used}/${slots.total} slot(s)${slots.granted ? ` (${slots.granted} granted)` : ''}${addon} · free addresses ${slots.free?.used ?? 0}/${slots.free?.limit ?? 3} · price $${slots.price?.monthUsd ?? 10}/month ($${slots.price?.yearUsd ?? 96}/year)`,
+  );
+}

package/lib/mcp-tools/databases.js

@@ -524,7 +524,8 @@ export function registerDatabaseTools(server) {
       title: 'Read a database schema and rows',
       description:
         'Read a Rootr (루터) DATABASE node — its schema (properties with ids/types and select options) plus all rows ' +
-        '(each with its rowId and values). ALWAYS call this before rootr_add_row / rootr_update_row so you know the exact ' +
+        '(each with its rowId and values; a row whose current value breaks a column check also carries ' +
+        '`issues: { [propId]: { message, askDeleteRow? } }` — saved as typed, just flagged). ALWAYS call this before rootr_add_row / rootr_update_row so you know the exact ' +
         'property ids/names and, for board/kanban views, which select column holds the status. Only works on DATABASE nodes.',
       annotations: { readOnlyHint: true, destructiveHint: false },
       inputSchema: {
@@ -562,6 +563,7 @@ export function registerDatabaseTools(server) {
       title: 'List database rows',
       description:
         'List the rows of a Rootr (루터) DATABASE (id + values + position), without the schema. ' +
+        'Rows whose current values break a column check carry `issues: { [propId]: { message, askDeleteRow? } }` (omitted when none). ' +
         'Use rootr_read_database instead when you also need the property/column definitions.',
       annotations: { readOnlyHint: true, destructiveHint: false },
       inputSchema: {
@@ -1290,7 +1292,25 @@ export function registerDatabaseTools(server) {
               'row: { "재등록 여부": true, "구분": { map: { "A": "A(재등록)" }, else: "재등록" } } — map looks at the value the ' +
               'NEW row came in with; else covers any value not in map; if that column is still EMPTY when carried, the mark waits and is ' +
               'applied once to the first value written there later (e.g. a later button step); missing select options are added }. ' +
-              'Names or ids. null turns it off.',
+              'Names or ids. null turns it off. ' +
+              'DUPLICATE RULES (all optional, same object): action?: "ask" (dialog; askDefault?: carry|merge_into_old|merge_all preselected) | ' +
+              '"carry" (= auto:true; copy into the new row) | "merge_into_old" (fill the representative earlier row, delete the new row unless ' +
+              'keepNew:true which keeps it linked) | "merge_all" (all same-value rows → one representative row; others deleted or kept linked); ' +
+              'sources?: "all" (default — per column take the most recent earlier row that HAS a value) | "latest" (only the latest earlier row); ' +
+              'strategy?: default per column, one of fill_empty (default) | prefer_new | prefer_old | latest | skip; columns?: { "<column>": ' +
+              'fill_empty | prefer_new | prefer_old | latest | skip | max | min | sum (number) | earliest | latest_date (date) | union ' +
+              '(multi_select/relation/files/person) | { append: { sep?: " / ", datePrefix?: true } } (text) } — a strategy on the wrong column ' +
+              'type is a 400; exclude = skip, overwrite = prefer_old; representative?: "latest" | "oldest", representativeWhen?: [{ propId, op, ' +
+              'values }] (first row matching wins). Every operation returns an opId (undo with rootr_dedupe_undo); preview with ' +
+              'rootr_dedupe_preview. ' +
+              'BY CONDITION: cases?: [{ when?: { within?: { column: "<date column>", days: 0 }, same?: ["<column>"], filters?: [{ propId, op, ' +
+              'values }] (on the earlier row) }, action, …overrides (askDefault/sources/strategy/columns/keepNew/representative/' +
+              'representativeWhen/mark/label; "mark": {} = no marks) }] (≤10) — each earlier row goes to the FIRST matching case, rows ' +
+              'matching none are untouched; any row in an ask case → nothing automatic; merge cases run first, then carry cases fill the ' +
+              'surviving row, which gets the first carry case\'s mark/label (else the merge case\'s). e.g. { cases: [{ when: { within: ' +
+              '{ column: "등록일", days: 0 } }, action: "merge_all", mark: {} }, { action: "carry" }] }. TEMPLATES: map/else values may ' +
+              'use {value} = the value the new row came in with: { "경로": { else: "{value} (다시)" } }; a value already in that shape is ' +
+              'kept; new values become select options.',
           ),
         validate: z
           .record(z.any())
@@ -1394,7 +1414,7 @@ export function registerDatabaseTools(server) {
 
   // ── DEDUPE(F5) — 같은 사람 찾기·합치기·새 행으로 두기 ─────────────────────
   //
-  // 화면의 중복 창과 같은 일을 에이전트도 할 수 있어야 한다. 그렇지 않으면 "지원자 붙여 넣으면서 이미 있는 사람은 합쳐 줘"
+  // 화면의 중복 창과 같은 일을 에이전트도 할 수 있어야 한다. 그렇지 않으면 "명단 붙여 넣으면서 이미 있는 사람은 합쳐 줘"
   // 같은 부탁에서 에이전트가 표 전체를 읽어 전화번호를 손으로 견주게 된다(9천 행이면 수 MB).
 
   server.registerTool(
@@ -1487,8 +1507,9 @@ export function registerDatabaseTools(server) {
         'The "이전 정보 가져오기" choice: copy the values of an EARLIER row of the same person (same dedupe value, e.g. phone) ' +
         'INTO row `rowId`, following the dedupe column\'s dedupeCarry settings (excluded columns such as the entry date, ' +
         'marks such as 재등록 여부=true / 구분 A→A(재등록)). The earlier row is NOT changed and nothing is linked. ' +
-        'Without `from` the most recent matching row (latestBy, else creation time) is used. Row history records it as carried from that ' +
-        'row. Tables with dedupeCarry.auto do this by themselves on every write path — use this for tables without auto or to pick a ' +
+        'Without `from` every earlier row with the same value is used (sources "all": per column the most recent row that has a value; ' +
+        'sources "latest": only the latest row). The response lists the columns that actually changed (copied, changedCount, ' +
+        'nothingChanged) and an opId for rootr_dedupe_undo. Tables whose dedupeCarry action is carry (or auto) do this by themselves on every write path — use this for tables without it or to pick a ' +
         'specific earlier row. Only rows the caller can see are used.',
       annotations: { readOnlyHint: false, destructiveHint: false },
       inputSchema: {
@@ -1508,6 +1529,90 @@ export function registerDatabaseTools(server) {
     },
   );
 
+  server.registerTool(
+    'rootr_dedupe_preview',
+    {
+      title: 'Preview how a row and its same-value rows would be carried/merged',
+      description:
+        'Read-only. For row `rowId` of a Rootr (루터) DATABASE with a dedupe column, shows what the table\'s duplicate rule (dedupeCarry on ' +
+        'the dedupe column — see rootr_update_column) would do: { action, targetRowId (row that stays), deleted, kept, fromRowIds, columns: ' +
+        '[{ column, strategy, before, after, from }], marked, pending, nothingChanged }. `rules` overrides the table rule for this preview ' +
+        'only (same shape: action, sources, strategy, columns, keepNew, representative, representativeWhen …). 404 when no other row has ' +
+        'the same value. Apply with rootr_dedupe_apply.',
+      annotations: { readOnlyHint: true, destructiveHint: false },
+      inputSchema: {
+        databaseId: z.string().describe(DATABASE_TARGET_DESC),
+        rowId: z.string().describe('The (new) row whose duplicates to handle'),
+        rules: z.record(z.any()).optional().describe('Override the table rule for this call (dedupeCarry shape)'),
+        fromRowIds: z.array(z.string()).optional().describe('Limit the earlier rows used as sources'),
+      },
+    },
+    async ({ databaseId, rowId, rules, fromRowIds }) => {
+      try {
+        const client = makeClient();
+        const id = await resolveNodeId(client, databaseId);
+        return jsonResult(await client.dedupe(id, rowId, { rules, fromRowIds, dryRun: true }));
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    'rootr_dedupe_apply',
+    {
+      title: "Apply the table's duplicate rule to a row (carry / merge into the earlier row / merge all)",
+      description:
+        'Writes. Same input as rootr_dedupe_preview; applies it: carry copies into the row, merge_into_old fills the representative earlier ' +
+        'row and deletes this row (unless keepNew), merge_all keeps one representative row and deletes the rest (unless keepNew). Returns ' +
+        'the same fields plus `opId` — undo the whole operation (restores cells, recreates deleted rows) with rootr_dedupe_undo. Preview ' +
+        'first when deleting rows. The caller must be able to edit the kept row and delete the others.',
+      annotations: { readOnlyHint: false, destructiveHint: true },
+      inputSchema: {
+        databaseId: z.string().describe(DATABASE_TARGET_DESC),
+        rowId: z.string().describe('The (new) row whose duplicates to handle'),
+        action: z.enum(['carry', 'merge_into_old', 'merge_all']).optional().describe('Override the action (default: the table rule; ask → askDefault or carry)'),
+        rules: z.record(z.any()).optional().describe('Override the table rule for this call (dedupeCarry shape)'),
+        fromRowIds: z.array(z.string()).optional().describe('Limit the earlier rows used as sources'),
+        targetRowId: z.string().optional().describe('merge_into_old: the earlier row that stays'),
+      },
+    },
+    async ({ databaseId, rowId, action, rules, fromRowIds, targetRowId }) => {
+      try {
+        const client = makeClient();
+        const id = await resolveNodeId(client, databaseId);
+        return jsonResult(await client.dedupe(id, rowId, { action, rules, fromRowIds, targetRowId }));
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    'rootr_dedupe_undo',
+    {
+      title: 'Undo one duplicate-handling operation',
+      description:
+        'Undo a carry/merge by its `opId` (returned by rootr_dedupe_apply, rootr_carry_over, rootr_merge_rows, row writes that ' +
+        'auto-handled a duplicate as `deduped.opId`, and recorded in row history as via "dedupe:<opId>"). Cells it changed go back to ' +
+        'their values before the operation and rows it deleted are recreated with the same id. A second undo is refused.',
+      annotations: { readOnlyHint: false, destructiveHint: false },
+      inputSchema: {
+        databaseId: z.string().describe(DATABASE_TARGET_DESC),
+        opId: z.string().describe('The operation id'),
+      },
+    },
+    async ({ databaseId, opId }) => {
+      try {
+        const client = makeClient();
+        const id = await resolveNodeId(client, databaseId);
+        return jsonResult(await client.dedupeUndo(id, opId));
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
+
   server.registerTool(
     'rootr_rule_violations',
     {

package/lib/mcp-tools/documents.js

@@ -480,7 +480,9 @@ export function registerDocumentTools(server) {
         'Partially update a published Rootr (루터) document\'s public settings — only the fields you pass are ' +
         'changed, everything else (including slug) is left as-is. Examples: {"isPublic": false} to unpublish; ' +
         '{"allowCommits": true} to let public readers propose edits; {"skin": "tech-dark"} or ' +
-        '{"layout": {"cover": true}} to restyle the public page; {"expiresAt": "2026-12-31T00:00:00Z"} to set an ' +
+        '{"layout": {"cover": true}} to restyle the public page; {"seoDescription": "...", "seoImage": "<attachment id>"} ' +
+        'to set the search-result description and link-preview image (search engines are pinged right away); ' +
+        '{"expiresAt": "2026-12-31T00:00:00Z"} to set an ' +
         'auto-close date, or {"expiresAt": null} to clear it. ' +
         'Owner-level action (MANAGE): works with an account key (PAT), not with workspace-scoped/connector tokens.',
       annotations: { readOnlyHint: false, destructiveHint: false },
@@ -510,6 +512,20 @@ export function registerDocumentTools(server) {
           .boolean()
           .optional()
           .describe('true hides the page from search engines (Team plan and up)'),
+        seoDescription: z
+          .union([z.string().max(300), z.null()])
+          .optional()
+          .describe(
+            'Search-result / link-preview description (meta description, og:description). Aim for ~160 characters ' +
+              'that say what the page covers with the words people search for. null or "" falls back to the opening text.',
+          ),
+        seoImage: z
+          .union([z.string(), z.null()])
+          .optional()
+          .describe(
+            'Cover image for link previews (og:image): an image attachment id from the same workspace — upload one ' +
+              'with rootr_upload_attachment first. 1200×630 landscape fits best. null removes it (the Rootr title card is used).',
+          ),
         skin: z
           .enum([
             'classic',

package/lib/mcp-tools/domains.js

@@ -0,0 +1,236 @@
+import { z } from 'zod';
+
+import { RootrApiError } from '../client.js';
+import { domainPaymentHelp } from '../domain-billing.js';
+import { jsonResult, errorResult, makeClient, requireWorkspace, resolveNodeId, NODE_TARGET_HINT } from './shared.js';
+
+/**
+ * CUSTOM-DOMAIN — 발행한 페이지(PAGE)를 **고객 도메인**(www.customer.co.kr)으로 연다.
+ *
+ * 고객은 DNS 에 한 줄(CNAME `www` → connect.rootr.site)만 넣는다. 등록하면 서버가 그 도메인의 DNS 를 어디서 관리하는지
+ * (가비아·카페24·Cloudflare…)를 이름서버로 짚어, 그 업체 화면 기준의 단계를 같이 준다 — 에이전트는 그 단계를 사람에게
+ * 그대로 전하면 된다. 원격 커넥터에서도 그대로 돈다(파일·환경을 쓰지 않는다).
+ *
+ * 3단계(과금): 내 도메인은 1개당 월 $10(연 결제 월 $8) — "도메인 연결" 애드온의 자리를 하나 쓴다. 자리가 없으면 서버가 402 를 주고,
+ * 여기서는 그 까닭과 할 일(결제 탭 주소)을 사람 말로 붙여 돌려준다. 무료 주소 `{이름}.rootr.site`(Team 부터, 3개까지)는 결제 없이 바로 열린다.
+ */
+
+const WS_ARG = z.string().optional().describe('Workspace id; defaults to ROOTR_WORKSPACE/config if omitted');
+
+const STATUS_HINT =
+  'kind: PAID (own domain, uses one paid slot) or FREE (name.rootr.site, no DNS, live at once). ' +
+  'status: SUSPENDED (the custom-domain payment lapsed — paying again in Settings → Billing reopens it), PENDING_DNS (the DNS line is not visible yet — propagation usually takes 10 min–1 h), PENDING_CERT ' +
+  '(DNS is right, the HTTPS certificate is being issued — minutes), ACTIVE (live), ERROR (see lastError). ' +
+  'lastErrorCode is one of DNS_NOT_FOUND, DNS_WRONG_TARGET (observedTarget = what is there now), TXT_MISSING, ' +
+  'CERT_PENDING, CERT_FAILED, CF_BLOCKED, CF_ERROR, CF_OFF; lastError is the same in plain Korean.';
+
+/** 등록 응답의 안내를 사람이 읽는 글로(서버 dns-providers.ts guideText 와 같은 모양). */
+function guideText(guide, lang) {
+  if (!guide?.provider) return '';
+  const p = guide.provider;
+  const head = `${p.name?.[lang] ?? p.id}${p.dnsUrl ? ` — ${p.dnsUrl}` : ''}`;
+  const steps = (p.steps?.[lang] ?? []).map((s, i) => `${i + 1}. ${s}`);
+  const quirks = (p.quirks?.[lang] ?? []).map((s) => `- ${s}`);
+  return [head, ...steps, ...(quirks.length ? [lang === 'ko' ? '주의:' : 'Watch out:', ...quirks] : [])].join('\n');
+}
+
+function recordLine(r) {
+  return `${r.type}  name(host)=${r.name}  value=${r.value ?? '(not configured on this server yet)'}  TTL=default`;
+}
+
+export function registerDomainTools(server) {
+  server.registerTool(
+    'rootr_list_custom_domains',
+    {
+      title: 'List custom domains of a workspace',
+      description:
+        'List the custom domains (e.g. www.customer.co.kr) connected to published PAGE or DOCUMENT nodes in a Rootr (루터) ' +
+        'workspace: hostname, kind (PAID own domain / FREE name.rootr.site), which page it opens (rootNode), status, the DNS ' +
+        'line(s) to add, and the live URL — plus `slots`: paid-domain slots (total = bought + granted, used, available), ' +
+        'the add-on state (interval, cancelAt, pastDue), free addresses used of 3, and the price ($10/month, $96/year). ' +
+        STATUS_HINT +
+        ' Workspace ADMIN or OWNER only.',
+      annotations: { readOnlyHint: true, destructiveHint: false },
+      inputSchema: { workspace: WS_ARG },
+    },
+    async ({ workspace }) => {
+      try {
+        const ws = requireWorkspace(workspace);
+        return jsonResult(await makeClient(ws).listCustomDomains(ws));
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    'rootr_add_custom_domain',
+    {
+      title: 'Connect a custom domain to a published page or document',
+      description:
+        'Connect the customer\'s own domain (e.g. www.customer.co.kr) — or a FREE address name.rootr.site — to a PAGE or ' +
+        'DOCUMENT node (a document makes a blog-like site, e.g. blog.customer.co.kr) so it opens as a normal website: the root ' +
+        'path shows it, `/{child}` shows its published child pages and documents, no ' +
+        '"Rootr" signature. The page should already be published to the web (rootr_publish_node). Team plan and up — a Free ' +
+        'workspace gets 403 PLAN_UPGRADE_REQUIRED. Workspace ADMIN/OWNER only. ' +
+        'FREE address: pass `subdomain: "acme"` (or hostname acme.rootr.site) — no DNS, no payment, live immediately; ' +
+        'lowercase a-z 0-9 and hyphen, 3–30 chars, globally unique, up to 3 per workspace, names like www/api/admin/mail and ' +
+        'anything containing "rootr" are reserved. ' +
+        'OWN domain: $10/month per domain, $8/month billed yearly ($96/year) — the "Custom domain" add-on. With a free slot it ' +
+        'just connects. If the add-on exists but is full you get 402 CUSTOM_DOMAIN_CHARGE_CONFIRM_REQUIRED: tell the person ' +
+        'the price and, only after they agree, call again with confirmCharge: true (adds one slot, prorated). With no add-on ' +
+        'you get 402 CUSTOM_DOMAIN_PAYMENT_REQUIRED: the person must start it in Settings → Billing (the error says where). ' +
+        'The customer then adds ONE DNS line (CNAME, name `www`, value connect.rootr.site). The result includes ' +
+        '`records` (the exact line), `guide.provider` (the DNS provider detected from the name servers — Gabia, Whois, ' +
+        'Cafe24, Hosting.kr, iNames, Dotname, Cloudflare, GoDaddy, Namecheap, Route 53, Squarespace, OnlyDomains, Wix, ' +
+        'or a generic guide — with click-by-click steps in Korean and English) and `instructions` (the same as text). ' +
+        'Relay those steps to the human as they are. A bare root domain (customer.co.kr) cannot hold a CNAME at most ' +
+        'providers — connect www.customer.co.kr and forward the root to it (guide.provider.forwarding). ' +
+        'Afterwards call rootr_check_custom_domain; the server also re-checks every 5 minutes and notifies the person ' +
+        'who registered it when it goes live.',
+      annotations: { readOnlyHint: false, destructiveHint: false },
+      inputSchema: {
+        target: z.string().describe(`The PAGE or DOCUMENT node to open at the domain root: node id${NODE_TARGET_HINT}`),
+        hostname: z
+          .string()
+          .optional()
+          .describe('The domain, e.g. www.customer.co.kr (a pasted URL is fine), or acme.rootr.site for a free address'),
+        subdomain: z
+          .string()
+          .optional()
+          .describe('Free address name only: "acme" → acme.rootr.site (no DNS, no payment). Use instead of hostname'),
+        confirmCharge: z
+          .boolean()
+          .optional()
+          .describe('Set true ONLY after the person agreed to pay for one more domain slot ($10/month or $96/year, prorated)'),
+        provider: z
+          .string()
+          .optional()
+          .describe('Override the detected DNS provider: gabia, whois, cafe24, hostingkr, inames, dotname, cloudflare, godaddy, namecheap, route53, squarespace, onlydomains, wix, other'),
+        lang: z.enum(['ko', 'en']).optional().describe('Language of `instructions` (default ko)'),
+        workspace: WS_ARG,
+      },
+    },
+    async ({ target, hostname, subdomain, confirmCharge, provider, lang, workspace }) => {
+      try {
+        if (!hostname && !subdomain) throw new Error('Pass hostname (www.customer.co.kr) or subdomain (acme → acme.rootr.site).');
+        const ws = requireWorkspace(workspace);
+        const client = makeClient(ws);
+        const rootNodeId = await resolveNodeId(client, target);
+        const out = await client.addCustomDomain(ws, { hostname, subdomain, rootNodeId, provider, confirmCharge });
+        const l = lang === 'en' ? 'en' : 'ko';
+        if (out.kind === 'FREE') {
+          const instructions =
+            l === 'ko'
+              ? `무료 주소가 바로 열렸습니다: https://${out.hostname} — DNS 설정이 필요 없습니다.`
+              : `The free address is live now: https://${out.hostname} — no DNS setup needed.`;
+          return jsonResult({ ...out, instructions });
+        }
+        const instructions = [
+          l === 'ko' ? `DNS 에 이 한 줄을 넣으세요:` : 'Add this one DNS line:',
+          ...(out.records ?? []).map(recordLine),
+          '',
+          guideText(out.guide, l),
+          ...(out.guide?.isApex
+            ? ['', l === 'ko' ? `루트 도메인은 CNAME 을 못 거는 곳이 많습니다 — www.${out.guide.apex} 로 연결하고 루트는 포워딩하세요.` : `Most providers cannot put a CNAME on the root — connect www.${out.guide.apex} and forward the root to it.`]
+            : []),
+        ].join('\n');
+        return jsonResult({ ...out, instructions });
+      } catch (err) {
+        const help = err instanceof RootrApiError ? domainPaymentHelp(err) : null;
+        if (help) err.hint = help;
+        return errorResult(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    'rootr_check_custom_domain',
+    {
+      title: 'Check a custom domain now',
+      description:
+        'Re-check a custom domain right now (DNS + HTTPS certificate) and return its status with a plain-language ' +
+        'reason. ' +
+        STATUS_HINT +
+        ' Calling it again within 10 seconds returns the previous result. Team plan and up; ADMIN/OWNER only.',
+      annotations: { readOnlyHint: false, destructiveHint: false },
+      inputSchema: {
+        domainId: z.string().describe('Domain id from rootr_list_custom_domains / rootr_add_custom_domain'),
+        workspace: WS_ARG,
+      },
+    },
+    async ({ domainId, workspace }) => {
+      try {
+        const ws = requireWorkspace(workspace);
+        return jsonResult(await makeClient(ws).checkCustomDomain(ws, domainId));
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    'rootr_rename_custom_domain',
+    {
+      title: 'Change the name of a not-yet-connected custom domain',
+      description:
+        'Fix the hostname of an own (PAID) custom domain that is not live yet (status PENDING_DNS, PENDING_CERT or ' +
+        'ERROR) — e.g. a typo, or a different name instead of www. The paid slot moves to the new name: no charge, no ' +
+        'refund. The old name is disconnected (status REMOVED) and the result is a NEW domain id with the new DNS line ' +
+        'and provider guide — tell the human the new CNAME line. A live (ACTIVE) domain or a free name.rootr.site ' +
+        'address cannot be renamed: remove it and add a new one. Team plan and up; ADMIN/OWNER only.',
+      annotations: { readOnlyHint: false, destructiveHint: false },
+      inputSchema: {
+        domainId: z.string().describe('Domain id from rootr_list_custom_domains / rootr_add_custom_domain'),
+        hostname: z.string().describe('The new hostname, e.g. "www.customer.co.kr"'),
+        provider: z.string().optional().describe('DNS provider id for the new name (gabia, cafe24, cloudflare, …); omit to auto-detect'),
+        lang: z.enum(['ko', 'en']).optional().describe('Language of the returned step-by-step guide (default ko)'),
+        workspace: WS_ARG,
+      },
+    },
+    async ({ domainId, hostname, provider, lang, workspace }) => {
+      try {
+        const ws = requireWorkspace(workspace);
+        const out = await makeClient(ws).renameCustomDomain(ws, domainId, { hostname, provider });
+        const l = lang === 'en' ? 'en' : 'ko';
+        const instructions = [
+          l === 'ko'
+            ? `${out.renamedFrom?.hostname ?? hostname} → ${out.hostname} 로 바꿨습니다(결제 그대로). DNS 에 이 한 줄을 넣으세요:`
+            : `Renamed ${out.renamedFrom?.hostname ?? hostname} → ${out.hostname} (billing unchanged). Add this one DNS line:`,
+          ...(out.records ?? []).map(recordLine),
+          '',
+          guideText(out.guide, l),
+        ].join('\n');
+        return jsonResult({ ...out, instructions });
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    'rootr_remove_custom_domain',
+    {
+      title: 'Disconnect a custom domain',
+      description:
+        'Disconnect a custom domain: the site stops answering at that domain immediately and the certificate host is ' +
+        'deleted. The page itself and its rootr.io/p/… address are untouched. Tell the human to also remove the CNAME ' +
+        'line at their DNS provider. For an own (paid) domain the add-on quantity goes down by one (prorated credit); ' +
+        'removing the last one schedules the add-on to end at the end of the billing period (`billing` in the result). ' +
+        'Free addresses have no billing. Works on any plan; ADMIN/OWNER only.',
+      annotations: { readOnlyHint: false, destructiveHint: true },
+      inputSchema: {
+        domainId: z.string().describe('Domain id from rootr_list_custom_domains'),
+        workspace: WS_ARG,
+      },
+    },
+    async ({ domainId, workspace }) => {
+      try {
+        const ws = requireWorkspace(workspace);
+        return jsonResult(await makeClient(ws).removeCustomDomain(ws, domainId));
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
+}