@carlesandres/house 0.3.1 → 0.4.1

package/src/CommandPalette.tsx

@@ -0,0 +1,150 @@
+/**
+ * CommandPalette — modal overlay for searching and running commands.
+ *
+ * Render-only: state lives in Browser.tsx alongside helpVisible / 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.
+ */
+
+import { RGBA } from "@opentui/core"
+import { colors } from "./theme/colors.ts"
+import type { AppCommand } from "./commands/types.ts"
+
+// Semi-transparent black scrim painted across the viewport behind the modal.
+// Opentui composites it over the chrome underneath, so the rest of the UI
+// reads as darkened while the modal stays fully opaque. Mirrors opencode's
+// dialog backdrop (cli/cmd/tui/ui/dialog.tsx).
+const SCRIM = RGBA.fromInts(0, 0, 0, 150)
+
+export interface CommandPaletteProps {
+	readonly commands: readonly AppCommand[]
+	readonly query: string
+	readonly selectedIndex: number
+	readonly viewportWidth: number
+	readonly viewportHeight: number
+}
+
+const FOOTER_HINT = "↑↓ select  enter run  esc close"
+
+export const CommandPalette = ({
+	commands,
+	query,
+	selectedIndex,
+	viewportWidth,
+	viewportHeight,
+}: CommandPaletteProps) => {
+	const overlayWidth = Math.min(viewportWidth - 4, 64)
+	// 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 bodyHeight = Math.min(desiredBody, maxBody)
+	const overlayHeight = chrome + bodyHeight
+	const left = Math.max(0, Math.floor((viewportWidth - overlayWidth) / 2))
+	const top = Math.max(0, Math.floor((viewportHeight - overlayHeight) / 2))
+
+	// 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.
+	const scrollTop = (() => {
+		if (commands.length <= bodyHeight) return 0
+		const maxScroll = commands.length - bodyHeight
+		let s = 0
+		if (selectedIndex >= bodyHeight) s = selectedIndex - bodyHeight + 1
+		return Math.max(0, Math.min(s, maxScroll))
+	})()
+	const visible = commands.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.
+	const SHORTCUT_WIDTH = 10
+	const titleWidth = Math.max(8, rowWidth - 2 /* selector */ - SHORTCUT_WIDTH - 1 /* gap */)
+
+	const fit = (s: string, width: number): string =>
+		s.length === width
+			? s
+			: s.length > width
+				? s.slice(0, Math.max(0, width - 1)) + "…"
+				: s + " ".repeat(width - s.length)
+
+	const fitRight = (s: string, width: number): string =>
+		s.length >= width ? s.slice(0, width) : " ".repeat(width - s.length) + s
+
+	return (
+		<box
+			position="absolute"
+			left={0}
+			top={0}
+			width={viewportWidth}
+			height={viewportHeight}
+			zIndex={20}
+			style={{ backgroundColor: SCRIM }}
+		>
+			<box
+				position="absolute"
+				left={left}
+				top={top}
+				width={overlayWidth}
+				height={overlayHeight}
+				title=" Commands "
+				titleAlignment="left"
+				paddingLeft={1}
+				paddingRight={1}
+				style={{
+					border: true,
+					borderColor: colors.textMuted,
+					flexDirection: "column",
+					backgroundColor: colors.surface,
+				}}
+			>
+				<text
+					wrapMode="none"
+					content={fit(`> ${query}▏`, rowWidth)}
+					style={{ fg: colors.textStrong }}
+				/>
+				<text content=" " />
+				{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
+						const selector = isSelected ? "▸ " : "  "
+						const titleText = fit(cmd.title, titleWidth)
+						const shortcutText = cmd.shortcut
+							? fitRight(cmd.shortcut, SHORTCUT_WIDTH)
+							: " ".repeat(SHORTCUT_WIDTH)
+						// Title and shortcut render as separate spans so the shortcut
+						// can use `textMuted` while the title uses `text`/`textStrong`.
+						// Same trick opencode pulls with `--text-weak` — the theme
+						// guarantees the contrast, we just pick the right role.
+						const titleFg = isSelected ? colors.textStrong : colors.text
+						return (
+							<text
+								key={cmd.id}
+								wrapMode="none"
+								style={isSelected ? { bg: colors.selectedBg } : {}}
+							>
+								<span style={{ fg: titleFg }}>{`${selector}${titleText} `}</span>
+								<span style={{ fg: colors.textMuted }}>{shortcutText}</span>
+							</text>
+						)
+					})
+				)}
+				<text content=" " />
+				<text
+					wrapMode="none"
+					content={fit(FOOTER_HINT, rowWidth)}
+					style={{ fg: colors.textMuted }}
+				/>
+			</box>
+		</box>
+	)
+}

