@carlesandres/house 0.4.6 → 0.4.8

package/src/CommandPalette.tsx

@@ -1,12 +1,14 @@
 /**
  * CommandPalette — modal overlay for searching and running commands.
  *
- * Render-only: state lives in Browser.tsx alongside helpVisible / filterOpen
+ * Render-only: state lives in Browser.tsx alongside filterOpen
  * (#70 design log §state location). Key handling sits in Browser.tsx's
  * `useKeyboard` palette-branch, mirroring the filterOpen pattern.
  *
- * V1 ships a flat list in `browserBindings` order — no category headers,
- * no mouse, no recency. See #91/#93/#94/#95/#96 for the follow-ups.
+ * Commands are grouped by semantic category while preserving command order
+ * inside each group. Browser.tsx owns the query and selected command index;
+ * this component turns those commands into render rows and keeps the selected
+ * row visible when the list is taller than the modal body.
  */
 
 import { RGBA } from "@opentui/core"
@@ -29,6 +31,52 @@ export interface CommandPaletteProps {
 }
 
 const FOOTER_HINT = "↑↓ select  enter run  esc close"
+const CATEGORY_ORDER = ["Navigation", "View", "File", "Appearance", "App"] as const
+
+type PaletteRow =
+	| { readonly kind: "spacer"; readonly key: string }
+	| { readonly kind: "header"; readonly key: string; readonly text: string }
+	| {
+			readonly kind: "command"
+			readonly key: string
+			readonly command: AppCommand
+			readonly commandIndex: number
+	  }
+
+export const orderCommandsForPalette = (commands: readonly AppCommand[]): readonly AppCommand[] => {
+	const grouped = new Map<string, AppCommand[]>()
+	for (const command of commands) {
+		const category = command.category ?? "Other"
+		const list = grouped.get(category)
+		if (list) list.push(command)
+		else grouped.set(category, [command])
+	}
+
+	const orderedCategories = [
+		...CATEGORY_ORDER.filter((category) => grouped.has(category)),
+		...Array.from(grouped.keys()).filter((category) => !CATEGORY_ORDER.includes(category as never)),
+	]
+
+	return orderedCategories.flatMap((category) => grouped.get(category) ?? [])
+}
+
+const buildRows = (commands: readonly AppCommand[]): readonly PaletteRow[] => {
+	const orderedCommands = orderCommandsForPalette(commands)
+	const rows: PaletteRow[] = []
+	let previousCategory: string | null = null
+	let commandIndex = 0
+	for (const command of orderedCommands) {
+		const category = command.category ?? "Other"
+		if (category !== previousCategory) {
+			if (previousCategory !== null) rows.push({ kind: "spacer", key: `spacer-${category}` })
+			rows.push({ kind: "header", key: `header-${category}`, text: category })
+			previousCategory = category
+		}
+		rows.push({ kind: "command", key: command.id, command, commandIndex })
+		commandIndex += 1
+	}
+	return rows
+}
 
 export const CommandPalette = ({
 	commands,
@@ -38,11 +86,12 @@ export const CommandPalette = ({
 	viewportHeight,
 }: CommandPaletteProps) => {
 	const overlayWidth = Math.min(viewportWidth - 4, 64)
+	const rows = buildRows(commands)
 	// Reserve: 2 for border (top+bottom), 1 query row, 1 spacer below query,
 	// 1 spacer above footer, 1 footer row. Body gets the rest.
 	const chrome = 2 + 1 + 1 + 1 + 1
 	const maxBody = Math.max(1, viewportHeight - 4 - chrome)
-	const desiredBody = Math.max(1, commands.length || 1)
+	const desiredBody = Math.max(1, rows.length || 1)
 	const bodyHeight = Math.min(desiredBody, maxBody)
 	const overlayHeight = chrome + bodyHeight
 	const left = Math.max(0, Math.floor((viewportWidth - overlayWidth) / 2))
@@ -51,17 +100,19 @@ export const CommandPalette = ({
 	// Inner content width: overlay minus 1-cell border + 1-cell padding on each side.
 	const rowWidth = Math.max(4, overlayWidth - 4)
 
-	// Window the visible slice around the selection. With 9 commands in v1
-	// this is usually a no-op (list fits), but the math is in place for the
-	// inevitable backlog growth.
+	// Window the visible slice around the selected command row. Headers and
+	// spacers are render-only rows, so selection still tracks command indexes.
 	const scrollTop = (() => {
-		if (commands.length <= bodyHeight) return 0
-		const maxScroll = commands.length - bodyHeight
+		if (rows.length <= bodyHeight) return 0
+		const maxScroll = rows.length - bodyHeight
 		let s = 0
-		if (selectedIndex >= bodyHeight) s = selectedIndex - bodyHeight + 1
+		const selectedRowIndex = rows.findIndex(
+			(row) => row.kind === "command" && row.commandIndex === selectedIndex,
+		)
+		if (selectedRowIndex >= bodyHeight) s = selectedRowIndex - bodyHeight + 1
 		return Math.max(0, Math.min(s, maxScroll))
 	})()
-	const visible = commands.slice(scrollTop, scrollTop + bodyHeight)
+	const visible = rows.slice(scrollTop, scrollTop + bodyHeight)
 
 	// Shortcut column width — long enough for `shift+t`-style chords but
 	// trimmed to prevent the title from being squeezed below ~16 cells.
@@ -110,9 +161,22 @@ export const CommandPalette = ({
 				{commands.length === 0 ? (
 					<text wrapMode="none" content="  (no matches)" style={{ fg: colors.textMuted }} />
 				) : (
-					visible.map((cmd, i) => {
-						const realIdx = scrollTop + i
-						const isSelected = realIdx === selectedIndex
+					visible.map((row) => {
+						if (row.kind === "spacer") {
+							return <text key={row.key} content=" " />
+						}
+						if (row.kind === "header") {
+							return (
+								<text
+									key={row.key}
+									wrapMode="none"
+									content={fit(row.text, rowWidth)}
+									style={{ fg: colors.textMuted, attributes: 1 }}
+								/>
+							)
+						}
+						const cmd = row.command
+						const isSelected = row.commandIndex === selectedIndex
 						const selector = isSelected ? "▸ " : "  "
 						const titleText = fit(cmd.title, titleWidth)
 						const shortcutText = cmd.shortcut

package/src/Footer.tsx

@@ -21,8 +21,10 @@
  * require a real cell-width counter (e.g. East Asian Width).
  */
 
+import type React from "react"
 import type { KeyBinding } from "./keymap/keymap.ts"
 import { displayKey } from "./keymap/displayKey.ts"
+import { Spinner } from "./Spinner.tsx"
 import { colors } from "./theme/colors.ts"
 
 /** Rows the Footer occupies. Importers use it for layout math so a future
@@ -38,24 +40,26 @@ export interface FooterProps<C> {
 	 *  no TTL, cleared by the caller when the underlying activity finishes.
 	 *  Loses to `notice` when both are set so transient toasts still surface. */
 	readonly discoveryStatus?: string | null
-	/** When a filter is applied but the input is closed, surface a chip in the
-	 *  hint row so the user remembers `[`/`]` walks the filtered set. Pass null
-	 *  while the filter input is open (the sidebar already shows the query) or
-	 *  when no filter is applied. */
-	readonly filterQuery?: string | null
+	/** Test seam: override spinner tick speed so tests don't sleep on the full
+	 *  production interval. Ignored when discoveryStatus is null. */
+	readonly discoverySpinnerIntervalMs?: number
+	readonly discoverySpinnerInitialFrameIndex?: number
+	/** Test seam: deterministic footer spinner driver. */
+	readonly discoverySpinnerRegisterTick?: ((tick: () => void) => void) | null
+	/** Optional toggle callback for the discovery-warning popover. */
+	readonly onDiscoveryWarningToggle?: () => void
 }
 
+const normalizeStatusLine = (status: string): string => status.replace(/\s+/g, " ").trim()
+
 const HINT_SEPARATOR = "  "
 
-/** Hint row entries. `key === null` is a standalone chip (e.g. the filter
- *  chip) and renders as muted text without the key/label split. */
 interface Hint {
-	readonly key: string | null
+	readonly key: string
 	readonly label: string
 }
 
-const hintWidth = (h: Hint): number =>
-	h.key === null ? h.label.length : h.key.length + 1 + h.label.length // key + " " + label
+const hintWidth = (h: Hint): number => h.key.length + 1 + h.label.length // key + " " + label
 
 const formatHint = <C,>(b: KeyBinding<C>): Hint | null => {
 	if (!b.hint) return null
@@ -65,8 +69,8 @@ const formatHint = <C,>(b: KeyBinding<C>): Hint | null => {
 }
 
 /** Drop hints from the end until they fit within `width`. If not even the
- *  first hint fits, fall back to the bare key (or label chip) truncated to
- *  width, so the row is never silently blank on tight viewports. */
+ *  first hint fits, fall back to the bare key truncated to width, so the row
+ *  is never silently blank on tight viewports. */
 const fitHints = (hints: readonly Hint[], width: number): Hint[] => {
 	if (width <= 0 || hints.length === 0) return []
 	const acc: Hint[] = []
@@ -79,19 +83,24 @@ const fitHints = (hints: readonly Hint[], width: number): Hint[] => {
 	}
 	if (acc.length > 0) return acc
 	const first = hints[0]!
-	if (first.key === null) return [{ key: null, label: first.label.slice(0, width) }]
 	return [{ key: first.key.slice(0, width), label: "" }]
 }
 
 const STATUS_SEPARATOR = " · "
 
+const isPartialDiscoveryWarning = (status: string | null): boolean =>
+	status?.startsWith("scan incomplete:") ?? false
+
 export const Footer = <C,>({
 	bindings,
 	ctx,
 	width,
 	notice,
 	discoveryStatus,
-	filterQuery,
+	discoverySpinnerIntervalMs,
+	discoverySpinnerInitialFrameIndex,
+	discoverySpinnerRegisterTick,
+	onDiscoveryWarningToggle,
 }: FooterProps<C>) => {
 	const usableWidth = Math.max(0, width - 2) // 1-cell horizontal padding each side
 
@@ -106,13 +115,6 @@ export const Footer = <C,>({
 	} as const
 
 	const hints: Hint[] = []
-	// The filter chip prepends to the hint row when a filter is applied and the
-	// input is closed. Bracketed to avoid looking like a `key:hint` binding —
-	// "filter" is not a key. Surfaces the otherwise-invisible invariant that
-	// `[`/`]` walks the filtered set. See DESIGN.md §7.1 Q1.
-	if (filterQuery && filterQuery.length > 0) {
-		hints.push({ key: null, label: `[filter: ${filterQuery}]` })
-	}
 	for (const b of bindings) {
 		// Hint visibility prefers `hintWhen` (binding-specific) over `when`
 		// (dispatch gate). Falling back to `when` keeps the original
@@ -126,14 +128,17 @@ export const Footer = <C,>({
 	// Discovery status sits left of the hints, separated by " · ". On tight
 	// viewports it claims its budget first; hints fit into the remainder so
 	// the indicator stays visible while less-essential hints drop off.
-	const status = discoveryStatus && discoveryStatus.length > 0 ? discoveryStatus : null
-	const statusBudget = status ? Math.min(status.length + STATUS_SEPARATOR.length, usableWidth) : 0
+	const status =
+		discoveryStatus && discoveryStatus.length > 0 ? normalizeStatusLine(discoveryStatus) : null
+	const isPartialWarning = isPartialDiscoveryWarning(status)
+	const statusBudget = status
+		? Math.min((isPartialWarning ? 1 : status.length) + STATUS_SEPARATOR.length, usableWidth)
+		: 0
 	const hintsWidth = Math.max(0, usableWidth - statusBudget)
 	const visibleHints = fitHints(hints, hintsWidth)
 	const statusContent = status
 		? status.slice(0, Math.max(0, statusBudget - STATUS_SEPARATOR.length))
 		: ""
-
 	const noticeContent = notice
 		? notice.length > usableWidth
 			? notice.slice(0, usableWidth)
@@ -156,12 +161,6 @@ export const Footer = <C,>({
 							/>,
 						]
 					: []
-			if (h.key === null) {
-				return [
-					...sep,
-					<text key={`l${i}`} content={h.label} wrapMode="none" style={{ fg: colors.secondary }} />,
-				]
-			}
 			return [
 				...sep,
 				<text key={`k${i}`} content={h.key} wrapMode="none" style={{ fg: colors.text }} />,
@@ -184,10 +183,45 @@ export const Footer = <C,>({
 		)
 	}
 
+	const warningTrigger = isPartialWarning ? (
+		<box
+			{...(onDiscoveryWarningToggle === undefined ? {} : { onMouseUp: onDiscoveryWarningToggle })}
+			style={{
+				width: 1,
+				height: 1,
+				flexDirection: "row",
+				backgroundColor: colors.backgroundElement,
+			}}
+		>
+			<text content="!" wrapMode="none" style={{ fg: colors.warning, attributes: 1 }} />
+		</box>
+	) : null
+
 	if (status !== null) {
+		const spinnerProps = {
+			fg: colors.secondary,
+			...(discoverySpinnerIntervalMs === undefined
+				? {}
+				: { intervalMs: discoverySpinnerIntervalMs }),
+			...(discoverySpinnerInitialFrameIndex === undefined
+				? {}
+				: { initialFrameIndex: discoverySpinnerInitialFrameIndex }),
+			...(discoverySpinnerRegisterTick === undefined
+				? {}
+				: { registerTick: discoverySpinnerRegisterTick }),
+		} satisfies React.ComponentProps<typeof Spinner>
+
 		return (
 			<box style={rowStyle}>
-				<text content={statusContent} wrapMode="none" style={{ fg: colors.secondary }} />
+				{isPartialWarning ? null : <Spinner {...spinnerProps} />}
+				{isPartialWarning ? null : (
+					<text content=" " wrapMode="none" style={{ fg: colors.textMuted }} />
+				)}
+				{isPartialWarning ? (
+					warningTrigger
+				) : (
+					<text content={statusContent} wrapMode="none" style={{ fg: colors.secondary }} />
+				)}
 				<text content={STATUS_SEPARATOR} wrapMode="none" style={{ fg: colors.textMuted }} />
 				{renderHints()}
 			</box>

package/src/Header.tsx

@@ -61,7 +61,10 @@ export const Header = ({ width, currentFile, version = pkg.version }: HeaderProp
 				backgroundColor: colors.backgroundPanel,
 			}}
 		>
-			<text content={left} wrapMode="none" style={{ fg: colors.text }} />
+			<text wrapMode="none">
+				<span style={{ fg: colors.text }}>{brand}</span>
+				{showFile && <span style={{ fg: colors.textMuted }}>{`${FILE_SEPARATOR}${file}`}</span>}
+			</text>
 			{showRight && <text content={right} wrapMode="none" style={{ fg: colors.text }} />}
 		</box>
 	)

package/src/Spinner.tsx

@@ -0,0 +1,39 @@
+import { useEffect, useRef, useState } from "react"
+import { colors } from "./theme/colors.ts"
+
+const FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"] as const
+const FRAME_COUNT = FRAMES.length
+const normalizeFrameIndex = (index: number) => ((index % FRAME_COUNT) + FRAME_COUNT) % FRAME_COUNT
+
+export interface SpinnerProps {
+	readonly fg?: string
+	readonly intervalMs?: number
+	readonly initialFrameIndex?: number
+	/** Test seam: deterministic driver for frame advancement. When present,
+	 *  Spinner registers its tick callback here instead of starting an interval. */
+	readonly registerTick?: ((tick: () => void) => void) | null
+}
+
+export const Spinner = ({
+	fg = colors.textMuted,
+	intervalMs = 100,
+	initialFrameIndex = 0,
+	registerTick = null,
+}: SpinnerProps) => {
+	const [index, setIndex] = useState(() => normalizeFrameIndex(initialFrameIndex))
+	const tickRef = useRef<() => void>(() => undefined)
+	tickRef.current = () => setIndex((prev) => (prev + 1) % FRAME_COUNT)
+
+	useEffect(() => {
+		if (registerTick) {
+			registerTick(() => tickRef.current())
+			return
+		}
+		const id = setInterval(() => {
+			tickRef.current()
+		}, intervalMs)
+		return () => clearInterval(id)
+	}, [intervalMs, registerTick])
+
+	return <text content={FRAMES[index] ?? FRAMES[0]} wrapMode="none" style={{ fg }} />
+}

package/src/StatusPopover.tsx

@@ -0,0 +1,189 @@
+import { useTerminalDimensions } from "@opentui/react"
+import { useMemo, useState } from "react"
+import { colors } from "./theme/colors.ts"
+
+export type StatusPopoverVariant = "info" | "warning" | "error" | "success"
+
+export interface StatusPopoverProps {
+	readonly icon: string
+	readonly content: string
+	readonly variant?: StatusPopoverVariant
+	readonly open?: boolean
+	readonly defaultOpen?: boolean
+	readonly onOpenChange?: (open: boolean) => void
+	readonly showPanel?: boolean
+	readonly minWidth?: number
+	readonly maxWidth?: number
+	readonly maxHeight?: number
+	readonly zIndex?: number
+}
+
+export interface StatusPopoverPanelProps {
+	readonly content: string
+	readonly variant?: StatusPopoverVariant
+	readonly minWidth?: number
+	readonly maxWidth?: number
+	readonly maxHeight?: number
+	readonly zIndex?: number
+}
+
+const clamp = (n: number, min: number, max: number) => Math.max(min, Math.min(max, n))
+
+const variantFg = (variant: StatusPopoverVariant): string => {
+	switch (variant) {
+		case "info":
+			return colors.info
+		case "warning":
+			return colors.warning
+		case "error":
+			return colors.error
+		case "success":
+			return colors.success
+	}
+}
+
+const measureLine = (line: string): number => line.length
+
+const wrapLine = (line: string, width: number): string[] => {
+	if (width <= 0) return [line]
+	if (line.length <= width) return [line]
+	const out: string[] = []
+	let i = 0
+	while (i < line.length) {
+		out.push(line.slice(i, i + width))
+		i += width
+	}
+	return out
+}
+
+export const StatusPopover = ({
+	icon,
+	content,
+	variant = "warning",
+	open,
+	defaultOpen = false,
+	onOpenChange,
+	showPanel = true,
+	minWidth = 14,
+	maxWidth = 40,
+	maxHeight = 12,
+	zIndex = 30,
+}: StatusPopoverProps) => {
+	const { width: viewportWidth, height: viewportHeight } = useTerminalDimensions()
+	const [uncontrolledOpen, setUncontrolledOpen] = useState(defaultOpen)
+	const isOpen = open ?? uncontrolledOpen
+	const setOpen = (next: boolean) => {
+		if (open === undefined) setUncontrolledOpen(next)
+		onOpenChange?.(next)
+	}
+
+	const lines = useMemo(() => content.split(/\r?\n/), [content])
+	const textWidth = useMemo(() => {
+		const widest = Math.max(1, ...lines.map(measureLine))
+		return clamp(widest, minWidth, Math.min(maxWidth, Math.max(1, viewportWidth - 4)))
+	}, [content, lines, maxWidth, minWidth, viewportWidth])
+
+	const wrapped = useMemo(
+		() => lines.flatMap((line) => wrapLine(line, textWidth)),
+		[lines, textWidth],
+	)
+	const bodyHeight = Math.min(maxHeight, Math.max(1, wrapped.length))
+	const popoverWidth = Math.min(textWidth + 2, Math.max(1, viewportWidth - 2))
+	const popoverHeight = Math.min(bodyHeight + 2, Math.max(3, viewportHeight - 2))
+
+	const left = 1
+	const top = Math.max(0, viewportHeight - popoverHeight - 2)
+
+	const linesToRender = wrapped.slice(0, Math.max(0, popoverHeight - 2))
+	while (linesToRender.length < popoverHeight - 2) linesToRender.push("")
+	const triggerFg = variantFg(variant)
+	const borderColor = variantFg(variant)
+
+	return (
+		<>
+			<box
+				onMouseUp={() => setOpen(!isOpen)}
+				style={{
+					width: 3,
+					height: 1,
+					flexDirection: "row",
+					backgroundColor: colors.backgroundElement,
+				}}
+			>
+				<text content={` ${icon} `} wrapMode="none" style={{ fg: triggerFg, attributes: 1 }} />
+			</box>
+			{showPanel && isOpen && (
+				<box
+					position="absolute"
+					left={left}
+					top={top}
+					width={popoverWidth}
+					height={popoverHeight}
+					zIndex={zIndex}
+					style={{
+						border: true,
+						borderColor,
+						backgroundColor: colors.backgroundPanel,
+						flexDirection: "column",
+					}}
+				>
+					<text content="" />
+					{linesToRender.map((line, i) => (
+						<text key={i} content={line} wrapMode="none" style={{ fg: colors.text }} />
+					))}
+					<text content="" />
+				</box>
+			)}
+		</>
+	)
+}
+
+export const StatusPopoverPanel = ({
+	content,
+	variant = "warning",
+	minWidth = 14,
+	maxWidth = 40,
+	maxHeight = 12,
+	zIndex = 30,
+}: StatusPopoverPanelProps) => {
+	const { width: viewportWidth, height: viewportHeight } = useTerminalDimensions()
+	const lines = useMemo(() => content.split(/\r?\n/), [content])
+	const textWidth = useMemo(() => {
+		const widest = Math.max(1, ...lines.map(measureLine))
+		return clamp(widest, minWidth, Math.min(maxWidth, Math.max(1, viewportWidth - 4)))
+	}, [lines, maxWidth, minWidth, viewportWidth])
+	const wrapped = useMemo(
+		() => lines.flatMap((line) => wrapLine(line, textWidth)),
+		[lines, textWidth],
+	)
+	const bodyHeight = Math.min(maxHeight, Math.max(1, wrapped.length))
+	const popoverWidth = Math.min(textWidth + 2, Math.max(1, viewportWidth - 2))
+	const popoverHeight = Math.min(bodyHeight + 2, Math.max(3, viewportHeight - 2))
+	const linesToRender = wrapped.slice(0, Math.max(0, popoverHeight - 2))
+	while (linesToRender.length < popoverHeight - 2) linesToRender.push("")
+
+	const borderColor = variantFg(variant)
+
+	return (
+		<box
+			position="absolute"
+			left={1}
+			top={Math.max(0, viewportHeight - popoverHeight - 2)}
+			width={popoverWidth}
+			height={popoverHeight}
+			zIndex={zIndex}
+			style={{
+				border: true,
+				borderColor,
+				backgroundColor: colors.backgroundPanel,
+				flexDirection: "column",
+			}}
+		>
+			<text content="" />
+			{linesToRender.map((line, i) => (
+				<text key={i} content={line} wrapMode="none" style={{ fg: colors.text }} />
+			))}
+			<text content="" />
+		</box>
+	)
+}

package/src/cli/argv.ts

@@ -4,6 +4,8 @@ import { themeDefinitions } from "../theme/registry.ts"
 export interface ParsedArgs {
 	/** First positional argument, or null if none was given. */
 	readonly path: string | null
+	/** Value of `--root <dir>`, or null. */
+	readonly root: string | null
 	/** Value of `--theme <id>`, or null. Validated by the boot layer against the registry. */
 	readonly theme: string | null
 	/** Value of `--tone dark|light`, or null. Validated by the boot layer. */
@@ -12,7 +14,7 @@ export interface ParsedArgs {
 	readonly width: string | null
 	/** Value of `--sort <mode>` (`dirs-first` or `files-first`), or null. Validated by the boot layer. */
 	readonly sort: string | null
-	/** True when `--serve` was passed: serve the given file as HTML, skip TUI. */
+	/** True when `--serve` was passed: serve the positional path as HTML, skip TUI. */
 	readonly serve: boolean
 	/** Value of `--port <N>`, or null. Validated by the boot layer. */
 	readonly port: string | null
@@ -58,6 +60,7 @@ const createProgram = () =>
 		.option("--no-mdx")
 		.option("--focus [mode]")
 		.option("--show [list]")
+		.option("--root [dir]")
 		.option("-h, --help")
 		.option("-v, --version")
 		.argument("[path]")
@@ -71,6 +74,7 @@ const VALUE_FLAGS: ReadonlySet<string> = new Set([
 	"--sidebar",
 	"--focus",
 	"--show",
+	"--root",
 ])
 
 const BOOLEAN_FLAGS: ReadonlySet<string> = new Set([
@@ -115,6 +119,7 @@ export const parseArgv = (argv: readonly string[]): ParsedArgs => {
 
 	return {
 		path: typeof pathArg === "string" ? pathArg : null,
+		root: stringOrNull(opts["root"]),
 		theme: stringOrNull(opts["theme"]),
 		tone: stringOrNull(opts["tone"]),
 		width: stringOrNull(opts["width"]),
@@ -134,9 +139,11 @@ export const parseArgv = (argv: readonly string[]): ParsedArgs => {
 
 const themeList = themeDefinitions.map((t) => t.id).join(", ")
 
-export const usage = `usage: house [path] [options]
+export const usage = `usage:
+  house [query] [options]
+  house --serve <path> [--port N]
 
-  path           file or directory; defaults to the current directory
+  query          initial filter query; omit to browse the full discovery root
 
 options:
   --theme <id>   color theme: ${themeList} (default: opencode)
@@ -144,10 +151,11 @@ options:
   --width <N>    cap rendered markdown width at N columns
   --show <list>  reveal normally-skipped entries; comma-separated subset of:
                    hidden, gitignored. Use --show "" to clear.
+  --root <dir>   discovery root to walk (overrides defaultRoot config/env)
   --sort <mode>  sidebar order: dirs-first (default) or files-first
   --sidebar <m>  initial sidebar visibility: auto (default), on, or off
   --focus <m>    startup focus: sidebar, reader, or filter (default: filter)
-  --serve        serve the given file as HTML in the browser (skips TUI)
+  --serve        serve the positional path as HTML in the browser (skips TUI)
   --port <N>     port for --serve (default: OS-assigned)
   -h, --help     show this help and exit
   -v, --version  print version and exit
@@ -155,8 +163,13 @@ options:
   --no-update-check  suppress the "newer version available" check (also via NO_UPDATE_NOTIFIER=1)
   --no-mdx       exclude .mdx files from discovery (default: included)
 
+examples:
+  house README.md
+  house --root docs
+  house --serve README.md
+
 configuration:
   file: $XDG_CONFIG_HOME/house/config.toml  (default ~/.config/house/config.toml)
-  keys: theme, tone, mdx, show, focus
-  env:  HOUSE_THEME, HOUSE_TONE, HOUSE_MDX, HOUSE_SHOW, HOUSE_FOCUS
+  keys: theme, tone, mdx, show, focus, defaultRoot
+  env:  HOUSE_THEME, HOUSE_TONE, HOUSE_MDX, HOUSE_SHOW, HOUSE_FOCUS, HOUSE_DEFAULT_ROOT
   precedence (high → low): flags → env → file → defaults`