@mcptoolshop/claude-synergy 1.0.1 → 1.1.0

package/CHANGELOG.md

@@ -5,6 +5,50 @@ 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.1.0] - 2026-05-22
+
+### Added
+- **`hk diff [product] --since N(d|w|m|y)`** — "what changed in this window," grouped by product+version. Default `--since` is `7d`. Accepts `--until`, `--kind`, `--limit` (default 200; caps total change rows, not releases), `--json`, `--db`. Answers "what landed lately?" without a search term. Relative dates: `7d`, `2w`, `3m`, `1y` (resolved to ISO at the CLI boundary).
+- **`hk breaking`** — filter-browse of breaking changes across the corpus. No search term required. Accepts `--product`, `--since`, `--until`, `--limit` (default 50), `--json`, `--db`.
+- **Three new MCP tools** (8 → 11):
+  - `get_changes_since` — `{since (required), until?, product?, kind?, limit?}` → changes grouped by product+version.
+  - `search_breaking_changes` — `{product?, since?, until?, limit?}` → flat list of breaking changes.
+  - `compare_versions` — `{product, from_version, to_version}` → all changes between two versions of one product.
+- **OpenAI embedding provider** — `text-embedding-3-small` (1536-dim) default, configurable model via `OPENAI_EMBED_MODEL` (`text-embedding-3-large` → 3072, `text-embedding-ada-002` → 1536). Env: `OPENAI_API_KEY`, optional `OPENAI_BASE_URL` for OpenAI-compatible gateways. Supports Matryoshka dim truncation when a smaller dim is requested. Use `--embed openai` on `hk hybrid` / `hk embed`.
+- **Configurable embedding dimension** — `schema_meta.embedding_dim` stamps the active vector dimension. The `chunks_vec` sqlite-vec table is now created dynamically at the stamped dim rather than hard-coded to 768. Switching to a provider with a different dim while chunks exist raises `EMBEDDING_DIM_MISMATCH` (`AppError`) instead of silently corrupting the vector table.
+- **Synergy DB ingestion** — `hk ingest` now populates the previously dead synergy schema (`synergies`, `synergy_products`, `synergy_steps`, `synergy_evidence`, `synergy_change_refs`) from `synergies/*.md` frontmatter + body sections. Powers the `list_synergies` / `read_synergy` MCP tools off the DB. Filesystem fallback retained for lazy migration of existing installs that haven't re-ingested. `INSERT … ON CONFLICT DO UPDATE` preserves synergy IDs across re-ingest. Stub product rows (`source_tier = 0`, `notes = 'synergy-stub'`) are created for synergy-referenced products that have no fetch pipeline yet.
+- **`claude-code` auto-sync** — Anthropic's `claude-code` product is now fetched automatically on every `hk sync` via the GitHub Releases API (Tier 1 / `gh-releases`). Previously the corpus was manually seeded with no incremental sync path. Tier reclassified 2 → 1 to reflect the structured-API source.
+- **Generic `keep-a-changelog` parser** — any product whose source is a CHANGELOG.md in [Keep-a-Changelog](https://keepachangelog.com/) format can be wired with a single entry in `products.yaml` (`fetch_strategy: raw-changelog`, `parser: keep-a-changelog`). Handles bracketed/unbracketed versions, optional `v` prefix, paren or hyphen date separators, pre-release and build-metadata suffixes. `[Unreleased]` and other non-version headings are skipped; undated version headings (`## 1.2.3` with no date) are preserved with `releasedAt: null` so the parser is lossless. The network fetcher (`fetchKeepAChangelog`) drops undated entries on incremental sync since `null > since` can't be evaluated.
+- **GitHub Releases sync — early-exit pagination** — `gh-releases` fetcher now stops paginating once an entire page falls below the `--since` watermark. Repos with 500+ releases (e.g. continue-dev) drop from 5 pages to 1–2 on a daily sync — ~80% reduction in GitHub API quota.
+
+### Changed
+- `hk query` gained `--until <date>` (date upper bound).
+- `hk hybrid` gained `--until <date>` (date upper bound).
+- `hk latest` gained `--since <date>` (date lower bound).
+- MCP `search` tool gained optional `until` input.
+- MCP `latest_releases` tool gained optional `since` input.
+- MCP `list_synergies` tool gained optional `product` filter.
+- MCP tool count 8 → 11.
+- CLI command count 15 → 17.
+- Test suite 382 → 508 (+126 tests across 6 new unit files, 3 extended integration files, and §8.19 regression for ghReleases pagination).
+- claude-code product reclassified Tier 2 → Tier 1 in `products.yaml` and docs to reflect structured-API source (GitHub Releases).
+- README CLI surface and MCP tools tables updated to reflect new commands and flags.
+- Handbook `cli-reference` and `mcp-server` pages updated with new commands and tool input schemas.
+
+### Migration notes
+- **Schema v2 → v3 auto-migrates on first `hk init` after upgrade.** The migration stamps `embedding_dim = 768` into `schema_meta` to preserve existing Ollama-embedded DBs at their current dimension. No data is moved. Migration is one-way — a v3 DB cannot be opened by older tool versions.
+- **Existing 768-dim Ollama embeddings continue to work without re-embed.** The dim guard only triggers if you switch to a provider that produces a different vector size (e.g. Ollama 768 → OpenAI 1536).
+- **Switching embedding providers across different dimensions on a populated DB:** `hk embed` will refuse with `EMBEDDING_DIM_MISMATCH`. To switch, wipe and re-initialize the DB:
+  ```bash
+  rm data/claude-synergy.db data/claude-synergy.db-wal data/claude-synergy.db-shm
+  hk init
+  hk ingest
+  hk embed --embed <new-provider>
+  ```
+  Alternatively, OpenAI supports Matryoshka truncation — pass a target dim within the model's native size (e.g. truncate `text-embedding-3-small` from 1536 to 768 to stay compatible with an existing Ollama DB).
+- **Synergies still live as markdown** in `synergies/*.md` — the DB tables (`synergies`, `synergy_products`, `synergy_steps`, `synergy_evidence`, `synergy_change_refs`) are a cache populated on `hk ingest`. Edits to synergy files take effect on next ingest. The MCP server prefers the DB but falls back to the filesystem when the DB is empty (lazy migration for existing installs).
+- **Stub product rows** may appear in `products` table with `source_tier = 0`, `notes = 'synergy-stub'` for synergy-referenced products that have no fetch pipeline yet (e.g. `claude-cowork`, `claude-design`). These satisfy FK constraints without polluting the changelog corpus.
+
 ## [1.0.1] - 2026-05-22
 
 ### Changed
@@ -120,6 +164,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - 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.1.0]: https://github.com/mcp-tool-shop-org/claude-synergy/releases/tag/v1.1.0
 [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

package/CONTRIBUTING.md

@@ -30,7 +30,8 @@ Thanks for your interest in contributing. This guide covers adding new products,
 |---|---|---|
 | `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`). |
