---
name: resources
description: "Create and maintain Pai Console project Resources: typed pages, canvas view blocks, HTML prototypes, Excalidraw whiteboards, live Knowledge projections, attributes and filters, notes, folders, suggestions, comments, image/video assets, and files. Use for documents, reports, PRDs/SOWs, dashboards, mockups, editable diagrams, page approval/ownership/filtering, suggestions, comments, uploads, asset reuse/deletion, or moving/restoring/deleting pages and empty folders."
argument-hint: "[project] [topic or resource type]"
compatibility: "Pai 0.2.5+ (MCP corp)"
---

# Resources: pages, views, whiteboards, images, files

Read shared `pai-console` first through the current client's skill mechanism. Replies follow the user's language; preserve Mexican Spanish business formatting, MXN amounts, and `America/Mexico_City` dates where required. Spanish section identifiers, server errors, and established paths quoted here are intentional contract exceptions.

**References:** contract-generated `references/page-types.md` for built-in sections, blocks, limits, and rules; **`views`** for `pai-view@1` catalogs/recipes. Prefer these over the ~35 KB `page_catalog`; call `page_catalog`/`page_types` only for a suspected version difference or organization/project custom types.

## 1. Choose the resource

| Need | Resource |
|---|---|
| Known document structure (note, guide, decision, report, process, overview, PRD, SOW, architecture, discovery, design inventory) | `layout: "document"` page **with built-in `typeSlug`**; required sections govern |
| Dashboard, visual report, screen mockup, freeform Pai components | `layout: "canvas"` page with **`view`**, **without `typeSlug`**; no built-in type allows it |
| Free JavaScript, simulation, interactive/pixel-precise mockup | **`html`** block (§3), **without `typeSlug`**; no built-in type allows it. **Not a screen prototype:** screens require `view` (`screens`) |
| Manually editable brainstorming, flow, map, draft architecture, Mermaid flowchart | **Whiteboard** (`whiteboard_create`, §3), collaborative Excalidraw in Resources, embedded through `whiteboard`. For display only, use `Flow` (`views`) |
| Existing Knowledge (C4, ERD, screens, flows, decisions, risks, glossary…) | Live **`projection`** in a v2 page (§3), resolved at read time rather than copied |
| Quick Markdown, including client-authored notes | Note (`note_create`, §9) |
| PDF, spreadsheet, contract, binary | Resources file (§6), not a page |
| Atomic decision, rule, entity, component | Knowledge node (`knowledge`), not a page |

A **page is read continuously; a node is queried, linked, and superseded**. Pages cite nodes; nodes cite pages through `sources: [{type:"page", pageId}]`.

## 2. Create a page

1. **Search:** `page_search` by topic and `page_list` following `nextCursor` for paths. Update equivalents (§4).
2. **Choose type:** `references/page-types.md`, or `page_types {slug}` for full `authoringGuide` and example.
3. **Choose path:** English kebab-case folders, no extension/dates except series: `architecture/payments`, `reports/checkout-performance`, `dashboards/project-status`, `guides/deploy-staging`, `reports/2026-10-weekly`.
4. **Compose:**
   ```json
   { "schemaVersion": 1, "componentSetVersion": "pai-core-v1", "layout": "document",
     "sections": [ { "id": "resumen", "title": "Summary", "blocks": [ { "id": "intro", "type": "text", "markdown": "…" } ] } ] }
   ```
   - Section IDs match the type (`resumen`, `hallazgos`) in its order.
   - Block IDs match `^[a-zA-Z][a-zA-Z0-9_-]{0,79}$`, unique page-wide; use meaningful names (`summaryCallout`, not `b1`).
   - Limits: 40 sections, 200 blocks, 500 000 JSON characters.
5. **`page_validate {content, typeSlug}`** until no `issues`. Check contract, missing/misordered sections, prohibited blocks, and quality (dated URL sources, minimum text).
6. **`page_create`** with:
   - `path`, Spanish business `title`, `description`, `typeSlug`;
   - `audience`: `internal` (team) or `client`. Ask if unspecified; absent a decision, use `internal`;
   - `content`, commit-style `summary` (≤80);
   - stable `idempotencyKey`: `page-<project>-<hyphenated-path>`.
