Summary
The setting that controls how a buffer kind is placed in a window — split vs.
take-over-the-window — is (set-display-rule! KIND ACTION), surfaced via the
describe-display-policy command and concept:display-policy. It works well, but
it's very hard to find unless you already know the term "display rule": a real
user hit this trying to make the AI-agent/shell buffer take over the window instead
of splitting, and the natural search terms surface nothing.
Repro (the discoverability gap)
Goal a user has: "make the AI agent / shell open full-window instead of splitting."
The words they reach for — none of which resolve to the right node:
kb_search "take over window"
kb_search "fullscreen buffer" / "open fullscreen"
kb_search "don't split" / "no split"
kb_search "maximize on open"
kb_search "window placement"
The actual answer — (set-display-rule! "shell" "replace-focused") — lives under
concept:display-policy and the set-display-rule! scheme-api node, keyed on the
jargon "display policy / display rule", which a user wouldn't guess.
Why it matters
This is a basic customization (where do my buffers open?) that's "hard to describe
but easy to want" — exactly the kind of QoL setting that should be searchable by
intent, not by the internal term. The mechanism is good; only discoverability is the gap.
Proposed fix (cheap)
Add intent-keyword aliases to the two KB nodes so kb_search resolves them:
concept:display-policy and the set-display-rule! scheme-api node →
:ALIASES: / tags like:
window-placement, split-vs-replace, take-over-window, replace-focused, fullscreen-buffer, dont-split, no-split, maximize-on-open, where-buffers-open, shell-window, agent-window
Optional extras:
- A short "Windows / buffer placement" section in the config/extension guide that
shows (set-display-rule! "shell" "replace-focused") as the worked example.
- Consider listing
set-display-rule! in the :set/option-search surface (it's a
Scheme-only setter today, so it doesn't show up alongside set-option! options).
Context
Found while configuring the AI-agent window during the two-machine collab validation
(feat/crdt-collab-validation). Default Shell rule is ReuseOrSplit horizontal:35%;
the fix a user wants is ReplaceFocused, but they can't find the lever.
Summary
The setting that controls how a buffer kind is placed in a window — split vs.
take-over-the-window — is
(set-display-rule! KIND ACTION), surfaced via thedescribe-display-policycommand andconcept:display-policy. It works well, butit's very hard to find unless you already know the term "display rule": a real
user hit this trying to make the AI-agent/shell buffer take over the window instead
of splitting, and the natural search terms surface nothing.
Repro (the discoverability gap)
Goal a user has: "make the AI agent / shell open full-window instead of splitting."
The words they reach for — none of which resolve to the right node:
kb_search "take over window"kb_search "fullscreen buffer"/"open fullscreen"kb_search "don't split"/"no split"kb_search "maximize on open"kb_search "window placement"The actual answer —
(set-display-rule! "shell" "replace-focused")— lives underconcept:display-policyand theset-display-rule!scheme-api node, keyed on thejargon "display policy / display rule", which a user wouldn't guess.
Why it matters
This is a basic customization (where do my buffers open?) that's "hard to describe
but easy to want" — exactly the kind of QoL setting that should be searchable by
intent, not by the internal term. The mechanism is good; only discoverability is the gap.
Proposed fix (cheap)
Add intent-keyword aliases to the two KB nodes so
kb_searchresolves them:concept:display-policyand theset-display-rule!scheme-api node →:ALIASES:/ tags like:window-placement, split-vs-replace, take-over-window, replace-focused, fullscreen-buffer, dont-split, no-split, maximize-on-open, where-buffers-open, shell-window, agent-windowOptional extras:
shows
(set-display-rule! "shell" "replace-focused")as the worked example.set-display-rule!in the:set/option-search surface (it's aScheme-only setter today, so it doesn't show up alongside
set-option!options).Context
Found while configuring the AI-agent window during the two-machine collab validation
(
feat/crdt-collab-validation). DefaultShellrule isReuseOrSplit horizontal:35%;the fix a user wants is
ReplaceFocused, but they can't find the lever.