+| `raw-changelog` | Source is a raw CHANGELOG/HISTORY.md file (aider-style only) | `url` (raw file URL), `parser` (currently only `aider-history`). |
+| `keep-a-changelog` | Source is a CHANGELOG.md in [Keep-a-Changelog](https://keepachangelog.com/) format | `url` (raw file URL). |
 | `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`. |
@@ -50,8 +51,8 @@ hk query "some keyword"       # verify releases appear in search
 
 | Tier | Meaning | Examples |
 |------|---------|---------|
-| 1 | Structured API (GitHub Releases) — highest fidelity | SDKs, MCP ecosystem |
-| 2 | Raw markdown changelog | claude-code, aider |
+| 1 | Structured API (GitHub Releases) — highest fidelity | SDKs, MCP ecosystem, claude-code (since v1.1) |
+| 2 | Raw markdown changelog | 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 |
@@ -59,7 +60,7 @@ hk query "some keyword"       # verify releases appear in search
 ## Running tests
 
 ```bash
-pnpm test               # unit + integration + regression (~13s, ~294 tests)
+pnpm test               # unit + integration + regression (~18s, 508 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)

package/README.es.md

@@ -65,7 +65,7 @@ claude-synergy/
 │   └── plugins-{official,community,knowledge-work}/  # Plugin marketplaces
 ├── synergies/               # 12 curated cross-product workflows
 ├── src/                     # TypeScript implementation
-├── test/                    # 382 tests (unit, integration, regression, smoke)
+├── test/                    # 508 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)
@@ -73,7 +73,7 @@ claude-synergy/
 └── 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.
+**Cifras actualizadas (a partir de la versión 1.1.0):** 44 productos / 1.186 archivos de lanzamiento / 6.042 cambios / 1.225 entidades / 12 sinergias / 508 pruebas / 11 herramientas MCP / 17 comandos de línea de comandos.
 
 ---
 
@@ -84,11 +84,12 @@ claude-synergy/
 | **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. |
+| **3 — sincronización + servidor MCP** | ✅ implementado | `hk fetch / sync / seed-markers`; `claude-synergy-mcp` expone 11 herramientas a través de stdio (8 en la versión original de Nivel 3, 3 añadidas en la versión 1.1). |
 | **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`. |
+| **5 — Navegación con ventanas en la versión 1.1 + integración de OpenAI** | ✅ implementado | `hk diff` / `hk breaking`, límites de fecha para todos los comandos de navegación, 3 nuevas herramientas MCP (un total de 11), proveedor de incrustación de OpenAI, dimensión de incrustación configurable, `claude-code` se sincroniza automáticamente, analizador genérico `keep-a-changelog`. |
 
 Hoja de ruta para la versión 0.8+: se encuentra en [URGENT_FINDINGS.md](URGENT_FINDINGS.md) y en los problemas.
 
@@ -126,8 +127,12 @@ hk sync                              # combined fetch → ingest → embed (cron
 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)