7. Inspect `warnings`, `document.revision`; return path/revision and response `url` prefixed by the Portal host (`https://app.pai.lat` production; staging Portal in staging).

Validated report with five required sections: `examples/report-page.json`. Canvas examples: `../views/examples/`.

## 3. Views, HTML, projections, whiteboards

Choose `view` for Pai component dashboards/data; `html` for free JavaScript/pixel-precise interactions; `projection` for live Knowledge; `embed` for Figma/Slides/Miro/YouTube/Loom **https URLs only**, never HTML or `<iframe>`.

### `view` (`pai-view@1`)

Use **`views`** for catalog, validated recipes, data/design rules, errors. Container page: `layout: "canvas"`, block `{id, type: "view", title, spec}`, **no `typeSlug`**, `page_validate` before saving. MCP Apps support is client-dependent; CLI requires text fallback, and a successful call does not prove rendering (`pai-console` §6).

### `html` (interactive mockups/prototypes)

Portal displays an isolated iframe (`sandbox="allow-scripts"`), without cookies, storage, popups, forms, or network. This behavior belongs to Portal and is not a guarantee that a Claude/Codex client rendered anything.

```json
{ "id": "flowMockup", "type": "html", "title": "Flow mockup", "description": "Choose a step to see its details.", "height": "auto",
  "html": "<style>body{margin:0;padding:16px;background:var(--background);color:var(--foreground)}button{border:1px solid var(--border);border-radius:8px;background:var(--card);color:inherit}</style><button id=b>Approve</button><p id=d></p><script>b.onclick=()=>d.textContent='Approved';</script>" }
```

- Fields: `title` (1–240, accessible name/index title), optional `description` (≤240), `html` (full document/fragment), `height` `"auto"` (content growth to 4000) or integer **120–4000 px**.
- Limits: **512 KB/block**, **1 MB total HTML/page**, UTF-8 bytes. Each version retains full content.
- Scripts: inline or https `src` only from `https://cdnjs.cloudflare.com/`, `https://cdn.jsdelivr.net/npm/`, `https://unpkg.com/`, `https://cdn.tailwindcss.com/`. Inline styles or `fonts.googleapis.com`; fonts `fonts.gstatic.com`; images `data:`, `blob:`, or https.
- **No network:** CSP `connect-src 'none'` blocks `fetch`, XHR, WebSocket, EventSource, `sendBeacon`. **Embed data in HTML.**
- Theme: Portal injects live Pai/organization CSS variables. Use `var(--background)`, `var(--foreground)`, `var(--card)`, `var(--muted)`, `var(--muted-foreground)`, `var(--border)`, `var(--primary)`, `var(--primary-foreground)`, `var(--success)`, `var(--warning)`, `var(--destructive)`, `var(--chart-1)`…`var(--chart-5)`, `var(--radius)`, `var(--font-sans)` for both modes; never hardcode colors.
- Write-rejecting errors (`page_create`/`page_update`: `BAD_REQUEST`, `path: message`; `page_validate`: `issues`):
  - `HTML_BLOCK_TOO_LARGE`, `HTML_PAGE_TOO_LARGE`: reduce/split pages;
  - `HTML_SCRIPT_HOST`: disallowed host, non-https, protocol-relative `//…`, credentials, or port; use permitted CDN/inline;
  - `HTML_PREVIEW_IN_MARKDOWN`: a ```` ```html preview ```` fence in block Markdown; use `html` block.
- Nonblocking `warnings`, also in validation:
  - `html-network-blocked`: network calls will fail; embed data;
  - `html-sensitive-field`: passwords, cards, OTP (`type=password`, `autocomplete=cc-*`, `one-time-code`); make the mockup explicit, never request real data.
- `kb:` inside `html` is neither citation nor indexed. Use v2 block `refs` or cite in `title`/`description`.
- In `audience: client` pages, clients see the block (without staff code-view button) and receive full `html` through `page_read`; include no internal data. V2 replaces HTML `kb:` references with their text for clients.
- Console cannot create/edit HTML or height, only title/description; agent uses `page_create`/`page_update`.
- `page_read view=content`/search return a Portal-opening summary (literal “HTML interactivo · ábrelo en el Portal”), not code.
- `page_migrate` converts a top-level Markdown note fence ```` ```html preview h=400px ```` into `html`. Nested list/quote conversion fails; move it to top level.

