@carlesandres/house 0.4.7 → 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

@@ -40,30 +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
@@ -73,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[] = []
@@ -87,22 +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
 
@@ -117,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
@@ -137,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)
@@ -167,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 }} />,
@@ -195,6 +183,20 @@ 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,
@@ -211,9 +213,15 @@ export const Footer = <C,>({
 
 		return (
 			<box style={rowStyle}>
-				<Spinner {...spinnerProps} />
-				<text content=" " wrapMode="none" style={{ fg: colors.textMuted }} />
-				<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/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

@@ -14,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
@@ -139,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)
@@ -149,11 +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)
+  --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
@@ -161,6 +163,11 @@ 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, defaultRoot

package/src/commands/buildCommands.ts

@@ -2,9 +2,8 @@
  * Derive palette commands from `browserBindings` plus the annotation map.
  *
  * The annotation map is the *only* hand-written list keyed by binding id:
- * it carries (a) hide flags for bindings that are pure keystroke nav, and
- * (b) title rewrites for bindings whose `description` reads as a help-row
- * entry rather than a palette command. Every other binding is exposed
+ * it carries title rewrites and metadata for bindings whose raw
+ * `description` reads awkwardly as a palette command. Every enabled binding is exposed
  * verbatim — its `description` becomes the palette `title`, its first key
  * becomes the `shortcut`.
  *
@@ -30,49 +29,40 @@ interface Annotation {
 }
 
 /**
- * Pure-keystroke nav (j/k/space/b/[/]…) is intentionally hidden — those
- * bindings have no command-shaped meaning. Reader prev/next file (`[`/`]`)
- * and sidebar `open` (Return/l) are the borderline cases from #70 Q6a;
- * hidden in v1, reconsider if users ask. Title rewrites convert
- * help-overlay phrasing ("Toggle sidebar visibility") into imperative
- * palette phrasing ("Toggle sidebar"). See #70 design log §6.
+ * Title rewrites convert keymap phrasing into imperative palette phrasing.
+ * With the help overlay removed (#139), the palette is the only in-app full
+ * action index, so all currently-enabled actions stay discoverable here.
  */
 const annotations: Record<string, Annotation> = {
 	// --- Keep, with title rewrites where the binding description reads awkwardly as a command ---
 	quit: { category: "App" },
 	"focus.toggle": { title: "Toggle focus", category: "View" },
 	"sidebar.toggle": { title: "Toggle sidebar", category: "View" },
-	"help.toggle": { title: "Show help", category: "App" },
+	"sidebar.down": { category: "Navigation" },
+	"sidebar.up": { category: "Navigation" },
+	"sidebar.jumpDown": { category: "Navigation" },
+	"sidebar.jumpUp": { category: "Navigation" },
+	"sidebar.pageDown": { category: "Navigation" },
+	"sidebar.pageUp": { category: "Navigation" },
+	"sidebar.top": { category: "Navigation" },
+	"sidebar.bottom": { category: "Navigation" },
+	"sidebar.open": { title: "Open file", category: "Navigation" },
 	"filter.open": { title: "Filter files…", category: "Navigation" },
+	"filter.clearOrOpen": { category: "Navigation" },
 	"discovery.toggleAll": {
 		title: "Toggle hidden / gitignored files",
 		category: "Navigation",
 		keywords: ["hidden", "gitignore", "dotfiles", "all"],
 	},
+	"reader.back": { title: "Back to sidebar", category: "Navigation" },
+	"reader.prevFile": { title: "Previous file", category: "Navigation" },
+	"reader.nextFile": { title: "Next file", category: "Navigation" },
 	"serve.current": { title: "Open in browser", category: "File" },
 	"file.edit": { title: "Open in editor", category: "File", keywords: ["editor", "vim", "vscode"] },
 	"theme.next": { category: "Appearance" },
 	"theme.prev": { category: "Appearance" },
 	"theme.toneToggle": { title: "Toggle dark/light tone", category: "Appearance" },
 
-	// --- Hide: pure keystroke navigation (j/k/space/b/g/G…) ---
-	"sidebar.down": { hidden: true },
-	"sidebar.up": { hidden: true },
-	"sidebar.jumpDown": { hidden: true },
-	"sidebar.jumpUp": { hidden: true },
-	"sidebar.pageDown": { hidden: true },
-	"sidebar.pageUp": { hidden: true },
-	"sidebar.top": { hidden: true },
-	"sidebar.bottom": { hidden: true },
-
-	// --- Hide: borderline reader nav. `[`/`]` and Return-to-open feel command-shaped
-	//     but are pure keystroke navigation under the hood. #70 Q6a — reconsider
-	//     if user feedback expects them in the palette.
-	"sidebar.open": { hidden: true },
-	"reader.back": { hidden: true },
-	"reader.prevFile": { hidden: true },
-	"reader.nextFile": { hidden: true },
-
 	// --- Hide: the palette opener itself shouldn't appear in the palette ---
 	"palette.open": { hidden: true },
 }
@@ -80,8 +70,8 @@ const annotations: Record<string, Annotation> = {
 /**
  * Build the AppCommand list for a given render. Iterates `browserBindings`
  * in array order (the empty-query palette renders in this order, by design
- * — see #70 design log §empty-state ordering), drops hidden entries and
- * those whose `when` predicate currently returns false, and resolves
+ * — see #70 design log §empty-state ordering), drops explicitly-hidden entries
+ * and those whose `when` predicate currently returns false, and resolves
  * annotations to populate title / category / keywords.
  */
 export const buildCommands = (ctx: BrowserCtx): readonly AppCommand[] => {
@@ -89,9 +79,8 @@ export const buildCommands = (ctx: BrowserCtx): readonly AppCommand[] => {
 	for (const binding of browserBindings) {
 		const ann = annotations[binding.id]
 		if (ann?.hidden) continue
-		// Same gating the keymap dispatcher uses. Disabled bindings get
-		// hidden from the palette (per #70 Q5b — see #96 for the show-with-
-		// reason follow-up after the atom-driven migration).
+		// Same gating the keymap dispatcher uses. Disabled bindings stay out of
+		// the palette; #96 tracks a future show-with-reason mode.
 		if (binding.when && !binding.when(ctx)) continue
 		const cmd: AppCommand = {
 			id: binding.id,

package/src/commands/score.ts

@@ -34,7 +34,7 @@ const fuzzyIncludes = (text: string, query: string): boolean => {
 
 const searchText = (command: AppCommand): string =>
 	normalize(
-		[command.title, command.category, command.shortcut, ...(command.keywords ?? [])]
+		[command.title, command.category, ...(command.keywords ?? [])]
 			.filter((s): s is string => Boolean(s))
 			.join(" "),
 	)