@carlesandres/house 0.4.3 → 0.4.5

package/CHANGELOG.md

@@ -6,6 +6,36 @@ The publish workflow (`.github/workflows/publish.yml`) runs on the `release: pub
 
 ## [Unreleased]
 
+## [0.4.5] — 2026-05-24
+
+### Changed
+
+- npm install/upgrade runtime baseline is now explicit: Node `>=22.22.2` is required when installing `@carlesandres/house` via npm, matching transitive engine requirements.
+
+### Docs
+
+- README now calls out the Node `>=22.22.2` requirement for npm-based install/upgrade.
+
+### Tests
+
+- CI now includes an npm global-install smoke matrix on Node `22.22.2` and Node `24` with `engine-strict=true`, catching runtime-floor regressions before release.
+
+## [0.4.4] — 2026-05-24
+
+### Added
+
+- Discovery visibility controls: new `--show <list>` CLI flag, `HOUSE_SHOW` env var, and TOML `show = ["..."]` config, replacing boolean discovery toggles with explicit categories (`hidden`, `gitignored`).
+- Session visibility toggle: `shift+a` flips discovery between the configured visibility set and showing all categories, preserving selection across the re-walk.
+- Launch-in-filter option: `--start-in-filter` CLI flag, `HOUSE_START_IN_FILTER` env var, and TOML `start_in_filter = true` open the sidebar filter prompt focused at startup.
+
+### Changed
+
+- Discovery plumbing now uses a first-class visibility-category model so future categories can be added without reshaping CLI/config/TUI surfaces.
+
+### Docs
+
+- README updated for the discovery-show vocabulary (`--show`, `HOUSE_SHOW`, `show=[...]`) and the `shift+a` keybind.
+
 ## [0.4.3] — 2026-05-23
 
 ### Fixed
@@ -173,7 +203,9 @@ 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.3...HEAD
+[Unreleased]: https://github.com/carlesandres/house/compare/v0.4.5...HEAD
+[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
 [0.4.3]: https://github.com/carlesandres/house/compare/v0.4.2...v0.4.3
 [0.4.2]: https://github.com/carlesandres/house/compare/v0.4.1...v0.4.2
 [0.4.1]: https://github.com/carlesandres/house/compare/v0.4.0...v0.4.1

package/README.md

@@ -14,7 +14,14 @@ A terminal markdown reader and navigator — themable and configurable, with a k
 - **Open in browser**
 - **Open in `$EDITOR`**
 
-Requires [Bun](https://bun.sh) on `PATH`. Supported on macOS and Linux; Windows is unsupported and unvalidated (see [#129](https://github.com/carlesandres/house/issues/129)).
+Requires [Bun](https://bun.sh) on `PATH`.
+
+## Runtime requirements
+
+- Bun: required to run `house`.
+- npm install/upgrade path: Node `>=22.22.2` (Node 24 LTS recommended).
+
+Supported on macOS and Linux; Windows is unsupported and unvalidated (see [#129](https://github.com/carlesandres/house/issues/129)).
 
 ## Install
 
@@ -47,12 +54,13 @@ house [options] <path>
 | `--theme <name>` | `opencode` | Starting theme (see list below) |
 | `--tone dark\|light` | `dark` | Starting tone |
 | `--width <N>` | — | Cap rendered markdown width at N columns |
-| `--all` | off | Include hidden and gitignored files in discovery |
+| `--show <list>` | `""` | Reveal normally-skipped entries; comma-separated subset of `hidden`, `gitignored`. Use `--show ""` to clear. |
 | `--sort <mode>` | `dirs-first` | Sidebar order: `dirs-first` or `files-first` |
 | `--sidebar <mode>` | `auto` | Initial sidebar visibility: `auto`, `on`, or `off` |
 | `--serve` | off | Serve the given file as HTML in the browser (skips TUI) |
 | `--port <N>` | OS-assigned | Port for `--serve` |
 | `--no-mdx` | off | Exclude `.mdx` files from discovery |
+| `--start-in-filter` | off | Open the sidebar filter prompt on launch so you can type a query immediately. Press Esc to dismiss. |
 | `--no-update-check` | off | Suppress the "newer version available" check (also via `NO_UPDATE_NOTIFIER=1`) |
 | `--config-path` | — | Print the resolved config-file path and exit |
 | `-h`, `--help` | — | Show help and exit |
@@ -73,16 +81,22 @@ Run `house --config-path` to print the exact location.
 theme = "tokyonight"
 tone  = "dark"
 mdx   = true
+show  = ["hidden", "gitignored"]
+start_in_filter = false
 ```
 
-Supported keys: `theme`, `tone`, `mdx`.
+Supported keys: `theme`, `tone`, `mdx`, `show`, `start_in_filter`.
+
+`show` is a list of normally-skipped categories to opt into. Known categories: `hidden` (dot-prefixed entries), `gitignored` (entries matched by a `.gitignore`). Default is the empty list. Hard skips (`node_modules`, `.git`, `.venv`) always apply.
 
 Precedence, highest to lowest:
 
-1. CLI flags (`--theme`, `--tone`, `--no-mdx`)
-2. Env vars (`HOUSE_THEME`, `HOUSE_TONE`, `HOUSE_MDX`)
+1. CLI flags (`--theme`, `--tone`, `--no-mdx`, `--show`, `--start-in-filter`)
+2. Env vars (`HOUSE_THEME`, `HOUSE_TONE`, `HOUSE_MDX`, `HOUSE_SHOW`, `HOUSE_START_IN_FILTER`)
 3. Config file
-4. Built-in defaults (`opencode` / `dark` / `mdx = true`)
+4. Built-in defaults (`opencode` / `dark` / `mdx = true` / `show = []` / `start_in_filter = false`)
+
+`HOUSE_SHOW` takes a comma-separated list (`HOUSE_SHOW=hidden,gitignored`). For `show` specifically, each source completely replaces the next — categories don't merge across layers. Press `shift+a` in the TUI to round-trip between the configured set and the full vocabulary without editing config.
 
 The file is optional — a missing file is fine. Invalid keys, unknown themes, or malformed TOML fail loudly with a one-line error. Per-project config (`.house/config.toml`) and additional keys are deferred.
 
@@ -116,6 +130,7 @@ The file is optional — a missing file is fine. Invalid keys, unknown themes, o
 | `g` | First file |
 | `G` | Last file |
 | `/` | Filter files (fuzzy match on path) |
+| `A` | Toggle hidden + gitignored entries (session-only; round-trips with the configured `show`) |
 | `↵` / `→` / `l` | Open file (focus reader) |
 
 ### Reader

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@carlesandres/house",
-	"version": "0.4.3",
+	"version": "0.4.5",
 	"description": "TUI-first markdown reader on opentui",
 	"type": "module",
 	"license": "MIT",
@@ -12,6 +12,9 @@
 		"url": "https://github.com/carlesandres/house/issues"
 	},
 	"homepage": "https://github.com/carlesandres/house#readme",
+	"engines": {
+		"node": ">=22.22.2"
+	},
 	"keywords": [
 		"markdown",
 		"reader",

package/src/Browser.tsx

@@ -67,6 +67,15 @@ 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
+	/** 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
+	 *  restored across the re-walk the parent triggers. */
+	readonly onToggleAll?: () => void
+	/** Open the sidebar filter prompt on mount so the user can type
+	 *  immediately. Esc closes it through the normal close path — no
+	 *  special "first close" behavior. */
+	readonly startInFilter?: boolean
 }
 
 const defaultReadFile = (path: string): Promise<string> => Effect.runPromise(readFileText(path))
@@ -95,6 +104,8 @@ export const Browser = ({
 	readFile = defaultReadFile,
 	updateNotice = null,
 	updateNoticeTtlMs = 10000,
+	onToggleAll,
+	startInFilter = false,
 }: BrowserProps) => {
 	const renderer = useRenderer()
 	const { width, height } = useTerminalDimensions()
@@ -123,10 +134,16 @@ export const Browser = ({
 				return initialShownForAuto(width)
 		}
 	})
-	const [focus, setFocus] = useState<"sidebar" | "reader">(() => (shown ? "sidebar" : "reader"))
+	// startInFilter mirrors `openFilter`'s focus rule: the filter input lives
+	// in the sidebar, so opening it on mount also forces sidebar focus
+	// regardless of `--sidebar=off` (§7.1's visibility derivation surfaces
+	// the sidebar via focus even when `shown` is false).
+	const [focus, setFocus] = useState<"sidebar" | "reader">(() =>
+		shown || startInFilter ? "sidebar" : "reader",
+	)
 	const [sidebarScroll, setSidebarScroll] = useState<number>(0)
 	const [helpVisible, setHelpVisible] = useState<boolean>(false)
-	const [filterOpen, setFilterOpen] = useState<boolean>(false)
+	const [filterOpen, setFilterOpen] = useState<boolean>(startInFilter)
 	const [filterQuery, setFilterQuery] = useState<string>("")
 	const [paletteOpen, setPaletteOpen] = useState<boolean>(false)
 	const [paletteQuery, setPaletteQuery] = useState<string>("")
@@ -142,7 +159,7 @@ export const Browser = ({
 	// updates even when multiple keys arrive in a single React batch (the
 	// first key opens the filter; subsequent keys in the same tick would
 	// otherwise still observe filterOpen=false through closure).
-	const filterOpenRef = useRef(false)
+	const filterOpenRef = useRef(startInFilter)
 	const filterQueryRef = useRef("")
 	const [footerNotice, setFooterNoticeState] = useState<{
 		readonly text: string
@@ -151,6 +168,13 @@ export const Browser = ({
 	const pushFooterNotice = (text: string, ttlMs = 2000): void =>
 		setFooterNoticeState({ text, ttlMs })
 	const serverRef = useRef<ServerHandle | null>(null)
+	// #145 selection preservation across an `all` re-walk. When the user
+	// toggles, we snapshot the currently selected path; once the new file set
+	// streams in, we restore selection by path. If the path isn't present in
+	// the new set (e.g. it was a hidden file and `all` just went off), the
+	// ref stays armed so toggling back later re-selects it. Any user-driven
+	// selection move (j/k/g/G/click) clears it — user intent has moved on.
+	const pendingSelectionPathRef = useRef<string | null>(null)
 
 	// Stop the preview server on unmount so re-mounts (tests) and clean
 	// shutdowns don't leak a listening socket.
@@ -211,6 +235,22 @@ export const Browser = ({
 		}
 	}, [displayedFiles.length, selectedIndex])
 
+	// #145 selection restoration. Runs whenever the displayed file list
+	// changes (re-walk batches, filter changes). If the user has a path
+	// armed (set by toggleAll) and it now appears in the displayed subset,
+	// restore selection to that index and disarm. If the path is not
+	// present, keep the ref armed — toggling back later (or future stream
+	// batches in the same toggle) will find it.
+	useEffect(() => {
+		const target = pendingSelectionPathRef.current
+		if (target === null) return
+		const idx = displayedFiles.findIndex((f) => f.path === target)
+		if (idx >= 0) {
+			setSelectedIndex(idx)
+			pendingSelectionPathRef.current = null
+		}
+	}, [displayedFiles])
+
 	const selected = displayedFiles[selectedIndex]
 
 	// Track the path whose content is currently rendered. Updated lazily via
@@ -269,7 +309,15 @@ export const Browser = ({
 		filterQuery,
 		paletteOpen,
 		setFocus,
-		setSelectedIndex,
+		// Wrapped so any keymap-driven selection move (j/k/g/G/[/], reader
+		// prev/next) clears the pending-restore ref from #145. Internal
+		// callers that should NOT clear pending (the filter modal's typing
+		// branch, the post-filter clamp effect, the restoration effect
+		// itself) deliberately use the raw `setSelectedIndex` setter.
+		setSelectedIndex: (updater) => {
+			pendingSelectionPathRef.current = null
+			setSelectedIndex(updater)
+		},
 		toggleShown: () => {
 			// Two layout shapes, two behaviors:
 			//   wide  → flip the sticky `shown` preference. Per DESIGN.md §7.1
@@ -330,6 +378,19 @@ export const Browser = ({
 		},
 		cycleTheme,
 		toggleTone,
+		toggleAll: () => {
+			// Snapshot the currently displayed selection unless a snapshot is
+			// already armed (a prior toggle's selection survived the re-walk
+			// and is still waiting to come back). The armed path is the one
+			// the user originally chose; preserving it across a toggle-off /
+			// toggle-on round-trip is the headline ergonomic of #145.
+			// User-driven nav (j/k/g/G via the wrapped setSelectedIndex below)
+			// clears pending, so a follow-up toggle starts a fresh snapshot.
+			if (pendingSelectionPathRef.current === null && selected) {
+				pendingSelectionPathRef.current = selected.path
+			}
+			onToggleAll?.()
+		},
 		serveCurrent: () => {
 			const file = displayedFiles[selectedIndex]
 			if (!file) return

package/src/cli/argv.ts

@@ -9,8 +9,6 @@ export interface ParsedArgs {
 	readonly tone: string | null
 	/** Value of `--width <N>`, or null. Validated by the boot layer (must be a positive integer). */
 	readonly width: string | null
-	/** True when `--all` was passed: include hidden + gitignored files in discovery. */
-	readonly all: boolean
 	/** 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. */
@@ -31,6 +29,14 @@ export interface ParsedArgs {
 	readonly noUpdateCheck: boolean
 	/** True when `--no-mdx` was passed: exclude `.mdx` files from discovery. */
 	readonly noMdx: boolean
+	/** True when `--start-in-filter` was passed: open the sidebar filter
+	 *  prompt on launch (one-way override; default is off). */
+	readonly startInFilter: boolean
+	/** Raw value of `--show <list>`, or null if the flag wasn't passed.
+	 *  Comma-separated list of category names; the boot layer validates
+	 *  tokens against the known vocabulary (see `discovery/show.ts`).
+	 *  `--show ""` is a meaningful value: clears the set. */
+	readonly show: string | null
 }
 
 /**
@@ -45,7 +51,6 @@ export const parseArgv = (argv: readonly string[]): ParsedArgs => {
 	let theme: string | null = null
 	let tone: string | null = null
 	let width: string | null = null
-	let all = false
 	let sort: string | null = null
 	let serve = false
 	let port: string | null = null
@@ -55,6 +60,8 @@ export const parseArgv = (argv: readonly string[]): ParsedArgs => {
 	let sidebar: string | null = null
 	let noUpdateCheck = false
 	let noMdx = false
+	let show: string | null = null
+	let startInFilter = false
 
 	for (let i = 0; i < argv.length; i++) {
 		const arg = argv[i]!
@@ -71,9 +78,6 @@ export const parseArgv = (argv: readonly string[]): ParsedArgs => {
 				width = argv[i + 1] ?? null
 				i++
 				continue
-			case "--all":
-				all = true
-				continue
 			case "--sort":
 				sort = argv[i + 1] ?? null
 				i++
@@ -113,6 +117,18 @@ export const parseArgv = (argv: readonly string[]): ParsedArgs => {
 			case "--no-mdx":
 				noMdx = true
 				continue
+			case "--start-in-filter":
+				startInFilter = true
+				continue
+			case "--show":
+				// Always consume the following arg, even when it looks like
+				// a flag — `--show ""` is meaningful (explicit empty set),
+				// and the empty-string regression matters more than the
+				// near-miss case of someone forgetting the value. Boot
+				// validates tokens.
+				show = argv[i + 1] ?? null
+				i++
+				continue
 		}
 		if (path === null && !arg.startsWith("-")) {
 			path = arg
@@ -124,7 +140,6 @@ export const parseArgv = (argv: readonly string[]): ParsedArgs => {
 		theme,
 		tone,
 		width,
-		all,
 		sort,
 		serve,
 		port,
@@ -134,6 +149,8 @@ export const parseArgv = (argv: readonly string[]): ParsedArgs => {
 		sidebar,
 		noUpdateCheck,
 		noMdx,
+		show,
+		startInFilter,
 	}
 }
 
@@ -147,7 +164,8 @@ options:
   --theme <id>   color theme: ${themeList} (default: opencode)
   --tone <mode>  dark or light (default: dark)
   --width <N>    cap rendered markdown width at N columns
-  --all          include hidden and gitignored files in discovery
+  --show <list>  reveal normally-skipped entries; comma-separated subset of:
+                   hidden, gitignored. Use --show "" to clear.
   --sort <mode>  sidebar order: dirs-first (default) or files-first
   --sidebar <m>  initial sidebar visibility: auto (default), on, or off
   --serve        serve the given file as HTML in the browser (skips TUI)
@@ -157,9 +175,10 @@ options:
   --config-path  print path to the config file and exit
   --no-update-check  suppress the "newer version available" check (also via NO_UPDATE_NOTIFIER=1)
   --no-mdx       exclude .mdx files from discovery (default: included)
+  --start-in-filter  open the sidebar filter prompt on launch
 
 configuration:
   file: $XDG_CONFIG_HOME/house/config.toml  (default ~/.config/house/config.toml)
-  keys: theme, tone, mdx
-  env:  HOUSE_THEME, HOUSE_TONE, HOUSE_MDX
+  keys: theme, tone, mdx, show, start_in_filter
+  env:  HOUSE_THEME, HOUSE_TONE, HOUSE_MDX, HOUSE_SHOW, HOUSE_START_IN_FILTER
   precedence (high → low): flags → env → file → defaults`

package/src/commands/buildCommands.ts

@@ -44,6 +44,11 @@ const annotations: Record<string, Annotation> = {
 	"sidebar.toggle": { title: "Toggle sidebar", category: "View" },
 	"help.toggle": { title: "Show help", category: "App" },
 	"filter.open": { title: "Filter files…", category: "Navigation" },
+	"discovery.toggleAll": {
+		title: "Toggle hidden / gitignored files",
+		category: "Navigation",
+		keywords: ["hidden", "gitignore", "dotfiles", "all"],
+	},
 	"serve.current": { title: "Open in browser", category: "File" },
 	"file.edit": { title: "Open in editor", category: "File", keywords: ["editor", "vim", "vscode"] },
 	"theme.next": { category: "Appearance" },

package/src/config/load.ts

@@ -13,23 +13,39 @@
 import { homedir } from "node:os"
 import { join } from "node:path"
 import { Config, ConfigProvider, Effect, Schema } from "effect"
+import { parseShowList, SHOW_CATEGORIES, type ShowCategory } from "../discovery/show.ts"
 import { themeDefinitions } from "../theme/registry.ts"
 
 export interface HouseConfig {
 	readonly theme: string
 	readonly tone: "dark" | "light"
 	readonly mdx: boolean
+	/** 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. */
+	readonly show: readonly ShowCategory[]
+	/** Open the sidebar filter prompt on launch so the user can type
+	 *  immediately. Esc returns to normal focus (no special behavior).
+	 *  Default false. */
+	readonly startInFilter: boolean
 }
 
 export interface CliOverrides {
 	readonly theme: string | null
 	readonly tone: string | null
 	readonly mdx: boolean | null
+	/** When non-null, the parsed `--show` list completely replaces env/file
+	 *  (no per-category merging — sets compose by replacement, like every
+	 *  other CLI override here). `--show ""` sets the empty set. */
+	readonly show: readonly ShowCategory[] | null
+	readonly startInFilter: boolean | null
 }
 
 const DEFAULT_THEME = "opencode"
 const DEFAULT_TONE: "dark" | "light" = "dark"
 const DEFAULT_MDX = true
+const DEFAULT_SHOW = ""
+const DEFAULT_START_IN_FILTER = false
 
 const themeIds = themeDefinitions.map((t) => t.id)
 
@@ -39,7 +55,13 @@ 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"])
+const KNOWN_FILE_KEYS: ReadonlySet<string> = new Set([
+	"theme",
+	"tone",
+	"mdx",
+	"show",
+	"start_in_filter",
+])
 
 const schema = Config.all({
 	theme: Config.schema(Schema.Literals(themeIds), "theme"),
@@ -48,6 +70,12 @@ const schema = Config.all({
 	// (TOML bools, env vars, CLI flags all flow through as text). Mapped to
 	// a real boolean in `loadConfig` below.
 	mdx: Config.schema(Schema.Literals(["true", "false"] as const), "mdx"),
+	// `show` arrives as a comma-separated string from every provider
+	// (`fileProvider` coerces TOML arrays via `String()`, which produces
+	// `"hidden,gitignored"`). Token-level validation happens in `loadConfig`
+	// so the error message can list valid categories at the field's path.
+	show: Config.schema(Schema.String, "show"),
+	start_in_filter: Config.schema(Schema.Literals(["true", "false"] as const), "start_in_filter"),
 })
 
 const defaultsProvider = (): ConfigProvider.ConfigProvider =>
@@ -55,6 +83,8 @@ const defaultsProvider = (): ConfigProvider.ConfigProvider =>
 		theme: DEFAULT_THEME,
 		tone: DEFAULT_TONE,
 		mdx: String(DEFAULT_MDX),
+		show: DEFAULT_SHOW,
+		start_in_filter: String(DEFAULT_START_IN_FILTER),
 	})
 
 /**
@@ -170,9 +200,13 @@ const envProvider = (env: Record<string, string | undefined>): ConfigProvider.Co
 	const theme = env["HOUSE_THEME"]
 	const tone = env["HOUSE_TONE"]
 	const mdx = env["HOUSE_MDX"]
+	const show = env["HOUSE_SHOW"]
+	const startInFilter = env["HOUSE_START_IN_FILTER"]
 	if (theme !== undefined) entries.push(["theme", theme])
 	if (tone !== undefined) entries.push(["tone", tone])
 	if (mdx !== undefined) entries.push(["mdx", mdx])
+	if (show !== undefined) entries.push(["show", show])
+	if (startInFilter !== undefined) entries.push(["start_in_filter", startInFilter])
 	return ConfigProvider.fromUnknown(Object.fromEntries(entries))
 }
 
@@ -181,6 +215,9 @@ const cliProvider = (overrides: CliOverrides): ConfigProvider.ConfigProvider =>
 	if (overrides.theme !== null) entries.push(["theme", overrides.theme])
 	if (overrides.tone !== null) entries.push(["tone", overrides.tone])
 	if (overrides.mdx !== null) entries.push(["mdx", String(overrides.mdx)])
+	if (overrides.show !== null) entries.push(["show", overrides.show.join(",")])
+	if (overrides.startInFilter !== null)
+		entries.push(["start_in_filter", String(overrides.startInFilter)])
 	return ConfigProvider.fromUnknown(Object.fromEntries(entries))
 }
 
@@ -217,15 +254,42 @@ export const formatConfigError = (err: unknown): string => {
 
 export const loadConfig = (
 	options: LoadOptions = {},
-): Effect.Effect<HouseConfig, Config.ConfigError> => {
-	const cli = options.cli ?? { theme: null, tone: null, mdx: null }
+): Effect.Effect<HouseConfig, Config.ConfigError | Error> => {
+	const cli = options.cli ?? {
+		theme: null,
+		tone: null,
+		mdx: null,
+		show: null,
+		startInFilter: null,
+	}
 	const onWarning = options.onWarning ?? ((msg) => process.stderr.write(`${msg}\n`))
 	const provider = cliProvider(cli).pipe(
 		ConfigProvider.orElse(envProvider(options.env ?? process.env)),
 		ConfigProvider.orElse(fileProvider(options.filePath ?? defaultConfigPath(), onWarning)),
 		ConfigProvider.orElse(defaultsProvider()),
 	)
-	return schema
-		.parse(provider)
-		.pipe(Effect.map((raw) => ({ theme: raw.theme, tone: raw.tone, mdx: raw.mdx === "true" })))
+	return schema.parse(provider).pipe(
+		Effect.flatMap((raw) => {
+			const parsed = parseShowList(raw.show)
+			if (!parsed.ok) {
+				// Effect's `Config.ConfigError` requires a `SchemaError` or
+				// `SourceError` cause that we don't have a clean constructor
+				// for here — surface as a plain Error and let the boot
+				// layer's existing `formatConfigError` (which already handles
+				// `instanceof Error`) render it.
+				return Effect.fail(
+					new Error(
+						`show: unknown category "${parsed.invalid.join('", "')}" (valid: ${SHOW_CATEGORIES.join(", ")})`,
+					),
+				)
+			}
+			return Effect.succeed({
+				theme: raw.theme,
+				tone: raw.tone,
+				mdx: raw.mdx === "true",
+				show: parsed.value,
+				startInFilter: raw.start_in_filter === "true",
+			})
+		}),
+	)
 }

package/src/discovery/show.ts

@@ -0,0 +1,48 @@
+/**
+ * Discovery visibility categories.
+ *
+ * Each name identifies a class of entries that the walker normally skips and
+ * that the user can opt into showing. The set is intentionally an open vocab:
+ * adding a future category (e.g. `"build-artifacts"`) means one entry here,
+ * one branch in `walk`, and no churn in the CLI/config surface — `--show`,
+ * `HOUSE_SHOW`, and TOML `show = [...]` all carry whatever names live in this
+ * tuple.
+ */
+export const SHOW_CATEGORIES = ["hidden", "gitignored"] as const
+
+export type ShowCategory = (typeof SHOW_CATEGORIES)[number]
+
+export const isShowCategory = (value: string): value is ShowCategory =>
+	(SHOW_CATEGORIES as readonly string[]).includes(value)
+
+/**
+ * Parse a comma-separated list of category names. Whitespace around tokens
+ * is trimmed; empty tokens (trailing comma, double comma) are dropped.
+ * Returns `{ ok, value }` on success or `{ ok: false, invalid }` listing
+ * tokens that aren't known categories — callers shape the error message
+ * for their surface (CLI vs config).
+ */
+export type ParseShowResult =
+	| { readonly ok: true; readonly value: readonly ShowCategory[] }
+	| { readonly ok: false; readonly invalid: readonly string[] }
+
+export const parseShowList = (raw: string): ParseShowResult => {
+	const tokens = raw
+		.split(",")
+		.map((t) => t.trim())
+		.filter((t) => t.length > 0)
+	const invalid = tokens.filter((t) => !isShowCategory(t))
+	if (invalid.length > 0) return { ok: false, invalid }
+	// De-dupe while preserving the configured order — callers that care
+	// about presence use Set membership; emitting a unique sequence keeps
+	// the round-trip (encode/decode) stable.
+	const seen = new Set<ShowCategory>()
+	const out: ShowCategory[] = []
+	for (const t of tokens as ShowCategory[]) {
+		if (!seen.has(t)) {
+			seen.add(t)
+			out.push(t)
+		}
+	}
+	return { ok: true, value: out }
+}

package/src/discovery/walk.ts

@@ -2,6 +2,7 @@ import { readdir, readFile } from "node:fs/promises"
 import { extname, join, relative, resolve } from "node:path"
 import { Data, Effect, Stream } from "effect"
 import ignore, { type Ignore } from "ignore"
+import type { ShowCategory } from "./show.ts"
 
 export interface FileEntry {
 	/** Absolute path on disk. */
@@ -15,8 +16,11 @@ export interface FileEntry {
 export type SortOrder = "dirs-first" | "files-first"
 
 export interface WalkOptions {
-	/** Include hidden files and gitignored entries. Hard skips still apply. */
-	readonly all?: boolean
+	/** Categories of normally-skipped entries to opt into. Empty (the
+	 *  default) yields the conservative set: no dotfiles, no gitignored
+	 *  entries. Order is irrelevant — semantics are set membership. Hard
+	 *  skips (`node_modules`, `.git`, `.venv`) always apply. */
+	readonly show?: Iterable<ShowCategory>
 	/** Group order within each directory. Default `dirs-first`. */
 	readonly sort?: SortOrder
 	/** Include `.mdx` files alongside `.md`/`.markdown`. Default `true`. */
@@ -88,13 +92,13 @@ async function* walkDirGen(
 	dirPath: string,
 	rootPath: string,
 	parentLevels: readonly IgnoreLevel[],
-	opts: { all: boolean; sort: SortOrder; mdx: boolean },
+	opts: { showHidden: boolean; showGitignored: boolean; sort: SortOrder; mdx: boolean },
 	signal: AbortSignal,
 ): AsyncGenerator<FileEntry, void, void> {
 	if (signal.aborted) return
 
 	let levels = parentLevels
-	if (!opts.all) {
+	if (!opts.showGitignored) {
 		const ig = await tryLoadGitignore(dirPath)
 		if (signal.aborted) return
 		if (ig) levels = [...parentLevels, { dir: dirPath, ig }]
@@ -114,17 +118,17 @@ async function* walkDirGen(
 
 		if (entry.isDirectory()) {
 			if (HARD_SKIP_DIRS.has(entry.name)) continue
-			if (!opts.all && entry.name.startsWith(".")) continue
-			if (!opts.all && isIgnored(entryPath, true, levels)) continue
+			if (!opts.showHidden && entry.name.startsWith(".")) continue
+			if (!opts.showGitignored && isIgnored(entryPath, true, levels)) continue
 			yield* walkDirGen(entryPath, rootPath, levels, opts, signal)
 			continue
 		}
 
 		if (!entry.isFile()) continue
-		if (!opts.all && entry.name.startsWith(".")) continue
+		if (!opts.showHidden && entry.name.startsWith(".")) continue
 		const allowed = opts.mdx ? MARKDOWN_EXTENSIONS : MARKDOWN_EXTENSIONS_NO_MDX
 		if (!allowed.has(extname(entry.name).toLowerCase())) continue
-		if (!opts.all && isIgnored(entryPath, false, levels)) continue
+		if (!opts.showGitignored && isIgnored(entryPath, false, levels)) continue
 
 		yield {
 			path: entryPath,
@@ -143,7 +147,7 @@ async function* walkDirGen(
  * Rules (see DESIGN.md §6):
  * - Extensions: `.md`, `.markdown`, and `.mdx` (unless `mdx: false`).
  * - Hard skips (always): `node_modules`, `.git`, `.venv`.
- * - Hidden files/dirs (leading `.`) skipped unless `all: true`.
+ * - Hidden files/dirs (leading `.`) skipped unless `show` contains `"hidden"`.
  * - `.gitignore` honored, including nested `.gitignore` files.
  * - Symlinks not followed.
  * - Sort: alphabetical within each group; directories before files
@@ -154,8 +158,10 @@ export const walk = (
 	options: WalkOptions = {},
 ): Stream.Stream<FileEntry, DiscoveryError> => {
 	const absRoot = resolve(root)
+	const show = new Set<ShowCategory>(options.show ?? [])
 	const opts = {
-		all: options.all ?? false,
+		showHidden: show.has("hidden"),
+		showGitignored: show.has("gitignored"),
 		sort: options.sort ?? ("dirs-first" as SortOrder),
 		mdx: options.mdx ?? true,
 	}

package/src/index.tsx

@@ -19,6 +19,7 @@ import pkg from "../package.json" with { type: "json" }
 import { Browser } from "./Browser.tsx"
 import { parseArgv, usage } from "./cli/argv.ts"
 import { defaultConfigPath, formatConfigError, loadConfig } from "./config/load.ts"
+import { parseShowList, SHOW_CATEGORIES, type ShowCategory } from "./discovery/show.ts"
 import { walk, type FileEntry, type SortOrder } from "./discovery/walk.ts"
 import { Header } from "./Header.tsx"
 import { readFileText } from "./io/readFile.ts"
@@ -59,15 +60,29 @@ export type SidebarMode = "auto" | "on" | "off"
 
 interface DiscoverShellProps {
 	readonly target: string
-	readonly all: boolean
+	/** Resolved discovery vocabulary from the config layer. The shift+a
+	 *  toggle (#145) is session-only sugar that flips between this set
+	 *  and the full vocabulary; the underlying categories remain
+	 *  independent everywhere else. */
+	readonly initialShow: readonly ShowCategory[]
 	readonly sort: SortOrder
 	readonly mdx: boolean
 	readonly maxWidth: number | null
 	readonly sidebarMode: SidebarMode
+	readonly startInFilter: boolean
 }
 
-const DiscoverShell = ({ target, all, sort, mdx, maxWidth, sidebarMode }: DiscoverShellProps) => {
+const DiscoverShell = ({
+	target,
+	initialShow,
+	sort,
+	mdx,
+	maxWidth,
+	sidebarMode,
+	startInFilter,
+}: DiscoverShellProps) => {
 	const updateNotice = useUpdateNotice()
+	const [show, setShow] = useState<readonly ShowCategory[]>(initialShow)
 	const [files, setFiles] = useState<readonly FileEntry[]>([])
 	const [scanning, setScanning] = useState<boolean>(true)
 	const [scanError, setScanError] = useState<string | null>(null)
@@ -76,7 +91,15 @@ const DiscoverShell = ({ target, all, sort, mdx, maxWidth, sidebarMode }: Discov
 	const countRef = useRef(0)
 
 	useEffect(() => {
-		const program = walk(target, { all, sort, mdx }).pipe(
+		// Restart from a clean slate every time the discovery set changes.
+		// Required for the `all` toggle (#145): without this, a flip would
+		// concatenate the new walk onto stale entries and leave `scanning`
+		// stuck on whatever the previous walk last set it to.
+		setFiles([])
+		setScanning(true)
+		setScanError(null)
+		countRef.current = 0
+		const program = walk(target, { show, sort, mdx }).pipe(
 			Stream.groupedWithin(64, Duration.millis(60)),
 			Stream.runForEach((chunk) =>
 				Effect.sync(() => {
@@ -101,7 +124,7 @@ const DiscoverShell = ({ target, all, sort, mdx, maxWidth, sidebarMode }: Discov
 		return () => {
 			Effect.runFork(Fiber.interrupt(fiber))
 		}
-	}, [target, all, sort, mdx])
+	}, [target, show, sort, mdx])
 
 	const discoveryStatus = scanError ?? (scanning ? `indexing… ${countRef.current}` : null)
 
@@ -111,7 +134,17 @@ const DiscoverShell = ({ target, all, sort, mdx, maxWidth, sidebarMode }: Discov
 			maxWidth={maxWidth}
 			discoveryStatus={discoveryStatus}
 			sidebarMode={sidebarMode}
+			startInFilter={startInFilter}
 			updateNotice={updateNotice}
+			onToggleAll={() => {
+				// shift+a is the only place the categories are treated as a
+				// single thing. If every category is already on, fall back
+				// to "show none"; otherwise opt into the full vocabulary.
+				// Each press is a stable round-trip between [] and full.
+				const next: readonly ShowCategory[] =
+					show.length === SHOW_CATEGORIES.length ? [] : [...SHOW_CATEGORIES]
+				setShow(next)
+			}}
 		/>
 	)
 }
@@ -209,6 +242,20 @@ if (import.meta.main) {
 		process.exit(0)
 	}
 
+	// Parse --show eagerly so an invalid token fails fast with the CLI-style
+	// "house: ..." message, before any I/O work in loadConfig kicks off.
+	let cliShow: readonly ShowCategory[] | null = null
+	if (args.show !== null) {
+		const parsed = parseShowList(args.show)
+		if (!parsed.ok) {
+			console.error(
+				`house: --show: unknown category "${parsed.invalid.join('", "')}" (valid: ${SHOW_CATEGORIES.join(", ")})`,
+			)
+			process.exit(2)
+		}
+		cliShow = parsed.value
+	}
+
 	const config = await Effect.runPromise(
 		loadConfig({
 			cli: {
@@ -217,13 +264,18 @@ if (import.meta.main) {
 				// --no-mdx is a one-way override: present means "off". When
 				// absent, fall through to env/file/default.
 				mdx: args.noMdx ? false : null,
+				// `--show` replaces env/file when present (set semantics —
+				// no per-category merge across sources). `null` falls through.
+				show: cliShow,
+				// One-way override: present means "on". Absent → env/file/default.
+				startInFilter: args.startInFilter ? true : null,
 			},
 		}),
 	).catch((err: unknown) => {
 		console.error(`house: ${formatConfigError(err)}`)
 		process.exit(2)
 	})
-	const { theme: themeId, tone, mdx } = config
+	const { theme: themeId, tone, mdx, show, startInFilter } = config
 	const themeDef = getThemeDefinition(themeId)
 	if (themeDef === undefined) {
 		// Unreachable: Config.schema validated themeId against themeDefinitions.
@@ -298,10 +350,11 @@ if (import.meta.main) {
 			themeId,
 			tone,
 			maxWidth,
-			all: args.all,
+			show,
 			sort,
 			mdx,
 			sidebarMode,
+			startInFilter,
 			updateCheck: !args.noUpdateCheck,
 		})
 	}
@@ -312,10 +365,11 @@ interface TuiBootOptions {
 	readonly themeId: string
 	readonly tone: "dark" | "light"
 	readonly maxWidth: number | null
-	readonly all: boolean
+	readonly show: readonly ShowCategory[]
 	readonly sort: SortOrder
 	readonly mdx: boolean
 	readonly sidebarMode: SidebarMode
+	readonly startInFilter: boolean
 	/** Run the npm-registry probe and surface the "update available" notice.
 	 *  False suppresses both the toast and the quit-time print. */
 	readonly updateCheck: boolean
@@ -326,10 +380,11 @@ async function runTui({
 	themeId,
 	tone,
 	maxWidth,
-	all,
+	show,
 	sort,
 	mdx,
 	sidebarMode,
+	startInFilter,
 	updateCheck,
 }: TuiBootOptions): Promise<void> {
 	let stats: Awaited<ReturnType<typeof stat>>
@@ -366,11 +421,12 @@ async function runTui({
 			<RegistryProvider initialValues={[[themeAtom, initialTheme]]}>
 				<DiscoverShell
 					target={target}
-					all={all}
+					initialShow={show}
 					sort={sort}
 					mdx={mdx}
 					maxWidth={maxWidth}
 					sidebarMode={sidebarMode}
+					startInFilter={startInFilter}
 				/>
 			</RegistryProvider>,
 		)

package/src/keymap/browser.ts

@@ -43,6 +43,11 @@ export interface BrowserCtx {
 	/** Suspend the TUI, hand the TTY to `$EDITOR`, resume and re-read on
 	 *  exit. No-op when nothing is selected; gating is the binding's job. */
 	readonly editCurrent: () => void
+	/** Toggle hidden + gitignored discovery axes together (#145 — UI sugar
+	 *  for `shift+a`; the underlying flags stay independent everywhere
+	 *  else). Snapshots the current selected path so it can be restored
+	 *  once the re-walk completes. */
+	readonly toggleAll: () => void
 }
 
 /** Step size for shift+j/k and the space/b/page keys. Constant for v1; could
@@ -147,6 +152,19 @@ export const browserBindings: readonly KeyBinding<BrowserCtx>[] = [
 		when: paletteClosed,
 		run: (c) => c.openPalette(),
 	},
+	{
+		id: "discovery.toggleAll",
+		group: "Sidebar",
+		description: "Show / hide hidden and gitignored files",
+		// No footer hint: shift+a is help/palette only. The footer hint row is
+		// already at width capacity on narrow viewports, and the toggle isn't
+		// a per-row action you reach for constantly.
+		keys: ["shift+a"],
+		// Selection-preservation logic lives in Browser.tsx — see the
+		// `pendingSelectionPath` ref. The toggle itself is session-only and
+		// does not write back to the TOML config.
+		run: (c) => c.toggleAll(),
+	},
 	{
 		id: "theme.next",
 		group: "Global",