@seomi/ssh 0.1.0

package/README.md

@@ -0,0 +1,61 @@
+# @seomi/ssh
+
+> Одной командой настраивает беспарольный SSH-доступ для AI-агента к вашим серверам.
+
+`@seomi/ssh` — CLI-инсталлятор: за один интерактивный прогон он настраивает доступ агента
+по SSH-ключу к одному или нескольким серверам (dev / prod / кастомные) и записывает карту
+доступа в инструкции агента (`AGENTS.md` / `CLAUDE.md`). Облегчённый родственник
+[`@seomi/wp-mcp`](../seomi-wp-mcp) — без WordPress и MCP, только SSH.
+
+## Быстрый старт
+
+```bash
+npm install -g @seomi/ssh
+cd my-project
+seomi-ssh init
+```
+
+## Возможности
+
+- **`init`** — интерактивная настройка: спрашивает про серверы **в цикле** (роль, host,
+  user, port, ключ, рабочая директория), повторяет «добавить ещё?» до отказа. 1..N серверов.
+- **SSH-визард** на каждый сервер — генерация ed25519-ключа (или переиспользование),
+  копирование публичного ключа (`ssh-copy-id` → ssh-pipe fallback), проверка по `BatchMode`,
+  при неудаче — печать ручной подсказки с содержимым `.pub`.
+- **Запись инструкций агенту** — managed-блок с картой серверов и готовыми примерами
+  `ssh` / `scp` / `rsync` (значения берутся из `.claude/.env`).
+- **Skill `aif-ssh`** — копируется в `.claude/skills/` целевого проекта и учит агента
+  пользоваться настроенным доступом.
+- **Идемпотентность** — повторный запуск не дублирует ключи, env-записи и managed-блок.
+
+> `update` и `doctor` объявлены в справке, но пока не реализованы (заглушки).
+
+## Пример
+
+```bash
+$ seomi-ssh init
+› Шаг 1: Опрос серверов
+? Роль сервера › prod
+? [prod] Host (домен или IP) › prod.example.com
+? [prod] SSH-пользователь › ai-agent
+? Добавить ещё один сервер? › No
+› Шаг 2: Настройка SSH-ключей
+[ok] «prod»: ключ настроен и проверен
+› Шаг 3: Запись реквизитов в .claude/.env
+› Шаг 4: Инструкции агенту (AGENTS.md / CLAUDE.md)
+[ok] created: AGENTS.md
+```
+
+Используйте `seomi-ssh init --dry-run`, чтобы прогнать опрос без записи на диск и SSH-вызовов.
+
+---
+
+## Документация
+
+| Раздел | Описание |
+|--------|----------|
+| [Команда `init`](docs/init.md) | Настройка SSH-доступа: поведение, конфигурация `.claude/.env`, примеры, диагностика |
+
+## Лицензия
+
+Условия лицензии указаны в поле `license` файла `package.json`.

