rootr-cli 0.10.0 → 0.13.0

package/lib/mcp-tools/forms.js

@@ -7,23 +7,78 @@ const fieldShape = z
     id: z.string().optional().describe('Stable field id (also the key under response `values`). Server-generated if omitted.'),
     name: z.string().describe('Field label shown to respondents'),
     type: z
-      .enum(['text', 'textarea', 'number', 'select', 'multi_select', 'checkbox', 'date'])
+      // FORM-TALLY-P1/P2 — 백엔드 `form-schema.ts`의 FORM_FIELD_TYPES와 **같은 목록**이어야
+      // 한다. 여기만 옛 7종에 머물러 있으면 AI가 이메일·파일 항목을 못 만든다.
+      .enum([
+        'text', 'textarea', 'number', 'select', 'multi_select', 'checkbox', 'date',
+        'email', 'phone', 'url', 'rating', 'scale', 'time', 'file',
+        'matrix', 'ranking', 'csat', 'nps',
+      ])
       .describe('Field input type'),
     required: z.boolean().optional().describe('Whether the field must be filled in'),
     options: z
-      .array(z.object({ name: z.string(), color: z.string() }))
+      // 보기는 글자로만 적어도 된다 — 색은 꾸밈이라 서버가 기본값을 붙인다.
+      .array(z.union([z.string(), z.object({ name: z.string(), color: z.string().optional() })]))
       .optional()
-      .describe('Choices for select/multi_select fields'),
+      .describe('Choices for select/multi_select/matrix/ranking fields'),
+    help: z.string().optional().describe('One line under the question, e.g. "예: 010-0000-0000"'),
+    placeholder: z.string().optional().describe('Greyed-out example inside the input'),
+    min: z.number().optional().describe('rating/scale only: lowest number (rating 1, scale 0 or 1)'),
+    max: z.number().optional().describe('rating/scale only: highest number (rating 5, scale 10). 2–10.'),
+    rows: z.array(z.string()).optional().describe('matrix only: the rows down the left side'),
+    page: z.number().optional().describe('Which page this question is on (1-based). Split a long form.'),
+    hidden: z
+      .boolean()
+      .optional()
+      .describe('Not shown; filled from the URL (?이름=값). Use to record where a signup came from.'),
+    showIf: z
+      .object({ fieldId: z.string(), equals: z.string() })
+      .optional()
+      .describe('Show this question only when an earlier field equals this value (conditional logic).'),
   })
   .describe('One form field definition.');
 
 const FIELDS_GUIDE =
-  'Fields are typed inputs shown to respondents: text | textarea | number | select | multi_select | checkbox | date; ' +
-  'select/multi_select need `options` ({name,color}[]). Read the form first (rootr_read_form) before updating so ' +
+  'Fields are typed inputs shown to respondents. Basic: text | textarea | number | select | multi_select | ' +
+  'checkbox | date. Contact: email | phone | url (each is format-checked server-side). Survey: rating (stars) | ' +
+  'scale (numbered buttons) | csat (1-5) | nps (0-10) | matrix (rows x options, Likert) | ranking (drag order). ' +
+  'Also: time (HH:MM) and file (uploaded on the published page only). ' +
+  'select/multi_select/matrix/ranking need `options` ({name,color}[]); matrix also needs `rows`. ' +
+  'Per-field extras: `help` (a hint line), `placeholder`, `page` (split into multiple pages), `hidden` + URL ' +
+  'params (record the traffic source), `showIf` (show only when an earlier answer matches). ' +
+  'Read the form first (rootr_read_form) before updating so ' +
   'you keep each field\'s `id` stable — response values are keyed by field id, so renaming/dropping an id orphans ' +
   'past responses\' answers for that field.';
 
 /** FORM node tools: create/read/update the field definitions, list/submit responses, manage public share links. */
