docs/design/web-shell-skill-toggle-refresh.md
Skill toggle requests can emit two settings_changed events for one persisted
change. The daemon metadata added by #9051 gives both events the same mutation
id and reports whether live-session activation was applied, deferred, or
partial.
Web Shell currently keeps a session-less /workspace/skills snapshot for the
composer. Once loaded, that snapshot overrides the active session's
available_commands_update, so a disabled Skill can remain in autocomplete.
The generic workspace settings signal also drops the mutation metadata and
cannot de-duplicate the two events.
The daemon React SDK exposes the latest Skill toggle mutation separately from the generic settings version. Valid Skill toggle mutations do not increment the generic settings signal, and consecutive events with the same mutation id increment the Skill signal once. Events without valid mutation metadata retain the existing settings behavior.
With an active session, Web Shell treats available_commands_update as the
authoritative command and Skill snapshot. Without a session, it refreshes and
uses /workspace/skills. A deferred or partial activation also refreshes that
workspace snapshot and temporarily uses it for the affected active session; a
failed refresh is surfaced to the user.
/workspace/skills once.