rootr-cli 0.18.0 → 0.20.0

package/lib/mcp-tools/databases.js

@@ -128,10 +128,11 @@ export function registerDatabaseTools(server) {
         'column order, so one call keeps the columns in exactly the order you list them. ' +
         'The FIRST property must be type "title" (the row label). Other types: text | number | select | multi_select | ' +
         'status | date | checkbox | url | email | phone | person | files | relation | formula | rollup | ' +
-        'created_time | last_edited_time | created_by | last_edited_by | unique_id. ' +
+        'created_time | last_edited_time | created_by | last_edited_by | unique_id | vector. ' +
         'select/multi_select/status take options:[{name,color,group?}] (group ∈ todo|in_progress|done, status only); ' +
         'relation takes relationDatabaseId; formula takes formula ("{수량} * {단가}"); rollup takes ' +
-        'rollup:{relation,property?,function}; unique_id takes prefix ("TASK" → "TASK-42"). The last seven types are ' +
+        'rollup:{relation,property?,function}; unique_id takes prefix ("TASK" → "TASK-42"); vector takes dimensions ' +
+        '(the length of the embeddings you will store with rootr_set_row_vectors). The last seven types are ' +
         'filled in by the server and take no row value. ' +
         'Views default to a single table view; view types are table | board | gallery | calendar | timeline | list — ' +
         'a "board" view needs config.groupBy (a select/status property id), a "timeline"/"calendar" view needs ' +
@@ -176,8 +177,14 @@ export function registerDatabaseTools(server) {
                   'created_by',
                   'last_edited_by',
                   'unique_id',
+                  'vector',
                 ])
                 .describe('Column type; the FIRST property must be "title"'),
+              dimensions: z
+                .number()
+                .int()
+                .optional()
+                .describe('vector only: the length of every vector you will store, e.g. 1536 or 3072'),
               options: z
                 .array(z.object({ name: z.string(), color: z.string(), group: z.string().optional() }))
                 .optional()
@@ -466,7 +473,13 @@ export function registerDatabaseTools(server) {
           client.getDatabase(id),
           client.listRows(id, { withBody: includeBody === true }),
         ]);
-        return jsonResult({ database, rows });
+        // 감사 ROUND-17 #9 — 좁혀진 롤업(상대 표가 "본인 행만"이거나 못 여는 표)은 값이 전체 합계가 아니다 — 모델이 전체로 옮겨 적지 않게 적는다
+        const narrowed = Array.isArray(database?.narrowedRollups) ? database.narrowedRollups : [];
+        const nameOf = new Map((database?.properties ?? []).map((p) => [p.id, p.name]));
+        const note = narrowed.length
+          ? `Rollup column(s) ${narrowed.map((id) => `"${nameOf.get(id) ?? id}"`).join(', ')} only count rows you can see (the linked table is "own rows only" or not readable) — not full totals.`
+          : undefined;
+        return jsonResult(note ? { database, rows, narrowedRollupsNote: note } : { database, rows });
       } catch (err) {
         return errorResult(err);
       }
@@ -863,6 +876,8 @@ export function registerDatabaseTools(server) {
         'A rollup may also read a FORMULA column in the linked table, and min/max work on date columns ' +
         '(that is how "last call date" is built). ' +
         'For unique_id pass prefix to get "TASK-42" style ids. ' +
+        'For vector pass dimensions — an embedding column YOU fill with rootr_set_row_vectors and search with ' +
+        'rootr_query_vectors (Rootr never embeds it for you; people see only "vector · N dims" in the grid). ' +
         'created_time / last_edited_time / created_by / last_edited_by / unique_id / formula / rollup are filled in by the server — ' +
         'they take no value and rootr_update_row will refuse to set them. ' +
         'Returns the created column WITH ITS id.',
@@ -892,8 +907,9 @@ export function registerDatabaseTools(server) {
             'created_by',
             'last_edited_by',
             'unique_id',
+            'vector',
           ])
-          .describe('Column type'),
+          .describe('Column type ("vector" = an embedding column for agents — pass dimensions)'),
         options: z
           .array(z.object({ name: z.string(), color: z.string(), group: z.string().optional() }))
           .optional()
