rootr-cli 0.16.0 → 0.17.1

package/README.md

@@ -1,774 +1,468 @@
 # rootr-cli
 
-Rootr(마크다운 지식협업 SaaS) 공식 CLI + MCP 서버. 에이전트나 사람이 Rootr 문서를
-로컬 파일처럼 읽고/쓰고/검색할 수 있게 해줍니다.
+Official CLI and MCP server for [Rootr](https://rootr.io) — a team documentation workspace that
+AI agents can read **and write**.
 
-- `rootr` CLI: `ls`, `read`, `write`, `append`, `edit`, `search`, `rm`, `attach`, `ws`, `ask`, `config`
-- `rootr mcp`: stdio 기반 MCP 서버 (Claude Code / Claude Desktop 등에 등록해서 사용), 도구 90종+
-  — 문서·워크스페이스/스캐폴딩·LOG 데이터스토어·RCA ask·이슈·웹훅·첨부파일에 더해
-  스프레드시트/화이트보드/폼/프레젠테이션/페이지/녹음/CRM/데이터베이스까지. 정확한 목록은 MCP `tools/list`로 확인하세요.
+Point Claude, Cursor, or any MCP client at your workspace and it can browse the document tree,
+read and edit markdown, add rows to a database, open and close issues, build a slide deck, run a
+spreadsheet, publish a public page, sign a document, or ask a question and get an answer with
+citations back to the exact paragraph.
 
-순수 Node.js ESM, 빌드 과정 없음. Node 18 이상 필요(내장 `fetch` 사용).
+*(한국어 문서: [README.ko.md](https://github.com/gwmage/rootr-cli/blob/main/README.ko.md))*
 
-## 링크
+- `rootr` CLI — documents, databases, forms, signed documents, publishing, permissions, memory
+- `rootr mcp` — stdio MCP server, **167 tools** (see [MCP tools](#mcp-tools))
 
-- 소스: https://github.com/gwmage/rootr-cli
-- npm: https://www.npmjs.com/package/rootr-cli
-- 원격 커넥터(설치 없이 바로 연결): `https://rootr.io/mcp` — Claude Code/Desktop 등에서
-  로컬 CLI 설치 없이 원격 MCP 엔드포인트로 바로 연결할 수 있습니다. 로컬 CLI(`rootr mcp`)와
-  기능은 동일하며, 자체 인프라에 CLI를 두고 싶을 때만 이 저장소를 설치하면 됩니다.
-- 라이선스: MIT (`LICENSE` 참고)
+Plain Node.js ESM, no build step. Node 18+ (uses the built-in `fetch`).
 
-## 설치
+## Links
 
-이 저장소 안에서 바로 실행하거나, 전역 설치할 수 있습니다.
+- Source: <https://github.com/gwmage/rootr-cli>
+- npm: <https://www.npmjs.com/package/rootr-cli>
+- Remote connector (nothing to install): `https://rootr.io/mcp`
+- Docs: <https://rootr.io/en/docs> · authoring reference: <https://rootr.io/llms.txt>
+- License: MIT (see `LICENSE`)
+
+## Two ways to connect
+
+**1. Remote connector — nothing to install.** Rootr hosts an MCP endpoint with OAuth:
+
+```
+https://rootr.io/mcp
+```
+
+Add it as a custom connector in Claude (Streamable HTTP), sign in, done. Same tools as the local
+server. This is the recommended path for most people.
+
+**2. Local CLI** — use this package when you want the client running on your own machine or
+infrastructure, or when you want the shell commands.
 
 ```bash
-cd cli
-npm install
+npx rootr-cli mcp        # run the MCP server straight from npm
+npm install -g rootr-cli # or install the `rootr` command globally
+```
+
+Or from a clone:
 
-# 방법 1: 직접 실행
+```bash
+npm install
 node bin/rootr.js --help
+```
 
-# 방법 2: 전역 설치 (심볼릭 링크로 rootr 명령 사용)
-npm install -g .
-rootr --help
+Docker:
+
+```bash
+docker build -t rootr-cli .
+docker run -i --rm -e ROOTR_API_KEY=rootr_xxx -e ROOTR_WORKSPACE=ws_123 rootr-cli
 ```
 
-## 설정
+## Configuration
 
-우선순위: **환경변수 > `~/.rootr/config.json`**
+Precedence: **environment variables > `~/.rootr/config.json`**
 
-| 환경변수 | 설정파일 키 | 설명 |
+| Env var | Config key | Description |
 |---|---|---|
-| `ROOTR_API_KEY` | `apiKey` | `rootr_...` 형태의 API 키. 모든 요청에 `x-api-key` 헤더로 전송됩니다. |
-| `ROOTR_WORKSPACE` | `workspace` | 워크스페이스 id |
-| `ROOTR_BASE_URL` | `baseUrl` | 기본값 `https://rootr.io/api/v1` |
+| `ROOTR_API_KEY` | `apiKey` | API key (`rootr_...`), sent as the `x-api-key` header |
+| `ROOTR_WORKSPACE` | `workspace` | Workspace id |
+| `ROOTR_BASE_URL` | `baseUrl` | Defaults to `https://rootr.io/api/v1` |
 
-설정 파일에 저장하기:
+Save them to the config file:
 
 ```bash
 rootr config --api-key rootr_xxxxxxxxxxxxxxxx --workspace ws_123
-# 필요하면 온프레미스/개발 서버용 base-url도 지정 가능
+# self-hosted or dev server
 rootr config --api-key rootr_xxx --workspace ws_123 --base-url https://dev.rootr.io/api/v1
 ```
 
-`~/.rootr/config.json`은 `chmod 600`으로 생성됩니다.
+`~/.rootr/config.json` is written with mode `600`.
 
-### 키 2종
+### Two kinds of key
 
-Rootr API 키는 두 종류가 있고, 도구별로 요구하는 종류가 다릅니다.
+- **Workspace key** — scoped to one workspace. Scopes: `docs:read`, `docs:write`, `graph:read`,
+  `ask`, `webhooks:manage`. Enough for almost every tool.
+- **Account key (PAT)** — acts for the whole account. With the `workspaces:create` scope it can
+  create new workspaces (`rootr_create_workspace`). Trying that with a workspace key returns 403
+  with a hint saying an account key is required.
 
-- **워크스페이스 키**: 특정 워크스페이스 안에서만 동작. 스코프는
-  `docs:read`/`docs:write`/`graph:read`/`ask`/`webhooks:manage` 중 일부.
-  대부분의 문서/LOG/이슈/웹훅/ask 도구는 이 키로 충분합니다.
-- **계정 키 (PAT)**: 사용자 계정 전체로 동작. `workspaces:create` 스코프가 있으면
-  새 워크스페이스를 만들 수 있습니다 (`rootr_create_workspace`). 워크스페이스 키로
-  워크스페이스 생성을 시도하면 403과 함께 계정 키가 필요하다는 힌트가 출력됩니다.
-
-현재 설정 확인 (API 키는 앞 12자만 표시):
+Show the current configuration (only the first 12 characters of the key are printed):
 
 ```bash
 rootr config
-# config file: /home/you/.rootr/config.json
-# apiKey:      rootr_abcd...
-# workspace:   ws_123
-# baseUrl:     https://rootr.io/api/v1
 ```
 
-## CLI 사용법
-
-경로 인자 규칙: `/`로 시작하면 **경로**로 취급되어 by-path API로 노드 id를 알아냅니다
-(워크스페이스 설정 필요). `/`로 시작하지 않으면 **노드 id**로 취급합니다.
+### Working with several workspaces
 
-### 트리 조회
+Register each workspace's key once:
 
 ```bash
-rootr ls                # 전체 트리
-rootr ls /notes         # /notes 하위만
+rootr config --add-key rootr_xxx --label "Sales"
+rootr config                       # list registered keys
 ```
 
-출력: `TYPE\tpath` 형식, 경로 정렬.
+After that, `rootr use` (and the `rootr_use_workspace` MCP tool) accepts a **name, an id, or a
+rootr.io URL**; the key that opens that workspace is selected and remembered automatically. An
+account key (PAT) switches to any workspace you belong to.
 
-### 문서 읽기
+A workspace key does not open anything outside its own workspace. Because of that, `rootr ws`
+marks entries your registered keys cannot open — **being listed and being reachable are not the
+same thing**.
 
-```bash
-rootr read /notes/todo.md          # 마크다운 원문을 stdout으로
-rootr read /notes/todo.md --json   # 메타데이터 포함 JSON 전체
-rootr read <nodeId>                # id로도 가능
-```
+Web URLs (`https://rootr.io/en/w/<ws>/d/<doc>`) can be pasted directly into any node argument.
+If the URL belongs to another workspace, the error tells you to switch first.
 
-### 문서 쓰기 (전체 교체, 없으면 생성)
+> The remote connector (`https://rootr.io/mcp`) is bound to the single workspace you picked when
+> you authorized it. For another workspace, issue a new connector for that workspace.
 
-```bash
-echo "# 제목" | rootr write /notes/new.md
-rootr write /notes/new.md --file ./local.md
-rootr write <nodeId> --file ./local.md --if-match "\"abc123\""   # 낙관적 동시성 제어
-```
+## CLI
 
-경로가 아직 없으면 자동으로 문서를 생성합니다(`createParents: true`).
-`--if-match`를 지정했는데 그 사이 문서가 바뀌었으면 412 오류와 함께
-"문서가 그 사이 변경됨: 다시 읽고 재시도" 힌트가 출력됩니다.
+Path arguments starting with `/` are resolved as **paths** through the by-path API (needs a
+workspace). Anything else is treated as a **node id**.
 
-### 안전하게 추가 (append) — 충돌 걱정 없는 기본 수단
+### Documents
 
 ```bash
-rootr append /notes/log.md "오늘 배포 완료"
-rootr append /notes/log.md "- 항목 하나 더" --heading "## 할 일"
-cat diff.md | rootr append /notes/log.md
-rootr append /notes/log.md --file ./chunk.md
-```
+rootr ls                                  # whole tree, TYPE<TAB>path
+rootr ls /notes                           # one subtree
 
-`--heading`을 지정하면 해당 헤딩 섹션 끝에 추가되고, 없으면 문서 끝에 추가됩니다.
-append는 전체 내용을 다시 쓰지 않으므로 다른 프로세스와 동시에 써도 충돌하지 않습니다.
+rootr read /notes/todo.md                 # markdown to stdout
+rootr read /notes/todo.md --json          # full JSON with metadata
 
-### 텍스트 치환 (edit)
+echo "# Title" | rootr write /notes/new.md
+rootr write /notes/new.md --file ./local.md
+rootr write <nodeId> --file ./local.md --if-match '"abc123"'   # optimistic concurrency
 
-```bash
-rootr edit /notes/todo.md --find "- [ ] 배포" --replace "- [x] 배포"
+rootr append /notes/log.md "deploy finished"
+rootr append /notes/log.md "- one more item" --heading "## Todo"
+cat diff.md | rootr append /notes/log.md
+
+rootr edit /notes/todo.md --find "- [ ] deploy" --replace "- [x] deploy"
 rootr edit /notes/todo.md --find "TODO" --replace "DONE" --all
+
+rootr comments /notes/spec.md             # comments, including ones left on the public page
+rootr search "deployment runbook"
+rootr mv /notes/old.md /archive/old.md    # move and/or rename
+rootr rm /notes/old.md --yes              # to the trash, recoverable
+rootr restore <id>                        # undo a delete (id, not path)
+rootr attach ./diagram.png --doc /notes/spec.md --heading "## Design"
 ```
 
-`--find`한 텍스트가 없거나 여러 번 나타나면(고유하지 않으면) 서버가 409를 반환하고
-그 이유가 그대로 출력됩니다. `--all`을 주면 모든 일치 항목을 치환합니다.
+`append` never rewrites the whole document, so concurrent writers cannot clobber each other —
+prefer it over `write`. `--heading` appends to the end of that heading's section.
 
-### 검색
+`edit` returns 409 if the `--find` text is missing or not unique; the server's reason is printed
+as-is. `write --if-match` returns 412 if the document changed in the meantime.
+
+### Workspaces and questions
 
 ```bash
-rootr search "배포 절차"
+rootr ws                                  # id<TAB>name
+rootr use "Sales"                         # switch — id, name, or rootr.io URL
+rootr ask "why did latency go up after last week's deploy?"
+rootr ask "why did payment failures rise?" --workspace ws_123
 ```
 
-출력: `path — snippet` 목록.
+`ask` queries the workspace knowledge graph (GraphRAG) and prints the answer plus citations in
+`document path: quote` form. Requires the `ask` scope.
 
-### 문서 삭제 (휴지통으로)
+### Databases
 
 ```bash
-rootr rm /notes/todo.md          # 확인 후 삭제
-rootr rm /notes/todo.md --yes    # 확인 없이 (스크립트용)
+rootr db create --file spec.json --parent /projects   # columns in the given order, rows included
+rootr db rows /projects/tasks --body --backlinks      # rows, with row bodies and inbound links
+rootr db row-add /projects/tasks --values '{"Title":"Ship v2","Status":"Doing"}'
+rootr db rows-new /projects/tasks --file rows.json    # many at once — all or nothing
+rootr db rows-set /projects/tasks --ids r1,r2 --values '{"Status":"Done"}'
+rootr db rows-each /projects/tasks --json '[{"rowId":"r1","values":{"Score":3}}]'
+rootr db rows-rm  /projects/tasks --ids r1,r2 --yes
+rootr db view /projects/tasks Calendar --scale month  # views: table, board, calendar, timeline
+rootr db lock /projects/tasks --schema managers --rows own --locked "Approved,Score"
+rootr db notify  /projects/tasks --file rules.json    # notification rules
+rootr db buttons /projects/tasks --file buttons.json  # buttons that do work when pressed
+rootr db button-run /projects/tasks fill-summary --rows r1,r2
+rootr db row-page <rowId> --type RECORDING            # give one row a typed detail page
 ```
 
-휴지통으로 옮기는 **복구 가능한** 삭제입니다. 30일이 지나면 자동으로 완전 삭제됩니다.
-되돌리려면 `rootr restore <id>` — 화면에서 Ctrl+Z 를 누르는 것과 같은 일입니다.
-**경로가 아니라 id** 입니다(휴지통에 든 것은 이미 트리에 없어 경로로는 못 찾습니다).
-`rootr rm` 이 마지막 줄에 그 id 를 찍어 주니 그대로 쓰면 됩니다. MCP 로는
-`rootr_restore_node`. `--yes` 없이 실행하면 확인을 묻습니다
-(파이프/CI처럼 입력이 없는 환경에서는 "아니오"로 처리되어 안전합니다).
-`docs:write` 스코프가 필요합니다.
-
-### 워크스페이스 목록 · 전환
+### Forms
 
 ```bash
-rootr ws                       # 목록 (현재 워크스페이스에 *, 못 여는 곳은 표시)
-rootr use "영업팀"              # 전환 — id · 이름 · rootr.io 주소 아무거나
+rootr form new /intake/request --collect db \
+  --fields '[{"name":"Email","type":"email","required":true},{"name":"How urgent?","type":"scale"}]'
+rootr form show /intake/request                       # read the questions before changing them
+rootr form set  /intake/request --fields '[...]'      # replaces the question set
+rootr form collect /intake/request --to sheet         # create and wire a destination
+rootr form responses /intake/request --latest         # --latest = newest one per person
+rootr form response-edit <responseId> --values '{"Email":"a@b.com"}'
 ```
 
-`rootr ws` 출력은 `id\tname` 목록입니다. 등록된 키가 워크스페이스 전용 키뿐이면 목록에는
-보이지만 열 수 없는 워크스페이스에 `[등록된 키로는 접근 불가]`가 붙습니다 — 목록에 보이는
-것과 접근되는 것은 다릅니다. `rootr use`는 그 워크스페이스를 여는 키를 골라 함께 기억합니다.
+`--fields` takes a JSON array as a **string**, not a file path.
 
-### 워크스페이스 여러 개 쓰기 (키 등록 + 전환)
+18 question types, including `text`, `email`, `phone`, `url`, `rating`, `scale`, `time`, `file`,
+`matrix`, `ranking`, `csat` and `nps`. `--collect db|sheet` creates the destination and wires it
+up, mapping questions to columns.
 
-워크스페이스마다 키가 다르면 한 번만 등록해 두세요:
+### Publishing and access
 
 ```bash
-rootr config --add-key rootr_xxx --label "영업팀"
-rootr config                       # 등록된 키 목록 확인
+rootr publish /handbook --children              # works for every node type
+rootr publish /handbook --status                # is it public, at what URL, children included?
+rootr publish /projects/tasks --layout board --skin paper   # 9 layouts × 6 skins
+rootr publish /handbook/policy.md --comments --expires 2026-12-31T00:00:00Z
+rootr publish /handbook --off
+
+rootr access /handbook --private                # or --public / --inherit
+rootr access /handbook --grant <userId> --level WRITE
+rootr access /handbook --revoke <userId>
+
+rootr readreq /handbook/policy.md --users u1,u2 --due 2026-10-01T00:00:00Z --ack
+rootr readreq /handbook/policy.md               # who has read it, completion rate
 ```
 
-이후 MCP에서 `rootr_use_workspace` 도구로 **이름·id·루터 웹 주소** 중 아무거나 주면 활성
-워크스페이스가 바뀌고, 그 워크스페이스를 담당하는 키가 자동으로 선택·기억됩니다. 계정
-키(PAT)를 쓰면 소속된 어느 워크스페이스로든 바로 전환됩니다.
-
-워크스페이스 키는 자기 워크스페이스 밖에서는 열리지 않습니다 — `rootr ws`(=`rootr_workspaces`)
-목록에 보여도 접근은 안 되는 경우가 있어, 등록된 키가 워크스페이스 키뿐이면 목록에
-`[등록된 키로는 접근 불가]`를 함께 표시합니다.
-
-문서를 가리키는 웹 주소(`https://rootr.io/ko/w/<ws>/d/<doc>`)는 `rootr_read` 등 모든 노드
-인자에 그대로 붙여넣을 수 있습니다. 다른 워크스페이스의 주소면 "먼저 전환하라"고 알려줍니다.
-
-> 원격 커넥터(`https://rootr.io/mcp`)는 승인할 때 고른 워크스페이스 하나에만 연결됩니다.
-> 다른 워크스페이스가 필요하면 그 워크스페이스로 커넥터를 새로 발급하세요.
-
-### 사용량 한도
-
-프로그램(API 키·MCP) 호출 중 **조회 계열**(`docs:read`/`graph:read`/`ask`)에만 한도가 있습니다.
-쓰기·업로드는 제한하지 않습니다.
-
-| 플랜 | 한도 |
-| --- | --- |
-| Free | **하루 180회** (KST 자정 리셋) |
-| Team | 시간당 5,000회 |
-| Business | 시간당 50,000회 |
-| Platform | 무제한 |
-
-한도의 80%를 쓰면 MCP 도구 응답 끝에 남은 횟수 안내가 붙고, 다 쓰면 429와 함께
-업그레이드 링크가 담긴 안내가 나옵니다. 응답 헤더로도 확인할 수 있습니다
-(`X-RateLimit-Remaining`, `X-RateLimit-Reset`, `X-RateLimit-Window`).
-
-### 서명문서 · 연구노트 (sign)
+### Signed documents and research notes
 
-서명문서는 마크다운 문서인데 **올리는 순간 본문이 얼고**, 결재라인에 적힌 사람들이
-차례로 서명합니다. 서명마다 공인시점확인(TSA)과 해시 체이닝이 붙어 위·변조를
-증명할 수 있고, 서명된 문서는 삭제되지 않습니다(30년 보존).
-전자결재와 국가R&D 전자연구노트가 같은 기능 하나입니다.
+A signed document is a markdown document whose body **freezes the moment it is submitted**; the
+people on the approval line then sign in order. Every signature carries a trusted timestamp (TSA)
+and hash chaining, so tampering is provable, and signed documents are never deleted (30-year
+retention). Corporate approval flows and national R&D electronic research notes are the same
+feature.
 
 ```bash
-# 만들기 — 본문·결재라인까지 한 번에. 연구노트는 점검자만 정하면 두 단계가 자동
-rootr sign new "/연구노트/2026-08-25 실험기록" --file note.md --reviewer <연구책임자 userId>
+# create — body and approval line in one step; a research note only needs a reviewer
+rootr sign new "/notes/2026-08-25 experiment" --file note.md --reviewer <reviewer userId>
 
-# 결재라인을 직접 짜려면 (배열 순서 = 서명 순서)
+# build the approval line by hand (array order = signing order)
 cat > line.json <<'EOF'
-[ { "label": "기재자", "members": [{ "userId": "u1", "role": "AUTHOR" }] },
-  { "label": "부서장", "rule": "ANY", "members": [{ "userId": "u2" }, { "userId": "u3" }] } ]
+[ { "label": "Author",  "members": [{ "userId": "u1", "role": "AUTHOR" }] },
+  { "label": "Manager", "rule": "ANY", "members": [{ "userId": "u2" }, { "userId": "u3" }] } ]
 EOF
-rootr sign line /연구노트/2026-08-25\ 실험기록 --file line.json
+rootr sign line "/notes/2026-08-25 experiment" --file line.json
 
-# 올리기: 확인 코드를 메일로 받고 → 그 6자리를 넘긴다
-rootr sign code   /연구노트/2026-08-25\ 실험기록
-rootr sign submit /연구노트/2026-08-25\ 실험기록 --code 123456
+# submit: request a confirmation code by email, then pass those 6 digits
+rootr sign code   "/notes/2026-08-25 experiment"
+rootr sign submit "/notes/2026-08-25 experiment" --code 123456
 
-# 다음 사람: 내 차례인 것만 보고 → 서명 (또는 사유를 달아 반려)
+# next signer: see only what is waiting on you, then sign (or reject with a reason)
 rootr sign list --pending
 rootr sign code <id> && rootr sign approve <id> --code 123456
-rootr sign reject <id> --comment "근거 자료가 빠졌습니다" --code 123456
+rootr sign reject <id> --comment "supporting data is missing" --code 123456
 
-# 여러 건 한 번에 (코드 하나로 최대 100건)
+# many at once (up to 100 with a single code)
 rootr sign code --bulk
 rootr sign bulk <id1> <id2> <id3> --code 123456
 
-# 증명
-rootr sign verify <id>     # 본문·서명·시점확인·원장이 성한지
-rootr sign ledger          # 워크스페이스 원장 전체 재계산
+# proof
+rootr sign verify <id>     # body, signatures, timestamps and ledger intact?
+rootr sign ledger          # recompute the whole workspace ledger
 ```
 
-**확인 코드는 CLI가 대신 만들어 줄 수 없습니다.** 코드는 서명하는 사람 메일로만
-가고, 서버가 개인키를 보관하는 구조에서 그게 "본인이 눌렀다"의 유일한 증거입니다.
-10분 유효, 5회 틀리면 죽고, 30초 안에 다시 요청하면 거절됩니다.
+**The CLI cannot mint the confirmation code for you.** It is emailed to the signer only. In a
+design where the server holds the private key, that code is the single piece of evidence that a
+human pressed the button. It is valid for 10 minutes, dies after 5 wrong attempts, and a repeat
+request within 30 seconds is refused.
 
-서명된 문서는 고치는 게 아니라 **개정본**을 냅니다(`rootr sign revise <id> --note "…"`).
-원본은 `SUPERSEDED`로 남습니다 — 지침이 "고친 흔적과 원본이 모두 보여야 한다"를
-요구하기 때문입니다.
+Approval-line members are `{"userId"}` or `{"email","displayName"}` — with an email address a
+person can sign without a Rootr account.
 
-### 제보 보내기 (feedback)
+A signed document is never edited in place. You issue a **revision**
+(`rootr sign revise <id> --note "…"`) and the original stays as `SUPERSEDED`, because the
+regulations require both the original and the trace of the change to remain visible.
+
+### Team memory
 
 ```bash
-rootr feedback "행을 추가하려는데 rootr_add_row가 칸 이름을 못 찾는다고 합니다. 칸 id로 바꾸니 됐습니다." --kind friction
-rootr feedback --file report.md --kind bug --email me@example.com
-cat error.log | rootr feedback --kind bug
+rootr memory                                          # recall everything
+rootr memory --query seminar --kind 지시               # filtered
+rootr memory add "Report times in KST only" --kind 지시 --source /rules.md
+rootr memory edit <id> --content "corrected sentence" # only the fields you pass change
+rootr memory forget <id>                              # retire (--hard deletes the row)
 ```
 
-오류·불편·제안을 Rootr 팀에 보냅니다. **로그인도, 워크스페이스도, API 키도 필요
-없습니다** — 키가 틀려서 아무것도 못 하는 상태에서도 보내집니다(그 제보가 우리가
-제일 받고 싶은 제보입니다). 사용량 한도에도 걸리지 않고, 크레딧도 쓰지 않습니다.
-
-`--kind`는 `bug`(안 되는 것) · `friction`(되지만 불편·헷갈림) · `idea`(있으면 좋겠다) ·
-`praise` · `other` 중 하나이며, 생략하면 `other`입니다. `--title`을 안 주면 본문 첫
-줄이 제목이 됩니다. 답을 받고 싶을 때만 `--email`을 주세요.
+`--kind` is one of four literal values: `지시` (how the team wants work done), `사람` (someone's
+role or preference), `프로젝트` (an ongoing effort), `참고` (a reference). The same four values
+are the enum on the `rootr_remember` / `rootr_recall` MCP tools.
 
-같은 사람이 10분 안에 같은 내용을 또 보내면 한 건으로 합칩니다 — 실패 재시도
-안에서 반복 호출해도 목록이 더러워지지 않습니다.
+One-line facts that outlive a session and are shared by the whole workspace. This is the same
+data as the `rootr_remember` / `rootr_recall` / `rootr_forget` MCP tools and the "Memory" menu in
+the app. **Long things belong in a document; one-liners belong in memory.**
 
-### RCA 질의응답 (ask)
+### Scaffolding a workspace
 
 ```bash
-rootr ask "지난주 배포 후 지연이 왜 늘었어?"
-rootr ask "왜 결제 실패가 늘었지?" --workspace ws_123
+rootr scaffold plan "a workspace for running a hardware startup's QA process"
+rootr scaffold review --file tree.json     # get graded before anything is created
+rootr scaffold apply  --file tree.json --root /qa
+rootr scaffold built --root /qa            # inspect the shape of what was created
+rootr scaffold test  --root /qa            # actually exercise relations, rollups, formulas, forms
 ```
 
-워크스페이스의 지식그래프(GraphRAG)에 질문하고 답변 본문 + 인용(문서 경로: 인용문)을 출력합니다.
-`ask` 스코프가 필요합니다. `--workspace`를 생략하면 설정된 기본 워크스페이스를 사용합니다.
-
-### 팀의 기억 (memory)
+### Reporting a problem
 
 ```bash
-rootr memory                                     # 전체 회상 (상태·id·종류·출처)
-rootr memory --query 세미나 --kind 지시          # 걸러서 보기
-rootr memory add "보고 시각은 KST로만 표기한다" --kind 지시 --source /규칙.md
-rootr memory edit <id> --content "고친 문장"     # 그 기억만 고치기(준 칸만 바뀜)
-rootr memory edit <id> --kind 참고               # 종류만 고치기
-rootr memory forget <id>                         # 폐기(--hard면 행 삭제)
+rootr feedback "rootr_add_row could not find my column by name; column ids worked." --kind friction
+rootr feedback --file report.md --kind bug --email me@example.com
+cat error.log | rootr feedback --kind bug
 ```
 
-세션이 끝나도 남는, 워크스페이스 전체가 공유하는 한 줄 사실입니다. MCP의
-`rootr_remember`/`rootr_recall`/`rootr_forget`과 같은 길을 터미널에서 쓰는
-명령이고, 화면의 "기억" 메뉴와도 같은 데이터를 봅니다. **긴 건 문서로, 한 줄은
-기억으로** — 자세한 규칙은 MCP 도구 설명을 참고하세요.
+Sends bugs, friction and ideas to the Rootr team. **No login, no workspace, no API key required**
+— it works even when a wrong key means nothing else does, and that is exactly the report we most
+want. It does not count against usage limits and does not consume credits.
 
-## MCP 서버로 사용하기
+`--kind` is one of `bug`, `friction`, `idea`, `praise`, `other` (default `other`). Without
+`--title` the first line of the body becomes the title. Pass `--email` only if you want a reply.
+The same body sent twice within 10 minutes is merged into one report, so retry loops do not
+pollute the queue.
 
-`rootr mcp`는 stdio로 MCP(Model Context Protocol) 서버를 구동합니다. 제공 도구 152종:
+## Usage limits
 
-노드를 가리키는 인자(`target`, `databaseId`, `spreadsheetId`, `formId`, `crmId`, `trackerId`,
-`recordingId`, `presentationId`, `whiteboardId`, `logId`, `parentId` 등)는 **노드 id와 경로를 모두**
-받습니다 — CLI와 같은 규칙으로 `/`로 시작하면 경로로 해석합니다.
-즉 `rootr_add_row`에 `databaseId: "/제작 공정/칸반"`을 그대로 넘길 수 있어,
-경로만 아는 에이전트가 uuid를 찾아 헤맬 필요가 없습니다.
-`rootr_list`·`rootr_search` 출력도 각 줄 끝에 `[노드 id]`를 함께 표시합니다.
+Only **read-type** calls (`docs:read` / `graph:read` / `ask`) made programmatically (API key or
+MCP) are metered. Writes and uploads are not limited.
 
-#### 문서 (workspace 키, docs:read/docs:write)
-
-| 도구 | 설명 |
-|---|---|
-| `rootr_list` | 워크스페이스 트리 목록 |
-| `rootr_read` | 문서 마크다운 읽기 |
-| `rootr_append` | **(권장)** 문서에 안전하게 추가 — 충돌 불가능 |
-| `rootr_edit` | 정확한 텍스트 스니펫 치환 |
-| `rootr_write` | 문서 전체 교체(파괴적) 또는 신규 생성 |
-| `rootr_search` | 워크스페이스 검색 |
-| `rootr_comment_document` | 문서에 댓글 달기 |
-| `rootr_list_document_comments` | 문서에 달린 댓글 목록 |
-| `rootr_duplicate_node` | 노드 통째로 복제(하위까지) |
-| `rootr_move_node` | 노드 옮기기 / 이름 바꾸기 |
-
-에이전트에게는 가능하면 `rootr_append`/`rootr_edit`을 우선 사용하고,
-`rootr_write`는 정말 전체를 다시 쓸 때만 (가능하면 `ifMatch`와 함께) 쓰도록
-각 도구 설명에 명시되어 있습니다.
-
-#### 첨부파일 (workspace 키, docs:write)
+| Plan | Limit |
+| --- | --- |
+| Free | **180 calls per day** (resets at midnight KST) |
+| Team | 5,000 per hour |
+| Business | 50,000 per hour |
+| Platform | Unlimited |
 
-| 도구 | 설명 |
-|---|---|
-| `rootr_upload_attachment` | 로컬 파일(`filePath`) 또는 base64(`base64Data`)를 업로드하고 `{id, url, markdown}` 반환 |
-| `rootr_attach_image_to_document` | 위 업로드 + 지정 문서에 `rootr_append`로 바로 삽입 (가장 흔한 용법) |
+At 80% of the limit, MCP tool responses append a note with the remaining count. At the limit you
+get a 429 with an upgrade link. The response headers carry the same information
+(`X-RateLimit-Remaining`, `X-RateLimit-Reset`, `X-RateLimit-Window`).
 
-`url`은 `/attachments/{id}/raw` — 로그인 없이 렌더되는 공개 경로라 published(`/p/`) 문서에도
-그대로 쓸 수 있습니다. CLI에서는 `rootr attach <file> [--doc <path|id>] [--heading "## X"] [--alt <text>]`.
+## MCP tools
 
-#### 워크스페이스 / 스캐폴딩
+`rootr mcp` speaks MCP over stdio. 167 tools:
 
-| 도구 | 필요 스코프 | 설명 |
+| Group | Count | Tools |
 |---|---|---|
-| `rootr_workspaces` | 계정 키 또는 워크스페이스 키 | 내 워크스페이스 목록 |
-| `rootr_scaffold_plan` | 워크스페이스 불필요 | 짓기 1단계 — 물어볼 것·설계 규칙·건축 자재 목록을 받는다 |
-| `rootr_scaffold_review` | 워크스페이스 불필요 | 짓기 2단계 — **만들기 전에** 설계를 검사받는다(점수·고칠 곳). 컴파일러처럼 고쳐 가며 짓는다 |
-| `rootr_create_workspace` | **계정 키(PAT) + workspaces:create** | 짓기 3단계 — 계획된 트리로 새 워크스페이스 생성(검사 결과도 같이 돌려준다) |
-| `rootr_scaffold_apply` | docs:write | 짓기 3단계 — 기존 워크스페이스에 트리 적용(검사 결과도 같이 돌려준다) |
-| `rootr_delete_workspace` | **계정 키(PAT) + OWNER** | 짓다 실패해 남은 **빈 워크스페이스 치우기**. 이름을 그대로 다시 적어야 지워진다(되돌릴 수 없음) |
-
-스캐폴딩은 **plan → 물어보기 → 설계 → review → 고치기 → apply** 한 바퀴입니다.
-`review` 를 건너뛰면 "얇은 마크다운 파일 묶음"이 됩니다. CLI 로도 같은 세 단계를 쓸 수 있습니다:
-`rootr scaffold plan "..."` / `rootr scaffold review --file tree.json` / `rootr scaffold apply --file tree.json`.
-
-#### LOG 데이터스토어 (docs:read/docs:write)
-
-| 도구 | 설명 |
-|---|---|
-| `rootr_create_log_store` | 타입드 LOG 스토어 생성 (필드: string/int/float/bool/datetime/json/enum/level/relation) |
-| `rootr_update_log_fields` | 필드 스키마 갱신 — **전체 교체**(유지할 필드도 다시 보내야 함) |
-| `rootr_add_log_entries` | 엔트리(행) 추가 |
-| `rootr_query_log_entries` | 엔트리 조회/필터(시간범위·source·level·anomalyOnly) |
-| `rootr_log_stats` | 집계 통계(hour/day/source/level × count/avg/max/min/sum) |
-
-#### RCA 질의응답 (ask 스코프)
-
-| 도구 | 설명 |
-|---|---|
-| `rootr_ask` | 지식그래프(GraphRAG)에 자연어 질문, 답변+인용 반환 |
-
-#### 이슈 트래커 (docs:read/docs:write)
-
-| 도구 | 설명 |
-|---|---|
-| `rootr_create_issue_tracker` | 이슈 트래커 생성 |
-| `rootr_list_issues` | 이슈 목록(state/label/type/assignee/검색어 필터) |
-| `rootr_create_issue` | 이슈 생성(labels/type/parentIssueId 지원) |
-| `rootr_get_issue` | 이슈 상세 조회 |
-| `rootr_update_issue` | 이슈 갱신(닫기: state=CLOSED + stateReason) |
-| `rootr_comment_issue` | 이슈에 댓글 추가 |
-
-#### 웹훅 (webhooks:manage 스코프)
-
-| 도구 | 설명 |
-|---|---|
-| `rootr_list_webhooks` | 워크스페이스 웹훅 목록 |
-| `rootr_create_webhook` | 웹훅 생성 — 응답의 secret은 **1회만 노출** |
-| `rootr_delete_webhook` | 웹훅 삭제 |
-
-#### 표(DATABASE) — 행과 열 (docs:read/docs:write)
-
-| 도구 | 설명 |
-|---|---|
-| `rootr_read_database` | 스키마(열 정의)+행 전체 읽기 — **다른 표 도구를 쓰기 전에 먼저** (`includeBody: true` 면 행마다 상세 내용까지) |
-| `rootr_list_rows` | 행만 조회(스키마 제외, `includeBody` 지원, `backlinks: true`면 "나를 가리키는 다른 표의 행"도 함께) |
-| `rootr_add_row` | 행 추가 (`values`는 열 이름 또는 id로 지정, `body`로 상세 내용까지) |
-| `rootr_update_row` | 행 수정 (칸반 카드 이동 = select 열 값 변경, `body`로 상세 내용 교체) |
-| `rootr_bulk_create_rows` | 행 여러 개를 한 번에 추가 |
-| `rootr_bulk_update_rows` | 여러 행을 **같은 값**으로 한 번에 수정 |
-| `rootr_bulk_update_rows_each` | 여러 행을 **행마다 다른 값**으로 한 번에 수정 |
-| `rootr_delete_row` | 행 삭제 |
-| `rootr_bulk_delete_rows` | 행 여러 개를 한 번에 삭제 |
-| `rootr_create_view` | 보기 추가 — 테이블/보드/캘린더/타임라인/갤러리 (달력은 `calendarScale`로 주·달·해) |
-| `rootr_update_view` | 보기 수정 — 열 숨기기·이름·그룹·필터·정렬·열 너비·달력 단위(`calendarScale`) |
-| `rootr_delete_view` | 보기 삭제 |
-| `rootr_create_row_page` | 행에 상세 페이지 붙이기(문서 또는 서명문서) |
-| `rootr_set_row_page_type` | 앞으로 만드는 행이 무엇으로 열릴지 정하기 |
-| `rootr_unlink_row_page` | 행과 상세 페이지의 연결 끊기 |
-| `rootr_add_column` | **열 추가** — 기존 열·행은 그대로 |
-| `rootr_update_column` | 열 이름 변경 / select 선택지 교체 |
-| `rootr_delete_column` | 열 삭제(파괴적) |
-| `rootr_read_database_permissions` | 표에 걸린 자물쇠 보기 |
-| `rootr_set_database_permissions` | 표 잠그기 — 칸·뷰 잠금 / 본인 행만 / 관리자만 고칠 칸 |
-| `rootr_read_database_notifications` | 표 알림 규칙 보기 |
-| `rootr_set_database_notifications` | 표 알림 규칙 저장 — 누구에게·언제·어떤 것만 |
-| `rootr_list_database_buttons` | 표 위 **버튼** 목록 보기(고칠 수 있는지 `myLevel`도 함께) |
-| `rootr_set_database_buttons` | 버튼 만들고 고치기 — **목록 통째로 교체**(남길 것도 같이 보내야 함) |
-| `rootr_run_database_button` | 버튼 누르기 — 행 만들기·값 채우기·AI로 칸 채우기가 순서대로 |
-| `rootr_list_document_commits` | 공개 문서에 온 변경 제안 목록 |
-| `rootr_merge_document_commit` | 변경 제안 반영(세 벌 병합 — 덮어쓰기 아님) |
-| `rootr_reject_document_commit` | 변경 제안 거절(사유는 제안자에게 전달) |
-| `rootr_read_node_access` | 이 문서·폴더를 누가 볼 수 있는지(공개범위 + 따로 준 권한) |
-| `rootr_set_node_visibility` | 비공개로 잠그기 / 상위 설정 따르기 |
-| `rootr_grant_node_permission` | 한 사람(또는 그룹)에게 READ·WRITE·MANAGE 주기 |
-| `rootr_revoke_node_permission` | 준 권한 거두기 |
-| `rootr_update_form_response` | 이미 들어온 폼 응답 고치기(폼 검사 규칙 다시 통과) |
-| `rootr_delete_form_response` | 폼 응답 한 건 삭제 |
-| `rootr_create_form_collector` | 응답 모을 표·스프레드시트를 **만들어서** 연결(표는 질문 그대로 칸 생성) |
-
-**표 버튼 — 매번 하는 준비 동작을 한 번에.** 새 건이 생길 때마다 상태=접수, 담당=나,
-마감=오늘+7 을 손으로 다시 채우는 일을 버튼 하나로 만듭니다. 단계는 **적힌 순서대로**
-돌고 **앞 단계가 만든 행을 뒤 단계가 받으므로**, "행을 만들고 → 그 행의 요약을 AI가 쓰고
-→ 그 행을 연다"가 한 번 누름으로 끝납니다. 값에는 `@today` · `@today+7` · `@me` 를 쓸 수
-있고 누르는 그 시점에 채워집니다. 버튼은 권한을 늘리지 않습니다 — **누른 사람 권한 그대로**
-돕니다(만들기·고치기는 관리자, 누르기는 편집 권한).
-
-```bash
-rootr db buttons <표>                      # 지금 달린 버튼 보기
-rootr db buttons <표> --file buttons.json  # 목록 통째로 저장(남길 것도 같이)
-rootr db button-run <표> <버튼id>           # 한 번 누르기 (--rows id,id 로 고른 행 지정)
-rootr db view <표> <뷰> --scale year       # 달력 보기를 주·달·해 중에서
-```
-
-```json
-[{ "label": "접수", "icon": "📥", "steps": [
-    { "kind": "add_row", "values": { "상태": "접수", "담당": "@me", "마감": "@today+7" } },
-    { "kind": "ai_fill", "target": "created", "propId": "요약", "prompt": "{제목}을 한 문장으로 요약해." },
-    { "kind": "open_row" }
-] }]
-```
-
-스캐폴드로 표를 지을 때도 `database.buttons` 에 같은 모양을 넣으면 **표와 함께** 달립니다.
-
-**행에 댓글 달기.** 표의 한 행에 댓글을 달려면 `rootr_comment_document` 에 **표**를
-`target` 으로, **행 id**를 `blockId` 으로 줍니다(읽기는 `rootr_list_document_comments`,
-명령줄은 `rootr comments <표> --block <행id>`). 상세 문서가 없는 행에도 달립니다.
-`@[userId]` 로 사람을 부르면 알림이 가고, 그 알림은 **그 행**을 열면서 댓글을 짚어 줍니다.
-
-**사람 칸은 여러 명을 담습니다.** 회의 참석자·공동 담당처럼 여럿이 들어가는 자리가
-흔해서, 값은 이름 목록(`["김대표","이팀장"]`)입니다. 이름 하나만 보내도 받아 주고
-목록으로 맞춰 돌려줍니다. 새로 들어온 사람에게만 알림이 갑니다.
-
-**"만들면서 같이 잠그기".** 공개범위는 스캐폴드 트리에서도 노드마다 지정할 수 있습니다 —
-`{ name: "채용", visibility: "PRIVATE", access: [{ subjectId: "<userId>", level: "READ" }] }`.
-폴더는 만들어 주면서 잠그는 건 사람이 따로 해야 하는 상태가 되지 않도록, 한 번에 갑니다.
-명령줄에서는 `rootr access <경로|id> --private`, `--grant <userId> --level READ`,
-`--revoke <userId>` 입니다. (웹에 공개하는 것과는 다릅니다 — 그건 `rootr_set_document_public`.)
-
-응답 모을 곳은 `rootr form collect <폼> --to db|sheet`로 **만들면서** 연결합니다 —
-표로 만들면 폼 질문 그대로 칸이 생기므로, 표를 미리 만들고 칸 이름을 맞출 필요가 없습니다
-(이름이 하나라도 어긋나면 그 칸은 영영 빈 칸으로 남습니다). 스캐폴드 트리에서는 폼 노드에
-`form.collectInto: "database" | "spreadsheet"`로 같은 일을 합니다.
-
-폼 응답은 `rootr form responses <폼> [--latest]`로 보고, `rootr form response-edit <응답id>
---values '{"필드id":"값"}'`로 고치고, `rootr form response-rm <응답id> --yes`로 지웁니다.
-`--latest`는 같은 사람이 여러 번 낸 것 중 마지막 한 건만 남깁니다(익명 제출은 합치지 않습니다).
-
-행의 **상세 내용(본문 메모)** — 화면에서 칸반 카드를 열면 속성 아래에 적는 그 글 — 은
-`body`로 오갑니다. 실체는 표 밑에 달리는 문서 한 장이고, 없으면 쓸 때 만들어집니다.
-명령줄에서도 됩니다: `rootr db row-add <표> --values '{"제목":"킥오프"}' --body "..."`,
-`rootr db row-body <표> <rowId> --file memo.md`, `rootr db rows <표> --body`.
-
-열은 **한 번에 하나씩** 다룹니다. REST의 `PATCH /databases/:id`는 `properties`
-배열을 통째로 교체하기 때문에, 에이전트가 배열을 다시 만들다 빠뜨린 열이 그대로
-사라집니다. 위 세 도구는 서버가 병합하므로 나머지 열이 없어지지 않습니다.
-
-- **열을 추가해도 기존 행 데이터는 건드리지 않습니다** — 새 열은 값이 채워지기 전까지 빈 칸으로 읽힙니다.
-- **열의 `type`은 바꿀 수 없습니다**(모든 행의 값을 다시 써야 하므로). 새 열을 만들어 값을 옮기세요.
-- `title` 열은 추가로 만들 수도, 삭제할 수도 없습니다.
-- 삭제한 열의 값은 행 안에 남아 있지만 화면에는 나오지 않습니다 — 사용자 확인 후 호출하세요.
-
-#### 폼(FORM) — 받아 적는 창구 (docs:read/docs:write)
-
-| 도구 | 설명 |
-|---|---|
-| `rootr_create_form` | 폼 만들기 — 질문 정의·응답 모을 표(`targetDatabaseId`)까지 한 번에 |
-| `rootr_read_form` | 질문 정의와 설정 읽기 — **고치기 전에 먼저** |
-| `rootr_update_form` | 질문·설정 수정(`config`는 아래 설명 참고) |
-| `rootr_create_form_collector` | 응답 모을 표·스프레드시트를 **만들어서** 연결(표는 질문 그대로 칸 생성) |
-| `rootr_list_form_responses` | 들어온 응답 목록 |
-| `rootr_submit_form_response` | 응답 한 건 제출(사람 대신 넣어 줄 때) |
-| `rootr_update_form_response` | 이미 들어온 응답 고치기(폼 검사 규칙 다시 통과) |
-| `rootr_delete_form_response` | 응답 한 건 삭제 |
-| `rootr_create_form_share_link` | 폼 전용 공유 링크 발급(`/f/<토큰>`) |
-| `rootr_list_form_share_links` | 발급된 공유 링크 목록 |
-
-폼을 밖에 여는 정상 경로는 **`rootr_publish_node`** 입니다 — 발행하면 `/p/<슬러그>`
-주소가 나오고 **응답 받기도 같이 켜집니다**. `config.publicSubmit`을 손으로 만질 일은
-거의 없고, 그만 받고 싶으면 `closesAt`·`maxResponses`를 걸거나 발행을 내리세요.
-`config.theme`은 `clean`·`paper`·`noir`·`ocean`·`sunset`·`mint`·`bento`·`brutal`·
-`vivid`·`dark` 10종이며, `cover`/`logo`는 이미지 **주소**라 `rootr_upload_attachment`로
-먼저 올리고 받은 url을 넣습니다(비워 두면 기본 커버가 붙습니다).
-
-#### 웹에 공개 발행 (docs:write)
-
-| 도구 | 설명 |
-|---|---|
-| `rootr_publish_node` | **아무 노드나** 공개 — 문서·표·폼·시트·화이트보드·덱, 하위까지 |
-| `rootr_set_node_public` | 이미 공개한 것의 설정 변경(하위 포함 여부·검색 노출·만료) |
-| `rootr_node_public_status` | 지금 공개돼 있는지, 주소는 무엇인지 |
-| `rootr_publish_document` | 문서 전용 발행(구형 — 새로 짤 때는 `rootr_publish_node`) |
-| `rootr_set_document_public` | 문서 전용 공개 설정 변경 |
-| `rootr_document_public_status` | 문서 전용 공개 상태 |
-
-#### 스프레드시트 (docs:read/docs:write)
-
-| 도구 | 설명 |
-|---|---|
-| `rootr_create_spreadsheet` | 스프레드시트 만들기(시트 여러 장 가능) |
-| `rootr_read_spreadsheet` | 시트·셀·수식 읽기 |
-| `rootr_patch_spreadsheet_cells` | **(권장)** 셀 값·수식만 콕 집어 쓰기 |
-| `rootr_update_spreadsheet` | 설정·아이콘 변경, 또는 시트 전체 교체(파괴적) |
-| `rootr_create_sheet` | 시트(탭) 추가 |
-| `rootr_update_sheet` | 시트 한 장 이름 변경·크기 조정 |
-| `rootr_delete_sheet` | 시트(탭) 삭제 |
-
-#### 화이트보드 (docs:read/docs:write)
-
-| 도구 | 설명 |
-|---|---|
-| `rootr_create_whiteboard` | 화이트보드 만들기 |
-| `rootr_read_whiteboard` | 도형·연결선 읽기 |
-| `rootr_update_whiteboard` | 장면 교체 또는 병합(merge), 설정·아이콘 |
-
-#### 녹음 · 회의록 (docs:read/docs:write)
-
-| 도구 | 설명 |
-|---|---|
-| `rootr_create_recording` | 녹음 노드 만들기 |
-| `rootr_upload_recording_audio` | 오디오 올리기(올리면 받아쓰기가 시작됩니다) |
-| `rootr_transcribe_recording` | 받아쓰기 실행/재실행 |
-| `rootr_read_recording` | 받아쓴 글·화자 구간 읽기 |
-| `rootr_rename_recording_speakers` | 화자 이름 바꾸기(화자1 → 김대표) |
-| `rootr_summarize_recording` | 요약·회의록 만들기 |
-| `rootr_download_recording_audio` | 원본 오디오 내려받기 |
-
-#### CRM (docs:read/docs:write)
-
-| 도구 | 설명 |
-|---|---|
-| `rootr_crm_create` | CRM 노드 만들기(파이프라인·칸 정의) |
-| `rootr_crm_get` | 파이프라인·칸·건수 보기 |
-| `rootr_crm_update` | 파이프라인·칸·설정 수정 |
-| `rootr_crm_list_companies` / `rootr_crm_get_company` | 회사 목록 / 상세(연락처·딜·활동·할 일) |
-| `rootr_crm_upsert_company` | 회사 추가·수정·삭제 |
-| `rootr_crm_list_contacts` / `rootr_crm_get_contact` | 연락처 목록 / 상세 |
-| `rootr_crm_upsert_contact` | 연락처 추가·수정·삭제 |
-| `rootr_crm_list_deals` / `rootr_crm_get_deal` | 딜 목록 / 상세 |
-| `rootr_crm_upsert_deal` | 딜 추가·수정·삭제 |
-| `rootr_crm_move_deal` | 딜을 다음 칸으로 옮기기(칸반 카드 이동) |
-| `rootr_crm_log_activity` / `rootr_crm_list_activities` | 활동 기록 남기기 / 타임라인 조회 |
-| `rootr_crm_upsert_task` / `rootr_crm_list_tasks` | 후속 할 일 만들기·수정 / 목록 |
-| `rootr_crm_import` | 여러 건 한 번에 가져오기 |
-
-#### 템플릿 (docs:read/docs:write)
-
-| 도구 | 설명 |
-|---|---|
-| `rootr_list_templates` | 문서·표 템플릿 목록 |
-| `rootr_apply_template` | 템플릿으로 노드 만들기 |
-| `rootr_save_as_template` | 지금 노드를(또는 즉석 정의를) 템플릿으로 저장 |
-| `rootr_update_template` | 템플릿 수정 |
-
-#### 기억 (docs:read / docs:write)
-
-| 도구 | 설명 |
-|---|---|
-| `rootr_remember` | 한 줄 사실을 기억시키기(같은 내용이면 갈아끼움). `memoryId`를 함께 주면 그 기억을 그 자리에서 고치기 |
-| `rootr_recall` | 이 워크스페이스가 아는 것 꺼내 오기 |
-| `rootr_forget` | 더 이상 맞지 않는 기억 폐기 |
-
-**에이전트에게**: 이건 세션이 끝나도 남는, **워크스페이스 전체가 공유하는** 기억입니다
-(개인 메모는 여기 두지 말고 자기 메모리에 두세요). **긴 건 문서로, 한 줄은
-기억으로, 그리고 기억은 반드시 문서를 가리키게** 하세요 — 이야기를 기억에 밀어
-넣으면 기억이 "짧은 문서 더미"가 되면서 둘 다 망합니다. 규칙·결정한 이유·한 번
-겪은 함정을 남기고, 그 근거가 된 문서 경로를 `source`로 같이 주세요(그래야 그
-문서가 바뀔 때 루터가 "확인 필요" 표시를 답니다).
-
-기억은 워크스페이스를 처음 만질 때 **도구 응답에 자동으로 딸려옵니다** — 굳이
-`rootr_recall`을 먼저 부르지 않아도 눈앞에 놓입니다. 이 자동 회상은 무료 조회
-한도를 쓰지 않습니다.
-
-사람이 직접 보고 고치려면 워크스페이스 왼쪽 메뉴의 **기억**에서 볼 수 있고,
-"표로 열기"를 누르면 평범한 표로 열려 권한·기록이 그대로 따라옵니다.
-
-#### 제보 (인증 불필요)
-
-| 도구 | 설명 |
-|---|---|
-| `rootr_send_feedback` | 오류·불편·제안 보내기 — 키가 없거나 틀려도 들어갑니다 |
-
-**에이전트에게**: 이 도구는 시켜야 부르는 도구가 아닙니다. 일하다가 예상 못 한
-오류를 만나거나, 도구가 설명과 다르게 동작하거나, 우회를 하게 되거나, 사용자가
-"이거 안 된다/헷갈린다"고 말하면 **묻지 말고 그 자리에서 한 번 보내고** 하던 일을
-계속하세요. 도구 설명에도 같은 말이 적혀 있습니다. 같은 문제로 두 번 보내지 마세요
-(10분 내 같은 내용은 자동으로 합쳐집니다).
-
-#### 읽음 확인 (docs:read/docs:write)
-
-| 도구 | 설명 |
-|---|---|
-| `rootr_set_read_requirement` | 이 문서를 반드시 읽게 하기(대상·기한) |
-| `rootr_read_requirement` | 누가 읽었고 누가 안 읽었는지 |
-| `rootr_clear_read_requirement` | 읽음 요구 해제 |
-
-#### 서명문서 · 연구노트 (docs:read/docs:write)
-
-| 도구 | 설명 |
-|---|---|
-| `rootr_create_signed_document` | 서명문서 만들기 — 본문·모드·결재라인까지 한 번에 |
-| `rootr_read_signed_document` | 결재라인 진행·서명 목록·내 차례인지(`canSign`) |
-| `rootr_set_approval_line` | 결재라인 다시 짜기 (올리기 전에만) |
-| `rootr_apply_research_note_preset` | 연구노트로 전환 + 기재자→점검자 두 단계 자동 |
-| `rootr_request_signing_code` | 확인 코드를 서명자 메일로 발송 (서명 전 필수) |
-| `rootr_submit_signed_document` | 올리기 — 본문이 얼고 기안자가 첫 서명 |
-| `rootr_sign_document` | 내 차례에 서명 |
-| `rootr_reject_signed_document` | 반려 (사유 필수) |
-| `rootr_reopen_signed_document` | 아무도 서명 안 한 초안 다시 열기 |
-| `rootr_revise_signed_document` | 개정본 만들기 (원본은 남는다) |
-| `rootr_verify_signed_document` | 위변조 검증 — 본문·서명·시점확인·원장 |
-| `rootr_list_signed_documents` | 목록 (`pendingMine`: 내 차례인 것만) |
-| `rootr_bulk_sign_documents` | 코드 하나로 최대 100건 묶음 서명 |
-| `rootr_verify_ledger` | 워크스페이스 원장(해시 체인) 전체 재계산 |
-
-에이전트가 대신 눌러 줄 수 없는 자리가 하나 있습니다 — **서명**. 확인 코드는
-사람 메일로만 가므로 흐름은 항상 `rootr_request_signing_code` → 사람에게 6자리를
-물어봄 → `rootr_sign_document` 입니다. 코드를 지어내면 403이고, 5회 틀리면 코드가
-죽습니다.
-
-표의 행마다 서명문서를 붙이려면 `rootr_create_database`에 `rowPageType: "SIGNED"`를
-주세요 — 그 표는 행을 열 때마다 서명문서(연구노트)가 만들어집니다(실험 기록 대장,
-점검 대장).
-
-#### 문서 버전 / 삭제
-
-| 도구 | 설명 |
-|---|---|
-| `rootr_document_versions` | 문서 버전 히스토리 조회 |
-| `rootr_read_document_version` | 그 시점 본문을 그대로 읽기(되돌리기 전에 확인용) |
-| `rootr_restore_document_version` | 문서를 예전 버전으로 되돌리기 |
-| `rootr_update_node` | 아무 노드나 이름·아이콘 변경 / 옮기기 |
-| `rootr_delete_node` | 노드를 휴지통으로 이동(복구 가능) |
-
-#### 페이지 (웹페이지)
-
-페이지(PAGE)는 **바깥 사람이 볼 화면**입니다 — 행사 안내·제품 소개·신청 받기처럼
-링크 하나로 보여 줄 것. 전용 MCP 도구(`rootr_create_page`, `rootr_read_page`,
-`rootr_append_page_blocks`, `rootr_update_page`, `rootr_update_page_block`,
-`rootr_read_page_live_data`)로 저작합니다.
-
-HTML을 짜는 것이 아니라 **정해진 블록 14종을 골라 쌓습니다** — `hero` `text`
-`features` `gallery` `pricing` `testimonials` `faq` `timeline` `cta` `footer` +
-표에서 값을 끌어오는 `liveStats` `liveTable` `liveChart` + 신청을 받는 `form` + 자유 블록 `custom`.
-
-`custom`은 **격리된 방**입니다: HTML/CSS를 마음대로 쓰되 `sandbox` 아이프레임 안에서만
-그려집니다(스크립트 없음·같은 출처 아님·바깥 통신 차단). 그래서 대담한 CSS도 바깥 화면을
-못 덮습니다 — 저장할 때 `<script>`와 `on*=`는 지워집니다. 방 안에서는 페이지 분위기 색을
-`var(--pg-text)` `var(--pg-card)` `var(--pg-accent)` 처럼 쓸 수 있습니다.
-블록별 props는 **`/llms.txt`의 "Pages" 섹션**에 표로 정리돼 있습니다.
+| Documents | 22 | list, read, write, append, edit, search, comment, version history, commits & merges, publish, trash & restore |
+| Databases | 26 | create, columns, views, rows (single & bulk), row pages, permissions, notifications, buttons |
+| CRM | 18 | companies, contacts, deals (incl. pipeline moves), activities, tasks, CSV import |
+| Signed documents & research notes | 14 | create, sign, revise, reject, reopen, approval lines, signing codes, ledger verification, research-note preset |
+| Forms | 10 | create, read, update, responses, share links, collectors |
+| Presentations & images | 10 | decks, slides, diagram slides, image generation and background removal |
+| Workspaces & scaffolding | 9 | list, create, delete, switch, plan / review / apply a document tree, health check |
+| Pages | 6 | HTML page nodes: create, read, update, append and patch blocks, live data |
+| Spreadsheets | 7 | create, read, update, per-sheet create/update/delete, patch cells & formulas |
+| Recordings | 7 | create, upload & download audio, transcribe, summarize, rename speakers |
+| Issue tracker | 6 | create tracker, list / create / get / update issue, comment |
+| Permissions & visibility | 10 | grant / revoke node permissions, read access, visibility, public status, read requirements |
+| LOG datastores | 5 | create store, update fields, add entries, query, stats |
+| Templates | 4 | list, apply, save as template, update |
+| Whiteboards | 3 | create, read and update the shapes & edges scene |
+| Attachments | 2 | upload a file, attach an image straight into a document |
+| Agent memory | 3 | remember, recall, forget |
+| Webhooks | 3 | list, create (secret shown once), delete |
+| Root-cause Q&A | 1 | ask the workspace knowledge graph, answer with citations |
+| Feedback | 1 | send feedback to the Rootr team |
+
+Guidance baked into the tool descriptions: agents should reach for `rootr_append` and
+`rootr_edit`, and use `rootr_write` only for a genuine full rewrite (ideally with `ifMatch`).
+Tools that take a `workspace` argument fall back to `ROOTR_WORKSPACE` / the config file, and
+return a clear error if neither is set. Every tool description is written in English (it is the
+schema an agent consumes), and tools that return JSON reply with pretty-printed JSON text.
+
+Scope notes: document, database, spreadsheet, whiteboard, form, page, presentation, recording,
+signed-document, issue, CRM and LOG tools need `docs:read` / `docs:write`; `rootr_ask` needs
+`ask`; webhook tools need `webhooks:manage`; `rootr_create_workspace` needs an account key with
+`workspaces:create`.
+
+### Pages
+
+A PAGE is **a screen for people outside the workspace** — an event announcement, a product page,
+a sign-up. You do not write HTML: you stack **14 predefined block types** — `hero`, `text`,
+`features`, `gallery`, `pricing`, `testimonials`, `faq`, `timeline`, `cta`, `footer`, the
+table-backed `liveStats`, `liveTable`, `liveChart`, the `form` block, and the free-form `custom`.
+
+`custom` is an **isolated room**: write any HTML/CSS you like, but it renders inside a `sandbox`
+iframe (no scripts, not same-origin, no outbound calls), so even bold CSS cannot leak onto the
+rest of the page. `<script>` and `on*=` attributes are stripped on save. Inside the room you can
+use the page's palette through `var(--pg-text)`, `var(--pg-card)`, `var(--pg-accent)`.
+Per-block props are tabulated in the **"Pages" section of [`/llms.txt`](https://rootr.io/llms.txt)**.
 
 ```bash
-# 페이지 만들기 (블록을 생략하면 hero/text/footer 뼈대로 시작)
+# create a page (omit blocks to start from a hero/text/footer skeleton)
 curl -X POST "$BASE/workspaces/$WS/pages" -H "x-api-key: $KEY" \
   -H 'Content-Type: application/json' \
-  -d '{"name":"가을 행사","config":{"theme":"midnight"},
-       "blocks":[{"type":"hero","props":{"title":"가을 개발자 밋업","subtitle":"10월 12일 · 서울"}}]}'
+  -d '{"name":"Autumn meetup","config":{"theme":"midnight"},
+       "blocks":[{"type":"hero","props":{"title":"Autumn Developer Meetup","subtitle":"Oct 12 · Seoul"}}]}'
 
-# 블록 덧붙이기(있는 블록은 그대로) / 통째 교체 / 라이브 값 확인
-curl -X POST  "$BASE/pages/$ID/blocks" -d '{"blocks":[{"type":"faq","props":{"items":[...]}}]}' ...
+# append blocks (existing ones untouched) / replace config / read live values
+curl -X POST  "$BASE/pages/$ID/blocks" -d '{"blocks":[{"type":"faq","props":{"items":[]}}]}' ...
 curl -X PATCH "$BASE/pages/$ID"        -d '{"config":{"theme":"warm"}}' ...
-curl        "$BASE/pages/$ID/live-data" -H "x-api-key: $KEY"
+curl         "$BASE/pages/$ID/live-data" -H "x-api-key: $KEY"
 ```
 
-`liveStats`/`liveTable`/`liveChart`의 `source.nodeId`는 같은 워크스페이스의
-DATABASE·LOG 노드이고, 칸은 **이름**으로 가리킵니다(칸 id가 아닙니다).
-`form` 블록의 `formNodeId`에 폼 노드를 걸면 방문자가 **그 자리에서 신청**합니다 —
-폼을 따로 공개할 필요가 없습니다. 비공개(PRIVATE) 서브트리에 있는 표·폼은 공개
-페이지에서 조용히 빠집니다(일부러 그렇습니다).
+For `liveStats` / `liveTable` / `liveChart`, `source.nodeId` is a DATABASE or LOG node in the
+same workspace and columns are referenced **by name** (not by column id). Point a `form` block's
+`formNodeId` at a form node and visitors submit **right there** — the form does not have to be
+published separately. Tables and forms that live under a PRIVATE subtree are silently dropped
+from a public page, on purpose.
 
-공개는 여느 노드와 같습니다: `POST /v1/nodes/:id/publish` → `rootr.io/p/{slug}`.
+Publishing works like any other node: `POST /v1/nodes/:id/publish` → `rootr.io/p/{slug}`.
 
-#### 프레젠테이션
+### Presentations
 
-프레젠테이션(PRESENTATION)은 전용 MCP 도구(`rootr_create_presentation`,
-`rootr_read_presentation`, `rootr_append_presentation_slides`,
-`rootr_update_presentation_slide`, `rootr_reorder_presentation_slides`,
-`rootr_update_presentation`)로 저작합니다. 슬라이드에 넣을 그림은
-`rootr_generate_image`(문장으로 이미지 생성)와 `rootr_remove_image_background`(배경 지우기)로
-만들 수 있습니다 — 둘 다 AI 크레딧을 씁니다. 아래처럼 **같은 API 키로 REST를 직접
-호출**해도 됩니다 (`x-api-key` 헤더, `docs:write`):
+Decks are authored with `rootr_create_presentation`, `rootr_read_presentation`,
+`rootr_append_presentation_slides`, `rootr_update_presentation_slide`,
+`rootr_reorder_presentation_slides` and `rootr_update_presentation`. Artwork can be produced with
+`rootr_generate_image` (image from a sentence) and `rootr_remove_image_background` — both spend
+AI credits. The same thing works over plain REST with the same API key (`x-api-key`,
+`docs:write`):
 
 ```bash
-# 덱 생성 (슬라이드 포함 가능)
+# create a deck (slides optional)
 curl -X POST "$BASE/workspaces/$WS/presentations" -H "x-api-key: $KEY" \
   -H 'Content-Type: application/json' \
-  -d '{"name":"제안서","slides":[{"id":"SLD-001","kind":"cover","title":"..."}]}'
+  -d '{"name":"Proposal","slides":[{"id":"SLD-001","kind":"cover","title":"..."}]}'
 
-# 슬라이드 부분 수정(머지) / 추가 / 순서 변경
+# patch one slide (merge) / append / reorder
 curl -X PATCH "$BASE/presentations/$ID/slides/SLD-001" -H "x-api-key: $KEY" \
-  -H 'Content-Type: application/json' -d '{"slide":{"notes":"발표 대본"}}'
-curl -X POST "$BASE/presentations/$ID/slides"  -d '{"slides":[...]}' ...
+  -H 'Content-Type: application/json' -d '{"slide":{"notes":"speaker notes"}}'
+curl -X POST "$BASE/presentations/$ID/slides"  -d '{"slides":[]}' ...
 curl -X POST "$BASE/presentations/$ID/reorder" -d '{"order":["SLD-002","SLD-001"]}' ...
 ```
 
-##### 슬라이드에 다이어그램 그려 넣기
+#### Diagrams on a slide
 
-구조도·업무 흐름도·순서도·데이터 흐름도·상태도는 손으로 SVG를 짜지 말고
-`rootr_create_diagram_slide`에 **형식이 정해진 JSON 스펙**을 넘기세요. 서버가
-검증하고 그려서 슬라이드에 바로 꽂습니다 — 화면은 물론 PDF·PPTX 내보내기에도
-그대로 나옵니다. 슬라이드의 `diagram`(mermaid) 필드는 **뷰어가 그리지 않으므로**
-이 도구를 쓰는 것이 유일한 방법입니다.
+For architecture, workflow, sequence, dataflow and lifecycle diagrams, do not hand-write SVG.
+Pass a **typed JSON spec** to `rootr_create_diagram_slide`; the server validates it, renders it,
+and drops it onto the slide — it survives PDF and PPTX export too. A slide's `diagram` (mermaid)
+field is **not rendered by the viewer**, so this tool is the only way.
 
-종류마다 스펙 모양이 다르니 **`rootr_diagram_schema`로 스키마와 예제를 먼저
-받아보세요.** 맞지 않는 스펙은 어느 항목이 왜 틀렸는지와 고치는 법을 달아 거절되니,
-그대로 고쳐 다시 부르면 됩니다.
+Each type has its own spec shape, so **fetch the schema and an example first with
+`rootr_diagram_schema`**. A spec that does not fit is rejected with which field is wrong and how
+to fix it, so you can correct it and call again.
 
 ```bash
-# 스펙 모양 보기 (architecture | workflow | sequence | dataflow | lifecycle)
+# see the spec shape (architecture | workflow | sequence | dataflow | lifecycle)
 curl "$BASE/diagram-types/workflow/schema" -H "x-api-key: $KEY"
 
-# 그려서 슬라이드에 꽂기 (slideId를 주면 그 슬라이드를 다시 그린다)
+# render it onto a slide (pass slideId to redraw an existing slide)
 curl -X POST "$BASE/presentations/$ID/diagram-slides" -H "x-api-key: $KEY" \
   -H 'Content-Type: application/json' \
-  -d '{"type":"workflow","spec":{...},"title":"이슈는 검수를 통과해야만 main에 들어간다",
-       "blocks":[{"heading":"검수가 관문","body":"..."}]}'
+  -d '{"type":"workflow","spec":{},"title":"An issue reaches main only through review",
+       "blocks":[{"heading":"Review is the gate","body":"..."}]}'
 ```
 
-`quality`는 기본 `standard`이고, `showcase`는 손으로 다듬은 대표 그림용 엄격
-기준이라 `standard`가 통과시키는 스펙도 거절합니다. 그림 속 글자는 지식 그래프에
-들어가지 않으니 사실은 `title`·`blocks`·`notes`에도 남기세요.
-
-**고품질 덱을 만들 때는 슬라이드 `html` 필드에 1280×720 완결 HTML을 직접 구워
-넣는 방식을 권장**합니다 — 뷰어가 기본 템플릿 대신 그대로 렌더합니다(완전 자유
-디자인). 필수 규칙(외부 요청 차단이라 전부 인라인, 이미지=data URI 내장, 폰트
-폴백 스택, `<span class="pn">`=페이지번호, 그래프용 텍스트(title/blocks/notes/alt)
-병행 유지)은 **`/llms.txt`의 "Presentations" 섹션**에 정리돼 있습니다 — 저작 전에
-꼭 읽어보세요. AI 이미지 생성은 `POST /v1/workspaces/:ws/images/generate`(AI
-크레딧 차감)를 사용합니다.
-
-모든 도구 설명은 영어(에이전트가 소비하는 스키마)로 작성되어 있고, JSON을 반환하는
-도구는 보기 좋게 들여쓴 JSON 텍스트로 응답합니다. `workspace` 인자를 받는 도구는
-생략 시 `ROOTR_WORKSPACE`/설정파일의 기본 워크스페이스를 사용하며, 그것도 없으면
-명확한 에러를 반환합니다.
+`quality` defaults to `standard`; `showcase` applies the stricter bar meant for hand-tuned hero
+diagrams and will reject specs that `standard` accepts. Text inside a rendered diagram does not
+reach the knowledge graph, so keep the facts in `title`, `blocks` and `notes` as well.
 
-### Claude Code / Claude Desktop에 등록하기
+**For high-quality decks, bake self-contained 1280×720 HTML into the slide's `html` field** — the
+viewer renders it verbatim instead of the default template, giving you a completely free design.
+The rules (inline everything because outbound requests are blocked, images as data URIs, a font
+fallback stack, `<span class="pn">` for page numbers, and keeping the text fields filled so the
+deck still feeds the knowledge graph) are documented in the **"Presentations" section of
+[`/llms.txt`](https://rootr.io/llms.txt)** — read it before authoring. AI image generation uses
+`POST /v1/workspaces/:ws/images/generate` and spends AI credits.
 
-`~/.claude.json`(Claude Code) 또는 Claude Desktop의 MCP 설정 파일에 다음을 추가:
+### Register with Claude Code / Claude Desktop
 
 ```json
 {
   "mcpServers": {
     "rootr": {
-      "command": "node",
-      "args": ["/path/to/rootr/backend/cli/bin/rootr.js", "mcp"],
+      "command": "npx",
+      "args": ["-y", "rootr-cli", "mcp"],
       "env": {
         "ROOTR_API_KEY": "rootr_xxxxxxxxxxxxxxxx",
         "ROOTR_WORKSPACE": "ws_123"
@@ -778,34 +472,48 @@ curl -X POST "$BASE/presentations/$ID/diagram-slides" -H "x-api-key: $KEY" \
 }
 ```
 
-전역 설치했다면 `command`를 `"rootr"`, `args`를 `["mcp"]`로만 써도 됩니다.
-
-## 에러 처리
-
-API가 비-2xx를 반환하면 응답 본문의 `message`(있으면)를 stderr에 출력하고
-exit code 1로 종료합니다. 상황별 힌트:
-
-- `401`/`403` → API 키/워크스페이스 스코프 확인 안내
-- `412` → "문서가 그 사이 변경됨: 다시 읽고 재시도" 안내 (If-Match 불일치)
-- `409` → 서버가 준 이유 메시지를 그대로 표시 (예: edit의 find 불일치/중복)
-
-## 개발 메모
-
-- 의존성: `@modelcontextprotocol/sdk`(MCP 서버), `zod`(도구 입력 스키마).
-  CLI 자체(`bin/rootr.js`, `lib/config.js`, `lib/client.js`, `lib/resolve.js`)는
-  외부 의존성 없이 동작합니다.
-- 빌드 스텝 없음 — 순수 ESM 자바스크립트.
-- 파일 구성:
-  - `bin/rootr.js` — 엔트리포인트, 명령 디스패치
-  - `lib/config.js` — 설정 로드/저장
-  - `lib/client.js` — Rootr REST API 클라이언트(문서/워크스페이스/스캐폴딩/LOG/ask/이슈/웹훅)
-  - `lib/resolve.js` — path/id 타겟 해석 공통 로직
-  - `lib/mcp.js` — MCP stdio 서버 진입점, 도구 모듈 조립
-  - `lib/mcp-tools/shared.js` — MCP 도구 공통 헬퍼(textResult/jsonResult/errorResult/makeClient/requireWorkspace)
-  - `lib/mcp-tools/documents.js` — 문서 도구 6종
-  - `lib/mcp-tools/workspaces.js` — 워크스페이스/스캐폴딩 도구 4종
-  - `lib/mcp-tools/logs.js` — LOG 데이터스토어 도구 5종
-  - `lib/mcp-tools/ask.js` — RCA ask 도구 1종
-  - `lib/mcp-tools/issues.js` — 이슈 트래커 도구 6종
-  - `lib/mcp-tools/webhooks.js` — 웹훅 도구 3종
-  - `lib/mcp-tools/misc.js` — 문서버전/삭제 도구 2종
+With a global install, use `"command": "rootr"` and `"args": ["mcp"]`. From a clone, point
+`command` at `node` and `args` at `["/path/to/rootr-cli/bin/rootr.js", "mcp"]`.
+
+## Errors
+
+On a non-2xx response the CLI prints the API's `message` to stderr and exits 1, with hints:
+
+- `401` / `403` — check the API key and workspace scopes
+- `412` — document changed since you read it; read again and retry (If-Match mismatch)
+- `409` — the server's reason is shown verbatim (e.g. `edit` found no unique match)
+- `429` — usage limit reached; the message carries the reset time and an upgrade link
+
+## Development
+
+- Dependencies: `@modelcontextprotocol/sdk` (MCP server) and `zod` (tool input schemas). The CLI
+  itself (`bin/rootr.js`, `lib/config.js`, `lib/client.js`, `lib/resolve.js`) has none.
+- No build step — plain ESM JavaScript.
+
+```
+bin/rootr.js            entry point, command dispatch
+lib/config.js           config load/save
+lib/credentials.js      API key / workspace resolution
+lib/context.js          per-call request context
+lib/client.js           Rootr REST client
+lib/resolve.js          path/id target resolution
+lib/mcp.js              MCP stdio server, assembles the tool modules
+lib/mcp-tools/*.js      one module per tool group (shared, documents, pages, workspaces,
+                        databases, spreadsheets, whiteboards, forms, presentations,
+                        recordings, signed, templates, attachments, public, memory,
+                        logs, issues, crm, webhooks, ask, feedback, misc)
+```
+
+Smoke-test the MCP server without any credentials — it must start and list its tools:
+
+```bash
+printf '%s\n' \
+  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"t","version":"1"}}}' \
+  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
+  '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' \
+  | node bin/rootr.js mcp
+```
+
+## License
+
+MIT — see [`LICENSE`](LICENSE).