Sign up
View stargazers13Sign up

docs: keep internal guides focused on architecture#9755

merged2
main
trim-internal-documentation
openedSep 4, 2026byJJulius Marminge
31 files changed
View on GitHubTwo-way sync enabledPR last imported 3d ago

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.

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

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 for commit 33a9aaeeb8f50f2cc568e1ffbcde67d0b48527ad. Bugbot is set up for automated code reviews on this repo. Configure here.

MmacroscopeappBotSep 4, 2026
Synced from GitHub

Macroscope skipped reviewing this pull request. Per-review cost limit exceeded (workspace setting).

This review would cost an estimated $12.24, which exceeds your per-review limit of $10.00.

The top 3 files driving up this estimate:

FileDiff SizeEstimate
docs/internals/providers.md32.31KB$1.62
docs/internals/product-analytics.md19.68KB$0.98
docs/internals/t3-connect.md18.63KB$0.93

Tip

To get this pull request reviewed, you can:

  1. Comment @macroscope-app on this PR to request a manual review (monthly spend limits still apply).
  2. Exclude the file(s) above from review by adding a pattern to your .macroscope/ignore.md — note that creating this file replaces Macroscope's built-in default ignores rather than extending them.
  3. Raise your cost limit in your workspace billing settings.

Turn off this reminder going forward

Ggithub-actionsBotSep 4, 2026
Synced from GitHub

Thread transfer impact

✅ Thread transfer remains within every enforced ceiling.

ProviderMetricMain baselineThis PRImpactPR ceiling
CodexTotal thread wire13.6 KiB13.6 KiB−21 B (−0.2%)15.1 KiB✅
CodexThread snapshot wire7.0 KiB7.0 KiB+4 B (+0.1%)7.3 KiB✅
CodexLive turn WebSocket wire6.6 KiB6.5 KiB−25 B (−0.4%)7.8 KiB✅
CodexLive turn WebSocket decoded57.1 KiB57.0 KiB−44 B (−0.1%)66.4 KiB✅
CodexLive turn messages109−1 (−10.0%)21✅
ClaudeTotal thread wire13.6 KiB13.5 KiB−60 B (−0.4%)15.1 KiB✅
ClaudeThread snapshot wire7.0 KiB7.0 KiB+1 B (+0.0%)7.3 KiB✅
ClaudeLive turn WebSocket wire6.6 KiB6.5 KiB−61 B (−0.9%)7.8 KiB✅
ClaudeLive turn WebSocket decoded57.9 KiB57.8 KiB−44 B (−0.1%)66.4 KiB✅
ClaudeLive turn messages109−1 (−10.0%)21✅

Baseline: f6db420 · PR result: 33a9aae · Source CI: success

Scenario and decoded snapshot size

10 historical turns, 5 command tools per turn, 878.9 KiB retained MCP result per historical turn, and a 1.05 MiB retained result in the measured turn.

  • Codex decoded thread snapshot: 113.8 KiB
  • Claude decoded thread snapshot: 114.5 KiB

Updated in place by a trusted workflow. PR artifacts are strictly validated and never executed.

MmacroscopeappBotSep 4, 2026
Synced from GitHub

Approvability

Verdict: Would Approve

Macroscope's review found this PR approvable — This PR reorganizes and condenses internal and operational documentation, adds replacement runbooks, and updates documentation links. The sole code change only changes build prerequisite error text; production runtime behavior and product defaults remain unchanged.

Not approved because:

  • Per-review cost limit exceeded (workspace setting). Approvability relies on correctness review in order to determine eligibility

No code changes detected at 33a9aae. Prior analysis still applies.

Review your spending limits in Billing settings, or comment @macroscope-app review this PR to bypass the limit and review now. You can add or adjust custom eligibility rules. Learn more.

Added 2 commits

  • docs: distinguish browser WebSocket authentication33a9aae
  • docs: keep internal guides focused on architectureaf04aae