rootr-cli 0.24.0 → 0.26.0

package/README.ko.md

@@ -307,20 +307,30 @@ rootr sign ledger          # 워크스페이스 원장 전체 재계산
 
 ### 문서 보내기 · 문서함 (send · mail)
 
-폴더만 빼고 어떤 노드든 이메일 1~20명에게 **보낼 때의 복사본**으로 보낼 수 있습니다. 담기는 내용은
-공개 페이지와 같아서 사람·첨부·관계 칸은 나가지 않습니다. 받는 사람은 메일 링크로 **루터 계정 없이**
-열고, 그 이메일에 루터 계정이 있거나 나중에 가입하면 받은 문서함에도 그대로 있습니다. 보낸 뒤 원본을
-고치거나 지워도 받은 문서는 그대로입니다. 보내려면 그 노드에 쓰기(WRITE) 권한이 있어야 합니다(공유와 같은 문턱).
+어떤 노드든(폴더 포함) 이메일 1~20명에게 보낼 수 있습니다. **복사본이 아니라 원본 그 문서**를 그 이메일에
+열어 주는 것입니다 — `--access read`(보기, 기본) · `comment`(댓글) · `write`(편집). 받는 사람은 언제나 최신
+내용을 보고, 편집을 받았으면 원본을 직접 고칩니다. 그 이메일(인증된)의 루터 계정은 우리 워크스페이스 구성원이
+아니어도 문서함에서 그 문서만 엽니다(트리·구성원·검색은 안 보임). 계정이 없으면 메일 링크에서 받은 이메일을
+넣어야 읽기 전용으로 보입니다. 보내려면 그 노드에 구성원으로서 쓰기(WRITE) 권한이 있어야 하고(공유와 같은
+문턱), 내 권한까지만 줄 수 있습니다.
 
 ```bash
-rootr send "/보고서/3분기 실적" --to partner@example.com,cfo@example.com --message "말씀드린 자료입니다"
+rootr send "/보고서/3분기 실적" --to partner@example.com,cfo@example.com --access comment --message "말씀드린 자료입니다"
 rootr mail                 # 받은 문서 (안 읽은 수 함께)
-rootr mail sent            # 보낸 문서 — 읽었는지, 메일 실패
-rootr mail show <id>       # 열기 (문서는 마크다운 본문, 그 밖은 --json 으로 전부)
-rootr mail revoke <id>     # 회수 — 받는 쪽에서 본문이 안 보이고 링크는 410
+rootr mail sent            # 보낸 문서 — 권한·읽었는지·메일 실패
+rootr mail show <id>       # 지금 내용 (문서는 마크다운 본문, 그 밖은 --json 으로 전부, 폴더 안은 --node <아래 id>)
+rootr mail access <id> write   # 받는 사람 권한 바꾸기
+rootr mail revoke <id>     # 회수 — 받는 사람이 바로 못 열고 링크는 410
 rootr mail hide <id>       # 내 문서함에서만 지우기
+rootr mail webhook add https://example.com/hooks/rootr   # 내 계정 웹훅: doc_mail.received / revoked / read
+rootr mail webhook list | rm <id> | test <id>
 ```
 
