@myvillage/cli 1.10.1 → 1.17.0

package/src/commands/agent-grant.js

@@ -0,0 +1,131 @@
+import chalk from 'chalk';
+import { isAuthenticated } from '../utils/auth.js';
+import { readAgentConfig } from '../utils/local-agent.js';
+import { getPlatformClient } from '../utils/api.js';
+
+const VALID_PROVIDERS = ['google', 'microsoft', 'zoom'];
+
+function ensureAuthed() {
+  if (!isAuthenticated()) {
+    console.log(chalk.red("  ✗ Authentication required. Run 'myvillage login' first."));
+    return false;
+  }
+  return true;
+}
+
+function resolveAgentId(name) {
+  const config = readAgentConfig(name);
+  if (!config) {
+    console.log(chalk.red(`  ✗ Local agent "${name}" not found`));
+    return null;
+  }
+  const agentId = config?.man?.agent_id;
+  if (!agentId) {
+    console.log(
+      chalk.red(
+        `  ✗ Agent "${name}" has not been registered on the platform yet. ` +
+          `Run 'myvillage agent start ${name}' once to register it.`,
+      ),
+    );
+    return null;
+  }
+  return agentId;
+}
+
+function normalizeProvider(provider) {
+  const lc = (provider || '').toLowerCase();
+  if (!VALID_PROVIDERS.includes(lc)) {
+    console.log(
+      chalk.red(`  ✗ Invalid provider "${provider}". Must be one of: ${VALID_PROVIDERS.join(', ')}`),
+    );
+    return null;
+  }
+  return lc.toUpperCase();
+}
+
+function printApiError(err, fallback) {
+  const status = err?.response?.status;
+  const data = err?.response?.data;
+  const code = data?.code ? ` (${data.code})` : '';
+  const message = data?.error || err?.message || fallback;
+  console.log(chalk.red(`  ✗ ${message}${code}${status ? ` [HTTP ${status}]` : ''}`));
+}
+
+// ── List grants ────────────────────────────────────────────
+
+export async function agentGrantsCommand(name) {
+  if (!ensureAuthed()) return;
+  const agentId = resolveAgentId(name);
+  if (!agentId) return;
+
+  const client = getPlatformClient();
+  try {
+    const response = await client.get(`/agents/${agentId}/credential-grants`);
+    const grants = response.data?.data ?? [];
+    if (grants.length === 0) {
+      console.log(chalk.dim(`  No active credential grants for agent "${name}".`));
+      console.log(chalk.dim(`  Grant one with: myvillage agent grant ${name} <google|microsoft|zoom>`));
+      return;
+    }
+    console.log(chalk.bold(`Active credential grants for "${name}" (${agentId}):\n`));
+    for (const g of grants) {
+      const granted = new Date(g.grantedAt).toISOString().slice(0, 10);
+      console.log(`  - ${chalk.cyan(g.provider)}  granted ${granted}`);
+    }
+  } catch (err) {
+    printApiError(err, 'Failed to list grants');
+  }
+}
+
+// ── Grant a provider ───────────────────────────────────────
+
+export async function agentGrantCommand(name, provider) {
+  if (!ensureAuthed()) return;
+  const agentId = resolveAgentId(name);
+  if (!agentId) return;
+  const upperProvider = normalizeProvider(provider);
+  if (!upperProvider) return;
+
+  const client = getPlatformClient();
+  try {
+    await client.post(`/agents/${agentId}/credential-grants`, { provider: upperProvider });
+    console.log(
+      chalk.green(`  ✓ Granted ${upperProvider} to agent "${name}".`) +
+        chalk.dim(`\n    The agent can now use ${upperProvider}-backed tools (e.g. gmail_send).`),
+    );
+  } catch (err) {
+    if (err?.response?.status === 404 && err?.response?.data?.code === 'CREDENTIAL_NOT_CONNECTED') {
+      console.log(
+        chalk.yellow(
+          `  ⚠ You haven't connected ${upperProvider} yet. ` +
+            `Connect it from the mobile app or web portal, then re-run this command.`,
+        ),
+      );
+      return;
+    }
+    printApiError(err, 'Failed to grant provider');
+  }
+}
+
+// ── Revoke a provider ──────────────────────────────────────
+
+export async function agentRevokeCommand(name, provider) {
+  if (!ensureAuthed()) return;
+  const agentId = resolveAgentId(name);
+  if (!agentId) return;
+  const upperProvider = normalizeProvider(provider);
+  if (!upperProvider) return;
+
+  const client = getPlatformClient();
+  try {
+    await client.delete(`/agents/${agentId}/credential-grants/${upperProvider}`);
+    console.log(
+      chalk.green(`  ✓ Revoked ${upperProvider} from agent "${name}".`) +
+        chalk.dim(
+          `\n    Tools using ${upperProvider} will fail within ~60 seconds (cache TTL).`,
+        ),
+    );
+  } catch (err) {
+    printApiError(err, 'Failed to revoke provider');
+  }
+}

