gflows 1.0.0 → 1.0.2

package/CHANGELOG.md

@@ -7,14 +7,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.0.2] - 2026-07-25
+
+### Changed
+
+- Hub read-only screens stay in Ink: `/doctor`, `/help`, `/status`, `/config`, `/version` (enter/esc return)
+
+## [1.0.1] - 2026-07-25
+
 ### Added
 
 - Fullscreen **Ink** TUI hub (`gflows` on TTY): bordered frame, tips / what’s next, actions, `❯` slash prompt, status bar
 - Slash commands: `/init` `/start` `/sync` `/pr` `/finish` `/doctor` `/help` …
+- In-hub `/` autocomplete (↑↓ select, Tab complete, Enter run)
 - Interactive prompts via **@clack/prompts** (Inquirer removed)
 - Legacy Clack menu fallback when TUI cannot run; `gflows viz` for scrollback panel
 - `gflows init`: optional `package.json` script alias (`--script-alias g`, TTY prompt); docs recommend shell `alias g=gflows` for shortest DX
-- Hub wizards (`/start`, `/finish`, `/sync`) run **inside Ink** (fewer Clack drop-outs); only git dispatch leaves the TUI
+- Hub wizards (`/start`, `/finish`, `/sync`, `/list`) run **inside Ink** (fewer drop-outs); only git dispatch leaves the TUI
+
+### Fixed
+
+- Hub no longer exits after dispatch (`stdin.ref` after Ink unmount; alternate screen)
+- `/list` renders a styled in-hub branch view instead of plain stdout under a tall gap
 
 ## [1.0.0] - 2026-07-24
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gflows",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "author": "Ali AlNaghmoush (https://github.com/alialnaghmoush)",
   "repository": {
     "type": "git",

package/src/commands/doctor.ts

@@ -17,34 +17,30 @@ import { hint, success } from "../out.js";
 import { readActiveRun } from "../run-state.js";
 import type { ParsedArgs } from "../types.js";
 
-interface Check {
+/** One doctor health check row. */
+export interface DoctorCheck {
   ok: boolean;
   name: string;
   detail: string;
 }
 
+/** Structured doctor report (CLI + hub). */
+export interface DoctorReport {
+  ok: boolean;
+  checks: DoctorCheck[];
+}
+
 /**
- * Runs health checks and prints a report (or JSON).
+ * Collects repo health checks without printing or exiting.
  */
-export async function run(args: ParsedArgs): Promise<void> {
-  let repoRoot: string;
-  try {
-    repoRoot = await resolveRepoRoot(args.cwd);
-  } catch (err) {
-    if (args.json) {
-      console.log(JSON.stringify({ ok: false, error: String(err) }, null, 2));
-      process.exit(2);
-    }
-    throw err;
-  }
-
-  const config = resolveConfig(
-    repoRoot,
-    { main: args.main, dev: args.dev, remote: args.remote },
-    { verbose: args.verbose },
-  );
+export async function collectDoctorReport(
+  cwd: string,
+  overrides?: { main?: string; dev?: string; remote?: string },
+): Promise<DoctorReport> {
+  const repoRoot = await resolveRepoRoot(cwd);
+  const config = resolveConfig(repoRoot, overrides ?? {}, {});
   const cfgRead = readConfigFile(repoRoot);
-  const checks: Check[] = [];
+  const checks: DoctorCheck[] = [];
 
   checks.push({
     ok: true,
@@ -121,9 +117,37 @@ export async function run(args: ParsedArgs): Promise<void> {
     detail: clean ? "clean" : "dirty (uncommitted changes)",
   });
 
-  const ok = checks.every((c) => c.ok);
+  return { ok: checks.every((c) => c.ok), checks };
+}
+
+/**
+ * Runs health checks and prints a report (or JSON).
+ */
+export async function run(args: ParsedArgs): Promise<void> {
+  let report: DoctorReport;
+  try {
+    report = await collectDoctorReport(args.cwd, {
+      main: args.main,
+      dev: args.dev,
+      remote: args.remote,
+    });
+  } catch (err) {
+    if (args.json) {
+      console.log(JSON.stringify({ ok: false, error: String(err) }, null, 2));
+      process.exit(2);
+    }
+    throw err;
+  }
+
+  const { ok, checks } = report;
 
   if (args.json) {
+    const repoRoot = await resolveRepoRoot(args.cwd);
+    const config = resolveConfig(
+      repoRoot,
+      { main: args.main, dev: args.dev, remote: args.remote },
+      { verbose: args.verbose },
+    );
     console.log(JSON.stringify({ ok, config, checks }, null, 2));
     if (!ok) process.exit(2);
     return;

package/src/commands/help.ts

@@ -6,10 +6,10 @@
 import type { ParsedArgs } from "../types.js";
 
 /**
- * Runs the help command: prints usage, commands, types, flags, and exit codes to stdout.
+ * Full help text (CLI stdout + hub scroll panel).
  */
-export async function run(_args: ParsedArgs): Promise<void> {
-  const out = `
+export function getHelpText(): string {
+  return `
 gflows — Modern Git branching workflow CLI
 
 Usage: gflows <command> [type] [name] [flags]
@@ -68,6 +68,12 @@ Exit codes: 0 success, 1 usage/validation, 2 Git or system error.
 
 Stuck?  gflows continue | gflows abort | gflows undo | gflows doctor
 Agents: see AGENTS.md, gflows schema, gflows mcp
-`;
-  console.log(out.trim());
+`.trim();
+}
+
+/**
+ * Runs the help command: prints usage, commands, types, flags, and exit codes to stdout.
+ */
+export async function run(_args: ParsedArgs): Promise<void> {
+  console.log(getHelpText());
 }

package/src/commands/mcp.ts

@@ -5,6 +5,7 @@
 
 import { EXIT_OK } from "../constants.js";
 import type { ParsedArgs } from "../types.js";
+import { getVersion } from "../version.js";
 
 interface JsonRpcRequest {
   jsonrpc?: string;
@@ -197,7 +198,7 @@ export async function run(_args: ParsedArgs): Promise<void> {
         respond(req.id, {
           protocolVersion: "2024-11-05",
           capabilities: { tools: {} },
-          serverInfo: { name: "gflows", version: "1.0.0" },
+          serverInfo: { name: "gflows", version: getVersion() },
         });
         continue;
       }

package/src/commands/schema.ts

@@ -5,6 +5,7 @@
 
 import type { ParsedArgs } from "../types.js";
 import { ALL_COMMANDS, BRANCH_TYPE_SHORTS } from "../types.js";
+import { getVersion } from "../version.js";
 
 /**
  * Emits JSON schema for agents and tooling.
@@ -12,7 +13,7 @@ import { ALL_COMMANDS, BRANCH_TYPE_SHORTS } from "../types.js";
 export async function run(_args: ParsedArgs): Promise<void> {
   const schema = {
     name: "gflows",
-    version: "1.0.0",
+    version: getVersion(),
     description: "Git branching workflow CLI (main + dev + typed short-lived branches)",
     exitCodes: {
       "0": "success",

package/src/commands/status-lines.ts

@@ -0,0 +1,92 @@
+/**
+ * Structured status lines for CLI-adjacent hub panels.
+ * Kept separate so `status.ts` stays focused on CLI printing.
+ * @module commands/status-lines
+ */
+
+import { resolveConfig } from "../config.js";
+import {
+  classifyBranch,
+  formatMergeTarget,
+  getBaseBranchName,
+  resolveMergeTarget,
+} from "../flow.js";
+import { getAheadBehind, getCurrentBranch, resolveRepoRoot } from "../git.js";
+import { readActiveRun } from "../run-state.js";
+
+/** One status line with optional tone for the hub panel. */
+export interface StatusLine {
+  text: string;
+  tone?: "default" | "ok" | "bad" | "muted" | "accent";
+}
+
+/**
+ * Collects human-readable status rows for the current branch.
+ */
+export async function collectStatusLines(cwd: string): Promise<StatusLine[]> {
+  const root = await resolveRepoRoot(cwd);
+  const config = resolveConfig(root, {}, {});
+  const current = await getCurrentBranch(root, {});
+  const active = readActiveRun(root);
+  const lines: StatusLine[] = [];
+
+  if (active) {
+    lines.push({
+      text: `Suspended: ${active.command} (${active.status})`,
+      tone: "bad",
+    });
+    lines.push({
+      text: "Run /continue after conflicts, or gflows abort / undo",
+      tone: "muted",
+    });
+  }
+
+  if (current === null) {
+    lines.push({ text: "HEAD is detached.", tone: "bad" });
+    lines.push({ text: "Try: git checkout dev", tone: "muted" });
+    return lines;
+  }
+
+  lines.push({ text: `Branch: ${current}`, tone: "accent" });
+
+  const classification = classifyBranch(current, config);
+
+  if (classification === "main") {
+    lines.push({ text: "Type: long-lived (main)" });
+    lines.push({ text: "Next: /start feature <name> or hotfix", tone: "muted" });
+    return lines;
+  }
+
+  if (classification === "dev") {
+    lines.push({ text: "Type: long-lived (dev)" });
+    lines.push({ text: "Next: /start feature <name>", tone: "muted" });
+    return lines;
+  }
+
+  if (classification === null) {
+    lines.push({ text: "Type: unknown" });
+    lines.push({ text: "Use a typed prefix or /start …", tone: "muted" });
+    return lines;
+  }
+
+  const mergeTarget = await resolveMergeTarget(root, current, classification, config, {});
+  const baseBranch = getBaseBranchName(
+    classification,
+    mergeTarget === "main-then-dev" && classification === "bugfix",
+    config,
+  );
+  const mergeTargetDisplay = formatMergeTarget(mergeTarget, config);
+  const { ahead, behind } = await getAheadBehind(root, baseBranch, current, {});
+
+  lines.push({ text: `Type: ${classification}` });
+  lines.push({ text: `Base: ${baseBranch}` });
+  lines.push({ text: `Merge target(s): ${mergeTargetDisplay}` });
+  lines.push({ text: `Ahead/behind: ${ahead} ahead, ${behind} behind` });
+  lines.push({
+    text:
+      ahead === 0 ? "No commits to finish yet — commit first" : `Next: /finish ${classification}`,
+    tone: ahead === 0 ? "muted" : "ok",
+  });
+
+  return lines;
+}

package/src/tui/HubHome.tsx

@@ -11,6 +11,7 @@ import { getCurrentBranch, resolveRepoRoot } from "../git.js";
 import { type RecommendAction, recommend } from "../recommend.js";
 import { getVersion } from "../version.js";
 import { collectVizSnapshot, type VizSnapshot } from "../viz.js";
+import { completeSlashInput, filterSlashCommands } from "./slash.js";
 
 const ACCENT = "#E88C4A";
 const MUTED = "#8A8A8A";
@@ -50,9 +51,12 @@ export function HubHome({
   const [repoPath, setRepoPath] = useState(cwd);
   const [selected, setSelected] = useState(0);
   const [input, setInput] = useState("");
+  const [slashIndex, setSlashIndex] = useState(0);
   const [showHelp, setShowHelp] = useState(false);
   const [loading, setLoading] = useState(true);
   const version = useMemo(() => getVersion(), []);
+  const slashMatches = useMemo(() => filterSlashCommands(input), [input]);
+  const slashMode = input.startsWith("/");
 
   useEffect(() => {
     let cancelled = false;
@@ -87,6 +91,17 @@ export function HubHome({
     if (selected >= actions.length) setSelected(Math.max(0, actions.length - 1));
   }, [actions.length, selected]);
 
+  useEffect(() => {
+    if (slashIndex >= slashMatches.length) {
+      setSlashIndex(Math.max(0, slashMatches.length - 1));
+    }
+  }, [slashMatches.length, slashIndex]);
+
+  const setSlashInput = (next: string) => {
+    setInput(next);
+    setSlashIndex(0);
+  };
+
   useInput((ch, key) => {
     if (key.ctrl && ch === "c") {
       onQuit();
@@ -94,7 +109,7 @@ export function HubHome({
     }
     if (key.escape) {
       if (input || showHelp) {
-        setInput("");
+        setSlashInput("");
         setShowHelp(false);
         return;
       }
@@ -109,23 +124,41 @@ export function HubHome({
       onQuit();
       return;
     }
+    if (key.tab && slashMode) {
+      const next = completeSlashInput(input, slashIndex);
+      if (next !== null) setSlashInput(next);
+      return;
+    }
     if (key.upArrow) {
+      if (slashMode && slashMatches.length > 0) {
+        setSlashIndex((i) => Math.max(0, i - 1));
+        return;
+      }
       setSelected((i) => Math.max(0, i - 1));
       return;
     }
     if (key.downArrow) {
+      if (slashMode && slashMatches.length > 0) {
+        setSlashIndex((i) => Math.min(slashMatches.length - 1, i + 1));
+        return;
+      }
       setSelected((i) => Math.min(actions.length - 1, i + 1));
       return;
     }
     if (key.backspace || key.delete) {
-      setInput((s) => [...s].slice(0, -1).join(""));
+      setSlashInput([...input].slice(0, -1).join(""));
       return;
     }
     if (key.return) {
       const cmd = input.trim();
       if (cmd.startsWith("/")) {
-        setInput("");
-        onSlash(cmd);
+        const match = slashMatches[slashIndex];
+        const body = cmd.slice(1);
+        const token = (body.split(/\s+/)[0] ?? "").toLowerCase();
+        const hasArgs = body.includes(" ");
+        const resolved = match && !hasArgs && token !== match.name ? `/${match.name}` : cmd;
+        setSlashInput("");
+        onSlash(resolved);
         return;
       }
       const action = actions[selected];
@@ -137,7 +170,7 @@ export function HubHome({
       return;
     }
     if (ch && !key.ctrl && !key.meta && ch >= " ") {
-      setInput((s) => s + ch);
+      setSlashInput(input + ch);
     }
   });
 
@@ -237,14 +270,29 @@ export function HubHome({
         <Box marginTop={1} flexDirection="column">
           <Text>
             <Text color={ACCENT}>❯ </Text>
-            {input || <Text color={MUTED}>type /start /finish /sync …</Text>}
+            {input || <Text color={MUTED}>type / for commands…</Text>}
             {input ? <Text color={ACCENT}>█</Text> : null}
           </Text>
-          <Text color={MUTED}>
-            {showHelp
-              ? "/init /start /sync /pr /finish /doctor /help  ·  esc clear  ·  ctrl+c quit"
-              : "? for shortcuts"}
-          </Text>
+          {slashMode && slashMatches.length > 0 ? (
+            <Box flexDirection="column" marginTop={0}>
+              {slashMatches.slice(0, 8).map((item, i) => {
+                const active = i === slashIndex;
+                return (
+                  <Text key={item.name} color={active ? FG : MUTED} bold={active}>
+                    {active ? <Text color={ACCENT}>› </Text> : "  "}/{item.name}
+                    <Text color={MUTED}>{`  ${item.hint}`}</Text>
+                  </Text>
+                );
+              })}
+              <Text color={MUTED}>↑↓ · tab complete · enter run · esc clear</Text>
+            </Box>
+          ) : (
+            <Text color={MUTED}>
+              {showHelp
+                ? "/init /start /sync /pr /finish /doctor /help  ·  esc clear  ·  ctrl+c quit"
+                : "? for shortcuts · / for command menu"}
+            </Text>
+          )}
         </Box>
       </Box>
 

package/src/tui/HubShell.tsx

@@ -6,9 +6,11 @@
 import { Box, Text, useApp, useInput } from "ink";
 import type React from "react";
 import { useState } from "react";
-import { FinishFlow, StartFlow, SyncFlow } from "./flows.js";
+import { FinishFlow, ListFlow, StartFlow, SyncFlow } from "./flows.js";
 import { HubHome } from "./HubHome.js";
 import { WizardFrame } from "./prompts.js";
+import { SLASH_COMMANDS } from "./slash.js";
+import { ConfigView, DoctorView, HelpView, StatusView, VersionView } from "./views.js";
 
 const ACCENT = "#E88C4A";
 const MUTED = "#8A8A8A";
@@ -22,8 +24,29 @@ type Screen =
   | { id: "start" }
   | { id: "finish" }
   | { id: "sync" }
+  | { id: "list" }
+  | { id: "doctor" }
+  | { id: "help" }
+  | { id: "status" }
+  | { id: "config" }
+  | { id: "version" }
   | { id: "notice"; message: string };
 
+/** Commands that leave Ink for git / side effects. */
+const DISPATCH_COMMANDS = new Set([
+  "init",
+  "pr",
+  "continue",
+  "switch",
+  "bump",
+  "delete",
+  "undo",
+  "abort",
+  "schema",
+  "mcp",
+  "completion",
+]);
+
 /**
  * Props for the hub shell.
  */
@@ -47,6 +70,43 @@ export function HubShell({ cwd, onDone }: HubShellProps): React.ReactElement {
   const cancelWizard = () => setScreen({ id: "home" });
   const runArgv = (argv: string[]) => finish({ kind: "run", argv });
 
+  const openInHub = (cmd: string): boolean => {
+    switch (cmd) {
+      case "start":
+        setScreen({ id: "start" });
+        return true;
+      case "finish":
+        setScreen({ id: "finish" });
+        return true;
+      case "sync":
+        setScreen({ id: "sync" });
+        return true;
+      case "list":
+        setScreen({ id: "list" });
+        return true;
+      case "doctor":
+        setScreen({ id: "doctor" });
+        return true;
+      case "help":
+        setScreen({ id: "help" });
+        return true;
+      case "status":
+        setScreen({ id: "status" });
+        return true;
+      case "config":
+        setScreen({ id: "config" });
+        return true;
+      case "version":
+        setScreen({ id: "version" });
+        return true;
+      case "viz":
+        setScreen({ id: "home", flash: "Branch map is shown on this screen." });
+        return true;
+      default:
+        return false;
+    }
+  };
+
   const handleSlash = (raw: string) => {
     const parts = raw.slice(1).trim().split(/\s+/);
     const cmd = (parts[0] ?? "").toLowerCase();
@@ -83,27 +143,25 @@ export function HubShell({ cwd, onDone }: HubShellProps): React.ReactElement {
       setScreen({ id: "sync" });
       return;
     }
-    if (cmd === "viz") {
-      setScreen({ id: "home", flash: "Branch map is shown on this screen." });
+    if (cmd === "config" && rest.length > 0) {
+      runArgv(["config", ...rest]);
       return;
     }
 
-    const known = new Set([
-      "init",
-      "pr",
-      "continue",
-      "switch",
-      "list",
-      "doctor",
-      "help",
-      "config",
-      "bump",
-      "status",
-    ]);
-    if (!known.has(cmd)) {
+    if (openInHub(cmd)) return;
+
+    if (!DISPATCH_COMMANDS.has(cmd) && !SLASH_COMMANDS.some((c) => c.name === cmd)) {
       setScreen({
         id: "notice",
-        message: `Unknown /${cmd} — press ? on the home screen for shortcuts.`,
+        message: `Unknown /${cmd} — type / for command hints.`,
+      });
+      return;
+    }
+
+    if (!DISPATCH_COMMANDS.has(cmd)) {
+      setScreen({
+        id: "notice",
+        message: `/${cmd} is not available from the hub yet.`,
       });
       return;
     }
@@ -116,18 +174,7 @@ export function HubShell({ cwd, onDone }: HubShellProps): React.ReactElement {
       finish({ kind: "quit" });
       return;
     }
-    if (action === "start") {
-      setScreen({ id: "start" });
-      return;
-    }
-    if (action === "finish") {
-      setScreen({ id: "finish" });
-      return;
-    }
-    if (action === "sync") {
-      setScreen({ id: "sync" });
-      return;
-    }
+    if (openInHub(action)) return;
     runArgv([action]);
   };
 
@@ -140,6 +187,24 @@ export function HubShell({ cwd, onDone }: HubShellProps): React.ReactElement {
   if (screen.id === "sync") {
     return <SyncFlow onCancel={cancelWizard} onDone={runArgv} />;
   }
+  if (screen.id === "list") {
+    return <ListFlow cwd={cwd} onDone={cancelWizard} />;
+  }
+  if (screen.id === "doctor") {
+    return <DoctorView cwd={cwd} onDone={cancelWizard} />;
+  }
+  if (screen.id === "help") {
+    return <HelpView onDone={cancelWizard} />;
+  }
+  if (screen.id === "status") {
+    return <StatusView cwd={cwd} onDone={cancelWizard} />;
+  }
+  if (screen.id === "config") {
+    return <ConfigView cwd={cwd} onDone={cancelWizard} />;
+  }
+  if (screen.id === "version") {
+    return <VersionView onDone={cancelWizard} />;
+  }
   if (screen.id === "notice") {
     return (
       <PressEnter

package/src/tui/flows.tsx

@@ -1,11 +1,13 @@
 /**
- * Multi-step Ink wizards for hub actions (start / finish / sync).
+ * Multi-step Ink wizards for hub actions (start / finish / sync / list).
  * @module tui/flows
  */
 
 import type React from "react";
-import { useState } from "react";
+import { useEffect, useState } from "react";
 import type { BranchType } from "../types.js";
+import { collectVizSnapshot, type VizSnapshot } from "../viz.js";
+import { type HubPanelLine, HubScrollPanel } from "./panels.js";
 import { InkConfirm, InkSelect, InkText, WizardFrame } from "./prompts.js";
 
 const BRANCH_TYPES: BranchType[] = ["feature", "bugfix", "chore", "release", "hotfix", "spike"];
@@ -138,3 +140,66 @@ export function SyncFlow({
     </WizardFrame>
   );
 }
+
+/**
+ * Styled branch list inside the hub (no drop-out to plain stdout).
+ */
+export function ListFlow({ cwd, onDone }: { cwd: string; onDone: () => void }): React.ReactElement {
+  const [lines, setLines] = useState<HubPanelLine[] | null>(null);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    let cancelled = false;
+    void (async () => {
+      try {
+        const snap = await collectVizSnapshot(cwd);
+        if (!cancelled) {
+          setLines(
+            formatListLines(snap).map((text, i) => ({
+              id: `b${i}`,
+              text,
+              tone: text.includes("●") ? ("ok" as const) : ("default" as const),
+            })),
+          );
+        }
+      } catch (err) {
+        if (!cancelled) {
+          setError(err instanceof Error ? err.message : String(err));
+          setLines([]);
+        }
+      }
+    })();
+    return () => {
+      cancelled = true;
+    };
+  }, [cwd]);
+
+  return <HubScrollPanel title="Branches" lines={lines} error={error} onDone={onDone} />;
+}
+
+/**
+ * Formats a viz snapshot into hub list rows.
+ */
+function formatListLines(snap: VizSnapshot): string[] {
+  const lines: string[] = [];
+  if (snap.suspended) lines.push(`⚠ suspended: ${snap.suspended}`);
+  for (const row of snap.rows) {
+    if (row.type !== "main" && row.type !== "dev") continue;
+    const mark = row.current ? "●" : "○";
+    lines.push(`${mark} ${row.name}  [${row.type}]`);
+  }
+  const workflow = snap.rows.filter((r) => r.type !== "main" && r.type !== "dev");
+  if (workflow.length === 0) {
+    lines.push("  (no workflow branches)");
+  } else {
+    for (let i = 0; i < workflow.length; i++) {
+      const row = workflow[i];
+      if (!row) continue;
+      const elbow = i === workflow.length - 1 ? "└─" : "├─";
+      const mark = row.current ? "●" : "○";
+      const ab = row.ahead === 0 && row.behind === 0 ? "synced" : `+${row.ahead}/-${row.behind}`;
+      lines.push(`${elbow} ${mark} ${row.name}  (${row.type}) ${ab}`);
+    }
+  }
+  return lines;
+}

package/src/tui/hub.ts

@@ -57,6 +57,12 @@ function runHubSession(cwd: string): Promise<HubSessionResult> {
           instance.unmount();
         },
       }),
+      {
+        // Keep hub off the primary scrollback so command output isn't stranded
+        // under a full-height cleared frame when we drop out for dispatch.
+        alternateScreen: true,
+        exitOnCtrlC: false,
+      },
     );
     void instance.waitUntilExit().then(() => {
       done({ kind: "quit" });
@@ -66,24 +72,43 @@ function runHubSession(cwd: string): Promise<HubSessionResult> {
 
 /**
  * Raw stdin “press enter” (no Clack / no Ink).
+ * Ink unrefs stdin on unmount — we must ref it again or the process exits
+ * before the user can return to the hub.
  */
 function waitEnterRaw(label: string): Promise<void> {
   return new Promise((resolve) => {
+    const stdin = process.stdin;
     process.stdout.write(`${label}\n`);
-    if (typeof process.stdin.setRawMode === "function") {
-      process.stdin.setRawMode(true);
+    if (typeof stdin.setRawMode === "function") {
+      stdin.setRawMode(true);
     }
-    process.stdin.resume();
+    stdin.resume();
+    stdin.ref();
+
+    // Drop buffered Enter from the hub key that launched this command.
+    if (typeof stdin.read === "function") {
+      for (;;) {
+        const pending = stdin.read();
+        if (pending === null) break;
+      }
+    }
+
+    const cleanup = () => {
+      stdin.off("data", onData);
+      if (typeof stdin.setRawMode === "function") {
+        stdin.setRawMode(false);
+      }
+      stdin.pause();
+      stdin.unref();
+    };
+
     const onData = (chunk: string | Buffer) => {
       const s = typeof chunk === "string" ? chunk : chunk.toString("utf8");
-      if (s === "\r" || s === "\n" || s === "\x03") {
-        process.stdin.off("data", onData);
-        if (typeof process.stdin.setRawMode === "function") {
-          process.stdin.setRawMode(false);
-        }
+      if (s.includes("\r") || s.includes("\n") || s.includes("\x03")) {
+        cleanup();
         resolve();
       }
     };
-    process.stdin.on("data", onData);
+    stdin.on("data", onData);
   });
 }

package/src/tui/panels.tsx

@@ -0,0 +1,111 @@
+/**
+ * Shared Ink panels for in-hub result screens (doctor / help / status / …).
+ * @module tui/panels
+ */
+
+import { Box, Text, useInput, useStdout } from "ink";
+import type React from "react";
+import { useState } from "react";
+import { WizardFrame } from "./prompts.js";
+
+const ACCENT = "#E88C4A";
+const MUTED = "#8A8A8A";
+const FG = "#E6E6E6";
+const GREEN = "#78C88C";
+const RED = "#E06C75";
+
+/** One styled line for {@link HubScrollPanel}. */
+export interface HubPanelLine {
+  /** Stable React key for the row. */
+  id: string;
+  text: string;
+  tone?: "default" | "ok" | "bad" | "muted" | "accent";
+}
+
+/**
+ * Scrollable framed panel that returns to the hub on enter/esc.
+ */
+export function HubScrollPanel({
+  title,
+  lines,
+  loading,
+  error,
+  onDone,
+}: {
+  title: string;
+  lines: HubPanelLine[] | null;
+  loading?: boolean;
+  error?: string | null;
+  onDone: () => void;
+}): React.ReactElement {
+  const { stdout } = useStdout();
+  const rows = stdout?.rows ?? 24;
+  const lineCount = lines?.length ?? 0;
+  const budget = Math.max(6, Math.min(lineCount || 6, rows - 8));
+  const [offset, setOffset] = useState(0);
+  const maxOffset = Math.max(0, lineCount - budget);
+  const safeOffset = Math.min(offset, maxOffset);
+  const visible = lines?.slice(safeOffset, safeOffset + budget) ?? [];
+
+  useInput((ch, key) => {
+    if (key.return || key.escape || (key.ctrl && ch === "c")) {
+      onDone();
+      return;
+    }
+    if (key.upArrow || ch === "k") {
+      setOffset((o) => Math.max(0, o - 1));
+      return;
+    }
+    if (key.downArrow || ch === "j") {
+      setOffset((o) => Math.min(maxOffset, o + 1));
+      return;
+    }
+    if (key.pageUp) {
+      setOffset((o) => Math.max(0, o - budget));
+      return;
+    }
+    if (key.pageDown) {
+      setOffset((o) => Math.min(maxOffset, o + budget));
+    }
+  });
+
+  return (
+    <WizardFrame title={title}>
+      {loading || lines === null ? (
+        <Text color={MUTED}>Loading…</Text>
+      ) : error ? (
+        <Text color={RED}>{error}</Text>
+      ) : (
+        <Box flexDirection="column">
+          {visible.map((line) => (
+            <Text key={line.id} color={toneColor(line.tone)} bold={line.tone === "ok"}>
+              {line.text}
+            </Text>
+          ))}
+        </Box>
+      )}
+      <Box marginTop={1}>
+        <Text color={MUTED}>
+          {maxOffset > 0 ? "↑↓ scroll · " : ""}
+          enter / esc return to hub
+        </Text>
+        <Text color={ACCENT}> █</Text>
+      </Box>
+    </WizardFrame>
+  );
+}
+
+function toneColor(tone: HubPanelLine["tone"]): string {
+  switch (tone) {
+    case "ok":
+      return GREEN;
+    case "bad":
+      return RED;
+    case "muted":
+      return MUTED;
+    case "accent":
+      return ACCENT;
+    default:
+      return FG;
+  }
+}

package/src/tui/slash.ts

@@ -0,0 +1,64 @@
+/**
+ * Slash-command catalog for the Ink hub prompt.
+ * @module tui/slash
+ */
+
+/** One slash command shown in hub autocomplete. */
+export interface SlashCommand {
+  /** Command name without leading `/`. */
+  name: string;
+  /** Short description for the suggestion list. */
+  hint: string;
+}
+
+/**
+ * Hub slash commands (order = suggestion priority).
+ */
+export const SLASH_COMMANDS: readonly SlashCommand[] = [
+  { name: "init", hint: "Initialize repo" },
+  { name: "start", hint: "Start new work (wizard)" },
+  { name: "sync", hint: "Sync with base (wizard)" },
+  { name: "pr", hint: "Open pull request" },
+  { name: "finish", hint: "Finish / merge (wizard)" },
+  { name: "continue", hint: "Continue suspended run" },
+  { name: "switch", hint: "Switch branch" },
+  { name: "list", hint: "List branches" },
+  { name: "doctor", hint: "Doctor checks" },
+  { name: "help", hint: "Show help" },
+  { name: "status", hint: "Repo status" },
+  { name: "config", hint: "Show config" },
+  { name: "version", hint: "Show version" },
+  { name: "bump", hint: "Bump version" },
+  { name: "viz", hint: "Branch map (on home)" },
+  { name: "quit", hint: "Leave hub" },
+] as const;
+
+/**
+ * Filters slash commands by the typed buffer (e.g. `/st` → start, status, switch).
+ */
+export function filterSlashCommands(input: string): SlashCommand[] {
+  if (!input.startsWith("/")) return [];
+  const body = input.slice(1);
+  const token = (body.split(/\s+/)[0] ?? "").toLowerCase();
+  // After a completed command + space, stop suggesting names
+  if (body.includes(" ") && token.length > 0) {
+    const exact = SLASH_COMMANDS.some((c) => c.name === token);
+    if (exact) return [];
+  }
+  if (token.length === 0) return [...SLASH_COMMANDS];
+  return SLASH_COMMANDS.filter((c) => c.name.startsWith(token));
+}
+
+/**
+ * Completes the command portion of a slash buffer (Tab).
+ * @returns updated input, or null if nothing to complete.
+ */
+export function completeSlashInput(input: string, selectedIndex = 0): string | null {
+  const matches = filterSlashCommands(input);
+  if (matches.length === 0) return null;
+  const pick = matches[Math.min(selectedIndex, matches.length - 1)];
+  if (!pick) return null;
+  const rest = input.includes(" ") ? input.slice(input.indexOf(" ")) : "";
+  if (rest.trim().length > 0) return null;
+  return `/${pick.name}${matches.length === 1 ? " " : ""}`;
+}

package/src/tui/views.tsx

@@ -0,0 +1,182 @@
+/**
+ * Read-only Ink screens that stay inside the hub (doctor / help / status / config).
+ * @module tui/views
+ */
+
+import type React from "react";
+import { useEffect, useState } from "react";
+import { collectDoctorReport } from "../commands/doctor.js";
+import { getHelpText } from "../commands/help.js";
+import { collectStatusLines } from "../commands/status-lines.js";
+import { resolveConfig } from "../config.js";
+import { resolveRepoRoot } from "../git.js";
+import { getVersion } from "../version.js";
+import { type HubPanelLine, HubScrollPanel } from "./panels.js";
+
+/**
+ * Doctor checks inside the hub.
+ */
+export function DoctorView({
+  cwd,
+  onDone,
+}: {
+  cwd: string;
+  onDone: () => void;
+}): React.ReactElement {
+  const [lines, setLines] = useState<HubPanelLine[] | null>(null);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    let cancelled = false;
+    void (async () => {
+      try {
+        const report = await collectDoctorReport(cwd);
+        if (cancelled) return;
+        const rows: HubPanelLine[] = report.checks.map((c) => ({
+          id: c.name,
+          text: `${c.ok ? "✓" : "✗"} ${c.name}: ${c.detail}`,
+          tone: c.ok ? "ok" : "bad",
+        }));
+        rows.push({
+          id: "summary",
+          text: report.ok
+            ? "gflows doctor: all critical checks passed."
+            : "gflows doctor: some checks failed.",
+          tone: report.ok ? "ok" : "bad",
+        });
+        setLines(rows);
+      } catch (err) {
+        if (!cancelled) {
+          setError(err instanceof Error ? err.message : String(err));
+          setLines([]);
+        }
+      }
+    })();
+    return () => {
+      cancelled = true;
+    };
+  }, [cwd]);
+
+  return <HubScrollPanel title="Doctor" lines={lines} error={error} onDone={onDone} />;
+}
+
+/**
+ * Scrollable help inside the hub.
+ */
+export function HelpView({ onDone }: { onDone: () => void }): React.ReactElement {
+  const lines: HubPanelLine[] = getHelpText()
+    .split("\n")
+    .map((text, i) => ({
+      id: `h${i}`,
+      text: text.length === 0 ? " " : text,
+      tone: text.endsWith(":") || text.startsWith("gflows") ? "accent" : "default",
+    }));
+
+  return <HubScrollPanel title="Help" lines={lines} onDone={onDone} />;
+}
+
+/**
+ * Branch status inside the hub.
+ */
+export function StatusView({
+  cwd,
+  onDone,
+}: {
+  cwd: string;
+  onDone: () => void;
+}): React.ReactElement {
+  const [lines, setLines] = useState<HubPanelLine[] | null>(null);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    let cancelled = false;
+    void (async () => {
+      try {
+        const rows = await collectStatusLines(cwd);
+        if (!cancelled) {
+          setLines(
+            rows.map((row, i) => ({
+              id: `s${i}`,
+              text: row.text,
+              tone: row.tone,
+            })),
+          );
+        }
+      } catch (err) {
+        if (!cancelled) {
+          setError(err instanceof Error ? err.message : String(err));
+          setLines([]);
+        }
+      }
+    })();
+    return () => {
+      cancelled = true;
+    };
+  }, [cwd]);
+
+  return <HubScrollPanel title="Status" lines={lines} error={error} onDone={onDone} />;
+}
+
+/**
+ * Resolved config snapshot inside the hub (read-only).
+ */
+export function ConfigView({
+  cwd,
+  onDone,
+}: {
+  cwd: string;
+  onDone: () => void;
+}): React.ReactElement {
+  const [lines, setLines] = useState<HubPanelLine[] | null>(null);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    let cancelled = false;
+    void (async () => {
+      try {
+        const root = await resolveRepoRoot(cwd);
+        const config = resolveConfig(root, {}, {});
+        if (cancelled) return;
+        setLines([
+          { id: "main", text: `main: ${config.main}`, tone: "accent" },
+          { id: "dev", text: `dev: ${config.dev}` },
+          { id: "remote", text: `remote: ${config.remote}` },
+          { id: "prefixes", text: "prefixes:", tone: "muted" },
+          ...Object.entries(config.prefixes).map(([type, prefix]) => ({
+            id: `p-${type}`,
+            text: `  ${type}: ${prefix}`,
+          })),
+          { id: "blank", text: " ", tone: "muted" },
+          {
+            id: "hint",
+            text: "Use: gflows config set <key> <value>",
+            tone: "muted",
+          },
+        ]);
+      } catch (err) {
+        if (!cancelled) {
+          setError(err instanceof Error ? err.message : String(err));
+          setLines([]);
+        }
+      }
+    })();
+    return () => {
+      cancelled = true;
+    };
+  }, [cwd]);
+
+  return <HubScrollPanel title="Config" lines={lines} error={error} onDone={onDone} />;
+}
+
+/**
+ * Version chip inside the hub.
+ */
+export function VersionView({ onDone }: { onDone: () => void }): React.ReactElement {
+  return (
+    <HubScrollPanel
+      title="Version"
+      lines={[{ id: "v", text: `gflows v${getVersion()}`, tone: "accent" }]}
+      onDone={onDone}
+    />
+  );
+}