qiksy 1.0.0

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

@@ -0,0 +1,390 @@
+#!/usr/bin/env node
+/**
+ * Client Finder — the local server behind the panel.
+ *
+ *   npm run backend:cf        # → http://localhost:5546
+ *
+ * Local-first, exactly like Work Finder and Travel: it runs on the seller's own
+ * machine, spends the seller's own Claude key through the `claude` CLI, and writes
+ * results to their disk. Nothing about a prospect ever reaches us.
+ *
+ * The panel is a thin client over four calls: what can I sell (`/api/state`), is
+ * this brief allowed (`/api/check`), go (`/api/run`), how is it going
+ * (`/api/jobs/:id`). The guard on `/api/check` and `/api/run` is plain JavaScript
+ * and runs before any token is spent — see lib/scope.mjs for why that matters.
+ */
+import { createServer } from 'node:http';
+import { writeFileSync, mkdirSync } from 'node:fs';
+import { resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { runClaude, extractJson } from './lib/agent.mjs';
+import { researchPrompt, briefToIcp, draftPrompt } from './lib/prompts.mjs';
+import { checkBrief } from './lib/scope.mjs';
+import { PRODUCTS, byId } from './lib/catalog.mjs';
+import { CHANNELS, needsBrowser } from './lib/channels.mjs';
+import { FORMATS, formatById, checkDraft } from './lib/formats.mjs';
+import { verifyAll, verifyProspect } from './lib/verify.mjs';
+import { toMarkdown } from './lib/report.mjs';
+import { createJob, getJob, view, listJobs, log, cancel } from './lib/jobs.mjs';
+import { status as browserStatus, connect as browserConnect, openTab } from './lib/browser.mjs';
+import { deliveryFor } from './lib/deliver.mjs';
+import { checkPartner } from './lib/access.mjs';
+import { probeEngine, startLogin, submitLoginCode } from './lib/engine.mjs';
+
+/* A REAL Anthropic key, not merely something that starts with "sk-".
+   That looser check let the literal `sk-subscription` through — a placeholder a
+   previous panel sent when the machine was signed in with a subscription — and it was
+   then exported as ANTHROPIC_API_KEY, overriding that very sign-in. Every run failed
+   with "Invalid API key" for exactly the setup the subscription path exists for.
+   Empty means "use whatever auth this machine already has", which is what we want. */
+const isRealKey = (v) => typeof v === 'string' && /^sk-ant-/.test(v.trim());
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)));
+const PORT = Number(process.env.PORT) || 5546;
+
+/** Origins allowed to drive this server: the panel in dev, the hub, and prod. */
+const UI_ORIGINS = new Set([
+  'http://localhost:4311', // the panel in dev (port assigned by scripts/new-app.mjs)
+  'http://localhost:4300',
+  'http://localhost:8199',
+  'https://qiksy.app',
+]);
+
+const json = (res, code, body) => {
+  res.writeHead(code, { 'Content-Type': 'application/json; charset=utf-8' });
+  res.end(JSON.stringify(body));
+};
+
+const readBody = (req) =>
+  new Promise((res) => {
+    let b = '';
+    req.on('data', (c) => (b += c));
+    req.on('end', () => {
+      try {
+        res(JSON.parse(b || '{}'));
+      } catch {
+        res({});
+      }
+    });
+  });
+
+/* ── the run ──────────────────────────────────────────────────────────────── */
+
+async function execute(job) {
+  const product = byId(job.input.productId);
+  const icp = briefToIcp({ product, brief: job.input.brief, channels: job.input.channels });
+
+  job.phase = 'searching';
+  log(job, `Ищу покупателей для «${product.name}»`);
+  if (needsBrowser(job.input.channels)) {
+    // Browser channels are declared but not wired yet: say so out loud rather than
+    // silently searching the open web and letting the picked channel imply more
+    // than happened.
+    log(job, '⚠ Каналы с логином (LinkedIn и др.) пока не подключены — этот прогон идёт по открытому вебу');
+  }
+
+  const res = await runClaude({
+    prompt: researchPrompt(icp, job.input.count),
+    model: job.input.model,
+    apiKey: job.input.apiKey,
+    signal: job.controller.signal,
+    onEvent: (line) => log(job, line),
+    /* Verify AS IT ARRIVES, not once at the end.
+       A prospect streamed mid-run used to carry no `verified` field at all, and the
+       final sweep ran after the cancelled/failed early-returns — so a run stopped at
+       7 of 10, or timed out, left every row unproven while the UI showed nothing
+       about it. On a product whose landing sells "проверенные ссылки" that is the
+       worst possible silence. Pure HTTP: no model, no tokens. */
+    onPartial: (p) => {
+      job.prospects.push(p);
+      log(job, `✅ ${job.prospects.length}. ${p.company}`);
+      void verifyProspect(p)
+        .then((v) => Object.assign(p, { verified: v.verified }))
+        .catch(() => {
+          /* a blip — the final sweep still covers it */
+        });
+    },
+  });
+
+  if (job.status === 'cancelled') return;
+
+  if (!res.ok) {
+    job.status = 'failed';
+    /* A twenty-minute wait should not be rewarded with `timeout after 1200s`. The
+       findings are real and writable — say that, because the panel now allows
+       drafting from a stopped run. */
+    job.error = /timeout/i.test(String(res.error))
+      ? 'Прогон шёл 20 минут и остановлен по лимиту. Найденное осталось — писать по нему можно.'
+      : res.error;
+    job.errorRaw = res.error;
+    job.finishedAt = Date.now();
+    return;
+  }
+
+  job.costUsd = res.costUsd;
+
+  // The model-side backstop fired: the brief looked like a brief to the guard but
+  // was not one. Surface it as a refusal, not as an empty result.
+  const refusal = String(res.result || '').match(/OUT_OF_SCOPE:\s*(\{.*\})/);
+  if (refusal) {
+    job.status = 'refused';
+    try {
+      job.error = JSON.parse(refusal[1]).say || 'Это вне задачи панели.';
+    } catch {
+      job.error = 'Это вне задачи панели.';
+    }
+    job.finishedAt = Date.now();
+    return;
+  }
+
+  const parsed = extractJson(res.result);
+  let prospects = Array.isArray(parsed) ? parsed : Array.isArray(parsed?.prospects) ? parsed.prospects : job.prospects;
+  if (!prospects.length) prospects = job.prospects;
+
+  /* The final array parsed from the model is a DIFFERENT array than the streamed one,
+     so the verdicts earned above have to be carried across by url — otherwise every
+     page is fetched a second time for an answer already in hand. */
+  const alreadyKnown = new Map(job.prospects.filter((p) => p.verified).map((p) => [p.url, p.verified]));
+  for (const p of prospects) {
+    if (!p.verified && alreadyKnown.has(p.url)) p.verified = alreadyKnown.get(p.url);
+  }
+
+  job.phase = 'verifying';
+  log(job, `Проверяю ссылки у ${prospects.length} кандидат(ов)…`);
+  prospects = await verifyAll(prospects, (p) => {
+    const v = p.verified;
+    log(job, `${!v.siteAlive ? '🔴' : v.dead.length ? '🟠' : '🟢'} ${p.company}`);
+  });
+
+  job.prospects = prospects;
+  job.phase = 'done';
+  job.status = 'done';
+  job.finishedAt = Date.now();
+
+  // Results live on the seller's disk, in the same folder the CLI writes to, so
+  // both entry points produce one history rather than two.
+  try {
+    // CF_DATA_DIR lets a packaged install keep results in the user's own folder
+    // (~/.qiksy/client-finder). Without it they would land inside the npx cache, which
+    // is wiped without warning. Unset → the CLI's own folder, so both entry points
+    // still write one history.
+    const runs = process.env.CF_DATA_DIR ? resolve(process.env.CF_DATA_DIR, 'runs') : resolve(ROOT, 'runs');
+    mkdirSync(runs, { recursive: true });
+    const stamp = new Date(job.startedAt).toISOString().replace(/[:.]/g, '-').slice(0, 19);
+    const meta = {
+      icp: 'panel',
+      model: job.input.model,
+      startedAt: new Date(job.startedAt).toISOString(),
+      finishedAt: new Date().toISOString(),
+      durationMs: job.finishedAt - job.startedAt,
+      costUsd: job.costUsd,
+      requested: job.input.count,
+      returned: prospects.length,
+      notes: `Панель · продукт ${product.name} · каналы: ${job.input.channels.join(', ') || 'web'}`,
+    };
+    writeFileSync(resolve(runs, `${stamp}-panel.json`), JSON.stringify({ icp, meta, prospects }, null, 2));
+    writeFileSync(resolve(runs, `${stamp}-panel.md`), toMarkdown({ icp, prospects, meta }));
+  } catch (e) {
+    log(job, `не смог записать отчёт: ${e.message}`);
+  }
+}
+
+/* ── http ─────────────────────────────────────────────────────────────────── */
+
+const server = createServer(async (req, res) => {
+  const url = new URL(req.url, 'http://x');
+  const path = url.pathname;
+  const seg = path.split('/').filter(Boolean);
+
+  const origin = req.headers.origin;
+  if (origin && UI_ORIGINS.has(origin)) {
+    res.setHeader('Access-Control-Allow-Origin', origin);
+    res.setHeader('Vary', 'Origin');
+    if (req.method === 'OPTIONS') {
+      // Chrome Private Network Access: a PUBLIC page (qiksy.app, https) reaching this
+      // LOCAL server (localhost) is blocked unless the preflight is answered with this
+      // header. Without it the panel connects from the dev origin but never from the
+      // live domain — which reads to the user as "engine not running".
+      if (req.headers['access-control-request-private-network'] === 'true') {
+        res.setHeader('Access-Control-Allow-Private-Network', 'true');
+      }
+      res.writeHead(204, {
+        'Access-Control-Allow-Methods': 'GET,POST,OPTIONS',
+        'Access-Control-Allow-Headers': 'Content-Type',
+        'Access-Control-Max-Age': '86400',
+      });
+      return res.end();
+    }
+  }
+
+  try {
+    /* Start Anthropic's own sign-in on this machine and hand back ITS link, so the
+       panel can offer "open" and "copy" instead of firing a browser off-screen. We
+       never build a "connect with Claude" of our own — this launches theirs, and the
+       panel polls /api/engine until it turns green. */
+    if (req.method === 'POST' && path === '/api/engine/login') {
+      return json(res, 200, await startLogin());
+    }
+
+    /* The callback page shows a code instead of redirecting when it cannot reach the
+       CLI's loopback (another machine, or a browser that won't open localhost). This
+       is where that code goes. */
+    if (req.method === 'POST' && path === '/api/engine/login/code') {
+      const { code } = await readBody(req);
+      return json(res, 200, submitLoginCode(code));
+    }
+
+    /* Can this machine run the agent at all? The gate asks BEFORE demanding a key,
+       because the CLI may already be logged in with a Claude subscription — in which
+       case a key is not just optional, it is irrelevant. ?force=1 re-probes after the
+       user has gone and logged in. */
+    if (req.method === 'GET' && path === '/api/engine') {
+      const force = /[?&]force=1/.test(req.url || '');
+      return json(res, 200, await probeEngine({ force }));
+    }
+
+    if (req.method === 'GET' && path === '/api/state') {
+      return json(res, 200, { products: PRODUCTS, channels: CHANNELS, formats: FORMATS, jobs: listJobs() });
+    }
+
+    // Validate as you type. Free — no model, no tokens.
+    if (req.method === 'POST' && path === '/api/check') {
+      const { brief } = await readBody(req);
+      return json(res, 200, checkBrief(brief));
+    }
+
+    if (req.method === 'POST' && path === '/api/access') {
+      const { partner, account } = await readBody(req);
+      return json(res, 200, await checkPartner(partner, account));
+    }
+
+    if (req.method === 'POST' && path === '/api/run') {
+      const body = await readBody(req);
+      const access = await checkPartner(body.partner, body.account);
+      if (!access.ok) return json(res, 403, { reason: 'Доступ только для партнёров', hint: access.reason });
+      const product = byId(body.productId);
+      // The product is a choice from OUR catalog, never free text — that is what
+      // makes "sell my own thing here" structurally impossible rather than merely
+      // discouraged.
+      if (!product) return json(res, 400, { error: 'Выберите продукт из списка' });
+
+      const guard = checkBrief(body.brief);
+      if (!guard.ok) return json(res, 422, guard);
+
+      const job = createJob({
+        productId: product.id,
+        channels: Array.isArray(body.channels) && body.channels.length ? body.channels : ['web'],
+        brief: String(body.brief).trim(),
+        /* Only a REAL key travels on. Anything else — a placeholder from a stale
+           client, junk from a typo — would be exported as ANTHROPIC_API_KEY and
+           override the machine's own Claude sign-in, breaking the subscription path
+           for the one user it exists for. Empty means "use whatever this machine
+           already has", which is exactly right. */
+        apiKey: typeof body.apiKey === 'string' && isRealKey(body.apiKey) ? body.apiKey : '',
+        count: Math.min(Math.max(Number(body.count) || 10, 1), 30),
+        model: body.model === 'opus' ? 'opus' : 'sonnet',
+      });
+      // Fire and forget: the panel polls /api/jobs/:id.
+      execute(job).catch((e) => {
+        job.status = 'failed';
+        job.error = e.message;
+        job.finishedAt = Date.now();
+      });
+      return json(res, 200, view(job));
+    }
+
+
+    /* ── drafts ───────────────────────────────────────────────────────────────
+     * A separate, cheap pass over prospects we already verified: no web tools, no
+     * second search. That also makes re-drafting the same list for another
+     * platform free of another research bill.
+     */
+    if (req.method === 'POST' && path === '/api/draft') {
+      const body = await readBody(req);
+      const access = await checkPartner(body.partner, body.account);
+      if (!access.ok) return json(res, 403, { error: access.reason });
+      const job = getJob(body.jobId);
+      if (!job) return json(res, 404, { error: 'нет такого прогона' });
+      const product = byId(job.input.productId);
+      const format = formatById(body.format);
+      const picked = Array.isArray(body.indexes) && body.indexes.length
+        ? body.indexes.map((i) => job.prospects[i]).filter(Boolean)
+        : job.prospects;
+      if (!picked.length) return json(res, 400, { error: 'нечего писать — список пуст' });
+
+      const out = await runClaude({
+        prompt: draftPrompt({
+          product,
+          prospects: picked,
+          format,
+          sender: body.sender,
+          language: body.language,
+          platform: body.platform,
+        }),
+        model: job.input.model,
+        /* Same rule, and the job's own key as the fallback — it was filtered by the
+           same check when the run started. */
+        apiKey:
+          typeof body.apiKey === 'string' && isRealKey(body.apiKey)
+            ? body.apiKey
+            : job.input.apiKey || '',
+        // Drafting reads what we already proved; giving it the web again would
+        // invite it to "check something" and pay for a second research run.
+        allowedTools: [],
+      });
+      if (!out.ok) return json(res, 500, { error: out.error });
+
+      const parsed = extractJson(out.result);
+      const list = Array.isArray(parsed) ? parsed : [];
+      const drafts = picked.map((p, i) => {
+        const d = list[i] || {};
+        return {
+          company: p.company,
+          url: p.url,
+          contact: p.contact || null,
+          subject: d.subject || '',
+          body: d.body || '',
+          check: checkDraft(format, d),
+        };
+      });
+      return json(res, 200, { format: format.id, costUsd: out.costUsd, drafts });
+    }
+
+
+    /* ── browser ("выход в браузер") ──────────────────────────────────────────
+     * A switch, not a mode of operation: off, drafts land in the panel and you
+     * paste them yourself; on, we open the right window in a Chrome you are
+     * logged into. Pressing send stays yours either way — that is the line
+     * between a tool and the automation that gets accounts restricted.
+     */
+    if (req.method === 'GET' && path === '/api/browser') {
+      return json(res, 200, await browserStatus());
+    }
+    if (req.method === 'POST' && path === '/api/browser/connect') {
+      return json(res, 200, await browserConnect());
+    }
+    if (req.method === 'POST' && path === '/api/browser/open') {
+      const { format, draft } = await readBody(req);
+      if (!draft) return json(res, 400, { error: 'нечего открывать' });
+      const plan = deliveryFor(String(format || 'email'), draft);
+      const out = await openTab(plan.url);
+      return json(res, out.ok ? 200 : 409, { ...plan, ...out });
+    }
+
+    if (req.method === 'GET' && seg[1] === 'jobs' && seg[2]) return json(res, 200, view(getJob(seg[2])));
+    if (req.method === 'POST' && seg[1] === 'jobs' && seg[2] && seg[3] === 'cancel') {
+      return json(res, 200, { ok: cancel(seg[2]) });
+    }
+    if (req.method === 'GET' && path === '/api/jobs') return json(res, 200, listJobs());
+
+    json(res, 404, { error: 'not found' });
+  } catch (e) {
+    json(res, 500, { error: e.message });
+  }
+});
+
+server.listen(PORT, () => {
+  console.log(`\n🔎 Client Finder backend → http://localhost:${PORT}`);
+  console.log(`   продуктов в каталоге: ${PRODUCTS.length} · каналов: ${CHANNELS.filter((c) => c.ready).length} готов(ы)`);
+  console.log(`   панель: http://localhost:4309\n`);
+});

