Collaboration

<!-- Reviewed 2026-09-07 (the PARAGRAPH rule — the panel follows the save): the covered editing session's quiet settle call now tells its host when the server has answered, so the Workflow panel beside the editor refetches the processes the save just rebuilt instead of showing the last read until a reload. Typing, sending and the shared log are unchanged; the settle answer (`transport.ts`) is read for `settled` only. --> <!-- Reviewed 2026-09-04 (the Build button — docs/design/build-button/README.md): the covered src/app/api/documents/[id]/ops/route.ts changed; a person's edit to a document being BUILT from a marketplace template marks the section it touched as kept (see Templates → "Building a document together"); the op log, the admission policy and everything this page describes are unchanged. --> <!-- Reviewed 2026-09-02 (saving a document updates its processes and its agent): the covered editing session gained one quiet call — when you pause for half a minute or leave the document it tells the server your edits have settled, so the document's index and its processes re-derive from the text (Authoring → Drafts → "What a save does"). Typing, sending and the shared log are unchanged. --> <!-- Reviewed 2026-08-26 (workflow panel engine hand-off): DocumentTab now hands the mounted editor's engine to the workspace's rail panels as well as the op-log session. Pure wiring — nothing THIS page documents (joining, presence, merging of edits) changed behavior; the Workflow panel it feeds is documented under Authoring → Workflows in documents. --> <!-- Reviewed 2026-08-18 (organization style sheet rev 2): the covered editor plumbing gained a pass-through headingStyles prop so h1–h3 render the org sheet's per-level fonts/sizes. Nothing THIS page documents changed behavior; the sheet itself is documented under Administration → Workspaces and Authoring → The editor. -->

Several people can work on the same document draft in Alchex. There is one draft per document, everyone opens the same one, and everyone's changes land in it. Use this when a policy or procedure is being written by more than one person, or when you want a colleague to fix a section while you keep working elsewhere.

Who can join

Editing a draft needs the Writer or Owner role on the document's team; a workspace Owner or Admin counts as team Owner everywhere. A Reader gets the document read-only. Access follows the team the document belongs to — see Permissions and Drafts.

The document opens ready to write

Open Governance → a document → Document and you can type immediately. There is no connecting step, no spinner, and no read-only moment to wait through: the document arrives with the page, and the first character you type is part of the draft.

That is worth saying plainly because it used to be otherwise. Opening a document meant waiting for a live connection to be established before a single word could be typed — and when that connection was slow rather than broken, the wait had no end.

Its text is on screen as soon as the page has it, so you can read, scroll and follow its links immediately, and nothing is loaded twice. What opens is always the draft's current content: Alchex reads the latest state at the moment you open the document, rather than showing a copy remembered from your last visit and catching it up in front of you. A document that has never had anything written in it opens empty, which is what it is.

How simultaneous edits merge

Edits merge automatically. Two people typing in different paragraphs both keep their work, always — the common case costs nothing and nobody is ever asked about it.

Two people typing in the same paragraph also both keep their text: the changes are woven together character by character, so the result is a merge rather than a last-writer-wins overwrite. There is no lock, no check-out, and no "someone else is editing" block. (The one lock that does exist belongs to review, not collaboration: while an approval request is pending, the document is read-only for everyone until it is decided or withdrawn — see Submit and approve.)

Structural changes — pressing Enter to split a paragraph, reordering sections, deleting a block, replacing one outright — always land too, in the order they arrive. A person's edit is never turned into a pending suggestion and never refused because a colleague got there first; only the assistant's edits are ever held back that way (see the note under Limits below).

There is no Save button and no save conflict. What you type becomes part of the shared draft as you type it, which is why you should still agree with your co-editors on who is rewriting what — Alchex will faithfully merge two people rewriting the same sentence into one sentence neither of them wrote.

Comments are separate from the text and are not merged into it: the document's conversation lives in its Comments panel, untouched by anyone's edits — see Comments.

Seeing each other's changes

A colleague's edits appear in your copy on their own, within about a second of them pausing. When somebody else is actively writing, Alchex checks more often; when the document is quiet it settles down. Your place in the document is kept: a change landing above where you are typing does not move your cursor or scroll the page out from under you.