package/src/Footer.tsx

@@ -11,6 +11,10 @@
  * were discovered. Intentional — `q:quit` and `?:help` are exactly what an
  * empty-vault user needs as an exit and discoverability anchor.
  *
+ * The filter input does not live here — it renders as a row inside the
+ * sidebar (see Browser.tsx). The pattern mirrors ghui's PR list, where the
+ * filter is part of the list it filters.
+ *
  * Width math assumes hint labels are ASCII plus a small set of single-cell
  * BMP glyphs (see `displayKey`). `fitHints` and notice clipping use string
  * length as a proxy for cell count; introducing a CJK or emoji label would
@@ -29,10 +33,15 @@ export interface FooterProps<C> {
 	readonly ctx: C
 	readonly width: number
 	readonly notice?: string | null
-	/** When set, the footer row turns into the filter input — `/<query>▏` —
-	 *  and suppresses both the hint row and the notice. Mirrors hunk's
-	 *  StatusBar: one row of chrome, content swaps by state. */
-	readonly filter?: { readonly query: string } | null
+	/** Persistent status line (e.g. "indexing… 42"). Distinct from `notice`:
+	 *  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
 }
 
 const HINT_SEPARATOR = "  "
@@ -62,39 +71,52 @@ const displayKey = (raw: string): string => {
 	}
 }
 
-const formatHint = <C,>(b: KeyBinding<C>): string | null => {
+/** 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 label: string
+}
+
+const hintWidth = (h: Hint): number =>
+	h.key === null ? h.label.length : h.key.length + 1 + h.label.length // key + " " + label
+
+const formatHint = <C,>(b: KeyBinding<C>): Hint | null => {
 	if (!b.hint) return null
 	const first = b.keys[0]
 	if (!first) return null
-	return `${displayKey(first)}:${b.hint}`
+	return { key: displayKey(first), label: b.hint }
 }
 
-/** Drop hints from the end until the joined string fits within `width`.
- *  If not even the first hint fits, fall back to the bare key portion so
- *  the user still sees a discoverability anchor (e.g. `?` instead of an
- *  empty row on an 8-column terminal). */
-const fitHints = (hints: readonly string[], width: number): string => {
-	if (width <= 0 || hints.length === 0) return ""
-	let acc = ""
+/** 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. */
+const fitHints = (hints: readonly Hint[], width: number): Hint[] => {
+	if (width <= 0 || hints.length === 0) return []
+	const acc: Hint[] = []
+	let used = 0
 	for (const h of hints) {
-		const next = acc.length === 0 ? h : `${acc}${HINT_SEPARATOR}${h}`
-		if (next.length > width) break
-		acc = next
+		const add = acc.length === 0 ? hintWidth(h) : HINT_SEPARATOR.length + hintWidth(h)
+		if (used + add > width) break
+		acc.push(h)
+		used += add
 	}
 	if (acc.length > 0) return acc
-	// Nothing fit. Render just the first hint's key (everything before `:`)
-	// truncated to width, so the row is never silently blank.
-	const firstKey = hints[0]!.split(":")[0] ?? ""
-	return firstKey.slice(0, width)
+	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: "" }]
 }
 
-/** Hints shown alongside the filter input. Mirrors the modal-mode key
- *  handler in `Browser.tsx`; if those bindings change, update both. */
-const FILTER_HINTS = "↵:open  esc:cancel"
-/** Minimum gap between the filter input and its hints on the same row. */
-const FILTER_HINT_GAP = 2
+const STATUS_SEPARATOR = " · "
 
