Skip to content
This repository was archived by the owner on Oct 10, 2026. It is now read-only.

Commit 9dd425b

Browse files
t3dotggclaude
andauthored
docs: split user and maintainer docs, fix 100+ stale claims (pingdotgg#4807)
Co-authored-by: Claude Fable 5 <[email protected]>
1 parent 50871eb commit 9dd425b

41 files changed

Lines changed: 1482 additions & 1400 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎AGENTS.md‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@ T3 Code has 3 key app surfaces: **web**, **desktop**, and **mobile**.
2828

2929
**Desktop** is the main surface most users install first. It's a full Electron app that bundles the server runner as well. The desktop app can also be used as the host server, allowing remote connections from app.t3.codes or the mobile app.
3030

31-
**Mobile** is a React native app for both iOS and Android. The mobile app allows for connecting to any T3 Code server to control work remotely. It is still in early access (Testflight), but it is pretty close to shipping globally.
31+
**Mobile** is a React Native app for both iOS and Android, available on the App Store and Google Play. The mobile app allows for connecting to any T3 Code server to control work remotely.
3232

3333
## A note from Theo
3434

@@ -72,7 +72,7 @@ The most common defect in this repo is a change that works on the path you teste
7272
- **Contracts.** Anything crossing the wire is typed in `packages/contracts`. Change the schema and the server, web, mobile, and desktop all follow.
7373
- **Reverse states.** If you added a way in, add the way out and the way to see it. Snooze needs unsnooze. Close needs reopen. A one-way door is a bug.
7474
- **Connection modes.** Local, remote/relay, and tunnel behave differently. Multi-device and multi-environment cases are real.
75-
- **Docs.** `docs/` mirrors this structure. Behavior changes that a user would notice belong in `docs/user/`; architecture changes in `docs/architecture/`; new vocabulary in `docs/reference/encyclopedia.md`.
75+
- **Docs.** `docs/` splits by audience. Behavior changes that a user would notice belong in `docs/user/` (shipped-product voice, no repo tooling or source paths); architecture and contributor changes in `docs/internals/`; runbooks in `docs/operations/`; new vocabulary in `docs/internals/glossary.md`.
7676

7777
## Dev servers
7878

@@ -123,13 +123,13 @@ An empty database is a bad test. Seed your worktree's `.t3` with a copy of real
123123

124124
Clients send typed WebSocket requests. The server turns them into _commands_, a pure _decider_ turns commands into persisted _events_, and a _projector_ derives the read model the UI renders. Provider CLIs run as subprocesses; per-provider _adapters_ translate their native protocols into orchestration events. Side effects run in queue-backed _reactors_ that emit _receipts_ when milestones land. Each turn ends with a _checkpoint_, a hidden git ref, so the app can diff and restore.
125125

126-
Full glossary with file links: `docs/reference/encyclopedia.md`
126+
Full glossary with file links: `docs/internals/glossary.md`
127127

128128
## Where code lives
129129

130-
- `apps/server` - WebSocket, orchestration, providers, checkpointing. Effect-heavy: read `.repos/effect-smol/LLMS.md` and `docs/operations/effect-fn-checklist.md` before writing Effect code.
130+
- `apps/server` - WebSocket, orchestration, providers, checkpointing. Effect-heavy: read `.repos/effect-smol/LLMS.md` before writing Effect code.
131131
- `apps/web` - React/Vite UI. `apps/desktop` wraps it, `apps/mobile` is React Native, `apps/marketing` is the site.
132-
- `packages/contracts` - Effect/Schema contracts. Schema only, no runtime logic.
132+
- `packages/contracts` - Effect/Schema contracts plus small derived helpers. No heavy runtime logic.
133133
- `packages/shared` - shared runtime utils, subpath exports, no barrel.
134134
- `packages/client-runtime` - client code shared by web and mobile.
135135
- `.repos/` - vendored read-only references. Prefer their patterns over invented ones. Never edit or import from them. Sync with `vpr sync:repos` when bumping the matching dependency.

‎README.md‎

Lines changed: 14 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -17,13 +17,13 @@ We wanted something performant, remote-ready, and truly open. If we ever go the
1717
>
1818
> - Codex: install [Codex CLI](https://developers.openai.com/codex/cli) and run `codex login`
1919
> - Claude: install [Claude Code](https://claude.com/product/claude-code) and run `claude auth login`
20-
> - Cursor: install [Cursor CLI](https://cursor.com/cli) and run `cursor-agent login`
20+
> - Cursor: install [Cursor CLI](https://cursor.com/cli) and run `agent login`
2121
> - Grok Build: install [Grok Build CLI](https://x.ai/cli) and run `grok login`
2222
> - OpenCode: install [OpenCode](https://opencode.ai) and run `opencode auth login`
2323
2424
### Try it out (install-free)
2525

26-
The easiest way to test T3 Code is to run the server in your terminal:
26+
The easiest way to test T3 Code is to run the server in your terminal (requires Node.js 22.16+, 23.11+, or 24.10+):
2727

2828
```bash
2929
npx t3@latest
@@ -61,17 +61,20 @@ We are very very early in this project. Expect bugs.
6161

6262
We are (mostly) not accepting contributions yet. Small fixes may be considered. Big features will not be.
6363

64-
There's no public docs site yet, checkout the miscellaneous markdown files in [docs](./docs).
65-
6664
## Documentation
6765

68-
- [Getting started](./docs/getting-started/quick-start.md)
69-
- [Remote access](./docs/user/remote-access.md)
70-
- [Keeping T3 Code in sync](./docs/user/server-updates.md)
71-
- [Architecture overview](./docs/architecture/overview.md)
72-
- [Provider guides](./docs/providers/codex.md)
73-
- [Operations](./docs/operations/ci.md)
74-
- [Reference](./docs/reference/encyclopedia.md)
66+
Full docs live in [docs/](./docs). There's no docs site yet.
67+
68+
- [Install and first run](./docs/user/install.md)
69+
- [Permission modes](./docs/user/permission-modes.md)
70+
- [Keyboard shortcuts](./docs/user/keybindings.md)
71+
- [Remote access from a phone or another machine](./docs/user/remote-access.md)
72+
- [Keeping app and server in sync](./docs/user/updating.md)
73+
- [Source control integrations](./docs/user/source-control.md)
74+
- Multiple accounts: [Codex](./docs/user/providers-codex.md) · [Claude](./docs/user/providers-claude.md)
75+
- Linux: [run T3 Code as a background service](./docs/user/background-service.md)
76+
77+
Building from source? Start at [docs/internals/overview.md](./docs/internals/overview.md).
7578

7679
## If you REALLY want to contribute still.... read this first
7780

‎docs/README.md‎

Lines changed: 41 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,41 @@
1-
# Documentation
2-
3-
- [Getting started](./getting-started/quick-start.md)
4-
- Architecture
5-
- [Overview](./architecture/overview.md)
6-
- [Connection runtime](./architecture/connection-runtime.md)
7-
- [Remote environments](./architecture/remote.md)
8-
- [Server updates](./architecture/server-updates.md)
9-
- User guides
10-
- [Background service](./user/background-service.md)
11-
- [Remote access](./user/remote-access.md)
12-
- [Keeping T3 Code in sync](./user/server-updates.md)
13-
- [Keybindings](./user/keybindings.md)
14-
- [T3 Connect](./cloud/t3-connect-clerk.md)
15-
- [Integrations](./integrations/source-control-providers.md)
16-
- [Mobile](./mobile/app.md)
17-
- [Operations](./operations/ci.md)
18-
- [Providers](./providers/codex.md)
19-
- [Reference](./reference/encyclopedia.md)
1+
# T3 Code docs
2+
3+
## Using T3 Code
4+
5+
- [Install and first run](./user/install.md)
6+
- [Permission modes](./user/permission-modes.md)
7+
- [Keyboard shortcuts](./user/keybindings.md)
8+
- [Remote access](./user/remote-access.md)
9+
- [Keeping app and server in sync](./user/updating.md)
10+
- [Source control integrations](./user/source-control.md)
11+
- [Background service (Linux)](./user/background-service.md)
12+
- Providers: [Codex](./user/providers-codex.md) · [Claude](./user/providers-claude.md)
13+
14+
Mobile app: [apps/mobile/README.md](../apps/mobile/README.md)
15+
16+
---
17+
18+
## Working on T3 Code
19+
20+
Everything below is for maintainers. Setup lives in the [root README](../README.md);
21+
policy in [CONTRIBUTING.md](../CONTRIBUTING.md); agent rules in [AGENTS.md](../AGENTS.md).
22+
23+
- [Architecture overview](./internals/overview.md)
24+
- [Workspace layout](./internals/workspace-layout.md)
25+
- [Glossary](./internals/glossary.md)
26+
- [Scripts](./internals/scripts.md)
27+
- [Connection runtime](./internals/connection-runtime.md)
28+
- [Providers](./internals/providers.md)
29+
- [Remote environments](./internals/remote.md)
30+
- [Server updates](./internals/server-updates.md)
31+
- [Resource telemetry](./internals/resource-telemetry.md)
32+
- [Environment auth](./internals/environment-auth.md)
33+
- [T3 Connect](./internals/t3-connect.md)
34+
- [CI gates](./internals/ci.md)
35+
36+
### Runbooks
37+
38+
- [Release](./operations/release.md)
39+
- [Observability](./operations/observability.md)
40+
- [Relay observability](./operations/relay-observability.md)
41+
- [Mobile app store screenshots](./operations/mobile-app-store-screenshots.md)

‎docs/architecture/connection-runtime.md‎

Lines changed: 0 additions & 140 deletions
This file was deleted.

0 commit comments

Comments
 (0)