--- name: pd-intel-documents description: Use when publishing, updating, sharing, or finding documents on PD Docs, PD Intelligence's document surface — "push this report to PD Intelligence", "publish this briefing or deck", "share this document with the team", "share it to a dataset", "send it to someone outside the org", "make it public", "get a shareable link", "who can see this document", "revoke access", "update the published report", "find the document I published", "read that document back". Covers publish_document, share_document, get_document_sharing, list_documents and read_document, the folder tools (list_folders, create_folder, move_to_folder), plus the sandbox every published HTML document renders in. To build the document itself, use pd-intel-report. --- # PD Docs — Publishing, Sharing & Reading Documents PD Docs is PD Intelligence's document surface. It hosts what you produce — briefings, reports, decks, deep-dive writeups, notes — so people read it at a link instead of receiving pasted text or loose files, including people who have no PD Intelligence account. These tools cover the whole lifecycle: | Goal | Tool | |------|------| | Create a document / replace one you own | `publish_document` | | Change who can see a document you own (or edit, while the owner lets Editors share) | `share_document` | | Check how any readable document is shared | `get_document_sharing` | | Find a document you can read | `list_documents` | | Read one document's body | `read_document` (the whole body, one call) | | See, make, or file into folders | `list_folders`, `create_folder`, `move_to_folder` | `publish_document`, `share_document`, `create_folder` and `move_to_folder` write; the rest read. There is no chunked upload or download-link tool: the body goes in and comes out of `publish_document` / `read_document` whole. The server has other write tools outside this skill — tags and creators (see `pd-intel-tagging` and `pd-intel-creators`) — but none of them are involved here: publishing a document never changes tracked source data. ## Publish - Pick the `mime_type` for the content you actually produced: `text/html` for self-contained HTML reports/decks, `text/markdown` for briefings and writeups, `text/plain` otherwise. New documents default to `text/html`, so set it explicitly for markdown or the dashboard will render it wrong. - **Save the returned `id`.** Updates and sharing both need it. Publishing the same title again *without* `document_id` creates a duplicate, not a new version — to revise, pass `document_id` (you must own it) and omit `mime_type` to keep the current type (passing one converts the document). - Body limit is 5 MB of UTF-8 text. Large self-contained HTML decks can exceed this — check the size first and trim embedded assets if needed. - Every byte of `content` is a token you write out, so keep rendered HTML lean (no embedded fonts or large images) rather than hoping for an upload path — there is none. - `mime_type: "text/uri-list"` saves a link instead of a body (one http(s) URL on the first line, optionally a blank line and the prompt that made it) — the way to file a Claude artifact in PD Docs without copying it. PD Docs never fetches the target, and sharing the link document does not grant access to it. - To revise safely, pass `expected_version` (the `version` you last read): if someone else saved since, the call errors and writes nothing. An Editor on the document may update it too, not only the owner. - `dataset_id` records provenance only; it grants nobody access, and setting it requires the `documents_manage` capability on that dataset. Access is entirely `share_document`'s job. - Renaming a document re-slugs it. Retitle freely before sharing; after wide sharing, prefer keeping the title stable. A new document is **private to you** until you share it. ## Share `share_document(document_id, ...)` applies only the facets you pass: `visibility` (`"public"` mints a link anyone can open / `"private"` revokes it), `dataset_ids` (everyone with access to those datasets can read), `organization_ids` (every member of those organizations; you must belong to each — `shareable_organizations` in the response lists them), `emails` (named people, as `role` `"viewer"` or `"editor"`), `is_global` (publish as a Guide for every platform member — system admins only), and `remove_dataset_ids` / `remove_organization_ids` / `remove_emails`. - Every facet needs the share right: the owner, or an Editor while the owner has `editors_can_share` on. `visibility` stays owner-only and `is_global` needs a system admin; both raise before anything changes when you lack them. - `emails` never takes the owner's or your own address. A guest asked for `"editor"` lands as `"viewer"`; `email_share_roles` shows the role each address actually got. - Grants are additive and idempotent; within one call the order is fixed — visibility, then grants, then removals last — so a grant+removal of the same target ends removed. - **Check the failure lists.** Targets that fail validation come back in `dataset_share_failures` / `organization_share_failures` / `email_share_failures` instead of raising — the call "succeeds" even when a grant didn't happen. Dataset shares need `documents_manage` on that dataset. Report failed targets to the user, don't silently drop them. - **A recipient email does not have to belong to a platform user.** Three outcomes, and only one is the kind of failure you fix by picking someone else: an address with **no** platform account **succeeds** as an external guest — that is the supported way to reach someone outside the org; an address belonging to an **inactive** platform user **fails** ("Not an active authorized user"); a malformed address fails. Addresses are lowercased and matched case-insensitively, so casing never creates a duplicate share. - `shared_with` / `shared_datasets` in the response are the **full audience after the call**, not a diff — echo them back as confirmation. - Setting `visibility: "private"` kills the public link immediately; going public again mints a **new** URL, so previously circulated links stay dead. - Removals take the same share right as grants and reach anyone's share, peers included. A Viewer, or an Editor with sharing off, can remove nothing. - Calling `share_document` with only `document_id` changes nothing and returns the current sharing state of a document you may share. **Sharing notifies people in the app.** A share is not a quiet database write: - Granting to `emails` notifies **active platform members only** — an in-app "Document shared with you". Re-sharing to someone who already has an active share notifies nobody, so a silent response can mean they already had access. - **The grant itself never emails anybody**, and an external guest has no app to be notified in — so a guest share completes with its recipient entirely unaware. Delivery is a separate, deliberate step, and there are two ways to take it: the owner sends `reader_url` on themselves, or they use **Send email** in the dashboard's share dialog, which mails the reader link to anyone who already holds an active share, guests included. Sending is not granting — that action only reaches people already shared with, and it has no MCP equivalent. So whenever a grant reaches a non-member, hand back `reader_url` and name both routes; otherwise the call succeeds, the audience list looks right, and nobody ever opens it. - Granting to `dataset_ids` notifies **every user with access to that dataset** — "New document available". One `dataset_ids` entry can therefore ping a large group at once. - The sharer is never notified of their own share, and removals never notify. So sharing is outward-facing in the strict sense: confirm the intended audience before granting, name the dataset when a dataset share will broadcast, and hand back the right link: `public_url` for a public share, `reader_url` for a named recipient. ## Inspect `get_document_sharing(document_id)` works on any document you can read, including ones shared *with* you ("how was this shared with me?"). `my_role` ("owner" / "editor" / "viewer") and `is_owner` say where you stand. `public_url` is null for anyone but the owner, even on a public document. `shared_with` / `shared_with_roles` are filled for the owner and for an Editor who may share; for anyone else they come back empty. That is redaction, not "unshared". Datasets, organizations and `is_global` are visible to every reader. `folder` names the folder the document sits in and the people, datasets and organizations that folder passes down, so check it before saying who can read a document. Unreachable documents return the same not-found as nonexistent ones. Both `share_document` and `get_document_sharing` return **two** links, and they are not interchangeable: | Field | Link | Who it is for | |---|---|---| | `reader_url` | `/docs/{uuid}` | named recipients — members and external guests alike; the recipient signs in with Google or Microsoft on the invited address | | `public_url` | `/docs/public/{token}` | anyone at all; `null` while the document is private | Revoking public access invalidates the token, so a re-published public link is a **new** URL and every circulated copy of the old one is dead. ## Folders `list_folders` shows every folder you can open — yours, ones shared with you, your organizations' and Guides — as `{id, parent_id, name, path, kind, my_role, can_edit}`. A document inherits its readers from its folder and every folder above it, so `move_to_folder(folder_id, document_ids)` is itself a share: whoever can read the destination reads the document. `create_folder(name, parent_folder_id?)` makes one where `can_edit` is true. `move_to_folder` moves each item on its own and reports `failures` per item; check them. ## Find and read - `list_documents(query?, limit?)` returns **metadata only** for everything you can read, most recently edited first — owned, shared with you, and shared to a dataset you hold MCP access on. `query` is a full-text search over title, description **and body** (English stemming, last word as a prefix); results come best match first and each row carries a `snippet` of the matching words. `limit` defaults to 50. Drafts never appear. Rows include `folder_id`, `size_bytes` and `version` (the `expected_version` to pass when you revise). - `read_document(document_id)` returns that metadata plus `content`, the whole body as text, in one call. Check `size_bytes` from `list_documents` first: bodies run up to several MB, and when the `snippet` already answers the question, skip the read. A saved link also carries `link`: `{url, prompt}`. - The `id` comes back as a **string**, and timestamps use `Z` wire format. - A draft, a document you cannot reach, and an id that never existed all fail **identically** — so a not-found tells you nothing about whether the document exists. Don't infer one from the other. Use these to revise a document whose id you no longer have: `list_documents` with a `query` on its title, then `publish_document` with that `document_id`. ## Where documents land - **Dashboard** — the Documents section (`/documents`: explorer, per-document view, editor). Platform members only. - **PD Docs reader** — the standalone `/docs/{uuid}` and `/docs/public/{token}` views. A document-only page with no dashboard around it. Active members also see "Open in PD Intelligence" there; guests and signed-out readers do not. Sharing grants access to that one document and never platform membership. - **MCP clients** — accessible documents surface back as resources (`pd://documents/ID`) and, depending on exposure, as prompts, so published content is readable in later sessions. `list_documents` / `read_document` are the tool equivalents, for when you need to find one yourself. **Everything published as HTML renders inside a locked-down sandbox on every one of those surfaces.** It decides what your document may do — no stored state, no forms, and cited links that do not open. Read `references/pd-docs-runtime.md` before publishing anything with scripts, charts, or source links in it. ## Typical flows - **Deliver a report:** build it with `pd-intel-report` → `publish_document` with the right `mime_type` and the source `dataset_id` → `share_document` to the requested audience → confirm with title, audience, and the right link. When the audience includes anyone outside the org, say explicitly that they were **not** notified and hand over `reader_url`. - **Find one you published earlier:** `list_documents` with a `query` on the title → `read_document` if you need the body back. - **Revise in place:** find the `id` (it's in the publish response; otherwise the user can read it from the document's dashboard URL) → `publish_document` with `document_id`, omitting `mime_type`. - **Audience audit:** `get_document_sharing` → report visibility, datasets, and (if owner) recipients and public link. - **Lock down:** `share_document` with `visibility: "private"` and/or `remove_*` facets; warn that a revoked public link is dead permanently.