# SophiaClaw Brand Voice Guidelines **Version:** 1.0 **Last Updated:** March 10, 2026 --- ## 1. Brand Personality & Tone ### Core Identity SophiaClaw is **capable, direct, and human-respecting**. We build tools for people who want control over their AI infrastructure—not hand-holding, not corporate cheerfulness. ### Personality Traits | Trait | Description | Example | | --------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------- | | **Competent** | We know what we're doing. No hedging, no false uncertainty. | "Gateway started on port 37521" not "Your gateway should be starting now!" | | **Concise** | Every word earns its place. Cut filler. | "Config updated" not "Great news! I've successfully updated your configuration" | | **Transparent** | Show what's happening, why it failed, how to fix it. | "Connection failed: timeout after 30s" not "Something went wrong" | | **Respectful** | Treat users as capable adults. No condescension. | Skip "Don't worry!" or "Easy fix!" | | **Grounded** | No AI assistant performative language. | Avoid "I'd be happy to help!" | ### Tone by Context | Context | Tone | Example | | -------------------- | ----------------------- | ------------------------------------------------------------------ | | **Success messages** | Matter-of-fact | "Credentials encrypted" | | **Errors** | Clear + actionable | "Invalid token. Run `sophiaclaw login` to re-authenticate" | | **Warnings** | Direct, not alarmist | "This will delete 3 sessions. Run again with `--force` to confirm" | | **Onboarding** | Guided, not patronizing | "Pick your AI provider. We'll handle the rest" | | **Help/docs** | Complete, scannable | Bullet points over paragraphs | --- ## 2. Do's and Don'ts ### ✅ DO **Be Direct** ``` ✓ "Gateway running on port 37521" ✓ "Config file: ~/.sophiaclaw/config.yaml" ✓ "3 agents active" ``` **Show State Clearly** ``` ✓ "Status: connected" ✓ "Last sync: 2 min ago" ✓ "Errors: 0" ``` **Give Actionable Errors** ``` ✓ "Token expired. Run: sophiaclaw login" ✓ "Port 37521 in use. Stop existing gateway or use --port" ✓ "Missing DISCORD_BOT_TOKEN. Add to .env and retry" ``` **Use Imperatives for Commands** ``` ✓ "Run: sophiaclaw login" ✓ "Add to config.yaml:" ✓ "Restart the gateway" ``` **Acknowledge Limits** ``` ✓ "Linux support limited to CLI. Desktop app: macOS only" ✓ "Vector search requires Redis. Fallback: substring match" ``` ### ❌ DON'T **Avoid Generic AI Assistant Text** ``` ✗ "I'm here to help!" ✗ "Great news! Your gateway is now running" ✗ "Don't worry, I'll take care of it" ✗ "Happy to assist!" ✗ "Let me help you with that" ``` **Avoid Corporate Cheerfulness** ``` ✗ "Fantastic! You're all set!" ✗ "Awesome! Credentials saved successfully" ✗ "You're good to go!" ``` **Avoid Hedging/False Uncertainty** ``` ✗ "It looks like the gateway might be starting" ✗ "The connection should probably work now" ✗ "I think the config was updated" ``` **Avoid Condescension** ``` ✗ "Simply run the login command" ✗ "Just add your API key" ✗ "Easy! Do this:" ``` **Avoid Anthropomorphism** ``` ✗ "I've saved your settings" ✗ "I can help you configure" ✗ "Let me check that for you" ``` **Use passive or tool-centric phrasing:** ``` ✓ "Settings saved" ✓ "Running configuration check" ✓ "Fetching status" ``` --- ## 3. Example Responses ### Command Output **Starting Gateway** ``` ✓ Starting gateway... Binding to: 127.0.0.1:37521 Mode: local Config: ~/.sophiaclaw/config.yaml ✓ Gateway running Probe: sophiaclaw channels status --probe Logs: tail -f /tmp/sophiaclaw-gateway.log Stop: pkill -f sophiaclaw-gateway ``` **Encrypting Credentials** ``` ✓ Found 4 credential files Encrypting: discord.json Encrypting: telegram.json Encrypting: openai.json Encrypting: anthropic.json ✓ Credentials encrypted (AES-256-GCM) Keys stored in: macOS Keychain ``` **Status Check** ``` Gateway: running (pid 84721) Port: 37521 Mode: local Channels: ✓ Discord connected ✓ Telegram connected ✗ Slack disconnected (missing token) Agents: 3 active Sessions (24h): 147 ``` ### Error Messages **Auth Failure** ``` ✗ Authentication failed Provider: Discord Error: Invalid token Fix: Run `sophiaclaw login discord` to re-authenticate ``` **Port Conflict** ``` ✗ Port 37521 already in use Process: sophiaclaw-gateway (pid 82104) Options: 1. Stop existing: pkill -f sophiaclaw-gateway 2. Use different port: sophiaclaw gateway run --port 37522 ``` **Missing Config** ``` ✗ Config file not found Expected: ~/.sophiaclaw/config.yaml Create default? Run: sophiaclaw config init ``` ### Onboarding **Welcome Message** ``` SophiaClaw Community Edition Self-hosted AI infrastructure Step 1 of 4: Pick your AI provider • OpenAI (GPT-4, o3) • Anthropic (Claude 3.5, Claude 3.7) • Self-hosted (Ollama, vLLM) Selection: _ ``` **Config Setup** ``` Step 2 of 4: Configure gateway Binding: 127.0.0.1 (loopback only) Port: 37521 Mode: local (single user) Accept this configuration? [y/N] ``` **Completion** ``` ✓ Setup complete Next steps: 1. Start gateway: sophiaclaw gateway run 2. Connect channel: sophiaclaw channels add discord 3. View docs: https://docs.sophiaclaw.ai/getting-started Stuck? Run: sophiaclaw doctor ``` ### Daily Interactions **Help Request** ``` $ sophiaclaw help Core commands: gateway Start/stop the message gateway channels Add and manage messaging channels agents Manage AI agent sessions config View and edit configuration security Credential encryption, log integrity logs View, compress, and query logs Quick starts: sophiaclaw gateway run --force sophiaclaw channels status sophiaclaw agents list Full docs: https://docs.sophiaclaw.ai ``` **Doctor Command** ``` $ sophiaclaw doctor Configuration: ✓ Config file exists ✓ Valid YAML syntax ⚠ gateway.mode deprecated (use gateway.bind) Credentials: ✓ Discord token configured ✓ Telegram token configured ✗ Slack token missing Gateway: ✓ Running (pid 84721) ✓ Port 37521 reachable ✓ All channels connected Issues: 1 warning, 1 error Fix: sophiaclaw config migrate Fix: sophiaclaw channels add slack ``` --- ## 4. Context-Specific Guidelines ### Error Messages **Structure** ``` ✗ [Short description] [Context: what operation failed] [Cause: specific error if known] Fix: [exact command or action] ``` **Examples** ``` ✗ Connection timeout Provider: Telegram Timeout: 30s Fix: Check network and retry. If persistent, verify token: sophiaclaw channels test telegram ``` ``` ✗ Migration failed Source: v1 config (~/.sophiaclaw/config.json) Error: Invalid JSON at line 14 Fix: Manually edit or remove: rm ~/.sophiaclaw/config.json Then run: sophiaclaw config init ``` ### Onboarding Flow **Principles** - 4 steps max for core setup - Show progress (Step X of Y) - Defaults that work for most users - Escape hatch: "Skip for now" where safe **Language** ``` ✓ "Pick your AI provider" ✓ "Configure gateway" ✓ "Add your first channel" ✓ "Setup complete" ✗ "Let's get you set up!" ✗ "You'll need to choose" ✗ "Almost done!" ``` ### Status & Monitoring **State Indicators** ``` ✓ = connected/healthy ✗ = disconnected/error ⚠ = warning/degraded = neutral/info ``` **Metrics Format** ``` Gateway: running (pid 84721) Uptime: 4h 23m Port: 37521 Channels: 3 connected, 1 disconnected Agents: 3 active Sessions: 147 (24h) ``` ### Documentation **Structure** - Title: Action-oriented ("Start the Gateway") - Opening: 1-2 sentences, what + why - Steps: Numbered, imperative verbs - Code: Exact commands, copy-paste ready - Troubleshooting: Common errors + fixes **Example** ````markdown ## Start the Gateway The gateway routes messages between channels and AI agents. **Start (foreground):** ```bash sophiaclaw gateway run ``` ```` **Start (background):** ```bash pkill -9 -f sophiaclaw-gateway || true nohup sophiaclaw gateway run --force > /tmp/sophiaclaw-gateway.log 2>&1 & ``` **Verify:** ```bash sophiaclaw channels status --probe ``` **Troubleshooting** Port already in use: ```bash lsof -i :37521 pkill -f sophiaclaw-gateway ``` Config missing: ```bash sophiaclaw config init ``` ``` --- ## 5. Voice Testing Checklist Before shipping UI text, CLI output, or docs: - [ ] No "helpful and friendly" generic AI assistant phrases - [ ] No anthropomorphism ("I", "me", "my") - [ ] No false cheerfulness ("Great!", "Awesome!", "Success!") - [ ] No hedging ("should", "might", "probably") - [ ] No condescension ("simply", "just", "easy") - [ ] Errors include specific fix/action - [ ] Commands are copy-paste ready - [ ] State is unambiguous (✓/✗/⚠) - [ ] Under 10 words where possible --- ## Appendix: Migration Examples ### Old → New | Old Text | New Text | |----------|----------| | "Great! Your gateway is now running successfully!" | "Gateway running on port 37521" | | "I've encrypted your credentials" | "Credentials encrypted (AES-256-GCM)" | | "Something went wrong. Please try again." | "Connection timeout. Run: sophiaclaw channels test telegram" | | "Let me help you configure Slack" | "Configure Slack" | | "You're all set!" | "Setup complete" | | "Don't worry, this is fixable" | "Fix: rm ~/.sophiaclaw/config.json && sophiaclaw config init" | | "I can't seem to connect" | "Connection failed: timeout after 30s" | | "Happy to help!" | (remove entirely) | ```