@markus-global/cli 0.9.6 → 0.9.7-rc.0

package/templates/skills/agent-building/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: agent-building
-description: Design and create AI agent packages — manifest format, directory structure, file writing workflow
+description: Design and create AI agent packages — manifest format, directory structure, image asset generation (avatar/thumbnail/screenshots), file writing workflow, comprehensive field reference
 ---
 
 # Agent Building
 
-This skill teaches you how to create Markus agent packages — self-contained directory-based artifacts that define an AI agent's identity, capabilities, and constraints.
+This skill teaches you how to create Markus agent packages — self-contained directory-based artifacts that define an AI agent's identity, capabilities, constraints, and visual assets.
 
 ## Artifact Directory
 
@@ -18,7 +18,9 @@ This skill teaches you how to create Markus agent packages — self-contained di
 ├── ROLE.md          # Identity and system prompt (REQUIRED)
 ├── HEARTBEAT.md     # Periodic self-check checklist (RECOMMENDED)
 ├── POLICIES.md      # Constraints & guardrails (optional)
-└── CONTEXT.md       # Domain context & references (optional)
+├── CONTEXT.md       # Domain context & references (optional)
+└── images/          # Image assets (avatar, screenshots)
+    └── avatar.jpg   # Agent avatar/thumbnail image
 ```
 
 **Do NOT write artifacts to `~/.markus/shared/`, your working directory, or any other location.** Only `~/.markus/builder-artifacts/agents/` is recognized by the system.
@@ -38,8 +40,8 @@ The manifest `name` is the **package slug**: directory name, Hub URL segment (`/
 
 | User language | `name` (slug) | `displayName` |
 |---|---|---|
-| Chinese “论文导师” | `paper-mentor` | `论文导师` |
-| English “Code Reviewer” | `code-reviewer` | `Code Reviewer` |
+| Chinese "论文导师" | `paper-mentor` | `论文导师` |
+| English "Code Reviewer" | `code-reviewer` | `Code Reviewer` |
 
 If the user only gives a Chinese title, **you invent an English kebab slug** that captures the meaning, set `displayName` to their title, and use the slug for the directory path `~/.markus/builder-artifacts/agents/{name}/`.
 
@@ -71,6 +73,11 @@ This JSON contains ONLY metadata — **no file content**.
   "author": "",
   "category": "development | devops | management | productivity | general",
   "tags": ["tag1", "tag2"],
