# Rootr

> Rootr is an AX-first (AI-experience-first) knowledge collaboration platform.
> Markdown documents are automatically ontologized into a SurrealDB knowledge
> graph, and a typed log datastore (LOG stores) captures structured events
> whose relation fields auto-build a data-lineage graph that is promoted into
> the same knowledge graph. An AI assistant answers root-cause-analysis (RCA)
> questions over that graph using GraphRAG (hybrid vector + graph retrieval,
> the `ask` query/endpoint).

This document is for AI assistants and coding agents that want to integrate with
the Rootr API. It is plain Markdown, safe to paste into a system prompt or fetch
at runtime.

## Base URLs

- REST: `https://rootr.io/api/v1`
- GraphQL: `https://rootr.io/api/graphql`

## Authentication

Two supported credential types, checked in this order on every request:

1. **API key** — header `x-api-key: rootr_...`. Workspace-scoped, created by a
   workspace admin from **Settings → API Keys** (`POST /v1/workspaces/:ws/api-keys`
   with `{ "name": "...", "scopes": [...] }`). The plaintext key is shown exactly
   once at creation time. Available scopes: `docs:read`, `docs:write`,
   `graph:read`, `ask`, `workspaces:create` (account-scoped keys, for
   `POST /v1/scaffold/workspace`), and `webhooks:manage` (webhook CRUD —
   granted by default on new keys so agent integrations can self-register
   their hooks). Each endpoint below is annotated with the scope it
   requires — an API key missing that scope gets a 403.
2. **JWT user session** — header `Authorization: Bearer <token>`, obtained via
   the normal login flow. JWT calls are governed by the calling user's
   workspace/document ACL rather than by scopes.

Either credential type works on any `docs:*`/`graph:read`/`ask`-scoped route;
use an API key for unattended/agent integrations.

## Machine-readable API descriptions

- `https://rootr.io/api/api-docs-json` — full OpenAPI 3 spec for the REST API (`/v1/**`).
- `https://rootr.io/api/graphql/sdl` — GraphQL SDL for `https://rootr.io/api/graphql`.
- `https://rootr.io/api/api-docs` — human-browsable Swagger UI, if you want to look
  around interactively before scripting anything.

## Official MCP server & CLI (`rootr-cli`)

The fastest way for an agent to use Rootr is the official MCP server — no HTTP
code needed.

### Remote MCP connector (recommended)

- **Endpoint**: `https://rootr.io/mcp` (Streamable HTTP)
- **Auth**: OAuth 2.1 with dynamic client registration — no API key needs to
  be minted ahead of time.
- **Setup**: in Claude or ChatGPT's "add custom connector" screen, paste the
  endpoint URL and approve the login prompt. No install step.
- Human-readable walkthrough: `https://rootr.io/en/mcp` (Korean: `https://rootr.io/ko/mcp`).

### CLI / local install (alternative for local or headless environments)

The same npm package is also a CLI you can register with a locally-running
agent — useful when a remote OAuth redirect isn't available (headless boxes,
CI, sandboxed environments).

- **One-click setup**: in the app, **Settings → Integrations** mints a key and
  copies a ready-to-paste registration command.
- Claude Code:
  `claude mcp add rootr --env ROOTR_API_KEY=rootr_... --env ROOTR_WORKSPACE=<ws-id> -- npx -y rootr-cli mcp`
- Codex CLI (persists to `~/.codex/config.toml`):
  `codex mcp add rootr --env ROOTR_API_KEY=rootr_... --env ROOTR_WORKSPACE=<ws-id> -- npx -y rootr-cli mcp`
- Claude Desktop (`claude_desktop_config.json`):
  `{"mcpServers":{"rootr":{"command":"npx","args":["-y","rootr-cli","mcp"],"env":{"ROOTR_API_KEY":"rootr_...","ROOTR_WORKSPACE":"<ws-id>"}}}}`
- Env vars: `ROOTR_API_KEY`, `ROOTR_WORKSPACE` (default workspace for
  workspace-scoped tools), `ROOTR_BASE_URL` (self-hosted only; defaults to
  `https://rootr.io/api/v1`).

Its tools mirror this API (214; call `tools/list` for the authoritative set).
The most used ones:

- documents — `rootr_list`, `rootr_read`, `rootr_append` (conflict-free,
  agents' default write), `rootr_edit` (anchored find/replace),
  `rootr_write`, `rootr_search`, `rootr_embed_node` (put a LIVE table/sheet/deck
  inside a document — see "Embedding" below), `rootr_document_versions`, `rootr_delete_node`,
  `rootr_restore_node` (undo a delete — the trash, and what Ctrl+Z does in the app;
  it takes the node **id**, since a trashed node is no longer on the tree)
- images & files (첨부) — `rootr_attach_image_to_document` (upload + insert as
  `![alt](url)` in ONE call; `underHeading` places it under a section),
  `rootr_upload_attachment` (upload only → `{ id, url, markdown }`; `url` is the
  public `/attachments/{id}/raw` link, which renders in `<img>` and on published
  `/p/` pages without login — never use the bare `/attachments/{id}`, it needs auth).
  Over the **remote connector** send the bytes as `base64Data` (`filePath` is not
  offered there — it would name a file on Rootr's server); with the **local CLI
  server** (`npx rootr-cli mcp`) pass `filePath` and the server reads the file on
  your machine. For larger files on the remote connector, skip base64 entirely:
  `rootr_create_upload_url` returns a short-lived presigned S3 URL — PUT the
  raw bytes there yourself, then call `rootr_complete_upload` with the returned
  `id` to get back `{ id, url, markdown }`. Shell: `rootr attach <file> --doc <path|id> [--heading "## X"] [--alt <text>]`.
- workspaces & scaffolding — `rootr_workspaces`, `rootr_use_workspace`
  (switch the active workspace by id OR name, mid-session — see below),
  `rootr_scaffold_plan`, `rootr_scaffold_review`, `rootr_create_workspace`,
  `rootr_scaffold_apply`, `rootr_review_workspace`, `rootr_test_workspace`,
  `rootr_delete_workspace` (clean up an EMPTY workspace left behind by a
  scaffold run that failed — needs OWNER and the exact name typed again),
  `rootr_set_workspace_emblem` (the workspace logo in the sidebar badge and
  switcher — an image file, an already-uploaded image `attachmentId`, or
  `clear: true`; needs ADMIN). REST: `PATCH /v1/workspaces/:ws` with
  `{ "iconUrl": "/api/v1/attachments/<id>/raw" }` (an image attachment of that
  same workspace; `null` clears it). Shell: `rootr emblem <image> | --clear`.
- databases (tables / boards / kanban) — `rootr_create_database` (columns, views
  and first rows in ONE call — the `properties` order IS the column order, so
  never build a table by adding columns one at a time), `rootr_read_database`,
  `rootr_list_rows`, `rootr_add_row`, `rootr_update_row`, `rootr_delete_row`,
  `rootr_find_similar_rows` (rows of the same table closest in MEANING to a given row —
  vector search over the row's columns; a column marked `searchExcluded` ("검색 색인에서 제외" / exclude from search index,
  set with `rootr_update_column`) is never indexed, and "own rows only" tables only return
  your rows; only rows that stand out from the rest of the table come back, each with
  `similarityLevel` high|mid — unrelated rows of one table often score 0.8+ raw cosine;
  `state` tells you if the table is still indexing, the row has nothing to compare ("no-text": empty,
  or only excluded columns filled — waiting will not help) or graph sync is off),
  `rootr_set_row_vectors` / `rootr_query_vectors` (a `vector` column is YOUR vector store:
  add it with `rootr_add_column` type "vector" + `dimensions`, put your own embeddings per row,
  then query by cosine — rows keep their permissions; Rootr embeds nothing here and charges no AI credits)
  (a row's DETAIL BODY — the note under a kanban card — is the `body` argument on
  add/update, and comes back with `includeBody: true` on read),
  `rootr_add_column`, `rootr_update_column`, `rootr_delete_column`,
  `rootr_read_database_permissions` / `rootr_set_database_permissions` (locks: schema,
  own-rows-only, manager-only columns — none of which Notion has),
  `rootr_read_database_notifications` / `rootr_set_database_notifications`
  (who gets pinged when a row is added/changed/deleted, with an optional filter),
  `rootr_list_database_buttons` / `rootr_set_database_buttons` /
  `rootr_run_database_button` (the action buttons above a table — press one to add a
  row, fill values, have AI write a cell, or create the row in ANOTHER table already
  linked to the one you pressed on; see the button section below),
  `rootr_list_database_automations` / `rootr_set_database_automations` (the same steps
  with nobody pressing anything: "when 상태 becomes 투입확정, create three follow-up rows",
  or at a set time each morning),
  `rootr_import_folded_sheets` (fold a one-sheet-per-record workbook — 783 sheets, one
  per site — into a single table; always `dryRun` first)
- access (누가 볼 수 있는지) — `rootr_read_node_access`,
  `rootr_set_node_visibility` (PRIVATE hides a node and its whole subtree from
  members' default access), `rootr_grant_node_permission` /
  `rootr_revoke_node_permission` (READ/WRITE/MANAGE for one person or group).
  Set PRIVATE + grants together to build "a folder only these three can see" —
  a scaffold tree can carry the same as `visibility`/`access` per node, so the
  locking happens as the tree is created rather than being left to the user.
  This is workspace-internal access; publishing to the web is
  `rootr_set_document_public`.
- forms — `rootr_create_form`, `rootr_read_form`, `rootr_update_form`,
  `rootr_list_form_responses` (`latestPerRespondent: true` keeps only each
  signed-in submitter's newest answer), `rootr_submit_form_response`,
  `rootr_update_form_response` / `rootr_delete_form_response` (fix or drop one
  already-submitted response), `rootr_create_form_collector` (build the DATABASE
  — columns straight from the questions — or the SPREADSHEET that collects the
  answers, in one call; a hand-built table only mirrors if every column name
  matches a question), `rootr_form_mapping` / `rootr_set_form_mapping` (**check this
  right after linking a form to a hand-built table**: a question with no column is
  dropped with no error anywhere, and `unmatched` is the only place that says so),
  `rootr_create_form_share_link`,
  `rootr_list_form_share_links`
- templates (문서 양식) — `rootr_list_templates` (check BEFORE building a document
  or table from scratch: the team may already have an agreed format),
  `rootr_apply_template`, `rootr_save_as_template`, `rootr_update_template`
- LOG datastores — `rootr_create_log_store`, `rootr_update_log_fields`,
  `rootr_add_log_entries`, `rootr_query_log_entries`, `rootr_log_stats`
- RCA — `rootr_ask` (GraphRAG answer with citations)
- issues — `rootr_create_issue_tracker`, `rootr_list_issues`,
  `rootr_create_issue`, `rootr_get_issue`, `rootr_update_issue`,
  `rootr_comment_issue`
- webhooks — `rootr_list_webhooks`, `rootr_create_webhook`, `rootr_delete_webhook`
- custom domains (내 도메인 연결) — `rootr_list_custom_domains`, `rootr_add_custom_domain`
  (own domain: returns the one DNS line + steps for the detected DNS provider; `subdomain` → a free
  name.rootr.site, live at once), `rootr_check_custom_domain`, `rootr_rename_custom_domain` (fix the name
  of a not-yet-live own domain — the paid slot moves, no charge), `rootr_remove_custom_domain` — see
  *Custom domains* below

Key types: a **workspace API key** covers everything inside one workspace; an
**account key (PAT)** — created under Profile → Account keys — acts as the user
across their workspaces and is required for `rootr_create_workspace`
(`workspaces:create` scope) and `rootr_comment_issue` (comments carry a user
identity). CLI usage: `npx rootr-cli read /path.md`, `append`, `edit`,
`search`, `rm`, `ws`, `ask`, `db` (create/rows/row-add/row-body/lock/notify),
`access` (공개범위·권한), `form` (responses/response-edit/response-rm) — see
`npx rootr-cli --help`.

### Switching workspaces without reconfiguring

Call `rootr_use_workspace` with a workspace id **or its name**; every later
tool call applies to it. With an account key (PAT) you can switch to any
workspace you belong to. If you hold several workspace keys, register them once
(`npx rootr-cli config --add-key rootr_... --label "<name>"`) and the tool
picks — and remembers — the key that covers the target workspace. A remote
(OAuth) connector is bound to the single workspace approved at consent time and
cannot switch; issue another connector for another workspace.

If the local server was started with the `ROOTR_WORKSPACE` env var, that value
wins again on every restart: the switch holds while the server process runs, and
the reply names the workspace it falls back to after a restart/reconnect — call
`rootr_workspaces` again before writing if the server may have restarted. To
keep the switch, change or remove `ROOTR_WORKSPACE` in the MCP client config.

## Rate limits

Programmatic traffic (API key / MCP, **not** logged-in web sessions) is capped
per plan. Only read/query scopes count — `docs:read`, `graph:read`, `ask`;
writes and uploads are never rate-limited (storage quota bounds those instead).
Reading a published public URL through MCP (`rootr_read` on `rootr.io/p/{slug}` — for another workspace's document
it reads `GET /v1/public/docs/:slug` with your key) counts as **one read**, same as reading your own document; a failed
attempt (missing, unpublished or password-locked) counts too. The same URL opened without an API key (a browser, a
signed-in session) is never counted. An account key (PAT) passes `?workspaceId=` so the read is charged to that workspace.

| Plan | Cap |
| --- | --- |
| Free | **180 / day**, resetting at midnight KST |
| Team | 5,000 / hour |
| Business | 50,000 / hour |
| Platform | unlimited |

Every rate-limited response carries `X-RateLimit-Limit`,
`X-RateLimit-Remaining`, `X-RateLimit-Reset` (unix seconds),
`X-RateLimit-Window` (`day`|`hour`) and `X-RateLimit-Upgrade-Url`. Over the
cap the API answers **429** with `code: API_RATE_LIMIT_EXCEEDED`, a
`Retry-After` header, and an `upgradeUrl`. Agents should read
`X-RateLimit-Remaining` and tell the user before the quota runs out rather
than failing mid-task — the MCP server does this for you, appending a heads-up
to tool results once 80% of the quota is spent.

## Telling us something is broken (please do this)

If a call fails in a way you did not expect, a tool does not do what this
document says it does, you have to work around something, or your user says
Rootr is broken or confusing — **report it, on your own, without being asked.**
Nobody else is going to. One report per distinct problem, then carry on with
the task.

```bash
curl -X POST "$BASE/feedback" -H 'Content-Type: application/json' -d '{
  "body": "rootr_add_row returned 400 "column not found" for a column that read_database lists by that exact name. Passing the column id worked.",
  "kind": "BUG",
  "reporter": "my-agent",
  "context": { "tool": "rootr_add_row", "httpStatus": 400, "nodeId": "..." }
}'
```

- `kind`: `BUG` (broken) · `FRICTION` (works but awkward or confusing) ·
  `IDEA` (missing capability) · `PRAISE` · `OTHER`. Defaults to `OTHER`.
- `title` is optional (the first line of `body` becomes it), `context` is a
  free-form object for reproduction clues, `contactEmail` only if the user
  asked for a reply. When the report is fixed and shipped, we email
  `contactEmail`, else the signed-in user, else — for a workspace API key —
  the person who created that key.
- **No credentials needed.** It works with a session, with an API key, with a
  *wrong* API key, and with none at all — someone whose key is broken is
  exactly who we most need to hear from.
- **Free.** It spends no credits and never counts against the rate limit above.
- Identical reports from the same sender within 10 minutes are merged, so never
  send one from inside a retry loop.
- Over MCP/CLI this is `rootr_send_feedback` / `rootr feedback "..."`.
- Never include secrets, API keys or customer content in a report.

## Quickstart

The examples below use `$WS` for a workspace id and `$KEY` for an API key with
the `docs:write`/`docs:read` scopes. All bodies are JSON unless noted.

### 1. Create a LOG store (a typed table for structured events)

```bash
curl -X POST "https://rootr.io/api/v1/workspaces/$WS/logs" \
  -H "x-api-key: $KEY" -H 'Content-Type: application/json' \
  -d '{
    "name": "checkout-errors",
    "fields": [
      { "name": "level", "type": "level" },
      { "name": "latencyMs", "type": "float" },
      { "name": "orderId", "type": "string" }
    ]
  }'
```

This creates a tree node of type `LOG` under the workspace root (or under
`parentId` if given) with the declared schema in `fields`. The response is the
log store's detail payload (id, path, fields, config, permission level).

### 2. Add a relation field (this is what builds the lineage graph)

Relations are just another field type — add or replace one via `PATCH
/logs/:id` on the *source* store, pointing at the *target* store's id:

```bash
curl -X PATCH "https://rootr.io/api/v1/logs/$LOG_ID" \
  -H "x-api-key: $KEY" -H 'Content-Type: application/json' \
  -d '{
    "fields": [
      { "name": "level", "type": "level" },
      { "name": "latencyMs", "type": "float" },
      {
        "name": "causedByDeploy",
        "type": "relation",
        "target": "<deploy-log-store-id>",
        "relation": "DERIVED_FROM",
        "many": false
      }
    ]
  }'
```

Field shape (`LogField` in `src/logs/log-schema.ts`):

- `name` (string, required), `type` (one of `string`, `int`, `float`, `bool`,
  `datetime`, `json`, `enum`, `level`, `relation`).
- For `type: "relation"`: `target` (required — the target LOG store's node id),
  `many` (optional bool — value is an id, or an array of ids when `true`), and
  `relation` (optional — one of `DERIVED_FROM` (default), `REFERENCES`,
  `TRANSFORMED_BY`, `ORIGIN_OF` — the lineage edge type used when the edge is
  auto-created).

`PATCH` replaces the whole `fields` array, so always resend every field you
want to keep, not just the new one.

### 3. Ingest entries — lineage edges are created automatically

```bash
curl -X POST "https://rootr.io/api/v1/logs/$LOG_ID/entries" \
  -H "x-api-key: $KEY" -H 'Content-Type: application/json' \
  -d '{
    "entries": [
      {
        "ts": "2026-07-05T09:00:00Z",
        "source": "checkout-svc",
        "level": "error",
        "message": "payment gateway timeout",
        "data": { "latencyMs": 4200, "orderId": "ord_123", "causedByDeploy": "<target-entry-id>" }
      }
    ]
  }'
```

For every entry, any `relation`-typed field found in `data` is resolved
against the target LOG store and a data-lineage edge (`logentry` →
`logentry`, typed by the field's `relation`) is created automatically —
the FK doubles as provenance. This runs synchronously during ingest
(`LogsService.appendEntries`, see `src/logs/logs.service.ts`); the response
includes a `linked` count and any `warnings` for relation targets that
could not be resolved.

Anomaly detection (z-score / thresholds / level-based) also runs on every
entry; anomalous (or otherwise store-policy-selected) entries are the ones
promoted into the knowledge graph — see `config.promotion` on the store.

Bulk import is also available for existing data:

```bash
curl -X POST "https://rootr.io/api/v1/logs/$LOG_ID/import" \
  -H "x-api-key: $KEY" -H 'Content-Type: application/json' \
  -d '{ "format": "csv", "csv": "ts,level,message\n2026-07-05T09:00:00Z,error,timeout", "hasHeader": true }'
```

`format` is `"csv"` (default) or `"parquet"` (`parquet` field is the file,
base64-encoded). Both converge on the same coercion/anomaly/lineage/dedup
pipeline as `/entries`.

### 4. Query entries and stats

```bash
# recent entries, optionally filtered
curl "https://rootr.io/api/v1/logs/$LOG_ID/entries?level=error&anomalyOnly=true&limit=50&order=desc" \
  -H "x-api-key: $KEY"

# aggregate stats (e.g. hourly error counts)
curl "https://rootr.io/api/v1/logs/$LOG_ID/stats?groupBy=hour&metric=count" \
  -H "x-api-key: $KEY"
```

`/entries` supports `from`, `to`, `source`, `level`, `anomalyOnly`, `limit`
(max 1000), `order` (`asc`/`desc`). `/stats` supports `from`, `to`,
`groupBy` (`hour`/`day`/`source`/`level`), `field`, `metric`
(`count`/`avg`/`max`/`min`/`sum`).

### 5. Ask a root-cause-analysis question (GraphRAG, over GraphQL)

```bash
curl -X POST "https://rootr.io/api/graphql" \
  -H "x-api-key: $KEY" -H 'Content-Type: application/json' \
  -d '{
    "query": "query($ws: String!, $q: String!) { ask(workspaceId: $ws, question: $q) { text citations { documentPath quote } } }",
    "variables": { "ws": "'"$WS"'", "q": "What is the root cause of the checkout latency spike?" }
  }'
```

`ask(workspaceId: String!, question: String!, scope: GqlScopeInput)` requires
the `ask` scope and returns `{ text, citations { index documentId
documentTitle documentPath chunkId quote }, subgraph { nodes edges } }` — a
natural-language answer grounded in the knowledge graph, with citations back
to the source documents/promoted log entries. There is also a REST,
multi-turn version of the same capability under
`/v1/workspaces/:ws/ask/threads` for conversational RCA sessions.

Other useful GraphQL queries (all `graph:read`, except `ask`): `searchEntities`,
`entity`, `neighbors` (n-hop traversal), `paths` (RCA chains between two
entities), `hybridSearch` (vector + graph retrieval), `documentGraph`,
`graphStats`. Fetch `https://rootr.io/api/graphql/sdl` for exact field/argument names.

## Documents — read & agent-safe writes

Documents are plain Markdown. Reading:

- `GET /v1/documents/:id` (`docs:read`) — JSON `{ id, path, content, etag, ... }`;
  with header `Accept: text/markdown` it returns the raw markdown body instead.
  The response also carries an `ETag` header.
- Resolve a path to an id: `GET /v1/workspaces/:ws/nodes/by-path?path=/gtm/BOARD.md`.
- Browse / search: `GET /v1/workspaces/:ws/tree`,
  `GET /v1/workspaces/:ws/search?q=...`.
- List what is under a folder:
  `GET /v1/workspaces/:ws/tree?rootId=<folder id>&depth=<1-10, default 2>` — a flat
  array of the nodes BELOW that folder (the folder itself is not included), each with
  `id`, `parentId`, `type`, `path`, `hasChildren`. Without `rootId` it starts at
  the workspace root. `depth` is capped at 10; to go deeper, call again with `rootId`
  set to a folder from the previous result. (There is no `/nodes?parentId=` or
  `/nodes/:id/children` route — this is the one.)
- Create a document: `POST /v1/workspaces/:ws/nodes` with
  `{ "type": "DOCUMENT", "path": "/a/b.md", "createParents": true, "content": "..." }`.

Writing — **prefer the narrowest operation**. All partial edits are serialized
per document on the server (two clients appending concurrently both land —
no lost updates), are computed against the live editing session when someone
has the document open, and merge into that session in real time:

1. **Append** (the default write for agents):
   `POST /v1/documents/:id/append` with `{ "content": "- new item" }` appends a
   block at the end of the document, or at the end of a heading section with
   `{ "content": "...", "underHeading": "## ✅ 승인 대기" }` (a missing section is
   created at the document end; pass `"createIfMissing": false` to 404 instead).
   Conflict-free by construction — never overwrites anyone.
2. **Anchored edit** (the Edit-tool mental model):
   `PATCH /v1/documents/:id` with `{ "find": "<exact current text>", "replace": "<new text>" }`.
   `find` must match exactly once; zero matches or an ambiguous match is a 409
   whose message tells you whether to re-read the document or bring more
   surrounding context (or set `"replaceAll": true` deliberately).
3. **Section patch**: `PATCH /v1/documents/:id` with
   `{ "op": "replace" | "append" | "prepend", "heading": "## Status", "content": "...", "createIfMissing": true }`
   — `heading` omitted applies the op to the whole document.
4. **Full replace** (last resort — replaces everything):
   `PUT /v1/documents/:id` with `{ "content": "..." }`. ALWAYS send
   `If-Match: <etag from GET>` so a concurrent edit fails with 412 instead of
   being silently clobbered.

**HTML comments are not kept.** A `<!-- ... -->` outside a code block is dropped
when a document is saved by any of the four writes above, so it cannot serve as
an invisible insertion marker. The write still succeeds (200) and the response
says so: `"warnings": ["1 HTML comment (<!-- ... -->) was removed ..."]` (MCP:
a `warning:` line in the tool result). To keep adding at a fixed place, append
with `underHeading` — consecutive table rows are joined without a blank line.

**Embedding a live table (or any node) inside a document** — the editor's
"Embed" block, like Notion's linked database. The document shows the node's
CURRENT content (rows, cells, slides), not a copy:

- `POST /v1/documents/:id/embeds` with `{ "node": "/Projects/Tasks" }` (a path or a
  node id; optional `"underHeading": "## Data"`) adds it at the end (or under that
  heading). Returns `{ embedded: "<node id>", marker: "[[embed:<node id>]]" }`.
  MCP: `rootr_embed_node`; CLI: `rootr embed <doc> <node> [--heading "## X"]`.
- Or write it yourself in any markdown write (PUT / append / PATCH / create):
  a line containing only `[[embed:/Projects/Tasks]]` or `[[embed:<node id>]]`.
  Paths are converted to ids when saved (reads return the id form). An unknown
  path — or one you cannot read — is a 400 `EMBED_TARGET_NOT_FOUND` and nothing
  is written. A document cannot embed itself; only DOCUMENT nodes hold embeds.
- Scaffolding: a DOCUMENT's `content` may use `[[embed:<name of a node in the
  same tree>]]` — it is linked after the whole tree is built (an unknown name
  rolls the tree back).

Optimistic locking: every `GET`/write response carries `etag`. Pass it as the
`If-Match` header (or the `ifMatch` body field on `PATCH`) — on mismatch the
write fails with 412 and you should re-read and retry. Appends don't need it.

Version history: `GET /v1/documents/:id/versions`, diff via
`GET /v1/documents/:id/versions/:from/diff/:to`, restore via
`POST /v1/documents/:id/versions/:vid/restore`.

## Webhooks (outbound)

Register a webhook to get POSTed when things change — the push counterpart of
the REST API, built for agent integrations. All management routes require the
`webhooks:manage` scope (a workspace-scoped key can only manage its own
workspace's hooks; human JWTs need the ADMIN role). A key with **no owner** (e.g. an
MCP connector key) lists, reads deliveries of, updates, redelivers and deletes **only the
webhooks it created itself** — other webhooks answer 404 like a missing one.

```bash
curl -X POST "https://rootr.io/api/v1/workspaces/$WS/webhooks" \
  -H "x-api-key: $KEY" -H 'Content-Type: application/json' \
  -d '{
    "name": "my agent",
    "url": "https://example.com/hooks/rootr",
    "events": ["document.updated", "comment.created"],
    "scopeNodeId": "<folder-node-id, optional>",
    "filterTags": ["ops"],
    "debounceSeconds": 30
  }'
```

- `GET /v1/workspaces/:ws/webhooks` — list (secrets masked).
- `PATCH /v1/workspaces/:ws/webhooks/:id` — update any field; `active: true` also resets the failure counter; `filterTags: []` or `null` clears the tag filter.
- `DELETE /v1/workspaces/:ws/webhooks/:id` — remove.
- `GET /v1/workspaces/:ws/webhooks/:id/deliveries` — delivery history (paginated); `POST .../deliveries/:deliveryId/redeliver` re-sends one.

**Subscribable events — exactly nine**: `document.created`, `document.updated`,
`document.moved`, `document.deleted`, `comment.created`, `extraction.completed`,
`extraction.failed`, `log.anomaly.rca`, `scaffold.applied`. There are no
per-type event names: in Rootr every node type is ultimately a document, so
**all content changes — issues, database rows, spreadsheets, whiteboards, form
responses — are delivered as `document.updated`**, with the specific mutation
in the payload's `data.change` field (e.g. `'issue.closed'`,
`'database.row.updated'`, `'form.response.created'`). Registering any other
event name is a 400.

`log.anomaly.rca` (automatic root-cause report for an anomalous error log
entry) is **grouped**: error entries in the same LOG store with the same level
and the same message shape (numbers, UUIDs and long hex ids removed) produce
**one** report per 10-minute window, and a workspace gets at most 30 automatic
reports per hour. To find the report that covers any entry — including one that
was grouped under an earlier entry — call
`GET /v1/workspaces/:ws/rca-reports?entryId=<entryId>` (`grouped: true` when
it is the earlier entry's report).

Delivery is a JSON POST shaped `{ event, workspaceId, data }`. `data` carries
the node's location (`path`, `nodeId`/`trackerId`/…) plus `change` (content
events only) — and **what changed, not the whole document**:

- Document edits include a unified `diff` (patch text, capped at 8 KB with
  `diffTruncated: true`). Read the full document via `GET /v1/documents/:id`
  when you need more than the diff (full history:
  `GET /v1/documents/:id/versions`). With coalescing, the diff spans the
  whole burst — baseline before the first edit → final state.
- `document.created` carries a `contentPreview` (first 500 chars) — a new
  document has no baseline, so no diff.
- Issue deliveries carry number, title, `bodyPreview` (first 300 chars +
  `bodyTruncated`), state, resolved labels and type (`{id,name,color}`) —
  read the full body via `GET /v1/issues/:issueId`.

Coalesced deliveries add a `coalesced` count.

Targeting — run many narrow hooks instead of one firehose:

- `scopeNodeId` — only events from that node's subtree.
- `filterTags` — only events whose node, **or any ancestor folder**, carries at
  least one of the tags (case-insensitive OR; AND-combined with the scope).
  Both are fail-closed: an event whose location can't be resolved is skipped.
- `debounceSeconds` (0–600; the UI defaults to 30) — trailing debounce: the
  delivery fires once the node has been quiet for N seconds, merging the burst
  into one delivery with the latest payload. Continuous editing is capped at
  5 minutes, after which an interim state is delivered.

**Verify signatures.** The `secret` (`whsec_...`) is returned exactly once, in
the create response. Every delivery carries `X-Rootr-Event`,
`X-Rootr-Delivery`, and `X-Rootr-Signature: sha256=<hex>` — HMAC-SHA256 of the
raw request body with your secret:

```js
const crypto = require('crypto');
const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
const ok = crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(req.headers['x-rootr-signature']));
```

**Avoid feedback loops**: mutations made with your own API key carry your
identity as `actorId: "apikey:<key-id>"` in `data` — ignore deliveries whose
`actorId` is yourself before reacting to them.

## Node tags

Tag any node (documents, folders, trackers, …) and target webhooks with them:

- `PATCH /v1/nodes/:id` with `{ "tags": ["ops", "backend"] }` (`docs:write`) —
  full replacement; each tag 1–30 chars, max 20 per node, case-insensitive
  duplicates dropped.
- `GET /v1/workspaces/:ws/tags` (`docs:read`) — distinct sorted tag list
  across the workspace, for autocomplete.

Tags on a folder apply to its whole subtree for webhook `filterTags` matching
(see above).

## Deleting and undoing a delete

`DELETE /v1/nodes/:id` (`docs:write`, WRITE) moves a node — and everything under
it — to the trash. Nothing is erased: `POST /v1/nodes/:id/restore` puts it back
where it was, children included. That restore is the same thing Ctrl+Z does in the
app right after a delete, and anyone with WRITE can call it, not just whoever
deleted it. Pass the node **id**: a trashed node is off the tree, so a path will not
find it — keep the id the delete returned. Purging for real is
`DELETE /v1/nodes/:id/purge` (workspace ADMIN) and is not recoverable.
MCP: `rootr_delete_node`, `rootr_restore_node`. CLI: `rootr rm`, `rootr restore <id>`.

## Issue trackers

`ISSUE_TRACKER` is a first-class node type: GitHub-style issues with
per-tracker `#numbers`, open/closed state, labels, custom types, assignees,
sub-issues, comments and an activity timeline. Create one directly
(`POST /v1/workspaces/:ws/issue-trackers`) or in a scaffold tree (see below).

- `POST /v1/issue-trackers/:id/issues` (`docs:write`) —
  `{ title, body?, labels?, type?, assigneeId?, parentIssueId? }`. `body` is
  markdown; `labels` is an array of label **ids**; `type` is a type **id**;
  `parentIssueId` makes it a sub-issue.
- `GET /v1/issue-trackers/:id/issues?state=OPEN|CLOSED|ALL&label=&type=&assigneeId=&q=` — list/filter.
- `PATCH /v1/issues/:issueId` — any field; `{ "state": "CLOSED", "stateReason": "completed" | "not_planned" | "duplicate" }` closes, `{ "state": "OPEN" }` reopens.
- `GET /v1/issues/:issueId/activities` — the timeline (assigned/labeled/typed/closed/referenced/…).
- Comment threads reuse the document comment API:
  `POST /v1/documents/:trackerId/comments` with `{ "body": "...", "blockId": "<issueId>" }`.
- Mention users with `@[<userId>]` in bodies/comments; reference other issues
  with `#N` — both link up automatically (notifications + 'referenced' rows).

Labels and types are **user-defined per tracker** as `{ id, name, color }`
lists (defaults: labels bug/enhancement/question, types bug/feature/task).
Manage them with `PATCH /v1/issue-trackers/:id` `{ "labels": [...], "types": [...] }`;
read them (plus open/closed counts) from `GET /v1/issue-trackers/:id`.
Trackers also support inbound webhooks (GitHub-compatible) — see
`POST /v1/issue-trackers/:id/inbound` in the OpenAPI spec.

## CRM

`CRM` is a first-class node type: a full sales/relationship-pipeline workspace
— companies, contacts, a multi-pipeline deal kanban, an activity timeline and
follow-up tasks — in one node. Create one directly
(`POST /v1/workspaces/:ws/crms`) or in a scaffold tree (see below). Use it
whenever the ask is "stage-tracked relationships over time", not a one-off list
of records: a sales team's pipeline, an agency's client roster, a hiring
pipeline, fundraising, partnership/BD management.

- **Companies** — `GET/POST /v1/crms/:id/companies`,
  `GET/PATCH/DELETE /v1/crm-companies/:companyId`. List filters: `q` (name/domain),
  `ownerId`, `tag`.
- **Contacts** — `GET/POST /v1/crms/:id/contacts`,
  `GET/PATCH/DELETE /v1/crm-contacts/:contactId`. Each has a `lifecycleStage`
  (`lead|mql|sql|opportunity|customer|evangelist`), a `leadStatus`, and a
  server-computed `leadScore`. List filters: `q` (name/email), `companyId`,
  `lifecycleStage`, `leadStatus`, `ownerId`, `tag`, sort by `leadScore`. Omit
  `companyId` on create to auto-link by email domain.
- **Deals** — `GET/POST /v1/crms/:id/deals`,
  `GET/PATCH/DELETE /v1/crm-deals/:dealId`, `POST /v1/crm-deals/:dealId/move`
  (kanban drag: reassign `stageId` — optionally `pipelineId` — and column
  `position`; logs a `stage_change` timeline entry). Deals carry
  `value`/`currency`/`probability`/`expectedCloseDate`; `PATCH` with
  `status: "won"|"lost"` closes a deal (stamps `closedAt` + an optional
  `wonLostReason`), `status: "open"` reopens it. List defaults to open deals;
  `status=won|lost|all` for others; filter by `pipelineId`/`stageId`/`ownerId`/
  `companyId`/`contactId`/`tag`; `sort=position` for board order.
- **Activities** (timeline) — `GET/POST /v1/crms/:id/activities`,
  `DELETE /v1/crm-activities/:activityId`. `type=note|call|email|meeting` plus
  system-logged events (created/stage_change/task_done/…), any subset of
  contact/company/deal links. Filter by `contactId`/`companyId`/`dealId`/`type`.
- **Tasks** (follow-ups) — `GET/POST /v1/crms/:id/tasks`,
  `PATCH/DELETE /v1/crm-tasks/:taskId`. Has a `due` date; `due=overdue|today|upcoming`
  filters the follow-up queue; `status: "done"` on `PATCH` stamps `completedAt`
  + a `task_done` timeline entry; create defaults the assignee to the caller.
- **Dashboard** — `GET /v1/crms/:id/summary`: pipeline value & weighted
  forecast per stage (value × stage probability), win rate, won-by-month
  (6 mo), task and lifecycle-stage counts.
- **Export / Import** — `GET /v1/crms/:id/export` (XLSX, one workbook with
  Companies/Contacts/Deals sheets), `POST /v1/crms/:id/import` (`{ entity,
  rows: [{column: value}] }` — company names are matched/created on the fly,
  per-row errors are reported).
- **Config** — `PATCH /v1/crms/:id` `{ "pipelines": [...], "fields": {...},
  "config": {...} }` replaces pipeline/stage defs (with probabilities) and
  custom field defs per entity (`contact`/`company`/`deal`, each
  `text|number|select|date|url|checkbox`); `GET /v1/crms/:id` reads them back
  plus record counts. Deals pointing at a removed stage move to the first
  stage of their (or the first) pipeline. Omit `pipelines` on create for the
  default 5-stage Sales Pipeline (Lead In 10% → Qualified 25% → Meeting 40% →
  Proposal 60% → Negotiation 80%).

MCP (rootr-cli >= 0.3.0) ships dedicated `rootr_crm_*` tools mirroring the
REST surface: `rootr_crm_create/get/update`, `rootr_crm_list_companies`/
`rootr_crm_upsert_company`/`rootr_crm_get_company` (same trio for contacts
and deals), `rootr_crm_move_deal`, `rootr_crm_log_activity`/
`rootr_crm_list_activities`, `rootr_crm_upsert_task`/`rootr_crm_list_tasks`
and `rootr_crm_import`. A `crm` node can also be part of a scaffold tree via
`rootr_scaffold_apply`/`rootr_create_workspace`.

Every company/contact/deal/activity/task is mirrored into the knowledge graph
as a shadow document, so `rootr_ask`/RCA can answer relationship questions
directly — who works at which company, why a deal was lost, what's overdue —
without you writing any extraction code.

## Presentations — author real slide decks over the API

`PRESENTATION` is a first-class node type: a deck of 16:9 slides
(**canvas is exactly 1280×720**) with a design theme, rendered in a sandboxed
viewer with a fullscreen present mode.

- `POST /v1/workspaces/:ws/presentations` (`docs:write`) —
  `{ name, path?, parentId?, icon?, theme?, slides?, config? }`. `theme` =
  `{ colors: {primary, secondary, accent, bg, text, muted}, fonts: {heading, body} }`
  (missing keys get defaults).
- `GET /v1/presentations/:id` / `PATCH /v1/presentations/:id` — read / update
  deck-level fields (`name`, `theme`, `slides` wholesale, `config`).
- `POST /v1/presentations/:id/slides` `{ "slides": [...] }` — append slides.
- `PATCH /v1/presentations/:id/slides/:slideId` `{ "slide": { ...partial } }` —
  **merges** the given fields into that slide (other fields survive).
- `POST /v1/presentations/:id/reorder` `{ "order": ["SLD-001", ...] }`.
- `GET /v1/diagram-types` / `GET /v1/diagram-types/:type/schema` (`docs:read`) —
  the five diagram families (`architecture`, `workflow`, `sequence`,
  `dataflow`, `lifecycle`) and, per family, its JSON Schema plus a worked
  example. **Read the schema before authoring** — each family has a different
  shape and a mismatch is rejected.
- **Slide videos (Team plan and above).** A slide may carry `videos: [{ src, title?, poster?, x?, y?, w?, h? }]`
  (max 20 per slide; canvas coords 1280×720, default 640×360 centred). `src` = an uploaded
  video (`POST /v1/attachments/upload?...&mimeType=video/mp4&nodeId=<deck id>`, ≤75MB, then
  `<app>/api/v1/attachments/<id>/raw`), an https video-file URL, or a YouTube/Vimeo link;
  `poster` = thumbnail image URL. Slide `html` may also hold `<video src=".../raw">`,
  `<div data-video-embed="https://www.youtube.com/watch?v=...">` or a YouTube/Vimeo `<iframe>`.
  A Free workspace gets `403 PLAN_UPGRADE_REQUIRED` (messageKey `error.plan.videoRequiresTeam`) when
  a write ADDS a video; existing videos stay playable and removable. Uploaded videos are served
  through short-lived signed links: reading a slide returns file URLs with a `vt=` query that
  lets them play inside the slide; writes strip `vt` (never store it), and a bare `/raw`
  link opened from another website is refused with `403 VIDEO_HOTLINK_BLOCKED`.
- **Slide animations (all plans).** In slide `html`, `data-anim="<effect>"` on any element animates it
  when the slide opens in view/present mode. Entrance: `fade`, `fade-up`, `fade-down`, `fly-left`,
  `fly-right`, `zoom`, `pop`, `blur`. Looping: `pulse`, `float`, `spin`, `blink`, `shake`.
  Duration/delay are inline CSS variables — `<div data-anim="fade-up" style="--anim-delay:.4s;--anim-dur:.8s">`;
  stagger delays to set the order. Hand-written `@keyframes`/`animation` CSS in the html plays too.
  Thumbnails and PDF/PPTX exports show the finished state; viewers with reduced-motion set see no motion.
- `POST /v1/presentations/:id/diagram-slides` (`docs:write`) —
  `{ type, spec, title?, subtitle?, blocks?, notes?, slideId?, quality? }`.
  Renders a typed diagram spec and bakes it into `slide.html`, so it shows in
  the viewer **and** in the PDF/PPTX exports. Appends a slide, or redraws
  `slideId`. `quality` is `standard` (default) or `showcase` (a strict
  composition bar for a hand-tuned hero diagram — it rejects specs that
  `standard` accepts). An invalid spec comes back naming the offending field
  with a suggested fix: apply it and retry. **Use this when the diagram has to
  look designed**; for a quick sketch, a structured `content` slide also draws
  its mermaid `diagram` field (see below).
- `POST /v1/workspaces/:ws/import/pptx?filename=<original name>.pptx&parentId=<optional>`
  (`docs:write`) — **import an existing PowerPoint file as a deck.** The request
  body is the raw `.pptx` bytes (`Content-Type: application/octet-stream`); the
  deck is named after `filename` minus its extension (a taken name gets
  ` (2)`). Returns `{ id, name, url, slides, images, videos, warnings }`.
  **What comes across:** slide order, each slide's title, all text (text boxes,
  tables, grouped shapes, SmartArt and chart labels/values) as `blocks`, speaker
  notes, embedded mp4/webm/mov videos and YouTube/Vimeo links on Team plan and above
  (as `videos[]`; on Free only the poster picture comes across, with a warning), and the
  pictures placed on each slide (uploaded as attachments, kept at
  their position on the 1280×720 canvas — a 4:3 deck is centred). **A picture
  that was cropped in PowerPoint arrives cropped:** only the visible region is
  stored, never the hidden part of the original (EXIF/location metadata is
  dropped from the cut picture). If a cropped picture cannot be cut — animated
  GIF, SVG/BMP, a corrupt or oversized image — it is left out rather than
  uploaded whole, and `warnings` says how to fix it in PowerPoint. Only
  rectangular crops are cut; a picture masked by a shape (circle, rounded
  rectangle) comes across as its full rectangle, with a warning. The imported
  text is searchable and answerable by `rootr_ask` like any other deck.
  **What does not:** shape layout, fonts, colours, animations and transitions,
  the *look* of charts/SmartArt/tables (text only), master/layout artwork,
  audio, and image formats a browser cannot draw (EMF/WMF/TIFF).
  Everything that was dropped or changed is listed in `warnings` — show them to
  the user. Password-protected files, legacy `.ppt`, and non-pptx files are
  rejected with a 400 whose `message` says what to do. Decks over 500 slides
  must be split.

```bash
curl -X POST "https://rootr.io/api/v1/workspaces/$WS/import/pptx?filename=q3-review.pptx" \
  -H "x-api-key: $KEY" -H 'Content-Type: application/octet-stream' \
  --data-binary @q3-review.pptx
```

Slide fields (all optional except a unique `id`, e.g. `SLD-001`):
`kind` (`cover|section|content|closing`), `layout` (see below),
`title` (assertion-style), `blocks` (`[{id, heading?, body?, icon?}]`),
`diagram` (`{type:'mermaid', code}` — drawn on `content` slides, below the
blocks; `cover`/`section`/`closing` ignore it, and a slide with baked
`html` shows only its html. A syntax error is shown on the slide. For a designed
diagram use `POST /v1/presentations/:id/diagram-slides`), `image`/`images`
(`{prompt?, placement?, src?, alt?, x?, y?, w?, h?}` — see the placement table
below), `code`, `html`, `notes` (speaker notes).

`layout` — the built-in template knows exactly these values on `content`
slides: `two-col` (two columns; needs 2+ blocks) and `kpi-grid` (alias `kpi`;
big-number cards, `heading` = the number, `body` = its label). **Any other
value is accepted but silently falls back to the default arrangement** (1–3 blocks
as stacked rows, 4 as a 2-column card grid, 5+ as 3 columns) — `2-col` and
`timeline` are NOT layouts. On `cover` and `section` slides `layout` is
printed as the small label above the title, so leave it out there unless you want
that text.

**The text spine feeds the knowledge graph for free**: `title` +
`blocks[].heading/body` + `notes` + every image `alt` are extracted as plain
text (no vision model). Always fill them — even when you bake custom HTML.

### Recommended contract for polished decks: bake `slide.html`

The viewer renders `slide.html` verbatim (instead of the built-in template)
inside a **sandboxed iframe** — this is the full-design-freedom path, and what
you should use for anything client-facing. Rules learned the hard way:

1. Ship a complete self-contained document sized exactly 1280×720
   (`html,body{width:1280px;height:720px;overflow:hidden}`). Never exceed
   720px height — overflow is clipped.
