Add winharness_docs tool and speed up agent workspace lookups.

Give agents embedded docs (paths, sessions, tools) via winharness_docs and docs CLI, skip .claude worktrees in glob/grep, and fix VS Code integrated-terminal prompt layout.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: perezdap

CONTEXT.md

@@ -13,7 +13,7 @@ One run of the agent against a Conversation built from the active session branch
 _Avoid_: Round, exchange, request.
 
 **Session**:
-A persisted JSONL file plus in-memory tree state. Distinct from Conversation (the ephemeral projection sent to the runtime for one turn).
+A persisted JSONL file plus in-memory tree state. Distinct from Conversation (the ephemeral projection sent to the runtime for one turn). Stored under `%APPDATA%\WinHarness\sessions\{workspaceKey}\` (override the config root with `WINHARNESS_CONFIG_DIR`).
 _Avoid_: Thread, chat (overloaded).
 
 **Session entry**:

README.md

@@ -75,6 +75,8 @@ dotnet publish .\src\WinHarness.Cli\WinHarness.Cli.csproj -c Release -r win-x64
 - `winharness models use --model-id local-coder`
 - `winharness tools list`
 - `winharness tools call --name read_file --arguments-json '{"path":"README.md"}'`
+- `winharness docs list`
+- `winharness docs get --topic sessions`
 - `winharness mcp list`
 - `winharness mcp add-stdio --id filesystem --command filesystem-mcp-server.exe [--arguments-json '["--root","C:\\src"]' --environment-json '{}' --enabled true]`
 - `winharness mcp add-http --id remote --endpoint https://example.com/mcp [--transport http|sse --headers-json '{"X-Client-Name":"WinHarness"}' --enabled true]`

src/WinHarness.Cli/Program.cs

@@ -25,6 +25,7 @@
 using WinHarness.Sessions;
 using WinHarness.Serialization;
 using WinHarness.Tools;
+using WinHarness.Tools.Docs;
 
 const string Version = "0.3.0";
 
@@ -467,6 +468,21 @@ await sink.WriteAsync(
     }
 });
 
+app.Add("docs list", () =>
+{
+    Console.WriteLine(WinHarnessDocsCatalog.FormatCatalog());
+});
+
+app.Add("docs get", (string topic, string? query = null, int maxOutputBytes = 16 * 1024) =>
+{
+    WinHarnessDocsCatalog.DocLookupResult result = WinHarnessDocsCatalog.Lookup(topic, query, maxOutputBytes);
+    Console.WriteLine(result.Content);
+    if (!result.Succeeded)
+    {
+        Environment.ExitCode = 1;
+    }
+});
+
 app.Add("providers list", () =>
 {
     WinHarnessOptions options = host.Services.GetRequiredService<WinHarnessOptions>();

src/WinHarness.Cli/Rendering/ScreenRegionController.cs

@@ -96,11 +96,41 @@ public static ScreenRegionController Create(IAnsiConsoleConfigurator ansiConfigu
             Environment.GetEnvironmentVariable(OptInEnvironmentVariable),
             ansiConfigurator.IsVirtualTerminalEnabled);
         bool redirected = Console.IsOutputRedirected || Console.IsInputRedirected;
-        int height = TryGetWindowDimension(Console.WindowHeight, out int h) ? h : -1;
+        int height = TryGetWindowDimension(Console.WindowHeight, out int h) ? AdjustHeightForHost(h) : -1;
         int width = TryGetWindowDimension(Console.WindowWidth, out int w) ? w : -1;
         return new ScreenRegionController(ScreenRegionLayout.Resolve(optedIn, redirected, width, height), optedIn, redirected);
     }
 
+    /// <summary>
+    /// VS Code / Cursor integrated terminals set <c>TERM_PROGRAM=vscode</c> and
+    /// clip the bottom row(s) under the panel chrome / Windows taskbar overlap.
+    /// </summary>
+    internal static bool IsVsCodeIntegratedTerminal() =>
+        string.Equals(Environment.GetEnvironmentVariable("TERM_PROGRAM"), "vscode", StringComparison.OrdinalIgnoreCase);
+
+    /// <summary>Rows to leave unused at the physical bottom in VS Code/Cursor.</summary>
+    private const int VsCodeBottomReserveRows = 2;
+
+    /// <summary>
+    /// Returns a layout height that avoids clipped bottom rows in VS Code's
+    /// integrated terminal. Other hosts use the reported height unchanged.
+    /// </summary>
+    internal static int AdjustHeightForHost(int height, bool? vsCodeTerminal = null)
+    {
+        if (height <= 0)
+        {
+            return height;
+        }
+
+        bool vsCode = vsCodeTerminal ?? IsVsCodeIntegratedTerminal();
+        if (!vsCode)
+        {
+            return height;
+        }
+
+        return Math.Max(ScreenRegionLayout.MinimumHeight, height - VsCodeBottomReserveRows);
+    }
+
     /// <summary>
     /// Maps the override environment value plus the probed terminal capability to
     /// the final opt-in decision. Unset → trust the probe; <c>0</c>/<c>false</c> →
@@ -232,7 +262,7 @@ public void OnResize()
             return;
         }
 
-        int height = TryGetWindowDimension(Console.WindowHeight, out int h) ? h : -1;
+        int height = TryGetWindowDimension(Console.WindowHeight, out int h) ? AdjustHeightForHost(h) : -1;
         int width = TryGetWindowDimension(Console.WindowWidth, out int w) ? w : -1;
         ScreenRegionLayout next = ScreenRegionLayout.Resolve(_optedIn, _redirected, width, height);
         if (next == _layout)
@@ -279,7 +309,11 @@ public void BeginPrompt()
         }
 
         // DECSC first so EndPrompt can restore the conversation cursor. Then
-        // paint the empty prompt (prefix only) via WritePromptInput.
+        // paint the empty prompt (prefix only) via WritePromptInput. Show the
+        // cursor while editing — some hosts (notably VS Code's integrated
+        // terminal) do not repaint the fixed prompt row unless the cursor sits
+        // on it.
+        Console.CursorVisible = true;
         Console.Write("\u001b7");
         WritePromptInput(string.Empty);
     }
@@ -331,12 +365,19 @@ public void WritePromptInput(string buffer)
 
         // Paint status + prompt without DECSC/DECRC — BeginPrompt already holds
         // the conversation cursor in the single DECSC slot. Status is a cyan
-        // accent bar; prompt rows stay normal so typing reads clearly.
+        // accent bar; prompt rows reset SGR and use a green › prefix so typed
+        // text stays visible on hosts that do not repaint off-cursor rows.
         Console.Write($"\u001b[{statusRow};1H\u001b[2K{FormatBar(_footerText, Layout.Width, BarStyle.Status)}");
         for (int i = 0; i < promptRows; i++)
         {
-            Console.Write($"\u001b[{statusRow + 1 + i};1H\u001b[2K{wrapped[start + i]}");
+            int row = statusRow + 1 + i;
+            Console.Write($"\u001b[{row};1H\u001b[2K{FormatPromptRow(wrapped[start + i])}");
         }
+
+        string lastPlain = wrapped[start + promptRows - 1];
+        int cursorRow = statusRow + promptRows;
+        Console.Write($"\u001b[{cursorRow};{lastPlain.Length + 1}H");
+        Console.CursorVisible = true;
     }
 
     /// <summary>
@@ -362,6 +403,7 @@ public void EndPrompt()
         SetRegion(Layout.ScrollTop, Layout.ScrollBottom);
         // Put the status bar back on its default row (Height - 1).
         Console.Write($"\u001b[{Layout.FooterStatusRow};1H\u001b[2K{FormatBar(_footerText, Layout.Width, BarStyle.Status)}");
+        Console.CursorVisible = false;
         Console.Write("\u001b8");
     }
 
@@ -488,6 +530,22 @@ private static string FormatBar(string text, int width, BarStyle style)
     /// </summary>
     private void WriteBar(int row, string text, BarStyle style) =>
         Console.Write($"\u001b7\u001b[{row};1H\u001b[2K{FormatBar(text, Layout.Width, style)}\u001b8");
+
+    /// <summary>
+    /// Formats one prompt display row with an explicit SGR reset and a green
+    /// <see cref="PromptLineView.Prefix"/> on the first row only (matches the
+    /// inactive-path Spectre prompt styling).
+    /// </summary>
+    private static string FormatPromptRow(string line)
+    {
+        if (!line.StartsWith(PromptLineView.Prefix, StringComparison.Ordinal))
+        {
+            return $"\x1b[0m{line}";
+        }
+
+        string content = line[PromptLineView.Prefix.Length..];
+        return $"\x1b[0m\x1b[1;32m{PromptLineView.Prefix}\x1b[0m{content}";
+    }
 }
 
 /// <summary>

src/WinHarness.Core/Runtime/SingleAgentRuntime.cs

@@ -29,6 +29,8 @@ public sealed class SingleAgentRuntime : IAgentRuntime
 - To check whether a CLI exists, use where.exe <name> or pwsh -NoProfile -Command "Get-Command <name>".
 - Do not use Unix shell builtins or POSIX-only commands such as command -v, which, bash, sh, ls, cat, rm -rf, chmod, or sudo unless the user explicitly asks for WSL/POSIX and the executable is known to exist.
 - Prefer PowerShell equivalents: Get-ChildItem, Get-Content, Remove-Item, New-Item, Set-Content, Join-Path.
