@guildai/cli 0.3.18 → 0.5.0

package/README.md

@@ -28,8 +28,12 @@ guild agent init --name my-agent
 ### 3. Develop and Save
 
 ```bash
-# Edit agent.ts, then save
-guild agent save --message "Initial implementation"
+# Edit agent.ts, then commit and save
+git add . && git commit -m "Initial implementation"
+guild agent save
+
+# Or stage+commit+push in one step
+guild agent save -A --message "Initial implementation"
 ```
 
 ### 4. Test Your Agent
@@ -54,7 +58,8 @@ guild auth status   # Check authentication status
 
 ```bash
 guild agent init --name my-agent        # Initialize a new agent
-guild agent save --message "..."        # Save changes
+guild agent save                        # Push commits and create a version
+guild agent save -A --message "..."    # Stage+commit+push in one step
 guild agent versions                    # List versions
 guild agent publish                     # Publish latest draft version
 guild agent unpublish                   # Unpublish latest published version

package/dist/commands/agent/chat.js

@@ -19,7 +19,7 @@ import { runGit } from '../../lib/git.js';
 import { suppressScrollbackClear } from '../../lib/alternate-screen.js';
 import * as readline from 'readline';
 import { pollForResponse } from '../../lib/session-polling.js';
-import { readStdinAsJSON } from '../../lib/stdin.js';
+import { readStdinAsJSON, ensureInteractiveStdin } from '../../lib/stdin.js';
 import { fetchSession, fetchSessionEvents } from '../../lib/session-resume.js';
 // ESM equivalent of __dirname
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -266,6 +266,7 @@ export function createAgentChatCommand() {
             else {
                 // Interactive mode: use shared ChatApp with full features
                 // (splash animation, task panel, status line, etc.)
+                ensureInteractiveStdin('guild agent chat');
                 const resumeCommand = 'guild agent chat';
                 // Handle --resume: fetch existing session + events
                 let resumeSession;

package/dist/commands/agent/clone.js

@@ -5,7 +5,7 @@ import { handleAxiosError, ErrorCodes } from '../../lib/errors.js';
 import * as fs from 'fs/promises';
 import * as path from 'path';
 import { getAuthenticatedUrl } from '../../lib/auth.js';
-import { runGit, GitError, formatGitError } from '../../lib/git.js';
+import { runGit, GitError, formatGitError, installPrePushHook } from '../../lib/git.js';
 import { createOutputWriter } from '../../lib/output.js';
 async function isDirectoryEmpty(dirPath) {
     try {
@@ -57,6 +57,8 @@ export function createAgentCloneCommand() {
             }
             await runGit(['clone', cloneUrl, targetDir]);
             output.progress(`✓ Cloned repository to ${targetDir}`);
+            await installPrePushHook(targetDir);
+            output.progress('✓ Installed pre-push hook');
             // Create guild.json if it doesn't exist
             const guildJsonPath = path.join(targetDir, 'guild.json');
             const guildJsonExists = await fs
@@ -80,8 +82,9 @@ export function createAgentCloneCommand() {
             output.progress('Next steps:');
             output.progress(`  1. cd ${targetDir}`);
             output.progress('  2. Make your changes to the code');
-            output.progress(`  3. Run 'guild agent save --message "your changes"'`);
-            output.progress(`  4. Run 'guild agent test' to test your changes`);
+            output.progress('  3. git add . && git commit -m "your changes"');
+            output.progress("  4. Run 'guild agent save' to push and create a version");
+            output.progress(`  5. Run 'guild agent test' to test your changes`);
         }
         catch (error) {
             if (error instanceof GitError) {

package/dist/commands/agent/init.js

@@ -8,7 +8,7 @@ import * as fs from 'fs/promises';
 import * as path from 'path';
 import * as readline from 'readline';
 import { getAuthenticatedUrl } from '../../lib/auth.js';
-import { runGit, GitError, formatGitError } from '../../lib/git.js';
+import { runGit, GitError, formatGitError, installPrePushHook } from '../../lib/git.js';
 import { resolveOwnerId } from '../../lib/owner-helpers.js';
 const TEMPLATE_CHOICES = [
     {
@@ -64,15 +64,23 @@ function isInteractive() {
 export function createAgentInitCommand() {
     const cmd = new Command('init');
     cmd
-        .description('Initialize current directory as a Guild agent')
+        .description('Initialize a directory as a Guild agent')
         .option('--name <name>', 'Agent name')
         .option('--template <template>', 'Agent template (LLM, AUTO_MANAGED_STATE, BLANK)')
         .option('--fork <agent-id>', 'Fork from existing agent')
         .option('--owner <owner-id>', 'Owner account (user or organization ID)')
+        .option('--directory <path>', 'Directory to initialize (created if needed)')
         .option('--force', 'Overwrite existing guild.json', false)
         .action(async (options) => {
-        const cwd = process.cwd();
-        const guildJsonPath = path.join(cwd, 'guild.json');
+        // Resolve target directory
+        const targetDir = options.directory
+            ? path.resolve(process.cwd(), options.directory)
+            : process.cwd();
+        // Create directory if it doesn't exist
+        if (options.directory) {
+            await fs.mkdir(targetDir, { recursive: true });
+        }
+        const guildJsonPath = path.join(targetDir, 'guild.json');
         try {
             // Check if already initialized
             const guildJsonExists = await fs
@@ -93,7 +101,7 @@ export function createAgentInitCommand() {
             if (!agentName) {
                 if (isInteractive()) {
                     // Use slugified directory name as default
-                    const dirName = path.basename(cwd);
+                    const dirName = path.basename(targetDir);
                     const defaultName = slugify(dirName);
                     agentName = await promptForName(defaultName);
                     if (!agentName) {
@@ -176,13 +184,13 @@ export function createAgentInitCommand() {
             format.detail(`Agent: ${agent.name} (${agent.id})`);
             format.detail(`Owner: ${owner.name}`);
             // Step 2: Initialize git repository if needed
-            const gitDir = path.join(cwd, '.git');
+            const gitDir = path.join(targetDir, '.git');
             const gitExists = await fs
                 .access(gitDir)
                 .then(() => true)
                 .catch(() => false);
             if (!gitExists) {
-                await runGit(['init'], { cwd });
+                await runGit(['init'], { cwd: targetDir });
                 steps.succeed('Initialize git repository');
             }
             else {
@@ -192,13 +200,17 @@ export function createAgentInitCommand() {
             // Step 3: Configure git remote
             try {
                 // Check if remote 'origin' exists
-                await runGit(['remote', 'get-url', 'origin'], { cwd });
+                await runGit(['remote', 'get-url', 'origin'], { cwd: targetDir });
                 // Remote exists, update it
-                await runGit(['remote', 'set-url', 'origin', agent.git_url], { cwd });
+                await runGit(['remote', 'set-url', 'origin', agent.git_url], {
+                    cwd: targetDir,
+                });
             }
             catch {
                 // Remote doesn't exist, add it
-                await runGit(['remote', 'add', 'origin', agent.git_url], { cwd });
+                await runGit(['remote', 'add', 'origin', agent.git_url], {
+                    cwd: targetDir,
+                });
             }
             steps.succeed('Configure git remote');
             format.detail(`Remote: ${agent.git_url}`);
@@ -242,7 +254,7 @@ export function createAgentInitCommand() {
                 console.error(`  guild agent get ${agent.id}`);
                 console.error('');
                 console.error('Or wait and try pulling the scaffolding manually:');
-                console.error(`  cd ${cwd}`);
+                console.error(`  cd ${targetDir}`);
                 console.error('  git pull origin main');
                 process.exit(1);
             }
@@ -258,7 +270,7 @@ export function createAgentInitCommand() {
             }
             for (let attempt = 1; attempt <= pullMaxAttempts; attempt++) {
                 try {
-                    await runGit(['pull', authenticatedGitUrl, 'main'], { cwd });
+                    await runGit(['pull', authenticatedGitUrl, 'main'], { cwd: targetDir });
                     steps.succeed('Pull scaffolding from remote');
                     break;
                 }
@@ -288,7 +300,7 @@ export function createAgentInitCommand() {
             await fs.writeFile(guildJsonPath, JSON.stringify(guildConfig, null, 2) + '\n', 'utf-8');
             steps.succeed('Create guild.json');
             // Add guild.json to .gitignore if not already present
-            const gitignorePath = path.join(cwd, '.gitignore');
+            const gitignorePath = path.join(targetDir, '.gitignore');
             try {
                 const gitignoreContent = await fs.readFile(gitignorePath, 'utf-8');
                 if (!gitignoreContent.includes('guild.json')) {
@@ -299,13 +311,25 @@ export function createAgentInitCommand() {
                 // .gitignore doesn't exist (backend should have created it), create it
                 await fs.writeFile(gitignorePath, 'guild.json\n');
             }
+            // Install pre-push hook to block direct git push
+            await installPrePushHook(targetDir);
             // Complete progress tracking
             steps.complete('Agent initialized successfully');
             // Display next steps
             format.section('Next steps:');
-            format.detail('1. Edit agent.ts to implement your agent logic');
-            format.detail(`2. Run 'guild agent save --message "Initial implementation"'`);
-            format.detail(`3. Run 'guild agent test' to test your agent`);
+            if (options.directory) {
+                format.detail(`1. cd ${targetDir}`);
+                format.detail('2. Edit agent.ts to implement your agent logic');
+                format.detail('3. git add . && git commit -m "Initial implementation"');
+                format.detail("4. Run 'guild agent save' to push and create a version");
+                format.detail(`5. Run 'guild agent test' to test your agent`);
+            }
+            else {
+                format.detail('1. Edit agent.ts to implement your agent logic');
+                format.detail('2. git add . && git commit -m "Initial implementation"');
+                format.detail("3. Run 'guild agent save' to push and create a version");
+                format.detail(`4. Run 'guild agent test' to test your agent`);
+            }
         }
         catch (error) {
             if (error instanceof GitError) {

package/dist/commands/agent/save.js

@@ -12,8 +12,9 @@ import { pollUntilComplete } from '../../lib/polling.js';
 export function createAgentSaveCommand() {
     const cmd = new Command('save');
     cmd
-        .description('Save agent code by committing and syncing with guildcore')
-        .option('--message <text>', 'Commit message describing the changes')
+        .description('Push committed changes to Guild and create a version')
+        .option('-A, --all', 'Stage all changes and commit before pushing', false)
+        .option('--message <text>', 'Commit message (required with --all)')
         .option('--wait', 'Wait for validation to complete before returning', false)
         .option('--publish', 'Publish after validation passes (implies --wait)', false)
         .option('--json', 'Output JSON only (no progress messages)', false)
@@ -21,9 +22,9 @@ export function createAgentSaveCommand() {
         const cwd = process.cwd();
         let guildConfig = null;
         const output = createOutputWriter();
-        // Check for --message
-        if (!options.message) {
-            output.error('Commit message is required', 'Provide a message describing your changes:\n  guild agent save --message "Add new feature"');
+        // With --all, a commit message is required
+        if (options.all && !options.message) {
+            output.error('Commit message is required with --all', 'Provide a message describing your changes:\n  guild agent save -A --message "Add new feature"');
             process.exit(1);
         }
         try {
@@ -39,45 +40,60 @@ export function createAgentSaveCommand() {
             }
             // Read guild.json
             guildConfig = JSON.parse(await fs.readFile(guildJsonPath, 'utf-8'));
-            // Check for uncommitted changes
+            // Check for uncommitted changes and unpushed commits
             const { stdout: statusOutput } = await runGit(['status', '--porcelain'], {
                 cwd,
             });
             const hasUncommittedChanges = statusOutput.trim().length > 0;
             let hasUnpushedCommits = false;
-            if (!hasUncommittedChanges) {
-                // Working tree is clean — check for unpushed commits from a
-                // previous save that committed locally but failed to push.
+            // Check for unpushed commits
+            try {
+                const { stdout: branchForCheck } = await runGit(['rev-parse', '--abbrev-ref', 'HEAD'], { cwd });
+                const { stdout: unpushed } = await runGit(['log', `origin/${branchForCheck.trim()}..HEAD`, '--oneline'], { cwd });
+                hasUnpushedCommits = unpushed.trim().length > 0;
+            }
+            catch {
+                // No remote tracking branch yet — if HEAD has commits, treat
+                // as unpushed so the push flow can create the remote branch.
                 try {
-                    const { stdout: branchForCheck } = await runGit(['rev-parse', '--abbrev-ref', 'HEAD'], { cwd });
-                    const { stdout: unpushed } = await runGit(['log', `origin/${branchForCheck.trim()}..HEAD`, '--oneline'], { cwd });
-                    hasUnpushedCommits = unpushed.trim().length > 0;
+                    const { stdout: logOutput } = await runGit(['log', '--oneline', '-1'], {
+                        cwd,
+                    });
+                    hasUnpushedCommits = logOutput.trim().length > 0;
                 }
                 catch {
-                    // No remote tracking branch yet — if HEAD has commits, treat
-                    // as unpushed so the push flow can create the remote branch.
-                    try {
-                        const { stdout: logOutput } = await runGit(['log', '--oneline', '-1'], {
-                            cwd,
-                        });
-                        hasUnpushedCommits = logOutput.trim().length > 0;
-                    }
-                    catch {
-                        hasUnpushedCommits = false;
-                    }
+                    hasUnpushedCommits = false;
                 }
-                if (!hasUnpushedCommits) {
-                    output.error('No changes to commit', 'Working tree is clean. Make changes to your code before saving.');
-                    process.exit(1);
+            }
+            if (options.all) {
+                // --all: stage and commit before pushing
+                if (hasUncommittedChanges) {
+                    await runGit(['add', '-A'], { cwd });
+                    output.progress('✓ Staged changes');
+                    await runGit(['commit', '-m', options.message], { cwd });
+                    output.progress('✓ Committed locally');
+                    hasUnpushedCommits = true;
                 }
-                output.progress('✓ Found unpushed commits, resuming push...');
             }
             else {
-                // Stage and commit new changes
-                await runGit(['add', '.'], { cwd });
-                output.progress('✓ Staged changes');
-                await runGit(['commit', '-m', options.message], { cwd });
-                output.progress('✓ Committed locally');
+                // Default: push-only, no staging or committing
+                if (!hasUnpushedCommits && hasUncommittedChanges) {
+                    output.error('Uncommitted changes', 'You have uncommitted changes. Either commit them first:\n  git add . && git commit -m "your message"\n\nOr use --all to stage and commit automatically:\n  guild agent save -A --message "your message"');
+                    process.exit(1);
+                }
+            }
+            if (!hasUnpushedCommits) {
+                output.error('No changes to save', 'Working tree is clean and there are no unpushed commits.');
+                process.exit(1);
+            }
+            // Resolve version summary: use --message if provided, otherwise
+            // extract the latest commit message.
+            let versionMessage = options.message;
+            if (!versionMessage) {
+                const { stdout: commitMsg } = await runGit(['log', '-1', '--pretty=%s'], {
+                    cwd,
+                });
+                versionMessage = commitMsg.trim();
             }
             // Get remote URL with auth credentials
             const { stdout: remoteUrl } = await runGit(['remote', 'get-url', 'origin'], {
@@ -94,8 +110,9 @@ export function createAgentSaveCommand() {
             });
             const currentBranch = branchName.trim();
             // Pull remote changes first (rebase to avoid merge commits)
+            const gitEnv = { GUILD_AGENT_SAVE: '1' };
             try {
-                const { stdout: pullOutput } = await runGit(['pull', '--rebase', authenticatedUrl, currentBranch], { cwd });
+                const { stdout: pullOutput } = await runGit(['pull', '--rebase', authenticatedUrl, currentBranch], { cwd, env: gitEnv });
                 if (pullOutput.includes('Updating') ||
                     pullOutput.includes('Fast-forward')) {
                     output.progress('✓ Synced with remote');
@@ -132,6 +149,7 @@ export function createAgentSaveCommand() {
                 try {
                     await runGit(['push', authenticatedUrl, `HEAD:${currentBranch}`], {
                         cwd,
+                        env: gitEnv,
                     });
                     break;
                 }
@@ -180,7 +198,7 @@ export function createAgentSaveCommand() {
             const client = new GuildAPIClient();
             let version = await client.post(`/agents/${guildConfig.agent_id}/versions`, {
                 commit_sha: commitSha,
-                summary: options.message,
+                summary: versionMessage,
                 version_type: 'COMMITTED',
             });
             output.progress(`✓ Created version (${version.id})`);
@@ -226,7 +244,7 @@ export function createAgentSaveCommand() {
                         failureDetails = 'Could not fetch validation details.';
                     }
                     failureDetails +=
-                        '\n\nFix the issues, then save a new version:\n  guild agent save --message "Fix validation errors"';
+                        '\n\nFix the issues, commit, and save a new version:\n  git add . && git commit -m "Fix validation errors"\n  guild agent save';
                     output.error('Validation failed', failureDetails);
                     process.exit(1);
                 }

package/dist/commands/agent/test.js

@@ -14,7 +14,7 @@ import { showBetaGuidance } from '../../lib/auth.js';
 import * as readline from 'readline';
 import { isQuietMode, getOutputMode } from '../../lib/output-mode.js';
 import { pollForResponse } from '../../lib/session-polling.js';
-import { readStdinAsJSON } from '../../lib/stdin.js';
+import { readStdinAsJSON, ensureInteractiveStdin } from '../../lib/stdin.js';
 import { loadLocalConfig, getWorkspaceId } from '../../lib/guild-config.js';
 import { runGit, GitError, formatGitError } from '../../lib/git.js';
 import { pollUntilComplete } from '../../lib/polling.js';
@@ -415,6 +415,7 @@ export function createAgentTestCommand() {
                 process.exit(0);
             }
             // Interactive mode: use shared ChatApp (spinner, progress, prompt)
+            ensureInteractiveStdin('guild agent test');
             const resumeCommand = 'guild agent test';
             const isInteractive = getOutputMode() === 'interactive' && !isQuietMode();
             if (isInteractive) {

package/dist/commands/chat.js

@@ -16,6 +16,7 @@ import { isUnfulfilledAgentInstallRequest, isFilteredTaskName, getTaskDisplayNam
 import { printResumeHint, fetchSession, fetchSessionEvents, eventsToDisplayMessages, } from '../lib/session-resume.js';
 import { AgentInstallPrompt } from '../components/AgentInstallPrompt.js';
 import { getWorkspaceId } from '../lib/guild-config.js';
+import { ensureInteractiveStdin } from '../lib/stdin.js';
 import { brand, BRAND_COLOR, code as codeColor } from '../lib/colors.js';
 import { SplashAnimation } from '../components/SplashAnimation.js';
 import { LOADING_TIMINGS } from '../lib/loading-messages.js';
@@ -1062,6 +1063,7 @@ export function createChatCommand() {
         }
         else {
             // Interactive mode - check auth first, then render UI with splash animation
+            ensureInteractiveStdin('guild chat');
             await ensureAuthenticated();
             // Build the resume command string for exit hints
             let resumeCommand = 'guild chat';

package/dist/commands/workspace/context/publish.js

@@ -13,7 +13,7 @@ export function createWorkspaceContextPublishCommand() {
         const output = createOutputWriter();
         try {
             const client = new GuildAPIClient();
-            await client.patch(`/workspaces/${workspaceId}/contexts/${contextId}`, {
+            await client.patch(`/contexts/${contextId}`, {
                 status: 'PUBLISHED',
             });
             output.success(`Context ${contextId} published successfully`);

package/dist/index.js

@@ -67,6 +67,7 @@ import { createDoctorCommand } from './commands/doctor.js';
 import { createSetupCommand } from './commands/setup.js';
 import { showSplashScreen, shouldShowSplash } from './lib/splash.js';
 import { checkForUpdate } from './lib/update-check.js';
+import { setupUnknownCommandSuggestions } from './lib/did-you-mean.js';
 import chalk from 'chalk';
 // ESM equivalent of __dirname
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -216,6 +217,8 @@ configCmd.addCommand(createConfigListCommand());
 configCmd.addCommand(createConfigGetCommand());
 configCmd.addCommand(createConfigSetCommand());
 configCmd.addCommand(createConfigPathCommand());
+// Set up cross-level "Did you mean?" suggestions for unknown commands
+setupUnknownCommandSuggestions(program);
 // Parse arguments
 program.parse(process.argv);
 //# sourceMappingURL=index.js.map

package/dist/lib/did-you-mean.d.ts

@@ -0,0 +1,25 @@
+import { Command } from 'commander';
+interface CommandEntry {
+    path: string;
+    description: string;
+    leafName: string;
+}
+/**
+ * Recursively collects all commands from the command tree.
+ * Includes both leaf commands and command groups (parents with subcommands).
+ * Aliases are added as separate entries.
+ */
+export declare function getAllCommands(cmd: Command, prefix?: string): CommandEntry[];
+/**
+ * Standard Levenshtein distance between two strings.
+ */
+export declare function levenshtein(a: string, b: string): number;
+/**
+ * Sets up cross-level "Did you mean?" suggestions for unknown commands.
+ *
+ * Disables Commander's built-in same-level suggestions and intercepts
+ * "unknown command" errors to search the entire command tree.
+ */
+export declare function setupUnknownCommandSuggestions(program: Command): void;
+export {};
+//# sourceMappingURL=did-you-mean.d.ts.map

package/dist/lib/did-you-mean.js

@@ -0,0 +1,143 @@
+// Copyright (c) 2026 Guild.ai All Rights Reserved
+/**
+ * Recursively collects all commands from the command tree.
+ * Includes both leaf commands and command groups (parents with subcommands).
+ * Aliases are added as separate entries.
+ */
+export function getAllCommands(cmd, prefix = '') {
+    const results = [];
+    for (const sub of cmd.commands) {
+        const name = sub.name();
+        const cmdPath = prefix ? `${prefix} ${name}` : name;
+        const description = sub.description();
+        const hasChildren = sub.commands.length > 0;
+        // Always include this command (even if it has subcommands)
+        results.push({ path: cmdPath, description, leafName: name });
+        // If this command has subcommands, also recurse into them
+        if (hasChildren) {
+            results.push(...getAllCommands(sub, cmdPath));
+        }
+        // Add aliases as separate entries
+        for (const alias of sub.aliases()) {
+            const aliasPath = prefix ? `${prefix} ${alias}` : alias;
+            results.push({ path: aliasPath, description, leafName: alias });
+            if (hasChildren) {
+                results.push(...getAllCommands(sub, aliasPath));
+            }
+        }
+    }
+    return results;
+}
+/**
+ * Standard Levenshtein distance between two strings.
+ */
+export function levenshtein(a, b) {
+    const m = a.length;
+    const n = b.length;
+    // Use a single-row DP approach for space efficiency
+    const row = Array.from({ length: n + 1 }, (_, i) => i);
+    for (let i = 1; i <= m; i++) {
+        let prev = i - 1;
+        row[0] = i;
+        for (let j = 1; j <= n; j++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            const val = Math.min(row[j] + 1, // deletion
+            row[j - 1] + 1, // insertion
+            prev + cost // substitution
+            );
+            prev = row[j];
+            row[j] = val;
+        }
+    }
+    return row[n];
+}
+/**
+ * Recursively disables Commander's built-in suggestion on all commands.
+ */
+function disableBuiltinSuggestions(cmd) {
+    cmd.showSuggestionAfterError(false);
+    for (const sub of cmd.commands) {
+        disableBuiltinSuggestions(sub);
+    }
+}
+/**
+ * Creates the writeErr handler that intercepts "unknown command" errors
+ * and prints cross-level suggestions.
+ */
+function createWriteErrHandler(program) {
+    return (str) => {
+        // Always write the original error
+        process.stderr.write(str);
+        // Check if this is an "unknown command" error
+        const match = /unknown command '([^']+)'/.exec(str);
+        if (!match) {
+            return;
+        }
+        const unknown = match[1];
+        const allCommands = getAllCommands(program);
+        // Determine the typed parent context from process.argv
+        // e.g., "guild agent trigger" → typed args are ["agent", "trigger"]
+        const typedArgs = process.argv.slice(2);
+        const typedParent = typedArgs.slice(0, -1).join(' ');
+        // Score each command
+        const scored = allCommands.map((entry) => {
+            const leafName = entry.leafName;
+            // Exact leaf name match gets score 0
+            let score = leafName === unknown ? 0 : levenshtein(unknown, leafName);
+            // Context bonus: if command's parent matches typed parent, reduce score
+            const entryParts = entry.path.split(' ');
+            const entryParent = entryParts.slice(0, -1).join(' ');
+            if (entryParent === typedParent && score > 0) {
+                score -= 0.5;
+            }
+            return { ...entry, score };
+        });
+        // Filter poor matches
+        const threshold = Math.max(2, unknown.length / 2);
+        const filtered = scored.filter((s) => s.score <= threshold);
+        if (filtered.length === 0) {
+            return;
+        }
+        // Sort by score, deduplicate by path
+        filtered.sort((a, b) => a.score - b.score);
+        const seen = new Set();
+        const unique = filtered.filter((entry) => {
+            if (seen.has(entry.path)) {
+                return false;
+            }
+            seen.add(entry.path);
+            return true;
+        });
+        // Print top 5 suggestions
+        const top = unique.slice(0, 5);
+        process.stderr.write('\nDid you mean?\n');
+        for (const entry of top) {
+            const cmd = `guild ${entry.path}`;
+            const padding = ' '.repeat(Math.max(2, 30 - cmd.length));
+            process.stderr.write(`  ${cmd}${padding}${entry.description}\n`);
+        }
+    };
+}
+/**
+ * Recursively configures writeErr on a command and all its subcommands.
+ */
+function configureOutputRecursively(cmd, writeErr) {
+    cmd.configureOutput({ writeErr });
+    for (const sub of cmd.commands) {
+        configureOutputRecursively(sub, writeErr);
+    }
+}
+/**
+ * Sets up cross-level "Did you mean?" suggestions for unknown commands.
+ *
+ * Disables Commander's built-in same-level suggestions and intercepts
+ * "unknown command" errors to search the entire command tree.
+ */
+export function setupUnknownCommandSuggestions(program) {
+    // Disable Commander's built-in suggestion on all commands
+    disableBuiltinSuggestions(program);
+    // Create a shared writeErr handler and apply it to all commands
+    const writeErr = createWriteErrHandler(program);
+    configureOutputRecursively(program, writeErr);
+}
+//# sourceMappingURL=did-you-mean.js.map

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

@@ -1,4 +1,4 @@
-export declare const WEBHOOK_SERVICES: readonly ["AZURE_DEVOPS", "BITBUCKET", "CYPRESS", "GITHUB", "GOOGLE_DOCS", "GOOGLE_LOGGING", "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,7 @@ export const WEBHOOK_SERVICES = [
     'CYPRESS',
     'GITHUB',
     'GOOGLE_DOCS',
+    'GOOGLE_COMPUTE',
     'GOOGLE_LOGGING',
     'JIRA',
     'LINEAR',

package/dist/lib/git.d.ts

@@ -6,6 +6,8 @@ export interface GitOptions {
     cwd?: string;
     /** Timeout in milliseconds (default: 30000 for most commands) */
     timeout?: number;
+    /** Extra environment variables to pass to the git subprocess */
+    env?: Record<string, string>;
 }
 /**
  * Result from a git command
@@ -57,4 +59,11 @@ export declare function runGit(args: string[], options?: GitOptions): Promise<Gi
  * Returns a user-friendly error message with the git output.
  */
 export declare function formatGitError(error: GitError): string;
+/**
+ * Install a pre-push hook that blocks direct git push.
+ *
+ * The hook allows pushes only when the GUILD_AGENT_SAVE env var is set,
+ * which guild agent save sets automatically.
+ */
+export declare function installPrePushHook(targetDir: string): Promise<void>;
 //# sourceMappingURL=git.d.ts.map

package/dist/lib/git.js

@@ -6,6 +6,8 @@
  * by preventing interactive prompts and providing clear error messages.
  */
 import { execa } from 'execa';
+import * as fs from 'fs/promises';
+import * as path from 'path';
 import { debug } from './errors.js';
 /**
  * Error thrown when a git command fails
@@ -71,7 +73,7 @@ const NETWORK_COMMANDS = ['clone', 'push', 'pull', 'fetch'];
  * }
  */
 export async function runGit(args, options = {}) {
-    const { cwd, timeout: customTimeout } = options;
+    const { cwd, timeout: customTimeout, env: extraEnv } = options;
     // Determine timeout based on command type
     const isNetworkCommand = args.length > 0 && NETWORK_COMMANDS.includes(args[0]);
     const timeout = customTimeout ?? (isNetworkCommand ? NETWORK_TIMEOUT : DEFAULT_TIMEOUT);
@@ -88,6 +90,7 @@ export async function runGit(args, options = {}) {
                 GIT_TERMINAL_PROMPT: '0',
                 // Prevent SSH from prompting for passwords/passphrases
                 GIT_SSH_COMMAND: 'ssh -o BatchMode=yes',
+                ...extraEnv,
             },
         });
     }
@@ -149,4 +152,24 @@ export function formatGitError(error) {
     }
     return lines.join('\n');
 }
+const PRE_PUSH_HOOK = `#!/bin/sh
+if [ "$GUILD_AGENT_SAVE" != "1" ]; then
+  echo "Please use \\\`guild agent save\\\` to push."
+  exit 1
+fi
+exit 0
+`;
+/**
+ * Install a pre-push hook that blocks direct git push.
+ *
+ * The hook allows pushes only when the GUILD_AGENT_SAVE env var is set,
+ * which guild agent save sets automatically.
+ */
+export async function installPrePushHook(targetDir) {
+    const hooksDir = path.join(targetDir, '.git', 'hooks');
+    await fs.mkdir(hooksDir, { recursive: true });
+    await fs.writeFile(path.join(hooksDir, 'pre-push'), PRE_PUSH_HOOK, {
+        mode: 0o755,
+    });
+}
 //# sourceMappingURL=git.js.map

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,13 +13,18 @@ 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 (pushes commits to Guild server)
+git add . && git commit -m "Description of changes"
+guild agent save
 
-# Save changes (commits and syncs to Guild server)
-guild agent save --message "Description of changes"
+# Or stage+commit+push in one step
+guild agent save -A --message "Description of changes"
 
 # Save and publish
 guild agent save --message "Description" --wait --publish
@@ -31,11 +41,9 @@ guild agent save --message "Description" --wait --publish
 ## NEVER Do These Things
 
 - ❌ Manually create `package.json`, `tsconfig.json`, or `guild.json`
-- ❌ Run `git push` directly (use `guild agent save`)
+- ❌ Run `git push` directly (use `guild agent save` — a pre-push hook blocks direct pushes)
 - ❌ 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 +53,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
@@ -87,15 +96,21 @@ guild agent grep "pattern" --published
 
 ### Saving Changes
 
+Git owns the working tree, Guild owns the remote. Use normal git commands to stage and commit, then `guild agent save` to push and create a version.
+
 ```bash
-# Save without publishing (creates draft)
-guild agent save --message "WIP: still testing"
+# Commit with git, then push via Guild (creates draft)
+git add . && git commit -m "WIP: still testing"
+guild agent save
+
+# Or stage+commit+push in one step
+guild agent save -A --message "WIP: still testing"
 
 # Save and wait for validation
 guild agent save --message "Fix bug" --wait
 
 # Save, validate, and publish
-guild agent save --message "Release v1.0" --wait --publish
+guild agent save -A --message "Release v1.0" --wait --publish
 ```
 
 ### Publishing
@@ -114,19 +129,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)
@@ -141,30 +159,21 @@ my-agent/
 
 ## Troubleshooting
 
-### "No changes to commit"
-
-You already committed. Just push:
+### "No changes to save"
 
-```bash
-git push origin main
-```
+Working tree is clean and there are no unpushed commits. Make a code change, commit it, 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

@@ -103,9 +103,10 @@ Press `Ctrl+C` to exit.
 ### 4. Save and publish
 
 ```bash
-guild agent save --message "First version" --wait --publish
+guild agent save -A --message "First version" --wait --publish
 ```
 
+- `-A` stages and commits all changes before pushing
 - `--wait` blocks until validation passes
 - `--publish` makes the agent available in the Guild catalog
 
@@ -288,16 +289,25 @@ guild agent chat "Hello"      # Send a single message
 
 ### 3. Save your work
 
+Commit with git, then push via Guild:
+
+```bash
+git add . && git commit -m "Add Slack notifications"
+guild agent save
+```
+
+Or stage+commit+push in one step:
+
 ```bash
