| 1 | --- |
| 2 | title: Artifacts |
| 3 | description: Make docs with your workspace, live. Keep them private, share them with people and teams, put them in spaces, or open them to the workspace. Comments, suggestions, 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. Your team edits them live, and the coding |
| 12 | agents you connect read and change them as you. Each one is private until |
| 13 | you share it. |
| 14 | |
| 15 | Open **Artifacts** in the rail on the left, or go to |
| 16 | `g1t.sh/<workspace>/-/artifacts`. On a phone, it's under **More** in the bar |
| 17 | at the bottom. Artifacts is open to every member of a workspace, on every |
| 18 | plan. |
| 19 | |
| 20 | ## How it fits together |
| 21 | |
| 22 | | | | |
| 23 | | --- | --- | |
| 24 | | **Artifacts** | A doc today. Each has one owner, the person who made it, and an address that ends in its id. | |
| 25 | | **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. | |
| 26 | | **Sharing** | Share an artifact with people and teams, each with a role, or open it to everyone in the workspace or to anyone in it with the link. | |
| 27 | | **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. | |
| 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 | On a phone, Home shows the list, and the sidebar's sections follow it. |
| 46 | - Each row shows the kind, who can open it (a lock when only you can, a globe |
| 47 | when the workspace can, a link when anyone in it with the link can, or how |
| 48 | many people it's shared with), where it is, and when it was last edited and |
| 49 | by whom. Its **⋯** menu has **Open in new tab**, **Add to Favorites**, |
| 50 | **Share…**, **Rename**, **Duplicate**, **Move to…**, **Copy link**, |
| 51 | **Export Markdown**, **Save as template** and **Move to trash**, as far as |
| 52 | your role allows. |
| 53 | |
| 54 | **Make something new** at the top starts one. **Docs** makes a doc in your |
| 55 | Private at once; its arrow starts one **From a template…** or **In a space…**. |
| 56 | Slides, Design and Dashboards say **Coming soon**. |
| 57 | |
| 58 | ## The sidebar |
| 59 | |
| 60 | | Section | What's there | |
| 61 | | --- | --- | |
| 62 | | **Search**, **Home**, **Templates** | As they say. **+** at the top makes a new artifact. | |
| 63 | | **Favorites** | What you starred. | |
| 64 | | **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. | |
| 65 | | **Private** | Your artifacts in no space. Only you see this section. | |
| 66 | | **Shared** | The highest artifact of each tree someone shared with you. | |
| 67 | | **Possibly out of date** | Docs whose cited code changed. Shown when there are any. | |
| 68 | | **Projects' docs** | Repositories' `docs/` folders, read-only. | |
| 69 | | **Trash** | What was moved to the trash, with how many. | |
| 70 | |
| 71 | The sidebar follows every change at once: an artifact you move to the trash |
| 72 | leaves it, one you restore comes back, and the count beside **Trash** moves |
| 73 | with them, without reloading the page. |
| 74 | |
| 75 | Drag a row onto a doc to put it inside, or onto the top edge of a row to put |
| 76 | it before it. Only a doc can hold other artifacts: a doc with others inside |
| 77 | is the folder. |
| 78 | |
| 79 | ## Sharing |
| 80 | |
| 81 | **Share** at the top of an artifact (or **⋯ → Share…**) opens who has access. |
| 82 | |
| 83 | <Steps> |
| 84 | |
| 85 | 1. Choose people or teams in the workspace, and a role. |
| 86 | 2. Add a message if you want one, then press **Invite**. People you add get |
| 87 | a notification with the link. |
| 88 | |
| 89 | </Steps> |
| 90 | |
| 91 | | Role | Can | |
| 92 | | --- | --- | |
| 93 | | **Can view** | Read it, its history and its comments. | |
| 94 | | **Can comment** | Read, and comment on passages or the whole doc. | |
| 95 | | **Can edit** | Write and organize it, accept or reject suggestions, restore versions, and move it to the trash. | |
| 96 | | **Full access** | Edit, share it, change its general access, and delete it from the trash for good. | |
| 97 | |
| 98 | **Who has access** lists the owner, everyone it's shared with directly (change |
| 99 | their role, or **Remove access**), and anyone who has access from a doc it's |
| 100 | inside, with a link to where that's set. |
| 101 | |
| 102 | **General access**: |
| 103 | |
| 104 | - **Everyone in the space**, or **Only people invited**, for an artifact in a |
| 105 | space or inside a doc. Only people invited stops access there: the space's |
| 106 | members, or whoever can open the doc above, can't open it unless invited. |
| 107 | - **Restricted**, **Everyone in the workspace**, or **Anyone in the workspace |
| 108 | with the link**, each with a role (never full access). This is set on an |
| 109 | artifact at the top of its tree, or on one that's only for people invited; |
| 110 | what's inside follows it. |
| 111 | - **Anyone in the workspace with the link** keeps it out of lists and search |
| 112 | until a member opens the link. After that, it's under their |
| 113 | **Shared with you**. |
| 114 | - Links for people outside the workspace aren't available. |
| 115 | |
| 116 | Only people with full access share an artifact, unless its space lets editors |
| 117 | share (see [Spaces](#spaces)). Anyone else sees the dialog read-only. |
| 118 | |
| 119 | ### Asking for access |
| 120 | |
| 121 | An artifact you can't open shows **You need access**. **Ask for access** |
| 122 | tells its owner and the people with full access (up to 20) in their notifications, |
| 123 | with your message if you add one. You can ask once a day for each artifact. |
| 124 | |
| 125 | ## Private |
| 126 | |
| 127 | An artifact is private when only its owner can open it: it's in your Private |
| 128 | section, it isn't shared with anyone, and its general access is |
| 129 | **Restricted**. It shows a lock with "Only you can see this". |
| 130 | |
| 131 | Workspace owners can't open someone's private artifacts, or artifacts in a |
| 132 | members-only space they aren't in. |
| 133 | |
| 134 | **Duplicate** makes a copy that is yours and private, next to the original |
| 135 | when you can add there, and in your Private otherwise. A copy is never shared |
| 136 | more widely than you chose. |
| 137 | |
| 138 | ## Spaces |
| 139 | |
| 140 | Every workspace starts with a **General** space for what everyone should |
| 141 | know. Make more from **+** beside **Spaces** in the sidebar, then **New |
| 142 | space**. No space has to exist: a workspace can have none at all, and |
| 143 | artifacts in no space live in their owners' **Private**. |
| 144 | |
| 145 | | Who it's for | Who can open it | |
| 146 | | --- | --- | |
| 147 | | **Open** (everyone in the workspace) | Every member, with the space's base role. Join it to see it in your sidebar. | |
| 148 | | **Team** | Members of that team, with the space's base role. | |
| 149 | | **Members only** | The people and teams listed in the space, and nobody else. | |
| 150 | |
| 151 | **Browse spaces** lists every space you can open; **Join** or **Leave** an |
| 152 | open one. Whoever makes a space has full access to it. Workspace owners have |
| 153 | full access to open and team spaces. |
| 154 | |
| 155 | A space's **Settings** (the gear beside it) change its name, address, who it's |
| 156 | for, the base role, its members and their roles, and the projects it's about. **Editors can share**, off by default, lets people |
| 157 | who can edit what's in the space share it too, up to **Can edit**. Only |
| 158 | people with full access give full access, change general access, or change |
| 159 | someone else's full access. |
| 160 | |
| 161 | ### Archiving and deleting a space |
| 162 | |
| 163 | Both are at the bottom of a space's **Settings**, for people with full access |
| 164 | to the space; workspace owners can also delete any space they can open. |
| 165 | |
| 166 | | | What happens | |
| 167 | | --- | --- | |
| 168 | | **Archive space** | It leaves the sidebar and search. Everything in it is kept. **Browse spaces** lists it under **Archived**, where **Restore** brings it back as it was, or **Delete** deletes it. | |
| 169 | | **Delete space** | Everything in it goes to the trash together, where anyone who could edit an artifact restores it as usual for 30 days. The space itself, its members and settings are gone for good. | |
| 170 | |
| 171 | Any space can be archived or deleted, **General** included. A workspace whose |
| 172 | General space is deleted has no General space; none takes its place, and |
| 173 | new spaces are made as usual. An artifact restored from a deleted space |
| 174 | comes back at the top of **General** when there is one you can add to, else |
| 175 | in its owner's **Private**. |
| 176 | |
| 177 | ## Docs |
| 178 | |
| 179 | Make a doc, give it a title, and press **Enter** to start writing. Type `/` |
| 180 | anywhere for the block menu. |
| 181 | |
| 182 | | Block | How to add it | In Markdown | |
| 183 | | --- | --- | --- | |
| 184 | | Text, Heading 1–3 | `/text`, `/h1`, or type `#`, `##`, `###` and a space | `#`, `##`, `###` | |
| 185 | | Bulleted, numbered and to-do lists | `/bullet`, `/numbered`, `/todo`, or type `-`, `1.`, `[]` | `-`, `1.`, `- [ ]` | |
| 186 | | Toggle | `/toggle` | `<details>` | |
| 187 | | Quote | `/quote`, or type `>` | `>` | |
| 188 | | Callout (info, warning, success) | `/callout`, `/warning`, `/tip` | `> [!NOTE]`, `> [!WARNING]`, `> [!TIP]` | |
| 189 | | Code, with syntax highlighting | `/code`, or type ` ``` ` and a language | fenced code | |
| 190 | | Table | `/table` | GitHub tables | |
| 191 | | Image, video, audio, file | `/image`, `/video`, `/audio`, `/file` | `![]()`, links | |
| 192 | | Diagram | `/diagram` or `/mermaid` | ` ```mermaid ` | |
| 193 | | Math | `/math` or `/latex` | `$$ … $$` | |
| 194 | | Embed from g1t | `/embed`, then the address of an issue, pull request, channel, project or artifact | a link | |
| 195 | | Date | `/date` | the date | |
| 196 | | Cite code | `/cite`: a repository, a path, and what there the doc describes | a link to the file | |
| 197 | |
| 198 | - **`@`** mentions a person. **`[[`** links to another artifact |
| 199 | by title; it lists yours under **Linked from**. |
| 200 | - **Add icon** above the title gives the doc an emoji. |
| 201 | - Images and files are served from `g1tusercontent.com`, never from `g1t.sh`, |
| 202 | up to 25 MB each. A workspace on the free plan keeps up to 1 GB of them, |
| 203 | across all its docs and artifacts; past it, a new file is refused and the |
| 204 | upload says so. Files already there stay. On the g1t plan there is no |
| 205 | such cap. |
| 206 | |
| 207 | Docs are live: everyone on one sees each other's changes and cursors, and the |
| 208 | faces at the top are who's there now. When your connection |
| 209 | drops, the header says **Offline, changes will sync** and sends your changes |
| 210 | when you're back. |
| 211 | |
| 212 | ### How a doc opens |
| 213 | |
| 214 | A doc's text is in the page itself, so it reads from the first moment, before |
| 215 | any script runs. The page then connects to the doc's live room and loads the |
| 216 | editor together, and the editor opens on the document the page carried: you |
| 217 | can read and type at once, and the room only sends what changed since the |
| 218 | doc was last saved. Anything you type before the room answers is kept and |
| 219 | sent then, so nothing is lost. A doc saved before g1t kept documents this way |
| 220 | is asked of its room the first time it opens, and kept from then on, so it |
| 221 | opens as fast as any other from the second time. The dot in the header says |
| 222 | where things stand: |
| 223 | |
| 224 | | Dot | Meaning | |
| 225 | | --- | --- | |
| 226 | | Faint, pulsing | Connecting to the live room. You can already read and edit. | |
| 227 | | Green | Live: everyone's changes show as they happen. | |
| 228 | | **Offline, changes will sync** | The connection dropped; your changes are kept and sent when it's back. | |
| 229 | |
| 230 | A doc that was never saved since this started, or one far larger than usual, |
| 231 | waits for the room's copy before the editor opens, as every doc once did. |
| 232 | |
| 233 | ### Comments |
| 234 | |
| 235 | Select text and choose **Comment** for a passage, or write in **Discussion** |
| 236 | at the bottom for the whole doc. The comments button at the top shows them |
| 237 | beside the text. `@`-mention someone in a comment to tell them; they're told |
| 238 | only if they can open the doc. |
| 239 | |
| 240 | ### Docs that cite code |
| 241 | |
| 242 | When a pull request that changes code a doc cites is merged, or a commit is |
| 243 | pushed to the default branch, the doc is marked **possibly out of date**: a |
| 244 | banner on it, a dot in the sidebar, and **Possibly out of date** in the |
| 245 | sidebar listing every such doc you can open. Its owner is told. Read what |
| 246 | changed, update it, then press **It's current**. |
| 247 | |
| 248 | ## Suggestions |
| 249 | |
| 250 | A coding agent you connect works on artifacts as you, through the |
| 251 | `artifact` MCP tool, so it opens only what you can open. Where you can |
| 252 | edit, its change is made as a new version. Where you can only comment, or |
| 253 | when it asks only to suggest, the change is filed as a suggestion: the |
| 254 | blocks it would replace are struck through in place, beside a card with |
| 255 | what it would write. Anyone who can edit the doc chooses **Accept**, |
| 256 | **Reject** or **Accept all**. See |
| 257 | [Connect a coding agent](/guides/bring-your-own-agent/#artifacts). |
| 258 | |
| 259 | ## Links in chat |
| 260 | |
| 261 | A link to an artifact in a message shows a card with its title, where it is |
| 262 | and when it was last edited, to each person who can open it. Anyone who |
| 263 | can't sees "An artifact you don't have access to", with no title. Seeing the |
| 264 | card doesn't count as opening a link-shared artifact. |
| 265 | |
| 266 | ## History |
| 267 | |
| 268 | **History** at the top of an artifact lists every version: when, who, and what |
| 269 | kind of change. Choose one to see what changed in it, |
| 270 | line by line. **Restore this version** makes it what it was then, as a new |
| 271 | version, so nothing is lost. Restoring needs edit access. |
| 272 | |
| 273 | ## Templates |
| 274 | |
| 275 | **Templates** in the sidebar lists g1t's and your workspace's, by kind. |
| 276 | Choose where a new one goes (Private, or a space you can add to), then **Use |
| 277 | template**. |
| 278 | |
| 279 | | Template | For | |
| 280 | | --- | --- | |
| 281 | | **Meeting notes** | Attendees, agenda, decisions, action items. | |
| 282 | | **Spec / RFC** | Problem, goals and non-goals, design, alternatives, rollout, open questions. | |
| 283 | | **Decision record** | Context, the decision, options compared, consequences. | |
| 284 | | **Runbook** | Symptoms, checks, the fix, when to escalate. | |
| 285 | | **Onboarding** | A new teammate's first day and week, people to know, links. | |
| 286 | | **Project brief** | Why, what done looks like, scope, team, milestones, risks. | |
| 287 | | **Postmortem** | Severity, timeline, root cause, what went well and badly, action items. | |
| 288 | | **Weekly update** | Shipped, in progress, next, blocked. | |
| 289 | |
| 290 | **⋯ → Save as template** saves any artifact as your workspace's. Everyone in |
| 291 | the workspace can use it, so the dialog warns you when not everyone can open |
| 292 | the artifact itself. Whoever saved a template, or an owner, can delete it. |
| 293 | |
| 294 | ## Trash |
| 295 | |
| 296 | **⋯ → Move to trash** puts an artifact, and everything inside it, in the |
| 297 | **Trash**; it leaves the sidebar at once. Anyone who can edit it can restore |
| 298 | it from there, with what was inside. After 30 days in the trash it's deleted |
| 299 | for good. Deleting it sooner needs full access: **Delete** beside one |
| 300 | artifact, or **Empty trash** at the top of the page. |
| 301 | |
| 302 | **Empty trash** deletes for good every artifact in the trash you have full |
| 303 | access to, with its history, comments and everything inside it. Artifacts |
| 304 | you can only edit stay; the page says how many go and how many stay before |
| 305 | you confirm. Emptying the trash can't be undone. |
| 306 | |
| 307 | ## Projects' docs |
| 308 | |
| 309 | A repository's own docs (its `docs/` folder and its README) can sit in the |
| 310 | sidebar, read-only, so one search covers them and your artifacts. |
| 311 | |
| 312 | <Steps> |
| 313 | |
| 314 | 1. Press **+** beside **Projects' docs** in the sidebar. |
| 315 | 2. Choose a repository you can read. Its README and every Markdown file under |
| 316 | `docs/` on the default branch appear, in their folders. |
| 317 | |
| 318 | </Steps> |
| 319 | |
| 320 | They follow the default branch and change through pull requests: **Edit in |
| 321 | Code** opens the file. Each person sees only the repositories they can read. |
| 322 | |
| 323 | ## Export |
| 324 | |
| 325 | **⋯ → Export Markdown** downloads a doc as a `.md` file. Diagrams export as |
| 326 | ` ```mermaid ` blocks, math as `$$` blocks, callouts as GitHub alerts, and |
| 327 | embeds and links as links. |
| 328 | |
| 329 | From your own agent or code, the `artifact` MCP tool and the REST API read, |
| 330 | make and change artifacts as you. See |
| 331 | [Connect a coding agent](/guides/bring-your-own-agent/#artifacts). |
| 332 | |
| 333 | ## Coming soon <Soon /> |
| 334 | |
| 335 | - **Slides**, with a presenter view. |
| 336 | - **Design**: screens, layouts and diagrams on a canvas. |
| 337 | - **Dashboards** of your workspace's numbers, each viewer seeing what they can. |
| 338 | - **Links for people outside the workspace**, view only, off unless a |
| 339 | workspace turns them on. |
| 340 | |
| 341 | ## Pricing |
| 342 | |
| 343 | Artifacts are included on every plan, with no seats. Files in docs count |
| 344 | toward storage. |