@guildai/cli 0.3.17 → 0.4.0

package/dist/lib/generated-types.d.ts

@@ -1,4 +1,4 @@
-export declare const WEBHOOK_SERVICES: readonly ["AZURE_DEVOPS", "BITBUCKET", "CYPRESS", "GITHUB", "GOOGLE_DOCS", "JIRA", "LINEAR", "NEWRELIC", "NOTION", "SLACK", "TESTRAIL", "ZENDESK"];
+export declare const WEBHOOK_SERVICES: readonly ["AZURE_DEVOPS", "BITBUCKET", "CYPRESS", "GITHUB", "GOOGLE_DOCS", "GOOGLE_COMPUTE", "GOOGLE_LOGGING", "JIRA", "LINEAR", "NEWRELIC", "NOTION", "SLACK", "TESTRAIL", "ZENDESK"];
 export type WebhookService = (typeof WEBHOOK_SERVICES)[number];
 export declare const TIME_TRIGGER_FREQUENCIES: readonly ["HOURLY", "DAILY", "WEEKLY", "MONTHLY"];
 export type TimeTriggerFrequency = (typeof TIME_TRIGGER_FREQUENCIES)[number];

package/dist/lib/generated-types.js

@@ -13,6 +13,8 @@ export const WEBHOOK_SERVICES = [
     'CYPRESS',
     'GITHUB',
     'GOOGLE_DOCS',
+    'GOOGLE_COMPUTE',
+    'GOOGLE_LOGGING',
     'JIRA',
     'LINEAR',
     'NEWRELIC',

package/dist/lib/npmrc.js

@@ -17,6 +17,7 @@ export async function configureNpmrc() {
     }
     try {
         await execa('npm', [
+            '--workspaces=false',
             'config',
             'set',
             '--location',
@@ -36,7 +37,14 @@ export async function cleanupNpmrc() {
     const keys = [...SCOPES.map((s) => `${s}:registry`), `${scope}:_authToken`];
     for (const key of keys) {
         try {
-            await execa('npm', ['config', 'delete', '--location', 'user', key]);
+            await execa('npm', [
+                '--workspaces=false',
+                'config',
+                'delete',
+                '--location',
+                'user',
+                key,
+            ]);
         }
         catch {
             // Key may not exist, that's fine

package/dist/lib/output.d.ts

@@ -1,5 +1,5 @@
 import { type Spinner } from './progress.js';
-import type { Agent, Pagination, Workspace, Trigger } from './api-types.js';
+import type { Agent, AgentVersion, Context, Pagination, Workspace, WorkspaceAgent, Trigger } from './api-types.js';
 /**
  * Session type from API responses
  */
@@ -19,6 +19,21 @@ interface Session {
  * Shared by agent list and agent search commands.
  */
 export declare function formatAgentTable(agents: Agent[], pagination: Pagination): void;
+/**
+ * Format an agent version list as a human-readable table.
+ * Used by agent versions command.
+ */
+export declare function formatVersionTable(versions: AgentVersion[], pagination: Pagination): void;
+/**
+ * Format a context list as a human-readable table.
+ * Used by workspace context list command.
+ */
+export declare function formatContextTable(contexts: Context[], pagination: Pagination): void;
+/**
+ * Format a workspace agent list as a human-readable table.
+ * Used by workspace agent list command.
+ */
+export declare function formatWorkspaceAgentTable(agents: WorkspaceAgent[]): void;
 /**
  * Format a workspace list as a human-readable table.
  * Used by workspace list command.
@@ -38,7 +53,7 @@ export declare function formatTriggerTable(triggers: Trigger[], pagination: Pagi
  * Output writer interface for consistent CLI output
  *
  * Implementations:
- * - HumanOutputWriter: Colors, tables, spinners for interactive use
+ * - InteractiveOutputWriter: Colors, tables, spinners for interactive use
  * - JSONOutputWriter: Pure JSON for scripting and automation
  */
 export interface OutputWriter {
@@ -69,9 +84,8 @@ export interface OutputWriter {
  * Uses colors, symbols, and formatting for readability.
  * Progress goes to stderr.
  */
-export declare class HumanOutputWriter implements OutputWriter {
+export declare class InteractiveOutputWriter implements OutputWriter {
     data(value: unknown): void;
-    private isAgentListResponse;
     success(message: string, details?: Record<string, unknown>): void;
     error(message: string, details?: string): void;
     progress(message: string): void;

package/dist/lib/output.js

@@ -76,6 +76,112 @@ export function formatAgentTable(agents, pagination) {
         console.log(chalk.dim(`\nShowing ${showing} of ${pagination.total_count} agents`));
     }
 }
+/**
+ * Format an agent version list as a human-readable table.
+ * Used by agent versions command.
+ */
+export function formatVersionTable(versions, pagination) {
+    if (versions.length === 0) {
+        console.log(chalk.dim('No versions found'));
+        return;
+    }
+    const table = new Table({
+        columns: [
+            { name: 'sha', title: 'SHA', alignment: 'left' },
+            { name: 'version', title: 'VERSION', alignment: 'left', color: 'cyan' },
+            { name: 'status', title: 'STATUS', alignment: 'left' },
+            { name: 'validation', title: 'VALIDATION', alignment: 'left' },
+            { name: 'summary', title: 'SUMMARY', alignment: 'left' },
+            { name: 'created', title: 'CREATED', alignment: 'left' },
+        ],
+    });
+    versions.forEach((v) => {
+        const validationColor = v.validation_status === 'PASSED'
+            ? chalk.green
+            : v.validation_status === 'FAILED'
+                ? chalk.red
+                : chalk.dim;
+        table.addRow({
+            sha: v.sha.slice(0, 7),
+            version: v.version_number || '-',
+            status: v.status,
+            validation: validationColor(v.validation_status || '-'),
+            summary: truncate(v.summary || '', 30),
+            created: v.created_at ? formatRelativeTime(v.created_at) : '',
+        });
+    });
+    table.printTable();
+    const showing = Math.min(pagination.limit, versions.length);
+    if (pagination.has_more) {
+        const nextOffset = pagination.offset + pagination.limit;
+        console.log(`\nShowing ${showing} of ${pagination.total_count} versions. ` +
+            chalk.dim(`Use --offset ${nextOffset} to see more.`));
+    }
+    else if (pagination.total_count > showing) {
+        console.log(chalk.dim(`\nShowing ${showing} of ${pagination.total_count} versions`));
+    }
+}
+/**
+ * Format a context list as a human-readable table.
+ * Used by workspace context list command.
+ */
+export function formatContextTable(contexts, pagination) {
+    if (contexts.length === 0) {
+        console.log(chalk.dim('No contexts found'));
+        return;
+    }
+    const table = new Table({
+        columns: [
+            { name: 'id', title: 'ID', alignment: 'left' },
+            { name: 'status', title: 'STATUS', alignment: 'left', color: 'cyan' },
+            { name: 'type', title: 'TYPE', alignment: 'left' },
+            { name: 'created', title: 'CREATED', alignment: 'left' },
+        ],
+    });
+    contexts.forEach((ctx) => {
+        table.addRow({
+            id: truncate(ctx.id, 12),
+            status: ctx.status,
+            type: ctx.type || '-',
+            created: ctx.created_at ? formatRelativeTime(ctx.created_at) : '',
+        });
+    });
+    table.printTable();
+    const showing = Math.min(pagination.limit, contexts.length);
+    if (pagination.has_more) {
+        const nextOffset = pagination.offset + pagination.limit;
+        console.log(`\nShowing ${showing} of ${pagination.total_count} contexts. ` +
+            chalk.dim(`Use --offset ${nextOffset} to see more.`));
+    }
+    else if (pagination.total_count > showing) {
+        console.log(chalk.dim(`\nShowing ${showing} of ${pagination.total_count} contexts`));
+    }
+}
+/**
+ * Format a workspace agent list as a human-readable table.
+ * Used by workspace agent list command.
+ */
+export function formatWorkspaceAgentTable(agents) {
+    if (agents.length === 0) {
+        console.log(chalk.dim('No agents installed in this workspace'));
+        return;
+    }
+    const table = new Table({
+        columns: [
+            { name: 'name', title: 'NAME', alignment: 'left' },
+            { name: 'version', title: 'VERSION', alignment: 'left', color: 'cyan' },
+            { name: 'auto_update', title: 'AUTO-UPDATE', alignment: 'left' },
+        ],
+    });
+    agents.forEach((wa) => {
+        table.addRow({
+            name: wa.agent.full_name || wa.agent.name,
+            version: wa.agent_version.version_number || wa.agent_version.sha.slice(0, 7),
+            auto_update: wa.should_autoupdate ? chalk.green('yes') : chalk.dim('no'),
+        });
+    });
+    table.printTable();
+}
 /**
  * Format a workspace list as a human-readable table.
  * Used by workspace list command.
@@ -199,23 +305,10 @@ export function formatTriggerTable(triggers, pagination) {
  * Uses colors, symbols, and formatting for readability.
  * Progress goes to stderr.
  */
-export class HumanOutputWriter {
+export class InteractiveOutputWriter {
     data(value) {
-        // Special handling for agent list responses
-        if (this.isAgentListResponse(value)) {
-            formatAgentTable(value.items, value.pagination);
-            return;
-        }
-        // Fallback to pretty JSON for other data
         console.log(JSON.stringify(value, null, 2));
     }
-    isAgentListResponse(value) {
-        return (typeof value === 'object' &&
-            value !== null &&
-            'items' in value &&
-            'pagination' in value &&
-            Array.isArray(value.items));
-    }
     success(message, details) {
         process.stderr.write(chalk.green('✓') + ' ' + message + '\n');
         if (details) {
@@ -273,7 +366,7 @@ export class JSONOutputWriter {
  */
 export function createOutputWriter() {
     const mode = getOutputMode();
-    return mode === 'json' ? new JSONOutputWriter() : new HumanOutputWriter();
+    return mode === 'json' ? new JSONOutputWriter() : new InteractiveOutputWriter();
 }
 /**
  * Create a no-op spinner (for quiet/JSON modes)

package/dist/lib/stdin.d.ts

@@ -1,3 +1,9 @@
+/**
+ * Exit with a helpful error when stdin is piped but no --mode flag was given.
+ * Call this before rendering an interactive UI (Ink render()) so users who
+ * accidentally pipe input without --mode get clear guidance instead of a hang.
+ */
+export declare function ensureInteractiveStdin(command: string): void;
 /**
  * Read JSON from stdin with a timeout.
  */

package/dist/lib/stdin.js

@@ -1,4 +1,22 @@
 // Copyright (c) 2026 Guild.ai All Rights Reserved
+/**
+ * Exit with a helpful error when stdin is piped but no --mode flag was given.
+ * Call this before rendering an interactive UI (Ink render()) so users who
+ * accidentally pipe input without --mode get clear guidance instead of a hang.
+ */
+export function ensureInteractiveStdin(command) {
+    if (!process.stdin.isTTY) {
+        console.error('Error: stdin is piped but --mode was not specified');
+        console.error('');
+        console.error('When piping input, use --mode to set the input format:');
+        console.error(`  echo '{"prompt":"hello"}' | ${command} --mode json`);
+        console.error(`  cat inputs.jsonl | ${command} --mode jsonl`);
+        console.error('');
+        console.error('Or run interactively (no pipe):');
+        console.error(`  ${command}`);
+        process.exit(1);
+    }
+}
 /**
  * Read JSON from stdin with a timeout.
  */

package/docs/CLI_WORKFLOW.md

@@ -1,3 +1,8 @@
+---
+name: Guild CLI Workflow
+description: Agent development using the Guild CLI. Activated when user mentions guild agent commands, saving/publishing agents, clone/pull workflow, or agent testing. Covers CLI commands and common workflows.
+---
+
 # Guild CLI Agent Development Workflow
 
 For local agent development using the Guild CLI. This workflow manages agent code via the Guild git server.
@@ -8,10 +13,11 @@ For local agent development using the Guild CLI. This workflow manages agent cod
 
 ```bash
 # Create a new agent
-guild agent init --name my-agent --template LLM
+guild agent create my-agent --template LLM
 
 # Clone an existing agent
-guild agent clone guildai/slack-assistant
+guild agent clone guildai/dev-assistant
+cd dev-assistant
 
 # Save changes (commits and syncs to Guild server)
 guild agent save --message "Description of changes"
@@ -35,7 +41,6 @@ guild agent save --message "Description" --wait --publish
 - ❌ Run `git pull` directly (use `guild agent pull`)
 - ❌ Run `git commit` directly (use `guild agent save`)
 - ❌ Edit `guild.json` (it's generated and gitignored)
-- ❌ Push to GitHub (agents sync to Guild's git server)
 
 ## Common Commands
 
@@ -45,31 +50,32 @@ guild agent save --message "Description" --wait --publish
 # Install Guild CLI skills for coding assistants (Claude Code, etc.)
 guild setup
 
-# Install skills and create a CLAUDE.md template
+# Also create a CLAUDE.md template
 guild setup --claude-md
 ```
 
 ### Creating Agents
 
 ```bash
-# Interactive creation
-guild agent init --name my-agent
-
-# With specific template
-guild agent init --name my-agent --template LLM
-guild agent init --name my-agent --template COMPILED
-guild agent init --name my-agent --template BLANK
+# Create with template (interactive — prompts for template if omitted)
+guild agent create my-agent
+guild agent create my-agent --template LLM
+guild agent create my-agent --template AUTO_MANAGED_STATE
+guild agent create my-agent --template BLANK
 
 # Fork an existing agent
-guild agent init --fork guildai/slack-assistant
+guild agent init --fork owner/agent-name
+
+# Clone to work on an existing agent
+guild agent clone owner/agent-name
 ```
 
 ### Working with Existing Agents
 
 ```bash
 # Clone to work on an agent
-guild agent clone guildai/slack-assistant
-cd slack-assistant
+guild agent clone guildai/dev-assistant
+cd dev-assistant
 
 # Pull remote changes (from collaborators or web edits)
 guild agent pull
@@ -114,19 +120,22 @@ guild agent versions --limit 1
 # Interactive test session
 guild agent test
 
+# Test uncommitted changes without saving
+guild agent test --ephemeral
+
 # Test with specific input
 guild agent chat "Hello, can you help me?"
 ```
 
 ## File Structure
 
-After `guild agent init`, you get:
+After `guild agent create`, you get:
 
 ```
 my-agent/
 ├── .git/              # Git repo (remote is Guild server)
 ├── .gitignore         # Includes guild.json
-├── agent.ts           # Your agent code
+├── agent.ts           # Your agent code (default; can also be in src/)
 ├── package.json       # Dependencies
 ├── tsconfig.json      # TypeScript config
 └── guild.json         # Agent ID (gitignored, local only)
@@ -143,28 +152,19 @@ my-agent/
 
 ### "No changes to commit"
 
-You already committed. Just push:
-
-```bash
-git push origin main
-```
+All changes are already committed. Make a code change first, then run `guild agent save` again.
 
 ### "guild.json not found"
 
 You're not in an agent directory. Either:
 
 - `cd` into the agent directory
-- Run `guild agent init` to create one
+- Run `guild agent create` to create one
 
 ### Validation Failed
 
-Check the error in `guild agent versions --limit 1`. Common issues:
+Check the error with `guild agent versions --limit 1`. Common issues:
 
 - TypeScript compilation errors
 - Missing dependencies
 - Invalid schema
-
-## See Also
-
-- [Agent Development Guide](https://github.com/agents-for-dev/guildai__agent-builder__019a8e0d-5280-726e-0000-b896bbbc2320/blob/main/docs/AGENT_DEVELOPMENT.md) - Comprehensive patterns and SDK usage
-- SDK: `@guildai/agents-sdk`

package/docs/getting-started.md

@@ -316,7 +316,7 @@ guild agent code               # View source of latest version
 
 ## Key Rules
 
-- Agent code lives at `agent.ts` in the project root.
+- Agent code lives in `agent.ts` (typically at the project root, but can be in a subdirectory like `src/`).
 - Don't add `@guildai/agents-sdk`, `zod`, or `@guildai-services/*` to `package.json`. The runtime provides them. Only add third-party packages you actually use.
 - Always call tools through `task.tools.<name>(args)`. Never access services directly.
 - Always use `guild agent save` to commit and `guild agent pull` to sync. Don't use raw git commands.

package/docs/output-format.md

@@ -46,7 +46,7 @@ interface OutputWriter {
 
 Two implementations:
 
-- `HumanOutputWriter` - Colors, symbols, formatted output
+- `InteractiveOutputWriter` - Colors, symbols, formatted output
 - `JSONOutputWriter` - Pure JSON
 
 Commands use `createOutputWriter()` to get the right implementation based on flags.

package/docs/skills/agent-dev.md

@@ -1,11 +1,11 @@
 ---
 name: Guild Agent Development
-description: Agent development using the Guild CLI. Activated when user mentions creating agents, guild agent commands, saving/publishing agents, or agent development workflow. Handles proper CLI workflow and prevents direct git operations.
+description: Local agent development using the Guild CLI. Activated when user mentions creating agents, guild agent commands, saving/publishing agents, or agent development workflow. Handles proper CLI workflow and prevents direct git operations.
 ---
 
 # Guild Agent Development
 
-Build agents for Guild using the CLI. **Always use the Guild CLI for agent operations — never use raw git commands.**
+Build agents for Guild using the CLI. **Always use the Guild CLI for agent operations - never use raw git commands.**
 
 ## When to Use This
 
@@ -33,7 +33,7 @@ guild setup --claude-md
 ### Creating Agents
 
 ```bash
-# Create from template (interactive — prompts for template)
+# Create from template (interactive - prompts for template)
 guild agent create my-agent
 
 # Create with specific template
@@ -80,18 +80,38 @@ guild agent test --ephemeral
 guild agent chat "Hello, can you help me?"
 ```
 
-## Use the Guild CLI for All Agent Operations
+## Guild CLI Is the ONLY Tool for Agent Operations
 
-**All agent work — creating, saving, testing, debugging — goes through Guild CLI.**
+**ALL agent work — creating, saving, testing, debugging, investigating — goes through Guild CLI.**
+
+### For Creating and Modifying
 
 - ✅ `guild agent create`, `guild agent init`, `guild agent clone`
 - ✅ `guild agent save --message "description"`
 - ✅ `guild agent pull` (sync remote changes into local directory)
 - ✅ `guild agent test`, `guild agent chat`
-- ✅ `guild agent get`, `guild agent versions`, `guild agent code`, `guild agent grep`
-- ❌ NEVER use `git commit`, `git push`, `git pull` for agent operations
+- ❌ NEVER use `git commit`, `git push`, `gh repo` for agent operations
 - ❌ NEVER manually create `package.json`, `tsconfig.json`, or `guild.json`
 
+### For Investigating and Debugging
+
+- ✅ `guild agent clone <id>` to get agent source locally
+- ✅ `guild agent versions <id>` to check version history
+- ✅ `guild agent code <id>` to view source
+- ✅ `guild agent get <id>` to view agent info
+- ✅ `guild agent grep <pattern>` to search across all agent code
+- ✅ Read local clones created by `guild agent clone`
+- ❌ NEVER use `git clone`, `gh repo`, or direct API calls for agent source — always use Guild CLI
+
+### If Guild CLI Can't Do Something
+
+**STOP and tell the user:**
+
+1. What you need to do
+2. Why Guild CLI can't do it
+3. Why you think `gh`/`git` is needed
+4. Let the user decide — never reach for `gh`/`git` on your own
+
 ---
 
 ## SDK Reference
@@ -118,12 +138,14 @@ import { ask, output, callTools } from '@guildai/agents-sdk';
 // Platform tools (from SDK)
 import { guildTools, userInterfaceTools } from '@guildai/agents-sdk';
 
-// Service tools (from separate packages — NOT from SDK)
+// Service tools (from separate packages - NOT from SDK)
 import { gitHubTools } from '@guildai-services/guildai~github';
 import { slackTools } from '@guildai-services/guildai~slack';
 import { jiraTools } from '@guildai-services/guildai~jira';
 import { bitbucketTools } from '@guildai-services/guildai~bitbucket';
 import { azureDevOpsTools } from '@guildai-services/guildai~azure-devops';
+import { pipedreamTools } from '@guildai-services/guildai~pipedream';
+import { cypressTools } from '@guildai-services/guildai~cypress';
 
 // Utilities
 import { pick, progressLogNotifyEvent } from '@guildai/agents-sdk';
@@ -141,12 +163,16 @@ Service tools are in separate `@guildai-services/*` packages. The runtime resolv
 
 | Service        | Package                                  | Export               | Tool Name Prefix |
 | -------------- | ---------------------------------------- | -------------------- | ---------------- |
-| GitHub         | `@guildai-services/guildai~github`       | `gitHubTools`        | `github_`        |
-| Slack          | `@guildai-services/guildai~slack`        | `slackTools`         | `slack_`         |
-| Jira           | `@guildai-services/guildai~jira`         | `jiraTools`          | `jira_`          |
-| Bitbucket      | `@guildai-services/guildai~bitbucket`    | `bitbucketTools`     | `bitbucket_`     |
 | Azure DevOps   | `@guildai-services/guildai~azure-devops` | `azureDevOpsTools`   | `azure_devops_`  |
+| Bitbucket      | `@guildai-services/guildai~bitbucket`    | `bitbucketTools`     | `bitbucket_`     |
+| Cypress        | `@guildai-services/guildai~cypress`      | `cypressTools`       | `cypress_`       |
+| GitHub         | `@guildai-services/guildai~github`       | `gitHubTools`        | `github_`        |
 | Guild          | `@guildai/agents-sdk`                    | `guildTools`         | `guild_`         |
+| Jira           | `@guildai-services/guildai~jira`         | `jiraTools`          | `jira_`          |
+| Linear         | `@guildai-services/guildai~linear`       | `linearTools`        | `linear_`        |
+| NewRelic       | `@guildai-services/guildai~newrelic`     | `newrelicTools`      | `newrelic_`      |
+| Pipedream      | `@guildai-services/guildai~pipedream`    | `pipedreamTools`     | `pipedream_`     |
+| Slack          | `@guildai-services/guildai~slack`        | `slackTools`         | `slack_`         |
 | User Interface | `@guildai/agents-sdk`                    | `userInterfaceTools` | `ui_`            |
 
 ### Tool Access via `task.tools.*`
@@ -169,7 +195,10 @@ const issues = await task.tools.jira_search_and_reconsile_issues_using_jql({
 });
 
 // User interface
-const response = await task.tools.ui_prompt({ type: 'text', text: 'What repo?' });
+const response = await task.tools.ui_prompt({
+  type: 'text',
+  text: 'What repo?',
+});
 await task.tools.ui_notify(progressLogNotifyEvent('Processing...'));
 
 // Guild
@@ -489,10 +518,23 @@ async function onToolResults(
 
 ### Slack-Specific Patterns
 
-When posting to Slack, convert markdown to Slack's mrkdwn format:
+When posting to Slack, convert markdown to Slack's mrkdwn format. Use an inline converter
+(`slackify-markdown` is CJS and breaks in the ESM agent runtime):
 
 ```typescript
-import slackifyMarkdown from 'slackify-markdown';
+// Simple markdown-to-Slack-mrkdwn converter (inline — do NOT use slackify-markdown)
+function slackifyMarkdown(md: string): string {
+  return md
+    .replace(/\*\*(.+?)\*\*/g, '*$1*') // bold: **text** → *text*
+    .replace(/(?<!\*)\*(?!\*)(.+?)(?<!\*)\*(?!\*)/g, '_$1_') // italic: *text* → _text_
+    .replace(/~~(.+?)~~/g, '~$1~') // strikethrough
+    .replace(/^### (.+)$/gm, '*$1*') // h3 → bold
+    .replace(/^## (.+)$/gm, '*$1*') // h2 → bold
+    .replace(/^# (.+)$/gm, '*$1*') // h1 → bold
+    .replace(/\[([^\]]+)\]\(([^)]+)\)/g, '<$2|$1>') // links
+    .replace(/^> (.+)$/gm, '> $1') // blockquotes (same syntax)
+    .replace(/`([^`]+)`/g, '`$1`'); // inline code (same syntax)
+}
 
 // In your agent:
 const responseText = '## Summary\n- Item 1\n- Item 2';
@@ -504,16 +546,6 @@ await task.tools.slack_chat_post_message({
 });
 ```
 
-Add `slackify-markdown` to `package.json` dependencies:
-
-```json
-{
-  "dependencies": {
-    "slackify-markdown": "^4.5.0"
-  }
-}
-```
-
 ---
 
 ## Anti-Hallucination Guide
@@ -522,7 +554,7 @@ Add `slackify-markdown` to `package.json` dependencies:
 
 ### NEVER `pick()` from `guildTools`
 
-**Always spread `guildTools` fully. NEVER use `pick(guildTools, [...])`.**
+**CRITICAL: Always spread `guildTools` fully. NEVER use `pick(guildTools, [...])`.**
 
 The SDK's `Task` type conditionally provides `task.guild: GuildService` based on whether the **full** `guildTools` set is in the tools type. Using `pick()` creates a subset type that doesn't satisfy this constraint, causing:
 
@@ -620,19 +652,17 @@ export default agent({ run: async (input, task) => { ... } })
   "version": "1.0.0",
   "author": "Guild.ai",
   "type": "module",
-  "dependencies": {
-    "slackify-markdown": "^4.5.0"
-  },
+  "dependencies": {},
   "devDependencies": {
     "typescript": "^5.0.0"
   }
 }
 ```
 
-**Important:**
+**CRITICAL:**
 
 - Do NOT add `@guildai/agents-sdk`, `@guildai-services/*`, or `zod` to dependencies. The runtime provides them.
-- DO add third-party packages your agent uses (e.g., `slackify-markdown`) to `dependencies`.
+- DO add third-party ESM-compatible packages your agent uses to `dependencies`. Note: CJS-only packages (e.g., `slackify-markdown`) will break in the ESM agent runtime — use inline alternatives instead.
 - `devDependencies` is for build tools only.
 
 ## Versioning
@@ -649,7 +679,7 @@ After `guild agent create` + `guild agent init`:
 my-agent/
 ├── .git/              # Git repo (remote is Guild server)
 ├── .gitignore         # Includes guild.json
-├── agent.ts           # Your agent code (at project root, NOT in src/)
+├── agent.ts           # Your agent code (default location; can also be in src/)
 ├── package.json       # Dependencies
 ├── tsconfig.json      # TypeScript config
 └── guild.json         # Agent ID (gitignored, local only)
@@ -657,10 +687,10 @@ my-agent/
 
 ## Version Lifecycle
 
-1. **Draft** — After `guild agent save` (no `--publish`)
-2. **Validating** — After `--publish`, running validation
-3. **Published** — Validation passed, available for use
-4. **Failed** — Validation failed, check errors
+1. **Draft** - After `guild agent save` (no `--publish`)
+2. **Validating** - After `--publish`, running validation
+3. **Published** - Validation passed, available for use
+4. **Failed** - Validation failed, check errors
 
 ## CLI Commands
 
@@ -671,9 +701,9 @@ guild agent create <name>                          # Create new agent (prompts f
 guild agent create <name> --template LLM           # Create with specific template
 guild agent init                                   # Initialize local workspace
 guild agent init --fork <agent-id>                 # Fork existing agent
+guild agent pull                                   # Pull remote changes
 guild agent save --message "description"           # Save changes
 guild agent save --message "v1.0" --wait --publish # Save + validate + publish
-guild agent pull                                   # Pull remote changes
 guild agent test                                   # Interactive test
 guild agent test --ephemeral                       # Ephemeral test
 guild agent chat "Hello"                           # Test with input
@@ -688,6 +718,15 @@ guild agent revalidate                             # Re-run validation
 guild agent code [agent-id]                        # View agent source
 guild agent grep <pattern>                         # Search agent code files for a regex pattern
 guild agent grep <pattern> --published             # Search only published agents
+guild agent owners                                 # List accounts that can own agents
+guild workspace select                             # Set default workspace (writes to guild.json if in agent dir)
+```
+
+### Environment Variable Overrides
+
+```bash
+GUILD_WORKSPACE_ID=<id> guild agent test           # Override workspace for this command
+GUILD_OWNER_ID=<id> guild agent init --name my-agent  # Override owner for agent creation
 ```
 
 ## Troubleshooting

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guildai/cli",
-  "version": "0.3.17",
+  "version": "0.4.0",
   "description": "Guild.ai CLI - Build, test, and deploy AI agents",
   "type": "module",
   "main": "dist/index.js",