rootr-cli 0.17.3 → 0.19.0

package/lib/mcp-tools/documents.js

@@ -1,8 +1,101 @@
 import { z } from 'zod';
 
 import { RootrApiError } from '../client.js';
+import { t as tr } from '../i18n.js';
 import { resolveTarget, requireResolved, resolveMoveDestination } from '../resolve.js';
-import { textResult, jsonResult, errorResult, makeClient, NODE_TARGET_HINT, NODE_URL_HINT } from './shared.js';
+import { textResult, jsonResult, errorResult, makeClient, resolveNodeId, NODE_TARGET_HINT, NODE_URL_HINT } from './shared.js';
+
+/**
+ * ISSUE-105 — 쓰기 응답의 `warnings` 를 도구 결과 글 끝에 붙인다. 서버는 HTML 주석(`<!-- … -->`)을 저장하면서 떨어뜨리는데
+ * 예전에는 200 만 돌려줘, 주석을 삽입 지점으로 쓰려던 에이전트가 다음 호출에서야(그것도 "다시 읽어라"로) 알았다.
+ */
+function withWarnings(text, result) {
+  const warnings = result && Array.isArray(result.warnings) ? result.warnings.filter((w) => typeof w === 'string') : [];
+  return warnings.length ? `${text}\n${warnings.map((w) => `warning: ${w}`).join('\n')}` : text;
+}
+
+/** EMBED-API — 쓰기 도구 본문에서 표를 끼워 넣는 표기. 모델이 읽는 곳에 한 번씩 적는다. */
+const EMBED_SYNTAX_HINT =
+  ' To show a LIVE table/spreadsheet/deck/board from this workspace inside the document, put `[[embed:/Path/To/Node]]` ' +
+  '(or `[[embed:<node id>]]`) alone on its own line — the editor renders the current rows, not a copy. Paths are ' +
+  'converted to ids when saved; an unknown path is rejected with 400. See rootr_embed_node.';
+
+/** 문서가 아닌 노드를 읽는 도구 — rootr_read 가 "Document not found" 대신 갈 곳을 말해 준다. */
+const READ_TOOL_BY_TYPE = {
+  PRESENTATION: 'rootr_read_presentation',
+  DATABASE: 'rootr_read_database',
+  SPREADSHEET: 'rootr_read_spreadsheet',
+  WHITEBOARD: 'rootr_read_whiteboard',
+  FORM: 'rootr_read_form',
+  PAGE: 'rootr_read_page',
+  RECORDING: 'rootr_read_recording',
+  SIGNED: 'rootr_read_signed_document',
+  LOG: 'rootr_query_log_entries',
+  ISSUE_TRACKER: 'rootr_list_issues',
+  FOLDER: 'rootr_list',
+};
+
+/**
+ * ISSUE-127 — 주소·경로가 문서가 아닌 노드(덱·표 등)로 풀렸을 때 `/documents/:id` 는 "Document not found" 라고만 답한다.
+ * 공개 주소를 받은 에이전트에게는 "없다"로 읽히므로, 무엇이고 어느 도구로 읽는지를 말한다. 문서 조회가 실제로 404 일 때만.
+ */
+function notADocumentError(err, resolved, target) {
+  const type = resolved?.node?.type;
+  if (!(err instanceof RootrApiError) || err.status !== 404 || !type || type === 'DOCUMENT') return null;
+  const tool = READ_TOOL_BY_TYPE[type];
+  return new RootrApiError(
+    tr(`이 대상은 문서가 아니라 ${type} 노드입니다: ${target}`, `This target is a ${type} node, not a document: ${target}`),
+    {
+      status: 404,
+      hint: tool
+        ? tr(`같은 대상을 ${tool} 에 넘기세요 (노드 id: ${resolved.id}).`, `Pass the same target to ${tool} (node id: ${resolved.id}).`)
+        : tr(`노드 id: ${resolved.id}`, `Node id: ${resolved.id}`),
+    },
+  );
+}
+
+/**
+ * ISSUE-127 — 남의 워크스페이스의 공개 문서. 주소를 받은 누구나 브라우저로 읽는 **공개 발행본**을 그대로 돌려준다.
+ *  - 비밀번호가 걸린 문서는 "잠겨 있다"고만 답한다. 통과 수단(비밀번호·통과증 인자)은 넣지 않는다.
+ *  - etag·노드 id 는 주지 않는다 — 고칠 수 있는 문서가 아니다(rootr_edit/write/append 는 이 되받기를 타지 않는다).
+ */
+async function readPublishedCopy(client, slug, target) {
+  let pub;
+  try {
+    pub = await client.getPublicDocument(slug);
+  } catch (err) {
+    if (err instanceof RootrApiError && err.status === 401 && err.body && err.body.code === 'PUBLIC_DOC_PASSWORD') {
+      throw new RootrApiError(
+        tr(`이 공개 문서는 비밀번호로 잠겨 있어 읽을 수 없습니다: ${target}`, `This public document is password-locked and cannot be read: ${target}`),
+        {
+          status: 401,
+          hint: tr(
+            '이 도구로는 비밀번호를 넣을 수 없습니다. 브라우저에서 열거나, 문서가 있는 워크스페이스의 접근 권한을 받으세요.',
+            'This tool cannot enter the password. Open it in a browser, or get access to the workspace the document lives in.',
+          ),
+        },
+      );
+    }
+    if (err instanceof RootrApiError && err.status === 404) requireResolved({ existed: false, target });
+    throw err;
+  }
+  if (!pub || typeof pub.content !== 'string') requireResolved({ existed: false, target });
+  const published = pub.publishedAt ? String(pub.publishedAt) : 'n/a';
+  return {
+    content: [
+      { type: 'text', text: pub.content },
+      {
+        type: 'text',
+        text: tr(
+          `공개 발행본 · 읽기 전용 — 연결된 워크스페이스에서 찾지 못해 공개 주소가 보여 주는 판을 읽었습니다. 제목: ${pub.name ?? ''} · 발행: ${published}\n` +
+            '발행 뒤에 고친 내용은 여기 없습니다. etag 를 주지 않습니다 — rootr_edit / rootr_write / rootr_append 로 고칠 수 없는 문서입니다.',
+          `Published public copy · read-only — not found in the connected workspace, so this is the version the public URL shows. Title: ${pub.name ?? ''} · published: ${published}\n` +
+            'Edits made after publishing are not included. No etag is given — rootr_edit / rootr_write / rootr_append cannot change this document.',
+        ),
+      },
+    ],
+  };
+}
 
 /** Registers the original 6 document tools: list/read/append/edit/write/search. */
 export function registerDocumentTools(server) {
@@ -57,7 +150,15 @@ export function registerDocumentTools(server) {
       title: 'Read a Rootr document',
       description:
         'Read the full markdown content of a Rootr (루터) document by path (starting with "/") or by node id. ' +
-        'Read a document before editing or appending to it so you know its current structure.',
+        'Read a document before editing or appending to it so you know its current structure. The response\'s ' +
+        'trailing "etag" line is the current ETag — pass it as ifMatch to rootr_write to guard against clobbering ' +
+        'concurrent changes. Note: a successful rootr_edit can reformat the WHOLE document (e.g. normalizing "-" ' +
+        'list markers to "*", or table cell spacing), not just the replaced snippet — re-read before another ' +
+        'rootr_edit on the same document rather than reusing text copied from an earlier read. ' +
+        'A published public URL (rootr.io/p/{slug}) also works: a document of the connected workspace reads normally; ' +
+        'one from ANOTHER workspace comes back as its published copy, marked read-only with no etag (it cannot be ' +
+        'edited from here), and a password-locked one is refused. Reading a public URL counts as one read against ' +
+        'the plan\'s read limit (Free: 180/day), exactly like reading your own document.',
       annotations: { readOnlyHint: true, destructiveHint: false },
       inputSchema: {
         target: z.string().describe('Document path (e.g. "/notes/todo.md") or node id, or a full rootr.io URL'),
@@ -67,9 +168,22 @@ export function registerDocumentTools(server) {
       try {
         const client = makeClient();
         const resolved = await resolveTarget(client, target);
+        // ISSUE-127 — 이 워크스페이스에서 못 찾은 공개 주소(/p/{slug})는 공개 발행본으로 되받는다. 읽기 도구인 여기서만.
+        if (!resolved.existed && resolved.publicSlug) return await readPublishedCopy(client, resolved.publicSlug, target);
         const id = requireResolved(resolved);
-        const { content } = await client.getDocumentMarkdown(id);
-        return textResult(content);
+        let doc;
+        try {
+          doc = await client.getDocumentMarkdown(id);
+        } catch (err) {
+          throw notADocumentError(err, resolved, target) ?? err;
+        }
+        const { content, etag } = doc;
+        return {
+          content: [
+            { type: 'text', text: content },
+            { type: 'text', text: `etag: ${etag || 'n/a'}` },
+          ],
+        };
       } catch (err) {
         return errorResult(err);
       }
@@ -87,7 +201,7 @@ export function registerDocumentTools(server) {
       annotations: { readOnlyHint: false, destructiveHint: false },
       inputSchema: {
         target: z.string().describe('Document path (starting with "/") or node id, or a full rootr.io URL'),
-        content: z.string().describe('Markdown content to append'),
+        content: z.string().describe('Markdown content to append.' + EMBED_SYNTAX_HINT),
         underHeading: z
           .string()
           .optional()
@@ -103,7 +217,43 @@ export function registerDocumentTools(server) {
         const resolved = await resolveTarget(client, target);
         const id = requireResolved(resolved);
         const result = await client.appendDocument(id, { content, underHeading });
-        return textResult(`appended (etag ${result.etag || 'n/a'})`);
+        return textResult(withWarnings(`appended (etag ${result.etag || 'n/a'})`, result));
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    'rootr_embed_node',
+    {
+      title: 'Embed a table (or any node) inside a Rootr document',
+      description:
+        'Put a LIVE view of another node — a database/table, spreadsheet, presentation, whiteboard, form, recording, ' +
+        'log store or issue tracker — inside a document, like the editor\'s "Embed" block (Notion\'s linked database). ' +
+        'The document shows the node\'s current content, not a copy, so edits to the table appear in the document. ' +
+        'Appends at the end of the document, or at the end of a heading\'s section. Same result as writing ' +
+        '`[[embed:/Path/To/Node]]` on its own line with rootr_append/rootr_write.',
+      annotations: { readOnlyHint: false, destructiveHint: false },
+      inputSchema: {
+        target: z.string().describe('Document to embed into — path (starting with "/"), node id, or a full rootr.io URL'),
+        node: z.string().describe('Node to embed: its id' + NODE_TARGET_HINT),
+        underHeading: z
+          .string()
+          .optional()
+          .describe('Heading to put it under, e.g. "## Data". Omit to add at the end. A missing heading is created at the end.'),
+      },
+    },
+    async ({ target, node, underHeading }) => {
+      try {
+        const client = makeClient();
+        const docId = requireResolved(await resolveTarget(client, target));
+        const nodeId = await resolveNodeId(client, node);
+        const res = await client.embedNode(docId, { node: nodeId, underHeading });
+        return textResult(
+          `embedded ${res.embedded} into the document as \`${res.marker}\` (etag ${res.etag || 'n/a'}). ` +
+            'It renders as a live view in the editor.',
+        );
       } catch (err) {
         return errorResult(err);
       }
@@ -118,7 +268,12 @@ export function registerDocumentTools(server) {
         'Replace an exact snippet of text ("find") with new text ("replace") inside a Rootr document. ' +
         'Fails with a clear error if the snippet is missing or ambiguous (not unique), so read the document ' +
         'first to copy the exact text to find. Good for precise, targeted edits; use rootr_append instead when ' +
-        'you are only adding new content.',
+        'you are only adding new content. A successful edit can reformat the WHOLE document as a side effect ' +
+        '(list markers and table spacing get normalized), so if you plan another rootr_edit right after this ' +
+        'one, rootr_read the document again first instead of reusing text from before this edit. ' +
+        'HTML comments (<!-- ... -->) are NOT kept when a document is saved, so do not use one as an insertion ' +
+        'marker — the result carries a "warning:" line when that happens; to keep adding at a fixed place use ' +
+        'rootr_append with underHeading.',
       annotations: { readOnlyHint: false, destructiveHint: false },
       inputSchema: {
         target: z.string().describe('Document path (starting with "/") or node id, or a full rootr.io URL'),
@@ -132,8 +287,8 @@ export function registerDocumentTools(server) {
         const client = makeClient();
         const resolved = await resolveTarget(client, target);
         const id = requireResolved(resolved);
-        await client.patchDocumentAnchor(id, { find, replace, replaceAll });
-        return textResult('edited');
+        const result = await client.patchDocumentAnchor(id, { find, replace, replaceAll });
+        return textResult(withWarnings('edited', result));
       } catch (err) {
         return errorResult(err);
       }
@@ -152,7 +307,7 @@ export function registerDocumentTools(server) {
       annotations: { readOnlyHint: false, destructiveHint: true },
       inputSchema: {
         target: z.string().describe('Document path (starting with "/", created if missing) or node id, or a full rootr.io URL'),
-        content: z.string().describe('Full new markdown content for the document'),
+        content: z.string().describe('Full new markdown content for the document.' + EMBED_SYNTAX_HINT),
         ifMatch: z
           .string()
           .optional()
@@ -164,6 +319,8 @@ export function registerDocumentTools(server) {
         const client = makeClient();
         const resolved = await resolveTarget(client, target);
         if (!resolved.existed) {
+          // ISSUE-127 — 만들 경로가 없는 대상(못 찾은 공개 주소 등)은 새 문서로 만들지 않는다(CLI `rootr write` 와 같은 답).
+          if (!resolved.path) requireResolved(resolved);
           if (!resolved.path) throw new RootrApiError(`대상을 찾을 수 없습니다: ${target}`);
           // creating with content IS the write — a follow-up PUT would just
           // double the version history and extraction work
@@ -176,10 +333,13 @@ export function registerDocumentTools(server) {
           });
           const id = created.id || (created.node && created.node.id);
           const url = created.url || (created.node && created.node.url);
-          return textResult(`created ${resolved.path} (id ${id})${url ? ` — ${url}` : ''}`);
+          // 서버가 실제로 둔 경로를 말한다 — "본인 행만" 표 바로 밑처럼 이름에 꼬리가 붙는 자리에서는 요청한 경로와 다르다.
+          // 꼬리 붙은 이름은 그 이름 그대로 적어야 다시 닿으므로(경로 풀이는 정확한 이름만 본다), 요청한 경로를 되읊으면 다음 쓰기가 또 새 문서를 만든다.
+          const at = created.path || (created.node && created.node.path) || resolved.path;
+          return textResult(`created ${at} (id ${id})${url ? ` — ${url}` : ''}`);
         }
-        const { etag } = await client.putDocument(resolved.id, content, { ifMatch });
-        return textResult(`wrote (etag ${etag || 'n/a'})`);
+        const written = await client.putDocument(resolved.id, content, { ifMatch });
+        return textResult(withWarnings(`wrote (etag ${written.etag || 'n/a'})`, written));
       } catch (err) {
         return errorResult(err);
       }
@@ -230,7 +390,9 @@ export function registerDocumentTools(server) {
         'Mentioning someone with @[userId] notifies them, and their notification opens that row and ' +
         'highlights this comment. ' +
         'Comments carry a user identity: the comment is attributed to the person who owns the key ' +
-        '(account keys and workspace keys both carry an owner). A key with no owner cannot comment.',
+        '(account keys and workspace keys both carry an owner). A key with no owner cannot comment. ' +
+        'On an "own rows only" table you can only comment on rows you can see — another person\'s row answers not found. ' +
+        'A reply (parentId) always joins its parent\'s thread: without blockId it inherits the parent\'s blockId, so a reply to a row comment is that row\'s comment too.',
       annotations: { readOnlyHint: false, destructiveHint: false },
       inputSchema: {
         target: z.string().describe('Document path (starting with "/") or node id, or a full rootr.io URL'),
@@ -260,7 +422,8 @@ export function registerDocumentTools(server) {
       description:
         'List the comment threads on a Rootr (루터) document, optionally filtered to one block. ' +
         'DB-ROW-COMMENT — for the comments on ONE ROW of a table, pass the DATABASE as `target` and the ' +
-        'ROW id as `blockId`. Works with any key.',
+        'ROW id as `blockId`. Works with any key. On an "own rows only" table you only get the threads of rows you can see ' +
+        '(the row author and table managers) — other rows\' threads are simply absent.',
       annotations: { readOnlyHint: true, destructiveHint: false },
       inputSchema: {
         target: z.string().describe('Document path (starting with "/") or node id, or a full rootr.io URL'),
@@ -487,7 +650,11 @@ export function registerDocumentTools(server) {
     'rootr_document_public_status',
     {
       title: 'Public status of a Rootr document',
-      description: 'Whether a Rootr (루터) document is published, and at which public slug/URL.',
+      description:
+        'Whether a Rootr (루터) document is published, and at which public slug/URL. ' +
+        '`closed: "PUBLIC_OWN_ROW_PAGE"` (with `isPublic: false` and a `closedReason`) means publishing is switched on but the ' +
+        'address is closed right now (the document came from a row of an "own rows only" table) — do NOT hand that URL out; ' +
+        'tell the user why and how to reopen it.',
       annotations: { readOnlyHint: true, destructiveHint: false },
       inputSchema: {
         target: z.string().describe('Document path (starting with "/") or node id, or a full rootr.io URL'),

package/lib/mcp-tools/forms.js

@@ -338,7 +338,9 @@ export function registerFormTools(server) {
     'rootr_list_form_share_links',
     {
       title: 'List a Rootr form\'s public share links',
-      description: 'List existing public share links/tokens issued for a Rootr (루터) FORM.',
+      description:
+        'List existing public share links/tokens issued for a Rootr (루터) FORM. ' +
+        'A link marked `closed: "PUBLIC_OWN_ROW_PAGE"` does not open right now (the form came from a row of an "own rows only" table) — do NOT hand it out.',
       annotations: { readOnlyHint: true, destructiveHint: false },
       inputSchema: {
         formId: z.string().describe(`FORM node id${NODE_TARGET_HINT}`),
@@ -355,4 +357,64 @@ export function registerFormTools(server) {
       }
     },
   );
+
+  // ---- FORM-MAP: 질문이 표의 어느 칸으로 들어가는가 ---------------------
+  // 2026-09-18 클린베테랑 요청 6번: 질문 이름과 칸 이름이 다르면 값이 조용히 빠졌고,
+  // 폼 10개 전부가 그래서 "응답은 들어오는데 행이 안 생기는" 상태였다.
+
+  server.registerTool(
+    'rootr_form_mapping',
+    {
+      title: 'Show which table column each form question feeds',
+      description:
+        'For a Rootr (루터) FORM linked to a DATABASE, show question → column for every question, and — the ' +
+        'point of this tool — `unmatched`: the questions with NO column, whose answers are silently dropped ' +
+        'when someone submits. Check this right after linking a form to a table or renaming anything: a ' +
+        'mismatch produces no error anywhere, and the loss is usually found weeks later. ' +
+        '`how` is "manual" (someone chose it), "auto" (names matched) or "none" (dropped). ' +
+        '`lastError` carries why the most recent submission failed to reach the table, if it did.',
+      annotations: { readOnlyHint: true, destructiveHint: false },
+      inputSchema: {
+        formId: z.string().describe(`FORM node id${NODE_TARGET_HINT}`),
+      },
+    },
+    async ({ formId }) => {
+      try {
+        const client = makeClient();
+        formId = await resolveNodeId(client, formId);
+        return jsonResult(await client.formMapping(formId));
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    'rootr_set_form_mapping',
+    {
+      title: 'Wire form questions to table columns by hand',
+      description:
+        'Pin which DATABASE column each question of a Rootr (루터) FORM writes into: { "<fieldId>": "<columnId>" }. ' +
+        'Questions you leave out keep matching BY NAME, and passing null for one puts it back to automatic. ' +
+        'Use this whenever the question wording differs from the column header ("성함" vs "이름") — otherwise ' +
+        'that answer is dropped with no warning. Call rootr_form_mapping first for the ids and the current state. ' +
+        'A field or column that does not exist is refused, not ignored.',
+      annotations: { readOnlyHint: false, destructiveHint: false },
+      inputSchema: {
+        formId: z.string().describe(`FORM node id${NODE_TARGET_HINT}`),
+        fieldMap: z
+          .record(z.string().nullable())
+          .describe('{ "<질문 id>": "<칸 id>" } — null puts that question back to name matching'),
+      },
+    },
+    async ({ formId, fieldMap }) => {
+      try {
+        const client = makeClient();
+        formId = await resolveNodeId(client, formId);
+        return jsonResult(await client.setFormMapping(formId, fieldMap));
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
 }

package/lib/mcp-tools/logs.js

@@ -50,7 +50,7 @@ export function registerLogTools(server) {
       description:
         'Update the field schema of an existing LOG store. WARNING: this REPLACES THE ENTIRE FIELD SET — ' +
         'you must resend every field you want to keep, not just the ones you are changing/adding. ' +
-        'Read the LOG store first (e.g. via rootr_read or a get-log call) to see its current fields before calling this.',
+        'Look up its current fields before calling this — rootr_read does not return field definitions (the LOG store detail does).',
       annotations: { readOnlyHint: false, destructiveHint: true },
       inputSchema: {
         logId: z.string().describe(`LOG store node id${NODE_TARGET_HINT}`),

package/lib/mcp-tools/misc.js

@@ -147,13 +147,16 @@ export function registerMiscTools(server) {
         'permanent delete. Use rootr_read/rootr_list first to confirm you have the right target.',
       annotations: { readOnlyHint: false, destructiveHint: true },
       inputSchema: {
-        target: z.string().describe('Document/folder path (starting with "/") or node id'),
+        target: z.string().optional().describe('Document/folder path (starting with "/") or node id'),
+        nodeId: z.string().optional().describe('Alias for `target` — node id of the item to delete'),
       },
     },
-    async ({ target }) => {
+    async ({ target, nodeId }) => {
       try {
+        const want = target ?? nodeId;
+        if (!want) throw new Error('target (or nodeId) is required');
         const client = makeClient();
-        const resolved = await resolveTarget(client, target);
+        const resolved = await resolveTarget(client, want);
         const id = requireResolved(resolved);
         await client.deleteNode(id);
         return jsonResult({
@@ -203,6 +206,9 @@ export function registerMiscTools(server) {
       description:
         'Read the READ-ACK state of a Rootr (루터) node — who must read it, the due date, who has read or ' +
         'acknowledged, and (for a DATABASE or FOLDER) how far through the documents inside each person is. ' +
+        'Each target has `completed`; on a DATABASE/FOLDER a person is done once they have read every document THEY can open ' +
+        '(`readCount`/`readTotal` per person — on an "own rows only" table that is their own row pages plus shared documents). ' +
+        'If you cannot see every document inside, other people carry only `completed` (no counts). ' +
         'Use it to answer "누가 아직 안 읽었나" for a 규정/공지/교육자료. If the node itself has no requirement ' +
         'but an ancestor does, `ancestorRequirementId` names the node that carries it.',
       annotations: { readOnlyHint: true, destructiveHint: false },

package/lib/mcp-tools/pages.js

@@ -25,7 +25,7 @@ import {
  */
 const BLOCK_GUIDE =
   'A page is `blocks[]` (ordered, max 200) + `config`. Each block is {id?, type, props}. ' +
-  'You assemble a page from these 15 block types:\n' +
+  'You assemble a page from these block types:\n' +
   '· hero {title, subtitle?, align?:"left"|"center", background?:{kind:"color",color}|{kind:"image",attachmentId}, button?:{label,target}} — the opening banner\n' +
   '· text {body (markdown), title?} — prose section; markdown is sanitized when rendered\n' +
   '· features {columns?:1|2|3, items:[{title, body, icon?(emoji)}]} — "what it does" grid\n' +
@@ -38,13 +38,31 @@ const BLOCK_GUIDE =
   '· footer {links:[{label, target}], contact?, copyright?}\n' +
   '· liveStats {cards:[{label, icon?, source:{nodeId(DATABASE/LOG node), agg:"count"|"sum"|"avg"|"min"|"max", column?}}]} — numbers read LIVE from a table\n' +
   '· liveTable {source:{nodeId}, columns?:[name], rowLimit?(1-200), orderBy?:{column, dir:"asc"|"desc"}}\n' +
-  '· liveChart {source:{nodeId}, chart:"bar"|"line"|"donut", labelColumn, valueColumn, agg:"count"|"sum"|"avg"}\n' +
+  '· liveChart {source:{nodeId, sheet?, range?}, chart, labelColumn, valueColumn?, agg?, …} — a LIVE chart (46 kinds, see CHARTS below)\n' +
   '· form {formNodeId(FORM node), headline?, submitLabel?} — visitors submit right on the page\n' +
   '· custom {html, height?(40-4000, default 260)} — free HTML/CSS, rendered inside a locked-down sandboxed iframe ' +
   '(no scripts, no same-origin, no network). Use it for a look the other blocks cannot make. Page theme colors are ' +
   'available inside as var(--pg-bg|text|muted|faint|card|line|accent|on-accent) and var(--pg-font). Scripts and ' +
   'on*= handlers are stripped on save — do not put behaviour here, only markup and CSS.\n' +
-  'LIVE/FORM BLOCKS: `source.nodeId` / `formNodeId` must be a node in the SAME workspace, and `column`/`labelColumn`/' +
+  'LAYOUT: any block takes `width:"full"|"twoThirds"|"half"|"third"` — neighbouring blocks sit side by side (phones stack them). ' +
+  'That is how a page becomes a DASHBOARD: a row of `chart:"kpi"` blocks at width "third", then charts at width "half".\n' +
+  'CHARTS (liveChart): chart ∈ bar|barH|stackedBar|stackedBarH|percentBar|lollipop|dumbbell|bullet|waterfall|pareto|radar|polarBar|line|step|area|stackedArea|percentArea|combo|slope|stream|calendar|pie|donut|halfDonut|rose|funnel|treemap|sunburst|waffle|histogram|boxplot|heatmap|scatter|bubble|sankey|chord|network|tree|kpi|gauge|progress|ring|candlestick|gantt|wordCloud|pivot. ' +
+  'source = a DATABASE, SPREADSHEET or LOG node (sheet: {nodeId, sheet?(name), range?:"A1:F200"} — first row = column names, formula results are read). ' +
+  'Category charts: labelColumn (dates are bucketed: dateBucket day|week|month|quarter|year|weekday|hour, empty periods filled with 0) + ' +
+  'valueColumn & agg (count|sum|avg|min|max|median|distinct — valueColumn is optional for count/distinct, which just count the matching rows per label) OR values:[{column?, agg, label?, as?:"bar"|"line"|"area", axis?:"left"|"right"}] (several series, combo/dual axis) ' +
+  'OR seriesColumn (break down / stack by another column; heatmap, stream and pivot need it). sort auto|value-desc|value-asc|label-asc|label-desc, limit (+ others:true folds the rest into "Other"), cumulative:true. ' +
+  'kpi|gauge|progress|ring: valueColumn+agg, optional dateColumn + period (today|7d|30d|90d|week|month|quarter|year) → value vs the previous same-length period + sparkline; goal or goalColumn. ' +
+  'scatter|bubble: xColumn, yColumn, sizeColumn?, seriesColumn?. histogram|boxplot: valueColumn (+labelColumn groups for boxplot), bins?. ' +
+  'sankey|chord|network: labelColumn (from) → targetColumn (to), value = agg. treemap|sunburst|tree: labelColumn + levels:[col,…]. ' +
+  'candlestick: labelColumn + open/high/low/closeColumn. gantt: labelColumn, startColumn, endColumn?. bullet: values[0]=actual + goalColumn (or goal). wordCloud: labelColumn (+splitWords:true for free text). ' +
+  'filters:[{column, op: is|is_not|contains|not_contains|gt|gte|lt|lte|empty|not_empty|last_days, value}] (values may be "@today-30"). ' +
+  'Display: title, subtitle, height(160-1200), format auto|number|compact|percent|krw|usd|decimal1|decimal2, prefix, suffix, palette theme|vivid|pastel|ocean|sunset|forest|mono, goalLabel, thresholds:[{value,color}], showLabels, showLegend, smooth. ' +
+  'rootr_read_page_live_data shows what each chart computed — a chart that could not be drawn says why (column_missing/no_rows/needs_number).\n' +
+  'LIVE/FORM BLOCKS: `source.nodeId` / `formNodeId` must be a node in the SAME workspace that you can open — write it as ' +
+  'the node id, a full "/folder/name" path, or a name that is the ONLY table/sheet/log (or form, for `formNodeId`) with ' +
+  'that name. The server resolves it and stores the id (the response shows the id). A path or name it cannot resolve — ' +
+  'missing, not readable by you, wrong node type, or a name shared by two nodes — is rejected with 400 and NOTHING is ' +
+  'saved; it is never stored as a silently empty block. `column`/`labelColumn`/' +
   '`valueColumn`/`orderBy.column` are the column NAMES as shown in the table (not column ids). A table or form that ' +
   'sits in a PRIVATE subtree is silently skipped on the published page — that is deliberate, never a bug to work around.\n' +
   'LINKS: every `target` is {kind:"url", href} (absolute http(s)://, mailto: or tel: only) or {kind:"node", nodeId} ' +
@@ -65,8 +83,11 @@ export function registerPageTools(server) {
       description:
         'Create a new PAGE node in a Rootr (루터) workspace — a web page assembled from safe typed blocks, which ' +
         'can then be published to the web at a public address (see rootr_publish_node). Use this when someone asks ' +
-        'for a landing page, an announcement page, an event page, a product/pricing page or a signup page. ' +
+        'for a DASHBOARD / report / KPI board over their tables, spreadsheets or logs (46 live chart kinds, numbers stay ' +
+        'current), or for a landing page, an announcement page, an event page, a product/pricing page or a signup page. ' +
         'Omit `blocks` to start from a hero/text/footer skeleton. ' +
+        'In the response, `nodeId` is the page\'s node id — pass THAT as `pageId` to every later page tool ' +
+        '(and in REST paths like /v1/pages/:nodeId/live-data). The response `id` is an internal page-row id and is NOT accepted there (404). ' +
         BLOCK_GUIDE +
         ' ' +
         NODE_URL_HINT +
@@ -222,9 +243,12 @@ export function registerPageTools(server) {
       title: 'Read what a page\'s live blocks currently show',
       description:
         'Read the values a Rootr (루터) PAGE\'s live blocks (liveStats/liveTable/liveChart) are showing right now — ' +
-        'the aggregates, rows and chart points computed from their source tables. Use it to check that a live block ' +
-        'points at the right table and column: an empty result usually means the source is missing, is in a PRIVATE ' +
-        'subtree, or the column name does not match.',
+        'the aggregates, rows and chart data computed from their source tables, spreadsheets or logs. Use it after ' +
+        'building a dashboard to check every chart actually draws. Each chart carries `data` shaped by kind ' +
+        '(category {labels, series[]} · single {value, previous, goal, spark} · xy · distribution · tree · flow · ohlc · range). ' +
+        'A chart that cannot draw says why: `{shape:"empty", reason:"column_missing"|"no_rows"|"needs_number", column}` — ' +
+        'fix that column name or filter. A block missing from the result means its source was not found, is deleted, ' +
+        'or sits in a PRIVATE subtree.',
       annotations: { readOnlyHint: true, destructiveHint: false },
       inputSchema: {
         pageId: z.string().describe(`PAGE node id${NODE_TARGET_HINT}`),

package/lib/mcp-tools/presentations.js

@@ -10,7 +10,7 @@ import { jsonResult, errorResult, makeClient, requireWorkspace, resolveNodeId, N
 const AUTHORING_GUIDE =
   'Authoring guide: give each slide ONE assertion-style title (a claim, e.g. "Latency dropped 40% after the cache fix" — ' +
   'not a topic label like "Latency"), plus blocks[] (bullet-like {id, heading?, body?, icon?} items) and, where useful, ' +
-  'a diagram ({type:"mermaid", code}) or images. Canvas is 16:9 (1280x720). Meaning must live in TEXT — ' +
+  'a diagram ({type:"mermaid", code} — drawn on "content" slides) or images. Canvas is 16:9 (1280x720). Meaning must live in TEXT — ' +
   'title/blocks[].heading/blocks[].body/notes are what auto-connects into the knowledge graph; diagrams/code/html and the ' +
   'image pixels themselves are visual-only and are NOT indexed, so never put facts ONLY in a diagram or picture.\n' +
   'Images: `image` is the single primary/background image (cover, section, full-bleed); `images[]` holds additional ' +
@@ -19,8 +19,10 @@ const AUTHORING_GUIDE =
   'an https URL, or a data: URI — you cannot upload the file bytes through these MCP tools, only reference the resulting URL. ' +
   'To get a REAL image, call rootr_generate_image with an English prompt (say "no text"), then put the returned `url` ' +
   'into the slide image\'s `src`; rootr_remove_image_background cuts out an image\'s background. ' +
-  '`placement` is a layout hint ("full"|"right"|"top"|...); x/y/w/h give freeform PPT-style placement in 1280x720 canvas ' +
-  'coords. ALWAYS add an `alt` caption to every image — alt text is part of the graph text spine, so a captioned image ' +
+  'Set `placement` on the primary `image`: "full" = background (full-bleed on cover/section/closing, faint on content); ' +
+  '"right" / "top" = beside / above the blocks, content slides only; other values are ignored and a content slide without ' +
+  'placement does not draw the image. For `images[]`, x/y/w/h give freeform PPT-style placement in 1280x720 canvas ' +
+  'coords (drawn only when both x and y are set). ALWAYS add an `alt` caption to every image — alt text is part of the graph text spine, so a captioned image ' +
   'connects into the knowledge graph while an uncaptioned one does not.\n' +
   'Use kind to mark each slide\'s role: "cover" (deck title slide), "section" (chapter divider), "content" (body slide, ' +
   'the default), "closing" (last slide / call to action).\n' +
@@ -54,7 +56,13 @@ const imageShape = z
       .optional()
       .describe('Caption / alt text. Part of the knowledge-graph text spine — ALWAYS set this so the image is indexed.'),
     prompt: z.string().optional().describe('English AI-generation prompt, no text baked into the image (used when src is absent)'),
-    placement: z.string().optional().describe('Layout hint: "full" | "right" | "top" | ...'),
+    placement: z
+      .string()
+      .optional()
+      .describe(
+        'Where the primary `image` goes: "full" (background — full-bleed on cover/section/closing, faint on content) | ' +
+          '"right" | "top" (content slides only). Other values are ignored.',
+      ),
     x: z.number().optional().describe('Freeform placement X in 1280x720 canvas coords'),
     y: z.number().optional().describe('Freeform placement Y in 1280x720 canvas coords'),
     w: z.number().optional().describe('Freeform placement width in canvas coords'),
@@ -66,7 +74,14 @@ const slideShape = z
   .object({
     id: z.string().optional().describe('Unique slide id, e.g. "SLD-001". Auto-generated if omitted.'),
     kind: z.string().optional().describe('cover | section | content | closing'),
-    layout: z.string().optional().describe('Layout hint, e.g. "2-col" | "kpi-grid" | "timeline"'),
+    layout: z
+      .string()
+      .optional()
+      .describe(
+        'Block arrangement on content slides: "two-col" (needs 2+ blocks) | "kpi-grid" (alias "kpi"). ' +
+          'Any other value silently falls back to the default arrangement. On cover/section slides it is printed as ' +
+          'the small label above the title.',
+      ),
     title: z.string().optional().describe('Assertion-style title (the claim this slide makes) — text spine'),
     blocks: z
       .array(
@@ -82,7 +97,10 @@ const slideShape = z
     diagram: z
       .object({ type: z.literal('mermaid').optional(), code: z.string() })
       .optional()
-      .describe('Mermaid diagram; visual only, not indexed — keep the facts in title/blocks too'),
+      .describe(
+        'Mermaid diagram, drawn below the blocks on "content" slides (ignored on cover/section/closing and when the ' +
+          'slide has baked html); visual only, not indexed — keep the facts in title/blocks too',
+      ),
     image: imageShape
       .optional()
       .describe('Single primary/background image (cover, section, full-bleed). See imageShape fields.'),
@@ -242,7 +260,12 @@ export function registerPresentationTools(server) {
       try {
         const client = makeClient();
         presentationId = await resolveNodeId(client, presentationId);
-        const result = await client.appendPresentationSlides(presentationId, ensureSlideIds(slides));
+        // ISSUE-185 — do NOT mint ids here: numbering by this call's own
+        // array index always collides with the deck's existing slides
+        // (e.g. restamping "SLD-001" onto a deck that already has one).
+        // The server fills any omitted slide/block id, avoiding the deck's
+        // current ids (see PresentationsService.appendSlides).
+        const result = await client.appendPresentationSlides(presentationId, slides);
         return jsonResult(result);
       } catch (err) {
         return errorResult(err);
@@ -328,8 +351,8 @@ export function registerPresentationTools(server) {
     },
     async ({ prompt, nodeId, workspace }) => {
       try {
-        const client = makeClient();
-        const ws = requireWorkspace(workspace);
+        const ws = requireWorkspace(workspace); // ISSUE-61 — 워크스페이스를 먼저 정하고 그 키로(attachments.js 와 같은 결함)
+        const client = makeClient(ws);
         nodeId = await resolveOptionalNodeId(client, nodeId);
         const result = await client.generateImage(ws, { prompt, nodeId });
         return jsonResult(result);
@@ -357,8 +380,8 @@ export function registerPresentationTools(server) {
     },
     async ({ attachmentId, nodeId, workspace }) => {
       try {
-        const client = makeClient();
-        const ws = requireWorkspace(workspace);
+        const ws = requireWorkspace(workspace); // ISSUE-61 — 위와 같다
+        const client = makeClient(ws);
         nodeId = await resolveOptionalNodeId(client, nodeId);
         const result = await client.removeImageBackground(ws, { attachmentId, nodeId });
         return jsonResult(result);
@@ -405,7 +428,8 @@ export function registerPresentationTools(server) {
       description:
         'Render a typed diagram spec into a Rootr (루터) presentation slide — architecture, workflow, sequence, ' +
         'dataflow, or lifecycle. The drawing is baked into the slide, so it shows on screen AND in the PDF/PPTX ' +
-        'exports. Use this instead of the mermaid `diagram` field, which the slide viewer does not draw.\n' +
+        'exports. Prefer this over the mermaid `diagram` field when the diagram has to look designed — a plain ' +
+        '"content" slide also draws its mermaid `diagram`, but with mermaid\'s default look.\n' +
         'Call rootr_diagram_schema first to get the exact shape for the family you want — the spec is validated ' +
         'fail-closed and a mismatch is rejected with the offending field named and a suggested fix, which you ' +
         'should apply and retry.\n' +

package/lib/mcp-tools/public.js

@@ -86,7 +86,8 @@ export function registerPublicTools(server) {
         '`{"password": "..."}` locks the page (the content is not sent at all until the password is entered — it is ' +
         'not hidden in the browser), `{"password": null}` unlocks; ' +
         '`{"expiresAt": "2026-12-31T00:00:00Z"}` auto-closes on that date, `null` clears it; ' +
-        '`{"noIndex": true}` asks search engines to stay away; ' +
+        '`{"noIndex": true}` asks search engines to stay away (Team plan and up — a Free workspace gets 403 ' +
+        'PLAN_UPGRADE_REQUIRED; a password-locked page is always hidden and cannot be re-exposed until unlocked); ' +
         '`{"design": {"layout": "board", "skin": "paper"}}` changes how a published TABLE looks — it does not ' +
         'have to be a table (cards, gallery, list, board, timeline, calendar, chart, ranking). ' +
         'For DOCUMENT nodes use rootr_set_document_public instead — documents keep their own settings (skins, ' +
@@ -129,6 +130,8 @@ export function registerPublicTools(server) {
         'currently open, when it expires, whether a password is set (the password itself is never returned), whether ' +
         'cloning is allowed, and whether the pages underneath went out with it. ' +
         '`publishable: false` means this type cannot be published at all (FOLDER). ' +
+        '`closed: "PUBLIC_OWN_ROW_PAGE"` (with `isPublic: false` and a `closedReason`) means publishing is switched on but the ' +
+        'address is closed right now — do NOT hand that URL out; tell the user why and how to reopen it. ' +
         'Call this before publishing so you do not tell the user a page is new when it already had a URL.',
       annotations: { readOnlyHint: true, destructiveHint: false },
       inputSchema: {