package/bin/seomi-ssh.mjs

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+/**
+ * seomi-ssh — entry point.
+ *
+ * Parses argv, sets the log level, and routes to a subcommand. Only `init` is
+ * implemented in this release; `update` and `doctor` are declared stubs so the
+ * surface is stable and discoverable.
+ */
+
+import { parseArgs } from 'node:util';
+import { initCommand } from '../src/commands/init.mjs';
+import { logger } from '../src/lib/logger.mjs';
+
+const HELP = `Usage: seomi-ssh <command> [options]
+
+Commands:
+  init           Interactive setup — configure passwordless SSH access for an
+                 AI agent to one or more servers (dev / prod / custom), write
+                 the connection params to .claude/.env, render the managed
+                 access block into AGENTS.md / CLAUDE.md, and drop the aif-ssh
+                 skill into .claude/skills/.
+  update         (not implemented yet) Regenerate the managed block from
+                 .claude/.env and self-update the package.
+  doctor         (not implemented yet) Diagnose configured servers (which are
+                 set up, which are reachable by key).
+
+Global options:
+  --verbose      Enable debug logging (DEBUG level).
+  --dry-run      init only: run prompts but make no changes; preview the block.
+  --help, -h     Show this help.
+  --version, -v  Print version.
+`;
+
+async function readVersion() {
+	const { readFile } = await import( 'node:fs/promises' );
+	const pkg = JSON.parse(
+		await readFile( new URL( '../package.json', import.meta.url ), 'utf8' )
+	);
+	return pkg.version;
+}
+
+async function main() {
+	const rawArgs = process.argv.slice( 2 );
+
+	if ( rawArgs.length === 0 || rawArgs[0] === '--help' || rawArgs[0] === '-h' ) {
+		process.stdout.write( HELP );
+		return 0;
+	}
+
+	if ( rawArgs[0] === '--version' || rawArgs[0] === '-v' ) {
+		process.stdout.write( ( await readVersion() ) + '\n' );
+		return 0;
+	}
+
+	const command = rawArgs[0];
+	const restArgs = rawArgs.slice( 1 );
+
+	const { values, positionals } = parseArgs( {
+		args: restArgs,
+		options: {
+			verbose: { type: 'boolean', default: false },
+			help: { type: 'boolean', short: 'h', default: false },
+			'dry-run': { type: 'boolean', default: false },
+		},
+		strict: false,
+		allowPositionals: true,
+	} );
+
+	if ( values.verbose ) {
+		logger.setLevel( 'debug' );
+	}
+
+	const opts = { ...values, positionals };
+
+	switch ( command ) {
+		case 'init':
+			return await initCommand( opts );
+		case 'update':
+		case 'doctor':
+			logger.warn( `Команда «${ command }» ещё не реализована в этой версии.` );
+			logger.info( 'Доступна только `seomi-ssh init`. См. `seomi-ssh --help`.' );
+			return 1;
+		default:
+			logger.error( `Unknown command: ${ command }` );
+			process.stdout.write( HELP );
+			return 1;
+	}
+}
+
+main()
+	.then( ( code ) => process.exit( code ?? 0 ) )
+	.catch( ( err ) => {
+		logger.error( 'Unhandled error:', err?.stack || err?.message || String( err ) );
+		process.exit( 1 );
+	} );

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@seomi/ssh",
+  "version": "0.1.0",
+  "description": "One-command CLI installer that sets up passwordless SSH access for AI agents in any project (dev/prod/custom servers) and writes the access map into AGENTS.md / CLAUDE.md.",
+  "type": "module",
+  "bin": {
+    "seomi-ssh": "bin/seomi-ssh.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "skills",
+    "templates",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "node --test \"test/*.test.mjs\""
+  },
+  "dependencies": {
+    "@inquirer/prompts": "^7.0.0"
+  },
+  "keywords": [
+    "ssh",
+    "ai-agent",
+    "claude",
+    "ai-factory",
+    "seomi",
+    "cli",
+    "deploy"
+  ],
+  "license": "SEE LICENSE IN LICENSE",
+  "publishConfig": {
+    "access": "public"
+  },
+  "directories": {
+    "test": "test"
+  }
+}

package/skills/aif-ssh/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: aif-ssh
+description: Use the SSH access that `seomi-ssh init` configured for this project — run remote commands, deploy files (scp/rsync), and diagnose servers. Connection parameters live in `.claude/.env` under SSH_<ROLE>_* keys. Trigger when the task needs work on a remote server (deploy, run a command remotely, tail logs, check disk/service status) or when the user mentions prod/dev/staging access.
+---
+
+# aif-ssh — использование SSH-доступа агентом
+
+Этот проект настроен через `@seomi/ssh`: для одного или нескольких серверов уже
+сконфигурирован беспарольный SSH-доступ (ed25519-ключ), а реквизиты записаны в
+`.claude/.env`. Этот skill учит, как этим доступом пользоваться.
+
+## Где брать реквизиты доступа
+
+**Первое и единственное место — `.claude/.env`.** Не используй `~/.ssh/config`, алиасы из
+других проектов и не угадывай host по имени проекта.
+
+Каждый сервер описан группой ключей с префиксом роли:
+
+```
+SSH_SERVERS=PROD,DEV              # реестр настроенных серверов (csv префиксов)
+
+SSH_PROD_HOST=prod.example.com
+SSH_PROD_USER=ai-agent
+SSH_PROD_PORT=22
+SSH_PROD_KEY=~/.ssh/id_ed25519
+SSH_PROD_ROOT=/var/www/app        # необязательный — рабочая директория
+```
+
+Алгоритм: прочитай `SSH_SERVERS`, выбери нужный префикс (`PROD` / `DEV` / кастомный),
+подставь `SSH_<PREFIX>_HOST/USER/PORT/KEY/ROOT` в команды ниже.
+
+## Готовые команды
+
+Пусть `H=$SSH_<PREFIX>_HOST`, `U=$SSH_<PREFIX>_USER`, `P=$SSH_<PREFIX>_PORT`,
+`K=$SSH_<PREFIX>_KEY`, `R=$SSH_<PREFIX>_ROOT`. Флаг порта добавляй только если порт ≠ 22.
+
+```bash
+# Выполнить команду на сервере
+ssh -p "$P" -i "$K" "$U@$H" "<command>"
+
+# Скопировать файл/каталог на сервер (порт у scp — заглавная -P)
+scp -P "$P" -i "$K" -r ./local-path "$U@$H:$R/"
+
+# Инкрементальная синхронизация каталога (предпочтительно для повторных деплоев)
+rsync -avz -e "ssh -i $K -p $P" ./local-dir/ "$U@$H:$R/"
+
+# Просмотр логов / статуса
+ssh -p "$P" -i "$K" "$U@$H" "tail -n 100 $R/storage/logs/app.log"
+```
+
+## Правила
+
+- **`.claude/.env` — источник истины.** Если ключа нет в `.claude/.env`, доступ к этому
+  серверу не настроен — не выдумывай реквизиты, предложи запустить `seomi-ssh init`.
+- **Не логируй и не выводи содержимое приватного ключа** (`$SSH_<PREFIX>_KEY` указывает на
+  файл — путь показывать можно, содержимое — нет).
+- **Деплой через SSH/scp/rsync — канонический путь.** Не предлагай GUI-клиенты
+  (PhpStorm/WebStorm Deploy, Cyberduck, FileZilla) первым вариантом.
+- **Перед разрушительными операциями на сервере** (`rm -rf`, перезапись, миграции БД,
+  рестарт сервисов) — подтверди у пользователя; одобрение для одного сервера не
+  распространяется на другие.
+- **Не путай окружения.** Перед командой на `PROD` убедись, что выбран правильный префикс;
+  для экспериментов предпочитай `DEV`/`staging`, если он настроен.
+
+## Управление доступом
+
+- `seomi-ssh init` — первичная настройка (добавить серверы, скопировать ключ, записать блок).
+- `seomi-ssh update` — перегенерировать managed-блок в `AGENTS.md`/`CLAUDE.md` после
+  изменения реквизитов в `.claude/.env`.
+- `seomi-ssh doctor` — проверить, какие серверы настроены и доступны ли они по ключу.

package/src/commands/init.mjs

