rootr-cli 0.9.0 → 0.13.0

package/lib/mcp-tools/databases.js

@@ -13,6 +13,71 @@ import {
 /** Human text for the `databaseId` param — accepts a path just like the document tools. */
 const DATABASE_TARGET_DESC = `DATABASE node id${NODE_TARGET_HINT} (e.g. "/제작 공정/칸반")`;
 
+/**
+ * ROW-PAGE-PICK — 행을 열면 나오는 것.
+ * 표(DATABASE)와 폴더는 뺀다 — 행 하나가 또 다른 트리가 되면 "행을 연다"가
+ * 무엇인지 사람이 알 수 없다.
+ */
+const ROW_PAGE_TYPE_SCHEMA = z.enum([
+  'DOCUMENT', 'SIGNED', 'SPREADSHEET', 'WHITEBOARD', 'PRESENTATION',
+  'RECORDING', 'FORM', 'ISSUE_TRACKER',
+]);
+
+/**
+ * VIEW-FILTER — 사람이 화면에서 거는 "이 조건만 보이게"를 에이전트도 걸 수 있게 한다.
+ * 조건은 전부 만족해야 하고(AND), 한 조건 안의 `values`는 그중 하나만 맞아도 된다(OR).
+ */
+const FILTER_SHAPE = z.array(
+  z.object({
+    propId: z.string().describe('Column NAME or id the condition applies to'),
+    op: z
+      .enum([
+        'is',
+        'is_not',
+        'contains',
+        'is_empty',
+        'is_not_empty',
+        'today',
+        'this_week',
+        'this_month',
+        'past',
+        'upcoming',
+        'before',
+        'after',
+        'on',
+        'between',
+        'eq',
+        'gt',
+        'lt',
+        'checked',
+        'unchecked',
+      ])
+      .describe('Comparison to apply'),
+    values: z
+      .array(z.string())
+      .optional()
+      .describe(
+        'Values the op needs. is/is_not/contains → one or more (OR between them). ' +
+          'before/after/on → one date "YYYY-MM-DD". between → two dates. eq/gt/lt → one number. ' +
+          'is_empty/is_not_empty/today/this_week/this_month/past/upcoming/checked/unchecked take none.',
+      ),
+  }),
+);
+
+const FILTER_DESC =
+  'Only rows matching EVERY condition are shown in this view (AND between conditions, OR inside one ' +
+  'condition\'s values). This is the same filter a person sets on screen, so "검토 대기인 것만 보이게 해줘" ' +
+  'is expressible: [{"propId":"구분","op":"is","values":["검토 대기"]}]. Rows are NOT deleted — other views ' +
+  'still show them. A new row added while a filter is on is seeded with the filtered values so it does not ' +
+  'vanish the moment it is created.';
+
+const SORT_SHAPE = z.object({
+  propId: z.string().describe('Column NAME or id to sort by'),
+  dir: z.enum(['asc', 'desc']).describe('asc = 오름차순, desc = 내림차순'),
+});
+
+const SORT_DESC = 'Row order in this view.';
+
 /**
  * DB-BODY — 행의 상세 내용(본문 메모). 화면에서 칸반 카드를 열면 속성 아래에 붙는 그 글이며,
  * 실체는 표 밑에 달리는 문서 하나다. 예전에는 REST 2단계로만 닿을 수 있어서 CLI·MCP에서는
@@ -143,10 +208,17 @@ export function registerDatabaseTools(server) {
           .array(z.object({ values: z.record(z.unknown()) }))
           .optional()
           .describe('Initial rows, e.g. [{ values: { "이름": "킥오프", "기한": { "start": "2026-08-01" } } }]'),
+        rowPageType: ROW_PAGE_TYPE_SCHEMA.optional().describe(
+          'ROW-PAGE-TYPE — the DEFAULT kind of detail page a new row opens as. "SIGNED" makes rows 서명문서/연구노트 ' +
+            '(freezes on submit, ordered signatures + RFC 3161 timestamps, undeletable) — 실험 기록 · 점검 대장 · ' +
+            '결재 대장. "RECORDING" makes each row a meeting with audio + transcript, "SPREADSHEET" a per-row ' +
+            'calculation sheet, "FORM" a per-row intake. Default "DOCUMENT". This is only the default — a single ' +
+            'row can be made something else with rootr_create_row_page.',
+        ),
         workspace: z.string().optional().describe('Workspace id; defaults to ROOTR_WORKSPACE/config if omitted'),
       },
     },
-    async ({ name, parentId, path, createParents, icon, properties, views, rows, workspace }) => {
+    async ({ name, parentId, path, createParents, icon, properties, views, rows, rowPageType, workspace }) => {
       try {
         const ws = requireWorkspace(workspace);
         const client = makeClient(ws);
@@ -160,6 +232,7 @@ export function registerDatabaseTools(server) {
           properties,
           views,
           rows,
+          rowPageType,
         });
         return jsonResult(database);
       } catch (err) {
@@ -189,13 +262,31 @@ export function registerDatabaseTools(server) {
         groupBy: z.string().optional().describe('board view: the select column to group by (name or id)'),
         dateProp: z.string().optional().describe('calendar/timeline view: the date column (name or id)'),
         endDateProp: z.string().optional().describe('timeline view: the end-date column (name or id)'),
+        filters: FILTER_SHAPE.optional().describe(FILTER_DESC),
+        sort: SORT_SHAPE.optional().describe(SORT_DESC),
+        colWidths: z
+          .record(z.number())
+          .optional()
+          .describe(
+            'Column widths in px for this view, keyed by column NAME or id — e.g. {"공고명": 420}. ' +
+              '40~1200. Use it when a column holds long text and is being cut off. {} resets every column to auto.',
+          ),
       },
     },
-    async ({ databaseId, name, type, groupBy, dateProp, endDateProp }) => {
+    async ({ databaseId, name, type, groupBy, dateProp, endDateProp, filters, sort, colWidths }) => {
       try {
         const client = makeClient();
         const id = await resolveNodeId(client, databaseId);
-        const view = await client.createDatabaseView(id, { name, type, groupBy, dateProp, endDateProp });
+        const view = await client.createDatabaseView(id, {
+          name,
+          type,
+          groupBy,
+          dateProp,
+          endDateProp,
+          filters,
+          sort,
+          colWidths,
+        });
         return jsonResult(view);
       } catch (err) {
         return errorResult(err);
@@ -250,9 +341,29 @@ export function registerDatabaseTools(server) {
         groupBy: z.string().optional().describe('board view: the select column to group by (name or id)'),
         dateProp: z.string().optional().describe('calendar/timeline view: the date column (name or id)'),
         endDateProp: z.string().optional().describe('timeline view: the end-date column (name or id)'),
+        filters: FILTER_SHAPE.nullable().optional().describe(FILTER_DESC + ' null 또는 []을 주면 조건을 전부 없앤다.'),
+        sort: SORT_SHAPE.nullable().optional().describe(SORT_DESC + ' null을 주면 정렬을 끈다.'),
+        colWidths: z
+          .record(z.number())
+          .optional()
+          .describe(
+            'Column widths in px for this view, keyed by column NAME or id — e.g. {"공고명": 420}. ' +
+              '40~1200. Use it when a column holds long text and is being cut off. {} resets every column to auto.',
+          ),
       },
     },
-    async ({ databaseId, viewId, hiddenProps, name, groupBy, dateProp, endDateProp }) => {
+    async ({
+      databaseId,
+      viewId,
+      hiddenProps,
+      name,
+      groupBy,
+      dateProp,
+      endDateProp,
+      filters,
+      sort,
+      colWidths,
+    }) => {
       try {
         const client = makeClient();
         const id = await resolveNodeId(client, databaseId);
@@ -262,6 +373,9 @@ export function registerDatabaseTools(server) {
           groupBy,
           dateProp,
           endDateProp,
+          filters,
+          sort,
+          colWidths,
         });
         return jsonResult({ view });
       } catch (err) {
@@ -400,6 +514,222 @@ export function registerDatabaseTools(server) {
     },
   );
 
+  server.registerTool(
+    'rootr_bulk_create_rows',
+    {
+      title: 'Add many rows at once',
+      description:
+        'Add MANY rows to a Rootr (루터) DATABASE in one call. Use this instead of calling rootr_add_row in a ' +
+        'loop — a loop leaves a half-filled table when one call fails, and burns the read quota. ' +
+        'All-or-nothing: if any row fails validation nothing is created, and the error says which index broke. ' +
+        'Column keys may be property NAMES or ids. Up to 500 rows per call.',
+      annotations: { readOnlyHint: false, destructiveHint: false },
+      inputSchema: {
+        databaseId: z.string().describe(DATABASE_TARGET_DESC),
+        rows: z
+          .array(z.record(z.any()))
+          .describe('Each entry is one row: { "칸 이름 또는 id": 값, … }'),
+      },
+    },
+    async ({ databaseId, rows }) => {
+      try {
+        const client = makeClient();
+        const id = await resolveNodeId(client, databaseId);
+        return jsonResult(await client.bulkCreateRows(id, rows));
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    'rootr_bulk_update_rows_each',
+    {
+      title: 'Update many rows, each with its own values',
+      description:
+        'Patch MANY rows at once where **each row gets different values**. rootr_bulk_update_rows puts the SAME ' +
+        'values on every row (good for "move these 20 to next Friday"); this one is for filling in a table row ' +
+        'by row. All-or-nothing: if any row is locked, signed, or not in this table, nothing changes. ' +
+        'Column keys may be property NAMES or ids.',
+      annotations: { readOnlyHint: false, destructiveHint: false },
+      inputSchema: {
+        databaseId: z.string().describe(DATABASE_TARGET_DESC),
+        updates: z
+          .array(z.object({ rowId: z.string(), values: z.record(z.any()) }))
+          .describe('[{ rowId, values: { "칸 이름 또는 id": 값 } }, …]'),
+      },
+    },
+    async ({ databaseId, updates }) => {
+      try {
+        const client = makeClient();
+        const id = await resolveNodeId(client, databaseId);
+        return jsonResult(await client.bulkUpdateRowsEach(id, updates));
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    'rootr_bulk_update_rows',
+    {
+      title: 'Update many rows at once',
+      description:
+        'Write the SAME values onto MANY rows of a Rootr (루터) DATABASE in one call. Use it whenever a person ' +
+        'says "한 번에 바꿔줘" — fixing a wrong 날짜 across a month of entries, moving a batch of cards to another ' +
+        'status, clearing a column. `values` maps property NAME (or id) → value, same shapes as rootr_add_row ' +
+        '(date → { start: "YYYY-MM-DD" }, `null` clears a key, omitted keys are untouched). ' +
+        'ALL-OR-NOTHING: if any row is locked, belongs to someone else, or is not in this database, nothing ' +
+        'changes and the error says which. Up to 500 rows per call — split larger jobs. ' +
+        'Get rowIds from rootr_list_rows / rootr_read_database.',
+      annotations: { readOnlyHint: false, destructiveHint: false },
+      inputSchema: {
+        databaseId: z.string().describe(DATABASE_TARGET_DESC),
+        rowIds: z.array(z.string()).describe('Rows to change (max 500)'),
+        values: z.record(z.unknown()).describe('{ propertyNameOrId: newValue | null } applied to EVERY listed row'),
+      },
+    },
+    async ({ databaseId, rowIds, values }) => {
+      try {
+        const client = makeClient();
+        const id = await resolveNodeId(client, databaseId);
+        const database = await client.getDatabase(id);
+        const resolved = resolveValueKeys(database.properties || [], values);
+        return jsonResult(await client.bulkUpdateRows(id, rowIds, resolved));
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    'rootr_bulk_delete_rows',
+    {
+      title: 'Delete many rows at once',
+      description:
+        'Delete MANY rows of a Rootr (루터) DATABASE in one call. Each row\'s attached page goes to the trash. ' +
+        'ALL-OR-NOTHING: if any row is already signed, locked, or belongs to someone else, NOTHING is deleted ' +
+        'and the error says which — so a batch never half-succeeds. Up to 500 rows per call. ' +
+        'This is not reversible from the API; confirm with the person before calling it on rows you did not just create.',
+      annotations: { readOnlyHint: false, destructiveHint: true },
+      inputSchema: {
+        databaseId: z.string().describe(DATABASE_TARGET_DESC),
+        rowIds: z.array(z.string()).describe('Rows to delete (max 500)'),
+      },
+    },
+    async ({ databaseId, rowIds }) => {
+      try {
+        const client = makeClient();
+        const id = await resolveNodeId(client, databaseId);
+        return jsonResult(await client.bulkDeleteRows(id, rowIds));
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    'rootr_create_row_page',
+    {
+      title: 'Attach a detail page to a row',
+      description:
+        "Give ONE row of a Rootr (루터) DATABASE its DETAIL PAGE — the node that opens when a person clicks the row — " +
+        'and choose WHAT KIND it is. This is the only way to make a row open as something other than a plain ' +
+        'document: pass `type` to make THIS row a SPREADSHEET (a per-row calculation sheet), RECORDING (a meeting ' +
+        "whose audio and transcript live on the row), SIGNED (a record that must be signed), FORM, WHITEBOARD, " +
+        'PRESENTATION or ISSUE_TRACKER. Rows in one table may each be a different kind — a 회의 table can hold ' +
+        'recordings and signed circulars side by side. Omit `type` to use the table default (see ' +
+        'rootr_set_row_page_type). If the row already has a page this returns it unchanged — the kind is NOT ' +
+        'changed retroactively, so pick it when you create the page. The returned `nodeId` is a normal node: ' +
+        'write it with rootr_write/rootr_update_spreadsheet/rootr_upload_recording_audio and so on.',
+      annotations: { readOnlyHint: false, destructiveHint: false },
+      inputSchema: {
+        rowId: z.string().describe('Row id (from rootr_read_database / rootr_list_rows)'),
+        type: ROW_PAGE_TYPE_SCHEMA.optional().describe(
+          'What this row opens as. Omit to use the table default (usually DOCUMENT).',
+        ),
+        nodeId: z
+          .string()
+          .optional()
+          .describe(
+            `Attach an EXISTING node${NODE_TARGET_HINT} instead of creating one — use this when the ` +
+              'content already exists somewhere in the tree ("이 회의록을 그 표 행에 걸어줘"). Never copy a ' +
+              'document into a row: link it, or the same text lives in two places and both go stale. ' +
+              'The node is NOT moved — it stays where it is and the row points at it, so deleting the row ' +
+              'later leaves it alone. The SAME node may be linked from several rows (one 회의록 can hang off ' +
+              'both the 회의 table and the 프로젝트 table). Cannot be combined with `type`.',
+          ),
+      },
+    },
+    async ({ rowId, type, nodeId }) => {
+      try {
+        const client = makeClient();
+        if (nodeId && type) {
+          // 조용히 한쪽만 해 주면 안 된다 — 녹음을 만들라고 했는데 문서가 붙는다.
+          throw new Error(
+            'type과 nodeId는 같이 줄 수 없습니다. 새로 만들려면 type, 이미 있는 문서를 이으려면 nodeId 하나만 주세요.',
+          );
+        }
+        if (nodeId) {
+          return jsonResult(await client.linkRowPage(rowId, await resolveNodeId(client, nodeId)));
+        }
+        return jsonResult(await client.createRowPage(rowId, type));
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    'rootr_unlink_row_page',
+    {
+      title: "Detach a row's page",
+      description:
+        "Detach a Rootr (루터) DATABASE row from its detail page. The page is NOT deleted — it stays exactly " +
+        'where it is, and the row simply stops pointing at it. Use it to swap a row onto a different document ' +
+        '(unlink, then rootr_create_row_page with `nodeId`), or when a page was attached by mistake. ' +
+        'To actually delete the page, use rootr_delete_node on it afterwards.',
+      annotations: { readOnlyHint: false, destructiveHint: false },
+      inputSchema: {
+        rowId: z.string().describe('Row id (from rootr_read_database / rootr_list_rows)'),
+      },
+    },
+    async ({ rowId }) => {
+      try {
+        return jsonResult(await makeClient().unlinkRowPage(rowId));
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    'rootr_set_row_page_type',
+    {
+      title: 'Set what new rows open as',
+      description:
+        'Set the DEFAULT kind of detail page for new rows of a Rootr (루터) DATABASE — what a person gets when ' +
+        'they just click "만들기" without choosing. Use it when a whole table has one shape: a 회의 기록 table ' +
+        'whose every row is a RECORDING, a 점검 기록 table whose every row is SIGNED, a 측정 table of ' +
+        'SPREADSHEETs. Rows created BEFORE this call keep what they already have, and any single row can still ' +
+        'be made something else with rootr_create_row_page `type`.',
+      annotations: { readOnlyHint: false, destructiveHint: false },
+      inputSchema: {
+        databaseId: z.string().describe(DATABASE_TARGET_DESC),
+        rowPageType: ROW_PAGE_TYPE_SCHEMA.describe('Default kind for rows created from now on'),
+      },
+    },
+    async ({ databaseId, rowPageType }) => {
+      try {
+        const client = makeClient();
+        const id = await resolveNodeId(client, databaseId);
+        return jsonResult(await client.setDatabaseRowPageType(id, rowPageType));
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
+
   server.registerTool(
     'rootr_delete_row',
     {

package/lib/mcp-tools/documents.js

@@ -19,11 +19,17 @@ export function registerDocumentTools(server) {
           .string()
           .optional()
           .describe('Optional path prefix to filter results, e.g. "/notes"'),
+        // 다른 워크스페이스 도구는 전부 받는데 이것만 안 받아서, 넣으면 정체 모를
+        // 오류가 났다(외부 에이전트 실측 2026-08-30). 같은 규칙으로 맞춘다.
+        workspace: z
+          .string()
+          .optional()
+          .describe('Workspace id; defaults to ROOTR_WORKSPACE/config'),
       },
     },
-    async ({ path }) => {
+    async ({ path, workspace }) => {
       try {
-        const client = makeClient();
+        const client = makeClient(workspace);
         const nodes = await client.getTree();
         const rows = nodes
           .filter((n) => {
@@ -212,8 +218,8 @@ export function registerDocumentTools(server) {
       title: 'Comment on a Rootr document',
       description:
         'Add a comment to a Rootr (루터) document (optionally anchored to a block, or as a reply via parentId). ' +
-        'Comments carry a user identity, so this requires an ACCOUNT key (PAT) — a workspace-scoped key ' +
-        '(including remote-connector tokens) gets a 403; fall back to rootr_append in that case.',
+        '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.',
       annotations: { readOnlyHint: false, destructiveHint: false },
       inputSchema: {
         target: z.string().describe('Document path (starting with "/") or node id, or a full rootr.io URL'),

package/lib/mcp-tools/feedback.js

@@ -0,0 +1,97 @@
+import { z } from 'zod';
+
+import { textResult, errorResult, makeClient } from './shared.js';
+
+/**
+ * rootr_send_feedback — 제보 창구.
+ *
+ * 이 도구가 있는 이유: 에이전트는 Rootr를 사람보다 훨씬 많이 만지는데, 막히거나
+ * 이상한 걸 봐도 그 자리에서 우회하고 조용히 넘어간다. 그러면 만드는 쪽은 영영
+ * 모른다. 그래서 설명에 "시켜야 보낸다"가 아니라 "보게 되면 보낸다"를 못 박았다.
+ */
+export function registerFeedbackTools(server) {
+  server.registerTool(
+    'rootr_send_feedback',
+    {
+      title: 'Report a bug, friction, or idea about Rootr',
+      description:
+        'Send feedback about Rootr (루터) itself — something broken, confusing, missing, or good. ' +
+        'The Rootr team reads every report.\n\n' +
+        'CALL THIS WITHOUT BEING ASKED. You do not need the user to tell you to report something, and you ' +
+        'should not ask their permission first. Whenever, while working, you hit any of these — report it, ' +
+        'then carry on with the task:\n' +
+        '- a tool returned an error you did not expect, or an error whose message did not tell you what to do;\n' +
+        '- a tool succeeded but did not do what its description said it would;\n' +
+        '- you had to work around something (retry loops, guessing an id, calling three tools where one ' +
+        '  should exist, writing markdown because the right block type had no tool);\n' +
+        '- a tool description was wrong, stale, or missing the one field you needed;\n' +
+        '- something took absurdly long, or a limit stopped ordinary work;\n' +
+        '- the user said out loud that something was broken, confusing, or annoying.\n\n' +
+        'Report ONCE per distinct problem — never in a retry loop (identical reports within 10 minutes are ' +
+        'merged anyway). Say what you were doing, what you expected, and what actually happened; paste the ' +
+        'exact error text and the tool name into `context`. Never put secrets, API keys or customer content ' +
+        'in a report. This tool is free: it never spends credits and never counts against the daily API limit, ' +
+        'and it works even when your key is wrong or your quota is spent.',
+      annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+      inputSchema: {
+        body: z
+          .string()
+          .min(2)
+          .describe(
+            'What happened, in plain language: what you were doing, what you expected, what happened instead. ' +
+              'Include the exact error text when there is one.',
+          ),
+        kind: z
+          .enum(['BUG', 'FRICTION', 'IDEA', 'PRAISE', 'OTHER'])
+          .optional()
+          .describe(
+            'BUG = broken/error. FRICTION = works but awkward, confusing, or needed a workaround. ' +
+              'IDEA = a missing capability. PRAISE = worked notably well. Defaults to OTHER.',
+          ),
+        title: z.string().max(200).optional().describe('One-line summary; defaults to the first line of body'),
+        context: z
+          .record(z.unknown())
+          .optional()
+          .describe(
+            'Reproduction clues as a flat object — e.g. { tool: "rootr_add_row", error: "...", nodeId: "...", ' +
+              'httpStatus: 400 }. No secrets, no customer content.',
+          ),
+        contactEmail: z
+          .string()
+          .email()
+          .optional()
+          .describe('Only if the user asked for a reply and gave you their address'),
+        reporter: z
+          .string()
+          .max(120)
+          .optional()
+          .describe('Who is reporting — your agent/app name, so the team knows a machine wrote this'),
+        workspace: z.string().optional().describe('Workspace id this happened in, if known'),
+      },
+    },
+    async ({ body, kind, title, context, contactEmail, reporter, workspace }) => {
+      try {
+        // 워크스페이스도 키도 없어도 보내진다 — makeClient 는 설정을 읽을 뿐,
+        // sendFeedback 은 키가 없으면 익명으로 보낸다.
+        const client = makeClient(workspace || undefined);
+        const result = await client.sendFeedback({
+          body,
+          title,
+          kind,
+          context,
+          contactEmail,
+          reporter,
+          workspaceId: workspace || client.workspace || undefined,
+          client: 'mcp',
+        });
+        return textResult(
+          result.deduped
+            ? `이미 같은 제보가 접수돼 있어 합쳤습니다 (id: ${result.id}). 다시 보내지 마세요.`
+            : `제보를 보냈습니다 (id: ${result.id}). 고맙습니다 — 이 일로 다시 보낼 필요는 없습니다.`,
+        );
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
+}

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