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/greet/FarewellCommand.cs

@@ -0,0 +1,52 @@
+using Terminal.Gui.App;
+
+namespace Terminal.Gui.Cli.Greet;
+
+/// <summary>An input command that says goodbye to someone.</summary>
+public sealed class FarewellCommand : ICliCommand<string>
+{
+    /// <inheritdoc />
+    public string PrimaryAlias => "farewell";
+
+    /// <inheritdoc />
+    public IReadOnlyList<string> Aliases { get; } = ["farewell", "bye"];
+
+    /// <inheritdoc />
+    public string Description => "Say goodbye to someone.";
+
+    /// <inheritdoc />
+    public CommandKind Kind => CommandKind.Input;
+
+    /// <inheritdoc />
+    public Type ResultType => typeof (string);
+
+    /// <inheritdoc />
+    public IReadOnlyList<CommandOptionDescriptor> Options { get; } =
+    [
+        new ("until", "u", typeof (string), "When you expect to meet again.", false, null)
+    ];
+
+    /// <inheritdoc />
+    public bool AcceptsPositionalArgs => true;
+
+    /// <inheritdoc />
+    public Task<CommandResult<string>> RunAsync (
+        IApplication app,
+        string? initial,
+        CommandRunOptions options,
+        CancellationToken cancellationToken)
+    {
+        var name = options.Arguments.Count > 0
+            ? string.Join (" ", options.Arguments)
+            : initial ?? "World";
+        var until = options.CommandOptions.TryGetValue ("until", out var untilValue)
+            ? untilValue
+            : null;
+
+        var farewell = until is not null
+            ? $"Goodbye, {name}! See you {until}."
+            : $"Goodbye, {name}!";
+
+        return Task.FromResult (new CommandResult<string> (CommandStatus.Ok, farewell, null, null));
+    }
+}

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>
@@ -26,14 +26,20 @@ public sealed class GreetCommand : ICliCommand<string>
         new ("formal", "f", typeof (bool), "Use a formal greeting style.", false, null)
     ];
 
+    /// <inheritdoc />
+    public bool AcceptsPositionalArgs => true;
+
     /// <inheritdoc />
     public Task<CommandResult<string>> RunAsync (
         IApplication app,
         string? initial,
         CommandRunOptions options,
         CancellationToken cancellationToken)
     {
-        var name = initial ?? "World";
+        var name = options.Arguments.Count > 0
+            ? string.Join (" ", options.Arguments)
+            : initial ?? "World";
+
         var formal = options.CommandOptions.TryGetValue ("formal", out var formalValue)
                      && formalValue.Equals ("true", StringComparison.OrdinalIgnoreCase);
 

examples/greet/InfoCommand.cs

@@ -0,0 +1,102 @@
+using Terminal.Gui.App;
+using Terminal.Gui.Input;
+using Terminal.Gui.ViewBase;
+using Terminal.Gui.Views;
+
+namespace Terminal.Gui.Cli.Greet;
+
+/// <summary>A viewer command that displays application information in a TUI markdown view.</summary>
+public sealed class InfoCommand : IViewerCommand
+{
+    private const string InfoMarkdown = """
+                                        # greet — Info
+
+                                        **Version:** 1.0.0
+
+                                        A demonstration of the `Terminal.Gui.Cli` library.
+
+                                        ## Features
+
+                                        This app shows how to:
+
+                                        - Register input and viewer commands
+                                        - Use `--help`, `--json`, `--opencli`, and `agent-guide`
+                                        - Embed an `agent-guide.md` resource
+                                        - Support `--cat` for headless content rendering
+                                        - Launch a TUI markdown viewer for `help` and `info`
+
+                                        ## Usage
+
+                                        ```
+                                        greet [name]              Greet someone (default: World)
+                                        greet --formal [name]     Use a formal greeting style
+                                        greet help                Browse help topics
+                                        greet help greet          Help for the greet command
+                                        greet info                Show this info page
+                                        greet --help              Render help as ANSI to stdout
+                                        ```
+                                        """;
+
+    /// <inheritdoc />
+    public string PrimaryAlias => "info";
+
+    /// <inheritdoc />
+    public IReadOnlyList<string> Aliases { get; } = ["info"];
+
+    /// <inheritdoc />
+    public string Description => "Display application information.";
+
+    /// <inheritdoc />
+    public CommandKind Kind => CommandKind.Viewer;
+
+    /// <inheritdoc />
+    public Type ResultType => typeof (void);
+
+    /// <inheritdoc />
+    public IReadOnlyList<CommandOptionDescriptor> Options { get; } = [];
+
+    /// <inheritdoc />
+    public async Task<CommandResult> RunAsync (
+        IApplication app,
+        string? initial,
+        CommandRunOptions options,
+        CancellationToken cancellationToken)
+    {
+        Runnable window = new ()
+        {
+            Title = "Info",
+            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 = InfoMarkdown; };
+
+        await app.RunAsync (window, cancellationToken);
+
+        return new CommandResult (CommandStatus.Ok, null, null, null);
+    }
+
+    /// <inheritdoc />
+    public Task<CommandResult?> RenderCatAsync (
+        CommandRunOptions options,
+        TextWriter stdout,
+        CancellationToken cancellationToken)
+    {
+        ArgumentNullException.ThrowIfNull (stdout);
+        MarkdownRenderer.RenderToAnsi (InfoMarkdown, stdout);
+        return Task.FromResult<CommandResult?> (new CommandResult (CommandStatus.Ok, null, null, null));
+    }
+}

examples/greet/Program.cs

@@ -0,0 +1,22 @@
+using System.Reflection;
+using Terminal.Gui.Cli;
+using Terminal.Gui.Cli.Greet;
+
+Assembly assembly = Assembly.GetExecutingAssembly ();
+
+CliHost host = new (options =>
+{
+    options.ApplicationName = "greet";
+    options.Version = "1.0.0";
+    options.DefaultCommand = "greet";
+    options.AgentGuide = "Terminal.Gui.Cli.Greet.agent-guide.md";
+    options.AgentGuideIsResource = true;
+    options.ResourceAssembly = assembly;
+    options.HelpProvider = new EmbeddedMarkdownHelpProvider (assembly);
+});
+
+host.Registry.Register (new GreetCommand ());
+host.Registry.Register (new FarewellCommand ());
+host.Registry.Register (new InfoCommand ());
+
+return await host.RunAsync (args);

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"
+```