+hk query "managed agents"            # FTS5 keyword search (+ --until <date>)
+hk hybrid "credential exfiltration"  # FTS5 + vec hybrid via RRF (+ --rerank, --until)
+
+# Windowed change browsing
+hk diff [product] --since 7d         # what changed in a window, grouped by product+version
+hk breaking --since 30d              # filter-browse of breaking changes (no search term)
 
 # Entity lookups
 hk env-var CLAUDE_CODE_WORKFLOWS     # when introduced + history
@@ -136,7 +141,7 @@ 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 latest [--product X] [--limit N]  # recent releases (+ --since <date>)
 hk products                          # list all 44 with counts
 hk top env_var                       # most-mentioned by entity type
                                      # (env_var, slash_command, cli_option,
@@ -144,6 +149,8 @@ hk top env_var                       # most-mentioned by entity type
                                      #  hook_event, setting_key)
 ```
 
+**Novedades en la versión 1.1:** `hk diff` y `hk breaking` responden a la pregunta "¿qué ha cambiado recientemente?" sin necesidad de un término de búsqueda. Los límites de fecha son uniformes: cada comando de navegación utiliza `--since` y `--until` en formato `YYYY-MM-DD` (o formato ISO 8601 completo), o en formato relativo (`7d`, `2w`, `3m`, `1y`).
+
 ---
 
 ## Ejemplos de flujos de trabajo
@@ -186,6 +193,30 @@ $ hk hybrid "credential exfiltration" --limit 3
 
 La consulta nunca dice "env_scrub"; el sistema lo muestra por similitud semántica. FTS5 puro no lo encuentra en absoluto.
 
+**Cambios en claude-code esta semana:**
+```
+$ hk diff claude-code --since 7d
+claude-code@2.1.147  2026-05-21  (3 changes)
+  [added]     Added the `Workflow` tool for deterministic multi-agent orchestration.
+  [changed]   Slash commands now lazy-load until first invocation.
+  [fixed]     Race condition in MCP server discovery on Windows.
+
+claude-code@2.1.146  2026-05-19  (1 change)
+  [fixed]     Restored `--debug` flag accidentally removed in 2.1.144.
+```
+
+**Explore los cambios importantes en todo el conjunto de datos:**
+```
+$ hk breaking --since 30d --limit 5
+2026-05-15  claude-agent-sdk-python@0.2.82       Headless and SDK sessions now use Task tools by default.
+2026-05-14  claude-agent-sdk-typescript@0.3.142  Headless and SDK sessions now use Task tools by default.
+2026-05-08  anthropic-sdk-go@1.42.0              Removed deprecated `client.Beta()` namespace.
+2026-04-29  cursor@0.49.0                        MCP server config moved from `cursor.json` to `.cursor/mcp.json`.
+2026-04-22  windsurf@1.10.0                      Removed `cascade.run` JSON-RPC method.
+```
+
+No se necesita un término de búsqueda: `hk breaking` es la respuesta a la pregunta "¿ha habido algún cambio importante recientemente?".
+
 ---
 
 ## Servidor MCP: proporcione a sus agentes acceso a este corpus
@@ -211,14 +242,19 @@ Herramientas disponibles:
 
 | Herramienta | Propósito |
 |---|---|
-| `search` | FTS5 + vec híbrido; reordenamiento opcional. Modo predeterminado para consultas en lenguaje natural. |
+| `search` | FTS5 + vec híbrido; reordenamiento opcional. Modo predeterminado para consultas en lenguaje natural. (+ límite superior de fecha `until`) |
 | `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). |
