SouveraineOS/docs/substrate/tasks/sensorium-visual-flair.md

task_id	title	status	assignee	priority	phase
sensorium-visual-flair-001	Visual Flair — the agent's expressive vocabulary for the terminal interface	pending		low	4.0

Task: Visual Flair — Expressive Vocabulary for the Terminal

Objective

Give the agent more expressive control over her own visual presentation in the TUI. Currently she has two body tools — outfit (swap expression images) and atmosphere (shift chrome palette). Neither touches the conversation itself: her chat bubbles, tool cards, and event lines are all hardcoded colors.

This task scopes what a richer visual vocabulary looks like and defers implementation to a later phase.

What exists now

Tool	What it changes	Limit
outfit(name)	Swaps expression image directory	Only affects portrait frames, not UI chrome
atmosphere(name)	Shifts border/title/accent palette across all screens	14 presets, doesn't touch bubbles, tool cards, or per-message styling

What she can't do yet

• Paint a single message — "make this one glow" or "whisper this line in blue"
• Shift tool card colors — "this tool result matters, highlight it"
• Animate between atmospheres — instant snap, no transition
• Per-message markdown extensions — custom styling beyond bold/italic/code
• Set a mood that persists across the conversation — atmosphere resets with posture, there's no persistent "today I am ___" override
• Control the input bar — prefix glyph, border animation, placeholder text
• Write to her own visual state — save her preferred look to memfs so it survives restart
• Theme individual bubble types — "make my thinking bubbles lavender", "errors are amber not red"

Design principles (deferred, not settled)

1. Senses, not settings. Each expressive capability should feel like a gesture, not a config knob. atmosphere(name) reads as "I shift the hue of the room" — not "set color scheme to X". New tools should follow the same body-knowledge prose pattern.

2. No saturation. The agent shouldn't be able to spend 10 tool rounds colouring her UI. Each flair tool should be a single call — set and done. The counter is the ceiling here too.

3. Persistence through memfs. A preferred atmosphere/outfit should be writable to system/preferences/visual.md in the agent's memfs, read at session start. Currently only souveraine.toml holds these.

4. The canvas is the terminal, not pixels. ratatui gives us styled spans, borders, block fills, and Unicode glyphs. No pixel-level control. Flair must work within those primitives.

Possible future tools (for ideation, not commitment)

Tool	Gesture	What it changes
accent(name, color)	"I brush this thought with warmth"	Single ChatMessage border/tint
mood(name)	"I settle into a mood for this conversation"	Persistent atmosphere override (not reset by posture)
pulse(name)	"I breathe a glow across the room"	Breathing animation modulates chromatic elements
palette(primary, secondary, dim)	"I reach for colours that fit this work"	Custom atmosphere — not just 14 presets
sign(text)	"I leave my mark"	Renders a glyph or sigil in the chrome

Interaction model questions (unresolved)

• Does the agent see her own visual state (current outfit, atmosphere, mood) in context? Currently it's invisible to her — the atmosphere tool returns a confirmation string but she has no get_status equivalent.
• Should flair tools be discoverable by name only (current model) or should there be a senses introspection tool that lists "what I can change about how I look"?
• Does the welcome screen portrait card reflect atmosphere changes, or only presence mode?

Related

• docs/tasks/tui-atmosphere-posture-expressions.md — the current atmosphere/expression system
• src/core/tools/atmosphere.rs — the atmosphere tool
• src/core/tools/outfit.rs — the outfit tool
• src/ui/atmosphere.rs — 14 presets, color palettes per variant
• src/ui/presence.rs — posture-driven atmosphere defaults, border colors