---
title: "Vulpine.app, the desktop app"
description: "Vulpine.app is the desktop app on the Mac (bundle id com.voidfab.vulpine, productName in src-tauri/tauri.conf.json). Glyph is its look: an ambient overlay that sits on screen beside your work."
type: "living"
source: "apps/glyph/README.md"
verified: "2026-10-06"
group: "Frontends"
---

> **Living doc**, checked against the code 2026-10-06

On this page
"Glyph" means the app as it draws in that look; menus and logs still say Glyph. The app runs as a Tauri shell whose
windows are moving to GPUI one surface at a time. It connects to the gateway and draws a swappable body (the chassis,
ADR 0036) around a swappable face, the Visual Theme: Orb, Cast (textmode.js engines), LED (the scanner face) or SVG.
[The frontends overview](/docs/frontends/overview) lists the other ways to talk to Vulpine.

## Architecture

```text
Glyph Tauri shell
  -> @voidfab/vulpine-voice-client
      -> vulpine-voice-gateway WebSocket
```

The gateway owns STT, TTS, turn authority and the brain. Glyph owns shell integration, microphone capture, audio
playback and visuals. There is no local STT, TTS or LLM path: run `vulpine-voice-gateway` before you start Glyph.


## First launch and the control socket

Give a newly installed Glyph its first launch from Finder. If macOS asks, click **Open Anyway** in System Settings →
Privacy & Security. A first launch from ssh or `launchctl kickstart` is refused (`OS_REASON_CODESIGNING`), because the
signing identity is not notarized. After one Finder launch, launchd and ssh launches of the same bundle work.

Glyph and `vulpine-glyphctl` talk over `glyph.sock`, under `$XDG_RUNTIME_DIR`, else under `$TMPDIR` (`socket_path` in
`src-tauri/src/ipc.rs`). The socket's directory must be owner-only (0700), or Glyph refuses to start. Once the socket is
bound, Glyph writes its path to a pointer, `~/Library/Application Support/com.voidfab.vulpine/glyph.sock.path` (0600).
vulpine-glyphctl tries `--socket <path>` or `$VULPINE_GLYPH_SOCKET` first (that path alone), then the pointer, then the
pointer under each earlier bundle id's folder (`crates/vulpine_bundle_move/src/legacy.rs`), then this shell's own path.
It uses the first that answers, and a stale pointer falls through (`src-tauri/src/ctl_socket.rs`). So a
vulpine-glyphctl in Terminal reaches a Glyph opened from the Dock, whatever `TMPDIR` the terminal exports.

If vulpine-glyphctl still says connection refused, find the socket with `lsof -U -c glyph` and run vulpine-glyphctl
with the same directory, for example `TMPDIR="$(getconf DARWIN_USER_TEMP_DIR)" vulpine-glyphctl status`.

**A gateway on another Mac.** Operations → Connection & privacy → Gateway on another Mac runs the relay
(`scripts/glyph-gateway-relay`) as a login agent. Name the gateway Mac's ssh alias; it is written to `[hosts] mini` in
`~/.config/vulpine/fox9.toml`. The relay is an ordinary ssh command hop, not `ssh -L`. It needs
`tools/gateway/glyph_gateway_remote_proxy.py` installed on the gateway host as
`~/.cache/fox9/runtime-relays/gateway-remote-proxy.py`. The card shows the route, the relay's state, its last hop error
and the loadout the session bound.

## Configuration

Glyph reads `config.toml` from `$XDG_CONFIG_HOME/glyph`, else `~/.config/glyph` (`config_dir` in
`src-tauri/src/config.rs`), and writes defaults on first run.

- `[glyph] chassis` is the launch body until a live switch is saved. After that Glyph launches with the last body
  picked; an unknown id falls back to `classic`. A fresh install writes `chassis = "halo"` and shows the Cast face in its
  Seal variant until a face is picked.
- `[glyph] labs` (default `false`) is the one Labs switch. Off, the Labs orb styles (Bricks and Voxel) are not offered in
  Look → Orb style, a pick of one is refused, and a remembered one draws Classic.
