rootr-cli 0.4.0 → 0.5.0

package/README.md

@@ -206,6 +206,13 @@ rootr ask "왜 결제 실패가 늘었지?" --workspace ws_123
 
 `rootr mcp`는 stdio로 MCP(Model Context Protocol) 서버를 구동합니다. 제공 도구 29종:
 
+노드를 가리키는 인자(`target`, `databaseId`, `spreadsheetId`, `formId`, `crmId`, `trackerId`,
+`recordingId`, `presentationId`, `whiteboardId`, `logId`, `parentId` 등)는 **노드 id와 경로를 모두**
+받습니다 — CLI와 같은 규칙으로 `/`로 시작하면 경로로 해석합니다.
+즉 `rootr_add_row`에 `databaseId: "/제작 공정/칸반"`을 그대로 넘길 수 있어,
+경로만 아는 에이전트가 uuid를 찾아 헤맬 필요가 없습니다.
+`rootr_list`·`rootr_search` 출력도 각 줄 끝에 `[노드 id]`를 함께 표시합니다.
+
 #### 문서 (workspace 키, docs:read/docs:write)
 
 | 도구 | 설명 |
@@ -282,10 +289,13 @@ rootr ask "왜 결제 실패가 늘었지?" --workspace ws_123
 | `rootr_document_versions` | 문서 버전 히스토리 조회 |
 | `rootr_delete_node` | 노드를 휴지통으로 이동(복구 가능) |
 
-#### 프레젠테이션 (현재 REST 전용 — 전용 MCP 도구는 예정)
+#### 프레젠테이션
 
-프레젠테이션(PRESENTATION) 노드는 아직 전용 MCP 도구가 없고, **같은 API 키로 REST를
-직접 호출**해 저작합니다 (`x-api-key` 헤더, `docs:write`):
+프레젠테이션(PRESENTATION)은 전용 MCP 도구(`rootr_create_presentation`,
+`rootr_read_presentation`, `rootr_append_presentation_slides`,
+`rootr_update_presentation_slide`, `rootr_reorder_presentation_slides`,
+`rootr_update_presentation`)로 저작합니다. 아래처럼 **같은 API 키로 REST를 직접
+호출**해도 됩니다 (`x-api-key` 헤더, `docs:write`):
 
 ```bash
 # 덱 생성 (슬라이드 포함 가능)
@@ -300,6 +310,33 @@ curl -X POST "$BASE/presentations/$ID/slides"  -d '{"slides":[...]}' ...
 curl -X POST "$BASE/presentations/$ID/reorder" -d '{"order":["SLD-002","SLD-001"]}' ...
 ```
 
+##### 슬라이드에 다이어그램 그려 넣기
+
+구조도·업무 흐름도·순서도·데이터 흐름도·상태도는 손으로 SVG를 짜지 말고
+`rootr_create_diagram_slide`에 **형식이 정해진 JSON 스펙**을 넘기세요. 서버가
+검증하고 그려서 슬라이드에 바로 꽂습니다 — 화면은 물론 PDF·PPTX 내보내기에도
+그대로 나옵니다. 슬라이드의 `diagram`(mermaid) 필드는 **뷰어가 그리지 않으므로**
+이 도구를 쓰는 것이 유일한 방법입니다.
+
+종류마다 스펙 모양이 다르니 **`rootr_diagram_schema`로 스키마와 예제를 먼저
+받아보세요.** 맞지 않는 스펙은 어느 항목이 왜 틀렸는지와 고치는 법을 달아 거절되니,
+그대로 고쳐 다시 부르면 됩니다.
+
+```bash
+# 스펙 모양 보기 (architecture | workflow | sequence | dataflow | lifecycle)
+curl "$BASE/diagram-types/workflow/schema" -H "x-api-key: $KEY"
+
+# 그려서 슬라이드에 꽂기 (slideId를 주면 그 슬라이드를 다시 그린다)
+curl -X POST "$BASE/presentations/$ID/diagram-slides" -H "x-api-key: $KEY" \
+  -H 'Content-Type: application/json' \
+  -d '{"type":"workflow","spec":{...},"title":"이슈는 검수를 통과해야만 main에 들어간다",
+       "blocks":[{"heading":"검수가 관문","body":"..."}]}'
+```
+
+`quality`는 기본 `standard`이고, `showcase`는 손으로 다듬은 대표 그림용 엄격
+기준이라 `standard`가 통과시키는 스펙도 거절합니다. 그림 속 글자는 지식 그래프에
+들어가지 않으니 사실은 `title`·`blocks`·`notes`에도 남기세요.
+
 **고품질 덱을 만들 때는 슬라이드 `html` 필드에 1280×720 완결 HTML을 직접 구워
 넣는 방식을 권장**합니다 — 뷰어가 기본 템플릿 대신 그대로 렌더합니다(완전 자유
 디자인). 필수 규칙(외부 요청 차단이라 전부 인라인, 이미지=data URI 내장, 폰트

package/lib/client.js

@@ -852,6 +852,24 @@ export class RootrClient {
     });
   }
 
