@mutagent/cli 0.1.248 → 0.1.249

package/dist/bin/cli.js

@@ -28,12 +28,23 @@ var __export = (target, all) => {
 var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
 var __require = /* @__PURE__ */ createRequire(import.meta.url);
 
+// src/lib/secure-file.ts
+import { writeFileSync, chmodSync } from "fs";
+function writeSecureFile(path, contents) {
+  writeFileSync(path, contents, { mode: SECURE_FILE_MODE });
+  try {
+    chmodSync(path, SECURE_FILE_MODE);
+  } catch {}
+}
+var SECURE_FILE_MODE = 384;
+var init_secure_file = () => {};
+
 // src/lib/config.ts
 import { cosmiconfigSync } from "cosmiconfig";
 import { z } from "zod";
 import { homedir } from "os";
 import { join } from "path";
-import { existsSync, readFileSync, writeFileSync, mkdirSync } from "fs";
+import { existsSync, readFileSync, mkdirSync } from "fs";
 function parseJsonSafe(content, schema) {
   try {
     const parsed = JSON.parse(content);
@@ -72,7 +83,7 @@ function saveCredentials(apiKey, endpoint) {
     apiKey,
     endpoint: endpoint ?? config.endpoint
   };
-  writeFileSync(CREDENTIALS_FILE, JSON.stringify(credentials, null, 2));
+  writeSecureFile(CREDENTIALS_FILE, JSON.stringify(credentials, null, 2));
 }
 function saveFullCredentials(creds) {
   if (!existsSync(CREDENTIALS_DIR)) {
@@ -96,11 +107,11 @@ function saveFullCredentials(creds) {
     defaultOrganization: creds.organizationId ?? existingCredentials.defaultOrganization,
     expiresAt: creds.expiresAt
   };
-  writeFileSync(CREDENTIALS_FILE, JSON.stringify(credentials, null, 2));
+  writeSecureFile(CREDENTIALS_FILE, JSON.stringify(credentials, null, 2));
 }
 function clearCredentials() {
   if (existsSync(CREDENTIALS_FILE)) {
-    writeFileSync(CREDENTIALS_FILE, JSON.stringify({}));
+    writeSecureFile(CREDENTIALS_FILE, JSON.stringify({}));
   }
 }
 function hasCredentials() {
@@ -129,7 +140,7 @@ function setDefaultWorkspace(workspaceId, source = "user") {
     defaultWorkspace: workspaceId,
     defaultWorkspaceSource: source
   };
-  writeFileSync(CREDENTIALS_FILE, JSON.stringify(updated, null, 2));
+  writeSecureFile(CREDENTIALS_FILE, JSON.stringify(updated, null, 2));
 }
 function setDefaultOrganization(organizationId) {
   if (!existsSync(CREDENTIALS_DIR)) {
@@ -145,10 +156,11 @@ function setDefaultOrganization(organizationId) {
     ...existingCredentials,
     defaultOrganization: organizationId
   };
-  writeFileSync(CREDENTIALS_FILE, JSON.stringify(updated, null, 2));
+  writeSecureFile(CREDENTIALS_FILE, JSON.stringify(updated, null, 2));
 }
 var configSchema, credentialsSchema, CREDENTIALS_DIR, CREDENTIALS_FILE;
 var init_config = __esm(() => {
+  init_secure_file();
   configSchema = z.object({
     apiKey: z.string().optional(),
     endpoint: z.string().default("https://api.mutagent.io"),
@@ -866,10 +878,10 @@ var init_sdk_client = __esm(() => {
 });
 
 // src/bin/cli.ts
-import { Command as Command12 } from "commander";
-import chalk18 from "chalk";
+import { Command as Command13 } from "commander";
+import chalk19 from "chalk";
 import { readFileSync as readFileSync10 } from "fs";
-import { join as join13, dirname as dirname3 } from "path";
+import { join as join14, dirname as dirname3 } from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 
 // src/commands/auth.ts
@@ -878,7 +890,7 @@ init_sdk_client();
 import { Command } from "commander";
 import chalk4 from "chalk";
 import { existsSync as existsSync5 } from "fs";
-import { join as join6 } from "path";
+import { join as join7 } from "path";
 
 // src/lib/output.ts
 import chalk from "chalk";
@@ -1117,6 +1129,9 @@ function scaffoldRcConfig(cwd = process.cwd(), deps = {}) {
 init_errors();
 init_config();
 import { spawn as spawn2 } from "child_process";
+import { mkdirSync as mkdirSync3, readdirSync } from "fs";
+import { homedir as homedir3 } from "os";
+import { join as join6 } from "path";
 
 // src/lib/installer-helix.ts
 init_errors();
@@ -1200,8 +1215,6 @@ async function installHelix(opts, deps = {}) {
   const locateInitBin = deps.locateInitBin ?? defaultLocateInitBin;
   const binPath = await locateInitBin(versionDir);
   const initArgs = ["init"];
-  if (opts.global)
-    initArgs.push("--global");
   const runInit = deps.runInit ?? defaultRunInit;
   const code = await runInit(binPath, initArgs, process.cwd());
   if (code !== 0) {
@@ -1277,7 +1290,7 @@ function defaultLocateInitBin(extractedDir) {
   const pkgDir = existsSync4(join5(extractedDir, "package", "package.json")) ? join5(extractedDir, "package") : extractedDir;
   const pkgJsonPath = join5(pkgDir, "package.json");
   if (!existsSync4(pkgJsonPath)) {
-    return Promise.reject(new MutagentError("INSTALL_FAILED", "Could not find package.json in the extracted helix plugin.", "The archive layout is unexpected — retry or report: mutagent install helix"));
+    return Promise.reject(new MutagentError("INSTALL_FAILED", `Could not find package.json under ${pkgDir}.`, "The package layout is unexpected — retry the install, or report it."));
   }
   const raw = JSON.parse(readFileSync4(pkgJsonPath, "utf-8"));
   const binRel = resolveBinField(raw);
@@ -1292,9 +1305,9 @@ function defaultLocateInitBin(extractedDir) {
 }
 function defaultRunInit(binPath, args, cwd) {
   return new Promise((resolve, reject) => {
-    const child = spawn("node", [binPath, ...args], { cwd, stdio: "inherit" });
+    const child = spawn("node", [binPath, ...args], { cwd, stdio: ["ignore", 2, 2] });
     child.on("error", (err) => {
-      reject(new MutagentError("INSTALL_FAILED", `Failed to run the helix plugin init: ${err.message}`, 'Ensure "node" is installed and available on your PATH.'));
+      reject(new MutagentError("INSTALL_FAILED", `Failed to run the package init: ${err.message}`, 'Ensure "node" is installed and available on your PATH.'));
     });
     child.on("close", (code) => {
       resolve(code ?? 1);
@@ -1356,6 +1369,10 @@ var NPM_PACKAGES = {
   diagnostics: "@mutagent/diagnostics",
   evaluator: "@mutagent/evaluator"
 };
+var INIT_BINS = {
+  diagnostics: "mutagent-diagnostics",
+  evaluator: "mutagent-evaluator"
+};
 var defaultRunner = (cmd, args) => new Promise((resolve, reject) => {
   const child = spawn2(cmd, args, { stdio: ["ignore", "pipe", "pipe"] });
   let stdout = "";
@@ -1373,6 +1390,29 @@ var defaultRunner = (cmd, args) => new Promise((resolve, reject) => {
     resolve({ code: code ?? 1, stdout, stderr });
   });
 });
+function countProjectFiles(root) {
+  const roots = [".claude", ".codex", ".agents"];
+  let n = 0;
+  const walk = (dir, depth) => {
+    if (depth > 6)
+      return;
+    let entries;
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      if (e.isDirectory())
+        walk(join6(dir, e.name), depth + 1);
+      else
+        n++;
+    }
+  };
+  for (const r of roots)
+    walk(join6(root, r), 0);
+  return n;
+}
 function isValidPackage(pkg) {
   return VALID_PACKAGES.includes(pkg);
 }
@@ -1384,6 +1424,16 @@ async function installPackage(pkg, opts, deps = {}) {
   if (!isAuthed()) {
     throw new MutagentError("AUTH_REQUIRED", `Authentication required to install ${pkg}.`, "Run: mutagent login");
   }
+  const projectPath = process.cwd();
+  if (opts.global === true) {
+    throw new MutagentError("INVALID_ARGUMENTS", "--global is no longer supported: install scope is no longer selectable.", [
+      "Every install is project-scoped now:",
+      `  the package resolves into ~/.mutagent/<pkg>/<version>, and its skill`,
+      `  is installed into the current project (${projectPath}).`,
+      "Nothing is installed globally. Re-run without --global."
+    ].join(`
+`));
+  }
   if (!isValidPackage(pkg)) {
     throw new MutagentError("INVALID_ARGUMENTS", `Unknown package "${pkg}". Valid: ${VALID_PACKAGES.join(", ")}`, "Run: mutagent install --help");
   }
@@ -1392,27 +1442,41 @@ async function installPackage(pkg, opts, deps = {}) {
   }
   const version = opts.version ?? VERSION_MATRIX[pkg];
   if (pkg === "helix") {
-    const { version: resolved } = await installHelix({ harness: opts.harness, global: opts.global, version }, deps.helix ?? {});
+    const { version: resolved } = await installHelix({ harness: opts.harness, version }, deps.helix ?? {});
     return finish({
       package: pkg,
       version: resolved,
       harness: opts.harness,
-      global: opts.global
+      scope: "project",
+      projectPath,
+      skillInstalled: true
     }, deps);
   }
   const npmPackage = NPM_PACKAGES[pkg];
-  const args = ["install", "-g", `${npmPackage}@${version}`];
+  const installRoot = join6(deps.homeDir ?? join6(homedir3(), ".mutagent", pkg), version);
+  mkdirSync3(installRoot, { recursive: true });
+  const args = ["install", "--prefix", installRoot, "--no-save", `${npmPackage}@${version}`];
   const runner = deps.runner ?? defaultRunner;
   const result = await runner("npm", args);
   if (result.code !== 0) {
     const detail = result.stderr.trim();
-    throw new MutagentError("INSTALL_FAILED", `npm failed to install ${npmPackage}@${version} (exit ${String(result.code)}).${detail ? ` ${detail.slice(0, 200)}` : ""}`, "Verify the package and version exist and that you have permission for a global npm install.");
-  }
+    throw new MutagentError("INSTALL_FAILED", `npm failed to install ${npmPackage}@${version} (exit ${String(result.code)}).${detail ? ` ${detail.slice(0, 200)}` : ""}`, `Verify the package and version exist, and that ${installRoot} is writable.`);
+  }
+  const pkgDir = join6(installRoot, "node_modules", npmPackage);
+  const initBin = await (deps.locateInitBin ?? defaultLocateInitBin)(pkgDir);
+  const countFiles = deps.countProjectFiles ?? countProjectFiles;
+  const before = countFiles(projectPath);
+  const initCode = await (deps.runInit ?? defaultRunInit)(initBin, ["init"], projectPath);
+  const landed = countFiles(projectPath) > before;
   return finish({
     package: pkg,
     version,
     harness: opts.harness,
-    global: opts.global,
+    scope: "project",
+    projectPath,
+    installRoot,
+    skillInstalled: initCode === 0 && landed,
+    ...initCode === 0 && landed ? {} : { nextStep: `${INIT_BINS[pkg]} init` },
     command: `npm ${args.join(" ")}`
   }, deps);
 }
@@ -1912,7 +1976,7 @@ Examples:
     }
     const isValid = await validateApiKey(apiKey, endpoint);
     const cwd = process.cwd();
-    const hasOnboarding = existsSync5(join6(cwd, ".mutagentrc.json"));
+    const hasOnboarding = existsSync5(join7(cwd, ".mutagentrc.json"));
     if (isJson) {
       const statusResult = {
         authenticated: isValid,
@@ -3301,14 +3365,14 @@ init_config();
 import { Command as Command7 } from "commander";
 import chalk13 from "chalk";
 import { readFileSync as readFileSync5 } from "fs";
-import { join as join8 } from "path";
+import { join as join9 } from "path";
 init_errors();
 
 // src/commands/skills.ts
 import { Command as Command6 } from "commander";
 import chalk12 from "chalk";
-import { existsSync as existsSync6, mkdirSync as mkdirSync3, writeFileSync as writeFileSync4 } from "fs";
-import { dirname, join as join7 } from "path";
+import { existsSync as existsSync6, mkdirSync as mkdirSync4, writeFileSync as writeFileSync4 } from "fs";
+import { dirname, join as join8 } from "path";
 import { execSync } from "child_process";
 
 // src/generated/skill-content.ts
@@ -3523,15 +3587,23 @@ user's UI and they cannot read them.
 When ANY mutagent CLI command returns a non-zero exit code or an error response:
 
 1. **Show the error to the user** (always) -- reproduce the exact command and output.
-2. **ASK the user** if they want to file a bug report with session context.
-3. **On user approval**, send feedback with the session transcript attached:
+2. **ASK the user** if they want to file a bug report.
+3. **On user approval**, send the feedback — **without a transcript**:
    \`\`\`bash
    mutagent feedback send "<one-line summary of the failure>" \\
-     --category cli --attach-transcript --json
+     --category cli --json
    \`\`\`
-   - \`--attach-transcript\` (bare) auto-detects the newest coding-agent session JSONL and uploads it as context.
    - Use \`--category stage:<spec|build|evaluate|diagnose|optimize>\` when the failure is about a specific lifecycle stage rather than the CLI itself.
 
+**Do NOT pass \`--attach-transcript\` unless the user explicitly asks for it.** It uploads
+the coding-agent session JSONL — source code, absolute paths (including their username),
+branch and repository names, internal hostnames, and the business context of their prompts.
+Credentials are scanned for and redacted, but detection is **best-effort**.
+
+Approval to "file a bug report" is **NOT** approval to upload a session. They are separate
+questions and must be asked separately. If you believe the transcript would genuinely help,
+say exactly what it contains and ask a second time.
+
 See [workflows/feedback.md](./workflows/feedback.md) for the full feedback surface.
 
 ### If \`mutagent feedback send\` itself fails
@@ -3615,9 +3687,9 @@ attached automatically — you never set it manually.
 
 3. Compose the feedback body from the user's own words
    → pick --category (default cli; use stage:<x> for a lifecycle stage)
-   → offer --attach-transcript when reporting a bug or a session-specific issue
+   → do NOT offer --attach-transcript unless the user explicitly asks for it (see Transcript safety below)
 
-4. mutagent feedback send "<body>" --category <c> [--attach-transcript] --json
+4. mutagent feedback send "<body>" --category <c> --json
    → show the returned id + category + transcriptAttached to the user
 \`\`\`
 
@@ -3629,9 +3701,12 @@ attached automatically — you never set it manually.
 mutagent feedback send "Optimizer results were great" --json
 mutagent feedback send "Eval gate was confusing" --category stage:evaluate --json
 mutagent feedback send "CLI crashed on login" --category cli \\
-  --title "login crash on first run" --attach-transcript --json
+  --title "login crash on first run" --json
 mutagent feedback send "Diagnose loop stalled" --category stage:diagnose \\
-  --session run_abc123 --attach-transcript /tmp/session.jsonl --json
+  --session run_abc123 --json
+
+# ONLY when the operator explicitly asked to attach their session — see Transcript safety:
+mutagent feedback send "CLI crashed on login" --category cli --attach-transcript --json
 \`\`\`
 
 ---
@@ -3642,11 +3717,11 @@ When a mutagent command fails, this is the canonical bug-report path:
 
 1. Show the user the failed command + error.
 2. ASK if they want to file a report.
-3. On approval, send feedback with the transcript attached so the team gets full context:
+3. On approval, send the feedback — WITHOUT a transcript:
    \`\`\`bash
-   mutagent feedback send "<one-line failure summary>" \\
-     --category cli --attach-transcript --json
+   mutagent feedback send "<one-line failure summary>" --category cli --json
    \`\`\`
+   Approval to "file a report" is NOT approval to upload a session. See Transcript safety.
 
 ---
 
@@ -3670,6 +3745,27 @@ When a mutagent command fails, this is the canonical bug-report path:
 
 - [SKILL.md](../SKILL.md) → Core Rules + Error Recovery
 - [workflows/setup.md](./setup.md) → login (prerequisite for feedback)
+
+
+## Transcript safety (\`--attach-transcript\`)
+
+**Never pass this flag on your own initiative.** Only when the operator explicitly asks to
+attach their session.
+
+A session JSONL contains **source code, absolute paths including their username, branch and
+repository names, internal hostnames, and the business context of every prompt**. It is a
+separate artifact from the feedback text and is uploaded whole (last-200KB tail).
+
+Credentials are scanned for and redacted before upload, and the byte size + source path are
+printed before the network call — but **detection is best-effort**. If the session handled
+secrets, do not attach it.
+
+"Yes, file a bug report" is **not** consent to upload a session. Ask separately, state what
+the file contains, and accept no as the default.
+
+**Response fields** when a transcript IS attached: \`transcriptAttached\`, \`transcriptBytes\`,
+\`transcriptSource\`, and \`redactions\`. **Always surface \`redactions\` to the operator** — it is
+how they learn something sensitive was in the file at all.
 `,
   "workflows/install.md": `---
 name: mutagent-cli-workflows-install
@@ -3690,8 +3786,17 @@ triggers:
 
 # Workflow — Install (Meta-Installer)
 
-> **Scope**: installs a Mutagent package globally (or per the target harness).
+> **Scope differs by package** — read \`scope\` in the response, never assume:
+> - \`helix\` → installed into the CURRENT project directory (\`scope: "project"\`).
+> - \`diagnostics\` / \`evaluator\` → **npm installs the package GLOBALLY**
+>   (\`scope: "global"\`, literally \`npm install -g\`). It does NOT go in the
+>   user's project. Its skill init is the part you later run in the project.
+>
 > This WRITES to the user's machine — confirm before running (Core Rule 5).
+>
+> **\`success: true\` does NOT mean the user is ready to go.** For \`diagnostics\`
+> and \`evaluator\` it means the npm package landed; the skill still needs the
+> package's own init. Branch on \`skillInstalled\` — see *Output handling* below.
 
 Read the **Core Rules** in [SKILL.md](../SKILL.md) first. Key reminders:
 - \`--json\` on every command
@@ -3707,7 +3812,7 @@ Read the **Core Rules** in [SKILL.md](../SKILL.md) first. Key reminders:
 mutagent install --help    # authoritative flags — read before first use
 
 mutagent install <package> [--harness <claude-code|codex|omp>] \\
-                           [--global] [--version <v>] [--json]
+                           [--version <v>] [--json]
 \`\`\`
 
 Where \`<package>\` is one of:
@@ -3720,7 +3825,7 @@ Where \`<package>\` is one of:
 
 **Flags** (verify against \`--help\`):
 - \`--harness <claude-code|codex|omp>\` -- target coding-agent harness (default \`claude-code\`).
-- \`--global\` -- install globally (default on).
+- Install scope is FIXED PER PACKAGE and is not selectable: \`helix\` installs into the current directory; \`diagnostics\`/\`evaluator\` are installed GLOBALLY by npm. \`--global\` is retired: passing it fails and explains both paths.
 - \`--version <v>\` -- pin a specific version (default: latest).
 - \`--json\` -- structured output (Rule 1).
 
@@ -3737,11 +3842,23 @@ Where \`<package>\` is one of:
    → read the current packages + flags (Rule 2)
 
 3. Confirm with the user WHAT will be installed and WHERE
-   → e.g. "I'll install @mutagent/diagnostics globally for claude-code. Proceed?"
+   → state the REAL destination for the package being installed, e.g.
+      helix:        "I'll install helix into <current directory>. Proceed?"
+      diagnostics:  "I'll install @mutagent/diagnostics GLOBALLY via npm, then
+                     you'll run its init inside your project. Proceed?"
 
 4. mutagent install <package> [--harness <h>] [--version <v>] --json
    → run the install
-   → show the command output (package, version, harness) to the user
+   → show the command output to the user: package, version, harness, and
+      \`scope\`. Surface \`projectPath\` ONLY when \`scope\` is \`"project"\` — it is
+      ABSENT from the response on the global npm path.
+
+5. CHECK \`skillInstalled\` in the JSON response — do NOT stop at \`success: true\`
+   → skillInstalled === true  → done; the skill is installed and usable
+   → skillInstalled === false → NOT done. Tell the user plainly that the npm
+      package is installed but the skill is not, then surface \`nextStep\`
+      (e.g. \`mutagent-diagnostics init\`) as the command to run next.
+      Confirm before running it — it writes to their project (Core Rule 5).
 \`\`\`
 
 ---
@@ -3760,17 +3877,62 @@ mutagent install diagnostics --harness codex --json
 
 ## Output handling
 
-- On success (\`{ success: true, package, version, harness, global }\`): tell the user what was installed and the resolved version. Surface \`_links.install\` / \`_links.login\`.
-- For \`helix\`: the CLI resolves a signed download URL from the login broker, downloads + sha256-verifies the plugin, then runs its init into the project. An \`INTEGRITY_ERROR\` means the download failed checksum verification — retry.
-- On an auth error (including a broker \`AUTH_REQUIRED\`): route to the login workflow, then retry.
+Success shape:
+
+\`\`\`json
+{
+  "success": true,
+  "package": "diagnostics",
+  "version": "1.2.3",
+  "harness": "claude-code",
+  "scope": "global",
+  "skillInstalled": false,
+  "nextStep": "mutagent-diagnostics init",
+  "_links": { "install": "...", "login": "..." }
+}
+\`\`\`
+
+\`helix\` instead returns \`"scope": "project"\` with \`"projectPath"\`, and
+\`"skillInstalled": true\`.
+
+- **\`skillInstalled\` is the field to branch on — NOT \`success\`.** \`success: true\`
+  reports that the install step did its job, not that the user is ready.
+  \`nextStep\` is present only when work remains.
+- \`skillInstalled: false\` (npm packages — \`diagnostics\`, \`evaluator\`): the npm
+  package is installed; the harness skill is **not**. Say so explicitly and give
+  the user \`nextStep\`. Reporting only "installed" here is a known past defect —
+  users were told a skill had landed when none had.
+- \`skillInstalled: true\` (\`helix\`): the CLI resolved a signed download URL from
+  the login broker, downloaded + sha256-verified the plugin, and ran its init
+  into the project. Nothing further is needed. An \`INTEGRITY_ERROR\` means the
+  download failed checksum verification — retry.
+- **\`scope\` tells you WHERE it went. Read it; do not assume.**
+  - \`"global"\` (\`diagnostics\`, \`evaluator\`) — npm installed the package into its
+    GLOBAL root (\`npm install -g\`). The package is **not** in the user's project;
+    never tell the user it is. No path is reported — run \`npm root -g\` if the
+    user needs the directory.
+  - \`"project"\` (\`helix\`) — installed into \`projectPath\`. Surface it so the user
+    can confirm the location.
+- On an auth error (including a broker \`AUTH_REQUIRED\`): route to the login
+  workflow, then retry.
+- On \`INVALID_ARGUMENTS\` naming \`--global\`: the flag is retired. Re-run without
+  it, or \`cd\` to the intended project first — the error names the path that
+  would have been used.
 
 ---
 
 ## Common pitfalls
 
+- **Treating \`success: true\` as "the user is ready".** For \`diagnostics\` and
+  \`evaluator\` it is not — check \`skillInstalled\` and surface \`nextStep\`. Stopping
+  at \`success\` leaves the user with a package and no skill, believing it works.
+- **Telling the user a globally-installed package is in their project.**
+  \`diagnostics\` and \`evaluator\` install globally (\`npm install -g\`). Report the
+  location from \`scope\`, never from the directory you ran in.
 - Running before login → auth error (install is login-gated).
 - Assuming \`helix\` installs from public npm — it is fetched from a private registry via a login-brokered signed URL (the CLI holds no static secret).
 - Installing without confirming with the user first (Core Rule 5).
+- Passing \`--global\` — retired; scope is fixed per package and is not selectable.
 
 ---
 
@@ -3954,7 +4116,7 @@ function getSkillFiles() {
 }
 function installCliSkill(targetRoot) {
   const files = getSkillFiles();
-  const skillDir = join7(targetRoot, SKILL_DIR);
+  const skillDir = join8(targetRoot, SKILL_DIR);
   const writtenFiles = [];
   let totalBytes = 0;
   const sortedKeys = Object.keys(files).sort((a, b) => {
@@ -3965,10 +4127,10 @@ function installCliSkill(targetRoot) {
     return a.localeCompare(b);
   });
   for (const relPath of sortedKeys) {
-    const destPath = join7(skillDir, relPath);
+    const destPath = join8(skillDir, relPath);
     const parentDir = dirname(destPath);
     if (!existsSync6(parentDir)) {
-      mkdirSync3(parentDir, { recursive: true });
+      mkdirSync4(parentDir, { recursive: true });
     }
     const raw = files[relPath] ?? "";
     const finalContent = raw.endsWith(`
@@ -4059,7 +4221,7 @@ What it does:
       let rcConfig;
       if (rcExists) {
         try {
-          rcConfig = JSON.parse(readFileSync5(join8(cwd, ".mutagentrc.json"), "utf-8"));
+          rcConfig = JSON.parse(readFileSync5(join9(cwd, ".mutagentrc.json"), "utf-8"));
         } catch {
           rcConfig = {};
         }
@@ -4214,10 +4376,10 @@ import { randomUUID } from "crypto";
 
 // src/commands/hooks/state.ts
 import { readFileSync as readFileSync6, writeFileSync as writeFileSync5, renameSync as renameSync2, unlinkSync, existsSync as existsSync7 } from "fs";
-import { join as join9 } from "path";
+import { join as join10 } from "path";
 import { tmpdir } from "os";
 function stateFilePath(sessionId) {
-  return join9(tmpdir(), `mutagent-hook-${sessionId}.json`);
+  return join10(tmpdir(), `mutagent-hook-${sessionId}.json`);
 }
 function readState(sessionId) {
   const path = stateFilePath(sessionId);
@@ -4891,8 +5053,8 @@ async function handlePostToolUseFailure() {
 }
 
 // src/commands/hooks/install.ts
-import { readFileSync as readFileSync7, writeFileSync as writeFileSync6, existsSync as existsSync8, mkdirSync as mkdirSync4 } from "fs";
-import { join as join10 } from "path";
+import { readFileSync as readFileSync7, writeFileSync as writeFileSync6, existsSync as existsSync8, mkdirSync as mkdirSync5 } from "fs";
+import { join as join11 } from "path";
 
 class SettingsParseError extends Error {
   settingsPath;
@@ -4954,8 +5116,8 @@ function migrateV1Hooks(settings) {
   return migrated;
 }
 function installHooks(cwd) {
-  const claudeDir = join10(cwd, ".claude");
-  const settingsPath = join10(claudeDir, "settings.local.json");
+  const claudeDir = join11(cwd, ".claude");
+  const settingsPath = join11(claudeDir, "settings.local.json");
   const existed = existsSync8(settingsPath);
   let settings = {};
   if (existed) {
@@ -4995,7 +5157,7 @@ function installHooks(cwd) {
   let userWarning;
   if (added.length > 0 || migrated.length > 0) {
     if (!existsSync8(claudeDir)) {
-      mkdirSync4(claudeDir, { recursive: true });
+      mkdirSync5(claudeDir, { recursive: true });
     }
     writeFileSync6(settingsPath, JSON.stringify(settings, null, 2) + `
 `, "utf-8");
@@ -5141,10 +5303,10 @@ times is safe.
 
 // src/commands/feedback.ts
 import { Command as Command10 } from "commander";
-import chalk16 from "chalk";
+import chalk17 from "chalk";
 import { type as osType, release as osRelease } from "os";
 import { readFileSync as readFileSync9 } from "fs";
-import { join as join12, dirname as dirname2 } from "path";
+import { join as join13, dirname as dirname2 } from "path";
 import { fileURLToPath } from "url";
 init_errors();
 init_config();
@@ -5152,12 +5314,12 @@ init_config();
 // src/lib/transcript.ts
 init_errors();
 import { homedir as osHomedir } from "os";
-import { join as join11 } from "path";
+import { join as join12 } from "path";
 import {
   existsSync as fsExistsSync,
   statSync as fsStatSync,
   readFileSync as readFileSync8,
-  readdirSync,
+  readdirSync as readdirSync2,
   openSync,
   readSync,
   closeSync
@@ -5185,12 +5347,12 @@ function defaultScan(dir) {
   const walk = (current) => {
     let entries;
     try {
-      entries = readdirSync(current, { withFileTypes: true });
+      entries = readdirSync2(current, { withFileTypes: true });
     } catch {
       return;
     }
     for (const entry of entries) {
-      const full = join11(current, entry.name);
+      const full = join12(current, entry.name);
       if (entry.isDirectory())
         walk(full);
       else if (entry.isFile() && entry.name.endsWith(".jsonl"))
@@ -5201,11 +5363,11 @@ function defaultScan(dir) {
   return out;
 }
 function buildSources(env, home) {
-  const ompBase = env.PI_CODING_AGENT_DIR ?? join11(home, ".omp", "agent");
+  const ompBase = env.PI_CODING_AGENT_DIR ?? join12(home, ".omp", "agent");
   return [
-    { harness: "claude-code", dir: join11(home, ".claude", "projects") },
-    { harness: "codex", dir: join11(home, ".codex", "sessions") },
-    { harness: "omp", dir: join11(ompBase, "sessions") }
+    { harness: "claude-code", dir: join12(home, ".claude", "projects") },
+    { harness: "codex", dir: join12(home, ".codex", "sessions") },
+    { harness: "omp", dir: join12(ompBase, "sessions") }
   ];
 }
 function resolveTranscript(attach, deps = {}) {
@@ -5251,6 +5413,276 @@ Or omit the path to auto-detect the newest coding-agent session.`);
   };
 }
 
+// src/lib/feedback-safety.ts
+import chalk16 from "chalk";
+
+// src/lib/secret-scan.ts
+var PATTERNS = [
+  {
+    kind: "private-key",
+    label: "Private key block",
+    regex: /-----BEGIN(?: [A-Z]+)* PRIVATE KEY-----[\s\S]*?-----END(?: [A-Z]+)* PRIVATE KEY-----/g
+  },
+  {
+    kind: "anthropic-api-key",
+    label: "Anthropic API key",
+    regex: /sk-ant-[A-Za-z0-9_-]{16,}/g
+  },
+  {
+    kind: "openai-api-key",
+    label: "OpenAI API key",
+    regex: /sk-(?!ant-)(?:proj-)?[A-Za-z0-9_-]{20,}/g
+  },
+  {
+    kind: "aws-access-key-id",
+    label: "AWS access key ID",
+    regex: /\b(?:AKIA|ASIA)[0-9A-Z]{16}\b/g
+  },
+  {
+    kind: "github-token",
+    label: "GitHub token",
+    regex: /\b(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9]{36,}\b|\bgithub_pat_[A-Za-z0-9_]{22,}\b/g
+  },
+  {
+    kind: "google-api-key",
+    label: "Google API key",
+    regex: /\bAIza[0-9A-Za-z_-]{35}\b/g
+  },
+  {
+    kind: "slack-token",
+    label: "Slack token",
+    regex: /\bxox[baprs]-[A-Za-z0-9-]{10,}\b/g
+  },
+  {
+    kind: "mutagent-api-key",
+    label: "Mutagent API key",
+    regex: /\bmt_[A-Za-z0-9]{16,}\b/g
+  },
+  {
+    kind: "bearer-token",
+    label: "Bearer token",
+    regex: /\bBearer\s+([A-Za-z0-9._-]{20,})/g
+  },
+  {
+    kind: "generic-assignment",
+    label: "Credential assignment",
+    regex: /(?:api[_-]?key|apikey|secret|password|passwd|token|access[_-]?key)["']?\s*[:=]\s*["']?([A-Za-z0-9._/+-]{16,})/gi
+  }
+];
+function hasCredentialEntropy(candidate) {
+  if (candidate.length < 16)
+    return false;
+  const distinct = new Set(candidate).size;
+  if (distinct < 8)
+    return false;
+  return !/(.)\1{7,}/.test(candidate);
+}
+function maskSecret(secret) {
+  const head = secret.slice(0, 6);
+  return `${head}${"*".repeat(Math.min(12, Math.max(4, secret.length - head.length)))}`;
+}
+function collectHits(content) {
+  const accepted = [];
+  const overlaps = (start, end) => accepted.some((hit) => start < hit.end && end > hit.start);
+  for (const pattern of PATTERNS) {
+    const regex = new RegExp(pattern.regex.source, pattern.regex.flags);
+    let match;
+    while ((match = regex.exec(content)) !== null) {
+      if (match[0].length === 0) {
+        regex.lastIndex += 1;
+        continue;
+      }
+      const captured = match[1];
+      const secret = captured ?? match[0];
+      const start = captured === undefined ? match.index : match.index + match[0].indexOf(captured);
+      const end = start + secret.length;
+      const exemptFromEntropy = pattern.kind === "private-key";
+      if (!exemptFromEntropy && !hasCredentialEntropy(secret))
+        continue;
+      if (overlaps(start, end))
+        continue;
+      accepted.push({ kind: pattern.kind, label: pattern.label, start, end, secret });
+    }
+  }
+  return accepted.sort((a, b) => a.start - b.start);
+}
+function lineOf(content, offset) {
+  let line = 1;
+  for (let i = 0;i < offset && i < content.length; i++) {
+    if (content[i] === `
+`)
+      line++;
+  }
+  return line;
+}
+function redactSecrets(content) {
+  if (!content)
+    return { content, matches: [] };
+  const hits = collectHits(content);
+  if (hits.length === 0)
+    return { content, matches: [] };
+  let out = "";
+  let cursor = 0;
+  for (const hit of hits) {
+    out += content.slice(cursor, hit.start);
+    out += `[REDACTED:${hit.kind}]`;
+    cursor = hit.end;
+  }
+  out += content.slice(cursor);
+  return {
+    content: out,
+    matches: hits.map((hit) => ({
+      kind: hit.kind,
+      label: hit.label,
+      line: lineOf(content, hit.start),
+      preview: maskSecret(hit.secret)
+    }))
+  };
+}
+
+// src/lib/by-design.ts
+var NOT_FOUND = String.raw`404|not\s+found|missing|unavailable|unpublished|doesn'?t\s+exist|does\s+not\s+exist|no\s+such\s+package|cannot\s+install|can'?t\s+install|fails?\s+to\s+install`;
+var NOT_A_COMMAND = String.raw`not\s+a\s+command|unknown\s+command|unrecognized|unrecognised|doesn'?t\s+exist|does\s+not\s+exist|not\s+found|missing|no\s+such\s+command|invalid\s+command`;
+function pairPatterns(subject, symptoms) {
+  return [
+    new RegExp(`${subject}[^\\n]{0,60}?(?:${symptoms})`, "i"),
+    new RegExp(`(?:${symptoms})[^\\n]{0,60}?${subject}`, "i")
+  ];
+}
+var TOOLS_PKG = String.raw`@mutagent\/tools`;
+var HELIX_PKG = String.raw`@mutagent\/helix`;
+var BY_DESIGN_ENTRIES = [
+  {
+    id: "mutagent-tools-not-on-npm",
+    title: "@mutagent/tools is not published to npm — on purpose",
+    looksLike: pairPatterns(TOOLS_PKG, NOT_FOUND),
+    reality: "@mutagent/tools is intentionally not published to the public npm registry, so a 404 there is the expected result rather than a broken release. Its functionality is compiled into the mutagent-cli binary that ships with the diagnostics and evaluator packages — installing either one already gives you the tooling, and there is nothing separate to install."
+  },
+  {
+    id: "mutagent-helix-not-on-npm",
+    title: "@mutagent/helix is not published to npm — on purpose",
+    looksLike: pairPatterns(HELIX_PKG, NOT_FOUND),
+    reality: "Helix is not distributed through the public npm registry, so a 404 there is expected. It is delivered by the Mutagent CLI itself, which authenticates you, fetches a signed download from private storage, verifies its checksum, and initializes it into your project. Install it with: mutagent install helix"
+  },
+  {
+    id: "trace-lives-in-a-different-binary",
+    title: "trace is a mutagent-cli command, not a mutagent command",
+    looksLike: [
+      ...pairPatterns(String.raw`mutagent\s+trace`, NOT_A_COMMAND),
+      /\btrace\b[^\n]{0,40}?(?:not\s+a\s+(?:valid\s+)?(?:sub)?command|unknown\s+command)/i
+    ],
+    reality: "trace is not a subcommand of mutagent. It lives in mutagent-cli — a different binary — which is installed alongside @mutagent/diagnostics, @mutagent/evaluator, or helix. Run: mutagent-cli trace <args>"
+  },
+  {
+    id: "two-separate-binaries",
+    title: "mutagent and mutagent-cli are two different binaries",
+    looksLike: [
+      /(?:no|not|missing|can'?t\s+find|cannot\s+find|couldn'?t\s+find|where\s+is)[^\n]{0,40}?mutagent-cli\s+(?:binary|executable|command)/i,
+      /mutagent-cli\s+(?:binary|executable|command)[^\n]{0,60}?(?:missing|not\s+found|doesn'?t\s+exist|does\s+not\s+exist|not\s+installed)/i,
+      new RegExp(String.raw`no\s+mutagent-cli[^\n]{0,40}?in\s+@mutagent\/cli`, "i")
+    ],
+    reality: "mutagent and mutagent-cli are separate binaries that come from separate packages. @mutagent/cli provides the mutagent binary only — account, configuration, and installation commands. The mutagent-cli binary ships with the diagnostics and evaluator packages and carries the trace tooling. Having both installed is normal and expected."
+  }
+];
+function matchByDesign(draft) {
+  if (!draft)
+    return [];
+  return BY_DESIGN_ENTRIES.filter((entry) => entry.looksLike.some((pattern) => pattern.test(draft)));
+}
+
+// src/lib/feedback-safety.ts
+function sanitizeTranscript(transcript) {
+  const { content, matches } = redactSecrets(transcript.content);
+  return {
+    transcript: { ...transcript, content },
+    redactions: matches
+  };
+}
+function buildPreview(transcript) {
+  return {
+    fileCount: 1,
+    bytes: Buffer.byteLength(transcript.content, "utf-8"),
+    sourcePath: transcript.sourcePath,
+    truncated: transcript.truncated
+  };
+}
+function buildTranscriptWarning(preview) {
+  const kb = (preview.bytes / 1024).toFixed(1);
+  return [
+    chalk16.yellow("⚠ About to upload your coding-agent session transcript."),
+    `  ${chalk16.bold("Source:")}  ${preview.sourcePath}`,
+    `  ${chalk16.bold("Sending:")} ${String(preview.fileCount)} file, ${kb} KB${preview.truncated ? " (tail only)" : ""}`,
+    "",
+    "  A session transcript typically contains:",
+    "    • source code and file contents you or the agent opened",
+    "    • absolute file paths, including your username and directory layout",
+    "    • branch names, commit messages, and repository names",
+    "    • internal hostnames, service names, and URLs",
+    "    • business context from your prompts and the agent replies",
+    "",
+    `  ${chalk16.dim("Credentials are scanned for and redacted automatically, but detection")}`,
+    `  ${chalk16.dim("is best-effort — review the source file if the session touched secrets.")}`,
+    `  ${chalk16.dim("Omit --attach-transcript to send feedback without it.")}`
+  ].join(`
+`);
+}
+function buildRedactionReport(redactions) {
+  if (redactions.length === 0)
+    return "";
+  const byKind = new Map;
+  for (const match of redactions) {
+    byKind.set(match.label, (byKind.get(match.label) ?? 0) + 1);
+  }
+  const lines = [
+    chalk16.green(`✓ Redacted ${String(redactions.length)} credential${redactions.length === 1 ? "" : "s"} from the transcript before upload:`)
+  ];
+  for (const [label, count] of byKind) {
+    lines.push(`    • ${label} ×${String(count)}`);
+  }
+  lines.push(chalk16.dim("  These were replaced with [REDACTED:…] markers and never left your machine."));
+  return lines.join(`
+`);
+}
+function buildByDesignNotice(entries) {
+  if (entries.length === 0)
+    return "";
+  const lines = [
+    chalk16.cyan("ℹ Heads up — this may describe intended behaviour:"),
+    ""
+  ];
+  for (const entry of entries) {
+    lines.push(`  ${chalk16.bold(entry.title)}`);
+    for (const line of wrap(entry.reality, 76)) {
+      lines.push(`    ${line}`);
+    }
+    lines.push("");
+  }
+  lines.push(chalk16.dim("  Sending anyway — if this is a regression rather than the design,"), chalk16.dim("  your report is exactly what we need. Nothing was withheld."));
+  return lines.join(`
+`);
+}
+function findByDesignMatches(draft) {
+  return matchByDesign(draft);
+}
+function wrap(text, width) {
+  const words = text.split(/\s+/);
+  const lines = [];
+  let current = "";
+  for (const word of words) {
+    if (current.length === 0) {
+      current = word;
+    } else if (current.length + 1 + word.length <= width) {
+      current += ` ${word}`;
+    } else {
+      lines.push(current);
+      current = word;
+    }
+  }
+  if (current.length > 0)
+    lines.push(current);
+  return lines;
+}
+
 // src/commands/feedback.ts
 var MAX_FEEDBACK_LENGTH = 1e4;
 var VALID_STAGES = ["spec", "build", "evaluate", "diagnose", "optimize"];
@@ -5259,7 +5691,7 @@ function getCliVersion() {
     return process.env.CLI_VERSION;
   try {
     const __dirname2 = dirname2(fileURLToPath(import.meta.url));
-    const pkgPath = join12(__dirname2, "..", "..", "package.json");
+    const pkgPath = join13(__dirname2, "..", "..", "package.json");
     const pkg = JSON.parse(readFileSync9(pkgPath, "utf-8"));
     return pkg.version ?? "0.1.1";
   } catch {
@@ -5336,14 +5768,18 @@ function buildPayload(feedback, category, title, session, transcript) {
 }
 function createFeedbackCommand() {
   const feedback = new Command10("feedback").description("Send product feedback to Mutagent").addHelpText("after", `
-${chalk16.bold("Examples:")}
-  ${chalk16.cyan('mutagent feedback send "Optimizer results were great"')}
-  ${chalk16.cyan('mutagent feedback send "Eval gate was confusing" --category stage:evaluate')}
-  ${chalk16.cyan('mutagent feedback send "CLI crashed on export" --category cli --attach-transcript --json')}
+${chalk17.bold("Examples:")}
+  ${chalk17.cyan('mutagent feedback send "Optimizer results were great"')}
+  ${chalk17.cyan('mutagent feedback send "Eval gate was confusing" --category stage:evaluate')}
+  ${chalk17.cyan('mutagent feedback send "CLI crashed on export" --category cli --json')}
 
-${chalk16.yellow("AI Agent (MANDATORY):")}
+${chalk17.yellow("AI Agent (MANDATORY):")}
   ALWAYS use --json: mutagent feedback send "..." --category cli --json
-  Attach the coding-agent session with --attach-transcript (auto-detects the newest session).
+  ${chalk17.yellow("Do NOT attach a transcript by default.")} --attach-transcript uploads the
+  coding-agent SESSION JSONL — source code, absolute paths, branch and repository
+  names, internal hostnames, and the business context of the operator's prompts.
+  Use it only when the operator explicitly asks for it. See:
+  ${chalk17.dim("mutagent feedback send --help")}
     `).action(() => {
     feedback.help();
   });
@@ -5352,33 +5788,39 @@ ${chalk16.yellow("AI Agent (MANDATORY):")}
 }
 function registerFeedbackSend(feedback) {
   feedback.command("send").description("Send product feedback about the Mutagent platform or CLI").argument("<feedback>", "The feedback body (content), max 10000 characters").option("--title <string>", "Optional 5–8 word summary of the session timeline").option("--category <value>", `Feedback category: 'cli', 'helix', or 'stage:<${VALID_STAGES.join("|")}>'`, "cli").option("--session <id>", "Link this feedback to a session id (maps to server sessionId)").option("--attach-transcript [path]", "Attach the coding-agent session JSONL. Bare = auto-detect newest; or pass an explicit path.").addHelpText("after", `
-${chalk16.bold("Arguments & flags:")}
-  ${chalk16.bold("<feedback>")}              Feedback body / content (required, ≤10000 chars)
-  ${chalk16.bold("--title <string>")}        Optional 5–8 word summary of the session timeline
-  ${chalk16.bold("--category <value>")}      ${chalk16.bold("cli")} (default) | ${chalk16.bold("helix")} | ${chalk16.bold("stage:<")}${VALID_STAGES.join("|")}${chalk16.bold(">")}
-                          ${chalk16.dim("stage = the lifecycle skill (evaluator/diagnostics live under stage:*)")}
-  ${chalk16.bold("--session <id>")}          Link feedback to a session id (server sessionId)
-  ${chalk16.bold("--attach-transcript")} ${chalk16.dim("[path]")}  Attach the coding-agent session JSONL (bare = auto-detect newest)
-  ${chalk16.bold("--json")}                  Structured output (MANDATORY for AI agents)
-
-${chalk16.bold("Examples:")}
-  ${chalk16.dim("$")} mutagent feedback send "The setup flow could show progress better"
-  ${chalk16.dim("$")} mutagent feedback send "Eval gate was confusing" --category stage:evaluate --title "eval gate unclear"
-  ${chalk16.dim("$")} mutagent feedback send "Diagnose loop stalled" --category stage:diagnose --session sess_abc123 --json
-  ${chalk16.dim("$")} mutagent feedback send "CLI crashed mid-run" --category cli --attach-transcript --json
-  ${chalk16.dim("$")} mutagent feedback send "Repro attached" --category cli --attach-transcript /tmp/session.jsonl
-
-${chalk16.bold("Category:")}
-  ${chalk16.bold("cli")}            Feedback about the CLI itself (default)
-  ${chalk16.bold("helix")}          Feedback about Helix
-  ${chalk16.bold("stage:<x>")}      Feedback about a lifecycle stage: ${VALID_STAGES.join(", ")}
-
-${chalk16.bold("Transcript (--attach-transcript):")}
+${chalk17.bold("Arguments & flags:")}
+  ${chalk17.bold("<feedback>")}              Feedback body / content (required, ≤10000 chars)
+  ${chalk17.bold("--title <string>")}        Optional 5–8 word summary of the session timeline
+  ${chalk17.bold("--category <value>")}      ${chalk17.bold("cli")} (default) | ${chalk17.bold("helix")} | ${chalk17.bold("stage:<")}${VALID_STAGES.join("|")}${chalk17.bold(">")}
+                          ${chalk17.dim("stage = the lifecycle skill (evaluator/diagnostics live under stage:*)")}
+  ${chalk17.bold("--session <id>")}          Link feedback to a session id (server sessionId)
+  ${chalk17.bold("--attach-transcript")} ${chalk17.dim("[path]")}  Attach the coding-agent session JSONL (bare = auto-detect newest)
+  ${chalk17.bold("--json")}                  Structured output (MANDATORY for AI agents)
+
+${chalk17.bold("Examples:")}
+  ${chalk17.dim("$")} mutagent feedback send "The setup flow could show progress better"
+  ${chalk17.dim("$")} mutagent feedback send "Eval gate was confusing" --category stage:evaluate --title "eval gate unclear"
+  ${chalk17.dim("$")} mutagent feedback send "Diagnose loop stalled" --category stage:diagnose --session sess_abc123 --json
+  ${chalk17.dim("$")} mutagent feedback send "CLI crashed mid-run" --category cli --attach-transcript --json
+  ${chalk17.dim("$")} mutagent feedback send "Repro attached" --category cli --attach-transcript /tmp/session.jsonl
+
+${chalk17.bold("Category:")}
+  ${chalk17.bold("cli")}            Feedback about the CLI itself (default)
+  ${chalk17.bold("helix")}          Feedback about Helix
+  ${chalk17.bold("stage:<x>")}      Feedback about a lifecycle stage: ${VALID_STAGES.join(", ")}
+
+${chalk17.bold("Transcript (--attach-transcript):")}
   Uploads your coding-agent SESSION JSONL as context (raw last-200KB tail) — a
   SEPARATE artifact from the feedback body. Bare flag auto-detects the newest
   session across claude-code, codex, and omp; explicit path overrides.
 
-${chalk16.yellow("AI Agent (MANDATORY):")}
+  ${chalk17.yellow("A session transcript contains source code, absolute paths (including your")}
+  ${chalk17.yellow("username), branch and repository names, internal hostnames, and the business")}
+  ${chalk17.yellow("context of your prompts.")} Credentials are scanned for and redacted before
+  upload, and the exact size + source path are printed before the network call.
+  Detection is best-effort — omit the flag if the session handled secrets.
+
+${chalk17.yellow("AI Agent (MANDATORY):")}
   ALWAYS use --json: mutagent feedback send "..." --json
   Auto-captured context (harness, CLI version, platform, OS, node version) is included automatically.
     `).action(async (feedbackBody, options) => {
@@ -5394,7 +5836,26 @@ ${chalk16.yellow("AI Agent (MANDATORY):")}
         throw new MutagentError("AUTH_REQUIRED", "Authentication required to send feedback.", `Authenticate first: mutagent auth login
 Or set an API key: mutagent config set apiKey <key>`);
       }
-      const transcript = resolveTranscript(options.attachTranscript);
+      const byDesign = findByDesignMatches(feedbackBody);
+      if (byDesign.length > 0 && !isJson) {
+        console.log(buildByDesignNotice(byDesign));
+      }
+      const rawTranscript = resolveTranscript(options.attachTranscript);
+      let transcript = null;
+      let redactions = [];
+      if (rawTranscript) {
+        const safe = sanitizeTranscript(rawTranscript);
+        transcript = safe.transcript;
+        redactions = safe.redactions;
+        const preview = buildPreview(transcript);
+        if (!isJson) {
+          console.log(buildTranscriptWarning(preview));
+          const report = buildRedactionReport(redactions);
+          if (report)
+            console.log(report);
+          console.log("");
+        }
+      }
       const payload = buildPayload(feedbackBody, category, options.title, options.session, transcript);
       const config = loadConfig();
       const endpoint = config.endpoint ?? "https://api.mutagent.io";
@@ -5407,12 +5868,24 @@ Or set an API key: mutagent config set apiKey <key>`);
           title: options.title,
           sessionId: options.session,
           transcriptAttached: transcript !== null,
+          ...transcript ? {
+            transcriptBytes: Buffer.byteLength(transcript.content, "utf-8"),
+            transcriptSource: transcript.sourcePath,
+            redactions: redactions.map((r) => ({ kind: r.kind, line: r.line }))
+          } : {},
+          ...byDesign.length > 0 ? {
+            byDesignMatches: byDesign.map((e) => ({
+              id: e.id,
+              title: e.title,
+              reality: e.reality
+            }))
+          } : {},
           _links: {
             send: "mutagent feedback send <feedback> [--title <s>] [--category cli|helix|stage:<x>] [--session <id>] [--attach-transcript [path]]"
           }
         });
       } else {
-        const suffix = transcript ? ` + transcript (${String(TAIL_BYTES)}B tail${transcript.truncated ? ", truncated" : ""})` : "";
+        const suffix = transcript ? ` + transcript (${String(Buffer.byteLength(transcript.content, "utf-8"))}B${transcript.truncated ? ` tail, truncated at ${String(TAIL_BYTES)}B cap` : ""})` : "";
         output.success(`Feedback sent! (${category})${suffix}`);
       }
     } catch (error) {
@@ -5423,33 +5896,38 @@ Or set an API key: mutagent config set apiKey <key>`);
 
 // src/commands/install/index.ts
 import { Command as Command11 } from "commander";
-import chalk17 from "chalk";
+import chalk18 from "chalk";
 init_errors();
 function createInstallCommand(deps) {
-  const install = new Command11("install").description("Install a Mutagent package (helix, diagnostics, evaluator)").argument("<package>", `Package to install: ${VALID_PACKAGES.join(", ")}`).option("--harness <harness>", `Target harness: ${VALID_HARNESSES.join(", ")}`, "claude-code").option("--global", "Install to ~/.claude instead of this project", false).option("--version <version>", "Package version to install (default: latest)").addHelpText("after", `
-${chalk17.bold("Arguments & flags:")}
-  ${chalk17.bold("<package>")}            ${VALID_PACKAGES.join(" | ")}
-  ${chalk17.bold("--harness <h>")}        ${VALID_HARNESSES.join(" | ")} ${chalk17.dim("(default: claude-code)")}
-  ${chalk17.bold("--global")}             Install to ~/.claude ${chalk17.dim("(default: this project)")}
-  ${chalk17.bold("--version <v>")}        Pin a package version ${chalk17.dim("(default: latest)")}
-  ${chalk17.bold("--json")}               Structured output
-
-${chalk17.bold("Examples:")}
-  ${chalk17.dim("$")} mutagent install helix
-  ${chalk17.dim("$")} mutagent install helix --harness codex
-  ${chalk17.dim("$")} mutagent install diagnostics
-  ${chalk17.dim("$")} mutagent install evaluator --version 1.2.3
-  ${chalk17.dim("$")} mutagent install diagnostics --harness codex --json
-
-${chalk17.bold("Packages:")}
-  ${chalk17.bold("helix")}        ${chalk17.green("(available)")} — the ADLC (Agent Development Life Cycle Orchestrator). Downloaded from a private
+  const install = new Command11("install").description("Install a Mutagent package (helix, diagnostics, evaluator)").argument("<package>", `Package to install: ${VALID_PACKAGES.join(", ")}`).option("--harness <harness>", `Target harness: ${VALID_HARNESSES.join(", ")}`, "claude-code").option("--global", "(retired) Install scope is fixed per package").option("--version <version>", "Package version to install (default: latest)").addHelpText("after", `
+${chalk18.bold("Arguments & flags:")}
+  ${chalk18.bold("<package>")}            ${VALID_PACKAGES.join(" | ")}
+  ${chalk18.bold("--harness <h>")}        ${VALID_HARNESSES.join(" | ")} ${chalk18.dim("(default: claude-code)")}
+  ${chalk18.bold("--version <v>")}        Pin a package version ${chalk18.dim("(default: latest)")}
+  ${chalk18.bold("--json")}               Structured output
+
+${chalk18.bold("Install scope")} ${chalk18.dim("(fixed per package — not selectable)")}:
+  ${chalk18.bold("helix")}                    → installed into the current directory
+  ${chalk18.bold("diagnostics")} | ${chalk18.bold("evaluator")}  → ${chalk18.yellow("installed GLOBALLY")} by npm; run the
+                             package's own init from your project afterwards.
+  ${chalk18.dim("--global")} is retired: scope is no longer a choice.
+
+${chalk18.bold("Examples:")}
+  ${chalk18.dim("$")} mutagent install helix
+  ${chalk18.dim("$")} mutagent install helix --harness codex
+  ${chalk18.dim("$")} mutagent install diagnostics
+  ${chalk18.dim("$")} mutagent install evaluator --version 1.2.3
+  ${chalk18.dim("$")} mutagent install diagnostics --harness codex --json
+
+${chalk18.bold("Packages:")}
+  ${chalk18.bold("helix")}        ${chalk18.green("(available)")} — the ADLC (Agent Development Life Cycle Orchestrator). Downloaded from a private
                  registry via a login-brokered signed URL, sha256-verified, then
                  initialized into your project. No static secret ships in the CLI.
-                 ${chalk17.dim("Installs every harness itself (Claude + Codex) — --harness does not apply.")}
-  ${chalk17.bold("diagnostics")}  Public npm package @mutagent/diagnostics ${chalk17.green("(available)")}
-  ${chalk17.bold("evaluator")}    Public npm package @mutagent/evaluator ${chalk17.green("(available)")}
+                 ${chalk18.dim("Installs every harness itself (Claude + Codex) — --harness does not apply.")}
+  ${chalk18.bold("diagnostics")}  Public npm package @mutagent/diagnostics ${chalk18.green("(available)")}
+  ${chalk18.bold("evaluator")}    Public npm package @mutagent/evaluator ${chalk18.green("(available)")}
 
-${chalk17.yellow("Note:")} install is login-gated. Run ${chalk17.cyan("mutagent login")} first (else exits with a login directive).
+${chalk18.yellow("Note:")} install is login-gated. Run ${chalk18.cyan("mutagent login")} first (else exits with a login directive).
     `).action(async (pkg, options) => {
     const isJson = getJsonFlag(install);
     const output = new OutputFormatter(isJson ? "json" : "table");
@@ -5461,14 +5939,23 @@ ${chalk17.yellow("Note:")} install is login-gated. Run ${chalk17.cyan("mutagent
           package: result.package,
           version: result.version,
           harness: result.harness,
-          global: result.global,
+          scope: result.scope,
+          ...result.projectPath ? { projectPath: result.projectPath } : {},
+          skillInstalled: result.skillInstalled,
+          ...result.nextStep ? { nextStep: result.nextStep } : {},
           _links: {
             install: "mutagent install <package> [--harness <h>] [--version <v>]",
             login: "mutagent login"
           }
         });
+      } else if (result.skillInstalled) {
+        output.success(`Installed ${result.package}@${result.version} for ${result.harness} in ${result.projectPath ?? "this project"}`);
       } else {
-        output.success(`Installed ${result.package}@${result.version} for ${result.harness}` + (result.command ? ` (${result.command})` : ""));
+        output.success(`Installed npm package ${result.package}@${result.version} globally` + (result.command ? ` (${result.command})` : ""));
+        console.log(`${chalk18.yellow("⚠")} No skill was installed yet — the package ships its own setup step.`);
+        if (result.nextStep) {
+          console.log(`${chalk18.blue("→")} Run next: ${chalk18.cyan(result.nextStep)}`);
+        }
       }
     } catch (error) {
       handleError(error, isJson);
@@ -5477,6 +5964,28 @@ ${chalk17.yellow("Note:")} install is login-gated. Run ${chalk17.cyan("mutagent
   return install;
 }
 
+// src/commands/trace.ts
+import { Command as Command12 } from "commander";
+init_errors();
+var TRACE_RELOCATION_HINT = "trace lives in the `mutagent-cli` binary, installed with @mutagent/diagnostics, @mutagent/evaluator or helix";
+function createTraceCommand() {
+  const trace = new Command12("trace").description("Not in this binary — trace lives in mutagent-cli").allowUnknownOption(true).allowExcessArguments(true).argument("[args...]", "Arguments intended for `mutagent-cli trace`").addHelpText("after", `
+This binary (mutagent) does not provide trace.
+
+  ${TRACE_RELOCATION_HINT}
+
+Install one of those, then run:
+
+  mutagent-cli trace <args>
+`).action((args) => {
+    const isJson = getJsonFlag(trace);
+    const forwarded = args.length > 0 ? ` ${args.join(" ")}` : " <args>";
+    handleError(new MutagentError("INVALID_ARGUMENTS", `\`mutagent trace\` is not a command — ${TRACE_RELOCATION_HINT}.`, `Run it with the other binary instead: mutagent-cli trace${forwarded}
+If mutagent-cli is not installed: mutagent install diagnostics`), isJson);
+  });
+  return trace;
+}
+
 // src/bin/cli.ts
 init_config();
 
@@ -5553,13 +6062,13 @@ if (process.env.CLI_VERSION) {
 } else {
   try {
     const __dirname2 = dirname3(fileURLToPath2(import.meta.url));
-    const pkgPath = join13(__dirname2, "..", "..", "package.json");
+    const pkgPath = join14(__dirname2, "..", "..", "package.json");
     const pkg = JSON.parse(readFileSync10(pkgPath, "utf-8"));
     cliVersion = pkg.version ?? cliVersion;
   } catch {}
 }
 setCliVersion(cliVersion);
-var program = new Command12;
+var program = new Command13;
 program.name("mutagent").description(`Mutagent CLI - command-line client for the Mutagent platform
 
   Documentation: https://docs.mutagent.io/cli
@@ -5569,52 +6078,52 @@ program.name("mutagent").description(`Mutagent CLI - command-line client for the
 });
 program.addHelpText("beforeAll", () => renderBanner());
 program.addHelpText("after", `
-${chalk18.bold.cyan("WORKFLOWS:")}
-  ${chalk18.bold("Setup")}                mutagent login  →  mutagent init
-  ${chalk18.bold("Lifecycle Tools")}      mutagent install <helix|diagnostics|evaluator>  ${chalk18.dim("(login-gated)")}
-  ${chalk18.bold("Feedback")}             mutagent feedback send "<what happened>" --category <cli|helix|stage:<x>>  ${chalk18.dim("[--session <id>] [--attach-transcript]")}
-
-${chalk18.dim("For CLI usage guidance for AI agents, see the Skill at")}
-${chalk18.cyan(".claude/skills/mutagent-cli/SKILL.md")}
-
-${chalk18.yellow("Non-Interactive Mode (CI/CD & Coding Agents):")}
-  export MUTAGENT_API_KEY=mt_...  ${chalk18.dim("or")}  --api-key mt_...
-  --json ${chalk18.dim("for structured output")}    --non-interactive ${chalk18.dim("to disable prompts")}
-
-${chalk18.yellow("Command Navigation:")}
-  mutagent login                        ${chalk18.dim("Login (browser OAuth — recommended)")}
-  mutagent auth status                  ${chalk18.dim("Check auth + workspace")}
-  mutagent init                         ${chalk18.dim("Initialize project (.mutagentrc.json)")}
-  mutagent workspaces list --json       ${chalk18.dim("List workspaces (verify ID)")}
-  mutagent config set workspace <id>    ${chalk18.dim("Set active workspace")}
-  mutagent usage --json                 ${chalk18.dim("Show account usage + provider status")}
-
-  mutagent providers list --json        ${chalk18.dim("List configured BYOK providers")}
-  mutagent providers list --models      ${chalk18.dim("See available models per provider")}
-
-  mutagent install helix                ${chalk18.dim("Install the ADL lifecycle conductor (login-gated)")}
-  mutagent install evaluator --version 1.2.3  ${chalk18.dim("Pin a version")}
-  mutagent install --help               ${chalk18.dim("helix | diagnostics | evaluator")}
-
-  mutagent hooks --help                 ${chalk18.dim("Hook setup for Claude Code session telemetry upload")}
-
-${chalk18.bold.red("Report Issues:")}
-  Hit a bug? Run: ${chalk18.cyan('mutagent feedback send "describe what went wrong" --category cli')}
-  Lifecycle-stage feedback: ${chalk18.cyan('mutagent feedback send "eval gate unclear" --category stage:evaluate')}
-  Link to a session: ${chalk18.cyan('mutagent feedback send "..." --session <session-id>')}
-  Attach your coding-agent session transcript: ${chalk18.cyan('mutagent feedback send "..." --attach-transcript')}
-  ${chalk18.dim("--category accepts: cli | helix | stage:<spec|build|evaluate|diagnose|optimize>")}
-
-${chalk18.yellow("Directive System:")}
+${chalk19.bold.cyan("WORKFLOWS:")}
+  ${chalk19.bold("Setup")}                mutagent login  →  mutagent init
+  ${chalk19.bold("Lifecycle Tools")}      mutagent install <helix|diagnostics|evaluator>  ${chalk19.dim("(login-gated)")}
+  ${chalk19.bold("Feedback")}             mutagent feedback send "<what happened>" --category <cli|helix|stage:<x>>  ${chalk19.dim("[--session <id>] [--attach-transcript]")}
+
+${chalk19.dim("For CLI usage guidance for AI agents, see the Skill at")}
+${chalk19.cyan(".claude/skills/mutagent-cli/SKILL.md")}
+
+${chalk19.yellow("Non-Interactive Mode (CI/CD & Coding Agents):")}
+  export MUTAGENT_API_KEY=mt_...  ${chalk19.dim("or")}  --api-key mt_...
+  --json ${chalk19.dim("for structured output")}    --non-interactive ${chalk19.dim("to disable prompts")}
+
+${chalk19.yellow("Command Navigation:")}
+  mutagent login                        ${chalk19.dim("Login (browser OAuth — recommended)")}
+  mutagent auth status                  ${chalk19.dim("Check auth + workspace")}
+  mutagent init                         ${chalk19.dim("Initialize project (.mutagentrc.json)")}
+  mutagent workspaces list --json       ${chalk19.dim("List workspaces (verify ID)")}
+  mutagent config set workspace <id>    ${chalk19.dim("Set active workspace")}
+  mutagent usage --json                 ${chalk19.dim("Show account usage + provider status")}
+
+  mutagent providers list --json        ${chalk19.dim("List configured BYOK providers")}
+  mutagent providers list --models      ${chalk19.dim("See available models per provider")}
+
+  mutagent install helix                ${chalk19.dim("Install the ADL lifecycle conductor (login-gated)")}
+  mutagent install evaluator --version 1.2.3  ${chalk19.dim("Pin a version")}
+  mutagent install --help               ${chalk19.dim("helix | diagnostics | evaluator")}
+
+  mutagent hooks --help                 ${chalk19.dim("Hook setup for Claude Code session telemetry upload")}
+
+${chalk19.bold.red("Report Issues:")}
+  Hit a bug? Run: ${chalk19.cyan('mutagent feedback send "describe what went wrong" --category cli')}
+  Lifecycle-stage feedback: ${chalk19.cyan('mutagent feedback send "eval gate unclear" --category stage:evaluate')}
+  Link to a session: ${chalk19.cyan('mutagent feedback send "..." --session <session-id>')}
+  Attach your coding-agent session transcript: ${chalk19.cyan('mutagent feedback send "..." --attach-transcript')}
+  ${chalk19.dim("--category accepts: cli | helix | stage:<spec|build|evaluate|diagnose|optimize>")}
+
+${chalk19.yellow("Directive System:")}
   Every --json response may include:
-  ${chalk18.bold("_directive.display")}      Type tag — 'status_card' for card-kind directives (drives test/docs guards)
-  ${chalk18.bold("_directive.renderedCard")} Pre-formatted card ${chalk18.red("(MUST echo verbatim in chat whenever this field exists — see SKILL.md Verbatim Card Display Protocol)")}
-  ${chalk18.bold("_directive.instruction")}  Next step for the agent (self-sufficient, no Skill required)
-  ${chalk18.bold("_directive.next")}         Array of suggested follow-up commands
-  ${chalk18.bold("_links")}                  Dashboard/API URLs (format as markdown links)
-  ${chalk18.bold("_compat")}                 Compat metadata: cliVersion, skillVersion, skillMinCliVersion
-
-${chalk18.yellow("AI Agent Rules (MANDATORY for coding agents):")}
+  ${chalk19.bold("_directive.display")}      Type tag — 'status_card' for card-kind directives (drives test/docs guards)
+  ${chalk19.bold("_directive.renderedCard")} Pre-formatted card ${chalk19.red("(MUST echo verbatim in chat whenever this field exists — see SKILL.md Verbatim Card Display Protocol)")}
+  ${chalk19.bold("_directive.instruction")}  Next step for the agent (self-sufficient, no Skill required)
+  ${chalk19.bold("_directive.next")}         Array of suggested follow-up commands
+  ${chalk19.bold("_links")}                  Dashboard/API URLs (format as markdown links)
+  ${chalk19.bold("_compat")}                 Compat metadata: cliVersion, skillVersion, skillMinCliVersion
+
+${chalk19.yellow("AI Agent Rules (MANDATORY for coding agents):")}
   1. Login (two paths):
      - CI / fully automated: export MUTAGENT_API_KEY=mt_... then mutagent login --json
      - Helping a user onboard: mutagent login --browser --json
@@ -5624,13 +6133,13 @@ ${chalk18.yellow("AI Agent Rules (MANDATORY for coding agents):")}
   2. EVERY command MUST include --json (no exceptions)
   3. Run <command> --help BEFORE first use of any command
   4. Parse _directive.renderedCard and copy it into your CHAT RESPONSE verbatim
-     ${chalk18.red("HARD STOP")}: do NOT run further commands until the card is rendered in chat
+     ${chalk19.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. ALL user interaction via AskUserQuestion — CLI is non-interactive
 ${!hasCredentials() ? `
-` + chalk18.yellow("  Warning: Not authenticated. Run: mutagent login") + `
+` + chalk19.yellow("  Warning: Not authenticated. Run: mutagent login") + `
 ` : ""}${!hasRcConfig() ? `
-` + chalk18.green("  Get started: mutagent init") + `
+` + chalk19.green("  Get started: mutagent init") + `
 ` : ""}`);
 var rawArgs = process.argv.slice(2);
 if (rawArgs.includes("-v") || rawArgs.includes("--version")) {
@@ -5667,7 +6176,8 @@ program.addCommand(createUsageCommand());
 program.addCommand(createHooksCommand());
 program.addCommand(createInstallCommand());
 program.addCommand(createFeedbackCommand());
+program.addCommand(createTraceCommand());
 program.parse();
 
-//# debugId=270F5210E72B26F864756E2164756E21
+//# debugId=EB9C87E26AFCFB5064756E2164756E21
 //# sourceMappingURL=cli.js.map