- Gateway settings live under `[vulpine]`. A file that says `[foxline]` is still read, with one launch line on stderr
  naming the new table; `[vulpine]` wins when a file has both.

```toml
[vulpine]
url = "ws://127.0.0.1:8780"
agent = "operator"
persona = ""
workspace = "catalog/agents/operator"
loadout = "default"
# ADR 0021 client speech-hint floor as the voice-client bargeInMinimumLevel
# (0, 1]; a mic frame during assistant playback corroborates a barge when its
# residual RMS clears level / 14. 0.18 = -37.8 dBFS (a laptop's built-in mic).
# A desk interface and microphone measured a conversational overlay at -43 dBFS
# and echo-only frames under -45 dBFS (ADR 0026 Pass 2), so it runs 0.07 (-46 dBFS).
barge_in_min_level = 0.18
```

`workspace` is the brain's working directory on the **gateway host**, not a path on the Glyph's machine. A Mac that
talks to a gateway on another Mac names the absolute directory on the gateway host, for example
`<checkout>/catalog/agents/operator`. An empty
workspace becomes `catalog/agents/<agent>`, and `start_session` fails if that relative path does not exist on the
gateway host.

Glyph sends no project root, cwd or Git path. When the loadout enables owned attention, the gateway resolves the project
root from the agent workspace and refuses the session if that repository is unsafe or unavailable.

### Hold-to-talk on the Globe key

`global_shortcuts.hold_to_talk` is the dictation key: hold it, speak, let go. It is absent by default. A chord table
(`[global_shortcuts.hold_to_talk] modifiers = […] key = "D"`) uses the Carbon hotkey path. The Globe (fn) key has no
scancode there, so `hold_to_talk = "Globe"` uses a small listen-only helper, `globectl`:

```toml
[global_shortcuts]            # TOML allows this header after the sub-tables
hold_to_talk = "Globe"
# globe_helper = "~/.local/bin/globectl"   # default: beside the Glyph binary, then ~/.local/bin
[global_shortcuts.hold_to_talk_fallback]  # optional: used only when the Globe key cannot run
modifiers = ["CommandOrControl", "Alt"]
key = "D"
```

Glyph runs `globectl` (`tools/globe/globectl.swift`) as a supervised child. If the helper or its grant is missing, Glyph
logs why, registers the fallback chord if one is set, and still launches.


The helper ships inside Vulpine.app at `Vulpine.app/Contents/MacOS/globectl`, the first place Glyph looks, signed with
the app's identity. A bundled Glyph needs no `globe_helper` line. For `glyph-dev`, build it with `just build-globectl`
or point `globe_helper` at a copy.

One-time setup on each Mac:

1. System Settings → Keyboard → "Press 🌐 key" → **Do Nothing**. The helper only listens and cannot swallow the key,
   so any other setting also opens the emoji picker or switches input source.
2. System Settings → Privacy & Security → **Input Monitoring** → enable **Vulpine**. macOS judges the responsible
   process, which is the app when it spawns the helper. Until the grant is on, the helper prints `no_input_monitoring`
   and retries every 5 s. After you install a new bundle, check this row again: a re-signed app can need its row
   toggled off and on.
3. `tools/globe/globectl --probe` reports both: `input_monitoring` (`granted` / `denied`) and `fn_usage` (`do_nothing`
   is the one wanted; `unset` is the system default, not Do Nothing).

Two gestures sit on top of the hold:

- **Double-tap for hands-free.** Two Globe taps whose presses are inside 400 ms (each tap under
  300 ms, no other key during it) open a dictation that keeps listening with the key up. It ends on
  the next tap, on Esc, or after 2.5 s with no new words in the partials (6 s to start talking).
  The first tap is an empty hold the gateway drops.
- **Esc discards.** Esc during a hold or a hands-free dictation ends it and nothing is typed. The
  tap only listens, so the Esc also reaches the focused app.


**Both keys wait for the microphone to settle.** A microphone plugged in, unplugged or made the default sends a burst
of Core Audio notifications. A press inside that burst waits for it to end, at most 1.5 s, before it opens the mic.


### Where the words land, and review mode

