focuses/

A focus is a named scoping of the chat surface — a subset of realms whose skills the chat LLM can see, plus an optional persona override. The point is routing reliability: a 30-skill world gives even a sharp realm skill room to lose to a competitor; strip the competitors out and the LLM has nothing to confuse the right skill with.

focuses/movies.yml

name: movies
displayName: Movies
description: "Recommend, rate, and recall films"
icon: "🎬"
defaultPersona: roger
realms: [movie]
builtins: true

Field	Required	Description
name	Yes	Stable slug — used by the /focus <name> slash command, the picker, and persistence.
displayName	No	Human label for the picker. Falls back to name.
description	No	One-line summary for the picker tooltip / chat badge.
icon	No	Emoji or single character for the picker.
defaultPersona	No	Persona slug to activate when a session enters this focus. Resolved against the same registry that personalities/ populates — world-authored or realm-shipped. Null = keep the world’s current persona.
realms	No	Realm names whose skills stay visible in this focus. Empty = no realm skills, only built-ins.
tools	No	By-name allowlist of additional tools/skills to pull into this focus regardless of realm membership. Additive with realms.
builtins	No (default true)	Which host-provided chat tools the focus keeps: true all, false none, or a list of categories as for an agent’s conversation.builtins ([memory, views]). Name the fewest the focus needs — the reason a focus exists is that fewer tools route better, and that holds for the host’s tools as much as for realm skills.
skills	No	Skills brought in by name, beside what realms and builtins bring — exactly as an agent’s conversation.skills: never a realm’s skill without its realm (refused), never a tool, and an unknown name is a validation error. Each one is another choice the model weighs on every turn, so add it with cause (Scope it to the job).

/focus slash command

The host’s /focus <name> slash command binds the user’s chat session to a focus. /focus off clears the binding; bare /focus lists available focuses. Binding takes effect from the next chat turn; the conversation transcript stays under whatever scope was in force when each message was sent.

When a focus declares defaultPersona, the host swaps both the persona’s Jinja includes (the voice the LLM speaks in) and the persona’s identity.yml#name (the display name the LLM introduces itself as, and the label on the chat bubble) for the focused session. Toggle focus off and the world’s default persona returns. The change is in-session — the world-level activePersonality is not rewritten.

Discovery and precedence

World-authored focuses live at config/focuses/<name>.yml; realm-shipped focuses live at <realm-dir>/focuses/<name>.yml. On slug collision, the world entry wins (user-authored overrides realm-shipped). Realm focuses carry an internal source = realm marker for UI disambiguation.

---