package/tools/travel/vendor/README.md

@@ -0,0 +1,58 @@
+# Travel Assistant (web)
+
+Ассистент поездок: headless-агенты Claude Code ищут в вебе билеты, отели и трансферы под маршрут, даты, класс и приоритет, а браузерный агент (Playwright MCP + Chrome) доводит выбранный вариант до **экрана оплаты** и останавливается — карту вводит только человек.
+
+**Кому это (решение владельца 25.07.2026).** Основной сценарий — HR, который возит людей на конференции и встречи («Киев → Брюссель, отель рядом с площадкой, трансфер»). Тот же инструмент закрывает турагентство (много клиентов, каждому — своё предложение) и человека, который планирует поездку себе и семье. Тариф считает **группы**, а не людей: бесплатно — одна своя группа, платно — клиенты/сотрудники без лимита.
+
+**Чем отличается от глобальных AI-планировщиков.** Агент обязан проверить **локальный рынок обоих городов**, а не только Booking/Google Flights: национальные ЖД, местное приложение такси, локальные сервисы аренды квартир, прямой тариф отеля — и честно предупредить, если местный сервис требует локальный номер телефона или не принимает иностранную карту.
+
+## Запуск
+
+```bash
+npm start          # сервер → http://localhost:5545
+npm run browser    # поднять/переиспользовать CDP Chrome на :9222 (для оформления броней)
+```
+
+Требуется: Node 18+, Claude Code CLI (`claude`) с активной подпиской, Google Chrome.
+
+Переменные окружения: `TA_PORT` — порт сервера (по умолчанию 5545), `TA_DB` — путь к базе (по умолчанию `data/db.json`).
+
+## Как пользоваться
+
+1. **Путешественники** — плитка группы («Я и моя семья» или клиент агентства) + карточки людей внутри (ФИО, паспорт, лояльность, особенности). Свежая установка пустая; данные живут только локально в `data/db.json`. Каждая следующая группа = клиент, это платный тариф.
+2. **Консоль на главном экране** — «[кто едет] едет в [город]», откуда/туда/обратно, бюджет, состав, **класс** (эконом · премиум · бизнес) и **приоритет** (дешевле · оптимально · быстрее · комфорт), что искать — и одна кнопка, которая создаёт поездку и сразу запускает агента. Редкое (критерии текстом, маршрут-цепочка, встреча) — за «Больше параметров».
+3. **Поиск** — агент идёт по источникам (Google Flights → Skyscanner → Kiwi; Booking → Airbnb; аэроэкспрессы → Welcome Pickups), учитывает тайминг прилёта против времени встречи и часовые пояса, найденные варианты прилетают в карточку поездки вживую. Итог: до 5 вариантов + рекомендация связки.
+4. **«Оформить №N»** — браузерный агент открывает вариант в новой вкладке, заполняет пассажира по карточке (как гость, без создания аккаунтов) и **останавливается на экране оплаты**. Отчёт: что заполнено, итоговая сумма, предупреждения. Капча или логин — агент вернёт ссылку для ручного продолжения.
+5. **«Оплачено ✓»** — после оплаты картой ассистент генерирует три блока для копирования: письмо путнику, смету расходов (с суточными, если заданы) и чеклист перед поездкой.
+6. **«Предложение клиенту»** (Pro) — вся подборка одной самодостаточной HTML-страницей под именем агентства: маршрут, кто едет, варианты с ценами, рекомендованная связка. Открыть, отправить, распечатать в PDF. Генерируется локально (`lib/proposal.mjs`), данные клиента машину не покидают.
+
+**Пока агент работает** видно, что он делает словами — «ищу…», «читаю skyup.aero», «нашёл: Motel One» — плюс список пройденных источников, таймер и счётчик найденного; сырой лог инструментов свёрнут под «Технический лог». Джобы живут в памяти, поэтому при перезапуске сервера зависшие поездки откатываются сами (`searching → draft`, `booking → options`) с записью в истории поездки.
+
+## Настройки
+
+- **Модель**: haiku (дёшево) / sonnet (баланс, по умолчанию) / opus.
+- **Поиск через браузер** — глубже (сайты с логином), но медленнее; по умолчанию поиск идёт через WebSearch/WebFetch.
+- **Доп. инструкции** — свободный текст, попадает в промпт поиска.
+- **Корпоративные дефолты** — юр.лицо для счетов, класс перелёта/поезда, звёздность отеля, per diem, валюта.
+
+## Архитектура
+
+```
+server.mjs            Node http (без зависимостей), порт 5545, только 127.0.0.1
+lib/store.mjs         data/db.json — команда, поездки, настройки (+ демо-сид)
+lib/agent.mjs         запуск `claude -p` (stream-json), парсинг результата
+lib/prompts.mjs       промпты: поиск / оформление / финальные документы
+lib/jobs.mjs          очередь фоновых задач (макс. 2 агента параллельно)
+scripts/approver-mcp.mjs    MCP-сервер разрешений для headless-агентов
+scripts/launch-browser.mjs  CDP Chrome на :9222 (переиспользует запущенный)
+public/               UI (vanilla JS)
+```
+
+**Разрешения агентов:** в глобальных `~/.claude/settings.json` инструменты WebSearch/WebFetch стоят в списке `ask`, что в headless-режиме означает автоотказ. Поэтому агенты запускаются с `--permission-prompt-tool mcp__approver__approve` — мини-MCP-сервер одобряет только белый список (WebSearch, WebFetch, mcp__playwright__*), всё прочее запрещено. `--tools` жёстко ограничивает встроенный набор (агентам недоступны Bash/Edit/Write).
+
+## Безопасность
+
+- **Карту вводит только человек.** Агент никогда не вводит номер карты/CVC/срок и не нажимает Pay/Confirm/Buy — это прошито в промпт оформления и продублировано в UI.
+- Паспортные данные живут только в локальном `data/db.json`: в поисковый промпт не попадают, в логах джобов маскируются (`FK1***56`), дев-сервер студии их не раздаёт.
+- Агент не создаёт аккаунты и не вводит пароли; при капче/логине останавливается и передаёт ссылку HR.
+- Сервер слушает только `127.0.0.1`.