-guild agent save --message "Add Slack notifications"
+guild agent save -A --message "Add Slack notifications"
 ```
 
-This commits your code and creates a new version in the Guild backend. Versions start as drafts.
+This pushes your commits and creates a new version in the Guild backend. Versions start as drafts.
 
 ### 4. Publish
 
 ```bash
-guild agent save --message "Ready to ship" --wait --publish
+guild agent save -A --message "Ready to ship" --wait --publish
 ```
 
 `--wait` blocks until validation passes. `--publish` makes the agent available in the catalog. You can also publish separately:
@@ -319,7 +329,7 @@ guild agent code               # View source of latest version
 - 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.
+- Use `git add` and `git commit` to manage your working tree. Use `guild agent save` to push and create versions. Don't use `git push` directly (a pre-push hook blocks it).
 - Don't edit `guild.json` — it's managed by the CLI.
 
 ## Other Commands
@@ -396,13 +406,9 @@ guild agent get
 guild agent get <agent-id>
 ```
 
-### "No changes to commit" after a failed save
-
-If a previous `guild agent save` committed locally but failed to push (e.g., network error), just run save again. It detects the unpushed commits and resumes:
+### "No changes to save"
 
-```bash
-guild agent save --message "Retry"
-```
+Working tree is clean and there are no unpushed commits. Make a code change, commit it, then run `guild agent save` again. If a previous save committed locally but failed to push (e.g., network error), just run `guild agent save` again — it detects the unpushed commits and resumes.
 
 ### Validation failures
 
