# DraftMesh — complete documentation

> The markdown workspace where humans and AI agents collaborate safely.

This is the entire DraftMesh user guide as one plain-text document: the same
documentation the app serves in its own help panel. Individual topics are at
https://www.draftmesh.com/docs. A shorter product summary is at https://www.draftmesh.com/llms.txt

Contents:
1. Getting started
2. Workspaces & sync
3. Reading, editing & suggesting
4. Comments & review
5. Supported file types
6. Data-driven pages
7. AI assistants (MCP)
8. History, restore & search
9. On your phone
10. Admin: Your organization
11. Admin: Access & sharing
12. Admin: Governing AI agents
13. Admin: Audit & activity
14. Admin: Security posture FAQ

---

# Getting started

Source: https://www.draftmesh.com/docs/getting-started
Section: Using DraftMesh

DraftMesh is a home for the documents you and your team — including AI assistants — write together. Every document is a **plain file on your disk**. DraftMesh never locks your writing into a database: you can open, edit, move, or back up the files with any tool you like, and DraftMesh will pick up the changes.

[Screenshot: The DraftMesh window with a document open]

## Who else is in here

A document is rarely yours alone. The people who open it want different things from it — and so do the AI assistants you connect. DraftMesh gives each of them exactly the verbs their job needs.