Glyph types a held dictation (dictation.v1 `source: hold`). It asks the screen agent over its socket
(`~/.local/state/vulpine/screen/screen.sock`; `screen_agent_socket` overrides) to type the words into the app that had
the focus at key-down. It relays the agent's insert proof, which "scratch that" erases by.

The target is pinned. Every write carries the key-down app's pid and bundle id, and the screen agent refuses to type if
the front app changed, so words never land in another app. A refusal shows on the chip as `APP CHANGED — NOT TYPED`
(`NOT TYPED — <reason>` otherwise), with no **Scratch that** beside it.


**Trailing capture** (`hold_to_talk_trailing_capture`, default `true`). A key-up while you are still speaking keeps the
microphone open until 250 ms of quiet, never past 1.5 s. `false` ends the capture at key-up. The **Trailing capture**
switch sets the key (below).


`hold_to_talk_literal = false` turns on **review mode** (default `true`: type at release). Nothing is typed at release.
The chip shows the raw words and, beside them, the tidy the gateway returns behind its deletion-only guards
(`dictation_tidy`). Then:

| choice | key | say (after the wake) | types |
|---|---|---|---|
| send it | Return | "send it" | the tidy |
| say it plain | Shift+Return | "say it plain" | the raw words |
| scratch that | Esc | "scratch that" | nothing |

The three keys are system-wide only while a review is open. A tidy the guard refused is never offered: the chip says
"plain only" and Return types the raw words. After ten seconds with no choice nothing is typed, and the chip says so.

`hold_to_talk_style` picks the tidy's style (`clean`, `email`, `chat`, `code`), and the `dictation_tidy_request` carries
it. With no style set (the default, "auto" in the tab), the gateway picks one for the app the hold went down on: the
loadout's `[dictation.styles]`, then its built-in table, then plain. The chip names the style applied: the gateway's
`dictation_tidy.style` when its reply carries one, else the style Glyph sent, else `auto`.

```toml
[global_shortcuts]
hold_to_talk = "Globe"
hold_to_talk_literal = false   # review mode; absent or true = type at release
# hold_to_talk_style = "clean"
# screen_agent_socket = "~/.local/state/vulpine/screen/screen.sock"
```

Glyph reads `~/.config/glyph/config.toml` at launch, so a relaunch applies a hand edit. The gateway side needs the
screen agent running. The gateway admits holds unless the bound loadout says `[dictation] hold_to_talk = false`.

### Dictation controls: Voice → Hold-to-talk, the chip and vulpine-glyphctl

Every control below takes the path its key or spoken verb takes. Nothing new crosses the wire.

- **The chip.** During a review it shows **Send** / **Plain** / **Scratch** (the Return / Shift+Return / Esc path).
  After an insert it shows `TYPED` with a **Scratch that** button for 6 s. A click on the chip never takes the focus
  from the field the words went to.
- **Operations → Voice → Hold-to-talk**: the switch, the key's live route and any setup still unmet, **Literal /
  Review**, the tidy style (review mode only), a read-only stream line, **Scratch that**, and, while a call is
  recorded, a meeting line with **Opt out** and **Forget…**. Meeting minutes are on the Admin's Meetings page.
- **Settings persist.** The switch, the mode, the style and the key choice apply at once and are written to the
  `[global_shortcuts]` keys of `~/.config/glyph/config.toml`. Every other line keeps its bytes, and the first write of
  a session keeps a `config.toml.bak`. The writer refuses a missing, symlinked, unwritable or unparsable file, and says
  so. A key choice takes effect at the next launch.
- **Scratch that** erases the last insert inside the gateway's 120 s window. **Keep that** has no button: say it, or
  run `vulpine-glyphctl keep-that`.


