Prohelp and the prompt gutter :: Shell Architecture :: OpenShellOrg Docs

Prohelp and the prompt gutter

Write this so someone with no background can follow.

Stance

Prohelp is a shell-agnostic sibling product — not bundled with Open Shell. When prohelp is installed, Open Shell may surface help without the user typing --help or help.

All gutter chrome renders on the display overlay layer. Nothing in this page prints to stdout or pollutes the pipeline record.

Automatic help affordance

When the current input buffer matches a prohelp entry, the shell shows an interactive help control immediately — no --help typing required.

This builds trust: users see help appear when the shell recognizes the command, instead of guessing whether documentation exists.

Detection

Open Shell evaluates the input buffer on each edit (debounced):

  1. Match the first argv token (or full prefix) against prohelp SDL detectPattern / matchPrefix

  2. On match, activate the help affordance for that topic id

  3. On no match, hide the affordance (do not leave a stale ?)

Complex matchers stay in prohelp SDL; the shell only runs the cheap prefix/regex pass and asks prohelp whether a topic exists.

Placement (primary and secondary)

Reserve a gutter band at the left edge of the prompt row — black or terminal-background space before context tokens.

When prohelp recognizes the command, the ? help button is the first context affordance in that band (leftmost clickable/highlight target before [gcloud: …] tokens).

[?] [gcloud: ftn ▾] [py: .venv ▾]  rjamd@desk:~/code › kubectl get
 ^ gutter                          ^ input buffer (matched)

  • Gutter sits on the display overlay — not part of the editable input string

  • Click, Enter-on-focus, or bound key opens prohelp scoped to the matched topic

  • When context chrome is on a separate row, gutter ? leads that row (see Front context integration)

Secondary — inline ghost (optional theme)

When gutter is disabled or the terminal is too narrow:

  • Show a ghost/hover ? immediately after the last character of the matched command prefix on the input line

  • Lower contrast until hover/focus; same prohelp route as gutter

  • Themes may enable both; default is gutter-only

Help icon (glyph policy)

Glyph Verdict

U+2370 (⍰)

Rejected — monospace fonts render it poorly; visibility inconsistent

Raw ? (U+003F)

Acceptable fallback — readable everywhere

Custom TUI glyph

v1 target — drawn in overlay layer (not stdout/stdin); theme pack id e.g. oso.help-icon

Ship ? first; swap to custom overlay glyph when terminal host supports styled overlay cells without touching the byte stream.

Prompt gutter zone (shell-owned chrome)

The gutter is a reserved left band on the prompt/display overlay:

  • Prevents command prompts from lining up flush against the terminal left wall

  • Owns basic CLI UX chrome so tools stop printing ad-hoc > arrows and bullet lists to stdout

Gutter width (sketch)

Profile Columns (monospace cells)

Minimal (help only)

2 — one ? + 1sp padding

Standard

3 — optional ▶ grabber + ?

Choice menu

4–6 — marker column + help; list markers may extend row below

Width is fixed per theme (gutterWidthHint in prohelp/SDL theme packs), not computed from stdout.

Dynamic gutter content (overlay only)

All glyphs render on the display overlay — never stdout:

Glyph / pattern Role Notes

▶ (U+25B6) or custom graphic

Line emphasis, input grabber

Replaces programmer-printed > prompt arrows

▪ (U+25AA)

Compact bullet for equal-option lists

Shell-owned list chrome

A`–`Z / 0`–`9

Simple choice menu markers

Pairs with overlay list; not Readline key spam

?

Prohelp entry when topic matches

First affordance when prohelp detects command

Scope: "good enough" basic CLI UX. Rich layouts (multi-pane help, search, pagination) stay in prohelp TUI and framework overlays.

Deprecated pattern: printf-style ad-hoc formatting in command output for prompts, arrows, and menus — prefer shell-owned gutter + display overlay.

Front context integration

When persistent shell context is active (e.g. gcloud configuration token focused, or namespace loaded):

  • Prohelp scopes to that namespace — requiresContext keys filter topics

  • Gutter ? appears at the start of the persistent context row (not only on the input line)

  • Invoking help while a context token is focused passes namespace + key values to prohelp

[?] [gcloud: ftn ▾] [py: .venv ▾]     ← context row (gutter ? scopes to gcloud)
                              rjamd@desk:~/code › gcloud compute instances list

If both input-buffer match and focused context apply, context scope wins for topic filtering; input match still controls whether ? is visible.

Prohelp topic SDL (names tentative — implement in openshellorg/prohelp schema):

Field Type Purpose

detectPattern

string (regex) or array

Match against input buffer for auto-help (primary)

matchPrefix

string

Cheaper alternative to regex — literal prefix e.g. kubectl, gcloud

detectMode

enum

argv0, prefix, or regex — how shell applies detect fields

autoHelp

boolean (default true when detect fields present)

Whether to show gutter/ghost affordance without user typing help

requiresContext

string[]

Context keys required; scopes help when token focused (existing field)

scopeNamespace

string

Default namespace for context-row help (e.g. gcloud)

gutterPlacement

enum

primary-gutter (default), inline-ghost, or both

gutterIcon

string

? or theme glyph id (default ?; v1 custom TUI id)

gutterWidthHint

integer

Theme hint for reserved gutter columns (default 2)

gutterPriority

integer

When multiple topics match, lower number wins

Example fragment:

topic: gcloud-compute-instances-list
matchPrefix: gcloud compute instances list
autoHelp: true
requiresContext: [gcloud.configuration, gcloud.project]
scopeNamespace: gcloud
gutterPlacement: primary-gutter
gutterIcon: ?
gutterWidthHint: 3

Layer placement

Layer Prohelp + gutter

Display overlay

Gutter band, ?, ▶, list markers — all transient chrome

Context chrome

Context-row gutter ?; token focus scopes prohelp

Control plane

Routes focus: gutter ? → prohelp overlay; does not insert ? into input buffer

Base (stdout)

Never — pipeline record stays clean

Non-goals

  • Bundling prohelp with Open Shell

  • Requiring prohelp for shell startup

  • Replacing prohelp TUI with gutter alone — gutter is discoverability, not the help viewer

Input-line primary: ▶ in the gutter

The gutter’s primary job on the command input row is to hold ▶ — the type-here grabber. That is the canonical reason the input line has a gutter.

  • Draw ▶ inside the gutter band — not as a separate chevron after an empty gutter cell.

  • Auto-?, list markers (▪, A–Z), and emphasis arrows share the same gutter column(s) when active (e.g. [?▶]).

  • Context rows may indent to gutter width for alignment; they do not get a blank faux-gutter that pretends to own ▶.

See prompt spatial layout for 1-line / 2-line placement.

Arrow mode (▶ lifetime)

▶ in the input gutter is not a hard-coded always-on history glyph. Top-bar arrow mode:

  • ephemeral — reticle while editing; gone after submit; never in copy

  • persist — remains on committed history rows; present in copy

Detail and ASCII: prompt spatial layout. Overlay-only persist (visible but stripped from copy) is advanced later.

Line modes and gutter

With prompt spatial layout:

  • 2-line: gutter holds ▶ (and optional ?) on the input row only; command editor to its right; context row indents to gutter width

  • 1-line: gutter holds ▶ at the left of the single combined row

Auto-? still appears when prohelp matches the input buffer — never inserted into the editable command string. Context-token focus may still scope help; see front-context integration above.