### `projection` (live Knowledge)

In `schemaVersion: 2`, `{id, type: "projection", format, selection: {refs} | {query}, params?}` resolves only what the reader can see, storing no own data. Formats: `c4`, `erd`, `screen`, `screen-list`, `use-case`, `use-case-list`, `flow`, `decision-table`, `requirement-list`, `risk-list`, `assumption-list`, `glossary`, `fact-list`, `actor-list`, `task-timeline`, `node-cards`, `knowledge-table`. `page_validate`, then `page_update`.

- Show an existing projection with `page_projection {path, blockId}` (`blockId` from `page_read`), using Portal reader visibility. `projection.state`: `ready`, `empty` (nothing visible), `broken` (`message`, plus staff-only `missing`). Clients can use it for client-visible pages/nodes.
- `page_read view=full` returns resolved `projections` as data for reasoning/editing, without drawing.
- Staff `knowledge_view` projects ERD/C4 directly without a page.
- Missing block → `NOT_FOUND`; non-projection block → `BAD_REQUEST`; read with `page_read`.

### Whiteboards (`whiteboard_*`, `whiteboard`)

A `whiteboard` format page stores a live collaborative Excalidraw scene in Resources. Like notes: staff or client-organization members can create; a client's board is visible to its organization and Pai, editable by its organization; staff boards default to `internal` unless `audience: "client"`.

**Never write coordinates.** Send `{graph}` or `{mermaid}`; server lays it out:
- `graph`: `{direction?: "TB"|"LR"|"RL"|"BT", nodes: [{id, label, shape?, group?, tone?}], edges?: [{from, to, label?, dashed?}], groups?: [{id, label}]}`. `shape`: `rectangle`, `ellipse`, `diamond`, `note`, `text`; `tone`: `default`, `info`, `success`, `warning`, `destructive`, `muted`. IDs use letters/digits/`_ . : -`. Limits: 300 nodes, 600 edges, 50 groups, 280-character texts.
- `mermaid`: `flowchart` with nodes `A[text]`, `A(text)`, `A([text])`, `A{text}`, `A((text))`, `A>text]`; edges `-->`, `---`, `-.->`, `==>`, `-->|text|`; `subgraph … end`; ≤20 000 characters.

1. Create: `whiteboard_create {path, title, content?, audience?, summary?, idempotencyKey?}`. Full path, e.g. `diagrams/sales-flow`; no `content` creates empty. Returns `path`, `revision`, `url`, semantic `summary`.
2. Read: `whiteboard_read {path}` returns node IDs/text/shapes/groups, connections, groups, free text, `otherCount` for non-node strokes/shapes, `revision`, and `preview`; MCP Apps hosts can show `WhiteboardSketch`. **Always read before writing:** people draw manually.
3. Write: `whiteboard_update {path, expectedRevision, mode, content, idempotencyKey, summary?, versionName?}`.
   - Default **`append`** adds to the right; edges can target existing IDs/text; new IDs cannot collide.
   - **`replace` erases people's drawings**; only when explicitly requested.
   - Required `idempotencyKey`: reuse only for identical retries; changed content yields literal “La clave de idempotencia ya se usó con otro contenido”. `versionName` names the saved version.
   - Open boards receive live edits.
4. On `CONFLICT` (literal “La pizarra cambió desde que la leíste…”), reread with `whiteboard_read`, integrate, retry once. On `UNAVAILABLE` (“la colaboración no está disponible”), retry with the same key. `page_update`/`note_update` reject boards with “Esta página es una pizarra: se edita en el Portal o con whiteboard_update”.
5. Staff `note_audience_set` publishes a board to clients; `page_move` preserves its scene.
6. `WhiteboardSketch` accepts only server `whiteboard_read.preview`; never invent/assemble it manually.

Embed with `{id, type: "whiteboard", page, title?}`: `page` is same-project board **`document.id` UUID**, not path. Shows preview/open and, for editors, inline edit. No built-in type permits it: omit `typeSlug`.
- Validation: `WHITEBOARD_NOT_FOUND` (absent in project), `WHITEBOARD_NOT_A_BOARD`, warning `WHITEBOARD_NOT_CLIENT_VISIBLE` (client page cannot show team-only board).
- `page_read view=full` returns `whiteboards` titles/summaries or `hidden` for invisible boards.

