# Perplexity Pack — План 1: провенанс-вет + перенос конфигурации

> **For agentic workers:** REQUIRED SUB-SKILL: superpowers:executing-plans (inline). Steps use checkbox syntax.

**Goal:** Провести провенанс-вет трёх MCP-пакетов research-слоя и аддитивно перенести их блоки в main `.mcp.json`.

**Architecture:** Факты по каждому пакету берутся командами `npm view` (метаданные + README) и best-effort `gh api` (звёзды/активность). По собранным фактам пишется вет-док `docs/research/research-vet.md` и дом-README `docs/research/README.md`; затем в `.mcp.json` добавляются три блока серверов (perplexity/exa/firecrawl), Active-постура, ключи через `${VAR}`.

**Tech Stack:** npm CLI, GitHub API (gh), JSON config `.mcp.json`.

## Цель

Доделать первую часть интеграции «Perplexity Pack»: вет происхождения трёх пакетов и
перенос их конфигурации в main. Реализует якоря спеки {#D2} (провенанс-вет) и {#D3}
(перенос конфигурации) из `docs/superpowers/specs/2026-06-14-perplexity-pack-research-tooling-design.md`.

```skills-json
[]
```

```steps-json
[
  {"op":"Bash","object":"npm view @perplexity-ai/mcp-server --json","ref":"D2"},
  {"op":"Bash","object":"npm view @perplexity-ai/mcp-server readme","ref":"D2"},
  {"op":"Bash","object":"npm view exa-mcp-server --json","ref":"D2"},
  {"op":"Bash","object":"npm view exa-mcp-server readme","ref":"D2"},
  {"op":"Bash","object":"npm view firecrawl-mcp --json","ref":"D2"},
  {"op":"Bash","object":"npm view firecrawl-mcp readme","ref":"D2"},
  {"op":"Bash","object":"gh api repos/exa-labs/exa-mcp-server","ref":"D2"},
  {"op":"Bash","object":"gh api repos/firecrawl/firecrawl-mcp-server","ref":"D2"},
  {"op":"Write","object":"docs/research/research-vet.md","ref":"D2"},
  {"op":"Write","object":"docs/research/README.md","ref":"D2"},
  {"op":"Edit","object":".mcp.json","ref":"D3"}
]
```

```verified-context-json
[
  {"id":"vc1","kind":"EXTRACTED","ref":".mcp.json","anchor":"\"$schema\": \"https://raw.githubusercontent.com/anthropics/claude-code/main/schemas/mcp.json\""},
  {"id":"vc2","kind":"EXTRACTED","ref":"docs/security/infosec-vet.md","anchor":"Провенанс-вет внешних инструментов A8 infosec-tooling"},
  {"id":"vc3","kind":"EXTRACTED","ref":"tools/cost-pricing.mjs","anchor":"export const PRICING = Object.freeze("}
]
```

---

## Task 1: Сбор фактов по пакетам (провенанс-вет)

**Files:**
- Read-only внешние источники (npm registry, GitHub API).

- [ ] **Step 1: Метаданные perplexity**

Run: `npm view @perplexity-ai/mcp-server --json`
Expected: JSON с полями `name`, `version`, `license`, `repository`, `maintainers`, `time`.

- [ ] **Step 2: README perplexity**

Run: `npm view @perplexity-ai/mcp-server readme`
Expected: текст README (назначение, какие tools, что исполняет).

- [ ] **Step 3: Метаданные exa**

Run: `npm view exa-mcp-server --json`
Expected: JSON с метаданными пакета.

- [ ] **Step 4: README exa**

Run: `npm view exa-mcp-server readme`
Expected: текст README.

- [ ] **Step 5: Метаданные firecrawl**

Run: `npm view firecrawl-mcp --json`
Expected: JSON с метаданными пакета.

- [ ] **Step 6: README firecrawl**

Run: `npm view firecrawl-mcp readme`
Expected: текст README.

- [ ] **Step 7: GitHub-активность exa**

Run: `gh api repos/exa-labs/exa-mcp-server`
Expected: JSON со `stargazers_count`, `pushed_at`, `license`. Best-effort: при 404/ошибке
используется `repository.url` из npm-метаданных (Step 3), факт фиксируется как degraded.

- [ ] **Step 8: GitHub-активность firecrawl**

Run: `gh api repos/firecrawl/firecrawl-mcp-server`
Expected: JSON со звёздами/активностью. Best-effort: при 404 берётся `repository.url` из
npm-метаданных (Step 5), фиксируется degraded. (perplexity — официальный репо
perplexityai; звёзды берутся из npm/repository.url если gh недоступен.)

## Task 2: Вет-док и дом раздела

**Files:**
- Create: `docs/research/research-vet.md`
- Create: `docs/research/README.md`

- [ ] **Step 9: Написать вет-док**

Создать `docs/research/research-vet.md` по образцу `docs/security/infosec-vet.md`:
дата 2026-06-14, методология (npm view + gh api), на каждый из трёх пакетов таблица
(владелец/мейнтейнеры, лицензия, версия/пин, активность/последний релиз, что исполняет,
сеть/телеметрия) и вердикт ПРИНЯТ/ОТКЛОНЁН. Итоговая таблица вердиктов. Состав пака —
все три, если у всех вердикт ПРИНЯТ; любой ОТКЛОНЁН исключается из переноса (Step 11).
Раздел «Ограничения вета»: глубокий разбор исходников за пределами README — degraded
под текущими ограничениями, отдельным проходом при активации серверов.

- [ ] **Step 10: Написать дом-README раздела**

Создать `docs/research/README.md`: назначение раздела research-tooling, ссылка на
вет-док, три сервера и их роли (perplexity — ранжированный ответ + sonar; exa —
семантическое обнаружение; firecrawl — глубокое чтение + обход), пометка про ключи
в user env и про риск bulk-load MCP-инструментов при субагент-прогонах.

## Task 3: Перенос блоков в main `.mcp.json`

**Files:**
- Modify: `.mcp.json`

- [ ] **Step 11: Добавить три блока серверов**

В `.mcp.json` перед `_disabled_marketing_servers_note` добавить три блока
`mcpServers` (`perplexity`/`exa`/`firecrawl`) по образцу блока `openapi`/`sentry`:
`command`/`args`/`env` (ключ через `${VAR}`)/`comment` (назначение, источник пакета,
вердикт вета, пин). Перенести только пакеты с вердиктом ПРИНЯТ из Step 9. Существующие
блоки не трогать. JSON оставить валидным по объявленной `$schema`.

---

## Self-Review

- Покрытие спеки: Task 1+2 реализуют {#D2} (вет); Task 3 — {#D3} (перенос). {#D4}–{#D9}
  — за Планами 2 и 3.
- Плейсхолдеров нет: команды точные, содержание вет-дока и блоков описано.
- Согласованность: имена пакетов и серверов едины (perplexity/exa/firecrawl).

## Примечания к исполнению

- Шаги `gh api` — best-effort: при недоступности репо-slug истина берётся из
  `repository.url` npm-метаданных; в вет-доке помечается degraded.
- Регрессия vitest и обновление реестра/нормативки/роутера — Планы 2 и 3 (не здесь:
  `.mcp.json`-правка на vitest не влияет).
