feat: help TUI viewer, markdown rendering, rename ExampleApp to greet

CLAUDE.md

@@ -21,7 +21,7 @@ If guidance conflicts, follow `specs/constitution.md`.
 - `tests/Terminal.Gui.Cli.Tests` — unit tests
 - `tests/Terminal.Gui.Cli.IntegrationTests` — integration tests
 - `tests/Terminal.Gui.Cli.SmokeTests` — smoke tests
-- `examples/Terminal.Gui.Cli.ExampleApp` — sample console app
+- `examples/greet` — sample console app
 
 ## Build and test
 

Terminal.Gui.Cli.slnx

@@ -16,7 +16,7 @@
     <File Path="Directory.Build.props" />
     <File Path="Directory.Build.targets" />
   </Folder>
-  <Project Path="examples/Terminal.Gui.Cli.ExampleApp/Terminal.Gui.Cli.ExampleApp.csproj" />
+  <Project Path="examples/greet/Terminal.Gui.Cli.Greet.csproj" />
   <Project Path="src/Terminal.Gui.Cli/Terminal.Gui.Cli.csproj" />
   <Project Path="tests/Terminal.Gui.Cli.IntegrationTests/Terminal.Gui.Cli.IntegrationTests.csproj" />
   <Project Path="tests/Terminal.Gui.Cli.SmokeTests/Terminal.Gui.Cli.SmokeTests.csproj" />

examples/Terminal.Gui.Cli.ExampleApp/GreetCommand.cs → examples/greet/GreetCommand.cs

@@ -1,6 +1,6 @@
 using Terminal.Gui.App;
 
-namespace Terminal.Gui.Cli.ExampleApp;
+namespace Terminal.Gui.Cli.Greet;
 
 /// <summary>An input command that prompts for a name and returns a greeting.</summary>
 public sealed class GreetCommand : ICliCommand<string>

examples/Terminal.Gui.Cli.ExampleApp/InfoCommand.cs → examples/greet/InfoCommand.cs

@@ -1,6 +1,6 @@
 using Terminal.Gui.App;
 
-namespace Terminal.Gui.Cli.ExampleApp;
+namespace Terminal.Gui.Cli.Greet;
 
 /// <summary>A viewer command that displays application information.</summary>
 public sealed class InfoCommand : IViewerCommand

examples/Terminal.Gui.Cli.ExampleApp/Program.cs → examples/greet/Program.cs

@@ -1,12 +1,12 @@
 using System.Reflection;
 using Terminal.Gui.Cli;
-using Terminal.Gui.Cli.ExampleApp;
+using Terminal.Gui.Cli.Greet;
 
 CliHost host = new (options =>
 {
-    options.ApplicationName = "example-app";
+    options.ApplicationName = "greet";
     options.Version = "1.0.0";
-    options.AgentGuide = "Terminal.Gui.Cli.ExampleApp.agent-guide.md";
+    options.AgentGuide = "Terminal.Gui.Cli.Greet.agent-guide.md";
     options.AgentGuideIsResource = true;
     options.ResourceAssembly = Assembly.GetExecutingAssembly ();
 });

examples/greet/README.md

