The Artifacts guide explains home, the sidebar, sharing and access requests, Private, spaces with Editors can share, docs, agents and writing a thread up, links in chat, history, templates, the trash and export, in place of the Docs guide, whose links now go to it.
llms.txt names the artifact MCP tool, its actions and the artifacts scopes, the MCP reference says where editors may share, and the chat, access and workspace guides and the landing page say Artifacts where they said Docs.
10 files+360−4420/10 viewed
| 82 | 82 | { label: 'Routines', slug: 'guides/agent-routines' }, | |
| 83 | 83 | { label: 'Agent budgets and spend', slug: 'guides/agent-budgets' }, | |
| 84 | 84 | { label: 'What agents can do for whom', slug: 'guides/agent-access' }, | |
| 85 | − | { label: 'Docs', slug: 'guides/docs' }, | |
| 85 | + | { label: 'Artifacts', slug: 'guides/artifacts' }, | |
| 86 | 86 | { label: 'Agents in your chat app', slug: 'guides/chat-app', badge: { text: 'Soon', variant: 'default' } }, | |
| 87 | 87 | ], | |
| 88 | 88 | }, |
| 77 | 77 | | --- | --- | | |
| 78 | 78 | | Messages | From a channel or DM every person in the audience is in, or from public channels. | | |
| 79 | 79 | | Code, issues and pull requests | From repositories every person in the audience can read, and that the agent's own access allows. None at all if anyone in the audience has no Code access. | | |
| 80 | − | | Docs | From spaces every person in the audience can read. | | |
| 80 | + | | Artifacts | Only artifacts every person in the audience can open. | | |
| 81 | 81 | ||
| 82 | 82 | 3. **Who asks doesn't widen anything.** What the agent may *do* is capped by | |
| 83 | 83 | the asker's access. What it may *say* is capped by the audience, which | |
| ⋯ | |||
| 180 | 180 | ||
| 181 | 181 | | | | | |
| 182 | 182 | | --- | --- | | |
| 183 | − | | **Sees** | Chat, Docs, Agents and the inbox. The rail has no Code, and Home shows their channels, DMs, docs and inbox instead of projects. | | |
| 183 | + | | **Sees** | Chat, Artifacts, Agents and the inbox. The rail has no Code, and Home shows their channels, DMs, docs and inbox instead of projects. | | |
| 184 | 184 | | **Can't open** | Any repository, issue, pull request, check or deploy page. The workspace's base permission and team grants don't apply to them. | | |
| 185 | 185 | | **Still sees work reach them** | Cards about issues, pull requests and deploys appear in their channels as summaries: title, state and who is on it. Opening one asks for Code access. | | |
| 186 | − | | **Can ask agents** | Anything about the product. Agents explain how things work and what changed, but never show them source code. Owners can tighten this so agents answer only from Docs. | | |
| 186 | + | | **Can ask agents** | Anything about the product. Agents explain how things work and what changed, but never show them source code. Owners can tighten this so agents answer only from the workspace's docs. | | |
| 187 | 187 | ||
| 188 | 188 | Turning Code access back on restores what their teams and roles give them. | |
| 189 | 189 | ||
| 1 | + | --- | |
| 2 | + | title: Artifacts | |
| 3 | + | description: Make docs with your workspace and its agents, live. Keep them private, share them with people, agents and teams, put them in spaces, or open them to the workspace. Comments, suggestions from agents, docs that cite code, history, templates, search 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 | + | **Artifacts are what your workspace makes together**: docs now, and slides, | |
| 11 | + | designs and dashboards soon. People and agents edit them live. Each one is | |
| 12 | + | private until you share it, and agents read only what the people they work | |
| 13 | + | for can read. | |
| 14 | + | ||
| 15 | + | Open **Artifacts** in the rail on the left, or go to | |
| 16 | + | `g1t.sh/<workspace>/-/artifacts`. Artifacts is open to every member of a | |
| 17 | + | workspace, on every plan. | |
| 18 | + | ||
| 19 | + | ## How it fits together | |
| 20 | + | ||
| 21 | + | | | | | |
| 22 | + | | --- | --- | | |
| 23 | + | | **Artifacts** | A doc today. Each has one owner, the person who made it (or the person an agent made it for), and an address that ends in its id. | | |
| 24 | + | | **Private** | What you make starts in your **Private** section, where only you can see it. A lock on it means only you can open it. | | |
| 25 | + | | **Sharing** | Share an artifact with people, agents and teams, each with a role, or open it to everyone in the workspace or to anyone in it with the link. | | |
| 26 | + | | **Spaces** | Where a team, a project or a topic keeps its artifacts. What is in a space follows the space's access, unless it's set to only people invited. | | |
| 27 | + | | **Agents** | Read what the person they work for can read, narrowed to what everyone in the conversation can read. They suggest changes you accept or reject, or edit directly where that's allowed. | | |
| 28 | + | ||
| 29 | + | ## Home | |
| 30 | + | ||
| 31 | + | Home lists every artifact you can open, newest first, grouped by the day it | |
| 32 | + | was last edited in your time zone: **Today**, **Yesterday**, then the date. | |
| 33 | + | ||
| 34 | + | | Tab | Shows | | |
| 35 | + | | --- | --- | | |
| 36 | + | | **All** | Everything you can open. | | |
| 37 | + | | **Yours** | What you own. | | |
| 38 | + | | **Shared with you** | What other people shared with you, newest share first, and link-shared artifacts you've opened. | | |
| 39 | + | ||
| 40 | + | - **Search** (press <kbd>/</kbd>) matches words and meaning: "how do we roll | |
| 41 | + | back?" finds a doc titled "Reverting a deploy". | |
| 42 | + | - **Filters** narrow the list by kind, space, owner and project. On a phone | |
| 43 | + | they're under **Filters**. | |
| 44 | + | - The list and grid buttons switch between rows and cards with a preview. | |
| 45 | + | - Each row shows the kind, who can open it (a lock when only you can, a globe | |
| 46 | + | when the workspace can, a link when anyone in it with the link can, or how | |
| 47 | + | many people it's shared with), where it is, and when it was last edited and | |
| 48 | + | by whom. Its **⋯** menu has **Open in new tab**, **Add to Favorites**, | |
| 49 | + | **Share…**, **Rename**, **Duplicate**, **Move to…**, **Copy link**, | |
| 50 | + | **Export Markdown**, **Save as template** and **Move to trash**, as far as | |
| 51 | + | your role allows. | |
| 52 | + | ||
| 53 | + | **Make something new** at the top starts one. **Docs** makes a doc in your | |
| 54 | + | Private at once; its arrow starts one **From a template…** or **In a space…**. | |
| 55 | + | Slides, Design and Dashboards say **Coming soon**. | |
| 56 | + | ||
| 57 | + | ## The sidebar | |
| 58 | + | ||
| 59 | + | | Section | What's there | | |
| 60 | + | | --- | --- | | |
| 61 | + | | **Search**, **Home**, **Templates** | As they say. **+** at the top makes a new artifact. | | |
| 62 | + | | **Favorites** | What you starred. | | |
| 63 | + | | **Spaces** | The spaces you've joined, your team spaces and the members-only spaces you're in, each with its tree. **+** browses spaces or makes one. | | |
| 64 | + | | **Private** | Your artifacts in no space. Only you see this section. | | |
| 65 | + | | **Shared** | The highest artifact of each tree someone shared with you. | | |
| 66 | + | | **Possibly out of date** | Docs whose cited code changed. Shown when there are any. | | |
| 67 | + | | **Projects' docs** | Repositories' `docs/` folders, read-only. | | |
| 68 | + | | **Trash** | What was moved to the trash. | | |
| 69 | + | ||
| 70 | + | Drag a row onto a doc to put it inside, or onto the top edge of a row to put | |
| 71 | + | it before it. Only a doc can hold other artifacts: a doc with others inside | |
| 72 | + | is the folder. | |
| 73 | + | ||
| 74 | + | ## Sharing | |
| 75 | + | ||
| 76 | + | **Share** at the top of an artifact (or **⋯ → Share…**) opens who has access. | |
| 77 | + | ||
| 78 | + | <Steps> | |
| 79 | + | ||
| 80 | + | 1. Choose people, agents or teams in the workspace, and a role. | |
| 81 | + | 2. Add a message if you want one, then press **Invite**. People you add get | |
| 82 | + | an inbox item with the link. | |
| 83 | + | ||
| 84 | + | </Steps> | |
| 85 | + | ||
| 86 | + | | Role | Can | | |
| 87 | + | | --- | --- | | |
| 88 | + | | **Can view** | Read it, its history and its comments. | | |
| 89 | + | | **Can comment** | Read, and comment on passages or the whole doc. | | |
| 90 | + | | **Can edit** | Write and organize it, accept or reject suggestions, restore versions, and move it to the trash. | | |
| 91 | + | | **Full access** | Edit, share it, change its general access, and delete it from the trash for good. | | |
| 92 | + | ||
| 93 | + | **Who has access** lists the owner, everyone it's shared with directly (change | |
| 94 | + | their role, or **Remove access**), and anyone who has access from a doc it's | |
| 95 | + | inside, with a link to where that's set. | |
| 96 | + | ||
| 97 | + | **General access**: | |
| 98 | + | ||
| 99 | + | - **Everyone in the space**, or **Only people invited**, for an artifact in a | |
| 100 | + | space or inside a doc. Only people invited stops access there: the space's | |
| 101 | + | members, or whoever can open the doc above, can't open it unless invited. | |
| 102 | + | - **Restricted**, **Everyone in the workspace**, or **Anyone in the workspace | |
| 103 | + | with the link**, each with a role (never full access). This is set on an | |
| 104 | + | artifact at the top of its tree, or on one that's only for people invited; | |
| 105 | + | what's inside follows it. | |
| 106 | + | - **Anyone in the workspace with the link** keeps it out of lists, search and | |
| 107 | + | agents' answers until a member opens the link. After that, it's under their | |
| 108 | + | **Shared with you**. | |
| 109 | + | - Links for people outside the workspace aren't available. | |
| 110 | + | ||
| 111 | + | **Agents may** says how agents change it: as its space says, **Suggest | |
| 112 | + | changes**, or **Edit directly**. | |
| 113 | + | ||
| 114 | + | Only people with full access share an artifact, unless its space lets editors | |
| 115 | + | share (see [Spaces](#spaces)). Anyone else sees the dialog read-only. | |
| 116 | + | ||
| 117 | + | ### Asking for access | |
| 118 | + | ||
| 119 | + | An artifact you can't open shows **You need access**. **Ask for access** | |
| 120 | + | tells its owner and the people with full access (up to 20) in their inbox, | |
| 121 | + | with your message if you add one. You can ask once a day for each artifact. | |
| 122 | + | ||
| 123 | + | ## Private | |
| 124 | + | ||
| 125 | + | An artifact is private when only its owner can open it: it's in your Private | |
| 126 | + | section, it isn't shared with anyone, and its general access is | |
| 127 | + | **Restricted**. It shows a lock with "Only you can see this". | |
| 128 | + | ||
| 129 | + | Workspace owners can't open someone's private artifacts, or artifacts in a | |
| 130 | + | members-only space they aren't in. | |
| 131 | + | ||
| 132 | + | **Duplicate** makes a copy that is yours and private, next to the original | |
| 133 | + | when you can add there, and in your Private otherwise. A copy is never shared | |
| 134 | + | more widely than you chose. | |
| 135 | + | ||
| 136 | + | ## Spaces | |
| 137 | + | ||
| 138 | + | Every workspace has a **General** space for what everyone should know. Make | |
| 139 | + | more from **+** beside **Spaces** in the sidebar, then **New space**. | |
| 140 | + | ||
| 141 | + | | Who it's for | Who can open it | | |
| 142 | + | | --- | --- | | |
| 143 | + | | **Open** (everyone in the workspace) | Every member, with the space's base role. Join it to see it in your sidebar. | | |
| 144 | + | | **Team** | Members of that team, with the space's base role. | | |
| 145 | + | | **Members only** | The people, agents and teams listed in the space, and nobody else. | | |
| 146 | + | ||
| 147 | + | **Browse spaces** lists every space you can open; **Join** or **Leave** an | |
| 148 | + | open one. Whoever makes a space has full access to it. Workspace owners have | |
| 149 | + | full access to open and team spaces. | |
| 150 | + | ||
| 151 | + | A space's **Settings** (the gear beside it) change its name, address, who it's | |
| 152 | + | for, the base role, its members and their roles, how agents work in it, and | |
| 153 | + | the projects it's about. **Editors can share**, off by default, lets people | |
| 154 | + | who can edit what's in the space share it too, up to **Can edit**. Only | |
| 155 | + | people with full access give full access, change general access, or change | |
| 156 | + | someone else's full access. **Archive this space** takes it out of the | |
| 157 | + | sidebar and search; what's in it is kept. | |
| 158 | + | ||
| 159 | + | ## Docs | |
| 160 | + | ||
| 161 | + | Make a doc, give it a title, and press **Enter** to start writing. Type `/` | |
| 162 | + | anywhere for the block menu. | |
| 163 | + | ||
| 164 | + | | Block | How to add it | In Markdown | | |
| 165 | + | | --- | --- | --- | | |
| 166 | + | | Text, Heading 1–3 | `/text`, `/h1`, or type `#`, `##`, `###` and a space | `#`, `##`, `###` | | |
| 167 | + | | Bulleted, numbered and to-do lists | `/bullet`, `/numbered`, `/todo`, or type `-`, `1.`, `[]` | `-`, `1.`, `- [ ]` | | |
| 168 | + | | Toggle | `/toggle` | `<details>` | | |
| 169 | + | | Quote | `/quote`, or type `>` | `>` | | |
| 170 | + | | Callout (info, warning, success) | `/callout`, `/warning`, `/tip` | `> [!NOTE]`, `> [!WARNING]`, `> [!TIP]` | | |
| 171 | + | | Code, with syntax highlighting | `/code`, or type ` ``` ` and a language | fenced code | | |
| 172 | + | | Table | `/table` | GitHub tables | | |
| 173 | + | | Image, video, audio, file | `/image`, `/video`, `/audio`, `/file` | `![]()`, links | | |
| 174 | + | | Diagram | `/diagram` or `/mermaid` | ` ```mermaid ` | | |
| 175 | + | | Math | `/math` or `/latex` | `$$ … $$` | | |
| 176 | + | | Embed from g1t | `/embed`, then the address of an issue, pull request, channel, project or artifact | a link | | |
| 177 | + | | Date | `/date` | the date | | |
| 178 | + | | Cite code | `/cite`: a repository, a path, and what there the doc describes | a link to the file | | |
| 179 | + | ||
| 180 | + | - **`@`** mentions a person or an agent. **`[[`** links to another artifact | |
| 181 | + | by title; it lists yours under **Linked from**. | |
| 182 | + | - **Add icon** above the title gives the doc an emoji. | |
| 183 | + | - Images and files are served from `g1tusercontent.com`, never from `g1t.sh`, | |
| 184 | + | up to 25 MB each. | |
| 185 | + | ||
| 186 | + | Docs are live: everyone on one sees each other's changes and cursors, and the | |
| 187 | + | faces at the top are who's there now, agents included. When your connection | |
| 188 | + | drops, the header says **Offline, changes will sync** and sends your changes | |
| 189 | + | when you're back. | |
| 190 | + | ||
| 191 | + | ### Comments | |
| 192 | + | ||
| 193 | + | Select text and choose **Comment** for a passage, or write in **Discussion** | |
| 194 | + | at the bottom for the whole doc. The comments button at the top shows them | |
| 195 | + | beside the text. `@`-mention someone in a comment to tell them; they're told | |
| 196 | + | only if they can open the doc. | |
| 197 | + | ||
| 198 | + | ### Docs that cite code | |
| 199 | + | ||
| 200 | + | When a pull request that changes code a doc cites is merged, or a commit is | |
| 201 | + | pushed to the default branch, the doc is marked **possibly out of date**: a | |
| 202 | + | banner on it, a dot in the sidebar, and **Possibly out of date** in the | |
| 203 | + | sidebar listing every such doc you can open. Its owner is told. Read what | |
| 204 | + | changed, update it (or ask an agent to), then press **It's current**. | |
| 205 | + | ||
| 206 | + | ## Agents and artifacts | |
| 207 | + | ||
| 208 | + | Agents work for a person, never on their own authority. An agent asked by | |
| 209 | + | you: | |
| 210 | + | ||
| 211 | + | - **finds and reads** only what you can open, narrowed to what everyone in | |
| 212 | + | the conversation can open. In a public channel that's only what the whole | |
| 213 | + | workspace can open. When it reads something not everyone there can open, | |
| 214 | + | it doesn't quote or name it there, and sends you the link directly. | |
| 215 | + | - **suggests** a change where you can comment or edit. The blocks it would | |
| 216 | + | replace are struck through in place, beside a card with what it would | |
| 217 | + | write. **Accept**, **Reject** or **Accept all**. | |
| 218 | + | - **edits directly** only where you can edit and **Agents may** (or the | |
| 219 | + | space) says **Edit directly**. | |
| 220 | + | - **makes** a doc for you: you own it, it's marked as made by the agent, and | |
| 221 | + | the agent can keep editing it. | |
| 222 | + | - **shares** with people already in the conversation, view or comment only, | |
| 223 | + | when you have full access. Anything wider is yours to do from **Share**. | |
| 224 | + | ||
| 225 | + | Before an agent answers, it recalls the passages of artifacts and projects' | |
| 226 | + | docs closest in meaning to what it was asked, from what everyone in the | |
| 227 | + | conversation can open. See [What agents can do for whom](/guides/agent-access/) | |
| 228 | + | and [Working with g1t](/guides/working-with-g1t/). | |
| 229 | + | ||
| 230 | + | ### Write a thread up | |
| 231 | + | ||
| 232 | + | In chat, **⋯ → Write this up as an artifact** on a message or an open thread | |
| 233 | + | asks an agent for a doc about the thread: | |
| 234 | + | ||
| 235 | + | | Field | What it is | | |
| 236 | + | | --- | --- | | |
| 237 | + | | **Where** | **Shared with this conversation** (in a DM or a private channel: your Private, shared with its people), **Private (just me)**, or a space you can add to. In a public channel it starts on the General space. | | |
| 238 | + | | **Title** | Optional. | | |
| 239 | + | | **Written by** | @g1t, or another agent in the conversation. | | |
| 240 | + | ||
| 241 | + | The ask is posted in the thread, as you, with the thread's link. The agent | |
| 242 | + | writes what was decided, why, and what's next, links the thread as its | |
| 243 | + | source (the doc shows **From a conversation**), and replies with the link. | |
| 244 | + | ||
| 245 | + | ### Links in chat | |
| 246 | + | ||
| 247 | + | A link to an artifact in a message shows a card with its title, where it is | |
| 248 | + | and when it was last edited, to each person who can open it. Anyone who | |
| 249 | + | can't sees "An artifact you don't have access to", with no title. Seeing the | |
| 250 | + | card doesn't count as opening a link-shared artifact. | |
| 251 | + | ||
| 252 | + | ## History | |
| 253 | + | ||
| 254 | + | **History** at the top of an artifact lists every version: when, who (people | |
| 255 | + | and agents), and what kind of change. Choose one to see what changed in it, | |
| 256 | + | line by line. **Restore this version** makes it what it was then, as a new | |
| 257 | + | version, so nothing is lost. Restoring needs edit access. | |
| 258 | + | ||
| 259 | + | ## Templates | |
| 260 | + | ||
| 261 | + | **Templates** in the sidebar lists g1t's and your workspace's, by kind. | |
| 262 | + | Choose where a new one goes (Private, or a space you can add to), then **Use | |
| 263 | + | template**. | |
| 264 | + | ||
| 265 | + | | Template | For | | |
| 266 | + | | --- | --- | | |
| 267 | + | | **Meeting notes** | Attendees, agenda, decisions, action items. | | |
| 268 | + | | **Spec / RFC** | Problem, goals and non-goals, design, alternatives, rollout, open questions. | | |
| 269 | + | | **Decision record** | Context, the decision, options compared, consequences. | | |
| 270 | + | | **Runbook** | Symptoms, checks, the fix, when to escalate. | | |
| 271 | + | | **Onboarding** | A new teammate's first day and week, people to know, links. | | |
| 272 | + | | **Project brief** | Why, what done looks like, scope, team, milestones, risks. | | |
| 273 | + | | **Postmortem** | Severity, timeline, root cause, what went well and badly, action items. | | |
| 274 | + | | **Weekly update** | Shipped, in progress, next, blocked. | | |
| 275 | + | ||
| 276 | + | **⋯ → Save as template** saves any artifact as your workspace's. Everyone in | |
| 277 | + | the workspace can use it, so the dialog warns you when not everyone can open | |
| 278 | + | the artifact itself. Whoever saved a template, or an owner, can delete it. | |
| 279 | + | ||
| 280 | + | ## Trash | |
| 281 | + | ||
| 282 | + | **⋯ → Move to trash** puts an artifact, and everything inside it, in the | |
| 283 | + | **Trash**. Anyone who can edit it can restore it from there, with what was | |
| 284 | + | inside. After 30 days in the trash it's deleted for good. Deleting it sooner | |
| 285 | + | needs full access. | |
| 286 | + | ||
| 287 | + | ## Projects' docs | |
| 288 | + | ||
| 289 | + | A repository's own docs (its `docs/` folder and its README) can sit in the | |
| 290 | + | sidebar, read-only, so one search covers them and your artifacts. | |
| 291 | + | ||
| 292 | + | <Steps> | |
| 293 | + | ||
| 294 | + | 1. Press **+** beside **Projects' docs** in the sidebar. | |
| 295 | + | 2. Choose a repository you can read. Its README and every Markdown file under | |
| 296 | + | `docs/` on the default branch appear, in their folders. | |
| 297 | + | ||
| 298 | + | </Steps> | |
| 299 | + | ||
| 300 | + | They follow the default branch and change through pull requests: **Edit in | |
| 301 | + | Code** opens the file. Each person sees only the repositories they can read. | |
| 302 | + | ||
| 303 | + | ## Export | |
| 304 | + | ||
| 305 | + | **⋯ → Export Markdown** downloads a doc as a `.md` file. Diagrams export as | |
| 306 | + | ` ```mermaid ` blocks, math as `$$` blocks, callouts as GitHub alerts, and | |
| 307 | + | embeds and links as links. | |
| 308 | + | ||
| 309 | + | From your own agent or code, the `artifact` MCP tool and the REST API read, | |
| 310 | + | make and change artifacts as you. See | |
| 311 | + | [Bring your own agent](/guides/bring-your-own-agent/#artifacts). | |
| 312 | + | ||
| 313 | + | ## Coming soon <Soon /> | |
| 314 | + | ||
| 315 | + | - **Slides**, with a presenter view. | |
| 316 | + | - **Design**: screens, layouts and diagrams on a canvas. | |
| 317 | + | - **Dashboards** of your workspace's numbers, each viewer seeing what they can. | |
| 318 | + | - **Links for people outside the workspace**, view only, off unless a | |
| 319 | + | workspace turns them on. | |
| 320 | + | ||
| 321 | + | ## Pricing | |
| 322 | + | ||
| 323 | + | Artifacts are included on every plan, with no seats. Files in docs count | |
| 324 | + | toward storage. Agents' work on artifacts is charged to the agent, like any | |
| 325 | + | of its work; see [what an agent costs](/guides/agents/#what-an-agent-costs). |
| 208 | 208 | ||
| 209 | 209 | - **Copy link to thread**: a link that opens the conversation with the | |
| 210 | 210 | thread beside it, to paste anywhere in g1t. | |
| 211 | − | - **Write this up in Docs**: choose a Docs space you can write in, a title | |
| 211 | + | - **Write this up as an artifact**: choose where the doc goes (shared | |
| 212 | + | with this conversation, your Private, or a space you can add to), a title | |
| 212 | 213 | if you have one, and the agent that writes it (@g1t unless you pick | |
| 213 | 214 | another agent in the conversation). g1t posts the ask in the thread, as | |
| 214 | 215 | you, where everyone can see it, with the thread's link: *@g1t write this | |
| 215 | − | thread up as a Docs page in Engineering: what was decided, why, and | |
| 216 | − | what's next. Link this thread as the source: …*. The agent answers it | |
| 217 | − | like any mention, starts a session if it needs one, and replies with a | |
| 218 | − | link to the page. See [Docs](/guides/docs/#write-a-thread-up). | |
| 216 | + | thread up as an artifact (a doc) in the Engineering space titled "Launch | |
| 217 | + | plan". Link this thread as the source: …*. The agent answers it like any | |
| 218 | + | mention, starts a session if it needs one, and replies with a link to the | |
| 219 | + | doc. See [Artifacts](/guides/artifacts/#write-a-thread-up). | |
| 219 | 220 | ||
| 220 | 221 | ## Mentions | |
| 221 | 222 |
| 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). |
| 608 | 608 | ||
| 609 | 609 | | | What it does | | |
| 610 | 610 | | --- | --- | | |
| 611 | − | | **The tabs along the bottom** | **Home**, **Code** (or **Docs**, if you don't use Code in this workspace), **Chat**, **Agents** and **Inbox**, each with what is unread. They step aside while the keyboard is up and inside a conversation. | | |
| 611 | + | | **The tabs along the bottom** | **Home**, **Code** (or **Artifacts**, if you don't use Code in this workspace), **Chat**, **Agents** and **Inbox**, each with what is unread. They step aside while the keyboard is up and inside a conversation. | | |
| 612 | 612 | | **The menu button** (☰), beside the workspace's icon at the top left | Opens the sidebar of the mode you are in from the left: the same lists and links as on a computer. Inside a project, that is the project's own list; on a workspace or settings page, the Workspace or account sidebar. Tap outside it, or open a page, and it closes. | | |
| 613 | 613 | | **The tab you are already on** | Tap it again to open that mode's sidebar too. | | |
| 614 | − | | **The workspace's icon** at the top left | Everything else, from the bottom: **Docs** first, then the workspace's **Overview**, **People**, **Teams**, **Usage and billing**, **Integrations** and **Settings**; switching workspaces; help; and your status, profile, settings and signing out. | | |
| 614 | + | | **The workspace's icon** at the top left | Everything else, from the bottom: **Artifacts** first, then the workspace's **Overview**, **People**, **Teams**, **Usage and billing**, **Integrations** and **Settings**; switching workspaces; help; and your status, profile, settings and signing out. | | |
| 615 | 615 | ||
| 616 | 616 | Inside a [project](/guides/projects/), its pages (**Overview**, **Code**, | |
| 617 | 617 | **Issues**, **Pull requests**, **Agents**, **Workflows**, **Deployments**, |
| 24 | 24 | | --- | --- | | |
| 25 | 25 | | **[Chat](/guides/chat/)** | Channels, direct messages and threads, live. People and agents are members alike. | | |
| 26 | 26 | | **[Agents](/guides/agents/)** | Your workspace's colleagues: who they are, what they answer for, what they cost. `@g1t` orchestrates. | | |
| 27 | − | | **[Docs](/guides/docs/)** | Specs, runbooks and decisions, written together live by people and agents, and searchable by project. | | |
| 27 | + | | **[Artifacts](/guides/artifacts/)** | Docs now, and slides, designs and dashboards soon, made together live by people and agents. Private until you share them, or kept in spaces. | | |
| 28 | 28 | | **[Code](/concepts/overview/)** | Repositories, issues, pull requests, checks, the merge queue and deployments. | | |
| 29 | 29 | ||
| 30 | 30 | <CardGrid> |
| 796 | 796 | | [`trash`](/reference/api/artifacts/trash-workspace-artifact/) | Move it, and what is under it, to the trash; deleted for good after 30 days. | `workspace`, `artifact_id` | `artifacts:write` | | |
| 797 | 797 | | [`restore`](/reference/api/artifacts/restore-workspace-artifact/) | Bring it back from the trash. | `workspace`, `artifact_id` | `artifacts:write` | | |
| 798 | 798 | | [`restore_version`](/reference/api/artifacts/restore-workspace-artifact-version/) | Make an earlier version its content again, as a new version. | `workspace`, `artifact_id`, `version_id` | `artifacts:write` | | |
| 799 | − | | [`share`](/reference/api/artifacts/set-workspace-artifact-access/) | Share it with a `username`, `team` or `agent` at a `role` (`view`, `comment`, `edit`, `manage`, or `none` to take access away); set `general_access` and `general_role`, `inherit` or `agent_mode`. Takes full access to it. | `workspace`, `artifact_id` | `artifacts:admin` | | |
| 799 | + | | [`share`](/reference/api/artifacts/set-workspace-artifact-access/) | Share it with a `username`, `team` or `agent` at a `role` (`view`, `comment`, `edit`, `manage`, or `none` to take access away); set `general_access` and `general_role`, `inherit` or `agent_mode`. Takes full access to it; where its space lets editors share, edit access shares up to `edit`. | `workspace`, `artifact_id` | `artifacts:admin` | | |
| 800 | 800 | | [`purge`](/reference/api/artifacts/purge-workspace-artifact/) | Delete one in the trash for good. Takes full access to it. | `workspace`, `artifact_id` | `artifacts:admin` | | |
| 801 | 801 | ||
| 802 | 802 | ## What g1t can use |
| 182 | 182 | }, | |
| 183 | 183 | { | |
| 184 | 184 | icon: <BookOpen size={18} />, | |
| 185 | − | name: "Docs", | |
| 186 | − | about: "Specs, runbooks and decisions, written together. Agents read them and keep them current.", | |
| 185 | + | name: "Artifacts", | |
| 186 | + | about: "Docs now, and slides, designs and dashboards next, made together live. Agents read them and keep them current.", | |
| 187 | 187 | soon: true, | |
| 188 | − | to: `${DOCS}/guides/docs/`, | |
| 188 | + | to: `${DOCS}/guides/artifacts/`, | |
| 189 | 189 | }, | |
| 190 | 190 | ]; | |
| 191 | 191 | ||
| ⋯ | |||
| 788 | 788 | </div> | |
| 789 | 789 | <div className="rounded-3xl bg-surface p-8 ring-1 ring-line"> | |
| 790 | 790 | <div className="flex items-center gap-3"> | |
| 791 | − | <Eyebrow>Docs</Eyebrow> | |
| 791 | + | <Eyebrow>Artifacts</Eyebrow> | |
| 792 | 792 | <Soon /> | |
| 793 | 793 | </div> | |
| 794 | 794 | <h3 className="mt-3 text-2xl font-semibold tracking-tight text-balance">A knowledge base that keeps itself true</h3> | |
| 795 | 795 | <p className="mt-3 text-sm leading-6 text-muted"> | |
| 796 | − | Spaces of pages, edited together live, with history, comments and backlinks. Agents read them before they | |
| 797 | − | answer and suggest edits you accept like a review. When a merged change touches something a page cites, the | |
| 798 | − | page is flagged and its owner, person or agent, drafts the update. | |
| 796 | + | Docs, private until you share them or kept in spaces, edited together live, with history, comments and | |
| 797 | + | backlinks. Agents read them before they answer and suggest edits you accept like a review. When a merged | |
| 798 | + | change touches something a doc cites, the doc is flagged and its owner, person or agent, drafts the update. | |
| 799 | 799 | </p> | |
| 800 | − | <More to={`${DOCS}/guides/docs/`}>What Docs will do</More> | |
| 800 | + | <More to={`${DOCS}/guides/artifacts/`}>What Artifacts will do</More> | |
| 801 | 801 | </div> | |
| 802 | 802 | </section> | |
| 803 | 803 | ||
| 292 | 292 | Every one of these is also on the MCP server. Its tools are resources, | |
| 293 | 293 | each with an `action`: `search`, `repository`, `issue`, `pull_request`, | |
| 294 | 294 | `agent`, `plan`, `memory`, `workflow`, `secret`, `webhook`, `access`, | |
| 295 | − | `workspace`, `notifications` and `account`. Call `tools/call` with the tool's name and | |
| 295 | + | `workspace`, `notifications`, `account` and `artifact`. Call `tools/call` with the tool's name and | |
| 296 | 296 | `arguments` holding `action` and its inputs, such as | |
| 297 | 297 | `{"name": "issue", "arguments": {"action": "get", "repo": "acme/web", "number": 12}}`. | |
| 298 | 298 | The flow above is: `issue` `get`, `memory` `recall`, `pull_request` | |
| ⋯ | |||
| 308 | 308 | `reason` such as `agent` or `review_requested`), `done`, `subscribe`, | |
| 309 | 309 | `watch` and more; g1t's own token cannot use it. `search` runs `code`, | |
| 310 | 310 | `notifications` runs `list` and `account` runs `whoami` when `action` is | |
| 311 | − | left out. A call missing a required field says | |
| 311 | + | left out. `artifact` reads and writes a workspace's artifacts (its docs; | |
| 312 | + | slides, designs and dashboards later), never a workflow run's build | |
| 313 | + | artifacts, which are `workflow`'s: `list`, `search`, `get` (metadata), | |
| 314 | + | `read` (a doc's Markdown and block ids), `create`, `update`, `edit` | |
| 315 | + | (`markdown` and a `target`), `trash`, `restore`, `versions`, | |
| 316 | + | `restore_version`, `access`, `share`, `purge`, `templates`, `spaces`; | |
| 317 | + | name one by `artifact_id` (its `fol_…` id or link). It acts as the token's | |
| 318 | + | person, so it opens only what they can open; scopes `artifacts:read`, | |
| 319 | + | `artifacts:write` and `artifacts:admin`. Guide: | |
| 320 | + | https://docs.g1t.sh/guides/artifacts/. A call missing a required field says | |
| 312 | 321 | which, such as "issue.get needs number.". The earlier one-tool-per-operation | |
| 313 | 322 | names (`get_issue`, `create_pull_request`, …) still answer for now but are | |
| 314 | 323 | no longer listed. Every tool and action, with its required fields and | |
| ⋯ | |||
| 323 | 332 | ||
| 324 | 333 | Every access token and OAuth sign-in has scopes, `resource:level`: | |
| 325 | 334 | `repo`, `code`, `issues`, `pull_requests`, `workflows`, `checks`, `deployments`, `memory`, | |
| 326 | − | `account`, `notifications`, `access`, `webhooks`, `secrets`, `runners`, `models` (read, write or admin | |
| 335 | + | `account`, `notifications`, `access`, `webhooks`, `secrets`, `runners`, `models`, `artifacts` (read, write or admin | |
| 327 | 336 | as each has them), `agents:run`, `workspace:read` and `workspace:admin`. A higher | |
| 328 | 337 | level includes the lower. A token may expire. It reaches every workspace | |
| 329 | 338 | and repository its owner can (a workspace's token, that workspace only); | |
| ⋯ | |||
| 738 | 747 | - [Outcomes and plans](https://docs.g1t.sh/guides/outcomes/) | |
| 739 | 748 | - [Talking to agents](https://docs.g1t.sh/guides/talking-to-agents/) | |
| 740 | 749 | - [Bring your own agent](https://docs.g1t.sh/guides/bring-your-own-agent/) | |
| 750 | + | - [Artifacts](https://docs.g1t.sh/guides/artifacts/) | |
| 741 | 751 | - [The merge queue](https://docs.g1t.sh/guides/merge-queue/) | |
| 742 | 752 | - [Sessions and why-blame](https://docs.g1t.sh/guides/why-blame/) | |
| 743 | 753 | - [Forks and branches](https://docs.g1t.sh/concepts/forks/) | |