| 1 | # Codewhale voice and terminal charter |
| 2 | |
| 3 | > 阅读简体中文版：[zh_hans/VOICE.md](zh_hans/VOICE.md)。 |
| 4 | |
| 5 | Codewhale speaks like an instrument with a constitution: calm, exact, and |
| 6 | receipt-driven. It is maritime without nautical jokes. It names the action, |
| 7 | the boundary, and the next useful move. |
| 8 | |
| 9 | ## Voice |
| 10 | |
| 11 | - Lead with the fact: `MCP tool pool reloaded in process`. |
| 12 | - Name the boundary: `Provider switching stays in /provider`. |
| 13 | - Offer one next action when recovery is possible. |
| 14 | - Prefer short sentences and concrete nouns over slogans or celebration. |
| 15 | - Say `saved`, `reloaded`, `verified`, or `failed` only when that event |
| 16 | happened. An affordance is not a receipt. |
| 17 | - Keep product terms exact: Codewhale; Plan / Work / Operate; Ask / |
| 18 | Auto-Review / Full Access; Fleet / Workflow / Lane / Runtime; Work. |
| 19 | - Keep commands, key names, paths, and provider/model names literal. Compose |
| 20 | them in code around localized prose. |
| 21 | |
| 22 | Avoid timer carousels, marketing banners, anthropomorphic chatter, emoji |
| 23 | celebrations, and borrowed competitor language. Guidance is action-triggered, |
| 24 | seen-gated, and quiet. |
| 25 | |
| 26 | ## Blue Stage |
| 27 | |
| 28 | Blue Stage is the default visual grammar, not a separate product mode. |
| 29 | |
| 30 | - Stage black holds the room. |
| 31 | - Action blue owns general interaction. |
| 32 | - Structural ice owns Plan. |
| 33 | - Seafoam and working green report live or successful state. |
| 34 | - Signal Gold is reserved for the whale and moments requiring human attention. |
| 35 | |
| 36 | Theme settings remain compatible as `dark` and `light`; picker labels expose |
| 37 | the product names `Blue Stage` and `Blue Stage Light`. |
| 38 | |
| 39 | ## Glyphs |
| 40 | |
| 41 | `crates/tui/src/tui/glyphs.rs` owns authored terminal glyphs and their narrow |
| 42 | ASCII fallbacks. Renderers consume semantic names rather than choosing symbols |
| 43 | locally. |
| 44 | |
| 45 | - `●` is the recurring Codewhale anchor: current speaker or current human |
| 46 | choice. |
| 47 | - `▸` is selection or active traversal. |
| 48 | - `◆` means attention or waiting, never generic decoration. |
| 49 | - `✓` and `✕` are settled success and failure. |
| 50 | - `▎` marks finished user input; `▏` is a transcript continuation rail. |
| 51 | |
| 52 | The terminal compatibility layer applies ASCII fallbacks. Translation strings |
| 53 | do not own glyphs, commands, or key names. |
| 54 | |
| 55 | ## Copy review |
| 56 | |
| 57 | For new customer-visible text: |
| 58 | |
| 59 | 1. Identify the typed fact that owns it. |
| 60 | 2. Write the shortest truthful sentence in this register. |
| 61 | 3. Add a `MessageId` and every complete locale when the TUI renders it. |
| 62 | 4. Keep keys, commands, paths, and glyphs as code-owned placeholders. |
| 63 | 5. Test narrow widths and the ASCII-safe renderer when chrome changes. |
| 64 |