docs(plugin): explain which Claude Code surfaces show full council scenes vs compact council status

[JeremyDev87]

Background

This feature spans multiple Claude Code surfaces, and it is easy for future contributors to wire the wrong behavior into the wrong place. SessionStart, first-response output, live spinner cues, and the status bar all have different jobs.

Goal

Document the intended surface model for the request-driven Tiny Actor / council UX.

Scope

In scope:

• developer-facing docs/comments for plugin surfaces
• clarifying which surfaces show full scenes vs compact cues vs stable snapshots

Out of scope:

• end-user marketing copy

Desired model

• SessionStart: greeting/setup only, not the main council surface
• UserPromptSubmit / first response: opening council scene contract
• PreToolUse: compact live council cue
• PostToolUse: state transition update path
• status bar: compact persistent snapshot

Acceptance criteria

• the surface responsibilities are written down clearly enough to guide future implementation
• docs/comments reduce the chance of drifting back to a startup-only preview design

Suggested implementation plan

1. Add developer-facing documentation near the relevant plugin modules or docs.
2. Reference the intended role of each surface.
3. Keep the docs implementation-oriented rather than marketing-oriented.

Related

• parent issue for request-driven Tiny Actor council UX