@mutagent/cli 0.1.42 → 0.1.43

package/dist/bin/cli.js

@@ -7216,24 +7216,27 @@ description: |
 ---`;
 var SKILL_BODY = `# MutagenT CLI Skill
 
-## Quick Reference
-Run \`mutagent --help\` for full command list and examples.
-Run \`mutagent <command> --help\` for on-the-fly instructions before using any command.
+## First Things First
+Run \`mutagent --help\` — this is the CENTRAL navigation hub containing ALL commands, workflows, and rules.
+Run \`mutagent <command> --help\` BEFORE using ANY command for the first time.
 
-Key commands:
-- \`mutagent auth login\` — Authenticate
-- \`mutagent prompts list\` — List prompts
-- \`mutagent usage\` — Check plan limits and remaining optimization runs
-- \`mutagent explore\` — Discover prompts in codebase
-- \`mutagent integrate <framework>\` — Framework integration instructions
+## Agent Protocol (4 Rules)
+1. EVERY command MUST include \`--json\`
+2. Run \`<command> --help\` BEFORE first use
+3. **MANDATORY**: Parse \`_directive.renderedCard\` and copy it into your CHAT RESPONSE verbatim. The card appears in bash output but that is NOT sufficient — the user cannot read collapsed bash blocks. HARD STOP: do NOT run any further commands until the card text is rendered in your chat message.
+4. ALL user interaction via AskUserQuestion — CLI is non-interactive
 
-## Agent Usage Guidelines
+## Directive System
+Every JSON response may include:
+- \`_directive.renderedCard\` — Pre-formatted card that MUST be shown to the user verbatim
+- \`_directive.instruction\` — Next step for the agent
+- \`_directive.next\` — Array of suggested commands
+- \`_links\` — Dashboard/API URLs (format as markdown)
 
-- **ALWAYS** run \`mutagent prompts list --json\` and \`mutagent usage --json\` BEFORE creating or modifying resources
-- **ALWAYS** use the \`--json\` flag for machine-readable output
-- **ALWAYS** confirm with the user before write operations (create, update, delete, optimize)
-- **CHECK** \`mutagent usage\` before running \`optimize start\` to verify remaining optimization runs
-- Format dashboard links as markdown: \`[View on Dashboard](url)\`
+The agent MUST parse and act on directives. Cards in collapsed bash output are invisible to the user — always render them in chat.
+
+## Prompt Variables
+Use \`{single_braces}\`: \`"Analyze: {document}"\`
 
 ## Post-Onboarding Decision Tree
 
@@ -7259,58 +7262,56 @@ After \`mutagent auth login\`, the user lands in one of 3 paths:
 ### Path C: Manual
 User uses CLI commands directly. Run \`mutagent --help\`.
 
-## State Tracking
-- \`.mutagent/mutation-context.md\` — Local context file tracking all uploads
-- \`mutagent auth status\` — Shows onboarding completion + integration state
-- Comment markers (\`// MutagenT:START ... // MutagenT:END\`) in source files
+## Guided Evaluation Creation
+Use \`--guided --json\` when creating evaluations (NEVER \`--guided\` alone — it launches interactive prompts that agents can't use):
+\\\`\\\`\\\`
+mutagent prompts evaluation create <id> --guided --json
+\\\`\\\`\\\`
 
-## Wireframe Templates
+**When to use guided mode:**
+The optimizer requires each criterion to have \`name\`, \`description\` (scoring rubric), and \`evaluationParameter\` (a field from the prompt's inputSchema or outputSchema). If the user's existing evaluation format doesn't match this shape — e.g. they have generic rubrics without per-field targeting, or criteria that don't map 1:1 to schema fields — use \`--guided\` to:
+1. Fetch the prompt's inputSchema + outputSchema fields
+2. Show which fields need coverage
+3. Return a criteria template with the exact JSON shape
 
-### Active Operation Status Card
-\`\`\`
-┌─────────────────────────────────────────┐
-│ ⚡ MutagenT: Optimizing                │
-│ ─────────────────────────────────────── │
-│ Prompt:  "email-summarizer" (ID: 42)    │
-│ Dataset: "customer-emails" (150 items)  │
-│ Status:  Running — Iteration 3/10       │
-│ Score:   0.72 → 0.85 (+18%)            │
-│ ████████████░░░░░░░░ 60%               │
-│                                         │
-│ \uD83D\uDD17 View: https://app.mutagent.io/...   │
-└─────────────────────────────────────────┘
-\`\`\`
+**Validation rules the CLI enforces:**
+- Every criterion MUST have \`name\`, \`description\`, and \`evaluationParameter\`
+- \`evaluationParameter\` MUST match an actual schema field name
+- No duplicate \`evaluationParameter\` values — each criterion targets a unique field
+- ALL schema fields must be covered (missing fields = error)
 
-### Optimization Scorecard
-\`\`\`
-┌─────────────────────────────────────────┐
-│ \uD83D\uDCCA Optimization Results                │
-│ ─────────────────────────────────────── │
-│ BEFORE                                  │
-│   System: "You are a helpful..."        │
-│   Score:  0.62                          │
-│                                         │
-│ AFTER                                   │
-│   System: "You are an expert..."        │
-│   Score:  0.91 (+47%)                   │
-│                                         │
-│ Iterations: 5 | Best: #4               │
-│ ─────────────────────────────────────── │
-│ Score Progression:                      │
-│ #1: 0.62  #2: 0.71  #3: 0.78          │
-│ #4: 0.91  #5: 0.89                     │
-│                                         │
-│ [Apply] [Reject] [View Details]         │
-│                                         │
-│ \uD83D\uDD17 Dashboard: https://app.mutagent...  │
-│ \uD83D\uDD17 Optimizer: https://app.mutagent...  │
-└─────────────────────────────────────────┘
-\`\`\`
+## State Tracking
+- \`.mutagent/mutation-context.md\` — Codebase index of discovered/uploaded prompts
+- Check and update this file after explore, create, and dataset operations
+- \`mutagent auth status\` — Auth + workspace state
+- Comment markers (\`// MutagenT:START ... // MutagenT:END\`) in source files
+
+## Post-Optimization
+After \`optimize results\`: ALWAYS show the before/after diff to the user first. Then offer choices via AskUserQuestion: Apply / Reject.
 
 ## Evaluation Criteria Reminder
 Every evaluation MUST specify criteria targeting either:
 - Input variable fields (from inputSchema)
-- Output fields (from outputSchema / structured output)`;
+- Output fields (from outputSchema / structured output)
+
+## Optimization Cost Control
+- Default max-iterations is 1. NEVER increase without explicit user request.
+- Each iteration incurs LLM costs. Starting >1 iterations without consent = protocol violation.
+- If user wants more, confirm the number via AskUserQuestion first.
+
+## Claude Code Hooks (Session Telemetry)
+Optional — sends session activity to MutagenT traces API for observability.
+
+Install via \`.claude/settings.local.json\`:
+\\\`\\\`\\\`json
+{"hooks": {
+  "SessionStart": [{"matcher": "startup", "hooks": [{"type": "command", "command": "mutagent hooks claude-code session-start"}]}],
+  "Stop": [{"hooks": [{"type": "command", "command": "mutagent hooks claude-code session-end"}]}],
+  "PreToolUse": [{"hooks": [{"type": "command", "command": "mutagent hooks claude-code pre-tool-use"}]}],
+  "PostToolUse": [{"hooks": [{"type": "command", "command": "mutagent hooks claude-code post-tool-use"}]}]
+}}
+\\\`\\\`\\\`
+Or run: \`mutagent init\` (option 1 installs skill + hooks together)`;
 var SKILL_DIR = ".claude/skills/mutagent-cli";
 var SKILL_FILE = "SKILL.md";
 function createSkillsCommand() {
@@ -7686,7 +7687,23 @@ async function handlePostToolUse() {
   ]);
 }
 function createHooksCommand() {
-  const hooks = new Command18("hooks").description("Hook handlers for AI coding assistants");
+  const hooks = new Command18("hooks").description("Hook handlers for AI coding assistants").addHelpText("after", `
+Claude Code Session Telemetry:
+  Sends lightweight session activity to the MutagenT traces API for observability.
+
+  Install by adding to .claude/settings.local.json:
+
+  {
+    "hooks": {
+      "SessionStart": [{"matcher": "startup", "hooks": [{"type": "command", "command": "mutagent hooks claude-code session-start"}]}],
+      "Stop": [{"hooks": [{"type": "command", "command": "mutagent hooks claude-code session-end"}]}],
+      "PreToolUse": [{"hooks": [{"type": "command", "command": "mutagent hooks claude-code pre-tool-use"}]}],
+      "PostToolUse": [{"hooks": [{"type": "command", "command": "mutagent hooks claude-code post-tool-use"}]}]
+    }
+  }
+
+  Or run: mutagent init (option 1 installs skill + hooks together)
+    `);
   const claudeCode = hooks.command("claude-code").description("Claude Code session telemetry");
   claudeCode.command("session-start").description("Handle session start event").action(async () => {
     await safeExecute(handleSessionStart);
@@ -7754,10 +7771,16 @@ ${chalk24.yellow("Command Navigation:")}
   mutagent prompts optimize results <job-id>  ${chalk24.dim("View scorecard")}
 
   mutagent integrate <framework>        ${chalk24.dim("Framework integration guide")}
-  mutagent hooks claude-code <event>   ${chalk24.dim("Hook handler for Claude Code telemetry")}
+  mutagent hooks --help                 ${chalk24.dim("Hook setup for Claude Code telemetry")}
   mutagent playground run <id> --input '{...}'  ${chalk24.dim("Quick test")}
 
-${chalk24.yellow("Workflow: Evaluate → Optimize:")}
+${chalk24.yellow("★ Workflow: Framework Integration (Tracing):")}
+  1. mutagent explore                                    ${chalk24.dim("← discover prompts/agents in codebase")}
+  2. mutagent integrate <framework>                      ${chalk24.dim("← get integration instructions")}
+  3. Apply tracing code to your codebase                 ${chalk24.dim("← follow the guide output")}
+  4. mutagent traces list --json                         ${chalk24.dim("← verify traces are arriving")}
+
+${chalk24.yellow("★ Workflow: Evaluate → Optimize:")}
   1. mutagent prompts create --help               ${chalk24.dim("← read help")}
   2. mutagent prompts create ... --json            ${chalk24.dim("← upload prompt with {variables} + inputSchema")}
   3. mutagent prompts dataset add --help           ${chalk24.dim("← read help")}
@@ -7765,14 +7788,50 @@ ${chalk24.yellow("Workflow: Evaluate → Optimize:")}
   5. mutagent prompts evaluation create <id> --guided --json  ${chalk24.dim("← guided eval")}
   6. mutagent prompts optimize start <id> --dataset <d> --evaluation <e> --json
 
+${chalk24.yellow("Post-Onboarding Decision Tree:")}
+  After ${chalk24.bold("mutagent auth login")}, users land in one of 3 paths:
+  ${chalk24.bold("Path A")} (Tracing):      explore → integrate <framework> → apply tracing → verify
+  ${chalk24.bold("Path B")} (Optimization): explore → prompts create → dataset add → eval create → optimize
+  ${chalk24.bold("Path C")} (Manual):       Use CLI commands directly — run mutagent <command> --help
+
+${chalk24.yellow("Directive System:")}
+  Every --json response may include:
+  ${chalk24.bold("_directive.renderedCard")}  Pre-formatted card for the user ${chalk24.red("(MUST be shown in chat)")}
+  ${chalk24.bold("_directive.instruction")}   Next step for the agent
+  ${chalk24.bold("_directive.next")}          Array of suggested follow-up commands
+  ${chalk24.bold("_links")}                   Dashboard/API URLs (format as markdown links)
+
+${chalk24.yellow("Evaluation Criteria Format:")}
+  Each criterion MUST have: ${chalk24.bold("name")}, ${chalk24.bold("description")} (scoring rubric), ${chalk24.bold("evaluationParameter")}
+  evaluationParameter MUST match an inputSchema or outputSchema field name
+  No duplicate evaluationParameter values — each criterion targets a unique field
+  ALL schema fields must be covered (missing fields = error)
+  Use ${chalk24.bold("--guided --json")} to generate criteria templates from prompt schemas
+
+${chalk24.yellow("Optimization Cost Control:")}
+  Default max-iterations is 1. ${chalk24.red("NEVER increase without explicit user request.")}
+  Each iteration incurs LLM costs — confirm with user before starting >1.
+
+${chalk24.yellow("Post-Optimization:")}
+  After ${chalk24.bold("optimize results")}: ALWAYS show the before/after diff to the user first.
+  Then offer choices: ${chalk24.bold("Apply")} / ${chalk24.bold("Reject")}.
+
+${chalk24.yellow("State Tracking:")}
+  .mutagent/mutation-context.md — Codebase index of discovered/uploaded prompts
+  Update after explore, create, and dataset operations
+  mutagent auth status — Auth + workspace state
+  Comment markers (// MutagenT:START ... // MutagenT:END) in source files
+
 ${chalk24.yellow("AI Agent Rules (MANDATORY for coding agents):")}
   1. EVERY command MUST include --json (no exceptions)
   2. Run <command> --help BEFORE first use of any command
   3. Use --guided --json for evaluation creation (NEVER --guided alone)
-  4. Parse _directive.renderedCard and copy it into your CHAT RESPONSE verbatim — bash output is NOT sufficient
+  4. Parse _directive.renderedCard and copy it into your CHAT RESPONSE verbatim
+     ${chalk24.red("HARD STOP")}: do NOT run further commands until the card is rendered in chat
   5. After mutagent init, verify workspace: mutagent workspaces list --json
   6. Use {single_braces} for template variables in prompts
-  7. Collect evaluation rubrics from the user — NEVER auto-generate
+  7. Collect evaluation criteria from the user — NEVER auto-generate
+  8. ALL user interaction via AskUserQuestion — CLI is non-interactive
 ${!hasCredentials() ? `
 ` + chalk24.yellow("  Warning: Not authenticated. Run: mutagent auth login --browser") + `
 ` : ""}${!hasRcConfig() ? `
@@ -7807,5 +7866,5 @@ program.addCommand(createUsageCommand());
 program.addCommand(createHooksCommand());
 program.parse();
 
-//# debugId=167F4784D8F12D3E64756E2164756E21
+//# debugId=3B726C6C3EEAEFBE64756E2164756E21
 //# sourceMappingURL=cli.js.map