@mcptoolshop/claude-synergy 0.0.0 → 1.0.1

package/CHANGELOG.md

@@ -0,0 +1,132 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.1] - 2026-05-22
+
+### Changed
+- README: center badges directly under logo. Uses inline `<img>` tags inside `<p align="center">` instead of markdown badge syntax — markdown badges with surrounding blank lines render as a separate paragraph on GitHub and npm, breaking center alignment.
+
+## [1.0.0] - 2026-05-22
+
+### Added
+- Structured error shape (`AppError` class) with `code`, `message`, `hint`, `cause?`, `retryable?` across all CLI commands.
+- Logging levels: `--verbose`, `--debug` flags + `HK_LOG_LEVEL` env var (silent/normal/verbose/debug). Secrets never logged at any level.
+- Exit code 3 for partial success (fetch/sync where some products fail but others succeed).
+- Dependabot config for automated npm + GitHub Actions dependency updates.
+- Dependency audit step (`pnpm audit`) in CI test workflow.
+- CHANGELOG.md included in npm tarball.
+
+### Changed
+- Version promoted from 0.7.2 to 1.0.0 — first stable release.
+- All CLI error paths use `formatError()` with structured output; `--json` mode returns error shape as JSON.
+- Legacy `HK_DEBUG=1` env var mapped to `--debug` log level for backward compatibility.
+
+## [0.7.2] - 2026-05-22
+
+### Security
+- Path-traversal sanitization on all file-write paths (products/, data/).
+- Command-injection guards on CLI subcommands that shell out.
+- Input validation hardening across fetch + ingest pipeline.
+- YAML-escape sanitization for user-supplied strings entering products.yaml.
+
+### Added
+- Pagination support for GitHub Releases fetcher (handles repos with 100+ releases).
+- Provider timeout guards — all external HTTP calls now enforce per-request timeouts.
+- `publishConfig` added to package.json for scoped npm publishing.
+- LICENSE file (MIT) added to repo root.
+- 3 new tests covering ghReleases pagination edge cases.
+- `fetchWithRetry` utility — timeout, retry, and exponential backoff for all external HTTP calls.
+- Signal handling (`SIGINT`/`SIGTERM`) for graceful shutdown in long-running commands.
+- Schema versioning with automatic migration detection on `hk init`.
+- Embed cost tracking — estimated token/cost metrics logged after `hk embed`.
+- Progress callbacks for ingest and embed pipelines (stderr progress when TTY attached).
+- `--json` flag on `hk query`, `hk latest`, `hk products` for machine-readable output.
+- Empty-state guidance — helpful messages when DB is empty or query returns zero results.
+- CONTRIBUTING.md — guide for adding products, running tests, and submitting PRs.
+- Troubleshooting section in README (database locks, sqlite-vec load, fetch errors, schema mismatch).
+- 88 new tests covering proactive health, behavioral humanization, visual polish, and feature pass (suite total: 382).
+- `exports` field in package.json for programmatic import resolution.
+- `prepublishOnly` build guard — prevents shipping empty `dist/`.
+- `fetchWithRetry` test suite (25 tests: retry, backoff, timeout, Retry-After, AbortSignal, GitHub rate-limit enrichment).
+- `--json` output mode integration tests (5 tests: query, latest, products, top, env-var).
+- Embed budget guard tests (10 tests: maxRequests, maxTokens, signal cancellation, partial-commit consistency).
+
+### Changed
+- Coverage thresholds adjusted to 77/75/85/77 (statements/branches/functions/lines) to reflect post-refactor baseline.
+- Test count 294 to 382 (88 new tests across 4 swarm stages + feature pass).
+- README badge row: replaced static shields.io test badge with dynamic CI status badge; added npm version badge.
+- README test counts and live numbers updated to reflect v0.7.2 baseline.
+- npm tarball reduced from 1.1 MB to 62 KB by excluding docs/logo.png from `files` field.
+- Build scripts now use `--external playwright` to avoid bundling native Chromium bindings.
+
+## [0.7.1] - 2026-05-21
+
+### Added
+- Tests catch up to Phase 4d code: 52 new unit tests covering `products-config`, `fetch-mcp-registry`, and `fetch-playwright`. Suite now at 291 tests, all passing.
+
+### Fixed
+- CI: pinned pnpm to v10 in `test.yml` and `sync.yml`. `pnpm@latest` resolves to v11, which enforces a 24-hour `minimumReleaseAge` that blocked five consecutive release CI runs.
+
+## [0.7.0] - 2026-05-21
+
+### Added
+- **Phase 4d** — full feature pass for v0.7 line:
+  - README refresh — numbers, fetch strategies, and roadmap aligned with shipped reality.
+  - YAML-driven products config — `TARGETS` and `PRODUCT_META` consolidated into `products.yaml`. Adding a product is now a one-entry YAML edit.
+  - MCP registry catalogs — Smithery and the official MCP Registry now fetched as Tier 4 catalog sources.
+  - Playwright fetcher — Windsurf changelog (CSR-only) now reachable via headless browser. Closes the v0.6 CSR-fallback gap.
+
+## [0.6.1] - 2026-05-21
+
+### Added
+- Test suite caught up to Phase 4b/4c shipped code: 239 tests, all passing. Coverage ~85%.
+
+### Fixed
+- continue-cli release bodies now filtered to exclude raw git-commit dumps (cuts ~15k of 21k noisy changes).
+
+## [0.6.0] - 2026-05-21
+
+### Added
+- **Phase 4c — continue-cli commit-dump filter**: detect-and-skip pattern for release bodies that are pure git-log dumps. Cleans the corpus without losing actual changelog entries.
+- 12th synergy file curated.
+
+### Changed
+- Total change count dropped from 21,210 → 5,957 — the noise that was inflating Tier-4a counts is gone.
+
+## [0.5.1] - 2026-05-21
+
+### Added
+- **Phase 4c — turndown HTML→markdown ingest**: HTML bodies (GitHub Copilot, VS Code Chat, Cursor) are now converted to markdown before per-bullet parsing, so FTS5 + entity extraction works end-to-end on HTML sources.
+
+## [0.5.0] - 2026-05-21
+
+### Added
+- **Tier 4b — HTML-scrape fetcher** for products without a Releases API:
+  - GitHub Copilot via `github.blog/changelog/label/copilot/`
+  - VS Code Chat via `code.visualstudio.com/updates/v1_NNN`
+  - Windsurf via CSR fallback (full Playwright fetch deferred to v0.7)
+- Total: 34 products / 1,101 release files.
+
+## [0.4.0] - 2026-05-21
+
+### Added
+- **Initial public release** through Tier 4a. Highlights:
+  - 33 products covered: Anthropic SDKs (7 languages), Agent SDKs (2), `ant` CLI, claude-code-action, claude-code-security-review, 15 MCP ecosystem SDKs, plus Cursor (RSS), Aider (raw `HISTORY.md`), Continue.dev, Cody Enterprise (filtered RSS).
+  - 1,057 release files / ~19,618 changes / 12 synergies.
+  - Fetcher strategies: `gh-releases`, `rss`, `raw-changelog`.
+  - SQLite + FTS5 corpus, sqlite-vec semantic search with Contextual Retrieval, `claude-synergy-mcp` MCP server exposing 8 tools over stdio.
+
+[1.0.1]: https://github.com/mcp-tool-shop-org/claude-synergy/releases/tag/v1.0.1
+[1.0.0]: https://github.com/mcp-tool-shop-org/claude-synergy/releases/tag/v1.0.0
+[0.7.2]: https://github.com/mcp-tool-shop-org/claude-synergy/releases/tag/v0.7.2
+[0.7.1]: https://github.com/mcp-tool-shop-org/claude-synergy/releases/tag/v0.7.1
+[0.7.0]: https://github.com/mcp-tool-shop-org/claude-synergy/releases/tag/v0.7.0
+[0.6.1]: https://github.com/mcp-tool-shop-org/claude-synergy/releases/tag/v0.6.1
+[0.6.0]: https://github.com/mcp-tool-shop-org/claude-synergy/releases/tag/v0.6.0
+[0.5.1]: https://github.com/mcp-tool-shop-org/claude-synergy/releases/tag/v0.5.1
+[0.5.0]: https://github.com/mcp-tool-shop-org/claude-synergy/releases/tag/v0.5.0
+[0.4.0]: https://github.com/mcp-tool-shop-org/claude-synergy/releases/tag/v0.4.0

