qiksy 1.0.0

package/ARCHITECTURE.md

@@ -0,0 +1,78 @@
+# Qiksy Engine — one local engine for every local-first tool
+
+**Owner decision 2026-07-25:** one engine, not three. Work Finder, Travel and Client
+Finder are ~75% the same backend (`spawn-claude.mjs` is byte-identical across them;
+`agent/jobs/engine/store/license/plans` differ by only 15–43 lines). So they collapse into
+ONE process, ONE port, ONE installer — and a new tool is a new MODULE, not a new installer.
+
+The owner chose the **clean** shape: a shared CORE + tool MODULES mounted under namespaced
+routes on a single port.
+
+## Shape
+
+```
+qiksy-engine/
+  bin/qiksy.mjs         # branded launcher — starts the engine, checks Claude, opens the UI
+  server.mjs            # ONE http server, ONE port (5544). Shared CORS + /api/engine.
+                        # Dispatches /api/<tool>/… → that tool module's handler.
+  core/
+    spawn-claude.mjs    # start `claude` cross-platform (byte-identical today)
+    agent.mjs           # headless `claude -p` runner + approver-MCP + tool/mcp restrictions
+    jobs.mjs            # in-memory job registry + concurrency queue
+    engine.mjs          # Claude sign-in / status  (ONE for all tools → /api/engine/*)
+    store.mjs           # JSON store base; DATA_DIR is PER-TOOL (…/wf, …/travel, …/cf)
+    browser.mjs         # shared CDP Chrome on :9222 (auto-apply / imports)
+    http.mjs            # tiny helpers: json(), body(), cors(), notFound()
+  tools/
+    work-finder/  { id:'wf',     mount(ctx) → handler, seed() }
+    travel/       { id:'travel', … }
+    client-finder/{ id:'cf',     … }
+```
+
+## Module contract
+
+Each tool exports:
+
+```js
+export default {
+  id: 'wf',                         // route namespace: /api/wf/…
+  dataSub: 'wf',                    // DATA_DIR/<dataSub> for this tool's db + files
+  defaults,                        // fresh-install db shape
+  // Given the shared core (jobs, agent runner, browser, per-tool store), return an async
+  // (req, res, seg) → handled:boolean. `seg` has the /api/<id> prefix already stripped,
+  // so a module's routing is IDENTICAL to its standalone backend today.
+  mount(ctx) { return async (req, res, seg) => { … } },
+};
+```
+
+The engine owns: the http server, CORS (the shared UI-origin allow-list + Chrome
+Private-Network preflight), `/api/engine/*` (sign-in is one Claude for all tools), and
+static UI serving. Everything tool-specific stays in the module — routes, prompts, schema.
+
+## Migration (staged; WF keeps working throughout)
+
+1. **Core + server skeleton** (this stage): the package, the branded launcher, the
+   module-mounting server with shared CORS + `/api/engine`. New port while unproven.
+2. **WF module**: refactor `work-finder-backend`'s request handler into a `mount()` — its
+   big segment-switch moves in almost verbatim (the `/api` prefix strip makes `seg` match).
+   Verify WF works through the engine on the test port. Then point the WF frontend at
+   `http://localhost:5544/api/wf` and retire the old standalone backend.
+3. **Client Finder module**: same, from `client-finder-backend`.
+4. **Travel module**: LAST and coordinated — a second session is actively editing
+   `products/travel-assistant` + shared components right now; fold Travel in once that work
+   settles, so we don't clobber each other.
+5. **Installer**: the launcher (`bin/qiksy.mjs`) becomes the one thing every installer
+   (npx → desktop app) starts. `bin/qiksy-work-finder.mjs` (the WF-only launcher already
+   committed) is the stepping stone; it generalises to `qiksy` here.
+
+## Frontends
+
+Each app changes only its API base: `http://localhost:5544` → `http://localhost:5544/api/<id>`
+(and the engine sign-in stays at `/api/engine`). One line per app (`API_BASE` in
+`wfController.ts` / Travel `controller.ts` / CF). Nothing else in the UIs moves.
+
+## Data
+
+`WF_DATA_DIR` (the launcher sets `~/.qiksy`) holds a subfolder per tool — `…/wf`,
+`…/travel`, `…/cf` — so the three JSON stores never collide. The CDP browser profile is
+shared (one Chrome).

package/INSTALL-PROMPT.md

