@orchagent/cli 0.3.31 → 0.3.34

package/dist/adapters/agents-md.js

@@ -32,13 +32,26 @@ exports.agentsMdAdapter = {
         const orgSlug = agent.org_slug || 'unknown';
         const agentRef = `${orgSlug}/${agent.name}`;
         const description = agent.description || '';
+        // Build skills section if present
+        let skillsSection = '';
+        if (agent.resolvedSkills && agent.resolvedSkills.length > 0) {
+            skillsSection = '\n### Bundled Skills\n\nThe following skills are bundled with this agent and must be applied.';
+            for (const skill of agent.resolvedSkills) {
+                skillsSection += `\n\n#### ${skill.name}`;
+                if (skill.description) {
+                    skillsSection += `\n\n${skill.description}`;
+                }
+                skillsSection += `\n\n${skill.prompt}`;
+            }
+            skillsSection += '\n';
+        }
         // Use orchagent markers for managed section
         const content = `<!-- orchagent:${agentRef} -->
 ## ${agent.name}
 
 ${description}
 
-${agent.prompt || ''}
+${agent.prompt || ''}${skillsSection}
 <!-- /orchagent:${agentRef} -->
 `;
         return [

package/dist/adapters/claude-code.js

@@ -70,6 +70,17 @@ exports.claudeCodeAdapter = {
         if (agent.output_schema) {
             body += `\n\n## Output Schema\n\nThis agent should return output matching:\n\`\`\`json\n${JSON.stringify(agent.output_schema, null, 2)}\n\`\`\``;
         }
+        // Embed resolved skills
+        if (agent.resolvedSkills && agent.resolvedSkills.length > 0) {
+            body += '\n\n## Bundled Skills\n\nThe following skills are bundled with this agent and must be applied.';
+            for (const skill of agent.resolvedSkills) {
+                body += `\n\n### ${skill.name}`;
+                if (skill.description) {
+                    body += `\n\n${skill.description}`;
+                }
+                body += `\n\n${skill.prompt}`;
+            }
+        }
         // Combine frontmatter + body
         const content = `---\n${yaml_1.default.stringify(frontmatter).trim()}\n---\n\n${body.trim()}\n`;
         return [

package/dist/adapters/cursor.js

@@ -38,6 +38,18 @@ exports.cursorAdapter = {
     convert(agent) {
         const normalizedName = (0, utils_1.normalizeAgentName)(agent.name);
         const description = agent.description || `Rules from ${agent.name}`;
+        // Build skills section if present
+        let skillsSection = '';
+        if (agent.resolvedSkills && agent.resolvedSkills.length > 0) {
+            skillsSection = '\n\n## Bundled Skills\n\nThe following skills are bundled with this agent and must be applied.';
+            for (const skill of agent.resolvedSkills) {
+                skillsSection += `\n\n### ${skill.name}`;
+                if (skill.description) {
+                    skillsSection += `\n\n${skill.description}`;
+                }
+                skillsSection += `\n\n${skill.prompt}`;
+            }
+        }
         // Cursor .mdc format
         const content = `---
 description: ${description}
@@ -47,7 +59,7 @@ alwaysApply: false
 
 # ${agent.name}
 
-${agent.prompt || ''}
+${agent.prompt || ''}${skillsSection}
 `;
         return [
             {

package/dist/commands/call.js

@@ -15,6 +15,8 @@ const llm_1 = require("../lib/llm");
 const analytics_1 = require("../lib/analytics");
 const pricing_1 = require("../lib/pricing");
 const DEFAULT_VERSION = 'latest';
+// Well-known field names for file content in prompt agent schemas (priority order)
+const CONTENT_FIELD_NAMES = ['code', 'content', 'text', 'source', 'input', 'file_content', 'body'];
 // Keys that might indicate local file path references in JSON payloads
 const LOCAL_PATH_KEYS = ['path', 'directory', 'file', 'filepath', 'dir', 'folder', 'local'];
 /**
@@ -43,13 +45,42 @@ function warnIfLocalPathReference(jsonBody) {
         if (pathKey) {
             process.stderr.write(`Warning: Your payload contains a local path reference ('${pathKey}').\n` +
                 `Remote agents cannot access your local filesystem. The path will be interpreted\n` +
-                `by the server, not your local machine. Use --help for more information.\n\n`);
+                `by the server, not your local machine.\n\n` +
+                `Tip: Use 'orchagent run <agent>' instead to execute locally with filesystem access.\n\n`);
         }
     }
     catch {
         // If parsing fails, skip the warning (the actual error will be thrown later)
     }
 }
+/**
+ * Infer the best JSON field name for file content based on the agent's input schema.
+ * Returns the field name to use, or 'content' as a safe default.
+ */
+function inferFileField(inputSchema) {
+    if (!inputSchema || typeof inputSchema !== 'object')
+        return 'content';
+    const props = inputSchema.properties;
+    if (!props || typeof props !== 'object')
+        return 'content';
+    const properties = props;
+    // Check for well-known field names in priority order
+    for (const field of CONTENT_FIELD_NAMES) {
+        if (properties[field] && properties[field].type === 'string')
+            return field;
+    }
+    // If there's exactly one required string property, use that
+    const required = (inputSchema.required ?? []);
+    const stringProps = Object.entries(properties)
+        .filter(([, v]) => v.type === 'string')
+        .map(([k]) => k);
+    if (stringProps.length === 1)
+        return stringProps[0];
+    const requiredStrings = stringProps.filter(k => required.includes(k));
+    if (requiredStrings.length === 1)
+        return requiredStrings[0];
+    return 'content';
+}
 function parseAgentRef(value) {
     const [ref, versionPart] = value.split('@');
     const version = versionPart?.trim() || DEFAULT_VERSION;
@@ -147,16 +178,24 @@ function registerCallCommand(program) {
         .option('--skills-only <skills>', 'Use only these skills')
         .option('--no-skills', 'Ignore default skills')
         .option('--file <path...>', 'File(s) to upload (can specify multiple)')
+        .option('--file-field <field>', 'Schema field name for file content (prompt agents)')
         .option('--metadata <json>', 'JSON metadata to send with files')
         .addHelpText('after', `
 Examples:
   orch call orchagent/invoice-scanner invoice.pdf
+  orch call orchagent/useeffect-checker --file src/App.tsx
+  orch call orchagent/useeffect-checker --file src/App.tsx --file-field code
   orch call orchagent/leak-finder --data '{"repo_url": "https://github.com/org/repo"}'
   cat input.json | orch call acme/agent --data @-
   orch call acme/image-processor photo.jpg --output result.png
 
 Note: Use 'call' for server-side execution (requires login), 'run' for local execution.
 
+File handling:
+  For prompt agents, file content is read and sent as JSON mapped to the agent's
+  input schema. Use --file-field to specify the field name (auto-detected by default).
+  For code agents, files are uploaded as multipart form data.
+
 Important: Remote agents cannot access your local filesystem. If your --data payload
 contains keys like 'path', 'directory', 'file', etc., those values will be interpreted
 by the server, not your local machine. To send local files, use the positional file
@@ -207,7 +246,8 @@ Paid Agents:
             }
             if (isOwner) {
                 // Owner: show free message, no balance check needed
-                process.stderr.write(`Cost: FREE (author)\n\n`);
+                if (!options.json)
+                    process.stderr.write(`Cost: FREE (author)\n\n`);
             }
             else {
                 // Non-owner: check balance
@@ -215,7 +255,8 @@ Paid Agents:
                 pricingInfo = { price_cents: price ?? null };
                 if (!price || price <= 0) {
                     // Price missing or invalid - warn but proceed (server will enforce)
-                    process.stderr.write(`Warning: Pricing data unavailable. The server will verify payment.\n\n`);
+                    if (!options.json)
+                        process.stderr.write(`Warning: Pricing data unavailable. The server will verify payment.\n\n`);
                 }
                 else {
                     // Valid price - check balance
@@ -233,11 +274,13 @@ Paid Agents:
                             process.exit(errors_1.ExitCodes.PERMISSION_DENIED);
                         }
                         // Sufficient balance - show cost preview
-                        process.stderr.write(`Cost: $${(price / 100).toFixed(2)}/call\n\n`);
+                        if (!options.json)
+                            process.stderr.write(`Cost: $${(price / 100).toFixed(2)}/call\n\n`);
                     }
                     catch (err) {
                         // Balance check failed - warn but proceed (server will enforce)
-                        process.stderr.write(`Warning: Could not verify balance. The server will check payment.\n\n`);
+                        if (!options.json)
+                            process.stderr.write(`Warning: Could not verify balance. The server will check payment.\n\n`);
                     }
                 }
             }
@@ -354,8 +397,45 @@ Paid Agents:
             }
             headers['Content-Type'] = 'application/json';
         }
+        else if ((filePaths.length > 0 || options.metadata) && agentMeta.type === 'prompt') {
+            // Prompt agent + files/metadata: read content and send as JSON
+            const fieldName = options.fileField || inferFileField(agentMeta.input_schema);
+            let bodyObj = {};
+            // Include metadata if provided
+            if (options.metadata) {
+                try {
+                    bodyObj = JSON.parse(options.metadata);
+                }
+                catch {
+                    throw new errors_1.CliError('--metadata must be valid JSON.');
+                }
+            }
+            if (filePaths.length === 1) {
+                // Single file: map content to the inferred/specified schema field
+                const fileContent = await promises_1.default.readFile(filePaths[0], 'utf-8');
+                bodyObj[fieldName] = fileContent;
+                sourceLabel = filePaths[0];
+            }
+            else if (filePaths.length > 1) {
+                // Multiple files: map first to the schema field, add all as files object
+                const allContents = {};
+                for (const fp of filePaths) {
+                    allContents[path_1.default.basename(fp)] = await promises_1.default.readFile(fp, 'utf-8');
+                }
+                // Set the primary field to the first file's content
+                const firstContent = await promises_1.default.readFile(filePaths[0], 'utf-8');
+                bodyObj[fieldName] = firstContent;
+                bodyObj.files = allContents;
+                sourceLabel = `${filePaths.length} files`;
+            }
+            if (llmCredentials) {
+                bodyObj.llm_credentials = llmCredentials;
+            }
+            body = JSON.stringify(bodyObj);
+            headers['Content-Type'] = 'application/json';
+        }
         else if (filePaths.length > 0 || options.metadata) {
-            // Handle multipart file uploads
+            // Code agent: handle multipart file uploads
             // Inject llm_credentials into metadata if available
             let metadata = options.metadata;
             if (llmCredentials) {
@@ -379,9 +459,9 @@ Paid Agents:
             sourceLabel = multipart.sourceLabel;
         }
         const url = `${resolved.apiUrl.replace(/\/$/, '')}/${org}/${parsed.agent}/${parsed.version}/${endpoint}`;
-        // Make the API call with a spinner
-        const spinner = (0, spinner_1.createSpinner)(`Calling ${org}/${parsed.agent}@${parsed.version}...`);
-        spinner.start();
+        // Make the API call with a spinner (suppress in --json mode for clean machine-readable output)
+        const spinner = options.json ? null : (0, spinner_1.createSpinner)(`Calling ${org}/${parsed.agent}@${parsed.version}...`);
+        spinner?.start();
         let response;
         try {
             response = await (0, api_1.safeFetchWithRetryForCalls)(url, {
@@ -391,7 +471,7 @@ Paid Agents:
             });
         }
         catch (err) {
-            spinner.fail(`Call failed: ${err instanceof Error ? err.message : 'Unknown error'}`);
+            spinner?.fail(`Call failed: ${err instanceof Error ? err.message : 'Unknown error'}`);
             throw err;
         }
         if (!response.ok) {
@@ -409,7 +489,7 @@ Paid Agents:
                 : undefined;
             // Part 2: Handle 402 Payment Required
             if (response.status === 402 || errorCode === 'INSUFFICIENT_CREDITS') {
-                spinner.fail('Insufficient credits');
+                spinner?.fail('Insufficient credits');
                 let errorMessage = 'Insufficient credits to call this agent.\n\n';
                 // Use pricing info from pre-call check if available
                 if (pricingInfo?.price_cents) {
@@ -422,22 +502,31 @@ Paid Agents:
                 throw new errors_1.CliError(errorMessage, errors_1.ExitCodes.PERMISSION_DENIED);
             }
             if (errorCode === 'LLM_KEY_REQUIRED') {
-                spinner.fail('LLM key required');
+                spinner?.fail('LLM key required');
                 throw new errors_1.CliError('This public agent requires you to provide an LLM key.\n' +
                     'Use --key <key> --provider <provider> or set OPENAI_API_KEY/ANTHROPIC_API_KEY env var.');
             }
+            if (errorCode === 'LLM_RATE_LIMITED') {
+                const rateLimitMsg = typeof payload === 'object' && payload
+                    ? payload.error?.message || 'Rate limit exceeded'
+                    : 'Rate limit exceeded';
+                spinner?.fail('Rate limited by LLM provider');
+                throw new errors_1.CliError(rateLimitMsg + '\n\n' +
+                    'This is the LLM provider\'s rate limit on your API key, not an OrchAgent limit.\n' +
+                    'To switch providers: orch call <agent> --provider <gemini|anthropic|openai>', errors_1.ExitCodes.RATE_LIMITED);
+            }
             const message = typeof payload === 'object' && payload
                 ? payload.error
                     ?.message ||
                     payload.message ||
                     response.statusText
                 : response.statusText;
-            spinner.fail(`Call failed: ${message}`);
+            spinner?.fail(`Call failed: ${message}`);
             throw new errors_1.CliError(message);
         }
-        spinner.succeed(`Called ${org}/${parsed.agent}@${parsed.version}`);
-        // After successful call, if it was a paid agent, show cost
-        if ((0, pricing_1.isPaidAgent)(agentMeta) && pricingInfo?.price_cents && pricingInfo.price_cents > 0) {
+        spinner?.succeed(`Called ${org}/${parsed.agent}@${parsed.version}`);
+        // After successful call, if it was a paid agent, show cost (suppress in --json mode)
+        if (!options.json && (0, pricing_1.isPaidAgent)(agentMeta) && pricingInfo?.price_cents && pricingInfo.price_cents > 0) {
             process.stderr.write(`\nCost: $${(pricingInfo.price_cents / 100).toFixed(2)} USD\n`);
         }
         // Track successful call

package/dist/commands/config.js

@@ -10,7 +10,7 @@ function getAllValidFormatIds() {
     const skillFormatIds = [...config_1.VALID_FORMAT_IDS];
     return [...new Set([...adapterIds, ...skillFormatIds])];
 }
-const SUPPORTED_KEYS = ['default-format'];
+const SUPPORTED_KEYS = ['default-format', 'default-scope'];
 function isValidKey(key) {
     return SUPPORTED_KEYS.includes(key);
 }
@@ -29,6 +29,13 @@ async function setConfigValue(key, value) {
         await (0, config_1.setDefaultFormats)(formats);
         process.stdout.write(`Set default-format to: ${formats.join(',')}\n`);
     }
+    if (key === 'default-scope') {
+        if (value !== 'user' && value !== 'project') {
+            throw new errors_1.CliError('Invalid scope. Must be "user" or "project"');
+        }
+        await (0, config_1.setDefaultScope)(value);
+        process.stdout.write(`Set default-scope to: ${value}\n`);
+    }
 }
 async function getConfigValue(key) {
     if (!isValidKey(key)) {
@@ -44,6 +51,15 @@ async function getConfigValue(key) {
             process.stdout.write(`${formats.join(',')}\n`);
         }
     }
+    if (key === 'default-scope') {
+        const scope = await (0, config_1.getDefaultScope)();
+        if (!scope) {
+            process.stdout.write('(not set)\n');
+        }
+        else {
+            process.stdout.write(`${scope}\n`);
+        }
+    }
 }
 async function listConfigValues() {
     const config = await (0, config_1.loadConfig)();
@@ -56,6 +72,14 @@ async function listConfigValues() {
     else {
         process.stdout.write('  default-format: (not set)\n');
     }
+    // default-scope
+    const scope = config.default_scope;
+    if (scope) {
+        process.stdout.write(`  default-scope: ${scope}\n`);
+    }
+    else {
+        process.stdout.write('  default-scope: (not set)\n');
+    }
     process.stdout.write('\n');
 }
 function registerConfigCommand(program) {

package/dist/commands/delete.js

@@ -9,6 +9,7 @@ const chalk_1 = __importDefault(require("chalk"));
 const config_1 = require("../lib/config");
 const api_1 = require("../lib/api");
 const errors_1 = require("../lib/errors");
+const agent_ref_1 = require("../lib/agent-ref");
 const analytics_1 = require("../lib/analytics");
 async function promptText(message) {
     const rl = promises_1.default.createInterface({
@@ -23,16 +24,6 @@ async function promptConfirm(message) {
     const answer = await promptText(`${message} (y/N): `);
     return answer.toLowerCase() === 'y' || answer.toLowerCase() === 'yes';
 }
-function parseAgentArg(value) {
-    const atIndex = value.lastIndexOf('@');
-    if (atIndex === -1 || atIndex === 0) {
-        return { name: value, version: 'latest' };
-    }
-    return {
-        name: value.slice(0, atIndex),
-        version: value.slice(atIndex + 1) || 'latest',
-    };
-}
 function registerDeleteCommand(program) {
     program
         .command('delete <agent>')
@@ -41,29 +32,29 @@ function registerDeleteCommand(program) {
         .option('--dry-run', 'Show what would be deleted without making changes')
         .addHelpText('after', `
 Examples:
-  orch delete my-agent           # Delete latest version
-  orch delete my-agent@v1        # Delete specific version
-  orch delete my-agent --dry-run # Preview deletion
+  orch delete org/my-agent           # Delete latest version
+  orch delete org/my-agent@v1        # Delete specific version
+  orch delete org/my-agent --dry-run # Preview deletion
 `)
         .action(async (agent, options) => {
-        const { name: agentName, version } = parseAgentArg(agent);
+        const ref = (0, agent_ref_1.parseAgentRef)(agent);
         const config = await (0, config_1.getResolvedConfig)();
         if (!config.apiKey) {
             throw new errors_1.CliError('Not logged in. Run `orch login` first.');
         }
         process.stdout.write('Finding agent...\n');
-        // Find the agent
+        // Find the agent by name, filtering by org if provided
         const agents = await (0, api_1.listMyAgents)(config);
-        const matching = agents.filter(a => a.name === agentName);
+        const matching = agents.filter(a => a.name === ref.agent && (!a.org_slug || a.org_slug === ref.org));
         if (matching.length === 0) {
-            throw new errors_1.CliError(`Agent '${agentName}' not found`);
+            throw new errors_1.CliError(`Agent '${ref.org}/${ref.agent}' not found`);
         }
         // Select version
         let selectedAgent;
-        if (version !== 'latest') {
-            selectedAgent = matching.find(a => a.version === version);
+        if (ref.version !== 'latest') {
+            selectedAgent = matching.find(a => a.version === ref.version);
             if (!selectedAgent) {
-                throw new errors_1.CliError(`Version '${version}' not found for agent '${agentName}'`);
+                throw new errors_1.CliError(`Version '${ref.version}' not found for agent '${ref.org}/${ref.agent}'`);
             }
         }
         else {

package/dist/commands/init.js

@@ -45,6 +45,80 @@ const SCHEMA_TEMPLATE = `{
   }
 }
 `;
+const CODE_TEMPLATE_PY = `"""
+orchagent code agent entrypoint.
+
+Reads JSON input from stdin, processes it, and writes JSON output to stdout.
+This is the standard orchagent code agent protocol.
+
+Usage:
+  echo '{"input": "hello"}' | python main.py
+"""
+
+import json
+import sys
+
+
+def main():
+    # Read JSON input from stdin
+    raw = sys.stdin.read()
+    try:
+        data = json.loads(raw) if raw.strip() else {}
+    except json.JSONDecodeError:
+        print(json.dumps({"error": "Invalid JSON input"}))
+        sys.exit(1)
+
+    user_input = data.get("input", "")
+
+    # --- Your logic here ---
+    result = f"Received: {user_input}"
+    # --- End your logic ---
+
+    # Write JSON output to stdout
+    print(json.dumps({"result": result}))
+
+
+if __name__ == "__main__":
+    main()
+`;
+function readmeTemplate(agentName, type) {
+    const callExample = type === 'code'
+        ? `orchagent call ${agentName} input-file.txt`
+        : `orchagent call ${agentName} --data '{"input": "Hello world"}'`;
+    const runExample = type === 'code'
+        ? `orchagent run ${agentName} --input '{"file_path": "src/app.py"}'`
+        : `orchagent run ${agentName} --input '{"input": "Hello world"}'`;
+    return `# ${agentName}
+
+A brief description of what this agent does.
+
+## Usage
+
+### Server execution
+
+\`\`\`sh
+${callExample}
+\`\`\`
+
+### Local execution
+
+\`\`\`sh
+${runExample}
+\`\`\`
+
+## Input
+
+| Field | Type | Description |
+|-------|------|-------------|
+| \`input\` | string | The input to process |
+
+## Output
+
+| Field | Type | Description |
+|-------|------|-------------|
+| \`result\` | string | The agent's response |
+`;
+}
 const SKILL_TEMPLATE = `---
 name: my-skill
 description: When to use this skill
@@ -63,27 +137,50 @@ function registerInitCommand(program) {
         .option('--type <type>', 'Type: prompt, code, or skill (default: prompt)', 'prompt')
         .action(async (name, options) => {
         const cwd = process.cwd();
+        // When a name is provided, create a subdirectory for the project
+        const targetDir = name ? path_1.default.join(cwd, name) : cwd;
         const agentName = name || path_1.default.basename(cwd);
+        // Create the subdirectory if a name was provided
+        if (name) {
+            await promises_1.default.mkdir(targetDir, { recursive: true });
+        }
         // Handle skill type separately
         if (options.type === 'skill') {
-            const skillPath = path_1.default.join(cwd, 'SKILL.md');
+            const skillPath = path_1.default.join(targetDir, 'SKILL.md');
+            // Check if already initialized
+            try {
+                await promises_1.default.access(skillPath);
+                throw new errors_1.CliError(`Already initialized (SKILL.md exists in ${name ? name + '/' : 'current directory'})`);
+            }
+            catch (err) {
+                if (err.code !== 'ENOENT') {
+                    throw err;
+                }
+            }
             const skillContent = SKILL_TEMPLATE.replace('my-skill', agentName);
             await promises_1.default.writeFile(skillPath, skillContent);
-            process.stdout.write(`Initialized skill "${agentName}" in ${cwd}\n`);
+            process.stdout.write(`Initialized skill "${agentName}" in ${targetDir}\n`);
             process.stdout.write(`\nFiles created:\n`);
-            process.stdout.write(`  SKILL.md - Skill content with frontmatter\n`);
+            process.stdout.write(`  ${name ? name + '/' : ''}SKILL.md - Skill content with frontmatter\n`);
             process.stdout.write(`\nNext steps:\n`);
-            process.stdout.write(`  1. Edit SKILL.md with your skill content\n`);
-            process.stdout.write(`  2. Run: orchagent publish\n`);
+            if (name) {
+                process.stdout.write(`  1. cd ${name}\n`);
+                process.stdout.write(`  2. Edit SKILL.md with your skill content\n`);
+                process.stdout.write(`  3. Run: orchagent publish\n`);
+            }
+            else {
+                process.stdout.write(`  1. Edit SKILL.md with your skill content\n`);
+                process.stdout.write(`  2. Run: orchagent publish\n`);
+            }
             return;
         }
-        const manifestPath = path_1.default.join(cwd, 'orchagent.json');
-        const promptPath = path_1.default.join(cwd, 'prompt.md');
-        const schemaPath = path_1.default.join(cwd, 'schema.json');
+        const manifestPath = path_1.default.join(targetDir, 'orchagent.json');
+        const promptPath = path_1.default.join(targetDir, 'prompt.md');
+        const schemaPath = path_1.default.join(targetDir, 'schema.json');
         // Check if already initialized
         try {
             await promises_1.default.access(manifestPath);
-            throw new errors_1.CliError(`Already initialized (orchagent.json exists)`);
+            throw new errors_1.CliError(`Already initialized (orchagent.json exists in ${name ? name + '/' : 'current directory'})`);
         }
         catch (err) {
             if (err.code !== 'ENOENT') {
@@ -95,29 +192,49 @@ function registerInitCommand(program) {
         manifest.name = agentName;
         manifest.type = ['code', 'skill'].includes(options.type) ? options.type : 'prompt';
         await promises_1.default.writeFile(manifestPath, JSON.stringify(manifest, null, 2) + '\n');
-        // Create prompt template (for prompt-based agents)
-        if (options.type !== 'code') {
+        // Create prompt template (for prompt-based agents) or entrypoint (for code agents)
+        if (options.type === 'code') {
+            const entrypointPath = path_1.default.join(targetDir, 'main.py');
+            await promises_1.default.writeFile(entrypointPath, CODE_TEMPLATE_PY);
+        }
+        else {
             await promises_1.default.writeFile(promptPath, PROMPT_TEMPLATE);
         }
         // Create schema template
         await promises_1.default.writeFile(schemaPath, SCHEMA_TEMPLATE);
-        process.stdout.write(`Initialized agent "${agentName}" in ${cwd}\n`);
+        // Create README
+        const readmePath = path_1.default.join(targetDir, 'README.md');
+        await promises_1.default.writeFile(readmePath, readmeTemplate(agentName, options.type));
+        process.stdout.write(`Initialized agent "${agentName}" in ${targetDir}\n`);
         process.stdout.write(`\nFiles created:\n`);
-        process.stdout.write(`  orchagent.json - Agent configuration\n`);
-        if (options.type !== 'code') {
-            process.stdout.write(`  prompt.md      - Prompt template\n`);
+        const prefix = name ? name + '/' : '';
+        process.stdout.write(`  ${prefix}orchagent.json - Agent configuration\n`);
+        if (options.type === 'code') {
+            process.stdout.write(`  ${prefix}main.py        - Agent entrypoint (stdin/stdout JSON)\n`);
         }
-        process.stdout.write(`  schema.json    - Input/output schemas\n`);
+        else {
+            process.stdout.write(`  ${prefix}prompt.md      - Prompt template\n`);
+        }
+        process.stdout.write(`  ${prefix}schema.json    - Input/output schemas\n`);
+        process.stdout.write(`  ${prefix}README.md      - Agent documentation\n`);
         process.stdout.write(`\nNext steps:\n`);
         if (options.type !== 'code') {
-            process.stdout.write(`  1. Edit prompt.md with your prompt template\n`);
-            process.stdout.write(`  2. Edit schema.json with your input/output schemas\n`);
-            process.stdout.write(`  3. Run: orchagent publish\n`);
+            const stepNum = name ? 2 : 1;
+            if (name) {
+                process.stdout.write(`  1. cd ${name}\n`);
+            }
+            process.stdout.write(`  ${stepNum}. Edit prompt.md with your prompt template\n`);
+            process.stdout.write(`  ${stepNum + 1}. Edit schema.json with your input/output schemas\n`);
+            process.stdout.write(`  ${stepNum + 2}. Run: orchagent publish\n`);
         }
         else {
-            process.stdout.write(`  1. Edit schema.json with your input/output schemas\n`);
-            process.stdout.write(`  2. Deploy your code and get the URL\n`);
-            process.stdout.write(`  3. Run: orchagent publish --url <your-agent-url>\n`);
+            const stepNum = name ? 2 : 1;
+            if (name) {
+                process.stdout.write(`  1. cd ${name}\n`);
+            }
+            process.stdout.write(`  ${stepNum}. Edit main.py with your agent logic\n`);
+            process.stdout.write(`  ${stepNum + 1}. Test: echo '{"input": "test"}' | python main.py\n`);
+            process.stdout.write(`  ${stepNum + 2}. Run: orchagent publish\n`);
         }
     });
 }