Improve Orchestrator docs structure and caching guidance

[frostebite]

Summary

• Fix Mermaid rendering by removing incompatible dependency overrides that caused visible [object Promise] output and missing diagram labels.
• Rename the Orchestrator sidebar section and add a first Introduction to Orchestrator subsection containing Introduction, GameCI vs Orchestrator, Getting Started, and Examples.
• Merge cache checkpointing/survival into Caching and structured build outputs into Storage, with links updated after the page moves.
• Rewrite the Orchestrator introduction and comparison pages for a clearer first-read path, and place CLI above API Reference.

Verification

• yarn build
• Playwright smoke check for Orchestrator intro, comparison, getting started, examples, caching, and load balancing pages: no visible [object Promise], Mermaid labels render, Introduction section precedes CLI, and CLI precedes API Reference.

Summary by CodeRabbit

• Documentation

  • Reorganized Orchestrator documentation with new introduction section covering setup and features
  • Added comparison guide between standard GameCI and Orchestrator approaches
  • Expanded caching configuration and storage documentation
  • Enhanced build services and structured output documentation
  • Added troubleshooting section for build scenarios
  • Updated navigation structure and section labels

• Chores

  • Updated dependency resolutions

[github-actions]

[coderabbitai]

Warning

Rate limit exceeded

@frostebite has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 54 minutes and 7 seconds before requesting another review.

To keep reviews running without waiting, you can enable usage-based add-on for your organization. This allows additional reviews beyond the hourly cap. Account admins can enable it under billing.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 6712f1a1-cd3a-46e3-9463-d83252558a26

📥 Commits

Reviewing files that changed from the base of the PR and between e63299c and 3eb7e6d.

⛔ Files ignored due to path filters (1)

