(Chore): Big FT Docs Reorg

[TylerJang27]

Before	After

Migrated with the following in mind to be more hierarchical and match Merge's organization:

• Overview (new vid?)
• Getting started (update to have test collections instructions after launch)
  • Test Collections
• Flaky test detection (more details on detection time SLAs)
  • ...Each monitor
  • The importance of PR Test Results
  • Infrastructure Failure Protection
• Flaky test management
  • ...Managing detected flaky tests
  • Test labels
  • Pull request comments
  • Ticketing
• Quarantining
  • Quarantine Service Ability
• Webhooks
  • ...Slack/Teams things
  • ...ticketing things
• Agents
  • Autofix Flaky Tests
  • Autofix CI Failures
  • MCP Server (alias link to MCP reference)
• Reference
  • CLI reference
  • API reference
  • MCP reference
• Cookbooks? Agents? (TBD)

Remaining work to be done:

• Update docs and onboarding to not recommend installing the launcher
• More API and MCP love
• Test collections coming soon

[trunk-staging-io]

😎 Merged successfully - details.

[claude]

Claude finished @TylerJang27's task in 5m 13s —— View job

---

Claude Code Review

• Read PR context
• Examine the diff (77 files)
• Check renamed files for broken relative links
• Look for stale references in unchanged files
• Check summary.md and .gitbook.yaml for consistency
• Post review feedback

---

This is a substantial reorganization. I focused the review on link integrity and structural concerns introduced by the file moves. The narrative content edits look fine (titles preserved, descriptions sensible, new section README intros are short and appropriate).

I left a few inline comments on summary.md and .gitbook.yaml. The bulk of the link-rot findings are below since most of those files aren't in the diff and don't accept inline comments.

Blocking — broken relative links inside moved files

These files moved to a deeper directory but their relative links weren't updated:

flaky-tests/agents/autofix-flaky-tests.md (moved from flaky-tests/, now one level deeper)

• L11: ../setup-and-administration/github-app-permissions.md → ../../setup-and-administration/github-app-permissions.md
• L21: ./detection/README.md → ../detection/README.md
• L29 (twice on same line): ./webhooks/README.md → ../webhooks/README.md

flaky-tests/detection/infrastructure-failure-protection.md (moved from flaky-tests/)

• Last bullet: [detects flaky tests](detection/) resolves to flaky-tests/detection/detection/. Should be ./ or ../detection/ (and re-read the sentence — the page is itself under detection/ now, so this self-reference reads oddly).

flaky-tests/detection/the-importance-of-pr-test-results.md (moved from flaky-tests/)

• Last line: […](get-started/ci-providers/) → ../get-started/ci-providers/

flaky-tests/management/ticketing/{jira,linear,other-ticketing-platforms}.md (moved from flaky-tests/ticketing-integrations/, now one level deeper). Image refs were updated to ../../../.gitbook/assets/... but doc-to-doc links were not:

• jira-integration.md L83: ../dashboard.md#test-case-details → ../../dashboard.md#test-case-details
• linear-integration.md L45: same fix
• linear-integration.md L55: ../webhooks/linear-integration.md → ../../webhooks/linear-integration.md
• other-ticketing-platforms.md L21: ../dashboard.md#test-case-details → ../../dashboard.md#test-case-details

flaky-tests/reference/api-reference.md

