@guildai/cli 0.4.0 → 0.5.1

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/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 = [
     {
@@ -311,6 +311,8 @@ 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
@@ -318,13 +320,15 @@ export function createAgentInitCommand() {
             if (options.directory) {
                 format.detail(`1. cd ${targetDir}`);
                 format.detail('2. Edit agent.ts to implement your agent logic');
-                format.detail(`3. Run 'guild agent save --message "Initial implementation"'`);
-                format.detail(`4. Run 'guild agent test' to test your agent`);
+                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. Run 'guild agent save --message "Initial implementation"'`);
-                format.detail(`3. Run 'guild agent test' to test your agent`);
+                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) {

package/dist/commands/agent/owners.js

@@ -13,7 +13,7 @@ export function createAgentOwnersCommand() {
             const client = new GuildAPIClient();
             const [me, orgs, globalConfig] = await Promise.all([
                 client.get('/me'),
-                client.get('/me/organizations'),
+                client.fetchAll('/me/organizations'),
                 loadGlobalConfig(),
             ]);
             const defaultOwnerId = globalConfig?.default_owner;
@@ -24,7 +24,7 @@ export function createAgentOwnersCommand() {
                     type: 'user',
                     is_default: defaultOwnerId === me.id,
                 },
-                ...orgs.items.map((org) => ({
+                ...orgs.map((org) => ({
                     id: org.id,
                     name: org.name,
                     type: 'organization',

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/config/set.js

@@ -56,8 +56,8 @@ async function resolveOwnerName(ownerId) {
         if (me.id === ownerId) {
             return me.name;
         }
-        const orgs = await client.get('/me/organizations');
-        const org = orgs.items.find((o) => o.id === ownerId);
+        const orgs = await client.fetchAll('/me/organizations');
+        const org = orgs.find((o) => o.id === ownerId);
         return org?.name;
     }
     catch (error) {

package/dist/commands/trigger/create.js

@@ -50,8 +50,8 @@ export function createTriggerCreateCommand() {
             }
             const client = new GuildAPIClient();
             // Find workspace_agent_id from agent identifier
-            const workspaceAgentsResponse = await client.get(`/workspaces/${workspaceId}/workspace_agents`);
-            const workspaceAgent = workspaceAgentsResponse.items.find((wa) => wa.agent.full_name === options.agent ||
+            const allWorkspaceAgents = await client.fetchAll(`/workspaces/${workspaceId}/workspace_agents`);
+            const workspaceAgent = allWorkspaceAgents.find((wa) => wa.agent.full_name === options.agent ||
                 wa.agent.name === options.agent ||
                 wa.agent.id === options.agent);
             if (!workspaceAgent) {

package/dist/commands/workspace/agent/remove.js

@@ -30,10 +30,10 @@ export function createWorkspaceAgentRemoveCommand() {
                 }
                 workspaceId = resolved.workspaceId;
             }
-            // List workspace agents to find the one to remove
-            const response = await client.get(`/workspaces/${workspaceId}/workspace_agents`);
+            // List all workspace agents to find the one to remove
+            const allWorkspaceAgents = await client.fetchAll(`/workspaces/${workspaceId}/workspace_agents`);
             // Find the agent by identifier (match full_name, name, agent id, or workspace_agent id)
-            const workspaceAgent = response.items.find((wa) => wa.id === agentIdentifier ||
+            const workspaceAgent = allWorkspaceAgents.find((wa) => wa.id === agentIdentifier ||
                 wa.agent.full_name === agentIdentifier ||
                 wa.agent.name === agentIdentifier ||
                 wa.agent.id === agentIdentifier);

package/dist/lib/api-client.d.ts

@@ -50,5 +50,13 @@ export declare class GuildAPIClient {
      * Make a DELETE request
      */
     delete<T = unknown>(endpoint: string, config?: AxiosRequestConfig): Promise<T>;
+    /**
+     * Fetch all items from a paginated endpoint by paging through results.
+     * Use for display commands or ID-based lookups where you need the complete list.
+     *
+     * @param endpoint - API endpoint path (may include query params)
+     * @returns Flat array of all items across all pages
+     */
+    fetchAll<T>(endpoint: string): Promise<T[]>;
 }
 //# sourceMappingURL=api-client.d.ts.map

package/dist/lib/api-client.js

@@ -121,5 +121,27 @@ export class GuildAPIClient {
     async delete(endpoint, config) {
         return this.request('DELETE', endpoint, config);
     }
+    /**
+     * Fetch all items from a paginated endpoint by paging through results.
+     * Use for display commands or ID-based lookups where you need the complete list.
+     *
+     * @param endpoint - API endpoint path (may include query params)
+     * @returns Flat array of all items across all pages
+     */
+    async fetchAll(endpoint) {
+        const PAGE_SIZE = 100;
+        const allItems = [];
+        let offset = 0;
+        while (true) {
+            const separator = endpoint.includes('?') ? '&' : '?';
+            const url = `${endpoint}${separator}limit=${PAGE_SIZE}&offset=${offset}`;
+            const response = await this.get(url);
+            allItems.push(...response.items);
+            offset += response.pagination.limit;
+            if (!response.pagination.has_more)
+                break;
+        }
+        return allItems;
+    }
 }
 //# sourceMappingURL=api-client.js.map

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

@@ -170,7 +170,7 @@ export type AgentListResponse = PaginatedResponse<Agent>;
 export type WorkspaceListResponse = PaginatedResponse<Workspace>;
 export type VersionListResponse = PaginatedResponse<AgentVersion>;
 export type ContextListResponse = PaginatedResponse<Context>;
-export type WorkspaceAgentListResponse = CountedResponse<WorkspaceAgent>;
+export type WorkspaceAgentListResponse = PaginatedResponse<WorkspaceAgent>;
 /**
  * Response from creating a new agent.
  */

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/owner-helpers.js

@@ -27,8 +27,8 @@ export async function resolveOwnerId(options) {
         if (me.id === ownerFlag) {
             return { id: me.id, name: me.name, type: 'user' };
         }
-        const orgs = await client.get('/me/organizations');
-        const org = orgs.items.find((o) => o.id === ownerFlag);
+        const orgs = await client.fetchAll('/me/organizations');
+        const org = orgs.find((o) => o.id === ownerFlag);
         if (org) {
             return { id: org.id, name: org.name, type: 'organization' };
         }
@@ -43,8 +43,8 @@ export async function resolveOwnerId(options) {
         if (me.id === envOwnerId) {
             return { id: me.id, name: me.name, type: 'user' };
         }
-        const orgs = await client.get('/me/organizations');
-        const org = orgs.items.find((o) => o.id === envOwnerId);
+        const orgs = await client.fetchAll('/me/organizations');
+        const org = orgs.find((o) => o.id === envOwnerId);
         if (org) {
             return { id: org.id, name: org.name, type: 'organization' };
         }
@@ -63,9 +63,9 @@ export async function resolveOwnerId(options) {
     }
     // Priority 4: Fetch user + orgs
     const me = await client.get('/me');
-    const orgs = await client.get('/me/organizations');
+    const orgs = await client.fetchAll('/me/organizations');
     // No orgs → use current user
-    if (orgs.items.length === 0) {
+    if (orgs.length === 0) {
         debug('No organizations found, using current user as owner');
         return { id: me.id, name: me.name, type: 'user' };
     }
@@ -80,7 +80,7 @@ export async function resolveOwnerId(options) {
             name: `${me.name} (personal)`,
             value: { id: me.id, name: me.name, type: 'user' },
         },
-        ...orgs.items.map((org) => ({
+        ...orgs.map((org) => ({
             name: org.name,
             value: { id: org.id, name: org.name, type: 'organization' },
         })),

package/docs/CLI_WORKFLOW.md

@@ -19,8 +19,12 @@ guild agent create my-agent --template LLM
 guild agent clone guildai/dev-assistant
 cd dev-assistant
 
-# Save changes (commits and syncs to Guild server)
-guild agent save --message "Description of changes"
+# Save changes (pushes commits to Guild server)
+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 publish
 guild agent save --message "Description" --wait --publish
@@ -37,9 +41,8 @@ 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)
 
 ## Common Commands
@@ -93,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
@@ -150,9 +159,9 @@ my-agent/
 
 ## 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"
 

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

@@ -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
@@ -87,10 +93,13 @@ guild agent chat "Hello, can you help me?"
 ### 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`
-- ❌ NEVER use `git commit`, `git push`, `gh repo` 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
@@ -702,7 +711,8 @@ guild agent create <name> --template LLM           # Create with specific templa
 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                                   # 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
@@ -731,9 +741,9 @@ GUILD_OWNER_ID=<id> guild agent init --name my-agent  # Override owner for agent
 
 ## 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"
 
@@ -757,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.4.0",
+  "version": "0.5.1",
   "description": "Guild.ai CLI - Build, test, and deploy AI agents",
   "type": "module",
   "main": "dist/index.js",