• yarn.lock is excluded by !**/yarn.lock, !**/*.lock

📒 Files selected for processing (26)

• docs/03-github-orchestrator/01-introduction-to-orchestrator/01-introduction.mdx
• docs/03-github-orchestrator/01-introduction-to-orchestrator/02-game-ci-vs-orchestrator.mdx
• docs/03-github-orchestrator/01-introduction-to-orchestrator/03-getting-started.mdx
• docs/03-github-orchestrator/01-introduction-to-orchestrator/04-examples/01-command-line.mdx
• docs/03-github-orchestrator/01-introduction-to-orchestrator/04-examples/02-github-actions.mdx
• docs/03-github-orchestrator/01-introduction-to-orchestrator/04-examples/03-aws.mdx
• docs/03-github-orchestrator/01-introduction-to-orchestrator/04-examples/04-kubernetes.mdx
• docs/03-github-orchestrator/01-introduction-to-orchestrator/04-examples/_category_.yaml
• docs/03-github-orchestrator/01-introduction-to-orchestrator/_category_.yaml
• docs/03-github-orchestrator/01-introduction.mdx
• docs/03-github-orchestrator/02-game-ci-vs-orchestrator.mdx
• docs/03-github-orchestrator/05-api-reference.mdx
• docs/03-github-orchestrator/05-providers/09-gitlab-integration.mdx
• docs/03-github-orchestrator/07-advanced-topics/01-caching.mdx
• docs/03-github-orchestrator/07-advanced-topics/08-storage.mdx
• docs/03-github-orchestrator/07-advanced-topics/12-hot-runner-protocol.mdx
• docs/03-github-orchestrator/07-advanced-topics/13-build-output-system.mdx
• docs/03-github-orchestrator/07-advanced-topics/15-large-projects.mdx
• docs/03-github-orchestrator/07-advanced-topics/20-cache-checkpointing.mdx
• docs/03-github-orchestrator/07-advanced-topics/_category_.yaml
• docs/03-github-orchestrator/08-cli/_category_.yaml
• docs/03-github-orchestrator/_category_.yaml
• docs/09-troubleshooting/common-issues.mdx
• package.json
• versioned_docs/version-2/03-github-orchestrator/_category_.yaml
• versioned_docs/version-3/03-github-orchestrator/_category_.yaml

📝 Walkthrough

Walkthrough

This pull request restructures the Orchestrator documentation by creating a new "Introduction to Orchestrator" subdirectory, reorganizing introductory content and examples, consolidating advanced topics (merging build-output-system and cache-checkpointing into core sections), updating cross-doc relative paths to reflect deeper nesting, and updating category labels from "Github (Orchestrator)" to "Orchestrator".

Changes

Documentation Restructuring & Consolidation

Layer / File(s)	Summary
Navigation Structure docs/03-github-orchestrator/_category_.yaml, docs/03-github-orchestrator/01-introduction-to-orchestrator/_category_.yaml, docs/03-github-orchestrator/01-introduction-to-orchestrator/04-examples/_category_.yaml, versioned_docs/version-*/03-github-orchestrator/_category_.yaml	Category labels renamed from "Github (Orchestrator)" to "Orchestrator". New "Introduction to Orchestrator" section added with position: 1.0, and examples subsection position adjusted from 2.0 to 4.0 to accommodate the restructure.
Introduction Content Migration docs/03-github-orchestrator/01-introduction-to-orchestrator/01-introduction.mdx, docs/03-github-orchestrator/01-introduction-to-orchestrator/02-game-ci-vs-orchestrator.mdx	New MDX pages added under nested subdirectory replacing removed top-level files. Introduction page covers Orchestrator workflow (provision, sync, cache, build, cleanup), provider overview, and common starting points. Game-CI vs Orchestrator page provides comparison table, decision guide, and migration path.
Example Documentation Updates docs/03-github-orchestrator/01-introduction-to-orchestrator/03-getting-started.mdx, docs/03-github-orchestrator/01-introduction-to-orchestrator/04-examples/01-command-line.mdx, docs/03-github-orchestrator/01-introduction-to-orchestrator/04-examples/02-github-actions.mdx, docs/03-github-orchestrator/01-introduction-to-orchestrator/04-examples/03-aws.mdx, docs/03-github-orchestrator/01-introduction-to-orchestrator/04-examples/04-kubernetes.mdx	Relative link paths updated from ../... to ../../... (or deeper) to account for increased nesting depth in restructured directory layout.
Advanced Topics Content Consolidation docs/03-github-orchestrator/07-advanced-topics/01-caching.mdx, docs/03-github-orchestrator/07-advanced-topics/08-storage.mdx, docs/03-github-orchestrator/07-advanced-topics/10-build-services.mdx, docs/03-github-orchestrator/07-advanced-topics/12-hot-runner-protocol.mdx	Sections from removed 13-build-output-system.mdx and 20-cache-checkpointing.mdx merged into caching and storage docs. Caching expanded with checkpointing, retention, workspace locking, pre-warming, and troubleshooting. Storage adds structured build outputs section. Hot runner protocol updated to reference storage/output system.
Related Documentation Updates docs/03-github-orchestrator/05-api-reference.mdx, docs/03-github-orchestrator/05-providers/09-gitlab-integration.mdx, docs/09-troubleshooting/common-issues.mdx, docs/03-github-orchestrator/07-advanced-topics/17-build-reliability.mdx	API reference adjusted with new sidebar position and updated Getting Started/CLI links. GitLab integration corrected to new command-line path. Troubleshooting expanded with "Unity exits 0 but no build" section. Build reliability adds Unity process cleanup guidance for Windows runners.
Removed Legacy Files (deleted) docs/03-github-orchestrator/01-introduction.mdx, (deleted) docs/03-github-orchestrator/02-game-ci-vs-orchestrator.mdx, (deleted) docs/03-github-orchestrator/07-advanced-topics/13-build-output-system.mdx, (deleted) docs/03-github-orchestrator/07-advanced-topics/20-cache-checkpointing.mdx	Top-level introduction and game-ci-vs-orchestrator files removed; content integrated into nested intro section. Standalone build-output-system and cache-checkpointing pages consolidated into core advanced-topics sections.
Dependency Cleanup package.json	Removed pinned mermaid@11.14.0 and dompurify@3.4.2 from Yarn resolutions, retaining only uuid@npm:^11.1.0 mapping.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• game-ci/documentation#541: Overlapping code-level changes to Orchestrator documentation files, adding/renaming introduction, providers, and advanced topics.
• game-ci/documentation#531: Related Orchestrator documentation restructuring, including Cloud Runner → Orchestrator rename and sidebar updates.
• game-ci/documentation#539: Touches the same docs/03-github-orchestrator/01-introduction.mdx with formatting and typo fixes.

Suggested reviewers

• GabLeRoux

---

🐰 Documentation blooms anew,
Paths rewoven, structures true;
Intro nested, content whole—
Orchestrator's role in scroll!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The description covers verification steps and main objectives but does not follow the provided template structure with 'Changes' section and 'Checklist' items.	Reformat the description to match the template: add a 'Changes' section with bullet points, and include the 'Checklist' with checkboxes for contribution guide, README, and tests.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes the main changes: restructuring Orchestrator documentation and improving caching guidance, matching the core content of the changeset.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/unity-ci-hardening

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[github-actions]

Visit the preview URL for this PR (updated for commit 3eb7e6d):

https://game-ci-5559f--pr558-docs-unity-ci-harden-av2dy6my.web.app

_{(expires Mon, 11 May 2026 22:39:05 GMT)}

_{🔥 via Firebase Hosting GitHub Action 🌎}

_{Sign: 1f0574f15f83e11bfc148eae8646486a6d0e078b}