+| `latest_releases` | Lanzamientos recientes en todos los productos (o en uno). (+ límite inferior de fecha `since`) |
 | `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. |
+| `list_synergies` | Flujos de trabajo entre productos. (+ filtro de producto opcional) |
 | `read_synergy` | Texto completo de un archivo de sinergia. |
+| `get_changes_since` | **Nuevo.** Cambios en un intervalo de tiempo, agrupados por producto y versión. Entradas: `since` (obligatorio), `until?`, `product?`, `kind?`, `limit?`. |
+| `search_breaking_changes` | **Nuevo.** Lista plana de cambios importantes: no se necesita un término de búsqueda. Entradas: `product?`, `since?`, `until?`, `limit?`. |
+| `compare_versions` | **Nuevo.** Todos los cambios entre dos versiones de un producto. Entradas: `product`, `from_version`, `to_version`. |
+
+Las tres nuevas herramientas replican `hk diff` / `hk breaking` y el flujo de trabajo de comparación de versiones que anteriormente requería scripts. Consulte [manual → servidor MCP](https://mcp-tool-shop-org.github.io/claude-synergy/handbook/mcp-server/) para obtener los esquemas de entrada completos.
 
 ---
 
@@ -226,11 +262,11 @@ Herramientas disponibles:
 
 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.
+- **Nivel 1 (Lanzamientos de GitHub)** — `gh api repos/<owner>/<repo>/releases` para 23 productos, incluidos los SDK de Anthropic (7 idiomas), los SDK de Agentes (2), la CLI de ant, **claude-code** (ahora se sincroniza automáticamente a través de gh-releases a partir de la versión 1.1, anteriormente se inicializaba manualmente), claude-code-action, claude-code-security-review y 15 SDK del ecosistema MCP.
+- **Nivel 2 (markdown sin formato)** — `Aider-AI/aider/HISTORY.md`. El analizador genérico `keep-a-changelog` (v1.1+) también está disponible para cualquier producto cuyo origen sea un archivo CHANGELOG.md en formato Keep-a-Changelog: configúrelo mediante una entrada en `products.yaml`.
+- **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`.
 
@@ -255,7 +291,7 @@ Estrategias de recuperación: `gh-releases | rss | raw-changelog | html-scrape |
 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               # unit + integration + regression (~18s, 508 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)
@@ -265,9 +301,9 @@ 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/unit/` | por módulo: extracción, ingestión, consulta (incl. `until` / navegación / desde / comparación), base de datos (incl. migración de configuración de dimensión v3), incrustación, híbrido, extracción + cada proveedor (Ollama / Voyage / **OpenAI**) + extracción de RSS/changelog (incl. analizador **keep-a-changelog**) / HTML + extracción del registro MCP + extracción de Playwright + configuración de productos + ingestión/consulta de sinergias. |
+| `test/integration/` | de extremo a extremo: canalización, sincronización, servidor MCP (JSON-RPC de stdio, 11 herramientas), CLI (incl. `hk diff`, `hk breaking`). |
+| `test/regression/` | §8.1–§8.19 — cada uno protege contra un error real corregido durante el desarrollo (§8.19: la paginación de salida temprana de ghReleases conserva los elementos dentro del intervalo). |
 | `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` |
@@ -308,8 +344,22 @@ La sincronización es idempotente: es seguro volver a ejecutarla después de un
 
 `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).
+- **Ollama (por defecto, 768 dimensiones)**: asegúrese de que Ollama esté en ejecución (`ollama serve`) y que el modelo de incrustación se haya descargado (`ollama pull nomic-embed-text`).
+- **Voyage (1024 dimensiones)**: configure la variable de entorno `VOYAGE_API_KEY`. Verifique su clave de API en [dash.voyageai.com](https://dash.voyageai.com).
+- **OpenAI (1536 dimensiones por defecto, configurable)**: configure la variable `OPENAI_API_KEY`. El modelo predeterminado es `text-embedding-3-small`; puede cambiarlo con `OPENAI_EMBED_MODEL` (por ejemplo, `text-embedding-3-large` para 3072 dimensiones). Utilícelo a través de `hk hybrid --embed openai` o `hk embed --embed openai`.
+
+**Incompatibilidad de dimensiones de incrustación al cambiar de proveedor**
+
+Cada proveedor genera vectores de una dimensión fija (Ollama 768, Voyage 1024, OpenAI 1536 por defecto; OpenAI admite dimensiones configurables dentro del tamaño nativo del modelo). La base de datos almacena la dimensión activa en `schema_meta.embedding_dim`. Cambiar de proveedor a una dimensión diferente mientras existen fragmentos genera un error `EMBEDDING_DIM_MISMATCH` (un error de la aplicación) en lugar de corromper silenciosamente la tabla de vectores. Para cambiar:
+
+```bash
+rm data/claude-synergy.db data/claude-synergy.db-wal data/claude-synergy.db-shm
+hk init
+hk ingest
+hk embed --embed openai     # new provider, new dim, fresh chunks_vec
+```
+
+Para la truncación de Matryoshka de OpenAI (dimensión menor a la nativa), configure `OPENAI_EMBED_MODEL` y pase la dimensión deseada a través de la construcción del proveedor en `hk embed`; consulte la [sección de incrustaciones del manual](https://mcp-tool-shop-org.github.io/claude-synergy/handbook/cli-reference/#embedding-providers-and-dimensions) para obtener más detalles.
 
 **Incompatibilidad de versión de esquema / base de datos corrupta**
 

package/README.fr.md

@@ -65,7 +65,7 @@ claude-synergy/
 │   └── plugins-{official,community,knowledge-work}/  # Plugin marketplaces
 ├── synergies/               # 12 curated cross-product workflows
 ├── src/                     # TypeScript implementation
-├── test/                    # 382 tests (unit, integration, regression, smoke)
+├── test/                    # 508 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)
@@ -73,7 +73,7 @@ claude-synergy/
 └── URGENT_FINDINGS.md       # 23 actionable items surfaced from the corpus
 ```
 
-**Chiffres clés (à partir de la version 1.0.0) :** 44 produits / 1 186 fichiers de publication / 6 042 modifications / 1 225 entités / 12 synergies / 382 tests.
+**Chiffres en direct (version v1.1.0) :** 44 produits / 1 186 fichiers de publication / 6 042 modifications / 1 225 entités / 12 synergies / 508 tests / 11 outils MCP / 17 commandes CLI.
 
 ---
 
@@ -84,11 +84,12 @@ claude-synergy/
 | **1 — corpus Markdown (bootstrap)** | ✅ réalisé | Study-swarm a alimenté 706 fichiers de publication de janvier à mai 2026 ; étendu à 1 186 par l'étape 4. |
 | **2a — SQLite + FTS5 + CLI** | ✅ réalisé | CLI `hk` ; 15 sous-commandes ; ingestion inférieure à 300 ms. |
 | **2b — sqlite-vec + récupération contextuelle** | ✅ réalisé | Fournisseur adaptable (aucun/structuré/ollama/claude-haiku contexte × ollama/voyage embed × aucun/ollama-judge/voyage/cohere rerank). |
-| **3 — synchronisation + serveur MCP** | ✅ réalisé | `hk fetch / sync / seed-markers` ; `claude-synergy-mcp` expose 8 outils via stdio. |
+| **3 — synchronisation + serveur MCP** | ✅ réalisé | `hk fetch / sync / seed-markers` ; `claude-synergy-mcp` expose 11 outils via stdio (8 dans la version initiale, 3 ajoutés en v1.1). |
 | **4a — extension au-delà d'Anthropic** | ✅ réalisé | +15 SDK MCP, Cursor (RSS), Aider (HISTORY.md), Continue.dev, Cody Enterprise (RSS filtré). |
 | **4b — récupérateur HTML** | ✅ réalisé | GitHub Copilot + VS Code Chat (Windsurf nécessite Playwright — v0.7). |
 | **4c — ingestion HTML→Markdown avec turndown** | ✅ réalisé | Les corps HTML (Copilot/VS Code/Cursor) génèrent désormais des lignes individuelles pour FTS5 + l'extraction d'entités. |
 | **4d — Playwright + registre MCP + configuration YAML** | ✅ réalisé | Windsurf via Playwright ; Smithery + registre MCP officiel comme catalogues de l'étape 4 ; les produits sont regroupés dans `products.yaml`. |
+| **5 — Navigation avec fenêtrage v1.1 + intégration OpenAI** | ✅ réalisé | `hk diff` / `hk breaking`, limites de date pour toutes les commandes de navigation, 3 nouveaux outils MCP (total de 11), fournisseur d'intégration OpenAI, dimension d'intégration configurable, synchronisation automatique de `claude-code`, analyseur générique `keep-a-changelog`. |
 
 Feuille de route pour la version 0.8+ : consultable dans [URGENT_FINDINGS.md](URGENT_FINDINGS.md) et les problèmes.
 
@@ -126,8 +127,12 @@ hk sync                              # combined fetch → ingest → embed (cron
 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)
