| 1 | --- |
| 2 | title: Docs |
| 3 | description: Write a workspace's specs, runbooks, decisions and onboarding together, live, with your agents. Spaces and pages, a block editor with diagrams and math, comments, suggestions from agents you accept or reject, pages that cite code and say when it changed, projects' docs folders, full history, templates, search by project, and Markdown export. |
| 4 | --- |
| 5 | |
| 6 | import { Steps } from '@astrojs/starlight/components'; |
| 7 | import Soon from '../../../components/Soon.astro'; |
| 8 | import Aside from '../../../components/Aside.astro'; |
| 9 | |
| 10 | **Docs is the workspace's written knowledge**: specs, runbooks, decisions, |
| 11 | onboarding and meeting notes, in the same place as the conversations and the |
| 12 | code they describe. People and agents write it together. Agents read it before |
| 13 | they answer, and when they change a page, you see exactly what they changed |
| 14 | and decide whether it stays. |
| 15 | |
| 16 | Docs is open to every member of a workspace, on every plan. Open **Docs** in |
| 17 | the rail on the left, or go to `g1t.sh/<workspace>/-/docs`. |
| 18 | |
| 19 | ## How it fits together |
| 20 | |
| 21 | | | | |
| 22 | | --- | --- | |
| 23 | | **Spaces** | Where pages live: one for the whole workspace, one per team or project, or a private one for a few people. Each space decides who can read and write it, and how agents change it. | |
| 24 | | **Pages** | A tree inside each space. A page can hold other pages. Every page has an icon, an optional cover, owners, linked projects, history, comments and backlinks. | |
| 25 | | **The editor** | Blocks you add with `/`: text, headings, lists, to-dos, toggles, callouts, code, tables, images and files, Mermaid diagrams, math, and live cards for issues, pull requests, channels, projects and other pages. | |
| 26 | | **Agents** | Read the pages the person they work for can read. Suggest changes you accept or reject inline, or edit directly where a space allows it. Every change is attributed in the history. | |
| 27 | | **Code** | A page cites the code it describes. When a merged pull request changes that code, the page says it may be out of date, and its owners are told. A project's `docs/` folder can sit beside your spaces, read-only. | |
| 28 | |
| 29 | Docs is its own mode, not a tab in a project. To see the pages about one |
| 30 | project, filter Docs by that project. |
| 31 | |
| 32 | ## Spaces |
| 33 | |
| 34 | Every workspace starts with a **General** space for things everyone should |
| 35 | know. Make more from **New space** on Docs' home, or **+** beside **Spaces** |
| 36 | in the sidebar. |
| 37 | |
| 38 | A space is for one of three audiences: |
| 39 | |
| 40 | | Who it's for | Who can open it | |
| 41 | | --- | --- | |
| 42 | | **Everyone in the workspace** | Every member, with the space's base role. | |
| 43 | | **A team** | Members of that team, with the space's base role. | |
| 44 | | **Only its members** | The people, agents and teams listed in the space, and nobody else. Workspace owners don't see a private space unless they're added. | |
| 45 | |
| 46 | Whoever makes a space has full access to it. Owners of the workspace have full |
| 47 | access to every workspace and team space. |
| 48 | |
| 49 | ### Roles |
| 50 | |
| 51 | Each person's role in a space is the highest that applies to them: the |
| 52 | space's base role (for everyone, or for the team), and any role they were |
| 53 | given in the space's **Members**, directly or through a team. |
| 54 | |
| 55 | | Role | Can | |
| 56 | | --- | --- | |
| 57 | | **Can view** | Read pages, their history and their comments. | |
| 58 | | **Can comment** | Read, and comment on passages or whole pages. | |
| 59 | | **Can edit** | Write and organize pages, accept or reject suggestions, restore versions, and move pages to the trash. | |
| 60 | | **Full access** | Edit, change the space's settings and members, and delete pages from the trash for good. | |
| 61 | |
| 62 | Change them in the space's **Settings** (the gear beside the space in the |
| 63 | sidebar, or **Settings** on the space's page): |
| 64 | |
| 65 | - **Members**: add a person, an agent or a team with a role; change or remove |
| 66 | it. A private space always keeps at least one person with full access. |
| 67 | - **Agents in this space**: **Suggest changes** (the default) or **Edit |
| 68 | directly**. See [Agents and pages](#agents-and-pages). |
| 69 | - **Projects**: the repositories the space is about, as `owner/name`. Docs |
| 70 | can be filtered by them. |
| 71 | - **Archive this space** takes it out of the sidebar and search. Its pages and |
| 72 | history are kept. The General space can't be archived. |
| 73 | |
| 74 | ## Pages |
| 75 | |
| 76 | Make a page with **New page** on Docs' home or a space's page, **+** beside a |
| 77 | space or a page in the sidebar (a page inside it), or from a |
| 78 | [template](#templates). Give it a title, and press **Enter** to start |
| 79 | writing. |
| 80 | |
| 81 | Above the title, **Add icon** gives the page an emoji and **Add cover** a |
| 82 | banner. Under the title you see who edited it last and when, its owners, the |
| 83 | projects it's linked to, and how long it takes to read. |
| 84 | |
| 85 | ### Organize |
| 86 | |
| 87 | - **Drag** a page in the sidebar onto another to put it inside, or onto the |
| 88 | top edge of one to put it before it. Drop it on a space's name to move it |
| 89 | to the top of that space. |
| 90 | - **⋯ → Move** does the same from the page, including to another space. Pages |
| 91 | inside a page move with it. |
| 92 | - **⋯ → Duplicate** copies a page, content and all, next to it. |
| 93 | - A page's address ends in its id: `/<workspace>/-/docs/engineering/release-plan-pag_01j…`. |
| 94 | Renaming or moving a page keeps every link to it working. |
| 95 | |
| 96 | ### Favorites and recent |
| 97 | |
| 98 | Star a page (the star at the top of it) to keep it under **Favorites** in the |
| 99 | sidebar. **Recent** lists the pages you opened last. |
| 100 | |
| 101 | ### Trash |
| 102 | |
| 103 | **⋯ → Move to trash** puts a page, and the pages inside it, in the **Trash** |
| 104 | (in the sidebar). Anyone who can edit the space can restore it from there, |
| 105 | with what was inside it. Deleting from the trash removes the page, its |
| 106 | history and its comments for good, and needs full access to the space. |
| 107 | |
| 108 | ## The editor |
| 109 | |
| 110 | Type `/` anywhere for the block menu, and keep typing to filter it. |
| 111 | |
| 112 | | Block | How to add it | In Markdown | |
| 113 | | --- | --- | --- | |
| 114 | | Text, Heading 1–3 | `/text`, `/h1`, or type `#`, `##`, `###` and a space | `#`, `##`, `###` | |
| 115 | | Bulleted, numbered and to-do lists | `/bullet`, `/numbered`, `/todo`, or type `-`, `1.`, `[]` | `-`, `1.`, `- [ ]` | |
| 116 | | Toggle | `/toggle` | `<details>` | |
| 117 | | Quote | `/quote`, or type `>` | `>` | |
| 118 | | Callout (info, warning, success) | `/callout`, `/warning`, `/tip`. Click its icon to change its kind. | `> [!NOTE]`, `> [!WARNING]`, `> [!TIP]`, `> [!CAUTION]` | |
| 119 | | Divider | `/divider`, or type `---` | `---` | |
| 120 | | Code, with syntax highlighting | `/code`, or type ` ``` ` and a language | fenced code | |
| 121 | | Table | `/table` | GitHub tables | |
| 122 | | Image, video, audio, file | `/image`, `/video`, `/audio`, `/file`: upload one, or paste a link | `![]()`, links | |
| 123 | | Diagram | `/diagram` or `/mermaid`. **Edit source** to change it; it's drawn as you type. | ` ```mermaid ` | |
| 124 | | Math | `/math` or `/latex`. Click the formula to change it. | `$$ … $$` | |
| 125 | | Embed from g1t | `/embed`, then paste the address of an issue, pull request, channel, project or page. The card shows its live title and state (open, merged, closed). | a link | |
| 126 | | Date | `/date` | the date | |
| 127 | | Cite code | `/cite`: choose a repository and a path, and what there the page describes (the file or folder, a symbol, an endpoint, an environment variable). See [Pages that cite code](#pages-that-cite-code). | a link to the file | |
| 128 | |
| 129 | Inline: |
| 130 | |
| 131 | - **Bold**, *italic*, underline, ~~strikethrough~~, `code` and links from the |
| 132 | toolbar that appears when you select text, or with Markdown as you type |
| 133 | (`**bold**`, `_italic_`, `` `code` ``) and the usual shortcuts |
| 134 | (<kbd>⌘ B</kbd>, <kbd>⌘ I</kbd>, <kbd>⌘ U</kbd>). |
| 135 | - **`@`** mentions a person or an agent. A person mentioned in a page is |
| 136 | told, once, in their notifications. |
| 137 | - **`[[`** links to another page by title. The page you link to lists yours |
| 138 | under **Linked from**. |
| 139 | |
| 140 | Every block has a handle on its left when you hover it: drag it to move the |
| 141 | block, or open its menu to change its type, color or delete it. Press |
| 142 | <kbd>Tab</kbd> to nest a block under the one above it. |
| 143 | |
| 144 | **Pasting Markdown** turns it into blocks. **⋯ → Copy as Markdown** puts the |
| 145 | whole page on your clipboard as Markdown. |
| 146 | |
| 147 | Images and files you add are kept with the workspace and served from |
| 148 | `g1tusercontent.com`, never from `g1t.sh`. Each can be up to 25 MB. |
| 149 | Anyone with a file's address can open it, as with any shared link, so don't |
| 150 | put a page's files where the page itself shouldn't go. |
| 151 | |
| 152 | <Aside type="note" title="Who can edit"> |
| 153 | People who can only view or comment see the page live, with everyone's |
| 154 | changes as they happen, but can't change it. The editor says so under the |
| 155 | title. |
| 156 | </Aside> |
| 157 | |
| 158 | ## Writing together |
| 159 | |
| 160 | Pages are live: everyone with a page open sees each other's changes as they |
| 161 | type, with a cursor and name for each person. The faces at the top of the page |
| 162 | are who's on it now, agents included while they work on it. |
| 163 | |
| 164 | Edits merge however many people type at once, even in the same paragraph, and |
| 165 | nothing is lost if your connection drops: the page says **Offline** and |
| 166 | sends your changes when you're back. |
| 167 | |
| 168 | ## Comments |
| 169 | |
| 170 | - **On a passage**: select text and choose **Comment**. The passage is |
| 171 | highlighted, and the thread stays attached to it as the page changes. |
| 172 | - **On the whole page**: write in **Discussion** at the bottom of the page. |
| 173 | - **All of them**: the comments button at the top of the page opens them |
| 174 | beside the text, in the order they appear in it. |
| 175 | |
| 176 | Reply in a thread, react to a comment, and **Resolve** a thread when it's |
| 177 | done (you can reopen it). `@`-mention someone in a comment to tell them; they |
| 178 | are told only if they can read the page. |
| 179 | |
| 180 | Anyone who can comment can start threads, reply, react and resolve. Only a |
| 181 | comment's author edits it; its author or an editor deletes it; editors delete |
| 182 | whole threads. |
| 183 | |
| 184 | ## Agents and pages |
| 185 | |
| 186 | Agents work on Docs for a person, never on their own authority. An agent |
| 187 | asked by you: |
| 188 | |
| 189 | - **reads** only pages in spaces you can read. When it answers somewhere |
| 190 | others will read the answer (a channel), it uses only pages everyone there |
| 191 | can read. See [What agents can do for whom](/guides/agent-access/). |
| 192 | - **suggests** a change where you can comment or edit. A suggestion is a |
| 193 | tracked change: the blocks it replaces are struck through in place, and |
| 194 | the card beside them (or above the page on a narrower screen) shows what |
| 195 | it would write instead. |
| 196 | - **edits directly** only where you can edit **and** the space's **Agents in |
| 197 | this space** is **Edit directly**. Otherwise its edit becomes a |
| 198 | suggestion. |
| 199 | - **makes new pages** where you can edit, such as "write this up" in a |
| 200 | thread. The page is yours: you're its owner, and it links back to where it |
| 201 | came from. |
| 202 | |
| 203 | ### How agents find your docs |
| 204 | |
| 205 | You don't have to point an agent at the right page. Before an agent answers |
| 206 | in chat, and as it works through each step of a session, it recalls the |
| 207 | passages of your Docs closest in meaning to what it's been asked: a few |
| 208 | sections of pages (and of projects' docs), each with the page and heading it |
| 209 | came from, so it can follow your runbooks and decisions and link you to them. |
| 210 | When nothing in Docs is about the question, it recalls nothing. |
| 211 | |
| 212 | - **Only what everyone in the conversation can read.** In a DM or a private |
| 213 | channel, that's the spaces every person there can read; in a public |
| 214 | channel, only spaces the whole workspace can read. Private spaces stay |
| 215 | private: their pages never reach a conversation that includes someone |
| 216 | outside them. Projects' docs come only from repositories everyone there |
| 217 | can read (in a public channel, only public repositories). |
| 218 | - **Required reading first.** An agent can be given spaces to read first. |
| 219 | Recall looks there before the rest of the workspace, so a support agent |
| 220 | leans on the support runbooks. |
| 221 | - **Current, not cached.** A page is indexed within about half a minute of |
| 222 | a change, without slowing the editor, and pages in the trash, or in an archived space, are never recalled. A page |
| 223 | marked possibly out of date is recalled with that warning, so the agent |
| 224 | says so instead of trusting it. |
| 225 | - **Meaning, then words.** Recall matches by meaning, so "how do we roll |
| 226 | back?" finds a section titled "Reverting a deploy". When meaning finds |
| 227 | too little, passages with the question's words fill in. |
| 228 | |
| 229 | An agent can still read a whole page, search, or list a space's pages when |
| 230 | recall isn't enough; recall is the head start. |
| 231 | |
| 232 | ### Write a thread up |
| 233 | |
| 234 | In chat, **⋯ → Write this up in Docs** on a message or an open thread asks |
| 235 | an agent for a page about the thread. Choose the space (only spaces you can |
| 236 | write in are listed), a title if you want one, and which agent writes it: |
| 237 | @g1t, or another agent in the conversation. The ask is posted in the thread, |
| 238 | as you, so everyone there sees what was asked, and it carries the thread's |
| 239 | link. The agent writes what was decided, why, and what's next, links the |
| 240 | thread as its source, and replies with the page. As with any page an agent |
| 241 | makes for you, you own it. |
| 242 | |
| 243 | ### Accept or reject |
| 244 | |
| 245 | Each suggestion says which agent made it, who it was for, and why. |
| 246 | |
| 247 | - **Accept** applies it to the page, live for everyone on it. The history |
| 248 | records it as "Suggested by @inky, accepted by @ana". |
| 249 | - **Reject** drops it. Nothing on the page changes. |
| 250 | - **Accept all** applies every open suggestion on the page, oldest first. |
| 251 | |
| 252 | Accepting needs edit access to the space. When the part of the page a |
| 253 | suggestion changes was deleted meanwhile, the suggestion can't be applied and |
| 254 | is marked stale. |
| 255 | |
| 256 | A page's owners are told when an agent suggests a change to it. |
| 257 | |
| 258 | <Aside type="tip" title="Ask in chat"> |
| 259 | "@inky the rollout section of the release plan is out of date, fix it" in a |
| 260 | channel works: Inky reads the page, and suggests or makes the change for |
| 261 | you, depending on the space. |
| 262 | </Aside> |
| 263 | |
| 264 | ## Pages that cite code |
| 265 | |
| 266 | A page about code says which code. When that code changes, the page tells |
| 267 | you it may be out of date, instead of quietly going wrong. |
| 268 | |
| 269 | **Cite code in the text.** Type `/cite`, choose a repository and a path, and |
| 270 | say what the page describes there: |
| 271 | |
| 272 | | What it describes | For example | |
| 273 | | --- | --- | |
| 274 | | A file or folder | `src/export.ts`, `src/export` (everything in it) | |
| 275 | | A symbol | `exportCsv` in `src/export.ts` | |
| 276 | | An endpoint | `POST /v1/exports` in `api/routes.rs` | |
| 277 | | An environment variable | `EXPORT_BUCKET` in `wrangler.jsonc` | |
| 278 | |
| 279 | The path can be a pattern: `*` matches within a folder, `**` across folders |
| 280 | (`src/**/*.sql`), `?` one character. The citation is a chip in the text that |
| 281 | opens the code at the commit it was cited at. A link to a file in a repository |
| 282 | (`/acme/web/blob/main/src/export.ts`), pasted or written by an agent, counts |
| 283 | as a citation too. |
| 284 | |
| 285 | **Say what the whole page describes.** Under the title, **Describes** lists |
| 286 | repositories and paths the page is about. Press **+** to add one, or remove |
| 287 | one from the same place. Anyone who can edit the page can change it. |
| 288 | |
| 289 | **When the code changes.** When a pull request that changes a cited path is |
| 290 | merged, or a commit is pushed straight to the default branch, the page is |
| 291 | marked **possibly out of date**: |
| 292 | |
| 293 | - A banner on the page says which change and which paths: "Possibly out of |
| 294 | date since acme/web#431 changed src/export.ts". **Review changes** opens |
| 295 | the pull request's changes. |
| 296 | - The page's owners are told in their notifications. |
| 297 | - The page shows **Possibly stale** on its card, a dot in the sidebar's tree, |
| 298 | and in **Possibly stale** in the sidebar, which lists every such page you |
| 299 | can read. Docs' home shows the latest under **Possibly out of date**. |
| 300 | |
| 301 | Read what changed, update the page if it needs it, then press **Mark as |
| 302 | current**. That needs edit access, and clears it for everyone. |
| 303 | |
| 304 | Only the change's repository decides who sees it: someone who can't read |
| 305 | that repository sees "a change you can't see" instead of its name, and is |
| 306 | told without it. |
| 307 | |
| 308 | **Agents keep pages current.** An agent asked to bring a page up to date |
| 309 | reads what changed, then edits the page or suggests the change as usual, |
| 310 | saying the edit brings it up to date: once it is applied (or you accept the |
| 311 | suggestion), the page is current again. An agent only learns of changes in |
| 312 | repositories the person it works for can read. |
| 313 | |
| 314 | ## History |
| 315 | |
| 316 | **⋯ → History** lists every version of the page: when, who (people and agents), |
| 317 | and what kind of change it was. Choose a version to see what changed in it, |
| 318 | line by line. |
| 319 | |
| 320 | A new version is recorded: |
| 321 | |
| 322 | - after a burst of editing, at most every 10 minutes while people type; |
| 323 | - for every change an agent makes, and every suggestion accepted; |
| 324 | - when a version is restored. |
| 325 | |
| 326 | **Restore this version** makes the page what it was then, as a new version, |
| 327 | so nothing after it is lost. Restoring needs edit access. |
| 328 | |
| 329 | ## Templates |
| 330 | |
| 331 | Start a page with its structure already in place: **Templates** in the |
| 332 | sidebar, the template row on Docs' home, or ask an agent to use one. |
| 333 | |
| 334 | g1t's templates: |
| 335 | |
| 336 | | Template | For | |
| 337 | | --- | --- | |
| 338 | | **Meeting notes** | Attendees, agenda, decisions, action items. | |
| 339 | | **Spec / RFC** | Problem, goals and non-goals, design with a diagram, alternatives, rollout, open questions. | |
| 340 | | **Decision record** | Context, the decision, options compared, consequences. | |
| 341 | | **Runbook** | Symptoms, checks, the fix, when to escalate. | |
| 342 | | **Onboarding** | A new teammate's first day and week, people to know, links. | |
| 343 | | **Project brief** | Why, what done looks like, scope, team, milestones, risks. | |
| 344 | | **Postmortem** | Severity, timeline, root cause, what went well and badly, action items. | |
| 345 | | **Weekly update** | Shipped, in progress, next, blocked. | |
| 346 | |
| 347 | Save any page as one of your workspace's templates with **⋯ → Save as |
| 348 | template**. Everyone in the workspace can use it. Whoever saved a template, |
| 349 | or an owner, can delete it. |
| 350 | |
| 351 | ## Search and projects |
| 352 | |
| 353 | The search box at the top of the sidebar, and **Search docs** on Docs' home, |
| 354 | look through every page you can read, and the projects' docs shown in Docs, by |
| 355 | their words and by what they mean. Type words, or ask a question: "how do we |
| 356 | rotate the API key?" finds the section that explains it even when it's |
| 357 | worded differently. Each result shows the passage that matched, under its |
| 358 | heading. Narrow it to one space or one project. |
| 359 | |
| 360 | Linking to a page from the editor searches titles and text as you type. |
| 361 | |
| 362 | A page belongs to a project when the page, or its space, is linked to the |
| 363 | project. On Docs' home, **All projects** filters the recently edited pages and |
| 364 | the spaces to one project. |
| 365 | |
| 366 | Agents search the same way, and only find what the people they answer can |
| 367 | read. See [How agents find your docs](#how-agents-find-your-docs). |
| 368 | |
| 369 | ## Projects' docs |
| 370 | |
| 371 | A repository's own docs (its `docs/` folder and its README) stay in the |
| 372 | repository and change through pull requests. Docs can show them beside your |
| 373 | spaces, so one sidebar and one search cover both. |
| 374 | |
| 375 | <Steps> |
| 376 | |
| 377 | 1. On Docs' home, press **Show a project's docs**, or **+** next to |
| 378 | **Projects' docs** in the sidebar. |
| 379 | 2. Choose a repository you can read. Its README and every Markdown file under |
| 380 | `docs/` on the default branch appear in the sidebar, in their folders. |
| 381 | |
| 382 | </Steps> |
| 383 | |
| 384 | - The files are read-only here, rendered as Code renders them, with links and |
| 385 | pictures pointing into the repository. **Edit in Code** opens the file; |
| 386 | change it there or in a pull request. |
| 387 | - They follow the default branch: every push reads the changed files again. |
| 388 | - Search finds them with your pages, marked with the repository's name. |
| 389 | - Each person sees only the repositories they can read, whoever added them. |
| 390 | - Whoever added a project's docs, or a workspace owner, can stop showing them |
| 391 | from the bin icon on any of its pages. |
| 392 | |
| 393 | A project's docs show its first 300 Markdown files; a file over 512 KB is |
| 394 | listed but not shown. |
| 395 | |
| 396 | ## Export |
| 397 | |
| 398 | - **⋯ → Export Markdown** downloads a page as a `.md` file. |
| 399 | - **Export** on a space's page downloads the whole space as a zip of Markdown |
| 400 | files, in folders that follow its page tree. |
| 401 | |
| 402 | Diagrams export as ` ```mermaid ` blocks, math as `$$` blocks, callouts as |
| 403 | GitHub alerts, toggles as `<details>`, and embeds and page links as links, so |
| 404 | the files read well anywhere Markdown does. |
| 405 | |
| 406 | ## Coming soon <Soon /> |
| 407 | |
| 408 | - **"Write this up" from a thread** in one click, linked both ways. |
| 409 | - **A documenter agent** that keeps a space current after merges (updating |
| 410 | the pages marked possibly out of date) and writes the weekly summary. |
| 411 | - **Editing a project's docs from Docs**, opening a pull request for you. |
| 412 | |
| 413 | ## Pricing |
| 414 | |
| 415 | Docs is included on every plan: spaces, pages, live editing, comments, history |
| 416 | and search, with no seats. Files in pages count toward storage. Agents' work |
| 417 | on pages is charged to the agent, like any of its work; see |
| 418 | [what an agent costs](/guides/agents/#what-an-agent-costs). |