• L11: [authenticated](../setup-and-administration/apis/#authentication) → ../../setup-and-administration/apis/#authentication

flaky-tests/reference/mcp-reference/investigate-ci-failure.md

• L9: [Autofix CI Failures](../../autofix-ci-failures.md) resolves to the now-deleted flaky-tests/autofix-ci-failures.md. Should be ../../agents/autofix-ci-failures.md.

Blocking — stale references to old paths in files NOT changed by this PR

The reorg moved several pages, but these incoming references were missed:

• .gitbook/includes/retries.md:8 — ../../flaky-tests/quarantining.md → ../../flaky-tests/quarantining/
• setup-and-administration/github-app-permissions.md:9 — ../flaky-tests/github-pull-request-comments.md → ../flaky-tests/management/github-pull-request-comments.md
• setup-and-administration/apis/README.md:13 — ../../flaky-tests/flaky-tests.md → ../../flaky-tests/reference/api-reference.md
• flaky-tests/get-started/ci-providers/circleci.md:138 — hard-coded https://docs.trunk.io/flaky-tests/uploader → https://docs.trunk.io/flaky-tests/reference/cli-reference (or rely on a redirect, see below)
• merge-queue/optimizations/README.md:30 and :33 — ../../flaky-tests/quarantining.md → ../../flaky-tests/quarantining/

Recommended — additional redirects in .gitbook.yaml

Only two redirects were added (flaky-tests → overview, and the MCP tool reference path). External docs, blog posts, and Slack history almost certainly link to the other moved top-level pages (/flaky-tests/quarantining, /flaky-tests/uploader, /flaky-tests/managing-detected-flaky-tests, /flaky-tests/test-collections, /flaky-tests/test-labels, /flaky-tests/autofix-flaky-tests, /flaky-tests/autofix-ci-failures, /flaky-tests/the-importance-of-pr-test-results, /flaky-tests/infrastructure-failure-protection, /flaky-tests/quarantine-service-availability, /flaky-tests/ticketing-integrations*, /flaky-tests/use-mcp-server*). I left a more detailed list as an inline comment on .gitbook.yaml.

Structural concerns in summary.md

• L127 [MCP Server](flaky-tests/reference/mcp-reference/README.md) under Agents points at the same target as L131 under Reference > MCP reference — the page is reachable from two TOC entries.
• L132–138 list Configuration sub-pages under Reference > MCP reference, but the files actually live at flaky-tests/agents/mcp-server/configuration/. The filesystem location and TOC location are in different sections, which makes the structure hard to maintain. Pick one home for the configuration pages.

Minor

• flaky-tests/agents/mcp-server/configuration/github-copilot-ide.md — lost its trailing newline during the rename.
• flaky-tests/detection/README.md — also missing a trailing newline (\ No newline at end of file on the diff's last hunk).
• flaky-tests/management/ticketing/README.md — missing trailing newline; also a dangling footnote definition ([^1]: with no body) at the end of the file.
• The new Detection Time section added to flaky-tests/detection/README.md says "From the time that a test with configured flake detection is uploaded, it will take at most 20 minutes for the flakiness to be detected" — small grammar tighten: "From the time a test with configured flake detection is uploaded, flakiness will be detected within 20 minutes."

---

Setting review_passed: false because the broken in-page and incoming links would ship as 404s on the published docs site.
· Branch

[claude]

Claude finished @TylerJang27's task in 3m 7s —— View job

---

Claude Code Review

• Fetch latest commits and diff
• Verify previously flagged broken in-page links
• Verify previously flagged stale references in unchanged files
• Check redirect coverage in .gitbook.yaml
• Re-check summary.md structural concerns
• Look for any new issues introduced
• Post review feedback

---

The new commit (address more comments) resolves all of the blocking issues from the prior review. Verified each one:

✅ Fixed — broken in-page relative links

• flaky-tests/agents/autofix-flaky-tests.md — ../../setup-and-administration/..., ../detection/README.md, ../webhooks/README.md all correct now
• flaky-tests/detection/infrastructure-failure-protection.md — last bullet now points to ./README.md and ../quarantining/#enable-quarantining
• flaky-tests/detection/the-importance-of-pr-test-results.md — link now uses ../get-started/ci-providers/README.md
• flaky-tests/management/ticketing/{jira,linear,other-ticketing-platforms}.md — ../../dashboard.md and ../../webhooks/... are correct
• flaky-tests/reference/api-reference.md — ../../setup-and-administration/apis/#authentication
• flaky-tests/reference/mcp-reference/investigate-ci-failure.md — ../../agents/autofix-ci-failures.md

✅ Fixed — stale incoming references

• .gitbook/includes/retries.md, setup-and-administration/github-app-permissions.md, setup-and-administration/apis/README.md, flaky-tests/get-started/ci-providers/circleci.md, merge-queue/optimizations/README.md — all updated. A repo-wide grep for the old paths in .md files now returns zero hits.

✅ Mostly addressed — additional redirects

13 of the 15 suggested redirects landed in .gitbook.yaml. Two top-level URLs are still missing — flagged inline on .gitbook.yaml (recommended, non-blocking but flaky-tests/uploader is the most-likely-externally-linked of the lot).

⚠️ Still open (non-blocking)

• summary.md L127 / L132–138 — MCP Server reachable from two TOC entries; configuration pages live in agents/ but listed under Reference > MCP reference. Both flagged inline again so you can confirm these are intentional design choices.
• flaky-tests/management/ticketing/README.md line 32 — dangling [^1]: footnote definition (no body) referenced from the Linear table cell. Renders as an empty footnote.
• Trailing newlines still missing on flaky-tests/agents/mcp-server/configuration/github-copilot-ide.md, flaky-tests/detection/README.md, flaky-tests/management/ticketing/README.md (trunk fmt would normalize).
• flaky-tests/detection/README.md — small grammar tighten on the new "Detection Time" sentence (suggestion in inline comment).

---

The previously blocking link-rot is gone, so I'm setting review_passed: true. The remaining items are polish — handle in this PR or a follow-up at your discretion.
· Branch

[github-actions]

Auto-approved: Claude code review passed.

[claude]

Claude Code Review

• Fetch latest changes
• Verify previously flagged issues
• Check for new issues
• Post review

View job run

[claude]

Claude finished @TylerJang27's task in 2m 31s —— View job

---

Claude Code Review

• Fetch latest commits and diff
• Verify previously flagged issues are still resolved
• Check for any new issues introduced
• Re-check non-blocking polish items
• Post review feedback

---

The new commit (final comments) addresses the structural concern from the prior review and adds the two missing redirects.

✅ Resolved this round

• Filesystem ↔ TOC alignment. Configuration files moved from flaky-tests/agents/mcp-server/configuration/ → flaky-tests/reference/mcp-reference/configuration/ so the on-disk location now matches the TOC. Internal links updated correctly:
  • flaky-tests/agents/autofix-ci-failures.md:17 — bearer-auth link rewritten to ../reference/mcp-reference/configuration/bearer-auth.md
  • flaky-tests/reference/mcp-reference/README.md:55-58 — config links now resolve relative to current dir
  • summary.md:132-138 — TOC entries point at the new location
• Redirects. flaky-tests/uploader → flaky-tests/reference/cli-reference.md and flaky-tests/managing-detected-flaky-tests → flaky-tests/management/managing-detected-flaky-tests.md are now present in .gitbook.yaml (lines 259, 266).
• Repo-wide grep for agents/mcp-server and flaky-tests/use-mcp-server (outside of .gitbook.yaml redirects) returns zero hits — no stale references introduced by the move.

⚠️ Still open from prior review (non-blocking polish)

• summary.md:127 — MCP Server under Agents still points at the same target as L131 under Reference > MCP reference. GitBook will render the page in two TOC slots. Fine if intentional as a cross-reference; flagging once more so it's a deliberate choice.
• flaky-tests/management/ticketing/README.md:32 — dangling [^1]: footnote with no body, referenced from the Linear table cell on L30. Renders as an empty footnote.
• Trailing newlines still missing on three files (trunk fmt would normalize):
  • flaky-tests/reference/mcp-reference/configuration/github-copilot-ide.md
  • flaky-tests/detection/README.md
  • flaky-tests/management/ticketing/README.md
• flaky-tests/detection/README.md:96 — small grammar tighten on the "Detection Time" sentence ("From the time that … it will take" → "Once a test … is uploaded, flakiness will be detected within 20 minutes").

Optional follow-up

• Now that the configuration files live under reference/mcp-reference/configuration/, the prior suggestion of redirects for flaky-tests/use-mcp-server/configuration/... (if those URLs were ever published) would point there instead of the old agents/mcp-server/configuration/ path. Worth checking whether any external links exist before adding.

---

No new issues introduced by this round of changes. Previously blocking link-rot remains resolved. Setting review_passed: true — remaining items are polish that can land in this PR or a follow-up.
· Branch

[github-actions]

Auto-approved: Claude code review passed.