@elisym/cli 0.3.2 → 0.5.0

package/dist/index.js

@@ -1,16 +1,19 @@
 #!/usr/bin/env -S node --no-deprecation
-import { readFileSync, writeFileSync, readdirSync, statSync, rmSync, existsSync, mkdirSync, renameSync } from 'node:fs';
-import { homedir } from 'node:os';
-import { dirname, join, basename } from 'node:path';
-import { SolanaPaymentStrategy, validateAgentName, ElisymIdentity, MediaService, RELAYS, formatSol, ElisymClient, jobRequestKind, DEFAULT_KIND_OFFSET, DEFAULTS, serializeConfig, getProtocolProgramId, getProtocolConfig, LIMITS, calculateProtocolFee, BoundedSet } from '@elisym/sdk';
-import { isEncrypted, parseConfig, encryptSecret } from '@elisym/sdk/node';
+import { readFileSync, readdirSync, statSync, renameSync, mkdirSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve, basename, relative, sep } from 'node:path';
+import { SolanaPaymentStrategy, validateAgentName, RELAYS, ElisymIdentity, formatSol, ElisymClient, MediaService, jobRequestKind, DEFAULT_KIND_OFFSET, DEFAULTS, makeCensor, DEFAULT_REDACT_PATHS, createSlidingWindowLimiter, getProtocolProgramId, getProtocolConfig, LIMITS, calculateProtocolFee, BoundedSet } from '@elisym/sdk';
+import { ElisymYamlSchema, resolveInHome, resolveInProject, createAgentDir, writeYaml, writeSecrets, listAgents, loadAgent, agentPaths, readMediaCache, lookupCachedUrl, newCacheEntry, writeMediaCache } from '@elisym/sdk/agent-store';
 import { isAddress, createSolanaRpc, address } from '@solana/kit';
-import { nip19, getPublicKey, generateSecretKey } from 'nostr-tools';
+import { generateSecretKey, getPublicKey, nip19 } from 'nostr-tools';
+import YAML from 'yaml';
 import { Command } from 'commander';
+import { isEncrypted } from '@elisym/sdk/node';
+import { createHash } from 'node:crypto';
+import { lookup } from 'node:dns/promises';
+import { Socket } from 'node:net';
+import pino from 'pino';
 import pLimit from 'p-limit';
-import YAML from 'yaml';
-import { spawn } from 'node:child_process';
-import { StringDecoder } from 'node:string_decoder';
+import { parseSkillMd, validateSkillFrontmatter, ScriptSkill as ScriptSkill$1 } from '@elisym/sdk/skills';
 import { fileURLToPath } from 'node:url';
 
 var __defProp = Object.defineProperty;
@@ -22,69 +25,6 @@ var __export = (target, all) => {
   for (var name in all)
     __defProp(target, name, { get: all[name], enumerable: true });
 };
-function agentDir(name) {
-  return join(AGENTS_ROOT, name);
-}
-function configPath(name) {
-  return join(AGENTS_ROOT, name, "config.json");
-}
-function loadConfig(name, passphrase) {
-  validateAgentName(name);
-  const path = configPath(name);
-  const raw = readFileSync(path, "utf-8");
-  return parseConfig(raw, passphrase);
-}
-function saveConfig(config) {
-  validateAgentName(config.identity.name);
-  const dir = agentDir(config.identity.name);
-  mkdirSync(dir, { recursive: true });
-  writeFileSync(join(dir, "config.json"), serializeConfig(config), { mode: 384 });
-}
-function listAgents() {
-  try {
-    return readdirSync(AGENTS_ROOT).filter((name) => {
-      try {
-        statSync(join(AGENTS_ROOT, name, "config.json"));
-        return true;
-      } catch {
-        return false;
-      }
-    });
-  } catch {
-    return [];
-  }
-}
-function deleteAgent(name) {
-  validateAgentName(name);
-  const dir = agentDir(name);
-  for (const file of ["config.json", "jobs.json"]) {
-    try {
-      const filePath = join(dir, file);
-      const size = statSync(filePath).size;
-      writeFileSync(filePath, Buffer.alloc(size, 0));
-    } catch {
-    }
-  }
-  try {
-    for (const entry of readdirSync(dir)) {
-      if (entry.startsWith("jobs.json.corrupt.")) {
-        try {
-          const fp = join(dir, entry);
-          writeFileSync(fp, Buffer.alloc(statSync(fp).size, 0));
-        } catch {
-        }
-      }
-    }
-  } catch {
-  }
-  rmSync(dir, { recursive: true, force: true });
-}
-var AGENTS_ROOT;
-var init_config = __esm({
-  "src/config.ts"() {
-    AGENTS_ROOT = join(homedir(), ".elisym", "agents");
-  }
-});
 
 // src/commands/init.ts
 var init_exports = {};
@@ -92,20 +32,6 @@ __export(init_exports, {
   cmdInit: () => cmdInit,
   fetchModels: () => fetchModels
 });