package/src/commands/agent-local.js

@@ -12,6 +12,18 @@ import {
   agentJoinCommunity as apiAgentJoinCommunity,
   listCommunities,
   getAgentActivity,
+  listMyUnlinkedAgentProfiles,
+  createVillageAgent as apiCreateVillageAgent,
+  listAgentTasks,
+  assignAgentTask,
+  claimAgentTask,
+  completeAgentTask,
+  upsertAgentMemory,
+  listAgentMemory,
+  getAgentMemoryEntry,
+  deleteAgentMemoryEntry,
+  listKnowledgeFiltered,
+  shareKnowledgeAsAgent,
 } from '../utils/api.js';
 import {
   getAgentDir,
@@ -39,6 +51,36 @@ export async function agentCreateLocalCommand() {
   }
 
   try {
+    // Optional: let the developer reuse an existing AgentProfile (network identity)
+    // they already own and haven't yet linked to a VillageAgent.
+    let preselectedProfile = null;
+    try {
+      const result = await listMyUnlinkedAgentProfiles();
+      const profiles = Array.isArray(result?.data) ? result.data : [];
+      if (profiles.length > 0) {
+        const { useExisting } = await inquirer.prompt([{
+          type: 'confirm',
+          name: 'useExisting',
+          message: `You have ${profiles.length} unlinked network identity(ies). Reuse one for this agent?`,
+          default: false,
+        }]);
+        if (useExisting) {
+          const { profileId } = await inquirer.prompt([{
+            type: 'list',
+            name: 'profileId',
+            message: 'Pick a network identity:',
+            choices: profiles.map(p => ({
+              name: `@${p.handle} — ${p.displayName}`,
+              value: p.id,
+            })),
+          }]);
+          preselectedProfile = profiles.find(p => p.id === profileId) || null;
+        }
+      }
+    } catch {
+      // listMyUnlinkedAgentProfiles can fail if the user has no villager — that's fine, just skip
+    }
+
     const answers = await inquirer.prompt([
       {
         type: 'input',
@@ -151,6 +193,16 @@ export async function agentCreateLocalCommand() {
       model: answers.model,
     });
 
+    // If the developer picked an existing AgentProfile, pre-fill man.agent_id
+    // so `start` skips the lazy-create step and links the VillageAgent shim to it instead.
+    if (preselectedProfile?.id) {
+      const cfg = readAgentConfig(answers.name);
+      cfg.man = cfg.man || {};
+      cfg.man.agent_id = preselectedProfile.id;
+      cfg.man.handle = preselectedProfile.handle;
+      writeAgentConfig(answers.name, cfg);
+    }
+
     spinner.succeed('Agent scaffolded!');
 
     console.log(brand.green(`  \u2713 Agent created at ~/.myvillage/agents/${answers.name}/\n`));
@@ -231,7 +283,7 @@ export async function agentStartCommand(name) {
     }
   }
 
-  // Register on MAN if first start
+  // Register on MAN if first start (skipped when `create` preselected an existing AgentProfile)
   if (!agentConfig.man?.agent_id) {
     const regSpinner = villageSpinner('Registering agent on the MAN network...').start();
     try {
@@ -251,6 +303,32 @@ export async function agentStartCommand(name) {
 
       regSpinner.succeed(`Registered as @${agent.handle || agentConfig.name} on MAN.`);
 
+      // Also create the VillageAgent shim so this agent has a task queue
+      // and shared autonomous-engagement controls. This is what `loop.js`
+      // polls against. Failure is non-fatal — the agent can still run locally.
+      try {
+        const shimResult = await apiCreateVillageAgent({
+          name: agentConfig.display_name || agentConfig.name,
+          title: 'Developer Agent',
+          description: agentConfig.description || '',
+          avatar: agent.avatarUrl || '',
+          archetypes: [],
+          greeting: '',
+          starterPrompts: [],
+          associatedVillages: [],
+          specialInstructions: null,
+          agentProfileId: agent.id,
+        });
+        const shim = shimResult.agent || shimResult;
+        if (shim?.id) {
+          agentConfig.man.village_agent_id = shim.id;
+          writeAgentConfig(name, agentConfig);
+        }
+      } catch (shimErr) {
+        const shimMsg = shimErr.response?.data?.error || shimErr.message;
+        console.log(brand.teal(`  Note: task queue not available (${shimMsg}). Agent will run in feed-monitoring mode.`));
+      }
+
       // Auto-join default communities so the agent can post
       try {
         const commResult = await listCommunities({ pageSize: 50 });
@@ -284,6 +362,34 @@ export async function agentStartCommand(name) {
     }
   }
 
+  // If we have an AgentProfile but no VillageAgent shim yet (e.g., the developer
+  // preselected an existing AgentProfile via `create`), create it now.
+  if (agentConfig.man?.agent_id && !agentConfig.man?.village_agent_id) {
+    try {
+      const shimResult = await apiCreateVillageAgent({
+        name: agentConfig.display_name || agentConfig.name,
+        title: 'Developer Agent',
+        description: agentConfig.description || '',
+        avatar: '',
+        archetypes: [],
+        greeting: '',
+        starterPrompts: [],
+        associatedVillages: [],
+        specialInstructions: null,
+        agentProfileId: agentConfig.man.agent_id,
+      });
+      const shim = shimResult.agent || shimResult;
+      if (shim?.id) {
+        agentConfig.man.village_agent_id = shim.id;
+        writeAgentConfig(name, agentConfig);
+        console.log(brand.teal(`  Task queue ready: ${shim.id}`));
+      }
+    } catch (shimErr) {
+      const shimMsg = shimErr.response?.data?.error || shimErr.message;
+      console.log(brand.teal(`  Note: task queue not available (${shimMsg}).`));
+    }
+  }
+
   // Migrate tools.yaml: replace man-feed with myvillage MCP server
   const toolsConfig = readToolsYaml(name);
   if (toolsConfig.servers?.['man-feed'] && !toolsConfig.servers?.['myvillage']) {
@@ -300,6 +406,9 @@ export async function agentStartCommand(name) {
   if (agentConfig.man?.agent_id) {
     process.env.MYVILLAGE_AGENT_ID = agentConfig.man.agent_id;
   }
+  if (agentConfig.man?.village_agent_id) {
+    process.env.MYVILLAGE_VILLAGE_AGENT_ID = agentConfig.man.village_agent_id;
+  }
 
   // Fork the daemon process
   const spinner = villageSpinner(`Starting agent "${name}"...`).start();
@@ -670,3 +779,247 @@ export async function agentDeleteLocalCommand(name) {
     console.log(chalk.red(`  \u2717 Failed to delete agent: ${err.message}\n`));
   }
 }
+
+// \u2500\u2500 Tasks \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+
+function resolveVillageAgentId(name) {
+  if (!agentExists(name)) {
+    console.log(chalk.red(`  \u2717 Agent "${name}" not found.\n`));
+    return null;
+  }
+  const config = readAgentConfig(name);
+  const id = config?.man?.village_agent_id;
+  if (!id) {
+    console.log(chalk.yellow(`  Agent "${name}" has no task queue yet \u2014 start it once so the VillageAgent shim is created.\n`));
+    return null;
+  }
+  return id;
+}
+
+export async function agentTaskListCommand(name, options = {}) {
+  if (!isAuthenticated()) {
+    console.log(chalk.red('  \u2717 Authentication required. Run \'myvillage login\' first.'));
+    return;
+  }
+  const villageAgentId = resolveVillageAgentId(name);
+  if (!villageAgentId) return;
+
+  try {
+    const result = await listAgentTasks(villageAgentId, {
+      status: options.status,
+      limit: options.limit ? Number(options.limit) : undefined,
+    });
+    const tasks = result.tasks || [];
+    if (tasks.length === 0) {
+      console.log(brand.teal(`  No tasks${options.status ? ` with status ${options.status}` : ''}.\n`));
+      return;
+    }
+    console.log(brand.teal(`  ${tasks.length} task(s):\n`));
+    for (const t of tasks) {
+      console.log(`  ${brand.gold(t.id)}  ${chalk.bold(t.taskType)}  ${t.status}  priority=${t.priority}`);
+      if (t.instruction) console.log(`    ${chalk.dim(t.instruction)}`);
+    }
+    console.log('');
+  } catch (err) {
+    const msg = err.response?.data?.error || err.message;
+    console.log(chalk.red(`  \u2717 Failed to list tasks: ${msg}\n`));
+  }
+}
+
+export async function agentTaskAssignCommand(name, options = {}) {
+  if (!isAuthenticated()) {
+    console.log(chalk.red('  \u2717 Authentication required. Run \'myvillage login\' first.'));
+    return;
+  }
+  const villageAgentId = resolveVillageAgentId(name);
+  if (!villageAgentId) return;
+
+  if (!options.type) {
+    console.log(chalk.red('  \u2717 --type is required (e.g., CLIENT_TASK, GENERATE_POST, SHARE_KNOWLEDGE)\n'));
+    return;
+  }
+
+  let inputObj = {};
+  if (options.input) {
+    try { inputObj = JSON.parse(options.input); }
+    catch { console.log(chalk.red('  \u2717 --input must be valid JSON\n')); return; }
+  }
+
+  try {
+    const result = await assignAgentTask(villageAgentId, {
+      taskType: options.type,
+      instruction: options.instruction,
+      input: inputObj,
+      priority: options.priority ? Number(options.priority) : 5,
+    });
+    const task = result.task || result;
+    console.log(brand.green(`  \u2713 Task ${task.id} assigned (${task.taskType}, status=${task.status}).\n`));
+  } catch (err) {
+    const msg = err.response?.data?.error || err.message;
+    console.log(chalk.red(`  \u2717 Failed to assign task: ${msg}\n`));
+  }
+}
+
+// Exported for use by the runtime loop, not registered as a CLI command directly.
+export async function pollAndClaimNextTask(villageAgentId) {
+  const result = await listAgentTasks(villageAgentId, { status: 'PENDING', limit: 5 });
+  const pending = result.tasks || [];
+  if (pending.length === 0) return null;
+  for (const task of pending) {
+    try {
+      const claim = await claimAgentTask(villageAgentId, task.id);
+      return claim.data || claim;
+    } catch {
+      // Race lost \u2014 try the next task
+    }
+  }
+  return null;
+}
+
+export async function reportTaskOutcome(villageAgentId, taskId, outcome) {
+  return completeAgentTask(villageAgentId, taskId, outcome);
+}
+
+// ── Memory (short-term KV) and Recall (long-term searchable) ────
+
+function resolveAgentProfileId(name) {
+  if (!agentExists(name)) {
+    console.log(chalk.red(`  ✗ Agent "${name}" not found.\n`));
+    return null;
+  }
+  const config = readAgentConfig(name);
+  const id = config?.man?.agent_id;
+  if (!id) {
+    console.log(chalk.yellow(`  Agent "${name}" hasn't registered on the network yet — start it once so an AgentProfile is created.\n`));
+    return null;
+  }
+  return id;
+}
+
+export async function agentMemoryCommand(name, action, ...args) {
+  if (!isAuthenticated()) {
+    console.log(chalk.red('  ✗ Authentication required. Run \'myvillage login\' first.'));
+    return;
+  }
+  const agentProfileId = resolveAgentProfileId(name);
+  if (!agentProfileId) return;
+
+  try {
+    if (action === 'list') {
+      const result = await listAgentMemory(agentProfileId);
+      const items = result.data || result.memories || result;
+      if (!Array.isArray(items) || items.length === 0) {
+        console.log(brand.teal('  No memory entries.\n'));
+        return;
+      }
+      console.log(brand.teal(`  ${items.length} memory entr${items.length === 1 ? 'y' : 'ies'}:\n`));
+      for (const m of items) {
+        console.log(`  ${chalk.bold(m.key)}${m.category ? chalk.dim(` [${m.category}]`) : ''}`);
+        const v = typeof m.value === 'string' ? m.value : JSON.stringify(m.value);
+        console.log(`    ${chalk.dim(v.slice(0, 200))}`);
+      }
+      console.log('');
+    } else if (action === 'get') {
+      const key = args[0];
+      if (!key) {
+        console.log(chalk.red('  ✗ Usage: myvillage agent memory <name> get <key>\n'));
+        return;
+      }
+      const result = await getAgentMemoryEntry(agentProfileId, key);
+      console.log(JSON.stringify(result.data || result, null, 2));
+    } else if (action === 'set') {
+      const [key, ...rest] = args;
+      const value = rest.join(' ');
+      if (!key || !value) {
+        console.log(chalk.red('  ✗ Usage: myvillage agent memory <name> set <key> <value>\n'));
+        return;
+      }
+      // Try JSON first so { "foo": 1 } stays structured; fall back to string.
+      let parsed;
+      try { parsed = JSON.parse(value); } catch { parsed = value; }
+      await upsertAgentMemory(agentProfileId, { key, value: parsed });
+      console.log(brand.green(`  ✓ ${key} set.\n`));
+    } else if (action === 'delete') {
+      const key = args[0];
+      if (!key) {
+        console.log(chalk.red('  ✗ Usage: myvillage agent memory <name> delete <key>\n'));
+        return;
+      }
+      await deleteAgentMemoryEntry(agentProfileId, key);
+      console.log(brand.green(`  ✓ ${key} deleted.\n`));
+    } else {
+      console.log(chalk.red(`  ✗ Unknown memory action: ${action}. Use list|get|set|delete.\n`));
+    }
+  } catch (err) {
+    const msg = err.response?.data?.error || err.message;
+    console.log(chalk.red(`  ✗ Memory ${action} failed: ${msg}\n`));
+  }
+}
+
+export async function agentRecallCommand(name, query, options = {}) {
+  if (!isAuthenticated()) {
+    console.log(chalk.red('  ✗ Authentication required. Run \'myvillage login\' first.'));
+    return;
+  }
+  const agentProfileId = resolveAgentProfileId(name);
+  if (!agentProfileId) return;
+  if (!query) {
+    console.log(chalk.red('  ✗ Usage: myvillage agent recall <name> <query>\n'));
+    return;
+  }
+
+  try {
+    const result = await listKnowledgeFiltered({
+      createdByAgentId: agentProfileId,
+      search: query,
+      limit: options.limit ? Number(options.limit) : 10,
+    });
+    const items = result.data || result.knowledge || result.knowledgeSubmissions || [];
+    if (!Array.isArray(items) || items.length === 0) {
+      console.log(brand.teal(`  No memories matched "${query}".\n`));
+      return;
+    }
+    console.log(brand.teal(`  ${items.length} matching memor${items.length === 1 ? 'y' : 'ies'}:\n`));
+    for (const k of items) {
+      const text = k.originalText || k.text || '';
+      console.log(`  ${brand.gold(k.id)}  ${chalk.dim(new Date(k.createdAt).toLocaleString())}`);
+      console.log(`    ${text.slice(0, 280)}${text.length > 280 ? '…' : ''}`);
+    }
+    console.log('');
+  } catch (err) {
+    const msg = err.response?.data?.error || err.message;
+    console.log(chalk.red(`  ✗ Recall failed: ${msg}\n`));
+  }
+}
+
+export async function agentRememberCommand(name, text, options = {}) {
+  if (!isAuthenticated()) {
+    console.log(chalk.red('  ✗ Authentication required. Run \'myvillage login\' first.'));
+    return;
+  }
+  const agentProfileId = resolveAgentProfileId(name);
+  if (!agentProfileId) return;
+  if (!text) {
+    console.log(chalk.red('  ✗ Usage: myvillage agent remember <name> "<text to remember>"\n'));
+    return;
+  }
+
+  const themes = options.themes
+    ? options.themes.split(',').map(t => t.trim()).filter(Boolean)
+    : [];
+
+  try {
+    const result = await shareKnowledgeAsAgent({
+      original_text: text,
+      summary: options.summary || null,
+      themes,
+      sharing_option: options.sharing || 'PRIVATE',
+      agent_profile_id: agentProfileId,
+    });
+    const k = result.knowledge || result.data || result;
+    console.log(brand.green(`  ✓ Remembered as ${k.id || 'knowledge entry'}.\n`));
+  } catch (err) {
+    const msg = err.response?.data?.error || err.message;
+    console.log(chalk.red(`  ✗ Remember failed: ${msg}\n`));
+  }
+}

package/src/commands/create-app.js

@@ -7,7 +7,7 @@ import inquirer from 'inquirer';
 import { isAuthenticated } from '../utils/auth.js';
 import { createGameCommand } from './create-game.js';
 import { createAgenticAppProject } from '../utils/agentic-templates.js';
-import { registerOAuthClient } from '../utils/api.js';
+import { registerOAuthClient, registerClientAgent, listMyAgents } from '../utils/api.js';
 
 export async function createCommand() {
   // Check authentication
@@ -160,6 +160,65 @@ async function applicationFlow() {
     }
   }
 
+  // Client agent automation (optional)
+  let agentConfig = null;
+  if (hasOAuth && oauthCredentials) {
+    const { enableAgent } = await inquirer.prompt([{
+      type: 'confirm',
+      name: 'enableAgent',
+      message: 'Enable platform agent automation?',
+      default: false,
+    }]);
+
+    if (enableAgent) {
+      try {
+        const agentResult = await listMyAgents();
+        const agents = agentResult.data || agentResult;
+
+        if (Array.isArray(agents) && agents.length > 0) {
+          const { selectedAgent, workflowTypes } = await inquirer.prompt([
+            {
+              type: 'list',
+              name: 'selectedAgent',
+              message: 'Which agent should automate this app?',
+              choices: agents.map(a => ({ name: `@${a.handle} — ${a.displayName || a.handle}`, value: a })),
+            },
+            {
+              type: 'checkbox',
+              name: 'workflowTypes',
+              message: 'Select workflow types:',
+              choices: [
+                { name: 'Submission Processor', value: 'SUBMISSION_PROCESSOR', checked: true },
+                { name: 'Digest Generator', value: 'DIGEST_GENERATOR' },
+                { name: 'Member Matcher', value: 'MEMBER_MATCHER' },
+                { name: 'Stale Data Detector', value: 'STALE_DATA_DETECTOR' },
+              ],
+              validate: input => input.length > 0 ? true : 'Select at least one workflow type.',
+            },
+          ]);
+
+          const agentSpinner = villageSpinner('Registering client agent...').start();
+          const regResult = await registerClientAgent({
+            villageAgentId: selectedAgent.villageAgent?.id || selectedAgent.villageAgentId || selectedAgent.id,
+            clientId: slug,
+            clientName: basics.name,
+            baseUrl: 'http://localhost:3000',
+            workflowType: workflowTypes[0],
+          });
+          agentConfig = { apiKey: regResult.apiKey, clientId: slug };
+          agentSpinner.succeed('Client agent registered!');
+          console.log(chalk.yellow.bold('  ⚠  Save your API key — it won\'t be shown again!'));
+          console.log(brand.teal(`  API Key: ${brand.gold(regResult.apiKey)}`));
+        } else {
+          console.log(brand.teal('  No agents found. Create one first with: myvillage agent create'));
+        }
+      } catch (err) {
+        console.log(chalk.yellow(`  ⚠ Failed to register client agent: ${err.response?.data?.error || err.message}`));
+        console.log(chalk.dim('  You can register later with: myvillage agent register-client'));
+      }
+    }
+  }
+
   // Scaffold project (always Next.js)
   const spinner = villageSpinner('Creating application...').start();
   try {
@@ -172,6 +231,7 @@ async function applicationFlow() {
       includeRestApi,
       mcpToolGroups,
       oauthCredentials,
+      agentConfig,
     });
 
     spinner.text = 'Installing dependencies...';

package/src/commands/game.js

@@ -665,6 +665,72 @@ export async function gameSubmitCommand() {
   }
 }
 
+// ── game draft (return to draft) ────────────────────
+
+export async function gameDraftCommand() {
+  if (!isAuthenticated()) {
+    console.log(chalk.red('  ✗ Authentication required. Run \'myvillage login\' first.'));
+    return;
+  }
+
+  const gameId = getGameId();
+  if (!gameId) return;
+
+  const checkSpinner = villageSpinner('Checking game status...').start();
+  let game;
+  try {
+    const result = await getGameDetail(gameId);
+    game = result.game;
+    checkSpinner.stop();
+  } catch (err) {
+    const message = err.response?.data?.error || err.message;
+    checkSpinner.fail(`Failed to fetch game: ${message}`);
+    return;
+  }
+
+  if (game.status === 'DRAFT') {
+    console.log(brand.teal(`\n  "${game.title}" is already in DRAFT status.\n`));
+    return;
+  }
+
+  if (game.status === 'PUBLISHED') {
+    console.log(chalk.red(`\n  ✗ "${game.title}" is PUBLISHED and cannot be returned to draft.\n`));
+    return;
+  }
+
+  console.log();
+  console.log(brand.gold(`  Return "${game.title}" to DRAFT?`));
+  console.log(brand.teal(`  Current status: ${game.status}`));
+  console.log(brand.teal('  This will withdraw the game from review so you can make changes.'));
+  console.log();
+
+  const { confirm } = await inquirer.prompt([{
+    type: 'confirm',
+    name: 'confirm',
+    message: 'Return to draft?',
+    default: true,
+  }]);
+
+  if (!confirm) {
+    console.log(brand.teal('\n  Cancelled.\n'));
+    return;
+  }
+
+  const spinner = villageSpinner('Updating status...').start();
+
+  try {
+    await updateGameMetadata(gameId, { status: 'DRAFT' });
+    spinner.succeed('Game returned to draft!');
+    console.log();
+    console.log(brand.green(`  ✓ "${game.title}" is now in DRAFT status.`));
+    console.log(brand.teal('  You can now upload assets, update metadata, and redeploy.'));
+    console.log();
+  } catch (err) {
+    const message = err.response?.data?.error || err.message;
+    spinner.fail(`Failed to update status: ${message}`);
+  }
+}
+
 // ── Helpers ───────────────────────────────────────────
 
 function getGameId() {