Adds doc snippet compile validation; fixes v1 API rot in agent docs (#5480)

* Add doc snippet compile validation with obsolete-API rejection

Roslyn-based validator that compiles every fenced C# block in the agent
docs (ai-v2-primer.md, build-app.md, common-patterns.md) against the built
Terminal.Gui assembly, so example rot fails CI instead of misleading
readers. Statement fragments are wrapped in a Runnable<string?> harness;
blocks marked WRONG / `snippet: ignore` are skipped.

Obsolete-API use (CS0618/CS0612) is treated as a failure, not a warning,
so v1 rot like the legacy static Application.Init cannot pass as
"compiled". testdata/obsolete-api.md + a CI negative-test step assert the
validator rejects obsolete APIs. The check caught real rot fixed here:
two cookbook snippets used the obsolete TextView (now a plain content
View, pointing at gui-cs/Editor's EditorView).

Result: 29 compiled, 1 skipped, 0 failed; negative test green.

Rebased onto develop after #5478 merged (squash), keeping only this PR's
files; no overlap with the merged agent-docs lint changes.

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

* Fix Validate Doc Snippets CI: full history for GitVersion

The workflow built Terminal.Gui without fetch-depth:0, so GitVersion.MsBuild
failed on the shallow clone ("Repository is a shallow clone"). Match the
build-validation workflow's checkout (fetch-depth: 0).

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

---------

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

Author: tig

.claude/cookbook/common-patterns.md

@@ -46,7 +46,7 @@ public sealed class FormWindow : Runnable<FormData?>
             X = 1,
             Y = 7,
             Width = Dim.Fill (1),
-            ColorScheme = Colors.ColorSchemes ["Error"]
+            SchemeName = "Error"
         };
 
         Button submitButton = new ()
@@ -96,11 +96,13 @@ public record FormData (string Name, string Email, int Age);
 A scrollable list with item selection and actions.
 
 ```csharp
+using System.Collections.ObjectModel;
+
 public sealed class ListWindow : Runnable
 {
     private readonly ListView _listView;
     private readonly Label _detailLabel;
-    private readonly List<string> _items = ["Apple", "Banana", "Cherry", "Date", "Elderberry"];
+    private readonly ObservableCollection<string> _items = ["Apple", "Banana", "Cherry", "Date", "Elderberry"];
 
     public ListWindow ()
     {
@@ -131,21 +133,21 @@ public sealed class ListWindow : Runnable
             Y = Pos.AnchorEnd (1)
         };
 
-        _listView.SelectedItemChanged += (_, e) =>
+        // ListView is IValue<int?> — the selected index. SelectedItem is int?.
+        _listView.ValueChanged += (_, e) =>
         {
-            if (e.Value >= 0 && e.Value < _items.Count)
+            if (e.NewValue is int index && index < _items.Count)
             {
-                _detailLabel.Text = $"Selected: {_items [e.Value]}";
+                _detailLabel.Text = $"Selected: {_items [index]}";
             }
         };
 
-        selectButton.Accepting += (_, e) =>
+        selectButton.Accepted += (_, _) =>
         {
-            if (_listView.SelectedItem >= 0)
+            if (_listView.SelectedItem is int selected)
             {
-                MessageBox.Query (App!, "Selection", $"You selected: {_items [_listView.SelectedItem]}", "OK");
+                MessageBox.Query (App!, "Selection", $"You selected: {_items [selected]}", "OK");
             }
-            e.Handled = true;
         };
 
         Add (_listView, _detailLabel, selectButton);
@@ -166,43 +168,33 @@ public sealed class MenuApp : Runnable
     {
         Title = "Menu Demo";
 
-        MenuBar menuBar = new ()
-        {
-            Menus =
-            [
-                new MenuBarItem (
-                    "File",
-                    [
-                        new MenuItem ("New", "", () => NewFile (), null, null, KeyCode.N | KeyCode.CtrlMask),
-                        new MenuItem ("Open...", "", () => OpenFile (), null, null, KeyCode.O | KeyCode.CtrlMask),
-                        new MenuItem ("Save", "", () => SaveFile (), null, null, KeyCode.S | KeyCode.CtrlMask),
-                        null, // Separator
-                        new MenuItem ("Exit", "", () => App!.RequestStop (), null, null, KeyCode.Q | KeyCode.CtrlMask)
-                    ]),
-                new MenuBarItem (
-                    "Edit",
-                    [
-                        new MenuItem ("Cut", "", null, null, null, KeyCode.X | KeyCode.CtrlMask),
-                        new MenuItem ("Copy", "", null, null, null, KeyCode.C | KeyCode.CtrlMask),
-                        new MenuItem ("Paste", "", null, null, null, KeyCode.V | KeyCode.CtrlMask)
-                    ]),
-                new MenuBarItem (
-                    "Help",
-                    [
-                        new MenuItem ("About...", "", () => ShowAbout ())
-                    ])
-            ]
-        };
-
-        TextView editor = new ()
+        MenuBar menuBar = new ();
+
+        menuBar.Add (new MenuBarItem ("_File",
+                                      [
+                                          new MenuItem { Title = "_New", Key = Key.N.WithCtrl, Action = NewFile },
+                                          new MenuItem { Title = "_Open...", Key = Key.O.WithCtrl, Action = OpenFile },
+                                          new MenuItem { Title = "_Save", Key = Key.S.WithCtrl, Action = SaveFile },
+                                          new Line (), // Separator
+                                          new MenuItem { Title = "_Quit", Key = Key.Q.WithCtrl, Action = () => App!.RequestStop () }
+                                      ]));
+
+        menuBar.Add (new MenuBarItem ("_Help",
+                                      [
+                                          new MenuItem { Title = "_About...", Action = ShowAbout }
+                                      ]));
+
+        // Main content area below the menu bar. (For a real multi-line editor,
+        // use gui-cs/Editor's EditorView — the core TextView is deprecated.)
+        View content = new ()
         {
             X = 0,
-            Y = 1,
+            Y = Pos.Bottom (menuBar),
             Width = Dim.Fill (),
             Height = Dim.Fill ()
         };
 
-        Add (menuBar, editor);
+        Add (menuBar, content);
     }
 
     private void NewFile () => MessageBox.Query (App!, "New", "New file created", "OK");
@@ -216,7 +208,7 @@ public sealed class MenuApp : Runnable
 
 ## Split View Layout
 
-Horizontal or vertical split layout with resizable panes.
+Side-by-side panes positioned with `Pos`/`Dim`. (`TileView` does not exist in v2 — use plain views and `ViewArrangement` for user-resizable panes.)
 
 ```csharp
 public sealed class SplitWindow : Runnable
@@ -225,27 +217,27 @@ public sealed class SplitWindow : Runnable
     {
         Title = "Split View Demo";
 
-        TileView tileView = new ()
+        FrameView leftPane = new ()
         {
-            X = 0,
-            Y = 0,
-            Width = Dim.Fill (),
+            Title = "Left Pane",
+            Width = Dim.Percent (50),
             Height = Dim.Fill (),
-            Orientation = Orientation.Vertical  // or Horizontal
-        };
 
-        // Left pane
-        FrameView leftPane = new () { Title = "Left Pane" };
+            // Let the user resize this pane with mouse or keyboard (optional)
+            Arrangement = ViewArrangement.RightResizable
+        };
         leftPane.Add (new Label { Text = "Left content", X = 1, Y = 1 });
 
-        // Right pane
-        FrameView rightPane = new () { Title = "Right Pane" };
+        FrameView rightPane = new ()
+        {
+            Title = "Right Pane",
+            X = Pos.Right (leftPane),
+            Width = Dim.Fill (),
+            Height = Dim.Fill ()
+        };
         rightPane.Add (new Label { Text = "Right content", X = 1, Y = 1 });
 
-        tileView.Tiles.ElementAt (0).ContentView.Add (leftPane);
-        tileView.Tiles.ElementAt (1).ContentView.Add (rightPane);
-
-        Add (tileView);
+        Add (leftPane, rightPane);
     }
 }
 ```
@@ -254,7 +246,7 @@ public sealed class SplitWindow : Runnable
 
 ## Tab View
 
-Tabbed interface with multiple content pages.
+Tabbed interface with multiple content pages. (v1's `TabView` is now `Tabs`: each added `View` becomes a tab, and its `Title` is the tab label.)
 
 ```csharp
 public sealed class TabbedWindow : Runnable
