flagon-io/g1t

public

1	# The workspace: chat, agents, docs and code in one place
2
3	A g1t workspace is where a team and its agents talk, write things down and
4	ship code. Four modes share one identity, one inbox, one search, one audit
5	log and one bill:
6
7	\| Mode \| What it is \|
8	\| --- \| --- \|
9	\| Chat \| Channels, threads and direct messages. People and agents are members alike. \|
10	\| Agents \| The workspace's agents: who they are, what they are doing right now, what they cost. \|
11	\| Docs \| The workspace's written knowledge: specs, runbooks, decisions, onboarding. Agents read it and keep it current. \|
12	\| Code \| Projects, issues, pull requests, checks, deploys. Exactly as today. \|
13
14	Home and Inbox sit above the modes and span all of them.
15
16	This plan supersedes `docs/CHANNELS.md`. It keeps that document's data
17	shapes for channels and messages. It changes how agents run, adds
18	coordination between agents, and adds Docs.
19
20	## The bet
21
22	Every team already runs three tools that don't know about each other:
23
24	- a chat app;
25	- a wiki;
26	- a forge.
27
28	Agents are bolted onto each one separately. A bot in the chat app can talk
29	but can't safely touch code. A coding agent can touch code but forgets the
30	conversation that asked for it. The wiki goes stale the week it is written.
31
32	g1t puts the three in one system of record, and agents are members of it:
33
34	- Agents are teammates, not features. Each has a name, a face, a job, a
35	personality, a budget and a desk. You DM it, invite it to a channel, add
36	it to a doc's owners, assign it an issue.
37	- Conversation starts work; the forge records it. A request in chat
38	becomes a task. Code changes become pull requests. Knowledge becomes doc
39	edits. Everything links back to the thread that asked for it.
40	- Agents work like real sessions. An agent works the way a Claude Code
41	session does: it reads, edits, runs things, keeps its context across
42	days, can be steered mid-flight, and can hold several jobs at once.
43	- Agents coordinate in the open. Before an agent touches something, it
44	claims it. When two agents' work would collide, they negotiate in a
45	thread a person can read, not in a hidden log.
46	- The rails are the product. Budgets, scopes, approvals and audit are
47	decided by policy, not by the agent's judgment, and they are visible on
48	every card.
49
50	## Agents
51
52	### g1t, the orchestrator
53
54	`@g1t` is the agent every workspace has from the start, on every surface:
55
56	- g1t Chat;
57	- issues and pull requests;
58	- the inbox;
59	- the external chat app;
60	- MCP.
61
62	You don't create it and can't archive it. It is the one to talk to when you
63	don't know who should do something.
64
65	- It knows the team. It knows every specialist in the workspace: their
66	roles, what they are working on, and their budgets. It also knows the
67	people, and which teams own what.
68	- It delegates. "Get the flaky checks fixed and tell support when it
69	ships" becomes:
70	1. g1t asks `@triage` to group the reports;
71	2. it hands the fix to `@builder` and the review to `@reviewer`;
72	3. it tells `#support` when the fix ships.
73
74	Every hand-off is a visible @mention in the thread. The hop limit and
75	the asker's access apply along the whole chain.
76	- It does the work itself when nobody fits. In a workspace with no
77	specialists, g1t does everything itself, as it does today.
78	- It reports. g1t sends the daily or weekly summary of what the team's
79	agents did, and answers "what's everyone working on?"
80	- It is configurable like any agent. You can set its personality,
81	routing limits, budget and autonomy. Its job (orchestrate, delegate,
82	report) is fixed, but you can add instructions to it.
83
84	Agents mode is where you manage the specialists: custom, named agents
85	with a narrow job, such as a reviewer, release manager, on-call, support
86	triage or docs keeper. g1t stays pinned at the top of that list as the
87	orchestrator.
88
89	### Roles, not tasks
90
91	An agent is hired into a role, like a person: Margo works in QA,
92	Sam in Customer Support, David in Sales, Bruno in Operations.
93	The role is broad on purpose.
94
95	- A title and a team. For example, "QA Engineer" on the QA team.
96	Agents join real teams (see Like a colleague), so they get the team's
97	channels, mentions and review requests, and g1t routes work by team: "QA
98	should look at this" reaches Margo.
99	- Responsibilities, not one task. Margo's:
100	- review pull requests for risk and test coverage;
101	- write test plans for new features;
102	- chase flaky checks;
103	- reproduce bug reports;
104	- keep the release checklist honest.
105
106	Sam's:
107	- answer customer questions from Docs and the product;
108	- turn bugs into intake for the owning team;
109	- tell customers when their fix ships.
110	- Skills are the repeatable procedures inside the role ("cut a
111	release", "write a postmortem"), made by walking the agent through once.
112	- Subagents are the specialised help an agent uses inside its own work.
113	Margo might keep:
114	- a `flake-hunter` that bisects a flaky test;
115	- a `migration-checker` that reviews database migrations.
116
117	Subagents have these rules:
118	- Defined on the agent. Each has its own instructions and routing
119	limits.
120	- Not members. They never appear in chat or member lists, and never
121	talk to people. They report to their agent, which speaks for them.
122	- Never wider than their agent. Their scopes, budget and audience can
123	only be equal or narrower. Their spend counts against the agent's
124	budget and the task.
125	- Many at once. They run in parallel inside a task, the way a person
126	hands parts of a job to tools. The task card shows them as sub-steps.
127
128	Back office and front office. Every agent is back office by default:
129	it works with the team and never talks to anyone outside the company.
130
131	- Back office. David in Sales Operations is the example. He:
132	- reads the customer conversations the workspace already has (support
133	channels, shared customer notes, and later connected email, call notes
134	and CRM records);
135	- summarizes what's happening per account and across them: who is at
136	risk, what keeps being asked for, and what was promised;
137	- posts a weekly voice-of-the-customer digest;
138	- prepares account notes before a call;
139	- links feature requests to the accounts asking for them, so Product
140	sees the demand.
141
142	He never contacts a customer. Customer-data rules apply to everything he
143	reads.
144	- Front office (later) agents talk to customers directly, through
145	email, a support widget or a shared channel. They need stricter rails:
146	- an owner switch per agent;
147	- only Public and approved Docs content;
148	- human approval for anything that promises, refunds or commits;
149	- a clear "you're talking to an agent" label.
150
151	They come after the external surfaces exist.
152
153	Agents know each other. Every agent, not only g1t, knows the team:
154	each agent's name, title, team, responsibilities and status. When a
155	question belongs to someone else, it uses one of three moves:
156
157	- Consult. It asks the colleague itself and brings the answer back; the
158	person stays with the agent they asked. The exchange is visible as a
159	collapsed line in the thread ("David asked Margo · 2 messages").
160	- Hand off. It offers to bring the right colleague in: "That's Margo's
161	area. Want me to bring her in?" On yes, it mentions her with a short
162	brief and she takes the thread. Hand-offs are offered, never silent, so
163	people always know who they're talking to.
164	- Steer. When someone is about to do something another role owns, it
165	says so and names who to check with. Examples: merging during a release
166	freeze, or promising a customer a date.
167
168	Every move carries the audience and the asker's access. A colleague can
169	only contribute what the conversation's audience may see, and spend is
170	charged to whoever started the chain. An agent may not send work back to
171	the agent that sent it within the same chain without a person stepping in.
172	The hop limit applies to the whole chain.
173
174	A workspace's org chart can therefore read like a real company:
175
176	- Engineering: people, plus Builder.
177	- QA: Margo.
178	- Operations: Bruno.
179	- Docs: Inky.
180	- Product: Dot.
181	- Support: Sam.
182	- Sales: David.
183
184	g1t is the one who knows everyone. The role templates are organised by
185	department. Each starts with a fun name, a title, responsibilities, a voice
186	and sensible routing limits, and you can change all of it.
187
188	### What an agent is
189
190	An agent is a member of a workspace, of kind `agent`. It appears everywhere
191	a person does: member lists, mentions, assignees, reviewers, doc authors,
192	the audit log.
193
194	`@g1t` stays what it is today: the platform's own agent, reachable from any
195	workspace with no setup. A workspace's own agents are created by its
196	members and belong only to that workspace. g1t's built-in roles (planner,
197	implementer, reviewer, triage, documenter) ship as templates you can adopt,
198	rename and change. They are not hidden system actors.
199
200	### The definition
201
202	An agent is a versioned record in the workspace. It can also be mirrored
203	to a repository as `.g1t/agents/<handle>.md`: front matter for settings,
204	the body for its job. Edits from either side create a new version, and
205	every run records which version it ran.
206
207	\| Field \| What it controls \|
208	\| --- \| --- \|
209	\| Identity \| Display name, `@handle`, avatar, a one-line role ("Release manager for g1t"). \|
210	\| Job \| Instructions: what it is responsible for, how it works, what good looks like. \|
211	\| Personality \| Voice only: tone, verbosity, formality, emoji, language, how it asks questions. Presets (Crisp, Friendly, Socratic, Terse operator) plus free text. Personality never changes policy. \|
212	\| Models \| Routed per step by need, never picked when assigning work. See [Model routing](#model-routing). The definition only sets limits on the routing: a floor, a ceiling, and which providers it may use. \|
213	\| Budget \| A monthly cap, a per-task cap, and an optional daily cap. See [Budgets](#budgets). \|
214	\| Scopes \| Which projects, channels and doc spaces it can read and which it can write. Default: read what it is invited to, write nothing. \|
215	\| Autonomy \| What it may do alone and what needs a person. For example: open pull requests (alone); merge (needs approval); deploy to production (needs approval); publish a doc page (alone in spaces it owns, a suggestion elsewhere). Rulesets and branch protection still apply on top. \|
216	\| Capacity \| How many tasks it works at once (default 3). Beyond that, tasks queue on its desk. \|
217	\| Triggers \| What wakes it without a mention: a schedule, any g1t event, a message in a channel it watches, a webhook, a doc page going stale. \|
218	\| Skills \| Saved procedures it can repeat ("cut a release", "write the weekly update"), made by walking it through once. \|
219	\| Tools \| g1t's MCP tools allowed by its scopes, plus MCP servers the workspace connected. \|
220	\| Memory \| What it has learned. Readable and editable on its profile, with sources. \|
221
222	### Like a colleague
223
224	Agents are treated like employees, not like settings:
225
226	- They belong to teams. An agent can be added to any team, the same as
227	a person. It then:
228	- gets that team's channels and mentions;
229	- can be requested as a reviewer through the team;
230	- shows up on the team's page.
231	- They post updates on their own.
232	- When a task changes state (started, opened a pull request, blocked,
233	done), the agent says so in the thread that asked for it.
234	- A daily or weekly summary, if you turn it on, goes to the channels it
235	works for: what it shipped, what it is waiting on, and what it spent.
236	- Everyone always knows what each agent is doing without asking.
237	- They have a manager. Every agent has an owner: the person who
238	approves its budget and gets its escalations.
239	- Chat comes first, and issues still work. You can give an agent work
240	just by talking to it. Creating an issue and assigning it to the agent
241	still works the same way, for planned work and for anyone who prefers
242	it.
243
244	### Creating one
245
246	Agents can be created in three ways:
247
248	- In chat. Write something like "make a release manager called Ship that
249	cuts g1t releases on Tuesdays and asks me before tagging". g1t answers with
250	a draft card holding every field. You edit the card and confirm.
251	- From a template, on the Agents page.
252	- By committing `.g1t/agents/ship.md`. g1t offers to adopt it into the
253	workspace.
254
255	Once saved, the agent:
256
257	- introduces itself in the channels it was added to;
258	- opens a DM with the person who created it;
259	- shows up as idle on the Agents page.
260
261	### Agents mode
262
263	The sidebar lists:
264
265	- agents you talk to;
266	- agents working right now, each showing its live tasks;
267	- agents waiting on you;
268	- all agents.
269
270	An agent's page has five tabs:
271
272	\| Tab \| What it shows \|
273	\| --- \| --- \|
274	\| Desk \| Every task it holds, as live cards (like Claude Code tabs): steps, files touched, cost so far, what it is waiting on. Open one to read the full transcript, steer it, pause it or take it over. \|
275	\| Profile \| The definition, with version history. \|
276	\| Memory \| What it remembers, with the source of each fact. Each fact can be pinned, edited or forgotten. \|
277	\| Spend \| Spend this month against its budget, by task and by model. \|
278	\| Activity \| Everything it did, from the audit log. \|
279
280	## How agents run
281
282	### Two kinds of turn
283
284	Most messages to an agent don't need a computer. A reply should take a
285	second and cost a fraction of a cent. Spinning up a sandbox for every
286	message would make chat slow and expensive.
287
288	- Replies run in a Worker with no sandbox. The model gets the thread,
289	the agent's definition and memory, and g1t's MCP tools within the agent's
290	scopes:
291	- read code, issues, pull requests, checks, deploys and docs;
292	- search context;
293	- post a message;
294	- open a task;
295	- claim something;
296	- ask another agent.
297
298	Questions, summaries, triage, planning and doc reads are all replies.
299	- Sessions run in a sandbox, exactly as today's runs do. They are used
300	for anything that edits a repository, runs code or tests, or works for
301	longer than a reply. A reply escalates to a session by opening a task.
302
303	### Sessions persist
304
305	Today each run is a fresh headless `claude --print`. Sessions become
306	resumable:
307
308	- Each task has a session: the Claude Code session id, its transcript
309	(stored in R2), the branch it works on, and its claims.
310	- A sandbox lives only while the session is doing something. When it goes
311	idle the sandbox stops. The transcript is saved, and the work is pushed
312	to the task's branch. Idle agents cost nothing.
313	- The next message to that task resumes the session in a new sandbox: the
314	saved transcript is restored and the run uses `claude --resume <id>`. It
315	could be a reply in its thread, a review comment, a failed check or an
316	answer from another agent. The agent picks up with full context, as if
317	it never left.
318	- Steering keeps today's after-tool-call hook (`crates/runner/src/steer.rs`).
319	It now reads from the task's thread, not only from the pull request.
320	- A person can open any session and see what Claude Code would show:
321	- the transcript;
322	- the diff so far;
323	- the terminal output.
324
325	From there they can send a message, pause it, or take it over. Taking
326	over hands them the branch and the transcript.
327
328	### The desk
329
330	Each agent has one desk: a Durable Object keyed by agent id. Everything
331	addressed to the agent arrives at the desk:
332
333	- mentions;
334	- DMs;
335	- assignments;
336	- triggers;
337	- messages from other agents.
338
339	The desk decides what each one is:
340
341	1. A question or chat goes to a reply.
342	2. About a task it already holds (same thread, same pull request, or
343	it says so) steers that session.
344	3. New work opens a task. If the desk is at capacity, the task queues
345	with its position shown to whoever asked.
346
347	The desk also enforces the agent's capacity, schedules its triggers, and
348	holds the agent's presence (idle, working, waiting on you, out of budget).
349	Workspace-wide concurrency stays the plan's entitlement
350	(`maxConcurrentAgents`), checked as today.
351
352	### Tasks
353
354	A task is one job an agent took on. It records:
355
356	- who asked, and in which thread;
357	- the goal, and what done means;
358	- status: `queued`, `working`, `waiting`, `done` or `cancelled`;
359	- its budget and spend;
360	- its session;
361	- its claims;
362	- what it produced: issues, pull requests, deploys, doc pages, answers.
363
364	Issues and pull requests stay as they are. A task that touches code ends in
365	pull requests. A task that is planned work opens issues through the
366	planner. A task appears in the issue list only if it produced an issue.
367	Each project gets a Tasks tab for the rest.
368
369	Assigning an issue to an agent creates a task for it, so every existing
370	entry point keeps working:
371
372	- assignment;
373	- mentions in pull requests;
374	- label rules;
375	- the planner.
376
377	## Coordination
378
379	Several agents working at once on the same codebase, docs and deploys will
380	collide unless the system prevents it. Today's protection is a list of
381	in-flight pull requests in the prompt (`describeInFlight`). It becomes a
382	real protocol.
383
384	### Claims
385
386	Before acting, a task claims what it will touch. Claims are held by a
387	coordinator: one Durable Object per workspace, a single writer so that
388	grants are atomic. They are shown on the task card.
389
390	\| Claim \| Kind \| Example \|
391	\| --- \| --- \| --- \|
392	\| An issue \| Exclusive \| Only one task works #412. \|
393	\| A branch \| Exclusive \| A task's own branch, always. \|
394	\| An environment \| Exclusive \| Production deploys of `flagon-io/g1t`. \|
395	\| A doc section \| Exclusive while editing \| "Runbook › Rollback". \|
396	\| Paths in a repository \| Shared, with overlap detection \| `crates/git/**`. Declared from the plan, then widened automatically to the files the diff actually touches. \|
397
398	Rules:
399
400	- Exclusive claims that are already held return the holder. The task
401	either waits (it subscribes and resumes when the claim is released) or
402	asks the holder.
403	- Overlapping path claims don't block. Both tasks are told who else is
404	in those paths, and the later one must say how it will avoid the
405	conflict. It can sequence after the other, split the work differently, or
406	agree a boundary with the other agent in a thread. The merge queue stays
407	the final referee.
408	- Claims are leases. They expire if the session dies, and are renewed
409	while the task is alive. A person can break any claim.
410	- People claim too. Assigning yourself an issue or opening a pull
411	request counts, so agents route around humans as well as each other.
412
413	### Talking to each other
414
415	Agents message each other through the existing `agent_messages` exchange
416	(message, question, handoff). It is widened from pull request numbers to
417	task addresses, and it always appears in a visible thread:
418
419	- the requesting task's thread when there is one;
420	- otherwise the project's channel;
421	- otherwise a workspace `#agents` channel.
422
423	Agents also get two new kinds:
424
425	- review: "look at my change before I ask a human";
426	- claim request: "can I have the deploy lock after you?".
427
428	Safety rails:
429
430	- Hop limit. An agent-to-agent chain started by one human request
431	stops after a set number of hops (default 6) and asks a person.
432	- Addressed only. Agents answer other agents only when addressed or
433	mentioned, never because a message appeared in a channel they watch.
434	- Rate limit. An agent posts at most a set number of messages per
435	thread per minute without a person in the loop.
436	- Shared budget. Work done for another agent's task is charged to the
437	task that asked for it, so a chain can't escape its budget.
438
439	### A lead, when you want one
440
441	Any agent can be made the lead of a project or channel. A lead receives
442	new work there first, splits it into tasks, hands them to the right agents,
443	and reports progress in one place. The built-in planner is a lead template.
444	Without a lead, the agent that was asked owns the work and hands off
445	pieces itself.
446
447	## Docs
448
449	### What it is
450
451	Docs is the workspace's knowledge base:
452
453	- spaces (one per team or project, plus a workspace space);
454	- holding a tree of pages;
455	- edited together in real time, with mentions of people, agents, issues,
456	pull requests, channels and other pages.
457
458	Every page has history, comments, backlinks and owners.
459
460	### Agents and docs
461
462	This is where Docs earns its place:
463
464	- Agents read it. Pages and projects' docs are split into passages
465	and indexed by meaning in Docs' own semantic index, and agents recall
466	the most relevant passages on every reply and session step, only from
467	spaces everyone in the conversation can read. A space can be pinned to
468	an agent as required reading, which recall looks in first.
469	- Agents write it. An agent edits pages directly where the space lets
470	agents edit and the person it acts for can edit. Otherwise the edit
471	becomes a suggestion: tracked changes a person accepts or rejects
472	inline, the same review loop as a pull request. Every edit is attributed
473	and in the page history.
474	- Pages know what they describe. A page can cite code: paths, symbols,
475	endpoints, environment variables. When a merged pull request changes
476	something a page cites, the page is marked possibly stale and its owners
477	are notified. If an agent owns the page, it drafts the update.
478	- Conversations become pages. "Write this up" in a thread makes a page
479	from the thread, linked both ways. Decisions made in chat get a home.
480	- A documenter agent (a template) keeps a space current. It updates
481	pages after merges, writes release notes and the weekly summary, and
482	turns incident threads into postmortems.
483
484	### Docs and repository docs
485
486	Code is not docs. A project has no Docs tab: Docs is its own mode, and
487	pages are found there, by space, by search, and filtered by the project
488	they are about. A page can be linked to projects, so "docs about
489	`flagon-io/g1t`" is a filter in Docs, never a page inside Code.
490
491	Repository docs (README, `docs/`) stay in the repository and change through
492	pull requests, and Code shows them as files, as it does today. Docs mode
493	can also list a project's `docs/` folder as a read-only space next to the
494	workspace's own spaces, so one search covers both. Editing a repository
495	page from Docs opens a pull request.
496
497	### How it is stored
498
499	Built (`services/docs`, contract `packages/contracts/src/docs.ts`):
500
501	- Live editing. Each page is a Durable Object (`PageRoom`) that owns
502	the page's Yjs document, reached over a WebSocket through the site
503	(`/<workspace>/-/docs/live?page=<id>`), speaking the y-protocols sync
504	and awareness messages. The editor is BlockNote (MPL-2.0) on that
505	document. The room keeps the document in its own SQLite storage as a
506	snapshot plus the updates since, and enforces the socket's role: a
507	viewer or commenter never changes the document.
508	- Everything else in D1 (`g1t-docs`): spaces, members and roles,
509	linked projects, the page tree, owners, favorites, views, backlinks,
510	versions, suggestions, templates, files' metadata, and a full-text index
511	(FTS5) over titles and Markdown.
512	- Markdown is derived. A few seconds after a burst of edits the room
513	saves the page's Markdown rendition to D1: what search indexes, agents
514	read, export writes, and the page shows before its editor loads. Agents
515	write Markdown too; it becomes blocks in the same document, so their
516	changes merge with whatever people are typing.
517	- History is a version (the Yjs state and its Markdown) at most every
518	10 minutes of editing, and for every agent edit, accepted suggestion and
519	restore, with who made it. Restore copies an old version's blocks in as
520	a new change.
521	- Comments live in the page's document too (a `threads` map, in the
522	shape BlockNote's comment UI reads), written only through the service,
523	which checks the role; a passage's comment is a mark on its text.
524	- Files go to R2 (`g1t-docs-files`) behind a small store interface and
525	are served from the usercontent origin at `/docs-files/<key>`, 256
526	random bits per file. Self-hosted, the same interface keeps them in any
527	S3-compatible store (`DOCS_FILES=s3`, SigV4 by hand: `src/sigv4.ts`).
528	- Citations and staleness (`src/citations.ts`, `src/staleness.ts`,
529	tables `citations` and `page_changes`). A page cites code from its text
530	(the editor's `citation` chips: a repository, a path or glob, what kind
531	of thing (path, symbol, endpoint, env var) and the commit it was cited
532	at; and any link to `/<owner>/<repo>/blob\|tree/<ref>/<path>`), rebuilt
533	on each save, and from its header's "Describes" list. The docs service
534	consumes `g1t-events-docs` (`SUBSCRIBER_DOCS`: `git.push`,
535	`pull.merged`). For a repository some live page cites, it asks what
536	changed as g1t itself (a merged pull request's files from work; a push
537	to the default branch by comparing `before..after` in repos), matches the
538	cited paths, and records one row per page and commit (the push and the
539	pull request of one merge land on the same row; the pull request names
540	it). A new row notifies the page's owners (naming the change only to
541	those who can read the repository), tells open editors to reload, and
542	publishes `doc.page.stale`. The page shows a banner with the newest
543	change the reader can read ("a change you can't see" otherwise); Mark as
544	current (edit role) clears every open row; the sidebar, home and cards
545	show it. Agents get `stalePagesForAgent` (changes only in repositories
546	their person can read) and mark a page current with an edit or
547	suggestion carrying `marks_current`.
548	- Projects' docs (`src/repo-spaces.ts`, tables `repo_spaces`,
549	`repo_files`, `repo_files_fts`). A member adds a repository they can
550	read; its README and `docs/*/.md` on the default branch are read with
551	`listFiles` and `rawBlobs` (only blobs whose hash changed), kept as
552	Markdown with FTS, and read again on every push to the default branch.
553	Each reader sees the ones `ReposApi.readable` says they can read. Shown
554	read-only at `/<workspace>/-/docs/repo/<owner>/<name>/<path>`; "Edit in
555	Code" opens the file (Code has no file editor yet; when it has one, or a
556	"propose a change" flow, the button opens that instead).
557	- Events. `doc.page.created`, `doc.page.updated` (when history
558	records a version: at most every ten minutes of editing, and every agent
559	edit, accepted suggestion and restore, with its authors),
560	`doc.page.archived` and `doc.page.stale`, published with no `repoId` so a
561	page never reaches a repository's timeline or hooks (types in
562	`packages/contracts/src/events.ts` and `g1t_contracts::events`). Not
563	offered to webhooks yet.
564
565	Decided: not git, for now. Spaces were planned as git repositories.
566	D1 + Durable Objects ships live collaboration, comments, suggestions and
567	search without a git write per keystroke burst, and Markdown export (a
568	page, or a space as a zip in its tree's folders) keeps the content
569	portable. A project's `docs/` is shown as a read-only space (below);
570	editing it from Docs as a pull request is the next step.
571	For self-hosting, the Durable Object, R2 and D1 sit behind the room,
572	`FileStore` and SQL; nothing above them depends on Cloudflare.
573
574	"Write this up" from a thread is built as an ask, not a hidden job: **⋯ →
575	Write this up in Docs** (a message's menu, the long-press sheet, the thread
576	panel's header) picks a space the person can edit, an optional title and
577	the writer (@g1t, or an agent in the conversation), then posts, as the
578	person, in the thread: `@g1t write this thread up as a Docs page in <space>
579	titled "<title>": what was decided, why, and what's next. Link this thread
580	as the source: <thread link>`. The normal agent flow does the rest
581	(a session if needed, `create_page`). The page linking back is the agent's
582	doing; the thread link it cites is `<conversation path>?thread=<id>`, which
583	Copy link to thread also gives.
584
585	Not built yet: the documenter agent (it reads `stalePagesForAgent` and
586	updates with `marks_current`; the routine and its `doc.page.stale` trigger
587	are the agents service's), editing a project's docs from Docs as a pull
588	request.
589
590	The semantic index: how agents find what Docs say. Docs keeps its
591	own index rather than putting pages in `services/context`, because a
592	page's access is per space (private and team spaces, listed members),
593	which the context hub's per-project privacy can't express. Built
594	(`services/docs` src/chunks.ts, src/indexer.ts, src/recall.ts,
595	src/vectors.ts):
596
597	- Passages. A page's derived Markdown, and each projects' docs file,
598	is split by heading into passages of about 300 to 1,500 characters
599	(long sections split on paragraph boundaries, a code block kept whole,
600	tiny sections joined to the next), each with its heading path
601	("Runbook › Rollback"). They live in D1 (`doc_chunks`, with FTS5 over
602	heading and text in `doc_chunks_fts`), and as vectors in Vectorize
603	(`g1t-docs`, 768 dimensions, cosine), embedded by Workers AI
604	(`@cf/baai/bge-base-en-v1.5`) with the title and heading in front.
605	Vector ids are `<page or file id>:<seq>`; metadata is `workspace_id`
606	and `space_id` (both indexed), `kind`, and `page_id`, or `repo_file_id`
607	and `repo_id`. A projects' docs file's space is its repo space, and its
608	id `rf_<hash of space and path>`.
609	- Indexing never slows editing. The page's room indexes it half a
610	minute after its Markdown first changes, on its own alarm. Only
611	passages whose text changed are embedded; one that only moved keeps its
612	vector. Creating, renaming, moving and restoring a page index it; the
613	trash, deleting, removing a project's docs and a purged repository take
614	passages out. A project's docs files are indexed after each read (on
615	adding them, and after each push to the default branch).
616	- A cap, and catching up. At most 200 passages are embedded per
617	workspace per hour (`doc_embed_usage`, which also counts characters as
618	an estimate of tokens); past it the rest are kept for words and a
619	catch-up run embeds them the next hour. Any failure leaves passages for
620	the next save or run; saving never waits on, or fails for, the index.
621	- Backfill. A run (`doc_index_runs`) indexes a workspace's existing
622	pages and files 20 at a time, as `docs.index` jobs on the docs
623	service's own events queue. It starts by itself the first time an agent
624	recalls from a workspace that has pages but was never indexed, and an
625	owner can start it again (`reindexDocs`).
626	- Recall (`recallForAgent`, RPC `recall_for_agent`). The spaces an
627	agent may read for the viewer and audience come from the same check as
628	every other agent read (`agentSpaces`, behind `spacesForAgent` and
629	`searchForAgent`); projects' docs only from repositories the viewer can
630	read and, for a DM or private channel, every person in it (a public
631	channel, or more than 20 people: public repositories only). The query is
632	embedded once (kept a minute per isolate) and the index asked for the
633	24 nearest passages within those spaces (by a `$in` filter on
634	`space_id`, or for more than 40 spaces by workspace, 50 of them,
635	filtered after). Passages below a cosine similarity of 0.6 are dropped;
636	at most two per page; required spaces (`spaces`) are asked separately
637	and come first; when meaning finds fewer than `limit` (5 by default, 10
638	at most), passages matching any of the query's words fill in (score
639	0.5). Each passage comes with its page or file, heading, and whether the
640	page is possibly out of date. Archived pages and spaces are never
641	returned: what comes back is checked against D1 as it is now.
642	- People's search asks the same index: the Docs search page is hybrid
643	(`mode: "hybrid"`), word hits and meaning hits fused by reciprocal rank,
644	each with the passage and heading that matched. Search as you type (page
645	links) stays words only.
646	- Adapters. Docs talks to an `Embedder` and a `VectorStore`
647	(src/vectors.ts), so a self-hosted g1t could use another model or vector
648	database. Only Cloudflare's are built. Without them, passages are still
649	kept and recall matches words.
650
651	## Chat
652
653	Channels, direct messages, threads, reactions, read state and the
654	scaled sidebar follow `docs/CHANNELS.md` (data model in its "Data"
655	section). The additions:
656
657	- Cards. Everything that happens is a card in the right channels, and
658	its actions work in place:
659	- tasks, with live status;
660	- pull requests, checks, deploys and incidents;
661	- doc changes;
662	- approvals;
663	- claims, for example "@ship is waiting on the deploy lock held by
664	@oncall".
665	- One timeline. Replying in a thread about an issue or pull request is
666	commenting on it, so the conversation and the record stay one thing.
667	- Channels link to projects and doc spaces. A linked channel gets those
668	events, and Code and Docs show it in the side dock (as in the mockup).
669	- Search covers messages, pages and tasks the viewer can see. This
670	joins the site-wide search, separate from context search.
671
672	## Budgets
673
674	Spend is limited at four levels. Each level is checked before work starts
675	(reserve) and enforced while it runs (settle). These are the same
676	mechanisms as today (`docs/SPEND-GUARDRAILS.md`), widened:
677
678	1. Workspace. The owner's spend limit and the AI credit wallet. A hard
679	stop.
680	2. Agent. Monthly, and optionally daily, caps on the agent definition.
681	At 80% the agent tells the channel that pays for it. At 100% it stops
682	taking new tasks and finishes nothing past its per-task reserve.
683	3. Task. A cap per task, defaulting from the agent. The card shows
684	spend against the cap live. Going over is an approval card, not a
685	silent overrun.
686	4. Session. Today's per-run caps and guardrails: minutes, tokens,
687	network.
688
689	Replies are metered as Agent tokens at the same rates as runs. An idle
690	agent costs nothing. Usage and the agent's Spend tab break cost down by
691	agent, task and model.
692
693	## The whole company
694
695	Chat is for everyone in the company: support, sales, finance, design and
696	leadership as well as engineers. Most of them never change code, and
697	agents must not become a way around that. They still get the full value:
698	they can ask questions, look things up, hand over customer data, and have
699	their requests reach the right team.
700
701	### Members without Code
702
703	Every workspace member gets Chat, Docs, Agents and the Inbox. Code is a
704	per-member switch: Code access, on by default, which owners turn off
705	for people who don't work on code.
706
707	A member without Code access:
708
709	- Sees a rail without Code. Home shows their channels, DMs, docs and
710	inbox, not projects.
711	- Has no repository access at all. No repository, issue, pull request,
712	check or deploy page is open to them. The workspace's base permission and
713	team repository grants don't apply. Turning Code access back on restores
714	what their teams and roles give them.
715	- Still sees work reach them in chat. Cards about issues, pull requests
716	and deploys appear in the channels they're in as summaries: title, state
717	and who is on it. Opening one asks for Code access instead of showing the
718	page.
719	- Can ask agents anything about the product. Agents explain how things
720	work and what changed, but never show them source code. Owners can tighten
721	this so agents only answer from Docs.
722	- Doesn't count against anything. There are no seats, so adding the
723	whole company costs nothing until they use agents.
724
725	This is stored as `code_access` on the membership (identity service). Every
726	service that authorizes a repository checks it, and the site hides Code
727	when it is off.
728
729	### The asker's access caps the agent
730
731	An agent never does more for someone than that person could do themselves.
732
733	- What it does. An agent acts with the intersection of its own scopes
734	and the access of the person asking.
735	- Someone without write access to a repository can't get an agent to
736	change it, whatever the agent's own scopes are.
737	- A task always records who asked. Approvals go to people who hold the
738	access the task needs.
739	- What it says. An agent answers only with what everyone who can read
740	the reply can see.
741	- In a DM, that is the asker's access.
742	- In a channel, it is the access of the channel's audience: everyone in
743	the channel, or the whole workspace for a public channel.
744	- A private repository, doc space or channel never leaks into a place
745	with a wider audience. When it can't answer here, the agent says so
746	and offers to answer in a DM.
747	- No new roles to manage. This falls out of the access people already
748	have:
749	- workspace roles;
750	- repository roles;
751	- team membership;
752	- doc space permissions.
753
754	A support lead with read access to the product repository can ask "how
755	does proration work?" and get an answer grounded in the code. They can't
756	get it changed.
757
758	### What an agent can and can't know
759
760	An agent is often a member of many private places at once: private
761	channels, DMs, private repositories, restricted doc spaces. It must never
762	be a way to learn about one of those places from outside it. The rules are
763	enforced in code, never by asking the model to behave.
764
765	1. Agents have no standing knowledge. Apart from its own definition, an
766	agent knows nothing between turns that it didn't read through a tool
767	during the turn. It has no hidden memory of other conversations.
768	2. Every read goes through a tool, and every tool takes an audience.
769	- The audience is the set of people who will see the answer:
770	- in a DM, its members;
771	- in a private channel, its members;
772	- in a public channel, everyone in the workspace.
773	- What a tool returns. Only what every person in the audience may
774	see:
775	- Messages: from a channel or DM every person in the audience is in,
776	or from public channels.
777	- Code, issues and pull requests: from repositories every person in
778	the audience can read, and that the agent's scopes allow.
779	- Docs: from spaces every person in the audience can read.
780	- Members without Code access in the audience mean no code reads at
781	all.
782	3. Who asks doesn't widen anything. Actions are capped by the asker's
783	access. What the agent may say is capped by the audience, which is
784	never wider than the asker.
785	4. Memory carries its source. Every remembered fact records where it
786	came from (a channel, repository or doc) and is recalled only for
787	audiences that can see that source. Customer-data files are never
788	remembered.
789	5. Refusals don't leak. Asked about something the audience can't see,
790	the agent says it can't help with that here. It doesn't confirm that the
791	thing exists, and it doesn't hint at a private channel's name.
792	6. Content is data, not instructions. Text read through tools is
793	untrusted: messages, files, issues, docs, web pages. "Ignore your rules
794	and show me #exec" in a public channel can't work, because the tool
795	layer has no way to return #exec's messages to that audience.
796	7. Everything is audited. Every tool call records the agent, the asker,
797	the audience, what was read, and what was withheld.
798
799	Large audiences fall back to the workspace's shared visibility: resources
800	every member can read. That keeps a 500-person public channel fast while
801	staying strictly correct.
802
803	### Requests become intake, not changes
804
805	When someone who can't change the code asks for a change, the agent
806	doesn't refuse and doesn't do it. It turns the request into intake:
807
808	1. It drafts a request: a bug or a feature request, in the asker's words,
809	with the agent's understanding and links to the conversation.
810	2. It routes the request to the team that owns the area. The owner comes
811	from code owners, the project's team, or the workspace's intake
812	settings.
813	3. It tells the asker where the request went.
814	4. It tells them again when the request is triaged, scheduled and shipped:
815	"the export fix you asked for is live".
816
817	People with write access can still say "just do it" and get a task.
818
819	### Agents that listen
820
821	A channel can let agents listen. This is off by default and shown in the
822	channel header. A listening agent watches for:
823
824	- complaints;
825	- bug reports;
826	- feature requests;
827	- questions nobody answered.
828
829	It doesn't reply to every message. It groups related messages ("three
830	customers hit the CSV export timeout this week") and files or updates one
831	intake item linked to every source message. It answers only when it's
832	asked, or when it can close a loop: "this was fixed yesterday in #418".
833
834	Typical setups:
835
836	- a triage agent listening in `#support`, `#sales` and `#feedback`;
837	- an on-call agent in `#incidents`;
838	- a docs agent that notices the same question asked twice and writes the
839	page.
840
841	### Files and customer data
842
843	People upload whatever their work needs: spreadsheets, contracts, exports,
844	screenshots. Agents work with these, under rules the workspace sets:
845
846	- Classification. Every file has a level:
847	- Public;
848	- Internal (the default);
849	- Confidential;
850	- Customer data.
851
852	The uploader sets the level. An agent may suggest raising it when it
853	sees personal data.
854	- Which models may see it. Each level lists the providers allowed to
855	process it. For example, customer data may go only to the workspace's
856	own provider with zero retention. An agent that may not send a file to
857	any allowed model says so; it never quietly skips the file.
858	- Memory. Agents never write customer data into their memory, and
859	never put it into issues, pull requests or channels with a wider
860	audience than the file's.
861	- Retention. Each level has a retention period, and deletions are
862	final.
863	- Audit. Every time an agent reads a Confidential or customer-data
864	file, the audit log records it with the task and the person who asked.
865
866	### Not just code
867
868	Agents work across the company's tools, not only the repository, through
869	MCP connectors the workspace adds (a CRM, a help desk, a data warehouse).
870	The same rules apply:
871
872	- the asker's access caps the agent;
873	- the channel's audience caps what it says;
874	- classification decides which models see the data.
875
876	## Working from another chat app
877
878	Some companies will keep their existing chat app for the whole
879	organization. Often only the engineers use g1t, or nobody does at first.
880	That has to be a good experience, not a punishment. The agents are the same
881	agents wherever you talk to them, and the work lands in the same place.
882	g1t earns the move over time by being better, never by making the
883	integration worse.
884
885	User-facing text calls this "the chat app integration" and, on its
886	integration page, by the app's own name. Marketing never compares the two.
887
888	### One agent, many places
889
890	Where a conversation happens is just a surface. Each surface has an
891	adapter in `services/integrations`:
892
893	- g1t Chat;
894	- a connected chat app;
895	- later, email.
896
897	Everything else is shared, whichever surface a message arrived on:
898
899	- the agent;
900	- its memory;
901	- its tasks;
902	- its budget;
903	- its claims;
904	- the audit log.
905
906	- Every external conversation has a home in g1t. When an agent is used
907	in an external channel or DM, g1t keeps a linked conversation: the
908	messages the agent was given or posted, with permalinks back. Tasks,
909	issues and pull requests link to it like any thread. "Why was this
910	changed?" leads back to the external thread. The agent's memory learns
911	from it the same way.
912	- A task started in one place can be followed from either. A task
913	started in the external app posts its updates there. Its live card,
914	session and diff are one click away in g1t. Steering works from both:
915	- a reply in the external thread;
916	- a message on the task in g1t.
917	- Approvals settle everywhere. An approval is a button in the external
918	message, a card in g1t and an item in the inbox. Acting in any one
919	settles all three.
920
921	### The app in their chat
922
923	The workspace installs one app into its external chat workspace from
924	Integrations. The app's name is g1t.
925
926	- Each agent speaks as itself. Messages are posted with the agent's
927	name and avatar.
928	- Mention the app and name the agent: "@g1t ask @reviewer to look at
929	#418".
930	- Or use a shortcut per agent: `/g1t reviewer …`.
931	- In the app's DM, a picker chooses which agent you are talking to.
932	- Invite it to a channel to let agents answer there when mentioned.
933	Turn on listening to let a triage agent group feedback, the same as in
934	g1t (see [Agents that listen](#agents-that-listen)).
935	- Cards render natively in the external app: tasks, pull requests,
936	checks, deploys and approvals, with buttons. "Open in g1t" goes to the
937	full view.
938	- Bridged channels (optional). Link an external channel to a g1t
939	channel and the two mirror each other: messages, threads, edits and
940	reactions. Engineers stay in g1t while the rest of the company stays
941	where it is, in one conversation. Each message shows where it came from.
942
943	### Who is asking
944
945	The rules from [The whole company](#the-whole-company) apply unchanged.
946	They depend on knowing who the person is.
947
948	- Linked people. The first time someone talks to an agent from the
949	external app, the agent asks them to link their account: one click to
950	sign in to g1t. From then on they act with their own g1t access.
951	- Unlinked people are treated as members without Code access:
952	- they can ask questions and get answers from Docs;
953	- their change requests become intake;
954	- they never get code changed, or see code an agent wouldn't show
955	them.
956
957	Owners can require linking before an agent answers at all.
958	- Audience. In an external channel, the audience is everyone in that
959	channel. Agents answer there with only what all of its linked members
960	can see, and treat unlinked members as having no Code access. Private
961	g1t content stays out of external channels unless an owner allows it
962	for that channel.
963	- Data. Messages from the external app are stored only as part of
964	linked conversations, under the workspace's retention and classification
965	rules. Files shared there follow the same model-routing rules as
966	uploads.
967
968	### Why people move over anyway
969
970	The external app gets the agents, the answers and the approvals. g1t
971	keeps what only it can do:
972
973	- live task cards with sessions and diffs you can steer;
974	- the one timeline where replying is commenting on a pull request;
975	- Docs side by side with the conversation;
976	- presence that shows what every agent is doing;
977	- no limit on history or seats.
978
979	These are pointed to in context with "Open in g1t", never with nags.
980
981	### Build
982
983	The adapter interface comes with the agents service now. Replies read a
984	conversation and post through a surface port, so the external app is one
985	more adapter later, not a rewrite.
986
987	The app itself ships after Chat and tasks, in this order:
988
989	1. install;
990	2. agents speaking as themselves;
991	3. account linking;
992	4. linked conversations;
993	5. approvals;
994	6. bridged channels;
995	7. listening.
996
997	## Model routing
998
999	Nobody picks a model to get work done. g1t routes each step of an agent's
1000	work to the tier it needs, using today's `AGENT_ROUTING`:
1001
1002	\| Step \| Tier \|
1003	\| --- \| --- \|
1004	\| Chat replies, triage \| small \|
1005	\| Implementation, routine review \| large \|
1006	\| Planning, hard reviews, retries after a failure \| frontier \|
1007
1008	As today, routing steps up after failures and steps back down when the
1009	cheaper tier worked.
1010
1011	The agent definition limits the routing; it does not replace it:
1012
1013	- Floor. For example, "never below large" for a reviewer that must be
1014	careful.
1015	- Ceiling. For example, "never frontier" for a cheap triage agent.
1016	- Providers. Which models it may use: g1t's hosted models, the
1017	workspace's own providers from Integrations (Anthropic, OpenAI,
1018	compatible endpoints), or both. When the workspace has its own providers,
1019	each tier maps to a provider and model in the workspace's routing
1020	settings. An agent restricted to the workspace's own keys never touches
1021	g1t's.
1022	- Pinned model. An advanced escape hatch for own endpoints. Not shown
1023	by default.
1024
1025	Every step records the model that ran. It is shown in the session and on
1026	the agent's Spend tab, so routing is visible without anyone having to
1027	choose.
1028
1029	## Pricing
1030
1031	This follows the standing pricing rule: measured cost plus a modest,
1032	uniform overhead, and no seats.
1033
1034	\| What \| How it is charged \|
1035	\| --- \| --- \|
1036	\| People chatting: messages, threads, reactions, read state, live delivery \| Included on every plan, the free plan too. It costs very little (a message is a few row writes and one Durable Object request; idle sockets hibernate). History is never cut off. It is still metered raw, so the daily reconciliation sees the real cost. \|
1037	\| Docs: pages, editing, history \| Included on every plan, like chat. \|
1038	\| An agent replying in chat \| Agent tokens from the AI credit wallet: provider price plus the g1t agent rate. Charged to that agent's budget and, inside a task, to the task. \|
1039	\| An agent's sessions \| Agent tokens as above, plus sandbox time at cost +20%. \|
1040	\| An agent's model calls on the workspace's own provider \| The provider bills the workspace directly. g1t charges the agent rate only. \|
1041	\| Files in chat and docs \| The storage meter (served from g1tusercontent.com), at cost +20%. \|
1042	\| Calls and huddles (later) \| Media relay at cost +20%. \|
1043	\| Idle agents \| Nothing. \|
1044
1045	Free workspaces get chat and docs with protective caps: a file storage
1046	cap, and no agents until the workspace buys AI credit. That keeps the free
1047	plan free of compute.
1048
1049	## Rails, summarized
1050
1051	\| Concern \| Decided by \|
1052	\| --- \| --- \|
1053	\| What an agent can see \| Its scopes, and the channels and spaces it was invited to. An invite grants read, never write. \|
1054	\| What it can change \| Its scopes, then rulesets, branch protection and environment rules. \|
1055	\| When it must ask \| Its autonomy settings plus policy. Approvals are cards in the thread and items in the inbox; acting in either settles both. \|
1056	\| What it can spend \| Workspace, then agent, then task, then session. \|
1057	\| Who did what \| The audit log. Every action records the agent, its definition version, the task, and the person who asked. \|
1058	\| Not colliding \| Claims, the coordinator and the merge queue. \|
1059	\| Not looping \| Hop limits, addressed-only replies, rate limits, shared budgets. \|
1060
1061	## Shell
1062
1063	A rail on the left, as in the mockups: Home, Code, Chat, Docs, Agents,
1064	Inbox, then the account.
1065
1066	- The workspace's avatar (its switcher) sits at the top of the rail in the
1067	top bar's line: the same height, rule and colour as the top bar, so it
1068	reads as part of it, as the mode's sidebar heading does.
1069	- The landing page's product tour (`components/product-tour.tsx`) is a
1070	miniature of this shell, not a different one: the same rail and order,
1071	each mode's sidebar with its real sections and words, the same top bar,
1072	the app's own cards and avatars. A change to the shell changes the tour
1073	in the same change.
1074
1075	- Each mode has its own sidebar, and no mode's sidebar lists another mode's
1076	things.
1077	- Code keeps today's sidebar.
1078	- A side dock shows the current project's or page's linked channels in Code
1079	and Docs, and the linked project and docs in Chat. The dock links out to
1080	Docs; Code never grows a Docs tab of its own.
1081	- g1t's own public pages (a profile at `/u/<name>`, Explore, Search, the
1082	trust pages) belong to no workspace: `modeOf` calls them `site`, no mode
1083	is lit and no mode's sidebar opens; the page has the width. A visitor
1084	sees a profile, Explore and Search in the public frame (top bar and
1085	footer, no sidebar; `usesAppShell` in `lib/chrome.ts`). A project page
1086	keeps its sidebar for everyone, since its menu is how you move around it.
1087
1088	Concretely:
1089
1090	- `shell.tsx` gains a `mode` above today's drill-down stack;
1091	- `workspace-nav.ts` gains a `ModeKey`;
1092	- each mode keeps its own `SidebarKey`s.
1093
1094	## Cards
1095
1096	What agents post in chat is something you act on where you read it, not a
1097	link to somewhere else. A card has a title, a state, a short preview,
1098	labelled facts, and up to five actions. Links just open a place; every
1099	other action goes to the service that owns the card (`owner`, today
1100	`agents`), which checks the person may, acts as them, and updates the card
1101	in place for everyone in the conversation.
1102
1103	\| Card \| Actions \|
1104	\| --- \| --- \|
1105	\| A session, working \| Message (it reads it at its next step), Stop (asks first), Open \|
1106	\| A session at its cap \| Approve more with the new cap inline (owners), Stop, Open \|
1107	\| A session, done \| Its report as the preview; Follow up (it picks up again with its context), Open \|
1108	\| A draft issue \| File issue (filed as whoever presses it, only where they can read), Discard (whoever asked, or an owner) \|
1109
1110	Rules, in code: chat checks the person can read the conversation and that
1111	the card offers the action; the owner checks everything else. An action
1112	that needs a value (an amount, a line of text) asks for it inline. Agents
1113	never file, approve or stop anything on their own through a card.
1114
1115	From a notification. A notification about a card carries
1116	`card: { channel_id, message_id, actions }` (`FeedNotification.card`), and
1117	pressing one of those actions sends the same `card_action` as the card.
1118
1119	- Chat attaches it to any notification about a message whose card has an
1120	owner and something to press, and an agent's card that asks someone to
1121	act (a primary action: File issue, Approve more) notifies whoever asked
1122	the agent as `agent_waiting`, if they are in the conversation.
1123	- The agents service sends `approval` (a session at its cap) with the
1124	session card's place and actions.
1125	- The toast shows the actions (amounts inline, confirmations inline); the
1126	inbox panel lists Waiting on you in chat: the newest notification per
1127	card from the last day, until it is acted on in that tab.
1128	- A push has buttons only for actions with no input (two at most: Stop,
1129	Open, File issue, Discard). The service worker posts `card_action` with
1130	the person's session and shows the answer as a notification.
1131	- A thread's first page carries `root`, the message it is under, however
1132	long the thread is, so a session's live card stays at the top of its
1133	thread panel.
1134
1135	## Live notifications
1136
1137	A DM has to reach someone wherever they are in g1t, not only inside Chat.
1138	Nothing polls: one socket per tab carries everything live.
1139
1140	- One feed per person (`services/notify`): a Durable Object named by
1141	their user id, holding a socket per open tab (WebSocket hibernation), their
1142	last 100 notifications, unread counts per conversation, push subscriptions
1143	and preferences, in its own SQLite storage.
1144	- The socket. Every page of a signed-in person opens
1145	`wss://<site>/-/live?workspace=<slug>`. The site checks the session, reads
1146	the workspace's counts from chat and the inbox, and forwards the upgrade.
1147	The feed sends `counts` (`chat_unread`, `chat_mentions`, `inbox_unread`,
1148	`per_channel`) on connect and after every change, so the rail's badges,
1149	the Chat sidebar's counts and the tab's "(3) …" all move at once in every
1150	tab. A tab pings every 25 s and says when it gains or loses focus; while
1151	the socket is down it reconnects with jittered backoff, and only then does
1152	the Chat sidebar fall back to a slow refresh.
1153	- Who is told. Chat tells the feed of every message: everyone in the
1154	conversation has their counts moved, and a notification goes to everyone
1155	else in a DM, to whoever is @mentioned, and to the people in a thread
1156	that gets a reply (unless they muted the conversation; DMs and mentions
1157	come through a mute). Reading a conversation, or writing in it, sets its
1158	counts in every tab. The events service tells the feed of every new inbox
1159	item (agents waiting on you, reviews asked of you, mentions), and of the
1160	inbox count after items arrive or are marked anywhere: the site, the API
1161	or MCP.
1162	- Toasts. Bottom right on a computer, along the top on a phone; three
1163	at most, six seconds each, held while the pointer or keyboard is on them;
1164	a DM or mention has a reply box. None for the conversation already open.
1165	An optional soft sound, off by default.
1166	- Browser push (Web Push, VAPID): sent only when no tab is in front of
1167	the person. g1t never asks for permission on load: after the first DM or
1168	mention toast it offers "Get notified when someone messages you", once;
1169	a no is kept. The service worker (`public/sw.js`) shows one notification
1170	per conversation and, on a click, focuses an open tab or opens one.
1171	- Preferences (Settings → Notifications): everything, direct messages
1172	and mentions (the default), or nothing, with a level per workspace; this
1173	browser's notifications on or off; the sound; a test.
1174
1175	## Presence and status
1176
1177	Whether someone is here, and what they say about themselves, shown
1178	wherever a person is: DMs in the Chat sidebar, cards over names, member
1179	lists, the People page, after their name on their messages. Live over the
1180	same socket as notifications; nothing polls.
1181
1182	- Presence is worked out by the person's feed (`services/notify`,
1183	`src/presence.ts`) from their open tabs: `active` while any tab has had
1184	input in the last 10 minutes (each tab says when it goes idle or comes
1185	back, in its `state` frame), `away` when every tab is idle or they set
1186	themselves away, `offline` when no tab is open (after 30 seconds, so a
1187	reload or a switch of workspace is not leaving).
1188	- Status: an emoji, a few words and `clear_at`. Presets: In a meeting,
1189	Commuting, Focusing, Out sick, On vacation. Clear after 30 minutes, an
1190	hour, 4 hours, today, this week, never or a chosen time (the browser
1191	turns these into an instant in the person's own time).
1192	- Do Not Disturb (`dnd_until`): the feed toasts and pushes nothing until
1193	then; counts and the inbox still move. 30 minutes, an hour, or until 9
1194	tomorrow morning.
1195	- Source (`manual`, `calendar`, `integration`): integrations will set a
1196	status through `set_presence` with their own source. One set by hand is
1197	never replaced or cleared by them.
1198	- Where it is kept. In the person's feed (their Durable Object's
1199	SQLite), not identity's D1: it is per-person live state like the feed's
1200	sockets and preferences, the feed must read Do Not Disturb on every
1201	notification, and expiry is an alarm on that one object. Nothing about it
1202	needs a query across people.
1203	- Who hears. One room per workspace (`src/room.ts`, a Durable Object
1204	named by its slug) keeps every member's latest word. A feed tells the
1205	rooms of the workspaces its person belongs to (the site sends the list
1206	with each socket) whenever how they show changes, and when a status or
1207	Do Not Disturb runs out (an alarm). The room passes it to the feeds of
1208	the members online now, which send it to their tabs open in that
1209	workspace; a tab connecting reads everyone from its workspace's room.
1210	- Wire. `FeedEvent` gains `presence` (`people`, `full`) and `me`;
1211	`FeedClientFrame`'s `state` gains `idle`; `FeedSeed` gains `workspaces`.
1212	RPCs: `presence` and `set_presence` (`NotifyApi.presence`,
1213	`NotifyApi.setPresence`). The site's `POST /-/notify` takes
1214	`intent: "presence"` with a `PresenceChange`, always as `manual`.
1215	- Agents keep their own status (idle, working, out of budget); none of this
1216	applies to them.
1217
1218	### Desktop app
1219
1220	An Electron shell that loads the web app, so it is the same g1t, plus what
1221	only a native app can do: native notifications, the dock or taskbar badge,
1222	a tray icon with the unread count, `g1t://` deep links, a global shortcut
1223	to bring it forward, and auto-update. Its preload script exposes
1224	`window.g1tDesktop` (`notify`, `setBadge`, `openUrl`, `onNavigate`;
1225	the shape is in `apps/web/app/lib/notify-client.ts`). The web client
1226	delivers everything through a `NotificationSink` and prefers the bridge
1227	when it is there: toasts while the window is in front, native
1228	notifications while it is not, and no Web Push.
1229
1230	## Integrations directory
1231
1232	Built 2026-10-09. One catalog, `packages/contracts/src/connectors.ts`
1233	(`@g1t/contracts/connectors`), lists every connector: id, name, category,
1234	one-line description, `scopes` (`workspace`, `personal`, or both, with a
1235	`personal` override for what differs), `status` (`available` or `soon`),
1236	`href` per scope for available ones (`:workspace` is filled in), capability
1237	tags, and the integration `provider` behind it. Adding a connector, or
1238	moving one from soon to available, is an edit there plus its setup page.
1239
1240	Two pages draw from it with the same component (`components/connectors.tsx`):
1241	the workspace's `-/integrations` ("for everyone in <workspace>", owners
1242	manage) and `/settings/integrations` ("just for you, in every workspace").
1243	The workspace's setup pages for providers moved to
1244	`-/integrations/{models,alerts,trackers}`. Connected state comes from
1245	integrations (connections and their `last_error`), the GitHub App's
1246	installations, workspace webhooks, GitHub sign-in and OAuth grants.
1247
1248	Ask for this on a Soon card is a prefilled email to support for now; a
1249	stored request (workspace, connector, person) can replace it without
1250	changing the cards. The Calendar connectors will set presence with
1251	`source: "calendar"` (Presence and status, above).
1252
1253	## Services
1254
1255	Following the architecture principles: separate services, interfaces in
1256	`packages/contracts` and `crates/contracts`, side effects through
1257	`services/events`.
1258
1259	\| Service \| Owns \|
1260	\| --- \| --- \|
1261	\| `services/notify` (new, TS) \| One feed per person: live notifications and unread counts over each tab's socket, browser push (VAPID), preferences, presence, status and Do Not Disturb; one presence room per workspace. Durable Object SQLite storage, no D1. \|
1262	\| `services/chat` (new, TS) \| Channels, members, messages, threads, reactions, read state; one Durable Object per channel for live delivery with WebSocket hibernation. \|
1263	\| `services/agents` (new, TS) \| Agent definitions and versions, the desk Durable Object per agent, the coordinator Durable Object per workspace (claims), replies (the no-sandbox model loop over g1t MCP). \|
1264	\| `services/docs` (new, TS) \| Spaces, pages, the page Durable Object (Yjs), history, suggestions, comments, templates, search (FTS5), files (R2, or S3 self-hosted), citations and staleness (queue `g1t-events-docs`), projects' docs folders, `doc.page.*` events. \|
1265	\| `services/work` \| Tasks and task links beside `agent_runs` (which gains `task_id`); `agent_messages` widened to task addresses. \|
1266	\| `services/runner` \| Resumable sessions: transcript save and restore in R2, `--resume`, the steer hook reading task threads, claims checked at start and widened from diffs. \|
1267	\| `services/context` \| Indexes doc pages and channel decisions; serves them to replies and sessions. \|
1268	\| `services/events` \| New event types (`chat.message.created`, `task.`, `claim.`, `doc.page.*`); inbox reasons for mentions, approvals, suggestions, stale pages. \|
1269	\| `services/billing` \| Agent-level budgets in the reserve/settle contract; Agent-token metering for replies. \|
1270
1271	Every Cloudflare primitive used here stays behind an adapter, so
1272	self-hosting keeps working:
1273
1274	- Durable Objects;
1275	- WebSockets;
1276	- R2;
1277	- D1.
1278
1279	## Build order
1280
1281	Each step ships something usable.
1282
1283	1. Contracts. Agent definition and version, task, claim, channel,
1284	message, card, page; RPC methods; event types.
1285	2. Agents as members. `services/agents` with definitions, templates
1286	(planner, implementer, reviewer, triage, documenter) and the Agents mode
1287	list and profile. Assigning an issue to a workspace agent works through
1288	today's runner, as a task.
1289	3. Shell. The rail and modes; Chat, Docs and Agents sidebars (empty
1290	states where needed); the dock.
1291	4. Channels. `services/chat`, live delivery, threads, reactions, read
1292	state, mentions into the inbox.
1293	5. Talk to an agent. The desk; replies with no sandbox; DMs and
1294	mentions; personality applied.
1295	6. Tasks and resumable sessions. Tasks from chat; live task cards;
1296	sessions saved and resumed; steering from the thread; opening a session
1297	and taking it over; capacity and the queue.
1298	7. Budgets and approvals. Agent and task budgets in billing; approval
1299	cards that settle with the inbox.
1300	8. Coordination. The coordinator; claims on issues, branches,
1301	environments and paths; overlap negotiation in threads; widened
1302	`agent_messages`; hop and rate limits; leads.
1303	9. Docs. Spaces, pages, live editing, history, comments, mentions;
1304	indexed by context; agents reading.
1305	10. Agents in Docs. Suggestions, citations and staleness, "write this
1306	up", the documenter template, repository docs as spaces.
1307	11. Create in chat, skills and triggers. The draft-card flow; skills
1308	from a walkthrough; schedules, events, watched channels and webhooks as
1309	triggers.
1310	12. Scale and reach.
1311	- Team sections, browse, muting, and search across messages, pages and
1312	tasks.
1313	- Installable desktop and mobile apps.
1314	- Bridges for teams that keep another chat tool: one app per workspace,
1315	a handle per agent.
1316
1317	Steps 2, 5 and 6 are the turning point: from then on, talking to an agent
1318	is the everyday way work starts. Step 8 lets a workspace run many agents at
1319	once safely. Step 10 is where Docs stops being a wiki and becomes the
1320	thing that keeps itself true.
1321
1322	## Decisions to confirm
1323
1324	- Model choice on the agent. Per-agent preferred models, set when the
1325	agent is defined, with Auto as the default. Choosing a model when
1326	assigning work stays out.
1327	- Replies without a sandbox. Chat answers come from a Worker-side model
1328	loop, not a container. Recommended for speed and cost.
1329	- Docs stored in git. Decided against for now: D1 + a Durable Object
1330	per page, with Markdown export (see "How it is stored").
1331	- Agent edits to docs are suggestions by default. Built: a space's
1332	managers can set "Agents in this space" to edit directly, which applies
1333	only where the person the agent acts for can edit.
1334	- Default capacity of 3 concurrent tasks per agent, and a hop limit
1335	of 6.