docs: --tia not for CI

Author: nunomaduro

continuous-integration.md

@@ -181,6 +181,26 @@ Of course, you may customize the scripts above according to your requirements. F
 
 Once you have created your `.chipperci.yml` file, commit and push the `.chipperci.yml` file so Chipper CI can run your tests. Keep in mind that once you make this commit, your test suite will execute on all new commits.
 
+## The Tia Engine And CI
+
+The [Tia Engine](/docs/tia) re-runs only the tests affected by your latest changes, which makes it a wonderful companion while you work locally. On CI, however, you should not pass the `--tia` flag to the command that runs your test suite:
+
+```bash
+./vendor/bin/pest --ci        # runs the full suite on every commit
+./vendor/bin/pest --ci --tia  # replays cached results — not what you want on CI
+```
+
+Your pipeline is the place where every test runs against a clean checkout, so it should always execute the full suite. There is one exception: the dedicated workflow that records the shared baseline your team downloads. That job is separate from your test pipeline, and it is the only place `--tia` belongs on CI:
+
+```yaml
+      - name: Run tests
+        run: ./vendor/bin/pest --parallel --tia --coverage --fresh
+```
+
+For the complete workflow, including how to upload the recorded baseline as an artifact, see [Sharing The Baseline From CI](/docs/tia#sharing-the-baseline-from-ci).
+
+> **Note:** If you enable TIA in your `tests/Pest.php` file, you should use `pest()->tia()->locally()` rather than `always()`, so that TIA is skipped whenever you run Pest with the `--ci` flag.
+
 ## Sharding Your Tests
 
 If you have a large test suite, you may wish to shard your tests across multiple CI jobs to speed up execution time. Pest supports test sharding out of the box, allowing you to split your tests into smaller groups that may be run in parallel.

pest5-now-available.md

@@ -50,7 +50,7 @@ Duration: 3.92s
 
 A replay isn't a shortcut that skips work — each cached test stores everything it produced, including the exact lines and branches it covered, so a replayed run reports the same code coverage as a full run. And the dependency tree understands your whole stack: a migration change re-runs only the tests that queried that table, editing a shared JS component walks Vite's module graph to find every Inertia page that imports it, and a comment-only edit or formatter pass re-runs nothing at all. Pest detects Laravel, Symfony, Livewire, Inertia, and browser assets automatically via Composer.
 
-For teams, you may have CI record the baseline once per merge to `main` so every developer downloads the result and starts replaying immediately. To learn more, check out the [Tia Engine documentation](/docs/tia).
+The Tia Engine is built for local development, so you should keep `--tia` out of the command that runs your test suite on CI — your pipeline should always execute the full suite against a clean checkout. The one exception is a dedicated workflow that records the baseline once per merge to `main`, so every developer downloads the result and starts replaying immediately. To learn more, check out the [Tia Engine documentation](/docs/tia).
 
 <a name="the-agent"></a>
 ## The Agent Plugin

tia.md

@@ -21,6 +21,8 @@ To get started, you may add the `--tia` flag to any Pest invocation:
 
 The first run is the **baseline** — the engine enables a coverage driver (PCOV or Xdebug) and records the dependency graph as your tests execute. You may expect a small overhead on this run only.
 
+> **Warning:** The Tia Engine is built for local development, and you should not add `--tia` to the command that runs your test suite on CI. Your pipeline exists to verify every test against a clean checkout, so it should always execute the full suite — the single exception is the dedicated job that records the shared baseline, described in [Sharing The Baseline From CI](#sharing-the-baseline-from-ci).
+
 > **Note:** You don't have to pay this baseline cost on every machine. You may have CI record the baseline once and have every developer download it from GitHub Actions, so their very first `--tia` run replays immediately. See [Sharing The Baseline From CI](#sharing-the-baseline-from-ci) to set this up.
 
 Every subsequent run is a **replay**. The engine compares your working tree against the baseline and re-runs only the tests affected by your changes:
@@ -76,11 +78,11 @@ Pest supports a few flags alongside `--tia`:
 | Flag | Behavior |
 |---|---|
 | `--tia` | Replay if a baseline graph exists, otherwise record. |
-| `--no-tia` | Disable TIA for this run, even if `pest()->tia()->always()` is configured. |
+| `--no-tia` | Disable TIA for this run, even if `pest()->tia()->locally()` is configured. |
 | `--tia --fresh` | Discard any existing graph and re-record from scratch. Use this after large refactors or when the graph feels stale. |
 | `--tia --refetch` | Discard the local graph and force a fresh CI baseline fetch, bypassing the 24-hour cooldown that otherwise applies after a fetch found no baseline. |
 | `--tia --filtered` | Narrow PHPUnit to only the affected test files rather than loading all tests and replaying cached results for unaffected ones. Automatically disabled when you pass an explicit test path or a `--coverage` report; if no tests are affected, Pest stops and tells you so. |
-| `--tia --locally` | Equivalent to `pest()->tia()->always()->locally()` — run TIA automatically on local machines but skip on CI. |
+| `--tia --locally` | Equivalent to `pest()->tia()->locally()` — run TIA automatically on local machines but skip on CI. |
 | `--tia --baselined` | Opt in to fetching the shared baseline from CI when no local graph exists or the local graph drifts. |
 | `--baseline` | Print the absolute path of this project's TIA storage directory and exit. Designed for CI uploads — see [Sharing The Baseline From CI](#sharing-the-baseline-from-ci). |
 
@@ -100,6 +102,8 @@ Each enabling flag has an environment variable equivalent, useful for CI matrice
 
 Recording the baseline locally may take minutes on large suites. Instead, you may have CI record it once per merge to `main`, and every developer downloads the result.
 
+Recording the baseline is the one job where `--tia` belongs on CI. It should live in a workflow of its own — the pipeline that tests your pull requests and commits continues to run the full suite with `./vendor/bin/pest --ci`, without any TIA flags.
+
 Baseline fetching is opt-in. You may enable it with `--tia --baselined` on the command line, the `PEST_TIA_BASELINED=1` environment variable, or — preferred for teams — by calling `pest()->tia()->baselined()` in `tests/Pest.php`. Once enabled, when Pest detects no local graph (or the local graph is out of date) it uses GitHub's CLI to download the latest successful run of a `tia-baseline.yml` workflow's `pest-tia-baseline` artifact. Pest then validates the fetched graph against your project state — if it matches, it is adopted. Otherwise, it is discarded and a local rebuild proceeds.
 
 > **Note:** Baseline fetching relies on the [GitHub CLI](https://cli.github.com/) (`gh`), so it is only available for repositories hosted on GitHub, and `gh` must be installed and authenticated (`gh auth login`) on the machine doing the fetch. When a fetch cannot proceed — missing CLI, no authentication, a network or rate-limit error, or no baseline artifact yet — Pest reports the reason and falls back to recording a local baseline.
@@ -154,13 +158,24 @@ You may configure TIA behavior in `tests/Pest.php` via `pest()->tia()`:
 
 ```php
 pest()->tia()
-    ->always()     // run TIA on every invocation, no --tia flag needed
-    ->locally()    // restrict always() to local environments only
+    ->locally()    // run TIA on every local invocation, no --tia flag needed
     ->baselined()  // fetch the shared baseline from CI when no local graph exists
     ->filtered();  // narrow PHPUnit to only affected test files
 ```
 
-**`always()`** activates TIA for every `pest` run without requiring the `--tia` flag. Pair it with **`locally()`** to restrict that behavior to local machines — when you pass the `--ci` flag, TIA is skipped automatically. An explicit `--tia` on the command line always takes effect regardless, and `--no-tia` will disable it for a single run.
+Typically, you should reach for **`locally()`**. It activates TIA for every `pest` run without requiring the `--tia` flag, and restricts that behavior to local machines — on CI, or whenever you pass the `--ci` flag, TIA is skipped automatically, so your pipeline keeps running the full suite:
+
+```php
+pest()->tia()->locally();
+```
+
+Alternatively, **`always()`** activates TIA everywhere, CI included. The two are alternatives rather than a pair, so there is no need to chain them — and because the Tia Engine is built for local development, `locally()` is the option you should prefer:
+
+```php
+pest()->tia()->always();
+```
+
+In either case, an explicit `--tia` on the command line always takes effect, and `--no-tia` will disable TIA for a single run.
 
 **`filtered()`** enables filtered mode, equivalent to `--tia --filtered`. In this mode, Pest narrows PHPUnit to only the affected test files rather than loading the full suite and replaying cached results for unaffected tests: