@carlesandres/house 0.4.6 → 0.4.7

package/CHANGELOG.md

@@ -6,6 +6,33 @@ The publish workflow (`.github/workflows/publish.yml`) runs on the `release: pub
 
 ## [Unreleased]
 
+## [0.4.7] — 2026-05-27
+
+### Added
+
+- `--root <path>` and TOML `defaultRoot` let launches default to a configured browsing root while preserving explicit path arguments.
+- Discovery/indexing status now shows a spinner in the chrome instead of only static text.
+
+### Changed
+
+- File actions now use uppercase `E` / `O` instead of lowercase `e` / `o`, adding a small amount of friction to edit and open-in-browser actions.
+- Sidebar filtering now applies after a short debounce to reduce churn while typing.
+- Filtered browsing now keeps the first match sticky/selected as results update.
+
+### Fixed
+
+- PTY typing coverage and footer hint tests now match the shifted file-action bindings.
+- CI typechecking now satisfies exact optional prop typing in the release branch.
+
+### Docs
+
+- Removed the obsolete `CONTEXT.md` glossary and inlined the beta-term explanation into `DESIGN.md` with cleaned-up cross-references.
+- ROADMAP shipped items were pruned after the covered work landed.
+
+### Tests
+
+- Browser test noise from React act warnings was reduced around the new filter behavior coverage.
+
 ## [0.4.6] — 2026-05-25
 
 ### Added
@@ -73,7 +100,7 @@ The publish workflow (`.github/workflows/publish.yml`) runs on the `release: pub
 
 ### Added
 
-- Editor hand-off: press `e` to open the selected file in `$EDITOR`/`$VISUAL` (`#19`).
+- Editor hand-off: press `E` to open the selected file in `$EDITOR`/`$VISUAL` (`#19`).
 - Sidebar rows now render basename-first with segment-aware parent-path elision, improving scanability in deep trees.
 - `ctrl+\\` clears an active sidebar filter query without leaving filter mode.
 
@@ -207,7 +234,7 @@ The v1 MVP, published as `@carlesandres/openmdr` on npm.
 ### Added — keymap
 
 - `KeyBinding[]` with `id` / `description` / `keys` / `group` / optional `when` / `run`. Single source for both `useKeyboard` dispatch and the help overlay.
-- Bindings: `j`/`k` + arrows, shift-jump, page/half-page, `g`/`G`, `return`/`l`/`→`, `escape`/`h`/`←`, `[`/`]`, `tab`, `\`, `?`, `q`/`ctrl+c`. Reserved (not bound): `/`, `e`, `o`, `r`.
+- Bindings: `j`/`k` + arrows, shift-jump, page/half-page, `g`/`G`, `return`/`l`/`→`, `escape`/`h`/`←`, `[`/`]`, `tab`, `\`, `?`, `q`/`ctrl+c`. Reserved (not bound): `/`, `r`.
 
 ### Added — release infra
 
@@ -230,7 +257,8 @@ The v1 MVP, published as `@carlesandres/openmdr` on npm.
 
 Search, stdin, URL fetching, cross-file link following, `$EDITOR` hand-off, syntax highlighting, persistent config, OS-appearance auto-detect, single-binary distribution (issue [#2](https://github.com/carlesandres/openmdr/issues/2)), Homebrew tap. All tracked.
 
-[Unreleased]: https://github.com/carlesandres/house/compare/v0.4.6...HEAD
+[Unreleased]: https://github.com/carlesandres/house/compare/v0.4.7...HEAD
+[0.4.7]: https://github.com/carlesandres/house/compare/v0.4.6...v0.4.7
 [0.4.6]: https://github.com/carlesandres/house/compare/v0.4.5...v0.4.6
 [0.4.5]: https://github.com/carlesandres/house/compare/v0.4.4...v0.4.5
 [0.4.4]: https://github.com/carlesandres/house/compare/v0.4.3...v0.4.4

package/README.md

@@ -111,8 +111,8 @@ The file is optional — a missing file is fine. Invalid keys, unknown themes, o
 | `s` | Toggle sidebar visibility |
 | `?` | Show / dismiss help overlay |
 | `ctrl+p` | Command palette |
-| `o` | Open current file in browser as HTML |
-| `e` | Open current file in `$EDITOR` (`$VISUAL` takes precedence) |
+| `O` | Open current file in browser as HTML |
+| `E` | Open current file in `$EDITOR` (`$VISUAL` takes precedence) |
 | `t` | Next theme |
 | `T` | Previous theme |
 | `L` | Toggle dark / light tone |

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@carlesandres/house",
-	"version": "0.4.6",
+	"version": "0.4.7",
 	"description": "TUI-first markdown reader on opentui",
 	"type": "module",
 	"license": "MIT",

package/src/Browser.tsx

@@ -22,7 +22,7 @@ import { CommandPalette } from "./CommandPalette.tsx"
 import { filterFiles } from "./discovery/filter.ts"
 import { type FileEntry } from "./discovery/walk.ts"
 import { BRAND, BRAND_NAME } from "./brand.ts"
-import { Footer, FOOTER_HEIGHT } from "./Footer.tsx"
+import { Footer, FOOTER_HEIGHT, type FooterProps } from "./Footer.tsx"
 import { Header, HEADER_HEIGHT } from "./Header.tsx"
 import { HelpOverlay } from "./HelpOverlay.tsx"
 import { openInEditor, resolveEditor } from "./io/editor.ts"
@@ -55,6 +55,17 @@ export interface BrowserProps {
 	/** Persistent footer indicator (e.g. "indexing… 42"). Pass null/undefined
 	 *  when discovery has finished; the indicator clears. */
 	readonly discoveryStatus?: string | null
+	/** Test seam: override the footer discovery spinner speed. */
+	readonly discoverySpinnerIntervalMs?: number
+	readonly discoverySpinnerInitialFrameIndex?: number
+	/** Test seam: deterministic footer spinner driver. */
+	readonly discoverySpinnerRegisterTick?: ((tick: () => void) => void) | null
+	/** Test seam: override filter debounce timing. */
+	readonly filterDebounceMs?: number
+	/** Test seam: override rendered-path debounce timing. */
+	readonly renderedPathDebounceMs?: number
+	/** Test seam: disable reader-empty-state tip rotation effect. */
+	readonly disableReaderEmptyStateRotation?: boolean
 	/** Initial sidebar visibility (`--sidebar` flag). `auto` consults the
 	 *  launch viewport bucket once; subsequent visibility goes through `s`. */
 	readonly sidebarMode?: SidebarMode
@@ -69,6 +80,8 @@ export interface BrowserProps {
 	/** TTL (ms) for the update-notice toast. Exposed so tests can use a small
 	 *  value instead of sleeping for the production 10s window. */
 	readonly updateNoticeTtlMs?: number
+	/** Test seam: disable footer-notice auto-clear timers. */
+	readonly disableFooterNoticeAutoClear?: boolean
 	/** Flip the parent's discovery vocabulary (#145). Browser doesn't need
 	 *  to know which categories are currently on — the toggle is opaque
 	 *  from this side; we just snapshot the selected path so it can be
@@ -105,16 +118,26 @@ export const setReaderEmptyStateTipRotationForTests = (next: number) => {
 	nextReaderEmptyStateTipRotation = next
 }
 
+const FILTER_DEBOUNCE_MS = 50
+const RENDERED_PATH_DEBOUNCE_MS = 80
+
 export const Browser = ({
 	files,
 	initialIndex = 0,
 	maxWidth = null,
 	discoveryStatus = null,
+	discoverySpinnerIntervalMs,
+	discoverySpinnerInitialFrameIndex,
+	discoverySpinnerRegisterTick = null,
+	filterDebounceMs = FILTER_DEBOUNCE_MS,
+	renderedPathDebounceMs = RENDERED_PATH_DEBOUNCE_MS,
+	disableReaderEmptyStateRotation = false,
 	sidebarMode = "auto",
 	onQuit,
 	readFile = defaultReadFile,
 	updateNotice = null,
 	updateNoticeTtlMs = 10000,
+	disableFooterNoticeAutoClear = false,
 	onToggleAll,
 	startupFocus = null,
 }: BrowserProps) => {
@@ -166,7 +189,8 @@ export const Browser = ({
 	const [sidebarScroll, setSidebarScroll] = useState<number>(0)
 	const [helpVisible, setHelpVisible] = useState<boolean>(false)
 	const [filterOpen, setFilterOpen] = useState<boolean>(startInFilter)
-	const [filterQuery, setFilterQuery] = useState<string>("")
+	const [filterInput, setFilterInput] = useState<string>("")
+	const [filterApplied, setFilterApplied] = useState<string>("")
 	const [paletteOpen, setPaletteOpen] = useState<boolean>(false)
 	const [paletteQuery, setPaletteQuery] = useState<string>("")
 	const [paletteIndex, setPaletteIndex] = useState<number>(0)
@@ -186,7 +210,9 @@ export const Browser = ({
 	// first key opens the filter; subsequent keys in the same tick would
 	// otherwise still observe filterOpen=false through closure).
 	const filterOpenRef = useRef(startInFilter)
-	const filterQueryRef = useRef("")
+	const filterInputRef = useRef("")
+	const filterAppliedRef = useRef("")
+	const autoSelectForAppliedFilterRef = useRef(true)
 	const focusRef = useRef<"sidebar" | "reader">(focus)
 	const restoreFilterOnSidebarFocusRef = useRef(startInFilter)
 	const [footerNotice, setFooterNoticeState] = useState<{
@@ -220,9 +246,10 @@ export const Browser = ({
 	// the other's display window.
 	useEffect(() => {
 		if (footerNotice === null) return
+		if (disableFooterNoticeAutoClear) return
 		const timer = setTimeout(() => setFooterNoticeState(null), footerNotice.ttlMs)
 		return () => clearTimeout(timer)
-	}, [footerNotice])
+	}, [disableFooterNoticeAutoClear, footerNotice])
 
 	// Push the update-available nudge once, when it arrives from the parent
 	// (the registry probe resolves asynchronously after boot). 10s gives the
@@ -257,8 +284,29 @@ export const Browser = ({
 		pushFooterNotice(`tone: ${nextTone}`)
 	}
 
-	const displayedFiles = useMemo(() => filterFiles(files, filterQuery), [files, filterQuery])
-	const filterHasNoMatches = filterQuery.length > 0 && displayedFiles.length === 0
+	useEffect(() => {
+		if (filterInput === filterApplied) return
+		const timer = setTimeout(() => {
+			filterAppliedRef.current = filterInput
+			setFilterApplied(filterInput)
+		}, filterDebounceMs)
+		return () => clearTimeout(timer)
+	}, [filterApplied, filterDebounceMs, filterInput])
+
+	useEffect(() => {
+		autoSelectForAppliedFilterRef.current = true
+	}, [filterApplied])
+
+	const displayedFiles = useMemo(() => filterFiles(files, filterApplied), [files, filterApplied])
+	const filterHasNoMatches = filterInput.length > 0 && displayedFiles.length === 0
+
+	useEffect(() => {
+		if (filterApplied.length === 0) return
+		if (!autoSelectForAppliedFilterRef.current) return
+		if (displayedFiles.length === 0) return
+		setSelectedIndex(0)
+		autoSelectForAppliedFilterRef.current = false
+	}, [displayedFiles, filterApplied])
 	// When the filtered list shrinks, keep selectedIndex valid. The reset to 0
 	// on every query change happens in the keystroke handler, not here, so a
 	// no-op rerender doesn't snap the cursor back to the top.
@@ -296,9 +344,9 @@ export const Browser = ({
 	useEffect(() => {
 		const target = selected?.path ?? null
 		if (target === renderedPath) return
-		const timer = setTimeout(() => setRenderedPath(target), 80)
+		const timer = setTimeout(() => setRenderedPath(target), renderedPathDebounceMs)
 		return () => clearTimeout(timer)
-	}, [selected?.path, renderedPath])
+	}, [selected?.path, renderedPath, renderedPathDebounceMs])
 
 	useEffect(() => {
 		if (!renderedPath) {
@@ -340,7 +388,7 @@ export const Browser = ({
 		helpVisible,
 		filterOpen,
 		restoreFilterOnSidebarFocus: restoreFilterOnSidebarFocusRef.current,
-		filterQuery,
+		filterQuery: filterInput,
 		paletteOpen,
 		setFocus,
 		// Wrapped so any keymap-driven selection move (j/k/g/G/[/], reader
@@ -350,6 +398,7 @@ export const Browser = ({
 		// itself) deliberately use the raw `setSelectedIndex` setter.
 		setSelectedIndex: (updater) => {
 			pendingSelectionPathRef.current = null
+			autoSelectForAppliedFilterRef.current = false
 			setSelectedIndex(updater)
 		},
 		toggleShown: () => {
@@ -393,8 +442,10 @@ export const Browser = ({
 			// Reset both the ref and the state so the freshly-opened modal
 			// shows an empty input and selection lands on the first file in
 			// the (now unfiltered) list.
-			filterQueryRef.current = ""
-			setFilterQuery("")
+			filterInputRef.current = ""
+			filterAppliedRef.current = ""
+			setFilterInput("")
+			setFilterApplied("")
 			setSelectedIndex(() => 0)
 			focusRef.current = "sidebar"
 			if (focus !== "sidebar") setFocus("sidebar")
@@ -467,7 +518,7 @@ export const Browser = ({
 			if (!file) return
 			const editor = resolveEditor(process.env)
 			if (!editor) {
-				pushFooterNotice("set $EDITOR or $VISUAL to use e")
+				pushFooterNotice("set $EDITOR or $VISUAL to use E")
 				return
 			}
 			if (!renderer) {
@@ -543,6 +594,8 @@ export const Browser = ({
 			// the Return semantic (open the match in the reader); false is
 			// Esc (stop typing, keep the applied filter, stay in sidebar).
 			const closeFilter = (commit: boolean) => {
+				filterAppliedRef.current = filterInputRef.current
+				setFilterApplied(filterInputRef.current)
 				const picked = displayedFiles[selectedIndex] ?? null
 				const effectiveCommit = commit && picked !== null
 				restoreFilterOnSidebarFocusRef.current = false
@@ -583,20 +636,22 @@ export const Browser = ({
 				// outside the modal: clear the query, reset selection. The
 				// keymap doesn't see keys in filter mode, so this branch is
 				// the in-modal half of that single chord.
-				filterQueryRef.current = ""
-				setFilterQuery("")
+				filterInputRef.current = ""
+				filterAppliedRef.current = ""
+				setFilterInput("")
+				setFilterApplied("")
 				setSelectedIndex(() => 0)
 				return
 			}
 			if (key.name === "backspace" || key.name === "delete") {
 				// Backspace on empty input closes the modal — the leading `/`
 				// chevron is the last thing left to "delete."
-				if (filterQueryRef.current.length === 0) {
+				if (filterInputRef.current.length === 0) {
 					closeFilter(false)
 					return
 				}
-				filterQueryRef.current = filterQueryRef.current.slice(0, -1)
-				setFilterQuery(filterQueryRef.current)
+				filterInputRef.current = filterInputRef.current.slice(0, -1)
+				setFilterInput(filterInputRef.current)
 				setSelectedIndex(() => 0)
 				return
 			}
@@ -615,8 +670,8 @@ export const Browser = ({
 				char = key.shift ? key.name.toUpperCase() : key.name
 			}
 			if (char !== null) {
-				filterQueryRef.current = filterQueryRef.current + char
-				setFilterQuery(filterQueryRef.current)
+				filterInputRef.current = filterInputRef.current + char
+				setFilterInput(filterInputRef.current)
 				setSelectedIndex(() => 0)
 			}
 			return
@@ -733,11 +788,12 @@ export const Browser = ({
 	const currentFile = selected?.relativePath ?? null
 	const content = loaded?.path === renderedPath ? loaded.content : ""
 	const readerEmptyStateTitle = filterHasNoMatches
-		? `No files match: ${filterQuery}`
+		? `No files match: ${filterInput}`
 		: `${BRAND} ${BRAND_NAME}`
 	const readerEmptyStateVisible = error == null && renderedPath == null
 
 	useEffect(() => {
+		if (disableReaderEmptyStateRotation) return
 		if (readerEmptyStateVisible) {
 			if (!readerEmptyStateVisibleRef.current) {
 				readerEmptyStateVisibleRef.current = true
@@ -746,7 +802,7 @@ export const Browser = ({
 			return
 		}
 		readerEmptyStateVisibleRef.current = false
-	}, [readerEmptyStateVisible])
+	}, [disableReaderEmptyStateRotation, readerEmptyStateVisible])
 
 	// Sidebar virtualization: render only the visible window. Without this,
 	// every keystroke re-renders all N file rows even though only the bg of
@@ -797,6 +853,19 @@ export const Browser = ({
 				: browserBindings,
 		[helpVisible],
 	)
+	const footerProps = {
+		bindings: footerBindings,
+		ctx,
+		width,
+		notice: footerNotice?.text ?? null,
+		discoveryStatus,
+		filterQuery: !filterOpen && filterInput.length > 0 ? filterInput : null,
+		...(discoverySpinnerIntervalMs === undefined ? {} : { discoverySpinnerIntervalMs }),
+		...(discoverySpinnerInitialFrameIndex === undefined
+			? {}
+			: { discoverySpinnerInitialFrameIndex }),
+		...(discoverySpinnerRegisterTick === undefined ? {} : { discoverySpinnerRegisterTick }),
+	} satisfies FooterProps<BrowserCtx>
 	const readerEmptyStateTips = useMemo(() => buildReaderEmptyStateTips(browserBindings, ctx), [ctx])
 	const readerEmptyStateTip = useMemo(
 		() => pickTipByRotation(readerEmptyStateTips, readerEmptyStateTipRotation),
@@ -809,7 +878,7 @@ export const Browser = ({
 		<>
 			{filterRowVisible && (
 				<PromptRow
-					query={filterQuery}
+					query={filterInput}
 					editing={filterOpen}
 					placeholder="/ to filter…"
 					width={sidebarTextWidth}
@@ -1007,14 +1076,7 @@ export const Browser = ({
 					</box>
 				)}
 			</box>
-			<Footer
-				bindings={footerBindings}
-				ctx={ctx}
-				width={width}
-				notice={footerNotice?.text ?? null}
-				discoveryStatus={discoveryStatus}
-				filterQuery={!filterOpen && filterQuery.length > 0 ? filterQuery : null}
-			/>
+			<Footer {...footerProps} />
 			{helpVisible && (
 				<HelpOverlay bindings={browserBindings} viewportWidth={width} viewportHeight={height} />
 			)}

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
@@ -43,6 +45,12 @@ export interface FooterProps<C> {
 	 *  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
 }
 
 const HINT_SEPARATOR = "  "
@@ -92,6 +100,9 @@ export const Footer = <C,>({
 	notice,
 	discoveryStatus,
 	filterQuery,
+	discoverySpinnerIntervalMs,
+	discoverySpinnerInitialFrameIndex,
+	discoverySpinnerRegisterTick,
 }: FooterProps<C>) => {
 	const usableWidth = Math.max(0, width - 2) // 1-cell horizontal padding each side
 
@@ -185,8 +196,23 @@ export const Footer = <C,>({
 	}
 
 	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}>
+				<Spinner {...spinnerProps} />
+				<text content=" " wrapMode="none" style={{ fg: colors.textMuted }} />
 				<text content={statusContent} wrapMode="none" style={{ fg: colors.secondary }} />
 				<text content={STATUS_SEPARATOR} wrapMode="none" style={{ fg: colors.textMuted }} />
 				{renderHints()}

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/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. */
@@ -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"]),
@@ -144,6 +149,7 @@ 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)
   --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)
@@ -157,6 +163,6 @@ options:
 
 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`