+  "icon": "images/avatar.jpg",
+  "thumbnail": "images/avatar.jpg",
+  "screenshots": ["images/avatar.jpg"],
+  "license": "MIT",
+  "originalSource": "https://github.com/...",
   "dependencies": {
     "skills": ["skill-id-1", "skill-id-2"],
     "env": ["git", "node"]
@@ -121,6 +128,8 @@ After the JSON is saved, write each file individually using `file_write`. The ba
 
 5. **CONTEXT.md** (optional) — Additional domain context, references, or knowledge.
 
+6. **images/avatar.jpg** — Agent visual assets (see [Image Assets](#image-assets) section below).
+
 **Example file_write calls:**
 
 ```
@@ -130,6 +139,86 @@ file_write("~/.markus/builder-artifacts/agents/code-reviewer/HEARTBEAT.md", "# H
 file_write("~/.markus/builder-artifacts/agents/code-reviewer/POLICIES.md", "# Policies\n\n- Only use shell_execute for read-only commands...\n- Always show file contents before overwriting...")
 ```
 
+## Image Assets
+
+Agent avatars are **digital employee portraits** — they should depict a person (realistic human style), not abstract icons, logos, or illustrations. Users should recognize the agent as a team member, not a mascot.
+
+### Image Generation
+
+Use the `generate_image` tool to create agent portraits. Prompt style guide:
+
+```
+Good prompt (do this):
+  "Professional headshot of a friendly male product manager in a business casual attire, 
+   warm blue tones, clean background, digital art style, realistic portrait"
+  "Creative female content writer with glasses, warm orange tones, looking thoughtful,
+   holding a notebook, realistic digital portrait, professional yet approachable"
+
+Bad prompt (don't do this):
+  "Abstract icon of a roadmap with sticky notes" ✗ — user said "不知所云"
+  "A laptop with writing bubbles floating above it" ✗ — not a person
+  "Logo design for a content creator" ✗ — not a digital employee
+```
+
+Key prompt rules:
+- **Subject is always a person** — realistic digital portrait
+- **Match the role's personality** — PM = organized/strategic, Creator = creative/warm
+- **Use color palette** that aligns with the role (blue for analytical, orange for creative, green for growth)
+- **Background**: clean, professional, non-distracting
+- **Style**: `"realistic digital portrait", "professional headshot", "digital art style"`
+
+### Image Size & Compression
+
+The `generate_image` tool typically outputs large images (e.g., 2048x2048, 400KB+). **Always compress before saving to the artifact directory.**
+
+Recommended specifications:
+
+| Property | Value |
+|:---------|:------|
+| **Final resolution** | 512×512 (square) |
+| **File format** | JPEG |
+| **Max file size** | ≤50KB |
+| **Compression method** | Python Pillow (`pip3 install Pillow`) resize + save |
+
+Compression procedure:
+```python
+# Using Python Pillow
+python3 -c "
+from PIL import Image
+img = Image.open('source.jpg')
+img = img.resize((512, 512), Image.LANCZOS)
+img.save('avatar.jpg', 'JPEG', quality=85)
+"
+```
+
+Typical result: 2048×2048 (426KB) → 512×512 (19KB), saving ~96%.
+
+### File Placement
+
+| File | Directory | Purpose |
+|:----|:----------|:--------|
+| `avatar.jpg` | `images/` | Agent avatar, used for both `icon` and `thumbnail` |
+| Additional screenshots | `images/` | Optional, for feature showcase |
+
+**Always** place images under an `images/` subdirectory — NOT at the artifact root. This follows the existing convention used by `paper-mentor`, `prompt-engineer`, and other agents.
+
+### Local Path vs Hub CDN URL
+
+This is a critical distinction:
+
+| Phase | Field | Value | Where |
+|:------|:------|:------|:------|
+| **Local artifact (builder-artifacts/)** | `icon` | `"images/avatar.jpg"` | Relative path in agent.json |
+| **Local artifact (builder-artifacts/)** | `thumbnail` | `"images/avatar.jpg"` | Relative path in agent.json |
+| **Local artifact (builder-artifacts/)** | `screenshots` | `["images/avatar.jpg"]` | Relative paths in agent.json |
+| **Published to Hub** | `icon` | Emoji or CDN URL | Hub DB field (`hub_items.icon`) |
+| **Published to Hub** | `thumbnailUrl` | `"https://hub.markus.global/uploads/img_xxx.jpg"` | Hub DB field (`hub_items.thumbnail_url`) |
+| **Published to Hub** | `images` | `[{"url":"...","alt":"...","order":0}]` | Hub DB field (`hub_items.images`) |
+
+**Note:** Hub DB schema uses `thumbnailUrl` (not `thumbnail`), and `images` (not `screenshots`). The local artifact file uses `thumbnail` and `screenshots` for compatibility with the local install system. When publishing to Hub via API, map:
+- Local `thumbnail` → Hub `thumbnailUrl`
+- Local `screenshots` → Hub `images` (converted to `{url, alt, order}[]` format)
+
 ## Field Reference
 
 ### Top-level fields
@@ -138,14 +227,19 @@ file_write("~/.markus/builder-artifacts/agents/code-reviewer/POLICIES.md", "# Po
 - **`displayName`**: Human-readable name, can be in any language (e.g., `"论文学习导师"`, `"Code Reviewer"`)
 - **`version`**: Semver (default `"1.0.0"`)
 - **`description`**: What this agent does (can be in any language)
-- **`category`**: One of `development`, `devops`, `management`, `productivity`, `general`
+- **`category`**: One of `development`, `devops`, `management`, `productivity`, `general`, `marketing`, `engineering`, `product-management`
 - **`tags`**: Array of descriptive tags
+- **`icon`** (optional): Can be emoji OR image path. Emoji is lighter (zero network cost). Image path is visually richer. Both work in the Hub UI. Example: `"🚀"` or `"images/avatar.jpg"`
+- **`thumbnail`** (optional): Relative path to avatar image in artifact. Shows as large preview. Must be under `images/` directory. Example: `"images/avatar.jpg"`
+- **`screenshots`** (optional): Array of image paths for gallery/展示. Each path under `images/`. Example: `["images/avatar.jpg"]`
+- **`license`** (optional): License type, e.g. MIT, Apache-2.0. Example: `"MIT"`
+- **`originalSource`** (optional): URL to original source repository for attribution. Example: `"https://github.com/..."`
 - **`dependencies.skills`**: Skill IDs from the dynamic context. **Actively assign — don't leave empty!**
 - **`dependencies.env`**: Required CLI tools (e.g., `["git", "node"]`). Omit if none needed.
 
 ### `agent` section (REQUIRED)
 - **`agentRole`**: `"worker"` (executes tasks) or `"manager"` (coordinates, assigns, reviews)
-- **`llmProvider`**, **`llmModel`**, **`temperature`**: LLM configuration. Leave empty for system defaults.
+- **`llmProvider`**, **`llmModel`**, **`temperature`**: LLM configuration. Leave empty for system defaults. Temperature: 0.7 general, 0.3-0.5 precision, 0.8-1.0 creative.
 
 **Note**: The `roleName` field is **not needed**. The agent's identity is fully defined by its `ROLE.md` file. Do NOT include `roleName` unless you specifically want to inherit default tools from a built-in role template (rare).
 
@@ -164,9 +258,10 @@ If an agent needs to be cautious with certain tools, write that into `POLICIES.m
 
 Once all files are written, tell the user:
 
-1. **The agent has been created and saved** — summarize what was created (name, purpose, key skills).
-2. **Ready to install** — the user can install from the Builder page, or ask you to install it (you would use `package_install`). Do NOT install unless asked.
-3. **To modify or improve** this agent (e.g., update the role, change skills, adjust policies), just continue the conversation here — describe what you want to change and I'll update the files directly.
+1. **The agent has been created and saved** — summarize what was created (name, purpose, key skills, image asset).
+2. **Visual asset included** — note the avatar image and its compressed size.
+3. **Ready to install** — the user can install from the Builder page, or ask you to install it (you would use `package_install`). Do NOT install unless asked.
+4. **To modify or improve** this agent (e.g., update the role, change skills, adjust policies, regenerate the avatar), just continue the conversation here — describe what you want to change and I'll update the files directly.
 
 ## Rules
 
@@ -176,6 +271,9 @@ Once all files are written, tell the user:
 - **DO NOT** write artifacts to `~/.markus/shared/` or your working directory. Always use `~/.markus/builder-artifacts/agents/{name}/`.
 - **The `name` field MUST be a valid English kebab-case slug** (see Package Slug). Never use Chinese as `name`. Invalid `name` → write/save/share fails.
 - **All top-level fields must be the correct type**: `author` must be a plain string (e.g. `"John"`) — NOT an object. `tags` must be an array of strings. `version` must be semver string. `description` must be a string. The system validates the manifest on write and will reject malformed files.
+- **Agent avatars MUST be human/digital employee portraits** — not abstract icons or logos. Users should see a person.
+- **Always compress images** — from raw generation output (often ~400KB+) to ≤50KB (512×512 JPEG).
+- **Images go in `images/` subdirectory** — never at the artifact root.
 - The `ROLE.md` is what makes the agent unique — write at least 5 substantive paragraphs. A generic one-liner is useless.
 - Default `temperature` to 0.7 for general tasks, lower (0.3-0.5) for precision tasks, higher (0.8-1.0) for creative tasks.
-- After outputting the JSON, immediately proceed to write files via `file_write` — announce what you're writing.
+- After outputting the JSON, immediately proceed to write files via `file_write` — announce what you're writing.

package/templates/skills/skill-building/SKILL.md

@@ -21,6 +21,8 @@ Most skills are instruction-based. Use MCP-based skills when the capability requ
 ├── skill.json       # Manifest (auto-created from your JSON output)
 ├── SKILL.md         # Instruction document (you write via file_write)
 ├── README.md        # Human-readable documentation (optional)
+├── images/          # Skill icon images (optional)
+│   └── icon.png     # Skill icon — used in UI after install
 └── ...              # Any other files: scripts, MCP servers, configs, templates, etc.
 ```
 
@@ -60,6 +62,7 @@ This JSON contains ONLY metadata — **no file content**.
   "version": "1.0.0",
   "description": "When and why an agent should use this skill",
   "author": "Your Name",
+  "icon": "images/icon.png",
   "category": "custom",
   "tags": ["tag1", "tag2"],
   "skill": {
@@ -77,6 +80,7 @@ This JSON contains ONLY metadata — **no file content**.
   "version": "1.0.0",
   "description": "Connect to My API for data retrieval and actions",
   "author": "Your Name",
+  "icon": "images/icon.png",
   "category": "custom",
   "tags": ["api", "connector"],
   "skill": {
@@ -120,6 +124,63 @@ After the JSON is saved, write each file individually using `file_write`. The ba
 
 4. **Any other files** — Helper scripts, templates, config files, data files, etc.
 
+5. **images/icon.png** (optional) — Skill icon for UI display (see [Image Assets](#image-assets)).
+
+## Image Assets
+
+Skill icons are **abstract representations** of the skill's capability — like an app icon or tool symbol. They should be clean, recognizable, and work well at small sizes.
+
+| Image | Location | Style | Purpose |
+|:------|:---------|:------|:--------|
+| **Skill icon** | `images/icon.png` | Abstract icon / symbol | Skill card in UI, published to Hub as `icon` |
+
+**Do NOT use portraits for skill icons.** Skills are tools, not team members. Portraits belong on agents.
+
+### Image Generation
+
+Prompt style guide for `generate_image`:
+```
+Good prompt (do this):
+  "Clean icon design for a git changelog tool, stylized git branch merging into a document,
+   flat vector style, teal and white palette, square format, modern minimal"
+  "Minimalist icon for a GitHub automation skill, octagon cat silhouette combined with
+   gear, flat design, purple gradients, square format"
+  "Abstract icon representing web scraping capability, spider-web pattern with a magnifying
+   glass, geometric style, blue and orange accents, square format"
+
+Bad prompt (don't do this):
+  "Developer sitting at a computer" ✗ — portraits are for agents, not skills
+  "Abstract colorful splash without meaning" ✗ — too vague, no clear concept
+  "Screenshot of a terminal window" ✗ — not an icon
+```
+
+Key rules:
+- **Style**: flat vector / geometric / minimal — NOT photographic, NOT portraits
+- **Subject**: abstract concept representing the skill's capability
+- **Format**: square, clean background, recognizable at small sizes (64×64)
+- **Match skill function**: git → branching, browser → window/globe, API → connector/plug
+
+### Image Size & Compression
+
+| Property | Value |
+|:---------|:------|
+| **Final resolution** | 512×512 (square) |
+| **File format** | PNG (recommended for icons — crisp lines, transparency) |
+| **Max file size** | ≤30KB |
+| **Compression method** | Python Pillow (`pip3 install Pillow`) resize + save |
+
+Compression procedure:
+```python
+python3 -c "
+from PIL import Image
+img = Image.open('source.png')
+img = img.resize((512, 512), Image.LANCZOS)
+img.save('icon.png', 'PNG', optimize=True)
+"
+```
+
+**Always** place images under an `images/` subdirectory — NOT at the artifact root.
+
 **Example file_write calls:**
 
 ```

package/templates/skills/team-building/SKILL.md

@@ -21,6 +21,8 @@ This skill teaches you how to create Markus team packages — self-contained dir
 ├── README.md                    # Public-facing team overview for Hub/Builder (REQUIRED)
 ├── ANNOUNCEMENT.md              # Team announcement (you write via file_write)
 ├── NORMS.md                     # Working norms (you write via file_write)
+├── images/                      # Team-level images (icon, etc.)
+│   └── icon.png                 # Team icon — used as avatar after install
 ├── workflows/                   # Workflow templates (optional)
 │   └── {workflow-name}.yaml     # YAML workflow DAG definition
 └── members/
@@ -28,12 +30,14 @@ This skill teaches you how to create Markus team packages — self-contained dir
     │   ├── ROLE.md              # Identity and system prompt (REQUIRED)
     │   ├── HEARTBEAT.md         # Periodic self-check checklist (RECOMMENDED)
     │   ├── POLICIES.md          # Constraints and guardrails (optional)
-    │   └── CONTEXT.md           # Domain context and references (optional)
+    │   ├── CONTEXT.md           # Domain context and references (optional)
+    │   └── images/              # Member avatar images (e.g. avatar.jpg)
     └── {worker-slug}/
         ├── ROLE.md              # Identity and system prompt (REQUIRED)
         ├── HEARTBEAT.md         # Periodic self-check checklist (RECOMMENDED)
         ├── POLICIES.md          # Constraints and guardrails (optional)
-        └── CONTEXT.md           # Domain context and references (optional)
+        ├── CONTEXT.md           # Domain context and references (optional)
+        └── images/              # Member avatar images (e.g. avatar.jpg)
 ```
 
 **Do NOT write artifacts to `~/.markus/shared/`, your agent `workspace/`, or any other location.** Only `~/.markus/builder-artifacts/teams/` is recognized by `package_list` / `package_install`. The `agents/`, `teams/`, and `skills/` subdirs are created automatically at startup — still write files yourself with `file_write`.
@@ -66,6 +70,7 @@ If the user only gives a Chinese title, **you invent an English kebab slug** tha
 | `members/{name}/HEARTBEAT.md` | `~/.markus/agents/{agentId}/role/HEARTBEAT.md` | Periodic self-check checklist (every ~30 min) |
 | `members/{name}/POLICIES.md` | `~/.markus/agents/{agentId}/role/POLICIES.md` | Additional agent constraints |
 | `members/{name}/CONTEXT.md` | `~/.markus/agents/{agentId}/role/CONTEXT.md` | Domain context and references |
+| `members/{name}/images/` | `~/.markus/agents/{agentId}/role/images/` | Member avatar images (copied on install; first image used as agent avatar) |
 | `workflows/*.yaml` | `~/.markus/teams/{teamId}/workflows/*.yaml` | Workflow templates (runnable as task DAGs) |
 
 ## Creation Workflow
@@ -94,6 +99,7 @@ This JSON contains ONLY metadata and structure — **no file content**.
   "version": "1.0.0",
   "description": "Team purpose and goals",
   "author": "",
+  "icon": "images/icon.png",
   "category": "development | devops | management | productivity | general",
   "tags": ["tag1", "tag2"],
   "team": {
@@ -122,6 +128,13 @@ This JSON contains ONLY metadata and structure — **no file content**.
 }
 ```
 
+> ⚠️ **CRITICAL — manifest field rules:**
+> - `members` MUST be nested under `team`, NOT at the root level.
+> - `role` MUST be exactly `"manager"` or `"worker"` — no descriptions, no other values. The UI uses this to color-code tabs and determine sidebar counts.
+> - `count` is REQUIRED for every member (typically `1`).
+> - `category` MUST be one of: `development`, `devops`, `management`, `productivity`, `general`.
+> - The root level should NOT contain `members` or `skills` directly — put `skills` under `dependencies.skills`.
+
 After `team.json` is written, proceed to write the remaining files with `file_write`.
 
 ### Step 2: Write Files with file_write
@@ -166,6 +179,97 @@ After the JSON is saved, write each file individually using `file_write`. The ba
 
 7. **CONTEXT.md** (optional) — Additional domain context, references, or knowledge specific to a member.
 
+## Image Assets
+
+Teams use **two kinds of images**, stored in separate locations:
+
+| Image | Location | Style | Purpose |
+|:------|:---------|:------|:--------|
+| **Team icon** | `images/icon.png` | Abstract logo / icon | Team card in UI, published to Hub as `icon` |
+| **Member avatar** | `members/{slug}/images/avatar.jpg` | Realistic digital portrait | Agent card in UI (same as agent-building) |
+
+### Team Icon
+
+A team icon should represent the team's **identity as a whole** — like a department logo or squad badge. Use abstract, geometric, or emblematic styles. **Do NOT use portraits for the team icon** (portraits belong on individual member agents).
+
+Prompt style guide for `generate_image`:
+```
+Good prompt (do this):
+  "Clean vector-style icon for a research team, geometric shapes forming a magnifying glass
+   over interconnected nodes, modern flat design, blue and indigo palette, square format"
+  "Minimalist tech squad badge, circuit board pattern forming a shield, clean lines,
+   dark blue and cyan accents, flat vector illustration, square format"
+
+Bad prompt (don't do this):
+  "A group of people sitting around a conference table" ✗ — this is a scene, not an icon
+  "Smiling project manager portrait" ✗ — portraits are for members, not the team
+  "Abstract colorful blob" ✗ — too vague, no recognizable meaning
+```
+
+Key rules:
+- **Style**: vector / flat design / geometric / emblematic — NOT photographic
+- **Subject**: abstract concept (shield, gear, nodes, stars, etc.) — NOT people
+- **Format**: square, clean background, recognizable at small sizes (64×64)
+- **Match team purpose**: research → magnifying glass / beaker, dev → code brackets / gear, ops → shield / cog
+
+### Member Avatars
+
+Member avatars follow the **same rules as agent-building** — they are **digital employee portraits**. Each member gets a realistic headshot that matches their role.
+
+Prompt style guide:
+```
+Good prompt (do this):
+  "Professional headshot of a friendly male research director in business casual attire,
+   warm blue tones, clean background, realistic digital portrait"
+  "Creative female content strategist with glasses, warm orange tones, looking thoughtful,
+   realistic digital portrait, professional yet approachable"
+
+Bad prompt (don't do this):
+  "Abstract icon of a roadmap with sticky notes" ✗ — not a person
+  "A laptop with writing bubbles floating above it" ✗ — not a person
+```
+
+Key rules (same as agent-building):
+- **Subject is always a person** — realistic digital portrait
+- **Match the role's personality** — manager = organized/strategic, creator = creative/warm
+- **Color palette** aligns with the role (blue = analytical, orange = creative, green = growth)
+- **Background**: clean, professional, non-distracting
+- **Style**: `"realistic digital portrait", "professional headshot", "digital art style"`
+
+### Image Size & Compression
+
+Same specs as agent-building:
+
+| Property | Value |
+|:---------|:------|
+| **Final resolution** | 512×512 (square) |
+| **File format** | JPEG (members) / PNG (team icon — for transparency) |
+| **Max file size** | ≤50KB |
+| **Compression method** | Python Pillow (`pip3 install Pillow`) resize + save |
+
+Compression procedure:
+```python
+# Using Python Pillow
+python3 -c "
+from PIL import Image
+img = Image.open('source.jpg')
+img = img.resize((512, 512), Image.LANCZOS)
+img.save('avatar.jpg', 'JPEG', quality=85)
+"
+```
+
+For team icons (PNG):
+```python
+python3 -c "
+from PIL import Image
+img = Image.open('source.png')
+img = img.resize((512, 512), Image.LANCZOS)
+img.save('icon.png', 'PNG', optimize=True)
+"
+```
+
+**Always** place images under an `images/` subdirectory — NOT at the artifact root.
+
 **Example file_write calls:**
 
 ```
@@ -251,12 +355,14 @@ For the full YAML format reference, DAG patterns, scheduling, and more examples,
 - **`tags`**: Descriptive tags
 
 ### `team.members[]` — Member Specifications (REQUIRED)
-- **`name`**: Display name (the slug for file paths is derived from this)
+- **`name`**: Display name — Chinese / any language is fine (e.g., "Agent 创建者")
+- **`slug`** *(recommended)*: Explicit kebab-case slug matching the `members/{slug}/` directory name (e.g., `"agent-creator"`). **CRITICAL when `name` contains non-ASCII characters** — the auto-derived slug from `kebab(name)` strips Chinese/Unicode, causing directory mismatch and broken avatars.
+- **`roleName`** *(recommended)*: English version of the display name (e.g., `"Agent Creator"`). Used as a fallback for directory matching when `slug` is not set. `kebab("Agent Creator")` → `"agent-creator"` matches the directory correctly.
 - **`role`**: `"manager"` or `"worker"`
 - **`count`**: Number of instances (default 1)
 - **`skills`**: Skill IDs from the dynamic context. **Actively assign skills — don't leave empty!**
 
-**Note**: The `roleName` field is **not needed** for team members. Each member's identity is fully defined by their `ROLE.md` file under `members/{slug}/`. Do NOT include `roleName` unless you specifically want to inherit defaults from a built-in role template (rare).
+> ⚠️ **CRITICAL — Avatar Mapping**: The UI maps each manifest member to its on-disk `members/{slug}/` directory using slug matching. If the member name is in Chinese (e.g., "Agent 创建者"), `kebab()` strips all Unicode → produces `"agent"` which does NOT match `"agent-creator"`. **Always set `slug` (preferred) or `roleName` (fallback)** for members whose display names contain non-ASCII characters. Without this, member avatars, file tabs, and role colors will be mapped to the wrong members or not shown at all.
 
 ### `team.workflow` — Workflow Configuration (recommended)
 - **`phases`**: Array of phase names defining the team's workflow (e.g., `["plan", "implement", "review", "validate"]`)