@@ -263,29 +255,25 @@ public sealed class TabbedWindow : Runnable
     {
         Title = "Tabbed Interface";
 
-        TabView tabView = new ()
-        {
-            X = 0,
-            Y = 0,
-            Width = Dim.Fill (),
-            Height = Dim.Fill ()
-        };
+        Tabs tabs = new ();
 
-        // Tab 1: Settings
-        View settingsTab = new ();
+        // Tab 1: Settings — Title becomes the tab label
+        View settingsTab = new () { Title = "Settings" };
         settingsTab.Add (
             new Label { Text = "Enable Feature:", X = 1, Y = 1 },
             new CheckBox { X = 20, Y = 1, Text = "Enabled" }
         );
 
         // Tab 2: About
-        View aboutTab = new ();
+        View aboutTab = new () { Title = "About" };
         aboutTab.Add (new Label { Text = "Version 1.0.0", X = 1, Y = 1 });
 
-        tabView.AddTab (new Tab { DisplayText = "Settings", View = settingsTab }, false);
-        tabView.AddTab (new Tab { DisplayText = "About", View = aboutTab }, false);
+        tabs.Add (settingsTab, aboutTab);
+
+        // Tabs is IValue<View?> — set Value to switch tabs programmatically
+        tabs.Value = settingsTab;
 
-        Add (tabView);
+        Add (tabs);
     }
 }
 ```
@@ -340,9 +328,14 @@ public sealed class ProgressWindow : Runnable
         Add (_statusLabel, _progressBar, cancelButton);
     }
 
-    public override void OnLoaded ()
+    protected override void OnIsRunningChanged (bool newIsRunning)
     {
-        base.OnLoaded ();
+        base.OnIsRunningChanged (newIsRunning);
+
+        if (!newIsRunning)
+        {
+            return;
+        }
 
         // Start simulated work
         App!.AddTimeout (TimeSpan.FromMilliseconds (100), () =>
@@ -376,7 +369,7 @@ private void OpenFile ()
     {
         Title = "Open File",
         AllowsMultipleSelection = false,
-        DirectoryPath = Environment.CurrentDirectory
+        Path = Environment.CurrentDirectory  // Starting directory
     };
 
     // Optional: filter by extension
@@ -397,15 +390,15 @@ private void SaveFile ()
     SaveDialog dialog = new ()
     {
         Title = "Save File",
-        DirectoryPath = Environment.CurrentDirectory,
-        FileName = "document.txt"
+        Path = Environment.CurrentDirectory  // Starting directory
     };
 
     App!.Run (dialog);
 
+    // FileName is the name portion of the chosen Path (null if canceled)
     if (!dialog.Canceled && !string.IsNullOrEmpty (dialog.FileName))
     {
-        string path = dialog.FileName;
+        string path = dialog.Path;
         // Save to path...
     }
 }
@@ -438,6 +431,8 @@ private void OpenMultipleFiles ()
 Display tabular data with TableView.
 
 ```csharp
