Workflow Mode

Every session has an optional workflow mode that drives two things:

1. Visual identification — a small purple dot next to the session name in the sidebar so designers and reviewers can spot design sessions at a glance.
2. System-prompt budget — 'code' mode drops the design preview docs (~600 tokens) from the system prompt every turn. Real cost reduction for sessions that don't need them.

Modes are intentionally soft: they're a hint, not a gate. The agent's tool catalogue is the same in every mode; the mode only affects the static doc sections shipped in the system prompt and the sidebar visual. You can flip back and forth without breaking anything.

The four states

Auto-detection

The first time the agent emits a site-preview or design-params block in a session, the server-side hook auto-flips the session to 'design'. One-way — never overrides an explicit user choice and never auto-flips back.

You can think of it as: "Hey, this session is doing design — let's make that visible."

Manual override

Right-click any session in the sidebar → Workflow mode → pick one:

• Design — purple dot, design docs included
• Code — no dot, design docs excluded
• Mixed — no dot, all docs included
• Auto-detect — clears the manual choice and resumes auto-detection

A coloured dot in the menu shows the current state. The selection takes effect immediately for the next turn — the active turn (if any) keeps its existing prompt to avoid mid-turn weirdness.

What "drops 600 tokens" actually means

When a session is 'code', the system prompt's ## Site Preview section is omitted. Concretely:

• Site preview block format docs (single + multi-item examples)
• Iteration affordances description (Alt+click, design-params slider example)
• Reference to ~/.fabric-agent/docs/site-preview.md

Total: ~600 tokens that the model would have read every turn but couldn't use anyway in a backend session. Multiplied across a long session — say 60 turns — that's 36,000 tokens of pure savings before any new content is added.

What stays in the prompt regardless of mode:

• The html-preview, pdf-preview, image-preview, mermaid, datatable, spreadsheet block docs
• All tool definitions (including publish_design, export_design)
• All other reference sections

When auto-detect won't fire

Auto-detect looks for the literal fenced-block markers ```site-preview or ```design-params in the assistant's text content. If you're using:

• Streaming partial output that gets cancelled before completion
• An external/proxy backend that strips fence info
• A custom agent that emits design intent without those specific markers

…auto-detect won't fire. Use the manual override.

Upstream-merge compatibility

Mode is an optional field on SessionHeader/SessionConfig. Sessions imported from upstream (or created by older versions) have no mode, and that's treated identically to 'mixed' — the system prompt is unchanged, the sidebar dot is absent, the agent behaves exactly as before. No migration required, no behaviour regressions.

If you're maintaining a fork that merges from upstream often, the mode field travels through SESSION_PERSISTENT_FIELDS automatically and won't conflict with new upstream additions in adjacent fields.

Operational notes

• Sessions written by the older app: opening them in the new app shows them as Mixed (no dot). They keep working untouched. To convert: right-click → Workflow mode → choose.
• Forks that don't merge this feature: sessions tagged 'design'/'code' in this app and shared with a fork without the feature simply ignore the unknown field.
• The system prompt is static + cacheable. We only invalidate the cache when mode changes (which is rare). So the token-budget win compounds with prompt-cache hits across the session.

See also

• Design Workflow — the loop that drives the auto-detect signal
• Site Preview Block — the block that triggers 'design' mode
• Sessions & Conversations — broader context on session metadata