### Flow block

`{id, type: "flow", node, title?, height?}`: same-project `flow` node **UUID**; height 240–1200 px, default 480. Read-only canvas/open control; build with `flows`.

## 4. Update a page

1. Before rewriting, `page_comprehension` (staff aggregate; others own data): missed questions suggest explanations to improve, **never personal grading**. `page_knowledge_health {path}` identifies superseded/archived/contradicted/unvalidated `kb:` citations; without path, counts by page.
   - `quiz_respond {path, blockId, answers | responses}` acts **as the user**, and attempts count as theirs. Only on explicit request with their answers.
2. `page_read {path, view: "full"}`; retain `document.id`, `document.revision`.
3. Modify **that complete content**. `page_update` replaces the entire page; never start from summary, partial content, or `page_version`.
4. `page_validate` → `page_update {path, expectedDocumentId, expectedRevision, content, summary}`. Detach type with `detachType: true`; `typeSlug: null` is invalid.
5. `CONFLICT`: reread, integrate, retry once.
6. After `page_create` returns `replayed`, **reread** before updating; its revision may be stale.

## 5. Image/video assets

Project assets upload once and are reused by ID in same-project pages, notes, whiteboards. Never use external URLs/dataURLs as asset references.

| Tool | Behavior |
|---|---|
| `asset_list {kind?, q?, cursor?, limit?}` | Search name/`kind` (`image`, `video`, `other`) before reupload; `nextCursor`, max 100; returns `id`, name/type/size, `href`, `usedIn`; can render on MCP Apps hosts |
| `asset_get {assetId}` | Dimensions/duration, uploader, `href`, `usedIn`, `canDelete` |
| `asset_upload {filename, contentType, size, documentId?}` | Non-idempotent preparation: each call reserves a new asset |
| `asset_confirm {assetId}` | Idempotent confirmation after PUT; sets `ready` |
| `asset_delete {assetId}` | Irreversible deletion |

Clients see assets used in visible content and their own unused uploads. `usedIn` includes only visible documents.

### Choose the upload path

Search `asset_list` by name/kind first and reuse existing IDs. Use the actual returned URLs and headers; never hardcode a storage or MCP origin.

1. **PUT, with shell:** `asset_upload {organizationId,projectId,filename,contentType,size,sha256?,documentId?}` prepares an asset. Size is exact bytes; SHA-256 is original-file hex or base64url. PNG/JPEG/WebP/GIF ≤10 MB, SVG ≤1 MB, MP4/WebM ≤200 MB. Execute returned `upload.curl`, replacing `<archivo>` with the safely quoted local path, before `upload.expiresIn` (300 seconds). Send binary bytes and exactly the returned headers; do not add x-amz-checksum-* headers. The single-use ticket targets the MCP domain; sandbox/domain permission may be required. `signedUrl` is the direct bucket alternative. After HTTP 200, finalize with `asset_upload {organizationId,projectId,assetId}` or `asset_confirm {organizationId,projectId,assetId}`.
2. **Inline, without shell:** for files ≤100 KB, provide filename, contentType, raw base64 `data` without a data: prefix, and mandatory original-file `sha256`. The asset becomes ready in that call. Never invent or re-encode bytes to imitate an unavailable file.
3. **Chat attachment:** pass the actual host-provided `file` object: required `download_url` and `file_id`, optional `mime_type` and `file_name`. ChatGPT supplies this through openai/fileParams; the server downloads and finalizes it. Never fabricate an attachment URL or ID. Server download restrictions remain authoritative.
4. **Portal fallback:** without shell or usable inline/attachment bytes, ask the person to upload in the project's Resources gallery at returned `portalUrl`, then locate it with `asset_list`. Report missing sandbox permission rather than claiming an upload succeeded.

`documentId` is an editable page/note/whiteboard UUID, not a path. Without it, uploads go to the staff-only gallery; clients use a document they can edit. Finalization is idempotent for ready assets and verifies declared size/type, optional digest, image bytes and SVG safety. Pending assets expire after 24 hours. Never persist upload URLs; save assetId or href.