package/tools/travel/vendor/docs/CONTRACT.md

@@ -0,0 +1,174 @@
+# Travel Assistant (web) — контракт архитектуры
+
+Веб-версия ассистента `~/Desktop/travel-assistant/` (Cowork + CLAUDE.md). Архитектура — точная калька с Work Finder (`~/Desktop/work-finder/`): zero-dependency Node http-сервер + headless-агенты `claude -p` + vanilla JS UI. Этот файл — контракт между backend, frontend и тестами. Менять контракт можно только синхронно во всех трёх местах.
+
+## Мета
+
+- Папка: `qiksy-studio/products/travel-assistant/`
+- Порт: **5545** (у Work Finder — 5544). Переопределяется env `TA_PORT`, а не `PORT` — общий `PORT` читают чужие дев-серверы в воркспейсе, и коллизия увела бы бэкенд не на тот порт.
+- Путь к базе: `data/db.json`, переопределяется env `TA_DB` (нужно тестам).
+- Node ≥ 18, **без npm-зависимостей**. `npm start` → `node server.mjs`.
+- Язык UI и всех текстов — **русский**.
+- Домен и правила поведения агентов берём из `~/Desktop/travel-assistant/CLAUDE.md` (источники поиска, тайминги/часовые пояса, критерии, «не выдумывай», ≤5 вариантов, рейтинг ≥7.0, стоп перед оплатой).
+
+## Файлы (владение при сборке)
+
+```
+products/travel-assistant/
+  server.mjs                 # http-сервер + роутинг + статика public/   [BE]
+  lib/store.mjs              # db.json: load/save (атомарно), seed        [BE]
+  lib/jobs.mjs               # очередь фоновых задач (макс 2)             [BE]
+  lib/agent.mjs              # запуск claude -p, парсинг stream-json      [BE]
+  lib/prompts.mjs            # промпты: search / book / finalize          [BE]
+  scripts/approver-mcp.mjs   # MCP-сервер разрешений для headless-агентов [BE]
+  scripts/launch-browser.mjs # CDP Chrome :9222 (переиспользует живой)    [BE]
+  package.json               # name, scripts: start, browser              [BE]
+  README.md                  # как запустить + что умеет                  [BE]
+  public/index.html          # разметка всех вью                          [FE]
+  public/app.js              # состояние, поллинг, рендер                 [FE]
+  public/styles.css          # дизайн-токены + компоненты                 [FE]
+  docs/CONTRACT.md           # этот файл
+```
+
+Тесты: `qiksy-studio/tests/travel-assistant.spec.mjs` [TESTS].
+
+## Схема db.json
+
+```jsonc
+{
+  "team": [{
+    "id": "t_abc123", "nameRu": "Иванов Алексей Сергеевич", "nameEn": "Ivanov Oleksii",
+    "position": "Senior Backend Developer", "dob": "14.03.1990", "gender": "М",
+    "citizenship": "Ukraine", "passportNo": "FK123456", "passportValidUntil": "22.08.2030",
+    "email": "a.ivanov@company.com", "phone": "+380 67 111 22 33",
+    "loyaltyAir": "Lufthansa Miles&More 992100012345", "loyaltyHotel": "Booking Genius (level 2)",
+    "notes": "окно, не любит ранние рейсы до 7:00, рост 192 см — Economy Plus / exit row",
+    "demo": true
+  }],
+  "corporate": {
+    "legalEntity": "", "travelAgency": "", "geniusLevel": "", "airlineCodes": "",
+    "insurance": "", "transferVendor": "",
+    "flightClass": "эконом", "trainClass": "2 класс", "hotelStars": "3-4*",
+    "perDiem": "", "hrTimezone": "Europe/Kyiv", "currency": "EUR"
+  },
+  "trips": [{
+    "id": "trip_abc123", "createdAt": 0, "updatedAt": 0,
+    "title": "Львов → Берлин",            // генерится из from/to если пусто
+    "travelerIds": ["t_abc123"],
+    "from": "Львов", "to": "Берлин",
+    "departDate": "2026-08-15", "returnDate": "2026-08-20",   // return может быть ""
+    "meetingAt": "встреча 10:00 16 августа",                   // опционально
+    "budget": "до 400€ на всё",                                // свободный текст
+    "needTransport": true, "needHotel": true, "needTransfer": "auto", // auto|yes|no
+    "criteria": "без пересадок, отель ближе к Alexanderplatz",
+    "status": "draft",   // draft|searching|options|booking|ready_to_pay|paid|cancelled
+    "options": [],        // см. «Формат Option»
+    "summary": "",        // абзац-резюме от поискового агента
+    "recommendation": { "text": "", "ids": [], "comboTotal": "" },
+    "bookingReports": [], // [{ optionN, text, stoppedAt, totalShown, warnings:[], at }]
+    "blocks": { "letter": "", "costTable": "", "checklist": "" },
+    "activity": []        // [{ at, text }] — журнал событий поездки
+  }],
+  "settings": { "model": "sonnet", "browserSearch": false, "extraInstructions": "" }
+}
+```
+
+Статусная машина поездки: `draft → searching → options → booking → ready_to_pay → paid`; `cancelled` — из любого статуса; повторный поиск разрешён из `options` (перезаписывает options). Ошибка джоба возвращает статус назад (`searching→draft`, `booking→options`).
+
+Seed: при первом старте (нет db.json) — 5 демо-карточек команды из CLAUDE.md ассистента (Иванов, Кравченко, Мельник, Шевченко, Бондар; `demo: true`), corporate/settings по умолчанию, trips пустой.
+
+## Формат Option (выход поискового агента, элемент `trip.options`)
+
+```jsonc
+{
+  "n": 1,                       // сквозная нумерация: транспорт сначала, отели после
+  "kind": "flight",             // flight|train|bus|hotel|transfer
+  "title": "Wizz Air W6 6051",  // отель: название отеля
+  "brand": "Wizz Air",
+  "price": { "amount": 89, "currency": "EUR", "unit": "total" },  // unit: total|per_night
+  "badge": "recommended",       // recommended|cheapest|null
+  "link": "https://...",        // прямая ссылка на бронирование, НЕ главная страница
+  "notes": "",
+  // транспорт (flight/train/bus):
+  "depart": { "time": "14:30", "date": "2026-08-15", "place": "Львов LWO" },
+  "arrive": { "time": "16:05", "date": "2026-08-15", "place": "Берлин BER" },
+  "duration": "2 ч 35 мин", "direct": true,
+  "stops": [],                  // [{ "place": "Варшава WAW", "wait": "1 ч 20 мин" }]
+  "baggage": "ручная кладь 10 кг включена, багаж 20 кг +35€",
+  // отель (hotel):
+  "rating": { "score": 9.2, "reviews": 4494 }, "stars": 4,
+  "address": "Invalidenstraße 54, Mitte", "distanceKm": 1.1,
+  "nights": 5, "pricePerNight": 84, "totalPrice": 420,
+  "amenities": [{ "label": "бесплатная отмена", "green": true }, { "label": "Wi-Fi", "green": false }],
+  // трансфер (transfer):
+  "service": "FEX (аэропортовый экспресс)", "pickupAt": "BER T1", "vehicle": ""
+}
+```
+
+Ненужные для kind поля агент опускает. Ответ поискового агента целиком:
+
+```jsonc
+{ "options": [...максимум 5...], "summary": "Из найденного я бы выделил...",
+  "recommendation": { "text": "...", "ids": [1, 4], "comboTotal": "≈ 509€" },
+  "notFound": "" }   // честное «не нашёл X, потому что Y» — если применимо
+```
+
+## REST API
+
+Все ответы JSON. Ошибки: `{ "error": "текст" }` + соответствующий HTTP-код.
+
+| Метод и путь | Что делает |
+|---|---|
+| `GET /api/state` | `{ team, corporate, trips, settings, jobs }` — всё сразу (jobs — активные + 20 последних) |
+| `POST /api/team` | создать карточку (body = поля без id) |
+| `PUT /api/team/:id` | обновить карточку |
+| `DELETE /api/team/:id` | удалить карточку |
+| `PUT /api/corporate` | обновить корпоративные настройки |
+| `PUT /api/settings` | обновить настройки (model/browserSearch/extraInstructions) |
+| `POST /api/trips` | создать поездку (status=draft) |
+| `PUT /api/trips/:id` | править поля поездки (только в draft/options) |
+| `DELETE /api/trips/:id` | удалить поездку |
+| `POST /api/trips/:id/search` | старт поиска → job search, status=searching |
+| `POST /api/trips/:id/book` | body `{ "n": 2 }` → job book, status=booking |
+| `POST /api/trips/:id/paid` | HR оплатила → job finalize, status=paid (блоки генерятся асинхронно) |
+| `POST /api/trips/:id/cancel` | status=cancelled |
+| `GET /api/jobs` | список джобов `[{ id, type, tripId, status, startedAt, finishedAt, error, logTail }]` |
+| `GET /api/jobs/:id` | полный джоб + полный лог (массив строк) |
+
+Job: `{ id, type: 'search'|'book'|'finalize', tripId, status: 'queued'|'running'|'done'|'error', log: [], error, startedAt, finishedAt }`. Очередь — максимум 2 одновременно, как в Work Finder. Джобы живут в памяти (не в db.json).
+
+## Агенты (lib/prompts.mjs + lib/agent.mjs)
+
+Механика запуска `claude -p` — скопировать из work-finder `lib/agent.mjs` (stream-json, извлечение JSON из ответа, обработка ошибок, модель из settings). Разрешения — через approver-mcp, как там.
+
+1. **search** — инструменты WebSearch/WebFetch (если `settings.browserSearch` — плюс Playwright MCP как в work-finder). В промпт входит: маршрут/даты/бюджет/критерии/meetingAt; корпоративные дефолты; карточки путников **без паспортных данных** (только имя, должность, лояльность, особенности); правила из CLAUDE.md ассистента: порядок источников (Google Flights → Skyscanner → Kiwi; Booking → Airbnb; аэроэкспрессы → Welcome Pickups → Bolt/Uber), тайминг прилёта относительно встречи и часовые пояса (местное время всегда), когда нужен/не нужен трансфер, «не выдумывай — честно скажи не нашёл», ≤5 вариантов, отели рейтинг ≥7.0, бюджет не превышать, группа >1 — логика групповых поездок. Требуемый выход — строго JSON по формату Option выше (схему привести в промпте дословно).
+2. **book** («Оформить №N») — браузерный агент: Playwright MCP поверх CDP :9222 (`npm run browser` поднимает Chrome — скрипт-калька с work-finder). В промпт: option целиком + полная карточка путника (тут паспорт нужен для полей) + corporate (юр.лицо для счёта). Жёсткие правила из CLAUDE.md: заполнять как гость (не создавать аккаунты), дойти до **экрана оплаты и остановиться**; никогда не вводить номер карты/CVC/срок; никогда не жать Pay/Confirm/Buy; паспортные данные не вставлять в URL; если капча/логин — остановиться и вернуть ссылку для ручного продолжения. Выход JSON: `{ "filled": ["пассажир", "тариф", ...], "stoppedAt": "экран оплаты Booking", "totalShown": "420€", "warnings": [], "manualLink": "" }` → сохраняется в `trip.bookingReports`, status=ready_to_pay.
+3. **finalize** (после «Оплачено») — без браузера, без веб-поиска: по trip + bookingReports сгенерировать три блока из CLAUDE.md (§«Шаг 5»): письмо путнику, сводка стоимости (markdown-таблица, + суточные если заданы), чеклист перед поездкой. Выход JSON `{ "letter": "...", "costTable": "...", "checklist": "..." }` → `trip.blocks`.
+
+## UI (public/) — русский, три вью
+
+Роутинг по hash: `#trips` (дефолт) / `#trip/<id>` / `#team` / `#settings`. Поллинг `GET /api/state` раз в 2 с, пока есть активный джоб — раз в 1 с.
+
+- **Поездки**: кнопка «Новая поездка» (форма: откуда/куда, даты, кто едет — чекбоксы из команды, встреча, бюджет, что нужно: транспорт/отель/трансфер(auto|да|нет), критерии). Список карточек: маршрут, даты, путники, статус-бейдж, суммы.
+- **Поездка** (деталь): hero-блок в стиле артефактов ассистента (микро-метка «КОМАНДИРОВКА · ФИО · должность», заголовок «Город А → Город Б», мета-строка с датами/ночами/встречей); пайплайн статусов; при `searching/booking` — живой лог джоба (logTail); при `options` — плашка «⭐ Рекомендованная связка» (текст + итог + кнопка «Оформить связку») и карточки вариантов со сквозной нумерацией: транспорт — таймлайн (время-станция → капсула длительности на градиентной линии → время-станция, метка «прямой»/пересадки), отель — плашка рейтинга Booking-стиля (#003580, «9.2 · 4 494»), ★-звёздность, чипы удобств (зелёные — отмена/завтрак), расстояние с SVG-пином; у каждой карточки: цена справа (крупно, «от/за ночь» мелко), бейджи («⭐ рекомендую» зелёный, «самый дешёвый» янтарный), ссылка «Открыть ↗» и кнопка **«Оформить №N»** (POST book); при `ready_to_pay` — отчёт агента (filled/stoppedAt/totalShown/warnings) + кнопка «Оплачено ✓» (POST paid) + предупреждение «карту вводит только HR»; при `paid` — три блока (письмо / смета / чеклист) с кнопками копирования (скрипт copy → fallback execCommand → выделение, как в CLAUDE.md).
+- **Команда**: карточки сотрудников (демо-бейдж), добавление/правка/удаление — модалка со всеми полями.
+- **Настройки**: корпоративные дефолты + модель (haiku/sonnet/opus) + «поиск через браузер» + доп. инструкции.
+
+### Дизайн-токены (светлая тема, дословно из CLAUDE.md ассистента)
+
+```css
+--bg:#f6f8fc; --card:#fff; --ink:#0f172a; --ink-2:#475569; --ink-3:#94a3b8;
+--line:#e6eaf2; --line-2:#eef1f7; --navy:#0a2540; --navy-2:#142a4d; --accent:#1f6feb;
+--gold:#b56500; --gold-bg:#fff3df; --green:#15803d; --green-bg:#ecfdf3; --booking:#003580;
+--shadow-sm:0 1px 2px rgba(15,23,42,.04),0 1px 3px rgba(15,23,42,.06);
+--shadow-md:0 4px 12px rgba(15,23,42,.08); --shadow-lg:0 12px 28px rgba(10,37,64,.18);
+```
+
+Радиусы: карточки 14, hero 18, кнопки 8, чипы 999, номер-бейдж 10. Шрифт — системный стек, база 14px/1.5. Иконки — inline SVG `viewBox="0 0 24 24" stroke="currentColor" stroke-width="2"`, эмодзи запрещены (кроме ⭐ в бейджах и ★★★★ звёздности). Фон body — заливка `--bg` (это standalone-приложение, не Cowork-артефакт). Экранирование любых данных при рендере обязательно (escapeHtml — как в work-finder).
+
+## Безопасность (не обсуждается)
+
+- Платёжные данные не хранить, не запрашивать, не вводить; финальную кнопку оплаты не нажимать — это правило прошивается в промпт book-агента и дублируется в UI.
+- Паспортные данные: живут только в db.json локально; в поисковый промпт не попадают; в лог джоба не выводить полностью (маскировать номер: `FK1***56`).
+- Сервер слушает только localhost (`127.0.0.1`).
+- `data/db.json` не должен попадать ни под какую статическую раздачу и ни под какой файловый watcher: каждая запись в него иначе устраивает live-reload шторм. (Старый общий дев-сервер студии `serve.mjs`, который раздавал весь корень воркспейса, удалён 2026-07-22 — приложения теперь обслуживает Vite из своих папок, так что раздачи этого пути больше нет по построению.)