```bash
vulpine-glyphctl dictation hold [--literal|--review] [--style clean|email|chat|code|auto]   # opens the mic; nothing spoken
vulpine-glyphctl dictation release
vulpine-glyphctl dictation hold --source remote         # mic stays closed; PCM comes from `dictation feed`
vulpine-glyphctl dictation feed [--from <path|->] [--edges <path|->] [--rate 16000]   # a hold on outside PCM (remotectl, a FIFO)
vulpine-glyphctl dictation review send|plain|scratch    # an open review, as its keys
vulpine-glyphctl dictation erase-last                   # "scratch that" for the last insert
vulpine-glyphctl dictation status                       # hold, mode, style, key route, last insert — no words
vulpine-glyphctl dictation mode --literal|--review [--style s|auto]   # persisted; auto = the gateway picks per app
vulpine-glyphctl dictation on|off                       # the switch, persisted (off removes hold_to_talk)
vulpine-glyphctl keep-that                              # the gateway answers aloud
vulpine-glyphctl recall --at 15:00 [--minutes 20] | --from 14:00 --to 14:30 | --last 15 [--session current]
vulpine-glyphctl meet status | opt-out [<call_id>] | forget [<call_id>]
vulpine-glyphctl meet minutes [<call_id>|last]          # the typed minutes on one line — prints model text
vulpine-glyphctl enroll start [--seconds 30] | status | discard   # real-voice enrollment from this mic
```

Each verb prints one JSON line (`{"ok": …, "verb": …}`) and exits 1 on a refusal. `meet minutes` is the one verb that
prints model text; every other verb prints counts, ids and reasons. `enroll start` records a speaker embedding from this
mic (10 to 60 seconds; only the averaged embedding is kept, the audio is deleted) when `[speaker] enrollment_from_mic`
is on and this Glyph is the voice owner.


## Operations

The status capsule stays visible in every Visual Theme. Open it to see the live link, phase, session, model, capture,
startup configuration and the bounded diagnostic log. When the current continuity has agent attention or settled
background work, the closed capsule also shows category counts (current counts, not unread state).

Operations offers the runtime controls; authority stays in the gateway:

- microphone on/off and the exact capture device;
- the body (Classic, Island, Halo, Familiar, Ribbon, Printer) and the Visual Theme (Orb, Cast, LED, SVG; Cast engines:
  Seal, Sigil, Corona, Hyphae, Beat);
- window dragging from the overlay or its move handle;
- transient assistant subtitles (Look);
- the Halo's and the Island's glances (Voice → Glances): **Level meter**, the mic and Vulpine's voice as two 8-segment
  bars from the Glyph's own analyzers (`apps/glyph/src/plugins/levelMeter.ts`), and **Agent attention**, how many herdr
  panes wait and which agent waited last (`apps/glyph/src/plugins/glances.ts`). Each is dark when there is nothing to
  show, still under reduced motion, and never a click target;
- Persona and Voice Profile, as the gateway reports them. When a Persona has no voice assets of its own, the deployment
  voice stays visible and voice switching is off;
- the model, as the gateway advertises it;
- interrupt, new session and reconnect;
- copy and clear the diagnostic JSON.

### The five groups, the face mirror and the look

Operations opens on five groups:

- **Look**: the body (Halo; Classic, Island, Printer, Familiar and Ribbon with Labs on, and a saved one is still drawn),
  face and face variant, mood color, face opacity, ring light, panel look and the glances. With Labs on, also Fox
  follows replies and the portrait.
- **Voice**: microphone on/off, capture device, Persona and voice, subtitles, and hold-to-talk (key, Literal / Review,
  tidy style, Scratch that, the meeting line; above).
- **Conversation window**: its switch, Show / hide, Cards open in, Open on a show and the Capture button.
- **Connection & privacy**: pairing (Connect to your gateway), the gateway on another Mac, the session (interrupt, new
  session, reconnect, connect), model, room, Share the front app with the brain, Permissions and microphone access.