+다른 명령을 쓰고 나면 새로 받은 문서가 있을 때 stderr 로 한 줄이 나옵니다(`📬 받은 문서 2건 — … · rootr mail`).
+stdout 과 `--json` 출력은 그대로입니다. 끄려면 `ROOTR_MAIL_NOTICE=0`. MCP 서버는 같은 소식을 아무 도구 응답 끝에
+키마다 한 번 붙입니다. 웹훅 요청은 서명되어 있습니다 — `add` 때 한 번 보이는 비밀값으로
+`X-Rootr-Signature: sha256=HMAC_SHA256(secret, 원문)` 을 확인하세요. 몸통에는 문서 내용이 없습니다(`apiUrl` 을 부르세요).
+
 ### 제보 보내기 (feedback)
 
 ```bash
@@ -368,7 +378,7 @@ rootr memory forget <id>                         # 폐기(--hard면 행 삭제)
 
 ## MCP 서버로 사용하기
 
-`rootr mcp`는 stdio로 MCP(Model Context Protocol) 서버를 구동합니다. 제공 도구 197종:
+`rootr mcp`는 stdio로 MCP(Model Context Protocol) 서버를 구동합니다. 제공 도구 202종:
 
 노드를 가리키는 인자(`target`, `databaseId`, `spreadsheetId`, `formId`, `crmId`, `trackerId`,
 `recordingId`, `presentationId`, `whiteboardId`, `logId`, `parentId` 등)는 **노드 id와 경로를 모두**
@@ -520,6 +530,10 @@ rootr db buttons <표> --file buttons.json  # 목록 통째로 저장(남길 것
 rootr db button-run <표> <버튼id>           # 한 번 누르기 (--rows id,id 로 고른 행 지정)
 rootr db automations <표> --file rules.json # 자동 규칙 — 사람이 안 눌러도 도는 것
 rootr db view <표> <뷰> --scale year       # 달력 보기를 주·달·해 중에서
+rootr db view <표> <뷰> --density compact --freeze 1   # 촘촘한 줄 · 왼쪽 첫 칸 고정
+rootr db column <표> 지원일 --time off --range off      # 시간·기간 없이 날짜 하나만
+rootr db column <표> 마감일 --overdue on                # 지난 날짜를 빨갛게(기본은 꺼짐)
+rootr db column <표> 특이사항 --wrap on --align center  # 긴 글 줄바꿈 · 가운데 정렬
 ```
 
 ```json
@@ -651,7 +665,7 @@ rootr db view <표> <뷰> --scale year       # 달력 보기를 주·달·해
 
 | 도구 | 설명 |
 |---|---|
-| `rootr_publish_node` | **아무 노드나** 공개 — 문서·표·폼·시트·화이트보드·덱, 하위까지 |
+| `rootr_publish_node` | **아무 노드나** 공개 — 문서·표·폼·시트·화이트보드·덱·페이지, 하위까지. **페이지(PAGE)는 Team 플랜부터**(무료는 403 `PLAN_UPGRADE_REQUIRED`, 하위 포함 시 페이지는 건너뛰고 개수를 알려 줌) |
 | `rootr_set_node_public` | 이미 공개한 것의 설정 변경(하위 포함 여부·검색 노출·만료) |
 | `rootr_node_public_status` | 지금 공개돼 있는지, 주소는 무엇인지 |
 | `rootr_publish_document` | 문서 전용 발행(구형 — 새로 짤 때는 `rootr_publish_node`) |
@@ -819,10 +833,15 @@ rootr db view <표> <뷰> --scale year       # 달력 보기를 주·달·해
 
 | 도구 | 설명 |
 |---|---|
-| `rootr_send_document` | 노드 하나를 이메일 1~20명에게 보낼 때의 복사본으로 보내기 (계정 없어도 메일 링크로 열림) |
-| `rootr_list_doc_mail` | 내 문서함 — `box`: inbox(받은, 기본) / sent(보낸), 안 읽은 수 함께 |
-| `rootr_read_doc_mail` | 한 통 열기 — 본문(`payload`), 받은 것은 읽음 처리, 회수된 것은 본문 없음 |
-| `rootr_revoke_doc_mail` | 보낸 문서 회수 (보낸 사람만) |
+| `rootr_send_document` | 노드 하나를 이메일 1~20명에게 보내기 — 복사본이 아니라 원본을 `access`(read 보기·comment 댓글·write 편집)만큼 열어 줌 |
+| `rootr_list_doc_mail` | 내 문서함 — `box`: inbox(받은, 기본) / sent(보낸), 안 읽은 수·권한·원본 상태 함께 |
+| `rootr_read_doc_mail` | 한 통 열기 — 원본의 지금 내용(읽기 전용)·권한·원본 주소, 폴더면 `node` 로 아래 것, 받은 것은 읽음 처리 |
+| `rootr_set_doc_mail_access` | 보낸 문서의 받는 사람 권한 바꾸기 (보낸 사람만, 내 권한까지) |
+| `rootr_revoke_doc_mail` | 보낸 문서 회수 — 받는 사람이 바로 못 연다 (보낸 사람만) |
+| `rootr_add_doc_mail_webhook` | 내 계정 받은 문서 웹훅 만들기 — doc_mail.received·revoked·read, HMAC 서명, 비밀값은 한 번만 |
+| `rootr_list_doc_mail_webhooks` | 내 받은 문서 웹훅 목록(마지막 전달 상태) |
+| `rootr_remove_doc_mail_webhook` | 내 받은 문서 웹훅 지우기 |
+| `rootr_test_doc_mail_webhook` | 시험 전송(doc_mail.test) 후 전달 결과 |
 
 문서함은 워크스페이스가 아니라 **사람(이메일)**에 붙습니다. 사람 없는 워크스페이스 키(원격 커넥터)는
 그 키를 만든 구성원으로 동작합니다.
@@ -844,11 +863,20 @@ rootr db view <표> <뷰> --scale year       # 달력 보기를 주·달·해
 `rootr_append_page_blocks`, `rootr_update_page`, `rootr_update_page_block`,
 `rootr_read_page_live_data`)로 저작합니다.
 
-HTML을 짜는 것이 아니라 **정해진 블록 15종을 골라 쌓습니다** — `hero` `text`
+HTML을 짜는 것이 아니라 **정해진 블록 16종을 골라 쌓습니다** — `hero` `text`
 `features` `gallery` `pricing` `testimonials` `faq` `timeline` `cta` `footer` +
 표에서 값을 끌어오는 `liveStats` `liveTable` `liveChart` + 신청을 받는 `form` +
 방문자가 시간을 잡는 `booking`(`{bookingNodeId, headline?, type?}` — 예약을 켜고 공개한 표의 노드 id) +
-자유 블록 `custom`.
+모션그래픽 동영상 `video` + 자유 블록 `custom`.
+
+**같은 페이지 안 이동** — 버튼·링크의 `target`에 `{"kind":"block","blockId":"booking"}`을 주면 새 탭 없이
+그 블록까지 부드럽게 내려갑니다(인스타그램 앱 안 브라우저에서 사람을 잃지 않는 광고 랜딩용). 가리킨 블록이
+페이지에 없으면 400이라, 만들 때 그 블록에 `id`를 직접 붙여 둡니다. `text` 본문에서는 `[글](#블록id)`.
+
+**동영상(Team 플랜)** — `hero.background`에 `{"kind":"video","attachmentId":"…","posterAttachmentId":"…"}`,
+동영상 블록은 `{attachmentId, posterAttachmentId?, caption?, aspect?: "16:9"|"9:16"|"1:1"|"4:5", bleed?}`.
+둘 다 소리 없이 자동 재생·반복·컨트롤 없음이고, 동작 줄이기를 켠 방문자에게는 포스터 그림만 보입니다.
+히어로 동영상에는 `portraitAttachmentId`·`portraitPosterAttachmentId`(휴대폰 세로판)를 더할 수 있습니다 — 세로 화면은 그 판을, 아니면 기본판을 하나만 내려받습니다.
 
 **랜딩 페이지**용으로 두 블록은 가운데 본문 기둥을 벗어나 화면 폭 전체를 쓸 수 있습니다.
 `hero`에 `size: "screen"`을 주면 화면 한 장을 채우는 큰 제목(화면 폭 전체·화면 높이·큰 글자)이 되고,
@@ -899,6 +927,10 @@ DATABASE·SPREADSHEET·LOG 노드이고, 칸은 **이름**으로 가리킵니다
 페이지에서 조용히 빠집니다(일부러 그렇습니다).
 
 공개는 여느 노드와 같습니다: `POST /v1/nodes/:id/publish` → `rootr.io/p/{slug}`.
+단 **페이지를 웹에 게시하는 것은 Team 플랜부터**입니다 — 무료 워크스페이스는 403 `PLAN_UPGRADE_REQUIRED`
+(아무것도 바뀌지 않음). 무료에서도 페이지를 만들고 편집하고 워크스페이스 안에서 보는 것은 그대로 됩니다.
+Team 에서 공개한 뒤 무료로 내려가면 공개 설정은 남아 있지만 방문자에게는 "게시되어 있지 않습니다" 화면이
+나가고, 다시 Team 으로 올리면 같은 주소가 다시 발행하지 않아도 열립니다.
 
 #### 프레젠테이션
 

package/README.md

@@ -11,7 +11,7 @@ citations back to the exact paragraph.
 *(한국어 문서: [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, **197 tools** (see [MCP tools](#mcp-tools))
+- `rootr mcp` — stdio MCP server, **202 tools** (see [MCP tools](#mcp-tools))
 
 Plain Node.js ESM, no build step. Node 18+ (uses the built-in `fetch`).
 
@@ -201,10 +201,18 @@ rootr db rows-rm  /projects/tasks --ids r1,r2 --yes
 rootr db duplicates /hr/applicants --row r9            # same person (dedupe column) + latest linked history
 rootr db merge /hr/applicants r9 --into r1             # merge a duplicate into the existing row
 rootr db keep-duplicate /hr/applicants r9 --from r1    # keep as a new row, link both
+rootr db rename-col /hr/applicants "대처-클레임" "대처-청소 후 사진 제출" --dry  # what follows a rename (formulas, {col} templates, rollups, forms, pages); drop --dry to rename
+rootr db carry-over /hr/applicants r9                  # re-application: copy the latest earlier row into r9 (earlier row untouched)
+rootr db column-set /hr/applicants Phone --json '{"dedupe":true,"dedupeCarry":{"auto":true,"exclude":["Applied on"],"mark":{"Re-applied":true}}}'
+rootr db column-set /hr/applicants Phone --json '{"validate":{"kind":"mobile_kr","mode":"block"}}'   # also date · birthdate · range, mode warn
+rootr db rule-violations /hr/applicants                # existing values that break a validate rule (nothing changed)
 rootr db history /hr/applicants --row r1               # who changed what, when, how
 rootr db restore /hr/applicants --at 2026-10-15T09:00:00+09:00 --yes  # rows + columns/views back to that time
 rootr db view /projects/tasks Calendar --scale month  # views: table, board, calendar, timeline
 rootr db view /hr/applicants Board --cards "Interview date,Phone"  # fields shown on board cards
+rootr db view /hr/applicants Table --density compact --freeze 1  # compact rows, keep the first column fixed
+rootr db column /hr/applicants "Applied on" --overdue off --time off --range off  # plain single date, no red
+rootr db column /hr/applicants Notes --wrap on --align center     # wrap long text, center it
 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
@@ -269,7 +277,15 @@ rootr publish /handbook --status                # is it public, at what URL, chi
 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
+```
+
+Every node type publishes on the Free plan **except PAGE** (the block-built web page): publishing a
+page to the web needs the **Team plan**. On Free, `rootr publish <page>` fails with
+`PLAN_UPGRADE_REQUIRED` and nothing changes; `--children` skips pages underneath and says how many.
+A page published on Team stays saved if the workspace later drops to Free — visitors see a
+"not published" screen until it is upgraded again, and `--status` says so.
 
+```bash
 rootr access /handbook --private                # or --public / --inherit
 rootr access /handbook --grant <userId> --level WRITE
 rootr access /handbook --revoke <userId>
@@ -329,21 +345,32 @@ regulations require both the original and the trace of the change to remain visi
 
 ### Sending a document to someone (mailbox)
 
-Any node except a folder can be emailed to 1–20 addresses as a **copy taken at send time** — the
-same content a public page shows, so person / attachment / relation columns never go out. The
-recipient opens it from the email link **without a Rootr account**; if that address has (or later
-gets) a Rootr account, it is also in their inbox. Editing or deleting the original afterwards does
-not change what they received. Sending needs WRITE on the node, the same bar as sharing.
+Any node — a folder too — can be sent to 1–20 email addresses. It is **not a copy**: the address
+gets access to the **original** at `--access read` (view, default) · `comment` · `write` (edit), so
+they always see the latest version and, with `write`, edit the original itself. A Rootr account on
+that (verified) email opens it from its inbox even if it is not in your workspace — it sees that
+node only, never your tree, members or search. Without an account the email link asks for the
+address and then shows it read-only. Sending needs WRITE on the node as a member (the same bar as
+sharing); you can give at most your own level.
 
 ```bash
-rootr send "/reports/Q3 numbers" --to partner@example.com,cfo@example.com --message "As discussed"
+rootr send "/reports/Q3 numbers" --to partner@example.com,cfo@example.com --access comment --message "As discussed"
 rootr mail                 # received (with the unread count)
-rootr mail sent            # what you sent — read or not, email failures
-rootr mail show <id>       # open it (a document prints its markdown; --json for any type)
-rootr mail revoke <id>     # withdraw: the recipient no longer sees the content, the link answers 410
+rootr mail sent            # what you sent — access, read or not, email failures
+rootr mail show <id>       # the current content (a document prints its markdown; --json for any type; --node <child> inside a folder)
+rootr mail access <id> write   # change what the recipient can do
+rootr mail revoke <id>     # withdraw: the recipient loses access at once, the link answers 410
 rootr mail hide <id>       # remove from your own mailbox only
+rootr mail webhook add https://example.com/hooks/rootr   # your own webhook: doc_mail.received / revoked / read
+rootr mail webhook list | rm <id> | test <id>
 ```
 
+After any other command, newly received documents print one line to stderr
+(`📬 2 new documents received — … · rootr mail`); stdout and `--json` stay clean. Turn it off with
+`ROOTR_MAIL_NOTICE=0`. The MCP server appends the same news to the end of any tool result, once
+per key. Webhook requests are signed: verify `X-Rootr-Signature: sha256=HMAC_SHA256(secret, raw body)`
+with the secret shown once at `add`. The body never contains the document — GET its `apiUrl`.
+
 ### Team memory
 
 ```bash
@@ -425,7 +452,7 @@ is refused and says when the grace was used.
 
 ## MCP tools
 
-`rootr mcp` speaks MCP over stdio. 197 tools:
+`rootr mcp` speaks MCP over stdio. 202 tools:
 
 | Group | Count | Tools |
 |---|---|---|
@@ -487,11 +514,23 @@ signed-document, issue, CRM and LOG tools need `docs:read` / `docs:write`; `root
 ### 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 **15 predefined block types** — `hero`, `text`,
+a sign-up. You do not write HTML: you stack **16 predefined block types** — `hero`, `text`,
 `features`, `gallery`, `pricing`, `testimonials`, `faq`, `timeline`, `cta`, `footer`, the
 table-backed `liveStats`, `liveTable`, `liveChart`, the `form` block, the `booking` block
 (a visitor scheduling calendar: `{bookingNodeId, headline?, type?}` — the node id of a published
-table with visitor booking on) — plus the free-form `custom`.
+table with visitor booking on), the `video` block (a looping motion-graphic clip) — plus the free-form `custom`.
+
+**Same-page links.** A button or link `target` can be `{"kind":"block","blockId":"booking"}` — it
+jumps to that block on the same page (smooth scroll, same tab; ideal for a hero "Book now" button
+on an ad landing page opened in an in-app browser). The block must exist on the page (else 400),
+so give it an explicit `id`. In a `text` block, `[label](#<blockId>)` does the same.
+
+**Videos (Team plan).** `hero.background` can be `{"kind":"video","attachmentId":"…","posterAttachmentId":"…"}`
+and the `video` block is `{attachmentId, posterAttachmentId?, caption?, aspect?: "16:9"|"9:16"|"1:1"|"4:5", bleed?}`.
+Both autoplay muted and looped with no controls; the poster shows for reduced-motion visitors. A hero video can add
+`portraitAttachmentId` / `portraitPosterAttachmentId` — a vertical cut that portrait phone screens play instead (only one file is downloaded). Upload the
+mp4 with `POST /v1/attachments/upload?workspaceId=…&nodeId=<page>&mimeType=video/mp4` (body = bytes,
+`Content-Type: application/octet-stream`).
 
 For a **landing page**, two options let a block use the whole page width instead of the centred
 text column: `hero` with `size: "screen"` is a full-screen hero (edge to edge, one viewport tall,
@@ -543,7 +582,8 @@ takes `width: half | third | twoThirds` so a page becomes a **live dashboard**
 published separately. Tables and forms that live under a PRIVATE subtree are silently dropped
 from a public page, on purpose.
 
-Publishing works like any other node: `POST /v1/nodes/:id/publish` → `rootr.io/p/{slug}`.
+Publishing works like any other node: `POST /v1/nodes/:id/publish` → `rootr.io/p/{slug}` —
+**Team plan and up** for pages (Free → `403 PLAN_UPGRADE_REQUIRED`; pages still work inside the workspace).
 
 ### Embedding a table inside a document