rootr-cli 0.6.0 → 0.7.1

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`는 그 워크스페이스를 여는 키를 골라 함께 기억합니다.
 
 ### 워크스페이스 여러 개 쓰기 (키 등록 + 전환)
 
@@ -169,9 +172,16 @@ rootr config --add-key rootr_xxx --label "영업팀"
 rootr config                       # 등록된 키 목록 확인
 ```
 
-이후 MCP에서 `rootr_use_workspace` 도구로 **이름이나 id**를 주면 활성 워크스페이스가
-바뀌고, 그 워크스페이스를 담당하는 키가 자동으로 선택·기억됩니다. 계정 키(PAT)를 쓰면
-소속된 어느 워크스페이스로든 바로 전환됩니다.
+이후 MCP에서 `rootr_use_workspace` 도구로 **이름·id·루터 웹 주소** 중 아무거나 주면 활성
+워크스페이스가 바뀌고, 그 워크스페이스를 담당하는 키가 자동으로 선택·기억됩니다. 계정
+키(PAT)를 쓰면 소속된 어느 워크스페이스로든 바로 전환됩니다.
+
+워크스페이스 키는 자기 워크스페이스 밖에서는 열리지 않습니다 — `rootr ws`(=`rootr_workspaces`)
+목록에 보여도 접근은 안 되는 경우가 있어, 등록된 키가 워크스페이스 키뿐이면 목록에
+`[등록된 키로는 접근 불가]`를 함께 표시합니다.
+
+문서를 가리키는 웹 주소(`https://rootr.io/ko/w/<ws>/d/<doc>`)는 `rootr_read` 등 모든 노드
+인자에 그대로 붙여넣을 수 있습니다. 다른 워크스페이스의 주소면 "먼저 전환하라"고 알려줍니다.
 
 > 원격 커넥터(`https://rootr.io/mcp`)는 승인할 때 고른 워크스페이스 하나에만 연결됩니다.
 > 다른 워크스페이스가 필요하면 그 워크스페이스로 커넥터를 새로 발급하세요.

package/bin/rootr.js