@@ -954,9 +970,25 @@ export function registerDatabaseTools(server) {
           .optional()
           .describe('rollup only: what to gather through which relation'),
         prefix: z.string().optional().describe('unique_id only: prefix for the number, e.g. "TASK" → "TASK-42"'),
+        dimensions: z
+          .number()
+          .int()
+          .min(1)
+          .max(4096)
+          .optional()
+          .describe('vector only: the length of every vector you will store, e.g. 1536 or 3072'),
+        searchExcluded: z
+          .boolean()
+          .optional()
+          .describe(
+            'Exclude this column from the search index: its values never go into the index behind rootr_ask, AI explore ' +
+              'and rootr_find_similar_rows (people still see them in the table). It is NOT a read permission — the in-app ' +
+              'chat, button AI-fill steps, formula/rollup columns and MCP reads still see the values; to hide values from ' +
+              'people, use an "own rows only" table or a private node. Table managers only.',
+          ),
       },
     },
-    async ({ databaseId, name, type, options, relationDatabaseId, formula, rollup, prefix }) => {
+    async ({ databaseId, name, type, options, relationDatabaseId, formula, rollup, prefix, searchExcluded, dimensions }) => {
       try {
         const client = makeClient();
         const id = await resolveNodeId(client, databaseId);
@@ -968,6 +1000,8 @@ export function registerDatabaseTools(server) {
           formula,
           rollup,
           prefix,
+          searchExcluded,
+          dimensions,
         });
         return jsonResult({ property });
       } catch (err) {
@@ -982,8 +1016,10 @@ export function registerDatabaseTools(server) {
       title: 'Rename a column / set its options',
       description:
         'Rename ONE column of a Rootr (루터) DATABASE, replace the choices of a select/multi_select column, edit a ' +
-        'formula or rollup config, or turn an existing relation column TWO-WAY. ' +
-        'The column TYPE cannot be changed — that would rewrite every row — so add a new column and move the values instead. ' +
+        'formula or rollup config, turn an existing relation column TWO-WAY, or exclude it from the search index ' +
+        '(searchExcluded: true — managers only; values already indexed are removed before this returns). ' +
+        'The column TYPE and a vector column\'s dimensions cannot be changed — that would rewrite every row (or every stored vector) — ' +
+        'so passing type or dimensions is refused; add a new column and move the values instead. ' +
         'Call rootr_read_database first to get the exact propertyId.\n' +
         '`reverseName` on a relation column pairs it with the linked table: that table gets a matching column with ' +
         'this name and filling either side fills the other. Pass an empty string to unpair (neither column is deleted). ' +
@@ -1004,13 +1040,33 @@ export function registerDatabaseTools(server) {
           .optional()
           .describe('rollup only: { relation, property?, function, where? } — replaces the whole config'),
         prefix: z.string().optional().describe('unique_id only: the new prefix'),
+        type: z.string().optional().describe('Not changeable — passing it is refused with the reason'),
+        dimensions: z.number().optional().describe('Not changeable (vector only) — passing it is refused with the reason'),
         reverseName: z
           .string()
           .optional()
           .describe('relation only: pair it two-way under this name in the linked table; "" unpairs'),
+        searchExcluded: z
+          .boolean()
+          .optional()
+          .describe(
+            'Exclude this column from the search index: its values never go into the index behind rootr_ask, AI explore ' +
+              'and rootr_find_similar_rows (people still see them in the table). It is NOT a read permission — the in-app ' +
+              'chat, button AI-fill steps, formula/rollup columns and MCP reads still see the values; to hide values from ' +
+              'people, use an "own rows only" table or a private node. Table managers only. false puts the column back into the index.',
+          ),
       },
     },
-    async ({ databaseId, propertyId, name, options, formula, rollup, prefix, reverseName }) => {
+    async ({ databaseId, propertyId, name, options, formula, rollup, prefix, reverseName, searchExcluded, type, dimensions }) => {
+      // 조용히 무시하지 않는다 — 못 바꾸는 것을 넘기면 까닭과 할 일을 말한다(벡터 차원을 바꾸면 저장된 벡터가 전부 틀려진다).
+      if (type !== undefined || dimensions !== undefined) {
+        return errorResult(
+          new Error(
+            '칸 종류(type)와 벡터 차원(dimensions)은 바꿀 수 없습니다. 새 칸을 만들고 값을 옮겨 주세요.' +
+              '\n힌트: 벡터 칸을 다른 차원으로 쓰려면 rootr_add_column(type "vector", dimensions 지정)으로 새 칸을 만든 뒤 벡터를 다시 넣으세요.',
+          ),
+        );
+      }
       try {
         const client = makeClient();
         const id = await resolveNodeId(client, databaseId);
@@ -1021,6 +1077,7 @@ export function registerDatabaseTools(server) {
           rollup,
           prefix,
           reverseName,
+          searchExcluded,
         });
         return jsonResult({ property });
       } catch (err) {
@@ -1161,7 +1218,10 @@ export function registerDatabaseTools(server) {
       description:
         'Remove ONE column from a Rootr (루터) DATABASE. The values stored under it are NOT erased from the rows, ' +
         'so re-adding a column is not enough to bring them back in the UI — confirm with the user before calling this. ' +
-        'The title column cannot be deleted. Views grouped/dated by the column are cleared automatically.',
+        'Exception: values of a vector column are erased (see below). ' +
+        'The title column cannot be deleted. Views grouped/dated by the column are cleared automatically. ' +
+        'For a vector column the stored vectors are deleted with it (not kept for re-adding — re-add the column and ' +
+        'store the vectors again with rootr_set_row_vectors).',
       annotations: { readOnlyHint: false, destructiveHint: true },
       inputSchema: {
         databaseId: z.string().describe(DATABASE_TARGET_DESC),
@@ -1440,4 +1500,165 @@ export function registerDatabaseTools(server) {
       }
     },
   );
+
+  // ── DB-SEARCH — vector similarity search across rows ──────────────
+
+  server.registerTool(
+    'rootr_find_similar_rows',
+    {
+      title: 'Find semantically similar rows',
+      description:
+        'Find rows in a DATABASE that are semantically similar to a given row (duplicate reports, ' +
+        'a past answer to a similar inquiry, a similar experiment). Uses vector embeddings of the ' +
+        'row\'s columns — no keyword matching. Columns marked "exclude from search index" (searchExcluded) are never ' +
+        'indexed, and on an "own rows only" table you only get your own rows. Only rows that stand out from the ' +
+        'rest of the table are returned (the raw cosine of unrelated rows in one table is often 0.8+, so a fixed ' +
+        'cut-off lies): each row carries `similarityLevel` ("high" | "mid") and the raw `similarityScore`. ' +
+        'An empty list with `compared` > 0 means "nothing is especially similar", not an error. ' +
+        '`state`: "ready", "indexing" (the row, or `pending` other rows of the table, are not indexed yet — the rows found so far are returned; retry in a few seconds), "no-text" (the row has ' +
+        'nothing to compare — it is empty or only its excluded columns are filled; retrying will not help) or ' +
+        '"sync-off" (graph sync is turned off — `syncOffAt` says where to turn it back on: "node" = this table\'s menu, ' +
+        '"folder" = the parent folder named in `syncOffFolder`, "workspace" = workspace settings › General).',
+      annotations: { title: 'Find similar rows', readOnlyHint: true, openWorldHint: false },
+      inputSchema: {
+        databaseId: z.string().describe(DATABASE_TARGET_DESC),
+        rowId: z.string().describe('The row whose similar counterparts you want to find'),
+        topK: z.number().int().min(1).max(20).optional().default(5)
+          .describe('How many similar rows to return (default 5, max 20)'),
+      },
+    },
+    async ({ databaseId, rowId, topK }) => {
+      try {
+        const client = makeClient();
+        const id = await resolveNodeId(client, databaseId);
+        const qs = `rowId=${encodeURIComponent(rowId)}&topK=${topK ?? 5}`;
+        const result = await client.request(`/databases/${encodeURIComponent(id)}/rows/similar?${qs}`);
+        return jsonResult(result);
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
+
+  // ── DB-VECTOR(기획 5단계) — 에이전트용 벡터 칸: 직접 넣고 직접 찾는다 ───────────
+  //
+  // 루터 표가 에이전트의 벡터 저장소가 된다. 행과 같은 권한을 탄다(본인 행만 표에서는 남의 행을 못 넣고 못 찾는다).
+
+  server.registerTool(
+    'rootr_set_row_vectors',
+    {
+      title: 'Store vectors in a vector column',
+      description:
+        'Store YOUR OWN embeddings in a "vector" column of a Rootr (루터) DATABASE — up to 500 { rowId, vector } per ' +
+        'call; sending a row again replaces its vector. Every vector must have exactly the column\'s `dimensions` ' +
+        '(create the column with rootr_add_column type "vector" + dimensions). Rootr does not embed anything here and ' +
+        'charges no AI credits. Rows you may not edit (own-rows-only tables, manager-locked column) are refused ' +
+        'with the reason — nothing is written if any item is invalid. To check which rows already hold a vector, read the ' +
+        'rows (rootr_list_rows / rootr_read_database: each row has `vectors` — column id → dimensions, empty when none). ' +
+        'To read one row\'s vector use rootr_get_row_vector; to remove it use rootr_delete_row_vector.',
+      annotations: { readOnlyHint: false, destructiveHint: false },
+      inputSchema: {
+        databaseId: z.string().describe(DATABASE_TARGET_DESC),
+        column: z.string().describe('The vector column — its id or header name'),
+        items: z
+          .array(z.object({ rowId: z.string(), vector: z.array(z.number()) }))
+          .min(1)
+          .max(500)
+          .describe('[{ rowId, vector: [..numbers..] }]'),
+      },
+    },
+    async ({ databaseId, column, items }) => {
+      try {
+        const client = makeClient();
+        const id = await resolveNodeId(client, databaseId);
+        return jsonResult(await client.putVectors(id, column, items));
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    'rootr_query_vectors',
+    {
+      title: 'Nearest rows by vector',
+      description:
+        'Find the rows of a DATABASE whose stored vector (in a "vector" column) is closest to the vector you pass — ' +
+        'cosine similarity, highest first, with each row\'s values and `score`. Use it as a vector store: embed your ' +
+        'query with the same model you used for rootr_set_row_vectors. `minScore` drops weak matches. Rows the caller ' +
+        'cannot see (own-rows-only tables) are never returned. Rows without a stored vector are skipped. ' +
+        'The column can hold at most 50,000 vectors — a bigger column is refused, not searched partially — and the scan has ' +
+        'no index, so latency grows with the number of rows in the column.',
+      annotations: { readOnlyHint: true, openWorldHint: false },
+      inputSchema: {
+        databaseId: z.string().describe(DATABASE_TARGET_DESC),
+        column: z.string().describe('The vector column — its id or header name'),
+        vector: z.array(z.number()).describe('Query vector — same length as the column\'s dimensions'),
+        topK: z.number().int().min(1).max(100).optional().default(10).describe('How many rows (default 10, max 100)'),
+        minScore: z.number().min(-1).max(1).optional().describe('Only rows with cosine ≥ this'),
+      },
+    },
+    async ({ databaseId, column, vector, topK, minScore }) => {
+      try {
+        const client = makeClient();
+        const id = await resolveNodeId(client, databaseId);
+        return jsonResult(await client.queryVectors(id, column, { vector, topK, minScore }));
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    'rootr_get_row_vector',
+    {
+      title: 'Read one row\'s stored vector',
+      description:
+        'Read the vector stored for ONE row in a "vector" column. Returns { rowId, propId, dimensions, vector }; ' +
+        '`vector` is null when the row has no vector yet — so this is also the check "does this row hold a vector". ' +
+        'Rows you cannot see (own-rows-only tables) are refused.',
+      annotations: { readOnlyHint: true, destructiveHint: false },
+      inputSchema: {
+        databaseId: z.string().describe(DATABASE_TARGET_DESC),
+        rowId: z.string().describe('Row id from rootr_list_rows / rootr_read_database'),
+        column: z.string().describe('The vector column — its id or header name'),
+      },
+    },
+    async ({ databaseId, rowId, column }) => {
+      try {
+        const client = makeClient();
+        const id = await resolveNodeId(client, databaseId);
+        return jsonResult(await client.getRowVector(id, rowId, column));
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    'rootr_delete_row_vector',
+    {
+      title: 'Remove one row\'s stored vector',
+      description:
+        'Remove the vector stored for ONE row in a "vector" column. The row itself and its other values stay. ' +
+        'The vector is gone for queries from then on (rootr_query_vectors will not return it). Rows you cannot ' +
+        'edit (own-rows-only tables, manager-locked column) are refused with the reason.',
+      annotations: { readOnlyHint: false, destructiveHint: true },
+      inputSchema: {
+        databaseId: z.string().describe(DATABASE_TARGET_DESC),
+        rowId: z.string().describe('Row id from rootr_list_rows / rootr_read_database'),
+        column: z.string().describe('The vector column — its id or header name'),
+      },
+    },
+    async ({ databaseId, rowId, column }) => {
+      try {
+        const client = makeClient();
+        const id = await resolveNodeId(client, databaseId);
+        await client.deleteRowVector(id, rowId, column);
+        return jsonResult({ deleted: true, rowId });
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
 }

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}`),

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}`),