Problem
The dominant failure mode for AI agents (and v1 migrators) building Terminal.Gui apps is hallucinated v1 API: button.Clicked, Application.Init (), Toplevel, view.Bounds, new Button ("OK"), TabView, TileView, the 6-arg MenuItem ctor, etc.
Today the agent''s actual experience at that moment is a bare compiler error with zero guidance:
CS1061: ''Button'' does not contain a definition for ''Clicked''
The docs ecosystem (ai-v2-primer.md, CLAUDE.md, AGENTS.md) only helps agents that read it. An analyzer corrects every consumer at the moment of error — including agents and humans who never open the docs — and the v1→v2 corrections table in ai-v2-primer.md is effectively the diagnostic spec already.
Proposal
Ship a Terminal.Gui.Analyzers package (bundled in the main NuGet package so every app gets it for free) with diagnostics, and where feasible code fixes, for the known v1 names:
| Detected |
Diagnostic message (and code fix) |
.Clicked += on a View |
Use Accepted (post-event) or Accepting (cancelable) |
Static Application.Init/Run/Shutdown/Top |
Use Application.Create ().Init () / app.Run<T> () / app.Dispose () |
Toplevel |
Use Runnable or Window |
.Bounds on a View |
Use Viewport |
new Button ("...") / new Label (x, y, "...") |
Object initializer: new Button { Text = "..." } |
TabView / Tab |
Use Tabs (Add views; Title is the tab label) |
TileView |
Removed — Pos/Dim panes + ViewArrangement |
RadioGroup |
OptionSelector |
Colors.ColorSchemes [...] / ColorScheme = |
SchemeName / Scheme |
KeyCode.X | KeyCode.CtrlMask |
Key.X.WithCtrl |
.Accepting handler that ignores e entirely |
Belongs on Accepted (the anti-pattern event-patterns.md forbids) |
Most of these are name-based and cheap to detect (the symbols don''t exist, so the analyzer matches identifier + receiver-type heuristics and supplies a better message alongside CS1061/CS0246; obsolete-shim members are an alternative where a real member can carry [Obsolete]).
Why now
PR #5480 added compile validation for doc snippets and found 14 broken examples — several were exactly these patterns, written by AI agents into our own docs. Anything that fools our doc pipeline is fooling app builders daily.
Context
🤖 Filed by Claude Code at Tig''s request (follow-up from PR #5478).
Problem
The dominant failure mode for AI agents (and v1 migrators) building Terminal.Gui apps is hallucinated v1 API:
button.Clicked,Application.Init (),Toplevel,view.Bounds,new Button ("OK"),TabView,TileView, the 6-argMenuItemctor, etc.Today the agent''s actual experience at that moment is a bare compiler error with zero guidance:
The docs ecosystem (ai-v2-primer.md, CLAUDE.md, AGENTS.md) only helps agents that read it. An analyzer corrects every consumer at the moment of error — including agents and humans who never open the docs — and the v1→v2 corrections table in ai-v2-primer.md is effectively the diagnostic spec already.
Proposal
Ship a
Terminal.Gui.Analyzerspackage (bundled in the main NuGet package so every app gets it for free) with diagnostics, and where feasible code fixes, for the known v1 names:.Clicked +=on a ViewAccepted(post-event) orAccepting(cancelable)Application.Init/Run/Shutdown/TopApplication.Create ().Init ()/app.Run<T> ()/app.Dispose ()ToplevelRunnableorWindow.Boundson a ViewViewportnew Button ("...")/new Label (x, y, "...")new Button { Text = "..." }TabView/TabTabs(Add views;Titleis the tab label)TileViewViewArrangementRadioGroupOptionSelectorColors.ColorSchemes [...]/ColorScheme =SchemeName/SchemeKeyCode.X | KeyCode.CtrlMaskKey.X.WithCtrl.Acceptinghandler that ignoreseentirelyAccepted(the anti-pattern event-patterns.md forbids)Most of these are name-based and cheap to detect (the symbols don''t exist, so the analyzer matches identifier + receiver-type heuristics and supplies a better message alongside CS1061/CS0246; obsolete-shim members are an alternative where a real member can carry
[Obsolete]).Why now
PR #5480 added compile validation for doc snippets and found 14 broken examples — several were exactly these patterns, written by AI agents into our own docs. Anything that fools our doc pipeline is fooling app builders daily.
Context
.Accepting-ignores-ediagnostic also gives reviewers an automated answer for the most common event-pattern review nit.🤖 Filed by Claude Code at Tig''s request (follow-up from PR #5478).