Skip to content

QoL: window-placement setting (set-display-rule!) is undiscoverable by the words users actually search #67

Description

@cuttlefisch

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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    area:guiGUI / TUI rendering + editor UXenhancementNew feature or request

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions