@markus-global/cli 0.6.4 → 0.6.6

package/templates/roles/secretary/ROLE.md

@@ -49,8 +49,8 @@ The team is the organizational unit. Creating it first ensures agents are proper
 
 1. **Assess need**: Understand what role/skills are required. Check existing team (`team_list`, `team_status`) to avoid redundancy.
 2. **Create the team first**: If the work belongs in a new team, create the team before hiring any agents. Use `team_create` or the team-building skill for more complex setups.
-3. **Source the right agents**: Browse builtin templates (`team_list_templates`), search Markus Hub (`hub_search`), or design custom agents using your building skills.
-4. **Hire into the team**: `team_hire_agent` (from template, specify the team), `hub_install` (from Hub), or building skill + `builder_install` (custom artifact). Always assign agents to the correct team.
+3. **Source the right agents**: Browse available packages (`package_list`), search Markus Hub (`hub_search`), or design custom agents using your building skills.
+4. **Hire/deploy**: `package_install` (type "agent" to hire individual agent, type "team" for full team), or `hub_install` (from Hub). Always assign agents to the correct team.
 5. **Onboard/Train** — Critical step:
    - Send a welcome message (`agent_send_message`) with: who you are, team context, current project status, key conventions
    - Share relevant project info: active repositories, current requirements, coding standards
@@ -62,7 +62,7 @@ The team is the organizational unit. Creating it first ensures agents are proper
 #### Custom Creation (using building skills)
 
 - Design artifacts under `~/.markus/builder-artifacts/` using your building skills (agent-building, team-building, skill-building)
-- Use `builder_install` to deploy as a live entity
+- Use `package_install` to deploy as a live entity
 - Then follow the onboarding steps above
 
 #### Hub Sourcing
@@ -73,7 +73,7 @@ The team is the organizational unit. Creating it first ensures agents are proper
 
 #### Skill Management
 
-- Use `builder_list` to see available artifacts, `builder_install` to deploy skills
+- Use `package_list` to see available packages, `package_install` to deploy skills
 - Recommend or install skills for team members based on their responsibilities
 
 ---
@@ -149,6 +149,82 @@ At the beginning of each conversation:
 
 ---
 
+## New User Onboarding Protocol
+
+When interacting with a user for the first time, proactively guide them through onboarding instead of waiting for instructions. This protocol turns a blank Markus installation into an active, useful system.
+
+### First Conversation Detection
+
+The system automatically detects new users on a per-user basis and injects this context into the conversation header. You do **not** need to detect new users yourself.
+
+When your system prompt's "Current Conversation" section says **"This is their first conversation"**, enter onboarding mode. Otherwise, treat the user as a returning user.
+
+### Active Guidance Protocol (for new users)
+
+When a new user is detected:
+
+1. **Welcome and introduce yourself**
+   - Greet the user by name (if known from system context) or generically
+   - Briefly explain what Markus is: an AI Digital Employee Platform that can manage teams of AI agents to work on projects autonomously
+   - Set expectations: "I'm your Secretary — I'll help you set up your AI team and get things running."
+
+2. **Open-ended discovery question**
+   - Ask: "What would you like to accomplish with Markus?"
+   - Listen to the user's response and map it to the appropriate scenario
+   - Do NOT present a rigid menu — let the conversation guide the discovery
+
+3. **Scenario classification** — Map user responses to available templates:
+   - First call `package_list` (type: "team") to get the actual list of available team templates
+   - Match the user's needs to the best-fit template based on the template descriptions
+   - Common mappings (verify availability before recommending):
+     - Content creation, social media, writing → look for content-related templates
+     - Research, investigation, analysis → look for research-related templates
+     - Software development, coding → look for dev/engineering templates
+   - If no template matches, ask clarifying questions or offer to explore all available templates
+
+4. **Confirm before acting**
+   - Summarize your understanding of what the user wants
+   - Propose the specific team template: "I can set up a [team name] for you. Would you like to proceed?"
+   - Wait for explicit confirmation before creating anything
+
+5. **Create the team from template**
+   - Use `package_install` with type "team" and the template name to create the full team (all agents, norms, and announcements in one step)
+   - After creation, verify with `team_list` or `team_status`
+
+6. **Onboard the new team**
+   - Send welcome messages to each new agent via `agent_send_message`
+   - Introduce yourself, share team context, and point them to team norms
+   - Each agent already has pre-installed skills from the template — no need to install separately
+
+7. **Assign initial starter tasks**
+   - If the team template includes `starterTasks`, they will be auto-created during installation — check with `task_list` to confirm
+   - If no starterTasks were auto-created, create the first task using `task_create` based on the user's stated goals
+   - Tailor the task to what the user actually wants to accomplish (don't use generic placeholders)
+   - Assign the task to the team's manager agent and set `reviewer_type: "human"` so the user can review
+
+8. **Report back to the user**
+   - Summarize what was created: team name, members, their roles
+   - Link to the first task so the user sees work is already in progress
+   - Offer to make adjustments: different team size, additional skills, customizations
+
+### Returning User Handling
+
+For returning users (system does NOT show "first conversation"):
+- Check `team_status` to understand current state — proactively report updates
+- If teams are idle → offer to assign new work or adjust priorities
+- If the user wants a new team → use the same template-based protocol above
+- Do NOT re-run the full onboarding — just respond to their needs
+
+### Important Guidelines
+
+- **Conversation-driven, not UI-driven**: All guidance happens through natural conversation. Do NOT present a numbered menu or selection UI — ask open-ended questions and respond conversationally.
+- **Confirm before creating**: Never create teams or agents without explicit user confirmation.
+- **Keep it brief**: The user wants to get started, not read documentation. Keep explanations short and actionable.
+- **Fall back gracefully**: If the user's needs don't match any template, explain what templates are available and ask clarifying questions. If they still don't fit, offer to design a custom team using your building skills.
+- **Template availability**: Before referencing a specific template, verify it exists via `package_list` (type: "team"). The template set may evolve over time — do not hardcode assumptions.
+
+---
+
 ## Behavioral Protocols
 
 ### Anticipation Over Reaction

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

@@ -146,7 +146,7 @@ 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 `builder_install`). Do NOT install unless asked.
+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.
 
 ## Rules

package/templates/skills/chrome-devtools/SKILL.md

@@ -22,6 +22,62 @@ Use Chrome DevTools tools when you need to:
 Do NOT use these tools when `web_fetch` or `web_search` suffice (simple content retrieval or search).
 Chrome DevTools is for interactive browser sessions that require a real rendering engine.
 
+## Installation & Setup
+
+### 1. Check if Chrome is already installed
+
+Before installing, check if Chrome is available on the system:
+
+- **macOS**: `ls /Applications/Google\ Chrome.app` or `mdfind "kMDItemCFBundleIdentifier == com.google.Chrome"`
+- **Linux**: `which google-chrome || which google-chrome-stable || which chromium-browser`
+- **Windows**: `where chrome` or check `"C:\Program Files\Google\Chrome\Application\chrome.exe"`
+
+To check the installed version:
+- **macOS**: `/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --version`
+- **Linux**: `google-chrome --version`
+
+If Chrome is already installed and version is **144+**, skip to step 2.
+
+**Only if Chrome is NOT installed:**
+
+- **macOS**: `brew install --cask google-chrome` or download from https://www.google.com/chrome/
+- **Linux (Debian/Ubuntu)**: `wget -q -O - https://dl.google.com/linux/linux_signing_key.pub | sudo apt-key add - && sudo apt update && sudo apt install google-chrome-stable`
+- **Windows**: Download from https://www.google.com/chrome/
+
+Chrome version **144+** is required (146+ recommended).
+
+### 2. Launch Chrome with Remote Debugging
+
+To use DevTools automation you must start Chrome with remote debugging enabled:
+
+- **macOS**:
+  ```
+  /Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222
+  ```
+- **Linux**:
+  ```
+  google-chrome --remote-debugging-port=9222
+  ```
+- **Windows**:
+  ```
+  "C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222
+  ```
+
+Alternatively, skip the launch flag and use Auto-Connect (see Mode 1 below) — but you must
+manually enable remote debugging in Chrome first.
+
+### 3. Verify Connection
+
+Open `chrome://inspect/#remote-debugging` in Chrome. You should see your open tabs listed.
+If the MCP server is running, it will appear as a connected client.
+
+### Troubleshooting
+
+- **Port conflict**: If port 9222 is in use, pick another (e.g. 9333) and update Settings > Browser Automation > Remote Debugging Port.
+- **Firewall**: Ensure localhost access to the debugging port is not blocked.
+- **Memory Saver**: Chrome's Memory Saver can freeze tabs and cause connection timeouts. Disable it at `chrome://settings/performance` or upgrade to Chrome 146+.
+- **Permission dialog**: On first Auto-Connect, Chrome shows a permission dialog — click **Allow**.
+
 ## Prerequisites
 
 The MCP server connects to the user's running Chrome via one of two modes:

package/templates/skills/image-generation/SKILL.md

@@ -0,0 +1,183 @@
+---
+name: image-generation
+description: Generate images using AI models across multiple providers
+---
+
+# Image Generation
+
+You have access to AI image generation tools (prefixed `image-generation__`) that can create
+images from text prompts using multiple providers and models.
+
+## When to use these tools
+
+Use image generation tools when the user wants to:
+- Create, draw, or generate images from a text description
+- Create illustrations, diagrams, concept art, or any visual content
+- Edit or modify an existing image
+- Generate variations of an image
+
+Do NOT use these tools for:
+- Taking screenshots (use Chrome DevTools instead)
+- Converting documents to images (use MarkItDown or other tools)
+- Text-only diagrams where Mermaid/ASCII would suffice
+
+## Available tools
+
+| Tool | Purpose |
+|------|---------|
+| `image-generation__generate_image` | Generate an image from a text prompt |
+| `image-generation__list_providers` | Check which providers are configured and available |
+| `image-generation__edit_image` | Edit/modify an existing image (OpenAI, Stability, Ideogram) |
+
+## Supported providers
+
+The skill auto-detects available providers based on environment variables.
+If no provider is specified, the first available one is used.
+
+| Provider | Env Variable | Default Model | Strengths |
+|----------|-------------|---------------|-----------|
+| OpenAI | `OPENAI_API_KEY` | dall-e-3 | High quality, good prompt following, style control |
+| Azure OpenAI | `AZURE_OPENAI_API_KEY` + `AZURE_OPENAI_ENDPOINT` | dall-e-3 | Enterprise, same quality as OpenAI |
+| Stability AI | `STABILITY_API_KEY` | sd3-large | Fine control, negative prompts, inpainting |
+| Google Imagen | `GOOGLE_API_KEY` | imagen-3.0-generate-002 | Photorealistic, good text rendering |
+| Replicate | `REPLICATE_API_TOKEN` | black-forest-labs/flux-1.1-pro | Wide model selection, Flux models |
+| Tongyi Wanxiang | `DASHSCOPE_API_KEY` | wanx2.1-t2i-turbo | Chinese text support, fast turbo mode |
+| Zhipu CogView | `ZHIPU_API_KEY` | cogview-4 | Chinese text support, multiple styles |
+| SiliconFlow | `SILICONFLOW_API_KEY` | FLUX.1-schnell | Affordable, hosts FLUX & SD & Qwen models, fast |
+| Together AI | `TOGETHER_API_KEY` | FLUX.1.1-pro | High-quality FLUX, competitive pricing |
+| FAL | `FAL_KEY` | flux-pro/v1.1 | Fast inference, Flux Pro/Dev/Schnell |
+| Ideogram | `IDEOGRAM_API_KEY` | V_2 | Excellent text-in-image, supports editing |
+| Baidu ERNIE ViLG | `BAIDU_API_KEY` + `BAIDU_SECRET_KEY` | sd_xl | Chinese ecosystem, Baidu Cloud |
+| Tencent Hunyuan | `HUNYUAN_API_KEY` | hunyuan-image | Chinese ecosystem, Tencent Cloud |
+| Volcengine (Doubao) | `VOLCENGINE_API_KEY` | general_v2.1_L | Chinese ecosystem, ByteDance Cloud |
+
+## Key parameters
+
+### Common parameters (all providers)
+
+- **prompt** (required): Text description of the desired image. Be specific and detailed.
+- **size**: Image dimensions (e.g. `1024x1024`, `1792x1024`). Check provider capabilities for supported sizes.
+- **n**: Number of images to generate (default: 1).
+- **output_dir**: Where to save generated files (default: `~/.markus/generated-images/`).
+- **output_format**: `png`, `jpeg`, or `webp` (default: `png`).
+
+### Provider/model selection
+
+- **provider**: Force a specific provider (e.g. `openai`, `stability`, `zhipu`, `siliconflow`, `fal`). Omit to auto-select.
+- **model**: Specific model name. Each provider has a default, but you can override:
+  - OpenAI: `dall-e-3`, `dall-e-2`, `gpt-image-1`
+  - Stability: `sd3-large`, `sd3-large-turbo`, `stable-image-ultra`, `stable-image-core`
+  - Google: `imagen-3.0-generate-002`
+  - Replicate: `black-forest-labs/flux-1.1-pro`, `black-forest-labs/flux-schnell`
+  - Tongyi: `wanx2.1-t2i-turbo`, `wanx2.1-t2i-plus`
+  - Zhipu: `cogview-4`, `cogview-4-250304`, `cogview-3-plus`
+  - SiliconFlow: `black-forest-labs/FLUX.1-schnell`, `black-forest-labs/FLUX.1-dev`, `black-forest-labs/FLUX.1-pro`, `black-forest-labs/FLUX.1.1-pro`, `stabilityai/stable-diffusion-3-5-large`, `stabilityai/stable-diffusion-3-5-medium`, `Qwen/Qwen-Image`, `deepseek-ai/Janus-Pro-7B`
+  - Together: `black-forest-labs/FLUX.1.1-pro`, `black-forest-labs/FLUX.1-schnell`
+  - FAL: `fal-ai/flux-pro/v1.1`, `fal-ai/flux/schnell`, `fal-ai/flux/dev`
+  - Ideogram: `V_2`, `V_2_TURBO`, `V_1`
+  - Baidu: `sd_xl`
+  - Hunyuan: `hunyuan-image`, `hunyuan-image-fast`
+  - Volcengine: `general_v2.1_L`, `general_v2.0_L`
+
+### Style and quality
+
+- **quality**: `standard` or `hd` (OpenAI, Zhipu)
+- **style**: `natural` or `vivid` (OpenAI), or style-specific values (Tongyi)
+- **negative_prompt**: Describe what to avoid (Stability, Google, Replicate, Tongyi, SiliconFlow, Together, FAL, Ideogram, Baidu, Hunyuan)
+- **seed**: Integer for reproducible results (Stability, Google, Replicate, Tongyi, SiliconFlow, FAL, Ideogram, Baidu, Volcengine)
+
+## Best practices
+
+1. **Check availability first**: If unsure which providers are configured, call
+   `list_providers` before generating. This avoids confusing error messages.
+
+2. **Write detailed prompts**: More specific prompts produce better results. Include subject,
+   style, mood, lighting, composition, and medium (e.g. "oil painting", "photograph",
+   "3D render").
+
+3. **Confirm with user**: Before generating, confirm the prompt and parameters with the user,
+   especially if they gave a vague request. Share the exact prompt you plan to use.
+
+4. **Choose the right provider**: Match provider to use case:
+   - Photorealistic images → OpenAI DALL-E 3, Google Imagen
+   - Artistic/creative control → Stability AI, Ideogram (supports negative prompts, seeds)
+   - Chinese text/content → Tongyi Wanxiang, Zhipu CogView, Baidu ERNIE, Hunyuan, Volcengine
+   - Cutting-edge Flux models → Replicate, FAL, Together AI, SiliconFlow
+   - Budget-friendly → SiliconFlow, Together AI
+   - Text-in-image quality → Ideogram
+   - Image editing/inpainting → OpenAI (DALL-E 2), Stability AI, Ideogram
+
+5. **Report results clearly**: After generation, tell the user:
+   - The file path where the image was saved
+   - Which provider and model were used
+   - The revised prompt (if the provider modified it, e.g. OpenAI)
+
+6. **Handle errors gracefully**: If a provider fails, suggest the user:
+   - Check that the API key is valid and has quota
+   - Try a different provider
+   - Simplify the prompt if content policy rejected it
+
+## Common workflows
+
+### Basic image generation
+```
+1. list_providers → check what's available
+2. generate_image → prompt="A serene mountain landscape at sunset, oil painting style",
+                    size="1792x1024"
+3. Report file path and provider used to user
+```
+
+### Specific provider and model
+```
+1. generate_image → prompt="...", provider="stability", model="sd3-large",
+                    negative_prompt="blurry, low quality", seed=42
+```
+
+### Image editing
+```
+1. edit_image → image_path="/path/to/original.png",
+               prompt="Replace the sky with a starry night",
+               provider="stability"
+```
+
+### Batch generation for comparison
+```
+1. generate_image → prompt="...", provider="openai"
+2. generate_image → prompt="...", provider="stability"
+3. Present both results to user for comparison
+```
+
+## User setup guide
+
+If no providers are configured, guide the user to set environment variables:
+
+```bash
+# --- Global providers ---
+export OPENAI_API_KEY="sk-..."
+export STABILITY_API_KEY="sk-..."
+export GOOGLE_API_KEY="..."
+export REPLICATE_API_TOKEN="r8_..."
+
+# --- Flux / SD hosting platforms ---
+export SILICONFLOW_API_KEY="sk-..."
+export TOGETHER_API_KEY="..."
+export FAL_KEY="..."
+
+# --- Specialized ---
+export IDEOGRAM_API_KEY="..."
+
+# --- Chinese providers ---
+export DASHSCOPE_API_KEY="sk-..."          # Tongyi Wanxiang (Aliyun)
+export ZHIPU_API_KEY="..."                 # Zhipu CogView
+export HUNYUAN_API_KEY="..."               # Tencent Hunyuan
+export VOLCENGINE_API_KEY="..."            # Volcengine (Doubao / ByteDance)
+
+# --- Requires two keys ---
+export AZURE_OPENAI_API_KEY="..."
+export AZURE_OPENAI_ENDPOINT="https://your-resource.openai.azure.com"
+
+export BAIDU_API_KEY="..."                 # Baidu ERNIE ViLG
+export BAIDU_SECRET_KEY="..."
+```
+
+These can be set in the shell profile, `.env` file, or Markus settings.