| 1 | # Contributing to g1t |
| 2 | |
| 3 | g1t is built the way it asks others to build: issues and pull requests on |
| 4 | [g1t.sh/flagon-io/g1t](https://g1t.sh/flagon-io/g1t), required checks that prove |
| 5 | a change works, and a merge queue that keeps `main` passing. |
| 6 | |
| 7 | ## A change ships with its docs |
| 8 | |
| 9 | Documentation is part of the product, held to the same bar as the code. |
| 10 | A pull request that changes what someone can do, see or call changes the |
| 11 | docs in the same pull request: |
| 12 | |
| 13 | | If you change | Update | |
| 14 | | --- | --- | |
| 15 | | Something a person does on g1t.sh | The guide for it in `apps/docs/src/content/docs/guides/` | |
| 16 | | An API route, a field, or an MCP tool | `apps/api/src/operations.rs` descriptions (they feed the OpenAPI document and the API reference), the example and notes for it in `apps/api/src/reference.json`, `reference/mcp.md`, and any guide that shows the call. Then refresh the docs' copy of the OpenAPI document with `G1T_WRITE_OPENAPI=1 cargo test -p g1t-api openapi`; `cargo test` fails until you do. | |
| 17 | | How agents behave | `guides/working-with-g1t.md`, and `apps/web/public/llms.txt` | |
| 18 | | Settings, limits or prices | The page that names them, and the table it is in | |
| 19 | | A new feature | A section in the guide that owns it, linked from the docs home if it is a new task | |
| 20 | |
| 21 | The style, in short: plain sentences, second person, no marketing words, |
| 22 | sentence-case headings, a numbered list for steps, a table for options, and |
| 23 | every API mention with its exact route or tool name. Examples are copyable |
| 24 | and real. Nothing is documented that the code does not do. |
| 25 | |
| 26 | Check the docs build before you push: |
| 27 | |
| 28 | ```sh |
| 29 | cd apps/docs && npm run build |
| 30 | ``` |
| 31 | |
| 32 | ## Icons |
| 33 | |
| 34 | - **Interface icons come from [Lucide](https://lucide.dev/icons).** In the |
| 35 | apps, import them from `lucide-react`. In the docs, use `@lucide/astro`: |
| 36 | import an icon component, or give `apps/docs/src/components/Card.astro` |
| 37 | and `Aside.astro` a Lucide name such as `icon="git-branch"`. Starlight's |
| 38 | own `<Card>`, `<LinkCard>` and `<Aside>` draw Starlight's icon set, so the |
| 39 | docs import the wrappers in `apps/docs/src/components/` instead. |
| 40 | - **Brand marks come from [Simple Icons](https://simpleicons.org)** |
| 41 | (`simple-icons`), and follow each brand's own usage guidelines. Add the |
| 42 | dependency with the first one you show. |
| 43 | - **The g1t logo and illustrations are our own artwork**, in |
| 44 | `apps/web/app/components/logo.tsx` and `art.tsx`. |
| 45 | - Never hand-copy an icon's SVG paths into a file. If Lucide lacks the |
| 46 | icon you need, pick the closest one that it has. |
| 47 | |
| 48 | ## Interface components |
| 49 | |
| 50 | - **Build the site from the components in `apps/web/app/components/ui`**, |
| 51 | which are [shadcn/ui](https://ui.shadcn.com) components themed with |
| 52 | g1t's tokens: buttons, cards, badges, tables, tabs, separators, |
| 53 | breadcrumbs, menus, dialogs, sheets, tooltips, form controls. |
| 54 | - **If shadcn has a component you need and `ui` doesn't, add it there** |
| 55 | first, themed with the tokens, then use it. Don't rebuild it inline. |
| 56 | - **Change how something looks through the component's variants**, not |
| 57 | with a one-off class string at the call site. A long `className` on a |
| 58 | `div` that draws a card, a pill or a button is a component that should |
| 59 | exist. |
| 60 | - Hover hints use the `Tooltip` component, never `title=`. Native |
| 61 | `<select>`, file inputs, checkboxes and radios use their `ui` |
| 62 | components. |
| 63 | - **Every avatar is `Avatar`** (`ui/avatar.tsx`), and every agent's is |
| 64 | `Avatar` with `agent` set, or `AgentAvatar` (`components/agent-avatar.tsx`), |
| 65 | which wraps it. That draws the agent's bot face (`AgentFace`, |
| 66 | `components/agent-face.tsx`) from its `look` or its `avatar_seed`, puts |
| 67 | the agent marker in its corner and names it "…, agent" to a screen |
| 68 | reader. Never hand-draw an agent's face, a sparkle, a letter on a tile or |
| 69 | the marker at a call site: a place that shows an agent differently is a |
| 70 | bug. |
| 71 | - Look at every page you change, in light and dark, on a desktop and a |
| 72 | phone, before calling it done. |
| 73 | |
| 74 | ## Before you push |
| 75 | |
| 76 | - `cargo test` in the crate or service you changed. |
| 77 | - `npx tsc -b --force` in `apps/web` (the incremental build misses changes |
| 78 | in `packages/contracts`). |
| 79 | - Look at what you changed in a browser. Screenshots catch what type |
| 80 | checks do not. |
| 81 | |
| 82 | ## Checking g1t against GitHub |
| 83 | |
| 84 | g1t runs GitHub Actions workflows as GitHub does. The Conformance |
| 85 | workflow is how that is checked: `.g1t/workflows/conformance.yml` and |
| 86 | `.github/workflows/conformance.yml` are the same file (a test in |
| 87 | `crates/actions` fails when they differ), and each run's |
| 88 | `conformance-report` artifact records what its jobs saw: which `GITHUB_*` |
| 89 | and `RUNNER_*` variables were set and of what kind, every key of the |
| 90 | contexts and the event and its type, how the workspace is laid out, and |
| 91 | the values of outputs, files, caches, artifacts and expressions that |
| 92 | should be the same everywhere. It reads no secrets and runs only by hand. |
| 93 | |
| 94 | 1. Run it on both, at the same commit: **Actions → Conformance → Run |
| 95 | workflow** on GitHub and on g1t.sh. |
| 96 | 2. Download each run's `conformance-report` artifact, and name the two |
| 97 | files `github.json` and `g1t.json`. |
| 98 | 3. Compare them: |
| 99 | |
| 100 | ```sh |
| 101 | node scripts/conformance-diff.mjs github.json g1t.json |
| 102 | ``` |
| 103 | |
| 104 | It lists what GitHub has that g1t lacks or has otherwise, then what only |
| 105 | g1t has, and exits 1 while there are differences. A difference is a bug in |
| 106 | g1t, or belongs in [What g1t can't do yet](https://docs.g1t.sh/about/limitations/). |
| 107 | Add a step and a `CHECK_` value to the workflow for anything new g1t |
| 108 | should match. |
| 109 | |
| 110 | ## Deploying |
| 111 | |
| 112 | Pushes to `main` deploy themselves: `.g1t/workflows/deploy.yml` runs |
| 113 | `scripts/deploy.mjs`, which deploys only the parts that changed, migrations |
| 114 | first. Every deployable part is listed in `deploy/stack.jsonc`; a new service |
| 115 | or app goes there, and in the table on |
| 116 | [How a self-hosted g1t runs](https://docs.g1t.sh/guides/self-hosting-architecture/#each-part) |
| 117 | (`npm run test:deploy` says what is missing). |
| 118 | [Deploy g1t to Cloudflare](https://docs.g1t.sh/guides/deploy-to-cloudflare/) |
| 119 | covers the tool, the workflow, rollbacks, adding a unit and first-time |
| 120 | setup. |
| 121 | |
| 122 | - **Migrations run before the code**, so the old code reads the new schema |
| 123 | for a minute or more. Add tables and columns; change what rows mean in |
| 124 | two deploys (code that reads both forms first); never drop what live code |
| 125 | still reads. |
| 126 | - **The self-hosted runner** is released, not deployed: bump `version` in |
| 127 | `crates/runner/Cargo.toml`, merge, and push a `runner-v<version>` tag. |
| 128 | `.g1t/workflows/runner-release.yml` builds, signs and publishes it, and |
| 129 | runners update themselves to it. `scripts/runner-release.mjs` does the |
| 130 | same by hand. |
| 131 | - **The desktop app** is released the same way: bump `version` in |
| 132 | `apps/desktop/src-tauri/Cargo.toml`, merge, and push a |
| 133 | `desktop-v<version>` tag. `.g1t/workflows/desktop-release.yml` builds |
| 134 | the installers (Linux on g1t's machines; Windows and macOS on machines |
| 135 | registered for them, or Windows cross-built on Linux once its download |
| 136 | hosts are allowed, each switched on by a repository variable the |
| 137 | workflow's header names; a platform with no machine is left out of that |
| 138 | release), signs the updater's files and publishes them, and installed |
| 139 | apps update themselves. `scripts/desktop-release.mjs` does the |
| 140 | same by hand. The app loads the live site, so a change to the site needs |
| 141 | no release; only a change under `apps/desktop` does. The guide is |
| 142 | [The desktop app](https://docs.g1t.sh/guides/desktop/). |
| 143 | - **The phone app** for Android is released on g1t.sh/download while it |
| 144 | is not in Google Play (that waits on Flagon's D-U-N-S number): bump |
| 145 | `version` in `apps/mobile/app.config.ts` when its native side changes, |
| 146 | merge, and push a `mobile-v<version>` tag. |
| 147 | `.g1t/workflows/mobile-release.yml` has EAS build the APK and publishes |
| 148 | it; `scripts/mobile-release.mjs` does the same by hand. A change to the |
| 149 | app's code alone needs no release: `eas update --channel preview` in |
| 150 | `apps/mobile` reaches installed copies. Its server half (chat scopes, |
| 151 | `/-/notify`, notify's phone push) deploys with the site and services. |
| 152 | The guide is [The phone app](https://docs.g1t.sh/guides/mobile/). |
| 153 | |
| 154 | ## Speed |
| 155 | |
| 156 | Pages are a few rounds of service calls, and each round costs a trip to |
| 157 | the databases, so start calls together and add no rounds. |
| 158 | |
| 159 | - Every page answers with `Server-Timing`: each loader, each service's |
| 160 | calls and their database time. Look at it in DevTools when a page feels |
| 161 | slow. |
| 162 | - `scripts/perf/measure.ps1` times pages from your machine (`-BrowserUA` |
| 163 | for signed-out pages as a browser sees them). A page that only reads |
| 164 | must not set the `g1t_d1` cookie: a new read-only service method goes in |
| 165 | `READS` in `apps/web/app/lib/perf.ts`. |
| 166 | - Targets from the US: signed-out pages under 200 ms to first byte, |
| 167 | signed-in pages under 400 ms, streamed panels within a second. |
| 168 | - Workers run without Smart Placement; `scripts/perf/placement-probe.mjs` |
| 169 | measures a placement before you pin one. |
| 170 | - A TypeScript service reports its database time too (`db;dur`, from |
| 171 | `openD1` in `@g1t/contracts`): the round trips a method makes are what |
| 172 | it costs, so start them together (`Promise.all`), keep what never |
| 173 | changes across requests in the isolate (the artifacts service keeps a |
| 174 | workspace's slug for 30 s and whether its General space exists), and |
| 175 | don't wake a Durable Object for a read D1 can answer. |
| 176 | - Nothing live gates a page. A page carries what it shows (a doc's text |
| 177 | and its saved document), opens its sockets as it hydrates rather than |
| 178 | from inside the code they feed, keeps what is typed until they answer, |
| 179 | and says so with a dot, never a spinner. A page opened with an access |
| 180 | token gets its socket tickets with the page (the root loader mints the |
| 181 | feed's, an artifact's loader its room's) rather than asking for each. |
| 182 | - Code that only the browser runs (the doc editor) is still fetched with |
| 183 | the page: `vite.config.ts` notes the chunk and what it imports for the |
| 184 | route's `links`, and a link to such a page warms the chunk on hover. |
| 185 | Modules several routes share are grouped by who shares them |
| 186 | (`codeSplitting.groups`), so a page fetches tens of files, not a |
| 187 | hundred and more. Before this, opening a doc fetched 124 files |
| 188 | (1,049 KB) in three waves and the editor appeared at 2.8–3.3 s; a doc |
| 189 | now fetches 71 files (1,026 KB) in one wave, and against the deployed |
| 190 | services the editor appears at 2.1 s, of which the room's answer is |
| 191 | 0.65 s and the editor's own start 0.4 s. With the saved document in the |
| 192 | page, measured on g1t.sh signed in (2026-10-10, warm, 1440×900), the |
| 193 | editor appears at 1.5 s: first byte 0.53 s, scripts by 0.75 s, the |
| 194 | editor's own start the rest. A doc without a saved document (one last |
| 195 | saved before documents were kept) waited for its room's first message |
| 196 | instead, 0.9 s after the socket opened, and appeared at 2.0–2.5 s; the |
| 197 | page now asks the room once and keeps the answer, so only its first |
| 198 | open pays. Still to cut: the live socket's four service calls before |
| 199 | the room answers, the page and sidebar's 27 database round trips in two |
| 200 | calls, the root loader's billing and identity calls (0.7–1.3 s and |
| 201 | 0.45 s inside), and the 3.4 MB of script a doc page decodes. |
| 202 | |
| 203 | ## Rate limits |
| 204 | |
| 205 | `RATE_LIMITS` in `packages/contracts/src/rate-limits.ts` is the table of |
| 206 | record, and the [rate limits page](https://docs.g1t.sh/reference/rate-limits/) |
| 207 | is the public one: change both, and the binding in the Worker's |
| 208 | `wrangler.jsonc`, together (`front-door-limits.test.ts` fails when they |
| 209 | disagree). Limits fail open, keys hash anything secret, and each Worker |
| 210 | takes its namespace ids from its own block of a hundred (41xx packages, |
| 211 | 42xx web, 43xx repos, 44xx api, 45xx og, 46xx status). |
| 212 | |
| 213 | ## Operating g1t.sh |
| 214 | |
| 215 | For Flagon staff. |
| 216 | |
| 217 | - **Incidents** are declared, updated and resolved in sudo, under |
| 218 | **Platform → Incidents**, and appear on status.g1t.sh within 30 seconds. |
| 219 | Declare as soon as people are affected, and pick the higher severity |
| 220 | when unsure. SEV1 (down for most people, or data at risk) gets an update |
| 221 | at least every 30 minutes and SEV2 (a core part broken for many) at least |
| 222 | hourly; both email subscribers and need a blameless postmortem within |
| 223 | five working days. |
| 224 | - **An Artifacts outage:** `scripts/ops/gitstore-namespaces.mjs` shows a |
| 225 | failing namespace. After 15 minutes, serve it read-only from the fallback |
| 226 | git store (`scripts/ops/restore-to-gitstore.mjs restore`, then the repos |
| 227 | Worker's secret `GIT_FALLBACK_NAMESPACES`) and open an incident. To |
| 228 | switch back, `reconcile` anything the fallback took, then delete the |
| 229 | secret. The script's header has every step. |
| 230 | - **Costs and margin**, model prices, credits and the platform pause are |
| 231 | in sudo, under **Costs & margin**. The code is in `services/billing/src` |
| 232 | (`costs.rs`, `margin.rs`, `pricing.rs`, `budget.rs`, `platform.rs`). |