@@ -3,9 +3,10 @@ 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 } from '../lib/resolve.js';
+import { resolveTarget, requireResolved, resolveMoveDestination } from '../lib/resolve.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
@@ -19,9 +20,11 @@ const USAGE = `Rootr CLI v${pkg.version}
   rootr append <path|id> [<text>] [--heading "## X"] [--file <f>]  문서 끝(또는 헤딩 아래)에 안전하게 추가
   rootr edit <path|id> --find <text> --replace <text> [--all]      본문 내 텍스트 치환
   rootr search <query>                             워크스페이스 검색
+  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 config [--api-key <k>] [--workspace <w>] [--base-url <u>]  설정 조회/저장
   rootr config --add-key <k> [--label <name>] [--workspace <w>]     워크스페이스별 키 추가 등록
@@ -70,7 +73,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) {
@@ -218,6 +224,21 @@ async function cmdSearch(args) {
   }
 }
 
+async function cmdMv(args) {
+  const source = args._[0];
+  const dest = args._[1];
+  if (!source || !dest) throw new Error('사용법: rootr mv <path|id> <새 경로|폴더 id>');
+
+  const client = makeClient();
+  const resolved = await resolveTarget(client, source);
+  const id = requireResolved(resolved);
+
+  const { parentId, name } = await resolveMoveDestination(client, dest);
+  const updated = await client.updateNode(id, { parentId, name });
+
+  console.log(`이동했습니다: ${resolved.path || id} → ${updated.path || dest}`);
+}
+
 async function cmdRm(args) {
   const target = args._[0];
   if (!target) throw new Error('사용법: rootr rm <path|id> [--yes]');
@@ -302,11 +323,47 @@ 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) {
@@ -405,6 +462,8 @@ async function main() {
       return cmdSearch(args);
     case 'attach':
       return cmdAttach(args);
+    case 'mv':
+      return cmdMv(args);
     case 'rm':
       return cmdRm(args);
     case 'ws':
@@ -413,6 +472,8 @@ async function main() {
       return cmdAsk(args);
     case 'config':
       return cmdConfig(args);
+    case 'use':
+      return cmdUse(args);
     case 'mcp':
       return cmdMcp(args);
     default:

package/lib/client.js

@@ -33,6 +33,19 @@ export class RootrApiError extends Error {
 }
 
 function hintFor(status, body) {
+  // WS-SCOPE — the single most confusing failure: a workspace-scoped key used
+  // against another workspace. The API says so precisely; without repeating it
+  // as an instruction the assistant reads the generic hint below and starts
+  // guessing at invitations/permissions for a workspace the user already owns.
+  const detail = body && (body.message || body.error || '');
+  if (status === 403 && typeof detail === 'string' && /does not belong to this workspace/i.test(detail)) {
+    return (
+      '이 키는 다른 워크스페이스 전용 키입니다. 목록에 보인다고 접근되는 것은 아닙니다.\n' +
+      '조치: rootr.io > 설정 > API 키에서 계정 키(PAT)를 발급해 `rootr config --api-key <키>` 로 등록하거나, ' +
+      '그 워크스페이스용 키를 `rootr config --add-key <키> --workspace <워크스페이스 id>` 로 추가하세요. ' +
+      '(rootr_workspaces 로 어떤 워크스페이스가 실제로 열리는지 확인할 수 있습니다.)'
+    );
+  }
   if (status === 401 || status === 403) {
     return (
       'API 키 또는 워크스페이스 스코프를 확인하세요 (rootr config로 현재 설정 확인). ' +
@@ -298,6 +311,14 @@ export class RootrClient {
     return this.request(`/nodes/${encodeURIComponent(id)}`, { method: 'DELETE' });
   }
 
+  /** Rename and/or move a node. `parentId: null` moves it to the workspace root. */
+  async updateNode(id, { name, icon, tags, parentId, position } = {}) {
+    return this.request(`/nodes/${encodeURIComponent(id)}`, {
+      method: 'PATCH',
+      body: { name, icon, tags, parentId, position },
+    });
+  }
+
   // ---- Comments / publishing / duplication (document-level extras) --------
 
   /** Comments carry a user identity — needs an account key (PAT) or user session; workspace keys 403. */

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/documents.js

@@ -1,7 +1,7 @@
 import { z } from 'zod';
 
 import { RootrApiError } from '../client.js';
-import { resolveTarget, requireResolved } from '../resolve.js';
+import { resolveTarget, requireResolved, resolveMoveDestination } from '../resolve.js';
 import { textResult, jsonResult, errorResult, makeClient } from './shared.js';
 
 /** Registers the original 6 document tools: list/read/append/edit/write/search. */
@@ -54,7 +54,7 @@ export function registerDocumentTools(server) {
         'Read a document before editing or appending to it so you know its current structure.',
       annotations: { readOnlyHint: true, destructiveHint: false },
       inputSchema: {
-        target: z.string().describe('Document path (e.g. "/notes/todo.md") or node id'),
+        target: z.string().describe('Document path (e.g. "/notes/todo.md") or node id, or a full rootr.io URL'),
       },
     },
     async ({ target }) => {
@@ -80,7 +80,7 @@ export function registerDocumentTools(server) {
         'you just need to add new information (log entries, notes, findings) to an existing document.',
       annotations: { readOnlyHint: false, destructiveHint: false },
       inputSchema: {
-        target: z.string().describe('Document path (starting with "/") or node id'),
+        target: z.string().describe('Document path (starting with "/") or node id, or a full rootr.io URL'),
         content: z.string().describe('Markdown content to append'),
         underHeading: z
           .string()
@@ -115,7 +115,7 @@ export function registerDocumentTools(server) {
         'you are only adding new content.',
       annotations: { readOnlyHint: false, destructiveHint: false },
       inputSchema: {
-        target: z.string().describe('Document path (starting with "/") or node id'),
+        target: z.string().describe('Document path (starting with "/") or node id, or a full rootr.io URL'),
         find: z.string().describe('Exact existing text to find (must be unique unless replaceAll is set)'),
         replace: z.string().describe('Text to replace it with'),
         replaceAll: z.boolean().optional().describe('Replace all occurrences instead of requiring uniqueness'),
@@ -144,7 +144,7 @@ export function registerDocumentTools(server) {
         'as ifMatch to avoid clobbering concurrent changes. Prefer rootr_append or rootr_edit for incremental changes.',
       annotations: { readOnlyHint: false, destructiveHint: true },
       inputSchema: {
-        target: z.string().describe('Document path (starting with "/", created if missing) or node id'),
+        target: z.string().describe('Document path (starting with "/", created if missing) or node id, or a full rootr.io URL'),
         content: z.string().describe('Full new markdown content for the document'),
         ifMatch: z
           .string()
@@ -216,7 +216,7 @@ export function registerDocumentTools(server) {
         '(including remote-connector tokens) gets a 403; fall back to rootr_append in that case.',
       annotations: { readOnlyHint: false, destructiveHint: false },
       inputSchema: {
-        target: z.string().describe('Document path (starting with "/") or node id'),
+        target: z.string().describe('Document path (starting with "/") or node id, or a full rootr.io URL'),
         body: z.string().describe('Comment text (markdown)'),
         blockId: z.string().optional().describe('Block id to anchor the comment to'),
         parentId: z.string().optional().describe('Parent comment id, to reply in a thread'),
@@ -241,7 +241,7 @@ export function registerDocumentTools(server) {
         'List the comment threads on a Rootr (루터) document, optionally filtered to one block. Works with any key.',
       annotations: { readOnlyHint: true, destructiveHint: false },
       inputSchema: {
-        target: z.string().describe('Document path (starting with "/") or node id'),
+        target: z.string().describe('Document path (starting with "/") or node id, or a full rootr.io URL'),
         blockId: z.string().optional().describe('Only comments anchored to this block'),
       },
     },
@@ -270,7 +270,7 @@ export function registerDocumentTools(server) {
         'Returns the slug/URL. Check rootr_document_public_status first; unpublish or change settings via rootr_set_document_public.',
       annotations: { readOnlyHint: false, destructiveHint: false },
       inputSchema: {
-        target: z.string().describe('Document path (starting with "/") or node id'),
+        target: z.string().describe('Document path (starting with "/") or node id, or a full rootr.io URL'),
       },
     },
     async ({ target }) => {
@@ -297,7 +297,7 @@ export function registerDocumentTools(server) {
         'Owner-level action (MANAGE): works with an account key (PAT), not with workspace-scoped/connector tokens.',
       annotations: { readOnlyHint: false, destructiveHint: false },
       inputSchema: {
-        target: z.string().describe('Document path (starting with "/") or node id'),
+        target: z.string().describe('Document path (starting with "/") or node id, or a full rootr.io URL'),
         isPublic: z.boolean().optional().describe('false to unpublish, true to re-enable'),
         allowCommits: z.boolean().optional().describe('Whether public readers can propose git-style edit suggestions'),
         expiresAt: z
@@ -354,7 +354,7 @@ export function registerDocumentTools(server) {
       description: 'Whether a Rootr (루터) document is published, and at which public slug/URL.',
       annotations: { readOnlyHint: true, destructiveHint: false },
       inputSchema: {
-        target: z.string().describe('Document path (starting with "/") or node id'),
+        target: z.string().describe('Document path (starting with "/") or node id, or a full rootr.io URL'),
       },
     },
     async ({ target }) => {
@@ -392,4 +392,33 @@ export function registerDocumentTools(server) {
       }
     },
   );
+
+  server.registerTool(
+    'rootr_move_node',
+    {
+      title: 'Move or rename a Rootr node',
+      description:
+        'Move a Rootr (루터) document or folder to a different folder, and/or rename it. This is the only way ' +
+        'to relocate a node that already exists — creating with a target path only works up front. ' +
+        '`destination` accepts: a folder id, a folder path ending in "/" (moves into it, keeps the name), ' +
+        'a full new path incl. name (moves and renames in one call), or "/" for the workspace root.',
+      annotations: { readOnlyHint: false, destructiveHint: false },
+      inputSchema: {
+        target: z.string().describe('Node path (starting with "/") or node id to move'),
+        destination: z
+          .string()
+          .describe('Destination folder id or path — see description for the accepted forms'),
+      },
+    },
+    async ({ target, destination }) => {
+      try {
+        const client = makeClient();
+        const id = requireResolved(await resolveTarget(client, target));
+        const { parentId, name } = await resolveMoveDestination(client, destination);
+        return jsonResult(await client.updateNode(id, { parentId, name }));
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
 }

package/lib/mcp-tools/shared.js

@@ -8,7 +8,7 @@ import { resolveTarget, requireResolved } from '../resolve.js';
  * takes a path too, exactly like rootr_read, so an agent that only knows where
  * a node lives in the tree never has to hunt for its uuid.
  */
-export const NODE_TARGET_HINT = ', or its path starting with "/"';
+export const NODE_TARGET_HINT = ', or its path starting with "/", or a full rootr.io URL';
 
 /**
  * Resolve a path-or-id argument to a node id. Paths go through the by-path

package/lib/mcp-tools/workspaces.js

@@ -1,9 +1,10 @@
 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';
 
 /**
  * Scaffold `tree` argument schema. Declared as an ARRAY of node objects so MCP
@@ -25,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(
@@ -61,83 +40,32 @@ export function registerWorkspaceTools(server) {
         '(A hosted/remote connector is bound to a single workspace at consent time and cannot switch.)',
       annotations: { readOnlyHint: false, destructiveHint: false },
       inputSchema: {
-        workspace: z.string().describe('Workspace id, or its name (case-insensitive)'),
+        workspace: z
+          .string()
+          .describe('Workspace id, its name (case-insensitive), or a rootr.io URL to a page in it'),
       },
     },
     async ({ workspace }) => {
       try {
-        if (currentClientOverride()) {
-          return errorResult(
-            new Error(
-              '이 원격 연결은 승인 시 지정한 워크스페이스 하나에만 연결됩니다. ' +
-                '다른 워크스페이스를 쓰려면 설정>연동에서 그 워크스페이스로 커넥터를 새로 발급하세요.',
-            ),
-          );
-        }
-        const wanted = workspace.trim();
-        const wantedLower = wanted.toLowerCase();
-        const candidates = candidateClients();
-
-        // 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;
-        for (const candidate of candidates) {
-          let list = [];
-          try {
-            list = await candidate.client.listWorkspaces();
-          } catch {
-            continue;
-          }
-          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;
-        if (target) {
-          for (const candidate of candidates) {
-            try {
-              await candidate.client.request(`/workspaces/${encodeURIComponent(target.id)}`);
-              usable = candidate;
-              break;
-            } catch {
-              continue;
-            }
+        const hosted = currentClientOverride();
+        if (hosted) {
+          const url = parseRootrUrl(workspace);
+          const wanted = (url ? url.workspaceId : workspace).trim();
+          if (wanted === hosted.workspace) {
+            return textResult(`이미 이 워크스페이스(${hosted.workspace})에 연결되어 있습니다. 그대로 진행하세요.`);
           }
-        }
-        const match = target && usable ? { workspace: target, candidate: usable } : null;
-
-        if (target && !usable) {
           return errorResult(
             new Error(
-              `"${target.name || target.id}" 워크스페이스에 접근할 수 있는 키가 없습니다. ` +
-                '그 워크스페이스용 키를 등록하세요: rootr config --add-key <키>',
-            ),
-          );
-        }
-        if (!match) {
-          return errorResult(
-            new Error(
-              `"${wanted}" 워크스페이스를 찾지 못했습니다. rootr_workspaces로 접근 가능한 목록을 확인하세요. ` +
-                '목록에 없다면 그 워크스페이스용 키가 등록되지 않은 것입니다 (rootr config --add-key <키>).',
+              `이 원격 커넥터는 워크스페이스 ${hosted.workspace} 하나에만 연결되어 있어 ${wanted} 로 전환할 수 없습니다.\n` +
+                '조치: rootr.io > 설정 > 연동에서 그 워크스페이스로 커넥터를 하나 더 발급한 뒤 다시 시도하세요. ' +
+                '(사용자가 직접 해야 하는 작업입니다.)',
             ),
           );
         }
         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) {
@@ -161,24 +89,52 @@ export function registerWorkspaceTools(server) {
     async () => {
       try {
         const hosted = currentClientOverride();
-        const active = hosted ? hosted.workspace : loadConfig().workspace;
-        const seen = new Map();
-        for (const { client } of candidateClients()) {
-          let list = [];
+        // Hosted (remote connector) requests have no ~/.rootr/config.json to
+        // read — candidateClients() would return nothing and the tool used to
+        // answer "(no workspaces visible to this key)" even though the
+        // connector is happily bound to one workspace. Ask the API about the
+        // bound workspace directly instead. (A connector token has no userId,
+        // so GET /workspaces is not open to it — GET /workspaces/{id} is.)
+        if (hosted) {
+          let name = '';
           try {
-            list = await client.listWorkspaces();
+            const ws = await hosted.request(`/workspaces/${encodeURIComponent(hosted.workspace)}`);
+            name = ws.name || ws.slug || '';
           } catch {
-            continue; // a revoked/foreign key shouldn't hide the others
+            // fall through: the id alone is still more useful than nothing
           }
-          for (const w of list) if (!seen.has(w.id)) seen.set(w.id, w);
+          return textResult(
+            `* ${hosted.workspace}\t${name}\n\n` +
+              '이 원격 커넥터는 위 워크스페이스 하나에만 연결되어 있습니다 (승인 시 선택). ' +
+              '다른 워크스페이스가 필요하면 rootr.io > 설정 > 연동에서 그 워크스페이스로 커넥터를 하나 더 발급하세요.',
+          );
+        }
+        const cfg = loadConfig();
+        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 probe = !cfg.apiKey && (cfg.keys || []).length > 0;
+        const { workspaces, reachable, failures } = await surveyWorkspaces(candidates, { probe });
+        if (!workspaces.length) {
+          return textResult(
+            (failures ? '등록된 키로 워크스페이스 목록을 조회하지 못했습니다 (키 만료/취소 가능성).\n' : '이 컴퓨터에 등록된 Rootr 키가 없습니다.\n') +
+              '조치: rootr.io > 설정 > API 키에서 계정 키(PAT)를 발급해 `rootr config --api-key <키>` 로 등록하세요.',
+          );
         }
-        const rows = [...seen.values()].map(
-          (w) => `${w.id === active ? '* ' : '  '}${w.id}\t${w.name || w.slug || ''}`,
+        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.length
-            ? `${rows.join('\n')}\n\n(* = current; switch with rootr_use_workspace)`
-            : '(no workspaces visible to this key)',
+          `${rows.join('\n')}\n\n(* = 현재 워크스페이스, rootr_use_workspace 로 전환)` +
+            (blocked
+              ? '\n"접근 불가" = 내 소속 워크스페이스지만 등록된 키가 워크스페이스 전용이라 못 엽니다. ' +
+                '계정 키(PAT)를 등록하면 전부 열립니다: rootr.io > 설정 > API 키 → `rootr config --api-key <키>`'
+              : ''),
         );
       } catch (err) {
         return errorResult(err);

package/lib/resolve.js

@@ -1,15 +1,67 @@
 import { RootrApiError } from './client.js';
 
+/**
+ * Web-app route segments that address a single node: rootr.io/{locale?}/w/{ws}/{kind}/{id}
+ * (mirrors frontend/src/app/w/[ws]/*). Anything else under /w/{ws} is a
+ * workspace-level screen (graph, trash, settings …) with no node to resolve.
+ */
+const NODE_URL_KINDS = new Set(['d', 'db', 'sheet', 'whiteboard', 'log', 'form', 'deck', 'rec', 'issues', 'crm']);
+
+/**
+ * Parse a Rootr web URL an agent was handed by a human ("여기 봐줘: https://rootr.io/ko/w/…/d/…").
+ * Without this every such paste is treated as a node id and comes back as a
+ * bare "Not found", which reads like a permission problem and sends the
+ * assistant guessing. Returns null for anything that isn't a Rootr URL.
+ */
+export function parseRootrUrl(target) {
+  if (typeof target !== 'string' || !/^https?:\/\//i.test(target)) return null;
+  let url;
+  try {
+    url = new URL(target);
+  } catch {
+    return null;
+  }
+  const segments = url.pathname.split('/').filter(Boolean);
+  const at = segments.indexOf('w');
+  if (at === -1 || !segments[at + 1]) return null;
+  const kind = segments[at + 2];
+  const id = NODE_URL_KINDS.has(kind) ? segments[at + 3] : undefined;
+  return { workspaceId: segments[at + 1], nodeId: id, kind: id ? kind : undefined };
+}
+
 /**
  * Resolve a CLI/MCP "target" argument to a node id.
- * If it starts with '/', treat it as a path and look it up via by-path
- * (requires a workspace to be configured). Otherwise treat it as an id already.
+ * A full rootr.io URL is unpacked to the node id it points at; a value
+ * starting with '/' is a tree path looked up via by-path (requires a
+ * workspace); anything else is already an id.
  *
  * Returns { id, existed, path } where existed indicates whether the path
  * resolved to an existing node (always true for id-form targets, since we
  * don't verify those against the API).
  */
 export async function resolveTarget(client, target) {
+  const url = parseRootrUrl(target);
+  if (url) {
+    if (!url.nodeId) {
+      throw new RootrApiError(`이 주소는 문서가 아니라 워크스페이스 화면을 가리킵니다: ${target}`, {
+        hint: `해당 워크스페이스로 전환하려면 rootr_use_workspace 에 ${url.workspaceId} 를 넘기세요.`,
+      });
+    }
+    // The URL carries the workspace it lives in, so a mismatch is knowable
+    // BEFORE the API answers 404 — say so instead of letting it look missing.
+    if (client.workspace && url.workspaceId !== client.workspace) {
+      throw new RootrApiError(
+        `이 주소는 다른 워크스페이스(${url.workspaceId})의 노드입니다. 현재 활성 워크스페이스는 ${client.workspace} 입니다.`,
+        {
+          hint:
+            `먼저 rootr_use_workspace 로 ${url.workspaceId} 로 전환하세요. ` +
+            '전환이 안 되면 그 워크스페이스에 쓸 수 있는 키가 없는 것입니다 (rootr_workspaces 로 확인).',
+        },
+      );
+    }
+    return { id: url.nodeId, existed: true, path: undefined, url };
+  }
+
   if (!target.startsWith('/')) {
     return { id: target, existed: true, path: undefined };
   }
@@ -28,3 +80,48 @@ export function requireResolved(resolved) {
   }
   return resolved.id;
 }
+
+/**
+ * Resolve a "move destination" argument (used by `rootr mv` and
+ * `rootr_move_node`) to { parentId, name }.
+ * - a bare id (no leading '/'): move into that folder, keep the current name.
+ * - a path ending in '/', or a path that already resolves to a non-DOCUMENT
+ *   node: move into that folder, keep the current name.
+ * - any other '/'-prefixed path: treated as the full destination path
+ *   (parent + new name), so the same call can rename and move at once.
+ * - '/': move to the workspace root.
+ */
+export async function resolveMoveDestination(client, dest) {
+  if (!dest.startsWith('/')) {
+    return { parentId: dest };
+  }
+  if (dest === '/') {
+    return { parentId: null };
+  }
+
+  const trailingSlash = dest.endsWith('/');
+  const destPath = trailingSlash ? dest.slice(0, -1) : dest;
+  const existing = await client.getNodeByPath(destPath);
+  const existingNode = existing && (existing.node || existing);
+  if (existingNode && existingNode.type !== 'DOCUMENT') {
+    return { parentId: existingNode.id };
+  }
+  if (trailingSlash) {
+    throw new RootrApiError(`대상 폴더를 찾을 수 없습니다: ${destPath}`);
+  }
+
+  const lastSlash = destPath.lastIndexOf('/');
+  const parentPath = lastSlash > 0 ? destPath.slice(0, lastSlash) : '';
+  const name = destPath.slice(lastSlash + 1);
+  if (!name) throw new RootrApiError(`잘못된 대상 경로: ${dest}`);
+
+  if (!parentPath) {
+    return { parentId: null, name };
+  }
+  const parent = await client.getNodeByPath(parentPath);
+  const parentNode = parent && (parent.node || parent);
+  if (!parentNode) {
+    throw new RootrApiError(`대상 폴더를 찾을 수 없습니다: ${parentPath}`);
+  }
+  return { parentId: parentNode.id, name };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rootr-cli",
-  "version": "0.6.0",
+  "version": "0.7.1",
   "description": "Official Rootr CLI + MCP server — read, write, edit and search Rootr documents from the shell or from an AI agent.",
   "type": "module",
   "bin": {
@@ -37,5 +37,8 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
     "zod": "^3.23.8"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.mjs"
   }
 }