2. **Inline everything.** The iframe's CSP blocks all external requests
   (no CDN scripts/fonts/styles; `connect-src 'none'`). Diagrams: draw inline
   SVG (don't rely on mermaid here).
3. **Images**: `data:` URIs (WebP, keep each ≲100KB) always work and keep the
   slide self-contained. An uploaded attachment's `/v1/attachments/:id/raw` URL
   also loads in `<img>` — that route answers with
   `Cross-Origin-Resource-Policy: cross-origin`, so the opaque-origin iframe is
   not blocked. Only the `/raw` form: the bare `/v1/attachments/:id` needs auth
   and IS blocked.
4. Fonts: use a fallback stack (`Pretendard,'Noto Sans KR',system-ui,sans-serif`) —
   don't assume any webfont exists inside the iframe.
5. Page numbers: include `<span class="pn"></span>` (the viewer fills the
   number in; `class="pn2"` gets a zero-padded 2-digit variant).
6. Put meaningful `alt` text on every `<img>` — it reaches the graph.
7. Keep `title`/`blocks`/`notes` in sync with what the HTML shows (the graph
   reads those, plus the HTML's visible text).

Structured-only slides (no `html`) render via the built-in template. What it
does with the primary `image` depends on the slide's `kind` and the image's
`placement`:

| kind | `full` | `right` | `top` |
|---|---|---|---|
| `cover` | full-bleed background (darkened so the title stays readable) | ignored | ignored |
| `section` | full-bleed background | ignored | ignored |
| `content` | faint full-slide background (12% opacity) | panel on the right of the blocks | band above the blocks |
| `closing` | full-bleed background | ignored | ignored |

Always set `placement`: without it a `cover` treats the image as `full`, but a
`content` slide does not draw it at all. Any other `placement` value is accepted
and ignored. `images[]` (additional images) are drawn on every kind, absolutely
positioned — only when both `x` and `y` are set (`w`/`h` default to 320×200);
don't put `x`/`y` on the primary `image`, which is placed by `placement`.

**Export (PDF · PPTX)** is done by a person from the deck screen's ⋯ menu. It
runs in the browser — the server does not render slides to pictures, so there is
no export endpoint and no export MCP tool.

### AI image assets

- `POST /v1/workspaces/:ws/images/generate` (`docs:write`, **AI-credit
  metered**) — `{ prompt, nodeId?, context?: {title?, points?, palette?} }`.
  With `context` the server first plans a slide-aware prompt, then generates;
  the result is stored as a workspace attachment
  (`{ id, url, filename, mimeType, size }`, auto-downscaled to slide-friendly
  WebP). Also available: `POST .../images/describe` (vision → alt text) and
  `POST .../images/remove-background`.
- When credits are exhausted the API returns `AI_CREDITS_EXHAUSTED` — either
  top up in Settings → Billing or generate images elsewhere and upload via
  `POST /v1/attachments/upload`.

## Pages — build a real web page (no HTML from you)

`PAGE` is a first-class node type: an ordered list of **typed blocks** that
publishes as a real web page at `rootr.io/p/{slug}`. You assemble a page by
choosing blocks, which is what makes a published page safe to hand to strangers;
the one free-form escape hatch (`custom`) is sandboxed — see below. Use it whenever the answer
is something **outsiders will look at** (landing page, announcement, event page,
pricing page, signup page); use a DOCUMENT when the audience is the team.

- `POST /v1/workspaces/:ws/pages` (`docs:write`) —
  `{ name, path?, parentId?, createParents?, autoRename?, icon?, blocks?, config? }`.
  Omit `blocks` to start from a hero/text/footer skeleton.
  The response carries both `id` (internal page-row id) and `nodeId` — **use `nodeId`** as
  the `:id` of every `/v1/pages/:id…` call below (the row `id` answers 404 there).
- `GET /v1/pages/:id` — blocks + config.
- `POST /v1/pages/:id/blocks` `{ "blocks": [...] }` — **append** at the end
  (existing blocks untouched). Prefer this when you are only adding sections.
- `PATCH /v1/pages/:id` `{ blocks?, config? }` — `blocks` **replaces the whole
  page**; any block you leave out is deleted. Send only `config` to restyle
  without touching content.
- `GET /v1/pages/:id/live-data` — what the page's live blocks currently show.
  An empty result means the source table is missing, you cannot open it, or the
  column name does not match (a PRIVATE source still shows here for whoever can open
  it — it is only left out of the published page).

Live/form block sources (`source.nodeId`, `cards[].source.nodeId`, `formNodeId`) may be written
as the **node id**, a full **`"/folder/name"` path**, or a **name that is the only one** among the
tables/sheets/logs (forms for `formNodeId`) you can open. The server resolves it before saving
and stores the id — read it back from the response. A path or name it cannot resolve (missing,
not readable by you, wrong node type, or shared by two nodes) is rejected with **400 and nothing
is saved** — it is never stored as a silently empty block.

Blocks are `{ id?, type, props }` (id is generated if you omit it; keep the ids
you get back to edit one block later). Max 200 per page. The 17 types:

| type | props |
| --- | --- |
| `hero` | `{title, subtitle?, align?: left|center, size?: normal|screen, background?: {kind:'color',color}|{kind:'image',attachmentId}|{kind:'video',attachmentId,posterAttachmentId?,portraitAttachmentId?,portraitPosterAttachmentId?}, button?: {label,target}}` — `size: screen` = full-screen landing hero; `kind:'video'` = looping motion-graphic background (see "Page videos") |
| `text` | `{body (markdown, sanitized on render), title?}` |
| `features` | `{columns?: 1|2|3, items: [{title, body, icon?}]}` |
| `gallery` | `{images: [{attachmentId, caption?}]}` (workspace attachments only) |
| `pricing` | `{plans: [{name, price, period?, features: [string], highlight?, buttonLabel?, target?}]}` |
| `testimonials` | `{items: [{quote, name, affiliation?}]}` |
| `faq` | `{items: [{q, a}]}` |
| `timeline` | `{items: [{date, title, body?}]}` |
| `cta` | `{title, buttonLabel, target, body?}` |
| `footer` | `{links: [{label, target}], contact?, copyright?}` |
| `liveStats` | `{cards: [{label, icon?, source: {nodeId, agg: count|sum|avg|min|max, column?, dateColumn?, period?, filters?}}]}` |
| `liveTable` | `{source: {nodeId}, columns?, rowLimit? (1-200), orderBy?: {column, dir}, filters?, summary?: [{column, agg, label?}]}` |
| `liveChart` | `{source: {nodeId, sheet?, range?}, chart (46 kinds — see "Dashboards & charts"), labelColumn, valueColumn?, agg?, values?, seriesColumn?, dateBucket?, filters?, …}` |
| `form` | `{formNodeId, headline?, submitLabel?}` |
| `booking` | `{bookingNodeId, headline?, type?}` — a visitor scheduling calendar; `bookingNodeId` is the node **id** of a published DATABASE with visitor booking on |
| `custom` | `{html, height?: 40-4000 (default 260), minHeight?: none|screen, bleed?: boolean}` — free HTML/CSS in a sandboxed frame; `bleed: true` = full page width, no gaps; `minHeight: screen` = one viewport tall |
| `video` | `{attachmentId, posterAttachmentId?, caption?, aspect?: 16:9|9:16|1:1|4:5 (default 16:9), bleed?: boolean}` — a motion-graphic clip (autoplay, muted, loop, inline, no controls); `bleed: true` = full page width |

`filters` (on `liveStats` card.source, `liveTable`, `liveChart`) is the same shape everywhere:
`[{column, op, value?}]` with `op` one of `is|is_not|contains|not_contains|gt|gte|lt|lte|empty|not_empty|last_days`
(`value` may be `@today`/`@today+N` for a date column). This is how a card like "아내가 이번 주
운동한 횟수" is built: `source.filters: [{column:"사람",op:"is",value:"아내"},{column:"결과",op:"is",value:"운동함"}]`
plus `source.dateColumn` + `source.period: "week"` (period also accepts `today|7d|30d|90d|month|quarter|year|all`)
to scope it to the current week. `liveTable.summary` adds a totals row below the rows —
`[{column, agg: count|sum|avg|min|max, label?}]` — computed over every row the filters leave
(not just the `rowLimit` shown on screen), for a ledger's "합계/잔액" line.

**Full-screen hero, full-width bands and full-screen sections (landing pages).** Two options take
a block out of the centred text column and let it use the **whole page width**, and a third makes a
free-form section **one screen tall**:

- `hero.size: "screen"` — the hero spans the page edge to edge and is **one viewport tall**
  (minus the top name bar when `config.navEnabled` is on; capped at 1200px on very tall screens), with a
  much larger headline and button and the content centred vertically. `align` and `background`
  work as before; a background image gets a gradient overlay so the text stays readable.
  Omit it (or send `"normal"`) for the compact banner.
- `custom.bleed: true` — the sandboxed frame spans the full page width with **no padding or gap
  around it**, so consecutive bleed blocks read as seamless colour bands. Paint your own
  full-width background inside and keep the content in a centred max-width wrapper. `height`
  still applies, and the sandbox is exactly the same (no scripts, no network).
- `custom.minHeight: "screen"` — the frame is **one viewport tall on every device** (same rule as
  the hero: minus the top name bar, capped at 1200px), which a px `height` alone cannot do. A numeric
  `height` given together becomes the **floor** — frame height = max(one screen, `height`) — so
  set it to what the content needs on a short phone and nothing is clipped. Inside the frame use
  `height:100%` (html and body already are) and centre the content with flexbox. Combine with
  `bleed: true` for a section that fills the screen; stack several for a section-per-screen page.
  Without `bleed` the block stays in the text column and keeps its `width`.

`hero.size: "screen"` and `custom.bleed: true` always take the whole row — `width` is ignored and not stored on them. Every other block stays
in the centred column, so a typical landing page is: `hero {size:"screen"}` → a few
`custom {bleed:true}` bands → ordinary blocks → `footer`, with `config.navEnabled: false`.
Any other value is rejected with 400 (`size` must be `normal|screen`, `bleed` must be a boolean,
`minHeight` must be `none|screen`);
on a block type that does not have the option it is dropped like any unknown key.

**Scroll-in animation (`reveal`).** Every block type takes `reveal: "fade" | "fade-up"`
(default `"none"`, not stored). On the published page the block appears **once, when it scrolls
into view** — when its top edge passes about 85% of the viewport height; blocks already on the first
screen play right after load. `fade` fades in, `fade-up` also rises a little. A `hero` staggers
title → subtitle → button and keeps its background still. It combines with `width`,
`size: "screen"`, `bleed` and `minHeight`. Nothing shifts layout, and the effect is skipped
(everything simply visible) for visitors who ask for reduced motion and in browsers without
`IntersectionObserver`. Any other value is rejected with 400.

On a **`custom` block, `reveal` also starts the CSS animations inside the frame at that moment.**
The sandbox cannot be told when it scrolls into view, so without `reveal` an `animation` in your
HTML starts at page load and is over before a visitor scrolls down. With `reveal` set, the frame is
**created only when the block scrolls in** (its height is reserved beforehand, so nothing jumps) and
your `@keyframes` run from 0s right then. Write them so the content is fine without animation and
wrap them in `@media (prefers-reduced-motion: no-preference)`. Still no scripts — CSS only.

**The `booking` block puts a scheduling calendar on the page.** `bookingNodeId` is the node id of
a DATABASE that is **published and has visitor booking turned on** (see *Visitor booking* below) —
unlike live/form sources it must be the id, not a name or path. Visitors pick a slot right on the
page and the booking lands as a row in that table; `headline` is the title above the calendar and
`type` limits the block to one of the table's booking types. If the table is not published or
booking is off the block says so instead of drawing an empty calendar, and the table's id never
leaves the server.

**Page videos (Team plan and above).** The hero background `{kind:'video', attachmentId, posterAttachmentId?}`
and the `video` block play a **motion graphic**: always `autoplay muted loop playsinline`, no
controls, no sound — a moving picture, not a talk. The hero video covers the banner (also the
full-screen hero) under the same dark shade and white text as an image background. The poster
(`posterAttachmentId`, an image — use the video's first frame) shows while loading and **instead of
the video** for visitors who ask for reduced motion or whose browser blocks autoplay.
**Phone cut:** a 16:9 video covering a portrait phone screen shows only its middle strip, so a
hero video may also carry `portraitAttachmentId` (a vertical cut, e.g. 1080×1920) and
`portraitPosterAttachmentId`. A portrait screen (`orientation: portrait`) plays the portrait cut,
anything else the default one — the page downloads **only one** of them. It gets its own playback
signature `portraitVt`; the same workspace / video / Team rules apply, and a portrait poster without
a portrait video is 400. Upload first:
`POST /v1/attachments/upload?workspaceId=<ws>&nodeId=<page id>&filename=a.mp4&mimeType=video/mp4`
with the raw bytes as the body and `Content-Type: application/octet-stream` (H.264 MP4 with
`+faststart` plays everywhere, iPhone included). The attachment must be uploaded to **this page's
workspace** — anything else (missing, another workspace, not a video; a poster that is not an
image) is `400 PAGE_MEDIA_INVALID`. A Free workspace gets `403 PLAN_UPGRADE_REQUIRED` (messageKey
`error.plan.pageVideoRequiresTeam`) when an upload to a page or a page write **adds** a video;
videos already on a page keep playing. Reading a page (`GET /v1/pages/:id`, the public page) adds a
short-lived playback signature `vt` next to each video's `attachmentId`; play it at
`/v1/attachments/<attachmentId>/raw?vt=<vt>`. The bare `/raw` address of a video answers 403
(hotlink protection). `vt` is never stored — it is dropped on save.

**The `custom` block is the escape hatch.** When the other sixteen cannot make the look you
want, write HTML and CSS yourself — it renders inside a **locked-down sandboxed iframe**
(no scripts, opaque origin, `connect-src 'none'`, `form-action 'none'`), so it can style
itself freely but cannot touch the rest of the page, cover the viewport, or reach the
network. `<script>` and `on*=` handlers are stripped when the page is saved: put markup
and CSS there, never behaviour. Inside the frame the page's theme is available as
`var(--pg-bg|text|muted|faint|card|line|accent|on-accent)` and `var(--pg-font)`, so a
custom block can match the chosen theme instead of fighting it. Give it a `height` in px
(the frame does not auto-size). Interactive things — signup, live numbers — belong in the
`form` and `live*` blocks, which work; a custom block cannot submit anything.

**Live blocks read the table as it is right now** — publish once and the page
keeps up with the data. `source.nodeId` is a DATABASE, SPREADSHEET or LOG node in the same
workspace and every `column`/`labelColumn`/`valueColumn`/`orderBy.column` is the
column **name** shown in the table, not a column id. A source that sits in a
PRIVATE subtree is skipped on purpose on the **published** page, and its rows never reach
it (inside the app the viewer's own read permission decides, so the owner still sees it);
person / relation / attachment values never go out either. `form` and `booking` blocks
are not affected by PRIVATE — they only send the questions / free slots, like the form's
own share link.

**Dashboards & charts.** Any block takes `width: full | twoThirds | half | third` (and
`reveal: fade | fade-up`, see "Scroll-in animation" above);
neighbouring blocks sit side by side (phones stack them), so a page becomes a
dashboard: a row of `kpi` charts at `third`, then trend/composition charts at `half`.
`liveChart.chart` is one of 46 kinds —
comparison `bar barH stackedBar stackedBarH percentBar lollipop dumbbell bullet waterfall pareto radar polarBar`,
trend `line step area stackedArea percentArea combo slope stream calendar`,
part-to-whole `pie donut halfDonut rose funnel treemap sunburst waffle`,
distribution `histogram boxplot heatmap`, relationship `scatter bubble`,
flow/hierarchy `sankey chord network tree`, KPI `kpi gauge progress ring`,
special `candlestick gantt wordCloud pivot`.

- **Source**: a table, a spreadsheet (`{nodeId, sheet?, range?: "A1:F200"}` — first row
  holds the column names; formula results are read) or a log store (`ts source level message anomaly` + declared fields).
- **Category charts**: `labelColumn` (date columns are bucketed by `dateBucket`
  day/week/month/quarter/year/weekday/hour, missing periods filled with 0; select/status
  columns keep their option order) and either `valueColumn`+`agg`
  (count/sum/avg/min/max/median/distinct — `valueColumn` is optional for `count`/`distinct`,
  which just count the matching rows per label), `values: [{column?, agg, label?, as?: bar|line|area, axis?: left|right}]`
  (several series, combo with a second axis) or `seriesColumn` (break down / stack).
  `sort`, `limit` + `others` (fold the tail into "Other"), `cumulative`.
- **KPI / gauge / progress / ring**: `valueColumn`+`agg`; add `dateColumn` + `period`
  (today/7d/30d/90d/week/month/quarter/year) for the change against the previous
  period of the same length plus a sparkline; `goal` or `goalColumn`.
- **Others**: scatter/bubble `xColumn yColumn sizeColumn`; histogram/boxplot `valueColumn`;
  sankey/chord/network `labelColumn → targetColumn`; treemap/sunburst/tree `labelColumn + levels[]`;
  candlestick `open/high/low/closeColumn`; gantt `startColumn endColumn`.
- **Filters**: `[{column, op, value}]`, op = is, is_not, contains, not_contains, gt, gte, lt, lte,
  empty, not_empty, last_days (`value` may be `@today-30`).
- **Display**: `title subtitle height format(auto|number|compact|percent|krw|usd|decimal1|decimal2)
  prefix suffix palette(theme|vivid|pastel|ocean|sunset|forest|mono) goal goalLabel thresholds[{value,color}]
  showLabels showLegend smooth`.

Only aggregated values leave the server — never row ids, column ids or the source node id.
`GET /v1/pages/:id/live-data` returns what each chart computed; a chart that cannot draw
says why (`{shape:"empty", reason: column_missing|no_rows|needs_number, column}`).

**Form blocks receive real submissions.** Point `formNodeId` at a FORM node and
visitors fill it in on the page itself — the form does **not** need to be
published separately, because putting it on a published page *is* the act of
publishing it. Visitors submit at
`POST /v1/public/nodes/:slug/form-blocks/:blockId/responses` and attach files at
`.../form-blocks/:blockId/uploads`; the questions come from
`GET /v1/public/nodes/:slug/form-blocks`. The form node's id never leaves the
server — a visitor only ever sees the page slug and a block id.

**Links.** Every `target` is `{kind:'url', href}` (absolute `http(s)://`,
`mailto:` or `tel:` — internal path strings are rejected; opens in a new tab),
`{kind:'node', nodeId}` for a document in the same workspace, or
`{kind:'block', blockId}` to **jump to another block on the same page**. A node link points
at the in-app document for members, at the public address on the published page,
and disappears entirely if that document is not published. **Link to nodes**
rather than pasting addresses: nodes survive renames and moves.

A block link renders as `<a href="#pg-b-<blockId>">` — same tab, smooth scroll, the target
block's top lands just below the sticky name bar (full-screen hero and bleed blocks included).
Use it for landing pages opened in Instagram/Facebook in-app browsers, where a new tab loses
the visitor: e.g. a hero button "무료 진단 예약하기" → the `booking` block further down.
`blockId` must be the id of a block **on this page** — otherwise `400`
(`blocks[i].props.button.target.blockId "x" is not a block on this page`), also when an
update removes a block that a link still points at. So give the target block an explicit `id`
when you create the page:

```json
{"blocks":[
  {"type":"hero","props":{"title":"무료 진단","size":"screen",
    "button":{"label":"무료 진단 예약하기","target":{"kind":"block","blockId":"booking"}}}},
  {"id":"booking","type":"booking","props":{"bookingNodeId":"<table node id>"}}
]}
```

Inside a `text` block's markdown, `[label](#<blockId>)` is the same kind of same-page link.
Duplicating a page re-points block links at the copy's new block ids. A `#pg-b-<blockId>`
fragment in the page address opens the page scrolled to that block.

`config` is `{theme, accentColor?, navEnabled?, metaPixelId?}`. `theme` is one of `classic`,
`minimal`, `warm`, `pastel`, `editorial`, `mono`, `dark`, `midnight`; leave
`accentColor` out and the theme picks a matching accent. Every published page
carries the Rootr signature at the bottom.

`metaPixelId` is the numeric Meta (Facebook/Instagram) Pixel ID. When it is set, the
**published** page reports `PageView` on load and `Schedule` when a visitor completes a
booking in a `booking` block, so ads can be measured in Meta. The editor never loads the
pixel. Send `""` to turn it off. `config` is replaced as a whole on every update, so
resend the other keys with it.

Publishing is the ordinary path: `POST /v1/nodes/:id/publish` → `rootr.io/p/{slug}`.
**Publishing a page to the web needs the Team plan or above.** A Free workspace can build,
edit and share pages inside the workspace, but `publish` (and `PATCH …/public` with
`{"isPublic":true}`) answers `403 PLAN_UPGRADE_REQUIRED` (messageKey
`error.plan.pagePublishRequiresTeam`) and nothing changes. If the workspace drops to Free
after publishing, the public address (and its live-data / form-blocks / booking-blocks
side routes) answers `403 PAGE_PUBLISH_REQUIRES_TEAM` with no page content, and
`public-status` reports `isPublic:false, closed:"PAGE_PUBLISH_REQUIRES_TEAM"`. The
publication is kept — upgrading to Team reopens the same URL without publishing again.

**Visit tracking (GA-style, stored in the workspace).** Turn it on and the published page
records visits, scroll depth (25/50/75/90%), which blocks were seen, clicks, form and booking
steps and time on page — into **ordinary nodes** you read with the usual tools, not a separate
analytics screen. Next to the page a folder `<page> · 방문 분석` (`Analytics`) appears with:
a `LOG` (one entry per visitor action; columns event, visitor, session, new visitor, channel
— paid/search/social/email/referral/direct — utm source/medium/campaign/content/term, referrer,
device, browser incl. in-app (Instagram/KakaoTalk…), OS, country (looked up from the IP; the IP itself is never stored), screen, scroll %, block,
seconds, domain, conversion), a `DATABASE` "일별 방문"/"Daily visits" (one row per KST day:
visitors, sessions, new visitors, page views, avg seconds, read half, read to end, clicks,
form submits, bookings, conversions, conversion rate — refilled every 15 minutes by the
worker) and a `PAGE` dashboard of live charts over both. Conversions = sessions with a
completed form or booking. Only the **published** address records (editor preview and the
in-app view never do); custom domains record into the same page. No cookies; a visitor is a
random tag that differs per page; IPs are not stored; bots are dropped.
- `GET /v1/pages/:id/analytics` — `{enabled, folder, log, daily, dashboard, lastEventAt, rolledUpAt, last7d:{visitors,sessions,conversions}}`.
- `POST /v1/pages/:id/analytics` `{ "enabled": true, "locale"?: "ko"|"en" }` (`docs:write`, WRITE on the page and on its parent) — creates the folder and nodes on first enable (column names follow `locale`); `{ "enabled": false }` stops recording and keeps every node.
- `POST /v1/pages/:id/analytics/refresh?days=90` — recount the daily table now.
- Read the numbers: `GET /v1/databases/:daily` rows, `GET /v1/logs/:log/entries` / stats, or the dashboard's `live-data`.
- Scaffold: a PAGE node may carry `page.analytics: true` (+ `page.analyticsLocale`).

MCP: `rootr_create_page`, `rootr_read_page`, `rootr_append_page_blocks`,
`rootr_update_page`, `rootr_update_page_block`, `rootr_read_page_live_data`, `rootr_page_analytics`.
CLI: `rootr page stats|track|recount <page>`.
In-app assistant: `build_page`, `read_page`.

## Recordings — audio → speaker-labeled transcript → summary

`RECORDING` is a first-class node type for anything spoken the team needs as
text later: meetings, interviews, customer calls. Three separate steps, in this
order — **nothing runs automatically**, so no AI credit is ever spent without
someone asking for it:

1. **Store the audio.**
   `POST /v1/recordings/:id/audio?filename=&mimeType=&durationSec=`
   (`docs:write`) with the raw bytes as the body
   (`Content-Type: application/octet-stream`, max 100MB). Counts toward
   storage quota only. Status becomes `UPLOADED`.
2. **Transcribe.** `POST /v1/recordings/:id/transcribe` (**AI-credit
   metered**) queues speech-to-text with speaker diarization; status goes
   `TRANSCRIBING` → `READY` (poll `GET`). Call it again any time to redo it.
3. **Summarize.** `POST /v1/recordings/:id/summarize`
   `{ format?: 'summary'|'onepager', locale?: 'ko'|'en' }` (**AI-credit
   metered**) writes a markdown document as a sibling `DOCUMENT` node and
   returns `{ docId, format }`. Two formats, two documents (one never
   overwrites the other):
   - `summary` (default) — short minutes to skim: one-line outcome,
     participants, key points, decisions, action items.
   - `onepager` — the detailed briefing for someone who was NOT in the
     meeting: background, per-topic prose with quotes, a decisions table with
     rationale, an owner/due action table, risks and a timeline. Costs more.

Other endpoints: `POST /v1/workspaces/:ws/recordings`
`{ name?, parentId?, path?, icon?, expectedSpeakers? }` to create the node,
`GET /v1/recordings/:id` for the full detail, and
`PATCH /v1/recordings/:id` to relabel speakers:

- `{ "speakerNames": {"S1":"김개똥","S2":"홍길동"} }` renames voices in the
  CURRENT transcript. Merge-patch (send only the ones you're changing); the
  names apply everywhere, including the summary and the knowledge graph.
- `{ "expectedSpeakers": ["김개똥","홍길동"] }` is the who-will-be-in-the-room
  list used as a hint on the NEXT transcription: a voice that introduces itself
  ("팀장 이재민입니다") or is addressed by name comes back labeled with that name
  instead of `S1`. Voices the model can't place stay anonymous — a wrong name
  is worse than none. Settable at create time and from a scaffold
  (`recording: { expectedSpeakers: [...] }`), so a recurring-meeting slot
  carries its attendee list.

`GET` returns `status` (`EMPTY` → `UPLOADED` → `TRANSCRIBING` → `READY` |
`FAILED`), `audio`, `durationSec`, `speakerNames`, `expectedSpeakers`,
`summaryDocId`, `onepagerDocId`, `error`
and `transcript.segments` = `[{ speaker, start, end, text }]` (times in
seconds from the start of the audio).

**Step 3 is optional and you may prefer to skip it**: read the transcript from
`GET` and write the summary yourself with your own model, then create the
document with the normal document API — same result, none of the workspace's
AI credits. The transcript is also mirrored into the knowledge graph, so
`rootr_ask` can answer questions about what was said in a meeting.

## Signed documents · research notes (전자결재 · 국가R&D 전자연구노트)

`SIGNED` is a markdown document that **freezes when it is submitted**. After that
the body, its attachments and the approval line cannot be changed by ANY route
(REST, collab socket, version restore, import, MCP — the lock sits on the single
write funnel, not on individual endpoints), every signature carries an Ed25519
signature over the frozen content hash plus an RFC 3161 timestamp, and each
signature is hash-chained into a per-workspace ledger. Signed documents cannot be
deleted — 30-year retention (`onDelete: Restrict`), so a folder delete that would
take one with it is refused too.

Use it whenever the content has to be *provable*, not merely stored: 결재/승인
문서, 국가R&D 연구노트, 점검 기록, 회의 확인서. The Korean national R&D research-note
guideline asks for exactly three things and these are them: ① 전자서명 ② 시각
자동기록(Time Stamp) ③ 위·변조 확인.

**The one thing an agent cannot do is sign.** The confirmation code goes to the
signer's own mailbox, and that code is the only evidence a *person* pressed sign.
Always: request the code → **ask the human for the 6 digits** → send them. Never
invent one (403; five wrong tries kill the code; re-requesting inside 30s is
refused).

```bash
# 1) create — body + approval line in one call (order of steps = signing order)
curl -X POST "https://rootr.io/api/v1/workspaces/$WS/signed-docs" -H "x-api-key: $KEY" \
  -H 'Content-Type: application/json' -d '{
    "path": "/연구노트/2026-08-25 실험기록", "createParents": true,
    "content": "## 오늘 한 일
...", "mode": "RESEARCH_NOTE",
    "reviewerUserId": "<연구책임자 userId>" }'
# reviewerUserId만 주면 "기재자(만든 사람) → 점검자" 두 단계가 자동으로 짜인다.
# 직접 짜려면: "approvalLine": [ { "label":"기재자","members":[{"userId":"u1","role":"AUTHOR"}] },
#                                { "label":"부서장","rule":"ANY","members":[{"userId":"u2"},{"userId":"u3"}] } ]
# 워크스페이스 밖 사람은 메일 주소로: { "label":"거래처","members":[{"email":"kim@corp.com","displayName":"김철수"}] }
# 한 사람은 userId 아니면 email 하나만 — 둘 다 주면 400.

# 2) 본문은 올리기 전까지 평범한 문서처럼 고친다 (PUT /v1/documents/:id 등)

# 3) 올리기 — 본문이 언다. 올리기와 서명은 **다른 일**이다.
#    올리기 자체는 쓰기 권한이면 된다. code 는 올리는 사람이 1단계 서명자일
#    때만 필요하다(그때는 첫 서명이 함께 찍히므로). 1단계가 밖의 사람(메일
#    결재자)뿐이면 code 없이 올라간다.
curl -X POST "https://rootr.io/api/v1/signed-docs/$ID/submit" -H "x-api-key: $KEY" \
  -H 'Content-Type: application/json' -d '{}'
# 내가 1단계 서명자라면:
curl -X POST "https://rootr.io/api/v1/signed-docs/$ID/request-code" -H "x-api-key: $KEY"
curl -X POST "https://rootr.io/api/v1/signed-docs/$ID/submit" -H "x-api-key: $KEY" \
  -H 'Content-Type: application/json' -d '{ "code": "123456" }'
# code 를 빠뜨렸는데 필요했다면 403 REAUTH_REQUIRED 로 알려 준다 — 헷갈리면
# 그냥 빼고 불러 보고, 그 답이 오면 그때 사람에게 6자리를 물어보면 된다.

# 4) 다음 사람은 request-code 후 sign, 문제가 있으면 reject(사유 필수)
curl -X POST "https://rootr.io/api/v1/signed-docs/$ID/sign"   -d '{ "code":"..." }' ...
curl -X POST "https://rootr.io/api/v1/signed-docs/$ID/reject" -d '{ "code":"...", "comment":"근거 자료가 빠졌습니다" }' ...

# 5) 증명 — 로그인 없이도 열려 있다(본문은 안 내려온다)
curl "https://rootr.io/api/v1/signed-docs/$ID/verify"
# → { contentIntact, allSignaturesValid, allTimestamped, ledgerIntact, signatures:[...] }
```

**Signing from outside the workspace (공개 서명).** Put an `email` on an approval
member instead of a `userId` and that person needs no Rootr account. On submit
they get a mail with a link to `${origin}/sign/<token>` — one person, one
document, read-only. **The link alone signs nothing**: signing still needs a
6-digit code sent to that same mailbox, so a forwarded or leaked link is not
enough. When every signature is in, each outside signer is mailed a copy they can
print. These three routes take no auth (the token IS the key):
`GET /v1/sign/:token` (document + my turn) · `POST /v1/sign/:token/request-code` ·
`POST /v1/sign/:token` `{ code }` · `POST /v1/sign/:token/reject` `{ comment }`.

Other endpoints: `GET /v1/signed-docs/:id` (state: 결재라인 진행 + 서명 목록 +
`canSign`) · `PUT /v1/signed-docs/:id/approval-line` (올리기 전에만; 잠긴 뒤에는
409 `SIGNED_DOC_LOCKED`) · `POST /v1/signed-docs/:id/research-note-preset`
`{ reviewerUserId, noteMeta? }` · `POST /v1/signed-docs/:id/reopen` (아무도 서명
안 한 초안만) · `POST /v1/signed-docs/:id/revise` `{ note }` (서명된 문서는 고치는
게 아니라 개정본을 낸다 — 원본은 SUPERSEDED로 남는다) ·
`GET /v1/workspaces/:ws/signed-docs?pendingMine=true` (내 차례인 것만) ·
`POST /v1/workspaces/:ws/signed-docs/request-code` + `.../bulk-sign`
`{ nodeIds, code }` (한 코드로 최대 100건 — 연구책임자가 "이번 주 미점검 12건"을
문서마다 열지 않고 처리하는 통로). **초안(DRAFT)도 함께 처리한다** — 올리기용
코드를 문서마다 따로 받을 필요가 없다. 초안이면 올리고, 올리는 사람이 1단계
서명자면 그 자리에서 도장까지 찍는다. 건별 결과의 `did`가 `"submitted"` /
`"submitted+signed"` / `"signed"` 중 무엇이었는지 말해 준다. 올리기는 본문을
되돌릴 수 없게 얼리므로 **정말 그 문서들이 맞는지 확인하고 부를 것** · `GET /v1/workspaces/:ws/ledger/verify`
(원장 전체 재계산).

MCP: `rootr_create_signed_document`, `rootr_read_signed_document`,
`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`,
`rootr_bulk_sign_documents`, `rootr_verify_ledger`.
CLI: `rootr sign new|show|line|code|submit|sign|reject|revise|verify|list|bulk|ledger`.

### What a row opens as — one row at a time

A DATABASE row's **detail page** does not have to be a plain document. It can be a
SIGNED record, a SPREADSHEET, a WHITEBOARD, a PRESENTATION, a RECORDING, a FORM or
an ISSUE_TRACKER, and **rows in the same table may each be a different kind** — a
회의 table can hold recordings and signed circulars side by side.

- **This one row** — `POST /v1/database-rows/:rowId/page { "type": "RECORDING" }`.
  Returns `{ nodeId, type }`; that node is a normal node, so write it with the
  usual endpoints. If the row already has a page it comes back unchanged — the kind
  is not altered retroactively, so choose it when you create the page.
- **The table's default** — `rowPageType` at create time, or
  `PATCH /v1/databases/:id { "rowPageType": "SIGNED" }`. Set it when the person asks
  for a table whose rows are all one kind ("회의 기록 표, 행마다 녹음"). There is no
  screen for this — **you are the one who sets it**; the person then sees it marked
  "기본" in the picker that opens with an empty row. Only affects rows created from
  then on.
- **Reading it back** — every row carries `pageNodeType`, the kind actually
  attached. Judge by that, never by the table default.
- **Attaching something that already exists** —
  `POST /v1/database-rows/:rowId/page { "nodeId": "<node>" }`. Use this whenever the
  content is already in the tree ("이 회의록을 그 표 행에 걸어줘"). **Never copy a
  document into a row** — link it, or the same text lives in two places and both go
  stale. The node is not moved: it stays where it is, the row points at it, and
  deleting the row later leaves it alone (only a page *born* in the table is trashed
  with its row — and not even then if another row still points at it). The same node
  may be linked from **several rows**, in the same table or different ones — one
  회의록 can hang off both the 회의 table and the 프로젝트 table.
  `DELETE /v1/database-rows/:rowId/page` detaches without deleting.

So **a table whose every row is a signed record** (실험 기록 대장, 점검 대장, 결재
대장) is `rowPageType: "SIGNED"`, and one exceptional row inside it can still be a
plain document. Rows whose signed page is already signed cannot be deleted (the row
delete is refused before anything is removed).

MCP: `rootr_create_row_page` (with `type` **or** `nodeId`), `rootr_unlink_row_page`, `rootr_set_row_page_type`.
CLI: `rootr db row-page <rowId> --type RECORDING | --node <경로> | --unlink`, `rootr db row-page-type <표> SIGNED`.
Scaffold: a seed row takes `pageType` (make one) or `pagePath` (link one that exists).

### Add, change or delete MANY rows at once

`POST /v1/databases/:id/rows/bulk { "rows": [ { "이름": "홍길동" }, … ] }` adds many
rows in one call — use it instead of looping `POST rows`, which leaves a half-filled
table when one call fails. Column keys may be property **names** or ids.
`PATCH /v1/databases/:id/rows/each { "updates": [ { "rowId": "…", "values": { … } }, … ] }`
patches many rows where **each row gets its own values** (the plain `PATCH rows` below
puts the SAME values on every row).

**Make a load idempotent with `upsertKey`.** Add `"upsertKey": "<칸 이름 또는 id>"` to
`rows/bulk` and a row whose key value already exists is **updated instead of duplicated**,
so the same request can be sent any number of times with the same result. Use it for every
migration and every sync from an outside system: without it, retrying after a partial
failure double-loads — 20,000 calls split into three parallel batches, one batch failed on
a bad timestamp, the retry filtered "already loaded" by querying, and **903 rows landed
twice**. Nothing surfaces that; it was caught only by counting against the source. The key
column must be a plain stored column (text/number/date/select) — a formula, rollup or
relation is refused, and so is a row whose key is empty. The response then carries
`{ created, rowIds, updated, updatedRowIds }`.

**A workbook with one sheet per record** — 783 sheets, one per site; 1,281, one per
interview. `POST /v1/workspaces/:ws/databases/import/sheets { "xlsx": "<base64>",
"dryRun": true }` folds it into ONE table. `mode` is `"vertical"` (a sheet IS a row:
label on the left, value to its right) or `"header"` (every sheet repeats the same header
row; their data rows are merged and the sheet name becomes a column — that is the month,
or the branch). Omit `mode` and the server works it out. **Always dry-run first** and show
the detected mode, columns and first rows: folding 783 sheets the wrong way costs far more
to undo than to check. Also takes `sheetNameColumn`, `skipSheets`, `headerRow`,
`databaseId` (load into an existing table) and `upsertKey`. Columns land as text so a
phone number does not lose its leading zero — change the types afterwards.
MCP: `rootr_import_folded_sheets`.

`PATCH /v1/databases/:id/rows { "rowIds": [...], "values": { "작성일": { "start": "2026-08-01" } } }`
writes the same values onto every listed row; `POST /v1/databases/:id/rows/bulk-delete { "rowIds": [...] }`
deletes them. Both are **all-or-nothing**: if one row is locked, signed, owned by
someone else, or not in this database, nothing changes and the error names it — a
batch never half-succeeds. Max 500 rows per call. Reach for these whenever someone
says "한 번에" — 잘못 들어간 날짜 일괄 수정, 묶음 삭제.

MCP: `rootr_bulk_create_rows`, `rootr_bulk_update_rows` (same values), `rootr_bulk_update_rows_each` (per-row values), `rootr_bulk_delete_rows`.
CLI: `rootr db rows-new <표> --json '[{…},…]'` (or `--file rows.json`), `rootr db rows-set <표> --ids a,b --values '{"작성일":{"start":"2026-08-01"}}'`, `rootr db rows-each <표> --json '[{"rowId":"…","values":{…}},…]'`, `rootr db rows-rm <표> --ids a,b --yes`.

### Required reading (읽음 확인)

Put a read requirement on a DOCUMENT for one notice, or on a DATABASE/FOLDER to
require everything inside — progress then rolls up per person ("안의 문서를 몇 개
읽었나"). `GET|PUT|DELETE /v1/nodes/:id/read-requirement` (PUT takes
`{ userIds, dueAt, requireExplicitAck }` and replaces the whole roster);
`POST /v1/nodes/:id/read` and `POST /v1/nodes/:id/read-ack` record **your own**
reading — never someone else's. Setting or recording needs a key that acts as a
real person (a PAT); a connector key with no user attached is refused.
On a folder/table each person only has to read what **they can open** (`targets[].readTotal`,
`completed`) — on an "own rows only" table that is their own row pages plus shared documents.
People who cannot see every document inside get only `completed` for others (no counts).

MCP: `rootr_read_requirement`, `rootr_set_read_requirement`, `rootr_clear_read_requirement`.
CLI: `rootr readreq <표|문서> [--users a,b] [--due <ISO>] [--ack] [--clear]`.

### Forms — question types

18 question types: `text` `textarea` `number` `select` `multi_select` `checkbox`
`date` `email` `phone` `url` `time` `rating` `scale` `csat` `nps` `matrix`
`ranking` `file`. `email`/`phone`/`url` are format-checked server-side (a field
named "이메일" of type `text` checks nothing). `select`/`multi_select`/`matrix`/
`ranking` need `options`; `matrix` also needs `rows`. Options may be plain strings
(`["가","나"]`) or `{name,color}` — a missing colour defaults to grey.
`rating`/`scale` take `min`/`max` (2–10).
**Number range (blocks the form):** a `number` field takes `min` and/or `max` (any finite numbers, decimals ok,
`min ≤ max`) and an optional `rangeMessage` (≤ 200 chars). An answer outside the range is **refused** — 400 with
`rangeMessage` or the default "「나이」은(는) 15 이상 80 이하로 적어 주세요." — on every submit path (public link,
`POST /v1/forms/:id/responses`, `rootr_submit_form_response`, `rootr_update_form_response`), and the published
form shows the message under the question and will not submit. e.g. `{ "name": "나이", "type": "number", "min": 15,
"max": 80, "rangeMessage": "만 15세 이상만 신청할 수 있습니다." }`. This is separate from a column `validate` rule on
the linked table, which only warns.
**Pick from another table (`relation`):** `{ "name": "방문 지점", "type": "relation", "relationDatabaseId"?: "<표 id 또는
/경로>", "multiple"?: true, "publicPick"?: { "enabled": true, "showProps"?: ["지역"], "filter"?: [{ "propId": "모집중", "op": "is",
"values": ["true"] }] } }`. Respondents search the table and pick rows; omit `relationDatabaseId` to use the table that the
response table's relation column (same name, or the field map) points to — that column's `relationFilter` always applies.
The answer is stored as `{ id, title }` (an array when `multiple`) and becomes a real link in the relation column; a relation
column takes ONLY a `relation` question (the mapping reports a text question there as `how: "unfit"` with `why`, and
`PUT …/mapping` refuses it). Options: `GET /v1/forms/:id/relation-options?field=<fieldId>&q=` (members who can READ the
table: whole table, 30 rows, the table's identify line). **Public** pages get a list only when `publicPick.enabled`
(`GET /v1/public/forms/:token/relation-options`, `/v1/public/nodes/:slug/form-relation-options`,
`/v1/public/nodes/:slug/form-blocks/:blockId/relation-options`): a 2+ character search is required, ≤ 20 rows, only the title
and `showProps` (≤ 2) are returned, 30 requests/min; otherwise 404. "Own rows only" tables return nothing publicly, and the
form's creator must still be able to read the table. On submit the ids are checked (exists, visible to the submitter or
publicly pickable, meets the conditions) — otherwise 400. Public question payloads omit `relationDatabaseId`/`showProps`/
`filter`. CLI: `rootr form pick <form> <question> [search]`; MCP: answer with ids from `rootr_pick_rows`.

`file` takes ONE file by default; set `multiple: true` to take several (`maxFiles`
1–20, default 10). The answer is `{ id, filename, size }` for a single-file question and
an **array** of those for `multiple` (a lone object is wrapped; duplicates by `id` are
dropped; more than `maxFiles` is refused). Sending several files to a single-file
question is refused rather than silently keeping one. On the published page each file
goes up through the upload endpoint first; from the API/MCP/CLI upload with
`POST /v1/attachments/upload?workspaceId=&filename=` (`rootr_upload_attachment`, `rootr attach`)
and pass the returned `{ id, filename }` as the answer — or let
`rootr form submit <form> --files '{"<질문id>":["a.pdf","b.pdf"]}'` do both.
A linked table/sheet/XLSX export gets the file names (comma-separated) in a text column.

`allowImages: true` on a `text`/`textarea` question lets respondents paste, drop or pick
images into their answer. The answer stays a **string**; each image sits inside it as
markdown `![name](<app>/api/v1/attachments/<id>/raw?name=…)`, so a linked text column,
sheet or webhook receives it unchanged. A form whose only upload reason is
`allowImages` accepts images only on the upload endpoint (png/jpg/gif/webp/heic/avif; no SVG).

Per field: `help` (hint line under the question), `placeholder`, `page` (split a long
form into pages — the public page then shows a progress bar), `hidden` (not shown;
filled from the URL `?이름=값` — use it to record where a signup came from), and
`showIf: { fieldId, equals }` (show only when an earlier answer matches). A `date` field
shows a start date plus an optional end date; set `range: false` to ask for ONE date only. A question
hidden by `showIf` is skipped in the required check — otherwise only people who
answered one way could submit at all.

### Forms — locks, limits and completion

A FORM's `config` carries these:
`permissions: { editLock: "managers"|"open", responseScope: "own"|"all" }` — by
default only managers edit the questions and each person sees only their own
responses (휴가 사유 같은 것은 이 기본값을 그대로 두세요); and
`mirror.defaults: { <칸>: value }` — extra values stamped onto the row a response
creates, for columns the person did not answer. Use it to start a 신청 at "상신 중"
so a manager has something to move to 승인/거절. What the person answered always wins.
A default of `"@me"` becomes the logged-in submitter's name (person column → `[name]`,
title/text → name; left empty for anonymous submissions) — this is how a 휴가 신청 row
records who applied. `"@today"` / `"@today+7"` work for date columns.

Also on `config`:
`intro` / `thankYou` (markdown above the form and after submitting — put the date,
venue and fee here instead of cramming them into question labels),
`redirectUrl` (send people onward after submitting),
`notifyEmails: string[]` (email these when a response arrives — **without it nobody
knows**; up to 10), `confirmEmailField` + `confirmEmailBody` (mail the respondent),
`closesAt` (ISO) and `maxResponses` with `closedMessage` (stop accepting after a
date or a headcount — enforced on submit, not just hidden in the UI),
`webhookUrl` (POST each response; a Slack incoming-webhook URL works as-is),
`theme` (`clean|paper|dark|vivid|bento|brutal` — the **same six moods a published
DATABASE uses**; it now paints the whole public form page, not just a stored value,
and the owner can pick it in the app under 공유 → 디자인), `cover`, `logo`,
`oncePerPerson` (one response per person — matched by signed-in account, else by the
answer in `confirmEmailField` or the first `email` question; a second try gets 403
`ALREADY_SUBMITTED`. Fully anonymous answers can't be matched, so they are not blocked).

**Updating `config` merges** — you send only the keys you want to change and the rest
survive; send `null` for a key to clear it. (It used to overwrite the whole object, so
changing one limit wiped the intro, theme and webhook.)

A form published to `/p/{slug}` and the older `/f/{token}` share link now render the
**same body** — intro, pages, cover, logo, file questions, closing message and the
chosen theme. (`/f/` used to draw its own bare list of questions, so a form looked
different depending on which link you opened.)

MCP: `rootr_create_form`, `rootr_update_form`, `rootr_read_form`.
CLI: `rootr form new <경로> --fields '<json>' [--collect db|sheet]`,
`rootr form show <path|id>`, `rootr form set <path|id> --fields|--config '<json>'`,
`rootr form submit <path|id> --values '<json>' [--files '{"<질문id>":["a.pdf","b.pdf"]}']`.
Scaffold: `form: { fields, config, collectInto }` on a node.

A published FORM is **fillable** — visitors submit at `/p/{slug}`, and files go up
through `POST /v1/public/nodes/:slug/form-uploads` (10MB each, executables refused,
one file per request — a `multiple` question uploads each file then submits the array).
Old `/f/{token}` share links keep working: they redirect to `/p/{slug}` once the form
is published, and go back to their own page if it is unpublished. Embed it anywhere
with `<iframe src=".../p/{slug}?embed=1">` — that strips our header and clone chip.

## Publish anything to a public URL

Any node except a FOLDER can go out at `rootr.io/p/{slug}` — a DATABASE (visitors
get a searchable table and a **clone** button that drops a real, working table into
their own workspace), SPREADSHEET, WHITEBOARD, FORM (**fillable** — visitors submit),
PAGE (a block-assembled web page — see *Pages*), ISSUE_TRACKER,
LOG, CRM, RECORDING (transcript only), SIGNED, DOCUMENT.
Every type publishes on the Free plan **except PAGE**, which needs Team (Free → `403
PLAN_UPGRADE_REQUIRED`; see *Pages*). With `includeChildren` on Free, PAGE nodes
underneath are skipped and the response carries `skippedPagesRequireTeam: <count>`.

`POST /v1/nodes/:id/publish` · `PATCH /v1/nodes/:id/public` · `GET /v1/nodes/:id/public-status`
(MANAGE — use an account key/PAT, not a workspace-scoped one). Public read is
`GET /v1/public/nodes/:slug` with no auth; `.../children` lists what is published
underneath; `.../clone` copies it into the caller's workspace.

**Sub-pages.** `{"includeChildren": true}` publishes the **whole subtree** —
grandchildren included — each getting its own URL, listed on the parent page. Leave
it off and only that one node goes out; its sub-page names do not even appear.
Closing the parent, turning the switch back off, **moving a child out of the subtree**,
or deleting the parent all close the pages that went out because of it. Pages the
owner published on their own are never touched. Moving something INTO a published
parent does **not** publish it — closing is safe, opening is not.

**What never goes out**, whatever you publish: a table's person / attachment /
relation columns, the documents attached to its rows, form responses, recording
audio, CRM contacts and deal amounts, signer names on a signed document. Rows and
entries are capped at 500 per page and the page says so when it truncates. A page
can be locked with a password (the content is not sent at all until it is entered),
given an expiry, hidden from search, or have cloning refused.

A published DATABASE does not have to look like a table. Pick a `layout` — one of
`table`, `cards`, `gallery`, `list`, `board`, `timeline`, `calendar`, `chart`,
`ranking` — and a `skin` — one of `clean`, `paper`, `dark`, `vivid`, `bento`,
`brutal`. Some layouts need a column to exist: calendar/timeline need a date
column, board needs a select or status column, ranking needs a number column,
chart needs either. A layout whose column is missing falls back to the table and
says why. The two are stored separately, so setting one leaves the other alone.

MCP: `rootr_publish_node`, `rootr_set_node_public`, `rootr_node_public_status`.
CLI: `rootr publish <노드> [--children] [--off] [--status] [--layout <배치>] [--skin <분위기>]`.
REST: `PATCH /v1/nodes/:id/public` with `{"design":{"layout":"board","skin":"paper"}}`.
Documents keep their own richer path (skins, edit proposals) — `rootr_publish_document`.

## Custom domains — open a published page or document at your own domain (내 도메인 연결)

A published PAGE **or DOCUMENT** can be served at the customer's own domain (`www.customer.co.kr`,
`blog.customer.co.kr`) as an ordinary website: `/` shows it, `/{child}` its published child PAGE and
DOCUMENT nodes (the path comes from the child's name; they form the top menu), no `/ko` prefix,
canonical/OG URLs on that domain, no Rootr signature. A document opens in its public skin with the site
menu instead of the Rootr bar; links in it to sibling public documents are rewritten to the site paths.
Team plan and up (Free → `403 PLAN_UPGRADE_REQUIRED`). Workspace ADMIN/OWNER only.

Two kinds (`kind` on every domain):
- **FREE** — `{name}.rootr.site`: no DNS, no payment, `ACTIVE` immediately. Lowercase a-z, 0-9 and
  hyphen, 3–30 chars, no leading/trailing hyphen, globally unique, up to 3 per workspace
  (`400 FREE_SUBDOMAIN_LIMIT`). Reserved: www, api, app, admin, mail, connect, origin, docs, help, status,
  login, billing… and anything containing "rootr" or "inspirio".
  `GET /v1/workspaces/:ws/domains/subdomain?name=acme` → `{hostname, available, reason}` with
  reason ∈ invalid | reserved | taken | mine | limit.
- **PAID** — your own domain: **$10/month per domain, $8/month billed yearly ($96/year)**, one slot of the
  "Custom domain" add-on (its own Paddle subscription; quantity = slots). Slots = bought + granted by Rootr
  (invoiced B2B customers). Adding a domain when no slot is free:
  - add-on active → `402 CUSTOM_DOMAIN_CHARGE_CONFIRM_REQUIRED` (`details.quantity` = new quantity). Tell
    the person the price; after they agree, resend with `"confirmCharge": true` → quantity +1, prorated.
  - no add-on → `402 CUSTOM_DOMAIN_PAYMENT_REQUIRED` with `details: {slots, used, needed, priceUsd,
    billingUrl}`. A person must start the add-on in Settings → Billing (or from the page's Share →
    "Connect domain" window, which opens the checkout). Agents cannot pay.
  - add-on payment failed → `402 CUSTOM_DOMAIN_PAYMENT_PAST_DUE` (fix the card first).
  Removing a paid domain lowers the quantity (prorated credit); removing the last one schedules the add-on
  to end at the end of the period (the slot stays until then) — see `billing` in the DELETE response.
  If the add-on is canceled or stays unpaid for 7 days, the newest domains beyond the remaining slots become
  `SUSPENDED` (visitors get 404; the owner is notified) and reopen as soon as payment returns.

The customer adds **one DNS line**: `CNAME`, name `www`, value `connect.rootr.site`. Rootr
registers the name with its certificate provider and issues HTTPS by itself. Only when the same
hostname was registered before by a *different* workspace is one extra `TXT` line required
(`_rootr-verify.www`, value in `records`) — so a CNAME left behind cannot be taken over.
A bare root domain usually cannot hold a CNAME: connect `www.` and forward the root
(`provider.forwarding` explains how at that provider).

- `GET /v1/workspaces/:ws/domains/detect?host=www.customer.co.kr[&provider=gabia]` → where the
  DNS is managed (from the name servers: gabia, whois, cafe24, hostingkr, inames, dotname,
  cloudflare, godaddy, namecheap, route53, squarespace, onlydomains, wix, or `other`), the record,
  `isApex`/`suggestedHostname`, and `provider` = click-by-click `steps`, `quirks`,
  `forwarding` in `ko` and `en`. Relay the steps to the human as they are.
- `POST /v1/workspaces/:ws/domains` `{"hostname":"www.customer.co.kr","rootNodeId":"<PAGE or DOCUMENT id>","provider":"gabia"}`
  → `{id, kind:"PAID", status:"PENDING_DNS", records:[{type,name,host,value,ttl}], guide, billing}`.
  Free address: `{"subdomain":"acme","rootNodeId":"<PAGE id>"}` (or `"hostname":"acme.rootr.site"`) →
  `{kind:"FREE", status:"ACTIVE", records:[]}`.
- `POST /v1/workspaces/:ws/domains/:id/check` → re-check now. `status`: `PENDING_DNS` →
  `PENDING_CERT` (HTTPS being issued) → `ACTIVE`; `ERROR` when the certificate failed or was
  blocked. `lastErrorCode` ∈ DNS_NOT_FOUND, DNS_WRONG_TARGET (`observedTarget` = what is there
  now), TXT_MISSING, CERT_PENDING, CERT_FAILED, CF_BLOCKED, CF_ERROR, CF_OFF; `lastError` says it
  in plain Korean. The server also re-checks every 5 minutes and notifies the person who
  registered it (in-app + email) when it goes live.
- `GET /v1/workspaces/:ws/domains` (with `rootNode` name, `kind`) + `slots`: `{total, paid, granted, used,
  available, suspended, addon:{active, interval, status, cancelAt, pastDue}, free:{used, limit, suffix}, price}` ·
  `DELETE /v1/workspaces/:ws/domains/:id` (→ `billing: {action: decreased|cancel_scheduled|failed}` for paid).
- `PATCH /v1/workspaces/:ws/domains/:id` `{"hostname":"www.right.co.kr","provider":"gabia"}` → change the name of an
  own domain that is not live yet (PENDING_DNS / PENDING_CERT / ERROR). The paid slot moves to the new name (no charge,
  no refund); the old one becomes REMOVED and the answer is a **new** domain (new `id`, `renamedFrom`, new records).
  ACTIVE domains and free addresses → 400 (remove and add instead).
- Billing: `GET /v1/workspaces/:ws/billing` → `customDomains` (same summary + `checkoutReady`); checkout
  `POST /v1/workspaces/:ws/billing/checkout` `{"planId":"custom_domain","seats":1,"interval":"month"|"year"}`
  (`400 CUSTOM_DOMAIN_NOT_CONFIGURED` until the price exists, `400 CUSTOM_DOMAIN_ADDON_EXISTS` when one is active).

MCP: `rootr_list_custom_domains`, `rootr_add_custom_domain`, `rootr_check_custom_domain`,
`rootr_rename_custom_domain`, `rootr_remove_custom_domain`. When a domain goes live (and whenever its root is
re-published) the address is pinged to IndexNow. CLI: `rootr domain list | detect <domain> | add <domain> <page|doc> [--confirm-charge] |
add --subdomain <name> <page> | available <name> | check <id> | rename <id> <new domain> | remove <id>`.

## Search description & link-preview image (검색·링크 미리보기)

Every published document and node (not decks) can carry an owner-written **search description** and a
**cover image**. Unset → the description is the first ~160 characters of the body, the image is a generated
Rootr title card.
- Documents: `PATCH /v1/documents/:id/public` `{"seoDescription":"…","seoImage":"<attachment id>"}` →
  stored as `publicConfig.seo` `{description, imageAttachmentId}`.
- Other nodes (pages, tables, forms…): `PATCH /v1/nodes/:id/public` with the same two fields → `seo` on the
  status and on the public payload.
- `seoDescription`: up to 300 characters (search results show ~160); `null`/`""` clears it.
  `seoImage`: an **image** attachment (`POST /v1/attachments/upload`) of the **same workspace**, upload finished;
  `null` clears it. Anything else → 400. 1200×630 landscape fits best.
- Used for `<meta name="description">`, `og:description`, `og:image` (`/p/{slug}/opengraph-image` renders the
  cover), JSON-LD, and the same tags on a connected custom domain. Changing them pings IndexNow.
- Public pages are server-rendered: the first HTML already contains the full body, so crawlers that do not run
  JavaScript (Naver, Bing…) index the text, not just the title.

MCP: `rootr_set_document_public` / `rootr_set_node_public` with `seoDescription`, `seoImage`.
CLI: `rootr publish <path|id> --description "<text>" --cover <image file|attachment id|none>` (a file is uploaded first).

## Send a document to an email address (문서 보내기 · 문서함)

Any node — document, folder, table, spreadsheet, whiteboard, deck, form, issues, log,
CRM, recording, page, signed document — can be **sent** to 1–20 email addresses. Sending
is **not a copy**: it gives that email address access to the **original** node (and,
for a folder or a page with sub-pages, everything under it) at the level you choose —
`read` (view, default) · `comment` · `write` (edit). The recipient always sees the
latest version; with `write` their edits land in the original. You can give at most
your own level (never manage), and only workspace members can send (a recipient cannot
pass it on). The recipient's access is always capped by the **sender's current** access:
items inside a sent folder that the sender cannot see stay closed, and if the sender
leaves the workspace or is downgraded, the recipient's access shrinks with it (within
60 seconds).

**The email address owns it.** A Rootr account whose **verified** email matches
(case-insensitive) opens the original from its inbox with that access — even if it is
not a member of your workspace. Such a guest gets exactly that node: never your
workspace tree, members, search, chat, or other nodes, and cannot move, delete,
duplicate, share, publish or change permissions of it. Without an account, the email
link (`https://rootr.io/{locale}/m/{token}`) asks for the recipient's email address first and
then shows the current content **read-only** (filtered like a public page: no person /
attachment / relation columns, no booking visitors); signing up with that address puts
it in the inbox. Recipients with an account also get an in-app notification
(`DOC_RECEIVED`).

- `POST /v1/nodes/:id/send` (`docs:write`; WRITE on the node as a member — the same bar
  as sharing) with `{"to": ["a@example.com"], "access": "read|comment|write", "message":
  "optional, ≤2000"}` → `{"batchId", "access", "items": [{"id", "to", "emailed", "resent"}]}`.
  Sending again to the same address updates its access/message (`resent: true`) instead
  of adding a second grant. `emailed: false` (+ `error`) means the email failed; the
  access still stands. 400 `DOC_MAIL_INVALID_ACCESS` for manage/unknown, 403
  `DOC_MAIL_ACCESS_ABOVE_OWN` / `DOC_MAIL_GUEST_CANNOT_SEND`, 409 `PUBLIC_OWN_ROW_PAGE`
  for an item that comes from an "own rows only" table row.
- `GET /v1/doc-mail?box=inbox|sent&limit=&cursor=&q=` (`docs:read`) — your mailbox,
  summaries only (`access`, `original`: live|trashed|deleted, `nodeId`/`workspaceId`
  of a live original, `member` = whether you belong to that workspace), plus `unread`.
- `GET /v1/doc-mail/:id[?node=<child id>]` (`docs:read`) — the original's **current**
  content, read-only: `contentMd` for documents, `payload` (`kind` says the shape) for
  the rest, `children` (items inside; pass one as `node`), `access`, `openUrl` (the
  original in the editor). Works with any of the recipient's keys, even one bound to
  another workspace. Opening a received one marks it read. Someone else's id → 404.
- `PATCH /v1/doc-mail/:id` `{"access":"comment"}` (`docs:write`, sender only) — change
  the recipient's access.
- `POST /v1/doc-mail/:id/revoke` (`docs:write`, sender only) — the recipient loses access
  immediately and sees only the title and `revoked: true`; the email link answers 410.
- `DELETE /v1/doc-mail/:id[?box=inbox|sent]` (`docs:write`) — remove it from **your**
  mailbox (a removed received one stops opening for your account).
- `GET /v1/public/doc-mail/:token` (no auth) → only `{senderName, needsEmail: true}`.
  `POST /v1/public/doc-mail/:token/open` `{"email": "…"}` → the read-only content if the
  email matches; a wrong email and an unknown link give the same 404; 10 wrong tries per
  link lock it for 15 minutes (429); 410 `DOC_MAIL_REVOKED` / `DOC_MAIL_ORIGINAL_DELETED`.

Sending and reading belong to a person, so the caller must resolve to an account: a
sign-in session, an account key (PAT), or a workspace key. A workspace key without a
user (e.g. the remote MCP connector) acts as the member who created it; otherwise 403
`DOC_MAIL_ACCOUNT_REQUIRED`.

```bash
curl -X POST "https://rootr.io/api/v1/nodes/$NODE_ID/send" \
  -H "x-api-key: $ROOTR_API_KEY" -H "Content-Type: application/json" \
  -d '{"to":["partner@example.com"],"access":"comment","message":"Q3 numbers, as discussed"}'
curl "https://rootr.io/api/v1/doc-mail?box=inbox" -H "x-api-key: $ROOTR_API_KEY"
```

**Know when documents arrive (any client).** Every authenticated API response carries
`X-Rootr-Doc-Mail-Unread: N` (unread received documents of the caller's verified email).
Send `X-Rootr-Doc-Mail-Channel: <name>` (e.g. `cli`, `mcp`, your bot's name) and new
ones not yet announced on that channel come back once as `X-Rootr-Doc-Mail-New: N` +
`X-Rootr-Doc-Mail-New-Items` (base64url JSON `[{id,title,sender}]`, max 5); a successful
response marks them announced for that key + channel. The MCP server appends
"📬 New documents received (…)" to any tool result when there is news, and the CLI prints one
line to stderr after any command (off: `ROOTR_MAIL_NOTICE=0`).

**Webhooks for your own mailbox** (per account, not per workspace — a workspace webhook would
let that workspace's admins read members' inboxes):
- `POST /v1/doc-mail-webhooks` `{"url":"https://…","events":["doc_mail.received","doc_mail.revoked","doc_mail.read"],"name":"…"}`
  → includes `secret` **once**. Public http(s) only (private / loopback / metadata addresses
  are refused, also re-checked at every delivery; redirects are not followed). Max 5.
- `GET /v1/doc-mail-webhooks` · `DELETE /v1/doc-mail-webhooks/:id` ·
  `POST /v1/doc-mail-webhooks/:id/test` (a signed `doc_mail.test`) ·
  `GET /v1/doc-mail-webhooks/:id/deliveries`.
- Events: `doc_mail.received` (to the recipient — only for a verified email; re-sends too),
  `doc_mail.revoked` (to the recipient), `doc_mail.read` (to the sender, first open).
  Body `{"event","data":{id,title,nodeType,senderName,senderEmail,recipientEmail,message,access,
  sentAt,apiUrl,appUrl,…},"sentAt"}` — never the content; GET `apiUrl` with your key for it.
  Verify `X-Rootr-Signature: sha256=HMAC_SHA256(secret, raw body)`; also `X-Rootr-Event`,
  `X-Rootr-Delivery`. Retried up to 5 times; 10 failures in a row turn the webhook off.

MCP: `rootr_send_document` (`access`), `rootr_list_doc_mail`, `rootr_read_doc_mail`,
`rootr_set_doc_mail_access`, `rootr_revoke_doc_mail`, `rootr_add_doc_mail_webhook`,
`rootr_list_doc_mail_webhooks`, `rootr_remove_doc_mail_webhook`, `rootr_test_doc_mail_webhook`.
CLI: `rootr send <노드> --to a@x.com,b@y.com [--access read|comment|write] [--message "…"]` ·
`rootr mail [inbox|sent]` · `rootr mail show <id> [--node <child>]` ·
`rootr mail access <id> <level>` · `rootr mail revoke|hide <id>` ·
`rootr mail webhook add <url> [--events …]|list|rm <id>|test <id>`.

## Visitor booking — turn a published table into a scheduling page

A published DATABASE can take bookings from people who have no Rootr account. The
visitor opens the public link, picks a date, picks an open time, fills in their name
and email, and **their booking becomes one row in that table**. Nothing else to wire up.

Rules the owner sets: which weekdays, which hours, how long one booking is, a gap kept
before and after, how many hours of notice, how far ahead, a per-day cap, days off,
**blocked times**, and the timezone everything is read in.

There are **two gaps**. `bufferMin` is kept around bookings made through this table;
`calendarBufferMin` is kept around every event **already on the connected Google Calendar**
(travel time to an outside meeting). With `calendarBufferMin: 60, bufferMin: 0` a 14:00–15:00
meeting on Google closes 13:00–16:00, while online bookings can still sit back to back. Bookings
this table wrote to Google count as bookings, not existing events. Both are 0–240 minutes; a
table that never set `calendarBufferMin` uses `bufferMin` for both.

Blocked times close part of the open hours, once or on a repeat — `blockedTimes`:
`{"kind":"date","date":"2026-10-05","start":"13:00","end":"15:00"}` (one afternoon),
`{"kind":"daily","start":"12:00","end":"13:00"}` (lunch, every day),
`{"kind":"weekly","weekday":1,"start":"09:00","end":"11:00"}` (Monday mornings),
`{"kind":"weekly","weekday":5}` (every Friday — leave both times out to block the whole
day). Sending the list replaces it. The owner's own `label` on a rule never reaches
visitors.

Rootr emails the result to **both sides** — `notifyVisitor` (on by default) mails the visitor
when their booking is confirmed, still pending, or declined; `notifyEmails` is the owner-side
list. Visitors can cancel themselves from a link in that email — the link carries a secret
only their booking's email has, so no account is needed; turn it off with
`allowVisitorCancel: false` and links already sent stop working.
All-day events in the busy calendars block the whole day (`google.allDayBusy`, on by default) — Google marks
all-day events "free", so busy times alone would miss vacations, trips and holidays; working-location, birthday and
declined events never block. Set `google.meet` to also create a Google Meet room per booking (needs
`google.writeCalendarId`, no extra OAuth scope); the link lands in a "회의 링크" column
Rootr creates for you and in both emails. Bookings are confirmed instantly, or arrive as
"승인 대기" and wait for the owner (a pending booking **still holds its slot**; declining
frees it). Name and email are always asked; any other column can be added to the form.

What the server guarantees, so you do not have to: the times a visitor sees and the
times the server accepts come from the same calculation — there is no "the button was
there but it was refused". Two people clicking the same slot: exactly one wins (a
per-table lock). Other people's bookings are **not** in the public payload, and cloning
the page is blocked while booking is on, so visitor names and emails never leak.

Google Calendar is optional. Once the owner connects their account, busy times on the
calendars they pick block those slots (only free/busy is read — never event titles), and
each confirmed booking is written to the calendar they choose, then updated or removed if
the booking changes. If Google cannot be reached, the page refuses to show times rather
than offering ones that may already be taken. Connecting requires a **person** to approve
once in a browser — an API key cannot do it — but listing and wiring calendars is tooled.

Booking rides on publishing, so publish the table first (or let the scaffold do both).

MCP: `rootr_get_booking`, `rootr_set_booking`, `rootr_booking_slots`,
`rootr_list_google_calendars`, `rootr_connect_google_calendar`, `rootr_disconnect_google_calendar`.
CLI: `rootr booking show|set|slots <표>`, `rootr gcal list|connect|calendars|disconnect`.
REST: `GET/PUT /v1/nodes/:id/booking`; visitors use `GET /v1/public/nodes/:slug/booking/slots`
and `POST /v1/public/nodes/:slug/booking`.
Scaffold: put `booking: { enabled: true, … }` on a DATABASE node — it publishes the table,
creates the date/email/status columns it needs, and accepts `askFields` by column NAME.

## Build a workspace (scaffold) — make a real tool, not a pile of markdown

Turn a request like "프로젝트 관리 워크스페이스 만들어줘" into a genuinely useful
workspace. **Do NOT dump thin markdown files** (that is worse than a template).
Rootr gives you building blocks — compose them freely (they are NOT fixed presets;
you design the columns, views and document structure):

- **DATABASE** — typed columns + views (table / board / calendar / timeline). Use
  for anything trackable or tabular: tasks (board grouped by status), requirements
  & WBS (table), risks (table), milestones (timeline).
- **DOCUMENT** — free-form markdown. Use for narrative: an overview, a decision
  log, a requirements *spec* — any structure you design (headings, tables,
  checklists).
- **SPREADSHEET** — a grid with formulas and computed totals. Use when the content
  needs *calculation*, not just storage: a budget, a financial model, a
  reconciliation, an estimate/capacity sheet.
- **WHITEBOARD** — a freeform visual canvas. Use for things that are spatial, not
  tabular or linear: flow diagrams, brainstorming, architecture sketches, a user
  journey map.
- **FORM** — a fillable form that collects input from people outside the tree
  (optionally into a DATABASE via `targetDatabaseId`). Use for intake: a
  risk/bug submission form, an application, a survey, a request queue.
- **ISSUE_TRACKER** — GitHub-style issues (#numbers, open/closed, labels,
  custom types, assignees, sub-issues, comment threads, two-way webhooks).
  Use for bug/work tracking with a lifecycle — see "Issue trackers" above.
- **CRM** — companies, contacts (lifecycle stage + auto lead score), a
  multi-pipeline deal kanban (custom stages with win probability → weighted
  forecast), an activity timeline and follow-up tasks. Use instead of DATABASE
  whenever it's stage-tracked *relationships* over time, not one-off records —
  a sales pipeline, an agency's client roster, a hiring pipeline, fundraising,
  partnership/BD — see "CRM" above.
- **RECORDING** — an audio recording with a speaker-labeled transcript and a
  one-press summary document. Use for anything spoken the team needs as text
  later: recurring meetings, interviews, customer calls, workshops. Scaffold it
  as an empty slot (audio arrives later) — see "Recordings" above.
- **SIGNED** — a markdown document that freezes on submit and collects ordered
  signatures with timestamps, hash-chained so tampering is provable; undeletable.
  Use where the record must be *provable*: 결재/승인 문서, 국가R&D 연구노트, 점검
  기록 — see "Signed documents" above.
- **FOLDER** — groups any of the above.

Pick each block because it fits, not to check a box — a workspace doesn't need
every type. If a request genuinely needs something none of these can express, say
so — that is a gap to build into Rootr, not a reason to fake it with markdown.

### There are no templates — design it from scratch (this is not optional)
`plan` does **not** classify your request and hands you **no** structure. There is no
catalogue of domain skeletons behind it — that was removed on purpose. A bakery, a
dental clinic, a yoga studio and an SRE team need different things, and no fixed set
of skeletons could ever hold them; force-picking the nearest one means building
someone else's business. What you get back is the method:

- `analyzeFirst` — what to work out about how the job ACTUALLY runs, before you
  design anything: the daily and weekly rhythm, what piles up (each of those is a
  table), what moves through stages, what arrives from outside, where money is added
  up, what causes trouble when it is late, and above all **what is unique to this
  job** — that last one is the difference between a real tool and a generic template.
- `designRules` — how to turn the answers into structure: nouns that pile up become
  DATABASEs, "one A has many B" becomes a relation, stages become select + board,
  dates become calendar, outside input becomes FORM + `collectInto`, calculation
  becomes SPREADSHEET, counting becomes rollup, and the whole thing ends with a
  how-to-use manual.
- `buildingBlocks` — every block the product actually has, with a one-line "when to
  use". Weigh all of them for *this* job; you do not need to use every type.
- `questionPolicy` — ask the user **3-10 questions that you write yourself**. None
  are supplied. `dimensions` is a checklist of angles not to miss (scope, scale,
  current pain, existing tools, cadence, integrations, constraints, success metric),
  not a questionnaire to read out. Never re-ask what the request already states, and
  every answer must visibly change what you build.
- `loop` — the whole sequence, in order.

Only after the user answers do you design and `apply` the tree.

### Finish: write the manual, then RUN what you built
Three steps people skip. They are what separates a real tool from a pile of grids:

1. **Write the manual.** Put one DOCUMENT in the tree that says how to run this thing:
   the daily / weekly / monthly routine naming the actual tables and views, how the
   tables link to each other, where form answers land, what causes trouble if it is
   late — and **what the owner still has to fill in**: the assumptions you made
   because you could not ask them, the example rows to replace with real values, the
   notification address only they can decide. A manual that does not name at least
   half the tables you built is not this workspace's manual, and `review` says so.
2. **RUN it** with `POST /v1/workspaces/:ws/scaffold/selftest` (`rootr_test_workspace`,
   `rootr scaffold test`). This is the unit-test step and it catches what neither review
   can: relations pointing at rows that do not exist, rollups and formulas that produce
   nothing on real rows, board/calendar/filter views referencing columns that are gone,
   a form whose question names do not match the target table's columns (those answers
   vanish with no error), sheet formulas left uncomputed or sitting at #REF!/#DIV/0!.
   It writes nothing. Fix every `fail` and run it again. A workspace can score 100 on
   both reviews and still fail here — that is the whole point.
3. **Re-check the built shape** with `POST /v1/workspaces/:ws/scaffold/review-built`
   (`rootr_review_workspace`, `rootr scaffold built`). `scaffold/review` grades the
   tree you *designed*; this grades what actually exists. A design can score 100 and
   still land broken — a form whose answers go nowhere, a view whose filter vanished,
   rows that never linked. Pass `rootPath` to grade only the subtree you just added.

### Steps
```bash
# 1) plan — get the design METHOD (no templates, no skeletons; it does not classify).
#    Use the workspace-less form to consult BEFORE creating a workspace.
curl -X POST "https://rootr.io/api/v1/scaffold/plan" -H "x-api-key: $KEY" \
  -H 'Content-Type: application/json' -d '{ "intent": "프로젝트 관리 워크스페이스 만들어줘" }'
# → { message, analyzeFirst, designRules, buildingBlocks,
#     questionPolicy:{min:3,max:10,dimensions,instruction}, loop }
# Work out how the job runs (analyzeFirst), then GENERATE 3–10 questions of your own
# and ASK the user. Then design from designRules. Nothing here is a template.

# 2) review — check the tree you designed BEFORE building it. Creates nothing.
curl -X POST "https://rootr.io/api/v1/scaffold/review" -H "x-api-key: $KEY" \
  -H 'Content-Type: application/json' -d '{ "tree": [ ... ] }'
# → { score, counts, findings:[{level,at,rule,message}], summary }
# Fix every finding at level "error", then review again. Loop until it is clean.
# No task/order/customer/record to track and nothing to calculate — a design-standards
# doc, per-medium reference folders, a pure knowledge base? Add "mode": "docs" to the
# body. It drops the DATABASE/system rules (no-database error, table-count/relation/
# board/calendar substance floor, table-driven manual check) and only grades the
# documents themselves (empty/too-short). Do NOT invent a DATABASE just to satisfy
# the default rules when the request never needed one.

# 3) create the structure YOU design:
#    • new workspace (needs workspaces:create scope, account-scoped key):
curl -X POST "https://rootr.io/api/v1/scaffold/workspace" -H "x-api-key: $KEY" \
  -H 'Content-Type: application/json' -d '{ "name": "제품 개발", "intent": "...", "tree": [ ... ] }'
#    • into an existing workspace:
curl -X POST "https://rootr.io/api/v1/workspaces/$WS/scaffold/apply" -H "x-api-key: $KEY" \
  -H 'Content-Type: application/json' -d '{ "rootPath": "/제품 개발", "tree": [ ... ] }'

# 4) RUN it — the unit-test step. Does anything actually work? Writes nothing.
curl -X POST "https://rootr.io/api/v1/workspaces/$WS/scaffold/selftest" -H "x-api-key: $KEY" \
  -H 'Content-Type: application/json' -d '{ "rootPath": "/제품 개발" }'
# → { ran, passed, failed, warned, checks:[{level,at,check,message}] }
# Fix every "fail" and run again.

# 5) re-check the SHAPE of what got built (not the tree you sent).
curl -X POST "https://rootr.io/api/v1/workspaces/$WS/scaffold/review-built" -H "x-api-key: $KEY" \
  -H 'Content-Type: application/json' -d '{ "rootPath": "/제품 개발" }'
```

### The `tree` — each node is a FOLDER (children), DATABASE (database), DOCUMENT
### (content), SPREADSHEET (spreadsheet), WHITEBOARD (whiteboard), FORM (form),
### PAGE (page), ISSUE_TRACKER (issues), CRM (crm), or SIGNED (signed)

A DATABASE node (this is how you build a task board, a requirements table, etc.):
```json
{
  "name": "Tasks",
  "database": {
    "properties": [
      { "id": "title",  "name": "Task",     "type": "title" },
      { "id": "status", "name": "Status",   "type": "select",
        "options": [ {"name":"To Do","color":"gray"}, {"name":"In Progress","color":"blue"}, {"name":"Done","color":"green"} ] },
      { "id": "prio",   "name": "Priority", "type": "select",
        "options": [ {"name":"High","color":"red"}, {"name":"Med","color":"yellow"}, {"name":"Low","color":"gray"} ] },
      { "id": "owner",  "name": "Owner",    "type": "person" },
      { "id": "due",    "name": "Due",      "type": "date" }
    ],
    "views": [
      { "id": "board", "name": "Board", "type": "board", "config": { "groupBy": "status" } },
      { "id": "table", "name": "All",   "type": "table" }
    ],
    "rows": [
      { "values": { "title": "요구사항 정의", "status": "To Do", "prio": "High" } },
      { "values": { "title": "개념 설계",     "status": "To Do", "prio": "Med"  } }
    ]
  }
}
```
Rules: exactly one property must be type `title` (its position is up to you). Types:
title, text, number, select, multi_select, **status**, date, checkbox, url, **email**, **phone**,
person, files, **relation**, **formula**, **rollup**, **created_time**, **last_edited_time**,
**created_by**, **last_edited_by**, **unique_id**.
· select/multi_select/status take `options:[{name,color}]` — status options also take
  `group` ∈ todo | in_progress | done, which is what lets a board show "완료된 것들".
· relation takes `relationDatabaseId` (the node id of the table it points at); its row
  value is an array of **row ids** (titles are resolved for you on read). Add
  `reverseName` to make it **two-way**: the linked table gets a matching column with
  that name, and filling either side fills the other one. Use it whenever both tables
  need the link (calls ↔ applicants) — a one-way column leaves every aggregate on the
  other side wrong until somebody backfills it by hand, and nothing warns you. Existing
  one-way columns keep working; `PATCH .../columns/:propertyId { reverseName }` pairs one
  later, and `{ "reverseName": "" }` unpairs without deleting either column.
· formula takes `formula`, e.g. `"{수량} * {단가}"` or `"if({금액} >= 5000, \"큰 건\", \"작은 건\")"`.
  Functions: if, concat, length, upper, lower, contains, abs, round, floor, ceil, min, max,
  dateBetween, now, empty. Anything else is refused when you save the table — there is no
  `eval` behind this.
· rollup takes `rollup: { relation, property?, function, where? }` with function ∈ count |
  count_values | sum | average | min | max | show_original | percent_checked.
  `where` filters the LINKED rows **before** aggregating —
  `[{ property, op, value? }]` with op ∈ is | is_not | contains | not_contains | is_empty |
  is_not_empty | gt | gte | lt | lte. That is how "how many of this applicant's calls were
  no-answer" is built: `{ relation: "콜", function: "count", where: [{ property: "결과",
  op: "is", value: "부재" }] }`. A rollup can also gather a **formula** column in the linked
  table, and `min`/`max` work on **date** columns (that is "last call date"). Only a
  rollup of a rollup is refused — that would chase calculations across tables without end.
  `sameKey: "<key column>"` (title/text/phone/email/url) also gathers what the OTHER rows with
  the same key value link to, each linked row once — "all calls of this person" when one phone
  number has several rows. Keys compare like dedupe (phone numbers by digits). Nothing is copied
  between rows; in "own rows only" tables a member only counts rows they can see.
· unique_id takes `prefix` → rows read as "TASK-42". Numbers are never reused, so a deleted
  row's number does not come back.
· The last seven types are **filled in by the server**: they take no row value and a write
  that sets one is refused (400). They are recomputed on every read, so they never go stale.
View types: table, board, gallery, calendar, timeline, **list**.
A **board** view needs `config.groupBy` = a select/status property id; **timeline**/**calendar**
need `config.dateProp` (+ optional `endDateProp`). A **calendar** also takes
`config.calendarScale` ∈ week | month | year — the span it opens on (default month;
`year` lays out all twelve months at once). Match it to the table: `week` for a roster,
`year` for anniversaries and leave.

A DATABASE node may also carry `database.buttons` — the action buttons pinned above
the table, built in the same call so the user does not have to add them by hand:
```json
"buttons": [
  { "label": "접수", "icon": "📥", "steps": [
      { "kind": "add_row", "values": { "Status": "To Do", "Owner": "@me", "Due": "@today+7" } },
      { "kind": "ai_fill", "target": "created", "propId": "요약",
        "prompt": "{Task}를 한 문장으로 요약해." },
      { "kind": "open_row" }
  ] }
]
```
Put one on any table where people would otherwise retype the same setup every time.
Steps run in order and each receives the row the one before it made; values accept
`@today`, `@today+7` and `@me`, resolved when the button is pressed. See the button
section above for every step kind and the run endpoint.
**Creating a database** — use `POST /v1/workspaces/:ws/databases` (MCP
`rootr_create_database`, CLI `rootr db create`) with the columns in display
order; `properties[].id` and `views[].id` are filled in for you when omitted, and
a view's `config.groupBy`/`dateProp` may name a column instead of its id.
**Column names must be unique within a table** (trimmed, case-insensitive) — two columns named
the same get a 400 on create, on column add and on save; imports (Notion/CSV/xlsx) instead rename
the later one to `Name (2)` and say so in the result. Pass
`rows: [{ values: { "컬럼이름": 값 } }]` to seed the first rows in the same call.
Building a table by creating it empty and then adding columns one at a time makes
the column order depend on the order of your calls — don't.

**Changing the columns of a database that already exists** — do NOT rebuild the
whole `properties` array with `PATCH /v1/databases/:id` (whatever you leave out
is deleted, and a concurrent editor's column disappears with it). Edit one column
at a time and the server merges:
`POST /v1/databases/:id/columns` `{ name, type, options?, relationDatabaseId?, formula?, rollup?, prefix? }`
→ the created column with its id ·
`PATCH /v1/databases/:id/columns/:propertyId` `{ name?, options?, searchExcluded? }` (rename / re-list choices /
exclude from the search index) ·
`DELETE /v1/databases/:id/columns/:propertyId` — also removes the column from the value lines of buttons/automations in this
and other tables (add_row into this table, update_rows of its rows, ai_fill of it; an update_rows left with no values is dropped) and
reports them as `deleteCascade: { buttons, automations, templates, stoppedRules }` (`stoppedRules` = this table's automations whose
condition watched it — they stop; `templates` = `{칸}` placeholders still naming it, left as text). Saving the whole `properties`
array without a column does the same. `?preview=1` returns that `deleteCascade` WITHOUT deleting (ask the user first).
Adding a column never touches existing rows — they read empty until you fill them.
A column's `type` is immutable (changing it would rewrite every row): add a new
column and move the values instead. The `title` column cannot be added twice or deleted.
MCP: `rootr_add_column`, `rootr_update_column`, `rootr_delete_column`.

**Renaming a column cascades** (any door: the column PATCH, the whole-`properties` PATCH, MCP
`rootr_update_column`, CLI `rootr db rename-col`, the app's column menu). Everything that names the column is
rewritten in the same transaction: formulas in the table (`{col}` and `prop("col")` — exact column only, quoted
text untouched), button/automation templates `{col}` `{col+1}` `{relation.col}` (also in tables that link here),
rollups in other tables (pinned to the column id), linked form questions (kept connected by id — the question text
is not changed) and page live blocks (liveTable/liveStats/liveChart column names). Rename the column first — a
formula that names a column which does not exist yet is still refused (400). The response carries
`renameCascade` `{ formulas, buttons, automations, rollups, forms, pages, warnings, summary }`; `warnings` lists
what could not follow (e.g. "폼 「…」 질문 n곳의 연결이 끊깁니다" when two form questions would land on one column).
Preview without writing: `GET /v1/databases/:id/columns/:propertyId/rename-impact?name=<new name>` (MCP
`rootr_update_column` with `dryRun: true`). Views, relation conditions, dedupe, notifications, locks, row links and
booking settings store column ids and need nothing.

**Vector columns for agents** — `POST /v1/databases/:id/columns` `{ name, type: "vector", dimensions: 1536 }`
makes an embedding column. Fill it with `PUT /v1/databases/:id/vectors/:propId`
`{ items: [{ rowId, vector: [..] }] }` (≤500 per call, every vector exactly `dimensions` long, all-zero
vectors refused, every value must fit a 4-byte float — larger than about ±3.4e38 or too small to store (below about 1e-45)
answers 400 with the offending position; row write permission applies) and search it with
`POST /v1/databases/:id/vectors/:propId/query` `{ vector, topK?, minScore? }` → rows with `score` (cosine),
own-rows-only tables return only your rows. `GET /v1/databases/:id/rows/:rowId/vectors/:propId` reads one back,
`DELETE` removes it. Vectors are NOT row values (`values` refuses them) and never enter the search index.
Row listings carry `vectors: { rowId: { propId: dims } }` so you can see which rows are filled.
MCP: `rootr_set_row_vectors`, `rootr_query_vectors`.

**Filtering by meaning** — a view/personal filter `{ propId: "__similar__", op: "similar", values: [rowId] }`
keeps only rows that stand out as similar to that row (same rule as `rootr_find_similar_rows`), sorted most
similar first unless you set a sort. `POST /v1/databases/:id/rows/query` then also returns
`similar: { state, sourceRowId, scores }` — `state` "gone" means the row was deleted or you can't see it,
"no-text" means the source row has nothing to compare (empty, or only excluded columns filled).

**Keeping a column out of the search index** — `searchExcluded: true` on a column (add or patch;
table managers only, 403 otherwise; UI name "검색 색인에서 제외" / "Exclude from search index") keeps its values out
of the search index: the row chunks behind `rootr_ask` / AI explore / `rootr_find_similar_rows`, the table's
shadow document and row-page embeddings. Turning it on removes already-indexed values **before the call returns**, and
deleting the column then re-adding it with the same id keeps it excluded (only a manager can turn it off).
It is NOT a read permission: people see the column in the table, and tools that read the table as that person —
the in-app AI chat (@reference, read_database), a button's ai_fill step, formula/rollup columns, MCP/REST reads —
still see the values. To hide values from people, use an "own rows only" table or a private node. Locked columns
(`lockedProps`, a write lock) and view-hidden columns ARE searchable, because members can
see those values in the table. Relation columns never put the linked row's title into
search (the linked table has its own permissions). Attachment (`files`) columns put the
FILE NAMES (never the URLs) into the row's search text — exclude the column to keep names such as
"연봉계약서_홍길동.pdf" out of the index.
**Long rows** — a row's search text is split on column boundaries into pieces of about 6KB (a single long cell is
split inside, each part keeping its `Column: ` label), and every piece is embedded on its own, so words near the
end of a long row are found too. Search and `rootr_ask` still return a row once (its best piece). A row is indexed
up to 8 pieces (~48KB); past that, long columns are trimmed evenly so every column keeps a share, and the row's
index entry is marked `clipped`.
Excluding the TITLE column also masks row-page document names (and the paths of documents under them) in the index —
AI search results and sources (`rootr_ask`, AI explore, hybrid search) show them as "Table › row", and AI search no longer finds a row page
by that name. Name/keyword search (the sidebar, `rootr_search`, REST `/workspaces/:ws/search`) still finds the page by its real name
for anyone who can read it — this is not a read permission. On an "own rows only" table the chat, document embeds and page live blocks show a
member only their own rows, like the table itself.

**Locking a table** (no Notion equivalent) — `PATCH /v1/databases/:id/permissions`
(MANAGE only) `{ schemaLock?: "open"|"managers", rowScope?: "all"|"own", lockedProps?: ["승인"] }`.
MCP: `rootr_read_database_permissions`, `rootr_set_database_permissions`. CLI: `rootr db lock`.

**"Own rows only" (`rowScope: "own"`) is one rule** — anything that comes FROM a row of such a table is visible only
to that row's author and the table's managers: the row page and everything under it, and anything made from them —
duplicates (also into another folder or workspace), signed-document revisions, recording summaries, form response
sheets/tables, whiteboard conversions, templates saved from them and nodes applied from those templates — the linked-row
titles a relation column shows, the row's entities and edges in AI explore / GraphQL, its search chunks, and the row's
comment threads (reading, writing, comment notifications and `comment.created` webhook deliveries — comments of a deleted
row stay visible to table managers only). A reply belongs to its parent's thread: a reply posted with only `parentId`
inherits the parent's `blockId` (the row), so it is stored, listed, notified and delivered under the same rule as the
thread it answers. A relation value may only point at rows the caller can see (an id you cannot see
answers 400 like a missing id; ids already linked on the row being edited are kept — by every edit entry: single-row and
bulk patches, and `upsertKey` lines that update an existing row). Duplicating rows (`POST …/rows/bulk-duplicate`) copies
only the relation links the caller can see: links to rows you cannot see are left out of the copy (the original keeps
them) and the response reports how many as `skippedRelationLinks`. Form responses pulled into a spreadsheet
(`FORMRESPONSES`/`formLink`) follow the form: once the form comes from such a row, its responses leave the sheet's
published copy, page blocks over the sheet and the sheet's search copy at that moment. Deleting the
row or trashing the table keeps it closed. The author always sees their own. Sub-documents and sub-tables people put
under the table (not made from a row) follow normal node permissions no matter which tool created them. Linking an
existing document that sits directly under the table to a row makes it that row's page only while linked (same rule);
unlinking restores its own permissions. A document elsewhere linked to a row keeps the permissions of where it sits.
Public access (no sign-in) never shows anything from an "own rows only" table — a visitor is neither the row's author nor
a table manager. On a public page, live blocks (number cards, charts, tables) over such a table show **0 rows and 0 totals**
(the response lists the block under `scoped` with `by: "public"`); a published "own rows only" table shows its columns but
no rows and no row count; and anything that came from a row of such a table (row pages, things attached to a row, their
copies) cannot be published — publish and share-link calls answer **409 `PUBLIC_OWN_ROW_PAGE`**, and an address published
earlier answers 404 like a missing one. A status read (`GET …/public-status`) never calls such an address public: it answers
`isPublic: false` with `closed: "PUBLIC_OWN_ROW_PAGE"` and a `closedReason` (plus `closedTableGone: true` when that table
was permanently deleted), and share-link lists mark those links with `closed`. The stored setting is kept, so the same address
reopens when the table is switched back or the item is detached; `PATCH …/public {"isPublic": false}` turns it off for good.
Permanently deleting an "everyone sees all rows" table releases what came from its rows — those nodes stay visible and stay
published. Signed-in reads are unchanged: managers see every row, members their own.
Names a non-manager puts **directly under** such a table (new documents, row pages, renames, moves, copies, restores,
folders created by path) always get a short random suffix (`"면담 · 3fa9c1"`), and path lookups answer 404 for row
pages you cannot see — so whether a hidden row's name exists can't be probed by name clashes or paths.
Node names never contain "/" — every entry that creates or renames a node (documents, tables, signed documents, templates,
scaffold trees, logs, CRM, …) answers 400 `name must not contain "/"`. Names the server derives from an existing node
(a form's response table/sheet, a signed-document revision, a recording summary, a whiteboard's table, an applied
template) are never rejected for that: a "/" inherited from an older name is replaced with a space.
A suffixed name is addressed **only by its full name**: the create response returns the real `path` (suffix included) — use
that path (or the id) for later reads and writes. The path without the suffix is not an alias for it; a path resolves to the
same node for everyone (or 404 when you cannot see it), and writing to the un-suffixed path again creates another document.
A node you cannot read at all (private or restricted for you, in a workspace you are not in, or in the trash) answers
**404 `Not found`** on every call that takes its id — the same answer as an id that does not exist, so ids cannot be
probed for hidden nodes (a comment, attachment or share link on such a node likewise answers like a missing one). **403**
means you can read the node but the call needs a higher level (WRITE/MANAGE).

**Notifying people about a table** (no Notion equivalent — there each person must watch
for themselves) — `GET/PUT /v1/databases/:id/notifications` (PUT needs MANAGE)
`{ watchers: [{ userIds, events: ["created"|"updated"|"deleted"],
filter?: { propId, op: "is"|"contains"|"changed", value? } }] }`. The filter matters:
notify on everything and people switch notifications off. A person is never notified
about their own change, and matching several rules still sends one notification.
MCP: `rootr_read_database_notifications`, `rootr_set_database_notifications`.
CLI: `rootr db notify`.

**Change proposals on a published document** — `rootr_list_document_commits`,
`rootr_merge_document_commit` (three-way merge, never an overwrite — the owner's
in-flight edits survive; conflicts are refused until you pass `force`),
`rootr_reject_document_commit`. Comments: `rootr_list_document_comments`
(public-page comments land in the same place), CLI `rootr comments`.
`schemaLock: "managers"` lets editors fill rows but not change columns/views;
`rowScope: "own"` means people only see rows they created (managers see everything) —
that is what makes a form-fed table usable for applications or reports; `lockedProps`
names columns only managers may edit (approval flags, final scores). Read the current
setting with `GET /v1/databases/:id/permissions`. Defaults are wide open, so tables
that existed before this behave exactly as they did.

**Showing different columns per view** — `PATCH /v1/databases/:id/views/:viewId`
(MCP `rootr_update_view`) `{ hiddenProps: ["금액","비고"] }` hides those columns in
THAT view only. Columns may be named or given by id; the title column can't be
hidden. Hiding never erases values — `hiddenProps: []` brings everything back.
Only the passed view is touched, unlike `PATCH /v1/databases/:id` which replaces
the whole `views` array.

**Board card fields** — `PATCH /v1/databases/:id/views/:viewId` `{ cardProps: ["면접예정일","연락처"] }`
(MCP `rootr_update_view` `cardProps`, CLI `rootr db view <표> <보드> --cards "면접예정일,연락처"`) picks the fields
each board card shows, in order — rollups and formulas included (only those are computed). `null` goes back to the
default (the first 3 stored fields with a value). Sorting a view by a rollup/formula column sorts by its value: dates
by date, numbers by number, a multi-value rollup by its earliest (asc) or latest (desc) value.

**Readability: alignment, wrapping, compact rows, frozen columns** — per COLUMN, `PATCH /v1/databases/:id/columns/:propId`
(MCP `rootr_update_column`, CLI `rootr db column <표> <칸> --align center --wrap on`; also accepted by `POST …/columns`
and in the `properties` of a create) takes `align: "left"|"center"|"right"` (text alignment in the table; default numbers
right, the rest left) and `wrap: true` (long text wraps inside the cell instead of being cut; the row grows). `null` resets.
Per TABLE VIEW, `PATCH /v1/databases/:id/views/:viewId` (MCP `rootr_update_view`, CLI `rootr db view <표> <뷰> --density
compact --freeze 2`) takes `density: "compact"|"normal"` (lower rows, smaller text — more rows on one screen) and
`frozenColumns: 0–3` (the first N VISIBLE columns stay put while scrolling sideways, like Excel's freeze panes; 0 or
`null` = off). Combine with `hiddenProps` and `colWidths` for an at-a-glance view:
`{ density: "compact", frozenColumns: 1, hiddenProps: ["메모"], colWidths: { "상호명": 160 } }`.
Grid lines per TABLE VIEW (CLI `--lines all --line-strength strong`): `gridLines: "rows"|"all"|"none"` (`rows` = horizontal
lines between rows only — the default look; `all` = a border around every cell, like a spreadsheet; `none` = no lines) and
`lineStrength: "light"|"strong"` (`strong` = darker lines so rows are easier to tell apart). `null` resets to the default.

**Data-entry views: hidden columns in the row page, pinned filters, entry row, one day at a time** — four more TABLE VIEW
settings on the same endpoint (`PATCH /v1/databases/:id/views/:viewId`, also `POST …/views`; MCP `rootr_update_view` /
`rootr_create_view`; CLI `rootr db view <표> <뷰> --row-hidden on --quick "지역,담당자" --entry-row on --day-pager 접수일`).
Columns may be named or given by id; `null` (or `false` / `[]`) turns each one off.
- `rowPaneShowHidden: true` — columns hidden in THIS view (`hiddenProps`) stay hidden in the table but show expanded when a
  row is opened (side pane / row page). Without it the row page folds every column hidden in any view under "N hidden"
  (and remembers each person's last open/close per table).
- `quickFilters: ["지역","성별","담당자"]` (up to 6) — pinned at the TOP of the filter panel with no operator picker: text-like
  columns filter by "contains", select/status by "is" (option chips), multi-select/person by "has", relation by picking linked
  rows, date by "on that day". Typing applies after a short pause; they combine with the regular filters below. A pinned
  column's filter is "only me" (this browser) by default unless the view already has a shared filter on it.
- `filtersPersonalOnly: true` — filters set in this view always apply only to the person setting them (no switch to share
  them). Filters are "only me" by default in every view anyway (the title search at the top included); this removes the switch.
- `entryRow: true` (or `"bottom"`; `"top"` puts it above the rows — for tables read newest-first, and rows made there stick to
  the top; in a view sorted descending they stick to the top either way) — the table always has one empty row. Typing a value into any of its cells creates the row then
  (pre-filled with the values the view's filters imply, exactly like the "new row" button), and a new empty row appears; Tab
  moves across, Enter / Tab past the last column starts the next row. Clicking or focusing alone creates nothing.
- `dayPager: { dateProp: "접수일" }` (a `date` column) — the table shows ONE day at a time: ◀ date ▶, "Today" and a date
  picker above the table; only rows whose date falls on that day are listed (combined with the view's other filters and applied
  server-side, so counts and paging are right on 10k+ row tables); rows created in the view get that day. "Search all dates"
  (or typing in its search box) lifts the day limit until cleared. View filters on the same date column are replaced by the
  pager. The chosen day is kept per view in the URL (`?day=YYYY-MM-DD`).

**Date columns: overdue red, time, range** — a date column shows past dates in red ONLY when it has
`highlightOverdue: true` (deadline-like columns; default off — 지원일/통화일시 stay plain). `allowTime: false` removes
the 「시간」 toggle and `allowRange: false` removes the 「기간」(end date) button everywhere (table cell, row panel);
values written afterwards are stored as a single date (the server drops the time / end date from any write — rows,
forms, buttons, automations, API). Existing values keep showing and can only be cleared. Same endpoint as above:
`PATCH /v1/databases/:id/columns/:propId { "highlightOverdue": true }` or `{ "allowTime": false, "allowRange": false }`
(MCP `rootr_update_column`; CLI `rootr db column <표> <칸> --overdue on --time off --range off`). Turning them on for a
non-date column is a 400.

**Same person entered twice (duplicates)** — turn on `dedupe: true` for a phone/email/name column
(`PATCH /v1/databases/:id/columns/:propId`, MCP `rootr_update_column`); phone numbers compare digits only.
`dedupeShow: [propIds]` picks what the warning shows about the EXISTING row (a relation column shows its latest 5
linked rows — e.g. the call log — with the total); omit it and status, notes, dates and rollups are chosen automatically.
`POST /v1/databases/:id/duplicates` `{ rowId }` or `{ values }` (MCP `rootr_find_duplicates`, CLI
`rootr db duplicates`) returns the matching rows with that preview and history. Then either
`POST /v1/databases/:id/rows/:rowId/merge` `{ into }` (MCP `rootr_merge_rows`, CLI `rootr db merge`: fills the
existing row's empty cells, unions relations, leaves a "🔁 <label>" comment, deletes `rowId`) or
`POST /v1/databases/:id/rows/:rowId/keep-duplicate` `{ from }` (MCP `rootr_keep_duplicate`: keeps both rows and
links them with comments). In the app the warning pops up whenever a detection column is filled — typed, by a button,
an AI fill step, an automation or a paste — and the row panel shows a banner for rows still sharing the value. A form
filled INSIDE Rootr by a signed-in member who can read the table warns before submit (`POST /v1/forms/:id/duplicates`
`{ values: {questionId: answer} }`; submitting with `duplicate: { mergeInto }` or `{ keepFrom }`); public form links
never get this — those submissions only leave a "possible duplicate" comment for the team.

**Came back again: carry the previous row into the new one** — `dedupeCarry` on the dedupe column
(`PATCH /v1/databases/:id/columns/:propId`, MCP `rootr_update_column`) keeps the NEW row and copies the earlier row's
values into it (the earlier row is untouched, nothing is linked):
`{ "dedupeCarry": { "label": "재등록", "auto": true, "exclude": ["접수일"], "latestBy": "접수일", "overwrite": ["상태"], "relations": false,
"mark": { "재등록 여부": true, "구분": { "map": { "A": "A(재등록)" }, "else": "재등록" } } } }`. `label` (≤30 chars, optional) names this
action for the table — toasts, merge comments and dialog titles use it; blank = the neutral default ("이전 정보 가져오기").
`auto: true` applies it on EVERY write path (row add, the moment a detection cell is first filled, forms, button/automation
`add_row`, REST/MCP/bulk, in-app chat) instead of asking; without it the duplicate dialog offers "이전 정보 가져오기" and
`POST /v1/databases/:id/rows/:rowId/carry-over` `{ from? }` (MCP `rootr_carry_over`) does it on demand. Only empty cells
are filled unless the column is in `overwrite`; computed columns and the detection column itself are never copied; relation
columns only with `relations: true`. Several earlier rows → the latest by `latestBy` (a date column) or creation time.
`mark` stamps values on the new row; `map` reads the value the new row came in with, `else` covers any value not in
`map`; missing select options are added. If the map column is still EMPTY when the row is carried (row added first and
filled later, or a multi-step button that writes the dedupe column before the map column), nothing is stamped yet — the first
non-empty value written to that column later gets map/else once, recorded under the same op (row history `via: dedupe:<opId>`,
so undoing that op also lifts the late mark and leaves the value the person typed); later
edits are left alone, and a column that never gets a value gets no mark. Row history records `via: dedupe:<opId>`;
responses carry `carried: { fromRowId, fromRowIds, copied, changedCount, nothingChanged, marked, label?, pending?, opId }`
(`pending` = map columns still waiting) and the write that resolves a pending mark returns `carryMarked: [column names]`.
Only rows the writer can see are used. Imports don't carry.

**Duplicate rules — carry or merge, and how each column combines** — the same `dedupeCarry` object also decides WHAT happens
when a same-value row comes in and HOW values combine. `action`: `"ask"` (the duplicate dialog asks; `askDefault` =
carry | merge_into_old | merge_all is preselected) | `"carry"` (= `auto: true`, copy into the new row) | `"merge_into_old"`
(fill the representative earlier row; the new row is deleted, or kept and linked with `keepNew: true`) | `"merge_all"`
(every same-value row → one representative row; the others deleted or kept linked). `sources`: `"all"` (default — per
column the most recent earlier row that HAS a value; a mostly empty latest row no longer hides older values) or `"latest"`
(only the latest earlier row). `strategy` (default for every column): fill_empty (default) | prefer_new | prefer_old | latest |
skip; `columns` overrides per column with those or max | min | sum (number) | earliest | latest_date (date) | union
(multi_select, relation, files, person) | `{ "append": { "sep": " / ", "datePrefix": true } }` (text, oldest first, duplicates
skipped) — a strategy on the wrong column type is a 400. Shorter re-registration notes: `"unique": true` keeps the same piece once
(even with different date prefixes); `"emptyText": "기존 메모 없음"` stands in for an earlier row whose text is empty;
`"history": { "format": "{date}지원", "dateFormat": "YY-MM-DD", "sep": ", ", "only"?: true }` adds ONE line listing each earlier
row's date in that shape ("26-10-12지원, 26-10-14지원" — rebuilt each time, earlier history lines are recognised and merged);
`only` copies no earlier text, just that line. `exclude` = skip and `overwrite` = prefer_old still work; relation
columns are skipped by carry unless chosen (they are two-way) and unioned by merges. `representative`: `"latest"` (default) |
`"oldest"` by `latestBy`/creation time; `representativeWhen: [{ "propId": "상태", "op": "is", "values": ["확정"] }]` picks
the first row matching all filters. `mark` and `label` apply to the row that stays. Example — gather everything into the
latest row: `{ "action": "merge_all", "latestBy": "등록일", "columns": { "나이": "latest", "메모": { "append": { "sep": "\n",
"datePrefix": true } }, "통화": "union", "상태": "latest" } }`. Preview without writing: `POST
/v1/databases/:id/rows/:rowId/dedupe-preview { rules?, fromRowIds? }` → `{ action, targetRowId, deleted, kept, fromRowIds,
columns: [{ column, strategy, before, after, from }], marked, pending, nothingChanged }` (MCP `rootr_dedupe_preview`, CLI
`rootr db dedupe-preview`; `dryRun: true` on carry-over/merge does the same). Apply: `POST …/rows/:rowId/dedupe { action?,
rules?, fromRowIds?, targetRowId? }` (MCP `rootr_dedupe_apply`). Every operation gets an `opId` (row history `via:
dedupe:<opId>`); `POST /v1/databases/:id/dedupe-ops/:opId/undo` (MCP `rootr_dedupe_undo`, CLI `rootr db dedupe-undo`) puts
the changed cells back and recreates deleted rows with the same ids. Automatic merges from row writes answer with
`deduped: { … }` (merges are not reported as `carried`); button/automation runs handle duplicates once after the run
(`deduped: [{ rowId, … }]`), so a later step never writes to a row a merge deleted.

**Duplicate rules by condition — `cases`** — one action for every earlier row cannot say "merge rows from the same day, only
carry from older ones". `cases: [{ when?, action, …overrides }]` (≤10) puts EACH earlier same-value row into the FIRST case whose
`when` matches (all given keys must hold): `within: { "column": "<date column>", "days": 0 }` (|new − old| ≤ days in KST
dates; an empty date on the new row counts as today, an empty one on the earlier row never matches), `same: ["<column>", …]`
(values equal after the dedupe fold — case/spacing/phone format; lists compare as sets) and `filters: [{ propId, op, values }]`
(view filters on the EARLIER row). No `when` = catch-all. Rows matching no case are left alone. A case may override
askDefault, sources, strategy, columns, keepNew, representative, representativeWhen, `mark` and `label` (top-level keys are the
defaults; a case's `columns` merge per column over the top-level `columns` — same column → the case wins; `mark` replaces
the whole top-level mark, so `"mark": {}` = no marks for that case). Mixed results: if any row lands in an `ask` case nothing happens
automatically (the dialog/preview applies that case's askDefault); otherwise merge cases run first in case order (each over its
own rows plus the new row), then carry cases fill the surviving row. The surviving row gets the mark and label of the first carry
case that has rows (no carry rows → the first merge case's). One `opId` covers everything; preview/apply responses add
`cases: [{ index, action, rowIds, label?, marks }]`. Example: `{ "latestBy": "등록일", "cases": [{ "when": { "within": {
"column": "등록일", "days": 0 } }, "action": "merge_all", "label": "같은 날 합침", "mark": {} }, { "action": "carry", "label": "다시
들어옴", "mark": { "다시 옴": true, "경로": { "else": "{value} (다시)" } } }] }`. A choice/override sent with the dialog
(`action` in the request) uses that single action instead of the cases.

**Mark templates** — `map`/`else` values may contain `{value}` = the value written in the new row's column:
`{ "경로": { "else": "{value} (다시)" } }` turns 「경로B」 into 「경로B (다시)」; a value that already has the template's shape
(same prefix/suffix around a non-empty middle) is left as is, so it never becomes 「경로B (다시) (다시)」. `map` is optional
when only `else` is given. New values are added to the select options when they are first written (deferred marks too).
If the new row's column is EMPTY and the surviving row has no value there, `else` is written right away with `{value}` left out
and spaces tidied (`"{value} (다시)"` → 「(다시)」); the mark stays deferred, so the first real value written later replaces it
with the template applied (「경로B (다시)」).

**Keep rows with the same key in step — `keySync`** — when a table keeps several rows for the same person/item (the same
phone/email/name came back on another day and was kept as a new row), `keySync` on the KEY column (title/text/phone/email/url;
dedupe need not be on) copies later CHANGES to the other rows with the same key: `PATCH /v1/databases/:id/columns/:propId`
(MCP `rootr_update_column`, CLI `rootr db column-set`) `{ "keySync": { "columns": { "상태": "mirror", "메모": "append",
"연락 기록": "items" } } }` (names or ids, ≤20 columns; null turns it off). Keys compare like dedupe (phone numbers by digits,
other text ignoring case/spacing). `mirror` = the changed value is copied as is (any stored column; clearing clears);
`append` (text/title) = only the newly ADDED text is appended to the end of the other rows on a new line, skipped if that row
already contains it; `items` (relation/multi_select) = items added in one row are added to the others and items removed are
removed (relations as add/remove deltas, so the two-way partner stays right). It runs after edits from the table, row panel,
bulk edits, buttons, automations, REST/MCP and links made from the other side of a two-way relation; it does NOT run when a row
is created (a new row's initial values never overwrite older rows — carrying old values into a new row is `dedupeCarry`'s
job), when the key itself changed, for imports/upserts, restores, merges or carries. Copied writes appear in row history as
`via: key-sync`, do not wake automations (the rule runs once, on the row that was changed) and are never copied again (no
loops). Tables with "own rows only" sync only rows created by the same person. A key shared by more than 50 rows is skipped
(placeholders like "-"). Existing differences are not back-filled — only changes from now on.
Relations are usually better SHOWN than copied (copying puts the same person into the other table several times and breaks
its titles/counts): `GET /v1/databases/:id/rows/:rowId?sameKey=1` adds `sameKey: { keys: [{ propId, propName, value }], rows:
[{ id, values, createdAt, backlinks }], relationTitles, relationTargets, backlinkTitles, backlinkDatabaseNames }` — the other
rows sharing a keySync key (newest first, ≤50, only rows the caller can see) with their relation values and the rows of other
tables pointing at them (one-way relations included). The row panel shows them as "other rows with the same …"; nothing is
written. For a column, use a rollup with `sameKey`.

**Column value checks (validation)** — `validate` on a column (`PATCH /v1/databases/:id/columns/:propId`, MCP
`rootr_update_column`). Rules **only flag** a wrong input — the value is always saved exactly as typed (never blocked, never
reformatted). The user writes the rule: `{ "kind": "pattern", "pattern": "[A-Z]{2}-\\d{4}", "flags"?: "i", "negate"?: true,
"message": "{name}: {value} is not an employee id" }` — the WHOLE value must match (`^…$` is added); `negate: true` flags
values that CONTAIN the pattern instead (e.g. a national-ID number in a memo). Patterns run on a linear-time regex engine, so a
catastrophic pattern cannot stall the server; back-references (`\1`) and look-arounds are refused (400), max 500 chars.
Starting points (email, URL, international/KR/US phone, postal codes, digits only, …): `GET /v1/value-rules/presets` — copy one
and edit it; formats differ per country/company, so the product does not fix them. Try a rule before saving:
`POST /v1/value-rules/test { rule, type?, values: [...] }` → `results: [{ value, ok, message? }]` (MCP
`rootr_test_value_rule`, CLI `rootr db rule-test`). Other kinds: `{ "kind": "range", "min": 21, "askDeleteRow": true }`
(number column), `{ "kind": "date" }` (text column reads as a date), `{ "kind": "birthdate", "min"?: 21 }` (text/date; also
740812; min/max = age). Checked on every NEW write — cells, row panel, forms (message names the question), REST/MCP/bulk
(`row` = line number), buttons/automations: the write succeeds and the response carries `warnings: [{ propName, value,
message, row? }]`; send `checkWarnings: true` (row PATCH, form submit) to get 422 `VALUE_WARNINGS` first and ask the person.
Reading rows (`GET …/rows`, `POST …/rows/query`, `GET …/rows/:rowId`) adds `issues: { [propId]: { message, askDeleteRow? } }`
to each row whose CURRENT values break a rule (omitted when none) — the app marks those cells inline (⚠ on the cell, a line
under the field in the row panel, a line under the question in forms); nothing pops up and nothing is blocked.
Older settings (`mode: "block"`, `normalize`, `kind: "mobile_kr"`) are still read; block now behaves as warn. Existing
values are never changed; `GET /v1/databases/:id/rule-violations` (MCP `rootr_rule_violations`) lists the ones that break a
rule. Sheet imports return `ruleIssues`.

**Picking linked rows — same-name people, fast search** — the relation picker (cell and row panel) and the relation
filter search the WHOLE target table: `POST /v1/databases/:targetId/rows/pick` `{ q, filters?, ids?, limit? }` (MCP
`rootr_pick_rows`, CLI `rootr db pick <표> 김영희`) → `{ rows: [{ id, title, subtitle }], total, hasMore }` — exact name →
names starting with q → names containing q → identify columns (last phone digits "5678"), newest rows first within a rank.
`subtitle` comes from the target table's TITLE column `identifyProps`: `PATCH /v1/databases/:id/columns/<titlePropId>`
`{ "identifyProps": [{ "propId": "연락처", "mask": "last4" }, { "propId": "지원일" }] }` (MCP `rootr_update_column`
`identifyProps`, CLI `rootr db identify <표> 연락처:last4,지원일`) — up to 3 columns (names or ids; relation/files columns
refused), `mask: "last4"` shows only `***-5678`, `null` turns it off. Filters on a relation column match the linked rows'
TITLES with `contains` (e.g. a business name) and linked row ids with `is`/`is_not`; all text filters ignore spaces,
case and brackets/punctuation (`( ) [ ] · - . , /`) and treat ㈜ as (주); a blank `contains` value is no condition.

**Row & table history, point-in-time restore** — every row change (create/update/delete, incl. option renames/deletes,
merges, buttons, automations, forms, restores) is kept with who/when/how and the before/after values:
`GET /v1/databases/:id/history?rowId=&before=&beforeId=&limit=` (MCP `rootr_database_history`, CLI `rootr db history`;
page with the `at` + `id` of the last item). `POST /v1/databases/:id/rows/:rowId/restore` `{ changeId, side }`
(MCP `rootr_restore_row`) puts one row back — a deleted row returns with the same id. `POST /v1/databases/:id/restore`
`{ at, dryRun }` (MCP `rootr_restore_database`, CLI `rootr db restore`, managers only) puts the WHOLE table back to that
time — rows and the table definition (columns, select choices, views, buttons, automations; a deleted column returns with
its values). Preview with `dryRun: true` first. Over 300 rows it runs in the background and returns `job`; poll
`GET /v1/databases/:id/restore/:jobId`. Automations do not fire while restoring.

**Showing only some rows per view** — the same two endpoints (MCP `rootr_create_view`
and `rootr_update_view`) take `filters`, `sort` and `colWidths`, so a view can be
created already filtered instead of created then patched:
`{ name: "검토 대기", type: "table", filters: [{ propId: "구분", op: "is", values: ["검토 대기"] }],
sort: { propId: "마감일", dir: "asc" }, colWidths: { "공고명": 420 } }`. `sort` may also be a list of up to 3
(`[{ "propId": "지원일", "dir": "desc" }, { "propId": "등록일시", "dir": "desc" }]` — the next breaks ties of the previous); rows still
tied are ordered by creation time in the first criterion's direction (descending → the newest row first). `rows/query` takes the
same `sort` and orders the same way.
Every condition must match (AND); the `values` inside one condition are OR'd.
Ops: `is`, `is_not`, `contains`, `is_empty`, `is_not_empty`; dates `today`,
`this_week`, `this_month`, `past`, `upcoming`, `before`, `after`, `on`, `between`;
numbers `eq`, `gt`, `lt`; checkboxes `checked`, `unchecked`. Columns may be named
or given by id. Filtering hides rows in THAT view only — nothing is deleted, and a
row added while a filter is on is seeded with the filtered values so it doesn't
vanish as it's created. `filters: null` (or `[]`) and `sort: null` turn them off;
`colWidths` is px per column (40–1200), `{}` resets to auto.

**Week / month / year on a calendar view** — the same two endpoints take
`calendarScale: "week"|"month"|"year"` (top level, not inside `config`), which
decides the span a calendar view OPENS on. `month` is the default; `year` shows
twelve mini-months at once, shaded by how many rows fall on each day. The choice is
saved on the view, so everyone who opens it sees the same span.
MCP: `rootr_create_view`, `rootr_update_view`. CLI: `rootr db view <표> <뷰> --scale year`.

**Action buttons on a table** (no Notion-for-free equivalent — this is Notion's
button block) — a button pinned above the table that runs an ordered list of steps
when someone presses it. It exists because the repeated setup ("new issue: status =
접수, owner = me, due = +7 days") is otherwise retyped by hand every single time.

`GET /v1/databases/:id/buttons` → `{ buttons, myLevel }` ·
`PUT /v1/databases/:id/buttons { "buttons": [...] }` (MANAGE; a **full replace** —
send back the buttons you want to keep) · `POST /v1/databases/:id/buttons/:buttonId/run
{ "rowIds"?: [...], "input"?: "<text>" }` (WRITE).

A button is `{ id?, label, icon?, input?, steps: [...] }` — up to 12 buttons, 8 steps each.
Steps run in order, and **the row a step created is what the next step works on**,
which is what makes "add a row → have AI write its summary → open it" one press:

- `{ "kind": "add_row", "values"?: { … }, "database"?: "<표 id 또는 경로>",
  "link"?: { "relation": "<대상 표의 관계 칸>", "from": "selected"|"created" } }` — create a
  row, optionally pre-filled. **`database` puts it in ANOTHER table** and `link` wires it
  to the row the person pressed on, where `relation` is the relation column in the TARGET
  table that points back here. That pair turns "find the applicant, switch to the call table,
  press 부재, search the same person again" into one press.
  **Find-or-link** — add `"match": { "key": "{요청 건}", "on": "업체명", "normalize"?: ["spaces", "parens",
  "suffix:의원", "trailingDigits", "case"], "fill"?: "empty" }` and the step first looks for the row in the target
  table: `key` (filled from the pressed row) is compared with the column `on` — exactly first (spaces ignored, so
  "다라치과(홍대점)" picks that branch), then after `normalize` (`parens` drops "(긴급)"/"(소독)", `suffix:X` drops a
  trailing X, `trailingDigits` a trailing number, `case` ignores case; default `["spaces"]`). **One** match → nothing
  is created; the pressed row is added to that row's `link` relation (`fill: "empty"` also fills its blank cells
  from `values`). **None** → created as usual. **Two or more** → nothing is created and the pressed row gets a
  "후보 여러 곳: A, B" comment so a person picks (branch names in parentheses can mean different places).
  `on` may be a name and is stored as the column id; it must be a title/text/phone/email/url/select/number column.
- `{ "kind": "update_rows", "target": "created"|"selected", "values": { … } }` —
  write onto the rows this press just made, or onto the rows the person ticked.
  Add `"via": { "relation": "지원자" }` (or send `"target": { "relation": "지원자" }`) to write onto the rows
  **linked through that relation column** instead — e.g. an automation on 면접 조서 that sets the linked
  applicant's 진행상태 to 면접예정. The values then name columns of the linked table.
- `{ "kind": "ai_fill", "target", "propId", "prompt" }` — let AI write ONE cell. With `"fields": [{ "propId": "<column>", "prompt"?: "<what this column is>" }, …]` (≤20, instead of
  `propId`) ONE AI call fills SEVERAL columns at once from the same `prompt` (e.g. split one pasted text into 9 columns in one
  step instead of 9 steps — fewer steps and fewer AI calls); values the text does not contain are left empty, a value a
  column check blocks is skipped alone, the others are written together.
  The prompt may quote the row with `{칸이름}`, e.g. `"{제목}과 {메모}를 한 문장으로 요약해"`.
  If the AI fails, the button keeps going and the response says `aiFailed` and why. If the AI answered but the
  answer cannot go in the cell (not one of a select's options, not a number…) the row is left alone and the
  response counts it in `aiSkipped` with one sample in `aiSkippedAnswer`. An answer equal to the cell's
  current value is not written and is counted in `aiUnchanged` (not in `filled`). The AI sees the row's other
  columns but NOT the current value of the cell it is filling — quote it in the prompt (`{결과}`) if it matters.
  Fillable columns: title, text, number, select/status/multi_select, url, email, phone and **date**. A date answer must
  be ONE real `YYYY-MM-DD` (`YYYY-MM-DD HH:mm` keeps the time unless the column has `allowTime: false`); "없음", impossible dates (2026-02-30), year-less
  (10/20) or two dates leave the cell empty (`aiSkipped`) — never guessed. The model is told to resolve relative dates
  ("어제 지원") only when the source text itself states a reference date, and is not given today's date. An answer that
  fails the column's `validate` block rule is skipped too.
- `{ "kind": "open_row" }` — open the row that was made (the API just returns `openRowId`).

**Buttons that ask for text first** — `"input": { "label": "붙여 넣을 원문", "placeholder"?, "multiline"?: true,
"required"?: true, "split"?: { "by": "blank_line" } | { "by": "separator", "separator": "---" } | { "by": "ai" } }`.
Pressing it opens a text box (`label` is the prompt); the text goes wherever a step says `{@input}` — add_row /
update_rows values and ai_fill prompts — and is put in AFTER `{칸이름}`/`@today` are resolved (text inside the paste
is never re-read as a column). Typical: `[{ "kind": "add_row", "values": { "원문": "{@input}" } }, { "kind": "ai_fill",
"target": "created", "propId": "제목", "prompt": "{원문}에서 제목만 뽑아." }]` — paste → a new row holding the text →
AI fills the rest, with no row selected. Over the API pass `"input"` in the run body (≤ 30,000 chars); `required`
defaults to true (empty → 400). `split` runs the steps **once per item** when several are pasted at once
(`ai` = the model only returns where each item starts, the text is cut server-side); max 50 items (more → 400, nothing
made). Each item rolls back on its own if it fails; the response adds `records: { total, done, failed, errors: [{ index,
message }] }` (all failing → the first error). Saving is refused when a step uses `{@input}` on a button without
`input`, or a button has `input` but no step uses `{@input}`; automations cannot use `{@input}`. Sending
`input` to a button without one is a 400.

Column keys may be NAMES or ids, and values accept `@today`, `@today+7` and `@me`,
resolved by the server at press time. A text value may also quote the pressed row with `{칸이름}`
(`"{이름} {통화 건수+1}차"`): computed columns (rollup, formula) are read too, `{칸이름+N}` /
`{칸이름-N}` adds to a numeric value — on a DATE column it is N days later/earlier (`{투입예정일+3}` → 3 days after that
date). `{칸:YY-MM-DD}` writes a date in that shape (YYYY·YY·MM·M·DD·D), and `{칸+3|@today+3}` / `{메모|없음}` gives the value to
use when the column is empty. `{@today}`, `{@today+7}`, `{@today:YY-MM-DD}` work INSIDE text too (`"{@today:YY-MM-DD} 면접예정"`).
**Append a line:** a value `{ "append": "{@today:YY-MM-DD} {상태}", "sep"?: "\n", "unique"?: true }` on a text column adds that line
to the END of the cell's value at write time (empty cell → just the line; the same line already there → nothing, unless
`unique: false`) — no more rewriting `"{메모}\n…"`, which overwrote edits made in between. When several rows are selected each
new row is filled from ITS OWN source row. A relation column resolves to the linked rows: `{지원자}` is the linked row's TITLE (not
its id) and `{지원자.통화 건수}` reads a column of the (first) linked row — so an automation
`when: 지원자 changed → update_rows selected { "통화 건": "{지원자} {지원자.통화 건수}차" }` titles a call
row the moment a person is linked to it. **Relation → relation:** when a value is exactly `"{배정 매니저}"`
and the column it goes into is a relation to the SAME table, the row **ids** are copied instead of titles
(e.g. 사업장's 담당 매니저 ← 요청's 배정 매니저). Ids the receiving column's `relationFilter` rejects are left
out of that cell only — the rest of the step still runs, the row gets a comment and the response lists it in
`notes`. `rowIds` is only needed when a step targets
`"selected"`. A button grants no permission: it runs as whoever presses it, so a
button writing a `lockedProps` column stops there for someone who may not edit it.
The run response is `{ created, updated, filled, aiFailed, aiError, aiSkipped, aiSkippedAnswer, aiUnchanged, openRowId,
matched?, notes?, records? }` (`matched: { linked, created, ambiguous }` when a step used `match`) —
`created` is the **array of row ids** that were made (not a count), `updated` and
`filled` are counts, and `openRowId` is the last created row when the button ends
with `open_row`.
MCP: `rootr_list_database_buttons`, `rootr_set_database_buttons`,
`rootr_run_database_button`. CLI: `rootr db buttons`, `rootr db button-run [--input <text> | --input-file <f> | --input -]`.
Scaffold: `database.buttons` on the node, built with the table in one call.

**Automatic rules on a table** — the same steps, but nobody has to press anything.
A rule is "when this value becomes that, do these steps", and it exists because the
alternative is a person remembering to press a button: 투입이 확정되면 해피콜을
7·30·90일 뒤로 세 건 잡는 일을 손으로 하면, **안 누른 날은 그냥 빠진다.**

`GET /v1/databases/:id/automations` → `{ automations, myLevel }` ·
`PUT /v1/databases/:id/automations { "automations": [...] }` (MANAGE, full replace).

A rule is `{ id?, label, enabled?, on, when?, schedule?, steps }` — up to 10 per table.
`steps` is **exactly the button syntax** (add_row / update_rows / ai_fill), so there is
nothing new to learn; the row that woke the rule arrives as target `"selected"`.

- `on`: `["updated"]` (default), `["created"]`, `["schedule"]` — one or more.
- `when`: `{ property, op, value? }` with op ∈ `changed_to | changed | is | is_not |
  contains | gt | gte | lt | lte | is_empty | is_not_empty`. Prefer **`changed_to`** for
  state transitions — `is` stays true on every later edit, so a rule that creates rows
  would create them again on each save. `when` may also be an **array** of up to 5 of
  these — then ALL must hold (AND), e.g. `when: [{property:"누구", op:"is", value:"아내"},
  {property:"결과", op:"is", value:"운동함"}]` for a combined condition, instead of relying
  on a title string like "아내 운동함".
- `schedule`: `{ at: "09:00", days?: [1,2,3,4,5] }`, required when `on` includes
  `"schedule"`. Korean time, once a day. `when` then chooses WHICH rows to act on and
  may compare against `@today` / `@today+7`.

A rule runs **as the person who saved it**, never with more permission than that. A
rule watching a computed column (rollup/formula) must compare a value rather than use
`changed`/`changed_to` — computed values are not stored, so "the moment it changed"
does not exist; the server refuses that instead of quietly never firing. Rules that a
rule sets off are followed three levels deep and no further, so a pair of rules that
feed each other cannot spin. When a rule finishes with something a person should know — "후보 여러 곳" from
`match`, or relation ids a `relationFilter` kept out — it is written to the rule's `lastError` with that row
(the rule did not fail; the next clean run of that row clears it).
MCP: `rootr_list_database_automations`, `rootr_set_database_automations`.

**Commenting on a table ROW** — row comments hang off the DATABASE node with the
ROW id as the block: `POST /v1/documents/:databaseId/comments { body, blockId: "<rowId>" }`,
read back with `GET /v1/documents/:databaseId/comments?blockId=<rowId>`. They show
above the row's body when the row is opened, and they work even when the row has no
detail document. Mentioning someone with `@[userId]` notifies them, and their
notification opens that row with the comment highlighted. On an "own rows only" table a row's
comments follow the row: only people who can see the row read or write its thread or get its
notifications (a thread on a row you cannot see answers 404 on write and is simply absent from lists).
MCP: `rootr_comment_document`, `rootr_list_document_comments` (pass the table as the
target and the row id as `blockId`). CLI: `rootr comments <표> --block <rowId>`.

Row `values` are keyed by property id, and each value's shape depends on the column type:
title/text/select = string · number = number · checkbox = boolean ·
**person = string[]** (a list of names — a meeting has several attendees; a single
name is still accepted and stored as a one-item list) ·
multi_select = string[] · **date = { "start": "2026-08-01", "end"?: "2026-08-10" }**
(an object, NOT a bare date string) · files = [{ "name": "제안서.pdf", "url": "..." }]
(attach with `rootr_upload_attachment` first, then put the returned URL here). e.g. `"values": { "title": "킥오프", "date": { "start": "2026-08-01" } }`.

A row also has a **detail body** — the markdown note shown under the card's
properties when you open it. Pass `body` when creating (`POST /v1/databases/:id/rows`,
or inside `rows[]` of `POST /v1/workspaces/:ws/databases` and of a scaffold) or when
updating (`PATCH /v1/database-rows/:rowId` — `body` alone is a valid patch); read it
back with `GET /v1/databases/:id/rows?body=1`. The body lives in its own document
under the table, created on demand.

**Backlinks — reading a relation from the other side.** A `relation` column only
lives on one table (the one that points), so the table being pointed at cannot see
who points at it unless you ask for it explicitly: `GET /v1/databases/:id/rows?backlinks=1`
(MCP `rootr_list_rows` with `backlinks: true`, CLI `rootr db rows <표> --backlinks`).
Each row then gets a `backlinks` field — `{ [referrerDatabaseId]: { propName, rowIds } }`
— listing, per table that has a relation column aimed at this row, the name of that
column and the ids of the rows pointing here. It is computed fresh on every read (nothing
is stored, so it is always in sync with the relation column) and only includes tables and
rows you can actually see. Without the query param the field is absent entirely — existing
callers see no change. This is read-only: a **rollup** still only works on the table that
holds the relation column — if you want a stored count/sum on the pointed-at table, add a
relation column there too.

DOCUMENT: `{ "name": "요구사항 정의서.md", "content": "# 요구사항 정의서\n## 기능 요구사항\n..." }`

**Blocks markdown alone cannot hold** — a document body is markdown, so four of the
editor's blocks are written as one-line markers. Write them exactly and the editor
renders the real block; they survive every save unchanged.
· `> [!💡] 강조할 내용` — callout (any emoji as the icon).
· `- [>] 접히는 제목` — a toggle. Indent the content under it as usual; readers see it
  folded, which is the point of moving a Notion toggle across at all.
· `[[toc]]` — table of contents, built from the document's own headings.
· `[[bookmark:https://example.com "제목"]]` — a link card instead of a bare URL.
· `[[embed:<nodeId>]]` — **puts another node inside this document**: a table shows its
  first rows, a spreadsheet its top-left cells, a deck its slide count, a recording its
  length. This is Notion's inline database widened to every node type we have, so a
  meeting note can hold that meeting's recording, decision table and deck in one page.
  Permission is judged on the embedded node, not the document — an embed never widens
  what someone can see, and public pages do not render embeds at all.
FOLDER:   `{ "name": "기술 문서", "children": [ ... ] }`

SPREADSHEET — a formula-driven grid, e.g. a budget:
```json
{
  "name": "예산", "icon": "🧮",
  "spreadsheet": {
    "data": { "sheets": [ { "id": "s1", "name": "Budget", "rowCount": 20, "colCount": 6, "cells": {} } ] }
  }
}
```
`data` follows `SpreadsheetData` (`spreadsheets/spreadsheet-schema.ts`) — `sheets[].cells`
is keyed `"A1"`-style. `data`/`config` are both optional; omit to create an empty sheet.

WHITEBOARD — a freeform canvas, e.g. a flow or journey map:
```json
{ "name": "여정맵", "icon": "🗺️", "whiteboard": { "scene": { "elements": [] } } }
```
`scene` follows `WhiteboardScene` (`whiteboards/whiteboard-schema.ts`). Optional — omit for a
blank board the user draws on.

PAGE — a web page for people outside the workspace (landing, notice, event):
```json
{
  "name": "가을 행사 안내", "icon": "🌐",
  "page": {
    "blocks": [
      { "type": "hero", "props": { "title": "가을 개발자 밋업", "subtitle": "10월 12일 · 서울" } },
      { "type": "faq", "props": { "items": [ { "q": "참가비가 있나요?", "a": "무료입니다." } ] } },
      { "type": "form", "props": { "formNodeId": "신청 폼", "headline": "신청하기" } },
      { "type": "liveStats", "props": { "cards": [ { "label": "신청자", "source": { "nodeId": "/가을 행사/신청 명단", "agg": "count" } } ] } }
    ],
    "config": { "theme": "midnight" }
  }
}
```
`blocks` follows `PageBlock[]` (`pages/page-schema.ts`) — see *Pages* above for all 16 block
types, including `custom` (`{"type":"custom","props":{"html":"<style>…</style><div>…</div>","height":300}}`)
for a look the ready-made blocks cannot give. Omit `blocks` for a hero/text/footer skeleton.
**A live/form block inside a scaffold may name its source by NAME or "/path"** — the nodes it
points at are created in the same call, so their ids do not exist yet; they are rewritten to real
ids after the tree is built (same rule as a relation column's `relationDatabaseId`). A name that
matches nothing fails the call rather than leaving a dead block. The page is created **unpublished**; publish it
with `POST /v1/nodes/:id/publish` when the user asks for a public address.

FORM — external intake, optionally feeding a DATABASE by id:
```json
{
  "name": "리스크 접수", "icon": "⚠️",
  "form": {
    "fields": [
      { "id": "title", "label": "무엇이 문제인가요?", "type": "text", "required": true },
      { "id": "impact", "label": "영향도", "type": "select", "options": ["High", "Med", "Low"] }
    ],
    "targetDatabaseId": "<risks-database-node-id, optional>"
  }
}
```
`fields` follows `FormField[]` (`forms/form-schema.ts`). Set `targetDatabaseId` to a DATABASE
node's id in the same tree only when you want submissions to land there as rows — otherwise omit it.

**Check the question → column wiring after linking a form to a table.** Answers reach the
table by matching the question name to the column name, so a question the table has no
column for is **dropped with no error anywhere** — a form whose ten questions were all
worded differently accepted submissions for days and created no rows at all.
`GET /v1/forms/:id/mapping` shows every question, the column it feeds, whether that match
is `manual`/`auto`/`none`, the table's columns, `unmatched` (the questions being dropped)
and `lastError` (why the last submission failed to land). `PUT /v1/forms/:id/mapping
{ "fieldMap": { "<질문 id>": "<칸 id>" } }` pins them by hand — questions you leave out keep
matching by name, and `null` puts one back to automatic. The form's own detail response now
carries `unmatchedFields` too, so the editor can warn at save time.
MCP: `rootr_form_mapping`, `rootr_set_form_mapping`.

ISSUE_TRACKER — a ready-to-use issue tracker:
```json
{
  "name": "버그 트래커", "icon": "🐛",
  "issues": {
    "labels": [ { "name": "bug", "color": "#d73a4a" }, { "name": "urgent", "color": "#ff0000" } ],
    "types":  [ { "name": "bug" }, { "name": "feature" }, { "name": "chore" } ]
  }
}
```
`labels`/`types`/`config` are all optional — omit them for the default label
(bug/enhancement/question) and type (bug/feature/task) sets.

CRM — a full sales/relationship-pipeline workspace, pipeline customized for a
hiring flow instead of the default sales one:
```json
{
  "name": "채용 파이프라인", "icon": "🧑‍💼",
  "crm": {
    "pipelines": [
      {
        "name": "Hiring Pipeline",
        "stages": [
          { "name": "지원",   "probability": 10 },
          { "name": "서류",   "probability": 25 },
          { "name": "면접",   "probability": 60 },
          { "name": "오퍼",   "probability": 90 }
        ]
      }
    ]
  }
}
```
`pipelines`/`fields`/`config` are all optional — omit `pipelines` for the
default 5-stage Sales Pipeline (Lead In 10% → Qualified 25% → Meeting 40% →
Proposal 60% → Negotiation 80%). `fields` adds custom fields per entity:
`{ "contact": [ { "name": "LinkedIn", "type": "url" } ], "company": [...],
"deal": [...] }` (`type`: text/number/select/date/url/checkbox). Companies,
contacts, deals, activities and tasks are created afterwards through the CRM
REST API (see "CRM" above) — the scaffold payload only sets up the pipeline
shape and custom fields, not seed records.

SIGNED — 서명문서 · 연구노트. 문서와 결재라인까지 만들어 두고 멈춘다(서명은 사람이
직접 눌러야 한다):
```json
{
  "name": "2026-08-25 실험기록", "icon": "🔏",
  "signed": {
    "content": "## 오늘 한 일

## 결과

## 다음 계획
",
    "mode": "RESEARCH_NOTE",
    "reviewerUserId": "<연구책임자 userId>",
    "noteMeta": { "과제번호": "2026-XXXX", "과제명": "…", "기관": "…" }
  }
}
```
`reviewerUserId`만 주면 "기재자(만든 사람) → 점검자" 두 단계가 자동으로 짜인다.
직접 짜려면 `approvalLine: [{ label?, rule?: "ALL"|"ANY"|"N_OF_M", requiredCount?,
members: [{ userId, role?: "AUTHOR"|"REVIEWER"|"APPROVER" }] }]` — 배열 순서가 곧
서명 순서다. 결재자는 워크스페이스 멤버여야 한다. 서명·올리기는 스캐폴드가 하지
않는다: 확인 코드가 사람 메일로만 간다.

### A good PM workspace mixes them
overview + a requirements *spec* as DOCUMENTs; a **Tasks** board DATABASE; a
**Requirements** table (id/priority/status/acceptance-criteria columns); a **WBS**
table (phase/deliverable/owner/estimate); a **Risks** table (impact/likelihood/
mitigation/owner); a **Milestones** timeline (date column, timeline view). That is
the bar — not five near-empty .md files. Where it genuinely fits, add a **Budget**
SPREADSHEET (formulas, not a static table) or a **Risk intake** FORM feeding the
Risks DATABASE — only when the request calls for it, not by default.

### Make it look polished (the result must be visually impressive, not plain)
- Set `icon` (a single emoji) on every folder / database / key document — e.g.
  `{ "name": "Tasks", "icon": "✅", "database": {...} }`, `"📋 요구사항"`, `"⚠️ 리스크"`,
  `"🗓️ 마일스톤"`. Icons make the sidebar and pages read as a real product.
- Prefer **visual views**: a board (kanban) for tasks, a timeline for milestones,
  a gallery/calendar where it fits — not everything as a plain table.
- Write **rich documents**, never a lone heading: use `##` sections, markdown
  tables, task lists (`- [ ]`), bold/callouts, and real starter content the user
  can edit — a requirements spec should have numbered sections and acceptance
  criteria, not one line.
- Seed a few realistic example rows in each database so boards/tables aren't empty.
Aim for a workspace that looks like a polished, ready-to-use tool the moment it opens.

`plan` is modelless (deterministic routing); **you** generate the tree with your own
model. Output in the intent's language. Max 200 nodes / 200 rows-per-database per call.

## Learn more

- `https://rootr.io/blog` — root cause analysis and knowledge-graph writing, including
  a worked GraphRAG root-cause-analysis walkthrough
  (`https://rootr.io/blog/what-is-graphrag-root-cause-analysis`).
- `https://rootr.io/pricing` — plans and exact prices (Free / Team / Business / Platform).
- `https://rootr.io/pricing.md` — the same plans/prices as static Markdown, for agents
  that want to fetch and read pricing without rendering the page.

## Notes for integrators

- All `/v1/**` REST routes are namespaced by workspace (`:ws`) or by resource
  id once the resource is known (`/v1/logs/:id`, ...) — resource ids already
  encode their workspace, so most routes past creation don't need `:ws` again.
- Everything above is generated from, and should stay consistent with, the
  live OpenAPI/GraphQL schemas linked above — treat this file as a guided tour,
  and the schema documents as the source of truth for exact shapes.