+  /** Diagram families the server can draw, for discovery. */
+  async diagramTypes() {
+    return this.request('/diagram-types');
+  }
+
+  /** JSON Schema + a worked example for one diagram family. */
+  async diagramSchema(type) {
+    return this.request(`/diagram-types/${encodeURIComponent(type)}/schema`);
+  }
+
+  /** Render a typed diagram spec onto a slide (appends, or replaces slideId). */
+  async createDiagramSlide(presentationId, payload) {
+    return this.request(`/presentations/${encodeURIComponent(presentationId)}/diagram-slides`, {
+      method: 'POST',
+      body: payload,
+    });
+  }
+
   async updatePresentationSlide(presentationId, slideId, slide) {
     return this.request(
       `/presentations/${encodeURIComponent(presentationId)}/slides/${encodeURIComponent(slideId)}`,

package/lib/mcp-tools/attachments.js

@@ -2,7 +2,7 @@ import { readFileSync } from 'node:fs';
 
 import { z } from 'zod';
 
-import { jsonResult, errorResult, makeClient, requireWorkspace } from './shared.js';
+import { jsonResult, errorResult, makeClient, requireWorkspace, resolveOptionalNodeId, NODE_TARGET_HINT } from './shared.js';
 import { resolveTarget, requireResolved } from '../resolve.js';
 import { RootrApiError } from '../client.js';
 
@@ -24,7 +24,7 @@ const uploadInputSchema = {
     .string()
     .optional()
     .describe('Base64-encoded file bytes; use this when the caller has the file in memory instead of on disk'),
-  nodeId: z.string().optional().describe('Document/node id to associate the attachment with (permission-checked)'),
+  nodeId: z.string().optional().describe(`Document/node id${NODE_TARGET_HINT} to associate the attachment with (permission-checked)`),
   workspace: z.string().optional().describe('Workspace id; defaults to ROOTR_WORKSPACE/config'),
 };
 
@@ -48,6 +48,7 @@ export function registerAttachmentTools(server) {
       try {
         const client = makeClient();
         const ws = requireWorkspace(workspace);
+        nodeId = await resolveOptionalNodeId(client, nodeId);
         const data = readAttachmentBytes({ filePath, base64Data });
         const { id } = await client.uploadAttachment(ws, { filename, mimeType, nodeId, data });
         const url = client.attachmentRawUrl(id);

package/lib/mcp-tools/crm.js

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 
-import { jsonResult, errorResult, makeClient, requireWorkspace } from './shared.js';
+import { jsonResult, errorResult, makeClient, requireWorkspace, resolveNodeId, NODE_TARGET_HINT, resolveOptionalNodeId } from './shared.js';
 
 /**
  * Shared context repeated (shortened) across tool descriptions so an agent
@@ -61,7 +61,7 @@ export function registerCrmTools(server) {
       inputSchema: {
         name: z.string().optional().describe('CRM node name'),
         path: z.string().optional().describe('Full tree path to create at, e.g. "/sales/crm"'),
-        parentId: z.string().optional().describe('Parent folder/node id to create the CRM under'),
+        parentId: z.string().optional().describe(`Parent folder/node id${NODE_TARGET_HINT}`),
         icon: z.string().optional().describe('Emoji icon for the CRM node'),
         pipelines: z
           .array(pipelineShape)
@@ -81,6 +81,7 @@ export function registerCrmTools(server) {
       try {
         const ws = requireWorkspace(workspace);
         const client = makeClient(ws);
+        parentId = await resolveOptionalNodeId(client, parentId);
         const result = await client.createCrm(ws, {
           name,
           path,
@@ -111,7 +112,7 @@ export function registerCrmTools(server) {
         CRM_CONTEXT,
       annotations: { readOnlyHint: true, destructiveHint: false },
       inputSchema: {
-        crmId: z.string().describe('CRM node id'),
+        crmId: z.string().describe(`CRM node id${NODE_TARGET_HINT}`),
         includeSummary: z
           .boolean()
           .optional()
@@ -121,6 +122,7 @@ export function registerCrmTools(server) {
     async ({ crmId, includeSummary }) => {
       try {
         const client = makeClient();
+        crmId = await resolveNodeId(client, crmId);
         const crm = await client.getCrm(crmId);
         if (includeSummary) {
           const summary = await client.getCrmSummary(crmId);
@@ -144,7 +146,7 @@ export function registerCrmTools(server) {
         CRM_CONTEXT,
       annotations: { readOnlyHint: false, destructiveHint: false },
       inputSchema: {
-        crmId: z.string().describe('CRM node id'),
+        crmId: z.string().describe(`CRM node id${NODE_TARGET_HINT}`),
         pipelines: z
           .array(pipelineShape)
           .optional()
@@ -157,6 +159,7 @@ export function registerCrmTools(server) {
     async ({ crmId, pipelines, fields, config, icon }) => {
       try {
         const client = makeClient();
+        crmId = await resolveNodeId(client, crmId);
         const result = await client.updateCrm(crmId, {
           pipelines: coerceJson(pipelines),
           fields: coerceJson(fields),
@@ -182,7 +185,7 @@ export function registerCrmTools(server) {
         CRM_CONTEXT,
       annotations: { readOnlyHint: true, destructiveHint: false },
       inputSchema: {
-        crmId: z.string().describe('CRM node id'),
+        crmId: z.string().describe(`CRM node id${NODE_TARGET_HINT}`),
         q: z.string().optional().describe('Free-text search (name/domain/etc.)'),
         ownerId: z.string().optional().describe('Filter by owning user id'),
         tag: z.string().optional().describe('Filter by tag'),
@@ -194,6 +197,7 @@ export function registerCrmTools(server) {
     async ({ crmId, q, ownerId, tag, sort, limit, offset }) => {
       try {
         const client = makeClient();
+        crmId = await resolveNodeId(client, crmId);
         const result = await client.listCrmCompanies(crmId, { q, ownerId, tag, sort, limit, offset });
         return jsonResult(result);
       } catch (err) {
@@ -213,7 +217,7 @@ export function registerCrmTools(server) {
         CRM_CONTEXT,
       annotations: { readOnlyHint: false, destructiveHint: false },
       inputSchema: {
-        crmId: z.string().describe('CRM node id'),
+        crmId: z.string().describe(`CRM node id${NODE_TARGET_HINT}`),
         companyId: z.string().optional().describe('Existing company id to update/delete; omit to create a new company'),
         delete: z.boolean().optional().describe('If true (with companyId), delete the company instead of updating'),
         name: z.string().optional().describe('Company name (required when creating)'),
@@ -231,6 +235,7 @@ export function registerCrmTools(server) {
     async ({ crmId, companyId, delete: doDelete, custom, ...rest }) => {
       try {
         const client = makeClient();
+        crmId = await resolveNodeId(client, crmId);
         if (companyId && doDelete) {
           await client.deleteCrmCompany(companyId);
           return jsonResult({ deleted: true, companyId });
@@ -283,7 +288,7 @@ export function registerCrmTools(server) {
         CRM_CONTEXT,
       annotations: { readOnlyHint: true, destructiveHint: false },
       inputSchema: {
-        crmId: z.string().describe('CRM node id'),
+        crmId: z.string().describe(`CRM node id${NODE_TARGET_HINT}`),
         q: z.string().optional().describe('Free-text search (name/email/etc.)'),
         companyId: z.string().optional().describe('Filter by company id'),
         lifecycleStage: z.string().optional().describe('lead | mql | sql | opportunity | customer | evangelist'),
@@ -298,6 +303,7 @@ export function registerCrmTools(server) {
     async ({ crmId, q, companyId, lifecycleStage, leadStatus, ownerId, tag, sort, limit, offset }) => {
       try {
         const client = makeClient();
+        crmId = await resolveNodeId(client, crmId);
         const result = await client.listCrmContacts(crmId, {
           q,
           companyId,
@@ -327,7 +333,7 @@ export function registerCrmTools(server) {
         CRM_CONTEXT,
       annotations: { readOnlyHint: false, destructiveHint: false },
       inputSchema: {
-        crmId: z.string().describe('CRM node id'),
+        crmId: z.string().describe(`CRM node id${NODE_TARGET_HINT}`),
         contactId: z.string().optional().describe('Existing contact id to update/delete; omit to create a new contact'),
         delete: z.boolean().optional().describe('If true (with contactId), delete the contact instead of updating'),
         name: z.string().optional().describe('Contact name (required when creating)'),
@@ -353,6 +359,7 @@ export function registerCrmTools(server) {
     async ({ crmId, contactId, delete: doDelete, custom, ...rest }) => {
       try {
         const client = makeClient();
+        crmId = await resolveNodeId(client, crmId);
         if (contactId && doDelete) {
           await client.deleteCrmContact(contactId);
           return jsonResult({ deleted: true, contactId });
@@ -401,7 +408,7 @@ export function registerCrmTools(server) {
         CRM_CONTEXT,
       annotations: { readOnlyHint: true, destructiveHint: false },
       inputSchema: {
-        crmId: z.string().describe('CRM node id'),
+        crmId: z.string().describe(`CRM node id${NODE_TARGET_HINT}`),
         q: z.string().optional().describe('Free-text search (deal name/etc.)'),
         pipelineId: z.string().optional().describe('Filter by pipeline id'),
         stageId: z.string().optional().describe('Filter by stage id'),
@@ -418,6 +425,7 @@ export function registerCrmTools(server) {
     async ({ crmId, q, pipelineId, stageId, status, ownerId, companyId, contactId, tag, sort, limit, offset }) => {
       try {
         const client = makeClient();
+        crmId = await resolveNodeId(client, crmId);
         const result = await client.listCrmDeals(crmId, {
           q,
           pipelineId,
@@ -450,7 +458,7 @@ export function registerCrmTools(server) {
         CRM_CONTEXT,
       annotations: { readOnlyHint: false, destructiveHint: false },
       inputSchema: {
-        crmId: z.string().describe('CRM node id'),
+        crmId: z.string().describe(`CRM node id${NODE_TARGET_HINT}`),
         dealId: z.string().optional().describe('Existing deal id to update/delete; omit to create a new deal'),
         delete: z.boolean().optional().describe('If true (with dealId), delete the deal instead of updating'),
         name: z.string().optional().describe('Deal name (required when creating)'),
@@ -478,6 +486,7 @@ export function registerCrmTools(server) {
     async ({ crmId, dealId, delete: doDelete, contacts, custom, ...rest }) => {
       try {
         const client = makeClient();
+        crmId = await resolveNodeId(client, crmId);
         if (dealId && doDelete) {
           await client.deleteCrmDeal(dealId);
           return jsonResult({ deleted: true, dealId });
@@ -552,7 +561,7 @@ export function registerCrmTools(server) {
         CRM_CONTEXT,
       annotations: { readOnlyHint: false, destructiveHint: false },
       inputSchema: {
-        crmId: z.string().describe('CRM node id'),
+        crmId: z.string().describe(`CRM node id${NODE_TARGET_HINT}`),
         type: z.string().describe('note | call | email | meeting'),
         subject: z.string().optional(),
         body: z.string().optional().describe('Activity body/notes (markdown/plain text)'),
@@ -565,6 +574,7 @@ export function registerCrmTools(server) {
     async ({ crmId, ...rest }) => {
       try {
         const client = makeClient();
+        crmId = await resolveNodeId(client, crmId);
         const result = await client.createCrmActivity(crmId, rest);
         return jsonResult(result);
       } catch (err) {
@@ -582,7 +592,7 @@ export function registerCrmTools(server) {
         CRM_CONTEXT,
       annotations: { readOnlyHint: true, destructiveHint: false },
       inputSchema: {
-        crmId: z.string().describe('CRM node id'),
+        crmId: z.string().describe(`CRM node id${NODE_TARGET_HINT}`),
         contactId: z.string().optional(),
         companyId: z.string().optional(),
         dealId: z.string().optional(),
@@ -594,6 +604,7 @@ export function registerCrmTools(server) {
     async ({ crmId, contactId, companyId, dealId, type, limit, offset }) => {
       try {
         const client = makeClient();
+        crmId = await resolveNodeId(client, crmId);
         const result = await client.listCrmActivities(crmId, { contactId, companyId, dealId, type, limit, offset });
         return jsonResult(result);
       } catch (err) {
@@ -615,7 +626,7 @@ export function registerCrmTools(server) {
         CRM_CONTEXT,
       annotations: { readOnlyHint: false, destructiveHint: false },
       inputSchema: {
-        crmId: z.string().describe('CRM node id (required when creating; ignored when updating)'),
+        crmId: z.string().describe(`CRM node id${NODE_TARGET_HINT} (required when creating; ignored when updating)`),
         taskId: z.string().optional().describe('Existing task id to update; omit to create a new task'),
         title: z.string().optional().describe('Task title (required when creating)'),
         type: z.string().optional().describe('todo | call | email | meeting'),
@@ -630,6 +641,7 @@ export function registerCrmTools(server) {
     async ({ crmId, taskId, ...rest }) => {
       try {
         const client = makeClient();
+        crmId = await resolveNodeId(client, crmId);
         const result = taskId ? await client.updateCrmTask(taskId, rest) : await client.createCrmTask(crmId, rest);
         return jsonResult(result);
       } catch (err) {
@@ -648,7 +660,7 @@ export function registerCrmTools(server) {
         CRM_CONTEXT,
       annotations: { readOnlyHint: true, destructiveHint: false },
       inputSchema: {
-        crmId: z.string().describe('CRM node id'),
+        crmId: z.string().describe(`CRM node id${NODE_TARGET_HINT}`),
         status: z.string().optional().describe('open | done | all'),
         assigneeId: z.string().optional(),
         due: z.string().optional().describe('overdue | today | upcoming'),
@@ -662,6 +674,7 @@ export function registerCrmTools(server) {
     async ({ crmId, status, assigneeId, due, contactId, companyId, dealId, limit, offset }) => {
       try {
         const client = makeClient();
+        crmId = await resolveNodeId(client, crmId);
         const result = await client.listCrmTasks(crmId, {
           status,
           assigneeId,
@@ -693,7 +706,7 @@ export function registerCrmTools(server) {
         CRM_CONTEXT,
       annotations: { readOnlyHint: false, destructiveHint: false },
       inputSchema: {
-        crmId: z.string().describe('CRM node id'),
+        crmId: z.string().describe(`CRM node id${NODE_TARGET_HINT}`),
         entity: z.string().describe('contact | company | deal'),
         rows: z.array(z.record(z.unknown())).describe('Array of row objects to import, matching the entity shape'),
       },
@@ -701,6 +714,7 @@ export function registerCrmTools(server) {
     async ({ crmId, entity, rows }) => {
       try {
         const client = makeClient();
+        crmId = await resolveNodeId(client, crmId);
         const result = await client.importCrm(crmId, { entity, rows: coerceJson(rows) });
         return jsonResult(result);
       } catch (err) {

package/lib/mcp-tools/databases.js

@@ -1,6 +1,9 @@
 import { z } from 'zod';
 
-import { jsonResult, errorResult, makeClient } from './shared.js';
+import { jsonResult, errorResult, makeClient, resolveNodeId, NODE_TARGET_HINT } from './shared.js';
+
+/** Human text for the `databaseId` param — accepts a path just like the document tools. */
+const DATABASE_TARGET_DESC = `DATABASE node id${NODE_TARGET_HINT} (e.g. "/제작 공정/칸반")`;
 
 /**
  * Resolve a `{propertyNameOrId: value}` map to `{propertyId: value}` using the
@@ -40,15 +43,16 @@ export function registerDatabaseTools(server) {
         '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: {
-        databaseId: z.string().describe('DATABASE node id'),
+        databaseId: z.string().describe(DATABASE_TARGET_DESC),
       },
     },
     async ({ databaseId }) => {
       try {
         const client = makeClient();
+        const id = await resolveNodeId(client, databaseId);
         const [database, rows] = await Promise.all([
-          client.getDatabase(databaseId),
-          client.listRows(databaseId),
+          client.getDatabase(id),
+          client.listRows(id),
         ]);
         return jsonResult({ database, rows });
       } catch (err) {
@@ -66,13 +70,13 @@ export function registerDatabaseTools(server) {
         'Use rootr_read_database instead when you also need the property/column definitions.',
       annotations: { readOnlyHint: true, destructiveHint: false },
       inputSchema: {
-        databaseId: z.string().describe('DATABASE node id'),
+        databaseId: z.string().describe(DATABASE_TARGET_DESC),
       },
     },
     async ({ databaseId }) => {
       try {
         const client = makeClient();
-        const rows = await client.listRows(databaseId);
+        const rows = await client.listRows(await resolveNodeId(client, databaseId));
         return jsonResult({ rows });
       } catch (err) {
         return errorResult(err);
@@ -91,7 +95,7 @@ export function registerDatabaseTools(server) {
         'Call rootr_read_database first to learn the columns. Optionally set `position` to insert at an index.',
       annotations: { readOnlyHint: false, destructiveHint: false },
       inputSchema: {
-        databaseId: z.string().describe('DATABASE node id'),
+        databaseId: z.string().describe(DATABASE_TARGET_DESC),
         values: z.record(z.unknown()).describe('{ propertyNameOrId: value } for the new row'),
         position: z.number().optional().describe('0-based insert index; appended at the end if omitted'),
       },
@@ -99,9 +103,10 @@ export function registerDatabaseTools(server) {
     async ({ databaseId, values, position }) => {
       try {
         const client = makeClient();
-        const database = await client.getDatabase(databaseId);
+        const id = await resolveNodeId(client, databaseId);
+        const database = await client.getDatabase(id);
         const resolved = resolveValueKeys(database.properties || [], values);
-        const row = await client.createRow(databaseId, { values: resolved, position });
+        const row = await client.createRow(id, { values: resolved, position });
         return jsonResult(row);
       } catch (err) {
         return errorResult(err);
@@ -120,7 +125,7 @@ export function registerDatabaseTools(server) {
         'Optionally set `position` to reorder the row.',
       annotations: { readOnlyHint: false, destructiveHint: false },
       inputSchema: {
-        databaseId: z.string().describe('DATABASE node id'),
+        databaseId: z.string().describe(DATABASE_TARGET_DESC),
         rowId: z.string().describe('Row id (must belong to the database)'),
         values: z.record(z.unknown()).optional().describe('{ propertyNameOrId: newValue | null } partial patch'),
         position: z.number().optional().describe('New 0-based position for the row'),
@@ -129,12 +134,13 @@ export function registerDatabaseTools(server) {
     async ({ databaseId, rowId, values, position }) => {
       try {
         const client = makeClient();
+        const id = await resolveNodeId(client, databaseId);
         let resolved;
         if (values !== undefined) {
-          const database = await client.getDatabase(databaseId);
+          const database = await client.getDatabase(id);
           resolved = resolveValueKeys(database.properties || [], values);
         }
-        const row = await client.updateRow(databaseId, rowId, { values: resolved, position });
+        const row = await client.updateRow(id, rowId, { values: resolved, position });
         return jsonResult(row);
       } catch (err) {
         return errorResult(err);
@@ -151,14 +157,14 @@ export function registerDatabaseTools(server) {
         'Verify the row via rootr_read_database first — do not guess rowIds.',
       annotations: { readOnlyHint: false, destructiveHint: true },
       inputSchema: {
-        databaseId: z.string().describe('DATABASE node id'),
+        databaseId: z.string().describe(DATABASE_TARGET_DESC),
         rowId: z.string().describe('Row id to delete (must belong to the database)'),
       },
     },
     async ({ databaseId, rowId }) => {
       try {
         const client = makeClient();
-        await client.deleteRow(databaseId, rowId);
+        await client.deleteRow(await resolveNodeId(client, databaseId), rowId);
         return jsonResult({ deleted: true, rowId });
       } catch (err) {
         return errorResult(err);

package/lib/mcp-tools/documents.js

@@ -31,7 +31,12 @@ export function registerDocumentTools(server) {
             const p = n.path || '';
             return p === path || p.startsWith(path.endsWith('/') ? path : path + '/');
           })
-          .map((n) => `${n.type || '?'} ${n.path || n.name || n.id}`)
+          .map((n) => {
+            const label = n.path || n.name || n.id;
+            // Keep the id visible: tools that take a node id (databases, sheets,
+            // whiteboards, …) are otherwise unreachable from a listing.
+            return n.id && label !== n.id ? `${n.type || '?'} ${label}  [${n.id}]` : `${n.type || '?'} ${label}`;
+          })
           .sort();
         return textResult(rows.length ? rows.join('\n') : '(no matching nodes)');
       } catch (err) {
@@ -189,7 +194,11 @@ export function registerDocumentTools(server) {
       try {
         const client = makeClient();
         const results = await client.search(query);
-        const rows = results.map((r) => `${r.path || r.name || r.nodeId} — ${r.snippet || ''}`);
+        const rows = results.map((r) => {
+          const label = r.path || r.name || r.nodeId;
+          const id = r.nodeId && label !== r.nodeId ? `  [${r.nodeId}]` : '';
+          return `${label}${id} — ${r.snippet || ''}`;
+        });
         return textResult(rows.length ? rows.join('\n') : '(no results)');
       } catch (err) {
         return errorResult(err);
@@ -256,7 +265,9 @@ export function registerDocumentTools(server) {
         'and propose git-style edit suggestions the owner can merge. Publishing is an owner-level action: it needs ' +
         'MANAGE permission, which workspace-scoped keys (including remote-connector tokens) do not carry — use an ' +
         'ACCOUNT key (PAT) of the owner, or ask the user to publish from the share dialog. ' +
-        'Returns the slug/URL. Check rootr_document_public_status first; unpublish via rootr_set_document_public.',
+        'Safe to call again on an already-published document (republish): the public slug/URL never changes, so ' +
+        'links already shared out stay valid — republishing just creates a new published version from the current draft. ' +
+        'Returns the slug/URL. Check rootr_document_public_status first; unpublish or change settings via rootr_set_document_public.',
       annotations: { readOnlyHint: false, destructiveHint: false },
       inputSchema: {
         target: z.string().describe('Document path (starting with "/") or node id'),
@@ -278,19 +289,58 @@ export function registerDocumentTools(server) {
     {
       title: 'Update public settings of a Rootr document',
       description:
-        'Update a published Rootr (루터) document\'s public settings — e.g. {"isPublic": false} to unpublish. ' +
+        '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 ' +
+        '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 },
       inputSchema: {
         target: z.string().describe('Document path (starting with "/") or node id'),
         isPublic: z.boolean().optional().describe('false to unpublish, true to re-enable'),
+        allowCommits: z.boolean().optional().describe('Whether public readers can propose git-style edit suggestions'),
+        expiresAt: z
+          .union([z.string(), z.null()])
+          .optional()
+          .describe('ISO date to auto-close the public page, or null to clear an existing expiry'),
+        skin: z
+          .enum([
+            'classic',
+            'minimal',
+            'magazine',
+            'paper',
+            'tech-dark',
+            'vivid',
+            'manual',
+            'book',
+            'editorial',
+            'bento',
+            'glass',
+            'mesh',
+            'immersive',
+            'brutal',
+            'neumorph',
+            'y2k',
+          ])
+          .optional()
+          .describe('Visual skin for the public page'),
+        layout: z
+          .object({
+            cover: z.boolean().optional().describe('Show a cover banner'),
+            toc: z.boolean().optional().describe('Show a table of contents'),
+            width: z.enum(['narrow', 'wide']).optional().describe('Body width'),
+            paging: z.boolean().optional().describe('Paginate long documents'),
+          })
+          .optional()
+          .describe('Layout options; only the sub-fields you pass are changed'),
       },
     },
-    async ({ target, isPublic }) => {
+    async ({ target, isPublic, allowCommits, expiresAt, skin, layout }) => {
       try {
         const client = makeClient();
         const id = requireResolved(await resolveTarget(client, target));
-        return jsonResult(await client.setDocumentPublic(id, { isPublic }));
+        return jsonResult(await client.setDocumentPublic(id, { isPublic, allowCommits, expiresAt, skin, layout }));
       } catch (err) {
         return errorResult(err);
       }