+hk query "managed agents"            # FTS5 keyword search (+ --until <date>)
+hk hybrid "credential exfiltration"  # FTS5 + vec hybrid via RRF (+ --rerank, --until)
+
+# Windowed change browsing
+hk diff [product] --since 7d         # what changed in a window, grouped by product+version
+hk breaking --since 30d              # filter-browse of breaking changes (no search term)
 
 # Entity lookups
 hk env-var CLAUDE_CODE_WORKFLOWS     # when introduced + history
@@ -136,7 +141,7 @@ 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 latest [--product X] [--limit N]  # recent releases (+ --since <date>)
 hk products                          # list all 44 with counts
 hk top env_var                       # most-mentioned by entity type
                                      # (env_var, slash_command, cli_option,
@@ -144,6 +149,8 @@ hk top env_var                       # most-mentioned by entity type
                                      #  hook_event, setting_key)
 ```
 
+**Nouveautés de la version v1.1 :** `hk diff` et `hk breaking` répondent à la question "qu'est-ce qui a changé récemment ?" sans nécessiter de terme de recherche. Les limites de date sont uniformes : chaque commande de navigation accepte `--since` et `--until` au format `AAAA-MM-JJ` (ou format ISO 8601 complet), ou sous forme relative (`7d`, `2w`, `3m`, `1y`).
+
 ---
 
 ## Exemples de flux de travail
@@ -186,6 +193,30 @@ $ hk hybrid "credential exfiltration" --limit 3
 
 La requête ne contient jamais "env_scrub" ; le système le détecte par similarité sémantique. La recherche FTS5 classique ne le trouve pas du tout.
 
+**Ce qui a changé dans claude-code cette semaine :**
+```
+$ hk diff claude-code --since 7d
+claude-code@2.1.147  2026-05-21  (3 changes)
+  [added]     Added the `Workflow` tool for deterministic multi-agent orchestration.
+  [changed]   Slash commands now lazy-load until first invocation.
+  [fixed]     Race condition in MCP server discovery on Windows.
+
+claude-code@2.1.146  2026-05-19  (1 change)
+  [fixed]     Restored `--debug` flag accidentally removed in 2.1.144.
+```
+
+**Parcourir les modifications importantes dans l'ensemble des données :**
+```
+$ hk breaking --since 30d --limit 5
+2026-05-15  claude-agent-sdk-python@0.2.82       Headless and SDK sessions now use Task tools by default.
+2026-05-14  claude-agent-sdk-typescript@0.3.142  Headless and SDK sessions now use Task tools by default.
+2026-05-08  anthropic-sdk-go@1.42.0              Removed deprecated `client.Beta()` namespace.
+2026-04-29  cursor@0.49.0                        MCP server config moved from `cursor.json` to `.cursor/mcp.json`.
+2026-04-22  windsurf@1.10.0                      Removed `cascade.run` JSON-RPC method.
+```
+
+Pas de terme de recherche nécessaire — `hk breaking` est la réponse à la question "est-ce qu'il y a eu des modifications importantes récemment ?".
+
 ---
 
 ## Serveur MCP : donnez à vos agents accès à ce corpus
@@ -211,14 +242,19 @@ Outils exposés :
 
 | Outil | Fonctionnalité |
 |---|---|
-| `search` | FTS5 + recherche vectorielle ; réordonnancement optionnel. Mode par défaut pour les requêtes en langage naturel. |
+| `search` | FTS5 + vecteur hybride ; réordonnancement optionnel. Mode par défaut pour les requêtes en langage naturel. (+ limite de date supérieure `until`) |
 | `lookup_entity` | Historique précis des entités : variables d'environnement, commandes, identifiants de modèles, CVE, etc. |
-| `latest_releases` | Dernières versions disponibles pour les différents produits (ou un seul). |
+| `latest_releases` | Nouvelles versions récentes pour les produits (ou un seul). (+ limite de date inférieure `since`) |
 | `get_release` | Contenu complet d'une version. |
 | `list_products` | Énumération avec nombre d'occurrences + dernière version. |
 | `top_entities` | Entités les plus mentionnées par type. |
-| `list_synergies` | Flux de travail inter-produits sélectionnés. |
+| `list_synergies` | Flux de travail inter-produits. (+ filtre `product` optionnel) |
 | `read_synergy` | Texte intégral d'un fichier de synergie. |
+| `get_changes_since` | **Nouveau.** Modifications dans une fenêtre de temps, regroupées par produit + version. Entrées : `since` (obligatoire), `until?`, `product?`, `kind?`, `limit?`. |
+| `search_breaking_changes` | **Nouveau.** Liste plate des modifications importantes — aucun terme de recherche n'est nécessaire. Entrées : `product?`, `since?`, `until?`, `limit?`. |
+| `compare_versions` | **Nouveau.** Toutes les modifications entre deux versions d'un même produit. Entrées : `product`, `from_version`, `to_version`. |
+
+Les trois nouveaux outils reprennent `hk diff` / `hk breaking` et le flux de travail de comparaison de versions qui nécessitait auparavant un script. Consultez [manuel → serveur MCP](https://mcp-tool-shop-org.github.io/claude-synergy/handbook/mcp-server/) pour les schémas d'entrée complets.
 
 ---
 
@@ -226,11 +262,11 @@ Outils exposés :
 
 Vue d'ensemble complète dans [SOURCES.md](SOURCES.md).
 
-- **Niveau 1 (Dépôts GitHub)** — `gh api repos/<owner>/<repo>/releases` pour 22 produits, y compris les SDK Anthropic (7 langages), les SDK Agent (2), l'interface de ligne de commande ant, claude-code-action, claude-code-security-review, et 15 SDK de l'écosystème MCP.
-- **Niveau 2 (Markdown brut)** — `anthropics/claude-code/CHANGELOG.md` + `Aider-AI/aider/HISTORY.md`
-- **Niveau 3 (HTML / RSS)** — `platform.claude.com/docs/release-notes`, `support.claude.com/articles/12138966`, `cursor.com/changelog/rss.xml`, `sourcegraph.com/changelog/featured.rss` (filtré), `github.blog/changelog/label/copilot/`, `code.visualstudio.com/updates/v1_NNN`
-- **Niveau 4 (Catalogue)** — `anthropics/skills`, `claude-plugins-{official,community}`, `knowledge-work-plugins`
-- **Niveau 5 (Conseils)** — Compte X `@ClaudeCodeLog` ; miroir de changelog de marckrenn.
+- **Niveau 1 (Publications GitHub)** — `gh api repos/<owner>/<repo>/releases` pour 23 produits, y compris les SDK Anthropic (7 langages), les SDK Agent (2), l'outil CLI ant, **claude-code** (maintenant synchronisé automatiquement via gh-releases depuis la version v1.1 — auparavant configuré manuellement), claude-code-action, claude-code-security-review, et 15 SDK de l'écosystème MCP.
+- **Niveau 2 (Markdown brut)** — `Aider-AI/aider/HISTORY.md`. L'analyseur générique `keep-a-changelog` (v1.1+) est également disponible pour tout produit dont la source est un fichier CHANGELOG.md au format Keep-a-Changelog — à configurer via une entrée dans `products.yaml`.
+- **Niveau 3 (HTML / RSS)** — `platform.claude.com/docs/release-notes`, `support.claude.com/articles/12138966`, `cursor.com/changelog/rss.xml`, `sourcegraph.com/changelog/featured.rss` (filtré), `github.blog/changelog/label/copilot/`, `code.visualstudio.com/updates/v1_NNN`.
+- **Niveau 4 (catalogue)** — `anthropics/skills`, `claude-plugins-{official,community}`, `knowledge-work-plugins`.
+- **Niveau 5 (conseils)** — Compte X `@ClaudeCodeLog` ; miroir de changelog de marckrenn.
 
 Stratégies de récupération : `gh-releases | rss | raw-changelog | html-scrape | catalog | playwright`. Nouveau produit = une entrée dans `products.yaml`.
 
@@ -255,7 +291,7 @@ Index complet dans [synergies/INDEX.md](synergies/INDEX.md).
 La suite Vitest couvre les niveaux unitaires, d'intégration, de régression et de test de base. **[test-spec-3.md](test-spec-3.md) est la référence actuelle** à partir de la version v0.7.0 ; [test-spec.md](test-spec.md) (v1) et [test-spec-2.md](test-spec-2.md) (v2) restent dans le dépôt comme enregistrement historique de l'évolution de la conception.
 
 ```bash
