Document system overview
How documents move from draft to published version in Alchex, and the terms you meet along the way.
Alchex holds the written part of your management system — policies, procedures, forms, records and manuals — and keeps a record of who changed what, who approved it, and which version people are actually reading. This page gives you the mental model. Every section links to a page with the detail.
Where documents live
Everything sits under Governance — everything your team governs, in one list. The columns are Record, Type, Owner, Status, Version and Updated, and you can filter by type, owner or status. The list opens on Updated, most recent first, so whatever moved last is the first thing you see; click any column header to sort by it instead. Each document belongs to a team, and you only see documents in teams you belong to. There is also a personal "My Documents" view that spans every team you are a member of and shows only the documents you created.
A document can be handed to another team you belong to — Move to team… in the list's bulk actions — and what belongs to the record goes with it: its control and that control's agent if it is a control's definition, and the proof of the document itself. Files imported into a document have no team of their own at all; they belong to whichever team the document does, which is why they follow a move without anyone moving them. See Moving one to another team.
New at the top right opens one small popup: name the record, pick what kind it is — Policy, Procedure, Instruction, Manual, Control or List — and create it. That takes you straight into it, ready to work. If you are already working inside a team, the popup simply tells you which team the record will land in; it only asks when you are on All teams and there is nothing to derive.
Files you already have come in a different way, and a better one: drag them onto the page. The file names the record, so there is nothing to fill in — and what it becomes follows the file: Word and Markdown become documents, a PDF stays a PDF, and a spreadsheet becomes a register, with its own columns and rows already in it. (If uploading is the only thing your role allows, New goes straight to the file picker instead of the popup.)
Open a document and you land in the document workspace: the editor in the middle, the document's panels docking on the right edge — details, comments, version history, activity, all beside the text the same way — and one quiet top bar: the path on the left ending in the document's name (click the name right there to rename it), and on the right the faces of anyone else in the document and the small group of icon buttons that open those panels. That frame is the same on every kind of record — a document, a register, a risk record: one band across the top carrying the path, the panel buttons and the record's actions, the panels docking on the right edge, and every panel named in its own header with a ✕ to close it. Learn it once and you know where things are on all of them. Nothing sits above the text; the page belongs entirely to the document itself. The text is there from the first moment, and it is ready to write in: a document's content and its editor arrive together, so there is no blank page to sit through and no read-only pause before you can type. What you see is the draft as it stands right now — reopening a document never shows an older copy first. See The editor.
You talk to the assistant from the sidebar's Chat entry, and pin the document you mean with the ⌖ picker in the composer. (Until September 2026 the document's top bar carried a sparkle ✦ button of its own, and before that the assistant docked beside the text in a panel with a floating ✦ and a ⌘J shortcut. All of them are gone; the conversation is a screen you go to.) See AI review and assistance.
An archived document opens in the same workspace but read-only, behind a quiet banner saying when it was archived. That banner carries Restore — the state and the way out of it are the same sentence — and the Governance list offers the same Restore on an archived row's menu, so you never have to open a record just to bring it back.
A control opens in that same workspace with an extra panel: its audit rail. Because a control's audit judges the published definition, the rail knows whether this one has published yet and says so — it carries no publish button, because nothing in the app does; publishing is a review decided on My Approvals or the server's publish verb, and once a publish goes through the rail updates in place. See Controls and evidence.
The Governance list holds two kinds of row. Most are documents. The rest are registers — the running logs your documents point at, which carry the type List and open into a table of records rather than an editor. They live in the same list on purpose: what your team governs is one body of record, so there is one place to look at it, one set of columns, and one way to sort it. See Registers. What your documents cite in a connected system is not a row here at all — it is the source itself, cited directly; see Connectors as references.
Opening a document shows it straight away: its text paints from what the page already loaded, and it is ready to write in from that same moment — there is nothing to connect to first.
What the documents' processes did is not on this list: it is in each team's Activity, reached by clicking the team in the sidebar — one line per run, the process and the document named, the document linked. See Teams.
The lifecycle
A document is active from the moment it is created. It exists at v1, its team can read it, and nothing about it is hidden pending a first approval. What an approval buys is the next version, not the document's existence.
Once a version has been approved, the document has two things at once: one working copy that authors edit, and one approved version that readers see. They are never the same thing, and editing the working copy does not change what readers see. Before that first approval there is only one body — what you are writing is what your readers are reading.
An uploaded file is the exception, and deliberately so: it has no draft, because you did not write it. Uploading publishes it, and replacing the file publishes the next edition. See External documents.
The working copy is a workspace and the approved version is a claim, so they are held to different standards on purpose: you can leave anything you like in the working copy, half-finished notes included, and nothing stops you. Publishing is where the checks live — see Publishing for what has to be true before a version can be issued.
Before the first approval those two are the same body, so a note-to-self left in a new document is a note-to-self your readers can see. That is the trade the active-from-birth rule makes deliberately: a document nobody can read is no use to the team on day one, and the version label says exactly what a reader is looking at — v1, with no approval behind it yet.
| Stage | What the chip says | What is happening |
|---|---|---|
| Active, no approval yet | "Active · v1" | The document is in force at v1 and readers see what you are writing. The first approval publishes v2. |
| Working copy over an approved version | "Active · readers see v7" | You are editing a working copy. Readers still see the last approved version. |
| In review | "In review — requested by …" | An owner is deciding on the copy that was submitted. Authors keep writing meanwhile; what they write rides the next version. The decider reads the change list, and raises any question in the document's Comments panel. |
| Changes requested | "Draft · changes requested" | A reviewer sent it back with a note. The working copy is editable again, and the version in force is unchanged. |
| Published | "Published" in history | The approved copy became the new version — the one readers are now pinned to. A fresh working copy opens on top of it. |
The route through those stages:
- Author. Someone with author access creates or edits the draft. See Creating documents and The editor.
- Open a review. A review is opened through the server's submit verb — by an integration or administrative tooling today, and by the automation layer when it is connected; there is no Request approval button in the app. Opening one takes a fixed, fingerprinted copy of the draft and puts a pending request in front of the document owners — that copy is what they decide on, so the record can keep moving underneath it. The submitter can withdraw the review to close it without a decision. See Submit and approve.
- Decide. An owner decides from My Approvals — View changes on the row opens the submitted copy against the published version as a full comparison — and either approves it or requests changes with a note. Approval publishes immediately. Either way the person who submitted the review is told the outcome in their inbox — a rejection carries the reason, an approval says which version it published as.
- Publish. Publishing a control also tidies up after itself: evidence its text no longer cites is retired, and that cleanup never reaches outside the document's own team. On approval the version counts on — v7 becomes v8, whatever kind of change it was. The publisher may declare the change material so readers know to re-read it; that declaration is recorded on the version rather than changing its number. Uploaded files are never asked to declare anything. The published pointer moves and a new empty draft opens so work can continue. See Publishing.
- Next version. Editing the new draft starts the cycle again.
Two rules are worth knowing before you rely on them:
- A reviewer cannot approve their own request. The person who submitted the review is barred from deciding it, no matter what role they hold.
- The server's publish verb can publish the current draft directly, without a review — an Owner-rung act with no button in the app, for tooling and the automation layer. It is refused while somebody else's review is pending, and logged as a direct publish.
Concepts you will meet
| Term | What it means |
|---|---|
| Draft | The single editable working copy of a document. It stays editable while a review is open — the reviewer decides on the copy taken at submit. Before the first approval it is also what readers see — the document is active from birth. |
| Version | A published state of the document, carrying a label like v7. Its content is fixed the moment it is created and cannot be edited afterwards. The one readers see is marked Current; the ones before it are Superseded. See Version history. |
| Saved version | A version somebody saved by hand — it takes the next number in the document's one chain, exactly as a publish does, so it can be read or restored later. It publishes nothing and readers never see it. It is kept until you say otherwise. See Version history. |
| Automatic capture | A copy Alchex takes by itself every few minutes while a document is open, so the text survives a hiccup in live editing. It is not a version: it never appears in version history and is cleared after about a week. See Version history. |
| Approval request | A pending decision pinned to one fixed copy of a draft. Only one can be open at a time. |
| Comment | A note on a record — who said it, when, what they said. Every record carries the same Comments panel. See Comments. |
| Code | The identifier every record carries — a prefix for its kind, the team's code, a running number (PLC-HR-001, LIST-HR-001). Alchex mints it; nobody types it. Each kind has its own prefix and no two share one, so a code names exactly one record in the workspace, which is what makes it safe to quote to an auditor. Changing a document's type re-mints it; publishing fixes it. |
| Reference | A live link from your text to another record — a clause, a control, another document. It is part of the text, so what it names is searchable and visible to the assistant along with the words around it. See References. |
| External document | A file you uploaded (PDF, Word, Markdown) rather than authored in Alchex. Its type is always External, it counts on (v1, v2, v3) like every other record when you replace the file, and its history is a list of files — every published edition and upload stays downloadable, and Download in its ⋯ menu hands you the original file rather than a Word copy. It is owned, renamed, reviewed and published exactly like a document you wrote. See External documents. |
| Control link | The tie between a document and the control it evidences, so readiness views can see it. A control is itself a document (Type: Control) with an audit rail of its own. See Controls and evidence. |
| Audit scope | The clauses of your standard a document declares it covers. Attaching a document to a clause on the compliance record and editing the document's own scope picker write the same link, and every change to it is logged on the record's activity ledger. See The compliance record. |
A document opens as a full page beside the navigation — the text and its panels own everything to the right of the menu, edge to edge and top to bottom. The page carries its work panels docked down the right — comments, version history and the details card — each opened from a small group of icon buttons in the top bar, so reviewing a document never means leaving it. (The outline is not a panel: it floats inside the page itself, as a small stack of bars down the left edge that opens into the heading list — see The editor.) Two more join only when they have something to say: Assistant proposals, holding work the assistant wrote for a part you had already changed rather than merging over your words (see AI review and assistance), and the audit panel on a control. Each panel has exactly one door, and since August 2026 every one of them is in the top bar — the buttons moved up out of the 44-pixel column that used to run down the right edge, which is why the document now has that width back; the panels open where they always did. The bar carries those doors and the people in the document, never the workflow. (Approval is not a panel at all — deciding lives on My Approvals.) What the document cites, what backs it, and the files imported into it all live on the details panel — see References. The details panel also carries the document-control facts in a Document control section — in force or draft, who approved it and when it took effect, and when it is next due for review, each read from the record rather than typed into the text. That is the RECORD of a decision; the decisions themselves are made on My Approvals — see The editor.
Who can do what
Access has two layers: your workspace role, and your role in the team that owns the document.
| Role | Can |
|---|---|
| Reader | Read the published version and its history. Nothing else — no create, no edit. |
| Author | Everything a Reader can, plus create documents, edit the draft, and open or withdraw a review (through the server's submit and withdraw verbs). |
| Owner | Everything an Author can, plus approve or reject someone else's review (on My Approvals). Direct publish is a server-verb act at this same rung — no button offers it. |
Workspace owners and admins are treated as team owners for documents in any team. Full detail in Permissions.
Things that cannot be undone
- A document that ever published cannot be deleted. Retiring one means archiving it: it leaves the working list, keeps every version, approval and stored file, and Restore brings it back — a Writer may do that. Delete exists as a separate, permanent action for drafts that never became records (an abandoned import, a duplicate): it is Owner-only, always confirms first, and refuses published and control-backed documents. See Activity and archive.
- Removing a record something cites is allowed, and does not refuse. If another document's text points at it — or a control's instructions do — those chips turn red where they are written, keep the record's name, and offer Rebind. Nothing lists the citers first, and there is no admin override, because there is no refusal to override. Restoring the record turns the chips back. See References.
- Publishing moves the version that readers see. You can restore an older version into the draft and publish again, but the published history keeps every step.
- Winding a draft back is not one of these. A document records every change as it is made, so its history holds each editing session as well as each saved version, and returning to one supersedes the later work rather than deleting it — every later session stays in the list and can be returned to just as easily. See Version history.
- A version's content cannot be edited afterwards. A version stores the exact content it held at the moment it was created, and the database itself refuses any later change to it — so an approval always describes the content the approver actually saw. Correcting something means publishing a new version, and the old one stays in the history beside it.