-async function resolveImage(input, identity, media) {
-  if (!input) {
-    return "";
-  }
-  if (existsSync(input)) {
-    console.log(`  Uploading ${basename(input)}...`);
-    const data = readFileSync(input);
-    const blob = new Blob([data]);
-    const url = await media.upload(identity, blob, basename(input));
-    console.log(`  Uploaded: ${url}`);
-    return url;
-  }
-  return input;
-}
 async function fetchModels(provider, apiKey) {
   try {
     if (provider === "anthropic") {
@@ -138,31 +64,30 @@ async function fetchModels(provider, apiKey) {
     return FALLBACK_MODELS[provider] ?? ["gpt-4o"];
   }
 }
-async function cmdInit() {
+function pickTarget(options) {
+  return options.local ? "project" : "home";
+}
+async function cmdInit(nameArg, options = {}) {
   const { default: inquirer } = await import('inquirer');
+  const cwd = process.cwd();
   console.log("\n  elisym agent setup\n");
-  const { name } = await inquirer.prompt([
-    {
-      type: "input",
-      name: "name",
-      message: "Agent name:",
-      validate: (v) => {
-        try {
-          validateAgentName(v);
-          return true;
-        } catch (e) {
-          return e.message;
-        }
-      }
-    }
-  ]);
-  const existing = listAgents();
-  if (existing.includes(name)) {
+  let template;
+  if (options.config) {
+    const configPath = resolve(cwd, options.config);
+    const raw = readFileSync(configPath, "utf-8");
+    template = ElisymYamlSchema.parse(YAML.parse(raw) ?? {});
+    console.log(`  Loaded template from ${configPath}
+`);
+  }
+  const agentName = await resolveAgentName(nameArg, inquirer);
+  const target = pickTarget(options);
+  const sameLocation = target === "home" ? resolveInHome(agentName) : resolveInProject(agentName, cwd);
+  if (sameLocation) {
     const { overwrite } = await inquirer.prompt([
       {
         type: "confirm",
         name: "overwrite",
-        message: `Agent "${name}" already exists. Overwrite?`,
+        message: `Agent "${agentName}" already exists at ${sameLocation}. Overwrite secrets?`,
         default: false
       }
     ]);
@@ -170,7 +95,133 @@ async function cmdInit() {
       console.log("Aborted.");
       return;
     }
+  } else if (target === "project" && resolveInHome(agentName)) {
+    const { shadow } = await inquirer.prompt([
+      {
+        type: "confirm",
+        name: "shadow",
+        message: `A global agent "${agentName}" exists in ~/.elisym/${agentName}/. Create a project-local shadow?`,
+        default: true
+      }
+    ]);
+    if (!shadow) {
+      console.log("Aborted.");
+      return;
+    }
+  } else if (target === "home" && resolveInProject(agentName, cwd)) {
+    const { proceed } = await inquirer.prompt([
+      {
+        type: "confirm",
+        name: "proceed",
+        message: `A project-local agent "${agentName}" exists. Create a global agent with the same name?`,
+        default: true
+      }
+    ]);
+    if (!proceed) {
+      console.log("Aborted.");
+      return;
+    }
+  }
+  let yaml;
+  let promptedApiKey;
+  if (template) {
+    yaml = template;
+  } else {
+    const result = await promptYaml(inquirer);
+    yaml = result.yaml;
+    promptedApiKey = result.apiKey;
+  }
+  let llmApiKey;
+  if (yaml.llm) {
+    const envKey = yaml.llm.provider === "anthropic" ? process.env.ANTHROPIC_API_KEY : process.env.OPENAI_API_KEY;
+    if (envKey) {
+      llmApiKey = envKey;
+      console.log(
+        `  Using ${yaml.llm.provider === "anthropic" ? "ANTHROPIC" : "OPENAI"}_API_KEY from environment.`
+      );
+    } else if (promptedApiKey) {
+      llmApiKey = promptedApiKey;
+    } else {
+      const { apiKey } = await inquirer.prompt([
+        {
+          type: "password",
+          name: "apiKey",
+          message: `${yaml.llm.provider === "anthropic" ? "Anthropic" : "OpenAI"} API key:`,
+          mask: "*"
+        }
+      ]);
+      llmApiKey = apiKey || void 0;
+    }
+  }
+  const { passphrase } = await inquirer.prompt([
+    {
+      type: "password",
+      name: "passphrase",
+      message: "Passphrase to encrypt secrets (leave empty to skip):",
+      mask: "*"
+    }
+  ]);
+  if (passphrase) {
+    const { confirmPassphrase } = await inquirer.prompt([
+      {
+        type: "password",
+        name: "confirmPassphrase",
+        message: "Confirm passphrase:",
+        mask: "*",
+        validate: (value) => value === passphrase || "Passphrases do not match"
+      }
+    ]);
+  }
+  const nostrSecretBytes = generateSecretKey();
+  const nostrPubkey = getPublicKey(nostrSecretBytes);
+  const nostrSecretHex = Buffer.from(nostrSecretBytes).toString("hex");
+  const created = await createAgentDir({ target, name: agentName, cwd });
+  await writeYaml(created.dir, yaml);
+  await writeSecrets(
+    created.dir,
+    {
+      nostr_secret_key: nostrSecretHex,
+      llm_api_key: llmApiKey
+    },
+    passphrase || void 0
+  );
+  const npub = nip19.npubEncode(nostrPubkey);
+  console.log(`
+  Agent "${agentName}" created (${target}).`);
+  console.log(`  Location: ${created.dir}`);
+  console.log(`  Nostr:    ${npub}`);
+  if (yaml.payments[0]?.address) {
+    console.log(`  Solana:   ${yaml.payments[0].address}`);
+  }
+  if (passphrase) {
+    console.log("  Secrets encrypted with your passphrase.");
   }
+  console.log();
+}
+async function resolveAgentName(nameArg, inquirer) {
+  if (nameArg) {
+    validateAgentName(nameArg);
+    return nameArg;
+  }
+  const { inputName } = await inquirer.prompt([
+    {
+      type: "input",
+      name: "inputName",
+      message: "Agent name:",
+      validate: (value) => {
+        try {
+          validateAgentName(value);
+          return true;
+        } catch (e) {
+          return e.message;
+        }
+      }
+    }
+  ]);
+  validateAgentName(inputName);
+  return inputName;
+}
+async function promptYaml(inquirer) {
   const { description } = await inquirer.prompt([
     {
       type: "input",
@@ -179,19 +230,27 @@ async function cmdInit() {
       default: "An elisym AI agent"
     }
   ]);
-  const { pictureInput } = await inquirer.prompt([
+  const { displayName } = await inquirer.prompt([
+    {
+      type: "input",
+      name: "displayName",
+      message: "Display name (optional, for UI):",
+      default: ""
+    }
+  ]);
+  const { picture } = await inquirer.prompt([
     {
       type: "input",
-      name: "pictureInput",
-      message: "Avatar image (URL or local path, optional):",
+      name: "picture",
+      message: "Avatar file (relative to agent dir, e.g. ./avatar.png) or URL:",
       default: ""
     }
   ]);
-  const { bannerInput } = await inquirer.prompt([
+  const { banner } = await inquirer.prompt([
     {
       type: "input",
-      name: "bannerInput",
-      message: "Banner image (URL or local path, optional):",
+      name: "banner",
+      message: "Banner file (relative to agent dir, e.g. ./header.png) or URL:",
       default: ""
     }
   ]);
@@ -201,23 +260,14 @@ async function cmdInit() {
       name: "solanaAddress",
       message: "Solana address for receiving payments (leave empty to skip):",
       default: "",
-      validate: (v) => {
-        if (!v) {
+      validate: (value) => {
+        if (!value) {
           return true;
         }
-        return isAddress(v) || "Invalid Solana address";
+        return isAddress(value) || "Invalid Solana address";
       }
     }
   ]);
-  const { network } = await inquirer.prompt([
-    {
-      type: "list",
-      name: "network",
-      message: "Solana network:",
-      choices: [{ name: "devnet", value: "devnet" }],
-      default: "devnet"
-    }
-  ]);
   const { llmProvider } = await inquirer.prompt([
     {
       type: "list",
@@ -229,16 +279,21 @@ async function cmdInit() {
       ]
     }
   ]);
-  const { apiKey } = await inquirer.prompt([
-    {
-      type: "password",
-      name: "apiKey",
-      message: `${llmProvider === "anthropic" ? "Anthropic" : "OpenAI"} API key:`,
-      mask: "*"
-    }
-  ]);
+  const envKey = llmProvider === "anthropic" ? process.env.ANTHROPIC_API_KEY : process.env.OPENAI_API_KEY;
+  let apiKey = envKey;
+  if (!apiKey) {
+    const { promptedKey } = await inquirer.prompt([
+      {
+        type: "password",
+        name: "promptedKey",
+        message: `${llmProvider === "anthropic" ? "Anthropic" : "OpenAI"} API key:`,
+        mask: "*"
+      }
+    ]);
+    apiKey = promptedKey || void 0;
+  }
   console.log("  Fetching available models...");
-  const models = await fetchModels(llmProvider, apiKey);
+  const models = await fetchModels(llmProvider, apiKey ?? "");
   const { model } = await inquirer.prompt([
     {
       type: "list",
@@ -255,77 +310,21 @@ async function cmdInit() {
       default: 4096
     }
   ]);
-  const { passphrase } = await inquirer.prompt([
-    {
-      type: "password",
-      name: "passphrase",
-      message: "Passphrase to encrypt secrets (leave empty to skip):",
-      mask: "*"
-    }
-  ]);
-  if (passphrase) {
-    const { confirmPassphrase } = await inquirer.prompt([
-      {
-        type: "password",
-        name: "confirmPassphrase",
-        message: "Confirm passphrase:",
-        mask: "*",
-        validate: (v) => v === passphrase ? true : "Passphrases do not match"
-      }
-    ]);
-  }
-  const nostrSecretKey = generateSecretKey();
-  const nostrPubkey = getPublicKey(nostrSecretKey);
-  const nostrSecretHex = Buffer.from(nostrSecretKey).toString("hex");
-  const identity = ElisymIdentity.fromHex(nostrSecretHex);
-  const media = new MediaService();
-  let picture = "";
-  let banner = "";
-  if (pictureInput || bannerInput) {
-    console.log();
-    if (pictureInput) {
-      picture = await resolveImage(pictureInput, identity, media);
-    }
-    if (bannerInput) {
-      banner = await resolveImage(bannerInput, identity, media);
-    }
-  }
-  const protect = (secret) => passphrase ? encryptSecret(secret, passphrase) : secret;
-  const config = {
-    identity: {
-      secret_key: protect(nostrSecretHex),
-      name,
-      description,
-      picture: picture || void 0,
-      banner: banner || void 0
-    },
+  const yaml = ElisymYamlSchema.parse({
+    display_name: displayName || void 0,
+    description,
+    picture: picture || void 0,
+    banner: banner || void 0,
     relays: [...RELAYS],
-    payments: solanaAddress ? [{ chain: "solana", network, address: solanaAddress }] : void 0,
-    llm: {
-      provider: llmProvider,
-      api_key: protect(apiKey),
-      model,
-      max_tokens: maxTokens
-    }
-  };
-  saveConfig(config);
-  const npub = nip19.npubEncode(nostrPubkey);
-  console.log(`
-  Agent "${name}" created.`);
-  console.log(`  Nostr:  ${npub}`);
-  if (solanaAddress) {
-    console.log(`  Solana: ${solanaAddress}`);
-  }
-  if (passphrase) {
-    console.log("  Secrets encrypted with your passphrase.");
-  }
-  console.log(`  Config: ~/.elisym/agents/${name}/config.json
-`);
+    payments: solanaAddress ? [{ chain: "solana", network: "devnet", address: solanaAddress }] : [],
+    llm: { provider: llmProvider, model, max_tokens: maxTokens },
+    security: {}
+  });
+  return { yaml, apiKey: envKey ? void 0 : apiKey };
 }
 var FALLBACK_MODELS;
 var init_init = __esm({
   "src/commands/init.ts"() {
-    init_config();
     FALLBACK_MODELS = {
       anthropic: ["claude-sonnet-4-6", "claude-haiku-4-5-20251001", "claude-opus-4-6"],
       openai: ["gpt-4o", "gpt-4o-mini", "o3-mini"]
@@ -335,41 +334,32 @@ var init_init = __esm({
 
 // src/index.ts
 init_init();
-
-// src/commands/profile.ts
-init_config();
-async function resolveImage2(input, identity, media) {
-  if (!input) {
-    return "";
-  }
-  if (existsSync(input)) {
-    console.log(`  Uploading ${basename(input)}...`);
-    const data = readFileSync(input);
-    const blob = new Blob([data]);
-    const url = await media.upload(identity, blob, basename(input));
-    console.log(`  Uploaded: ${url}`);
-    return url;
-  }
-  return input;
-}
 async function cmdProfile(name) {
   const { default: inquirer } = await import('inquirer');
+  const cwd = process.cwd();
   if (!name) {
-    const agents = listAgents();
+    const agents = await listAgents(cwd);
     if (agents.length === 0) {
       console.error("No agents found. Run `elisym init` first.");
       process.exit(1);
     }
     const { selected } = await inquirer.prompt([
-      { type: "list", name: "selected", message: "Select agent:", choices: agents }
+      {
+        type: "list",
+        name: "selected",
+        message: "Select agent:",
+        choices: agents.map((agent) => ({
+          name: `${agent.name} (${agent.source})`,
+          value: agent.name
+        }))
+      }
     ]);
     name = selected;
   }
   const passphrase = process.env.ELISYM_PASSPHRASE;
-  const config = loadConfig(name, passphrase);
-  const identity = ElisymIdentity.fromHex(config.identity.secret_key);
+  const loaded = await loadAgent(name, cwd, passphrase);
   console.log(`
-  Editing agent "${name}"
+  Editing agent "${name}" (${loaded.source})
 `);
   let done = false;
   while (!done) {
@@ -379,13 +369,16 @@ async function cmdProfile(name) {
         name: "section",
         message: "What to edit?",
         choices: [
-          { name: `Profile (name: ${config.identity.name})`, value: "profile" },
           {
-            name: `Wallet (${config.payments?.[0]?.address ?? "not configured"})`,
+            name: `Profile (description: ${truncate(loaded.yaml.description ?? "")})`,
+            value: "profile"
+          },
+          {
+            name: `Wallet (${loaded.yaml.payments[0]?.address ?? "not configured"})`,
             value: "wallet"
           },
           {
-            name: `LLM (${config.llm?.provider ?? "not configured"} / ${config.llm?.model ?? "-"})`,
+            name: `LLM (${loaded.yaml.llm?.provider ?? "not configured"} / ${loaded.yaml.llm?.model ?? "-"})`,
             value: "llm"
           },
           { name: "Done", value: "done" }
@@ -398,70 +391,64 @@ async function cmdProfile(name) {
     }
     if (section === "profile") {
       const answers = await inquirer.prompt([
+        {
+          type: "input",
+          name: "displayName",
+          message: "Display name (for UI):",
+          default: loaded.yaml.display_name ?? ""
+        },
         {
           type: "input",
           name: "description",
           message: "Description:",
-          default: config.identity.description ?? ""
+          default: loaded.yaml.description ?? ""
         },
         {
           type: "input",
           name: "picture",
-          message: "Avatar (URL or local path):",
-          default: config.identity.picture ?? ""
+          message: "Avatar (relative path or URL, empty to clear):",
+          default: loaded.yaml.picture ?? ""
         },
         {
           type: "input",
           name: "banner",
-          message: "Banner (URL or local path):",
-          default: config.identity.banner ?? ""
+          message: "Banner (relative path or URL, empty to clear):",
+          default: loaded.yaml.banner ?? ""
         }
       ]);
-      config.identity.description = answers.description || void 0;
-      const media = new MediaService();
-      if (answers.picture) {
-        config.identity.picture = await resolveImage2(answers.picture, identity, media);
-      } else {
-        config.identity.picture = void 0;
-      }
-      if (answers.banner) {
-        config.identity.banner = await resolveImage2(answers.banner, identity, media);
-      } else {
-        config.identity.banner = void 0;
-      }
-      saveConfig(config);
+      const nextYaml = {
+        ...loaded.yaml,
+        display_name: answers.displayName || void 0,
+        description: answers.description ?? "",
+        picture: answers.picture || void 0,
+        banner: answers.banner || void 0
+      };
+      await writeYaml(loaded.dir, nextYaml);
+      loaded.yaml = nextYaml;
       console.log("  Profile updated.\n");
     }
     if (section === "wallet") {
-      const currentAddress = config.payments?.[0]?.address ?? "";
-      const currentNetwork = config.payments?.[0]?.network ?? "devnet";
+      const current = loaded.yaml.payments[0];
       const answers = await inquirer.prompt([
         {
           type: "input",
           name: "address",
-          message: "Solana address:",
-          default: currentAddress,
-          validate: (v) => {
-            if (!v) {
+          message: "Solana address (empty to clear):",
+          default: current?.address ?? "",
+          validate: (value) => {
+            if (!value) {
               return true;
             }
-            return isAddress(v) || "Invalid Solana address";
+            return isAddress(value) || "Invalid Solana address";
           }
-        },
-        {
-          type: "list",
-          name: "network",
-          message: "Network:",
-          choices: ["devnet"],
-          default: currentNetwork
         }
       ]);
-      if (answers.address) {
-        config.payments = [{ chain: "solana", network: answers.network, address: answers.address }];
-      } else {
-        config.payments = void 0;
-      }
-      saveConfig(config);
+      const nextYaml = {
+        ...loaded.yaml,
+        payments: answers.address ? [{ chain: "solana", network: "devnet", address: answers.address }] : []
+      };
+      await writeYaml(loaded.dir, nextYaml);
+      loaded.yaml = nextYaml;
       console.log("  Wallet updated.\n");
     }
     if (section === "llm") {
@@ -474,33 +461,29 @@ async function cmdProfile(name) {
             { name: "Anthropic (Claude)", value: "anthropic" },
             { name: "OpenAI (GPT)", value: "openai" }
           ],
-          default: config.llm?.provider ?? "anthropic"
+          default: loaded.yaml.llm?.provider ?? "anthropic"
         }
       ]);
       const { apiKey } = await inquirer.prompt([
         {
           type: "password",
           name: "apiKey",
-          message: `API key (leave empty to keep current):`,
+          message: "API key (leave empty to keep current):",
           mask: "*"
         }
       ]);
-      const effectiveKey = apiKey || config.llm?.api_key || "";
-      let plainKey = effectiveKey;
-      if (isEncrypted(plainKey) && passphrase) {
-        const { decryptSecret } = await import('@elisym/sdk/node');
-        plainKey = decryptSecret(plainKey, passphrase);
-      }
+      const currentKeyPlain = loaded.secrets.llm_api_key && !isEncrypted(loaded.secrets.llm_api_key) ? loaded.secrets.llm_api_key : "";
+      const probeKey = apiKey || currentKeyPlain;
       console.log("  Fetching available models...");
       const { fetchModels: fetchModels2 } = await Promise.resolve().then(() => (init_init(), init_exports));
-      const models = await fetchModels2(llmProvider, plainKey);
+      const models = await fetchModels2(llmProvider, probeKey);
       const { model } = await inquirer.prompt([
         {
           type: "list",
           name: "model",
           message: "Model:",
           choices: models,
-          default: config.llm?.model
+          default: loaded.yaml.llm?.model
         }
       ]);
       const { maxTokens } = await inquirer.prompt([
@@ -508,26 +491,109 @@ async function cmdProfile(name) {
           type: "number",
           name: "maxTokens",
           message: "Max tokens:",
-          default: config.llm?.max_tokens ?? 4096
+          default: loaded.yaml.llm?.max_tokens ?? 4096
         }
       ]);
-      const protect = (secret) => passphrase ? encryptSecret(secret, passphrase) : secret;
-      config.llm = {
-        provider: llmProvider,
-        api_key: apiKey ? protect(apiKey) : effectiveKey,
-        model,
-        max_tokens: maxTokens
-      };
-      saveConfig(config);
+      const nextLlm = { provider: llmProvider, model, max_tokens: maxTokens };
+      const nextYaml = { ...loaded.yaml, llm: nextLlm };
+      await writeYaml(loaded.dir, nextYaml);
+      loaded.yaml = nextYaml;
+      if (apiKey) {
+        await writeSecrets(loaded.dir, { ...loaded.secrets, llm_api_key: apiKey }, passphrase);
+        loaded.secrets = { ...loaded.secrets, llm_api_key: apiKey };
+      }
       console.log("  LLM updated.\n");
     }
   }
   console.log(`  Agent "${name}" saved.
 `);
 }
-
-// src/commands/start.ts
-init_config();
+function truncate(value, max = 40) {
+  if (value.length <= max) {
+    return value;
+  }
+  return value.slice(0, max - 1) + "\u2026";
+}
+var TCP_PROBE_TIMEOUT_MS = 3e3;
+function parseRelayUrl(url) {
+  try {
+    const parsed = new URL(url);
+    const isSecure = parsed.protocol === "wss:" || parsed.protocol === "https:";
+    const defaultPort = isSecure ? 443 : 80;
+    const port = parsed.port.length > 0 ? parseInt(parsed.port, 10) : defaultPort;
+    if (!Number.isFinite(port)) {
+      return null;
+    }
+    return { host: parsed.hostname, port };
+  } catch {
+    return null;
+  }
+}
+async function tcpProbe(host, port, timeoutMs) {
+  return new Promise((resolve3) => {
+    const started = Date.now();
+    const socket = new Socket();
+    let settled = false;
+    const finish = (result) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      socket.destroy();
+      resolve3(result);
+    };
+    const timer = setTimeout(() => finish({ error: "timeout" }), timeoutMs);
+    socket.once("connect", () => {
+      clearTimeout(timer);
+      finish({ openMs: Date.now() - started });
+    });
+    socket.once("error", (err) => {
+      clearTimeout(timer);
+      finish({ error: err.message });
+    });
+    socket.connect(port, host);
+  });
+}
+async function probeRelays(relays, logger, timeoutMs = TCP_PROBE_TIMEOUT_MS) {
+  const results = [];
+  for (const url of relays) {
+    const parsed = parseRelayUrl(url);
+    if (!parsed) {
+      logger.debug({ event: "net_diag_parse_failed", url }, "unparseable relay URL");
+      results.push({ url, host: "", port: 0, ips: [], error: "invalid URL" });
+      continue;
+    }
+    const { host, port } = parsed;
+    let ips = [];
+    try {
+      const resolved = await lookup(host, { all: true });
+      ips = resolved.map((entry) => entry.address);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      logger.debug(
+        { event: "net_diag_dns_failed", url, host, error: message },
+        "DNS lookup failed"
+      );
+      results.push({ url, host, port, ips: [], error: `dns: ${message}` });
+      continue;
+    }
+    const probe = await tcpProbe(host, port, timeoutMs);
+    if ("openMs" in probe) {
+      logger.debug(
+        { event: "net_diag_tcp_open", url, host, port, ips, tcpOpenMs: probe.openMs },
+        "TCP open"
+      );
+      results.push({ url, host, port, ips, tcpOpenMs: probe.openMs });
+    } else {
+      logger.debug(
+        { event: "net_diag_tcp_failed", url, host, port, ips, error: probe.error },
+        "TCP probe failed"
+      );
+      results.push({ url, host, port, ips, error: `tcp: ${probe.error}` });
+    }
+  }
+  return results;
+}
 var HEARTBEAT_INTERVAL_MS = 10 * 60 * 1e3;
 var MAX_CONCURRENT_JOBS = 10;
 var RECOVERY_MAX_RETRIES = 5;
@@ -552,8 +618,13 @@ var VALID_TRANSITIONS = {
 var JobLedger = class {
   entries = /* @__PURE__ */ new Map();
   path;
-  constructor(agentName) {
-    this.path = join(homedir(), ".elisym", "agents", agentName, "jobs.json");
+  /**
+   * @param ledgerPath absolute path to the ledger file
+   *   (typically `<agentDir>/.jobs.json`). Caller is responsible for
+   *   resolving the agent directory via `@elisym/sdk/agent-store`.
+   */
+  constructor(ledgerPath) {
+    this.path = ledgerPath;
     this.load();
   }
   load() {
@@ -651,13 +722,29 @@ var JobLedger = class {
   }
   /** Remove old delivered/failed entries (default: 7 days). */
   gc(maxAgeSecs = 7 * 24 * 60 * 60) {
-    const cutoff = Math.floor(Date.now() / 1e3) - maxAgeSecs;
+    this.pruneOldEntries(maxAgeSecs * 1e3);
+  }
+  /**
+   * Drop terminal entries (`delivered` / `failed`) whose `created_at`
+   * predates `now - retentionMs`. Stuck non-terminal entries are never
+   * pruned - recovery keeps retrying them until the retry budget runs
+   * out, then they become terminal and are eligible on the next sweep.
+   *
+   * Returns the number of entries deleted, for observability.
+   */
+  pruneOldEntries(retentionMs) {
+    const cutoff = Math.floor(Date.now() / 1e3) - Math.floor(retentionMs / 1e3);
+    let deleted = 0;
     for (const [id, entry] of this.entries) {
       if ((entry.status === "delivered" || entry.status === "failed") && entry.created_at < cutoff) {
         this.entries.delete(id);
+        deleted += 1;
       }
     }
-    this.flush();
+    if (deleted > 0) {
+      this.flush();
+    }
+    return deleted;
   }
 };
 
@@ -677,7 +764,7 @@ function sleepWithSignal(ms, signal) {
   if (!signal) {
     return new Promise((r) => setTimeout(r, ms));
   }
-  return new Promise((resolve, reject) => {
+  return new Promise((resolve3, reject) => {
     const cleanup = () => {
       clearTimeout(timer);
       signal.removeEventListener("abort", onAbort);
@@ -688,7 +775,7 @@ function sleepWithSignal(ms, signal) {
     };
     const timer = setTimeout(() => {
       cleanup();
-      resolve();
+      resolve3();
     }, ms);
     signal.addEventListener("abort", onAbort, { once: true });
   });
@@ -953,8 +1040,56 @@ var OpenAIClient = class {
     }));
   }
 };
+function resolveLevel(options) {
+  if (options.level) {
+    return options.level;
+  }
+  if (options.verbose) {
+    return "debug";
+  }
+  const envLevel = process.env.LOG_LEVEL;
+  if (envLevel) {
+    return envLevel;
+  }
+  return "info";
+}
+function createLogger(options = {}) {
+  const level = resolveLevel(options);
+  const baseOptions = {
+    name: "elisym-cli",
+    level,
+    redact: {
+      paths: DEFAULT_REDACT_PATHS,
+      censor: makeCensor()
+    }
+  };
+  let logger;
+  if (options.destination) {
+    logger = pino(baseOptions, options.destination);
+  } else if (options.tty === true) {
+    logger = pino({
+      ...baseOptions,
+      transport: {
+        target: "pino-pretty",
+        options: { destination: 2, colorize: true, translateTime: "HH:MM:ss" }
+      }
+    });
+  } else {
+    logger = pino(baseOptions, pino.destination(2));
+  }
+  function logWithIndent(line) {
+    process.stdout.write(`  ${line}
+`);
+  }
+  return {
+    logger,
+    logWithIndent,
+    bannerLog: logWithIndent
+  };
+}
 var payment = new SolanaPaymentStrategy();
 var LEDGER_GC_INTERVAL_MS = 60 * 60 * 1e3;
+var LEDGER_RETENTION_MS = 30 * 24 * 60 * 60 * 1e3;
 var TOTAL_JOB_TIMEOUT_MS = 5 * 60 * 1e3;
 function resolveJobPrice(tags, skills) {
   const skill = skills.route(tags);
@@ -963,6 +1098,8 @@ function resolveJobPrice(tags, skills) {
 var RATE_LIMIT_WINDOW_MS = 10 * 60 * 1e3;
 var MAX_JOBS_PER_CUSTOMER = 20;
 var GLOBAL_MAX_JOBS_PER_WINDOW = 200;
+var MAX_TRACKED_CUSTOMERS = 1e3;
+var GLOBAL_LIMITER_KEY = "__global__";
 var AgentRuntime = class {
   constructor(transport, skills, skillCtx, config, ledger, callbacks = {}) {
     this.transport = transport;
@@ -983,10 +1120,18 @@ var AgentRuntime = class {
   recoveryInterval = null;
   gcInterval = null;
   stopped = false;
-  /** Per-customer sliding window rate limiter: pubkey -> timestamps. */
-  customerJobs = /* @__PURE__ */ new Map();
-  /** Global sliding window rate limiter (Sybil protection). */
-  globalJobs = [];
+  /** Per-customer sliding-window rate limiter (keyed on customer pubkey). */
+  customerLimiter = createSlidingWindowLimiter({
+    windowMs: RATE_LIMIT_WINDOW_MS,
+    maxPerWindow: MAX_JOBS_PER_CUSTOMER,
+    maxKeys: MAX_TRACKED_CUSTOMERS
+  });
+  /** Global sliding-window rate limiter (Sybil protection). */
+  globalLimiter = createSlidingWindowLimiter({
+    windowMs: RATE_LIMIT_WINDOW_MS,
+    maxPerWindow: GLOBAL_MAX_JOBS_PER_WINDOW,
+    maxKeys: 1
+  });
   /** Fetch on-chain protocol config (fee, treasury). Always fetches fresh to avoid stale treasury. */
   async fetchProtocolConfig() {
     if (this.config.network !== "devnet") {
@@ -1001,7 +1146,7 @@ var AgentRuntime = class {
   }
   async run() {
     const log = this.callbacks.onLog ?? console.log;
-    this.ledger.gc();
+    this.ledger.pruneOldEntries(LEDGER_RETENTION_MS);
     await this.recoverPendingJobs();
     this.recoveryInterval = setInterval(
       () => this.recoverPendingJobs().catch((e) => log(`Recovery error: ${e}`)),
@@ -1009,7 +1154,7 @@ var AgentRuntime = class {
     );
     this.gcInterval = setInterval(() => {
       try {
-        this.ledger.gc();
+        this.ledger.pruneOldEntries(LEDGER_RETENTION_MS);
       } catch (e) {
         log(`GC error: ${e.message}`);
       }
@@ -1033,17 +1178,18 @@ var AgentRuntime = class {
         });
         return;
       }
-      if (this.isGlobalRateLimited()) {
-        this.transport.sendFeedback(job, { type: "error", message: "Server busy, try again later" }).catch(() => {
+      if (!this.customerLimiter.peek(job.customerId).allowed) {
+        this.transport.sendFeedback(job, { type: "error", message: "Rate limited, try again later" }).catch(() => {
         });
         return;
       }
-      if (this.isCustomerRateLimited(job.customerId)) {
-        this.transport.sendFeedback(job, { type: "error", message: "Rate limited, try again later" }).catch(() => {
+      if (!this.globalLimiter.peek(GLOBAL_LIMITER_KEY).allowed) {
+        this.transport.sendFeedback(job, { type: "error", message: "Server busy, try again later" }).catch(() => {
         });
         return;
       }
-      this.recordJobAccepted(job.customerId);
+      this.customerLimiter.check(job.customerId);
+      this.globalLimiter.check(GLOBAL_LIMITER_KEY);
       this.callbacks.onJobReceived?.(job);
       this.inFlight.add(job.jobId);
       this.pending++;
@@ -1055,8 +1201,8 @@ var AgentRuntime = class {
       });
     });
     log("Agent runtime started. Listening for jobs...");
-    await new Promise((resolve) => {
-      this.abortController.signal.addEventListener("abort", () => resolve(), { once: true });
+    await new Promise((resolve3) => {
+      this.abortController.signal.addEventListener("abort", () => resolve3(), { once: true });
       process.on("SIGINT", () => {
         log("Shutting down...");
         this.stop();
@@ -1069,40 +1215,10 @@ var AgentRuntime = class {
       });
     });
   }
-  /** Returns true if global job throughput has been exceeded (Sybil protection). Pure check - no side effects. */
-  isGlobalRateLimited() {
-    const now = Date.now();
-    this.globalJobs = this.globalJobs.filter((t) => now - t < RATE_LIMIT_WINDOW_MS);
-    return this.globalJobs.length >= GLOBAL_MAX_JOBS_PER_WINDOW;
-  }
-  /** Returns true if customer has exceeded the per-window job limit. Pure check - no side effects. */
-  isCustomerRateLimited(customerId) {
-    const now = Date.now();
-    const timestamps = this.customerJobs.get(customerId) ?? [];
-    const recent = timestamps.filter((t) => now - t < RATE_LIMIT_WINDOW_MS);
-    this.customerJobs.set(customerId, recent);
-    return recent.length >= MAX_JOBS_PER_CUSTOMER;
-  }
-  /** Record a job acceptance for rate limiting. Called only after all checks pass. */
-  recordJobAccepted(customerId) {
-    const now = Date.now();
-    this.globalJobs.push(now);
-    const timestamps = this.customerJobs.get(customerId) ?? [];
-    timestamps.push(now);
-    this.customerJobs.set(customerId, timestamps);
-  }
-  /** Clean up expired rate limit entries. */
+  /** Drop expired hits from both sliding-window limiters. */
   cleanupRateLimits() {
-    const now = Date.now();
-    this.globalJobs = this.globalJobs.filter((t) => now - t < RATE_LIMIT_WINDOW_MS);
-    for (const [key, timestamps] of this.customerJobs) {
-      const recent = timestamps.filter((t) => now - t < RATE_LIMIT_WINDOW_MS);
-      if (recent.length === 0) {
-        this.customerJobs.delete(key);
-      } else {
-        this.customerJobs.set(key, recent);
-      }
-    }
+    this.customerLimiter.prune();
+    this.globalLimiter.prune();
   }
   stop() {
     if (this.stopped) {
@@ -1479,7 +1595,6 @@ var SkillRegistry = class {
     return this.skills;
   }
 };
-var MAX_TOOL_OUTPUT = 1e6;
 var ScriptSkill = class {
   name;
   description;
@@ -1487,10 +1602,7 @@ var ScriptSkill = class {
   priceLamports;
   image;
   imageFile;
-  skillDir;
-  systemPrompt;
-  tools;
-  maxToolRounds;
+  inner;
   constructor(name, description, capabilities, priceLamports, image, imageFile, skillDir, systemPrompt, tools, maxToolRounds) {
     this.name = name;
     this.description = description;
@@ -1498,155 +1610,25 @@ var ScriptSkill = class {
     this.priceLamports = priceLamports;
     this.image = image;
     this.imageFile = imageFile;
-    this.skillDir = skillDir;
-    this.systemPrompt = systemPrompt;
-    this.tools = tools;
-    this.maxToolRounds = maxToolRounds;
+    this.inner = new ScriptSkill$1({
+      name,
+      description,
+      capabilities,
+      priceLamports: BigInt(Math.round(priceLamports)),
+      skillDir,
+      systemPrompt,
+      tools,
+      maxToolRounds,
+      image,
+      imageFile
+    });
   }
   async execute(input, ctx) {
-    if (!ctx.llm) {
-      throw new Error("LLM client not configured");
-    }
-    if (this.tools.length === 0) {
-      const result = await ctx.llm.complete(this.systemPrompt, input.data, ctx.signal);
-      return { data: result };
-    }
-    const toolDefs = this.tools.map((t) => ({
-      name: t.name,
-      description: t.description,
-      parameters: (t.parameters ?? []).map((p) => ({
-        name: p.name,
-        description: p.description,
-        required: p.required ?? true
-      }))
-    }));
-    const messages = [{ role: "user", content: input.data }];
-    for (let round = 0; round < this.maxToolRounds; round++) {
-      if (ctx.signal?.aborted) {
-        throw new Error("Job aborted");
-      }
-      const result = await ctx.llm.completeWithTools(
-        this.systemPrompt,
-        messages,
-        toolDefs,
-        ctx.signal
-      );
-      if (result.type === "text") {
-        return { data: result.text };
-      }
-      messages.push(result.assistantMessage);
-      const toolResults = [];
-      for (const call of result.calls) {
-        const toolDef = this.tools.find((t) => t.name === call.name);
-        if (!toolDef) {
-          toolResults.push({
-            callId: call.id,
-            content: `Error: unknown tool "${call.name}"`
-          });
-          continue;
-        }
-        const output = await this.runTool(toolDef, call, ctx.signal);
-        toolResults.push({ callId: call.id, content: output });
-      }
-      messages.push(...ctx.llm.formatToolResultMessages(toolResults));
-    }
-    throw new Error(`Max tool rounds (${this.maxToolRounds}) exceeded`);
-  }
-  runTool(toolDef, call, signal) {
-    return new Promise((resolve, _reject) => {
-      const args = [...toolDef.command];
-      const cmd = args.shift();
-      const params = toolDef.parameters ?? [];
-      for (const param of params) {
-        const value = call.arguments[param.name];
-        if (value !== void 0) {
-          if (param.required && params.indexOf(param) === 0) {
-            args.push(String(value));
-          } else {
-            args.push(`--${param.name}`, String(value));
-          }
-        }
-      }
-      const child = spawn(cmd, args, {
-        cwd: this.skillDir,
-        stdio: ["pipe", "pipe", "pipe"],
-        timeout: 6e4,
-        killSignal: "SIGKILL",
-        signal
-      });
-      let stdout = "";
-      let stderr = "";
-      const stdoutDecoder = new StringDecoder("utf8");
-      const stderrDecoder = new StringDecoder("utf8");
-      child.stdout.on("data", (data) => {
-        if (stdout.length < MAX_TOOL_OUTPUT) {
-          stdout += stdoutDecoder.write(data);
-          if (stdout.length > MAX_TOOL_OUTPUT) {
-            stdout = stdout.slice(0, MAX_TOOL_OUTPUT);
-          }
-        }
-      });
-      child.stderr.on("data", (data) => {
-        if (stderr.length < MAX_TOOL_OUTPUT) {
-          stderr += stderrDecoder.write(data);
-          if (stderr.length > MAX_TOOL_OUTPUT) {
-            stderr = stderr.slice(0, MAX_TOOL_OUTPUT);
-          }
-        }
-      });
-      child.on("close", (code) => {
-        if (code === 0) {
-          resolve(stdout.trim());
-        } else {
-          resolve(`Error (exit ${code}): ${stderr.trim() || stdout.trim()}`);
-        }
-      });
-      child.on("error", (err) => {
-        resolve(`Error: ${err.message}`);
-      });
-    });
+    return this.inner.execute(input, ctx);
   }
 };
 
 // src/skill/loader.ts
-var LAMPORTS_PER_SOL = 1e9;
-function solToLamports(sol) {
-  if (!Number.isFinite(sol) || sol < 0) {
-    return 0;
-  }
-  return Math.round(sol * LAMPORTS_PER_SOL);
-}
-function parseSkillMd(content) {
-  const lines = content.split("\n");
-  let start = -1;
-  let end = -1;
-  for (let i = 0; i < lines.length; i++) {
-    if (lines[i].trim() === "---") {
-      if (start === -1) {
-        start = i;
-      } else {
-        end = i;
-        break;
-      }
-    }
-  }
-  if (start === -1 || end === -1) {
-    throw new Error("SKILL.md must have YAML frontmatter between --- delimiters");
-  }
-  const yamlStr = lines.slice(start + 1, end).join("\n");
-  const frontmatter = YAML.parse(yamlStr);
-  if (!frontmatter.name || typeof frontmatter.name !== "string") {
-    throw new Error('SKILL.md: missing or invalid "name" field');
-  }
-  if (!frontmatter.description || typeof frontmatter.description !== "string") {
-    throw new Error('SKILL.md: missing or invalid "description" field');
-  }
-  if (!Array.isArray(frontmatter.capabilities) || frontmatter.capabilities.length === 0) {
-    throw new Error('SKILL.md: "capabilities" must be a non-empty array');
-  }
-  const systemPrompt = lines.slice(end + 1).join("\n").trim();
-  return { frontmatter, systemPrompt };
-}
 function loadSkillsFromDir(skillsDir) {
   const skills = [];
   let entries;
@@ -1668,22 +1650,26 @@ function loadSkillsFromDir(skillsDir) {
     try {
       const content = readFileSync(skillMdPath, "utf-8");
       const { frontmatter, systemPrompt } = parseSkillMd(content);
+      const parsed = validateSkillFrontmatter(frontmatter, systemPrompt, {
+        allowFreeSkills: true
+      });
       skills.push(
         new ScriptSkill(
-          frontmatter.name,
-          frontmatter.description,
-          frontmatter.capabilities,
-          solToLamports(frontmatter.price ?? 0),
-          frontmatter.image,
-          frontmatter.image_file,
+          parsed.name,
+          parsed.description,
+          parsed.capabilities,
+          Number(parsed.priceLamports),
+          parsed.image,
+          parsed.imageFile,
           entryPath,
-          systemPrompt,
-          frontmatter.tools ?? [],
-          frontmatter.max_tool_rounds ?? 10
+          parsed.systemPrompt,
+          parsed.tools,
+          parsed.maxToolRounds
         )
       );
     } catch (e) {
-      console.warn(`  ! Skipping skill "${entry}": ${e?.message ?? "unknown error"}`);
+      const message = e instanceof Error ? e.message : String(e);
+      console.warn(`  ! Skipping skill "${entry}": ${message}`);
     }
   }
   return skills;
@@ -1802,6 +1788,7 @@ function startWatchdog(deps) {
     transport,
     onPing,
     log,
+    logger,
     probeIntervalMs = WATCHDOG_PROBE_INTERVAL_MS,
     probeTimeoutMs = WATCHDOG_PROBE_TIMEOUT_MS,
     selfPingIntervalMs = WATCHDOG_SELF_PING_INTERVAL_MS,
@@ -1827,10 +1814,12 @@ function startWatchdog(deps) {
         return;
       }
       log("[watchdog] relay probe failed, resetting pool and re-subscribing");
+      logger?.info({ event: "pool_reset", reason: "probe_failed" }, "pool reset");
       resetPoolAndResubscribe();
     } catch (error) {
       const errorMessage = error instanceof Error ? error.message : String(error);
       log(`[watchdog] probe/reset error: ${errorMessage}`);
+      logger?.warn({ event: "probe_error", error: errorMessage }, "watchdog probe/reset error");
     } finally {
       busy = false;
     }
@@ -1846,10 +1835,15 @@ function startWatchdog(deps) {
         return;
       }
       log("[watchdog] self-ping failed, resetting pool and re-subscribing");
+      logger?.info({ event: "pool_reset", reason: "self_ping_failed" }, "pool reset");
       resetPoolAndResubscribe();
     } catch (error) {
       const errorMessage = error instanceof Error ? error.message : String(error);
       log(`[watchdog] self-ping/reset error: ${errorMessage}`);
+      logger?.warn(
+        { event: "self_ping_error", error: errorMessage },
+        "watchdog self-ping/reset error"
+      );
     } finally {
       busy = false;
     }
@@ -1868,37 +1862,33 @@ function startWatchdog(deps) {
 }
 
 // src/commands/start.ts
-async function cmdStart(name) {
-  if (!name) {
-    const agents = listAgents();
-    if (agents.length === 0) {
-      console.log("No agents configured. Run `elisym init` first.");
-      process.exit(1);
-    }
-    const { default: inquirer } = await import('inquirer');
-    const choices = [...agents, { name: "+ Create new agent", value: "__new__" }];
-    const { selected } = await inquirer.prompt([
-      { type: "list", name: "selected", message: "Select agent to start", choices }
-    ]);
-    if (selected === "__new__") {
-      const { cmdInit: cmdInit2 } = await Promise.resolve().then(() => (init_init(), init_exports));
-      await cmdInit2();
-      return;
-    }
-    name = selected;
+async function cmdStart(nameArg, options = {}) {
+  const cwd = process.cwd();
+  const agentName = await resolveStartAgentName(nameArg, cwd);
+  if (!agentName) {
+    return;
   }
-  const config = await loadConfigWithPrompt(name);
+  const loaded = await loadAgentWithPrompt(agentName, cwd);
+  const verbose = options.verbose === true || process.env.ELISYM_DEBUG === "1" || process.env.LOG_LEVEL === "debug";
+  const { logger, logWithIndent } = createLogger({
+    verbose,
+    tty: Boolean(process.stdout.isTTY)
+  });
   console.log(`
-  Starting agent ${name}...
+  Starting agent ${agentName} (${loaded.source})...
 `);
-  let solanaAddress;
-  if (config.payments?.length) {
-    const solPayment = config.payments.find((p) => p.chain === "solana");
-    if (solPayment) {
-      solanaAddress = solPayment.address;
-    }
+  if (loaded.shadowsGlobal) {
+    console.log(
+      `  ! Using project-local ${agentName} (shadows global agent in ~/.elisym/${agentName}/)
+`
+    );
+  }
+  if (verbose) {
+    console.log("  [debug] Verbose logging enabled. Structured diagnostics -> stderr.");
   }
-  const walletNetwork = config.payments?.find((p) => p.chain === "solana")?.network ?? "devnet";
+  const solPayment = loaded.yaml.payments.find((entry) => entry.chain === "solana");
+  const solanaAddress = solPayment?.address;
+  const walletNetwork = solPayment?.network ?? "devnet";
   if (solanaAddress) {
     try {
       const rpcUrl = getRpcUrl(walletNetwork);
@@ -1922,17 +1912,26 @@ async function cmdStart(name) {
 `);
     }
   }
-  if (!config.llm) {
+  if (!loaded.yaml.llm) {
     console.error("  ! No LLM configured. Run `elisym init` to set up LLM.\n");
     process.exit(1);
   }
-  const skillsDir = join(process.cwd(), "skills");
+  if (!loaded.secrets.llm_api_key) {
+    console.error(
+      `  ! No LLM API key. Set ${loaded.yaml.llm.provider === "anthropic" ? "ANTHROPIC_API_KEY" : "OPENAI_API_KEY"} env var or update the agent's secrets.
+`
+    );
+    process.exit(1);
+  }
+  const paths = agentPaths(loaded.dir);
+  const skillsDir = paths.skills;
   const allSkills = loadSkillsFromDir(skillsDir);
   if (allSkills.length === 0) {
     console.error(`  ! No skills found in ${skillsDir}
 `);
     console.error("  Create a skill directory with a SKILL.md to get started.");
-    console.error("  Example: ./skills/my-skill/SKILL.md\n");
+    console.error(`  Example: ${skillsDir}/my-skill/SKILL.md
+`);
     process.exit(1);
   }
   const registry = new SkillRegistry();
@@ -1948,53 +1947,88 @@ async function cmdStart(name) {
     process.exit(1);
   }
   const llm = createLlmClient({
-    provider: config.llm.provider,
-    apiKey: config.llm.api_key,
-    model: config.llm.model,
-    maxTokens: config.llm.max_tokens,
+    provider: loaded.yaml.llm.provider,
+    apiKey: loaded.secrets.llm_api_key,
+    model: loaded.yaml.llm.model,
+    maxTokens: loaded.yaml.llm.max_tokens,
     logUsage: true
   });
   const skillCtx = {
     llm,
-    agentName: config.identity.name,
-    agentDescription: config.identity.description ?? ""
+    agentName,
+    agentDescription: loaded.yaml.description ?? ""
   };
   console.log("  Connecting to relays and publishing capabilities...");
-  const identity = ElisymIdentity.fromHex(config.identity.secret_key);
-  const relays = config.relays?.length ? config.relays : [...RELAYS];
+  const identity = ElisymIdentity.fromHex(loaded.secrets.nostr_secret_key);
+  const relays = loaded.yaml.relays.length > 0 ? loaded.yaml.relays : [...RELAYS];
   const client = new ElisymClient({ relays });
+  if (process.env.ELISYM_NET_DIAG === "1") {
+    console.log("  [net-diag] Probing relay DNS + TCP connectivity...");
+    const results = await probeRelays(relays, logger);
+    for (const result of results) {
+      const ipSummary = result.ips.length > 0 ? result.ips.join(",") : "-";
+      if (result.tcpOpenMs !== void 0) {
+        console.log(`  [net-diag] ${result.url} -> ${ipSummary} TCP open in ${result.tcpOpenMs}ms`);
+      } else {
+        console.log(`  [net-diag] ${result.url} -> ${ipSummary} FAILED: ${result.error ?? "?"}`);
+      }
+    }
+  }
   const media = new MediaService();
+  const mediaCache = await readMediaCache(loaded.dir);
+  let mediaCacheDirty = false;
+  const pictureUrl = await resolveMediaField(
+    loaded.yaml.picture,
+    loaded.dir,
+    mediaCache,
+    media,
+    identity,
+    (updated) => mediaCacheDirty = mediaCacheDirty || updated
+  );
+  const bannerUrl = await resolveMediaField(
+    loaded.yaml.banner,
+    loaded.dir,
+    mediaCache,
+    media,
+    identity,
+    (updated) => mediaCacheDirty = mediaCacheDirty || updated
+  );
   for (const skill of allSkills) {
     if (skill.image || !skill.imageFile) {
       continue;
     }
-    try {
-      const filePath = join(skillsDir, skill.name, skill.imageFile);
-      console.log(`  Uploading ${basename(filePath)}...`);
-      const data = readFileSync(filePath);
-      const blob = new Blob([data]);
-      const url = await media.upload(identity, blob, basename(filePath));
-      console.log(`  Uploaded: ${url}`);
+    const skillRoot = join(skillsDir, skill.name);
+    const cacheKey = `./skills/${skill.name}/${skill.imageFile}`;
+    const absPath = join(skillRoot, skill.imageFile);
+    const url = await uploadOrReuse(
+      cacheKey,
+      absPath,
+      mediaCache,
+      media,
+      identity,
+      () => mediaCacheDirty = true
+    );
+    if (url) {
       skill.image = url;
-      const skillMdPath = join(skillsDir, skill.name, "SKILL.md");
-      const mdContent = readFileSync(skillMdPath, "utf-8");
-      const updated = mdContent.replace(/^(image_file:\s*.+)$/m, (m) => `${m}
-image: ${url}`);
-      writeFileSync(skillMdPath, updated);
-    } catch (e) {
-      console.warn(`  ! Failed to upload image for "${skill.name}": ${e.message}`);
     }
   }
+  if (mediaCacheDirty) {
+    await writeMediaCache(loaded.dir, mediaCache);
+  }
+  let profilePublished = false;
   try {
     await client.discovery.publishProfile(
       identity,
-      config.identity.name,
-      config.identity.description ?? "",
-      config.identity.picture,
-      config.identity.banner
+      agentName,
+      loaded.yaml.description ?? "",
+      pictureUrl,
+      bannerUrl
     );
+    profilePublished = true;
+    logger.debug({ event: "publish_ack", kind: 0 }, "profile published");
   } catch (e) {
     console.warn(`  ! Failed to publish profile: ${e.message}`);
+    logger.warn({ event: "publish_failed", kind: 0, error: e.message }, "profile publish failed");
   }
   const kinds = [jobRequestKind(DEFAULT_KIND_OFFSET)];
   function buildCard(skill) {
@@ -2011,11 +2045,21 @@ image: ${url}`);
       } : void 0
     };
   }
+  let cardsPublished = 0;
   for (const skill of allSkills) {
     try {
       await client.discovery.publishCapability(identity, buildCard(skill), kinds);
+      cardsPublished += 1;
+      logger.debug(
+        { event: "publish_ack", kind: 31990, skill: skill.name },
+        "capability card published"
+      );
     } catch (e) {
       console.warn(`  ! Failed to publish "${skill.name}": ${e.message}`);
+      logger.warn(
+        { event: "publish_failed", kind: 31990, skill: skill.name, error: e.message },
+        "capability publish failed"
+      );
     }
   }
   try {
@@ -2042,6 +2086,12 @@ image: ${url}`);
   } catch {
   }
   console.log("  Connected.\n");
+  if (verbose) {
+    console.log(
+      `  [debug] Published: profile=${profilePublished ? "ok" : "FAILED"} + ${cardsPublished}/${allSkills.length} capability cards (kind:31990)`
+    );
+    console.log(`  [debug] Relays: ${relays.length} configured (${relays.join(", ")})`);
+  }
   const onPing = (senderPubkey, nonce) => {
     client.ping.sendPong(identity, senderPubkey, nonce).catch(() => {
     });
@@ -2052,12 +2102,15 @@ image: ${url}`);
     heartbeatTimer = setInterval(async () => {
       try {
         await client.discovery.publishCapability(identity, heartbeatCard, kinds);
-      } catch {
+        logger.debug({ event: "heartbeat_ack", skill: heartbeatCard.name }, "heartbeat ok");
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        logger.warn({ event: "heartbeat_failed", error: message }, "heartbeat publish failed");
       }
     }, HEARTBEAT_INTERVAL_MS);
   }
   const transport = new NostrTransport(client, identity, [DEFAULT_KIND_OFFSET]);
-  const ledger = new JobLedger(name);
+  const ledger = new JobLedger(paths.jobs);
   const runtimeConfig = {
     paymentTimeoutSecs: DEFAULTS.PAYMENT_EXPIRY_SECS,
     maxConcurrentJobs: MAX_CONCURRENT_JOBS,
@@ -2066,26 +2119,49 @@ image: ${url}`);
     network: walletNetwork,
     solanaAddress
   };
-  const logWithIndent = (msg) => console.log(`  ${msg}`);
+  const rpcUrlForLog = stripRpcSecrets(process.env.SOLANA_RPC_URL ?? getRpcUrl());
+  logger.debug(
+    {
+      event: "config_resolved",
+      agent: agentName,
+      source: loaded.source,
+      network: walletNetwork,
+      relays,
+      solanaAddress,
+      rpcUrl: rpcUrlForLog
+    },
+    "config resolved"
+  );
+  const diagLog = (msg) => {
+    logWithIndent(msg);
+    logger.info({ event: "runtime_diag" }, msg);
+  };
   const watchdog = startWatchdog({
     client,
     identity,
     transport,
     onPing,
-    log: logWithIndent
+    log: diagLog,
+    logger
   });
   const runtime = new AgentRuntime(transport, registry, skillCtx, runtimeConfig, ledger, {
     onJobReceived: (job) => {
       const cap = job.tags.find((t) => t !== "elisym") ?? "unknown";
-      console.log(`  [job] ${job.jobId.slice(0, 16)} | cap=${cap}`);
+      process.stdout.write(`  [job] ${job.jobId.slice(0, 16)} | cap=${cap}
+`);
+      logger.info({ event: "job_received", jobId: job.jobId, capability: cap });
     },
     onJobCompleted: (jobId) => {
-      console.log(`  [job] ${jobId.slice(0, 16)} | delivered`);
+      process.stdout.write(`  [job] ${jobId.slice(0, 16)} | delivered
+`);
+      logger.info({ event: "job_delivered", jobId });
     },
     onJobError: (jobId, error) => {
-      console.error(`  [job] ${jobId.slice(0, 16)} | error: ${error}`);
+      process.stderr.write(`  [job] ${jobId.slice(0, 16)} | error: ${error}
+`);
+      logger.error({ event: "job_error", jobId, error });
     },
-    onLog: logWithIndent,
+    onLog: diagLog,
     onStop: () => {
       watchdog.stop();
       if (heartbeatTimer) {
@@ -2096,15 +2172,100 @@ image: ${url}`);
   console.log("  * Running. Press Ctrl+C to stop.\n");
   await runtime.run();
 }
+function stripRpcSecrets(raw) {
+  try {
+    const parsed = new URL(raw);
+    parsed.username = "";
+    parsed.password = "";
+    const marker = parsed.search.length > 0 ? "?***" : "";
+    parsed.search = "";
+    return `${parsed.toString()}${marker}`;
+  } catch {
+    return "[unparseable RPC URL]";
+  }
+}
+async function resolveMediaField(value, agentDir, cache, media, identity, onCacheUpdate) {
+  if (!value) {
+    return void 0;
+  }
+  if (isRemoteUrl(value)) {
+    return value;
+  }
+  const absPath = resolveInsideAgentDir(value, agentDir);
+  if (!absPath) {
+    console.warn(`  ! Skipping media field "${value}": path must stay inside the agent directory.`);
+    return void 0;
+  }
+  return uploadOrReuse(value, absPath, cache, media, identity, () => onCacheUpdate(true));
+}
+function resolveInsideAgentDir(value, agentDir) {
+  const agentRoot = resolve(agentDir);
+  const candidate = resolve(agentRoot, value);
+  const rel = relative(agentRoot, candidate);
+  if (rel === "" || rel.startsWith("..") || rel.includes(`..${sep}`)) {
+    return null;
+  }
+  return candidate;
+}
+async function uploadOrReuse(cacheKey, absPath, cache, media, identity, onCacheUpdate) {
+  try {
+    const cached = await lookupCachedUrl(cache, cacheKey, absPath);
+    if (cached) {
+      return cached;
+    }
+    console.log(`  Uploading ${basename(absPath)}...`);
+    const data = readFileSync(absPath);
+    const sha256 = createHash("sha256").update(data).digest("hex");
+    const blob = new Blob([data]);
+    const url = await media.upload(identity, blob, basename(absPath));
+    cache[cacheKey] = newCacheEntry(url, sha256);
+    onCacheUpdate();
+    console.log(`  Uploaded: ${url}`);
+    return url;
+  } catch (e) {
+    console.warn(`  ! Failed to upload ${basename(absPath)}: ${e.message}`);
+    return void 0;
+  }
+}
+function isRemoteUrl(value) {
+  return /^https?:\/\//i.test(value);
+}
 var MAX_PASSPHRASE_ATTEMPTS = 3;
-async function loadConfigWithPrompt(name) {
+async function resolveStartAgentName(nameArg, cwd) {
+  if (nameArg) {
+    return nameArg;
+  }
+  const agents = await listAgents(cwd);
+  if (agents.length === 0) {
+    console.log("No agents configured. Run `elisym init` first.");
+    process.exit(1);
+  }
+  const { default: inquirer } = await import('inquirer');
+  const choices = [
+    ...agents.map((agent) => ({
+      name: `${agent.name} (${agent.source}${agent.shadowsGlobal ? " - shadows global" : ""})`,
+      value: agent.name
+    })),
+    { name: "+ Create new agent", value: "__new__" }
+  ];
+  const { selected } = await inquirer.prompt([
+    { type: "list", name: "selected", message: "Select agent to start", choices }
+  ]);
+  if (selected === "__new__") {
+    const { cmdInit: cmdInit2 } = await Promise.resolve().then(() => (init_init(), init_exports));
+    await cmdInit2();
+    return void 0;
+  }
+  return selected;
+}
+async function loadAgentWithPrompt(name, cwd) {
   const envPassphrase = process.env.ELISYM_PASSPHRASE;
   try {
-    return loadConfig(name, envPassphrase);
+    return await loadAgent(name, cwd, envPassphrase);
   } catch (e) {
-    const isEncryptedConfigError = /encrypted but no passphrase/i.test(e?.message ?? "");
+    const isEncrypted3 = /encrypted secrets/i.test(e?.message ?? "");
     const isWrongPassphrase = /Decryption failed/i.test(e?.message ?? "");
-    if (!isEncryptedConfigError && !isWrongPassphrase) {
+    if (!isEncrypted3 && !isWrongPassphrase) {
       throw e;
     }
     if (!process.stdin.isTTY) {
@@ -2122,7 +2283,7 @@ async function loadConfigWithPrompt(name) {
       }
     ]);
     try {
-      return loadConfig(name, passphrase);
+      return await loadAgent(name, cwd, passphrase);
     } catch (e) {
       if (!/Decryption failed/i.test(e?.message ?? "")) {
         throw e;
@@ -2137,12 +2298,10 @@ async function loadConfigWithPrompt(name) {
   }
   throw new Error("Unreachable");
 }
-
-// src/commands/wallet.ts
-init_config();
 async function cmdWallet(name) {
+  const cwd = process.cwd();
   if (!name) {
-    const agents = listAgents();
+    const agents = await listAgents(cwd);
     if (agents.length === 0) {
       console.error("No agents found.");
       process.exit(1);
@@ -2153,33 +2312,32 @@ async function cmdWallet(name) {
         type: "list",
         name: "selected",
         message: "Select agent:",
-        choices: agents
+        choices: agents.map((agent) => ({
+          name: `${agent.name} (${agent.source})`,
+          value: agent.name
+        }))
       }
     ]);
     name = selected;
   }
   const passphrase = process.env.ELISYM_PASSPHRASE;
-  const config = loadConfig(name, passphrase);
-  const solPayment = config.payments?.find((p) => p.chain === "solana");
+  const loaded = await loadAgent(name, cwd, passphrase);
+  const solPayment = loaded.yaml.payments.find((entry) => entry.chain === "solana");
   if (!solPayment?.address) {
     console.error("Solana address not configured for this agent.");
     process.exit(1);
   }
-  const network = solPayment.network ?? "devnet";
-  const rpcUrl = getRpcUrl();
+  const rpcUrl = getRpcUrl(solPayment.network);
   const rpc = createSolanaRpc(rpcUrl);
   const walletAddress = address(solPayment.address);
   const { value: balance } = await rpc.getBalance(walletAddress).send();
   console.log(`
   Agent: ${name}`);
-  console.log(`  Network: ${network}`);
+  console.log(`  Network: ${solPayment.network}`);
   console.log(`  Address: ${solPayment.address}`);
   console.log(`  Balance: ${formatSol(Number(balance))} (${balance} lamports)
 `);
 }
-
-// src/index.ts
-init_config();
 function readPackageVersion() {
   try {
     const here = dirname(fileURLToPath(import.meta.url));
@@ -2193,50 +2351,57 @@ var PACKAGE_VERSION = readPackageVersion();
 
 // src/index.ts
 process.removeAllListeners("warning");
-var program = new Command().name("elisym").description("CLI agent runner for the elisym network").version(PACKAGE_VERSION);
-program.command("init").description("Create a new agent (interactive wizard)").action(cmdInit);
-program.command("profile [name]").description("Edit agent profile, wallet, and LLM settings").action(cmdProfile);
-program.command("start [name]").description("Start agent in provider mode").action(cmdStart);
-program.command("list").description("List all agents").action(() => {
-  const agents = listAgents();
-  if (agents.length === 0) {
-    console.log("No agents found. Run `elisym init` to create one.");
-    return;
-  }
-  console.log("\nAgents:");
-  for (const name of agents) {
+function safe(fn) {
+  return async (...args) => {
     try {
-      const config = loadConfig(name);
-      const secretKey = config.identity.secret_key;
-      let npub = "(encrypted)";
-      if (!secretKey.startsWith("encrypted:")) {
-        const secretBytes = Buffer.from(secretKey, "hex");
-        npub = secretBytes.length === 32 ? nip19.npubEncode(getPublicKey(secretBytes)) : "(invalid key)";
-      }
-      const solAddr = config.payments?.[0]?.address ? ` | Solana: ${config.payments[0].address}` : "";
-      console.log(`  ${name} | ${npub}${solAddr}`);
-    } catch {
-      console.log(`  ${name} (error loading config)`);
+      await fn(...args);
+    } catch (e) {
+      console.error(`Error: ${e instanceof Error ? e.message : String(e)}`);
+      process.exit(1);
     }
-  }
-  console.log();
-});
-program.command("wallet [name]").description("Show wallet balance").action(cmdWallet);
-program.command("delete <name>").description("Delete an agent").action(async (name) => {
-  const { default: inquirer } = await import('inquirer');
-  const { confirm } = await inquirer.prompt([
-    {
-      type: "confirm",
-      name: "confirm",
-      message: `Delete agent "${name}"? This cannot be undone.`,
-      default: false
+  };
+}
+var program = new Command().name("elisym").description("CLI agent runner for the elisym network").version(PACKAGE_VERSION);
+program.command("init [name]").description("Create a new agent").option("-c, --config <path>", "Load fields from an elisym.yaml template (non-interactive)").option("--local", "Create in project <project>/.elisym/<name>/ (default: ~/.elisym/<name>/)").action(
+  safe(async (name, options) => {
+    await cmdInit(name, options);
+  })
+);
+program.command("profile [name]").description("Edit agent profile, wallet, and LLM settings").action(safe(cmdProfile));
+program.command("start [name]").description("Start agent in provider mode").option(
+  "-v, --verbose",
+  "Enable debug logging (relay lifecycle, publish acks, subscription EOSE). Also togglable via ELISYM_DEBUG=1 or LOG_LEVEL=debug."
+).action(
+  safe(async (name, options) => {
+    await cmdStart(name, options);
+  })
+);
+program.command("list").description("List all agents (project-local and home-global)").action(
+  safe(async () => {
+    const cwd = process.cwd();
+    const agents = await listAgents(cwd);
+    if (agents.length === 0) {
+      console.log("No agents found. Run `elisym init` to create one.");
+      return;
     }
-  ]);
-  if (confirm) {
-    deleteAgent(name);
-    console.log(`Agent "${name}" deleted.`);
-  }
-});
+    console.log("\nAgents:");
+    for (const agent of agents) {
+      try {
+        const loaded = await loadAgent(agent.name, cwd);
+        const identity = ElisymIdentity.fromHex(loaded.secrets.nostr_secret_key);
+        const npub = nip19.npubEncode(identity.publicKey);
+        const solAddr = loaded.yaml.payments[0]?.address ? ` | Solana: ${loaded.yaml.payments[0].address}` : "";
+        const shadow = agent.shadowsGlobal ? " [shadows global]" : "";
+        console.log(`  ${agent.name} (${agent.source})${shadow} | ${npub}${solAddr}`);
+      } catch (e) {
+        const hint = /encrypted secrets/i.test(e?.message ?? "") ? " (encrypted)" : "";
+        console.log(`  ${agent.name} (${agent.source})${hint}`);
+      }
+    }
+    console.log();
+  })
+);
+program.command("wallet [name]").description("Show wallet balance").action(safe(cmdWallet));
 program.parse();
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map