Policy Handbooks

A handbook (new in 1.18.0) is a named, ordered bundle of published documents, usually policies and, from 1.18.2, SOPs, taken from any spaces and grouped into numbered sections, with an introduction at the front. People read it as one, print it as a paper copy and, with read confirmation, confirm it as a whole. The documents stay where they are: a handbook points at them, so an edit to a policy shows in every handbook that holds it.

Typical handbooks are an employee handbook for everyone, a security pack for engineering, or a site safety handbook for one team. Each policy in a handbook can also be kept out of its space’s listings, so readers find it only in the handbook (see Where people find it).

Handbooks are part of every edition. Confirming policies from a handbook and confirming a whole handbook are part of read confirmation, which needs the enterprise image and a license with the Policy acknowledgements entitlement; without it, handbooks are for reading and printing.

The Handbooks page

Handbooks in the sidebar (and in the command palette’s Go to group) opens a table of the handbooks you can read and the drafts you can edit: each one’s name and what it holds (“8 policies”, or “3 policies and 2 SOPs”; see Policies, SOPs and other documents), its owner, its status (Published or Draft) and a print button. Editors also get an edit button on each row they may change. The item appears for anyone who can read at least one handbook or may build one; everyone else never sees it.

New handbook is in the page header for whoever may build one. With read confirmation licensed, the table has a Confirmation column (see Progress).

Who builds handbooks

Building a handbook needs the Build handbooks permission (handbook.manage). How it is held decides what you can build:

• Held globally (the Administrator role holds it): you build workspace handbooks from any published document you can see, and you can also edit the handbooks owned by any space.
• Assigned on a space: you are that space’s handbook admin. You build handbooks owned by that space, from documents in the spaces where you hold Build handbooks.

There is no separate space admin role. To let someone run their space’s handbooks, put Build handbooks in a role and grant it to them, or to a group, with that space selected (see Granting a role in one space). A space you cannot read is never one you manage, whatever you were granted. Custom roles do not get the permission on upgrade; add it where you need it.

A handbook’s owner is the whole workspace or one space, and the owner decides who may edit it: a workspace handbook is edited by people who hold Build handbooks globally, a space handbook by people who hold it on that space or globally. Deleting a space deletes the handbooks it owns, never the documents in them.

With COMPASSDOCS_AUTHZ_LEGACY=1 set (see If something goes wrong), only admins build handbooks.

Editing a handbook that holds other spaces’ documents

You only ever work with documents from spaces you could add from: any space you can see for a workspace handbook, the spaces where you hold Build handbooks for a space handbook. A document from any other space shows in your editor only as “A document you can’t open”, without its title or text, and stays in the handbook when you save. The editor’s counts treat it as a plain document, so they never say whether it is a policy or an SOP.

While a handbook holds documents from a space you can’t add from, you can’t publish it, change who reads it or change its owner: “This handbook holds documents from spaces you can’t add from, so you can’t publish it or change who reads it or who owns it. Ask someone who can add from those spaces.” Those changes would show the other documents to new people, so they are left to someone who can add from every space in the handbook.

Who reads a handbook

The Who reads it choice in the editor sets the audience:

• A workspace handbook: Everyone in the workspace, or Chosen groups. A workspace handbook may name any groups.
• A space handbook: Members of the space, which means everyone who can read it, or Chosen groups. For a space handbook the groups only narrow the audience: a group member who cannot read the space does not read the handbook (“Members of these groups who can read People Ops.”).

A handbook’s editors read it too, whatever its status or audience. Reading a handbook needs no permission of its own.

Handbook access opens its policies. Anyone who can read a published handbook reads every published document in it through the handbook: the text, its images and the printed copy, even when the document is in a space they cannot open. The document’s own page (/doc/{id}) keeps its space’s permissions, unchanged. Unpublish the handbook, take a document out of it or take the document back to draft, and that access ends.

A handbook can reach past a private space

Putting a document from a private space into a handbook for everyone lets everyone read that document in the handbook. With read confirmation, a private-space policy set to ask Everyone who can see this space then asks the whole workspace too (see Handbooks and who is asked). Check the spaces of what you add before you publish.

Draft and published

A new handbook is a Draft: only its editors see it, in the list, the reader and the print preview, with a banner saying “This handbook is a draft. Only its editors can see it until it is published.” Publish handbook makes it readable by its audience; Unpublish takes it back to a draft.