A ticket's `UPLOAD_TICKET_INVALID` means expired, unknown or already used: prepare again. Fix `UPLOAD_TYPE_MISMATCH` / `UPLOAD_SIZE_MISMATCH` against the returned request before retrying the still-valid ticket. Content/digest mismatches are failures, not successful assets. Inspect actual errors; never silently substitute different bytes. An already uploaded asset missing from the gallery may still need finalization.

Legacy `page_asset_upload {path,filename,contentType,size}` remains for PNG/JPEG/WebP/GIF ≤10 MB on existing pages and also returns upload instructions. It has no asset_confirm step: referencing it in page_create/page_update verifies pending bytes. Prefer asset_upload for SVG, video, notes and whiteboards.

### Use

Only visible, `ready`, **same-project** assets. Other project/unconfirmed/invisible → `NOT_FOUND`; `/storage`, signed/external URL → `ASSET_ADAPTATION_REQUIRED`. No same-page restriction; reuse `asset_list` results. Audience follows containing content.

- Page: full `page_read`, CAS `page_update`.
  - Image `{type: "figure", assetId, alt, caption, credit?}`; use `assetId: null` until uploaded, never fabricate IDs.
  - Video `{type: "video", assetId, caption?, poster?}`; MP4/WebM, optional same-project image poster.
  - Saved `view`: `Image`, `Carousel`, `Video` (required `title`); rejected by `view_render`. Outside Portal/MCP view, alt-text frame is shown.
  - Markdown `![alt](/api/pages/assets/<assetId>)`.
- Note Markdown `![alt](<href>)`, `note_update` with `expectedRevision`; upload with note UUID `documentId` so clients can use their own note.
- Whiteboard graph `{id, label, image: "<assetId>"}`: image with label below, ignores `shape`. Visible `ready` image required or `invalid_input`; no video nodes.

### Delete

`asset_delete {assetId}` is **irreversible**, requires prior confirmation. No current page/note/board may use it; otherwise `CONFLICT` `ASSET_IN_USE`: remove references from every `usedIn` document first. Only staff/uploader; inspect `asset_get.canDelete`. Old versions retain alt text instead.

## 6. Resources files

1. Search `file_list` before uploading. `file_upload {organizationId,projectId,contentType,size,sha256?}` accepts ≤104857600 bytes (100 MiB), with exact size and optional original-file digest.
2. Execute returned `upload.curl` with the actual local path within five minutes, preserving returned headers and binary bytes. It uses an MCP-origin single-use ticket; signedUrl is the direct bucket alternative. Apply the same ticket/error/domain rules as asset uploads. Without shell, use Resources in Portal.
3. `file_create {organizationId,projectId,name,fileKey,folder?,mimeType?,sizeBytes?,visibility}` registers the successful upload. Omitted folder means root. Set visibility explicitly: internal is staff-only, shared is client-visible; agree before sharing. Never fabricate fileKey.
4. `file_update` renames/moves; `file_delete` is final. Empty folder deletion: §9.

### Manual folder order

`folder_reorder {organizationId,projectId,folder,items}` is staff-only. Read the folder's direct children first. folder is its path, or an empty string for the Resources root. items contains at most 500 direct-child shortIds or paths, including pages, files and subfolders. File paths are folder/name. This replaces the complete manual order; omitted children appear afterward by title. An empty items array clears manual order. Preserve existing unrelated ordering and inspect the returned complete ordered children, including each ordered flag.

## 7. Move, restore, delete

- `page_move {path, newPath, summary}` rewrites links; inspect `warnings`, disclose external backlinks.
- `page_restore {versionId, …CAS}` creates a new revision from an old version (`page_versions`).
- **`page_delete` hard-deletes** versions/comments/index; `page_restore` cannot recover. Returns broken backlinks. Read and confirm first; update or mark outdated content instead when appropriate.

## 8. Page attributes

All pages (pai-page/Markdown/notes) support date, owner, status, labels in Portal properties:

| Key | Format | Rule |
|---|---|---|
| `date` | Valid `YYYY-MM-DD` | Existing day |
| `owner` | User ID | Pai team or project-organization member; `milestone_owner_options`; clients see name only |
| `status` | `draft` \| `in_review` \| `approved` \| `archived` | Literal UI Borrador/En revisión/Aprobado/Archivado; absent means no status, not draft |
| `labels` | ≤10 strings, ≤40 characters each | Case-insensitive uniqueness; project-local free labels, no catalog tool; reuse `page_list`/`page_read.attributes` |

