Documentation

Getting started

The whole loop, start to finish: an account, a document, a tab, a submission, a review, and a merge. Every step below is what actually happens in the product today, not what's planned.

1. 1. Sign up

   Go to /signup and give it a handle (lowercase letters, numbers and hyphens), an email address, and a password. Writ sends a confirmation link to that address before you can write anything — click it to confirm. (If your instance has no mail server configured, which is normal for a local or trial install, the confirmation link is shown right on the page instead of emailed, so development doesn't need a real inbox. Some instances also require an invite code at signup — ask whoever runs yours if the form asks for one.)

2. 2. Log in

   Go to /login with the email and password you just confirmed. Writ authenticates you with a session cookie from here on.

3. 3. Create a document

   Your workspace at / has one form: a document name (2–64 lowercase letters, numbers or hyphens) and a visibility — Private or Public. Public documents can be read by anyone without an account; Private ones need a membership. Click Create document.

4. 4. Write your first tab

   A brand-new document has nothing in it. Its page offers one thing to do: Create the first tab, which opens the editor at the path you're about to write (for example notes.md). Writ saves as you type; click Submit when the edit is ready for comparison.

   What you type before Submit is kept as a draft on the server — it survives a closed tab and another device — and nothing is committed. Submit turns the draft into one commit and opens the comparison page. Every later edit goes through the full loop below.

5. 5. Propose an edit

   Open the document and choose Edit. Writ starts a numbered edit for you and saves it after you pause. Click the version name on Read, Edit, Changes, or a Submission to move through the versions that make sense there. Read includes published history, open submissions, and your private saved edits. Changes lets you choose an edit to compare with Published; submitted comparisons use their recorded submission base. A Submission lets you switch directly to another submission. Edit also lets you start a new edit or give the current one a clearer label. When it is ready, click Submit. Writ aligns your version against the published document sentence by sentence and labels each change wording only or meaning changed.

6. 6. Get it reviewed

   A submission that only changed wording can be finished right away by its author. If you are the document's only active human, you can also finish your own meaning-changing submission once its checks pass; Writ does not ask for a reviewer who does not exist. As soon as another verified human joins, the document's configured approval quorum applies to every open meaning-changing submission.

   The owner can add collaborators and choose the approval policy in Settings. Maintainers approve by default; a policy can include all members, list particular handles, or allow an author who already matches the policy to count their own explicit approval. Self-approval is off by default and never applies to agent-authored changes.

   If your document has rules in .semgit/rules.yaml (see Rules), some of them run automatically here too, and a blocked finding has to be fixed or waived before anyone can finish the submission, approved or not.

7. 7. Finish it

   Once any required approvals are present and nothing is blocked, the Finish button becomes available to whoever the document's merge policy permits. Click it, and the change lands on main — the document reflects it immediately.

Along the way

A few things worth knowing once the core loop feels familiar:

• The editor renders your Markdown as you type — headings, lists, emphasis — and keeps the plain-text source underneath. It saves to the current numbered edit after a short pause and keeps a local recovery copy until the server confirms the save.
• A tab can also be read as its raw Markdown source by adding ?raw=1 to its URL.
• Every document has a Comments page for anything that isn't a specific edit — a question, a note, a plan. A comment's later messages are replies.
• Agents (bots, scripts, other tools) are principals in Writ too — see The API for what they can do today.

Experimental tabs (#397): the overlapping-pages button opens the tabs in this document. A named edit covers all its tabs. Add tab creates a blank Markdown tab on that edit. Submit asks “Also changed” when other paths are included; Finish applies the entire submission, not just the open tab. Exports still cover only the selected tab.

Next: how to write rules your document enforces automatically — see Rules.