Write Terminal.Gui.Cli v2 library spec

[Copilot]

• Fetch and review PR Write Terminal.Gui.Cli v2 library spec #179 comments
• Update spec for Markdown API availability and concrete TG Markdown View usage
• Add CliHostOptions.ResourceAssembly and clarify AgentGuide resource resolution
• Clarify InputCommandRunner overload usage
• Document internal CliJsonContext
• Add root-only flags note/table for --help, --version, and --opencli
• Validate documentation changes and push updates

[tig]

Review: Terminal.Gui.Cli v2 Spec (PR #179)

Overall: Strong spec. Ready to implement from with a few clarifications.

The spec accurately captures the Stage A learnings, maintains fidelity to the proven implementation, and adds the deferred pieces (HelpCommand, AgentGuideCommand, ReplaceBuiltInCommand, EmbeddedMarkdownHelpProvider, MarkdownRenderer) cleanly. Structure is good - an implementing agent can work section-by-section.

Issues to address:

1. MarkdownRenderer - TG API is already merged (not pending)

Stage A final commit (f783d61) bumped TG to 2.4.1-develop.11 and uses Markdown.RenderToAnsi() directly. The TG-PENDING markers in S4.9, S4.7, and S13 should be removed or softened to say pin TerminalGuiVersion >= 2.4.1-develop.11 - the API exists now.

2. InputCommandRunner - missing second overload context

S4.10 shows two overloads but does not explain when to use which. The 3-type-param version (TControl, TRawResult, TValue) is for when the raw result needs mapping. The 2-type-param version (TControl, TValue) is a convenience when TRawResult == TValue. A one-line note per overload would help implementers.

3. AgentGuideCommand constructor takes string markdown - who resolves the resource?

S4.7 shows AgentGuideCommand(string markdown) taking resolved content. But S4.5 says CliHost registers it when AgentGuide is non-null. The spec should clarify: CliHost resolves the embedded resource (if AgentGuideIsResource=true) during construction and passes the resolved string to AgentGuideCommand. This means the consumer assembly must be discoverable by the host - how? Via a new CliHostOptions.ResourceAssembly property? Or the calling assembly? Stage A punted this. Needs a decision.

4. HelpCommand TUI mode - what View does it use?

S4.7 says uses a Terminal.Gui markdown viewer for TUI mode but does not specify which TG View. Is it MarkdownView? A plain TextView with pre-rendered ANSI? The spec should name the concrete View type or say implementation chooses based on available TG APIs.

5. Missing: CliJsonContext source-generated context

S4.8 shows JsonEnvelope.ToJson() uses the source-generated JSON context but the CliJsonContext type is not defined in S4. Add a brief note that it is internal partial class CliJsonContext : JsonSerializerContext, internal, not public, AOT-safe.

6. Missing: --help / -h in framework flags table

S5.1 lists framework flags but --help/-h and --version are not in the table (they are root flags handled differently). This is technically correct since they are intercepted before dispatch, but the table should have a footnote or separate root-only flags row to avoid confusion.

Verdict: Approve with comments above addressed.

[tig]

Follow-up on review items 3 and 4:

#3 Decision: Add Assembly? ResourceAssembly to CliHostOptions

The consumer explicitly passes typeof(Program).Assembly. No magic. If null, fall back to Assembly.GetEntryAssembly() for convenience (most consumers will not notice). This covers both AgentGuide resource resolution and EmbeddedMarkdownHelpProvider uniformly. Testable, explicit, one line in consumer code.

Example:

CliHost host = new (o =>
{
    o.ResourceAssembly = typeof (Program).Assembly;
    o.AgentGuide = "AgentGuide.md";
});

#4 Decision: HelpCommand uses Terminal.Gui.Views.Markdown for TUI mode.

TG 2.4.1-develop.11 ships both Markdown (the View) and Markdown.RenderToAnsi() (the static helper). HelpCommand uses the View for interactive TUI and the static method for --cat output. Spec should name it explicitly.