- Read: full `page_read.attributes` `{date, owner: {id, name} | null, status | null, labels[]}`; raw `frontmatter` remains. `page_list` includes attributes where present.
- Validate: `page_validate {frontmatter}`, optional `content`, same Portal schema/access checks; `issues` with `code: "PAGE_ATTRIBUTE_INVALID"`, `path: "frontmatter.<key>"`.
- Staff update: `page_frontmatter_update {path, frontmatter, expectedRevision, summary?}`, **merge-patch**: sent keys replace, `null` deletes, omitted keys remain. Revision from `page_read`; reread on `CONFLICT`. Audited in versions; also works on pai-page metadata without content changes.
- Notes: `note_update {attributes, expectedRevision}`, alone/with `markdown`. Clients can change date/status/labels on own notes, never owner (`FORBIDDEN`). `note_create` rejects attributes: set afterward.
- Invalid date/status, 11 labels, inaccessible owner → `BAD_REQUEST`, `<key>: <message>`, no write; correct and retry.
- Type/audience: `page_frontmatter_update` (`type`, `audience`) or note `note_audience_set`. Pai-page title/description: `page_update`.

### Filter/sort

`page_list`/`page_search` share filters: **AND across keys, OR within a key**.
- `status`: 1–4 values, e.g. `["in_review", "approved"]`.
- `owner`: case-insensitive name or staff ID.
- `labels`: any of 1–10.
- `dateFrom`/`dateTo`: inclusive `YYYY-MM-DD`; **exclude undated pages**.
- `audience`: `client`/`internal`; `page_list`-only `pathPrefix` scopes folders.

`page_list.sort`: `path` default, `date` newest first, `status` draft → in_review → approved → archived; missing values last. Follow `nextCursor` **with the same `sort`**; mismatched cursor silently restarts listing.

`page_search` neither sorts nor paginates: finds top 50 then filters; may return below `limit` despite more matches. Use `page_list` for complete filtered inventory.

```json
{ "organizationId": "…", "projectId": "…", "status": ["in_review"], "labels": ["payments"], "dateFrom": "2026-10-01", "sort": "date" }
```

## 9. Notes, folders, suggestions

**Folders:** `folder_create {parent, name}`: `parent` is `""` root or visible folder `path`; Spanish business `name` (1–120) generates slug (existing example “Actas de obra” → `actas-de-obra`). Staff defaults `internal`, exact path; occupied → `CONFLICT`. Use returned `path` for notes. No rename/move tool. Root literal UI labels are “Recursos” / “Recursos (raíz)”.

**Folder delete** `folder_delete {path, summary}` is irreversible; must be **empty at every depth**, including internal pages/files and subfolders' content. Empty subfolders are removed too.
1. Inspect `page_list {pathPrefix: "<path>/"}` and `file_list`; move/delete contents with `page_move`, `file_update`, `page_delete`, `file_delete` after confirming with the user.
2. Confirm deletion; supply audited `summary` reason (≤80), event `folder.delete`.
3. Root `""` → `invalid_input` (“La raíz de Recursos no se puede eliminar.”); invisible → `not_found`; visible content → `CONFLICT`, empty first. `FORBIDDEN` “No puedes eliminar esta carpeta.” means ownership or hidden content: clients can delete only client-created folders and subfolders. Do not retry; ask Pai.
4. Short URL then 404s; path URL redirects to closest existing ancestor. Returns `deleted` paths and parent URL.

**Notes** (client-editable Markdown):
- `note_create {path, title, markdown?, audience?, summary?}`. Staff defaults `internal` unless `client`; clients always `client` with random path suffix. Use returned path. Set attributes afterward (§8).
- **No `kb:`** citations in notes; use pai-page if required (literal error “Una nota no lleva referencias kb: …”).
- `note_update {path, expectedRevision, markdown?, attributes?}` replaces **entire** Markdown. Pai-page is not a note (“Las páginas de Pai se editan con page_update”).
- **Never overwrite client notes:** agent Markdown updates become client suggestions, returning `{suggested: true, setId, threadId}`. Not failure; do not retry. Tell the user; attributes still write directly.
- Staff `note_audience_set {path, audience}` publishes to organization; client-created notes cannot become `internal`.
- Convert via `page_create {…, derivedFromPageId}` using same-project note `document.id`, or `page_migrate`.

