@agentvalet/register 1.1.1 → 1.4.0

package/README.md

@@ -15,9 +15,29 @@ No installation required. Authenticate with GitHub, and your agent is registered
 1. Opens your browser to authenticate with GitHub
 2. Creates your AgentValet account (or finds your existing one)
 3. Registers this machine as an agent
-4. Writes config to `.agentvalet/` in the current directory
+4. Writes config and your private key to `~/.agentvalet/` in your **home**
+   directory (not the current directory)
 5. Outputs the environment variables you need
 
+## Already have an agent on this machine?
+
+An agent's private key exists only on your machine — the proxy never sees it,
+and there is no rotation endpoint. Overwriting it destroys that identity, along
+with its grants and audit continuity.
+
+So registering while `~/.agentvalet/agent.key` already belongs to a **different**
+agent stops with an error rather than overwriting it. You have two options:
+
+```bash
+# Keep both — store the new agent under ~/.agentvalet/<label>/
+npx @agentvalet/register claim <bind_secret> --label work-laptop
+
+# Replace the existing one — a timestamped backup is written first
+npx @agentvalet/register --force
+```
+
+Re-registering the *same* agent over its own key is always allowed.
+
 ## Requirements
 
 - Node.js 18+

package/dist/index.js

@@ -180,8 +180,72 @@ function sleep(ms) {
 
 // src/save.ts
 import { writeFile, mkdir } from "fs/promises";
+
+// src/config/key-guard.ts
+import { existsSync, copyFileSync, readFileSync } from "fs";
+import { dirname, join } from "path";
+var KeyClobberError = class extends Error {
+  constructor(keyPath, existingAgentId, message) {
+    super(message);
+    this.keyPath = keyPath;
+    this.existingAgentId = existingAgentId;
+    this.name = "KeyClobberError";
+  }
+  keyPath;
+  existingAgentId;
+};
+function existingKeyOwner(keyPath) {
+  if (!existsSync(keyPath)) return null;
+  const configPath = join(dirname(keyPath), "config.json");
+  if (!existsSync(configPath)) return null;
+  try {
+    const parsed = JSON.parse(readFileSync(configPath, "utf8"));
+    const id = parsed.agentId ?? parsed.lastAgentId;
+    return typeof id === "string" && id ? id : null;
+  } catch {
+    return null;
+  }
+}
+function backupExistingKey(keyPath) {
+  if (!existsSync(keyPath)) return null;
+  const stamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
+  let backup = `${keyPath}.bak.${stamp}`;
+  let n = 1;
+  while (existsSync(backup)) backup = `${keyPath}.bak.${stamp}-${n++}`;
+  copyFileSync(keyPath, backup);
+  return backup;
+}
+function assertSafeToWriteKey(keyPath, incomingAgentId, opts = {}) {
+  if (!existsSync(keyPath)) return;
+  const owner = existingKeyOwner(keyPath);
+  if (owner && owner === incomingAgentId) return;
+  if (opts.force) {
+    backupExistingKey(keyPath);
+    return;
+  }
+  const whose = owner ? `agent ${owner}` : "another agent (owner unknown)";
+  throw new KeyClobberError(
+    keyPath,
+    owner,
+    [
+      `${keyPath} already holds the private key for ${whose}.`,
+      "",
+      "Overwriting it would destroy that identity permanently: the key exists",
+      "only on this machine and there is no way to recover or rotate it.",
+      "",
+      "Options:",
+      `  \u2022 Keep both \u2014 move ${keyPath} aside first, or use 'claim --label <name>'`,
+      "    to store an additional agent under ~/.agentvalet/<name>/.",
+      "  \u2022 Replace it \u2014 re-run with --force. The existing key is copied to",
+      `    ${keyPath}.bak.<timestamp> before being replaced.`
+    ].join("\n")
+  );
+}
+
+// src/save.ts
 async function saveOutput(opts) {
   await mkdir(AGENT_DIR, { recursive: true });
+  assertSafeToWriteKey(AGENT_KEY_PATH, opts.agentId, { force: opts.force });
   await writeFile(AGENT_KEY_PATH, opts.privateKey, { mode: 384 });
   saveConfig({
     agentId: opts.agentId,
@@ -196,8 +260,8 @@ async function saveOutput(opts) {
 }
 
 // src/commands/refresh.ts
-import { readFileSync as readFileSync3, writeFileSync as writeFileSync2, existsSync as existsSync4, mkdirSync as mkdirSync2, statSync } from "fs";
-import { dirname, resolve as resolve2 } from "path";
+import { readFileSync as readFileSync4, writeFileSync as writeFileSync2, existsSync as existsSync5, mkdirSync as mkdirSync2, statSync } from "fs";
+import { dirname as dirname2, join as join2, resolve as resolve2 } from "path";
 
 // src/lib/jwt.ts
 import { createSign, createPrivateKey } from "crypto";
@@ -215,13 +279,13 @@ function signJwt(agentId, ownerId, privateKeyPem) {
 }
 
 // src/lib/skill-writer.ts
-import { existsSync, writeFileSync, mkdirSync } from "fs";
+import { existsSync as existsSync2, writeFileSync, mkdirSync } from "fs";
 import { execSync } from "child_process";
 import path from "path";
 import chalk2 from "chalk";
 function writeAgentsMd() {
   const dest = path.join(process.cwd(), "AGENTS.md");
-  if (existsSync(dest)) {
+  if (existsSync2(dest)) {
     console.log(chalk2.dim("  AGENTS.md already exists \u2014 skipping"));
     return;
   }
@@ -232,15 +296,18 @@ Never call platform APIs (Slack, Stripe, Gmail, GitHub, etc.) directly.
 
 ## Making a platform call
 
-Use the \`use_platform\` MCP tool:
+Pick the tool that matches what you are doing:
+
+- \`read_platform\` to read (always GET)
+- \`write_platform\` to create or update (POST, PUT or PATCH)
+- \`delete_platform\` to remove (always DELETE)
 
 \`\`\`
-use_platform({
+write_platform({
   platform: "slack",
   endpoint: "/api/chat.postMessage",
-  method: "POST",
   scope: "slack:write",
-  data: { channel: "#general", text: "Hello" }
+  body: { channel: "#general", text: "Hello" }
 })
 \`\`\`
 
@@ -261,7 +328,7 @@ Do not call platform APIs directly. Tell the user:
 }
 function writeSkillMd() {
   const dest = path.join(process.cwd(), "SKILL.md");
-  if (existsSync(dest)) {
+  if (existsSync2(dest)) {
     console.log(chalk2.dim("  SKILL.md already exists \u2014 skipping"));
     return;
   }
@@ -271,15 +338,16 @@ Routes all platform API calls through AgentValet's credential proxy.
 
 ## Making platform calls
 
-Use the \`use_platform\` tool instead of calling APIs directly:
+Use \`read_platform\`, \`write_platform\` or \`delete_platform\` instead of
+calling APIs directly. Reads use read_platform; creates and updates use
+write_platform; deletions use delete_platform.
 
 \`\`\`
-use_platform({
+write_platform({
   platform: "slack",
   endpoint: "/api/chat.postMessage",
-  method: "POST",
   scope: "slack:write",
-  data: { channel: "#general", text: "Hello" }
+  body: { channel: "#general", text: "Hello" }
 })
 \`\`\`
 
@@ -298,7 +366,7 @@ Dashboard: https://app.agentvalet.ai
 }
 function writeQuickstartDoc(opts) {
   const dest = path.join(process.cwd(), "AGENTVALET.md");
-  if (existsSync(dest)) {
+  if (existsSync2(dest)) {
     console.log(chalk2.dim("  AGENTVALET.md already exists \u2014 skipping"));
     return;
   }
@@ -381,9 +449,9 @@ AGENT_PRIVATE_KEY_PATH=${keyPath}
 }
 function writeFactoryDroidDroid() {
   const droidsDir = path.join(process.cwd(), ".factory", "droids");
-  if (!existsSync(droidsDir)) mkdirSync(droidsDir, { recursive: true });
+  if (!existsSync2(droidsDir)) mkdirSync(droidsDir, { recursive: true });
   const dest = path.join(droidsDir, "agentvalet.yaml");
-  if (existsSync(dest)) {
+  if (existsSync2(dest)) {
     console.log(chalk2.dim("  Factory Droid: .factory/droids/agentvalet.yaml already exists"));
     return;
   }
@@ -410,7 +478,8 @@ instructions: |
   ## Rules \u2014 read before every platform call
 
   1. NEVER call platform APIs (Slack, Stripe, Gmail, GitHub, etc.) directly.
-     Always use the \`use_platform\` MCP tool.
+     Always use \`read_platform\` (reads), \`write_platform\` (creates and
+     updates) or \`delete_platform\` (deletions).
 
   2. Call \`list_platforms\` at the start of any session that involves
      platform calls. Do not assume platforms are available.
@@ -418,7 +487,7 @@ instructions: |
   3. Call \`authzen_evaluate\` before any destructive operation
      (delete, send, charge, publish). Do not proceed if decision=false.
 
-  4. If \`use_platform\` returns \`{ status: "pending_approval" }\`,
+  4. If a platform call returns \`{ status: "pending_approval" }\`,
      wait for human approval. Do not retry the call.
 
   5. If AgentValet MCP tools are unavailable, stop and tell the user:
@@ -428,12 +497,11 @@ instructions: |
   ## Making a platform call
 
   \`\`\`
-  use_platform({
+  write_platform({
     platform: "slack",
     endpoint: "/api/chat.postMessage",
-    method: "POST",
     scope: "slack:write",
-    data: { channel: "#general", text: "Hello" }
+    body: { channel: "#general", text: "Hello" }
   })
   \`\`\`
 
@@ -453,9 +521,9 @@ instructions: |
 }
 function writeFactoryDroidCommand() {
   const commandsDir = path.join(process.cwd(), ".factory", "commands");
-  if (!existsSync(commandsDir)) mkdirSync(commandsDir, { recursive: true });
+  if (!existsSync2(commandsDir)) mkdirSync(commandsDir, { recursive: true });
   const statusDest = path.join(commandsDir, "av-status.md");
-  if (!existsSync(statusDest)) {
+  if (!existsSync2(statusDest)) {
     const statusContent = `# /av-status
 
 Check your AgentValet agent status and approved platform connections.
@@ -478,7 +546,7 @@ Check your AgentValet agent status and approved platform connections.
     console.log(chalk2.dim("  Factory Droid: .factory/commands/av-status.md already exists"));
   }
   const registerDest = path.join(commandsDir, "av-register.md");
-  if (!existsSync(registerDest)) {
+  if (!existsSync2(registerDest)) {
     const registerContent = `# /av-register
 
 Register or re-register this project with AgentValet.
@@ -505,9 +573,9 @@ After running, approve the agent at: https://app.agentvalet.ai/agents
 }
 function writeFactoryDroidReliabilityDroid() {
   const droidsDir = path.join(process.cwd(), ".factory", "droids");
-  if (!existsSync(droidsDir)) mkdirSync(droidsDir, { recursive: true });
+  if (!existsSync2(droidsDir)) mkdirSync(droidsDir, { recursive: true });
   const dest = path.join(droidsDir, "agentvalet-reliability.yaml");
-  if (existsSync(dest)) return;
+  if (existsSync2(dest)) return;
   const content = `# AgentValet Reliability Droid
 # Monitors agent call patterns and surfaces governance issues
 # Commit this file to your repo
@@ -540,7 +608,8 @@ instructions: |
      - If decision=false: block the call, explain why, suggest alternatives
      - If decision=true: allow, but log it
 
-  2. WHEN a droid calls \`use_platform\`, verify:
+  2. WHEN a droid calls \`read_platform\`, \`write_platform\` or
+     \`delete_platform\`, verify:
      - The platform is in the approved list from \`list_platforms\`
      - The scope matches what was approved
      - The call hasn't exceeded rate limits
@@ -589,7 +658,8 @@ function ensureMcpServer() {
 function generatePermissionsFile(agentId, ownerId, permissions) {
   const now = (/* @__PURE__ */ new Date()).toISOString();
   const platformSections = permissions.length === 0 ? "_No platforms approved yet. Visit https://app.agentvalet.ai to connect platforms._" : permissions.map((p) => {
-    const scopeList = p.scopes.map((s) => `  - \`${s}\``).join("\n");
+    const gated = new Set(p.approvalScopes ?? []);
+    const scopeList = p.scopes.map((s) => `  - \`${s}\`${gated.has(s) ? " \u2014 requires human approval" : ""}`).join("\n");
     const approvalNote = p.requireApproval ? "\n  > Requires human approval before executing.\n" : "";
     return `### ${p.platformName} (\`${p.platformId}\`)
 
@@ -611,19 +681,58 @@ ${platformSections}
 
 ---
 
+## Before any platform call
+
+1. **Check AgentValet first.** For any action on an external platform (Slack,
+   GitHub, Stripe, Gmail, Outlook, Notion, Linear, Jira, HubSpot, Salesforce,
+   or any other SaaS), call \`mcp__agentvalet__list_platforms\` **before** you
+   assume the platform is unavailable or reach for another route.
+2. **If the platform is listed here, you must use it.** Do not call the
+   platform's API directly, and do not use another MCP server's tool for a
+   platform AgentValet covers \u2014 that bypasses the audit log, the approval
+   flow, and the scope limits the owner configured.
+3. **If it is not listed**, say so: "AgentValet doesn't cover <platform> yet."
+   Ask the user whether to request the integration from their AgentValet
+   owner. Do not silently fall back to direct API calls or raw keys found in
+   the environment.
+4. **Destructive scopes** (\`*.delete\`, \`stripe:charge\`, \`mail:send\`) need
+   human approval. Warn the user before invoking them.
+5. **On \`pending_approval\`** \u2014 the action is queued and runs when the owner
+   approves. Tell the user and **do not retry**; a retry queues a duplicate.
+6. **If the AgentValet MCP tools are unavailable**, stop. Tell the user
+   "AgentValet MCP is not connected. Run: npx @agentvalet/register". Do not
+   attempt the platform call without governance.
+
+Read scopes are auto-approved. Write scopes may require approval. Destructive
+scopes always require approval.
+
+---
+
 ## How to call a platform
 
-All platform calls **must** go through the \`mcp__agentvalet__use_platform\` MCP tool.
+All platform calls **must** go through the AgentValet MCP tools. Pick the one
+that matches the operation:
 
-**NEVER** write inline JWT signing code, \`node -e\` scripts, or manual HTTP calls. The MCP tool handles all authentication internally.
+| Operation | Tool | Method |
+|---|---|---|
+| Read | \`mcp__agentvalet__read_platform\` | always GET |
+| Create or update | \`mcp__agentvalet__write_platform\` | POST (default), PUT or PATCH |
+| Delete | \`mcp__agentvalet__delete_platform\` | always DELETE |
+
+**NEVER** write inline JWT signing code, \`node -e\` scripts, or manual HTTP calls. The MCP tools handle all authentication internally.
 
 \`\`\`
-mcp__agentvalet__use_platform({
+mcp__agentvalet__read_platform({
+  platform: "<platformId>",
+  endpoint: "<endpoint>",
+  scope: "<scope>"
+})
+
+mcp__agentvalet__write_platform({
   platform: "<platformId>",
   endpoint: "<endpoint>",
-  method: "POST",
   scope: "<scope>",
-  data: { ... }
+  body: { ... }
 })
 \`\`\`
 
@@ -632,7 +741,7 @@ To refresh this file: \`npx @agentvalet/register refresh\`
 }
 
 // src/lib/require-agent.ts
-import { existsSync as existsSync2, readFileSync as readFileSync2 } from "fs";
+import { existsSync as existsSync3, readFileSync as readFileSync3 } from "fs";
 import { resolve } from "path";
 import chalk3 from "chalk";
 var NO_AGENT_MSG = chalk3.red("\n  \u2717 No agent registered.\n") + chalk3.dim(
@@ -665,9 +774,9 @@ function tryResolveAgent(envFile = ".env.agentvalet") {
   if (!keyPath) keyPath = AGENT_KEY_PATH;
   if (!agentId || !ownerId) {
     const envPath = resolve(envFile);
-    if (existsSync2(envPath)) {
+    if (existsSync3(envPath)) {
       try {
-        const vars = parseEnvFile(readFileSync2(envPath, "utf-8"));
+        const vars = parseEnvFile(readFileSync3(envPath, "utf-8"));
         agentId = agentId ?? vars["AGENTVALET_AGENT_ID"];
         ownerId = ownerId ?? vars["AGENTVALET_OWNER_ID"];
         apiUrl = vars["AGENTVALET_API_URL"] ?? apiUrl;
@@ -681,12 +790,12 @@ function tryResolveAgent(envFile = ".env.agentvalet") {
   if (process.env["AGENTVALET_API_URL"]) apiUrl = process.env["AGENTVALET_API_URL"];
   if (process.env["AGENTVALET_PRIVATE_KEY_PATH"]) keyPath = process.env["AGENTVALET_PRIVATE_KEY_PATH"];
   if (!agentId || !ownerId || !keyPath) return null;
-  if (!existsSync2(resolve(keyPath))) return null;
+  if (!existsSync3(resolve(keyPath))) return null;
   return { agentId, ownerId, keyPath, apiUrl };
 }
 
 // src/config/frameworks.ts
-import { existsSync as existsSync3 } from "fs";
+import { existsSync as existsSync4 } from "fs";
 import { execSync as execSync2 } from "child_process";
 import os from "os";
 import path2 from "path";
@@ -704,27 +813,27 @@ function codexDesktopInstalled() {
   const home = os.homedir();
   const platform = process.platform;
   if (platform === "darwin") {
-    return existsSync3("/Applications/Codex.app") || existsSync3(path2.join(home, "Applications", "Codex.app"));
+    return existsSync4("/Applications/Codex.app") || existsSync4(path2.join(home, "Applications", "Codex.app"));
   }
   if (platform === "win32") {
     const localAppData = process.env.LOCALAPPDATA ?? path2.join(home, "AppData", "Local");
     const programFiles = process.env["ProgramFiles"] ?? "C:\\Program Files";
-    return existsSync3(path2.join(localAppData, "Programs", "codex")) || existsSync3(path2.join(localAppData, "Programs", "Codex")) || existsSync3(path2.join(programFiles, "Codex"));
+    return existsSync4(path2.join(localAppData, "Programs", "codex")) || existsSync4(path2.join(localAppData, "Programs", "Codex")) || existsSync4(path2.join(programFiles, "Codex"));
   }
-  return existsSync3("/usr/share/applications/codex.desktop") || existsSync3(path2.join(home, ".local", "share", "applications", "codex.desktop"));
+  return existsSync4("/usr/share/applications/codex.desktop") || existsSync4(path2.join(home, ".local", "share", "applications", "codex.desktop"));
 }
 function claudeDesktopInstalled() {
   const home = os.homedir();
   const platform = process.platform;
   if (platform === "darwin") {
-    return existsSync3("/Applications/Claude.app") || existsSync3(path2.join(home, "Library", "Application Support", "Claude"));
+    return existsSync4("/Applications/Claude.app") || existsSync4(path2.join(home, "Library", "Application Support", "Claude"));
   }
   if (platform === "win32") {
     const appData = process.env.APPDATA ?? path2.join(home, "AppData", "Roaming");
     const localAppData = process.env.LOCALAPPDATA ?? path2.join(home, "AppData", "Local");
-    return existsSync3(path2.join(appData, "Claude")) || existsSync3(path2.join(localAppData, "AnthropicClaude")) || existsSync3(path2.join(localAppData, "Programs", "claude"));
+    return existsSync4(path2.join(appData, "Claude")) || existsSync4(path2.join(localAppData, "AnthropicClaude")) || existsSync4(path2.join(localAppData, "Programs", "claude"));
   }
-  return existsSync3(path2.join(home, ".config", "Claude"));
+  return existsSync4(path2.join(home, ".config", "Claude"));
 }
 function cursorInstalled() {
   const home = os.homedir();
@@ -732,24 +841,24 @@ function cursorInstalled() {
   if (platform === "win32") {
     const appData = process.env.APPDATA ?? path2.join(home, "AppData", "Roaming");
     const localAppData = process.env.LOCALAPPDATA ?? path2.join(home, "AppData", "Local");
-    return existsSync3(path2.join(appData, "Cursor")) || existsSync3(path2.join(localAppData, "Programs", "cursor"));
+    return existsSync4(path2.join(appData, "Cursor")) || existsSync4(path2.join(localAppData, "Programs", "cursor"));
   }
   if (platform === "darwin") {
-    return existsSync3(path2.join(home, "Library", "Application Support", "Cursor")) || existsSync3("/Applications/Cursor.app");
+    return existsSync4(path2.join(home, "Library", "Application Support", "Cursor")) || existsSync4("/Applications/Cursor.app");
   }
-  return existsSync3(path2.join(home, ".config", "Cursor")) || existsSync3("/usr/share/applications/cursor.desktop");
+  return existsSync4(path2.join(home, ".config", "Cursor")) || existsSync4("/usr/share/applications/cursor.desktop");
 }
 function detectFrameworks() {
   const home = os.homedir();
   return {
-    codex: existsSync3(path2.join(home, ".codex")) || tryBinary("codex"),
+    codex: existsSync4(path2.join(home, ".codex")) || tryBinary("codex"),
     codexDesktop: codexDesktopInstalled(),
-    claudeCode: existsSync3(path2.join(home, ".claude")) || tryBinary("claude"),
+    claudeCode: existsSync4(path2.join(home, ".claude")) || tryBinary("claude"),
     claudeDesktop: claudeDesktopInstalled(),
-    cursor: existsSync3(path2.join(process.cwd(), ".cursor")) || cursorInstalled(),
+    cursor: existsSync4(path2.join(process.cwd(), ".cursor")) || cursorInstalled(),
     cursorCli: tryBinary("cursor-agent"),
-    openclaw: existsSync3(path2.join(home, ".openclaw")),
-    factoryDroid: existsSync3(path2.join(home, ".factory")) || existsSync3(path2.join(process.cwd(), ".factory"))
+    openclaw: existsSync4(path2.join(home, ".openclaw")),
+    factoryDroid: existsSync4(path2.join(home, ".factory")) || existsSync4(path2.join(process.cwd(), ".factory"))
   };
 }
 function resolveAgentType(detected) {
@@ -816,22 +925,55 @@ var CLAUDE_START = "<!-- agentvalet:start -->";
 var CLAUDE_END = "<!-- agentvalet:end -->";
 var HOOK_COMMAND = "npx @agentvalet/register refresh --if-stale --quiet 2>/dev/null || true";
 var HOOK_MARKER = "agentvalet/register refresh";
+function projectRootFor(outputPath) {
+  return dirname2(dirname2(resolve2(outputPath)));
+}
 function writePermissionsFromEvent(agentId, ownerId, platforms, outputPath = "./.claude/agentvalet-permissions.md") {
   const content = generatePermissionsFile(agentId, ownerId, platforms);
   const resolvedPath = resolve2(outputPath);
-  mkdirSync2(dirname(resolvedPath), { recursive: true });
+  const projectRoot = projectRootFor(resolvedPath);
+  mkdirSync2(dirname2(resolvedPath), { recursive: true });
   writeFileSync2(resolvedPath, content, "utf-8");
-  embedInClaudeMd(content);
-  ensureHook();
+  embedInClaudeMd(content, projectRoot);
+  ensureHook(projectRoot);
+}
+async function writeGovernanceInstructions(agentId, ownerId) {
+  const writeRulesOnly = () => {
+    try {
+      writePermissionsFromEvent(agentId, ownerId, []);
+      console.log("  \u2713 CLAUDE.md \u2014 AgentValet governance rules");
+      return true;
+    } catch {
+      return false;
+    }
+  };
+  if (!tryResolveAgent()) {
+    writeRulesOnly();
+    return;
+  }
+  try {
+    await runRefresh({
+      envFile: ".env.agentvalet",
+      outputPath: ".claude/agentvalet-permissions.md",
+      ifStale: false,
+      quiet: true
+    });
+    console.log("  \u2713 CLAUDE.md \u2014 AgentValet governance rules and approved platforms");
+  } catch {
+    if (writeRulesOnly()) {
+      console.log("    Run `npx @agentvalet/register refresh` once approved to fill in platforms");
+    }
+  }
 }
 async function runRefresh(options) {
   const outputPath = resolve2(options.outputPath);
+  const projectRoot = projectRootFor(outputPath);
   if (options.ifStale) {
     try {
       const stat = statSync(outputPath);
       const fileIsFresh = Date.now() - stat.mtimeMs < 36e5;
-      const claudeMdPath = resolve2("CLAUDE.md");
-      const claudeMd = existsSync4(claudeMdPath) ? readFileSync3(claudeMdPath, "utf-8") : "";
+      const claudeMdPath = join2(projectRoot, "CLAUDE.md");
+      const claudeMd = existsSync5(claudeMdPath) ? readFileSync4(claudeMdPath, "utf-8") : "";
       const blockStart = claudeMd.indexOf(CLAUDE_START);
       const blockEnd = claudeMd.indexOf(CLAUDE_END);
       const blockContent = blockStart !== -1 && blockEnd !== -1 ? claudeMd.slice(blockStart, blockEnd) : "";
@@ -841,14 +983,14 @@ async function runRefresh(options) {
     }
   }
   const creds = tryResolveAgent(options.envFile);
-  if (!creds || !existsSync4(resolve2(creds.keyPath))) {
+  if (!creds || !existsSync5(resolve2(creds.keyPath))) {
     console.error("  \u2717 No agent registered.\n  Run the following command first to register an agent in this directory:\n\n    npx @agentvalet/register\n");
     process.exit(1);
   }
   const { agentId, ownerId, keyPath, apiUrl } = creds;
   let privateKeyPem;
   try {
-    privateKeyPem = readFileSync3(keyPath, "utf-8");
+    privateKeyPem = readFileSync4(keyPath, "utf-8");
   } catch {
     throw new Error(`Cannot read private key: ${keyPath}`);
   }
@@ -866,17 +1008,17 @@ async function runRefresh(options) {
   const json = await res.json();
   const platforms = json.data?.platforms ?? [];
   const content = generatePermissionsFile(agentId, ownerId, platforms);
-  mkdirSync2(dirname(outputPath), { recursive: true });
+  mkdirSync2(dirname2(outputPath), { recursive: true });
   writeFileSync2(outputPath, content, "utf-8");
-  embedInClaudeMd(content);
-  ensureHook();
+  embedInClaudeMd(content, projectRoot);
+  ensureHook(projectRoot);
   const detected = detectFrameworks();
   const refreshed = [];
   if (detected.codex || detected.codexDesktop) {
-    if (embedPermissionsBlock(resolve2("AGENTS.md"), content)) refreshed.push("AGENTS.md");
+    if (embedPermissionsBlock(join2(projectRoot, "AGENTS.md"), content)) refreshed.push("AGENTS.md");
   }
   if (detected.openclaw) {
-    if (embedPermissionsBlock(resolve2("SKILL.md"), content)) refreshed.push("SKILL.md");
+    if (embedPermissionsBlock(join2(projectRoot, "SKILL.md"), content)) refreshed.push("SKILL.md");
   }
   if (!options.quiet) {
     const extras = refreshed.length > 0 ? ` (also: ${refreshed.join(", ")})` : "";
@@ -884,9 +1026,9 @@ async function runRefresh(options) {
   }
 }
 function embedPermissionsBlock(filePath, permissionsContent) {
-  if (!existsSync4(filePath)) return false;
+  if (!existsSync5(filePath)) return false;
   try {
-    const existing = readFileSync3(filePath, "utf-8");
+    const existing = readFileSync4(filePath, "utf-8");
     const block = `${PERMISSIONS_START}
 ${permissionsContent.trimEnd()}
 ${PERMISSIONS_END}`;
@@ -908,19 +1050,19 @@ ${block}
     return false;
   }
 }
-function embedInClaudeMd(permissionsContent) {
-  const claudeMdPath = resolve2("CLAUDE.md");
+function embedInClaudeMd(permissionsContent, projectRoot) {
+  const claudeMdPath = join2(projectRoot, "CLAUDE.md");
   const block = `${CLAUDE_START}
 ${permissionsContent.trimEnd()}
 ${CLAUDE_END}`;
-  if (!existsSync4(claudeMdPath)) {
+  if (!existsSync5(claudeMdPath)) {
     writeFileSync2(claudeMdPath, `# Agent Instructions
 
 ${block}
 `, "utf-8");
     return;
   }
-  const existing = readFileSync3(claudeMdPath, "utf-8");
+  const existing = readFileSync4(claudeMdPath, "utf-8");
   if (existing.includes(CLAUDE_START)) {
     const replaced = existing.replace(
       new RegExp(`${CLAUDE_START}[\\s\\S]*?${CLAUDE_END}`, "m"),
@@ -935,12 +1077,12 @@ ${block}
 `, "utf-8");
   }
 }
-function ensureHook() {
-  const settingsPath = resolve2(".claude/settings.local.json");
+function ensureHook(projectRoot) {
+  const settingsPath = join2(projectRoot, ".claude", "settings.local.json");
   let settings = {};
-  if (existsSync4(settingsPath)) {
+  if (existsSync5(settingsPath)) {
     try {
-      settings = JSON.parse(readFileSync3(settingsPath, "utf-8"));
+      settings = JSON.parse(readFileSync4(settingsPath, "utf-8"));
     } catch {
       return;
     }
@@ -956,22 +1098,28 @@ function ensureHook() {
   }
   const perms = settings.permissions ?? {};
   const allow = perms.allow ?? [];
-  const mcpAllows = ["mcp__agentvalet__list_platforms", "mcp__agentvalet__use_platform"];
+  const mcpAllows = [
+    "mcp__agentvalet__list_platforms",
+    "mcp__agentvalet__read_platform",
+    "mcp__agentvalet__write_platform",
+    "mcp__agentvalet__delete_platform",
+    "mcp__agentvalet__use_platform"
+  ];
   const missing = mcpAllows.filter((e) => !allow.includes(e));
   if (missing.length > 0) {
     perms.allow = [...allow, ...missing];
     settings.permissions = perms;
   }
-  mkdirSync2(dirname(settingsPath), { recursive: true });
+  mkdirSync2(dirname2(settingsPath), { recursive: true });
   writeFileSync2(settingsPath, JSON.stringify(settings, null, 2) + "\n", "utf-8");
-  ensureMcpJson();
+  ensureMcpJson(projectRoot);
 }
-function ensureMcpJson() {
-  const mcpJsonPath = resolve2(".mcp.json");
+function ensureMcpJson(projectRoot) {
+  const mcpJsonPath = join2(projectRoot, ".mcp.json");
   let mcpConfig = {};
-  if (existsSync4(mcpJsonPath)) {
+  if (existsSync5(mcpJsonPath)) {
     try {
-      mcpConfig = JSON.parse(readFileSync3(mcpJsonPath, "utf-8"));
+      mcpConfig = JSON.parse(readFileSync4(mcpJsonPath, "utf-8"));
     } catch {
       return;
     }
@@ -1170,7 +1318,7 @@ async function writeLocalConfig(config) {
 // src/output/env.ts
 import chalk6 from "chalk";
 import { appendFile as appendFile2, writeFile as writeFile3 } from "fs/promises";
-import { existsSync as existsSync5 } from "fs";
+import { existsSync as existsSync6 } from "fs";
 import path4 from "path";
 function formatEnvBlock(vars) {
   return Object.entries(vars).map(([key, value]) => {
@@ -1181,7 +1329,7 @@ function formatEnvBlock(vars) {
 
 // src/config/ide.ts
 import { mkdir as mkdir3, writeFile as writeFile4, readFile as readFile2, appendFile as appendFile3, copyFile } from "fs/promises";
-import { existsSync as existsSync6 } from "fs";
+import { existsSync as existsSync7 } from "fs";
 import path5 from "path";
 import os2 from "os";
 function buildMcpEntry(params) {
@@ -1218,7 +1366,7 @@ function claudeDesktopFriendly() {
 }
 async function mergeJsonFile(filePath, key, value) {
   let existing = {};
-  if (existsSync6(filePath)) {
+  if (existsSync7(filePath)) {
     try {
       const text = await readFile2(filePath, "utf8");
       existing = JSON.parse(text);
@@ -1230,48 +1378,6 @@ async function mergeJsonFile(filePath, key, value) {
   existing.mcpServers = mcpServers;
   await writeFile4(filePath, JSON.stringify(existing, null, 2) + "\n", "utf8");
 }
-function buildClaudeMd(agentId, ownerId, proxyUrl) {
-  return `# AgentValet \u2014 Credential Governance
-
-Agent ID: \`${agentId}\`
-Owner ID: \`${ownerId}\`
-
-All external platform API calls **must** go through the AgentValet proxy.
-Never call platform APIs (Slack, Stripe, Gmail, GitHub, etc.) directly.
-
-## Making a platform call
-
-Use the \`mcp__agentvalet__use_platform\` MCP tool:
-
-\`\`\`
-mcp__agentvalet__use_platform({
-  platform: "slack",
-  endpoint: "/api/chat.postMessage",
-  method: "POST",
-  scope: "slack:write",
-  data: { channel: "#general", text: "Hello" }
-})
-\`\`\`
-
-## Before any platform session
-
-1. Call \`mcp__agentvalet__list_platforms\` to see approved platforms and scopes
-2. Call \`mcp__agentvalet__authzen_evaluate\` before destructive operations
-3. If a call returns \`pending_approval\` \u2014 wait, do not retry
-
-## Rules
-
-- **NEVER** write inline JWT signing code, \`node -e\` scripts, or manual HTTP calls
-- The MCP tool handles authentication automatically
-- \`AGENT_PRIVATE_KEY_PATH\` points to your key \u2014 do not read or log it
-
-## If AgentValet MCP is not connected
-
-Tell the user: "AgentValet MCP is not connected. Run: npx @agentvalet/register"
-
-Dashboard: ${proxyUrl.replace("api.", "app.")}
-`;
-}
 function buildCodexTomlBlock(params) {
   return `
 [mcp_servers.agentvalet]
@@ -1282,8 +1388,8 @@ env = { AGENT_ID = "${params.agentId}", OWNER_ID = "${params.ownerId}", PROXY_UR
 }
 async function appendCodexConfig(configPath) {
   const dir = path5.dirname(configPath);
-  if (!existsSync6(dir)) await mkdir3(dir, { recursive: true });
-  const existing = existsSync6(configPath) ? await readFile2(configPath, "utf8") : "";
+  if (!existsSync7(dir)) await mkdir3(dir, { recursive: true });
+  const existing = existsSync7(configPath) ? await readFile2(configPath, "utf8") : "";
   if (existing.includes("[mcp_servers.agentvalet]")) return false;
   return true;
 }
@@ -1292,7 +1398,7 @@ async function writeGlobalFrameworkConfigs(params) {
   const codexDir = path5.join(os2.homedir(), ".codex");
   const codexConfigPath = path5.join(codexDir, "config.toml");
   try {
-    if (!existsSync6(codexDir)) await mkdir3(codexDir, { recursive: true });
+    if (!existsSync7(codexDir)) await mkdir3(codexDir, { recursive: true });
     if (await appendCodexConfig(codexConfigPath)) {
       await appendFile3(codexConfigPath, buildCodexTomlBlock(params), "utf8");
       written.push("~/.codex/config.toml");
@@ -1317,7 +1423,7 @@ async function writeCodexProjectConfig(params) {
   return written;
 }
 async function stripAgentvaletFromMcpJson(filePath) {
-  if (!existsSync6(filePath)) return false;
+  if (!existsSync7(filePath)) return false;
   try {
     const text = await readFile2(filePath, "utf8");
     const config = JSON.parse(text);
@@ -1341,7 +1447,7 @@ async function cleanProjectScopedEntries() {
     cleaned.push(".cursor/mcp.json (project entry removed)");
   }
   const factoryProjectMcp = path5.join(cwd, ".factory/mcp.json");
-  if (existsSync6(factoryProjectMcp)) {
+  if (existsSync7(factoryProjectMcp)) {
     try {
       const text = await readFile2(factoryProjectMcp, "utf8");
       const config = JSON.parse(text);
@@ -1407,17 +1513,6 @@ async function writeIdeConfigs(params) {
       } catch (err) {
         console.warn(`  Warning: could not write .mcp.json: ${err.message}`);
       }
-      const claudeMdPath = path5.join(cwd, "CLAUDE.md");
-      if (!existsSync6(claudeMdPath)) {
-        try {
-          await writeFile4(claudeMdPath, buildClaudeMd(params.agentId, params.ownerId, params.proxyUrl), "utf8");
-          written.push("CLAUDE.md");
-        } catch (err) {
-          console.warn(`  Warning: could not write CLAUDE.md: ${err.message}`);
-        }
-      } else {
-        written.push("CLAUDE.md (already exists \u2014 skipped)");
-      }
     }
     if (detected.cursor || detected.cursorCli) {
       const cursorDir = path5.join(cwd, ".cursor");
@@ -1443,7 +1538,7 @@ async function writeIdeConfigs(params) {
 }
 async function mergeFactoryDroidMcpJson(filePath, key, value) {
   let existing = {};
-  if (existsSync6(filePath)) {
+  if (existsSync7(filePath)) {
     try {
       const text = await readFile2(filePath, "utf8");
       existing = JSON.parse(text);
@@ -1457,7 +1552,7 @@ async function mergeFactoryDroidMcpJson(filePath, key, value) {
 }
 async function updateGitignoreForFactoryDroid() {
   const gitignorePath = path5.join(process.cwd(), ".gitignore");
-  if (!existsSync6(gitignorePath)) return;
+  if (!existsSync7(gitignorePath)) return;
   const existing = await readFile2(gitignorePath, "utf8");
   if (existing.includes(".factory/mcp.json")) return;
   const additions = [
@@ -1676,6 +1771,7 @@ async function registerAgentFlow(apiKey, ownerId, scope = "user", presetName) {
         detected
       });
     }
+    await writeGovernanceInstructions(agent.agent_id, ownerId);
     ensureMcpServer();
   } else if (shouldSetup === false) {
     console.log("");
@@ -1838,8 +1934,8 @@ import chalk10 from "chalk";
 // src/commands/uninstall.ts
 import { Command as Command2 } from "commander";
 import chalk9 from "chalk";
-import { existsSync as existsSync7, readFileSync as readFileSync4, writeFileSync as writeFileSync3, rmSync } from "fs";
-import { resolve as resolve3, join } from "path";
+import { existsSync as existsSync8, readFileSync as readFileSync5, writeFileSync as writeFileSync3, rmSync } from "fs";
+import { resolve as resolve3, join as join3 } from "path";
 import { homedir } from "os";
 var CLAUDE_START2 = "<!-- agentvalet:start -->";
 var CLAUDE_END2 = "<!-- agentvalet:end -->";
@@ -1847,9 +1943,9 @@ var PERMISSIONS_START2 = "<!-- agentvalet:permissions:start -->";
 var PERMISSIONS_END2 = "<!-- agentvalet:permissions:end -->";
 var HOOK_MARKER2 = "agentvalet/register refresh";
 function stripPermissionsBlock(filePath) {
-  if (!existsSync7(filePath)) return false;
+  if (!existsSync8(filePath)) return false;
   try {
-    const content = readFileSync4(filePath, "utf-8");
+    const content = readFileSync5(filePath, "utf-8");
     if (!content.includes(PERMISSIONS_START2)) return false;
     const stripped = content.replace(new RegExp(`${PERMISSIONS_START2}[\\s\\S]*?${PERMISSIONS_END2}`, "m"), "").replace(/(\r?\n){3,}/g, "\n\n").trimEnd();
     writeFileSync3(filePath, stripped + "\n", "utf-8");
@@ -1860,8 +1956,8 @@ function stripPermissionsBlock(filePath) {
 }
 function stripClaudeMd() {
   const path8 = resolve3("CLAUDE.md");
-  if (!existsSync7(path8)) return;
-  let content = readFileSync4(path8, "utf-8");
+  if (!existsSync8(path8)) return;
+  let content = readFileSync5(path8, "utf-8");
   content = content.replace(new RegExp(`${CLAUDE_START2}[\\s\\S]*?${CLAUDE_END2}`, "m"), "");
   content = content.replace(/^@\.claude\/agentvalet-permissions\.md\s*$/m, "");
   content = content.replace(/(\r?\n){3,}/g, "\n\n").trim();
@@ -1869,9 +1965,9 @@ function stripClaudeMd() {
 }
 function stripSettingsJson() {
   const path8 = resolve3(".claude/settings.local.json");
-  if (!existsSync7(path8)) return;
+  if (!existsSync8(path8)) return;
   try {
-    const settings = JSON.parse(readFileSync4(path8, "utf-8"));
+    const settings = JSON.parse(readFileSync5(path8, "utf-8"));
     const hooks = settings.hooks ?? {};
     const ups = hooks.UserPromptSubmit ?? [];
     hooks.UserPromptSubmit = ups.filter(
@@ -1887,9 +1983,9 @@ function stripSettingsJson() {
   }
 }
 function stripMcpJson(filePath, options = {}) {
-  if (!existsSync7(filePath)) return false;
+  if (!existsSync8(filePath)) return false;
   try {
-    const config = JSON.parse(readFileSync4(filePath, "utf-8"));
+    const config = JSON.parse(readFileSync5(filePath, "utf-8"));
     let removed = false;
     if (options.wrapped === false) {
       if (config["agentvalet"] !== void 0) {
@@ -1913,9 +2009,9 @@ function stripMcpJson(filePath, options = {}) {
   }
 }
 function stripCodexTomlAt(filePath) {
-  if (!existsSync7(filePath)) return false;
+  if (!existsSync8(filePath)) return false;
   try {
-    const content = readFileSync4(filePath, "utf-8");
+    const content = readFileSync5(filePath, "utf-8");
     if (!content.includes("[mcp_servers.agentvalet]")) return false;
     const stripped = content.replace(
       /\r?\n?\[mcp_servers\.agentvalet\][\s\S]*?(?=\r?\n\[|\r?\n*$)/,
@@ -1928,9 +2024,9 @@ function stripCodexTomlAt(filePath) {
   }
 }
 function isAgentValetGeneratedDoc(filePath, markers) {
-  if (!existsSync7(filePath)) return false;
+  if (!existsSync8(filePath)) return false;
   try {
-    const content = readFileSync4(filePath, "utf-8");
+    const content = readFileSync5(filePath, "utf-8");
     const firstLine = content.split(/\r?\n/).find((l) => l.trim().length > 0) ?? "";
     return markers.some((m) => firstLine.startsWith(m));
   } catch {
@@ -1942,13 +2038,13 @@ function cleanLocally() {
   const stripped = [];
   const r = (p) => {
     const abs = resolve3(p);
-    if (existsSync7(abs)) {
+    if (existsSync8(abs)) {
       rmSync(abs, { recursive: true, force: true });
       removed.push(abs);
     }
   };
   const rAbs = (abs) => {
-    if (existsSync7(abs)) {
+    if (existsSync8(abs)) {
       rmSync(abs, { recursive: true, force: true });
       removed.push(abs);
     }
@@ -1971,12 +2067,12 @@ function cleanLocally() {
   if (stripMcpJson(resolve3(".cursor/mcp.json"))) stripped.push(".cursor/mcp.json");
   if (stripMcpJson(resolve3(".factory/mcp.json"), { wrapped: false })) stripped.push(".factory/mcp.json");
   const home = homedir();
-  if (stripMcpJson(join(home, ".claude.json"))) stripped.push("~/.claude.json");
-  const claudeDesktopConfig = process.platform === "darwin" ? join(home, "Library", "Application Support", "Claude", "claude_desktop_config.json") : process.platform === "win32" ? join(process.env.APPDATA ?? join(home, "AppData", "Roaming"), "Claude", "claude_desktop_config.json") : join(home, ".config", "Claude", "claude_desktop_config.json");
+  if (stripMcpJson(join3(home, ".claude.json"))) stripped.push("~/.claude.json");
+  const claudeDesktopConfig = process.platform === "darwin" ? join3(home, "Library", "Application Support", "Claude", "claude_desktop_config.json") : process.platform === "win32" ? join3(process.env.APPDATA ?? join3(home, "AppData", "Roaming"), "Claude", "claude_desktop_config.json") : join3(home, ".config", "Claude", "claude_desktop_config.json");
   if (stripMcpJson(claudeDesktopConfig)) stripped.push("claude_desktop_config.json");
-  if (stripMcpJson(join(home, ".cursor", "mcp.json"))) stripped.push("~/.cursor/mcp.json");
-  if (stripMcpJson(join(home, ".factory", "mcp.json"), { wrapped: false })) stripped.push("~/.factory/mcp.json");
-  if (stripCodexTomlAt(join(home, ".codex", "config.toml"))) stripped.push("~/.codex/config.toml");
+  if (stripMcpJson(join3(home, ".cursor", "mcp.json"))) stripped.push("~/.cursor/mcp.json");
+  if (stripMcpJson(join3(home, ".factory", "mcp.json"), { wrapped: false })) stripped.push("~/.factory/mcp.json");
+  if (stripCodexTomlAt(join3(home, ".codex", "config.toml"))) stripped.push("~/.codex/config.toml");
   if (stripCodexTomlAt(resolve3(".codex/config.toml"))) stripped.push(".codex/config.toml");
   stripClaudeMd();
   stripSettingsJson();
@@ -2081,7 +2177,7 @@ function uninstallCommand() {
     }
     let privateKeyPem;
     try {
-      privateKeyPem = readFileSync4(creds.keyPath, "utf-8").trim();
+      privateKeyPem = readFileSync5(creds.keyPath, "utf-8").trim();
     } catch {
     }
     if (!privateKeyPem) {
@@ -2198,13 +2294,13 @@ function revokeCommand() {
 import { Command as Command4 } from "commander";
 import chalk11 from "chalk";
 import { mkdir as mkdir5, readFile as readFile5, writeFile as writeFile8 } from "fs/promises";
-import { dirname as dirname2 } from "path";
+import { dirname as dirname3 } from "path";
 
 // src/lib/claude-config.ts
 import { homedir as homedir2 } from "os";
-import { join as join2 } from "path";
+import { join as join4 } from "path";
 import { readFile as readFile3, writeFile as writeFile6, mkdir as mkdir4, access } from "fs/promises";
-var CLAUDE_CONFIG_PATH = join2(homedir2(), ".claude", "config");
+var CLAUDE_CONFIG_PATH = join4(homedir2(), ".claude", "config");
 async function writeKeyToClaudeConfig(agentId, privateKeyPem) {
   let config = {};
   try {
@@ -2215,7 +2311,7 @@ async function writeKeyToClaudeConfig(agentId, privateKeyPem) {
   }
   config.agent_keys = config.agent_keys ?? {};
   config.agent_keys[agentId] = Buffer.from(privateKeyPem).toString("base64");
-  await mkdir4(join2(homedir2(), ".claude"), { recursive: true });
+  await mkdir4(join4(homedir2(), ".claude"), { recursive: true });
   await writeFile6(CLAUDE_CONFIG_PATH, JSON.stringify(config, null, 2), "utf-8");
 }
 
@@ -2250,7 +2346,7 @@ function injectCommand() {
     "--target <target>",
     "Where to write the key: agentvalet (default \u2014 modern store + MCP configs), env-local (.env.local), claude-legacy (~/.claude/config, deprecated)",
     "agentvalet"
-  ).option("--no-frameworks", "Skip IDE/framework configuration prompts (only with --target agentvalet)").option("--project", "Write project-scoped framework configs instead of user-scoped").action(async (opts) => {
+  ).option("--no-frameworks", "Skip IDE/framework configuration prompts (only with --target agentvalet)").option("--project", "Write project-scoped framework configs instead of user-scoped").option("--force", "Replace an existing agent key (a timestamped backup is written first)").action(async (opts) => {
     let privateKeyPem;
     try {
       privateKeyPem = await readFile5(opts.keyFile, "utf-8");
@@ -2270,7 +2366,8 @@ function injectCommand() {
           console.error(chalk11.dim("  Find it at https://app.agentvalet.ai or in your existing ~/.agentvalet/config.json"));
           process.exit(1);
         }
-        await mkdir5(dirname2(AGENT_KEY_PATH), { recursive: true });
+        await mkdir5(dirname3(AGENT_KEY_PATH), { recursive: true });
+        assertSafeToWriteKey(AGENT_KEY_PATH, opts.agentId, { force: opts.force });
         await writeFile8(AGENT_KEY_PATH, privateKeyPem, { mode: 384 });
         saveConfig({
           agentId: opts.agentId,
@@ -2325,7 +2422,7 @@ function injectCommand() {
         process.exit(1);
       }
     } catch (err) {
-      console.error(chalk11.red(String(err)));
+      console.error(chalk11.red(err instanceof KeyClobberError ? err.message : String(err)));
       process.exit(1);
     }
     console.log(chalk11.green("\n  Done. Your agent is ready to use."));
@@ -2368,7 +2465,7 @@ async function bindInstallToken(proxyUrl, bootstrapToken) {
   return { ...body, privateKeyPem: privateKey };
 }
 function installCommand() {
-  return new Command5("install").description("Install an agent on this machine using a one-time install token (generates the keypair locally and binds it)").argument("<token>", "install token (itok_...) from the dashboard").option("--no-frameworks", "skip IDE/framework configuration prompts").option("--project", "write project-scoped configs (.mcp.json, .cursor/mcp.json) instead of user-scoped (~/.claude.json, ~/.cursor/mcp.json)").action(async (token, opts) => {
+  return new Command5("install").description("Install an agent on this machine using a one-time install token (generates the keypair locally and binds it)").argument("<token>", "install token (itok_...) from the dashboard").option("--no-frameworks", "skip IDE/framework configuration prompts").option("--project", "write project-scoped configs (.mcp.json, .cursor/mcp.json) instead of user-scoped (~/.claude.json, ~/.cursor/mcp.json)").option("--force", "replace an existing agent key (a timestamped backup is written first)").action(async (token, opts) => {
     const scope = opts.project ? "project" : "user";
     if (!token.startsWith("itok_")) {
       console.error(chalk12.red('Invalid install token. Tokens start with "itok_".'));
@@ -2394,8 +2491,14 @@ function installCommand() {
     const agent_name = claim.agent_id;
     try {
       await mkdir6(AGENT_DIR, { recursive: true });
+      assertSafeToWriteKey(AGENT_KEY_PATH, agent_id, { force: opts.force });
       await writeFile9(AGENT_KEY_PATH, private_key_pem, { mode: 384 });
     } catch (err) {
+      if (err instanceof KeyClobberError) {
+        console.error(chalk12.red(`
+  \u2717 ${err.message}`));
+        process.exit(3);
+      }
       console.error(chalk12.red(`
   \u2717 Failed to write key: ${err instanceof Error ? err.message : err}`));
       process.exit(3);
@@ -2460,6 +2563,7 @@ function installCommand() {
             detected
           });
         }
+        await writeGovernanceInstructions(agent_id, owner_id);
         ensureMcpServer();
       }
     }
@@ -2530,14 +2634,14 @@ function installCommand() {
 // src/commands/claim.ts
 import { Command as Command6 } from "commander";
 import { generateKeyPairSync as generateKeyPairSync2 } from "crypto";
-import { mkdirSync as mkdirSync3, writeFileSync as writeFileSync4, existsSync as existsSync8 } from "fs";
+import { mkdirSync as mkdirSync3, writeFileSync as writeFileSync4, existsSync as existsSync9 } from "fs";
 import { homedir as homedir3 } from "os";
-import { join as join3 } from "path";
+import { join as join5 } from "path";
 import chalk13 from "chalk";
 var DEFAULT_PROXY_URL = "https://api.agentvalet.ai";
 function resolveAgentDir(label) {
-  const root = join3(homedir3(), ".agentvalet");
-  return label ? join3(root, label) : root;
+  const root = join5(homedir3(), ".agentvalet");
+  return label ? join5(root, label) : root;
 }
 function sanitiseLabel(label) {
   return label.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
@@ -2581,9 +2685,9 @@ function claimCommand() {
       process.exit(3);
     }
     const agentDir = resolveAgentDir(label);
-    const keyPath = join3(agentDir, "agent.key");
-    const identityPath = join3(agentDir, "agent.json");
-    if (existsSync8(keyPath)) {
+    const keyPath = join5(agentDir, "agent.key");
+    const identityPath = join5(agentDir, "agent.json");
+    if (existsSync9(keyPath)) {
       const msg = label ? `An agent already exists at ${keyPath}. Pick a different --label or remove the directory first.` : `A default agent already exists at ${keyPath}. Pass --label <name> to claim alongside it without overwriting.`;
       console.error(isJson ? JSON.stringify({ error: msg }) : chalk13.red(msg));
       process.exit(3);
@@ -2675,7 +2779,7 @@ function collectScope(value, previous) {
   return [...previous, value];
 }
 var program = new Command7();
-program.name("agentvalet-register").description("Self-register an AI agent with AgentValet").version(version).option("--owner <uuid>", "Owner ID (or set AGENTVALET_OWNER env var)").option("--name <name>", "Agent name").option("--description <desc>", "Agent description").option("--scope <platform:scope>", "Requested scope, repeatable", collectScope, []).option("--api-url <url>", "AgentValet API base URL", "https://api.agentvalet.ai").option("--json", "Machine-readable JSON output").option("--no-wait", "Register only, do not wait for approval").option("--timeout <seconds>", "Approval wait timeout in seconds", "300").option("--project", "Write project-scoped MCP configs (.mcp.json, .cursor/mcp.json) instead of user-scoped (~/.claude.json, ~/.cursor/mcp.json)").action(async (opts) => {
+program.name("agentvalet-register").description("Self-register an AI agent with AgentValet").version(version).option("--owner <uuid>", "Owner ID (or set AGENTVALET_OWNER env var)").option("--name <name>", "Agent name").option("--description <desc>", "Agent description").option("--scope <platform:scope>", "Requested scope, repeatable", collectScope, []).option("--api-url <url>", "AgentValet API base URL", "https://api.agentvalet.ai").option("--json", "Machine-readable JSON output").option("--no-wait", "Register only, do not wait for approval").option("--timeout <seconds>", "Approval wait timeout in seconds", "300").option("--project", "Write project-scoped MCP configs (.mcp.json, .cursor/mcp.json) instead of user-scoped (~/.claude.json, ~/.cursor/mcp.json)").option("--force", "Replace an existing agent's key (a timestamped backup is written first)").action(async (opts) => {
   const isJson = !!opts.json;
   let ownerId = opts.owner ?? process.env.AGENTVALET_OWNER ?? "";
   let agentName = opts.name ?? "";
@@ -2791,10 +2895,15 @@ Approve at: https://app.agentvalet.ai/agents
         agentId,
         ownerId: resolvedOwnerId,
         privateKey,
-        apiUrl: opts.apiUrl
+        apiUrl: opts.apiUrl,
+        force: !!opts.force
       }));
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err);
+      if (err instanceof KeyClobberError) {
+        console.error(isJson ? JSON.stringify({ error: msg, existing_agent_id: err.existingAgentId }) : chalk14.red(msg));
+        process.exit(3);
+      }
       console.error(isJson ? JSON.stringify({ error: msg }) : chalk14.red(`Failed to save output: ${msg}`));
       process.exit(3);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentvalet/register",
-  "version": "1.1.1",
+  "version": "1.4.0",
   "description": "Self-register AI agents with AgentValet",
   "type": "module",
   "bin": {
@@ -10,6 +10,13 @@
     "dist",
     "README.md"
   ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean --shims",
+    "dev": "tsx src/index.ts",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "node ../../scripts/no-secrets.mjs && pnpm build && node ../../scripts/no-workspace-protocol.mjs"
+  },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@octokit/auth-oauth-device": "^7.0.0",
@@ -22,22 +29,23 @@
     "undici": "^6.0.0"
   },
   "devDependencies": {
+    "@agentvalet/mcp-server": "workspace:^",
     "@types/node": "^20.0.0",
     "@types/prompts": "^2.4.0",
     "tsup": "^8.0.0",
     "tsx": "^4.0.0",
     "typescript": "^5.0.0",
-    "vitest": "^1.5.0",
-    "@agentvalet/mcp-server": "^1.4.1"
+    "vitest": "^1.5.0"
   },
   "engines": {
     "node": ">=18"
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/agentvalet/agentvalet.git"
+    "url": "git+https://github.com/AgentValet/AgentValet.git",
+    "directory": "packages/cli"
   },
-  "homepage": "https://agentvalet.ai",
+  "homepage": "https://github.com/AgentValet/AgentValet#readme",
   "bugs": {
     "url": "https://github.com/agentvalet/agentvalet/issues"
   },
@@ -53,11 +61,5 @@
     "valet",
     "agentvalet"
   ],
-  "license": "MIT",
-  "scripts": {
-    "build": "tsup src/index.ts --format esm --dts --clean --shims",
-    "dev": "tsx src/index.ts",
-    "test": "vitest run",
-    "typecheck": "tsc --noEmit"
-  }
-}
+  "license": "MIT"
+}