@@ -412,8 +418,9 @@ After saving, if validation fails:
 # Check the latest version for errors
 guild agent versions --limit 1
 
-# Fix the issue and save again
-guild agent save --message "Fix validation error" --wait
+# Fix the issue, commit, and save again
+git add . && git commit -m "Fix validation error"
+guild agent save --wait
 ```
 
 ### Agent test not responding
@@ -421,7 +428,7 @@ guild agent save --message "Fix validation error" --wait
 If `guild agent test` hangs or produces no output:
 
 1. Check your agent code compiles: look for TypeScript errors in `agent.ts`
-2. Make sure you've saved at least once: `guild agent save --message "initial"`
+2. Make sure you've saved at least once: `guild agent save -A --message "initial"`
 3. Try a single message instead: `guild agent chat "hello"`
 
 ## Next Steps

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
@@ -53,18 +53,24 @@ guild agent clone owner/agent-name
 
 ### Syncing and Saving
 
+Git owns the working tree, Guild owns the remote. Use normal git commands to stage and commit, then `guild agent save` to push and create a version.
+
 ```bash
 # Pull remote changes (e.g., edits from other collaborators)
 guild agent pull
 
-# Save without publishing (creates draft)
-guild agent save --message "Description of changes"
+# Commit with git, then push via Guild (creates draft)
+git add . && git commit -m "Description of changes"
+guild agent save
+
+# Or stage+commit+push in one step
+guild agent save -A --message "Description of changes"
 
 # Save and wait for validation
 guild agent save --message "Fix bug" --wait
 
 # Save, validate, and publish
-guild agent save --message "Release v1.0" --wait --publish
+guild agent save -A --message "Release v1.0" --wait --publish
 ```
 
 ### Testing
@@ -80,18 +86,41 @@ 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, investigating — goes through Guild CLI.**
 
-**All agent work — creating, saving, testing, debugging — goes through Guild CLI.**
+### For Creating and Modifying
 
 - ✅ `guild agent create`, `guild agent init`, `guild agent clone`
-- ✅ `guild agent save --message "description"`
+- ✅ `git add`, `git commit` (manage your own working tree)
+- ✅ `guild agent save` (push commits and create a version)
+- ✅ `guild agent save -A --message "desc"` (stage+commit+push in one step)
 - ✅ `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 push` directly (a pre-push hook blocks this — use `guild agent save`)
+- ❌ NEVER use `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 +147,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 +172,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 +204,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
@@ -525,7 +563,7 @@ await task.tools.slack_chat_post_message({
 
 ### 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:
 
@@ -630,7 +668,7 @@ export default agent({ run: async (input, task) => { ... } })
 }
 ```
 
-**Important:**
+**CRITICAL:**
 
 - Do NOT add `@guildai/agents-sdk`, `@guildai-services/*`, or `zod` to dependencies. The runtime provides them.
 - 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.
@@ -658,10 +696,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
 
@@ -672,9 +710,10 @@ 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 save --message "description"           # Save changes
-guild agent save --message "v1.0" --wait --publish # Save + validate + publish
 guild agent pull                                   # Pull remote changes
+guild agent save                                   # Push commits and create a draft version
+guild agent save -A --message "description"        # Stage+commit+push in one step
+guild agent save --message "v1.0" --wait --publish # Save + validate + publish
 guild agent test                                   # Interactive test
 guild agent test --ephemeral                       # Ephemeral test
 guild agent chat "Hello"                           # Test with input
@@ -689,13 +728,22 @@ 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
 
-### "No changes to commit"
+### "No changes to save"
 
-All changes are already committed. Make a code change first, then run `guild agent save` again.
+Working tree is clean and there are no unpushed commits. Make a code change, commit it, then run `guild agent save` again.
 
 ### "guild.json not found"
 
@@ -719,5 +767,5 @@ If `guild.json` is tracked in git (it shouldn't be):
 ```bash
 echo "guild.json" >> .gitignore
 git rm --cached guild.json
-guild agent save --message "fix: Add guild.json to gitignore"
+guild agent save -A --message "fix: Add guild.json to gitignore"
 ```

package/package.json

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