**Suggestions** (reviewable before/after):
- `page_suggest {path, baseRevision, suggestions, summary}`, staff agents only; current `page_read` revision or `CONFLICT`, then reread/repropose.
  - Pai-page: each suggestion has `blockId` and complete blocks: `replace` (`was`+`now`), `insert` (`now`, after block), `delete` (`was`).
  - Note: `was`/`now` `{text, range}`, UTF-16 offsets; empty range for insert; `was.text` must match range.
  - Thread audience `client` for client pages, otherwise `team`.
- `page_suggestions {path, state: open|all}`: `pending`, `accepted`, `rejected`, `stale`, `canDecide`.
- `page_suggestion_decide {setId, decisions}`: staff, or note editors. When no pending remain, accepted changes apply together in one revision; stale changes do not. Only when the user decides.
- Use suggestions instead of `page_update` for another person's/client's page or requests to propose changes.

## 10. Comments

Target `{kind: "page" | "knowledge" | "proposal", id}`: page `document.id`, node ID, proposal ID.

Page comments **require** `anchor {exact, prefix?, suffix?, blockId?, nodeId?, elementId?}` with literal `exact` from `page_read`.
- `{blockId, nodeId}`: project/organization diagram node; client-readable thread requires `visibility: client`.
- `{blockId, elementId}`: `pai-view@1` element.
- `nodeId`/`elementId` each require `blockId`, never both. Omit anchor for Knowledge/proposal comments.

Audience is immutable; replies inherit it:

| `audience` | Readers | Rule |
|---|---|---|
| `agent` | Author and their agent; `agent_inbox` | Own thread, no `audienceUserId` |
| `team` | Pai team | Staff only, no recipient; **server default for staff** |
| `client` | Client and Pai | Client page or sent proposal only |
| `person` | One person | `audienceUserId` from `comment_recipients {path}` (`kind: client \| staff`); client recipient must see page |

- Portal composer defaults to agent, **server does not**: explicitly send `audience: "agent"` for agent threads.
- Staff `needsAgent: true` only with `team`/`client`, adds to staff agents' inbox.
- `agent_inbox`: own unanswered agent threads and `needsAgent`; respond as person with `comment_reply` or as agent with `page_comment_reply` (`summary`, optional `resolve`).
- `comment_edit {target, threadId, commentId, body}` only own/this agent's comments; marked edited, audience/state unchanged.
- `comment_send_to_agent {threadId, body?}` creates a new agent thread on same fragment without altering original. `comment_resolve`/`comment_reopen` only for page threads.

Typical errors: missing/mismatched page anchor, `nodeId` without `blockId`, client thread on internal page, `needsAgent` with `agent`/`person`, editing others' comments (`FORBIDDEN`).

## Avoid

- No `typeSlug` with `view`/`html` (`bloque-no-permitido`).
- Do not duplicate `facts`/`data-table` figures in prose.
- Do not use legacy `type` values (`arquitectura`, `reporte`…); use `typeSlug`.
- No HTML/iframe in `embed` or Markdown; embeds contain https URL, interactive HTML uses `html`.
- No HTML network fetches/disallowed script hosts: embed data, use the four CDNs.
- New paths must not use Spanish, uppercase, or spaces; preserve established existing paths and type identifiers.
- Do not retry note suggestions as direct client-note overwrites.
- Do not omit `audience` for agent comments.
- Do not expect `folder_delete` to cascade content; empty it first.
- No unrequested whiteboard `replace`, coordinates, or raw Excalidraw elements; use `graph`/`mermaid`.

## Inline Knowledge citations

Use Markdown links `[label](kb:...)` for Knowledge references in page text. Never hide a kb: citation in backticks or raw HTML: schemaVersion 2 rejects citations outside links with KNOWLEDGE_CITATION_OUTSIDE_LINK. Read current page types; PRD v2 permits the documented additional metric/risk blocks without inventing section IDs.