-pnpm test               # unit + integration + regression (~16s, 382 tests)
+pnpm test               # unit + integration + regression (~18s, 508 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)
@@ -265,9 +301,9 @@ Structure :
 
 | Dossier | Ce qu'il couvre |
 |-----|----------------|
-| `test/unit/` | par module — extraction, ingestion, requête, base de données, intégration, recherche vectorielle, récupération + tous les fournisseurs + récupération-rss/changelog/html + récupération-mcp-registry + récupération-playwright + configuration des produits. |
-| `test/integration/` | de bout en bout — pipeline, synchronisation, serveur MCP (JSON-RPC via le flux standard), interface de ligne de commande. |
-| `test/regression/` | §8.1–§8.18 : chaque section protège contre un bug réel corrigé pendant le développement. |
+| `test/unit/` | par module — extraction, ingestion, requête (incl. `until` / navigation / depuis / comparaison), base de données (incl. migration de configuration de dimension v3), intégration, hybride, récupération + tous les fournisseurs (Ollama / Voyage / **OpenAI**) + récupération-RSS/changelog (incl. analyseur **keep-a-changelog**) / HTML + récupération-registre-MCP + récupération-playwright + configuration-produits + ingestion/requête de synergies. |
+| `test/integration/` | de bout en bout — pipeline, synchronisation, serveur MCP (JSON-RPC stdio, 11 outils), CLI (incl. `hk diff`, `hk breaking`). |
+| `test/regression/` | §8.1–§8.19 — chacun protège contre un bug réel corrigé pendant le développement (§8.19 : la pagination précoce de ghReleases préserve les éléments dans la fenêtre). |
 | `test/smoke/` | Test complet sur l'ensemble des fichiers (1 143 fichiers) simulant les produits réels. |
 | `test/fixtures/` | 3 produits factices + réponses HTTP simulées (RSS / GH / Voyage / Cohere / Ollama / Anthropic / Smithery / Registre MCP officiel). |
 | `test/helpers/` | `temp-db.ts`, `fetch-mock.ts`, `mcp-client.ts`, `seed-corpus.ts`, `golden-vectors.ts`, `playwright-mock.ts`, `yaml-fixtures.ts` |