package/CONTRIBUTING.md

@@ -0,0 +1,101 @@
+# Contributing to Claude Synergy
+
+Thanks for your interest in contributing. This guide covers adding new products, running tests, and submitting PRs.
+
+## Prerequisites
+
+- **Node >= 22** (`node -v` to check)
+- **pnpm >= 10** (`pnpm -v` to check)
+- **gh CLI** (optional, for testing `gh-releases` fetcher locally)
+
+## Adding a new product
+
+1. Open `products.yaml` at the repo root.
+2. Append an entry under `products:`. The minimum required fields are:
+
+```yaml
+- name: my-new-tool          # slug: lowercase alphanumeric + hyphens only
+  display_name: My New Tool   # human-readable name (shown in CLI output)
+  tier: 1                     # source tier (1-5, see below)
+  source_url: https://github.com/org/repo  # canonical URL for the source
+  fetch_strategy: gh-releases # must match the fetch.type below
+  fetch:
+    type: gh-releases
+    repo: org/repo            # owner/repo for GitHub Releases API
+```
+
+3. Pick the right fetch strategy for your source:
+
+| Strategy | When to use | Required `fetch:` fields |
+|---|---|---|
+| `gh-releases` | Repo publishes GitHub Releases | `repo` (owner/repo). Optional: `multi_package: true` for monorepos with scoped tags. |
+| `rss` | Source has an RSS feed | `url` (feed URL). Optional: `title_filter` (regex to filter entries). |
+| `raw-changelog` | Source is a raw CHANGELOG/HISTORY.md file | `url` (raw file URL), `parser` (currently only `aider-history`). |
+| `html-scrape` | Source is a blog/changelog page | `parser` (`github-copilot-blog`, `vscode-updates`). |
+| `playwright` | Source is client-rendered (no SSR) | No extra fields. Currently hardcoded to Windsurf. |
+| `catalog` | Source is an MCP registry | `catalog_type` (`official-mcp-registry` or `smithery`). Optional: `max_entries`. |
+
+4. Test your entry:
+
+```bash
+pnpm build
+hk init
+hk fetch --product my-new-tool
+hk ingest
+hk products                   # should list your product with release count
+hk query "some keyword"       # verify releases appear in search
+```
+
+## Tier semantics
+
+| Tier | Meaning | Examples |
+|------|---------|---------|
+| 1 | Structured API (GitHub Releases) — highest fidelity | SDKs, MCP ecosystem |
+| 2 | Raw markdown changelog | claude-code, aider |
+| 3 | HTML/RSS scrape | Cursor, Copilot, Cody |
+| 4 | Catalog snapshot (not versioned releases) | Skills, plugins, MCP registries |
+| 5 | Advisory / manual | X accounts, community mirrors |
+
+## Running tests
+
+```bash
+pnpm test               # unit + integration + regression (~13s, ~294 tests)
+pnpm test:watch         # interactive mode (re-runs on file change)
+pnpm test:coverage      # generates coverage/index.html (thresholds: 78/75/85/78)
+pnpm test:smoke         # opt-in full-corpus smoke test (set RUN_SMOKE=1)
+```
+
+Tests use real SQLite temp files (not `:memory:`) and mock all HTTP calls. No network access, no API keys needed.
+
+## Adding a new fetcher strategy
+
+1. Create `src/fetch-<name>.ts` with the parsing/fetching logic.
+2. Wire it into `src/fetch.ts` — add a case in the `fetchOne` switch statement.
+3. Add the type to `FetchType` in `src/products-config.ts`.
+4. Add test fixtures in `test/fixtures/` and unit tests in `test/unit/`.
+
+## PR guidelines
+
+- **Tests required** — `pnpm test` must pass. New code should have unit tests.
+- **No network in tests** — mock HTTP calls via `vi.spyOn(global, 'fetch')`. See existing tests for patterns.
+- **No source file edits without tests** — if you touch `src/*.ts`, add or update a test in `test/`.
+- **products.yaml only for new products** — adding a product needs no code change if an existing strategy fits.
+- **Keep commits focused** — one logical change per PR.
+
+## Local development
+
+```bash
+git clone https://github.com/mcp-tool-shop-org/claude-synergy
+cd claude-synergy
+pnpm install
+pnpm build               # compiles to dist/
+
+# Run CLI without building (dev mode):
+npx tsx src/cli.ts init
+npx tsx src/cli.ts query "some term"
+
+# Run MCP server (dev mode):
+npx tsx src/mcp-server.ts
+```
+
+**pnpm 10 quirk:** `pnpm dev` swallows CLI flags after `--`. Use `npx tsx src/cli.ts ...` directly during development.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mcp-tool-shop
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.es.md