Unpublishing asks first: readers lose access until it is published again, and its Handbook only documents are listed in their spaces meanwhile. Confirmations are kept, and publishing it again does not cancel any that are still current.

A document taken back to draft stays in the editor’s Contents, marked “draft, hidden from readers”, and is left out of the reader, the printed copy and confirmation until it is published again. A document in the Trash is left out everywhere, the editor included, and keeps its place in the handbook if it is restored.

Policies, SOPs and other documents

From 1.18.2 a handbook names what it holds. The Handbooks page, the reader, the confirm page, the printed copy and the editor all count and number the documents by the same rule:

The handbook holds	Counts read	Positions read
Policies only	“8 policies”	“Policy 3 of 8”
SOPs only	“4 SOPs”	“SOP 2 of 4”
Policies and SOPs	“3 policies and 2 SOPs”	“Document 2 of 5”
Policies, SOPs and other types	“3 policies, 2 SOPs and 1 other document”	“Document 2 of 6”
Other types only	“4 documents”	“Document 2 of 4”

A handbook of policies only reads exactly as it did in 1.18.0. In a mix, types other than policies and SOPs are counted as other documents, since the policies and SOPs are documents too, and each document’s type badge says which kind it is. A single document speaks of itself by its own kind, as in “For information. This SOP doesn’t ask you to confirm it.”

The type never decides whether a document asks to be confirmed. An SOP, or any other document, that requires read confirmation is confirmed in the handbook, and with the handbook, exactly like a policy; one that does not is For information.

Building a handbook

New handbook asks for the details first; Create handbook then opens the full editor, where you add the documents. The editor has the Details and Contents cards on the left and the Add documents panel (called Add policies before 1.18.2) on the right (above them on a narrow screen).

Details

• Title, up to 160 characters.
• Owner: Whole workspace (admins), or one of the spaces you manage. Only the owners you may choose are listed.
• Introduction, plain text or Markdown, up to 20,000 characters. It is the reader’s first page and opens the printed copy. A handbook without one opens straight at its first policy.
• Who reads it: see Who reads a handbook. Publishing with Chosen groups needs at least one group.
• With read confirmation licensed, Ask readers to confirm the whole handbook, and once that is on, Require a typed signature (see Confirming a handbook).

Contents

A new handbook starts with one section, Policies. Add section adds one at the end, Rename section renames it, and Remove section removes it; its policies move to the end of the section before it (or the start of the next), and the last section can’t be removed. Sections and documents are numbered as readers see them, and the card’s title counts what the handbook holds (“Contents · 3 policies and 2 SOPs”).

Each document’s row shows its number, title, version and date, and has Move up and Move down (which cross into the neighbouring section at a section’s edge), Remove from handbook, and the Where people find it menu. A handbook holds up to 50 sections and 200 documents, and a document appears in a handbook once.

Add documents

The panel searches the published documents you may add: from every space you can see for a workspace handbook, from the spaces you manage for a space handbook. A type filter reads Policies | SOPs | All types: Policies is the default, SOPs (new in 1.18.2) shows only SOPs, and All types shows every published document, with policies first, then SOPs. A space menu narrows to one space. When a filter finds nothing it says where else to look (“No published SOPs here. Try Policies or All types.”). Tick a result to add it to the end of Contents; untick it to take it out again.

Saving

Nothing is written until you save. Save, or CtrlS (⌘S on a Mac), keeps the details, the contents and every “Where people find it” change in one go, and the page warns you before you leave with unsaved changes. Preview opens the reader in a new tab. Every change is written to the audit log.

If someone else saved the handbook after you opened it, your save is refused with “This handbook was changed by someone else. Reload to see their changes.” Reload, then make your change again.

Publish, Unpublish and Delete

Publish handbook saves any unsaved changes first, then publishes; it needs at least one published document (“Add at least one document before publishing.”). Unpublish is described under Draft and published.

Delete handbook, at the bottom of the editor, asks first; for a published handbook you type its title to confirm. The handbook and its sections go. The documents stay in their spaces, with their own confirmations, and are listed there again. Whole-handbook confirmation records are kept for reporting.

Where people find it

Each policy in the editor has a Where people find it menu with two choices:

• Space + handbook (the default, and how every document works without handbooks): listed in its space, found by search, and read in the handbook too.
• Handbook only: hidden, for ordinary readers, from its space page, the sidebar and search. People open it from a handbook they have been given.

