@@ -11,6 +11,9 @@ export const MCP_SERVER_NAME = 'polylane';
 export const MCP_SERVER_URL = process.env.POLYLANE_MCP_URL || 'https://mcp.polylane.com/mcp';
 export const SKILL_DIRECTORY_NAME = 'polylane-cli';
 
+/** The prompt handed to a coding agent to map the current repository. */
+export const MAPPING_PROMPT = 'Map this repository with Polylane';
+
 export type WriteAction = 'created' | 'updated' | 'unchanged' | 'skipped';
 
 export interface WriteOutcome {
@@ -175,12 +178,28 @@ export function upsertGooseExtension(path: string, dryRun = false): WriteOutcome
   return { label, path, action: 'updated' };
 }
 
+/**
+ * How to launch an agent headlessly for a one-shot, auto-approved run of a
+ * prompt. Absent for agents with no scriptable headless entry (IDE/extension
+ * surfaces like Windsurf, Zed, Roo, VS Code).
+ */
+export interface HeadlessRun {
+  /** The executable to invoke; must resolve on PATH for the recipe to run. */
+  bin: string;
+  /** Build the full argv (excluding `bin`) for a one-shot run of `prompt`. */
+  args(prompt: string): string[];
+  /** Extra environment needed to run non-interactively (merged over process.env). */
+  env?: Record<string, string>;
+}
+
 export interface AgentSetup {
   id: string;
   name: string;
   detect(home: string): boolean;
   user(home: string, dryRun: boolean): WriteOutcome[];
   project?(projectDir: string, dryRun: boolean): WriteOutcome[];
+  /** How to run this agent headlessly, when it has a scriptable one-shot mode. */
+  headlessRun?: HeadlessRun;
 }
 
 function skillFile(baseDir: string): string {
@@ -191,6 +210,7 @@ export const AGENTS: AgentSetup[] = [
   {
     id: 'claude',
     name: 'Claude Code',
+    headlessRun: { bin: 'claude', args: (prompt) => ['-p', prompt, '--permission-mode', 'bypassPermissions'] },
     detect: (home) => existsSync(join(home, '.claude')) || existsSync(join(home, '.claude.json')),
     user: (home, dryRun) => [
       writeSkillFile(skillFile(join(home, '.claude')), dryRun),
@@ -204,6 +224,7 @@ export const AGENTS: AgentSetup[] = [
   {
     id: 'cursor',
     name: 'Cursor',
+    headlessRun: { bin: 'cursor-agent', args: (prompt) => ['-p', prompt, '--force'] },
     detect: (home) => existsSync(join(home, '.cursor')),
     user: (home, dryRun) => [
       writeSkillFile(skillFile(join(home, '.cursor')), dryRun),
@@ -217,6 +238,7 @@ export const AGENTS: AgentSetup[] = [
   {
     id: 'opencode',
     name: 'OpenCode',
+    headlessRun: { bin: 'opencode', args: (prompt) => ['run', prompt] },
     detect: (home) => existsSync(join(home, '.config', 'opencode')),
     user: (home, dryRun) => [
       writeSkillFile(skillFile(join(home, '.config', 'opencode')), dryRun),
@@ -240,6 +262,7 @@ export const AGENTS: AgentSetup[] = [
   {
     id: 'codex',
     name: 'Codex CLI',
+    headlessRun: { bin: 'codex', args: (prompt) => ['exec', '--full-auto', prompt] },
     detect: (home) => existsSync(join(home, '.codex')),
     user: (home, dryRun) => [
       writeSkillFile(skillFile(join(home, '.codex')), dryRun),
@@ -258,6 +281,7 @@ export const AGENTS: AgentSetup[] = [
   {
     id: 'pi',
     name: 'Pi',
+    headlessRun: { bin: 'pi', args: (prompt) => ['-p', prompt] },
     detect: (home) => existsSync(join(home, '.pi')),
     user: (home, dryRun) => [
       writeSkillFile(skillFile(join(home, '.pi', 'agent')), dryRun),
@@ -284,6 +308,7 @@ export const AGENTS: AgentSetup[] = [
   {
     id: 'cline',
     name: 'Cline',
+    headlessRun: { bin: 'cline', args: (prompt) => ['--yolo', prompt] },
     // Two Cline surfaces share one config format: the VS Code extension
     // (globalStorage) and the Cline CLI (~/.cline). Write to whichever exists
     // so we never create VS Code's storage tree for an uninstalled extension.
@@ -324,12 +349,14 @@ export const AGENTS: AgentSetup[] = [
   {
     id: 'goose',
     name: 'Goose',
+    headlessRun: { bin: 'goose', args: (prompt) => ['run', '--no-session', '-t', prompt], env: { GOOSE_MODE: 'auto' } },
     detect: (home) => existsSync(join(home, '.config', 'goose')),
     user: (home, dryRun) => [upsertGooseExtension(join(home, '.config', 'goose', 'config.yaml'), dryRun)],
   },
   {
     id: 'gemini',
     name: 'Gemini CLI',
+    headlessRun: { bin: 'gemini', args: (prompt) => ['-p', prompt, '--yolo'] },
     detect: (home) => existsSync(join(home, '.gemini')),
     user: (home, dryRun) => [
       upsertJsonEntry(join(home, '.gemini', 'settings.json'), ['mcpServers', MCP_SERVER_NAME], GEMINI_SERVER_ENTRY, dryRun),
 
@@ -4,6 +4,7 @@ import { configCommands } from './config';
 import { helpCommand } from './help';
 import { scanCommand } from './scan';
 import { setupCommand } from './setup';
+import { mapCommand } from './map';
 import { updateCommand } from './update';
 import { feedCommands } from './feed';
 import { issueCommands } from './issue';
@@ -52,6 +53,7 @@ export function registerAllCommands(): void {
     helpCommand,
     scanCommand,
     setupCommand,
+    mapCommand,
     updateCommand,
   ];
 
 
@@ -0,0 +1,142 @@
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { delimiter, join } from 'node:path';
+import type { Command } from '../command';
+import type { Config } from '../config/schema';
+import type { GlobalFlags } from '../types/flags';
+import { AGENTS, AGENT_IDS, MAPPING_PROMPT, agentById, type AgentSetup, type HeadlessRun } from '../agents/registry';
+import { isInteractive } from '../utils/env';
+import { promptSelect } from '../utils/prompt';
+import { CLIError } from '../errors/base';
+import { ExitCode } from '../errors/codes';
+
+/** Whether `bin` resolves to an executable on PATH. */
+export function onPath(bin: string): boolean {
+  const dirs = (process.env.PATH ?? '').split(delimiter).filter(Boolean);
+  const exts = process.platform === 'win32' ? ['.exe', '.cmd', '.bat', ''] : [''];
+  return dirs.some((dir) => exts.some((ext) => existsSync(join(dir, bin + ext))));
+}
+
+interface Runnable {
+  agent: AgentSetup;
+  run: HeadlessRun;
+}
+
+/**
+ * Pick the agent that will actually run the map. The primary agent runs it when
+ * it has a headless recipe whose binary is installed. Otherwise any other
+ * installed agent with a runnable recipe is a fallback — the map only needs an
+ * agent wired to the authed MCP, not the primary one — so a user whose primary
+ * is IDE-only (Windsurf/Zed/Roo/VS Code) can still map through a sibling CLI.
+ */
+export function resolveRunnable(
+  primary: AgentSetup | undefined,
+  installed: AgentSetup[],
+  isOnPath: (bin: string) => boolean = onPath
+): { runnable?: Runnable; viaSibling: boolean } {
+  if (primary?.headlessRun && isOnPath(primary.headlessRun.bin)) {
+    return { runnable: { agent: primary, run: primary.headlessRun }, viaSibling: false };
+  }
+  const sibling = installed.find(
+    (a) => a.id !== primary?.id && a.headlessRun && isOnPath(a.headlessRun.bin)
+  );
+  if (sibling?.headlessRun) {
+    return { runnable: { agent: sibling, run: sibling.headlessRun }, viaSibling: Boolean(primary) };
+  }
+  return { viaSibling: false };
+}
+
+function runChild(bin: string, argv: string[], env?: Record<string, string>): Promise<number> {
+  return new Promise((resolve, reject) => {
+    const child = spawn(bin, argv, {
+      stdio: 'inherit',
+      cwd: process.cwd(),
+      env: { ...process.env, ...(env ?? {}) },
+    });
+    child.on('error', (err) =>
+      reject(new CLIError(`Failed to launch ${bin}: ${(err as Error).message}`, ExitCode.GENERAL))
+    );
+    child.on('close', (code) => resolve(code ?? 0));
+  });
+}
+
+export const mapCommand: Command = {
+  name: 'map',
+  description: 'Map this repository into your workspace using your coding agent',
+  usage: 'polylane map [--agent <id>]',
+  options: [
+    {
+      flag: '--agent <id>',
+      description: 'Coding agent to run the map (defaults to your configured agent)',
+      type: 'string',
+    },
+  ],
+  examples: ['polylane map', 'polylane map --agent codex'],
+  async execute(config: Config, _flags: GlobalFlags, args: Record<string, unknown>): Promise<void> {
+    const home = homedir();
+    const installed = AGENTS.filter((a) => a.detect(home));
+
+    const requestedId = typeof args.agent === 'string' ? args.agent : undefined;
+    if (requestedId && !agentById(requestedId)) {
+      throw new CLIError(
+        `Unknown agent: "${requestedId}"`,
+        ExitCode.USAGE,
+        `Supported agents: ${AGENT_IDS.join(', ')}`
+      );
+    }
+
+    // Resolve the primary agent: explicit flag > configured choice > the only
+    // installed agent > interactive pick among installed agents.
+    let primary = requestedId
+      ? agentById(requestedId)
+      : config.agent
+        ? agentById(config.agent)
+        : undefined;
+    if (!primary && installed.length === 1) {
+      primary = installed[0];
+    } else if (!primary && installed.length > 1 && isInteractive(config.nonInteractive)) {
+      const runnable = installed.filter((a) => a.headlessRun && onPath(a.headlessRun.bin));
+      const choices = runnable.length ? runnable : installed;
+      const id = await promptSelect(
+        { nonInteractive: config.nonInteractive },
+        'Which coding agent should map this repository?',
+        choices.map((a) => ({ value: a.id, label: a.name }))
+      );
+      primary = agentById(id);
+    }
+
+    const { runnable, viaSibling } = resolveRunnable(primary, installed);
+
+    if (!runnable) {
+      // Nothing installed can run headlessly — hand off the manual instruction.
+      const name = primary?.name ?? 'your coding agent';
+      process.stderr.write(`Open ${name} in this repository and ask: "${MAPPING_PROMPT}"\n`);
+      return;
+    }
+
+    const { agent, run } = runnable;
+    const argv = run.args(MAPPING_PROMPT);
+
+    if (viaSibling && primary && primary.id !== agent.id) {
+      process.stderr.write(
+        `${primary.name} can't be launched headlessly; running the map with ${agent.name} instead.\n`
+      );
+    }
+
+    if (config.dryRun) {
+      process.stderr.write(`Would run: ${run.bin} ${argv.join(' ')}\n`);
+      return;
+    }
+
+    process.stderr.write(`Mapping this repository with ${agent.name}...\n`);
+    const code = await runChild(run.bin, argv, run.env);
+    if (code !== 0) {
+      throw new CLIError(
+        `${agent.name} exited with code ${code} before finishing the map`,
+        ExitCode.GENERAL,
+        `Run it yourself: open ${agent.name} and ask "${MAPPING_PROMPT}"`
+      );
+    }
+  },
+};
@@ -33,6 +33,7 @@ const NO_AUTH_COMMANDS = new Set([
   'help',
   'scan',
   'setup',
+  'map',
   'update',
   'version',
   'api list',
 
@@ -34,6 +34,7 @@ const RESOURCE_ORDER: Record<string, ResourceGroup> = {
   workspace: { name: 'workspace', description: 'Workspaces', order: 70 },
   auth: { name: 'auth', description: 'Authentication (login, status, logout)', order: 80 },
   setup: { name: 'setup', description: 'Wire the CLI into coding agents (agent skill + MCP server)', order: 85 },
+  map: { name: 'map', description: 'Map this repository into your workspace using your coding agent', order: 86 },
   config: { name: 'config', description: 'CLI configuration', order: 90 },
   telemetry: { name: 'telemetry', description: 'Anonymous usage telemetry (status/enable/disable)', order: 95 },
   api: { name: 'api', description: 'Raw API access (advanced)', order: 100 },