+using System.Data;
+
 public sealed class DataTableWindow : Runnable
 {
     public DataTableWindow ()
@@ -474,12 +469,21 @@ public sealed class DataTableWindow : Runnable
             Text = "Select a row"
         };
 
-        tableView.SelectedCellChanged += (_, e) =>
+        // TableView is IValue<TableSelection?> — ValueChanged fires when the selection moves.
+        // SelectedCell is a Point: X = column, Y = row.
+        tableView.ValueChanged += (_, e) =>
         {
-            if (e.NewRow >= 0 && e.NewRow < table.Rows.Count)
+            if (e.NewValue is not { } selection)
+            {
+                return;
+            }
+
+            int row = selection.SelectedCell.Y;
+
+            if (row >= 0 && row < table.Rows.Count)
             {
-                DataRow row = table.Rows [e.NewRow];
-                statusLabel.Text = $"Selected: {row ["Name"]} - ${row ["Price"]}";
+                DataRow dataRow = table.Rows [row];
+                statusLabel.Text = $"Selected: {dataRow ["Name"]} - ${dataRow ["Price"]}";
             }
         };
 
@@ -495,6 +499,8 @@ public sealed class DataTableWindow : Runnable
 Hierarchical data display.
 
 ```csharp
+using System.IO;
+
 public sealed class TreeWindow : Runnable
 {
     public TreeWindow ()
@@ -568,7 +574,9 @@ public sealed class StatusBarApp : Runnable
     {
         Title = "Status Bar Demo";
 
-        TextView editor = new ()
+        // Main content area. (For a real multi-line editor, use gui-cs/Editor's
+        // EditorView — the core TextView is deprecated.)
+        View content = new ()
         {
             Width = Dim.Fill (),
             Height = Dim.Fill (1)  // Leave 1 row for StatusBar
@@ -604,7 +612,7 @@ public sealed class StatusBarApp : Runnable
                                   };
 
         statusBar.Add (saveShortcut, quitShortcut);
-        Add (editor, statusBar);
+        Add (content, statusBar);
     }
 }
 ```
@@ -652,7 +660,7 @@ if possible.
 
 ## Tips for All Patterns
 
-1. **Always use `e.Handled = true`** in `Accepting` event handlers
+1. **Use `-ed` events (`Accepted`) for side effects**; use `Accepting` + `e.Handled = true` only to inspect or cancel
 2. **Use `Dim.Fill()` and `Pos.Center()`** instead of hardcoded values
 3. **Call `App!.RequestStop()`** to close the current window
 4. **Use `MessageBox.Query`** for simple dialogs