@@ -0,0 +1,51 @@
+# greet
+
+A sample CLI app built with `Terminal.Gui.Cli` that generates greetings.
+
+## Usage
+
+```bash
+# Launch the TUI greeting prompt
+greet greet
+
+# Provide a name directly (headless)
+greet greet --initial "Alice"
+
+# Formal greeting style
+greet greet --initial "Bob" --formal
+
+# JSON envelope output
+greet greet --initial "World" --json
+
+# Show help in the TUI markdown viewer
+greet help
+
+# Render help as ANSI markdown to stdout
+greet help --cat
+
+# Show root help (ANSI markdown to stdout)
+greet --help
+
+# Show version
+greet --version
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `greet` | Prompt for a name and return a greeting. |
+| `info`  | Display application information. |
+| `help`  | Show command help in a TUI markdown viewer. |
+
+## Building
+
+```bash
+dotnet build examples/Terminal.Gui.Cli.Greet/Terminal.Gui.Cli.Greet.csproj
+```
+
+## Running
+
+```bash
+dotnet run --project examples/Terminal.Gui.Cli.Greet -- greet --initial "World"
+```

examples/Terminal.Gui.Cli.ExampleApp/Resources/agent-guide.md → examples/greet/Resources/agent-guide.md

@@ -1,6 +1,6 @@
-# Example App Agent Guide
+# Greet App Agent Guide
 
-This document describes how AI agents should interact with `example-app`.
+This document describes how AI agents should interact with `greet`.
 
 ## Available Commands
 
@@ -17,9 +17,9 @@ An input command that prompts the user for their name and returns a greeting.
 **Usage:**
 
 ```bash
-example-app greet --initial "World"
-example-app greet --initial "World" --json
-example-app greet --initial "World" --formal
+greet greet --initial "World"
+greet greet --initial "World" --json
+greet greet --initial "World" --formal
 ```
 
 ### info
@@ -34,8 +34,8 @@ A viewer command that displays application information.
 **Usage:**
 
 ```bash