- **App**: the version and the updates (Sparkle on or why off, an update found, the last offer the update guard checked
  and its verdict, and **Check now**), Relaunch and Quit, the shortcuts (Mic on or off, and Show or hide:
  Cmd-Opt-Space), Command line, a line naming what lives in the Admin (live sessions, the events log, latency and
  meeting minutes), and the **Labs** switch. With Labs on, the collapsed **Labs & diagnostics** group holds the
  read-outs: live state with **Copy diagnostics** (this Glyph's own client events, redacted, as JSON), the effective
  configuration, the conversation window's health lines, Shell, Footprint, Owner export, hold-to-talk's Trailing
  capture and stream line, and the Herdr attention and background-work cards.

A config that still names the face keys `show_scanner` or `show_orb` loads, and Glyph logs once that they are ignored.

Above the groups, a face mirror draws the current face small, with the body, the face, the mood and a one-line look
summary (opacity, ring light, subtitles). The Voice group shows a badge while a dictation review waits, and the App
group the attention count. A finalized transcript that waits to be saved shows its Retry save above every group.

The look controls apply to every face:

- **Mood color**: Auto follows the mood Vulpine sets as it talks. A color pins that mood.
- **Face opacity**: 20 to 100 percent, so you can see your work through the face.
- **Ring light**: an on/off switch.
- **Fox follows replies** (Labs): on by default. After each reply the gateway's decision model picks a face or a
  gesture for the fox (the motion plan, `[decision_shadow] motion_plan`). Off asks the gateway to stop for this Glyph's
  session (`motion_plan_switch`). The position is the webview's own preference, not `faces.json`.

A body picked in the Look group switches live. Glyph moves and resizes the window and saves the choice to `chassis.txt`
in its state directory. Face picks and the look are saved to `faces.json` in the same directory, so `glyphctl`, the
Admin and a fresh webview read the same choices. Subtitles are not saved.

`glyphctl` drives the same controls:

```bash
vulpine-glyphctl chassis <classic|island|halo|familiar|ribbon|printer>
vulpine-glyphctl face <orb|cast|scanner|phonogram> [variant]   # vulpine-glyphctl face lists the variants
vulpine-glyphctl look [--opacity N] [--ring on|off] [--mood <mood>|auto]
vulpine-glyphctl subtitles <on|off>
```

`look` needs at least one option. `--opacity` takes `60`, `60%` or `0.6`. `--mood` takes `auto` or one of steady, wry, sassy, earnest, reflective, hushed, menace, playful, lively or dreamy. `vulpine-glyphctl status` prints the chassis, face, look and subtitles.

Glyph starts with the microphone off. Turn it on from Operations or the audio shortcut. `vulpine-glyphctl audio
enabled|disabled` returns only once capture has really changed. `vulpine-glyphctl room <name>` sets the room Glyph
declares at hello (`[vulpine] room`; `room none` clears it). Subtitles show only the current turn and are never saved.
The Herdr attention and background-work cards show ids and states only, never transcript, output or paths.


### Owner, playback and reads from vulpine-glyphctl

```bash
vulpine-glyphctl owner [--json]      # the ADR 0024 owner: attachment, owner id, lease generation, hello mode
vulpine-glyphctl playback [--json]   # the last played segments (≤ 16, newest first)
vulpine-glyphctl read <url> [--restart] [--timeout <secs>] | --text <text> | pause|resume|next|previous|restart|stop|where
```

`owner` and `playback` exit 1 until the webview has reported one, and the resume token is never printed. A `read`
command waits for the gateway's answer, at most 70 s.


See `docs/frontend-interfaces.md` for the complete Vigil and Glyph interface inventory and authority boundary.


## Diagnostics and Session cards, Relaunch, and `[owner] export`

Operations shows these read-outs:

- **Labs → Shell**: what `vulpine-glyphctl doctor` prints, from inside this Glyph (the `doctor_report` command): the
  socket path, whether it answers vulpine-glyphctl now, the pid, the launch (Finder, the Dock or launchd; a shell's
  TMPDIR; XDG_RUNTIME_DIR), the launch TMPDIR, the requests in flight and the WebGPU word. Refresh reads it again.
- **Labs → Footprint**: main, WebKit, helpers, total and lifetime max from the reporter's read, the read's
  age, and "Reported to the gateway N s ago (session …)" or why not. Read now reads it here.
- **Labs → Live state**: the draw loop (parked, drawing or stopped) and its idle poll.
- **Labs → Owner export**: the **Phone can answer** switch. On, the owner receipt is exported for a phone to
  answer this Glyph's dialogs ("Phone can answer: clients/foxline-glyph/owner.json · gen N"); off removes the
  file and stops the export. The switch is written to `config.toml` and read at launch:

```toml
[owner]
export = false   # absent or true = the phone can answer
```

- **Relaunch Glyph** (Operations → App): Glyph quits and reopens its bundle with the same launch environment, so the
  socket path and vulpine-glyphctl stay valid. A dev build outside an app bundle refuses. `vulpine-glyphctl relaunch`
  does the same from a shell.

## The welcome window: the privacy grants

The welcome window has one row per macOS privacy grant the Glyph uses: what it is for, its live status and one button.
The rows are numbered steps, required first, and only the current row's button is live. Nothing asks at launch. "All
set" shows once every needed row is on.

- **Microphone** (required) uses macOS's own prompt.
- **Input Monitoring** is for the Globe key's helper, required only when `hold_to_talk` names the Globe key. While no
  hold key is set, the row offers **Use Globe**, which writes `hold_to_talk = "Globe"` and starts the key with no
  relaunch, and **Not now**.
- **Accessibility** is required while the conversation window is on, so its ⌥⇧Space does not also reach the app in
  front. **Screen Recording** joins while the window's Capture button is on.
- For a list grant, **Open System Settings** opens the exact pane with a drag card: drag the Vulpine.app row into the
  list. A grant that needs a relaunch makes the window relaunch the Glyph, at most once in two minutes.

Typing and screen capture need no grant of the Glyph's own: the screen agent holds them. The window opens by itself on
the first launch and whenever a required grant is missing; its switch is saved as `auto_show` in
`~/Library/Application Support/<bundle id>/welcome.json`. `vulpine-glyphctl onboarding` opens it, and
`vulpine-glyphctl status` prints one `Grant` line per grant (`Grant microphone: granted (required)`). Other ways back:
the right-click menu's **Finish setup…** (only while a required grant is missing), Operations → Connection & privacy →
Permissions → **Review**, and the Admin's Glyph section.


## Launch the showcase: `vulpine-glyphctl showcase`

`vulpine-glyphctl showcase [--tile <id>]` opens the native visuals showcase on the Glyph's Mac, one at a time. The
showcase must be installed beside the Glyph binary or in `~/.local/bin`. The verb prints one JSON line: `opened`,
`already_open`, or a refusal (`not_installed`, `old_build`, `unknown_tile`, `bad_tile`, `spawn_failed`). The brain can
ask for it too (`brain_frontend_control`, `action: "showcase"`), for an owner-local caller only.


## vulpine-glyphctl on the PATH: App → Command line

vulpine-glyphctl ships inside the bundle. **Install vulpine-glyphctl in PATH** (Operations → App → Command line) writes
a small shim that finds the installed app each time it runs, so it survives upgrades. It writes into the first folder
on your login PATH among `/opt/homebrew/bin`, `/usr/local/bin`, `~/.local/bin` and `~/bin` that you can write to, else
`~/.local/bin`. **Install in /usr/local/bin…** uses macOS's administrator prompt; Glyph never runs sudo. **Remove**
deletes only Glyph's own shim. The card also shows the bundle id this Glyph runs under (`com.voidfab.vulpine`).


## Trailing capture and footprint reporting as switches

Two switches each write a config key. A switch applies to this session at once and is saved to `config.toml` through
`src-tauri/src/config_writer.rs`, the one writer, behind its guards (the operator's own regular file, a `.bak` once per
session, an atomic write, only the owned key touched). A refused write holds for this session only, and the card says
so:

- **Trailing capture** (hold-to-talk) writes `[global_shortcuts] hold_to_talk_trailing_capture`.
- **Labs → Footprint → Report to the gateway** writes `[footprint] report`. Off stops the once-a-minute reports to the
  gateway (the Admin then shows no "Glyph footprint, reported" for this Glyph), across binds. **Read now** still reads
  here.

```toml
[global_shortcuts]
hold_to_talk_trailing_capture = false   # absent or true = on

[footprint]
report = false                          # absent or true = on
```

The webview publishes both, and `screen_context_share` (Connection & privacy's front-app switch; absent = on), as
`switches.json` in the state dir, beside `faces.json` and `panel-look.txt` (the `set_glyph_switches` command, booleans
only). The Admin's **Glyph** section shows them as the **Trailing capture**, **Footprint reporting** and **Front app to
the brain** rows, after the Panel look. Until a Glyph publishes, the rows say "on (Glyph default, nothing published
yet)".

## The conversation window as the Glyph's sidecar


The conversation window runs as the Glyph's sidecar process (ADR 0046), drawn in GPUI (`convo-gpui`). The freya window
(`convo-freya`) is frozen and stays the fallback.

- **Operations → Conversation window**: an on/off switch. On, the Glyph starts the window once it knows its session
  (`<window> --observe <[vulpine] url> --session <id> --sidecar --hidden-start`). The window observes this Glyph's
  session read only and follows it across reconnects. It quits with the Glyph.
- **Show / hide** slides the window in and out; its own ⌥⇧Space does the same. On the Halo, the level meter on the
  display's edge is a 44 px button that opens and closes the window.
- **Cards open in**: the conversation window (the default) or the corner card, saved as `[conversation_window]
  cards`. **Open on a show** (on by default) reopens a closed window when a card arrives.
- **Crashes.** A window that exits unexpectedly starts again after 1 s, then after 4 s. A third crash in a row gives
  up, and the card says "Conversation window stopped" until Show / hide or the switch starts it again.
- **`vulpine-glyphctl doctor`** prints the window's health and a **signing** line. `matches` or `matches_shape` keeps
  the macOS privacy grants; `cdhash` (an ad-hoc build), `drifted` (another bundle id or team) and `local_identity` (a
  local certificate) say why macOS asks again. The release gate reads the same
  `bundle-identity.json`.
- The binary: `[conversation_window] path`, else `[conversation_window] binary` (a bare name), else `convo-gpui` and
  then `convo-freya`, each beside the Glyph binary and then in `~/.local/bin`; never PATH.
- What the window draws is fed through the sidecar envelope
  ([sidecar-envelope.v1](/docs/contracts/sidecar-envelope.v1), draft; `crates/sidecar_envelope`).


```toml
[conversation_window]
enabled = true                       # absent or false = off; the switch writes it
# binary = "convo-freya"             # optional: one window by name (default: convo-gpui, then convo-freya)
# path = "~/.local/bin/convo-gpui"   # optional: one window by path; the switch writes neither
# avatar = true                      # the Avatar portrait (Look → Portrait writes it); absent or false = off
# avatar_model = "~/Live2D/me/me.model3.json"  # the Live2D model it draws, or a .vrm; absent or "" = the built-in fox
# ascii_camera = true                # Look → Portrait → ASCII camera: the fox window opens on its Camera look
                                    #   (the camera starts only on its Start camera button; the welcome window's Camera row asks)
# avatar_hood = false                # Look → Portrait → Hood: absent or true = the avatar wears its hood
                                    #   (when its model has a hood parameter); false starts the window with --avatar-hood off
```

**Look → Portrait → Avatar** (Labs; off unless `avatar = true`) opens a fox window beside the conversation window on a
Live2D or VRM portrait, puppeted by avatar-puppet.v1. The Model field names a `.model3.json` or a `.vrm` on this Mac,
read in place. The portrait's mouth follows the played audio and the reply's words, and its face and gaze follow the
session's avatar actions.


## The orb drawn natively, the web page kept as an option

The overlay's Classic disc is drawn by `orb-gpui`, a native GPUI window one level over the overlay, placed on the
face's stage, with the mouse passing through to the face's button. It uses 27.7 MiB at rest and draws nothing while the
face is still; the WebKit orb measured 72 MiB.


- **Operations → Look → Orb drawing**: "Native (lighter)" (the default) or "Web page", saved as `[overlay_orb]
  drawn_by`.
- The page draws the disc whenever the native orb cannot: another look than the Classic disc, the binary not found, a
  failed start, three unexpected exits in a row, or "Web page" chosen.
- The binary: `[overlay_orb] path` when set, else `orb-gpui` beside the Glyph binary and then in `~/.local/bin`; never
  PATH. The orb never dials the gateway.

```toml
[overlay_orb]
drawn_by = "native"                # or "web"; absent = native; Look → Orb drawing writes it
# path = "~/.local/bin/orb-gpui"   # optional: one orb by path
```



## The right-click menu

The right-click menu opens at the pointer: Show / Hide conversation window, Settings…, Finish setup…, Check for
Updates…, Quit Glyph. It closes on Escape, on a press outside it (in another app too), on the hide shortcut, and when
the Glyph loses focus. **Show / Hide conversation window** is grayed, with the reason, when no window runs and a press
could not start one. The status pill is a toggle: its second click closes Operations.


## Panels on every body

A render frame from the brain or a tool (`pi_show_render`: a `card.v1` such as Forecast or Fleet status, or one of the
five chart kinds) draws as the panel kit's card in the body's panel place (`src/panels/GlyphPanels.tsx`, the chassis's
`renderCard` slot). The place belongs to the body, so every face gets it. Each body puts the card where it never covers
the status pill or the error toast:

| Body | Where the panel goes | Most room (pt, as of 2026-10-18) | Fit | Dismiss |
| --- | --- | --- | --- | --- |
| Classic (250 × 280, floating) | Over the disc, above the lip; the chip column stays over it | 234 wide, 176 tall | line | ×, Esc*, its ttl (held while the pointer is on it) |
| Island (560 × 520, top center) | A sheet below the island: under the capsule, its pill and its toast, centered | 420 wide; to 8 pt above the window's foot (about 435 tall at rest, 345 while it speaks) | full (brief while it speaks) | ×, Esc*, its ttl (held) |
| Halo (the display) | Lower right, over the toast and pill, clear of the summoned face and the dock | 400 wide; from 36 pt under the top to 140 pt over the pill | full | ×, Esc*, its ttl (held) |
| Familiar (the display) | Lower right, over the toast and pill; lower left while the familiar itself sits lower right | 400 wide; from 36 pt under the top to the toast | full | ×, Esc*, its ttl (held) |
| Ribbon (display width × 520, bottom edge) | Above the strip's right end, over the toast and pill | 400 wide; from 12 pt under the window's top to the toast | full | ×, Esc*, its ttl (held) |
| Printer (280 × 480, floating) | Under the case, across the window, over the oldest slips | 264 wide; from 104 pt down to the toast | brief | ×, Esc*, its ttl (held) |

- **Fit**: `full` is the card as sent, `brief` its header, headline and summary, `line` its header and summary. Every
  fit keeps the summary the reply says aloud. When the room shrinks (the Island while it speaks), the card steps down
  one fit before it paints, and back up when the room grows. A card is never cut off behind a hidden scroll.
- **Dismiss**: the ×, a click on the card, or the frame's ttl (five minutes when it sets none). Up to two older cards
  wait under the top one. Esc dismisses only where the page has the keys (the showcase, a browser): Vulpine.app never
  takes the keys from the app you work in.
- **The look**: Operations → Look → Panel look (Match theme, Graphite, Field kit, Porcelain) applies on every body.
  **Show a sample panel** draws the forecast with no gateway.


## Themes: Porcelain, Night glass, Tidewater and Brass

Four Glyph Themes ship in `apps/glyph/src/theme/themes/`: **Porcelain** (warm and light: bone, lacquer, one red
listening light, a still matte orb), **Night glass** (dark: violet with cyan and magenta, a holographic orb),
**Tidewater** and **Brass** (warm brass and cream on a near-black case, the look before the default became the Gateway
app's). Brass is built into the app (`src-tauri/src/theme.rs`), so it binds with no install. Every text pair in Porcelain,
Night glass and Tidewater meets WCAG AA.

```sh
just apps::glyph-themes-install --dry-run   # what it would copy, and where
just apps::glyph-themes-install             # into $XDG_CONFIG_HOME/glyph/themes (else .config/glyph/themes at home)
```

A file already there that differs is kept unless `--force`. Then **Operations → Look → Theme** lists them; picking
one binds it (as `vulpine-glyphctl theme porcelain` does), and **default** goes back. The chassis showcase takes
`?theme=porcelain` or `?theme=night-glass`.
