fix(cli): clearer Windows TUI error on Git Bash / MinTTY

GetConsoleMode only works on real Windows console handles. Git Bash,
MSYS and other MinTTY-based shells pipe stdio through the terminal
emulator instead of attaching a console, so the call fails with
ERROR_INVALID_HANDLE and the TUI aborts with a bare "GetConsoleMode
failed" message that leaves users at a dead end.

Detect that case via GetFileType: if the stdio handle returns
FILE_TYPE_PIPE the user is on MinTTY-piped stdio, so throw an
actionable IOException pointing at `winpty <command>` or the
terminals that do attach a real console (Windows Terminal,
PowerShell, cmd.exe).

Add a paragraph to docs/how-to.md under the TUI section covering
the same workaround so users finding the docs first don't trip
on it.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: dfa1

cli/src/main/java/io/github/dfa1/vortex/cli/tui/term/WindowsTerminal.java

@@ -34,6 +34,8 @@ public final class WindowsTerminal implements Terminal {
     private static final int ENABLE_PROCESSED_OUTPUT = 0x0001;
     private static final int ENABLE_VIRTUAL_TERMINAL_PROCESSING = 0x0004;
 
+    private static final int FILE_TYPE_PIPE = 0x0003;
+
     private static final Linker LINKER = Linker.nativeLinker();
     private static final SymbolLookup KERNEL32 = SymbolLookup.libraryLookup(
             "kernel32", Arena.global());
@@ -47,6 +49,8 @@ public final class WindowsTerminal implements Terminal {
     private static final MethodHandle GET_CONSOLE_SCREEN_BUFFER_INFO = downcall(
             "GetConsoleScreenBufferInfo",
             FunctionDescriptor.of(ValueLayout.JAVA_INT, ValueLayout.ADDRESS, ValueLayout.ADDRESS));
+    private static final MethodHandle GET_FILE_TYPE = downcall("GetFileType",
+            FunctionDescriptor.of(ValueLayout.JAVA_INT, ValueLayout.ADDRESS));
 
     private final Arena arena;
     private final MemorySegment stdoutHandle;
@@ -194,6 +198,18 @@ private void restore() {
     private static int readMode(Arena arena, MemorySegment handle) throws Throwable {
         MemorySegment slot = arena.allocate(4);
         if ((int) GET_CONSOLE_MODE.invokeExact(handle, slot) == 0) {
+            // Under Git Bash / MSYS / MinTTY stdio is piped from the terminal
+            // emulator rather than attached to a real Windows console, so
+            // GetConsoleMode fails with ERROR_INVALID_HANDLE. Distinguish
+            // that case so the user gets a pointer to `winpty` instead of
+            // a bare "GetConsoleMode failed".
+            int fileType = (int) GET_FILE_TYPE.invokeExact(handle);
+            if (fileType == FILE_TYPE_PIPE) {
+                throw new IOException(
+                        "TUI requires a real Windows console. Git Bash / MinTTY pipes stdio, so "
+                        + "console APIs fail. Re-run via `winpty <command>` or switch to "
+                        + "Windows Terminal, PowerShell, or cmd.exe.");
+            }
             throw new IOException("GetConsoleMode failed");
         }
         return slot.get(ValueLayout.JAVA_INT, 0);

docs/how-to.md

@@ -125,6 +125,23 @@ The `, stats` suffix on a row indicates the node carries zone-map statistics
 `vortex.dict` nodes show their dictionary entries; flat numeric leaves show
 a hex preview of the encoded buffer plus decoded data.
 
+**Windows: Git Bash / MinTTY.** The TUI calls `GetConsoleMode` on stdio,
+which only works on a real Windows console handle. Git Bash and other
+MinTTY-based shells pipe stdio through the terminal emulator, so the
+console APIs fail and the TUI aborts with a `winpty` pointer in the error
+message. Two options:
+
+```bash
+# wrap with winpty (ships with Git for Windows)
+winpty java -jar vortex-cli-*-all.jar tui data.vortex
+
+# or switch to a terminal that attaches a real console: Windows Terminal,
+# PowerShell, or cmd.exe
+```
+
+`inspect` (static, non-interactive) works in any shell since it does not
+toggle terminal modes.
+
 ---
 
 ## Project columns