-export const Footer = <C,>({ bindings, ctx, width, notice, filter }: FooterProps<C>) => {
+export const Footer = <C,>({
+	bindings,
+	ctx,
+	width,
+	notice,
+	discoveryStatus,
+	filterQuery,
+}: FooterProps<C>) => {
 	const usableWidth = Math.max(0, width - 2) // 1-cell horizontal padding each side
 
 	const rowStyle = {
@@ -104,48 +126,93 @@ export const Footer = <C,>({ bindings, ctx, width, notice, filter }: FooterProps
 		flexDirection: "row",
 		paddingLeft: 1,
 		paddingRight: 1,
-		backgroundColor: colors.background,
+		backgroundColor: colors.surface,
 	} as const
 
-	// Filter mode is two-column: input left, hints right, separated by a
-	// flex-grow spacer. Hints drop entirely on narrow viewports rather than
-	// pushing the input off-screen — the input is the primary surface.
-	if (filter) {
-		const input = `/${filter.query}▏`
-		const showHints = input.length + FILTER_HINT_GAP + FILTER_HINTS.length <= usableWidth
-		return (
-			<box style={rowStyle}>
-				<text content={input} wrapMode="none" style={{ fg: colors.textStrong }} />
-				{showHints && (
-					<>
-						<box style={{ flexGrow: 1 }} />
-						<text content={FILTER_HINTS} wrapMode="none" style={{ fg: colors.textMuted }} />
-					</>
-				)}
-			</box>
-		)
+	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}]` })
 	}
-
-	const hints: string[] = []
 	for (const b of bindings) {
 		if (b.when && !b.when(ctx)) continue
 		const h = formatHint(b)
 		if (h !== null) hints.push(h)
 	}
-	const hintContent = fitHints(hints, usableWidth)
+
+	// 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 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)
 			: notice
 		: null
 
-	// Notice > hints. Notice fg is strong; hints are muted.
-	const content = noticeContent ?? hintContent
-	const fg = noticeContent ? colors.textStrong : colors.textMuted
+	// Two-tone hint row: keys render in `text` (foreground-strength), the
+	// `:label` portion in `textMuted`. Matches ghui's footer treatment so
+	// the key — the actionable token — visually leads each hint.
+	const renderHints = () =>
+		visibleHints.flatMap((h, i) => {
+			const sep =
+				i > 0
+					? [
+							<text
+								key={`s${i}`}
+								content={HINT_SEPARATOR}
+								wrapMode="none"
+								style={{ fg: colors.textMuted }}
+							/>,
+						]
+					: []
+			if (h.key === null) {
+				return [
+					...sep,
+					<text key={`l${i}`} content={h.label} wrapMode="none" style={{ fg: colors.textMuted }} />,
+				]
+			}
+			return [
+				...sep,
+				<text key={`k${i}`} content={h.key} wrapMode="none" style={{ fg: colors.text }} />,
+				<text
+					key={`l${i}`}
+					content={` ${h.label}`}
+					wrapMode="none"
+					style={{ fg: colors.textMuted }}
+				/>,
+			]
+		})
+
+	// Priority: notice > (status + hints). Notice fg is strong; status sits
+	// at the muted level so it reads as ambient state, not an event.
+	if (noticeContent !== null) {
+		return (
+			<box style={rowStyle}>
+				<text content={noticeContent} wrapMode="none" style={{ fg: colors.textStrong }} />
+			</box>
+		)
+	}
+
+	if (status !== null) {
+		return (
+			<box style={rowStyle}>
+				<text content={statusContent} wrapMode="none" style={{ fg: colors.textMuted }} />
+				<text content={STATUS_SEPARATOR} wrapMode="none" style={{ fg: colors.textMuted }} />
+				{renderHints()}
+			</box>
+		)
+	}
 
-	return (
-		<box style={rowStyle}>
-			<text content={content} wrapMode="none" style={{ fg }} />
-		</box>
-	)
+	return <box style={rowStyle}>{renderHints()}</box>
 }

package/src/Header.tsx

@@ -0,0 +1,68 @@
+/**
+ * Header — single-row chrome above the two-pane area.
+ *
+ * Borderless single line modeled on ghui's PlainLine header: brand and
+ * current filename on the left, version on the right. The row is
+ * informational, not interactive — see issue #38 for the design discussion.
+ *
+ * Width degrades gracefully: the version drops first when the row gets
+ * tight, then the filename, leaving the brand mark as the irreducible
+ * identity element. Always rendered — the row is worth one cell on any
+ * viewport so the user never loses the filename indicator (notably, when
+ * the sidebar drawer overlays the reader on narrow viewports).
+ */
+
+import pkg from "../package.json" with { type: "json" }
+import { BRAND, BRAND_NAME } from "./brand.ts"
+import { colors } from "./theme/colors.ts"
+
+export const HEADER_HEIGHT = 1
+
+const FILE_SEPARATOR = " · "
+
+export interface HeaderProps {
+	readonly width: number
+	/** Currently selected file's relative path. When set, the Header shows
+	 *  it next to the brand mark — replaces the per-pane border title that
+	 *  used to carry this information. */
+	readonly currentFile?: string | null
+	/** Optional override for the version string (testing). Defaults to
+	 *  the running package's version. */
+	readonly version?: string
+}
+
+export const Header = ({ width, currentFile, version = pkg.version }: HeaderProps) => {
+	const brand = `${BRAND} ${BRAND_NAME}`
+	const right = `v${version}`
+	const file = currentFile && currentFile.length > 0 ? currentFile : null
+	const usableWidth = Math.max(0, width - 2) // 1-cell horizontal padding each side
+
+	// Priority: brand > filename > version. Brand is the irreducible identity
+	// anchor. Filename is per-selection useful info — keep it before the
+	// largely-static version string. `1` is the minimum gap between left and
+	// right groups so they never visually collide.
+	const leftWithFile = file !== null ? `${brand}${FILE_SEPARATOR}${file}` : brand
+	const showFileWithVersion = leftWithFile.length + 1 + right.length <= usableWidth
+	const showFileWithoutVersion = leftWithFile.length <= usableWidth
+	const showFile = file !== null && (showFileWithVersion || showFileWithoutVersion)
+	const left = showFile ? leftWithFile : brand
+	const showRight = left.length + 1 + right.length <= usableWidth
+
+	return (
+		<box
+			style={{
+				width,
+				height: HEADER_HEIGHT,
+				flexShrink: 0,
+				flexDirection: "row",
+				justifyContent: "space-between",
+				paddingLeft: 1,
+				paddingRight: 1,
+				backgroundColor: colors.surface,
+			}}
+		>
+			<text content={left} wrapMode="none" style={{ fg: colors.text }} />
+			{showRight && <text content={right} wrapMode="none" style={{ fg: colors.text }} />}
+		</box>
+	)
+}

package/src/HelpOverlay.tsx

@@ -6,9 +6,13 @@
  * keys — the dispatcher and the help text are the same source of truth.
  */
 
+import { RGBA } from "@opentui/core"
 import type { KeyBinding } from "./keymap/keymap.ts"
 import { colors } from "./theme/colors.ts"
 
+// See CommandPalette.tsx for the scrim rationale.
+const SCRIM = RGBA.fromInts(0, 0, 0, 150)
+
 export interface HelpOverlayProps<C> {
 	readonly bindings: readonly KeyBinding<C>[]
 	readonly viewportWidth: number
@@ -82,49 +86,63 @@ export const HelpOverlay = <C,>({
 	return (
 		<box
 			position="absolute"
-			left={left}
-			top={top}
-			width={overlayWidth}
-			height={overlayHeight}
+			left={0}
+			top={0}
+			width={viewportWidth}
+			height={viewportHeight}
 			zIndex={10}
-			title=" Help "
-			titleAlignment="left"
-			style={{
-				border: true,
-				borderColor: colors.borderActive,
-				padding: 1,
-				flexDirection: "column",
-				backgroundColor: colors.surface,
-			}}
+			style={{ backgroundColor: SCRIM }}
 		>
-			{rows.map((row) => {
-				switch (row.kind) {
-					case "header":
-						return (
-							<text
-								key={row.key}
-								wrapMode="none"
-								content={row.text}
-								style={{ fg: colors.borderActive, attributes: 1 /* bold */ }}
-							/>
-						)
-					case "footer":
-						return (
-							<text
-								key={row.key}
-								wrapMode="none"
-								content={row.text}
-								style={{ fg: colors.textMuted }}
-							/>
-						)
-					case "spacer":
-						return <text key={row.key} content=" " />
-					case "binding":
-						return (
-							<text key={row.key} wrapMode="none" content={row.text} style={{ fg: colors.text }} />
-						)
-				}
-			})}
+			<box
+				position="absolute"
+				left={left}
+				top={top}
+				width={overlayWidth}
+				height={overlayHeight}
+				title=" Help "
+				titleAlignment="left"
+				style={{
+					border: true,
+					borderColor: colors.textMuted,
+					padding: 1,
+					flexDirection: "column",
+					backgroundColor: colors.surface,
+				}}
+			>
+				{rows.map((row) => {
+					switch (row.kind) {
+						case "header":
+							return (
+								<text
+									key={row.key}
+									wrapMode="none"
+									content={row.text}
+									style={{ fg: colors.borderActive, attributes: 1 /* bold */ }}
+								/>
+							)
+						case "footer":
+							return (
+								<text
+									key={row.key}
+									wrapMode="none"
+									content={row.text}
+									style={{ fg: colors.textMuted }}
+								/>
+							)
+						case "spacer":
+							return <text key={row.key} content=" " />
+						case "binding":
+							return (
+								<text
+									key={row.key}
+									wrapMode="none"
+									content={row.text}
+									style={{ fg: colors.text }}
+								/>
+							)
+					}
+				})}
+			</box>
 		</box>
 	)
 }

package/src/brand.ts

@@ -0,0 +1,7 @@
+/**
+ * Brand mark. U+2302 HOUSE is a single-cell glyph in every monospace font
+ * we care about; falls back to a tofu box on rare fonts that lack it.
+ * Single import point so future placements (#76) stay in sync.
+ */
+export const BRAND = "⌂"
+export const BRAND_NAME = "house"

package/src/cli/argv.ts

@@ -21,6 +21,16 @@ export interface ParsedArgs {
 	readonly help: boolean
 	/** True when `--version` was passed. */
 	readonly version: boolean
+	/** True when `--config-path` was passed: print resolved config path and exit. */
+	readonly configPath: boolean
+	/** Value of `--sidebar <mode>` (`auto`, `on`, `off`), or null. Validated by the boot layer. */
+	readonly sidebar: string | null
+	/** True when `--no-update-check` was passed: suppress the npm-registry
+	 *  probe and the "update available" notice. Mirrors the
+	 *  `NO_UPDATE_NOTIFIER` env var so opt-out is reachable without env state. */
+	readonly noUpdateCheck: boolean
+	/** True when `--no-mdx` was passed: exclude `.mdx` files from discovery. */
+	readonly noMdx: boolean
 }
 
 /**
@@ -41,6 +51,10 @@ export const parseArgv = (argv: readonly string[]): ParsedArgs => {
 	let port: string | null = null
 	let help = false
 	let version = false
+	let configPath = false
+	let sidebar: string | null = null
+	let noUpdateCheck = false
+	let noMdx = false
 
 	for (let i = 0; i < argv.length; i++) {
 		const arg = argv[i]!
@@ -79,13 +93,48 @@ export const parseArgv = (argv: readonly string[]): ParsedArgs => {
 			case "-v":
 				version = true
 				continue
+			case "--config-path":
+				configPath = true
+				continue
+			case "--sidebar": {
+				// Don't swallow the following flag as the sidebar value.
+				// `--sidebar --width 80` should leave sidebar=null (the boot
+				// layer reports a missing value) without losing --width.
+				const next = argv[i + 1]
+				if (next !== undefined && !next.startsWith("-")) {
+					sidebar = next
+					i++
+				}
+				continue
+			}
+			case "--no-update-check":
+				noUpdateCheck = true
+				continue
+			case "--no-mdx":
+				noMdx = true
+				continue
 		}
 		if (path === null && !arg.startsWith("-")) {
 			path = arg
 		}
 	}
 
-	return { path, theme, tone, width, all, sort, serve, port, help, version }
+	return {
+		path,
+		theme,
+		tone,
+		width,
+		all,
+		sort,
+		serve,
+		port,
+		help,
+		version,
+		configPath,
+		sidebar,
+		noUpdateCheck,
+		noMdx,
+	}
 }
 
 const themeList = themeDefinitions.map((t) => t.id).join(", ")
@@ -100,7 +149,17 @@ options:
   --width <N>    cap rendered markdown width at N columns
   --all          include hidden and gitignored files in discovery
   --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)
   --port <N>     port for --serve (default: OS-assigned)
   -h, --help     show this help and exit
-  -v, --version  print version and exit`
+  -v, --version  print version and exit
+  --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)
+
+configuration:
+  file: $XDG_CONFIG_HOME/house/config.toml  (default ~/.config/house/config.toml)
+  keys: theme, tone, mdx
+  env:  HOUSE_THEME, HOUSE_TONE, HOUSE_MDX
+  precedence (high → low): flags → env → file → defaults`