The handbook
The handbook is where your team writes down how the workspace works, such as how you release, who owns what, what counts as production, when changes are frozen, and who Halon takes direction from during an incident. Halon reads it at the start of every chat and investigation, follows it, and links the page it followed in its answer.
Open it from the Handbook screen under Halon in the dashboard sidebar.
Starting a handbook
Section titled “Starting a handbook”An empty handbook offers three ways in.
- Draft with Halon. Halon reads your resource map, your repositories and their CI, and your past incidents and postmortems, then proposes a page for each thing a new teammate would need to know. Nothing is added until you accept it. See Pages Halon proposes.
- Import docs. Bring in docs you already keep. See Synced pages.
- Write a page. Start blank, or from one of the pages most teams write first.
| Starting page | What goes there |
|---|---|
| How we release | The tools and steps a release goes through, and when a release counts as done |
| Who owns what | Which team or person answers for each service, and whom to page |
| What production is | Which environments, databases and accounts are production, and which are safe to test in |
| Freeze windows | When nothing may be released or changed, and who may lift a freeze. See Freeze windows |
| On call | Who is on call for what, whom Halon pages when an alert fires at night, and what it may change on its own |
| Who directs Halon in an incident | The incident role Halon takes direction from, and anything else about who decides |
| Anything else | Anything Halon should follow in every chat and investigation |
Instructions your team wrote earlier for the whole workspace are kept as a page called General, with their history.
Instructions for one team, service or resource stay on the Memory page, under Instructions. When the handbook and a team’s or service’s instructions disagree, the more specific one wins.
Writing and editing pages
Section titled “Writing and editing pages”Click Add page, give the page a title, and write it. The editor has buttons for headings, lists and code, and Markdown switches to editing the Markdown itself. A page that uses formatting the editor has no button for, such as a link or a table, opens as Markdown so nothing in it is lost. Press Save page, or Cmd or Ctrl with S. Halon follows the page from its next chat or investigation.
Headings split a long page into sections Halon can find on their own, so use them.
Every save keeps the earlier wording. History on a page shows each earlier wording with who wrote it and when. If someone else saved the page while you were editing it, your save is refused and your words stay in the editor, so you can read their version and save again.
If you leave a page with changes you have not saved, the handbook asks before discarding them.
Drag pages in the list to change their order, which is the order Halon reads them in. To delete a page, open it and choose Delete page from its menu. Deleting a page removes its history too.
Writing the handbook needs the Handbook permission, which admins hold and anyone else is granted under Permissions. Everyone in the workspace can read it.
Freeze windows
Section titled “Freeze windows”A freeze window is a stretch of time when nothing may be released or changed, such as every Friday afternoon or the last week of December. Halon’s plans never run inside one. A plan scheduled for a time inside a window is refused when it is made and when it is approved, and a plan whose time comes during a window is stopped before it changes anything. Halon is told why, and when the window ends.
The Freeze windows starting page opens with a window to fill in, and any page you write can hold them under Add freeze window. Each window has the following.
| Field | What it does |
|---|---|
| Name | What the freeze is for, such as Friday afternoons |
| Repeats | Every week, from a day and time to a day and time, or Once, between two dates and times. A weekly window that ends earlier in the week than it starts runs across the weekend |
| Time zone | The time zone every time in the window is read in |
| Who may lift it | Optional. Halon names them when a plan is held back, and anyone allowed to edit the handbook lifts a freeze by changing or removing the window |
The page shows each window as a sentence, marked Frozen now while it holds, and Halon reads the same sentences at the start of every chat and investigation. A page can hold up to 20 windows. A freeze written only in a page’s words, or on a synced page, is something Halon reads but plans do not enforce, so set it as a window.
How Halon reads the handbook
Section titled “How Halon reads the handbook”Halon is given every short page whole at the start of a chat or investigation, in the handbook’s order. A page counts as short up to about 4,000 characters, and Halon is given at most about 24,000 characters of handbook this way. A longer page, and any past that budget, is named instead, and Halon searches it when it needs to. Each page shows which applies: Halon reads it whole or Halon searches it when needed.
When Halon follows a page, its answer names the page and links to it. A link to one section of a page opens at that heading.
Who directs Halon in an incident
Section titled “Who directs Halon in an incident”Anyone in an incident channel can ask Halon for something, so two people can ask for opposite things, such as one asking for a rollback while another says the database is at fault. Halon does not follow whoever spoke last. It says plainly that the requests conflict, names each person and what they asked, and follows the person who holds the role the handbook names. When that person has not decided, Halon asks them to before it changes anything.
The role is the Incident Lead until you add the Who directs Halon in an incident page and choose another from the roles on the Incident Roles screen under Configure (see Incident roles). If nobody holds the role in an incident yet, Halon asks the people there to assign it before acting on conflicting requests. If the role you chose is later disabled or deleted, Halon goes back to the Incident Lead and the page says so until you choose again.
Synced pages
Section titled “Synced pages”Import docs brings in docs you already keep, as pages that stay in step with where they come from.
| From | What to give | When it is read again |
|---|---|---|
| A repository on a connected GitHub, GitLab, Bitbucket or Azure DevOps | The repository, and a file such as HANDBOOK.md or AGENTS.md, or a folder such as docs/ | When its default branch changes, and every hour |
| A page in a connected Notion | The page’s link | Every hour |
Each file or document becomes a page. A folder brings in its Markdown and text files, up to 50, each up to 200 KB. A synced page is changed at its source, so it has no Edit. Open the source goes to it.
The list shows each source under Synced from, with when it was last read. If a read fails, or leaves a file out, the reason shows there and on its pages, and the pages keep what they last said. Sync now reads a source again at once. Stop syncing removes its pages from the handbook and leaves the source itself alone.
Pages Halon proposes
Section titled “Pages Halon proposes”Something Halon reads now beats what the handbook says. When a fresh reading contradicts a page, for example the page says releases go through one pipeline and the last few releases ran through another, Halon says so, works from what it read, and proposes an edit to the page. When drafting the handbook, it proposes new pages the same way.
Each proposal shows what Halon would write, what the page says now, and what Halon read that led to it.
| Choice | What happens |
|---|---|
| Accept edit or Add page | The page takes Halon’s wording, or is added. An edited page keeps its old wording in its history |
| Edit first | You change the wording, then it is saved |
| Dismiss | The handbook stays as it is, and Halon is told not to propose the same again |
Halon asks where it is working. In a dashboard chat the proposal is a card in the chat. In an incident channel it is a message in the thread with the same choices. Every proposal also waits in the handbook under Waiting for review until someone decides. Halon never proposes a change to a synced page or to who directs it.
If someone edits the page after Halon proposed a change, or adds a page with the same title, the proposal can no longer be accepted, so nobody overwrites a newer wording by accident.
The API and MCP
Section titled “The API and MCP”The handbook’s pages can be listed, read, added, changed and deleted with the REST API at /api/v1/handbook/pages and with the list_handbook_pages, get_handbook_page, upsert_handbook_page and delete_handbook_page MCP tools, under the handbook permission. freeze_windows sets a page’s freeze windows, and leaving it out keeps them. An edit sends back the wording_id it read, so one made over somebody else’s is refused. A synced page is changed only at its source.