+/**
+ * FORM-PERM / FORM-MIRROR — 폼 config 에 담기는 것.
+ * 자물쇠와 기본값은 코드에는 있는데 도구 설명에 없으면 에이전트가 영영 못 쓴다.
+ */
+const FORM_CONFIG_DESC =
+  'Form config object. Known keys: ' +
+  '`permissions: { editLock: "managers"|"open", responseScope: "own"|"all" }` — by default only managers may ' +
+  'edit the questions and each person sees only their OWN responses; set responseScope "all" to let writers ' +
+  'read every response (휴가 사유처럼 민감한 것은 기본값 그대로 두세요). ' +
+  '`mirror: { fieldMap, defaults: { <표의 칸 이름 또는 id>: value } }` — `defaults` stamps extra values onto the ' +
+  'row a response creates, for columns the person did not answer; use it to start a 신청 at "상신 중" so a ' +
+  'manager has something to move to 승인/거절. What the person actually answered always wins. ' +
+  '`publicSubmit` ("anon"|"login") — who may answer from outside the workspace. Publishing the form ' +
+  '(`rootr_publish_node`, or the 웹에 공개 switch) turns this on by itself, so you almost never set it by hand; ' +
+  'to stop taking answers use `closesAt`/`maxResponses`, or unpublish. ' +
+  // FORM-TALLY-P1/P2 — 여기 안 적으면 에이전트는 이 설정이 있는 줄도 모른다.
+  '`intro` / `thankYou` — markdown shown above the form and after submitting (put the date, venue and fee in ' +
+  '`intro` instead of cramming them into question labels). ' +
+  '`redirectUrl` — send people here after submitting (payment, next step). ' +
+  '`notifyEmails: string[]` — email these addresses when a response arrives (up to 10). Without it nobody knows. ' +
+  '`confirmEmailField` — the id of an email question; the respondent gets a confirmation mail. ' +
+  '`confirmEmailBody` — what that mail says. ' +
+  '`closesAt` (ISO) / `maxResponses` — stop accepting after a date or a headcount; `closedMessage` explains why. ' +
+  '`webhookUrl` — POST each response to this URL; a Slack incoming-webhook URL works as-is. ' +
+  '`theme` (clean|paper|noir|ocean|sunset|mint|bento|brutal|vivid|dark), `cover`, `logo` — how the published ' +
+  'form looks. `cover`/`logo` are image URLs: upload the file with `rootr_upload_attachment` and pass the url ' +
+  'it returns; leave `cover` empty and the form wears the default Rootr cover.'
+
 export function registerFormTools(server) {
   server.registerTool(
     'rootr_create_form',
@@ -41,7 +96,7 @@ export function registerFormTools(server) {
         icon: z.string().optional().describe('Emoji icon for the node'),
         fields: z.array(fieldShape).optional().describe('Initial field definitions; defaults to an empty form'),
         targetDatabaseId: z.string().optional().describe(`DATABASE node id${NODE_TARGET_HINT} whose rows mirror this form's responses`),
-        config: z.record(z.unknown()).optional().describe('Free-form form config object (e.g. publicSubmit mode)'),
+        config: z.record(z.unknown()).optional().describe(FORM_CONFIG_DESC),
         workspace: z.string().optional().describe('Workspace id; defaults to ROOTR_WORKSPACE/config if omitted'),
       },
     },
@@ -98,7 +153,7 @@ export function registerFormTools(server) {
         formId: z.string().describe(`FORM node id${NODE_TARGET_HINT}`),
         fields: z.array(fieldShape).optional().describe('COMPLETE fields array to set — omitted existing fields will be dropped'),
         targetDatabaseId: z.string().nullable().optional().describe(`DATABASE node id${NODE_TARGET_HINT} to mirror responses into, or null to unlink`),
-        config: z.record(z.unknown()).optional().describe('Free-form form config object (e.g. publicSubmit mode)'),
+        config: z.record(z.unknown()).optional().describe(FORM_CONFIG_DESC),
         icon: z.string().optional().describe('Emoji icon for the node'),
       },
     },

package/lib/mcp-tools/misc.js

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 
-import { jsonResult, errorResult, makeClient } from './shared.js';
+import { jsonResult, errorResult, makeClient, resolveNodeId, NODE_TARGET_HINT } from './shared.js';
 import { resolveTarget, requireResolved } from '../resolve.js';
 
 /** Miscellaneous document/node tools: version history, trash. */
@@ -95,4 +95,87 @@ export function registerMiscTools(server) {
       }
     },
   );