[Screenshot: Five columns: the author drafts and accepts suggestions; the reviewer highlights a sentence and comments; the approver signs off on one specific version; the guest sees one shared document on a link that expires; AI agents read, comment and propose, accept only where a document's owner granted it, and never approve, restore or share.]

## The window at a glance

- **Header** — the workspace switcher (folder icon), workspace search (`⌘ K` / `Ctrl K`), your name, sync controls, and the ⚙ Settings menu.
- **Files pane** (left) — every document in the open workspace, as folders and files. Click a file to open it. Hovering a folder offers **Copy link to folder**, a link that opens DraftMesh with that folder expanded. Drag the divider to resize, or collapse the pane with the ◀ button.
- **Document** (center) — the document itself, with a toolbar for switching between **Viewing**, **Suggesting**, **Editing**, and **Code**.
- **Comments** (right) — comments and suggestions on the open document. Toggle between a **List** and an **In-place** view.
- **Agents** — the robot button opens what AI assistants are connected to this document and what they have done with it, and is where you ask one to go and work on it. Asking an agent to work is a cloud feature, so on a DraftMesh running only on your own machine the button steps aside. See **AI assistants (MCP)**.
- **Version history** — the clock button opens the document's saved versions; every save is kept and any version can be restored.

## Workspaces

A workspace is just a folder on your machine. Open the workspace switcher in the header to pick one, add a folder you already have, create one in your account, or turn sync on and off per workspace.

## Making a new document

**New** at the top of the Files pane starts one: give it a name, pick the folder it goes in, and pick its type — Markdown, HTML, or JSON. The document is created and opens straight away, ready to type into. Typing a folder that doesn't exist yet makes it as well.

A document is still just a file, so nothing has to go through that button: create a `.md` in the workspace folder with whatever you already use — your editor, Finder, a script, a template — and it appears in the Files pane the same way. Renaming, moving, and deleting work like that too, and DraftMesh follows along.

Two other things can put a document in front of you: a connected AI assistant can create one (see **AI assistants (MCP)**), and creating a workspace in the cloud can seed it from a folder you upload (see **Workspaces & sync**).

## On a phone

Open DraftMesh on a phone and you get a different layout: a queue of what's waiting on you — sign-offs, replies, suggestions — instead of the full editor. See **On your phone**.

## Your name

Comments and edits are attributed to you. Running DraftMesh on your own machine without an account, set your display name under ⚙ Settings → **Your name** — that attribution is self-asserted, and the panel says so: it reads whatever you typed. Signed in, ⚙ Settings shows **Your account** instead, and your work is attributed to your verified account identity rather than to a name you can edit.

## The ⚙ Settings menu

Beyond your name, it holds:

- **Workspaces folder** — where workspaces downloaded from your account are put. Running DraftMesh on your own machine only.
- **Connect an AI assistant…** — see **AI assistants (MCP)**.
- **Administration…** — the organization console, shown only to admins. See **Admin: Your organization**.
- **Create an organization…** — signed in without one, this asks DraftMesh for an organization of your own so you can bring colleagues in. A person on the DraftMesh team reviews the request, and the dialog says so plainly; you can close it and come back — the request keeps its place.
- **Help & user guide…** — this guide.
- **Close** — dismisses the menu.

Signing in and out is not in this menu; those live in the header.

## Nothing leaves this device unless you say so

DraftMesh works fully offline with no account: reading, editing, commenting, history, and restore all work locally. Syncing to the cloud is a per-workspace opt-in — see **Workspaces & sync**.

---

# Workspaces & sync

Source: https://www.draftmesh.com/docs/workspaces-and-sync
Section: Using DraftMesh

## Opening and registering workspaces

Click the workspace name (or **Open workspace**) in the header to open the workspace picker.

What the picker offers depends on which DraftMesh you are using, and the difference is worth learning once. **DraftMesh on your own machine** works with folders on that machine, so it registers them, syncs them, and downloads account workspaces onto them. **DraftMesh cloud** — the signed-in web app — has no machine to point at, so it creates workspaces in your account instead. Registering a folder simply isn't a thing there, and it isn't hidden or greyed out: the section is absent.

[Screenshot: The workspace picker, with per-workspace sync toggles and a register-by-path field]

- **Open** a workspace by clicking its name.
- **Register a workspace…** points DraftMesh at a folder you already have — machine-side only. In the desktop app it is a button, **Add a folder**, which opens your system's folder picker. Reaching the same DraftMesh through a browser instead, where the page is not allowed to see real folder paths, it is a field: type the folder's absolute path and click **Register**. Either way the folder's markdown, HTML, and JSON files appear immediately — nothing is moved or converted.
- **Unregister** removes a workspace from DraftMesh's list — **on your own machine only**. The folder and its files are untouched: unregistering never deletes anything, and the dialog says so before you confirm. On **DraftMesh cloud** there is no unregister control, because there is nothing yet for it to do: removing a workspace from a hosted account isn't available, and a line under the workspace list says so rather than the picker offering a control that would remove nothing.

A workspace someone shared a document with you from is listed too, marked **Shared**. You can read its documents; changing one still needs that document to have been shared with you.

## Starting a workspace in the cloud

On DraftMesh cloud, **New workspace** at the bottom of the picker creates one in your account:

- **Workspace name** is all that's required.
- **Choose folder…** optionally seeds it: your browser hands DraftMesh the documents in the folder you pick — up to 100 of them, skipping anything hidden — any file *or* folder whose name begins with a dot — and anything that isn't a document. Each file that fails to upload is named rather than silently dropped, and the workspace is created either way.
- **Sync to this folder on my computer** is an optional hint. Your browser can't tell DraftMesh where the folder you picked actually lives, so if you also run DraftMesh on that machine and want it to adopt that exact folder rather than downloading a copy, type the path here.

**Create** makes it, and it opens.

## Getting a workspace onto another device

Open DraftMesh on the machine you want it on, and the picker's **In your account** section lists the workspaces in your account that this machine doesn't have, marked **Not on this device**. **Download to this device** asks which folder to put one in — give it an empty one — and **Download** materializes it there as real files.

## Turning sync on

Each workspace on your machine has its own **Sync on / Sync off** toggle in the picker. Sync is opt-in per workspace: a workspace you never sync stays entirely on this device. (On DraftMesh cloud there is nothing to toggle — those workspaces live in your account already.)

To sync you need to be signed in — click **Log in** in the header, or, on a machine with no DraftMesh window, run `draftmesh login` in a terminal (see **AI assistants (MCP)**). Once signed in and a workspace's sync is on:

- Changes save locally first, then sync to your account in the background. Working offline is always safe; DraftMesh catches up when you're back.
- The header shows a **Synced** pill when everything is up to date, and a **Sync now** button to trigger a sync immediately.
- Workspaces synced to your account can be downloaded onto your other devices, as described above. Where DraftMesh puts one down for you rather than asking, it uses your **Workspaces folder** (set under ⚙ Settings).

If a sync can't complete, the header says so honestly — for example "Sign in to sync", "Can’t reach DraftMesh right now", or "Already up to date". Your local files are never blocked by a failed sync.

## When two people change the same document

If a document changed both on your machine and in the cloud, DraftMesh merges the changes automatically when they don't overlap. When they genuinely collide, nothing is lost and nothing is silently overwritten: the document is flagged as a **conflict**, and a guided panel shows both versions so you decide what the document should say. Until you resolve it, both versions are kept.

Picking a document from the conflict list opens it for review. That view takes over the document area for as long as you are deciding — the document behind it is the very file you're resolving, so it has nothing to add — and **← Back to conflicts** returns you to the list. The **✕** in the panel's top corner closes the panel outright, from any state.

Inside the panel:

- Each conflicting passage is shown **side by side**: your version on the left, their version on the right, lined up against what the passage said before either of you touched it. The words that actually differ are highlighted, so two long paragraphs that differ by one clause no longer look identical. Where one version dropped the passage entirely, that column says **Deleted in this version**. **Show common ancestor** reveals the earlier text in full if you want to read it straight.
- Each column header says how many lines that version has and, when DraftMesh knows, when it last changed — **saved** for your copy, **synced** for the time theirs reached DraftMesh. Whichever is later is marked **Newer**. When a time isn't known, none is shown rather than guessed.
- Each conflicting passage offers **Use Your version**, **Use Their version**, **Keep both — Your version first**, **Keep both — Their version first**, or **Write custom text**. (Keeping both is two choices, because the order the two passages end up in is yours to pick.) **Next unresolved** jumps to the next passage still needing a choice.
- **Use your version for all** / **Use their version for all** set one answer across every passage in the document; individual passages can still be changed afterwards.
- **Resolve conflict** then restates, in plain language, exactly what your picks will do — "Your version will be used for 3 conflicts and their version for 2" — before **Confirm resolve** applies them.
- The choices stay pinned at the bottom of the panel while the passages scroll, so a long conflict never puts the buttons out of reach.

When several documents are in conflict at once, the list view offers **Use your version everywhere** / **Use their version everywhere**. It works through the documents one at a time, shows progress with a **Stop** button, and finishes with an honest tally — how many resolved, how many failed, and which were skipped because that choice wasn't available for them. Documents already resolved stay resolved if you stop.

Resolving updates the file on disk, and both versions stay in history either way.

## Sharing (on DraftMesh cloud)

Working in DraftMesh cloud — the signed-in web app, rather than the DraftMesh running on your own machine — the document toolbar carries a **Share** button. The Share panel is about **people**: an AI agent's access is not set here at all, but in **Connect an agent…** on the Agents panel (see **AI assistants (MCP)**).

- **People** — enter a **Teammate email** and a **Capability**: **View**, **Comment**, **Suggest**, or **Edit**. Sharing again with the same person changes their level rather than adding a second entry. Where the host can send email, the panel says *"an invitation email is on its way"*; where it can't, it says so — **Copy link** and send them the link yourself. The panel only ever promises what actually happened.
- **Whole workspace** — the same, for every document in this workspace at once. A per-document grant and a whole-workspace grant can coexist; a person's level on a document is the higher of the two.
- **Guest links** — for someone with no DraftMesh account at all. Choose a **Scope** (**Whole document** or **A section**), a **Capability**, and an **Expires** — **1 hour**, **24 hours**, **7 days**, or **30 days**. **Create guest link** mints it. A guest link can never carry **Edit**, and never lasts forever.
- Selecting text in the document offers two more routes: **Copy link**, a deep link that opens the document at that section for anyone who already has access, and **Share section…**, which issues a guest link exposing only that section.

**People with access**, **People with whole-workspace access**, and **Guest links** below list what exists, each row with **Revoke** behind a confirmation. Revoking bites immediately. Agents never appear in these lists — an agent's access shows on the Agents panel and in **Admin: Access review**.

Two things worth knowing before you try:

- **In an organization, sharing is admin-only.** The **Share** button is on everyone's toolbar, but in an organization DraftMesh answers a non-admin's Share panel with a refusal rather than a share roster — reading *who* has access is as restricted as granting it. **And sharing needs an organization at all** — on a personal account there is no organization behind it, so the Share panel's actions are refused. Holding **Edit** on a document never lets you pass it on.
- **A grant reaches further than the document.** The person you share with gains the workspace in their list, badged **Shared**, and can read its other documents — but only read. Writing anywhere still needs a grant on that exact document.

Admins get an organization-wide view of all of this; see **Admin: Access & sharing**.

---

# Reading, editing & suggesting

Source: https://www.draftmesh.com/docs/reading-editing-suggesting
Section: Using DraftMesh

Every markdown document has four modes, switched from the toolbar above the document:

[Screenshot: The document toolbar: Viewing, Suggesting, Editing and Code modes, plus Approve, Request changes and Request sign-off]

## Viewing

The default. The document renders as formatted prose. Select any text — a phrase, a whole section, even across a table — and a small menu appears:

[Screenshot: Selecting text in Viewing mode pops up Comment, Suggest and Copy link (plus Share section on DraftMesh cloud)]

- **Comment** — attach a comment to exactly the text you selected.
- **Suggest** — propose replacement text for the selection (see below).
- **Copy link** — copy a deep link that opens this document scrolled to this section.
- **Share section…** — on DraftMesh cloud, issue a guest link that exposes only this section. See **Workspaces & sync**.

Not every mode is offered on every document. **Suggesting** and **Editing** are absent on HTML and JSON files, which have no prose editor, and absent when the access you were granted doesn't reach that far — a document shared with you at **comment** shows **Viewing** and **Code** only, rather than buttons that would fail.

## Editing

A full rich-text editor: type directly, and formatting (headings, bold, lists, tables) is applied as you write. Editing shows a formatting toolbar above the document — **Bold**, **Italic**, a **Heading level** picker, **Bullet list**, **Ordered list** and **Link**. To leave a comment, switch to **Viewing** or **Suggesting** and select the text there. (Code mode has its own floating bar over the selection: **Bold**, **Italic**, **Inline code**, **Link**, and **Comment on selection**.)

There is no Save button — **changes auto-save**, and the status in the toolbar tells you when the document is **Saving…** or **Saved**. (`⌘ S` / `Ctrl S` saves on the spot if you'd rather not wait.) Every save becomes a version you can restore later. If a save can't be applied because someone else changed the document first, the toolbar says **Conflict**; other failures show **Save failed**, and pending typing shows **Unsaved changes** — rather than showing you a reassuring "Saved" that isn't true.

## Suggesting

Propose changes without changing the document. Select text and choose **Suggest**, or switch to Suggesting mode and simply type — your edits are captured as tracked changes instead of being applied.

[Screenshot: The suggestion form: proposed replacement text plus an optional note]

A suggestion shows up in the document as a strikethrough of the old text next to the proposed new text, and in the Comments panel with **Accept** and **Reject** buttons. The document's actual content only changes when someone accepts the suggestion.

[Screenshot: A suggestion rendered as tracked changes, with Accept and Reject in the comments panel]

## Code

The raw markdown, in a syntax-highlighted editor. Useful for precise formatting work — and for seeing exactly what is stored in your file, including the annotation markers described below. Code mode auto-saves just like Editing.

## Where comments and suggestions live

Comments, suggestions, and approvals are stored **inside the markdown file itself**, as invisible HTML comments (`<!-- @draftmesh{…} -->`). You can see them in Code mode:

[Screenshot: Code mode showing the raw markdown with DraftMesh annotation markers]

This is what keeps your documents portable: the file works in any editor, the annotations travel with the file, and if another tool edits the text, DraftMesh re-anchors the annotations to the surviving text — or marks them as orphaned rather than losing them.

---

# Comments & review

Source: https://www.draftmesh.com/docs/comments-and-review
Section: Using DraftMesh

Everything below is one step of the same short journey — draft it, ask an agent if you want one, let people question it in place, decide, and keep what you decided.

[Screenshot: A five-step flow across four lanes — author, AI agents, reviewers and guests, approver. Draft, ask an agent, review in place, decide, keep. Agents read, comment and propose; accepting suggestions can be delegated by a document's owner, while approving, restoring and sharing are always human acts.]

## Commenting

Select any text in Viewing mode and choose **Comment**. Comments anchor to exactly what you selected — a word, a paragraph, several blocks, or a table region — and the anchored text is highlighted in the document.

The Comments panel (the speech-bubble button in the toolbar) lists everything on the document. Each comment supports:

- **Reply** — threaded discussion under the comment.
- **Resolve** — mark it handled, after a confirming tap. Resolved comments leave the document text alone.
- **Assign** — hand the comment to a teammate or to a connected AI agent as a work item. The picker lists people and agents together, with agents badged as agents so you always know which you are handing work to. **Unassign** takes it back.

## Naming someone in a comment

Type `@` anywhere in a comment, a reply, or the note on a suggestion, and DraftMesh offers the people and agents already working in this workspace. Picking one drops their name into your text as ordinary prose — `@Ada Chen` — so the mention still reads correctly in any other editor, while DraftMesh also records it as a real reference. On a phone, that reference is what puts the comment in that person's Inbox (see **On your phone**).

Mentioning someone does not grant them anything. On a hosted DraftMesh account, a person you mention who can already reach the document is emailed about it; a local daemon sends nothing, and nobody is emailed about a document they cannot open. If they can't reach the document, share it with them.

Use the **View** toggle at the top of the panel to switch between **List** (all comments in a rail) and **In-place** (each comment beside the text it refers to — needs a wide enough window):

[Screenshot: In-place comments render beside the text they anchor to]

If the text a comment anchored to is later deleted or heavily rewritten, the comment isn't lost — it moves to an **Orphaned comments** section so the discussion is preserved.

## Reviewing suggestions

Suggestions appear in the same panel with **Accept** and **Reject** buttons; you can also click the tracked change where it sits in the prose and get **✓ Accept** / **✕ Reject** right there. Accepting takes a confirming click — *"Accept and apply?"* — then applies the proposed text; rejecting removes the proposal and leaves the document unchanged. Accepting is normally a human act: an AI assistant can propose an edit but not apply one — unless the document's **owner** has deliberately granted a specific agent accept/reject permission on that document (see **AI assistants (MCP)**). Sign-off is always human, on every document.

If the text moved under a suggestion, the controls say so — *"The original text has changed"* — instead of applying a change to the wrong place. A suggestion whose stored change can't be read is offered for rejection only.

## Approving a document

The document toolbar carries **Approve** and **Request changes** — a lightweight sign-off for "this version is good":

[Screenshot: After approving, the toolbar shows who approved]

- The badge is a **record**, not just a name: who decided, when, any note they left, and — once the version history has loaded — **exactly which version** they decided on.
- **View approved version** opens that version read-only, so "what did we actually sign off on?" is one click away.
- If the document changes after an approval, the badge greys out and says **content changed since** — a stale approval can't masquerade as a current one.
- **Request changes** records the opposite signal, visible to everyone on the document.
- Mixed decisions stay side by side. DraftMesh never reduces several people's sign-offs to one overall verdict — with one exception, below: an approval from outside your organization needs an internal one beside it.
- **Who may decide.** Anyone with **edit** on the document — and anyone an *open* sign-off request is addressed to, whatever level they hold: being asked is itself the permission, for that document, until the request is answered or cancelled. Agents never decide.
- **External decisions.** A decision by someone outside your organization — a guest, or a person from another organization the document was shared with — is marked **(external)** on its badge. It never stands alone: the toolbar says **Awaiting an internal sign-off** until a member of the owning organization also approves. That is the only aggregate rule DraftMesh applies to sign-offs.

## Asking someone to sign off

**Request sign-off** — the third button in the toolbar, after **Approve** and **Request changes** — turns "could you look at this?" into a tracked ask rather than a message in another app.

- Tick the people you want. The list is everyone active in this **workspace**, not only the people who have touched this document — minus you, and minus every agent. Approving is a human act, so an agent can ask for a sign-off but can never be asked for one. (The **Assign** picker on a comment is the other way round: it offers people and agents together, because doing the work is not deciding.) Anyone the list doesn't hold can be typed into **Someone else's name**.
- Add an optional note — *what* should they look at — and choose **Send request**.
- Each open request shows beside the sign-off controls — "Ada asked you to sign off", with the version and note where there are any. A request addressed to you is highlighted.
- When you Approve or Request changes, the requests addressed to you close automatically — the badge beside them is the answer. An addressee can answer even on a document they hold at **view** or **comment** — the request is what lets them decide, and only that.

A request is about the whole document, so it lives in the toolbar rather than as a comment chip in the margin. On a phone, sign-off requests arrive in the Inbox — see **On your phone**.

**Who has actually looked?** — on a hosted workspace, an admin sees a **Reviewers** strip under the sign-off controls: one line per person the document was shared with, per guest link, and per sign-off addressee, in plain words — *Raj · invited yesterday, not opened* · *Priya · opened today, no comment* · *Legal · approved v3 · content changed since* · *Elena — pricing review · approved (external)*. A collapsed strip counts external approvals apart and says *awaiting an internal sign-off* when they are the only ones. "Opened" is recorded when someone opens the document in DraftMesh (a guest, by the link they used); it is never a reason to grant or refuse anything, and only admins see it. A sign-off addressed to a typed name that matches nobody with access is called out on its own line rather than quietly listed as a person. Members and guests do not see the strip — the document's approval badges and open requests are what everyone sees. A guest's page does carry the sign-off *state* — *v4 · approved v3 · edited since*, or *v4 · approved (external) v4 · awaiting an internal sign-off* — but never the approver's name or note.

## Handing comments to an AI assistant

**✦ Form reply** (next to the document name, with a count of the comments and suggestions on the document) turns the document's comments into a structured brief for an assistant.

- **Scope** picks **My comments** or **All open comments**.
- The prompt is shown in full and is editable before it goes anywhere. Editing it here changes only the brief — never your comments.
- **Copy prompt** puts it on the clipboard for any AI chat, which is the point of the feature: the assistant needs no connection to DraftMesh at all.
- Where DraftMesh *can* reach an agent for you, a **Send to agent:** row appears under the prompt and hands it over directly. Running DraftMesh on your own machine, that target is **Claude Code on this machine**; with registered agents you pick which one. The row reports back plainly — *Sent to …* or *Send failed — try again*.

If your assistant is connected properly, you may not need this at all: see **AI assistants (MCP)**, where agents read comments, answer questions, and file suggestions themselves.

---

# Supported file types

Source: https://www.draftmesh.com/docs/supported-files
Section: Using DraftMesh

DraftMesh lists and manages the file types in the table below. Everything else in the folder is left alone (and anything ignored by the folder's ignore rules stays hidden).

The extensions are matched exactly, so `.md`, `.html` and `.json` are documents while `.htm`, `.jsonc` and `.json5` are not — a file with one of those is simply left where it is. Case doesn't matter.

`.markdown` sits in between. DraftMesh running on your own machine lists it and opens it like any other markdown file, but it is outside the sync scope — so it stays on that machine and never travels to your account. Rename it to `.md` if you want it synced.

| Type | Extension | What it's for | Modes | Comments & suggestions | Approvals | History & sync |
| --- | --- | --- | --- | --- | --- | --- |
| Markdown | `.md` | Prose documents — the heart of DraftMesh | Viewing, Suggesting, Editing, Code | Yes | Yes | Yes |
| HTML | `.html` | Rendered pages: dashboards, reports, business cases | Viewing, Code | Comments only | Yes | Yes |
| JSON | `.json` | Data files, typically feeding an HTML page | Viewing, Code | No | No | Yes |
| Google reference | `.gdoc`, `.gsheet`, `.gslides` | A pointer to a document that lives in Google Drive | Viewing, Code | No | No | Yes |
| Office document | `.docx`, `.xlsx`, `.pptx` | Word, Excel and PowerPoint files, previewed in place | Viewing | No | No | Yes |

## Markdown documents

Full collaboration: all four modes, comments and suggestions anchored to any selection, approvals, version history, search, and sync. The file stays plain markdown that any editor can open.

## HTML documents

An `.html` file renders as a real page inside a sandboxed frame — styles and scripts work, but the page can't reach outside its sandbox. You can comment on the rendered content and approve the document; editing happens in Code mode. HTML pages can also read JSON data files from the same workspace and update live — see **Data-driven pages**.

## JSON data files

A `.json` file opens as a collapsible tree in Viewing mode and as an editable text file in Code mode:

[Screenshot: A JSON file rendered as a collapsible tree]

JSON files are **data, not prose**, so they deliberately carry no comments, suggestions, or approvals — but they are versioned like everything else, so history answers "who changed this number, and when", and any version can be restored. DraftMesh refuses to save invalid JSON (from the editor or from an AI agent), so a typo can't silently break the dashboards reading the file. A JSON file written invalid by an outside tool still opens — Code mode shows it with a notice so you can fix it.

## Google reference files

A `.gdoc`, `.gsheet` or `.gslides` file — the small pointer file Google Drive for Desktop leaves on disk — is **not** the document. It is a few hundred bytes naming a file that lives in Google, so DraftMesh lists it, syncs it and versions it like any other file, and opens it to a card with the document's title, its owner, and an **Open in Google** link. That link is the way to read or change the document; the truth stays in Google, and nothing DraftMesh shows is editable here. There are no comments, suggestions or approvals on a pointer.

**Connect Google and the card shows more.** With the connector attached, DraftMesh reads the file's details from Drive and takes a **snapshot** of its contents, framed as *"Snapshot as of …"* — a Google Doc as read-only text, a Slides deck as its slides in order, a Google Sheet as a read-only grid with its tabs. The snapshot is also what makes the document **findable**: a phrase that appears only inside the Google document will match the reference in search, and an AI agent reading the file through DraftMesh sees the snapshot text as well as the pointer. Both of those start once DraftMesh has actually taken the snapshot, which it does in the background shortly after **you open the reference in DraftMesh, or an AI agent reads it through DraftMesh** — and takes again, the same way, the next time either happens after the document has changed in Google. A snapshot, once taken, is kept on this machine across DraftMesh restarts. Searching never waits on Google, so a reference nobody has opened or read yet still matches on its title, its owner and its link, and matches on its contents from then on. Snapshots are a cache held on the machine that took them — they never travel on the sync wire and never become a document of their own. A very large spreadsheet may be too big to snapshot; that card keeps its details and its link.

**Sharing a reference shares the snapshot.** The snapshot is read with the Google access of the account that connected Google to this DraftMesh — Google's own sharing on the referenced document is never consulted for whoever reads it here. So the rule is that a grant on a reference is a grant on its snapshot: treat a `.gdoc`, `.gsheet` or `.gslides` reference as workspace content whose text is the Google document's, and share it as you would share the Google document itself. Today the two halves live on different hosts. Google connects only to the DraftMesh on your own machine, which has no sharing door, so the snapshot there is seen by whatever reads through that DraftMesh — the reference's card, search, and any AI agent connected to it. DraftMesh cloud has no Google connector, so a reference reached through a hosted account — by a person it is shared with, or an agent granted it — shows the reference's own details and its link, and matches search on those, with no snapshot. Where a grant is made, the door says so: the Share panel and the Connect-an-agent dialog both carry this note on a reference. A snapshot is held only on the machine that took it.

**Every part of this degrades quietly.** No connector, a revoked token, a deleted Drive file, Google being down — the reference still lists, still opens, and still shows its title and link; the snapshot is simply absent, and search falls back to matching the pointer's own text as it did before. The one case that asks something of you is a connection made before slide previews existed: its access doesn't cover Slides, so the card offers **Reconnect Google**.

## Office documents

A `.docx`, `.xlsx` or `.pptx` file is an opaque container, not text, so DraftMesh **previews** it rather than editing it: Viewing mode renders the document, and there are no comments, suggestions or approvals. They are versioned and synced like everything else, and their text is extracted for search, so a phrase inside a Word document or a deck finds the file.

---

# Data-driven pages

Source: https://www.draftmesh.com/docs/data-driven-pages
Section: Using DraftMesh

An HTML document can read JSON files from its own workspace and refresh itself when the data changes. That turns a workspace into a small live dashboard: the numbers live in a `.json` file anyone (or any agent) can update, and the `.html` page presents them.

[Screenshot: An HTML dashboard rendering data from a workspace JSON file]

## How a page reads data

Inside a DraftMesh-rendered HTML document, a `window.draftmesh` bridge is available:

- `window.draftmesh.readJson(path)` — returns a Promise of the parsed contents of a JSON file in the same workspace (the path is relative to the workspace root, e.g. `"metrics.json"` or `"data/sales.json"`).
- `window.draftmesh.writeJson(path, data)` — asks to save `data` back to a JSON file in the same workspace. **You** decide: DraftMesh shows a confirmation naming the file and previewing exactly what would be written, and nothing is saved unless you approve it. See **Saving data from a page** below.
- `window.draftmesh.onDataChange(path, callback)` — calls your callback whenever that file changes, so the page can re-read and re-render. No polling needed. Omit the path (`onDataChange(callback)`) to hear about *every* data file in the workspace; the callback is handed the path that changed. It returns a function that unsubscribes.

Pages can only touch `.json` files from their own workspace — the bridge is not a general file or network API.

## A complete example

Create `metrics.json`:

```json
{
  "quarter": "Q3",
  "signups": [
    { "week": "W1", "count": 42 },
    { "week": "W2", "count": 58 }
  ]
}
```

And `dashboard.html`:

```html
<!doctype html>
<html>
<head><meta charset="utf-8"><title>Signups</title></head>
<body>
<h1>Signups</h1>
<div id="out">Loading…</div>
<script>
  function render(data) {
    document.getElementById("out").textContent =
      data.quarter + ": " +
      data.signups.map(function (s) { return s.week + "=" + s.count; }).join(", ");
  }
  function load() {
    window.draftmesh.readJson("metrics.json").then(render);
    window.draftmesh.onDataChange("metrics.json", function () {
      window.draftmesh.readJson("metrics.json").then(render);
    });
  }
  if (window.draftmesh) { load(); } else { window.addEventListener("draftmesh-ready", load); }
</script>
</body>
</html>
```

The last line is the recommended startup pattern: use the bridge if it's already there, otherwise wait for the `draftmesh-ready` event.

If a read fails, the Promise rejects with a reason you can show honestly: `not_found` (no such file), `invalid_json` (the file doesn't parse), or `unsupported_path` (not a `.json` file in this workspace).

## Saving data from a page

An interactive page — a cost model with editable inputs, a planning board — can offer a real Save button:

```js
saveButton.onclick = function () {
  window.draftmesh.writeJson("metrics.json", currentState).then(
    function () { statusEl.textContent = "Saved."; },
    function (err) {
      statusEl.textContent = err.message === "denied" ? "Not saved." : "Couldn't save (" + err.message + ").";
    }
  );
};
```

Calling `writeJson` never writes anything by itself — it asks. DraftMesh (not the page) shows a confirmation dialog naming the target file with a preview of the exact JSON that would be written; the save only happens when you approve it, and it lands as a normal versioned change attributed to you, so history and rollback apply. Every open page watching that file then refreshes through `onDataChange` as usual.

Details worth knowing:

- The target file must already exist — pages can update data stores, not create files (`not_found` otherwise).
- Declining the dialog rejects the Promise with `denied`; treat it as a normal answer, not an error.
- If the file changed between the preview and your approval, the save is refused with `conflict` — re-read and ask again.
- One ask at a time per page (`busy`), values must serialize to JSON (`invalid_data`), and very large payloads are refused (`too_large`).
- The bridge works in the full DraftMesh app. On the phone reader, pages render but the bridge doesn't answer yet — a `readJson` or `writeJson` Promise there never settles, so don't leave your page's UI waiting on one without a visible idle state.

## Updating the data

Anything that changes the JSON file updates every open page watching it:

- **In DraftMesh** — open the `.json` file in Code mode and edit it. Saves are validated, so you can't ship a syntax error to your dashboards.
- **Any other tool** — the file is just a file. Edit it in your code editor, write it from a script or a scheduled job; DraftMesh notices the change on disk, versions it, and notifies open pages.
- **An AI assistant** — a connected agent can update the file with its document-saving tool, with the same validation and the change attributed to the agent in history. See **AI assistants (MCP)**.

Every update lands in version history, so a bad number can always be traced and rolled back.

---

# AI assistants (MCP)

Source: https://www.draftmesh.com/docs/ai-assistants
Section: Using DraftMesh

AI assistants join your documents through **MCP** (Model Context Protocol) — the standard way tools like Claude, Cursor, and VS Code connect to outside services. A connected assistant can list and read your documents, search them, answer questions left in comments, reply to comment threads, propose suggestions, and update data files — always as itself, with its own name on everything it does.

## Connecting an assistant

Open ⚙ Settings → **Connect an AI assistant…**. You get the same list of assistants either way you're using DraftMesh, but what the panel can do for you differs:

[Screenshot: The Connect an AI assistant panel, offering Cloud and Local connections]

- **In your browser, on DraftMesh cloud** — the panel shows the **Cloud** setup line for each assistant: Claude, Claude Code, Cursor, VS Code, Codex and Windsurf. Copy the one for yours into its MCP settings and sign in when it asks. DraftMesh can't see your computer from there, so it says nothing about what you have installed and writes nothing for you.
- **Running DraftMesh on your own machine** — the panel additionally detects which assistants are installed and offers each one **both** ways to connect.

The two connections:

- **Cloud** — connects the assistant to your synced documents, from any device. It signs in with your account, nothing is installed, and its actions are recorded as acting on your behalf. Requires being signed in.
- **Local** — connects the assistant to the documents on this machine. No account needed; DraftMesh must be running. Click **Connect** to have DraftMesh write the configuration for you, or **Copy** the shown snippet and add it to the assistant's own settings yourself. The snippet is displayed in full — what you see is exactly what gets written.

After connecting, restart the assistant so it picks up the new connection.

### From a terminal, with no DraftMesh window

A DraftMesh installed headlessly — `npm i -g draftmesh`, or the one an assistant's connector starts on its own — needs no settings to reach the cloud: the package carries its cloud environment. Signing it in is one command, `draftmesh login`, which prints a short code and a link to approve it in a browser (any browser, so it works over SSH); `draftmesh whoami` shows who it is signed in as, and `draftmesh logout` ends the sign-in on that machine. An assistant connected locally can also start the same sign-in itself with its `connect_cloud` tool: it hands you the code to approve and never sees a credential — the sign-in lives in DraftMesh on that machine, and every client of it acts as you. To keep a headless DraftMesh entirely off the cloud, start it with `DRAFTMESH_LOCAL_ONLY=1`.

On your own machine each assistant's card says **Installed on this machine** or **Not detected**, and whether DraftMesh can see a connection for it — for some assistants it honestly can't, and says so rather than guessing. A card DraftMesh set up itself offers **Reconnect** and **Disconnect**; **Disconnect** removes only the entry DraftMesh wrote.

## What agents can — and can't — do

Agents get a deliberately bounded set of verbs:

- **Can:** read documents and history, search, add comments and replies, answer questions, resolve or reopen markers, propose suggestions, **ask a named person to sign off** on a document, save documents they've been granted edit on — typically the data files an agent is asked to keep fresh — and — where the connection offers it — create a new, empty workspace.
- **Can, only where a document's owner deliberately granted it:** accept or reject suggestions on that one document. This is off by default everywhere, it rides only on an **edit** grant, and only the document's owner — not any editor or admin — can switch it on.
- **Can't, ever:** approve or sign off a document, restore old versions, or manage sharing. **Approving is a human act**, whatever an agent has been granted. This boundary is enforced by DraftMesh itself, not by the assistant's good manners.

Asking for sign-off sits on the proposing side of that line: an assistant can record the ask and put it in your queue, but only you can answer it.

On shared cloud workspaces, a registered agent's default capability is **suggest** — it can read, comment, and propose, but its text only enters a document when a human accepts it. Granting an agent full edit rights — or the accept/reject permission that can ride on it — is an explicit, per-document decision by that document's **owner**, with its own confirmation step.

## Asking an agent to look at a document

Everything above is the assistant coming to DraftMesh. The reverse — you asking an agent to go and work on the document in front of you — has its own **Agents** panel, opened with the robot button on the document toolbar, next to the ones for Comments and version history. It is a panel rather than a corner of the Comments panel so that which agents are connected, and what they have done, is one click away instead of a scroll past every comment. Where there is nothing to report it says exactly what it knows — *"No active agent has access to this document"*, or for a workspace owner *"This organization has no active agents"* — rather than leaving you wondering, and while it is still fetching it says that too. It lists active agents only, and unless you own the workspace only the ones that already hold access on the document, so an empty panel is a statement about those and nothing wider. Asking an agent to come and work is a cloud feature: on a DraftMesh running only on your own machine the panel answers *"Agents aren't available on this host."* and the button then steps aside.

**Request review from an agent** opens a short form:

- **Agent** — which one. If it can't be reached yet, the form says so — *"This agent has no delivery endpoint, so it can't receive requests yet."* — rather than accepting a request that goes nowhere.
- **Scope** — **Whole document**, or **A section** and then which heading.
- **Instructions** — *"What should the agent look at?"* This is the whole brief; there is no other channel.
- **Send request**, and the request appears in the list below as it progresses.

If the agent doesn't have access to the document yet, sending grants it **Suggest** — enough to read, comment and propose, and never more. Giving an agent **Edit** stays a deliberate act with its own confirmation, and it is made in **Connect an agent…**, which is where an agent's access is set. Where you aren't allowed to grant, the form says so instead of failing at send time.

Each request shows what became of it: **Pending**, **Delivered**, **Completed**, **Failed**, or **Expired**. A completed review offers **Show the comment this answers**, so the result is one click from the thread it belongs to. **Cancel request** withdraws one that hasn't finished — anything still pending or delivered — and a request replaced by a newer one is marked *"Superseded by a newer request."* rather than left looking stuck.

**Connect an agent…**, below it, is the other question — not *"do this now"* but *"do this whenever"*: a standing rule that wakes an agent every time the document changes. That is administration rather than day-to-day work, and it is admin-only; see **Admin: Governing AI agents**. Rules connected to this document are listed here as **Connected agents**. A rule pinned to this exact document puts each firing in the list below, as a **Processing** request alongside the ones you sent by hand. A rule with a wider reach won't: DraftMesh says so under the list — the firing lands on whichever document changed, *"which, for a rule covering more than this file, is often not this one"*.

## Attribution and audit

Everything an agent does is labeled as agent work — in comment threads, in document attribution, and in version history. You can always tell whether a change came from a person or an assistant, and which one.

## Putting agents to work

- **Assign** a comment to a connected agent to hand it a task.
- Leave a **question** in a comment and let the agent answer it in-thread.
- Have an agent keep a **data file** fresh — metrics, statuses, inventories — while humans work in the prose (see **Data-driven pages**).
- Or skip the connection entirely: **✦ Form reply** exports a document's comments as a paste-ready handoff for any chat assistant.

---

# History, restore & search

Source: https://www.draftmesh.com/docs/history-and-search
Section: Using DraftMesh

## Version history

Every save — yours, a teammate's, or an agent's — becomes a version. Open the clock button in the document toolbar to see them:

[Screenshot: The version history panel listing saved versions with author and time]

- Click a version to **preview** the document as it was.
- **Restore version** makes that content the current document — as a *new* version, so nothing is ever destroyed. You can restore a restore.
- Approvals are recorded against specific versions, so history also answers "what exactly did we sign off on?"

Comments and suggestions live inside the file, so a version captures the prose *and* the discussion around it at that moment.

### Reading just the decisions

Sign-offs appear in the list as their own rows — **Approved this version** and **Requested changes on this version**, each against the version it was recorded on. The **Show: All versions / Decisions** toggle at the top of the panel hides everything else, leaving the document's decision trail on its own.

The filter is a view over the versions already loaded, so switching it back loses nothing. If the loaded pages hold no decisions the panel says so, and **Load older versions** keeps looking further back.

## Search

Press `⌘ K` (`Ctrl K`), or click the search box in the header:

[Screenshot: The search palette showing file-name and full-text matches]

Results come in three groups:

- **Files** — file-name matches.
- **Text matches** — full-text hits with a snippet.
- **Related** — semantically related passages, found by meaning rather than exact words. The relatedness index builds in the background on your machine; it appears shortly after a workspace is first opened.

Use `↑` `↓` to move, `Enter` to open, `Esc` to close. Search covers the workspace you have open.

## If something goes wrong

- **A save can't be applied** (someone else changed the document first): the toolbar reads **Conflict**, and DraftMesh never overwrites silently — re-open the latest version and your change can be re-applied. Other failed saves read **Save failed**, and typing not yet saved reads **Unsaved changes**.
- **"Some documents were not searched"**: a full-text search gives itself a few seconds and stops there rather than leaving you waiting, so on a very large workspace it can run out of time before it has read everything. What it did find is shown and is correct — it is just not the whole workspace, so don't read an empty result as proof that nothing matches. Searching again is the fix; narrowing the words is not, because the documents it missed were never read either.
- **A comment lost its text**: it becomes an orphaned comment in the panel rather than disappearing.
- **A bad edit shipped**: find the last good version in history and restore it.
- **A sync conflict**: both versions are kept and a guided panel lets you decide — see **Workspaces & sync**.

---

# On your phone

Source: https://www.draftmesh.com/docs/on-your-phone
Section: Using DraftMesh

Open DraftMesh in a phone browser and you get a layout built for a phone rather than a shrunken desktop window. It is a **review** surface: the work that arrives in bursts — sign-offs, replies, suggestions to accept or reject — done with a thumb, in a queue.

Long-form writing stays on the desktop layout. There is no rich-text editor here by design.

## Getting the phone layout (or leaving it)

DraftMesh picks the layout from the width of your screen. An explicit choice overrides that, and is remembered on this device from then on:

- **Me** tab → **Layout** → **Use the desktop layout** switches to the full app.
- To come back: in the desktop layout, **⚙ Settings** → **Layout** → **Use the phone layout**. (The entry appears when you're on a phone-sized screen or you previously chose the desktop layout.)
- Adding `?surface=mobile` or `?surface=desktop` to the address forces one, and is likewise remembered until you change it.

## Inbox — the things waiting on you

The Inbox is the home tab: everything in the open workspace that names *you*, newest first. An item lands here when someone asks you to sign off, assigns you a comment, mentions you, replies to a thread you started, or leaves you a question.

Filter chips across the top — **All**, **Approvals**, **Comments**, **Suggestions** — narrow the queue, and each chip carries its own count.

Approval rows carry two buttons:

- **Approve** signs off without opening the document. The request names the exact version you're signing, so this is a real decision, not a shortcut past one.
- **Review first** opens the sign-off review screen below.

Under the queue, **Done today** is a receipt strip of what you've already cleared. A tick means the write actually landed; a plain dot means it's still in flight; anything that failed says so in words rather than pretending it went through.

Tapping the workspace name at the top of the Inbox switches workspaces. The queue is always the open workspace's.

## Nothing is sent the instant you tap

Every action is queued rather than sent straight away, and the ones you're most likely to regret — **Approve**, a reply, a new comment, **Request changes** — sit for about five seconds behind an **Undo** button in the toast. Undo inside that window is a local drop: the write never happened at all.

The deliberate endings — resolving a thread, accepting or rejecting a suggestion, sending a suggestion of your own — go without the undo window, because each of them is already the confirming tap.

Leaving the screen, taking another action, or backgrounding the browser sends a queued action immediately rather than waiting out the timer. If a send fails, the item comes back into your queue with a **Retry** — nothing is quietly lost, and the **Done today** strip says "didn't send" rather than showing a tick.

## Reviewing a sign-off request

Tapping an approval item opens the review screen, which shows **what changed since you last approved this document** rather than the whole file again — with the version you're comparing against named in the band at the top. Your first sign-off on a document shows it in full, as does a document too large to compare change by change; the screen says which of those you're looking at.

- **Approve** records the decision, pinned to the version you just read.
- **Request changes** opens a sheet for a note explaining what should change first.

If the document moved underneath you between opening it and deciding, DraftMesh refuses the decision rather than attaching your name to prose you didn't read.

## Reviewing a suggestion

A suggestion item shows the proposed replacement against the current text, with **Accept edit** and **Reject**. If the text a suggestion anchored to has changed too much to apply automatically, the screen says so instead of guessing.

## Replying to a comment

Tapping a comment or question opens the thread sheet: the whole discussion, a composer, and **Resolve**. Quick-reply chips offer the common answer for that kind of marker — they *fill* the composer rather than sending, so nothing goes out over your name that you didn't read first. Type `@` to mention someone.

Resolve is disabled while you have text in the composer: resolving is not a place for a reply to disappear into.

## Reading a document

Open a document from the **Docs** tab or **Search**. (Inbox items open the review screen or the thread directly, not the whole document.) The reader renders the prose with existing comments and suggestions highlighted in place; tapping a highlight opens its thread — or, for a suggestion, the accept/reject screen above. Below the prose is a list of everything open on the document, in case a marker's text has moved.

Select any passage and a bar appears above the tab bar with **Comment** and **Suggest** — the same two acts as the desktop selection menu.

## Docs and Search

- **Docs** browses the workspace as folders and files, with a short list at the top: the most recently edited documents where DraftMesh knows edit times, otherwise anything waiting on you followed by A–Z. The heading over the list says which of those you're getting.
- **Search** matches file names as you type. Searching the *text inside* documents is a second, deliberate tap — **Search inside documents** — so a phone on a cellular connection doesn't read the whole workspace for every keystroke. Recent searches are kept for one-tap repeats.
- **Me** shows who you're signed in as, lets you switch workspaces, and holds the escape hatch back to the desktop layout.

---

# Admin: Your organization

Source: https://www.draftmesh.com/docs/administration
Section: Administration

DraftMesh's **Administration** console is where your organization's admins can see the whole account at once: what has happened, who can reach which documents, who has been invited, and which agents are registered.

It lives under ⚙ Settings → **Administration…**, and it is part of the signed-in cloud product. A DraftMesh running locally on your own machine has no organization and no console.

## Where your organization comes from

DraftMesh does not have its own directory of companies. Your organization is your **WorkOS organization** — the same one your identity provider signs people into — paired with a DraftMesh account that every workspace, share, agent, and audit record then belongs to.

**That pairing is set up deliberately, not on first sign-in.** An organization DraftMesh has not been set up for is refused rather than quietly created, which is what keeps one company's records from ever landing in another's. You ask for one with ⚙ Settings → **Create an organization…**; a person on the DraftMesh team reviews the request, and once it is granted you are its first admin.

Signing in *without* an organization is different: you get a personal account, created for you on the spot. It is yours and nobody else is in it. Sharing, agents and the console all belong to an *organization*, though, so a personal account has none of them — ask for one when you want to bring colleagues in.

## Admins and members

There are exactly two roles, and they are **flat**: **Admin** and **Member**. Every admin holds the same authority as every other — there is no senior admin, and no per-section permission to hand out.

**The person the organization was set up for is its first admin.** Everyone else who signs in afterwards arrives as a member, until an admin says otherwise or they were invited as an admin.

Admins change that in **Administration…** → **Overview**, in the **Members (as observed)** table: each person's row carries a **Role** of **Admin** or **Member**, and a **Make admin** / **Remove admin** button beside it. Two things the button refuses, and says why rather than failing silently:

- **An organization can never reach zero admins.** Once the member list has finished loading, the control on the last remaining admin is disabled and reads *"This is the organization's only admin. Promote someone else before removing their admin access."* — and whether or not the console has got that far, the server refuses to remove the last admin.
- **Only people can hold a role.** Agents and service accounts are listed but never promotable.

A demotion bites immediately: the next thing that person asks DraftMesh for is answered as a member, without waiting for them to sign out.

You can also set the role up front — an invitation sent from the **Members** section carries **Member** or **Admin**, applied when that person first signs in.

**Your account also records an owner**, separately from these roles. It is the billing and accountability contact, and it confers no extra power in the product — an owner who is not an admin sees no console. There is **no screen for changing who the owner is**, so if that needs to move, ask DraftMesh. Admin authority itself is not stuck: promote and demote as the team changes.

## Inviting someone in

**Administration…** → **Members** → **Invite someone…** takes an **Email address** and a **Role** (**Member** or **Admin**, defaulting to Member), and **Send invitation** puts the invitation out through your identity provider — this one always emails the person, where a document share does only when the host can send email (its Share panel says which happened).

The role you pick is applied when they first sign in, not before. Until they accept, the invitation sits in the table below with a state of **Pending**, **Accepted**, **Revoked**, or **Expired**, and a pending one can be withdrawn with **Revoke**.

Inviting the same address twice is safe and honest about itself: you are told the person *"already has an invitation outstanding — nothing new was sent"*, or that they are *"already a member of this organization"*, rather than quietly sending a second email.

An invitation is about getting into the organization. It grants no documents — sharing is a separate act, described in **Admin: Access & sharing**.

**Seats.** If your organization has a seat limit and every seat is taken, an invitation is refused and the console says so in as many words — *"this organization has no seats left (10 of 10 in use)"*. A seat is a person DraftMesh has seen in the organization; an invitation you have sent does not use one until that person signs in, so it is possible to send more invitations than you have seats and end up over the limit, which the **Seats** tile on Overview shows. Plans and seat limits are set by the DraftMesh team, not from this console — raising one is a conversation, not a button.

## What an admin can do that a member cannot

| | Admin | Member |
|---|---|---|
| ⚙ Settings → **Administration…** | Shown | Not shown |
| Share a document, or revoke a share | Yes | No |
| Create or revoke a guest link | Yes | No |
| Register, rotate, or revoke an agent | Yes | No |
| Invite someone to the organization | Yes | No |
| Make someone an admin, or remove admin | Yes | No |
| Read the organization's audit log | Yes | No |
| Read and write documents they have access to | Yes | Yes |
| Read and write every document in the organization | Yes | No |

**An admin's reach is not limited to the documents shared with them.** Admin authority carries **edit** on every document in the organization, with no grant needed — promoting someone hands them that.

A member does not see a greyed-out Administration entry, or one that fails when clicked. They see **nothing** — the menu simply does not have it. That is deliberate: a disabled control tells someone a door exists and invites them to rattle it.

Sharing and agent management are admin-only whatever else somebody holds. Being granted **edit** on a document never confers the ability to re-share it, register an agent, or read anyone else's activity.

## The five sections

- **Overview** — your organization's totals at a glance: **People & agents**, **Active sessions**, **Workspaces**, **Active agents**, **Document shares**, **Live guest links**, and **Seats** — how many people DraftMesh has seen in the organization against the seat limit on its plan (a person is a seat; agents and service accounts are not), with the plan named underneath. Two of the tiles say what they leave out, on the tile: **Active sessions** counts the credentials DraftMesh issued and not browser sign-ins, and **Active agents** is the live count with the registry total (revoked included) beside it. A **Single sign-on** card sits below the totals: each connection your WorkOS organization has, with its state in WorkOS's own words, and **Manage in WorkOS** to open the Admin Portal in a new tab. If DraftMesh cannot read it, the card says so rather than showing an empty list. Below that, **Members (as observed)** — the people and agents DraftMesh has actually seen, with their role, the promote/demote control, and a **Sessions** view of the device and agent credentials issued to each, with a per-device **Revoke** — plus, below it, **Members homed in another organization**: people who hold shares here but whose DraftMesh account lives elsewhere, listed by account id with the same connector **Block** control, because they cannot appear in the list above. And every workspace in the account.
- **Members** — the invitations this organization has outstanding: who has been asked in, at what role, and whether they have accepted yet.
- **Audit log** — every recorded action in the organization, filterable by action, person, and date, with a CSV export.
- **Access review** — everything shared across every workspace, in one list, with a **Revoke** on each row and a CSV export.
- **Agents** — the registered agents, where their work is delivered, the standing rules that wake them, and what happened to each delivery. What an agent can *reach* is its document grants, and those are listed under **Access review**, not here.

**Overview** and **Members** answer different questions, and the console says so on the page. Overview is a record of *who has used DraftMesh*; Members is a record of *who has been asked in*. Neither is a directory of your organization — DraftMesh does not read one.

**Audit log**, **Access review** and **Agents** each get a topic of their own in this guide; **Overview** and **Members** are covered above.

## What is not here yet

The console is a governance surface, not a control panel for your identity provider. **Identity-provider group membership and who is allowed to authenticate at all are configured in your WorkOS organization**, not in DraftMesh — and so is single sign-on itself: Overview's **Single sign-on** card *reports* your connections and hands you a link into WorkOS, but adding, editing or removing one happens there. (DraftMesh's own **Groups…**, in ⚙ Settings, are targets for document grants and nothing more — they are not the identity provider's groups and confer no console authority.) See **Admin: Security posture FAQ** for the full list of what does and does not live here.

---

# Admin: Access & sharing

Source: https://www.draftmesh.com/docs/admin-access-sharing
Section: Administration

Most sharing in DraftMesh is **one document at a time** — a grant names a workspace, a document path, and one person or agent, which keeps the blast radius of any single mistake to a single file. The one deliberate exception is a **whole-workspace grant**: one holder, every document in the workspace. For a person it is made in the Share panel's **Whole workspace** section; for an agent, in **Connect an agent…** on the document (see **Admin: Governing AI agents**). There is nothing in between — no folder-level grant.

## The four capability levels

Capabilities are a straight ladder. Each one includes everything below it:

| Level | Can |
|---|---|
| **view** | Read the document and its history |
| **comment** | …and leave comments and replies |
| **suggest** | …and propose tracked changes a human still has to accept |
| **edit** | …and change the document's text directly |

Because it is a ladder and not a grid, "at least suggest" is a single comparison everywhere in the product. There is no capability that lets someone change a document without either **edit** or a human accepting their suggestion.

One flag rides beside the ladder, for agents only: an agent **edit** grant can additionally carry **decide** — permission to accept or reject suggestions on that one document. It is off by default, doc-scoped always, and settable only by the document's **owner**; Access review badges it as *Decides suggestions*.

Sharing is an **admin-only** act, with one further narrowing: giving an **agent** edit — or the decide flag — is reserved for the **document's owner**, and a workspace-wide agent edit for the **workspace's owner**, not any admin. Holding **edit** on a document never lets you pass it on — a grantee cannot re-share, cannot invite anyone, and cannot widen their own level.

When one holder carries both a per-document grant and a whole-workspace grant, the two scopes combine differently by kind of holder. For a **person**, the effective level is the **higher** of the two — a document grant can only add. For an **agent**, the **document setting wins** where the two disagree — including when it is *lower*, which is how an owner narrows one agent on one sensitive file while leaving what it can do everywhere else alone.

## What a share does beyond the one document

Granting a person a document also makes them a **derived member of its workspace**, so they can find it. That workspace appears in their workspace list with a **Shared** badge, and they can read its other documents at **view**.

Writing is not derived. To comment, suggest, or edit anything, they need a grant on that exact document — a **view**-level read of a sibling never becomes a way in. Agents get none of this derived membership: an agent reaches exactly what its grants name — a document, or every document in the workspace where it holds a whole-workspace grant. A task credential is narrower still, pinned to the one document of its task.

## Guest links

A guest link lets someone read or respond to one document **without a DraftMesh account**. They open the URL and they are in, as a named-but-unverified guest.

Because a link is a bearer token — anyone holding it is the audience — it is deliberately bounded:

- **Capped below edit.** A guest link can carry **view**, **comment**, or **suggest**. Never **edit**. A tokenless holder cannot write document text.
- **Label it.** *Who is this link for?* is an optional note to yourself — "Elena — pricing review" — so two links to the same document can be told apart a week later. It is a label, not an address: nothing is sent to it, and the recipient never sees it.
- **Last opened.** Every link row, and every person's row, says when the document was last opened through it — or *Not opened*. The access review carries the same column and exports it, so a stale link can be judged on the row where it is revoked.
- **Always expiring.** Expiry is mandatory, not optional. **Expires** offers **1 hour**, **24 hours**, **7 days** (the default) and **30 days**. There is no permanent link.
- **Optionally section-scoped.** A link can expose the whole document or just one section of it. The server enforces that on every guest read and write — the boundary is not drawn in the browser.
- **Revocable at any time**, which takes effect immediately.

## What the recipient of a guest link sees

Worth knowing before you send one, because the guest page is a surface of its own and not the app you are looking at.

They get the document (or just the section you scoped the link to) rendered as prose, with the comments already on it, under a banner that says exactly what the link exposes: **"You’re viewing “Requirements” — section 2 of 5 of *Q3 Onboarding PRD* — as a guest"** for a section link, or **"You’re viewing the whole document *Q3 Onboarding PRD* as a guest"** for the whole thing. A section guest learns the document's title and how many sections sit beside theirs — never another section's heading or text. Under that, one line of record: the document's version number, every sign-off as state (*v4 · approved v3 · edited since*, with no approver's name or note — a decision from outside your organization is marked *(external)*, and the line says *awaiting an internal sign-off* while only outsiders have approved), and when the link expires. There is no sign-in prompt, no file list, no history, and no way to reach a second document.

On a link issued at **comment** or **suggest**, they can select a passage — the selection is widened to whole words — or simply tap a paragraph, then **Comment on selection** / **Comment on this paragraph**, give **Your name** and **Your comment**, optionally an address to **Email me a receipt** to, and choose **Send comment**. They are named-but-unverified: the name is whatever they type. The receipt names the document and the version their comment became; it carries neither the comment's text nor the link.

A guest can **Edit** and **Withdraw** their own comments — "own" meaning posted from the same browser: the page keeps a per-link session in that browser's storage and stamps every comment with it, so nobody else holding the same link can touch them, and clearing that storage (or switching devices) means older comments can no longer be changed from there. Withdrawing is refused once someone has replied, so a withdrawal never deletes another person's words; editing stays available. Both are recorded in the audit log as `guest.comment_edited` / `guest.comment_withdrawn`, by link, never by name.

The page also states, on the landing and again next to **Send comment**, where what they write ends up: *"Your comment is stored in this document, visible to everyone with access; revoking the link doesn't remove it."* That is the literal behaviour — revoking a link ends the guest's access and leaves their comment in the file, for an owner or editor to withdraw if it should go. **Admin: Security posture FAQ** answers that one in full, for forwarding.

A guest **can record a sign-off on one kind of link only**: a **suggest**-level link to the **whole document**. That page carries a **Sign off** panel — **Your name**, an optional note, **Approve** / **Request changes** — and the decision lands in the document as an approval marker in the guest's typed name, marked *guest · unverified* and *(external)*, with an audit row (`guest.signoff_recorded`) by link. **It never stands alone**: the document counts as approved only once a member of your organization has also approved, and until then the toolbar, the Reviewers strip and the guest page all say *awaiting an internal sign-off*. A comment-level or section-scoped link records no sign-off; its composer says so, and a guest who has no objection says so in a comment.

One thing to set expectations on: **a guest never gets a suggestion box, even on a link issued at suggest**. A suggest-level link behaves as a comment link, and the page tells them so — *"You can read this section and leave comments."* A **view** link says *"You can read this section. Commenting is off for this link."*

When a link is finished, the page says which kind of finished it is: **"This link has expired."**, **"This link has been revoked."**, or **"This link is no longer available."** — with a line telling them to come back to you for a new one.

## The Access review section

⚙ Settings → **Administration…** → **Access review** is the one place that answers "what has this organization shared?" without opening documents one at a time.

It has two tabs:

- **Shares** — every grant in every workspace: the workspace, the document, who holds it (a person or a registered agent), at what level, and who granted it. A grant held by a **revoked** agent is shown, marked as inert, rather than hidden — so you can clean it up.
- **Guest links** — every link ever issued: its document, level, scope, expiry, status, label, last-opened time, and the address it was emailed to (*Hand-copied* when none). **Expired and revoked links stay listed**, visibly marked. A governance list that quietly drops rows is a list you cannot trust, and a link you just revoked should read as *Revoked*, not vanish.

Each row has a **Revoke** with an inline confirmation. Revoking a person's grant here does exactly what revoking it from the document's own Share panel does — the same operation, not a second one. The same holds for an **agent's** grant: the document's **Agents** panel offers **Revoke access** on a connected agent's row for its own grant on that document, and it runs this same operation. Disconnecting a rule there deliberately does not revoke the agent's standing access — the confirm says so.

**Export CSV** downloads the current tab. The guest-link export deliberately contains **no link tokens**: a spreadsheet sitting in a downloads folder is a bad home for live document credentials. Use it for access reviews and security questionnaires, not for re-sending links.

## Things to know before you rely on this

These are real limits today, not oversights being hidden:

- **Groups are grant targets, nothing more.** A group (⚙ Settings → **Groups…**) is a named set of people and agents that a grant can be addressed to, so "Engineering can comment" *is* expressible. It is not a principal: it never signs in, never authors anything — every comment, suggestion and approval stays attributed to the individual who made it — and carries no admin authority. Adding someone to a group that already holds **edit** hands them edit everywhere the group reaches, which is why the Groups panel asks first. Grants are how a *member* reaches a document; an **Admin** needs none — admin authority carries edit on every document in the organization (see **Admin: Your organization**).
- **No folder-level grants.** A grant covers one document or the whole workspace — "just the `plans/` folder" is not expressible.
- **Sharing a document only sometimes notifies.** Where the host can send email, creating a grant queues an invitation and the Share panel says so; where it can't, you send the person the link yourself. A guest link is emailed only when you fill in **Email the link to** — then the message carries the link itself (a guest's whole identity *is* the URL, so this is the one email DraftMesh sends that contains a live credential; it draws on the same daily invitation allowance as share invitations). Leave the field empty and you copy the link by hand, as before. The panel reports which happened rather than promising either. A grant addressed to an email address simply waits until that person signs in. (Inviting somebody into the *organization* always mails them; see **Admin: Your organization**.)
- **Members cannot share their own documents.** Sharing is admin-only, so every grant and every guest link has to go through an admin.
- **A Google reference shares what its connected account sees.** A `.gdoc`, `.gsheet` or `.gslides` file is a pointer, and where Google is connected DraftMesh shows a snapshot of the referenced document read with the *connecting account's* Google access — Google's own sharing on that document is not checked against the reader. The rule is that a grant on the reference is a grant on that snapshot, for people and agents alike, and the Share panel and the Connect-an-agent dialog say so on a reference. Today no grant conveys one: Google connects only to the DraftMesh on a person's own machine, which has no sharing, and DraftMesh cloud, where grants live, has no Google connector — so a person or agent granted a reference through a hosted account sees the reference's own details and its link, and search matches those, not the Google document's text. Share a reference as you would share the Google document itself; that is the rule a hosted Google connector would inherit. See **Supported file types**.
- **Revoking access does not end an existing sign-in session.** The grant stops working immediately. The credentials DraftMesh itself issued — device sign-ins and agent credentials — are listed per member under **Administration…** → **Overview** → **Sessions**, and a device can be revoked there. A device that signs itself out — the account control's **Sign out**, or `draftmesh logout` in a terminal — asks DraftMesh cloud to end its own session in that list as it goes; where that cannot be confirmed (the cloud was unreachable at the time), the row stays until it expires or you revoke it here. So a revoke here is for a device its owner no longer has, did not sign out of, or signed out of while offline. A browser sign-in belongs to the identity provider and cannot be listed or ended from DraftMesh.

---

# Admin: Governing AI agents

Source: https://www.draftmesh.com/docs/admin-agents
Section: Administration

A **registered agent** is not a feature you switch on. It is a principal in your organization, with its own name, its own credential, and its own access — governed the same way a person is, and revocable the same way.

⚙ Settings → **Administration…** → **Agents** is where that governance happens.

For what agents can do inside a document, and how someone connects one to their own machine, see **AI assistants (MCP)**.

## Registering an agent

Registering mints two things at once: a principal your organization now contains, and a bearer credential that authenticates as it.

**The credential is shown exactly once.** When it appears, copy it — DraftMesh stores only a hash of it and cannot show it to you again. That is a security property, not an interface quirk: a credential a console can re-display is a credential the console is storing.

If a credential is lost or leaked, **Rotate** issues a new one and the old one stops working on the very next request. There is no grace period.

## Revoking an agent

**Revoke** ends the agent's participation, and it cascades:

- Its credentials are **deleted** — the token stops working immediately, not at expiry.
- Any task still in flight is marked **failed (agent revoked)**, visibly, rather than sitting pending forever against an endpoint nothing will sign for again.
- Its doc-connected subscriptions are **disabled** — kept, and visibly off, so you can still see what it had been connected to — and anything they had already queued is dropped.

Revoke is idempotent; revoking twice is safe.

**One thing revoke does not do: it does not remove the agent's document shares.** A revoked agent cannot authenticate, so those grants do nothing — but they stay in the list until you remove them. **Access review** shows them, marked *Agent revoked — this grant is inert*, which is where to clean them up.

## What an agent can reach

An agent holds document grants exactly as a person does, at the same four levels. Where they are *set* differs: the **Share** panel is for people, and an agent's access is set in **Connect an agent…** on the document itself — the same place its standing rule is authored — with **Access review** listing every agent grant across the workspace.

Two settings, side by side: **This document**, and **Rest of workspace**. The document setting wins where the two disagree — including when it is *lower*, which is how you narrow one agent on one sensitive file without touching what it can do everywhere else.

The default is **suggest**. An agent reads, comments, and proposes; its text enters a document only when a human accepts it. Granting an agent **edit** is a deliberate, per-document decision by **the document's owner** — never a default, never something the agent can arrange for itself, and not something any other admin can do on the owner's behalf. (For a document an agent created, the owner is the person who operates that agent.)

An edit grant can additionally carry **decide** — permission to accept or reject suggestions on that one document. Same rules, stricter still: owner-only, per document (a workspace-wide grant can never carry it), and shown in Access review as its own badge, because it is the one grant that closes review threads without a human click.

And there is a floor no grant can lift. **No agent credential can ever record an approval, roll back a version, or manage sharing.** Sign-off stays a human act on every document, whatever else the owner delegated, and DraftMesh enforces that server-side rather than trusting the agent to decline.

## Turning off one person's connector

Separate from agents you registered: a **connector** is an MCP client someone attaches to their own
DraftMesh account — the sort of thing an AI assistant on their laptop uses. ⚙ Settings →
**Administration…** → **Overview** → **Members (as observed)** carries a **Block** control for each
person, and a blocked connector is refused on its very next call. It closes the connector door and
nothing else: that person keeps their account, their sign-in, their devices, and the web app.

**A block is your organization's decision about your organization's door.** It stops their connector
when it acts as *you*. If the same person also belongs to another organization, that organization's
door is unaffected, and its admins can neither see your block nor lift it. That cuts both ways —
someone else blocking them elsewhere does not close your door either.

**Members homed in another organization** get the same control, in their own table just below.
These are people who hold shares here but whose DraftMesh account lives elsewhere — usually because
they signed in somewhere before accepting your invitation. They cannot appear in the list above,
because they have no member record in your organization at all; they are listed here by the account
id shown on the row, which is what the block is recorded against. The list is derived from the
shares your organization gave them, so it names the people you granted something to — not everyone
who could ever act as your organization.

**One person this lever cannot reach**: someone who has never signed in anywhere has no account id
to record a block against. They also cannot attach a connector, for the same reason, so there is
nothing to block until they do.

To shut every connector and every agent at once, rather than one person's, use the organization-wide
switch in **Agents** instead.

## Sending work out: webhooks and connections

Two settings decide where your documents' contents can travel, so both are admin-only and both are recorded.

- **Webhook** — the HTTPS endpoint DraftMesh POSTs signed tasks to. Its signing secret is show-once, like a credential; the roster displays only a short non-secret key id so you can tell which secret is live. You can clear the endpoint or rotate the secret at any time.
- **Doc-connected subscriptions** — standing rules that fire tasks automatically when a document is edited or commented on, with no human in the loop per event. Because a rule is broader authority than any single task, creating, changing, and removing one is an admin act and each is recorded.

A rule is created with **Connect an agent…** and names what should wake the agent — **The document is edited**, **The document is created**, **Someone adds a comment**, **Someone adds a suggestion**, **Someone asks a question**, **A comment or suggestion is resolved or reopened** — plus **Standing instructions**, the field answering *"What should the agent do every time it wakes up?"*. Its target is the document you connect it from. Workspace-wide rules exist on the API and are listed as **Every document in this workspace**, but the dialog always connects the open document.

Each rule appears under the agent's **Connections**, badged **Enabled** or **Paused**, with **Pause** / **Resume** to stop and restart it without losing it, **Edit** to change its triggers and instructions, and **Delete** to remove it. (The document's own **Connected agents** list offers the same two as **Edit…** and **Disconnect**, plus **Revoke access** for the agent's own grant on that document.) Every firing shows up in the agent's request list, so a rule that has run away with itself is visible rather than merely suspected.

**Disconnecting a rule does not revoke the agent's access.** Standing access outlives the rule by design: the agent keeps whatever it was granted on the document, visible in the Agents panel and in **Access review**, and editable by reopening **Connect an agent…** for it. To withdraw the agent's own grant on the document from the document itself, use **Revoke access** on its row; to withdraw its workspace-wide access, set **Rest of workspace** to **No access** under **Edit…**.

A subscription cannot be **retargeted** after it is created — you cannot point an existing rule at a different document. Disconnect it and connect again. That keeps a rule's identity and its target from drifting apart.

## Delivery history

Each agent's history shows what was sent, what came back, and what did not arrive. **Failed deliveries are the point of it** — a dead-letter reason is shown in full on its row rather than hidden behind a hover, because an operator opening this panel is usually there precisely because something did not arrive.

## Wiring your own agent

This topic covers governing agents. The engineering side — the MCP tool contract, the outbound task payload and its HMAC signature, retries and idempotency, subscriptions and Agent Card delivery — is covered in a separate operator guide, *Connecting your own agent*, together with the task webhook contract and a sample receiver. It is not published here — [ask us for it](/enterprise) and we will send the current copy.

---

# Admin: Audit & activity

Source: https://www.draftmesh.com/docs/admin-audit
Section: Administration

DraftMesh keeps an **append-only** record of what happened in your organization. Rows are added and never changed or deleted — the database itself refuses updates, deletes, and truncation of the table, so the record cannot be quietly edited even from behind the application.

⚙ Settings → **Administration…** → **Audit log** is where you read it.

## What is recorded

| Area | Recorded acts |
|---|---|
| **Documents** | Saves, restores, pushes and pulls between devices, merges, and conflict resolutions |
| **Workspaces** | Created, renamed |
| **Decisions** | Sign-off requested, and approval recorded. The **Result** column carries the decision itself — `requested`, `approved`, `changes_requested`, plus `capped` on the one closing row a single save with an implausible number of new markers writes, so a shortened page says so — and the **Target** column carries the document, the marker, and the version and content hash that marker pinned, so a row says what was approved and not merely that something was |
| **Sharing** | Grant created, access denied under a grant, grant revoked, share list viewed |
| **Guest access** | Link created, link revoked, guest session opened, guest comment left, guest comment edited or withdrawn by its author, guest request denied. A guest comment (and an edit or withdrawal of one) names the guest by the name they typed, flagged **Guest · unverified** exactly as it is on the comment itself |
| **Agents** | Registered, credential rotated, revoked; grants given, elevated to edit, or removed; tasks created, delivered, completed, failed, expired; webhook endpoint and secret changes; subscriptions created, changed, deleted, and firings that were dropped |
| **Your organization** | Invitations sent and withdrawn, roles changed — **and every attempt at one of those that did not take effect**, with the reason: an invitation that failed to send, a withdrawal of an invitation that was already accepted, a refused demotion of the last admin. One row per attempt, so "I tried twice and it failed twice" is two rows |
| **Authentication** | Device sign-ins (a desktop app pairing with your account); every refused request, with the reason |
| **This console** | Reading the audit log, reading the access review, viewing the overview, and every CSV export |

Each row carries who acted, what they acted on, whether it succeeded or was denied, when, and a request id. Where an assistant acted using a person's credential, the row names both. Where a task caused the act, the row names the task. Where the actor is a guest, the row says so in its type column, and a guest's *comment* carries the name they typed and the same guest id the comment in the document carries — so the two can be matched. A guest merely *opening* a document is recorded against the link they used, not a person.

For the organization's own acts the **Result** column tells you why something did not happen: a value starting `denied:` is a refusal DraftMesh made and an admin can act on (`denied:last_admin`, `denied:already_accepted`); one starting `failed:` means the identity provider did not complete the act and it is worth retrying (`failed:upstream_unavailable`).

**Reading the log is itself in the log.** "Who looked at everyone else's activity" is exactly the question this record exists to answer. Paging through a long log does not add rows — only the first page of a listing does, so a reader scrolling to the end cannot inflate the very thing they are reading. **Every export is recorded, every time**: a copy of the record leaving the system is the single most important line in it.

## Reading and filtering

**Presets** sit above the filter bar: **Decisions** narrows to sign-off requests and recorded approvals in one click. Add a **From / To** range to it and you have "everything approved this quarter" on one screen — and, with **Export CSV**, in one file.

The filter bar takes:

- **Action starts with** — a prefix, so `doc.` narrows to document activity, `agent.` to agents, `share.` to sharing. Typed characters are matched literally; wildcards are not a thing here.
- **Principal** — one person or agent.
- **From / To** — a date range.
- **Result** — **Any result**, **Success**, **Denied — no grant** for that one kind of refusal, or the broader **Denied** for every refusal however it arose.
- **Task id** — every row an agent task caused, from the id on the task.

**Apply filters** runs them and **Clear** puts the bar back. Results load newest first, with **Load more** for the next page.

## Exporting

**Export CSV** downloads the log under the filters currently applied — the same rows you are looking at, unpaged. This is the artifact to attach to a security questionnaire or hand to an auditor.

Two things about the file are worth knowing:

- It is **capped at 10,000 rows**. If your filters matched more, the file ends with a line reading `# truncated at 10000 rows — narrow your filters`. That notice exists because a silently short file is how an access review reaches a confidently wrong answer.
- Text columns are **neutralized against spreadsheet formulas**. Names and document paths are written by members, so a cell beginning `=` is written back out as text rather than something Excel will evaluate.

The **Access review** section has its own export on the same terms.

## Honest limits

State these plainly if someone asks:

- **Retention is indefinite and not configurable.** Nothing ages out, and there is no setting to make it. The record grows for as long as the account exists.
- **Browser sign-ins are not recorded.** A device pairing writes a row; signing in to the web app does not. Every *refused* request is recorded either way.
- **A guest is only as identified as the name they typed.** The name on a guest comment — or on a guest sign-off (`guest.signoff_recorded`) — is unverified, and a guest opening a document is recorded against the link, not a person — the log cannot tell one reader using a link four times from four readers using it once.
- **Opening a document to read it is not individually recorded.** Writes are — every save, restore, and merge. So are guest sessions, refused requests, and sync between devices. But a signed-in member reading a document they already have access to leaves no per-read row, so the log answers "who changed this and who was refused" fully, and "who looked at this" only partially. The log viewer carries a standing caution that successful document-read events may be sampled and read counts should be treated as a lower bound; take that as the ceiling on what this log will ever promise about reads, not as a hidden count you could go and find.
- **Panel views are hidden by default.** Opening the Share panel, the Groups list, the agent registry, or this log writes a row (`share.list_viewed`, `group.list_viewed`, `agent.list_viewed`, `audit.viewed`, `admin.*.viewed`) — a record that a list was shown, not that anything was done. Those rows are still written, but the viewer and the CSV leave them out unless you tick **Show panel views**, and the API leaves them out unless you pass `includeViews=true`. Guest opens, exports, and every grant, revocation and refusal are always shown.
- **Some high-volume machine events are counters, not rows** — webhook delivery retries, rejected agent callbacks, and subscription throttling are tracked as metrics. Recording each one would bury the acts that people actually performed.
- **There is no streaming to an external SIEM.** Getting the record out means the CSV export, run by an admin.
- **The record is append-only, but not cryptographically tamper-evident.** There is no hash chain over the rows — the guarantee comes from the database refusing to modify them, not from a signature you could verify independently.

---

# Admin: Security posture FAQ

Source: https://www.draftmesh.com/docs/admin-security-faq
Section: Administration

The questions admins actually get asked, answered against what DraftMesh does today — including where the answer is "not yet".

## Who can see this document?

**Per document:** open it and use its **Share** panel for the people granted on it and any guest links issued for it. An **agent's** access is deliberately not there — it shows on the document's **Agents** panel, and every grant of either kind appears in **Access review**.

**Across the organization:** ⚙ Settings → **Administration…** → **Access review**. Every grant and every guest link in every workspace, in one list, with a CSV export for the questionnaire.

Remember the two scopes a grant can have: **one document**, or the **whole workspace** — there is no folder level. A whole-workspace grant also reaches documents created later, so "who can see this document" includes the workspace-wide holders, not just the grants naming its path.

One kind of document deserves a second look. A **Google reference** (`.gdoc`, `.gsheet`, `.gslides`) shows, where Google is connected, a snapshot of the referenced Google document read with the *connecting account's* Google access, and Google's own sharing on the document does not narrow who sees that snapshot in DraftMesh. Today the snapshot exists only on the machine that connected Google, where there are no grants; for a reference held in a hosted account, "who can see this document" is the grant list as usual, and what they see is the reference's own details and its link. See **What is not here yet** below and **Admin: Access & sharing**.

## Who approved this version?

Approvals live **in the document**, as approval markers — who approved, and pinned to the exact content they approved, so an approval that predates a later edit is visibly not an approval of the current text. Open the document and look at its markers and history. A decision recorded from outside your organization — through a guest link, or by a member of another organization the document was shared with — is marked **external** on the document, and the document is not counted as approved until a member of your own organization has approved too.

**There is also an org-wide record.** Every sign-off *requested* and every approval *recorded* is written to the audit log as its own event, so "show me everything approved this quarter" is one screen: **Administration…** → **Audit log** → the **Decisions** preset, with a date range. Each row names the actor, the document, the version and content hash the marker pinned, and the decision itself — `approved` or `changes requested` — and **Export CSV** downloads exactly those rows, version binding included.

Three honest limits. The ledger records the decision **as the marker recorded it** — including *who* took it, which is the identity stamped on the marker rather than an independently verified signature. In practice that is the person who used the sign-off control; but anyone who can edit the document's raw text can write an approval marker, so treat a decision row the way you treat the approval in the document itself. The document remains the primary artifact, and a decision taken outside DraftMesh is not in here. And these events are written by the hosted service: a workspace kept only on a local daemon still has every approval marker in the file, but writes no decision events — the organization's audit log, and the console that reads it, are part of the hosted account.

## How do I turn someone's access off?

**Access review** → find their row → **Revoke**. It takes effect on the next request they make; there is no cache to wait out. The same button works for a guest link.

**Ending their sessions is partly yours to do from here.** **Administration…** → **Overview** → their row → **Sessions** lists every credential DraftMesh itself issued to them — device sign-ins, and any agent credentials bound to them — and each device row has a **Revoke** that signs that device out on its next request (a device that signs itself out asks to end its own row as it goes, so most rows you see are devices that did not). (An agent credential is listed there but revoked from **Agents**, which owns the whole cascade.) What that list does *not* hold is their **browser sign-in**: that is an account session kept by the sign-in provider, so there is still no "sign this person out everywhere" inside DraftMesh. Revoking their grants stops them reaching your documents; ending the browser session, or disabling the identity itself, is done in your identity provider.

**Taking away their admin authority** is separate, and immediate: **Administration…** → **Overview** → their row → **Remove admin**. The very next thing they ask DraftMesh for is answered as a member. DraftMesh will not let you remove the last admin — promote someone else first.

**Removing a person from the organization altogether is not built yet.** You can revoke every grant they hold and demote them; the account still lists them among the people it has observed.

Revoking an **agent** does more, and does it immediately — its credential is deleted, in-flight tasks are failed, and its standing subscriptions are switched off. Its document grants are left behind as inert rows for you to clean up.

## What happens to a guest's comment when their link is revoked?

**The comment stays in the document.** A guest comment is not held in a side store keyed to the link — it is written into the file as a marker, part of the document's text like every other comment, so it survives the link that produced it. Revoking the link ends that guest's *access*: they can no longer open the document, add anything, or edit or withdraw what they already wrote. It does not reach back into the file. If you want the comment gone, someone with **edit** on the document deletes the marker itself: there is no *Delete comment* button, so it is done in **Code** mode, where the annotation markers are visible in the raw markdown. That is a deliberate act by an owner or editor, recorded like any other edit and reversible from history. The audit rows about the guest (the link's issue and revocation, `guest.comment_created`, `guest.comment_edited`, `guest.comment_withdrawn`) are kept with the rest of the ledger, which is retained indefinitely and cannot be set to expire — so removing the comment text does not remove the record that it existed. The guest page says this before anyone types: *"Your comment is stored in this document, visible to everyone with access; revoking the link doesn't remove it."* For how guest links are issued and what else the guest sees, see **Admin: Access and sharing**.

## Where does SSO live?

**It is configured in your WorkOS organization — but you no longer have to leave DraftMesh to see whether it is connected.** DraftMesh authenticates people through WorkOS AuthKit and maps your WorkOS organization to your DraftMesh account. Which identity provider you use, which domains are allowed, whether SAML or OIDC, and who may authenticate at all are all configured there.

**Administration…** → **Overview** now carries a **Single sign-on** card listing each connection your organization has — its name, its provider, and its state in WorkOS's own words (*active*, *inactive*, *draft*, *validating*) — so "is SSO on for us?" is answered on the screen you are already looking at. **Manage in WorkOS** opens your organization's WorkOS Admin Portal in a new tab, which is where the configuration itself is changed. DraftMesh reads this; it does not own it. If DraftMesh cannot reach WorkOS the card says so rather than showing you an empty list — a blank card would read as "no SSO is configured", and that is the one thing it must never say by accident.

DraftMesh also has one seat-management screen of its own — **Administration…** → **Members**, where an admin can invite someone by email at **Member** or **Admin** and withdraw a pending invitation. The invitation itself is issued and mailed through your identity provider; DraftMesh is asking it to seat someone, not keeping a user directory. Password policy, login methods, and who may authenticate at all remain the identity provider's job by design, not gaps in a screen we forgot to build.

## What is not here yet

Said plainly, because a prospect's security team will ask:

- **No SCIM or directory sync.** DraftMesh does not read your WorkOS directory. It learns a person exists when that person first signs in, which is why the Overview's member list is labelled *as observed* — it is a subset of your directory, not a roster. (The **Single sign-on** card reports your *connections*, which is a different thing: it says which identity provider signs people in, not who is in it.)
- **No SSO configuration inside DraftMesh.** The **Single sign-on** card shows what your organization has connected and links out to WorkOS's Admin Portal; adding, editing or removing a connection happens there.
- **No MFA policy inside DraftMesh.** Multi-factor is enforced by your identity provider.
- **No browser-session listing or revocation.** Device and agent credentials are listed per member (**Overview** → **Sessions**) and a device can be revoked there. A browser sign-in is the identity provider's session, and DraftMesh can neither list it nor end it.
- **No configurable audit retention.** The record is kept indefinitely and cannot be set to expire.
- **No ownership-transfer screen.** The account's recorded owner is the billing and accountability contact and cannot be changed from inside DraftMesh. It confers no authority, so this is a bookkeeping limit rather than a lock-in: **admin** authority itself is freely granted and removed.
- **Two roles.** **Admin** and **Member**, flat — every admin equal, with no read-only or auditor tier and no way to give someone one section of the console. **Groups** exist (⚙ Settings → **Groups…**) but only as targets for document grants: a group carries no console authority, never signs in, and is never recorded as the author of anything.
- **No member removal.** You can revoke a person's grants and their admin role; you cannot delete them from the organization in DraftMesh.
- **A connector block reaches your own door only, and only for people with an account id.** Blocking someone's MCP connector stops it when it acts as *your* organization; it does not follow them into any other organization they belong to, and no other organization's block reaches you. It covers members of your organization and people homed elsewhere who hold shares here (both are listed, with the control, under **Overview**). A person who has never signed in has no account id to record a block against — and cannot attach a connector either, so there is nothing to block until they do. To stop everything at once rather than one person, the organization-wide agent switch is the blunt instrument.
- **No workspace removal on DraftMesh cloud.** A workspace in a hosted account cannot be removed from the account's list — the workspace picker says so in a line under the list, and offers no per-workspace removal control. Unregistering is a machine-side act today: it drops a folder from the local DraftMesh's list and never deletes files.
- **No per-reader check against Google on reference snapshots.** Where a local DraftMesh has Google connected, the snapshot it shows for a `.gdoc`, `.gsheet` or `.gslides` reference is exported with the connecting account's Google access, and whatever reads the reference through that DraftMesh — its card, search, an AI agent connected to it — sees the snapshot; DraftMesh does not ask Google whether *that reader* may open the document. Governing a reference is governing its snapshot (see **Admin: Access & sharing**). DraftMesh cloud has no Google connector, so a reference reached through a hosted account shows the reference's own details and its link only.

## How this page is kept true

Every "not yet" above names a gap that a shipped change can close. When one closes, this page changes in the same change — it is edited by whoever closes the issue, before the release, not discovered stale by the admin who quoted it to their security team. A gap list that is wrong in your favour today can be wrong against you tomorrow, and you cannot tell which from the page. If you find a line here that the console contradicts, that is a bug in DraftMesh: report it, and treat the console as the truth until it is fixed.

## Where the rest is written down

Your engineering and security reviewers will want more depth than an in-app guide should carry. Two documents exist for them: an **administrator guide** covering the same ground with the API surface included, and a **security overview** written to be handed to a security team as-is — identity, authorization, tenancy, sharing, agent access, audit, encryption, the search index, transport, and backups, each stating today's posture and its known limits. Neither is published here. The [security overview page](/security) on this site summarises the posture; [get in touch](/enterprise) for the current copies.