A handbook-only document is left out, for ordinary readers, of its space page, the sidebar page tree, search (keyword, semantic and Ask), the dashboard’s Latest in your spaces and Popular this week tiles, Pick up where you left off, the command palette, a person’s documents in the directory, related documents, sub-pages, Linked from and [[ link autocomplete, space and tag counts, the weekly digest, space subscription emails, the public site, the Outlook add-in, Ask in chat, the Claude connector and the REST API’s listings.

People who may write in the document’s space, admins included, still see it everywhere, marked Handbook only; hovering the chip names the handbooks it is read in. The space page tells them how many of its documents are handbook only, and where readers find them (“2 documents here are handbook only. You see them because you edit this space; readers find them only in Employee Handbook 2026.”).

This is about finding, not access. Anyone who can open the space can still open a handbook-only document by its link.

The setting is stored on the document, so it holds in every handbook the document is in. Changing it needs Build handbooks where the document lives as well as the right to edit the handbook, so a space’s handbook admin can’t hide another space’s document (“You can’t change where people find documents in that space.”). Changing it is metadata only: the document’s updated date and its confirmations do not move.

The no-orphans rule

Handbook only takes effect only while the document is in at least one published handbook. A handbook-only document in no published handbook is treated as Space + handbook everywhere, so unpublishing or deleting the last handbook, or removing the document from it, can never leave it impossible to find. Until a draft handbook is published, the editor says so: “Handbook only takes effect once the handbook is published. Until then these documents stay listed in their spaces.”

Reading a handbook

A handbook opens at /handbooks/{id}. The header carries the title and a line such as “8 policies in 3 sections · updated 2 Nov 2026 · owned by People Ops” (“3 policies and 2 SOPs in 2 sections” for a mix), with Print or save as PDF and, when the handbook asks to be confirmed as a whole, Confirm handbook. Its editors also get Edit.

The contents run down the left: the introduction, the sections and their numbered policies, with the headings of the policy on screen nested under it. On a phone they fold behind one Contents button above the page. With read confirmation licensed, a tick marks each policy you have confirmed, and Your progress shows how many of the policies that ask you are confirmed.

The introduction page offers Start reading, or Continue at the first policy still waiting for you once you have begun.

The policy page

Each policy has its own address, /handbooks/{id}/{document id}, so a link can point straight at it. The page shows:

• The document type, Handbook only when that applies, its position (Policy 3 of 8, or SOP 3 of 8 and Document 3 of 8; see Policies, SOPs and other documents), and, with read confirmation, your standing: To confirm, Confirmed or Updated since you confirmed.
• The title, and a facts row: Owner, Approved by, Version, Effective, Next review and Applies to. Empty facts are left out.
• In short, when the document has summary points.
• What changed in version N, when you confirmed an earlier version: the version notes written since, with Compare versions when you can open the document’s space.
• The document’s text, rendered as on its own page.
• The confirmation bar (see Confirming from the handbook), and Next with the following policy’s title. On the last policy of a handbook that asks to be confirmed, the bar offers Confirm handbook.
• Related documents. One in the same handbook opens in the reader; one outside it shows only when you may open it.

Where the facts come from:

• Version, Approved by and Effective are the latest published version’s number, its approver (left out when it went live without a review) and its date.
• Owner is the policy’s own owner; else its space’s Policy owner (see Policy defaults); else whoever switched on read confirmation for it (each only while an active account), the same owner the compliance portal shows; else whoever published the latest version; else its author.
• Next review is the document’s review due date.
• Applies to is the document’s own line (below).

The reader and the printed copy use the same rule, so they never disagree.

In short and Applies to

Two optional properties of a document feed the policy page. Both are in the document editor’s properties, with the summary and tags:

• In short: up to five points of up to 200 characters each, shown in a box above the text. **bold** is the only markup a point keeps.
• Applies to: one line of up to 200 characters, such as “All employees”, shown in the facts row.

On a published document, or a draft scheduled to publish, changing them needs publish rights. See In short and Applies to.

Confirming a handbook

Part of read confirmation: needs the enterprise image and a license with the Policy acknowledgements entitlement.

Each policy is confirmed in the reader exactly as on its own page, and counts in the same place. Switch on Ask readers to confirm the whole handbook and readers also get one page, /handbooks/{id}/confirm, that confirms every policy still waiting for them at once:

• Every policy is listed with where it stands: Confirmed, To confirm, Updated since you confirmed, or For information for a policy that does not ask this person.
• One statement to tick: “I have read and understood all 8 policies in Employee Handbook 2026, and I agree to follow them.” A policy that asks in its own words is listed under it (“These policies ask you to confirm in their own words:”) and keeps its own words on its record.
• Your typed name, and your password for a local account, when any waiting policy requires a typed signature or the handbook does.
• One button, Confirm 5 policies, that records a confirmation of each waiting policy against its current version, the same record its own card would write.

If a policy changed while you were reading, nothing is written and the page refreshes with the changes. From 1.18.2 the page also sends the statement and the contents it showed, and the server checks that the page you confirmed is the one it holds before writing anything. If the handbook changed under the page, say a document was added for information or a document’s type changed, the confirmation is refused in the same way and the page refreshes. A confirm page left open from before the upgrade refreshes once. The details, the audit entries and how the audience is worked out are on Policy acknowledgements.

The statement for SOPs and mixed handbooks

The statement names everything the handbook holds, the documents for information included, by the rule in Policies, SOPs and other documents:

• Policies only: unchanged from 1.18.0, “all 2 policies” included.
• SOPs only: “I have read and understood all 4 SOPs in Site Procedures, and I agree to follow them.”, “both SOPs in Site Procedures” for two, and “the SOP in Site Procedures, and I agree to follow it.” for one.
• A mix: the total, then the parts: “I have read and understood all 5 documents in Employee Handbook 2026 (3 policies and 2 SOPs), and I agree to follow them.” Two read “both documents in Employee Handbook 2026 (1 policy and 1 SOP)”, and other types are counted as other documents: “all 3 documents in Employee Handbook 2026 (2 policies and 1 other document)”.
• Other types only: “all 4 documents in …”, with no breakdown.

The rest of the page follows: the subtitle (“One confirmation covers every SOP below that is waiting for you.”), the list’s heading (“3 policies and 2 SOPs”), the line over documents that ask in their own words (“These SOPs ask you to confirm in their own words:”) and the button, which counts what is waiting (“Confirm 2 SOPs”, “Confirm 3 policies and 2 SOPs”).

Handbooks that already held other documents

A handbook that held documents other than policies before 1.18.2, such as an SOP or a guide added through All types, words its statement the new way for confirmations made from the upgrade on: “all 3 documents in … (2 policies and 1 other document)” where it used to read “all 3 policies in …”. Records already made keep the words they were made with, and still count for the contents they confirmed.

The typed signature

Require a typed signature covers confirmations made in the handbook: the whole-handbook page and the confirmation bar under each policy in the reader. Confirming from the policy’s own page in its space follows the policy’s own Require typed signature setting. Someone who reads a policy only through handbooks confirms it in a handbook, and must sign if any published handbook they can read that holds it has the switch on.

The handbook-level record

Once nothing in the handbook is left waiting for you, a whole-handbook record is kept: who, when, how many policies that confirmation recorded, the typed name if you signed, and a fingerprint of the policies and versions the handbook held, so the record says exactly what was confirmed. The record is kept when the handbook is deleted, and anonymising a person’s compliance record anonymises theirs too.

Progress on the Handbooks page

For a published handbook that asks to be confirmed as a whole, its editors and holders of Read compliance program see a Confirmation column on the Handbooks page: the share of the audience holding a whole-handbook record of the contents as they stand now, and how many people the audience is (“64% confirmed · 412 people”). Readers never see anyone else’s standing.

Printing

Print or save as PDF, in the reader and on each row of the Handbooks page, opens /handbooks/{id}/print?print=1: a print preview that opens your browser’s print dialog once it has loaded. Without ?print=1 it is just the preview, with its own Print or save as PDF button. Choose A4 or Letter in the toolbar (the default follows the workspace’s date format: Letter for a US format, A4 otherwise); ?paper=a4 or ?paper=letter picks one in the address.

The printed copy has:

• A cover in your accent colour, with your logo and company name, the title, the introduction when it is short enough (a longer one gets its own page), “8 policies · 3 sections”, “Printed 5 Nov 2026 by Dana Whitfield” and “The current version is always at” with the handbook’s address.
• A contents page: the sections and numbered policies, each with its space and version.
• Each policy on a new page, with a running header (the section, and Policy 3 of 8), a line of facts (type, space, version, effective date, owner), Applies to, In short and the text.
• An acknowledgement page with lines for full name, signature, date and manager, and where to return it (or, when the handbook asks to be confirmed, where to confirm online).

From 1.18.2 the printed copy names its contents as the reader does: the cover reads “3 policies and 2 SOPs · 2 sections”, the running header “SOP 3 of 8” or “Document 3 of 8”, and the acknowledgement page agrees to follow “the SOPs it contains” (“the SOP” for one, “the documents” for a mix) and points to where “your confirmation is recorded against each SOP’s version”. A handbook of policies only prints as before, “the policies it contains” however many it holds.

Every page but the cover has a footer: the handbook’s title and your company, “Printed 5 Nov 2026 by Dana Whitfield · uncontrolled when printed”, and the page number. A paper copy is a snapshot: the line reminds whoever holds it that the handbook online is the current one.

Anyone who can read the handbook can print it. A draft prints for its editors only, marked Draft on the cover and in every footer. Every print, from the button, the dialog or the browser’s own print command on the preview, is written to the audit log as handbook.printed.

In the audit log

Every change to a handbook is in the audit log under the handbook category:

Action	Shown as	Written when
handbook.created	Created handbook	A handbook is created, with its owner, audience and switches
handbook.updated	Edited handbook	The details change, with the fields that changed
handbook.contents_changed	Changed handbook contents	Sections or policies are added, removed, renamed or moved, with the contents before and after
handbook.find_mode_changed	Changed where people find a document	A document’s Where people find it changes (recorded against the document)
handbook.published	Published handbook	The handbook is published
handbook.unpublished	Unpublished handbook	The handbook is taken back to a draft
handbook.deleted	Deleted handbook	The handbook is deleted, with the documents it held; also for each handbook a space delete takes with it, with via: "space.delete"
handbook.printed	Printed handbook	Someone prints it
handbook.confirmed	Confirmed handbook	Someone confirms the whole handbook

Each policy confirmed from a handbook is also a document.acknowledge entry, as from its own page, marked via: "handbook" with the handbook’s id.

From 1.18.2 a change made through the Claude connector is the same entry as the editor’s, with via: "mcp" in its details. Before 1.18.2, handbook.find_mode_changed was shown as “Changed where people find a policy”.

With Claude

From 1.18.2 the Claude connector has five handbook tools: list_handbooks, read_handbook and handbook_status to read handbooks and see where you stand, create_handbook to build one and update_handbook_contents to change its sections and documents. They follow the same permissions as the app. create_handbook always makes a draft, for a person to review and publish here; update_handbook_contents is live at once on a published handbook, as Save is, and never publishes or unpublishes. No tool confirms a handbook or a policy: confirming stays the person’s own, in the app.

People who read only the handbook

People asked to confirm a policy only through a handbook (they read the handbook but can’t open the policy’s space) are reached like everyone else from 1.18.3: the policy is on their My policies, dashboard and sidebar badge, every request and reminder links into the handbook and names it, and they count in Team compliance, the team view and the portal, marked Through a handbook. See People asked only through a handbook.

Troubleshooting

Symptom	What to check
No Handbooks item in the sidebar	You can’t read any published handbook and don’t hold Build handbooks anywhere.
No New handbook button	You need Build handbooks, globally or on a space you can read.
A space is missing from Owner	You don’t hold Build handbooks on that space, or you can’t read it.
A document is missing from Add documents	It isn’t published, it’s in a space you can’t add from, or it is already in the handbook. Try SOPs or All types if it isn’t a policy.
A confirm page refreshed instead of confirming	A document in the handbook changed, or the contents did (a document added, a type changed), after the page was drawn. Read the refreshed page and confirm again.
Publish handbook or the audience is refused	The handbook holds documents from a space you can’t add from (see Editing a handbook that holds other spaces’ documents), it has no published document, or Chosen groups names no group.
“This handbook was changed by someone else. Reload to see their changes.”	Someone saved it after you opened it. Reload and make your change again.
A reader can’t open the handbook	It is a draft, or they are not in its audience. For a space handbook with chosen groups, they must also be able to read the space.
A handbook-only document still shows in its space	The handbook isn’t published yet (the no-orphans rule), or the person looking may write in that space and sees it marked Handbook only.
A reader can’t open a handbook policy from a link to /doc/{id}	That page keeps the space’s permissions. Link to the policy in the handbook instead: /handbooks/{id}/{document id}.
Confirm handbook doesn’t appear	Ask readers to confirm the whole handbook is off, the handbook is a draft, or read confirmation isn’t licensed.
Someone asked through a handbook got no reminder	Before 1.18.3 they weren’t reminded (see People who read only the handbook); from 1.18.3 they are.