docs: update test-tier docs for PerformanceTests + perf.yml split

Reflects the project layout from this PR in the docs:

  CLAUDE.md
    - Adds tests/Terminal.Gui.Editor.PerformanceTests to the test
      runner list, with the -c Release note + perf.yml pointer.
    - "Testing tiers": now four projects with a workflow + OS column;
      adds the "Performance gates" subsection that explains the two
      layers (stopwatch smoke + BenchmarkDotNet baseline) and calls
      out the `--job short` lowercase requirement.

  specs/constitution.md
    - §VI "Testing Tiers" table grows the fourth row + workflow + OS
      matrix columns. Adds rationale for ubuntu-only and the manual
      workflow_dispatch path for baseline.json refreshes.

  specs/plan.md
    - Repo-layout block adds tests/Terminal.Gui.Editor.PerformanceTests
      and a benchmarks/ subtree. EditorBenchmarks placeholder removed
      (it's not in the tree).
    - DoD checkbox updated from "three test projects" to "four", with
      the BenchmarkDotNet 3× baseline gate called out.

  README.md
    - Repo-layout adds benchmarks/ + examples/ rows.
    - Build block adds the PerformanceTests run line, with the
      ubuntu-latest-only / perf.yml pointer.

No behavior change; this is the doc tail of perf-suite-split.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: tig

.github/workflows/perf.yml

@@ -42,12 +42,12 @@ jobs:
           dotnet-quality: 'preview'
 
       - name: Restore
-        run: dotnet restore Terminal.Gui.Text.slnx
+        run: dotnet restore Terminal.Gui.Editor.slnx
 
       # Smoke tests are stopwatch-based (PerformanceSmokeTests.cs) — Release config matters
       # because Debug-mode timings would force the thresholds to be useless.
       - name: Build (Release)
-        run: dotnet build Terminal.Gui.Text.slnx -c Release --no-restore
+        run: dotnet build Terminal.Gui.Editor.slnx -c Release --no-restore
 
       - name: Terminal.Gui.Editor.PerformanceTests (smoke)
         run: dotnet run -c Release --project tests/Terminal.Gui.Editor.PerformanceTests --no-build

CLAUDE.md

@@ -38,8 +38,13 @@ Tests are xUnit.v3 and run as **executables** (each test project sets `<OutputTy
 dotnet run --project tests/Terminal.Gui.Editor.Tests
 dotnet run --project tests/Terminal.Gui.Editor.Tests
 dotnet run --project tests/Terminal.Gui.Editor.IntegrationTests
+dotnet run --project tests/Terminal.Gui.Editor.PerformanceTests -c Release
 ```
 
+The `PerformanceTests` project is stopwatch-based and only meaningful in Release. It runs in
+the dedicated `.github/workflows/perf.yml` workflow (ubuntu-latest only), separately from the
+correctness-focused `ci.yml`. See the "Testing tiers" section below.
+
 Run a single test by passing xUnit.v3 filter args after `--`:
 
 ```sh
@@ -165,16 +170,25 @@ private void ExtendCaretBy (int delta)
 
 ## Testing tiers
 
-Three test projects, mirroring Terminal.Gui's convention. **All three run fully in parallel** — Terminal.Gui's `Application` lifetime is per-instance (`Application.Create()` returns an `IApplication` whose `Init`/`Begin`/`End`/`Dispose` track via `ThreadLocal<>`, not process globals). Tests must never call the static `Application.Init()` shortcut, and must never enable `ConfigurationManager` (`CM.Enable(...)`) — both reach for process-global state and would force serialization.
+Four test projects, mirroring Terminal.Gui's convention. **The correctness projects all run fully in parallel** — Terminal.Gui's `Application` lifetime is per-instance (`Application.Create()` returns an `IApplication` whose `Init`/`Begin`/`End`/`Dispose` track via `ThreadLocal<>`, not process globals). Tests must never call the static `Application.Init()` shortcut, and must never enable `ConfigurationManager` (`CM.Enable(...)`) — both reach for process-global state and would force serialization.
 
-- `Terminal.Gui.Editor.Tests` — pure, no UI, no static state. Target ≥90% coverage.
-- `Terminal.Gui.Editor.Tests` — visual-line builder, wrap, caret/selection math, command handlers — anything that doesn't need an `IApplication`. Target ≥75%.
-- `Terminal.Gui.Editor.IntegrationTests` — full key-input → render scenarios via `AppFixture<T>`, which boots a per-test `IApplication` from `Application.Create()`. Parallel by default.
+- `Terminal.Gui.Editor.Tests` — pure, no UI, no static state. Target ≥90% coverage. Runs in `ci.yml`.
+- `Terminal.Gui.Editor.IntegrationTests` — full key-input → render scenarios via `AppFixture<T>`, which boots a per-test `IApplication` from `Application.Create()`. Parallel by default. Runs in `ci.yml`.
+- `Terminal.Gui.Editor.PerformanceTests` — stopwatch-based perf smoke tests. **Release only, ubuntu-latest only.** Lives in its own project and its own workflow (`.github/workflows/perf.yml`) because Windows/macOS GitHub-hosted runners are too noisy for wall-time assertions. The BenchmarkDotNet suite in `benchmarks/` runs from the same workflow.
 
-New tests default to the parallel-by-name project. Promote to `IntegrationTests` only when an `IApplication` (driver, input injection, full layout/draw) is genuinely needed.
+New tests default to the parallel-by-name project. Promote to `IntegrationTests` only when an `IApplication` (driver, input injection, full layout/draw) is genuinely needed. Promote to `PerformanceTests` only when you need a wall-time assertion — and remember it won't run on Windows/macOS CI, so don't put correctness checks there.
 
 **The one allowed exception:** a test that legitimately mutates a process-global (e.g. `Logging.Logger`, `Trace.EnabledCategories`, anything `static`) must opt out of cross-collection parallelism via a `[CollectionDefinition(name, DisableParallelization = true)]` + `[Collection(name)]` pair. See `tests/Terminal.Gui.Editor.IntegrationTests/HostingTests.cs` for the canonical example. Do **not** add an assembly-wide `xunit.runner.json` to make the whole project serial — that's the wrong tool for one offending class.
 
+### Performance gates
+
+Two layers, both in `.github/workflows/perf.yml`:
+
+1. **`Terminal.Gui.Editor.PerformanceTests`** — stopwatch smoke tests with deliberately loose thresholds (~5× typical wall time). They catch catastrophic regressions, not 10% drift.
+2. **`benchmarks/compare-baseline.sh`** — runs the focused `*VisualLineBuild*` BenchmarkDotNet filter and compares against `benchmarks/baseline.json`. Fails on >3× regression, celebrates on <0.8× improvement. **Run `--job short`** (lowercase) — `ShortRun` makes BDN reject it and the comparison silently no-ops.
+
+The full BenchmarkDotNet matrix (`Scrolling`, `EndToEndScroll`, `CaretMovement`, `DocumentAccess`) is opt-in via `workflow_dispatch` on the perf workflow with `full-suite: true`. That's the operator path for refreshing `baseline.json` — run, download artifact, commit the numbers.
+
 ### Diagnosing parallel-test hangs
 
 When integration tests run individually but hang when run as a suite, **the cause is almost always shared mutable state, not the parallelism itself**. Do not reach for `xunit.runner.json` with `parallelizeTestCollections: false` to "fix" it — that hides the bug and slows the suite. Walk this checklist instead:

README.md

@@ -18,10 +18,11 @@ Pre-alpha — see [`specs/00-plan.md`](specs/00-plan.md) for the full implementa
 ## Repository layout
 
 ```
-specs/      Planning and design docs
-src/        Terminal.Gui.Editor library (document layer + Editor view)
-tests/      xUnit.v3 test projects
-examples/   ted — standalone demo app
+specs/        Planning and design docs
+src/          Terminal.Gui.Editor library (document layer + Editor view)
+tests/        xUnit.v3 test projects (correctness + perf smoke)
+benchmarks/   BenchmarkDotNet suite + CI baseline
+examples/     ted — standalone demo app
 ```
 
 ## Build
@@ -31,8 +32,14 @@ Requires the .NET 10 SDK (preview).
 ```sh
 dotnet restore Terminal.Gui.Editor.slnx
 dotnet build   Terminal.Gui.Editor.slnx
+
+# Correctness suites — run on every push/PR across ubuntu/macos/windows.
 dotnet run --project tests/Terminal.Gui.Editor.Tests
 dotnet run --project tests/Terminal.Gui.Editor.IntegrationTests
+
+# Perf smoke + BenchmarkDotNet baseline gate — ubuntu-latest only in CI
+# (.github/workflows/perf.yml). Run locally in Release config.
+dotnet run --project tests/Terminal.Gui.Editor.PerformanceTests -c Release
 ```
 
 Run the demo:

specs/constitution.md

@@ -137,17 +137,19 @@ The fork is **hard** — re-syncs are manual and deliberate, triggered only by u
 
 ## VI. Testing Tiers
 
-Three test projects mirroring Terminal.Gui's convention:
+Four test projects mirroring Terminal.Gui's convention:
 
-| Project | Parallel | Purpose | Coverage Target |
-|---------|----------|---------|-----------------|
-| `Terminal.Gui.Editor.Tests` | ✅ | Pure, no UI, no static state | ≥ 90% |
-| `Terminal.Gui.Editor.Tests` | ✅ | Visual-line builder, wrap, caret/selection, commands | ≥ 75% |
-| `Terminal.Gui.Editor.IntegrationTests` | ✅ | Full key-input → render via `AppFixture<T>` (per-test `IApplication.Create()`) | Informational |
+| Project | Workflow | OS matrix | Purpose | Coverage Target |
+|---------|----------|-----------|---------|-----------------|
+| `Terminal.Gui.Editor.Tests` | `ci.yml` | ubuntu, macos, windows | Pure, no UI, no static state | ≥ 90% |
+| `Terminal.Gui.Editor.IntegrationTests` | `ci.yml` | ubuntu, macos, windows | Full key-input → render via `AppFixture<T>` (per-test `IApplication.Create()`) | Informational |
+| `Terminal.Gui.Editor.PerformanceTests` | `perf.yml` | ubuntu only, Release only | Stopwatch perf smoke tests + BenchmarkDotNet baseline gate | Wall-time guards |
 
-The lone exception: a class that mutates a process-global static (e.g. `HostingTests`) opts out of cross-collection parallelism via `[CollectionDefinition(..., DisableParallelization = true)]` + `[Collection(...)]`. Never disable parallelism at the assembly level.
+The three correctness projects run **in parallel** within each assembly. The lone exception: a class that mutates a process-global static (e.g. `HostingTests`) opts out of cross-collection parallelism via `[CollectionDefinition(..., DisableParallelization = true)]` + `[Collection(...)]`. Never disable parallelism at the assembly level.
 
-Tests run as **executables** (xUnit.v3): `dotnet run --project tests/<project>`.
+`PerformanceTests` lives in its own workflow because Windows / macOS GitHub-hosted runners share hosts with neighbour VMs — wall-time assertions there are too noisy to gate on. Ubuntu runners are still noisy but consistent enough that a >3× BenchmarkDotNet baseline ratio is a real signal. The full BenchmarkDotNet matrix runs only on `workflow_dispatch` (`full-suite: true`); that's the operator path for refreshing `benchmarks/baseline.json`.
+
+Tests run as **executables** (xUnit.v3): `dotnet run --project tests/<project>`. `PerformanceTests` always runs with `-c Release`.
 
 ## VII. Coding Standards
 

specs/plan.md

@@ -63,14 +63,17 @@ src/Terminal.Gui.Editor/           # the View
   Editor.cs / .Drawing / .Keyboard / .Mouse / .Selection / .Commands
   Rendering/                       # rendering pipeline types
 tests/
-  Terminal.Gui.Editor.Tests/         (parallel, pure)
-  Terminal.Gui.Editor.Tests/       (parallel, logic)
-  Terminal.Gui.Editor.IntegrationTests/  (parallel, per-test IApplication.Create())
+  Terminal.Gui.Editor.Tests/         (parallel, pure)               — ci.yml
+  Terminal.Gui.Editor.IntegrationTests/  (parallel, IApplication)  — ci.yml
+  Terminal.Gui.Editor.PerformanceTests/(stopwatch perf smoke)      — perf.yml (ubuntu, Release only)
+benchmarks/
+  Terminal.Gui.Editor.Benchmarks/      (BenchmarkDotNet suite)     — perf.yml
+  baseline.json                        (gated metrics)
+  compare-baseline.sh                  (CI compare script)
 examples/
-  ted/                             (TG demo app)
-  EditorBenchmarks/                (placeholder)
+  ted/                                 (TG demo app)
 third_party/AvaloniaEdit/
-  LICENSE  UPSTREAM.md             (commit d7a6b63 pinned)
+  LICENSE  UPSTREAM.md                 (commit d7a6b63 pinned)
 ```
 
 ## Dependencies
@@ -104,7 +107,7 @@ Each criterion is testable. This is the merge-to-`main` gate.
 
 - [ ] All features merged: drawing-overhaul, caret-anchors, read-only, find-and-replace, auto-indent, folding-ui, syntax-colorizer, word-wrap, multi-caret, clipboard.
 - [ ] `dotnet build Terminal.Gui.Editor.slnx` clean on Linux/macOS/Windows on net10.0.
-- [ ] All three test projects pass. Coverage: `Text.Tests` ≥ 90%, `Editor.Tests` ≥ 75%.
+- [ ] All test projects pass. Coverage: `Editor.Tests` ≥ 90%. `PerformanceTests` smoke tests + the `*VisualLineBuild*` BenchmarkDotNet gate stay within 3× of `benchmarks/baseline.json`.
 - [ ] `Editor.OnDrawingContent` does not iterate `text` by `char`. R1, R2, R4, R5 hold.
 - [ ] `Editor.TabWidth`, `Editor.SyntaxHighlighter`, `Editor.SyntaxLanguage` all removed.
 - [ ] No file under `src/Terminal.Gui.Editor/` references `Terminal.Gui`.