# 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] ## 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. Click a file to open it. 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. - **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, register a new folder by path, or turn sync on and off per workspace. ## 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. Set your display name under ⚙ Settings → **Your name**. Without an account the attribution is self-asserted (it says whatever you type); signing in attributes your work to your verified account identity instead. ## 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. [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. In the desktop app that is a button — **Add a folder** — which opens your system's folder picker. In a browser, which is not allowed to see real folder paths, it is a field: type the 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. The folder and its files are untouched — unregistering never deletes anything, and the dialog says so before you confirm. 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 Using DraftMesh in a browser, with no folder of your own to point at, **New workspace** in the picker creates one in your account instead: - **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 hidden folders 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 Under **In your account**, the picker lists workspaces in your account that this device doesn't have, marked **Not on this device**. **Download to this device** asks which folder to put it in — give it an empty one — and **Download** materializes it there as real files. ## Turning sync on Each workspace 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. To sync you need to be signed in — click **Log in** in the header. 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 — they materialize into 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. Inside the panel: - Each conflicting passage offers **Use your version**, **Use their version**, **Keep both**, or **Write custom text**. **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 (signed in) Signed in to DraftMesh in a browser, the document toolbar carries a **Share** button. Sharing is always **one document at a time** — there is no share-a-folder and no share-a-workspace. - **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. DraftMesh emails nobody, so **Copy link** and send them the link yourself. - **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. - **Copy link** on a selection (or from the selection menu's **Copy link**) gives a teammate a deep link straight to that section. **Share section…** in the same menu goes further and issues a guest link scoped to just that section. **People and agents with access** and **Guest links** below list what exists, each row with **Revoke** behind a confirmation. Revoking bites immediately. Two things worth knowing before you try: - **Sharing is admin-only.** The button is there for everyone, but DraftMesh refuses a grant from someone who isn't an admin of the organization. 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 and Request changes] ## 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] - **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. ## Editing A full rich-text editor: type directly, and formatting (headings, bold, lists, tables) is applied as you write. There is no Save button — **changes auto-save**, and the status in the toolbar tells you when the document is saving or saved. Every save becomes a version you can restore later. ## 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 (``). 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 ## 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, and it sends no email. 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. Accepting applies the proposed text to the document; rejecting removes the proposal and leaves the document unchanged. Only humans can accept — an AI assistant can propose an edit, but never apply one itself. ## 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. ## Asking someone to sign off **Request sign-off**, beside Approve, turns "could you look at this?" into a tracked ask rather than a message in another app. - Tick the people you want from the document's participants, or type a name 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. 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**. ## Handing comments to an AI assistant **✦ Form reply** (next to the document name, with a count of the open comments) 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 three kinds of files in a workspace. Everything else in the folder is left alone (and anything ignored by the folder's ignore rules stays hidden). | 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 | ## 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. --- # 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.onDataChange(path, callback)` — calls your callback whenever that file changes, so the page can re-read and re-render. No polling needed. Pages can only read `.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 Signups

Signups

Loading…
``` 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). ## 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. 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 where allowed (data files, or documents they've been granted edit on), and — where the connection offers it — create a new, empty workspace. - **Can't, ever:** accept or reject suggestions, approve documents, restore old versions, or manage sharing. **Deciding is a human act** — an agent proposes, a person accepts. 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 is an explicit, per-document decision by an admin, 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 — lives at the bottom of the Comments panel, under **Agent activity**. It is there only where there are agents to ask: on a DraftMesh with no registered agents and no request history it renders nothing at all rather than an empty box. **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 in the **Share** panel. 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 been picked up, and a request replaced by a newer one is marked *"Superseded by a newer request."* rather than left looking stuck. **Connect an agent…**, beside 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**, and every time one fires it appears in the same list as a request. ## 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* and *changes requested*, 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): DraftMesh never overwrites silently — re-open the latest version and your change can be re-applied. - **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. - 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. The first time someone signs in through it, DraftMesh creates the matching account behind the scenes and every workspace, share, agent, and audit record from then on belongs to it. If you sign in without an organization, you get a personal account of your own, on the same rules: it is yours, and nobody else is in it. ## 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 first person from your organization to sign in to DraftMesh becomes its first admin.** Everyone who signs in afterwards is a member until an admin says otherwise. 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.** On the last remaining admin the control is disabled and reads *"This is the organization's only admin. Promote someone else before removing their admin access."* - **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 — so unlike a document share, this one really does send the person an email. 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 still one document at a time, described in **Admin: Access & sharing**. ## 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 | 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**, **Registered agents**, **Document shares**, and **Live guest links**. Below the totals, **Members (as observed)** — the people and agents DraftMesh has actually seen, with their role and the promote/demote control — 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, what they can reach, where their work is delivered, and what happened to it. **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. Each of the sections below has its own topic in this guide. ## What is not here yet The console is a governance surface, not a control panel for your identity provider. **Single sign-on, group membership, and who is allowed to authenticate at all are configured in your WorkOS organization**, not in DraftMesh. 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 Everything DraftMesh shares is shared **one document at a time**. There is no "share this folder" and no "share this workspace" — a grant names a workspace, a document path, and one person or agent. That keeps the blast radius of any single mistake to a single file. ## 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. Sharing is an **admin-only** act. 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. ## 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 and task credentials get none of this: their access stays pinned to the one document they were granted. ## 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. - **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 reading **"You're viewing a shared section as a guest"**. There is no sign-in prompt, no file list, no history, and no way to reach a second document. Below **view**, they can select a passage and **Comment on selection**, then give **Your name** and **Your comment** and choose **Send comment**. They are named-but-unverified: the name is whatever they type. 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 *"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, and status. **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 here does exactly what revoking from the document's own Share panel does — it is the same operation, not a second one. **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: - **No groups.** You grant to individual people and agents. There is no "Engineering can comment". The **Admin** / **Member** roles govern the Administration console, not who can reach which document — a member and an admin are granted documents the same way. - **No workspace-level or folder-level grants.** Every grant is one document. - **Sharing a document notifies nobody.** Creating a grant or a guest link sends no email — you have to send the person the link yourself. (Inviting somebody into the *organization* is the one thing that does mail them; see **Admin: Your organization**.) A grant addressed to an email address simply waits until that person signs in. - **Members cannot share their own documents.** Sharing is admin-only, so every grant and every guest link has to go through an admin. - **Revoking access does not end an existing sign-in session.** The grant stops working immediately; there is no session-listing or session-revocation screen yet. --- # 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, and it appears in the same share roster. Nothing about it is a special case. 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 an admin — never a default and never something the agent can arrange for itself. And there is a floor no grant can lift. **No agent credential can ever accept or reject a suggestion, record an approval, roll back a version, or manage sharing.** Deciding is a human act, and DraftMesh enforces that server-side rather than trusting the agent to decline. ## 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 a standing instruction answering *"what should the agent do every time it wakes up?"*. Its target is one document, or **Every document in this workspace**. 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 instruction, and **Disconnect** to remove it. 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. 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. ## Task 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 | | **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 request denied | | **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 | | **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. **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 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**, or a specific kind of denial (**Denied — no grant**, **Denied — not owner**). - **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. - **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. - **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. That is the complete list for that document — the people and agents granted on it, and any guest links issued for it. **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 what a grant is scoped to: one document. There is no folder-level or workspace-level sharing to also check. ## 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. **There is no org-wide approvals report yet.** You cannot currently ask "show me everything approved this quarter" from one screen; you go document by document. ## 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 sign-in session is not something you can do from DraftMesh yet.** There is no session listing and no "sign this person out everywhere". Revoking their grants stops them reaching your documents; 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. ## Where does SSO live? **In your WorkOS organization, not in DraftMesh.** 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. DraftMesh does have 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. - **No MFA policy inside DraftMesh.** Multi-factor is enforced by your identity provider. - **No session listing or session revocation.** - **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, no groups.** **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. Document grants are still to individuals. - **No member removal.** You can revoke a person's grants and their admin role; you cannot delete them from the organization in DraftMesh. ## 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.