+
+  // ── READ-ACK — 읽고 확인해야 하는 문서 ─────────────────────────────────
+  // 규정·공지처럼 "읽었다"를 남겨야 하는 것. 표·폴더에 걸면 그 안의 문서 전부에
+  // 걸리고, 얼마나 읽었는지 완료율로 본다.
+
+  server.registerTool(
+    'rootr_read_requirement',
+    {
+      title: 'Read the read-acknowledgement status',
+      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. ' +
+        '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 },
+      inputSchema: {
+        nodeId: z.string().describe(`Node id${NODE_TARGET_HINT}`),
+      },
+    },
+    async ({ nodeId }) => {
+      try {
+        const client = makeClient();
+        return jsonResult(await client.readRequirement(await resolveNodeId(client, nodeId)));
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    'rootr_set_read_requirement',
+    {
+      title: 'Require people to read a document',
+      description:
+        'Make a Rootr (루터) node REQUIRED READING for the given people. Put it on a DOCUMENT for one notice, ' +
+        'or on a DATABASE/FOLDER to require everything inside (완료율 rolls up per person). `dueAt` is an ISO ' +
+        'date or null for no deadline; `requireExplicitAck: true` means opening it is not enough — the person ' +
+        'must press 확인. Replaces the whole roster, so send the full `userIds` list. NOTE: this records a real ' +
+        'person as the setter, so it needs a key that acts as a user (a PAT); a workspace connector key with no ' +
+        'user attached is refused.',
+      annotations: { readOnlyHint: false, destructiveHint: false },
+      inputSchema: {
+        nodeId: z.string().describe(`Node id${NODE_TARGET_HINT}`),
+        userIds: z.array(z.string()).describe('Everyone who must read it (replaces the current roster)'),
+        dueAt: z.string().nullable().optional().describe('ISO date, or null for no deadline'),
+        requireExplicitAck: z
+          .boolean()
+          .optional()
+          .describe('true = opening is not enough, the person must press 확인'),
+      },
+    },
+    async ({ nodeId, userIds, dueAt, requireExplicitAck }) => {
+      try {
+        const client = makeClient();
+        const id = await resolveNodeId(client, nodeId);
+        return jsonResult(await client.setReadRequirement(id, { userIds, dueAt, requireExplicitAck }));
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    'rootr_clear_read_requirement',
+    {
+      title: 'Stop requiring a document to be read',
+      description:
+        'Remove the READ-ACK requirement from a Rootr (루터) node. The record of who already read it is not ' +
+        'shown any more; the node itself is untouched.',
+      annotations: { readOnlyHint: false, destructiveHint: true },
+      inputSchema: {
+        nodeId: z.string().describe(`Node id${NODE_TARGET_HINT}`),
+      },
+    },
+    async ({ nodeId }) => {
+      try {
+        const client = makeClient();
+        return jsonResult(await client.clearReadRequirement(await resolveNodeId(client, nodeId)));
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
 }

package/lib/mcp-tools/presentations.js

@@ -268,7 +268,11 @@ export function registerPresentationTools(server) {
       try {
         const client = makeClient();
         presentationId = await resolveNodeId(client, presentationId);
-        const result = await client.updatePresentationSlide(presentationId, slideId, slide);
+        // 블록 id 는 이 도구도 채워 준다 — 스키마가 "생략하면 자동 생성"이라고
+        // 적어 두고서 이 길로만 400(blocks[].id is required)을 내던 것을 고친다
+        // (2026-08-29 실측). 슬라이드 id 는 서버가 어차피 slideId 로 못 박는다.
+        const patched = ensureSlideIds([{ ...slide, id: slideId }])[0];
+        const result = await client.updatePresentationSlide(presentationId, slideId, patched);
         return jsonResult(result);
       } catch (err) {
         return errorResult(err);

package/lib/mcp-tools/public.js

@@ -0,0 +1,148 @@
+import { z } from 'zod';
+
+import { jsonResult, errorResult, makeClient, resolveNodeId, NODE_TARGET_HINT } from './shared.js';
+
+/**
+ * PUBLIC-DB-DESIGN — 공개한 표를 **표 말고 다른 꼴로도** 보여준다
+ * (창업자 지시 2026-08-28: "꼭 표 형태일 필욘 없잖아").
+ * 값 목록은 서버(`public-nodes.dto.ts`)와 **같아야** 한다.
+ */
+const DB_DESIGN_SCHEMA = z.object({
+  layout: z
+    .enum(['table', 'cards', 'gallery', 'list', 'board', 'timeline', 'calendar', 'chart', 'ranking'])
+    .optional(),
+  skin: z.enum(['clean', 'paper', 'dark', 'vivid', 'bento', 'brutal']).optional(),
+});
+
+/**
+ * PUBLIC-ANY — **어떤 타입이든 공개 발행한다**(창업자 지시 2026-08-27).
+ *
+ * 문서·덱만 되던 것을 표·시트·화이트보드·폼·이슈·로그·CRM·녹음·서명문서까지 열었다.
+ * 문서는 이 도구로 불러도 예전 발행 경로로 넘어가므로, **무엇을 공개하든 여기 하나만
+ * 쓰면 된다** — 타입마다 다른 도구를 찾을 필요가 없다.
+ */
+export function registerPublicTools(server) {
+  server.registerTool(
+    'rootr_publish_node',
+    {
+      title: 'Publish anything to a public URL',
+      description:
+        'Publish ANY Rootr (루터) node at a public read-only URL (rootr.io/p/{slug}) — a DATABASE (visitors get a ' +
+        'searchable table and can clone it into their own workspace), SPREADSHEET, WHITEBOARD, FORM (questions only), ' +
+        'ISSUE_TRACKER, LOG, CRM, RECORDING (transcript only), SIGNED or DOCUMENT. Use this instead of ' +
+        'rootr_publish_document unless you specifically want the document-only extras (skins, edit proposals). ' +
+        'FOLDER cannot be published. ' +
+        'Set `includeChildren: true` to publish everything underneath as well — the WHOLE subtree, grandchildren ' +
+        'included, each getting its own URL and listed on the parent page. Leave it off and only this one node goes ' +
+        'out (its sub-page names do not even appear). Turning it back off, closing the parent, moving a child out, ' +
+        'or deleting the parent all close the pages that went out because of it — pages the owner published on their ' +
+        'own are left alone. ' +
+        'What is deliberately NOT exposed: a table\'s person/attachment/relation columns, the documents attached to ' +
+        'its rows, form responses, recording audio, CRM contacts and deal amounts, and signer names on a signed ' +
+        'document. Rows/entries are capped at 500 per page and the page says so when it truncates. ' +
+        'Owner-level action (MANAGE): use an ACCOUNT key (PAT), not a workspace-scoped/connector token. ' +
+        'Safe to call again — the slug never changes, so links already shared stay valid.',
+      annotations: { readOnlyHint: false, destructiveHint: false },
+      inputSchema: {
+        target: z.string().describe(`Node id${NODE_TARGET_HINT}`),
+        includeChildren: z
+          .boolean()
+          .optional()
+          .describe('Also publish everything underneath (whole subtree). Default false.'),
+        view: z
+          .string()
+          .optional()
+          .describe('DATABASE only: which saved view the public page opens with (view id).'),
+        design: DB_DESIGN_SCHEMA.optional().describe(
+          'DATABASE only: how the public page presents the table. `layout` is one of ' +
+            'table, cards, gallery, list, board, timeline, calendar, chart, ranking; `skin` is one of ' +
+            'clean, paper, dark, vivid, bento, brutal. Only the keys you send change — setting a skin ' +
+            'leaves the layout alone. Layouts that need a column (calendar/timeline need a date, board a ' +
+            'select/status, ranking a number, chart either) fall back to the table and say why.',
+        ),
+      },
+    },
+    async ({ target, includeChildren, view, design }) => {
+      try {
+        const client = makeClient();
+        const id = await resolveNodeId(client, target);
+        return jsonResult(await client.publishNode(id, { includeChildren, view, design }));
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    'rootr_set_node_public',
+    {
+      title: 'Update public settings of anything published',
+      description:
+        'Partially update a published Rootr (루터) node\'s public settings — only the fields you pass change, and ' +
+        'the slug is never touched, so shared links stay valid. ' +
+        '`{"isPublic": false}` closes it (and closes whatever went out under it); ' +
+        '`{"includeChildren": false}` closes just the sub-pages; ' +
+        '`{"allowClone": false}` hides the "clone this" button AND refuses the clone API; ' +
+        '`{"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; ' +
+        '`{"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, ' +
+        'edit proposals) on the older path. Owner-level action (MANAGE): use an account key (PAT).',
+      annotations: { readOnlyHint: false, destructiveHint: false },
+      inputSchema: {
+        target: z.string().describe(`Node id${NODE_TARGET_HINT}`),
+        isPublic: z.boolean().optional(),
+        includeChildren: z.boolean().optional(),
+        allowClone: z.boolean().optional(),
+        noIndex: z.boolean().optional(),
+        expiresAt: z.string().nullable().optional().describe('ISO date, or null to clear'),
+        password: z.string().nullable().optional().describe('null or "" removes the lock'),
+        view: z.string().optional().describe('DATABASE only: view id the public page opens with'),
+        design: DB_DESIGN_SCHEMA.optional().describe(
+          'DATABASE only: how the public page presents the table. `layout` — table, cards, gallery, list, ' +
+            'board, timeline, calendar, chart, ranking. `skin` — clean, paper, dark, vivid, bento, brutal. ' +
+            'Only the keys you send change.',
+        ),
+      },
+    },
+    async ({ target, ...settings }) => {
+      try {
+        const client = makeClient();
+        const id = await resolveNodeId(client, target);
+        const body = Object.fromEntries(Object.entries(settings).filter(([, v]) => v !== undefined));
+        return jsonResult(await client.setNodePublic(id, body));
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    'rootr_node_public_status',
+    {
+      title: 'Is this published, and at what URL',
+      description:
+        'Check whether a Rootr (루터) node is published and how: its public slug (rootr.io/p/{slug}), whether it is ' +
+        '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). ' +
+        '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: {
+        target: z.string().describe(`Node id${NODE_TARGET_HINT}`),
+      },
+    },
+    async ({ target }) => {
+      try {
+        const client = makeClient();
+        const id = await resolveNodeId(client, target);
+        return jsonResult(await client.nodePublicStatus(id));
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
+}

package/lib/mcp-tools/signed.js

@@ -35,7 +35,21 @@ const APPROVAL_STEP = z.object({
   members: z
     .array(
       z.object({
-        userId: z.string().describe('워크스페이스 멤버의 userId (외부인은 아직 결재자가 될 수 없다)'),
+        userId: z
+          .string()
+          .optional()
+          .describe('워크스페이스 멤버의 userId. 밖의 사람이면 대신 email을 쓴다'),
+        email: z
+          .string()
+          .optional()
+          .describe(
+            '워크스페이스 밖 결재자의 메일 주소. 그 사람에게 서명 링크가 메일로 가고, ' +
+              '계정 없이 서명한다. userId와 둘 중 하나만 쓴다',
+          ),
+        displayName: z
+          .string()
+          .optional()
+          .describe('메일 결재자를 화면에 뭐라고 부를지. 생략하면 메일 주소를 그대로 쓴다'),
         role: z
           .enum(['AUTHOR', 'REVIEWER', 'APPROVER'])
           .optional()
@@ -142,7 +156,8 @@ export function registerSignedDocTools(server) {
         'Replace the approval line (결재라인) of a SIGNED document. The array order IS the signing order; ' +
         'each step can require everyone (ALL), anyone (ANY) or N of M. Only possible BEFORE submit — once ' +
         'the document is submitted the line is frozen with the body (409 SIGNED_DOC_LOCKED); reject it first ' +
-        'to reopen. All members must be workspace members.',
+        'to reopen. Each member is EITHER a workspace member (userId) OR an outside person (email) — ' +
+        'an email signer gets a signing link by mail and signs without an account. Never both on one member.',
       annotations: { readOnlyHint: false, destructiveHint: true },
       inputSchema: {
         nodeId: z.string().describe(`서명문서 노드 id${NODE_TARGET_HINT}`),
@@ -234,21 +249,29 @@ export function registerSignedDocTools(server) {
     {
       title: 'Submit (freeze + first-sign) a signed document',
       description:
-        'Submit a SIGNED document: the body and attachments FREEZE (their SHA-256 is recorded), the author ' +
-        'signs first, and the next step\'s signers are notified. IRREVERSIBLE except by rejection — after ' +
-        'this the only way to change the content is a revision (rootr_revise_signed_document). Needs the ' +
-        'emailed code from rootr_request_signing_code.',
+        'Submit a SIGNED document: the body and attachments FREEZE (their SHA-256 is recorded) and the ' +
+        'first step\'s signers are notified. IRREVERSIBLE except by rejection — after this the only way ' +
+        'to change the content is a revision (rootr_revise_signed_document). ' +
+        'Submitting and signing are DIFFERENT acts: submitting only needs write access. `code` is required ' +
+        'ONLY when the submitter is themselves a signer in step 1, because then their signature is stamped ' +
+        'at the same time — get it with rootr_request_signing_code and ask the human for it. If step 1 has ' +
+        'no account members (e.g. only email signers), omit `code` entirely. When in doubt omit it: the ' +
+        'server answers REAUTH_REQUIRED if a code was in fact needed.',
       annotations: { readOnlyHint: false, destructiveHint: true },
       inputSchema: {
         nodeId: z.string().describe(`서명문서 노드 id${NODE_TARGET_HINT}`),
-        code: z.string().describe(CODE_HINT),
+        code: z
+          .string()
+          .optional()
+          .describe(`올리는 사람이 1단계 서명자일 때만 필요합니다. ${CODE_HINT}`),
         workspace: z.string().optional().describe('워크스페이스 id (생략하면 설정값)'),
       },
     },
     async ({ nodeId, code, workspace }) => {
       try {
         const client = makeClient(workspace);
-        return jsonResult(await client.submitSignedDoc(await resolveNodeId(client, nodeId), { code }));
+        const id = await resolveNodeId(client, nodeId);
+        return jsonResult(await client.submitSignedDoc(id, code ? { code } : {}));
       } catch (err) {
         return errorResult(err);
       }
@@ -314,9 +337,10 @@ export function registerSignedDocTools(server) {
     {
       title: 'Reopen an unsigned signed-document draft',
       description:
-        'Unlock a SIGNED document that was submitted but that NOBODY has signed yet, so the body and the ' +
-        'approval line can be edited again. Once any signature exists this refuses — make a revision instead ' +
-        '(rootr_revise_signed_document).',
+        'Unlock a SIGNED document so the body and the approval line can be edited again. Works when the ' +
+        'document was sent back (REJECTED), or when it is still in progress and **nobody has signed yet** — ' +
+        'the escape hatch for "I submitted it to the wrong address". Once any signature exists this refuses: ' +
+        'make a revision instead (rootr_revise_signed_document).',
       annotations: { readOnlyHint: false, destructiveHint: true },
       inputSchema: {
         nodeId: z.string().describe(`서명문서 노드 id${NODE_TARGET_HINT}`),
@@ -416,12 +440,16 @@ export function registerSignedDocTools(server) {
   server.registerTool(
     'rootr_bulk_sign_documents',
     {
-      title: 'Sign many Rootr documents at once',
+      title: 'Submit and sign many Rootr documents at once',
       description:
-        'Sign up to 100 SIGNED documents in one call with ONE emailed code (get it with ' +
-        'rootr_request_signing_code + bulk: true). Documents where it is not your turn are skipped and ' +
-        'reported, not failed. This is what makes 연구노트 usable in practice — a 연구책임자 signing "이번 주 ' +
-        '미점검 12건" without opening each one.',
+        'Process up to 100 SIGNED documents in one call with ONE emailed code (get it with ' +
+        'rootr_request_signing_code + bulk: true). ' +
+        '**DRAFT documents are submitted too** — you do NOT need a separate per-document code to submit ' +
+        'them first. A draft is frozen and, if you are a step-1 signer, stamped at the same time; a document ' +
+        'already IN_PROGRESS is simply signed. Each result carries `did`: "submitted", "submitted+signed" ' +
+        'or "signed". Documents where it is not your turn are skipped and reported, not failed. ' +
+        'This is what makes 연구노트 usable in practice — a 연구책임자 clearing "이번 주 미점검 12건" ' +
+        'without opening each one. Submitting FREEZES the body irreversibly, so pass only the ids you mean.',
       annotations: { readOnlyHint: false, destructiveHint: true },
       inputSchema: {
         nodeIds: z.array(z.string()).min(1).max(100).describe('서명할 노드 id 목록 (경로도 됩니다)'),

package/lib/mcp-tools/workspaces.js

@@ -152,15 +152,27 @@ export function registerWorkspaceTools(server) {
   server.registerTool(
     'rootr_scaffold_plan',
     {
-      title: 'Plan a workspace scaffold from an intent — then ASK THE USER before building',
+      title: 'Step 1 of scaffolding — get the design method, then think and ask',
       description:
-        'Step 1 of scaffolding, ALWAYS call this first. Given a natural-language intent (e.g. "SRE 온콜 위키" or ' +
-        '"sales CRM for a 5-person team"), Rootr\'s consultant returns a questionPolicy (ask the user MIN 3, up ' +
-        'to 10 clarifying questions — this is not optional), the dimensions to cover, domain frameworks, and the ' +
-        'buildingBlocks menu (DATABASE/DOCUMENT/SPREADSHEET/WHITEBOARD/FORM/ISSUE_TRACKER/FOLDER). You must then ' +
-        'GENERATE your own questions from those frameworks, ask the user, and only design the tree AFTER their ' +
-        'answers — every answer must visibly shape the result. Never build straight from a one-line intent. ' +
-        'No workspace needed; create with rootr_create_workspace or rootr_scaffold_apply afterwards.',
+        'ALWAYS call this first. There are NO templates and NO domain skeletons behind it — deliberately. It ' +
+        'does not classify your intent and it will not hand you a structure; what comes back is the METHOD: ' +
+        '`analyzeFirst` (the questions to answer about how this job actually runs before you design anything — ' +
+        'the daily and weekly rhythm, what piles up, what moves through stages, what arrives from outside, where ' +
+        'money is added up, what causes trouble when it is late, and above all what is UNIQUE to this job), ' +
+        '`designRules` (how to turn those answers into structure — nouns that pile up become DATABASEs, "one A ' +
+        'has many B" becomes a relation, stages become select + board, dates become calendar, outside input ' +
+        'becomes FORM + collectInto, calculation becomes SPREADSHEET, counting becomes rollup), `buildingBlocks` ' +
+        '(what the product actually offers), `questionPolicy` (ask the user 3-10 questions — you WRITE them, ' +
+        'none are provided), and `loop` (the whole sequence). Design it from scratch every time: a bakery, a ' +
+        'dental clinic and an SRE team need different things, and no catalogue of skeletons could hold them. ' +
+        'Treat it exactly like a coding request. When someone says "build me this" you ask a few clarifying ' +
+        'questions, write the code, compile it, run the tests, leave a README, and report. Same sequence here: ' +
+        'analyzeFirst = understanding the requirement · questionPolicy = the questions you ask · designRules = ' +
+        'writing the code · rootr_scaffold_review = compiling (fix what it flags, compile again) · ' +
+        'rootr_scaffold_apply = building · the how-to-use manual = the README · rootr_test_workspace = running ' +
+        'the tests. The user should only ever have to type that one sentence — ask your questions, take their ' +
+        'answers, and finish the whole thing in this conversation. If they do not answer or say "just do it", ' +
+        'assume the most plausible answers, build it anyway, and record the assumptions in the manual.',
       annotations: { readOnlyHint: true, destructiveHint: false },
       inputSchema: {
         intent: z.string().describe('Natural-language description of what the workspace/tree should be for'),
@@ -184,8 +196,10 @@ export function registerWorkspaceTools(server) {
       description:
         'Create an entirely new Rootr (루터) workspace pre-populated with the given document tree. ' +
         'REQUIRES an account key (PAT) with the workspaces:create scope — a workspace-scoped key cannot do this. ' +
-        'PRECONDITION: call rootr_scaffold_plan first and ask the user its 3-10 clarifying questions; design the ' +
-        'tree from their answers. Build a real tool, not a pile of thin markdown files: mix DATABASE (board/' +
+        'PRECONDITION: rootr_scaffold_plan first, ask the user its 3-10 clarifying questions, design the tree from ' +
+        'their answers, then run rootr_scaffold_review and fix everything it flags at `error` level. The ' +
+        'response carries the same `review` back, so a low score here means you shipped something thin. ' +
+        'Build a real tool, not a pile of thin markdown files: mix DATABASE (board/' +
         'timeline views, seed rows), SPREADSHEET (formulas), FORM, ISSUE_TRACKER and rich multi-section DOCUMENTs ' +
         'where they fit, and set an emoji `icon` on folders/databases/key documents. The `tree` shape follows ' +
         'the scaffold schema in llms.txt (max 200 nodes). AFTER creating: if your runtime can receive HTTP ' +
@@ -209,15 +223,105 @@ export function registerWorkspaceTools(server) {
     },
   );
 
+  server.registerTool(
+    'rootr_scaffold_review',
+    {
+      title: 'Check a designed tree BEFORE building it — the compiler pass',
+      description:
+        'Step 3 of scaffolding (plan → ask → design → REVIEW → fix → apply). Give it the tree you designed and ' +
+        'it returns { score 0-100, counts, findings[], summary } — every finding is a concrete defect with the ' +
+        'node path, e.g. a table whose only column is the title (that is a list, not a table), a lifecycle ' +
+        'column with no board view, a date column with no calendar, a form with nowhere to collect answers, ' +
+        'tables that are never related to each other, an empty guide document. Fix what it flags and review ' +
+        'again — like re-running a compiler — until nothing at `error` level is left. The rules are ' +
+        'domain-agnostic, so this works for a bakery or a dental clinic exactly as well as for a SaaS team. ' +
+        'Creates nothing and needs no workspace, so run it as many times as you like before committing.',
+      annotations: { readOnlyHint: true, destructiveHint: false },
+      inputSchema: {
+        tree: treeArg('The scaffold tree you designed — an ARRAY of node objects, same shape you would pass to rootr_scaffold_apply'),
+      },
+    },
+    async ({ tree }) => {
+      try {
+        const client = makeClient();
+        const result = await client.scaffoldReview(parseTree(tree));
+        return jsonResult(result);
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    'rootr_review_workspace',
+    {
+      title: 'Check the workspace you ACTUALLY built — not the tree you sent',
+      description:
+        'Step 5, after building. `rootr_scaffold_review` grades the tree you DESIGNED; this grades what really ' +
+        'exists in the workspace right now — whatever tools made it. Run it after every build: a design can score ' +
+        '100 and still land broken (a form whose answers go nowhere, a view whose filter vanished, rows that never ' +
+        'got linked). Returns the same { score, counts, findings[], summary }. Pass `rootPath` to grade only the ' +
+        'subtree you just added, otherwise an older workspace drags the score down and the number stops meaning ' +
+        'anything. Fix what it flags with the normal tools (add rows, write the guide document, add the missing ' +
+        'columns/views) and run it again until it is clean.',
+      annotations: { readOnlyHint: true, destructiveHint: false },
+      inputSchema: {
+        rootPath: z.string().optional().describe('Grade only this subtree, e.g. "/동네 빵집 운영"'),
+        workspace: z.string().optional().describe('Workspace id; defaults to ROOTR_WORKSPACE/config'),
+      },
+    },
+    async ({ rootPath, workspace }) => {
+      try {
+        const ws = requireWorkspace(workspace);
+        const client = makeClient(ws);
+        return jsonResult(await client.scaffoldReviewBuilt(ws, rootPath));
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    'rootr_test_workspace',
+    {
+      title: 'RUN the workspace you built — does it actually work?',
+      description:
+        'The last step, and the one that catches what the two review tools cannot. `rootr_scaffold_review` grades ' +
+        'the tree you designed; `rootr_review_workspace` grades the shape of what got built; this one **exercises ' +
+        'it**: does every relation point at a row that really exists, do rollups and formulas produce a value on ' +
+        'real rows, do board/calendar/filter views reference columns that exist, can the form actually deposit an ' +
+        'answer (target table alive AND every question name matching a column — a mismatch makes answers vanish ' +
+        'with no error), are sheet formulas computed and free of #REF!/#DIV/0!. Returns { ran, passed, failed, ' +
+        'warned, checks[] }. It writes nothing, so run it as often as you like. A workspace can score 100 on both ' +
+        'reviews and still fail here — that is exactly the case this exists for. Pass `rootPath` to test only the ' +
+        'subtree you just built. Fix every `fail` and run it again.',
+      annotations: { readOnlyHint: true, destructiveHint: false },
+      inputSchema: {
+        rootPath: z.string().optional().describe('Test only this subtree, e.g. "/동네 빵집 운영"'),
+        workspace: z.string().optional().describe('Workspace id; defaults to ROOTR_WORKSPACE/config'),
+      },
+    },
+    async ({ rootPath, workspace }) => {
+      try {
+        const ws = requireWorkspace(workspace);
+        const client = makeClient(ws);
+        return jsonResult(await client.scaffoldSelfTest(ws, rootPath));
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
+
   server.registerTool(
     'rootr_scaffold_apply',
     {
       title: 'Apply a scaffold tree to an existing workspace',
       description:
         'Create the given document tree inside an existing Rootr (루터) workspace, optionally rooted under an ' +
-        'existing path. Works with a workspace key (docs:write scope). PRECONDITION: call rootr_scaffold_plan ' +
-        'first and ask the user its 3-10 clarifying questions; design the tree from their answers (same quality ' +
-        'bar as rootr_create_workspace — real building blocks with icons/views/seed content, not thin markdown). ' +
+        'existing path. Works with a workspace key (docs:write scope). PRECONDITION: rootr_scaffold_plan first, ask ' +
+        'its 3-10 clarifying questions, design from the answers, then rootr_scaffold_review and fix every ' +
+        '`error` finding (same quality bar as rootr_create_workspace — real building blocks with icons/views/' +
+        'seed rows, not thin markdown). The response carries the `review` back so you can see what stayed weak, and AFTER it lands run rootr_review_workspace (rootPath = your new subtree) — that one grades what really exists. ' +
         'AFTER creating: if your runtime can receive HTTP callbacks, offer a webhook on the new subtree ' +
         '(rootr_create_webhook with scopeNodeId) so changes flow back to you — skip your own actorId.',
       annotations: { readOnlyHint: false, destructiveHint: false },