package/src/config/load.ts

@@ -20,6 +20,8 @@ export interface HouseConfig {
 	readonly theme: string
 	readonly tone: "dark" | "light"
 	readonly mdx: boolean
+	/** Default discovery-root strategy when no explicit `--root` flag is passed. */
+	readonly defaultRoot: "cwd" | "git"
 	/** Categories of normally-skipped entries to opt into. See
 	 *  `src/discovery/show.ts` for the vocabulary. Empty array (the
 	 *  default) yields the conservative discovery set. */
@@ -43,6 +45,7 @@ export interface CliOverrides {
 const DEFAULT_THEME = "opencode"
 const DEFAULT_TONE: "dark" | "light" = "dark"
 const DEFAULT_MDX = true
+const DEFAULT_ROOT: "cwd" | "git" = "cwd"
 const DEFAULT_SHOW = ""
 const DEFAULT_FOCUS: "sidebar" | "reader" | "filter" = "filter"
 
@@ -54,11 +57,19 @@ const themeIds = themeDefinitions.map((t) => t.id)
  * Used by `fileProvider` to warn about unrecognized keys (with a
  * did-you-mean hint when one is close) while still loading the rest.
  */
-const KNOWN_FILE_KEYS: ReadonlySet<string> = new Set(["theme", "tone", "mdx", "show", "focus"])
+const KNOWN_FILE_KEYS: ReadonlySet<string> = new Set([
+	"theme",
+	"tone",
+	"mdx",
+	"show",
+	"focus",
+	"defaultRoot",
+])
 
 const schema = Config.all({
 	theme: Config.schema(Schema.Literals(themeIds), "theme"),
 	tone: Config.schema(Schema.Literals(["dark", "light"] as const), "tone"),
+	defaultRoot: Config.schema(Schema.String, "defaultRoot"),
 	// Boolean stored as string literal because providers stringify values
 	// (TOML bools, env vars, CLI flags all flow through as text). Mapped to
 	// a real boolean in `loadConfig` below.
@@ -75,6 +86,7 @@ const defaultsProvider = (): ConfigProvider.ConfigProvider =>
 	ConfigProvider.fromUnknown({
 		theme: DEFAULT_THEME,
 		tone: DEFAULT_TONE,
+		defaultRoot: DEFAULT_ROOT,
 		mdx: String(DEFAULT_MDX),
 		show: DEFAULT_SHOW,
 		focus: DEFAULT_FOCUS,
@@ -192,11 +204,13 @@ const envProvider = (env: Record<string, string | undefined>): ConfigProvider.Co
 	const entries: Array<[string, string]> = []
 	const theme = env["HOUSE_THEME"]
 	const tone = env["HOUSE_TONE"]
+	const defaultRoot = env["HOUSE_DEFAULT_ROOT"]
 	const mdx = env["HOUSE_MDX"]
 	const show = env["HOUSE_SHOW"]
 	const focus = env["HOUSE_FOCUS"]
 	if (theme !== undefined) entries.push(["theme", theme])
 	if (tone !== undefined) entries.push(["tone", tone])
+	if (defaultRoot !== undefined) entries.push(["defaultRoot", defaultRoot])
 	if (mdx !== undefined) entries.push(["mdx", mdx])
 	if (show !== undefined) entries.push(["show", show])
 	if (focus !== undefined) entries.push(["focus", focus])
@@ -262,6 +276,13 @@ export const loadConfig = (
 	)
 	return schema.parse(provider).pipe(
 		Effect.flatMap((raw) => {
+			const defaultRoot =
+				raw.defaultRoot === "cwd" || raw.defaultRoot === "git" ? raw.defaultRoot : DEFAULT_ROOT
+			if (raw.defaultRoot !== defaultRoot) {
+				onWarning(
+					`house: ignoring invalid value ${JSON.stringify(raw.defaultRoot)} for defaultRoot in config/env; using "${DEFAULT_ROOT}"`,
+				)
+			}
 			const parsed = parseShowList(raw.show)
 			if (!parsed.ok) {
 				// Effect's `Config.ConfigError` requires a `SchemaError` or
@@ -278,6 +299,7 @@ export const loadConfig = (
 			return Effect.succeed({
 				theme: raw.theme,
 				tone: raw.tone,
+				defaultRoot,
 				mdx: raw.mdx === "true",
 				show: parsed.value,
 				focus: raw.focus,

package/src/index.tsx

@@ -9,6 +9,7 @@
  */
 
 import { stat } from "node:fs/promises"
+import { dirname, resolve } from "node:path"
 import { createCliRenderer, SyntaxStyle } from "@opentui/core"
 import type { BorderSides } from "@opentui/core"
 import { createRoot, useKeyboard, useRenderer, useTerminalDimensions } from "@opentui/react"
@@ -58,6 +59,39 @@ export interface AppProps {
  */
 export type SidebarMode = "auto" | "on" | "off"
 
+const pathIsDirectory = async (path: string): Promise<boolean> => {
+	try {
+		return (await stat(path)).isDirectory()
+	} catch {
+		return false
+	}
+}
+
+const findGitRoot = async (cwd: string): Promise<string> => {
+	const start = resolve(cwd)
+	let current = start
+	for (;;) {
+		if (await pathIsDirectory(resolve(current, ".git"))) return current
+		const parent = dirname(current)
+		if (parent === current) return start
+		current = parent
+	}
+}
+
+export const resolveDiscoveryRoot = async ({
+	cliRoot,
+	defaultRoot,
+	cwd,
+}: {
+	readonly cliRoot: string | null
+	readonly defaultRoot: "cwd" | "git"
+	readonly cwd: string
+}): Promise<string> => {
+	if (cliRoot !== null) return cliRoot
+	if (defaultRoot === "git") return findGitRoot(cwd)
+	return cwd
+}
+
 interface DiscoverShellProps {
 	readonly target: string
 	/** Resolved discovery vocabulary from the config layer. The shift+a
@@ -277,7 +311,7 @@ if (import.meta.main) {
 		console.error(`house: ${formatConfigError(err)}`)
 		process.exit(2)
 	})
-	const { theme: themeId, tone, mdx, show, focus: startupFocus } = config
+	const { theme: themeId, tone, mdx, show, focus: startupFocus, defaultRoot } = config
 	const themeDef = getThemeDefinition(themeId)
 	if (themeDef === undefined) {
 		// Unreachable: Config.schema validated themeId against themeDefinitions.
@@ -296,7 +330,9 @@ if (import.meta.main) {
 		maxWidth = n
 	}
 
+	const cwd = process.cwd()
 	const target = args.path ?? "."
+	const discoveryRoot = await resolveDiscoveryRoot({ cliRoot: args.root, defaultRoot, cwd })
 
 	if (args.serve) {
 		let stats: Awaited<ReturnType<typeof stat>>
@@ -357,6 +393,7 @@ if (import.meta.main) {
 		}
 		await runTui({
 			target,
+			discoveryRoot,
 			themeId,
 			tone,
 			maxWidth,
@@ -372,6 +409,7 @@ if (import.meta.main) {
 
 interface TuiBootOptions {
 	readonly target: string
+	readonly discoveryRoot: string
 	readonly themeId: string
 	readonly tone: "dark" | "light"
 	readonly maxWidth: number | null
@@ -387,6 +425,7 @@ interface TuiBootOptions {
 
 async function runTui({
 	target,
+	discoveryRoot,
 	themeId,
 	tone,
 	maxWidth,
@@ -430,7 +469,7 @@ async function runTui({
 		createRoot(renderer).render(
 			<RegistryProvider initialValues={[[themeAtom, initialTheme]]}>
 				<DiscoverShell
-					target={target}
+					target={discoveryRoot}
 					initialShow={show}
 					sort={sort}
 					mdx={mdx}

package/src/keymap/browser.ts

@@ -11,7 +11,7 @@ export type BrowserFocus = "sidebar" | "reader"
 export interface BrowserCtx {
 	readonly files: readonly FileEntry[]
 	/** True iff `files[selectedIndex]` resolves to an entry. The honest
-	 *  predicate for File-group actions (`o`, `e`, `[`, `]`): with debounced
+	 *  predicate for File-group actions (`O`, `E`, `[`, `]`): with debounced
 	 *  filter and sticky auto-select, `files.length > 0` can be true while
 	 *  `selectedIndex` is invalid for the displayed list. See #115. */
 	readonly hasSelected: boolean
@@ -278,7 +278,7 @@ export const browserBindings: readonly KeyBinding<BrowserCtx>[] = [
 		group: "File",
 		description: "Open current file in browser as HTML",
 		hint: "html",
-		keys: ["o"],
+		keys: ["shift+o"],
 		when: hasSelected,
 		run: (c) => c.serveCurrent(),
 	},
@@ -287,7 +287,7 @@ export const browserBindings: readonly KeyBinding<BrowserCtx>[] = [
 		group: "File",
 		description: "Open current file in $EDITOR",
 		hint: "edit",
-		keys: ["e"],
+		keys: ["shift+e"],
 		when: hasSelected,
 		run: (c) => c.editCurrent(),
 	},

package/src/serve/server.ts

@@ -2,7 +2,7 @@
  * Local HTML preview server for a single markdown file.
  *
  * One long-lived `Bun.serve` instance. The served file path is swappable
- * via `setTarget(path)` — used by the TUI's `o` binding so pressing it on a
+ * via `setTarget(path)` — used by the TUI's `O` binding so pressing it on a
  * new file retargets the existing server (live-reload fires) instead of
  * spawning a second one.
  *