+
+WinHarness reference: call winharness_docs before guessing paths or searching the workspace. Omit topic to list subjects (paths, sessions, tools, providers, mcp, chat, diagnostics).
 """;
 
     // Safety net for a single streamed response that never stops (e.g. a model that

src/WinHarness.Tools/BuiltinToolProvider.cs

@@ -73,7 +73,8 @@ public ValueTask<IReadOnlyList<ITool>> ListToolsAsync(CancellationToken cancella
             new EditFileTool(_workspaceRoot, _longPathService),
             new RunCommandTool(_workspaceRoot, _commandExecutor, _longPathService),
             new GlobTool(_workspaceRoot, _longPathService),
-            new GrepTool(_workspaceRoot, _longPathService)
+            new GrepTool(_workspaceRoot, _longPathService),
+            new WinHarnessDocsTool()
         ];
 
         return ValueTask.FromResult(tools);
@@ -195,7 +196,7 @@ protected static async ValueTask AtomicWriteAllTextAsync(
 
         private static readonly HashSet<string> IgnoredDirectoryNames = new(StringComparer.OrdinalIgnoreCase)
         {
-            ".git", "bin", "obj", "node_modules", ".vs", ".idea", ".vscode"
+            ".git", ".claude", "bin", "obj", "node_modules", ".vs", ".idea", ".vscode"
         };
 
         /// <summary>
@@ -608,7 +609,7 @@ protected override ValueTask<CommandResult> ExecuteInteractiveAsync(CommandReque
     private sealed class GlobTool : BuiltinTool
     {
         public GlobTool(string workspaceRoot, ILongPathService longPathService)
-            : base(workspaceRoot, longPathService, "glob", "List files matching a simple glob pattern (* and ? wildcards; skips .git, bin, obj, node_modules).", """{"type":"object","properties":{"pattern":{"type":"string"},"maxResults":{"type":"integer"}},"required":["pattern"]}""")
+            : base(workspaceRoot, longPathService, "glob", "List files matching a simple glob pattern (* and ? wildcards; skips .git, .claude, bin, obj, node_modules).", """{"type":"object","properties":{"pattern":{"type":"string"},"maxResults":{"type":"integer"}},"required":["pattern"]}""")
         {
         }
 
@@ -639,7 +640,7 @@ public override ValueTask<ToolResult> ExecuteAsync(ToolInvocation invocation, Ca
     private sealed class GrepTool : BuiltinTool
     {
         public GrepTool(string workspaceRoot, ILongPathService longPathService)
-            : base(workspaceRoot, longPathService, "grep", "Search text files (skips .git, bin, obj, node_modules).", """{"type":"object","properties":{"pattern":{"type":"string"},"filePattern":{"type":"string"},"maxResults":{"type":"integer"},"maxFileBytes":{"type":"integer"}},"required":["pattern"]}""")
+            : base(workspaceRoot, longPathService, "grep", "Search text files (skips .git, .claude, bin, obj, node_modules).", """{"type":"object","properties":{"pattern":{"type":"string"},"filePattern":{"type":"string"},"maxResults":{"type":"integer"},"maxFileBytes":{"type":"integer"}},"required":["pattern"]}""")
         {
         }
 

src/WinHarness.Tools/Docs/WinHarnessDocsCatalog.cs

@@ -0,0 +1,133 @@
+using System.Reflection;
+using System.Text;
+
+namespace WinHarness.Tools.Docs;
+
+/// <summary>
+/// Embedded WinHarness agent documentation topics shipped inside the tools assembly.
+/// </summary>
+public static class WinHarnessDocsCatalog
+{
+    private const string ResourcePrefix = "WinHarness.Docs.topics.";
+    private const int DefaultMaxOutputBytes = 16 * 1024;
+
+    private static readonly DocTopic[] Topics =
+    [
+        new("paths", "Configuration and data directory layout"),
+        new("sessions", "Persisted JSONL chat sessions"),
+        new("tools", "Built-in workspace tools and run_command rules"),
+        new("providers", "Providers, models, login, and reasoning effort"),
+        new("mcp", "MCP server configuration"),
+        new("chat", "REPL slash commands and chat flags"),
+        new("diagnostics", "Structured logs and timing fields"),
+    ];
+
+    public static IReadOnlyList<DocTopic> ListTopics() => Topics;
+
+    public static string FormatCatalog()
+    {
+        StringBuilder builder = new();
+        foreach (DocTopic topic in Topics)
+        {
+            builder.Append(topic.Id);
+            builder.Append(" — ");
+            builder.AppendLine(topic.Summary);
+        }
+
+        return builder.ToString().TrimEnd();
+    }
+
+    public static DocLookupResult Lookup(string? topicId, string? query, int maxOutputBytes)
+    {
+        if (string.IsNullOrWhiteSpace(topicId))
+        {
+            return new DocLookupResult(true, FormatCatalog(), null);
+        }
+
+        string normalizedId = topicId.Trim();
+        DocTopic? topic = Topics.FirstOrDefault(candidate =>
+            string.Equals(candidate.Id, normalizedId, StringComparison.OrdinalIgnoreCase));
+        if (topic is null)
+        {
+            string message = $"Unknown topic '{normalizedId}'. Valid topics: {string.Join(", ", Topics.Select(static t => t.Id))}.";
+            return new DocLookupResult(false, message, "unknown_topic");
+        }
+
+        string? body = LoadTopicBody(topic.Id);
+        if (body is null)
+        {
+            return new DocLookupResult(false, $"Topic '{topic.Id}' is registered but its embedded document is missing.", "missing_topic");
+        }
+
+        if (!string.IsNullOrWhiteSpace(query))
+        {
+            body = FilterByQuery(body, query);
+        }
+
+        int limit = maxOutputBytes > 0 ? maxOutputBytes : DefaultMaxOutputBytes;
+        body = Truncate(body, limit);
+        return new DocLookupResult(true, body, null);
+    }
+
+    private static string? LoadTopicBody(string topicId)
+    {
+        string resourceName = ResourcePrefix + topicId + ".md";
+        Assembly assembly = typeof(WinHarnessDocsCatalog).Assembly;
+        using Stream? stream = assembly.GetManifestResourceStream(resourceName);
+        if (stream is null)
+        {
+            return null;
+        }
+
+        using StreamReader reader = new(stream, Encoding.UTF8);
+        return reader.ReadToEnd();
+    }
+
+    private static string FilterByQuery(string body, string query)
+    {
+        string needle = query.Trim();
+        if (needle.Length == 0)
+        {
+            return body;
+        }
+
+        StringBuilder builder = new();
+        foreach (string line in body.Split('\n'))
+        {
+            if (line.Contains(needle, StringComparison.OrdinalIgnoreCase))
+            {
+                if (builder.Length > 0)
+                {
+                    builder.AppendLine();
+                }
+
+                builder.Append(line.TrimEnd('\r'));
+            }
+        }
+
+        return builder.Length == 0
+            ? $"No lines matched query '{needle}'."
+            : builder.ToString();
+    }
+
+    private static string Truncate(string content, int maxBytes)
+    {
+        byte[] bytes = Encoding.UTF8.GetBytes(content);
+        if (bytes.Length <= maxBytes)
+        {
+            return content;
+        }
+
+        int limit = Math.Max(0, maxBytes);
+        while (limit > 0 && (bytes[limit] & 0xC0) == 0x80)
+        {
+            limit--;
+        }
+
+        return Encoding.UTF8.GetString(bytes.AsSpan(0, limit)) + Environment.NewLine + "[output truncated]";
+    }
+
+    public sealed record DocTopic(string Id, string Summary);
+
+    public sealed record DocLookupResult(bool Succeeded, string Content, string? ErrorCode);
+}

src/WinHarness.Tools/Docs/topics/chat.md

@@ -0,0 +1,47 @@
+# WinHarness chat REPL
+
+## Launch
+
+```text
+winharness chat
+winharness chat --verbose
+winharness chat --output json
+winharness rpc
+```
+
+Default: continues the most recent persisted session for the current directory.
+
+## Common slash commands
+
+| Command | Purpose |
+| --- | --- |
+| `/help` | Command list |
+| `/session` | Session file path, id, name, counts |
+| `/new` | New session file |
+| `/resume` | Pick a saved session |
+| `/model` / `/provider` | Switch model or provider |
+| `/effort` | Reasoning effort |
+| `/skills` / `/skill` | Session skills |
+| `/compact` | Summarize older context |
+| `/clear` | Clear in-memory view (file unchanged) |
+| `/exit` | Leave |
+
+See `winharness_docs` topic `sessions` for session-specific commands.
+
+## While a turn is running
+
+| Input | Behavior |
+| --- | --- |
+| text + Enter | Follow-up queued for after the turn |
+| `>> text` + Enter | Steering injected between tool rounds |
+| `/abort` | Cancel turn |
+
+## Context files (project)
+
+Loaded from workspace: `AGENTS.md`, `CLAUDE.md`, `.winharness/SYSTEM.md`, skills under `.agents/skills` or `.winharness/skills` when trusted.
+
+Global copies under `%APPDATA%\WinHarness\`.
+
+## WinHarness self-reference
+
+Use `winharness_docs` (or `winharness docs get --topic <id>`) for paths, sessions, tools, and diagnostics — not workspace grep.