@@ -0,0 +1,147 @@
+/**
+ * `seomi-ssh init` — interactive setup orchestrator.
+ *
+ * Thin command: it sequences lib utilities and owns no business logic itself.
+ * Flow:
+ *   1. promptServers()            — interactive loop (1..N servers)
+ *   2. ensureSshKey() per server  — keygen → copy → verify → manual hint
+ *   3. mergeEnv()                 — write SSH_<PREFIX>_* + SSH_SERVERS to .claude/.env
+ *   4. detectAgentMdTargets()     — pick AGENTS.md / CLAUDE.md / both
+ *   5. renderAgentMdBlock() + insertOrUpdate() — managed block per target
+ *   6. copy skills/aif-ssh        — drop the access skill into .claude/skills/
+ *
+ * `--dry-run` runs the prompts but performs NO side effects (no ssh, no file
+ * writes); it prints what would happen and the rendered block instead.
+ */
+
+import { mkdir, copyFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { logger } from '../lib/logger.mjs';
+import { promptServers, toEnvUpdates } from '../lib/server-prompt.mjs';
+import { mergeEnv } from '../lib/env-writer.mjs';
+import { ensureSshKey } from '../lib/ssh-key-setup.mjs';
+import { detectAgentMdTargets } from '../lib/agent-md-target.mjs';
+import { renderAgentMdBlock } from '../lib/agent-md-renderer.mjs';
+import { insertOrUpdate } from '../lib/markers.mjs';
+
+const MARKER_NS = 'seomi-ssh';
+
+function packagePath( ...segments ) {
+	// init.mjs lives at <pkg>/src/commands/ — climb two levels to the package root.
+	return fileURLToPath( new URL( join( '../../', ...segments ), import.meta.url ) );
+}
+
+async function copySkill( cwd ) {
+	const src = packagePath( 'skills', 'aif-ssh', 'SKILL.md' );
+	const destDir = join( cwd, '.claude', 'skills', 'aif-ssh' );
+	await mkdir( destDir, { recursive: true } );
+	const dest = join( destDir, 'SKILL.md' );
+	await copyFile( src, dest );
+	logger.success( `skill aif-ssh → ${ dest }` );
+}
+
+function printSummary( servers, dryRun ) {
+	logger.info( `Серверов настроено: ${ servers.length }${ dryRun ? ' (dry-run, без записи)' : '' }` );
+	for ( const s of servers ) {
+		logger.info( `  • ${ s.role } → ${ s.user }@${ s.host }${ s.port && s.port !== '22' ? `:${ s.port }` : '' } (env SSH_${ s.prefix }_*)` );
+	}
+}
+
+/**
+ * @param {object}   [options]
+ * @param {string}   [options.cwd]            — project root (default process.cwd()).
+ * @param {boolean}  [options['dry-run']]     — no side effects, just preview.
+ * @param {string}   [options.envPath]        — override .claude/.env location.
+ * @param {string}   [options.templatePath]   — override bundled template path.
+ * @param {object}   [options._prompts]       — test seam for @inquirer/prompts.
+ * @param {Function} [options._promptSelect]  — test seam for agent-md-target select.
+ * @returns {Promise<number>} process exit code.
+ */
+export async function initCommand( options = {} ) {
+	const cwd = options.cwd || process.cwd();
+	const dryRun = Boolean( options[ 'dry-run' ] || options.dryRun );
+	const envPath = options.envPath || join( cwd, '.claude', '.env' );
+	const templatePath = options.templatePath || packagePath( 'templates', 'agent-md-block.md' );
+
+	logger.step( 'seomi-ssh init' + ( dryRun ? ' (dry-run)' : '' ) );
+
+	// --- 1. Prompt for servers -------------------------------------------
+	logger.step( 'Шаг 1: Опрос серверов' );
+	const servers = await promptServers( { _prompts: options._prompts } );
+	if ( servers.length === 0 ) {
+		logger.warn( 'Серверы не заданы — нечего настраивать. Выход.' );
+		return 0;
+	}
+	logger.success( `Введено серверов: ${ servers.length }` );
+
+	// --- 2. SSH key wizard per server ------------------------------------
+	logger.step( 'Шаг 2: Настройка SSH-ключей' );
+	for ( const srv of servers ) {
+		if ( dryRun ) {
+			logger.info( `[dry-run] ensureSshKey для «${ srv.role }» (${ srv.user }@${ srv.host }) пропущен` );
+			continue;
+		}
+		try {
+			const result = await ensureSshKey( {
+				sshHost: srv.host,
+				sshUser: srv.user,
+				sshPort: srv.port,
+				keyPath: srv.keyPath,
+			} );
+			if ( result.verified ) {
+				logger.success( `«${ srv.role }»: ключ настроен и проверен (${ result.keygenAction }/${ result.copyAction })` );
+			} else {
+				logger.warn( `«${ srv.role }»: автоматическая настройка не удалась — ручная подсказка:` );
+				logger.warn( result.manualHint );
+			}
+		} catch ( err ) {
+			// One server's failure must not abort the rest of the run.
+			logger.error( `«${ srv.role }»: ${ err.message }` );
+		}
+	}
+
+	// --- 3. Write connection params to .claude/.env ----------------------
+	logger.step( 'Шаг 3: Запись реквизитов в .claude/.env' );
+	const updates = toEnvUpdates( servers );
+	if ( dryRun ) {
+		logger.info( `[dry-run] mergeEnv пропущен; были бы записаны ключи: ${ Object.keys( updates ).join( ', ' ) }` );
+	} else {
+		const r = await mergeEnv( envPath, updates );
+		logger.success( `.claude/.env: добавлено ${ r.added.length }, обновлено ${ r.updated.length }, без изменений ${ r.unchanged.length }` );
+	}
+
+	// --- 4 & 5. Render + write the managed block -------------------------
+	logger.step( 'Шаг 4: Инструкции агенту (AGENTS.md / CLAUDE.md)' );
+	const block = await renderAgentMdBlock( servers, templatePath );
+	if ( dryRun ) {
+		const { targets } = await detectAgentMdTargets( { cwd, interactive: false } );
+		logger.info( `[dry-run] managed-блок был бы записан в: ${ targets.join( ', ' ) || '(none)' }` );
+		process.stdout.write( '\n--- managed block preview ---\n' + block + '--- end preview ---\n' );
+	} else {
+		const { targets } = await detectAgentMdTargets( {
+			cwd,
+			interactive: true,
+			_promptSelect: options._promptSelect,
+		} );
+		if ( targets.length === 0 ) {
+			logger.warn( 'Целевой файл инструкций не выбран — managed-блок не записан.' );
+		}
+		for ( const file of targets ) {
+			const res = await insertOrUpdate( file, block, { namespace: MARKER_NS } );
+			logger.success( `${ res.action }: ${ file }` );
+		}
+	}
+
+	// --- 6. Copy the access skill ----------------------------------------
+	logger.step( 'Шаг 5: Копирование skill aif-ssh' );
+	if ( dryRun ) {
+		logger.info( `[dry-run] копирование skills/aif-ssh → ${ join( cwd, '.claude', 'skills', 'aif-ssh', 'SKILL.md' ) } пропущено` );
+	} else {
+		await copySkill( cwd );
+	}
+
+	logger.step( 'Готово' );
+	printSummary( servers, dryRun );
+	return 0;
+}

package/src/lib/agent-md-renderer.mjs

@@ -0,0 +1,99 @@
+/**
+ * Render the managed AGENTS.md / CLAUDE.md block from the bundled template.
+ *
+ * Input is the list of server objects produced by `server-prompt.mjs`
+ * (role / prefix / host / user / port / keyPath / root). The block is two
+ * generated parts spliced into the template:
+ *
+ *   {{SERVER_TABLE}}    — one row per server (role, env-prefix, host, user, …)
+ *   {{SERVER_EXAMPLES}} — ssh / scp / rsync recipes per server, with the port
+ *                         flag and key path pre-filled from the entered values
+ *
+ * The recipes exist because agents otherwise default to `~/.ssh/config` aliases
+ * or GUI deploy clients; pre-cooking concrete `scp`/`rsync` commands keyed off
+ * `.claude/.env` keeps them on the canonical channel.
+ *
+ * Self-contained: only depends on the shared logger. No external commands.
+ */
+
+import { readFile } from 'node:fs/promises';
+import { logger } from './logger.mjs';
+
+function present( v ) {
+	return typeof v === 'string' && v.trim().length > 0;
+}
+
+/**
+ * A non-default port (anything other than blank/22) needs an explicit flag in
+ * the example commands. 22 is the ssh default, so we omit it for cleaner copy.
+ */
+function effectivePort( port ) {
+	return present( port ) && port.trim() !== '22' ? port.trim() : '';
+}
+
+function buildServerTable( servers ) {
+	const out = [
+		'| Роль | env-префикс | Host | User | Port | Рабочая директория |',
+		'|------|-------------|------|------|------|--------------------|',
+	];
+	for ( const s of servers ) {
+		out.push(
+			`| ${ s.role } | \`SSH_${ s.prefix }_*\` | ${ s.host } | ${ s.user } | ${ present( s.port ) ? s.port : '22' } | ${ present( s.root ) ? `\`${ s.root }\`` : '—' } |`
+		);
+	}
+	return out.join( '\n' );
+}
+
+function buildServerExamples( servers ) {
+	const blocks = [];
+	for ( const s of servers ) {
+		const port = effectivePort( s.port );
+		const sshPortFlag = port ? `-p ${ port } ` : '';
+		const scpPortFlag = port ? `-P ${ port } ` : '';
+		const key = present( s.keyPath ) ? s.keyPath : '~/.ssh/id_ed25519';
+		const target = `${ s.user }@${ s.host }`;
+		const root = present( s.root ) ? s.root : '<remote-path>';
+		const rsyncSsh = `-e "ssh -i ${ key }${ port ? ` -p ${ port }` : '' }"`;
+
+		const lines = [];
+		lines.push( `#### ${ s.role } — \`${ target }\` (env \`SSH_${ s.prefix }_*\`)` );
+		lines.push( '' );
+		lines.push( '```bash' );
+		lines.push( '# Выполнить команду на сервере' );
+		lines.push( `ssh ${ sshPortFlag }-i ${ key } ${ target } "<command>"` );
+		lines.push( '' );
+		lines.push( '# Скопировать файл/каталог на сервер' );
+		lines.push( `scp ${ scpPortFlag }-i ${ key } -r ./local-path ${ target }:${ root }/` );
+		lines.push( '' );
+		lines.push( '# Инкрементальная синхронизация каталога (рекомендуется для повторных деплоев)' );
+		lines.push( `rsync -avz ${ rsyncSsh } ./local-dir/ ${ target }:${ root }/` );
+		lines.push( '```' );
+		blocks.push( lines.join( '\n' ) );
+	}
+	return blocks.join( '\n\n' );
+}
+
+/**
+ * Render the managed block.
+ *
+ * @param {Array<object>} servers       Server objects from `promptServers`.
+ * @param {string}        templatePath  Path to `templates/agent-md-block.md`.
+ * @returns {Promise<string>}           The rendered block (no marker comments —
+ *                                      `markers.insertOrUpdate` wraps it).
+ */
+export async function renderAgentMdBlock( servers, templatePath ) {
+	if ( ! Array.isArray( servers ) || servers.length === 0 ) {
+		throw new Error( 'renderAgentMdBlock: at least one server is required' );
+	}
+	logger.debug( `[render] rendering block for ${ servers.length } server(s) from ${ templatePath }` );
+
+	const template = await readFile( templatePath, 'utf8' );
+	const rendered = template
+		.replaceAll( '{{SERVER_TABLE}}', buildServerTable( servers ) )
+		.replaceAll( '{{SERVER_EXAMPLES}}', buildServerExamples( servers ) );
+
+	// Collapse runs of 3+ blank lines for stable diffs across re-renders.
+	return rendered.replace( /\n{3,}/g, '\n\n' ).trim() + '\n';
+}
+
+export const _internals = { buildServerTable, buildServerExamples, effectivePort };

package/src/lib/agent-md-target.mjs

@@ -0,0 +1,107 @@
+/**
+ * Target-aware detection for AI agent instructions files (AGENTS.md / CLAUDE.md).
+ *
+ * Claude Code reads `CLAUDE.md` if present and IGNORES `AGENTS.md` next to it.
+ * Other agents (e.g. ai-factory tooling) treat `AGENTS.md` as the universal
+ * standard. This detector lets `init` / `update` / `doctor` keep the managed
+ * `seomi-ssh` block in the file the project actually uses — and, when both
+ * coexist, synchronize the block into both so no agent loses context.
+ *
+ * Decision tree:
+ *   1. Both files exist          → targets = [AGENTS.md, CLAUDE.md]      (source='both')
+ *   2. Only AGENTS.md exists     → targets = [AGENTS.md]                 (source='agents')
+ *   3. Only CLAUDE.md exists     → targets = [CLAUDE.md]                 (source='claude')
+ *   4. Neither, interactive=false→ targets = [<defaultName>]             (source='default')
+ *   5. Neither, interactive=true → select prompt → user / skipped        (source='user'|'skipped')
+ */
+
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { logger } from './logger.mjs';
+
+export const DEFAULT_TARGET = 'AGENTS.md';
+const AGENTS_FILE = 'AGENTS.md';
+const CLAUDE_FILE = 'CLAUDE.md';
+
+/**
+ * Detect which agent-instructions file(s) the project uses and return absolute
+ * paths to be updated with the managed `seomi-ssh` block.
+ *
+ * @param {object}   opts
+ * @param {string}   opts.cwd                — project root
+ * @param {boolean}  [opts.interactive=false]— allowed to prompt the user when
+ *                                              neither file exists
+ * @param {string}   [opts.defaultName='AGENTS.md'] — fallback when no file
+ *                                              exists and we cannot prompt
+ * @param {Function} [opts._promptSelect]      — test seam: replaces the
+ *                                              `@inquirer/prompts` `select`
+ *                                              call. Called with the same
+ *                                              options as `select()` and must
+ *                                              return a Promise<string>.
+ * @returns {Promise<{ targets: string[], source: 'both'|'agents'|'claude'|'default'|'user'|'skipped' }>}
+ */
+export async function detectAgentMdTargets( { cwd, interactive = false, defaultName = DEFAULT_TARGET, _promptSelect } = {} ) {
+	if ( ! cwd ) throw new Error( 'detectAgentMdTargets: `cwd` is required' );
+
+	logger.debug( `[agent-md] cwd=${ cwd }, interactive=${ interactive }, default=${ defaultName }` );
+
+	const agentsPath = join( cwd, AGENTS_FILE );
+	const claudePath = join( cwd, CLAUDE_FILE );
+	const existsAgents = existsSync( agentsPath );
+	const existsClaude = existsSync( claudePath );
+
+	logger.info( `[agent-md] AGENTS.md exists: ${ existsAgents }, CLAUDE.md exists: ${ existsClaude }` );
+
+	if ( existsAgents && existsClaude ) {
+		logger.info( '[agent-md] decision: both' );
+		logger.warn( '[agent-md] both files present — managed block will be synced to both, prefer keeping only AGENTS.md long-term' );
+		const targets = [ agentsPath, claudePath ];
+		logger.success( `[agent-md] targets: ${ targets.join( ', ' ) }` );
+		return { targets, source: 'both' };
+	}
+
+	if ( existsAgents ) {
+		logger.info( '[agent-md] decision: agents-only' );
+		const targets = [ agentsPath ];
+		logger.success( `[agent-md] targets: ${ targets.join( ', ' ) }` );
+		return { targets, source: 'agents' };
+	}
+
+	if ( existsClaude ) {
+		logger.info( '[agent-md] decision: claude-only' );
+		const targets = [ claudePath ];
+		logger.success( `[agent-md] targets: ${ targets.join( ', ' ) }` );
+		return { targets, source: 'claude' };
+	}
+
+	// Neither file exists.
+	if ( ! interactive ) {
+		logger.info( `[agent-md] decision: default (${ defaultName })` );
+		const targets = [ join( cwd, defaultName ) ];
+		logger.success( `[agent-md] targets: ${ targets.join( ', ' ) }` );
+		return { targets, source: 'default' };
+	}
+
+	// Interactive: ask the user which file to create.
+	const select = _promptSelect || ( await import( '@inquirer/prompts' ) ).select;
+	const choice = await select( {
+		message: 'Project has no AGENTS.md or CLAUDE.md. Create which one?',
+		default: AGENTS_FILE,
+		choices: [
+			{ name: 'AGENTS.md (universal, recommended)', value: AGENTS_FILE },
+			{ name: 'CLAUDE.md (Claude Code only)',       value: CLAUDE_FILE },
+			{ name: 'skip — do not create any file',       value: 'skip' },
+		],
+	} );
+
+	if ( choice === 'skip' ) {
+		logger.info( '[agent-md] decision: skipped' );
+		logger.success( '[agent-md] targets: (none)' );
+		return { targets: [], source: 'skipped' };
+	}
+
+	logger.info( `[agent-md] decision: user-chosen (${ choice })` );
+	const targets = [ join( cwd, choice ) ];
+	logger.success( `[agent-md] targets: ${ targets.join( ', ' ) }` );
+	return { targets, source: 'user' };
+}