@@ -0,0 +1,342 @@
+<p align="center">
+  <a href="README.ja.md">日本語</a> | <a href="README.zh.md">中文</a> | <a href="README.md">English</a> | <a href="README.fr.md">Français</a> | <a href="README.hi.md">हिन्दी</a> | <a href="README.it.md">Italiano</a> | <a href="README.pt-BR.md">Português (BR)</a>
+</p>
+
+<p align="center"><img src="https://raw.githubusercontent.com/mcp-tool-shop-org/brand/main/logos/claude-synergy/readme.png" alt="Claude Synergy" width="400"></p>
+
+<p align="center">
+  <a href="https://github.com/mcp-tool-shop-org/claude-synergy/actions/workflows/test.yml"><img src="https://github.com/mcp-tool-shop-org/claude-synergy/actions/workflows/test.yml/badge.svg" alt="tests"></a>
+  <a href="https://www.npmjs.com/package/@mcptoolshop/claude-synergy"><img src="https://img.shields.io/npm/v/@mcptoolshop/claude-synergy" alt="npm"></a>
+  <a href="#license"><img src="https://img.shields.io/badge/license-MIT-blue" alt="license"></a>
+  <a href="https://mcp-tool-shop-org.github.io/claude-synergy/"><img src="https://img.shields.io/badge/landing%20page-live-brightgreen" alt="landing page"></a>
+</p>
+
+Un espejo local y consultable de todos los registros de cambios de Anthropic y de las herramientas de desarrollo de IA relacionadas, además de una capa de **"Synergy"** (sinergia) que describe los flujos de trabajo entre productos, para que el agente LLM dentro del sistema sepa lo que el sistema puede hacer.
+
+```bash
+$ hk query redact
+2026-05-11  anthropic-cli@1.7.1            [changed]  redact api-key headers in debug logs
+2026-05-11  anthropic-sdk-java@2.31.0      [changed]  redact api-key headers in debug logs
+2026-05-11  anthropic-sdk-go@1.42.0        [changed]  redact api-key headers in debug logs
+2026-05-07  anthropic-sdk-typescript@0.95.1 [changed] redact api-key headers in debug logs
+
+4 results
+```
+
+
+**Una única consulta FTS (búsqueda de texto completo) revela una corrección de seguridad coordinada entre diferentes SDKs que ningún registro de cambios individual identificó como una vulnerabilidad (CVE).** Esa es la demostración clave: los patrones emergen cuando todos los registros de cambios están uno al lado del otro.
+
+Repositorio: [github.com/mcp-tool-shop-org/claude-synergy](https://github.com/mcp-tool-shop-org/claude-synergy)
+
+---
+
+## El problema
+
+Claude Code CLI se actualiza casi a diario. La API de Claude se actualiza con la misma frecuencia. Los SDKs se actualizan con cada nueva versión de la CLI. Claude Design, Cowork, Chat y Mobile se integran a través del Centro de Ayuda unificado. El ecosistema MCP implementa aproximadamente 200-300 nuevos servidores por semana. Además, existen 7 plataformas principales de herramientas de desarrollo de IA (Cursor, Aider, Continue, Copilot, Cody, Windsurf), cada una con sus propios registros de cambios y sus propios ciclos de lanzamiento.
+
+El agente LLM dentro de cualquiera de estos sistemas tiene un punto de corte de entrenamiento fijo. La brecha se amplía cada día. Aparecen funciones de las que el agente no es consciente. Se corrigen errores que el agente aún intenta solucionar. Se agregan variables de entorno y banderas que el agente nunca sugiere. Los flujos de trabajo entre productos que combinan múltiples plataformas permanecen sin descubrir.
+
+**Este repositorio cierra esa brecha.** La sección de "Synergy" lo convierte en un producto en lugar de un simple espejo.
+
+---
+
+## ¿Qué hay aquí?
+
+```
+claude-synergy/
+├── products/                # 44 product directories (1,186 release files)
+│   ├── claude-code/             # Anthropic CLI — 117 releases
+│   ├── claude-agent-sdk-{python,typescript}/  # Agent SDKs
+│   ├── anthropic-sdk-{python,typescript,go,java,csharp,ruby,php}/  # 7 language SDKs
+│   ├── claude-api/              # Platform release notes
+│   ├── anthropic-apps/          # Design / Cowork / Chat / Mobile (Help Center feed)
+│   ├── claude-code-action/      # GitHub Action
+│   ├── anthropic-cli/           # `ant` CLI
+│   ├── mcp-{python,typescript,go,java,csharp,kotlin,ruby,swift,rust,php}-sdk/
+│   ├── mcp-{spec,inspector,registry,mcpb,conformance}/
+│   ├── cursor/                  # RSS feed
+│   ├── aider/                   # raw HISTORY.md
+│   ├── continue-{dev,cli}/      # GH releases
+│   ├── cody-enterprise/         # filtered Sourcegraph RSS
+│   ├── github-copilot/          # HTML scrape (github.blog)
+│   ├── vscode-copilot-chat/     # HTML scrape (code.visualstudio.com)
+│   ├── windsurf/                # Playwright fetcher (CSR-only changelog)
+│   ├── skills/                  # Anthropic Skills catalog
+│   └── plugins-{official,community,knowledge-work}/  # Plugin marketplaces
+├── synergies/               # 12 curated cross-product workflows
+├── src/                     # TypeScript implementation
+├── test/                    # 382 tests (unit, integration, regression, smoke)
+├── data/claude-synergy.db   # SQLite database (created by `hk init`)
+├── schema.sql               # Tier 2a tables (products, releases, changes, entities, FTS5, …)
+├── schema-vec.sql           # Tier 2b tables (chunks, chunks_vec, chunks_fts)
+├── SOURCES.md               # 5-tier source landscape with fetch strategies
+└── URGENT_FINDINGS.md       # 23 actionable items surfaced from the corpus
+```
+
+**Estadísticas actualizadas (versión 1.0.0):** 44 productos / 1.186 archivos de lanzamiento / 6.042 cambios / 1.225 entidades / 12 sinergias / 382 pruebas.
+
+---
+
+## Estado: todas las etapas implementadas
+
+| Etapa | Estado | ¿Qué hay? |
+|------|--------|--------------|
+| **1 — corpus de Markdown (inicialización)** | ✅ implementado | Study-swarm recopiló 706 archivos de lanzamiento de enero a mayo de 2026; se ampliaron a 1186 en la etapa 4. |
+| **2a — SQLite + FTS5 + CLI** | ✅ implementado | CLI `hk`; 15 subcomandos; ingestión en menos de 300 ms. |
+| **2b — sqlite-vec + Recuperación contextual** | ✅ implementado | Proveedor adaptable (ninguno/estructurado/ollama/contexto de Claude-haiku × incrustaciones de ollama/viaje × ninguno/ollama-judge/viaje/cohere para reordenar). |
+| **3 — sincronización + servidor MCP** | ✅ implementado | `hk fetch / sync / seed-markers`; `claude-synergy-mcp` expone 8 herramientas a través de stdio. |
+| **4a — extender más allá de Anthropic** | ✅ implementado | +15 SDKs de MCP, Cursor (RSS), Aider (HISTORY.md), Continue.dev, Cody Enterprise (RSS filtrado). |
+| **4b — rastreador de HTML** | ✅ implementado | GitHub Copilot + VS Code Chat (Windsurf necesita Playwright — v0.7). |
+| **4c — ingestión de HTML a Markdown con turndown** | ✅ implementado | Los cuerpos de HTML (Copilot/VS Code/Cursor) ahora generan filas individuales para FTS5 + extracción de entidades. |
+| **4d — Playwright + registro de MCP + configuración YAML** | ✅ implementado | Windsurf a través de Playwright; Smithery + registro oficial de MCP como catálogos de la etapa 4; productos consolidados en `products.yaml`. |
+
+Hoja de ruta para la versión 0.8+: se encuentra en [URGENT_FINDINGS.md](URGENT_FINDINGS.md) y en los problemas.
+
+---
+
+## Seguridad y modelo de datos
+
+Esta herramienta se ejecuta localmente. **Datos utilizados:** una base de datos SQLite derivada y archivos de lanzamiento en formato Markdown, todos recreables. **Red:** solo conexiones HTTPS salientes cuando se ejecuta `hk fetch`/`hk sync` (API de GitHub, fuentes RSS, páginas de registro de cambios, registros de MCP) o `hk embed` con un proveedor remoto (Voyage, Cohere). **Credenciales:** lee las variables de entorno `GITHUB_TOKEN`, `VOYAGE_API_KEY`, `COHERE_API_KEY`, `ANTHROPIC_API_KEY`; nunca se registran ni se almacenan en el disco. **No se recopilan datos de telemetría.** Consulte [SECURITY.md](SECURITY.md) para obtener información sobre la política de informes.
+
+---
+
+## Instalación
+
+```bash
+git clone https://github.com/mcp-tool-shop-org/claude-synergy
+cd claude-synergy
+pnpm install
+pnpm build       # produces dist/cli.js + dist/mcp-server.js
+npm link         # makes `hk` and `claude-synergy-mcp` available globally
+```
+
+Para desarrollo sin compilación, use `npx tsx src/cli.ts ...` directamente. **Una peculiaridad de pnpm 10:** `pnpm dev` ignora las banderas de la CLI después de `--`; use `npx tsx` para el desarrollo.
+
+---
+
+## Interfaz de la CLI: 15 comandos
+
+```
+# DB lifecycle
+hk init                              # create DB with schema
+hk ingest                            # parse products/*/releases/*.md → DB (idempotent)
+hk embed                             # generate chunks + embeddings (sqlite-vec)
+hk fetch [--product X]               # incremental pull from sources
+hk sync                              # combined fetch → ingest → embed (cron-friendly)
+hk seed-markers                      # one-time setup after initial corpus
+
+# Search
+hk query "managed agents"            # FTS5 keyword search
+hk hybrid "credential exfiltration"  # FTS5 + vec hybrid via RRF (+ optional --rerank)
+
+# Entity lookups
+hk env-var CLAUDE_CODE_WORKFLOWS     # when introduced + history
+hk command code-review               # slash command + rename history
+hk model claude-opus-4-7             # model launch + mentions across products
+hk cve CVE-2025-66414                # CVE references in corpus
+
+# Browsing
+hk latest [--product X] [--limit N]  # recent releases
+hk products                          # list all 44 with counts
+hk top env_var                       # most-mentioned by entity type
+                                     # (env_var, slash_command, cli_option,
+                                     #  model_id, beta_header, cve, ghsa,
+                                     #  hook_event, setting_key)
+```
+
+---
+
+## Ejemplos de flujos de trabajo
+
+**Encontrar cuándo se introdujo una variable de entorno de Claude Code:**
+```
+$ hk env-var CLAUDE_CODE_WORKFLOWS
+env var CLAUDE_CODE_WORKFLOWS — 1 mention:
+
+2026-05-21  claude-code@2.1.147  [added]
+  Added the `Workflow` tool for deterministic multi-agent orchestration.
+  It is off by default — set `CLAUDE_CODE_WORKFLOWS=1` to enable
+```
+
+**Rastrear cambios importantes entre diferentes SDK:**
+```
+$ hk query TodoWrite --limit 5
+2026-05-15  claude-agent-sdk-python@0.2.82       [breaking]   Headless and SDK sessions now use Task tools...
+2026-05-14  claude-agent-sdk-typescript@0.3.142  [breaking]   Headless and SDK sessions now use Task tools...
+2026-05-08  claude-agent-sdk-typescript@0.2.136  [deprecated] Deprecated TodoWrite tool...
+```
+
+**Planificar una migración de modelo:**
+```
+$ hk model claude-opus-4-20250514
+model id claude-opus-4-20250514 — 2 mentions:
+
+2026-04-14  anthropic-sdk-python@0.94.0  [deprecated]
+  Deprecation of the Claude Sonnet 4 model and the Claude Opus 4 model,
+  with retirement on the Claude API scheduled for June 15, 2026...
+```
+
+**Búsqueda semántica en todo el corpus:**
+```
+$ hk hybrid "credential exfiltration" --limit 3
+2026-03-25  claude-code@2.1.83  [added]          vec#5 rrf=0.0154
+  Added `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB=1` to strip Anthropic and
+  cloud provider credentials from subprocess environments...
+```
+
+La consulta nunca dice "env_scrub"; el sistema lo muestra por similitud semántica. FTS5 puro no lo encuentra en absoluto.
+
+---
+
+## Servidor MCP: proporcione a sus agentes acceso a este corpus
+
+`claude-synergy-mcp` expone 8 herramientas a través de stdio. Conéctese a Claude Code (o cualquier host MCP) a través de `~/.claude/.mcp.json` o el archivo `.mcp.json` de su proyecto:
+
+```json
+{
+  "mcpServers": {
+    "claude-synergy": {
+      "command": "claude-synergy-mcp",
+      "env": {
+        "CLAUDE_SYNERGY_DB": "/path/to/claude-synergy/data/claude-synergy.db"
+      }
+    }
+  }
+}
+```
+
+Para el archivo `.vscode/mcp.json` de GitHub Copilot, utilice el envoltorio `servers` en lugar de `mcpServers` (consulte [synergy 12](synergies/12-mcp-config-format-gotcha.md)).
+
+Herramientas disponibles:
+
+| Herramienta | Propósito |
+|---|---|
+| `search` | FTS5 + vec híbrido; reordenamiento opcional. Modo predeterminado para consultas en lenguaje natural. |
+| `lookup_entity` | Historial exacto de entidades: variables de entorno, comandos, ID de modelos, CVE, etc. |
+| `latest_releases` | Lanzamientos recientes en todos los productos (o en uno). |
+| `get_release` | Contenido completo de un lanzamiento. |
+| `list_products` | Enumeración con conteos + última versión. |
+| `top_entities` | Entidades más mencionadas por tipo. |
+| `list_synergies` | Flujos de trabajo entre productos, seleccionados. |
+| `read_synergy` | Texto completo de un archivo de sinergia. |
+
+---
+
+## Fuentes: 5 niveles, 6 estrategias de recuperación
+
+Panorama general en [SOURCES.md](SOURCES.md).
+
+- **Nivel 1 (Lanzamientos de GitHub)** — `gh api repos/<owner>/<repo>/releases` para 22 productos, incluidos los SDK de Anthropic (7 idiomas), los SDK de Agentes (2), la CLI de ant, claude-code-action, claude-code-security-review y 15 SDK del ecosistema MCP.
+- **Nivel 2 (Markdown sin formato)** — `anthropics/claude-code/CHANGELOG.md` + `Aider-AI/aider/HISTORY.md`
+- **Nivel 3 (HTML / RSS)** — `platform.claude.com/docs/release-notes`, `support.claude.com/articles/12138966`, `cursor.com/changelog/rss.xml`, `sourcegraph.com/changelog/featured.rss` (filtrado), `github.blog/changelog/label/copilot/`, `code.visualstudio.com/updates/v1_NNN`
+- **Nivel 4 (Catálogo)** — `anthropics/skills`, `claude-plugins-{official,community}`, `knowledge-work-plugins`
+- **Nivel 5 (Asesoramiento)** — Cuenta de X `@ClaudeCodeLog`; espejo de changelog de marckrenn.
+
+Estrategias de recuperación: `gh-releases | rss | raw-changelog | html-scrape | catalog | playwright`. Nuevo producto = una entrada en `products.yaml`.
+
+---
+
+## Sinergias: lo que se desbloquea
+
+12 flujos de trabajo entre productos, seleccionados. Cada uno describe un patrón de composición, el desencadenante que lo convierte en la respuesta correcta y la evidencia del changelog que lo habilita. Ejemplos:
+
+- **08 — Universal SKILL.md format** (Code + Cursor + Codex): un autor de habilidad, tres agentes lo leen.
+- **09 — MCP across seven surfaces** (Code + Cursor + Continue + Copilot + Windsurf + Cody + API): un binario, todos los agentes.
+- **10 — Anthropic BYOK across surfaces**: una clave de API habilita a Claude en 7 editores con facturación unificada.
+- **11 — Claude Code orchestrates Aider**: traslada las ediciones pesadas a un modelo económico mientras Claude planifica.
+- **12 — MCP config format gotcha**: Copilot usa `servers`; todos los demás usan `mcpServers`.
+
+Índice completo en [synergies/INDEX.md](synergies/INDEX.md).
+
+---
+
+## Pruebas
+
+El conjunto de pruebas Vitest cubre los niveles de unidad / integración / regresión / pruebas básicas. **[test-spec-3.md](test-spec-3.md) es la autoridad actual** a partir de la versión v0.7.0; [test-spec.md](test-spec.md) (v1) y [test-spec-2.md](test-spec-2.md) (v2) permanecen en el repositorio como registro histórico de la línea de diseño.
+
+```bash
+pnpm test               # unit + integration + regression (~16s, 382 tests)
+pnpm test:watch         # interactive
+pnpm test:coverage      # generate coverage/index.html (thresholds: 78/75/85/78)
+pnpm test:smoke         # opt-in full-corpus smoke (RUN_SMOKE=1)
+```
+
+Estructura:
+
+| Directorio | Lo que cubre |
+|-----|----------------|
+| `test/unit/` | por módulo: extracción, ingestión, consulta, base de datos, incrustación, híbrido, recuperación + cada proveedor + recuperación de RSS/changelog/HTML + recuperación del registro MCP + recuperación de Playwright + configuración de productos. |
+| `test/integration/` | de extremo a extremo: canalización, sincronización, servidor MCP (JSON-RPC de stdio), CLI. |
+| `test/regression/` | §8.1–§8.18: Cada uno protege contra un error real corregido durante el desarrollo. |
+| `test/smoke/` | Prueba completa con todo el corpus contra productos reales (1143 archivos). |
+| `test/fixtures/` | 3 productos falsos + respuestas HTTP simuladas (RSS / GH / Voyage / Cohere / Ollama / Anthropic / Smithery / Registro oficial de MCP). |
+| `test/helpers/` | `temp-db.ts`, `fetch-mock.ts`, `mcp-client.ts`, `seed-corpus.ts`, `golden-vectors.ts`, `playwright-mock.ts`, `yaml-fixtures.ts` |
+
+**Por defecto, no hay conexión de red** — el proveedor HTTP se simula mediante `vi.spyOn(global, 'fetch')`. Se utiliza SQLite real en archivos temporales (no `:memory:`) porque la semántica de carga de la extensión `sqlite-vec` varía según la versión, y el almacenamiento en disco es la ruta canónica. Playwright se carga mediante importación dinámica y se simula mediante `vi.doMock('playwright', ...)` para que las pruebas se ejecuten sin instalar un navegador real.
+
+CI: `.github/workflows/test.yml` ejecuta `pnpm test:coverage` al realizar un push o una solicitud de extracción.
+
+---
+
+## Solución de problemas
+
+**"Base de datos bloqueada" o errores de WAL**
+
+Otro proceso de `hk` (o un servidor MCP obsoleto) mantiene la base de datos SQLite abierta. Cierre otros procesos de `hk` y luego intente de nuevo. Si el problema persiste, verifique si hay archivos `-wal` o `-shm` junto a `data/claude-synergy.db`: estos son archivos normales en modo WAL y se eliminarán cuando se cierre la última conexión. No los elimine mientras otro proceso tenga la base de datos abierta.
+
+**"No se encontró la extensión sqlite-vec" / falló la carga de sqlite-vec"**
+
+La extensión nativa `sqlite-vec` no se pudo cargar. Causas comunes:
+
+1. **Versión de Node demasiado antigua** — `claude-synergy` requiere Node 22+. Verifique con `node -v`.
+2. **Módulo nativo que necesita ser reconstruido** — ejecute `npm rebuild better-sqlite3` (o `pnpm rebuild better-sqlite3`).
+3. **Incompatibilidad de plataforma** — en Windows/ARM, `better-sqlite3` necesita un conjunto de herramientas de compilación de C++. Instale [windows-build-tools](https://github.com/nicedoc/windows-build-tools) o Visual Studio Build Tools con "Desarrollo de escritorio con C++".
+
+Nota: `sqlite-vec` es opcional. La búsqueda de palabras clave FTS5 (`hk query`) funciona sin ella. Solo `hk embed` y `hk hybrid` requieren la extensión vectorial.
+
+**"Error de sincronización para el producto X" / errores de fetch"**
+
+`hk fetch` y `hk sync` llaman a API externas. Causas comunes:
+
+- **Límite de velocidad de GitHub** — la estrategia `gh-releases` llama a `gh api`, que utiliza su `GITHUB_TOKEN`. Las solicitudes no autenticadas tienen un límite de 60 solicitudes/hora; autentíquese con `gh auth login` o configure `GITHUB_TOKEN` en su entorno.
+- **Red / proxy** — los extractores de RSS y HTML utilizan `fetch()`. Verifique la conectividad y cualquier configuración de proxy corporativa (`HTTPS_PROXY`).
+- **Producto desconocido** — `hk fetch --product foo` solo funciona para los productos que se enumeran en `products.yaml`. Ejecute `hk products` para ver todos los nombres disponibles.
+
+La sincronización es idempotente: es seguro volver a ejecutarla después de un fallo parcial. Las versiones ya descargadas se omiten.
+
+**"El proveedor de incrustación no responde"**
+
+`hk embed` llama a un servicio de incrustación externo:
+
+- **Ollama (predeterminado)** — asegúrese de que Ollama se está ejecutando (`ollama serve`) y que el modelo de incrustación se ha descargado (`ollama pull nomic-embed-text`).
+- **Voyage** — configure `VOYAGE_API_KEY` en su entorno. Verifique su clave de API en [dash.voyageai.com](https://dash.voyageai.com).
+
+**Incompatibilidad de versión de esquema / base de datos corrupta**
+
+Si la base de datos se creó con una versión de esquema anterior y la migración falla, o si los datos parecen incorrectos después de un fallo:
+
+```bash
+rm data/claude-synergy.db data/claude-synergy.db-wal data/claude-synergy.db-shm
+hk init
+hk ingest
+hk embed --context structured --embedding ollama   # optional, for vector search
+```
+
+Esto es seguro: la base de datos es una caché derivada. Todos los datos de origen se encuentran en los archivos `products/*/releases/*.md`.
+
+---
+
+## Archivos relacionados
+
+- [CONTRIBUTING.md](CONTRIBUTING.md) — Cómo agregar productos, ejecutar pruebas y enviar solicitudes de extracción (PR).
+- [URGENT_FINDINGS.md](URGENT_FINDINGS.md) — 23 elementos que requieren atención inmediata (vulnerabilidades de seguridad, obsolescencia de modelos, cambios importantes, problemas de configuración).
+- [SOURCES.md](SOURCES.md) — Panorama de fuentes de 5 niveles con estrategias de obtención.
+- [synergies/INDEX.md](synergies/INDEX.md) — 12 flujos de trabajo seleccionados que involucran varios productos.
+- [schema.sql](schema.sql) + [schema-vec.sql](schema-vec.sql) — Esquemas de SQLite y sqlite-vec.
+- [test-spec-3.md](test-spec-3.md) (actual) + [test-spec-2.md](test-spec-2.md), [test-spec.md](test-spec.md) (histórico) — Especificaciones del conjunto de pruebas.
+
+---
+
+## Licencia
+
+MIT. Creado por <a href="https://mcp-tool-shop.github.io/">MCP Tool Shop</a>.