game-ci · frostebite · Aug 17, 2026 · Aug 18, 2026 · Aug 22, 2026 · Aug 22, 2026
diff --git a/docs/03-github-cli/02-build.mdx b/docs/03-github-cli/02-build.mdx
diff --git a/docs/03-github-cli/03-remote-builds.mdx b/docs/03-github-cli/03-remote-builds.mdx
@@ -6,6 +6,15 @@ slug: /cli/remote-builds
 
 # Orchestrated Jobs
 
+:::info Core stays lean — advanced capability lives here
+`game-ci build`, `game-ci test`, and `game-ci activate` are deliberately thin, engine-invocation
+wrappers and stay that way on purpose. Caching, retry/recovery, extensibility hooks, and wrapping
+the engine's own process launch are `orchestrate`'s job, not core's — see
+[Orchestrate: advanced topics](./orchestrate-advanced) for [local caching](./orchestrate-advanced/local-caching),
+[middleware/hooks](./orchestrate-advanced/middleware), [build retry](./orchestrate-advanced/build-retry),
+and the [engine launch wrapper](./orchestrate-advanced/launch-wrapper).
+:::
+
 `game-ci orchestrate` schedules a provider-backed engine job. Providers can run standard builds, test
 workflows, custom engine commands, or a fully custom job definition.
 
@@ -37,58 +46,93 @@ package determines the command surface.
 | Direct standalone Orchestrator provider execution      | `game-ci orchestrate`                |
 | Executable provider protocol integration               | `game-ci serve` in the provider tool |
 
-## Orchestrator Plugin
+## Built-In Orchestrator
 
-The Orchestrator is the default provider backend for provider-backed execution. Load it as a CLI
-plugin:
+The Orchestrator is the default provider backend for provider-backed execution, and it ships as a
+built-in plugin — `game-ci` registers it automatically, the same way it registers the built-in
+Unity, Godot, and Unreal engine plugins. You do not need to pass `--plugin` to use
+`game-ci orchestrate` or any `--provider-strategy`:
 
 ```bash
-game-ci \
-  --plugin @game-ci/orchestrator-plugin \
-  orchestrate ./my-unity-project \
+game-ci orchestrate ./my-unity-project \
   --provider-strategy local-docker \
   --target-platform StandaloneLinux64
 ```
 
 Available Orchestrator provider types include:
 