@@ -0,0 +1,53 @@
+# The "paste this to Claude" install prompt
+
+The simplest install path for a non-technical user (HR, agencies) who already has **Claude
+Code** — the one real prerequisite (it is also the engine's fuel). They copy the block
+below, paste it into Claude Code, and Claude does the whole setup on their machine. The
+Work Finder page meanwhile polls `localhost:5544` and flips to the tool the moment the
+engine answers.
+
+This is the canonical text. The app surfaces it with a Copy button; keep the two in sync.
+
+---
+
+```
+You are setting up "Qiksy Work Finder" on this computer for a non-technical person. Do it
+for them, one step at a time, and keep every message short and plain — no jargon.
+
+You can run shell commands. Go:
+
+1. Check Node.js: run `node -v`. If it's missing or older than v18, install it the simplest
+   way for this OS and tell them what you're doing in one line:
+     - macOS:   `brew install node`  (if no Homebrew, install it first from https://brew.sh)
+     - Windows: `winget install OpenJS.NodeJS.LTS`
+     - Linux:   use the distro package manager (e.g. `sudo apt-get install -y nodejs npm`)
+   If a step needs their password or a click, tell them exactly what to do and wait.
+
+2. Start the engine (this downloads it the first time, then keeps it running):
+     `npx -y qiksy-work-finder`
+   Run it so it KEEPS RUNNING in the background — do not block on it. Then wait ~10 seconds.
+
+3. Confirm it's up: fetch `http://localhost:5544/api/engine`. Expect JSON with
+   `"running": true`. If `"claude": false` in that JSON, tell them Claude Code needs to be
+   signed in — the Work Finder page will show a "Connect your Claude" button for that; they
+   don't need to do anything in the terminal.
+
+4. When it's running, say exactly this and stop:
+   "✅ Work Finder is running. Go back to the Work Finder tab in your browser — it will
+    connect automatically. Keep THIS window open while you use it."
+
+Rules: never delete or change files that aren't part of this setup; if anything fails,
+explain in one plain sentence what happened and what they can try, don't dump errors.
+```
+
+---
+
+## Notes
+
+- **Persistence:** while this Claude window stays open, the engine runs. For always-on
+  (survives a reboot) the desktop app / a login agent is the later, nicer path.
+- **Publishing:** the `npx -y qiksy-work-finder` line needs the engine published to npm
+  first (owner `npm login`). Until then this prompt is staged, not live.
+- **Two doors, same page:** "paste to Claude" (this) is the fast door for anyone who has
+  Claude Code; the signed desktop app (double-click, its wizard even installs Claude Code)
+  is the later door for people who want zero terminal at all.

package/bin/qiksy.mjs

@@ -0,0 +1,302 @@
+#!/usr/bin/env node
+/**
+ * The Qiksy engine launcher — ONE command that brings up every Qiksy local-first tool.
+ *
+ * It supervises the three backends as separate processes on their own ports rather than
+ * importing them into one server. That is deliberate:
+ *   · the web apps already talk to 5544 / 5545 / 5546, so nothing on the front end has
+ *     to change and a half-finished engine can never take the tools down;
+ *   · each backend keeps its own lifecycle — one crashing does not kill the others;
+ *   · the backends are edited daily (sometimes by a parallel session), and this way the
+ *     launcher never has to reach inside their request handling.
+ *
+ * Everything runs on the user's machine, on their own Claude. Nothing is uploaded.
+ */
+import { spawn, spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { platform } from 'node:process';
+import { fileURLToPath } from 'node:url';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const PKG = resolve(HERE, '..');
+const isWin = platform === 'win32';
+
+const c = {
+  b: (s) => `\x1b[1m${s}\x1b[0m`,
+  dim: (s) => `\x1b[2m${s}\x1b[0m`,
+  blue: (s) => `\x1b[38;5;69m${s}\x1b[0m`,
+  green: (s) => `\x1b[32m${s}\x1b[0m`,
+  amber: (s) => `\x1b[33m${s}\x1b[0m`,
+  red: (s) => `\x1b[31m${s}\x1b[0m`,
+};
+
+/** One data home, one subfolder per tool — never inside the npx cache. */
+const DATA_HOME = process.env.QIKSY_HOME || join(homedir(), '.qiksy');
+try {
+  mkdirSync(DATA_HOME, { recursive: true });
+} catch {
+  /* unwritable home: each backend falls back to its own folder */
+}
+
+const TOOLS = [
+  {
+    id: 'work-finder',
+    name: 'Work Finder',
+    port: Number(process.env.WF_PORT) || 5544,
+    env: (dir, port) => ({ WF_DATA_DIR: dir, WF_PORT: String(port) }),
+  },
+  {
+    id: 'travel',
+    name: 'Travel Assistant',
+    port: Number(process.env.TA_PORT) || 5545,
+    env: (dir, port) => ({ TA_DB: join(dir, 'db.json'), TA_PORT: String(port) }),
+  },
+  {
+    id: 'client-finder',
+    name: 'Client Finder',
+    port: Number(process.env.CF_PORT) || 5546,
+    env: (dir, port) => ({ CF_DATA_DIR: dir, PORT: String(port) }),
+  },
+];
+
+function hasClaude() {
+  try {
+    return spawnSync('claude', ['--version'], { stdio: 'ignore', shell: isWin, timeout: 8000 }).status === 0;
+  } catch {
+    return false;
+  }
+}
+
+function openBrowser(url) {
+  try {
+    if (platform === 'darwin') spawnSync('open', [url], { stdio: 'ignore' });
+    else if (isWin) spawnSync('cmd', ['/c', 'start', '""', url], { stdio: 'ignore' });
+    else spawnSync('xdg-open', [url], { stdio: 'ignore' });
+  } catch {
+    /* headless box — the printed URL is the fallback */
+  }
+}
+
+/** Resolves once the port answers at all — each backend has its own health path. */
+async function waitFor(port, tries = 40) {
+  for (let i = 0; i < tries; i++) {
+    try {
+      const r = await fetch(`http://127.0.0.1:${port}/`, { signal: AbortSignal.timeout(1200) });
+      if (r) return true;
+    } catch {
+      /* not up yet */
+    }
+    await new Promise((r) => setTimeout(r, 500));
+  }
+  return false;
+}
+
+/* ══ Off switch & first aid ═══════════════════════════════════════════════════
+   A tool that can only be started is a trap: the person who installed it must be
+   able to stop it, see whether it is alive, and fix it when it is not — without
+   knowing what a process is. Hence `stop` / `status` / `restart` / `doctor`, and
+   the same words printed on the tool's own setup screen. */
+
+/** PIDs listening on a port, on any platform. Empty when nothing holds it. */
+function pidsOn(port) {
+  try {
+    if (isWin) {
+      const out = spawnSync('netstat', ['-ano'], { encoding: 'utf8', timeout: 6000 }).stdout || '';
+      return [
+        ...new Set(
+          out
+            .split('\n')
+            .filter((l) => l.includes(`:${port}`) && /LISTENING/i.test(l))
+            .map((l) => l.trim().split(/\s+/).pop())
+            .filter((p) => p && p !== '0')
+        ),
+      ];
+    }
+    const out = spawnSync('lsof', ['-ti', `tcp:${port}`, '-sTCP:LISTEN'], { encoding: 'utf8', timeout: 6000 }).stdout || '';
+    return out.split('\n').map((s) => s.trim()).filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+function killPid(pid) {
+  try {
+    if (isWin) spawnSync('taskkill', ['/PID', String(pid), '/F'], { stdio: 'ignore', timeout: 6000 });
+    else process.kill(Number(pid), 'SIGTERM');
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function isUp(port) {
+  try {
+    await fetch(`http://127.0.0.1:${port}/`, { signal: AbortSignal.timeout(1200) });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function cmdStatus() {
+  console.log(`\n${c.blue(c.b('  ◆ Qiksy'))}${c.dim('  — status')}\n`);
+  let anyUp = false;
+  for (const t of TOOLS) {
+    const up = await isUp(t.port);
+    anyUp ||= up;
+    console.log(up ? c.green(`  ✓ ${t.name.padEnd(18)} running · http://localhost:${t.port}`) : c.dim(`  · ${t.name.padEnd(18)} not running`));
+  }
+  console.log(
+    anyUp
+      ? c.dim('\n  Stop with:  npx qiksy stop\n')
+      : c.dim('\n  Start with: npx qiksy\n')
+  );
+}
+
+function cmdStop() {
+  console.log(`\n${c.blue(c.b('  ◆ Qiksy'))}${c.dim('  — stopping')}\n`);
+  let killed = 0;
+  for (const t of TOOLS) {
+    const pids = pidsOn(t.port);
+    if (!pids.length) {
+      console.log(c.dim(`  · ${t.name.padEnd(18)} was not running`));
+      continue;
+    }
+    for (const p of pids) if (killPid(p)) killed++;
+    console.log(c.green(`  ✓ ${t.name.padEnd(18)} stopped`));
+  }
+  console.log(c.dim(`\n  ${killed ? 'Everything is off.' : 'Nothing was running.'}  Start again: npx qiksy\n`));
+}
+
+async function cmdDoctor() {
+  console.log(`\n${c.blue(c.b('  ◆ Qiksy'))}${c.dim('  — checkup')}\n`);
+  const major = Number(process.versions.node.split('.')[0]);
+  console.log(major >= 18 ? c.green(`  ✓ Node.js ${process.versions.node}`) : c.red(`  ✗ Node.js ${process.versions.node} — needs 18 or newer`));
+  console.log(hasClaude() ? c.green('  ✓ Claude Code found') : c.amber('  ! Claude Code not found — install it from https://claude.com/claude-code'));
+  console.log(existsSync(DATA_HOME) ? c.green(`  ✓ Your data folder: ${DATA_HOME}`) : c.amber(`  ! No data folder yet (created on first run): ${DATA_HOME}`));
+
+  for (const t of TOOLS) {
+    const bundled = existsSync(join(PKG, 'tools', t.id, 'vendor', 'server.mjs'));
+    const up = await isUp(t.port);
+    const held = pidsOn(t.port);
+    if (!bundled) console.log(c.dim(`  · ${t.name.padEnd(18)} not in this build`));
+    else if (up) console.log(c.green(`  ✓ ${t.name.padEnd(18)} answering on ${t.port}`));
+    else if (held.length) console.log(c.amber(`  ! ${t.name.padEnd(18)} port ${t.port} is taken by something else (pid ${held.join(', ')})`));
+    else console.log(c.dim(`  · ${t.name.padEnd(18)} not running`));
+  }
+
+  console.log(c.dim('\n  If something is stuck:  npx qiksy restart'));
+  console.log(c.dim('  Your work is kept in the data folder above — restarting never deletes it.\n'));
+}
+
+const children = [];
+
+function start(tool) {
+  const dir0 = join(PKG, 'tools', tool.id, 'vendor');
+  const entry = join(dir0, 'server.mjs');
+  if (!existsSync(entry)) return null;
+  const dataDir = join(DATA_HOME, tool.id);
+  try {
+    mkdirSync(dataDir, { recursive: true });
+  } catch {
+    /* ignore */
+  }
+  const child = spawn(process.execPath, [entry], {
+    cwd: dir0,
+    env: { ...process.env, ...tool.env(dataDir, tool.port) },
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  // The backends are chatty; their logs belong in the engine's window, prefixed so a
+  // three-way tail stays readable.
+  const tag = c.dim(`[${tool.id}] `);
+  child.stdout?.on('data', (d) => process.stdout.write(String(d).replace(/^/gm, tag)));
+  child.stderr?.on('data', (d) => process.stderr.write(String(d).replace(/^/gm, tag)));
+  child.on('exit', (code) => {
+    if (code && code !== 0) console.log(c.red(`  ✗ ${tool.name} stopped (exit ${code})`));
+  });
+  children.push(child);
+  return child;
+}
+
+function stopAll() {
+  for (const ch of children) {
+    try {
+      ch.kill('SIGTERM');
+    } catch {
+      /* already gone */
+    }
+  }
+}
+process.on('SIGINT', () => {
+  console.log(c.dim('\n  Stopping…'));
+  stopAll();
+  process.exit(0);
+});
+process.on('SIGTERM', () => {
+  stopAll();
+  process.exit(0);
+});
+
+(async () => {
+  const cmd = (process.argv[2] || '').toLowerCase();
+
+  if (cmd === 'status') return cmdStatus();
+  if (cmd === 'stop') return cmdStop();
+  if (cmd === 'doctor' || cmd === 'check') return cmdDoctor();
+  if (cmd === 'help' || cmd === '--help' || cmd === '-h') {
+    console.log(`\n${c.blue(c.b('  ◆ Qiksy'))}${c.dim('  — your local engine')}\n`);
+    console.log('  npx qiksy            start everything (keep the window open)');
+    console.log('  npx qiksy status     what is running right now');
+    console.log('  npx qiksy stop       turn it off');
+    console.log('  npx qiksy restart    turn it off and on again');
+    console.log('  npx qiksy doctor     check what is wrong\n');
+    return;
+  }
+  if (cmd === 'restart') {
+    cmdStop();
+    // Give the OS a moment to release the ports before we bind them again.
+    await new Promise((r) => setTimeout(r, 1200));
+  }
+
+  console.log(`\n${c.blue(c.b('  ◆ Qiksy'))}${c.dim('  — your local engine')}`);
+  console.log(c.dim('  Runs on your own Claude · nothing leaves your machine\n'));
+
+  if (hasClaude()) {
+    console.log(c.green('  ✓ Claude Code detected\n'));
+  } else {
+    console.log(c.amber('  ! Claude Code not found on PATH'));
+    console.log(c.dim('    The tools still open and show you how to connect it.\n'));
+  }
+
+  const started = [];
+  for (const tool of TOOLS) {
+    const ch = start(tool);
+    if (ch) started.push(tool);
+    else console.log(c.dim(`  – ${tool.name} is not bundled in this build`));
+  }
+
+  if (!started.length) {
+    console.log(c.red('  ✗ Nothing to start — this package looks incomplete.'));
+    process.exit(1);
+  }
+
+  console.log(c.dim(`  Starting ${started.length} tool${started.length > 1 ? 's' : ''}…\n`));
+  const up = [];
+  for (const tool of started) {
+    const ok = await waitFor(tool.port);
+    console.log(
+      ok
+        ? c.green(`  ✓ ${tool.name.padEnd(18)} http://localhost:${tool.port}`)
+        : c.amber(`  ! ${tool.name.padEnd(18)} did not answer yet`)
+    );
+    if (ok) up.push(tool);
+  }
+
+  console.log('');
+  console.log(c.b('  Everything is running. Go back to your Qiksy tab — it connects on its own.'));
+  console.log(c.dim('  Keep this window open while you work.  Ctrl+C to stop.\n'));
+
+  if (up.length && !process.env.QIKSY_NO_OPEN) openBrowser('https://qiksy.app/');
+})();

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "qiksy",
+  "version": "1.0.0",
+  "description": "Qiksy — one local engine for every Qiksy tool (Work Finder, Travel Assistant, Client Finder). Runs on your own Claude; nothing leaves your machine.",
+  "type": "module",
+  "bin": {
+    "qiksy": "bin/qiksy.mjs"
+  },
+  "scripts": {
+    "start": "node bin/qiksy.mjs",
+    "bundle": "node scripts/bundle.mjs"
+  },
+  "files": [
+    "bin",
+    "tools",
+    "ARCHITECTURE.md",
+    "INSTALL-PROMPT.md",
+    "README.md"
+  ],
+  "keywords": [
+    "qiksy",
+    "claude",
+    "local-first",
+    "job-search",
+    "agents"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "UNLICENSED",
+  "homepage": "https://qiksy.app/"
+}

package/tools/client-finder/vendor/README.md

@@ -0,0 +1,70 @@
+# Client Finder — движок, этап 0
+
+**Критерии на входе → список покупателей с доказательствами на выходе.**
+Ни интерфейса, ни рассылки, ни браузера — только та часть, которая решает,
+существует ли продукт вообще. Полный план: [docs/CLIENT-FINDER.md](../../docs/CLIENT-FINDER.md).
+
+## Запуск
+
+```bash
+npm run find:clients products/client-finder-backend/icp/assist-ua-shops.json
+# или из этой папки:
+node find.mjs icp/assist-ua-shops.json --count 20 --model sonnet
+```
+
+Флаги: `--count` (сколько кандидатов, по умолчанию 12), `--model` (`sonnet` /
+`opus`), `--no-verify` (пропустить проверку ссылок).
+
+Результат — в `runs/`: `.json` для следующей стадии продукта и `.md`, который
+читает человек. Токены идут по **твоей** подписке Claude через CLI `claude`;
+прогон печатает, сколько потратил.
+
+## Критерий этапа 0
+
+Он назван заранее, чтобы «эффективно» потом не стало ощущением:
+
+1. Из 20 найденных контактов ты сам признаёшь годными **≥ 12** — «этим я бы написал».
+2. На эти 20 уходит **меньше времени**, чем на те же 20 руками.
+3. Через инструмент приходит **хотя бы одна реальная сделка студии**.
+
+Не выполнилось — продукта нет, и мы не построили под него витрину.
+
+## Как это устроено
+
+| Файл | Что делает |
+|---|---|
+| [find.mjs](find.mjs) | CLI: читает ICP, гоняет агента, проверяет, пишет отчёт |
+| [lib/agent.mjs](lib/agent.mjs) | запускает `claude -p` со stream-json; кандидаты стримятся строками `PROSPECT: {…}` по мере находки |
+| [lib/approver-mcp.mjs](lib/approver-mcp.mjs) | MCP-разрешалка: в `-p` режиме глобальный «ask» превращается в «deny» и глушит WebSearch/WebFetch — этот сервер их пропускает, а всё остальное (Bash, файлы) оставляет запрещённым |
+| [lib/prompts.mjs](lib/prompts.mjs) | **промпт и есть продукт** — контракт доказательств живёт здесь |
+| [lib/verify.mjs](lib/verify.mjs) | независимо дёргает каждую ссылку: агент сказал «я открыл» — проверяем, что страница есть |
+| [lib/report.mjs](lib/report.mjs) | markdown, который читаешь ты: зацепка, доказательства, честные пометки о мёртвых ссылках |
+| `icp/*.json` | сами критерии |
+
+## Почему без браузера
+
+Этап 0 ищет по публичному вебу — поиск и сайты компаний, этого достаточно.
+Playwright и залогиненные сессии означали бы ToS социальных сетей в продукте,
+которого ещё нет. Форма «агент находит и доказывает → пишет человек» появится
+на этапе 2, и появится осознанно.
+
+## Как писать ICP
+
+«Продай Assist» — не задача. Задача выглядит так: *владельцы магазинов на
+Shopify в Польше, у которых на сайте нет чата, писать по-польски, зацепка —
+конкретная страница их сайта*. Поля:
+
+- `who` — одно предложение, кто это;
+- `must` — критерии, каждый из которых агент обязан **проверить на странице**;
+- `mustNot` — то, что дисквалифицирует (и агент обязан сказать, что проверил);
+- `signals` — не обязательные признаки, поднимают уверенность;
+- `geo`, `language`, `contact`, `avoid`.
+
+Чем конкретнее `must`, тем меньше мусора: критерий, который нельзя проверить
+на странице, агент проверить не сможет — и либо соврёт, либо выкинет кандидата.
+
+## Персональные данные
+
+`runs/` **не коммитится** — там имена, почты и сайты живых людей. Хранится
+локально, у тебя. Когда дойдёт до продукта, срок хранения и право на удаление
+надо будет прописать (см. открытые вопросы в docs/CLIENT-FINDER.md).

package/tools/client-finder/vendor/find.mjs

@@ -0,0 +1,121 @@
+#!/usr/bin/env node
+/**
+ * Client Finder — stage 0: criteria in, a checkable list of buyers out.
+ *
+ *   node find.mjs icp/assist-shopify-pl.json            # 12 prospects (default)
+ *   node find.mjs icp/assist-shopify-pl.json --count 20
+ *   node find.mjs icp/… --model opus --no-verify
+ *
+ * No UI, no outreach, no browser — the whole point of this stage is to learn
+ * whether the engine can find people the owner would actually write to. Everything
+ * else waits until it can (see docs/CLIENT-FINDER.md).
+ *
+ * Costs run on YOUR Claude subscription/key via the `claude` CLI; the run prints
+ * what it spent.
+ */
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { resolve, dirname, basename } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { runClaude, extractJson } from './lib/agent.mjs';
+import { researchPrompt } from './lib/prompts.mjs';
+import { verifyAll } from './lib/verify.mjs';
+import { toMarkdown } from './lib/report.mjs';
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)));
+
+/* ── args ─────────────────────────────────────────────────────────────────── */
+const argv = process.argv.slice(2);
+const flag = (name, fallback) => {
+  const i = argv.indexOf(`--${name}`);
+  return i >= 0 && argv[i + 1] && !argv[i + 1].startsWith('--') ? argv[i + 1] : fallback;
+};
+const has = (name) => argv.includes(`--${name}`);
+
+const icpPath = argv.find((a) => !a.startsWith('--'));
+if (!icpPath) {
+  console.error('Usage: node find.mjs <icp.json> [--count 12] [--model sonnet] [--no-verify]');
+  process.exit(1);
+}
+const count = Number(flag('count', 12));
+const model = flag('model', 'sonnet');
+
+// Accept the path as typed: from the repo root (`npm run find:clients -- products/…`)
+// or from this folder (`node find.mjs icp/…`). Both are natural; failing on one of
+// them is just a papercut in the way of the first run.
+const icpFile = [resolve(process.cwd(), icpPath), resolve(ROOT, icpPath)].find(existsSync);
+if (!icpFile) {
+  console.error(`✗ ICP not found: ${icpPath} (looked in ${process.cwd()} and ${ROOT})`);
+  process.exit(1);
+}
+/** @type {import('./lib/prompts.mjs').Icp} */
+const icp = JSON.parse(readFileSync(icpFile, 'utf8'));
+
+/* ── run ──────────────────────────────────────────────────────────────────── */
+const started = new Date();
+console.log(`\n🎯 ${icp.product.name} · ICP «${icp.id}» · цель: ${count} кандидатов · модель ${model}`);
+console.log(`   ${icp.who}\n`);
+
+const streamed = [];
+const t0 = Date.now();
+
+const res = await runClaude({
+  prompt: researchPrompt(icp, count),
+  model,
+  onEvent: (line) => process.stdout.write(`   ${line}\n`),
+  onPartial: (p) => {
+    streamed.push(p);
+    console.log(`\n✅ ${streamed.length}. ${p.company} — ${p.url}`);
+    if (p.hook) console.log(`   зацепка: ${p.hook}`);
+  },
+});
+
+if (!res.ok) {
+  console.error(`\n✗ агент упал: ${res.error}`);
+  process.exit(1);
+}
+
+// The final fenced array is authoritative (a streamed line can be malformed); fall
+// back to what streamed if the agent forgot the closing array.
+const parsed = extractJson(res.result);
+let prospects = Array.isArray(parsed) ? parsed : Array.isArray(parsed?.prospects) ? parsed.prospects : streamed;
+if (!prospects.length) prospects = streamed;
+
+console.log(`\n📋 агент вернул ${prospects.length} кандидат(ов) за ${Math.round(res.durationMs / 1000)}с${res.costUsd != null ? ` · $${res.costUsd.toFixed(2)}` : ''}`);
+
+/* ── verify ───────────────────────────────────────────────────────────────── */
+if (!has('no-verify')) {
+  console.log(`\n🔎 проверяю ссылки (сайт + каждый источник)…`);
+  prospects = await verifyAll(prospects, (p) => {
+    const v = p.verified;
+    const mark = !v.siteAlive ? '🔴' : v.dead.length ? '🟠' : v.blocked.length ? '🟡' : '🟢';
+    console.log(`   ${mark} ${p.company} — проверено ${v.checked}${v.dead.length ? `, мёртвых ${v.dead.length}` : ''}`);
+  });
+}
+
+/* ── write ────────────────────────────────────────────────────────────────── */
+const meta = {
+  icp: icp.id,
+  model,
+  startedAt: started.toISOString(),
+  finishedAt: new Date().toISOString(),
+  durationMs: Date.now() - t0,
+  costUsd: res.costUsd,
+  requested: count,
+  returned: prospects.length,
+  notes: String(res.result || '')
+    .replace(/```json[\s\S]*?```/g, '')
+    .trim()
+    .slice(-1200),
+};
+
+const runsDir = resolve(ROOT, 'runs');
+mkdirSync(runsDir, { recursive: true });
+const stamp = started.toISOString().replace(/[:.]/g, '-').slice(0, 19);
+const slug = `${stamp}-${basename(icpPath).replace(/\.json$/, '')}`;
+writeFileSync(resolve(runsDir, `${slug}.json`), JSON.stringify({ icp, meta, prospects }, null, 2));
+writeFileSync(resolve(runsDir, `${slug}.md`), toMarkdown({ icp, prospects, meta }));
+
+const clean = prospects.filter((p) => p.verified?.ok !== false).length;
+console.log(`\n📄 runs/${slug}.md`);
+console.log(`   ${prospects.length} кандидат(ов), из них ${clean} прошли проверку ссылок`);
+console.log(`\nКритерий этапа 0: скольким из них ты бы написал? Нужно ≥ 12 из 20.\n`);