Docs
Docs is By Dawn’s wiki: runbooks, decisions and specs that live beside your tickets, where people and agents can both read them. This page shows you how to find your way around it, write and edit pages, review the edits agents propose, and start a page from a template.
Docs is part of some plans. If yours doesn’t include it, Docs shows Docs is not on your plan instead. If your organization had pages before its plan changed, they stay readable and exportable, but nobody can edit them.
Spaces and pages
Section titled “Spaces and pages”Open Docs from the sidebar, or press ⌘8. Pages live in spaces:
- Organization: one space for the whole organization. Every member can read and edit it, unless an admin makes it private.
- This project: one space per project, for that project’s pages. Project viewers can read it, and project members can edit it.
The switch at the top of Docs moves between This project and Organization. A space appears the first time someone creates a page in it, so there’s nothing to set up.
The Pages list on the left is the space’s tree. A page with pages under it is a section: it shows how many it holds, and opening it lists them under In this section. To move a page, drag it in the list: drop it between two pages to reorder it, or onto a page to put it under that one. You can also select it and press ⌥↑ or ⌥↓ (Alt↑ or Alt↓ on Windows and Linux).
The tabs at the top are Pages, Memory and Review:
- Memory holds short rules, concepts and decisions. Agents get the ones that matter as one-liners in every run, so a note is where you tell agents something once. A page holds the long-form reasoning a note points to. Memory is read in a project, so pick one first.
- Review holds the edits agents have proposed (see Review agent edits).
Create a page
Section titled “Create a page”-
Choose New page. To create it under an existing page, hover that page in the list and choose + instead.
-
Give it a Title, then pick a template (see Templates). Blank page starts empty.
-
Choose Create page.
In an empty space, Create the first page does the same.
Edit a page
Section titled “Edit a page”Choose Edit on the page. The editor is rich text: format with the toolbar or the usual shortcuts
(⌘B bold, ⌘I italic, ⌘E inline code). Type / for a block menu
(headings, lists, task lists, quotes, Note, Tip, Warning and Danger callouts, code blocks, Mermaid diagrams,
tables, dividers and images). Type @ to mention a person, ticket, epic or page. A ticket ID such as SAW-123
typed in the text becomes a link on its own.
Paste or drop an image to add it. PNG, JPEG, GIF, WebP and SVG images are accepted. Links must start with
https://, or be an anchor on the same page such as #rollout.
The bar under the editor tells you what’s saved. Press ⌘S to save and keep editing, or choose Save to save and go back to reading. Cancel drops your changes, and if you leave with unsaved changes, By Dawn asks first.
If someone else saved the page while you were editing, By Dawn merges their changes into yours when it can. When the same lines changed, it asks you to choose Keep my version or Take theirs and drop my edit.
History, comments and links
Section titled “History, comments and links”- History lists every revision. Compare any one with the previous or the current revision, inline or side by side, and choose Restore this revision to bring it back. Restoring saves it as a new revision, so nothing in the history is lost. An agent’s revisions carry a Worker badge that links to its ticket.
- Comments: select some text and choose Comment. Replies, @ mentions and Resolve work as you’d expect.
- Copy link copies the page’s link. Its menu can also copy the title as a link, or a
[[page]]link to paste into another page. - Backlinks, on the right, list the pages and tickets that link here. On a ticket, the Docs section’s Link a page links a page to it by hand.
- The export button saves the page as Markdown, HTML or a PDF, and the space’s header has Export space, which downloads every page as a zip file.
Verify a page
Section titled “Verify a page”Anyone who can edit a page can mark it as checked and still right. Choose Verify (or Re-verify), then how long it stays verified: 1 week, 1 month, 3 months or 6 months. The page shows Verified until that date. When the time runs out, it shows Stale, and By Dawn reminds the page’s owner under Docs to verify in the notification bell. Verifying a page that has no owner makes you its owner.
Review agent edits
Section titled “Review agent edits”Agents working on tickets can propose edits to pages, for example to record a decision they made. By default those edits wait for a person: Nothing shows on a page until someone approves it.
You’ll see them waiting:
- on the Review tab in Docs, and as a dot on Docs in the sidebar
- under Doc proposals in the notification bell, and in your Inbox
- in the Doc proposals section of the ticket that proposed them
Each proposal is one set of changes from one agent run, across one or more pages. When there’s nothing to review, the tab says Nothing waiting for review.
-
Open Review and choose a proposal. Yours to review lists the ones you can approve. Waiting on others lists the ones that touch a space you can’t edit.
-
Choose Show changes to see what each page would gain and lose. A badge says how each change fits the page: Applies cleanly, Merges with later edits or Conflict.
-
Choose Approve and apply to save every change, credited to the agent’s run and ticket. Choose Reject to drop them all.
A proposal is approved or rejected as a whole, not page by page. If a change has a Conflict, choose Resolve, edit the conflicting lines, choose Save resolution, then approve.
Rejecting doesn’t tell the agent, so if you want it to try again, say so on its ticket.
Let agents edit directly
Section titled “Let agents edit directly”An org owner or admin can let agents’ edits apply straight away, under Settings, then Organization, then Docs, in Agent doc writes:
- Propose: “A person approves each agent edit before it shows on a page. The default.”
- Direct: “Agent edits apply at once, attributed to the run and its ticket.”
A space can choose differently in Members & access › Agent edits. Either way, every agent edit is in the page’s History.
Templates
Section titled “Templates”A template starts a new page with a type and a body to fill in. By Dawn has five:
| Template | For |
|---|---|
| Blank page | anything |
| Decision record | a decision and why it was made. It asks for a key, such as D32, that you can link with [[D32]] |
| Runbook | the steps to run or fix something |
| RFC / spec | a proposal for others to comment on |
| Post-mortem | what went wrong and what you’ll change |
Your organization can add its own. They’re listed under Your organization’s templates when you create a page. To make one:
- From a page: on the page, choose ⋯ › Save as template. Give it a Name and Description, and choose whether it should ask for a key.
- From Settings: in Settings, then Organization, then Docs, under Doc templates, choose New template.
The person who made a template, or an org admin, can edit or delete it. A page made from a template doesn’t change when the template does.
Who can do what
Section titled “Who can do what”Each space gives its members one of three roles. An admin of the space sets them in Members & access:
| Role | Can |
|---|---|
| Viewer | read pages, history and backlinks |
| Editor | also write, move and restore pages, comment, and verify |
| Admin | also manage who has access |
A space either inherits its access (from the organization, or from its project) or is Private. A private space is open only to the people, teams and projects it lists, plus org owners and admins, and it shows a lock. To review a proposal, you need edit access to every space it touches.
How do I search Docs?
Press ⌘K (Ctrl K on Windows and Linux). The command palette searches tickets, pages and Memory notes together, and finds a page by its title, key or a phrase in it.
How do I delete a page?
Not from the app yet. Move it under a page of its own, such as one called “Archive”, so it’s out of the way.
Can I edit pages on my phone?
No. On a phone, Docs is read-only. Create and edit pages in the desktop or web app.
Can two people edit the same page at once?
Yes. Whoever saves second gets the other’s changes merged into theirs, or is asked to choose when the same lines changed. See Edit a page.