@arvoretech/hub 0.16.0 → 0.17.0

package/dist/{chunk-ALJAZQ33.js → chunk-Z4AZNX6V.js}

@@ -3,10 +3,10 @@ import {
 } from "./chunk-VMN4KGAK.js";
 
 // src/commands/generate.ts
-import { Command } from "commander";
-import { existsSync as existsSync2 } from "fs";
-import { mkdir as mkdir3, writeFile as writeFile3, readdir as readdir2, copyFile, readFile as readFile3, cp, rm } from "fs/promises";
-import { join as join3, resolve as resolve2 } from "path";
+import { Command as Command2 } from "commander";
+import { existsSync as existsSync3 } from "fs";
+import { mkdir as mkdir4, writeFile as writeFile4, readdir as readdir2, copyFile, readFile as readFile4, cp, rm } from "fs/promises";
+import { join as join4, resolve as resolve2 } from "path";
 import chalk3 from "chalk";
 import inquirer from "inquirer";
 
@@ -117,7 +117,7 @@ async function checkAndAutoRegenerate(hubDir) {
       return;
     }
     console.log(chalk.yellow("\n  Detected outdated configs, auto-regenerating..."));
-    const { generators: generators2 } = await import("./generate-YJEPLTSQ.js");
+    const { generators: generators2 } = await import("./generate-TBAEF7R5.js");
     const generator = generators2[result.editor];
     if (!generator) {
       console.log(chalk.red(`  Unknown editor '${result.editor}' in cache. Run 'hub generate' manually.`));
@@ -390,6 +390,337 @@ async function fetchRemoteSources(sources, hubDir, skillsDir, steeringDir) {
   return { skills: skillCount, steering: steeringCount, errors };
 }
 
+// src/commands/persona.ts
+import { Command } from "commander";
+import { join as join3 } from "path";
+import { readFile as readFile3, writeFile as writeFile3, mkdir as mkdir3 } from "fs/promises";
+import { existsSync as existsSync2 } from "fs";
+import React from "react";
+import { render } from "ink";
+
+// src/tui/PersonaApp.tsx
+import { useState, useCallback } from "react";
+import { Box, Text, useInput, useStdout, useApp } from "ink";
+import TextInput from "ink-text-input";
+
+// src/tui/theme.ts
+var colors = {
+  brand: "#22c55e",
+  brandDim: "#16a34a",
+  blue: "#3b82f6",
+  purple: "#a78bfa",
+  muted: "#6b7280",
+  dim: "#4b5563",
+  warning: "#eab308",
+  error: "#ef4444",
+  white: "#ffffff"
+};
+var symbols = {
+  check: "\u2713",
+  cross: "\u2717",
+  arrow: "\u276F",
+  dot: "\u25CF",
+  circle: "\u25CB",
+  tree: "\u{1F333}",
+  line: "\u2500",
+  corner: "\u256D",
+  cornerEnd: "\u2570",
+  vertical: "\u2502",
+  cornerRight: "\u256E",
+  cornerEndRight: "\u256F"
+};
+function horizontalLine(width) {
+  return symbols.line.repeat(width);
+}
+
+// src/tui/PersonaApp.tsx
+import { jsx, jsxs } from "react/jsx-runtime";
+var TECHNICAL_LEVELS = [
+  { value: "non-technical", label: "Non-technical", description: "No coding experience \u2014 CEO, PM, designer, etc." },
+  { value: "beginner", label: "Beginner", description: "Learning to code or just started working with devs" },
+  { value: "intermediate", label: "Intermediate", description: "Comfortable with code, still learning some tools" },
+  { value: "advanced", label: "Advanced", description: "Experienced developer, knows the stack well" }
+];
+var STEP_INFO = {
+  name: { title: "What's your name?", subtitle: "So the AI knows who it's talking to." },
+  role: { title: "What's your role?", subtitle: "e.g. CEO, Product Manager, Designer, Backend Dev, QA Engineer..." },
+  technical_level: { title: "How technical are you?", subtitle: "This changes how the AI explains things to you." },
+  context: { title: "Anything else the AI should know about you?", subtitle: `e.g. "I focus on business metrics", "I only work on the mobile app", "I review PRs but don't code"` },
+  language: { title: "What language should the AI use?", subtitle: "e.g. English, Portugu\xEAs, Espa\xF1ol..." }
+};
+function PersonaApp({ existing, onComplete }) {
+  const { stdout } = useStdout();
+  const { exit } = useApp();
+  const width = Math.min(stdout?.columns || 80, 80);
+  const CLEAR2 = "\x1B[2J\x1B[H";
+  const [step, setStep] = useState("name");
+  const [data, setData] = useState({
+    name: existing?.name || "",
+    role: existing?.role || "",
+    context: existing?.context || "",
+    technical_level: existing?.technical_level || "intermediate",
+    language: existing?.language || "English"
+  });
+  const [inputValue, setInputValue] = useState(existing?.name || "");
+  const [levelCursor, setLevelCursor] = useState(
+    TECHNICAL_LEVELS.findIndex((l) => l.value === (existing?.technical_level || "intermediate"))
+  );
+  const goTo = useCallback((next) => {
+    stdout?.write(CLEAR2);
+    setStep(next);
+  }, [stdout]);
+  const handleTextSubmit = useCallback((value, field, next) => {
+    if (!value.trim()) return;
+    setData((prev) => ({ ...prev, [field]: value.trim() }));
+    setInputValue("");
+    goTo(next);
+  }, [goTo]);
+  useInput((input, key) => {
+    if (step === "technical_level") {
+      if (key.upArrow) setLevelCursor((p) => p > 0 ? p - 1 : TECHNICAL_LEVELS.length - 1);
+      if (key.downArrow) setLevelCursor((p) => p < TECHNICAL_LEVELS.length - 1 ? p + 1 : 0);
+      if (key.return) {
+        setData((prev) => ({ ...prev, technical_level: TECHNICAL_LEVELS[levelCursor].value }));
+        setInputValue(data.context || "");
+        goTo("context");
+      }
+    }
+    if (step === "review") {
+      if (key.return || input === "y") {
+        onComplete(data);
+        goTo("done");
+      }
+      if (input === "b" || key.leftArrow) {
+        setInputValue(data.name);
+        goTo("name");
+      }
+    }
+    if (step === "done" && key.return) {
+      exit();
+    }
+  });
+  const info = STEP_INFO[step];
+  return /* @__PURE__ */ jsxs(Box, { flexDirection: "column", width, children: [
+    /* @__PURE__ */ jsxs(Box, { marginBottom: 1, children: [
+      /* @__PURE__ */ jsxs(Text, { color: colors.brand, bold: true, children: [
+        symbols.tree,
+        " Repo Hub"
+      ] }),
+      /* @__PURE__ */ jsxs(Text, { color: colors.dim, children: [
+        " ",
+        symbols.line,
+        " Persona Setup"
+      ] })
+    ] }),
+    info && /* @__PURE__ */ jsxs(Box, { flexDirection: "column", marginBottom: 1, paddingLeft: 1, children: [
+      /* @__PURE__ */ jsx(Text, { color: colors.white, bold: true, children: info.title }),
+      /* @__PURE__ */ jsx(Text, { color: colors.dim, children: info.subtitle })
+    ] }),
+    /* @__PURE__ */ jsxs(Box, { flexDirection: "column", paddingLeft: 2, children: [
+      step === "name" && /* @__PURE__ */ jsxs(Box, { children: [
+        /* @__PURE__ */ jsx(Text, { color: colors.brand, bold: true, children: "\u276F " }),
+        /* @__PURE__ */ jsx(
+          TextInput,
+          {
+            value: inputValue,
+            onChange: setInputValue,
+            onSubmit: (v) => {
+              handleTextSubmit(v, "name", "role");
+              setInputValue(data.role || "");
+            },
+            placeholder: "Jo\xE3o"
+          }
+        )
+      ] }),
+      step === "role" && /* @__PURE__ */ jsxs(Box, { children: [
+        /* @__PURE__ */ jsx(Text, { color: colors.brand, bold: true, children: "\u276F " }),
+        /* @__PURE__ */ jsx(
+          TextInput,
+          {
+            value: inputValue,
+            onChange: setInputValue,
+            onSubmit: (v) => {
+              handleTextSubmit(v, "role", "technical_level");
+            },
+            placeholder: "CEO"
+          }
+        )
+      ] }),
+      step === "technical_level" && /* @__PURE__ */ jsx(Box, { flexDirection: "column", children: TECHNICAL_LEVELS.map((level, i) => {
+        const active = i === levelCursor;
+        return /* @__PURE__ */ jsxs(Box, { flexDirection: "column", marginBottom: 1, children: [
+          /* @__PURE__ */ jsxs(Box, { children: [
+            /* @__PURE__ */ jsx(Text, { color: active ? colors.brand : colors.dim, children: active ? `${symbols.arrow} ` : "  " }),
+            /* @__PURE__ */ jsx(Text, { color: active ? colors.white : colors.muted, bold: active, children: level.label })
+          ] }),
+          /* @__PURE__ */ jsx(Box, { paddingLeft: 4, children: /* @__PURE__ */ jsx(Text, { color: colors.dim, children: level.description }) })
+        ] }, level.value);
+      }) }),
+      step === "context" && /* @__PURE__ */ jsx(Box, { flexDirection: "column", children: /* @__PURE__ */ jsxs(Box, { children: [
+        /* @__PURE__ */ jsx(Text, { color: colors.brand, bold: true, children: "\u276F " }),
+        /* @__PURE__ */ jsx(
+          TextInput,
+          {
+            value: inputValue,
+            onChange: setInputValue,
+            onSubmit: (v) => {
+              setData((prev) => ({ ...prev, context: v.trim() }));
+              setInputValue(data.language || "English");
+              goTo("language");
+            },
+            placeholder: "(optional \u2014 press Enter to skip)"
+          }
+        )
+      ] }) }),
+      step === "language" && /* @__PURE__ */ jsxs(Box, { children: [
+        /* @__PURE__ */ jsx(Text, { color: colors.brand, bold: true, children: "\u276F " }),
+        /* @__PURE__ */ jsx(
+          TextInput,
+          {
+            value: inputValue,
+            onChange: setInputValue,
+            onSubmit: (v) => {
+              handleTextSubmit(v || "English", "language", "review");
+            },
+            placeholder: "English"
+          }
+        )
+      ] }),
+      step === "review" && /* @__PURE__ */ jsxs(Box, { flexDirection: "column", children: [
+        /* @__PURE__ */ jsxs(Box, { flexDirection: "column", paddingLeft: 1, borderStyle: "round", borderColor: colors.dim, paddingRight: 1, children: [
+          /* @__PURE__ */ jsx(ReviewRow, { label: "Name", value: data.name }),
+          /* @__PURE__ */ jsx(ReviewRow, { label: "Role", value: data.role }),
+          /* @__PURE__ */ jsx(ReviewRow, { label: "Level", value: TECHNICAL_LEVELS.find((l) => l.value === data.technical_level)?.label || data.technical_level }),
+          data.context && /* @__PURE__ */ jsx(ReviewRow, { label: "Context", value: data.context }),
+          /* @__PURE__ */ jsx(ReviewRow, { label: "Language", value: data.language })
+        ] }),
+        /* @__PURE__ */ jsx(Box, { marginTop: 1, children: /* @__PURE__ */ jsxs(Text, { color: colors.dim, children: [
+          /* @__PURE__ */ jsx(Text, { color: colors.brand, children: "enter" }),
+          " save  ",
+          /* @__PURE__ */ jsx(Text, { color: colors.muted, children: "b" }),
+          " start over"
+        ] }) })
+      ] }),
+      step === "done" && /* @__PURE__ */ jsxs(Box, { flexDirection: "column", alignItems: "center", children: [
+        /* @__PURE__ */ jsxs(Text, { color: colors.brand, bold: true, children: [
+          symbols.check,
+          " Persona saved"
+        ] }),
+        /* @__PURE__ */ jsx(Box, { marginTop: 1, children: /* @__PURE__ */ jsxs(Text, { color: colors.dim, children: [
+          "Run ",
+          /* @__PURE__ */ jsx(Text, { color: colors.white, bold: true, children: "hub generate" }),
+          " to apply it to your AI agent."
+        ] }) }),
+        /* @__PURE__ */ jsx(Box, { marginTop: 1, children: /* @__PURE__ */ jsxs(Text, { color: colors.dim, children: [
+          "Press ",
+          /* @__PURE__ */ jsx(Text, { color: colors.brand, bold: true, children: "Enter" }),
+          " to exit"
+        ] }) })
+      ] })
+    ] })
+  ] });
+}
+function ReviewRow({ label, value }) {
+  return /* @__PURE__ */ jsxs(Box, { children: [
+    /* @__PURE__ */ jsx(Box, { width: 10, children: /* @__PURE__ */ jsx(Text, { color: colors.muted, children: label }) }),
+    /* @__PURE__ */ jsx(Text, { color: colors.white, bold: true, children: value })
+  ] });
+}
+
+// src/commands/persona.ts
+import { stringify } from "yaml";
+var ENTER_ALT_SCREEN = "\x1B[?1049h";
+var EXIT_ALT_SCREEN = "\x1B[?1049l";
+var CLEAR = "\x1B[2J\x1B[H";
+var HIDE_CURSOR = "\x1B[?25l";
+var SHOW_CURSOR = "\x1B[?25h";
+function getPersonaPath(hubDir) {
+  return join3(hubDir, ".hub", "persona.yaml");
+}
+async function loadPersona(hubDir) {
+  const personaPath = getPersonaPath(hubDir);
+  if (!existsSync2(personaPath)) return null;
+  try {
+    const { parse } = await import("yaml");
+    const content = await readFile3(personaPath, "utf-8");
+    return parse(content);
+  } catch {
+    return null;
+  }
+}
+function buildPersonaSection(persona) {
+  const lines = [];
+  lines.push(`
+## User Persona
+`);
+  lines.push(`You are talking to **${persona.name}**, who is a **${persona.role}**.`);
+  if (persona.technical_level === "non-technical") {
+    lines.push(`
+${persona.name} is not technical. Adapt your communication:
+- Never use jargon, acronyms, or technical terms without explaining them in plain language first.
+- Explain decisions in terms of business impact, user experience, and outcomes \u2014 not implementation details.
+- When showing progress, focus on what changed for the user/product, not what code was modified.
+- If you need to mention something technical, use analogies and simple language.
+- Keep responses short and focused on what matters to them.
+- When asking questions, frame them as business/product decisions, not technical choices.
+- Never show code snippets, terminal output, or file paths unless explicitly asked.`);
+  } else if (persona.technical_level === "beginner") {
+    lines.push(`
+${persona.name} is learning and not deeply technical yet. Adapt your communication:
+- Explain technical concepts briefly when you first mention them.
+- Avoid deep implementation details unless asked.
+- Use simple language but don't shy away from introducing technical terms with context.
+- When showing code or commands, briefly explain what they do.
+- Be encouraging and patient \u2014 frame things as learning opportunities.`);
+  } else if (persona.technical_level === "intermediate") {
+    lines.push(`
+${persona.name} is comfortable with code but may not know every tool or pattern. Adapt your communication:
+- Use technical language normally but explain niche or advanced concepts when relevant.
+- Show code and commands without excessive explanation, but add context for non-obvious decisions.
+- Focus on the "why" behind architectural choices.`);
+  } else {
+    lines.push(`
+${persona.name} is an experienced developer. Communicate directly:
+- Be concise and technical. Skip basic explanations.
+- Focus on trade-offs, edge cases, and non-obvious implications.
+- Show code directly without hand-holding.`);
+  }
+  if (persona.context) {
+    lines.push(`
+Additional context about ${persona.name}: ${persona.context}`);
+  }
+  if (persona.language && persona.language.toLowerCase() !== "english") {
+    lines.push(`
+Always communicate with ${persona.name} in **${persona.language}**.`);
+  }
+  return lines.join("\n");
+}
+var personaCommand = new Command("persona").description("Set up your personal AI profile \u2014 adapts how the agent communicates with you").action(async () => {
+  const hubDir = process.cwd();
+  const hubPath = join3(hubDir, ".hub");
+  await mkdir3(hubPath, { recursive: true });
+  const existing = await loadPersona(hubDir);
+  process.stdout.write(ENTER_ALT_SCREEN + CLEAR + HIDE_CURSOR);
+  const cleanup = () => {
+    process.stdout.write(SHOW_CURSOR + EXIT_ALT_SCREEN);
+  };
+  process.on("SIGINT", () => {
+    cleanup();
+    process.exit(0);
+  });
+  const { waitUntilExit } = render(
+    React.createElement(PersonaApp, {
+      existing: existing ?? void 0,
+      onComplete: async (persona) => {
+        const personaPath = getPersonaPath(hubDir);
+        await writeFile3(personaPath, stringify(persona), "utf-8");
+      }
+    })
+  );
+  await waitUntilExit();
+  cleanup();
+});
+
 // src/commands/generate.ts
 var HUB_DOCS_URL = "https://hub.arvore.com.br/llms-full.txt";
 async function syncRemoteSources(config, hubDir, skillsDir, steeringDir) {
@@ -464,9 +795,9 @@ function parseFrontMatter(content) {
 }
 async function readExistingMcpDisabledState(mcpJsonPath) {
   const disabledState = {};
-  if (!existsSync2(mcpJsonPath)) return disabledState;
+  if (!existsSync3(mcpJsonPath)) return disabledState;
   try {
-    const content = JSON.parse(await readFile3(mcpJsonPath, "utf-8"));
+    const content = JSON.parse(await readFile4(mcpJsonPath, "utf-8"));
     const servers = content.mcpServers || content.mcp || {};
     for (const [name, config] of Object.entries(servers)) {
       if (typeof config.disabled === "boolean") {
@@ -492,8 +823,8 @@ async function fetchHubDocsSkill(skillsDir) {
       return;
     }
     const content = await res.text();
-    const hubSkillDir = join3(skillsDir, "hub-docs");
-    await mkdir3(hubSkillDir, { recursive: true });
+    const hubSkillDir = join4(skillsDir, "hub-docs");
+    await mkdir4(hubSkillDir, { recursive: true });
     const skillContent = `---
 name: hub-docs
 description: Repo Hub (rhm) documentation. Use when working with hub.yaml, hub CLI commands, agent orchestration, MCP configuration, skills, workflows, or multi-repo workspace setup.
@@ -501,7 +832,7 @@ triggers: [hub, rhm, hub.yaml, generate, scan, setup, orchestrator, multi-repo,
 ---
 
 ${content}`;
-    await writeFile3(join3(hubSkillDir, "SKILL.md"), skillContent, "utf-8");
+    await writeFile4(join4(hubSkillDir, "SKILL.md"), skillContent, "utf-8");
     console.log(chalk3.green("  Fetched hub-docs skill from hub.arvore.com.br"));
   } catch {
     console.log(chalk3.yellow(`  Could not fetch hub docs, skipping hub-docs skill`));
@@ -576,7 +907,7 @@ function buildClaudeHooks(hooks) {
   return claudeHooks;
 }
 async function generateEditorCommands(config, hubDir, targetDir, editorName) {
-  const commandsDir = join3(targetDir, "commands");
+  const commandsDir = join4(targetDir, "commands");
   let count = 0;
   if (config.commands_dir) {
     const srcDir = resolve2(hubDir, config.commands_dir);
@@ -584,9 +915,9 @@ async function generateEditorCommands(config, hubDir, targetDir, editorName) {
       const files = await readdir2(srcDir);
       const mdFiles = files.filter((f) => f.endsWith(".md"));
       if (mdFiles.length > 0) {
-        await mkdir3(commandsDir, { recursive: true });
+        await mkdir4(commandsDir, { recursive: true });
         for (const file of mdFiles) {
-          await copyFile(join3(srcDir, file), join3(commandsDir, file));
+          await copyFile(join4(srcDir, file), join4(commandsDir, file));
           count++;
         }
       }
@@ -595,10 +926,10 @@ async function generateEditorCommands(config, hubDir, targetDir, editorName) {
     }
   }
   if (config.commands) {
-    await mkdir3(commandsDir, { recursive: true });
+    await mkdir4(commandsDir, { recursive: true });
     for (const [name, filePath] of Object.entries(config.commands)) {
       const src = resolve2(hubDir, filePath);
-      const dest = join3(commandsDir, name.endsWith(".md") ? name : `${name}.md`);
+      const dest = join4(commandsDir, name.endsWith(".md") ? name : `${name}.md`);
       try {
         await copyFile(src, dest);
         count++;
@@ -613,27 +944,27 @@ async function generateEditorCommands(config, hubDir, targetDir, editorName) {
 }
 async function writeManagedFile(filePath, managedLines) {
   const managedBlock = [HUB_MARKER_START, ...managedLines, HUB_MARKER_END].join("\n");
-  if (existsSync2(filePath)) {
-    const existing = await readFile3(filePath, "utf-8");
+  if (existsSync3(filePath)) {
+    const existing = await readFile4(filePath, "utf-8");
     const startIdx = existing.indexOf(HUB_MARKER_START);
     const endIdx = existing.indexOf(HUB_MARKER_END);
     if (startIdx !== -1 && endIdx !== -1) {
       const before = existing.substring(0, startIdx);
       const after = existing.substring(endIdx + HUB_MARKER_END.length);
-      await writeFile3(filePath, before + managedBlock + after, "utf-8");
+      await writeFile4(filePath, before + managedBlock + after, "utf-8");
       return;
     }
-    await writeFile3(filePath, managedBlock + "\n\n" + existing, "utf-8");
+    await writeFile4(filePath, managedBlock + "\n\n" + existing, "utf-8");
     return;
   }
-  await writeFile3(filePath, managedBlock + "\n", "utf-8");
+  await writeFile4(filePath, managedBlock + "\n", "utf-8");
 }
 async function generateCursor(config, hubDir) {
-  const cursorDir = join3(hubDir, ".cursor");
-  await mkdir3(join3(cursorDir, "rules"), { recursive: true });
-  await mkdir3(join3(cursorDir, "agents"), { recursive: true });
+  const cursorDir = join4(hubDir, ".cursor");
+  await mkdir4(join4(cursorDir, "rules"), { recursive: true });
+  await mkdir4(join4(cursorDir, "agents"), { recursive: true });
   const gitignoreLines = buildGitignoreLines(config);
-  await writeManagedFile(join3(hubDir, ".gitignore"), gitignoreLines);
+  await writeManagedFile(join4(hubDir, ".gitignore"), gitignoreLines);
   console.log(chalk3.green("  Generated .gitignore"));
   const cursorignoreLines = [
     "# Re-include repositories for AI context"
@@ -643,7 +974,7 @@ async function generateCursor(config, hubDir) {
     cursorignoreLines.push(`!${repoDir}/`);
   }
   cursorignoreLines.push("", "# Re-include tasks for agent collaboration", "!tasks/");
-  await writeManagedFile(join3(hubDir, ".cursorignore"), cursorignoreLines);
+  await writeManagedFile(join4(hubDir, ".cursorignore"), cursorignoreLines);
   console.log(chalk3.green("  Generated .cursorignore"));
   if (config.mcps?.length) {
     const mcpConfig = {};
@@ -656,27 +987,36 @@ async function generateCursor(config, hubDir) {
         mcpConfig[mcp.name] = buildCursorMcpEntry(mcp);
       }
     }
-    await writeFile3(
-      join3(cursorDir, "mcp.json"),
+    const sandbox = getSandboxService(config);
+    if (sandbox && !mcpConfig["sandbox"]) {
+      mcpConfig["sandbox"] = buildSandboxMcpEntry(sandbox.port);
+    }
+    await writeFile4(
+      join4(cursorDir, "mcp.json"),
       JSON.stringify({ mcpServers: mcpConfig }, null, 2) + "\n",
       "utf-8"
     );
     console.log(chalk3.green("  Generated .cursor/mcp.json"));
   }
   const orchestratorRule = buildOrchestratorRule(config);
-  await writeFile3(join3(cursorDir, "rules", "orchestrator.mdc"), orchestratorRule, "utf-8");
+  await writeFile4(join4(cursorDir, "rules", "orchestrator.mdc"), orchestratorRule, "utf-8");
   console.log(chalk3.green("  Generated .cursor/rules/orchestrator.mdc"));
   const cleanedOrchestratorForAgents = orchestratorRule.replace(/^---[\s\S]*?---\n/m, "").trim();
   const skillsSectionCursor = await buildSkillsSection(hubDir, config);
-  const agentsMdCursor = skillsSectionCursor ? cleanedOrchestratorForAgents + "\n" + skillsSectionCursor : cleanedOrchestratorForAgents;
-  await writeFile3(join3(hubDir, "AGENTS.md"), agentsMdCursor + "\n", "utf-8");
+  const personaCursor = await loadPersona(hubDir);
+  const personaSectionCursor = personaCursor ? buildPersonaSection(personaCursor) : "";
+  const agentsMdCursor = [cleanedOrchestratorForAgents, skillsSectionCursor, personaSectionCursor].filter(Boolean).join("\n");
+  await writeFile4(join4(hubDir, "AGENTS.md"), agentsMdCursor + "\n", "utf-8");
   console.log(chalk3.green("  Generated AGENTS.md"));
+  if (personaCursor) {
+    console.log(chalk3.green(`  Applied persona: ${personaCursor.name} (${personaCursor.role})`));
+  }
   const hubSteeringDirCursor = resolve2(hubDir, "steering");
   try {
     const steeringFiles = await readdir2(hubSteeringDirCursor);
     const mdFiles = steeringFiles.filter((f) => f.endsWith(".md"));
     for (const file of mdFiles) {
-      const raw = await readFile3(join3(hubSteeringDirCursor, file), "utf-8");
+      const raw = await readFile4(join4(hubSteeringDirCursor, file), "utf-8");
       const content = stripFrontMatter(raw);
       const mdcName = file.replace(/\.md$/, ".mdc");
       const mdcContent = `---
@@ -685,7 +1025,7 @@ alwaysApply: true
 ---
 
 ${content}`;
-      await writeFile3(join3(cursorDir, "rules", mdcName), mdcContent, "utf-8");
+      await writeFile4(join4(cursorDir, "rules", mdcName), mdcContent, "utf-8");
     }
     if (mdFiles.length > 0) {
       console.log(chalk3.green(`  Copied ${mdFiles.length} steering files to .cursor/rules/`));
@@ -696,8 +1036,16 @@ ${content}`;
   try {
     const agentFiles = await readdir2(agentsDir);
     const mdFiles = agentFiles.filter((f) => f.endsWith(".md"));
+    const sandboxSvc = getSandboxService(config);
     for (const file of mdFiles) {
-      await copyFile(join3(agentsDir, file), join3(cursorDir, "agents", file));
+      if (sandboxSvc) {
+        const agentName = file.replace(/\.md$/, "");
+        const agentContent = await readFile4(join4(agentsDir, file), "utf-8");
+        const withSandbox = injectSandboxContext(agentName, agentContent, sandboxSvc.port);
+        await writeFile4(join4(cursorDir, "agents", file), withSandbox, "utf-8");
+      } else {
+        await copyFile(join4(agentsDir, file), join4(cursorDir, "agents", file));
+      }
     }
     console.log(chalk3.green(`  Copied ${mdFiles.length} agent definitions`));
   } catch {
@@ -706,15 +1054,15 @@ ${content}`;
   const skillsDir = resolve2(hubDir, "skills");
   try {
     const skillFolders = await readdir2(skillsDir);
-    const cursorSkillsDir = join3(cursorDir, "skills");
-    await mkdir3(cursorSkillsDir, { recursive: true });
+    const cursorSkillsDir = join4(cursorDir, "skills");
+    await mkdir4(cursorSkillsDir, { recursive: true });
     let count = 0;
     for (const folder of skillFolders) {
-      const skillFile = join3(skillsDir, folder, "SKILL.md");
+      const skillFile = join4(skillsDir, folder, "SKILL.md");
       try {
-        await readFile3(skillFile);
-        const srcDir = join3(skillsDir, folder);
-        const targetDir = join3(cursorSkillsDir, folder);
+        await readFile4(skillFile);
+        const srcDir = join4(skillsDir, folder);
+        const targetDir = join4(cursorSkillsDir, folder);
         await cp(srcDir, targetDir, { recursive: true });
         count++;
       } catch {
@@ -725,15 +1073,15 @@ ${content}`;
     }
   } catch {
   }
-  const cursorSkillsDirForDocs = join3(cursorDir, "skills");
-  await mkdir3(cursorSkillsDirForDocs, { recursive: true });
+  const cursorSkillsDirForDocs = join4(cursorDir, "skills");
+  await mkdir4(cursorSkillsDirForDocs, { recursive: true });
   await fetchHubDocsSkill(cursorSkillsDirForDocs);
-  await syncRemoteSources(config, hubDir, join3(cursorDir, "skills"), join3(cursorDir, "rules"));
+  await syncRemoteSources(config, hubDir, join4(cursorDir, "skills"), join4(cursorDir, "rules"));
   if (config.hooks) {
     const cursorHooks = buildCursorHooks(config.hooks);
     if (cursorHooks) {
-      await writeFile3(
-        join3(cursorDir, "hooks.json"),
+      await writeFile4(
+        join4(cursorDir, "hooks.json"),
         JSON.stringify(cursorHooks, null, 2) + "\n",
         "utf-8"
       );
@@ -743,6 +1091,14 @@ ${content}`;
   await generateEditorCommands(config, hubDir, cursorDir, ".cursor/commands/");
   await generateVSCodeSettings(config, hubDir);
 }
+function buildSandboxMcpEntry(port) {
+  return { url: `http://localhost:${port}/mcp` };
+}
+function getSandboxService(config) {
+  const svc = config.services?.find((s) => s.type === "sandbox");
+  if (!svc) return null;
+  return { port: svc.port ?? 8080 };
+}
 function buildProxyUpstreams(proxyMcp, allMcps) {
   const upstreamNames = new Set(proxyMcp.upstreams || []);
   const upstreamEntries = [];
@@ -876,6 +1232,24 @@ function buildKiroMcpEntry(mcp, mode = "editor") {
     ...autoApprove && { autoApprove }
   };
 }
+var SANDBOX_AGENT_TARGETS = /* @__PURE__ */ new Set(["qa-frontend", "qa-backend", "coding-frontend", "coding-backend"]);
+function injectSandboxContext(agentName, content, sandboxPort) {
+  if (!SANDBOX_AGENT_TARGETS.has(agentName)) return content;
+  const section = `
+## Sandbox Environment
+
+A sandboxed execution environment is available via the \`sandbox\` MCP (http://localhost:${sandboxPort}/mcp).
+
+Use it to:
+- Run shell commands: \`shell.exec\`
+- Read/write files: \`file.read\`, \`file.write\`
+- Control a real browser: \`browser.navigate\`, \`browser.screenshot\`, \`browser.click\`
+- Execute code: \`jupyter.execute\`
+
+The sandbox workspace is mounted at \`/home/gem/workspace\`. Prefer running builds, tests, and browser interactions inside the sandbox rather than on the host machine.
+`;
+  return content.trimEnd() + "\n" + section;
+}
 function buildKiroAgentContent(rawContent) {
   const fmMatch = rawContent.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
   if (!fmMatch) {
@@ -1179,9 +1553,9 @@ async function buildSkillsSection(hubDir, config) {
   try {
     const folders = await readdir2(skillsDir);
     for (const folder of folders) {
-      const skillPath = join3(skillsDir, folder, "SKILL.md");
+      const skillPath = join4(skillsDir, folder, "SKILL.md");
       try {
-        const content = await readFile3(skillPath, "utf-8");
+        const content = await readFile4(skillPath, "utf-8");
         const fm = parseFrontMatter(content);
         if (fm?.name) {
           skillEntries.push({
@@ -1504,18 +1878,18 @@ If any validation agent leaves comments requiring fixes, call the relevant codin
   return parts.join("\n");
 }
 async function generateOpenCode(config, hubDir) {
-  const opencodeDir = join3(hubDir, ".opencode");
-  await mkdir3(join3(opencodeDir, "agents"), { recursive: true });
-  await mkdir3(join3(opencodeDir, "rules"), { recursive: true });
-  await mkdir3(join3(opencodeDir, "skills"), { recursive: true });
-  await mkdir3(join3(opencodeDir, "commands"), { recursive: true });
-  await mkdir3(join3(opencodeDir, "plugins"), { recursive: true });
+  const opencodeDir = join4(hubDir, ".opencode");
+  await mkdir4(join4(opencodeDir, "agents"), { recursive: true });
+  await mkdir4(join4(opencodeDir, "rules"), { recursive: true });
+  await mkdir4(join4(opencodeDir, "skills"), { recursive: true });
+  await mkdir4(join4(opencodeDir, "commands"), { recursive: true });
+  await mkdir4(join4(opencodeDir, "plugins"), { recursive: true });
   const gitignoreLines = buildGitignoreLines(config);
-  await writeManagedFile(join3(hubDir, ".gitignore"), gitignoreLines);
+  await writeManagedFile(join4(hubDir, ".gitignore"), gitignoreLines);
   console.log(chalk3.green("  Generated .gitignore"));
   if (config.repos.length > 0) {
     const ignoreContent = config.repos.map((r) => `!${r.name}`).join("\n") + "\n";
-    await writeFile3(join3(hubDir, ".ignore"), ignoreContent, "utf-8");
+    await writeFile4(join4(hubDir, ".ignore"), ignoreContent, "utf-8");
     console.log(chalk3.green("  Generated .ignore"));
   }
   const orchestratorContent = buildOpenCodeOrchestratorRule(config);
@@ -1523,22 +1897,27 @@ async function generateOpenCode(config, hubDir) {
     "Development orchestrator. Delegates specialized work to subagents following a structured pipeline: refinement, coding, review, QA, and delivery.",
     orchestratorContent
   );
-  await writeFile3(join3(opencodeDir, "agents", "orchestrator.md"), orchestratorAgent, "utf-8");
+  await writeFile4(join4(opencodeDir, "agents", "orchestrator.md"), orchestratorAgent, "utf-8");
   console.log(chalk3.green("  Generated .opencode/agents/orchestrator.md (primary agent)"));
-  await rm(join3(opencodeDir, "rules", "orchestrator.md")).catch(() => {
+  await rm(join4(opencodeDir, "rules", "orchestrator.md")).catch(() => {
   });
   const skillsSectionOC = await buildSkillsSection(hubDir, config);
-  const agentsMdOC = skillsSectionOC ? orchestratorContent + "\n" + skillsSectionOC : orchestratorContent;
-  await writeFile3(join3(hubDir, "AGENTS.md"), agentsMdOC + "\n", "utf-8");
+  const personaOC = await loadPersona(hubDir);
+  const personaSectionOC = personaOC ? buildPersonaSection(personaOC) : "";
+  const agentsMdOC = [orchestratorContent, skillsSectionOC, personaSectionOC].filter(Boolean).join("\n");
+  await writeFile4(join4(hubDir, "AGENTS.md"), agentsMdOC + "\n", "utf-8");
   console.log(chalk3.green("  Generated AGENTS.md"));
+  if (personaOC) {
+    console.log(chalk3.green(`  Applied persona: ${personaOC.name} (${personaOC.role})`));
+  }
   const hubSteeringDirOC = resolve2(hubDir, "steering");
   try {
     const steeringFiles = await readdir2(hubSteeringDirOC);
     const mdFiles = steeringFiles.filter((f) => f.endsWith(".md"));
     for (const file of mdFiles) {
-      const raw = await readFile3(join3(hubSteeringDirOC, file), "utf-8");
+      const raw = await readFile4(join4(hubSteeringDirOC, file), "utf-8");
       const content = stripFrontMatter(raw);
-      await writeFile3(join3(opencodeDir, "rules", file), content, "utf-8");
+      await writeFile4(join4(opencodeDir, "rules", file), content, "utf-8");
     }
     if (mdFiles.length > 0) {
       console.log(chalk3.green(`  Copied ${mdFiles.length} steering files to .opencode/rules/`));
@@ -1563,8 +1942,8 @@ async function generateOpenCode(config, hubDir) {
     opencodeConfig.mcp = mcpConfig;
   }
   opencodeConfig.instructions = [".opencode/rules/*.md"];
-  await writeFile3(
-    join3(hubDir, "opencode.json"),
+  await writeFile4(
+    join4(hubDir, "opencode.json"),
     JSON.stringify(opencodeConfig, null, 2) + "\n",
     "utf-8"
   );
@@ -1575,10 +1954,10 @@ async function generateOpenCode(config, hubDir) {
     const mdFiles = agentFiles.filter((f) => f.endsWith(".md"));
     for (const file of mdFiles) {
       if (file === "orchestrator.md") continue;
-      const content = await readFile3(join3(agentsDir, file), "utf-8");
+      const content = await readFile4(join4(agentsDir, file), "utf-8");
       const agentName = file.replace(/\.md$/, "");
       const converted = buildOpenCodeAgentMarkdown(agentName, content);
-      await writeFile3(join3(opencodeDir, "agents", file), converted, "utf-8");
+      await writeFile4(join4(opencodeDir, "agents", file), converted, "utf-8");
     }
     console.log(chalk3.green(`  Copied ${mdFiles.length} agents to .opencode/agents/`));
   } catch {
@@ -1589,10 +1968,10 @@ async function generateOpenCode(config, hubDir) {
     const skillFolders = await readdir2(skillsDir);
     let count = 0;
     for (const folder of skillFolders) {
-      const skillFile = join3(skillsDir, folder, "SKILL.md");
+      const skillFile = join4(skillsDir, folder, "SKILL.md");
       try {
-        await readFile3(skillFile);
-        await cp(join3(skillsDir, folder), join3(opencodeDir, "skills", folder), { recursive: true });
+        await readFile4(skillFile);
+        await cp(join4(skillsDir, folder), join4(opencodeDir, "skills", folder), { recursive: true });
         count++;
       } catch {
       }
@@ -1602,13 +1981,13 @@ async function generateOpenCode(config, hubDir) {
     }
   } catch {
   }
-  await fetchHubDocsSkill(join3(opencodeDir, "skills"));
-  await syncRemoteSources(config, hubDir, join3(opencodeDir, "skills"), join3(opencodeDir, "rules"));
+  await fetchHubDocsSkill(join4(opencodeDir, "skills"));
+  await syncRemoteSources(config, hubDir, join4(opencodeDir, "skills"), join4(opencodeDir, "rules"));
   await generateEditorCommands(config, hubDir, opencodeDir, ".opencode/commands/");
   if (config.hooks) {
     const plugin = buildOpenCodeHooksPlugin(config.hooks);
     if (plugin) {
-      await writeFile3(join3(opencodeDir, "plugins", "hub-hooks.js"), plugin, "utf-8");
+      await writeFile4(join4(opencodeDir, "plugins", "hub-hooks.js"), plugin, "utf-8");
       console.log(chalk3.green("  Generated .opencode/plugins/hub-hooks.js"));
     }
   }
@@ -2095,14 +2474,19 @@ function formatAction(action) {
   return map[action] || action;
 }
 async function generateClaudeCode(config, hubDir) {
-  const claudeDir = join3(hubDir, ".claude");
-  await mkdir3(join3(claudeDir, "agents"), { recursive: true });
+  const claudeDir = join4(hubDir, ".claude");
+  await mkdir4(join4(claudeDir, "agents"), { recursive: true });
   const orchestratorRule = buildOrchestratorRule(config);
   const cleanedOrchestrator = orchestratorRule.replace(/^---[\s\S]*?---\n/m, "").trim();
   const skillsSectionClaude = await buildSkillsSection(hubDir, config);
-  const agentsMdClaude = skillsSectionClaude ? cleanedOrchestrator + "\n" + skillsSectionClaude : cleanedOrchestrator;
-  await writeFile3(join3(hubDir, "AGENTS.md"), agentsMdClaude + "\n", "utf-8");
+  const personaClaude = await loadPersona(hubDir);
+  const personaSectionClaude = personaClaude ? buildPersonaSection(personaClaude) : "";
+  const agentsMdClaude = [cleanedOrchestrator, skillsSectionClaude, personaSectionClaude].filter(Boolean).join("\n");
+  await writeFile4(join4(hubDir, "AGENTS.md"), agentsMdClaude + "\n", "utf-8");
   console.log(chalk3.green("  Generated AGENTS.md"));
+  if (personaClaude) {
+    console.log(chalk3.green(`  Applied persona: ${personaClaude.name} (${personaClaude.role})`));
+  }
   const claudeMdSections = [];
   claudeMdSections.push(cleanedOrchestrator);
   const agentsDir = resolve2(hubDir, "agents");
@@ -2110,7 +2494,7 @@ async function generateClaudeCode(config, hubDir) {
     const agentFiles = await readdir2(agentsDir);
     const mdFiles = agentFiles.filter((f) => f.endsWith(".md"));
     for (const file of mdFiles) {
-      await copyFile(join3(agentsDir, file), join3(claudeDir, "agents", file));
+      await copyFile(join4(agentsDir, file), join4(claudeDir, "agents", file));
     }
     console.log(chalk3.green(`  Copied ${mdFiles.length} agents to .claude/agents/`));
   } catch {
@@ -2119,15 +2503,15 @@ async function generateClaudeCode(config, hubDir) {
   const skillsDir = resolve2(hubDir, "skills");
   try {
     const skillFolders = await readdir2(skillsDir);
-    const claudeSkillsDir = join3(claudeDir, "skills");
-    await mkdir3(claudeSkillsDir, { recursive: true });
+    const claudeSkillsDir = join4(claudeDir, "skills");
+    await mkdir4(claudeSkillsDir, { recursive: true });
     let count = 0;
     for (const folder of skillFolders) {
-      const skillFile = join3(skillsDir, folder, "SKILL.md");
+      const skillFile = join4(skillsDir, folder, "SKILL.md");
       try {
-        await readFile3(skillFile);
-        const srcDir = join3(skillsDir, folder);
-        const targetDir = join3(claudeSkillsDir, folder);
+        await readFile4(skillFile);
+        const srcDir = join4(skillsDir, folder);
+        const targetDir = join4(claudeSkillsDir, folder);
         await cp(srcDir, targetDir, { recursive: true });
         count++;
       } catch {
@@ -2138,16 +2522,16 @@ async function generateClaudeCode(config, hubDir) {
     }
   } catch {
   }
-  const claudeSkillsDirForDocs = join3(claudeDir, "skills");
-  await mkdir3(claudeSkillsDirForDocs, { recursive: true });
+  const claudeSkillsDirForDocs = join4(claudeDir, "skills");
+  await mkdir4(claudeSkillsDirForDocs, { recursive: true });
   await fetchHubDocsSkill(claudeSkillsDirForDocs);
-  await syncRemoteSources(config, hubDir, join3(claudeDir, "skills"), join3(claudeDir, "steering"));
+  await syncRemoteSources(config, hubDir, join4(claudeDir, "skills"), join4(claudeDir, "steering"));
   const hubSteeringDirClaude = resolve2(hubDir, "steering");
   try {
     const steeringFiles = await readdir2(hubSteeringDirClaude);
     const mdFiles = steeringFiles.filter((f) => f.endsWith(".md"));
     for (const file of mdFiles) {
-      const raw = await readFile3(join3(hubSteeringDirClaude, file), "utf-8");
+      const raw = await readFile4(join4(hubSteeringDirClaude, file), "utf-8");
       const content = stripFrontMatter(raw).trim();
       if (content) {
         claudeMdSections.push(content);
@@ -2158,7 +2542,7 @@ async function generateClaudeCode(config, hubDir) {
     }
   } catch {
   }
-  await writeFile3(join3(hubDir, "CLAUDE.md"), claudeMdSections.join("\n\n"), "utf-8");
+  await writeFile4(join4(hubDir, "CLAUDE.md"), claudeMdSections.join("\n\n"), "utf-8");
   console.log(chalk3.green("  Generated CLAUDE.md"));
   if (config.mcps?.length) {
     const mcpJson = {};
@@ -2171,8 +2555,8 @@ async function generateClaudeCode(config, hubDir) {
         mcpJson[mcp.name] = buildClaudeCodeMcpEntry(mcp);
       }
     }
-    await writeFile3(
-      join3(hubDir, ".mcp.json"),
+    await writeFile4(
+      join4(hubDir, ".mcp.json"),
       JSON.stringify({ mcpServers: mcpJson }, null, 2) + "\n",
       "utf-8"
     );
@@ -2214,22 +2598,22 @@ async function generateClaudeCode(config, hubDir) {
       claudeSettings.hooks = claudeHooks;
     }
   }
-  await writeFile3(
-    join3(claudeDir, "settings.json"),
+  await writeFile4(
+    join4(claudeDir, "settings.json"),
     JSON.stringify(claudeSettings, null, 2) + "\n",
     "utf-8"
   );
   console.log(chalk3.green("  Generated .claude/settings.json"));
   const gitignoreLines = buildGitignoreLines(config);
-  await writeManagedFile(join3(hubDir, ".gitignore"), gitignoreLines);
+  await writeManagedFile(join4(hubDir, ".gitignore"), gitignoreLines);
   console.log(chalk3.green("  Generated .gitignore"));
 }
 async function generateKiro(config, hubDir) {
-  const kiroDir = join3(hubDir, ".kiro");
-  const steeringDir = join3(kiroDir, "steering");
-  const settingsDir = join3(kiroDir, "settings");
-  await mkdir3(steeringDir, { recursive: true });
-  await mkdir3(settingsDir, { recursive: true });
+  const kiroDir = join4(hubDir, ".kiro");
+  const steeringDir = join4(kiroDir, "steering");
+  const settingsDir = join4(kiroDir, "settings");
+  await mkdir4(steeringDir, { recursive: true });
+  await mkdir4(settingsDir, { recursive: true });
   let mode = await getKiroMode(hubDir);
   if (!mode) {
     const { kiroMode } = await inquirer.prompt([
@@ -2250,25 +2634,32 @@ async function generateKiro(config, hubDir) {
     console.log(chalk3.dim(`  Using saved Kiro mode: ${mode}`));
   }
   const gitignoreLines = buildGitignoreLines(config);
-  await writeManagedFile(join3(hubDir, ".gitignore"), gitignoreLines);
+  await writeManagedFile(join4(hubDir, ".gitignore"), gitignoreLines);
   console.log(chalk3.green("  Generated .gitignore"));
   const kiroRule = buildKiroOrchestratorRule(config);
   const skillsSection = await buildSkillsSection(hubDir, config);
-  const kiroRuleWithSkills = skillsSection ? kiroRule + "\n" + skillsSection : kiroRule;
-  await writeFile3(join3(hubDir, "AGENTS.md"), kiroRuleWithSkills + "\n", "utf-8");
+  const personaKiro = await loadPersona(hubDir);
+  const personaSectionKiro = personaKiro ? buildPersonaSection(personaKiro) : "";
+  const kiroRuleWithSkills = [kiroRule, skillsSection, personaSectionKiro].filter(Boolean).join("\n");
+  await writeFile4(join4(hubDir, "AGENTS.md"), kiroRuleWithSkills + "\n", "utf-8");
   console.log(chalk3.green("  Generated AGENTS.md"));
+  if (personaKiro) {
+    console.log(chalk3.green(`  Applied persona: ${personaKiro.name} (${personaKiro.role})`));
+  }
+  await rm(join4(steeringDir, "orchestrator.md")).catch(() => {
+  });
   const hubSteeringDir = resolve2(hubDir, "steering");
   try {
     const steeringFiles = await readdir2(hubSteeringDir);
     const mdFiles = steeringFiles.filter((f) => f.endsWith(".md"));
     for (const file of mdFiles) {
-      const raw = await readFile3(join3(hubSteeringDir, file), "utf-8");
+      const raw = await readFile4(join4(hubSteeringDir, file), "utf-8");
       const content = stripFrontMatter(raw);
-      const destPath = join3(steeringDir, file);
+      const destPath = join4(steeringDir, file);
       let inclusion = "always";
       let meta;
-      if (existsSync2(destPath)) {
-        const existingContent = await readFile3(destPath, "utf-8");
+      if (existsSync3(destPath)) {
+        const existingContent = await readFile4(destPath, "utf-8");
         const existingFm = parseFrontMatter(existingContent);
         if (existingFm) {
           if (existingFm.inclusion === "auto" || existingFm.inclusion === "manual" || existingFm.inclusion === "fileMatch") {
@@ -2293,7 +2684,7 @@ async function generateKiro(config, hubDir) {
         }
       }
       const kiroSteering = buildKiroSteeringContent(content, inclusion, meta);
-      await writeFile3(destPath, kiroSteering, "utf-8");
+      await writeFile4(destPath, kiroSteering, "utf-8");
     }
     if (mdFiles.length > 0) {
       console.log(chalk3.green(`  Copied ${mdFiles.length} steering files to .kiro/steering/`));
@@ -2302,14 +2693,17 @@ async function generateKiro(config, hubDir) {
   }
   const agentsDir = resolve2(hubDir, "agents");
   try {
-    const kiroAgentsDir = join3(kiroDir, "agents");
-    await mkdir3(kiroAgentsDir, { recursive: true });
+    const kiroAgentsDir = join4(kiroDir, "agents");
+    await mkdir4(kiroAgentsDir, { recursive: true });
     const agentFiles = await readdir2(agentsDir);
     const mdFiles = agentFiles.filter((f) => f.endsWith(".md"));
     for (const file of mdFiles) {
-      const agentContent = await readFile3(join3(agentsDir, file), "utf-8");
-      const kiroAgent = buildKiroAgentContent(agentContent);
-      await writeFile3(join3(kiroAgentsDir, file), kiroAgent, "utf-8");
+      const agentContent = await readFile4(join4(agentsDir, file), "utf-8");
+      const agentName = file.replace(/\.md$/, "");
+      const sandboxSvc = getSandboxService(config);
+      const withSandbox = sandboxSvc ? injectSandboxContext(agentName, agentContent, sandboxSvc.port) : agentContent;
+      const kiroAgent = buildKiroAgentContent(withSandbox);
+      await writeFile4(join4(kiroAgentsDir, file), kiroAgent, "utf-8");
     }
     console.log(chalk3.green(`  Copied ${mdFiles.length} agents to .kiro/agents/`));
   } catch {
@@ -2318,15 +2712,15 @@ async function generateKiro(config, hubDir) {
   const skillsDir = resolve2(hubDir, "skills");
   try {
     const skillFolders = await readdir2(skillsDir);
-    const kiroSkillsDir = join3(kiroDir, "skills");
-    await mkdir3(kiroSkillsDir, { recursive: true });
+    const kiroSkillsDir = join4(kiroDir, "skills");
+    await mkdir4(kiroSkillsDir, { recursive: true });
     let count = 0;
     for (const folder of skillFolders) {
-      const skillFile = join3(skillsDir, folder, "SKILL.md");
+      const skillFile = join4(skillsDir, folder, "SKILL.md");
       try {
-        await readFile3(skillFile);
-        const srcDir = join3(skillsDir, folder);
-        const targetDir = join3(kiroSkillsDir, folder);
+        await readFile4(skillFile);
+        const srcDir = join4(skillsDir, folder);
+        const targetDir = join4(kiroSkillsDir, folder);
         await cp(srcDir, targetDir, { recursive: true });
         count++;
       } catch {
@@ -2337,10 +2731,10 @@ async function generateKiro(config, hubDir) {
     }
   } catch {
   }
-  const kiroSkillsDirForDocs = join3(kiroDir, "skills");
-  await mkdir3(kiroSkillsDirForDocs, { recursive: true });
+  const kiroSkillsDirForDocs = join4(kiroDir, "skills");
+  await mkdir4(kiroSkillsDirForDocs, { recursive: true });
   await fetchHubDocsSkill(kiroSkillsDirForDocs);
-  await syncRemoteSources(config, hubDir, join3(kiroDir, "skills"), steeringDir);
+  await syncRemoteSources(config, hubDir, join4(kiroDir, "skills"), steeringDir);
   if (config.mcps?.length) {
     const mcpConfig = {};
     const upstreamSet = getUpstreamNames(config.mcps);
@@ -2353,10 +2747,14 @@ async function generateKiro(config, hubDir) {
         mcpConfig[mcp.name] = buildKiroMcpEntry(mcp, mode);
       }
     }
-    const mcpJsonPath = join3(settingsDir, "mcp.json");
+    const sandbox = getSandboxService(config);
+    if (sandbox && !mcpConfig["sandbox"]) {
+      mcpConfig["sandbox"] = buildSandboxMcpEntry(sandbox.port);
+    }
+    const mcpJsonPath = join4(settingsDir, "mcp.json");
     const disabledState = await readExistingMcpDisabledState(mcpJsonPath);
     applyDisabledState(mcpConfig, disabledState);
-    await writeFile3(
+    await writeFile4(
       mcpJsonPath,
       JSON.stringify({ mcpServers: mcpConfig }, null, 2) + "\n",
       "utf-8"
@@ -2383,13 +2781,13 @@ async function generateKiro(config, hubDir) {
   await generateVSCodeSettings(config, hubDir);
 }
 async function generateVSCodeSettings(config, hubDir) {
-  const vscodeDir = join3(hubDir, ".vscode");
-  await mkdir3(vscodeDir, { recursive: true });
-  const settingsPath = join3(vscodeDir, "settings.json");
+  const vscodeDir = join4(hubDir, ".vscode");
+  await mkdir4(vscodeDir, { recursive: true });
+  const settingsPath = join4(vscodeDir, "settings.json");
   let existing = {};
-  if (existsSync2(settingsPath)) {
+  if (existsSync3(settingsPath)) {
     try {
-      const raw = await readFile3(settingsPath, "utf-8");
+      const raw = await readFile4(settingsPath, "utf-8");
       existing = JSON.parse(raw);
     } catch {
       existing = {};
@@ -2401,14 +2799,14 @@ async function generateVSCodeSettings(config, hubDir) {
     "git.detectSubmodulesLimit": Math.max(config.repos.length * 2, 20)
   };
   const merged = { ...existing, ...managed };
-  await writeFile3(settingsPath, JSON.stringify(merged, null, 2) + "\n", "utf-8");
+  await writeFile4(settingsPath, JSON.stringify(merged, null, 2) + "\n", "utf-8");
   console.log(chalk3.green("  Generated .vscode/settings.json (git multi-repo detection)"));
   const workspaceFile = `${config.name}.code-workspace`;
-  const workspacePath = join3(hubDir, workspaceFile);
+  const workspacePath = join4(hubDir, workspaceFile);
   let existingWorkspace = {};
-  if (existsSync2(workspacePath)) {
+  if (existsSync3(workspacePath)) {
     try {
-      const raw = await readFile3(workspacePath, "utf-8");
+      const raw = await readFile4(workspacePath, "utf-8");
       existingWorkspace = JSON.parse(raw);
     } catch {
       existingWorkspace = {};
@@ -2418,7 +2816,7 @@ async function generateVSCodeSettings(config, hubDir) {
     const existing2 = files.find((f) => f.endsWith(".code-workspace"));
     if (existing2) {
       try {
-        const raw = await readFile3(join3(hubDir, existing2), "utf-8");
+        const raw = await readFile4(join4(hubDir, existing2), "utf-8");
         existingWorkspace = JSON.parse(raw);
       } catch {
         existingWorkspace = {};
@@ -2454,7 +2852,7 @@ async function generateVSCodeSettings(config, hubDir) {
     folders,
     settings: existingWorkspace.settings || {}
   };
-  await writeFile3(workspacePath, JSON.stringify(workspace, null, "	") + "\n", "utf-8");
+  await writeFile4(workspacePath, JSON.stringify(workspace, null, "	") + "\n", "utf-8");
   console.log(chalk3.green(`  Generated ${workspaceFile}`));
 }
 function extractEnvVarsByMcp(mcps) {
@@ -2501,7 +2899,7 @@ async function generateEnvExample(config, hubDir) {
     totalVars++;
   }
   if (totalVars === 0) return;
-  await writeFile3(join3(hubDir, ".env.example"), lines.join("\n") + "\n", "utf-8");
+  await writeFile4(join4(hubDir, ".env.example"), lines.join("\n") + "\n", "utf-8");
   console.log(chalk3.green(`  Generated .env.example (${totalVars} vars)`));
 }
 function buildGitignoreLines(config) {
@@ -2591,7 +2989,7 @@ async function resolveEditor(opts) {
   ]);
   return editor;
 }
-var generateCommand = new Command("generate").description("Generate editor-specific configuration files from hub.yaml").option("-e, --editor <editor>", "Target editor (cursor, claude-code, kiro, opencode)").option("--reset-editor", "Reset saved editor preference and choose again").option("--check", "Check if generated configs are outdated (exit code 1 if outdated)").action(async (opts) => {
+var generateCommand = new Command2("generate").description("Generate editor-specific configuration files from hub.yaml").option("-e, --editor <editor>", "Target editor (cursor, claude-code, kiro, opencode)").option("--reset-editor", "Reset saved editor preference and choose again").option("--check", "Check if generated configs are outdated (exit code 1 if outdated)").action(async (opts) => {
   const hubDir = process.cwd();
   if (opts.check) {
     const result = await checkOutdated(hubDir);
@@ -2656,6 +3054,10 @@ Generating ${generator.name} configuration
 });
 
 export {
+  colors,
+  symbols,
+  horizontalLine,
+  personaCommand,
   generators,
   generateCommand,
   checkAndAutoRegenerate