Two short waits make up that delay, and they behave differently. Your own words leave your browser shortly after you stop typing — a pause of about half a second, so a sentence travels as one piece rather than one letter at a time. Then the other person's copy has to notice. Neither wait affects the document you are looking at: your own typing is never delayed by any of this, because it appears in your editor as you type and is sent afterwards.

Who else is here

The top bar shows the faces of everyone else in the document right now, to the right of its name. Hover one for the person's name. Past four, the rest collapse into a count.

Somebody appears within about twenty seconds of opening the document, and disappears about a minute after they close it or put the tab in the background — nobody has to announce that they are leaving, and a closed laptop settles by itself. When you are the only one here, the space is simply empty: this is a signal, not a permanent readout.

What you will not see is where in the document your colleagues are. There are no live cursors: you see who is with you and what they write, not their caret. So on a document two people are editing at once, coordinate in Comments or in chat rather than by watching a cursor. Typing @ in a comment opens a list of your teammates, and the person you choose is notified with the document and what you wrote: that, not a cursor, is how you get somebody's attention on a draft.

When the connection drops

Keep typing. The editor stays open and stays editable, and a Reconnecting… ribbon appears saying your edits are held here and will send when the connection returns. This is the ordinary case and it is not an error state — a document being edited offline is exactly the right thing to be looking at.

One limit matters, and it is the reason to leave the tab alone: the edits waiting to send are held by the open page, not by your browser. Close the tab or reload it before the ribbon clears and the unsent changes go with it. Wait for the ribbon to disappear before you close the document.

When a draft stops saving

Very occasionally Alchex will decide it cannot safely record what is happening, and it says so rather than guessing: This draft stopped saving. The text on your screen is intact and complete — nothing is deleted — but new edits are no longer being recorded, and the editor goes read-only so you cannot keep writing into a document that is not keeping it. The whole screen says the one thing: the save word in the top bar reads Save failed for as long as the notice is up, so nothing on the page is still telling you your work is safe.

Copy anything you have just written, then reload the page. Reloading re-opens the draft on the server's current content.

This happens when a change cannot be expressed safely, when an incoming change does not fit the copy of the document on your screen, or when the editor could not finish loading the part of itself that records new paragraphs. That middle one is not somebody editing the same words as you — it is an arriving change that names a part of the document your copy does not have, which means the two copies had already drifted apart before it arrived. In each case the alternative — carrying on and hoping — is how a paragraph disappears from somebody else's screen, so Alchex stops instead. A collision with a colleague's edit is not one of the causes: simultaneous edits merge, they never stop the draft saving. Whenever it does stop, Alchex records exactly which part of the document it could not name and why, so a stop that repeats on the same document can be traced rather than guessed at.

That third cause is the one worth knowing about, because it used to be silent. On a slow or interrupted connection the editor could finish loading its text surface but not the piece that gives each new paragraph its identity — and it would then accept everything you typed while recording none of it, with no ribbon and nothing to see. It now waits, and says This draft stopped saving if the missing piece never arrives. Reloading the page fetches it again and is almost always enough.

It is a genuine disagreement state, not a speed limit: editing the same paragraph in quick succession — typing, then immediately inserting a reference into it — is ordinary work and does not trigger it.

When a document is not editable

Some documents open read-only for everyone, with no ribbon and no notice. See Drafts for the full picture — the usual reasons are that the draft is in review, the document is archived, or your role on the team is Reader.

The discussion, in one place

Threaded comments anchor to text, and the Comments panel — opened from the document's top bar — lists all of them — open threads first, resolved kept as history below. Each one offers Show in document, which selects the passage it was written about and scrolls to it.

The panel is the same conversation the margin shows, not a copy of it: reply, resolve, edit your own words or delete them from either, and the other is already up to date.

Limits worth knowing

• Only one draft exists per document, so there is no way to work on two competing versions of the same document in parallel.
• Submitting a draft for review does not lock it: the reviewer decides on the exact content that was submitted, and anything typed afterwards simply rides the next version. See Submit and approve.
• Unsent edits do not survive closing the tab (see above).
• There are no live cursors — presence tells you who is in the document, never where they are in it.
• The assistant edits the same draft, so a change it makes appears in your editor while you are in it — unless it collides with something you have just written, in which case it waits for you as a suggestion instead of overwriting you. What the assistant writes while you have the document open is never recorded as your edit: on a document being built from a template, a section counts as yours only once you keep it or change its words. See AI review.