| 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). |