-example-app info --cat
-example-app info --cat --json
+greet info --cat
+greet info --cat --json
 ```
 
 ## Framework Options

examples/Terminal.Gui.Cli.ExampleApp/Terminal.Gui.Cli.ExampleApp.csproj → examples/greet/Terminal.Gui.Cli.Greet.csproj

@@ -2,8 +2,8 @@
 
   <PropertyGroup>
     <OutputType>Exe</OutputType>
-    <RootNamespace>Terminal.Gui.Cli.ExampleApp</RootNamespace>
-    <AssemblyName>Terminal.Gui.Cli.ExampleApp</AssemblyName>
+    <RootNamespace>Terminal.Gui.Cli.Greet</RootNamespace>
+    <AssemblyName>greet</AssemblyName>
     <IsPackable>false</IsPackable>
   </PropertyGroup>
 
@@ -12,7 +12,7 @@
   </ItemGroup>
 
   <ItemGroup>
-    <EmbeddedResource Include="Resources\agent-guide.md" LogicalName="Terminal.Gui.Cli.ExampleApp.agent-guide.md" />
+    <EmbeddedResource Include="Resources\agent-guide.md" LogicalName="Terminal.Gui.Cli.Greet.agent-guide.md" />
   </ItemGroup>
 
 </Project>

src/Terminal.Gui.Cli/CliHost.cs

@@ -141,8 +141,9 @@ private void WriteRootFlag (ArgParser.RootFlag rootFlag, TextWriter stdout)
         switch (rootFlag)
         {
             case ArgParser.RootFlag.Help:
-                stdout.WriteLine (_helpProvider.GetRootHelp (Registry) ??
-                                  new MetadataHelpProvider ().GetRootHelp (Registry));
+                var helpMarkdown = _helpProvider.GetRootHelp (Registry) ??
+                                   new MetadataHelpProvider ().GetRootHelp (Registry) ?? string.Empty;
+                MarkdownRenderer.RenderToAnsi (helpMarkdown, stdout);
                 break;
             case ArgParser.RootFlag.Version:
                 stdout.WriteLine ($"{_options.ApplicationName} {_options.Version ?? "0.0.0"}");

src/Terminal.Gui.Cli/HelpCommand.cs

@@ -1,4 +1,7 @@
 using Terminal.Gui.App;
+using Terminal.Gui.Input;
+using Terminal.Gui.ViewBase;
+using Terminal.Gui.Views;
 
 namespace Terminal.Gui.Cli;
 
@@ -37,11 +40,37 @@ public HelpCommand (ICommandRegistry registry, IHelpProvider helpProvider)
     public bool AcceptsPositionalArgs => true;
 
     /// <inheritdoc />
-    public Task<CommandResult> RunAsync (IApplication app, string? initial, CommandRunOptions options,
+    public async Task<CommandResult> RunAsync (IApplication app, string? initial, CommandRunOptions options,
         CancellationToken cancellationToken)
     {
         var markdown = ResolveHelp (options);
-        return Task.FromResult (new CommandResult (CommandStatus.Ok, markdown, null, null));
+        var title = options.Title ?? "Help";
+
+        Runnable window = new ()
+        {
+            Title = title,
+            Width = Dim.Fill (),
+            Height = Dim.Fill ()
+        };
+
+        Markdown markdownView = new ()
+        {
+            Width = Dim.Fill (),
+            Height = Dim.Fill (1)
+        };
+
+        StatusBar statusBar = new (
+        [
+            new Shortcut (Application.GetDefaultKey (Command.Quit), "Quit", window.RequestStop)
+        ]);
+
+        window.Add (markdownView, statusBar);
+
+        window.Initialized += (_, _) => { markdownView.Text = markdown; };
+
+        await app.RunAsync (window, cancellationToken);
+
+        return new CommandResult (CommandStatus.Ok, null, null, null);
     }
 
     /// <inheritdoc />

src/Terminal.Gui.Cli/MetadataHelpProvider.cs

@@ -11,23 +11,29 @@ public sealed class MetadataHelpProvider : IHelpProvider
         ArgumentNullException.ThrowIfNull (registry);
 
         StringBuilder builder = new ();
-        builder.AppendLine ("Commands:");
+        builder.AppendLine ("## Commands");
+        builder.AppendLine ();
+        builder.AppendLine ("| Command | Description |");
+        builder.AppendLine ("|---------|-------------|");
 
         foreach (ICliCommand command in registry.All)
         {
-            builder.AppendLine ($"  {command.PrimaryAlias}\t{command.Description}");
+            builder.AppendLine ($"| `{command.PrimaryAlias}` | {command.Description} |");
         }
 
         builder.AppendLine ();
-        builder.AppendLine ("Framework options:");
-        builder.AppendLine ("  --help, -h");
-        builder.AppendLine ("  --version");
-        builder.AppendLine ("  --opencli");
-        builder.AppendLine ("  --json");
-        builder.AppendLine ("  --initial <value>");
-        builder.AppendLine ("  --title, --prompt <value>");
-        builder.AppendLine ("  --timeout <duration>");
-        builder.AppendLine ("  --cat");
+        builder.AppendLine ("## Framework Options");
+        builder.AppendLine ();
+        builder.AppendLine ("| Option | Description |");
+        builder.AppendLine ("|--------|-------------|");
+        builder.AppendLine ("| `--help`, `-h` | Show help |");
+        builder.AppendLine ("| `--version` | Show version |");
+        builder.AppendLine ("| `--opencli` | Emit OpenCLI metadata JSON |");
+        builder.AppendLine ("| `--json` | Emit JSON envelope output |");
+        builder.AppendLine ("| `--initial <value>` | Pre-fill input value |");
+        builder.AppendLine ("| `--title`, `--prompt <value>` | Set window title |");
+        builder.AppendLine ("| `--timeout <duration>` | Cancel after duration |");
+        builder.AppendLine ("| `--cat` | Render viewer content to stdout |");
 
         return builder.ToString ();
     }

tests/Terminal.Gui.Cli.IntegrationTests/AssemblyAttributes.cs

@@ -0,0 +1,16 @@
+using System.Runtime.CompilerServices;
+using Xunit;
+
+[assembly: CollectionBehavior (DisableTestParallelization = true)]
+
+namespace Terminal.Gui.Cli.IntegrationTests;
+
+internal static class TestSetup
+{
+    [ModuleInitializer]
+    internal static void Init ()
+    {
+        Environment.SetEnvironmentVariable ("DisableRealDriverIO", "1");
+        Console.SetIn (TextReader.Null);
+    }
+}