-| Provider type     | Strategy value      | Description                                    |
-| ----------------- | ------------------- | ---------------------------------------------- |
-| Local Docker      | `local-docker`      | Run the job in Docker on the current machine.  |
-| Local System      | `local-system`      | Run directly on the current machine.           |
-| AWS               | `aws`               | Run on AWS ECS/Fargate.                        |
-| Kubernetes        | `k8s`               | Run as a Kubernetes job.                       |
-| Google Cloud Run  | `gcp-cloud-run`     | Run on Google Cloud Run.                       |
-| Azure ACI         | `azure-aci`         | Run on Azure Container Instances.              |
-| GitHub Actions    | `github-actions`    | Dispatch to a GitHub Actions workflow.         |
-| GitLab CI         | `gitlab-ci`         | Trigger a GitLab CI pipeline.                  |
-| Remote PowerShell | `remote-powershell` | Run on a remote Windows host.                  |
-| Ansible           | `ansible`           | Run through an Ansible inventory and playbook. |
-| CLI protocol      | `cli`               | Delegate to a custom provider executable.      |
-| Config-defined    | `config:<path>`     | Map lifecycle commands from YAML or JSON.      |
+| Provider type     | Strategy value          | Description                                                                              |
+| ----------------- | ----------------------- | ---------------------------------------------------------------------------------------- |
+| Local Docker      | `local-docker`          | Run the job in Docker on the current machine.                                            |
+| Local System      | `local`, `local-system` | Run directly on the current machine, no Docker. See [Local System](#local-system) below. |
+| AWS               | `aws`                   | Run on AWS ECS/Fargate.                                                                  |
+| Kubernetes        | `k8s`                   | Run as a Kubernetes job.                                                                 |
+| Google Cloud Run  | `gcp-cloud-run`         | Run on Google Cloud Run.                                                                 |
+| Azure ACI         | `azure-aci`             | Run on Azure Container Instances.                                                        |
+| GitHub Actions    | `github-actions`        | Dispatch to a GitHub Actions workflow.                                                   |
+| GitLab CI         | `gitlab-ci`             | Trigger a GitLab CI pipeline.                                                            |
+| Remote PowerShell | `remote-powershell`     | Run on a remote Windows host.                                                            |
+| Ansible           | `ansible`               | Run through an Ansible inventory and playbook.                                           |
+| CLI protocol      | `cli`                   | Delegate to a custom provider executable.                                                |
+| Config-defined    | `config:<path>`         | Map lifecycle commands from YAML or JSON.                                                |
 
 ## Local Docker
 
 ```bash
-game-ci \
-  --plugin @game-ci/orchestrator-plugin \
-  orchestrate ./my-unity-project \
+game-ci orchestrate ./my-unity-project \
   --provider-strategy local-docker \
   --target-platform StandaloneLinux64
 ```
 
 Use this when you want Orchestrator behavior, such as provider hooks and workspace services, without
 starting with a cloud account.
 
+## Local System
+
+`--provider-strategy local` (the alias `local-system` resolves to the same provider) runs the build
+directly on this machine — no Docker, no cloud account:
+
+```bash
+game-ci orchestrate ./my-unity-project \
+  --provider-strategy local \
+  --target-platform StandaloneLinux64
+```
+
+This drives the host activate → build/test → return-license step-script chain. It is comparable to
+the public CLI's classic `game-ci test --docker --local` host path, but is sourced from
+Orchestrator build parameters. The core `game-ci build` command uses Docker on Linux and Windows.
+Unlike `local-docker` (and the cloud providers above), the
+`local` strategy does not clone the repository or pull Git LFS content for you — it assumes the
+project at the invocation directory is already checked out and hydrated. That's the point of the
+strategy: it targets a persistent, self-hosted runner where the workspace already exists between
+runs, rather than a fresh container or VM.
+
+Common Local System options:
+
+| Option                    | Default | Description                                                                                                                                                                                           |
+| ------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--skip-activation`       | `false` | Skip the per-run Unity license activation/return steps. For a self-hosted runner with an already-licensed, long-lived Unity Hub session, rather than one that activates and deactivates on every run. |
+| `--engine-launch-wrapper` | empty   | Prefix the engine process with a host command such as `flock`. See [Engine launch wrapper](./orchestrate-advanced/launch-wrapper).                                                                    |
+
+The `local`/`local-system` strategy is also where the rest of the advanced, self-hosted-runner
+surface lives:
+
+- **[Local caching](./orchestrate-advanced/local-caching)** — persist the Unity `Library` folder and
+  Git LFS objects across runs (`--local-cache-enabled` and friends).
+- **[Middleware and hooks](./orchestrate-advanced/middleware)** — run your own commands/containers
+  around pipeline phases (`--middleware-pipeline`, `--middleware-files`).
+- **[Build retry and recovery](./orchestrate-advanced/build-retry)** — opt-in classify/decide/retry
+  recovery for known-transient Unity build failures (`--enable-build-retry`).
+- **[Engine launch wrapper](./orchestrate-advanced/launch-wrapper)** — wrap the engine's own process
+  launch, e.g. with a launch-serialization lock (`--engine-launch-wrapper`).
+
 ## AWS
 
 ```bash
 export AWS_PROFILE=my-profile
 export AWS_DEFAULT_REGION=us-east-1
 
-game-ci \
-  --plugin @game-ci/orchestrator-plugin \
-  orchestrate ./my-unity-project \
+game-ci orchestrate ./my-unity-project \
   --provider-strategy aws \
   --target-platform StandaloneLinux64 \
   --container-cpu 2048 \
@@ -114,9 +158,7 @@ profiles, SSO sessions, and runner roles.
 ## Kubernetes
 
 ```bash
-game-ci \
-  --plugin @game-ci/orchestrator-plugin \
-  orchestrate ./my-unity-project \
+game-ci orchestrate ./my-unity-project \
   --provider-strategy k8s \
   --target-platform StandaloneLinux64 \
   --kube-config "$KUBE_CONFIG_BASE64" \
@@ -139,9 +181,7 @@ Use `--custom-job` when the provider should run commands that do not map to a bu
 or test command.
 
 ```bash
-game-ci \
-  --plugin @game-ci/orchestrator-plugin \
-  orchestrate ./my-godot-project \
+game-ci orchestrate ./my-godot-project \
   --provider-strategy local-docker \
   --custom-job '- name: godot-export
   image: barichello/godot-ci:4.3
@@ -166,13 +206,11 @@ For protocol details, see
 
 ## Config-Defined Providers
 
-When the Orchestrator plugin is loaded, provider strategies can also point at YAML or JSON provider
-configuration files:
+Because the Orchestrator is a built-in plugin, provider strategies can also point at YAML or JSON
+provider configuration files without any extra setup:
 
 ```bash
-game-ci \
-  --plugin @game-ci/orchestrator-plugin \
-  orchestrate ./my-project \
+game-ci orchestrate ./my-project \
   --provider-strategy config:./.game-ci/providers/local-shell.yml
 ```
 
@@ -183,12 +221,10 @@ format, runtime environment variables, and examples.
 
 ## Configuration Files
 
-Orchestrated jobs can load the provider plugin and common options from `.game-ci.yml`:
+Orchestrated jobs can load common options from `.game-ci.yml`:
 
 ```yaml
 cliOptions:
-  plugins:
-    - '@game-ci/orchestrator-plugin'
   providerStrategy: local-docker
   targetPlatform: StandaloneLinux64
 ```
@@ -199,5 +235,12 @@ Then the command can stay short:
 game-ci orchestrate ./my-project
 ```
 
-Provider-specific options are registered by the loaded plugin, so run with `--help` after loading
-the plugin to inspect the exact option set available in your installed version.
+Provider-specific options are registered by the built-in Orchestrator plugin, so run with `--help`
+to inspect the exact option set available in your installed version.
+
+## See Also
+
+- [Orchestrate: advanced topics](./orchestrate-advanced) — caching, middleware/hooks, build retry,
+  and the engine launch wrapper
+- [Engine commands](/docs/cli/build) — core `build`/`test`/`activate`
+- [Configuration and plugins](/docs/cli/configuration-and-plugins)
diff --git a/docs/03-github-cli/04-configuration-and-plugins.mdx b/docs/03-github-cli/04-configuration-and-plugins.mdx
diff --git a/docs/03-github-cli/04-orchestrate-advanced/00-overview.mdx b/docs/03-github-cli/04-orchestrate-advanced/00-overview.mdx
@@ -0,0 +1,28 @@
+---
+sidebar_position: 0
+sidebar_label: Why This Lives Here
+slug: /cli/orchestrate-advanced
+---
+
+# Orchestrate: Advanced Topics
+
+`game-ci build`, `game-ci test`, and `game-ci activate` stay deliberately thin: resolve the engine,
+set up the environment, run it once, activate/return a license when needed. That is a structural
+choice, not a temporary gap. It keeps the core command surface small enough to read in one sitting
+and safe to depend on.
+
+Everything on this page and its sub-pages is capability that goes beyond invoking the engine once:
+
+- **[Local caching](/docs/cli/orchestrate-advanced/local-caching)** — persisting the Unity `Library`
+  folder and Git LFS objects across runs on a self-hosted runner.
+- **[Middleware and hooks](/docs/cli/orchestrate-advanced/middleware)** — trigger-aware commands and
+  containers wrapped around pipeline phases, for extensibility without forking a provider.
+- **[Build retry and recovery](/docs/cli/orchestrate-advanced/build-retry)** — opt-in
+  classify/decide/retry recovery for known transient Unity build failures.
+- **[Engine launch wrapper](/docs/cli/orchestrate-advanced/launch-wrapper)** — wrapping the engine's
+  own process launch, not the whole build step.
+
+All of it lives under `game-ci orchestrate` (`--provider-strategy local` / `local-system`, unless
+noted otherwise) rather than on `build`/`test`/`activate`, because each one is a real behavior
+change or a standing infrastructure concern — the kind of thing you opt into deliberately for a
+specific runner or pipeline, not something every `game-ci build` invocation should carry implicitly.