Pick any line to see why it is the way it is: the commit, the pull request and issue it came from, and what the agent was thinking.
| Billing: AI Gateway's analytics are read with the token that can see them, and a gateway that priced nothing is said | 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 | | |
| architecture and such | 20 | | How g1t is put together: a service, a binding, a store, an event route, the path of a request | Its page in the docs' Architecture section (`apps/docs/src/content/docs/architecture/`), and its diagram in `apps/docs/src/diagrams/architecture.ts`. [How g1t ships](https://docs.g1t.sh/architecture/shipping/#keeping-this-section-true) says which page covers what. | |
| Billing: AI Gateway's analytics are read with the token that can see them, and a gateway that priced nothing is said | 21 | |
| 22 | The style, in short: plain sentences, second person, no marketing words, | |
| 23 | sentence-case headings, a numbered list for steps, a table for options, and | |
| 24 | every API mention with its exact route or tool name. Examples are copyable | |
| 25 | and real. Nothing is documented that the code does not do. | |
| 26 | ||
| 27 | Check the docs build before you push: | |
| 28 | ||
| 29 | ```sh | |
| 30 | cd apps/docs && npm run build | |
| 31 | ``` | |
| 32 | ||
| 33 | ## Icons | |
| 34 | ||
| 35 | - **Interface icons come from [Lucide](https://lucide.dev/icons).** In the | |
| 36 | apps, import them from `lucide-react`. In the docs, use `@lucide/astro`: | |
| 37 | import an icon component, or give `apps/docs/src/components/Card.astro` | |
| 38 | and `Aside.astro` a Lucide name such as `icon="git-branch"`. Starlight's | |
| 39 | own `<Card>`, `<LinkCard>` and `<Aside>` draw Starlight's icon set, so the | |
| 40 | docs import the wrappers in `apps/docs/src/components/` instead. | |
| 41 | - **Brand marks come from [Simple Icons](https://simpleicons.org)** | |
| 42 | (`simple-icons`), and follow each brand's own usage guidelines. Add the | |
| 43 | dependency with the first one you show. | |
| 44 | - **The g1t logo and illustrations are our own artwork**, in | |
| 45 | `apps/web/app/components/logo.tsx` and `art.tsx`. | |
| 46 | - Never hand-copy an icon's SVG paths into a file. If Lucide lacks the | |
| 47 | icon you need, pick the closest one that it has. | |
| 48 | ||
| CONTRIBUTING says how the site's interface is built: from the shadcn components in apps/web/app/components/ui, themed with g1t's tokens, adding a missing one there first, changing looks through variants rather than one-off class strings, and looking at every changed page in both themes on a desktop and a phone. | 49 | ## Interface components |
| 50 | ||
| 51 | - **Build the site from the components in `apps/web/app/components/ui`**, | |
| 52 | which are [shadcn/ui](https://ui.shadcn.com) components themed with | |
| 53 | g1t's tokens: buttons, cards, badges, tables, tabs, separators, | |
| 54 | breadcrumbs, menus, dialogs, sheets, tooltips, form controls. | |
| 55 | - **If shadcn has a component you need and `ui` doesn't, add it there** | |
| 56 | first, themed with the tokens, then use it. Don't rebuild it inline. | |
| 57 | - **Change how something looks through the component's variants**, not | |
| 58 | with a one-off class string at the call site. A long `className` on a | |
| 59 | `div` that draws a card, a pill or a button is a component that should | |
| 60 | exist. | |
| 61 | - Hover hints use the `Tooltip` component, never `title=`. Native | |
| 62 | `<select>`, file inputs, checkboxes and radios use their `ui` | |
| 63 | components. | |
| Agents have faces, and are never mistaken for people. Every agent wears a little bot face drawn from a look it owns, shape, colour, eyes, mouth, antenna, accessory and pattern, chosen in its builder and on its Profile tab with a live preview, Shuffle and a way back to the face its seed gives it; the face blinks on its own time, breathes, narrows its eyes while the agent works, shuts them asleep and bounces when it finishes, all of it still for anyone who asked for less motion. Wherever an agent shows, in chat, in a list, on a mention, on a review or a commit, its avatar carries an agent marker, and the people reading it are told so. In Chat, direct messages are two lists: People, and Agents, which also holds the agents you haven't talked to yet; a conversation with both a person and an agent in it is marked in the list, named in the conversation's header, spelled out by the composer and explained once the first time it opens. Agents keep their look in the agents service, which every service passes along. The chat and agents guides say so, and CONTRIBUTING makes the shared avatar the only way to draw an agent. | 64 | - **Every avatar is `Avatar`** (`ui/avatar.tsx`), and every agent's is |
| 65 | `Avatar` with `agent` set, or `AgentAvatar` (`components/agent-avatar.tsx`), | |
| 66 | which wraps it. That draws the agent's bot face (`AgentFace`, | |
| 67 | `components/agent-face.tsx`) from its `look` or its `avatar_seed`, puts | |
| 68 | the agent marker in its corner and names it "…, agent" to a screen | |
| 69 | reader. Never hand-draw an agent's face, a sparkle, a letter on a tile or | |
| 70 | the marker at a call site: a place that shows an agent differently is a | |
| 71 | bug. | |
| CONTRIBUTING says how the site's interface is built: from the shadcn components in apps/web/app/components/ui, themed with g1t's tokens, adding a missing one there first, changing looks through variants rather than one-off class strings, and looking at every changed page in both themes on a desktop and a phone. | 72 | - Look at every page you change, in light and dark, on a desktop and a |
| 73 | phone, before calling it done. | |
| 74 | ||
| Billing: AI Gateway's analytics are read with the token that can see them, and a gateway that priced nothing is said | 75 | ## Before you push |
| 76 | ||
| 77 | - `cargo test` in the crate or service you changed. | |
| 78 | - `npx tsc -b --force` in `apps/web` (the incremental build misses changes | |
| 79 | in `packages/contracts`). | |
| 80 | - Look at what you changed in a browser. Screenshots catch what type | |
| 81 | checks do not. | |
| 82 | ||
| Merge remote-tracking branch 'origin/claude/cool-newton-7nm8r9' | 83 | ## Checking g1t against GitHub |
| 84 | ||
| 85 | g1t runs GitHub Actions workflows as GitHub does. The Conformance | |
| 86 | workflow is how that is checked: `.g1t/workflows/conformance.yml` and | |
| 87 | `.github/workflows/conformance.yml` are the same file (a test in | |
| 88 | `crates/actions` fails when they differ), and each run's | |
| 89 | `conformance-report` artifact records what its jobs saw: which `GITHUB_*` | |
| 90 | and `RUNNER_*` variables were set and of what kind, every key of the | |
| 91 | contexts and the event and its type, how the workspace is laid out, and | |
| 92 | the values of outputs, files, caches, artifacts and expressions that | |
| 93 | should be the same everywhere. It reads no secrets and runs only by hand. | |
| 94 | ||
| 95 | 1. Run it on both, at the same commit: **Actions → Conformance → Run | |
| 96 | workflow** on GitHub and on g1t.sh. | |
| 97 | 2. Download each run's `conformance-report` artifact, and name the two | |
| 98 | files `github.json` and `g1t.json`. | |
| 99 | 3. Compare them: | |
| 100 | ||
| 101 | ```sh | |
| 102 | node scripts/conformance-diff.mjs github.json g1t.json | |
| 103 | ``` | |
| 104 | ||
| 105 | It lists what GitHub has that g1t lacks or has otherwise, then what only | |
| 106 | g1t has, and exits 1 while there are differences. A difference is a bug in | |
| 107 | g1t, or belongs in [What g1t can't do yet](https://docs.g1t.sh/about/limitations/). | |
| 108 | Add a step and a `CHECK_` value to the workflow for anything new g1t | |
| 109 | should match. | |
| 110 | ||
| Billing: AI Gateway's analytics are read with the token that can see them, and a gateway that priced nothing is said | 111 | ## Deploying |
| 112 | ||
| 113 | Pushes to `main` deploy themselves: `.g1t/workflows/deploy.yml` runs | |
| 114 | `scripts/deploy.mjs`, which deploys only the parts that changed, migrations | |
| 115 | first. Every deployable part is listed in `deploy/stack.jsonc`; a new service | |
| architecture and such | 116 | or app goes there, in the table on |
| 117 | [How a self-hosted g1t runs](https://docs.g1t.sh/guides/self-hosting-architecture/#each-part), | |
| 118 | and in the one on [Services and contracts](https://docs.g1t.sh/architecture/services/#every-unit) | |
| The docs folder is gone, and what it held lives where people read it: how a self-hosted g1t runs and how to deploy g1t to Cloudflare are pages on docs.g1t.sh under Run g1t yourself, and speed, rate limits and operating g1t.sh are sections of CONTRIBUTING.md; code that cited a file in docs/ now points to the page or section that covers it, or says what it means itself, and applied migrations and the runner images are left as they were. | 119 | (`npm run test:deploy` says what is missing). |
| 120 | [Deploy g1t to Cloudflare](https://docs.g1t.sh/guides/deploy-to-cloudflare/) | |
| 121 | covers the tool, the workflow, rollbacks, adding a unit and first-time | |
| 122 | setup. | |
| 123 | ||
| 124 | - **Migrations run before the code**, so the old code reads the new schema | |
| 125 | for a minute or more. Add tables and columns; change what rows mean in | |
| 126 | two deploys (code that reads both forms first); never drop what live code | |
| 127 | still reads. | |
| 128 | - **The self-hosted runner** is released, not deployed: bump `version` in | |
| 129 | `crates/runner/Cargo.toml`, merge, and push a `runner-v<version>` tag. | |
| 130 | `.g1t/workflows/runner-release.yml` builds, signs and publishes it, and | |
| 131 | runners update themselves to it. `scripts/runner-release.mjs` does the | |
| 132 | same by hand. | |
| Merge main into rm-agents: mirroring removal, open signups, free-tier limits, the g1t CLI and runner fixes, with the agent removal kept. The CLI's table of operations is regenerated from the API without the agent, customize and AI credit operations; no CLI command used them. | 133 | - **The g1t CLI** is released the same way: bump `version` in |
| 134 | `crates/g1t/Cargo.toml`, merge, and push a `cli-v<version>` tag. | |
| 135 | `.g1t/workflows/cli-release.yml` builds it for every platform, signs | |
| 136 | the release with the runner's release key and publishes it to | |
| 137 | g1t.sh/downloads/cli/, where g1t.sh/install and g1t.sh/install.ps1 | |
| 138 | find it. `scripts/cli-release.mjs` does the same by hand. The command | |
| 139 | reference in the docs is generated from the CLI | |
| 140 | (`G1T_WRITE_DOCS=1 cargo test -p g1t cli_reference`), and its table of | |
| 141 | API operations from the OpenAPI document | |
| 142 | (`G1T_WRITE_OPS=1 cargo test -p g1t ops_table`); tests fail when either | |
| 143 | falls behind. The guide is [The g1t CLI](https://docs.g1t.sh/guides/cli/). | |
| preparing for cloud work | 144 | - **The desktop app** is released the same way: bump `version` in |
| 145 | `apps/desktop/src-tauri/Cargo.toml`, merge, and push a | |
| 146 | `desktop-v<version>` tag. `.g1t/workflows/desktop-release.yml` builds | |
| A desktop release goes out with what can be built. Linux is built on g1t's machines in every release; Windows and macOS each wait on a repository variable: a machine registered for them, or for Windows a cross build on Linux once aka.ms and download.visualstudio.microsoft.com are workflow-only domains, which is where the first release stopped. A platform with no machine is skipped and the download page says it is coming, with a word for the visitor whose platform this release lacks. The guide and CONTRIBUTING say so. | 147 | the installers (Linux on g1t's machines; Windows and macOS on machines |
| Merge branch 'main' into ask-integration | 148 | registered for them, or Windows cross-built on Linux, each switched on |
| 149 | by a repository variable the | |
| A desktop release goes out with what can be built. Linux is built on g1t's machines in every release; Windows and macOS each wait on a repository variable: a machine registered for them, or for Windows a cross build on Linux once aka.ms and download.visualstudio.microsoft.com are workflow-only domains, which is where the first release stopped. A platform with no machine is skipped and the download page says it is coming, with a word for the visitor whose platform this release lacks. The guide and CONTRIBUTING say so. | 150 | workflow's header names; a platform with no machine is left out of that |
| 151 | release), signs the updater's files and publishes them, and installed | |
| 152 | apps update themselves. `scripts/desktop-release.mjs` does the | |
| preparing for cloud work | 153 | same by hand. The app loads the live site, so a change to the site needs |
| 154 | no release; only a change under `apps/desktop` does. The guide is | |
| 155 | [The desktop app](https://docs.g1t.sh/guides/desktop/). | |
| The phone app with your own g1t, on g1t.sh/download until Google Play, and Node 24 (#5) | 156 | - **The phone app** for Android is released on g1t.sh/download while it |
| 157 | is not in Google Play (that waits on Flagon's D-U-N-S number): bump | |
| 158 | `version` in `apps/mobile/app.config.ts` when its native side changes, | |
| 159 | merge, and push a `mobile-v<version>` tag. | |
| 160 | `.g1t/workflows/mobile-release.yml` has EAS build the APK and publishes | |
| 161 | it; `scripts/mobile-release.mjs` does the same by hand. A change to the | |
| 162 | app's code alone needs no release: `eas update --channel preview` in | |
| 163 | `apps/mobile` reaches installed copies. Its server half (chat scopes, | |
| 164 | `/-/notify`, notify's phone push) deploys with the site and services. | |
| 165 | The guide is [The phone app](https://docs.g1t.sh/guides/mobile/). | |
| The docs folder is gone, and what it held lives where people read it: how a self-hosted g1t runs and how to deploy g1t to Cloudflare are pages on docs.g1t.sh under Run g1t yourself, and speed, rate limits and operating g1t.sh are sections of CONTRIBUTING.md; code that cited a file in docs/ now points to the page or section that covers it, or says what it means itself, and applied migrations and the runner images are left as they were. | 166 | |
| Merge branch 'worktree-agent-a63425cb2d4935c5f' | 167 | ## How g1t's own CI caches |
| 168 | ||
| 169 | g1t's workflows cache with `actions/cache` against g1t's own cache | |
| 170 | ([the Actions guide](https://docs.g1t.sh/guides/actions/#the-cache) has its | |
| 171 | rules). Three of them shape everything here: a run restores from its own | |
| 172 | ref, its pull request's base, then `main`, so a release tag never reads | |
| 173 | another tag's entries; a key is written once; and a repository holds | |
| 174 | 10 GiB, past which the entries restored longest ago go. So: | |
| 175 | ||
| 176 | - **`main` saves; pull requests and tags restore.** CI's Rust and desktop | |
| 177 | jobs keep their caches on each push to `main`, and the Caches workflow | |
| 178 | (`.g1t/workflows/caches.yml`) builds and saves what only releases use, | |
| 179 | when its key is missing. Release workflows only restore. | |
| 180 | - **Rust caches are keyed by the toolchain and the dependencies**, from | |
| 181 | `node scripts/deploy/ci-cache.mjs keys`: `rustc -V`, and a hash of the | |
| 182 | packages `Cargo.lock` takes from crates.io and git. A release bumping a | |
| 183 | workspace crate's version changes neither. A restore key never crosses | |
| 184 | toolchains. | |
| 185 | - **A Cargo target restored from an older entry is pruned before it is | |
| 186 | saved** (`ci-cache.mjs prune`), to what this build used. | |
| 187 | - **A partial install never saves a whole-install key.** npm's downloads | |
| 188 | and the crates are saved only by jobs that fetch all of them. | |
| 189 | - **One set of paths per entry.** An entry's version is the hash of its | |
| 190 | paths, so every step that names it, in every workflow, names the same | |
| 191 | ones. `crates/actions/tests/repository_workflows.rs` holds all of this. | |
| Merge branch 'worktree-agent-a3b9b1f730f55b5bf' | 192 | - **sccache only reads on a tag** (`scripts/sccache.sh` sets |
| 193 | `SCCACHE_GHA_RW_MODE=READ_ONLY` when `GITHUB_REF_TYPE` is `tag`): a | |
| 194 | release's run finds what `main`'s runs compiled, and saves nothing only | |
| 195 | its own tag could read. | |
| 196 | - **Images a build runs in are pinned by digest.** The CLI's release | |
| 197 | builds in `cargo-zigbuild` (`BUILDER` in `scripts/cli-release.mjs`), and | |
| 198 | its cache is keyed by that digest (`zigbuild` from `ci-cache.mjs keys`) | |
| 199 | rather than by this machine's `rustc`. | |
| Merge branch 'worktree-agent-a63425cb2d4935c5f' | 200 | |
| 201 | | Entry | Key | Saved by | Restored by | | |
| 202 | | --- | --- | --- | --- | | |
| 203 | | npm's downloads | `npm-full-<os>-<package-lock.json>` | Caches (`npm`) | every npm install | | |
| 204 | | Crates and their index | `cargo-crates-<os>-<deps>` | CI Rust (`cargo fetch` of the whole lockfile) | Deploy, the runner release | | |
| 205 | | The test build | `cargo-test-<os>-<rust>-<deps>` | CI Rust | CI Rust on pull requests | | |
| 206 | | Workers' builds | `cargo-workers-<os>-<rust>-<group>-<deps>` | Deploy | Deploy | | |
| 207 | | The runner's image build | `runner-musl-<os>-<rust>-<deps>` | Deploy | Deploy | | |
| 208 | | worker-build and its tools | `worker-build-…`, `worker-build-tools-…` | Deploy | Deploy | | |
| 209 | | Compiled crates | sccache's, one per crate | every Rust job | every Rust job | | |
| 210 | | The desktop app's check | `desktop-check-<os>-<rust>-<desktop deps>` | CI desktop | CI desktop on pull requests | | |
| 211 | | apt for Tauri | `apt-tauri-<os>-<scripts/apt-install.sh>` | CI desktop | the desktop release | | |
| 212 | | The runner release | `runner-release-<os>-<target>-<rust>-<deps>`, zig | Caches (`runner`) | the runner release | | |
| 213 | | The desktop release | `desktop-release-linux-…`, `desktop-release-windows-…`, `xwin-…`, `apt-tauri-windows-…` | Caches (`desktop-linux`, `desktop-windows`) | the desktop release | | |
| Merge branch 'worktree-agent-a3b9b1f730f55b5bf' | 214 | | The CLI release | `cli-release-<os>-<zigbuild>-<deps>` (`target/zig`, every platform) | Caches (`cli`), built whole | the CLI release | |
| Merge branch 'worktree-agent-a63425cb2d4935c5f' | 215 | |
| 216 | To see whether a change helped, read a run's cache steps: `Cache restored | |
| 217 | from key` names the entry (the key itself is a hit; another is a start), | |
| 218 | `Cache Size` and the step's time say what it cost, and the post step says | |
| 219 | whether it saved. `sccache's hits and misses` is on each Rust job's summary. | |
| Merge branch 'worktree-agent-a3b9b1f730f55b5bf' | 220 | `g1t cache usage` says what the repository's entries hold against its |
| 221 | 10 GiB, and `g1t cache list --sort size-in-bytes` which take the most. | |
| Merge branch 'worktree-agent-a63425cb2d4935c5f' | 222 | |
| Merge branch 'worktree-agent-a56293a6f836cd343' | 223 | ## Adding a machine size |
| 224 | ||
| 225 | g1t's hosted machines are one catalogue: `INSTANCE_TYPES` in | |
| 226 | `crates/contracts/src/actions.rs`, mirrored row for row in | |
| 227 | `packages/contracts/src/instances.ts`. Each row is a `runs-on` label, the | |
| 228 | machine it bills as (`machine`, such as `2-core`), the runner's Durable | |
| 229 | Object class that runs it (`class` / `sandboxClass`), the Cloudflare | |
| 230 | Containers instance type behind that class (`container`), its vCPUs, | |
| 231 | memory and disk, and its price a minute (`micros_per_minute`). The runner | |
| 232 | starts a job in its label's class, billing charges its minutes at its | |
| 233 | rate and reports them by machine, and the docs' tables follow it. | |
| 234 | ||
| 235 | - **A new label for an existing machine** (another name for the standard | |
| 236 | one, say): a row with the new label and class and the machine's | |
| 237 | `machine`, size and rate; the class and its binding below. | |
| 238 | - **A new size**: a row with a new `machine` key and its rate. The rate is | |
| 239 | what a minute costs at Cloudflare's list prices with half the vCPUs | |
| 240 | busy, plus 20%, rounded up to a tenth of a cent, and never under its | |
| 241 | cost with every vCPU busy; `rates_cover_the_machine_at_full_cpu_and_its_usual_cost_plus_the_margin` | |
| 242 | checks it. | |
| 243 | - **Pointing a label at another instance type**: change its `container` | |
| 244 | and size (and `machine`, if it is a different machine now), and the | |
| 245 | class's `instance_type` in `services/runner/wrangler.jsonc`. A custom | |
| 246 | instance type works the same way, once the account may use them: add its | |
| 247 | size to the runner test's table of instance types. | |
| 248 | - **Renaming a label**: change `label`; keep `machine`, so its minutes stay | |
| 249 | on the same line of everyone's usage. | |
| 250 | ||
| 251 | Never reuse a `machine` key for a different machine: past usage is | |
| 252 | reported under it. For a new class, add it to `services/runner/wrangler.jsonc` | |
| 253 | (`containers`, a `durable_objects` binding and a migration tag with | |
| 254 | `new_sqlite_classes`), export it from `services/runner/src/index.ts` | |
| 255 | (`export class SandboxXCore extends AttemptSandbox {}`), and give it a | |
| 256 | binding in `SANDBOX_BINDINGS` (`services/runner/src/egress.ts`). The tests | |
| 257 | that hold all of this together are `cargo test -p g1t-contracts instance` | |
| 258 | (the table, its rates and its TypeScript mirror) and the runner's | |
| 259 | `npm test` (every class in wrangler.jsonc, its instance type, size and | |
| 260 | binding against the catalogue). Then update the machine tables in | |
| 261 | `guides/actions.md`, `guides/usage-and-billing.md` and | |
| 262 | `architecture/compute.mdx`. | |
| 263 | ||
| The docs folder is gone, and what it held lives where people read it: how a self-hosted g1t runs and how to deploy g1t to Cloudflare are pages on docs.g1t.sh under Run g1t yourself, and speed, rate limits and operating g1t.sh are sections of CONTRIBUTING.md; code that cited a file in docs/ now points to the page or section that covers it, or says what it means itself, and applied migrations and the runner images are left as they were. | 264 | ## Speed |
| 265 | ||
| 266 | Pages are a few rounds of service calls, and each round costs a trip to | |
| 267 | the databases, so start calls together and add no rounds. | |
| 268 | ||
| 269 | - Every page answers with `Server-Timing`: each loader, each service's | |
| 270 | calls and their database time. Look at it in DevTools when a page feels | |
| 271 | slow. | |
| 272 | - `scripts/perf/measure.ps1` times pages from your machine (`-BrowserUA` | |
| 273 | for signed-out pages as a browser sees them). A page that only reads | |
| 274 | must not set the `g1t_d1` cookie: a new read-only service method goes in | |
| 275 | `READS` in `apps/web/app/lib/perf.ts`. | |
| 276 | - Targets from the US: signed-out pages under 200 ms to first byte, | |
| 277 | signed-in pages under 400 ms, streamed panels within a second. | |
| 278 | - Workers run without Smart Placement; `scripts/perf/placement-probe.mjs` | |
| 279 | measures a placement before you pin one. | |
| A doc opens at once: the page carries the document's saved state, so the editor mounts without waiting for its live room, which connects in the background and sends only what changed, with a quiet dot that turns green when it's synced; edits made before then are kept and sent once. The editor's code is preloaded from the page and fetched early when you hover a doc, the app's shared code ships in a few chunks instead of a hundred small ones, socket tickets come with the page instead of a round trip, and the artifacts service answers a page, a sidebar and a room in parallel lookups instead of a dozen in a row, reporting its database round trips in Server-Timing. The artifacts guide says how a doc opens, and CONTRIBUTING's Speed section has the numbers. | 280 | - A TypeScript service reports its database time too (`db;dur`, from |
| 281 | `openD1` in `@g1t/contracts`): the round trips a method makes are what | |
| 282 | it costs, so start them together (`Promise.all`), keep what never | |
| 283 | changes across requests in the isolate (the artifacts service keeps a | |
| 284 | workspace's slug for 30 s and whether its General space exists), and | |
| 285 | don't wake a Durable Object for a read D1 can answer. | |
| 286 | - Nothing live gates a page. A page carries what it shows (a doc's text | |
| 287 | and its saved document), opens its sockets as it hydrates rather than | |
| 288 | from inside the code they feed, keeps what is typed until they answer, | |
| 289 | and says so with a dot, never a spinner. A page opened with an access | |
| 290 | token gets its socket tickets with the page (the root loader mints the | |
| 291 | feed's, an artifact's loader its room's) rather than asking for each. | |
| 292 | - Code that only the browser runs (the doc editor) is still fetched with | |
| 293 | the page: `vite.config.ts` notes the chunk and what it imports for the | |
| 294 | route's `links`, and a link to such a page warms the chunk on hover. | |
| 295 | Modules several routes share are grouped by who shares them | |
| 296 | (`codeSplitting.groups`), so a page fetches tens of files, not a | |
| 297 | hundred and more. Before this, opening a doc fetched 124 files | |
| 298 | (1,049 KB) in three waves and the editor appeared at 2.8–3.3 s; a doc | |
| 299 | now fetches 71 files (1,026 KB) in one wave, and against the deployed | |
| 300 | services the editor appears at 2.1 s, of which the room's answer is | |
| A doc saved before g1t kept documents with the page opens as fast as any other from its second open: the page asks its room for the document once, sends it with the page and keeps it on the row, instead of leaving the editor to wait for the room's first message. The artifacts guide says so, and CONTRIBUTING's Speed section has today's measurements on g1t.sh and what is still to cut. | 301 | 0.65 s and the editor's own start 0.4 s. With the saved document in the |
| 302 | page, measured on g1t.sh signed in (2026-10-10, warm, 1440×900), the | |
| 303 | editor appears at 1.5 s: first byte 0.53 s, scripts by 0.75 s, the | |
| 304 | editor's own start the rest. A doc without a saved document (one last | |
| 305 | saved before documents were kept) waited for its room's first message | |
| 306 | instead, 0.9 s after the socket opened, and appeared at 2.0–2.5 s; the | |
| 307 | page now asks the room once and keeps the answer, so only its first | |
| 308 | open pays. Still to cut: the live socket's four service calls before | |
| 309 | the room answers, the page and sidebar's 27 database round trips in two | |
| 310 | calls, the root loader's billing and identity calls (0.7–1.3 s and | |
| 311 | 0.45 s inside), and the 3.4 MB of script a doc page decodes. | |
| The docs folder is gone, and what it held lives where people read it: how a self-hosted g1t runs and how to deploy g1t to Cloudflare are pages on docs.g1t.sh under Run g1t yourself, and speed, rate limits and operating g1t.sh are sections of CONTRIBUTING.md; code that cited a file in docs/ now points to the page or section that covers it, or says what it means itself, and applied migrations and the runner images are left as they were. | 312 | |
| 313 | ## Rate limits | |
| 314 | ||
| 315 | `RATE_LIMITS` in `packages/contracts/src/rate-limits.ts` is the table of | |
| 316 | record, and the [rate limits page](https://docs.g1t.sh/reference/rate-limits/) | |
| 317 | is the public one: change both, and the binding in the Worker's | |
| 318 | `wrangler.jsonc`, together (`front-door-limits.test.ts` fails when they | |
| 319 | disagree). Limits fail open, keys hash anything secret, and each Worker | |
| 320 | takes its namespace ids from its own block of a hundred (41xx packages, | |
| 321 | 42xx web, 43xx repos, 44xx api, 45xx og, 46xx status). | |
| 322 | ||
| 323 | ## Operating g1t.sh | |
| 324 | ||
| 325 | For Flagon staff. | |
| 326 | ||
| 327 | - **Incidents** are declared, updated and resolved in sudo, under | |
| 328 | **Platform → Incidents**, and appear on status.g1t.sh within 30 seconds. | |
| 329 | Declare as soon as people are affected, and pick the higher severity | |
| 330 | when unsure. SEV1 (down for most people, or data at risk) gets an update | |
| 331 | at least every 30 minutes and SEV2 (a core part broken for many) at least | |
| 332 | hourly; both email subscribers and need a blameless postmortem within | |
| 333 | five working days. | |
| The artifacts service is services/artifacts, the Worker g1t-artifacts, bound as ARTIFACTS by the API, the site and the agents; its live rooms move to it with a Durable Object transfer from g1t-docs-service, and its database, bucket, indexes and queue keep their names. The git store's binding and settings are GITSTORE, its ops scripts gitstore-*, and workflow run artifacts keep their compatible API under run_artifacts modules. The deploy tool puts a Worker that has never deployed before the Workers in its stage that bind to it, and the deploy guide gives the cutover runbook. | 334 | - **An Artifacts outage:** `scripts/ops/gitstore-namespaces.mjs` shows a |
| The docs folder is gone, and what it held lives where people read it: how a self-hosted g1t runs and how to deploy g1t to Cloudflare are pages on docs.g1t.sh under Run g1t yourself, and speed, rate limits and operating g1t.sh are sections of CONTRIBUTING.md; code that cited a file in docs/ now points to the page or section that covers it, or says what it means itself, and applied migrations and the runner images are left as they were. | 335 | failing namespace. After 15 minutes, serve it read-only from the fallback |
| 336 | git store (`scripts/ops/restore-to-gitstore.mjs restore`, then the repos | |
| 337 | Worker's secret `GIT_FALLBACK_NAMESPACES`) and open an incident. To | |
| 338 | switch back, `reconcile` anything the fallback took, then delete the | |
| 339 | secret. The script's header has every step. | |
| 340 | - **Costs and margin**, model prices, credits and the platform pause are | |
| 341 | in sudo, under **Costs & margin**. The code is in `services/billing/src` | |
| 342 | (`costs.rs`, `margin.rs`, `pricing.rs`, `budget.rs`, `platform.rs`). |
This file's history is long; its oldest lines are credited to the oldest commit read.