rootr-cli 0.7.0 → 0.8.0

package/README.md

@@ -152,13 +152,16 @@ rootr rm /notes/todo.md --yes    # 확인 없이 (스크립트용)
 (파이프/CI처럼 입력이 없는 환경에서는 "아니오"로 처리되어 안전합니다).
 `docs:write` 스코프가 필요합니다.
 
-### 워크스페이스 목록
+### 워크스페이스 목록 · 전환
 
 ```bash
-rootr ws
+rootr ws                       # 목록 (현재 워크스페이스에 *, 못 여는 곳은 표시)
+rootr use "영업팀"              # 전환 — id · 이름 · rootr.io 주소 아무거나
 ```
 
-출력: `id\tname` 목록 (계정 키면 소속된 전체 워크스페이스, 워크스페이스 키면 그 워크스페이스만).
+`rootr ws` 출력은 `id\tname` 목록입니다. 등록된 키가 워크스페이스 전용 키뿐이면 목록에는
+보이지만 열 수 없는 워크스페이스에 `[등록된 키로는 접근 불가]`가 붙습니다 — 목록에 보이는
+것과 접근되는 것은 다릅니다. `rootr use`는 그 워크스페이스를 여는 키를 골라 함께 기억합니다.
 
 ### 워크스페이스 여러 개 쓰기 (키 등록 + 전환)
 

package/bin/rootr.js

