# docs: keep internal guides focused on architecture · PR \#9755 · pingdotgg/t3code
[View on GitCafe](https://git.cafe/pingdotgg/t3code/pull/9755)
Repository: [pingdotgg/t3code](https://git.cafe/pingdotgg/t3code)
Visibility: public
State: merged
Source repository: pingdotgg/t3code
Source branch: trim-internal-documentation
Target branch: main
Head commit: 33a9aaeeb8f50f2cc568e1ffbcde67d0b48527ad
[Discussion and reviews](https://git.cafe/pingdotgg/t3code/pull/9755)
[Commits](https://git.cafe/pingdotgg/t3code/pull/9755/commits?format=markdown)
[Files changed](https://git.cafe/pingdotgg/t3code/pull/9755/diffs?format=markdown)
## Description
---
Internal documentation had become a second description of the code. Routine feature notes and implementation inventories made architectural decisions and important constraints harder to find.
Rewrites the internal guides around those decisions and constraints, moves setup procedures into operations runbooks, and removes redundant pages and an obsolete auth diagram. Adds documentation rules for both audiences. The only source edits update two moved-document references in desktop build errors.
Internal Markdown shrinks from 24,160 to 7,842 words, including the relocated runbooks. The user-guide rewrite follows in [#9756](https://github.com/pingdotgg/t3code/pull/9756).
Verification:
- Checked 155 local links and anchors and parsed the JSON example against this layer's tree.
- Scoped formatting, whitespace, and build-script lint checks passed.
- Both existing Linux/Windows build-prerequisite tests passed.
- No visual changes requiring screenshots.
Model: GPT-6. Harness: Codex.
> [!NOTE]
> ### Condense internal architecture docs and add operations runbooks
> - Replaces long-form internal architecture documents in `docs/internals/` with shorter, focused summaries covering only essential architecture and constraints. Removes detailed tables, protocol sequences, and reference sections from [server-updates.md](https://github.com/pingdotgg/t3code/pull/9755/files#diff-7c0f027ad66f6d1cdbd2393faaa39268ca84ae397ace112193caad8e8b9f8fd4), [providers.md](https://github.com/pingdotgg/t3code/pull/9755/files#diff-3d909027abc31a863f0c0e5ecef5aa50ac285620ad827db723eb0a4ac46d3f85), [remote.md](https://github.com/pingdotgg/t3code/pull/9755/files#diff-4345b9877559c2d27c1c76d6b4fe303a716f4cabb184e210a68cdf2271093313), [overview.md](https://github.com/pingdotgg/t3code/pull/9755/files#diff-95eab02942eab6f720bf5024761b900dae42fc0867f495ee2218e7b9e6a3f8c9), and several others.
> - Deletes [t3-connect.md](https://github.com/pingdotgg/t3code/pull/9755/files#diff-66b29665c8e001b0ae9ca92f9461d961ef7cf7e7257dce2366bcc3e69462fc4e) and [terminal-renderers.md](https://github.com/pingdotgg/t3code/pull/9755/files#diff-bfb17b026d45838c0816e0ae532c4b8436aa3769576ebace0def3805402b0b84) entirely.
> - Adds new operations runbooks: [connect-setup.md](https://github.com/pingdotgg/t3code/pull/9755/files#diff-da5f1eb8c837f484141cfa0340530a8f91fae9865f9260ac4a407e6cdf4b6288) (OAuth, passkeys, code-signing) and [development.md](https://github.com/pingdotgg/t3code/pull/9755/files#diff-d4193c695085935050d7dd7572ae2c767e26244ca27f5ae7fd015ff4c97c8ba2) (checkout, debugging, packaging).
> - Updates [AGENTS.md](https://github.com/pingdotgg/t3code/pull/9755/files#diff-a54ff182c7e8acf56acfd6e4b9c3ff41e2c41a31c9b211b2deb9df75d9a478f9) and [CONTRIBUTING.md](https://github.com/pingdotgg/t3code/pull/9755/files#diff-eca12c0a30e25b4b46522ebf89465a03ba72a03f540796c979137931d8f92055) with a documentation policy distinguishing internal architecture docs, user guides, and operations runbooks, plus rules on when to update or omit docs.
> - Reroutes cross-references in [release.md](https://github.com/pingdotgg/t3code/pull/9755/files#diff-a426703c462dd239e12f4c991868c2b2bcc70f5ff28e0b2fed4c76c2b545874b), [scripts/build-desktop-artifact.ts](https://github.com/pingdotgg/t3code/pull/9755/files#diff-384c39593c6da8887b4f03c00f763af0e3b689525d3555a9fe03fd05c808471d), [README.md](https://github.com/pingdotgg/t3code/pull/9755/files#diff-0b5ca119d2be595aa307d34512d9679e49186307ef94201e4b3dfa079aa89938), and [infra/relay/README.md](https://github.com/pingdotgg/t3code/pull/9755/files#diff-e1afb302369d186caf82880d92c36bb48ec0f0a2e499633c0bbb17006696823f) from removed internal sections to the new operations runbooks.
> - Risk: external links or bookmarks to deleted `docs/internals/t3-connect.md` or `docs/architecture/terminal-renderers.md` will 404.
>
>
>
> Macroscope summarized 33a9aae.
>
>
---
> [!NOTE]
> **Low Risk**
> Documentation-only changes with no product runtime behavior; the main downside is broken external links to removed internal pages.
>
> **Overview**
> **Documentation policy** now lives in `AGENTS.md` and `CONTRIBUTING.md`: internal docs should capture cross-boundary decisions and traps, not duplicate the code; user docs cover tasks; setup and procedures belong in `docs/operations/`.
>
> **Internal guides** (`docs/internals/*`, glossary, overview, providers, remote, connection runtime, etc.) are rewritten from long inventories into shorter constraint- and architecture-oriented pages with links into source instead of narrating implementation.
>
> **Structure cleanup** moves maintainer setup out of `docs/internals/scripts.md` (removed) into the **development runbook**, refreshes `docs/README.md` navigation, trims `apps/mobile/README.md`, and **deletes** redundant or relocated pages such as `docs/architecture/terminal-renderers.md` and `docs/internals/ci.md`. Cross-references (e.g. `CONTRIBUTING.md`, desktop build errors) point at the new runbook paths.
>
> Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit 33a9aaeeb8f50f2cc568e1ffbcde67d0b48527ad. Bugbot is set up for automated code reviews on this repo. Configure [here](https://www.cursor.com/dashboard/bugbot).