@@ -308,8 +344,22 @@ La synchronisation est idempotente : il est sûr de la relancer après un échec
 
 La commande `hk embed` appelle un service d'intégration externe :
 
-- **Ollama (par défaut)** : assurez-vous qu'Ollama est en cours d'exécution (`ollama serve`) et que le modèle d'intégration est téléchargé (`ollama pull nomic-embed-text`).
-- **Voyage** : définissez la variable d'environnement `VOYAGE_API_KEY`. Vérifiez votre clé API sur [dash.voyageai.com](https://dash.voyageai.com).
+- **Ollama (par défaut, 768 dimensions)** : assurez-vous qu'Ollama est en cours d'exécution (`ollama serve`) et que le modèle d'intégration est téléchargé (`ollama pull nomic-embed-text`).
+- **Voyage (1024 dimensions)** : définissez la variable d'environnement `VOYAGE_API_KEY`. Vérifiez votre clé API sur [dash.voyageai.com](https://dash.voyageai.com).
+- **OpenAI (1536 dimensions par défaut, configurable)** : définissez la variable `OPENAI_API_KEY`. Le modèle par défaut est `text-embedding-3-small`; vous pouvez le modifier avec `OPENAI_EMBED_MODEL` (par exemple, `text-embedding-3-large` pour 3072 dimensions). Utilisez-le via `hk hybrid --embed openai` ou `hk embed --embed openai`.
+
+**Incompatibilité de la dimension des vecteurs lors du changement de fournisseur**
+
+Chaque fournisseur produit des vecteurs d'une dimension fixe (Ollama 768, Voyage 1024, OpenAI 1536 par défaut – OpenAI prend en charge une dimension configurable dans les limites de la taille native du modèle). La base de données stocke la dimension active dans `schema_meta.embedding_dim`. Le changement de fournisseur entre des dimensions différentes alors que des fragments existent déclenche une erreur `EMBEDDING_DIM_MISMATCH` (une erreur de l'application) plutôt que de corrompre silencieusement la table des vecteurs. Pour changer de fournisseur :
+
+```bash
+rm data/claude-synergy.db data/claude-synergy.db-wal data/claude-synergy.db-shm
+hk init
+hk ingest
+hk embed --embed openai     # new provider, new dim, fresh chunks_vec
+```
+
+Pour la troncature Matryoshka d'OpenAI (dimension inférieure à la dimension native), définissez `OPENAI_EMBED_MODEL` et passez la dimension souhaitée via la construction du fournisseur dans `hk embed` – consultez la [section sur les intégrations du manuel](https://mcp-tool-shop-org.github.io/claude-synergy/handbook/cli-reference/#embedding-providers-and-dimensions) pour plus de détails.
 
 **Incompatibilité de version du schéma / base de données corrompue**