Fixes stale/contradictory AI agent instructions; adds agent docs lint and tuirec verification guidance (#5478)

* Fix inconsistencies in AI agent instruction files

- Local function naming: camelCase -> PascalCase in REFRESH.md and
  copilot-instructions.md (matches .editorconfig local_functions_rule,
  AGENTS.md, and event-patterns.md)
- Replace stale Tests/UnitTests references with current project names
  (UnitTestsParallelizable / UnitTests.NonParallelizable) across
  AGENTS.md, CONTRIBUTING.md, .aider.md, .cursorrules, .windsurfrules,
  copilot-instructions.md, and .claude workflows/tasks
- Replace deprecated --filter "FullyQualifiedName~" syntax with xUnit v3
  MTP --filter-method/--filter-class in copilot-instructions.md
- Remove machine-local path (D:\s\...) from AGENTS.md planning section
- build-app.md: use Accepted (post-event) for fire-and-forget handlers
  per event-patterns.md; show Accepting only for cancellation; fix
  v1-style new Button ("OK") to v2 object initializer
- build-test-workflow.md: .NET SDK 8.0 -> 10.0.100 per global.json

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* Add agent docs lint, tuirec verification guidance, promote local memories

- Add Scripts/lint-agent-docs.ps1 + lint-agent-docs.yml CI workflow: fails
  when known rot patterns reappear in agent instruction files (stale test
  project names, machine-local paths, camelCase local-function guidance,
  deprecated FullyQualifiedName~ filter syntax, SDK version drift vs
  global.json). The lint immediately caught a stale .NET SDK 8.0 claim in
  CONTRIBUTING.md, now fixed.
- Wire tuirec into agent entry points (CLAUDE.md, AGENTS.md, build-app.md):
  agents can verify TUI behavior by recording with tuirec and reading the
  asciinema .cast output back as text, per Scripts/tuirec/README.md.
- Promote durable guidance from machine-specific .claude/projects/ memory
  files into shared rules (.claude/rules/logging-tracing.md and
  fragile-areas.md); untrack .claude/projects/ and gitignore it (the
  directory name encoded a local user path).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* Document Windows ConPTY sixel limitation in tuirec README

Discovered while verifying the About Box fire animation: ConPTY strips
sixel DCS and the DA1 sixel handshake, so sixel content cannot be
captured in tuirec recordings on Windows (apps detect Sixel support:
False). Added to the troubleshooting table and validation checklist so
the next agent does not burn recordings rediscovering it.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* tuirec README: require measuring grid-anchored sixels, not eyeballing

Agents (including me) recurrently verify the wrong invariant when checking
sixel recordings: confirming the sixel appears, or that agg rendered it
faithfully at the requested cursor cell, and calling it done. That misses
size/position errors — notably the ~4% undersize from tuirec advertising a
cell resolution that does not match agg's rendered font cell (tuirec #84).

Adds a "Verifying Placement and Size (measure - don't eyeball)" section with
the cell-calibration recipe (measure agg's real cell from a known grid
reference; reconcile against the resolution the app used; confirm the
rendered bbox covers the target region), a checklist item, a troubleshooting
row for #84, and rewrites the workflow's "visual confirm" step to require
measurement for grid-anchored content. Also states the general principle:
verify the invariant the change was meant to satisfy, not a proxy.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* Sync CONTRIBUTING.md TFM to net10.0; lint stale TFMs

Codex review on #5478 flagged that build-test-workflow.md cites
CONTRIBUTING.md as its source of truth, but CONTRIBUTING.md still
described the project as net8.0 (line 28) even though the Required Tools
section was updated to .NET 10 — so the declared source could revert the
fix and mislead readers onto the wrong toolchain.

Test-first: added Rule 6 to lint-agent-docs.ps1 that derives the expected
target-framework moniker from global.json's SDK major and fails on any
mismatched `net<major>.0` reference. It flagged CONTRIBUTING.md:28
(net8.0); fixed that to `C# 14 (net10.0)`. Lint now passes (32 files).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: tig

.aider.md

@@ -34,7 +34,7 @@ Terminal.Gui v2 is a **complete rewrite**. Pre-2025 training data about Terminal
 dotnet restore
 dotnet build --no-restore
 dotnet test --project Tests/UnitTestsParallelizable --no-build
-dotnet test --project Tests/UnitTests --no-build
+dotnet test --project Tests/UnitTests.NonParallelizable --no-build
 ```
 
 ---

.claude/REFRESH.md

@@ -9,7 +9,7 @@
 3. **Use `[...]`** not `new () { ... }` for collections
 4. **SubView/SuperView** - never say "child", "parent", or "container"
 5. **Unused lambda params** - use `_` discard: `(_, _) => { }`
-6. **Local functions** - use camelCase: `void myLocalFunc ()`
+6. **Local functions** - use PascalCase: `void MyLocalFunc ()`
 7. **Backing fields** - place immediately before their property (ReSharper bug, must do manually)
 8. **SPACE BEFORE PARENTHESES** - `Method ()` not `Method()`, `array [i]` not `array[i]` (see `formatting.md`)
 9. **Braces on next line** - ALL opening braces on next line (Allman style)

.claude/projects/C--Users-Tig-s-gui-cs-Terminal-Gui/memory/feedback_no_console_writeline.md

@@ -0,0 +1,11 @@
+# Known Fragile Areas
+
+Areas of the codebase where seemingly-safe refactors cause cascading failures. Do not "fix" these in passing — file a separate issue instead.
+
+## TextView Initialization Ordering
+
+Do not change `TextView`'s `EndInit` ordering or initialization flow. Moving `base.EndInit ()` before `UpdateContentSize ()`/`UpdateScrollBars ()` fixes some tests but breaks others in the non-parallel test project.
+
+**Why:** `TextView` has complex initialization dependencies, and the non-parallel tests rely on specific ordering.
+
+**How to apply:** If `TextView` ContentSize tests fail, note the root cause (`UpdateContentSize` runs before `IsInitialized` is set) but do NOT fix it by reordering `EndInit`. File a separate issue or let a maintainer decide when to address it.

.claude/projects/C--Users-Tig-s-gui-cs-Terminal-Gui/memory/feedback_textview_fragile.md

@@ -0,0 +1,35 @@
+# Logging and Tracing
+
+**Never use `Console.WriteLine` or `Console.Error.WriteLine` for debug output.** Console output interferes with the terminal UI framework. Use the project's logging infrastructure instead:
+
+| Need | Use |
+|------|-----|
+| Library logging | `Terminal.Gui.App.Logging` |
+| Test output | `Terminal.Gui.Tests.TestLogging` |
+| Debug tracing | `Terminal.Gui.Tracing.Trace` |
+
+## Test Pattern
+
+```csharp
+using Terminal.Gui.Tests;
+using Terminal.Gui.Tracing;
+
+[Fact]
+public void MyTest ()
+{
+    // Enable logging and tracing in one call
+    using (TestLogging.Verbose (_output, TraceCategory.Command))
+    {
+        // Logs and traces appear in xUnit test output
+        CheckBox checkbox = new () { Id = "test" };
+        checkbox.InvokeCommand (Command.Activate);
+    }
+}
+```
+
+## Rules
+
+- `Tracing.Trace` is only available in DEBUG builds; do not use it to validate test results — all tests must pass in RELEASE builds.
+- Remove temporary debug tracing before committing.
+
+See `docfx/docs/logging.md` for full details.

.claude/rules/fragile-areas.md

@@ -61,10 +61,9 @@ public sealed class MainWindow : Runnable
 
         // Add controls here
         Button button = new () { Text = "Click Me", X = Pos.Center (), Y = Pos.Center () };
-        button.Accepting += (_, e) =>
+        button.Accepted += (_, _) =>
         {
             MessageBox.Query (App!, "Hello", "Button clicked!", "OK");
-            e.Handled = true;
         };
 
         Add (button);
@@ -80,11 +79,10 @@ public sealed class LoginWindow : Runnable<string?>
     {
         // ... setup UI ...
 
-        loginButton.Accepting += (_, e) =>
+        loginButton.Accepted += (_, _) =>
         {
             Result = usernameField.Text;  // Set return value
             App!.RequestStop ();          // Close window
-            e.Handled = true;
         };
     }
 }
@@ -150,10 +148,19 @@ See `.claude/cookbook/common-patterns.md` for recipes including:
 
 ### Button Click
 ```csharp
-button.Accepting += (sender, e) =>
+// Simple side-effect handler — use Accepted (post-event)
+button.Accepted += (_, _) =>
 {
     // Handle the click
-    e.Handled = true;  // Prevent further processing
+};
+
+// Use Accepting (pre-event) ONLY to inspect or cancel the in-flight action
+button.Accepting += (_, e) =>
+{
+    if (!CanProceed ())
+    {
+        e.Handled = true;  // Cancel — prevents Accepted from firing
+    }
 };
 ```
 
@@ -200,7 +207,7 @@ Dialog dialog = new ()
     Title = "Custom Dialog",
     Width = 40,
     Height = 10,
-    Buttons = [new Button ("OK"), new Button ("Cancel")]
+    Buttons = [new Button { Text = "OK" }, new Button { Text = "Cancel" }]
 };
 // Add controls to dialog...
 app.Run (dialog);
@@ -235,18 +242,44 @@ ConfigurationManager.Enable (ConfigLocations.All);
 
 Available themes: `Default`, `Dark`, `Light`, `Amber Phosphor`, `Green Phosphor`, `Blue Phosphor`
 
+## Verify Your App Actually Works (Give Yourself Eyes)
+
+You cannot see a TUI from a build log. Before declaring an app done, **run it and observe it** with [`tuirec`](https://github.com/gui-cs/tuirec) — it spawns the app in a PTY, injects keystrokes, and records the terminal output:
+
+```powershell
+dotnet build -c Release
+$ks = 'wait:1000,Tab,Enter,wait:800,Escape'
+
+tuirec record `
+    --binary dotnet `
+    --args "./bin/Release/net10.0/MyApp.dll" `
+    --name MyApp `
+    --keystrokes $ks `
+    --startup-delay 2000 --drain 1500 `
+    --cols 120 --rows 30
+```
+
+Then **verify the output yourself**:
+
+1. **Read `artifacts/MyApp.cast`** — it is asciinema v2 JSON (plain text). Inspect the frames to confirm the UI rendered what you expect (controls visible, focus moved, dialog appeared).
+2. Grep the cast for failures: `Select-String -Path artifacts/MyApp.cast -Pattern "error|exception|usage:"`.
+3. Check `artifacts/MyApp.gif` exists and is > 100KB (a blank recording is typically < 50KB).
+
+See [Scripts/tuirec/README.md](../../Scripts/tuirec/README.md) for the full keystroke syntax, validation checklist, and troubleshooting table. For in-process assertions (no PTY), use `InputInjector` and `VirtualTimeProvider` — see `docfx/docs/input-injection.md`.
+
 ## Checklist for Building Apps
 
 - [ ] Project setup with correct packages
 - [ ] Main window class inheriting from `Runnable` or `Runnable<T>`
 - [ ] Application lifecycle: Create -> Init -> Run -> Dispose
 - [ ] Layout using Pos/Dim (not hardcoded positions)
-- [ ] Event handlers with `e.Handled = true` when appropriate
+- [ ] `-ed` events (`Accepted`) for side effects; `-ing` events (`Accepting`) only to cancel
 - [ ] Proper cleanup with `Dispose` pattern
+- [ ] Behavior verified by running the app (tuirec recording or input injection), not just by compiling
 
 ## What NOT to Do
 
 - Don't use `Application.Init()` / `Application.Shutdown()` (legacy static API)
 - Don't hardcode sizes - use `Dim.Fill()`, `Dim.Auto()`, `Dim.Percent()`
-- Don't forget `e.Handled = true` in Accepting handlers
+- Don't use `Accepting` for fire-and-forget side effects - use `Accepted`; reserve `Accepting` (with `e.Handled = true`) for canceling
 - Don't block the main thread - use `Application.AddTimeout` for async work

.claude/rules/logging-tracing.md

@@ -51,8 +51,8 @@ Run these for each commit:
 ```bash
 dotnet build --no-restore
 dotnet test --project Tests/IntegrationTests --no-build
-dotnet test --project Tests/UnitTests --no-build
 dotnet test --project Tests/UnitTestsParallelizable --no-build
+dotnet test --project Tests/UnitTests.NonParallelizable --no-build
 ```
 
 ## Terminal.Gui Specific Requirements

.claude/tasks/build-app.md

@@ -4,8 +4,8 @@
 
 ## Required Tools
 
-- **.NET SDK**: 8.0.0 (see `global.json`)
-- **Runtime**: .NET 8.x (latest GA)
+- **.NET SDK**: 10.0.100 (see `global.json`)
+- **Runtime**: .NET 10.x (latest GA)
 - **Optional**: ReSharper/Rider for code formatting (honor `.editorconfig` and `Terminal.sln.DotSettings`)
 
 ## Build Commands
@@ -47,7 +47,7 @@ dotnet build --configuration Release --no-restore
 **Time:** ~10 min timeout
 
 ```bash
-dotnet test --project Tests/UnitTests --no-build --verbosity normal
+dotnet test --project Tests/UnitTests.NonParallelizable --no-build --verbosity normal
 ```
 
 - Uses `Application.Init` and static state
@@ -75,7 +75,7 @@ dotnet test --project Tests/IntegrationTests --no-build --verbosity normal
 ### Run All Tests
 
 ```bash
-dotnet test --project Tests/UnitTests --no-build --verbosity normal && dotnet test --project Tests/UnitTestsParallelizable --no-build --verbosity normal
+dotnet test --project Tests/UnitTestsParallelizable --no-build --verbosity normal && dotnet test --project Tests/UnitTests.NonParallelizable --no-build --verbosity normal
 ```
 
 ## Common Build Issues
@@ -94,7 +94,7 @@ dotnet publish ./Tests/NativeAotSmoke/NativeAotSmoke.csproj --configuration Rele
 **For clean builds, always run in this order:**
 
 ```bash
-dotnet restore && dotnet build --no-restore && dotnet test --project Tests/UnitTests --no-build && dotnet test --project Tests/UnitTestsParallelizable --no-build
+dotnet restore && dotnet build --no-restore && dotnet test --project Tests/UnitTestsParallelizable --no-build && dotnet test --project Tests/UnitTests.NonParallelizable --no-build
 ```
 
 This ensures:

.claude/tasks/clean-code-review.md

@@ -27,7 +27,7 @@ Before submitting a PR, ensure:
 
 - [ ] **Build passes** locally: `dotnet build --no-restore`
 
-- [ ] **Tests pass** locally: `dotnet test --project Tests/UnitTests --no-build && dotnet test --project Tests/UnitTestsParallelizable --no-build`
+- [ ] **Tests pass** locally: `dotnet test --project Tests/UnitTestsParallelizable --no-build && dotnet test --project Tests/UnitTests.NonParallelizable --no-build`
 
 ## PR Description Template
 
@@ -70,7 +70,7 @@ dotnet build --configuration Debug --no-restore
 ### 2. Run Tests
 
 ```bash
-dotnet test --project Tests/UnitTests --no-build --verbosity normal && dotnet test --project Tests/UnitTestsParallelizable --no-build --verbosity normal
+dotnet test --project Tests/UnitTestsParallelizable --no-build --verbosity normal && dotnet test --project Tests/UnitTests.NonParallelizable --no-build --verbosity normal
 ```
 
 **Expected:** All tests pass
@@ -106,7 +106,7 @@ git diff
 - ❌ Don't modify unrelated code
 - ❌ Don't remove/edit unrelated tests
 - ❌ Don't break existing functionality
-- ❌ Don't add tests to `UnitTests` if they can be parallelizable
+- ❌ Don't add tests to `UnitTests.NonParallelizable` if they can be parallelizable; never add tests to `UnitTests.Legacy`
 - ❌ Don't decrease code coverage
 - ❌ Don't introduce new warnings
 - ❌ Don't include commented-out code without explanation