@@ -3,7 +3,8 @@ import { readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { dirname, join, basename, extname } from 'node:path';
 
-import { loadConfig, saveConfig, maskKey, upsertKey, CONFIG_PATH, DEFAULT_BASE_URL } from '../lib/config.js';
+import { loadConfig, saveConfig, keyForWorkspace, maskKey, upsertKey, CONFIG_PATH, DEFAULT_BASE_URL } from '../lib/config.js';
+import { candidateClients, rememberWorkspace, resolveWorkspaceSwitch, surveyWorkspaces } from '../lib/credentials.js';
 import { RootrClient, RootrApiError } from '../lib/client.js';
 import { resolveTarget, requireResolved, resolveMoveDestination } from '../lib/resolve.js';
 
@@ -22,8 +23,10 @@ const USAGE = `Rootr CLI v${pkg.version}
   rootr mv <path|id> <새 경로|폴더 id>              문서/폴더 이동 및/또는 이름 변경
   rootr rm <path|id> [--yes]                       문서/폴더를 휴지통으로 이동 (복구 가능)
   rootr attach <file> [--doc <path|id>] [--heading "## X"] [--alt <text>]  파일 업로드(+문서에 삽입)
-  rootr ws                                         내 워크스페이스 목록 (id\tname)
+  rootr ws                                         내 워크스페이스 목록 (id\tname, 열 수 없는 곳은 표시)
+  rootr use <id|이름|주소>                          활성 워크스페이스 전환 (그 워크스페이스용 키도 기억)
   rootr ask <question> [--workspace <w>]           GraphRAG 질의응답 (RCA), 인용 포함 출력
+  rootr db create [--file <spec.json>] [--parent <path|id>]  표(DATABASE) 생성 — 컬럼 순서 그대로, 행까지 한 번에
   rootr config [--api-key <k>] [--workspace <w>] [--base-url <u>]  설정 조회/저장
   rootr config --add-key <k> [--label <name>] [--workspace <w>]     워크스페이스별 키 추가 등록
   rootr mcp                                        MCP stdio 서버 구동 (도구 90종+ — README 참고)
@@ -71,7 +74,10 @@ function readStdin() {
 
 function makeClient() {
   const cfg = loadConfig();
-  return new RootrClient(cfg);
+  // Several keys can live side by side, each bound to the workspace it opens
+  // (config.js keys[]). Use the one that covers the active workspace instead of
+  // insisting on a single default key.
+  return new RootrClient({ ...cfg, apiKey: keyForWorkspace(cfg, cfg.workspace) });
 }
 
 function printErrorAndExit(err) {
@@ -318,13 +324,49 @@ async function cmdAttach(args) {
 }
 
 async function cmdWs() {
-  const client = makeClient();
-  const workspaces = await client.listWorkspaces();
+  const cfg = loadConfig();
+  const candidates = candidateClients(cfg);
+  if (!candidates.length) {
+    throw new RootrApiError('이 컴퓨터에 등록된 Rootr 키가 없습니다.', {
+      hint: 'rootr.io > 설정 > API 키에서 계정 키(PAT)를 발급해 `rootr config --api-key <키>` 로 등록하세요.',
+    });
+  }
+  // Probing costs an API call per workspace, so only when it diagnoses something:
+  // no account key means every key is scoped and most of the list is unusable.
+  const probe = !cfg.apiKey && (cfg.keys || []).length > 0;
+  const { workspaces, reachable, failures } = await surveyWorkspaces(candidates, { probe });
+  if (!workspaces.length) {
+    throw new RootrApiError(
+      failures ? '등록된 키로 워크스페이스 목록을 조회하지 못했습니다 (키 만료/취소 가능성).' : '보이는 워크스페이스가 없습니다.',
+      { hint: 'rootr.io > 설정 > API 키에서 계정 키(PAT)를 발급해 `rootr config --api-key <키>` 로 등록하세요.' },
+    );
+  }
+  let blocked = false;
   for (const w of workspaces) {
-    console.log(`${w.id}\t${w.name || w.slug || ''}`);
+    const unreachable = probe && !reachable.has(w.id);
+    blocked = blocked || unreachable;
+    console.log(
+      `${w.id === cfg.workspace ? '* ' : '  '}${w.id}\t${w.name || w.slug || ''}${unreachable ? '\t[등록된 키로는 접근 불가]' : ''}`,
+    );
+  }
+  if (blocked) {
+    console.error(
+      '\n"접근 불가" = 내 소속 워크스페이스지만 등록된 키가 워크스페이스 전용이라 못 엽니다.\n' +
+        '계정 키(PAT)를 등록하면 전부 열립니다: rootr.io > 설정 > API 키 → `rootr config --api-key <키>`',
+    );
   }
 }
 
+async function cmdUse(args) {
+  const wanted = args._.join(' ').trim();
+  if (!wanted) throw new Error('사용법: rootr use <워크스페이스 id | 이름 | rootr.io 주소>');
+  const cfg = loadConfig();
+  const match = await resolveWorkspaceSwitch(wanted, cfg);
+  if (match.error) throw new RootrApiError(match.error);
+  rememberWorkspace(match, cfg);
+  console.log(`활성 워크스페이스: "${match.workspace.name || match.workspace.slug || ''}" (${match.workspace.id})`);
+}
+
 async function cmdAsk(args) {
   const question = args._.join(' ');
   if (!question) throw new Error('사용법: rootr ask <question> [--workspace <w>]');
@@ -392,6 +434,44 @@ async function cmdMcp() {
 
 // ---- entry ------------------------------------------------------------
 
+
+/**
+ * 표(DATABASE) 만들기 — 컬럼 순서를 그대로 지키려면 한 번에 만들어야 한다.
+ *
+ * 스펙은 JSON으로 받는다(파일 또는 표준입력): `{ name, properties[], views?, rows? }`.
+ * 컬럼을 하나씩 붙이는 방식은 호출 순서가 곧 컬럼 순서가 되어 옮겨온 표가 뒤죽박죽이
+ * 됐다 — 그래서 CLI도 "한 번에" 쪽만 제공한다.
+ */
+async function cmdDb(args) {
+  const sub = args._[0];
+  if (sub !== 'create') {
+    throw new Error('사용법: rootr db create [--file <spec.json>] [--parent <path|id>] [--ws <id>]');
+  }
+  const raw = typeof args.file === 'string' ? readFileSync(args.file, 'utf8') : await readStdin();
+  let spec;
+  try {
+    spec = JSON.parse(raw);
+  } catch {
+    throw new Error('스펙을 JSON으로 읽을 수 없습니다. { "name": "...", "properties": [...] } 형태여야 합니다.');
+  }
+  if (!spec.name && !spec.path) throw new Error('스펙에 name 또는 path가 있어야 합니다.');
+
+  const client = makeClient();
+  let parentId = spec.parentId;
+  if (typeof args.parent === 'string') {
+    const resolved = await resolveTarget(client, args.parent);
+    if (!resolved.existed) throw new Error(`부모를 찾을 수 없습니다: ${args.parent}`);
+    parentId = resolved.id;
+  }
+  const ws = args.ws || client.workspace;
+  if (!ws) throw new Error('워크스페이스를 알 수 없습니다. --ws 를 주거나 rootr use 로 정하세요.');
+
+  const db = await client.createDatabase(ws, { ...spec, parentId });
+  const cols = (db.properties || []).map((p) => p.name).join(', ');
+  console.log(`표 생성: ${db.path ?? db.name}  (${db.id})`);
+  if (cols) console.log(`컬럼 순서: ${cols}`);
+  if (typeof db.rowCount === 'number') console.log(`행: ${db.rowCount}개`);
+}
 async function main() {
   const argv = process.argv.slice(2);
   const args = parseArgs(argv);
@@ -431,6 +511,10 @@ async function main() {
       return cmdAsk(args);
     case 'config':
       return cmdConfig(args);
+    case 'use':
+      return cmdUse(args);
+    case 'db':
+      return cmdDb(args);
     case 'mcp':
       return cmdMcp(args);
     default:

package/lib/client.js

@@ -550,7 +550,68 @@ export class RootrClient {
     });
   }
 
-  // ---- Databases (rows) -------------------------------------------------
+  // ---- Templates ---------------------------------------------------------
+  // 문서 양식(템플릿). 인앱 어시스턴트는 예전부터 쓸 수 있었는데 MCP·CLI에는
+  // 없어서, 밖에서 붙은 에이전트는 양식이 있는 줄도 모르고 매번 맨바닥부터
+  // 만들었다(2026-08-18 점검에서 드러난 구멍).
+
+  async listTemplates(workspace) {
+    return this.request(`/workspaces/${encodeURIComponent(workspace)}/templates`);
+  }
+
+  async applyTemplate(workspace, templateId, { parentId } = {}) {
+    return this.request(
+      `/workspaces/${encodeURIComponent(workspace)}/templates/${encodeURIComponent(templateId)}/apply`,
+      { method: 'POST', body: { parentId } },
+    );
+  }
+
+  async createTemplate(workspace, { name, emoji, description, kind, spec } = {}) {
+    return this.request(`/workspaces/${encodeURIComponent(workspace)}/templates`, {
+      method: 'POST',
+      body: { name, emoji, description, kind, spec },
+    });
+  }
+
+  async saveTemplateFromNode(workspace, nodeId, { name, emoji, description } = {}) {
+    return this.request(
+      `/workspaces/${encodeURIComponent(workspace)}/templates/from-node/${encodeURIComponent(nodeId)}`,
+      { method: 'POST', body: { name, emoji, description } },
+    );
+  }
+
+  async updateTemplate(workspace, templateId, patch = {}) {
+    return this.request(
+      `/workspaces/${encodeURIComponent(workspace)}/templates/${encodeURIComponent(templateId)}`,
+      { method: 'PATCH', body: patch },
+    );
+  }
+
+  // ---- Databases --------------------------------------------------------
+
+  /**
+   * Create a DATABASE node with its columns (and optionally its first rows) in
+   * ONE call. `properties` order IS the column order — that is the whole point:
+   * building a table by adding columns one at a time made the order depend on
+   * the order of the calls, which is how migrated tables came out scrambled.
+   */
+  async createDatabase(workspace, { name, parentId, path, createParents, autoRename, icon, properties, views, rows } = {}) {
+    return this.request(`/workspaces/${encodeURIComponent(workspace)}/databases`, {
+      method: 'POST',
+      body: { name, parentId, path, createParents, autoRename, icon, properties, views, rows },
+    });
+  }
+
+  /**
+   * 뷰 하나만 고친다(이름·감출 컬럼·그룹 기준). PATCH /databases/:id 는 views 배열을
+   * 통째로 갈아끼워서 빠뜨린 뷰가 사라지는데, 여기서는 서버가 그 뷰만 병합한다.
+   */
+  async updateDatabaseView(databaseId, viewId, patch = {}) {
+    return this.request(
+      `/databases/${encodeURIComponent(databaseId)}/views/${encodeURIComponent(viewId)}`,
+      { method: 'PATCH', body: patch },
+    );
+  }
 
   /** Database definition: { id, name, icon, path, properties[], views[], rowCount }. */
   async getDatabase(databaseId) {

package/lib/credentials.js

@@ -0,0 +1,169 @@
+import { loadConfig, saveConfig, upsertKey } from './config.js';
+import { RootrClient } from './client.js';
+import { parseRootrUrl } from './resolve.js';
+
+/**
+ * Every credential this machine can use, default key first. An account key
+ * (PAT) reaches every workspace its owner belongs to; a workspace key reaches
+ * one. Which one applies to a given workspace is discovered by asking the API
+ * (listWorkspaces / a workspace-scoped call), never guessed from the key.
+ *
+ * Shared by the CLI (`rootr ws`, `rootr use`) and the MCP tools so both answer
+ * "which workspaces can I actually open?" the same way.
+ */
+export function candidateClients(cfg = loadConfig()) {
+  const out = [];
+  const seen = new Set();
+  if (cfg.apiKey) {
+    seen.add(cfg.apiKey);
+    out.push({ apiKey: cfg.apiKey, label: 'default', client: new RootrClient({ ...cfg, apiKey: cfg.apiKey }) });
+  }
+  for (const k of cfg.keys || []) {
+    if (!k.apiKey || seen.has(k.apiKey)) continue;
+    seen.add(k.apiKey);
+    out.push({ apiKey: k.apiKey, label: k.label || k.workspace || 'key', client: new RootrClient({ ...cfg, apiKey: k.apiKey }) });
+  }
+  return out;
+}
+
+/**
+ * Collect every workspace the registered keys can see, and (when asked) which
+ * of them a key can actually open — listing is not a capability probe: a
+ * workspace key lists all of its owner's workspaces while being rejected by
+ * every one but its own.
+ */
+export async function surveyWorkspaces(candidates, { probe = false, probeLimit = 12 } = {}) {
+  const seen = new Map();
+  const reachable = new Set();
+  let listed = 0;
+  let failures = 0;
+  for (const { client } of candidates) {
+    let list = [];
+    try {
+      list = await client.listWorkspaces();
+      listed += 1;
+    } catch {
+      failures += 1;
+      continue; // a revoked/foreign key shouldn't hide the others
+    }
+    for (const w of list) if (!seen.has(w.id)) seen.set(w.id, w);
+    if (!probe) continue;
+    for (const w of list.slice(0, probeLimit)) {
+      if (reachable.has(w.id)) continue;
+      try {
+        await client.request(`/workspaces/${encodeURIComponent(w.id)}`);
+        reachable.add(w.id);
+      } catch {
+        // scoped key rejected here; another key may still cover it
+      }
+    }
+  }
+  return { workspaces: [...seen.values()], reachable, listed, failures };
+}
+
+/**
+ * Resolve "which workspace did the user mean, and which key opens it?" from an
+ * id, a name, or a rootr.io URL. Returns either { workspace, candidate } or a
+ * { error } describing the cause AND the next step — a bare "not found" is what
+ * used to send agents guessing at invitations for workspaces the user owns.
+ */
+export async function resolveWorkspaceSwitch(wantedRaw, cfg = loadConfig()) {
+  const url = parseRootrUrl(wantedRaw);
+  const wanted = (url ? url.workspaceId : wantedRaw).trim();
+  const wantedLower = wanted.toLowerCase();
+  const candidates = candidateClients(cfg);
+  if (!candidates.length) {
+    return {
+      error:
+        '이 컴퓨터에 등록된 Rootr 키가 없습니다.\n' +
+        '조치: rootr.io > 설정 > API 키에서 계정 키(PAT)를 발급받아 `rootr config --api-key <키>` 로 등록하세요.',
+    };
+  }
+
+  // Step 1 — resolve the name/id to a real workspace. /workspaces lists the
+  // KEY OWNER's workspaces, so any key can answer this.
+  let target = null;
+  const visible = [];
+  let listed = 0;
+  for (const candidate of candidates) {
+    let list = [];
+    try {
+      list = await candidate.client.listWorkspaces();
+      listed += 1;
+    } catch {
+      continue;
+    }
+    for (const w of list) if (!visible.some((v) => v.id === w.id)) visible.push(w);
+    const hit = list.find(
+      (w) => w.id === wanted || (w.name || '').toLowerCase() === wantedLower || (w.slug || '').toLowerCase() === wantedLower,
+    );
+    if (hit) {
+      target = hit;
+      break;
+    }
+  }
+
+  // Step 2 — find a key that can actually WORK in it.
+  let usable = null;
+  let lastRejection = null;
+  if (target) {
+    for (const candidate of candidates) {
+      try {
+        await candidate.client.request(`/workspaces/${encodeURIComponent(target.id)}`);
+        usable = candidate;
+        break;
+      } catch (err) {
+        lastRejection = err;
+      }
+    }
+  }
+
+  // Listing can be unavailable (a legacy key with no owner attached gets 403 on
+  // /workspaces) while that key still opens the very workspace being asked for.
+  if (!target) {
+    for (const candidate of candidates) {
+      try {
+        const ws = await candidate.client.request(`/workspaces/${encodeURIComponent(wanted)}`);
+        if (ws && ws.id) return { workspace: ws, candidate };
+      } catch (err) {
+        lastRejection = err;
+      }
+    }
+  }
+  if (target && usable) return { workspace: target, candidate: usable };
+
+  if (target) {
+    const scoped = lastRejection && lastRejection.status === 403;
+    return {
+      error:
+        `"${target.name || target.id}" (${target.id}) 는 접근 권한 목록에는 있지만, 등록된 키로는 열 수 없습니다` +
+        `${target.role ? ` (내 역할: ${target.role})` : ''}.\n` +
+        (scoped
+          ? '원인: 지금 등록된 키가 다른 워크스페이스 전용 키입니다 (워크스페이스 키는 자기 워크스페이스 밖에서 403).\n'
+          : `원인: ${lastRejection ? lastRejection.message : '알 수 없음'}\n`) +
+        '조치 (둘 중 하나, 사용자가 직접):\n' +
+        '1) rootr.io > 설정 > API 키에서 계정 키(PAT)를 발급 → `rootr config --api-key <키>` (모든 워크스페이스에 통함)\n' +
+        `2) 그 워크스페이스용 키를 발급 → \`rootr config --add-key <키> --workspace ${target.id}\``,
+    };
+  }
+  const seenList = visible.length
+    ? `\n지금 보이는 워크스페이스: ${visible.map((w) => `${w.name || w.slug || ''}(${w.id})`).join(', ')}`
+    : '';
+  return {
+    error:
+      listed === 0
+        ? '등록된 키로 워크스페이스 목록을 조회하지 못했습니다 (키가 만료/취소되었거나 목록 권한이 없음).\n' +
+          '조치: rootr.io > 설정 > API 키에서 계정 키(PAT)를 새로 발급해 `rootr config --api-key <키>` 로 등록하세요.'
+        : `"${wanted}" 워크스페이스가 내 소속 목록에 없습니다.${seenList}\n` +
+          '조치: 주소가 맞는지 확인하고, 다른 계정의 워크스페이스라면 그 계정으로 발급한 키를 ' +
+          '`rootr config --add-key <키>` 로 등록하세요.',
+  };
+}
+
+/** Persist the switch: remember the workspace and which key covers it. */
+export function rememberWorkspace({ workspace, candidate }, cfg = loadConfig()) {
+  saveConfig({ workspace: workspace.id });
+  if (candidate && candidate.apiKey !== cfg.apiKey) {
+    upsertKey({ apiKey: candidate.apiKey, workspace: workspace.id, label: candidate.label });
+  }
+}

package/lib/mcp-tools/databases.js

@@ -1,6 +1,14 @@
 import { z } from 'zod';
 
-import { jsonResult, errorResult, makeClient, resolveNodeId, NODE_TARGET_HINT } from './shared.js';
+import {
+  jsonResult,
+  errorResult,
+  makeClient,
+  requireWorkspace,
+  resolveNodeId,
+  resolveOptionalNodeId,
+  NODE_TARGET_HINT,
+} from './shared.js';
 
 /** Human text for the `databaseId` param — accepts a path just like the document tools. */
 const DATABASE_TARGET_DESC = `DATABASE node id${NODE_TARGET_HINT} (e.g. "/제작 공정/칸반")`;
@@ -33,6 +41,118 @@ function resolveValueKeys(properties, values) {
  * "status" column = move a kanban card between columns).
  */
 export function registerDatabaseTools(server) {
+  server.registerTool(
+    'rootr_create_database',
+    {
+      title: 'Create a Rootr database (table / board / kanban)',
+      description:
+        'Create a DATABASE node — a typed table with columns, views and rows — in ONE call, optionally seeded with ' +
+        'its first rows. **Use this whenever you need a table**: moving a Notion database over, building a kanban ' +
+        'board, a task/requirement/risk tracker, anything with trackable rows. Do NOT fake a table with a markdown ' +
+        'document, and do NOT create an empty database and then add columns one by one — `properties` order IS the ' +
+        '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 | date | checkbox | url | person. select/multi_select take options:[{name,color}]. ' +
+        'Views default to a single table view; a "board" view needs config.groupBy = a select property id, a ' +
+        '"timeline" view needs config.dateProp. Row `values` are keyed by column NAME (or id); date values are ' +
+        '{ start: "YYYY-MM-DD", end? }, multi_select is string[].',
+      annotations: { readOnlyHint: false, destructiveHint: false },
+      inputSchema: {
+        name: z.string().describe('Table name, e.g. "업무 목록"'),
+        parentId: z.string().optional().describe(`Parent folder id${NODE_TARGET_HINT}; workspace root if omitted`),
+        path: z.string().optional().describe('Full path incl. name — wins over parentId+name, e.g. "/팀/업무 목록"'),
+        createParents: z.boolean().optional().describe('Create missing folders in `path` (default false)'),
+        icon: z.string().optional().describe('Emoji icon for the node'),
+        properties: z
+          .array(
+            z.object({
+              name: z.string().describe('Column header, e.g. "담당자"'),
+              type: z
+                .enum(['title', 'text', 'number', 'select', 'multi_select', 'date', 'checkbox', 'url', 'person'])
+                .describe('Column type; the FIRST property must be "title"'),
+              options: z
+                .array(z.object({ name: z.string(), color: z.string() }))
+                .optional()
+                .describe('select/multi_select only: the choices'),
+            }),
+          )
+          .optional()
+          .describe('Columns IN DISPLAY ORDER. Defaults to a single title column named "Name".'),
+        views: z
+          .array(z.record(z.unknown()))
+          .optional()
+          .describe('Views, e.g. [{ name: "보드", type: "board", config: { groupBy: "<select property id>" } }]'),
+        rows: z
+          .array(z.object({ values: z.record(z.unknown()) }))
+          .optional()
+          .describe('Initial rows, e.g. [{ values: { "이름": "킥오프", "기한": { "start": "2026-08-01" } } }]'),
+        workspace: z.string().optional().describe('Workspace id; defaults to ROOTR_WORKSPACE/config if omitted'),
+      },
+    },
+    async ({ name, parentId, path, createParents, icon, properties, views, rows, workspace }) => {
+      try {
+        const ws = requireWorkspace(workspace);
+        const client = makeClient(ws);
+        parentId = await resolveOptionalNodeId(client, parentId);
+        const database = await client.createDatabase(ws, {
+          name,
+          parentId,
+          path,
+          createParents,
+          icon,
+          properties,
+          views,
+          rows,
+        });
+        return jsonResult(database);
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    'rootr_update_view',
+    {
+      title: 'Edit a database view (hide columns, rename, regroup)',
+      description:
+        'Change ONE view of a Rootr (루터) DATABASE. Use `hiddenProps` to choose which columns that view shows — ' +
+        'the same table can look different per view (a "담당자" view hiding the amounts, etc). Hiding a column ' +
+        'does NOT erase its values: it disappears from that view only and comes back when you unhide it. ' +
+        'Columns may be given by NAME or id; the title column cannot be hidden and is ignored if listed. ' +
+        'Pass an empty array to show everything again. Only the fields you pass change, and other views are untouched.',
+      annotations: { readOnlyHint: false, destructiveHint: false },
+      inputSchema: {
+        databaseId: z.string().describe(DATABASE_TARGET_DESC),
+        viewId: z.string().describe('View id or view NAME (from rootr_read_database)'),
+        hiddenProps: z
+          .array(z.string())
+          .optional()
+          .describe('Columns to hide in this view, by name or id. [] shows every column again.'),
+        name: z.string().optional().describe('New view name'),
+        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)'),
+      },
+    },
+    async ({ databaseId, viewId, hiddenProps, name, groupBy, dateProp, endDateProp }) => {
+      try {
+        const client = makeClient();
+        const id = await resolveNodeId(client, databaseId);
+        const view = await client.updateDatabaseView(id, viewId, {
+          hiddenProps,
+          name,
+          groupBy,
+          dateProp,
+          endDateProp,
+        });
+        return jsonResult({ view });
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
+
   server.registerTool(
     'rootr_read_database',
     {

package/lib/mcp-tools/templates.js

@@ -0,0 +1,156 @@
+import { z } from 'zod';
+
+import {
+  jsonResult,
+  errorResult,
+  makeClient,
+  requireWorkspace,
+  resolveNodeId,
+  resolveOptionalNodeId,
+  NODE_TARGET_HINT,
+} from './shared.js';
+
+/**
+ * 문서 양식(템플릿) 도구.
+ *
+ * REST와 인앱 어시스턴트에는 예전부터 있었는데 MCP·CLI에만 없었다. 그래서 밖에서
+ * 붙은 에이전트(Claude 등)는 워크스페이스에 쓸 만한 양식이 이미 있는 줄도 모르고
+ * 매번 맨바닥부터 문서를 지어냈다 — 2026-08-18 점검에서 드러난 구멍이다.
+ *
+ * 양식은 세 종류다: `document`(마크다운 한 장), `database`(컬럼·뷰가 짜인 표),
+ * `tree`(폴더+문서+표가 얽힌 묶음). 빌트인 양식과 워크스페이스가 직접 만든 양식이
+ * 같은 목록에 함께 나온다.
+ */
+export function registerTemplateTools(server) {
+  server.registerTool(
+    'rootr_list_templates',
+    {
+      title: 'List document/database templates',
+      description:
+        'List the templates available in a Rootr (루터) workspace — builtins plus anything this workspace saved. ' +
+        'Each has an id, name, emoji, description and `kind` (document | database | tree). ' +
+        '**Call this before building a document or table from scratch**: if a fitting template exists, ' +
+        'rootr_apply_template gives the team their own agreed format instead of a shape you invented.',
+      annotations: { readOnlyHint: true, destructiveHint: false },
+      inputSchema: {
+        workspace: z.string().optional().describe('Workspace id; defaults to ROOTR_WORKSPACE/config if omitted'),
+      },
+    },
+    async ({ workspace }) => {
+      try {
+        const ws = requireWorkspace(workspace);
+        return jsonResult(await makeClient(ws).listTemplates(ws));
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    'rootr_apply_template',
+    {
+      title: 'Create a node from a template',
+      description:
+        'Instantiate a Rootr (루터) template — creates the real node(s) it describes and returns the created node. ' +
+        'A `document` template makes one document, `database` makes a table with its columns and views already set, ' +
+        '`tree` makes a whole folder/document/table structure. Get ids from rootr_list_templates.',
+      annotations: { readOnlyHint: false, destructiveHint: false },
+      inputSchema: {
+        templateId: z.string().describe('Template id from rootr_list_templates'),
+        parentId: z
+          .string()
+          .optional()
+          .describe(`Parent folder id${NODE_TARGET_HINT}; workspace root if omitted`),
+        workspace: z.string().optional().describe('Workspace id; defaults to ROOTR_WORKSPACE/config if omitted'),
+      },
+    },
+    async ({ templateId, parentId, workspace }) => {
+      try {
+        const ws = requireWorkspace(workspace);
+        const client = makeClient(ws);
+        parentId = await resolveOptionalNodeId(client, parentId);
+        return jsonResult(await client.applyTemplate(ws, templateId, { parentId }));
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    'rootr_save_as_template',
+    {
+      title: 'Save a node (or an inline spec) as a template',
+      description:
+        'Turn something into a reusable Rootr (루터) template. Either pass `nodeId` to capture an existing ' +
+        'document/table/folder as-is, or pass `kind` + `spec` to define one inline. Use this when the user says ' +
+        '"make this the standard format" or asks for a new form/양식. ' +
+        'NOTE: a template is workspace-wide and readable by every member — do not capture a restricted node ' +
+        'unless the user means to share its content with the whole workspace.',
+      annotations: { readOnlyHint: false, destructiveHint: false },
+      inputSchema: {
+        name: z.string().describe('Template name, e.g. "주간 보고서 양식"'),
+        nodeId: z
+          .string()
+          .optional()
+          .describe(`Capture this existing node${NODE_TARGET_HINT}. Omit when passing kind+spec instead.`),
+        kind: z
+          .enum(['document', 'database', 'tree'])
+          .optional()
+          .describe('Inline definition: document (markdown) | database (columns+views) | tree (structure)'),
+        spec: z
+          .record(z.unknown())
+          .optional()
+          .describe('Inline definition body, matching `kind`. Ignored when nodeId is given.'),
+        emoji: z.string().optional().describe('Emoji shown in the template gallery'),
+        description: z.string().optional().describe('One line on when to use it'),
+        workspace: z.string().optional().describe('Workspace id; defaults to ROOTR_WORKSPACE/config if omitted'),
+      },
+    },
+    async ({ name, nodeId, kind, spec, emoji, description, workspace }) => {
+      try {
+        const ws = requireWorkspace(workspace);
+        const client = makeClient(ws);
+        if (nodeId) {
+          const id = await resolveNodeId(client, nodeId);
+          return jsonResult(await client.saveTemplateFromNode(ws, id, { name, emoji, description }));
+        }
+        if (!kind || !spec) {
+          throw new Error('Pass either nodeId, or both kind and spec.');
+        }
+        return jsonResult(await client.createTemplate(ws, { name, emoji, description, kind, spec }));
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    'rootr_update_template',
+    {
+      title: 'Edit a template',
+      description:
+        'Change a Rootr (루터) template — its name, emoji, description or `spec`. Editing a builtin transparently ' +
+        'creates a workspace copy, so the builtin itself is never damaged. Use this for "change the standard format" ' +
+        'requests instead of saving a second near-identical template.',
+      annotations: { readOnlyHint: false, destructiveHint: false },
+      inputSchema: {
+        templateId: z.string().describe('Template id from rootr_list_templates'),
+        name: z.string().optional().describe('New name'),
+        emoji: z.string().optional().describe('New emoji'),
+        description: z.string().optional().describe('New one-line description'),
+        spec: z.record(z.unknown()).optional().describe('Replacement body, matching the template kind'),
+        workspace: z.string().optional().describe('Workspace id; defaults to ROOTR_WORKSPACE/config if omitted'),
+      },
+    },
+    async ({ templateId, name, emoji, description, spec, workspace }) => {
+      try {
+        const ws = requireWorkspace(workspace);
+        return jsonResult(
+          await makeClient(ws).updateTemplate(ws, templateId, { name, emoji, description, spec }),
+        );
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
+}

package/lib/mcp-tools/workspaces.js

@@ -1,9 +1,9 @@
 import { z } from 'zod';
 
 import { textResult, jsonResult, errorResult, makeClient, requireWorkspace } from './shared.js';
-import { loadConfig, saveConfig, keyForWorkspace, upsertKey } from '../config.js';
+import { loadConfig } from '../config.js';
 import { currentClientOverride } from '../context.js';
-import { RootrClient } from '../client.js';
+import { candidateClients, rememberWorkspace, resolveWorkspaceSwitch, surveyWorkspaces } from '../credentials.js';
 import { parseRootrUrl } from '../resolve.js';
 
 /**
@@ -26,28 +26,6 @@ function parseTree(tree) {
   }
 }
 
-/**
- * Every credential this machine can use, default key first. An account key
- * (PAT) reaches every workspace its owner belongs to; workspace keys reach one.
- * Which one applies to a given workspace is discovered by asking the API
- * (listWorkspaces), not guessed from the key string.
- */
-function candidateClients() {
-  const cfg = loadConfig();
-  const out = [];
-  const seen = new Set();
-  if (cfg.apiKey) {
-    seen.add(cfg.apiKey);
-    out.push({ apiKey: cfg.apiKey, label: 'default', client: new RootrClient({ ...cfg, apiKey: cfg.apiKey }) });
-  }
-  for (const k of cfg.keys || []) {
-    if (!k.apiKey || seen.has(k.apiKey)) continue;
-    seen.add(k.apiKey);
-    out.push({ apiKey: k.apiKey, label: k.label || k.workspace || 'key', client: new RootrClient({ ...cfg, apiKey: k.apiKey }) });
-  }
-  return out;
-}
-
 /** Workspace listing and scaffolding tools: rootr_workspaces, rootr_scaffold_plan, rootr_create_workspace, rootr_scaffold_apply. */
 export function registerWorkspaceTools(server) {
   server.registerTool(
@@ -69,12 +47,10 @@ export function registerWorkspaceTools(server) {
     },
     async ({ workspace }) => {
       try {
-        const wantedUrl = parseRootrUrl(workspace);
-        const wanted = (wantedUrl ? wantedUrl.workspaceId : workspace).trim();
-        const wantedLower = wanted.toLowerCase();
-
-        if (currentClientOverride()) {
-          const hosted = currentClientOverride();
+        const hosted = currentClientOverride();
+        if (hosted) {
+          const url = parseRootrUrl(workspace);
+          const wanted = (url ? url.workspaceId : workspace).trim();
           if (wanted === hosted.workspace) {
             return textResult(`이미 이 워크스페이스(${hosted.workspace})에 연결되어 있습니다. 그대로 진행하세요.`);
           }
@@ -86,117 +62,10 @@ export function registerWorkspaceTools(server) {
             ),
           );
         }
-        const candidates = candidateClients();
-        if (!candidates.length) {
-          return errorResult(
-            new Error(
-              '이 컴퓨터에 등록된 Rootr 키가 없습니다.\n' +
-                '조치: rootr.io > 설정 > API 키에서 계정 키(PAT)를 발급받아 `rootr config --api-key <키>` 로 등록하세요.',
-            ),
-          );
-        }
-
-        // Step 1 — resolve the name/id to a real workspace. /workspaces lists
-        // the KEY OWNER's workspaces, so any key can answer this.
-        let target = null;
-        let listed = 0;
-        const visible = [];
-        for (const candidate of candidates) {
-          let list = [];
-          try {
-            list = await candidate.client.listWorkspaces();
-            listed += 1;
-          } catch {
-            continue;
-          }
-          for (const w of list) if (!visible.some((v) => v.id === w.id)) visible.push(w);
-          const hit = list.find(
-            (w) => w.id === wanted || (w.name || '').toLowerCase() === wantedLower || (w.slug || '').toLowerCase() === wantedLower,
-          );
-          if (hit) {
-            target = hit;
-            break;
-          }
-        }
-
-        // Step 2 — find a key that can actually WORK in it. Listing is not a
-        // capability probe: a workspace-scoped key still lists all of its
-        // owner's workspaces while being rejected by every one but its own.
-        // Only a workspace-scoped call proves the binding.
-        let usable = null;
-        let lastRejection = null;
-        if (target) {
-          for (const candidate of candidates) {
-            try {
-              await candidate.client.request(`/workspaces/${encodeURIComponent(target.id)}`);
-              usable = candidate;
-              break;
-            } catch (err) {
-              lastRejection = err;
-              continue;
-            }
-          }
-        }
-        // Listing can be unavailable (a legacy key with no owner attached gets
-        // 403 on /workspaces) — but that key may still be able to open the very
-        // workspace being asked for. Ask the workspace directly before giving up.
-        let match = target && usable ? { workspace: target, candidate: usable } : null;
-        if (!match && !target) {
-          for (const candidate of candidates) {
-            try {
-              const ws = await candidate.client.request(`/workspaces/${encodeURIComponent(wanted)}`);
-              if (ws && ws.id) {
-                match = { workspace: ws, candidate };
-                break;
-              }
-            } catch (err) {
-              lastRejection = err;
-            }
-          }
-        }
-
-        // Listed-but-unreachable is the common real case: the workspace IS the
-        // user's, but every registered key is workspace-scoped to another one.
-        // Name that cause explicitly — a vague "no key" message makes the
-        // assistant invent permission problems (asking for an invite to the
-        // user's OWN workspace).
-        if (target && !usable) {
-          const scoped = lastRejection && lastRejection.status === 403;
-          return errorResult(
-            new Error(
-              `"${target.name || target.id}" (${target.id}) 는 접근 권한 목록에는 있지만, 등록된 키로는 열 수 없습니다` +
-                `${target.role ? ` (내 역할: ${target.role})` : ''}.\n` +
-                (scoped
-                  ? '원인: 지금 등록된 키가 다른 워크스페이스 전용 키입니다 (워크스페이스 키는 자기 워크스페이스 밖에서 403).\n'
-                  : `원인: ${lastRejection ? lastRejection.message : '알 수 없음'}\n`) +
-                '조치 (둘 중 하나, 사용자가 직접):\n' +
-                '1) rootr.io > 설정 > API 키에서 계정 키(PAT)를 발급 → `rootr config --api-key <키>` (모든 워크스페이스에 통함)\n' +
-                `2) 그 워크스페이스용 키를 발급 → \`rootr config --add-key <키> --workspace ${target.id}\``,
-            ),
-          );
-        }
-        if (!match) {
-          const seenList = visible.length
-            ? `\n지금 보이는 워크스페이스: ${visible.map((w) => `${w.name || w.slug || ''}(${w.id})`).join(', ')}`
-            : '';
-          return errorResult(
-            new Error(
-              listed === 0
-                ? '등록된 키로 워크스페이스 목록을 조회하지 못했습니다 (키가 만료/취소되었거나 목록 권한이 없음).\n' +
-                  '조치: rootr.io > 설정 > API 키에서 계정 키(PAT)를 새로 발급해 `rootr config --api-key <키>` 로 등록하세요.'
-                : `"${wanted}" 워크스페이스가 내 소속 목록에 없습니다.${seenList}\n` +
-                  '조치: 주소가 맞는지 확인하고, 다른 계정의 워크스페이스라면 그 계정으로 발급한 키를 ' +
-                  '`rootr config --add-key <키>` 로 등록하세요.',
-            ),
-          );
-        }
         const cfg = loadConfig();
-        saveConfig({ workspace: match.workspace.id });
-        // Remember which key covers this workspace so later calls resolve
-        // directly instead of probing every key again.
-        if (match.candidate.apiKey !== cfg.apiKey) {
-          upsertKey({ apiKey: match.candidate.apiKey, workspace: match.workspace.id, label: match.candidate.label });
-        }
+        const match = await resolveWorkspaceSwitch(workspace, cfg);
+        if (match.error) return errorResult(new Error(match.error));
+        rememberWorkspace(match, cfg);
         const name = match.workspace.name || match.workspace.slug || '';
         return textResult(`활성 워크스페이스를 "${name}" (${match.workspace.id}) 로 바꿨습니다. 이후 도구 호출은 여기에 적용됩니다.`);
       } catch (err) {
@@ -241,52 +110,25 @@ export function registerWorkspaceTools(server) {
           );
         }
         const cfg = loadConfig();
-        const active = cfg.workspace;
+        const candidates = candidateClients(cfg);
         // Probing costs one API call per workspace (they count against the
         // daily read quota), so only do it in the case it actually diagnoses:
         // no account key registered, i.e. every credential here is scoped to
         // one workspace and most of the list is unusable.
-        const probeReachability = !cfg.apiKey && (cfg.keys || []).length > 0;
-        const seen = new Map();
-        const reached = [];
-        let failures = 0;
-        for (const { client, label } of candidateClients()) {
-          let list = [];
-          try {
-            list = await client.listWorkspaces();
-          } catch {
-            failures += 1;
-            continue; // a revoked/foreign key shouldn't hide the others
-          }
-          for (const w of list) if (!seen.has(w.id)) seen.set(w.id, w);
-          // Which workspace each key can actually WRITE in is what decides
-          // whether rootr_use_workspace will succeed — listing does not.
-          for (const w of probeReachability ? list.slice(0, 12) : []) {
-            if (reached.includes(w.id)) continue;
-            try {
-              await client.request(`/workspaces/${encodeURIComponent(w.id)}`);
-              reached.push(w.id);
-            } catch {
-              // scoped key rejected here; another key may still cover it
-            }
-          }
-          void label;
-        }
-        const rows = [...seen.values()].map(
-          (w) =>
-            `${w.id === active ? '* ' : '  '}${w.id}\t${w.name || w.slug || ''}` +
-            (!probeReachability || reached.includes(w.id) ? '' : '\t[등록된 키로는 접근 불가]'),
-        );
-        if (!rows.length) {
+        const probe = !cfg.apiKey && (cfg.keys || []).length > 0;
+        const { workspaces, reachable, failures } = await surveyWorkspaces(candidates, { probe });
+        if (!workspaces.length) {
           return textResult(
-            failures
-              ? '등록된 키로 워크스페이스 목록을 조회하지 못했습니다 (키 만료/취소 가능성).\n' +
-                  '조치: rootr.io > 설정 > API 키에서 계정 키(PAT)를 발급해 `rootr config --api-key <키>` 로 등록하세요.'
-              : '이 컴퓨터에 등록된 Rootr 키가 없습니다.\n' +
-                  '조치: rootr.io > 설정 > API 키에서 계정 키(PAT)를 발급해 `rootr config --api-key <키>` 로 등록하세요.',
+            (failures ? '등록된 키로 워크스페이스 목록을 조회하지 못했습니다 (키 만료/취소 가능성).\n' : '이 컴퓨터에 등록된 Rootr 키가 없습니다.\n') +
+              '조치: rootr.io > 설정 > API 키에서 계정 키(PAT)를 발급해 `rootr config --api-key <키>` 로 등록하세요.',
           );
         }
-        const blocked = rows.some((r) => r.includes('접근 불가'));
+        const rows = workspaces.map(
+          (w) =>
+            `${w.id === cfg.workspace ? '* ' : '  '}${w.id}\t${w.name || w.slug || ''}` +
+            (!probe || reachable.has(w.id) ? '' : '\t[등록된 키로는 접근 불가]'),
+        );
+        const blocked = probe && workspaces.some((w) => !reachable.has(w.id));
         return textResult(
           `${rows.join('\n')}\n\n(* = 현재 워크스페이스, rootr_use_workspace 로 전환)` +
             (blocked

package/lib/mcp.js

@@ -7,6 +7,7 @@ import { registerLogTools } from './mcp-tools/logs.js';
 import { registerAskTools } from './mcp-tools/ask.js';
 import { registerIssueTools } from './mcp-tools/issues.js';
 import { registerDatabaseTools } from './mcp-tools/databases.js';
+import { registerTemplateTools } from './mcp-tools/templates.js';
 import { registerWebhookTools } from './mcp-tools/webhooks.js';
 import { registerMiscTools } from './mcp-tools/misc.js';
 import { registerCrmTools } from './mcp-tools/crm.js';
@@ -122,6 +123,7 @@ export function buildMcpServer({ name, version }) {
   withQuotaWarnings(server);
 
   registerDocumentTools(server);
+  registerTemplateTools(server);
   registerWorkspaceTools(server);
   registerLogTools(server);
   registerAskTools(server);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rootr-cli",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Official Rootr CLI + MCP server — read, write, edit and search Rootr documents from the shell or from an AI agent.",
   "type": "module",
   "bin": {