feat: search(query) MCP tool — cerca cross-repo via GitHub API + topic_index (#60)

* feat: search(query) MCP tool — cerca cross-repo via GitHub API + topic_index

* fix: word boundary matching in search() — 'pubblica' non matcha piu' 'pubblicati'

* docs: documenta search() tool nel README

* docs: riscrive README — allineato a stato reale ACB (10 repo, v3, search)

- session_bootstrap non più '~40 righe' (ora 80+)
- topic_index da v2 a v3 (analyses)
- tool MCP: tabella con output e quando usarlo
- search: sezione dedicata con esempio JSON
- esempio config: ora link a dataciviclab.config.yml
- sezione degrado: unificata e aggiornata (search issues)
- rimosso riferimento windows (codex-context.ps1 non esiste piu')
- riorganizzato: artifact prodotti/consumati prima, tool MCP dopo

Author: Gabrymi93

README.md

@@ -3,135 +3,131 @@
 Genera contesto operativo compatto per agenti [DataCivicLab](https://github.com/dataciviclab)
 da GitHub e, se disponibile, dai checkout locali dei repo Lab.
 
-## Artifact
+ACB è il **layer di contesto** dell'ecosistema: ogni 6 ore scansiona 10 repo,
+colleziona segnali da source-observatory, dataset-incubator e data-explorer,
+e produce artifact che dicono ad agenti e umani *"cosa è successo e cosa serve attenzione"*.
+
+## Artifact prodotti
 
 | Artifact | Versione | Ruolo |
 |---|---|---|
-| `session_bootstrap.md` | — | orientamento rapido per agenti e umani (~40 righe) |
-| `workspace_triage.json` | v1 | PR, issue, discussion, warning, git state |
-| `topic_index.json` | v2 | repos attivi, dataset per fonte, topic operativi |
+| `session_bootstrap.md` | — | orientamento rapido: segnali, PR, discussion, stato git |
+| `workspace_triage.json` | v1 | dati strutturati: issue, PR, discussion, warning, radar, pipeline |
+| `topic_index.json` | v3 | indice navigabile: repos, dataset per fonte, analisi, explorer themes |
 
-La CI aggiorna gli artifact GitHub-only ogni 6 ore sul branch `context`.
+URL su branch `context`:
 
-## Artifact Consumati
+```text
+https://raw.githubusercontent.com/dataciviclab/agent-context-builder/context/session_bootstrap.md
+https://raw.githubusercontent.com/dataciviclab/agent-context-builder/context/workspace_triage.json
+https://raw.githubusercontent.com/dataciviclab/agent-context-builder/context/topic_index.json
+```
 
-ACB preferisce artifact JSON generati e versionati dai repo Lab rispetto a
-frontmatter o README manuali. Oggi consuma:
+## Artifact consumati da upstream
 
 | Repo | Path | Uso |
 |---|---|---|
-| `source-observatory` | `data/radar/radar_summary.json` | health complessivo delle fonti nel registry |
-| `source-observatory` | `data/catalog/catalog_signals.json` | drift/inventory per singola fonte |
-| `dataset-incubator` | `registry/pipeline_signals.json` | stato operativo dei dataset candidate |
-| `dataset-incubator` | `registry/clean_catalog.json` | dataset clean/queryable disponibili |
+| `source-observatory` | `data/radar/radar_summary.json` | health 33 fonti (GREEN/YELLOW/RED) |
+| `source-observatory` | `data/catalog/catalog_signals.json` | drift inventariale per fonte |
+| `dataset-incubator` | `registry/pipeline_signals.json` | stato 83 candidate pipeline |
+| `dataset-incubator` | `registry/clean_catalog.json` | 63 dataset pubblicati (slug, colonne, periodo) |
+| `data-explorer` | `src/data/themes.json.py` | 6 temi editoriali + gap explorer |
 
-`radar_summary` presidia la connettivita' e la disponibilita'; `catalog_signals` resta sul drift inventariale.
+## Tool MCP
 
-URL raw:
+Esposti via `agent-context-mcp` (server MCP `dataciviclab-context`).
 
-```text
-https://raw.githubusercontent.com/dataciviclab/agent-context-builder/context/session_bootstrap.md
-https://raw.githubusercontent.com/dataciviclab/agent-context-builder/context/workspace_triage.json
-https://raw.githubusercontent.com/dataciviclab/agent-context-builder/context/topic_index.json
-```
-
-## Utilizzo
+| Tool | Output | Quando usarlo |
+|---|---|---|
+| `session_bootstrap()` | Markdown | Prima chiamata della sessione — orientamento: segnali, PR, discussion, radar |
+| `workspace_triage()` | JSON | Dati precisi: conteggi, stato git, source health, pipeline state |
+| `topic_index(resolve=)` | JSON | Esplorare dataset/analisi per tema o slug |
+| `search(query, limit=10)` | JSON | Cercare in tutto il Lab: issue, PR, dataset, analisi |
+| `refresh_context()` | OK/error | Forzare rebuild CI (richiede GITHUB_TOKEN con scope workflow) |
 
-### Shared mode via MCP
+### `search()` nel dettaglio
 
-Usa `agent-context-mcp` / `dataciviclab-context` per leggere gli artifact remoti.
-Non richiede checkout locale.
+Combina due fonti in una risposta:
 
-```bash
-pip install -e ".[mcp]"
-agent-context-mcp
+```
+search("disuguaglianza")
+  ├── GitHub Issues Search API → issue/PR da tutti i repo dataciviclab
+  └── topic_index.json locale → dataset e analisi per nome/slug/fonte
 ```
 
-Tool MCP:
+Senza `GITHUB_TOKEN` funziona solo su dataset e analisi (topic_index).
 
-| Tool | Uso |
-|---|---|
-| `session_bootstrap` | orientamento rapido: repo attivi, PR, issue, discussion |
-| `workspace_triage` | triage machine-readable: PR, issue, warning, git state |
-| `topic_index` | indice v2: repos, datasets per fonte, topic operativi |
-| `refresh_context` | triggera build CI; richiede `GITHUB_TOKEN` con scope `workflow` |
+Esempio di risposta:
 
-Esempio `settings.json`:
+```json
+{
+  "query": "rifiuti",
+  "total": 9,
+  "results": {
+    "issues": [
+      {"repo": "dataciviclab/data-explorer", "number": 201, "title": "feat: add ISPRA GHG...", "type": "pr"}
+    ],
+    "datasets": [
+      {"slug": "ispra_ru_base", "name": "Rifiuti Urbani", "source": "ISPRA"}
+    ],
+    "analyses": [
+      {"slug": "rifiuti-km2", "name": "Rifiuti per km²..."}
+    ]
+  }
+}
+```
+
+### Configurazione MCP
 
 ```json
 {
   "mcpServers": {
     "dataciviclab-context": {
       "command": "agent-context-mcp",
       "env": {
-        "GITHUB_TOKEN": "<opzionale-per-refresh>"
+        "GITHUB_TOKEN": "<opzionale: serve per refresh_context e search issues>"
       }
     }
   }
 }
 ```
 
-### Local mode
-
-Esegue il builder localmente per includere lo stato git (branch, dirty).
+## Utilizzo locale
 
 ```bash
-pip install -e .
-agent-context build \
-  --config dataciviclab.config.yml \
-  --out generated/ \
-  --workspace-root ~/dev/dataciviclab-workspace
-```
-
-Windows:
-
-```powershell
-.\codex-context.ps1 -WorkspaceRoot "C:\path\to\dataciviclab-workspace"
-```
-
-Il wrapper imposta UTF-8, neutralizza `CURL_CA_BUNDLE` ereditato e usa `.venv314`
-o `.venv` se presenti.
-
-## Configurazione (`dataciviclab.config.yml`)
+pip install -e ".[mcp]"
 
-Definisce organizzazione, repo e topic da monitorare.
+# Solo GitHub (stato CI)
+agent-context build --config dataciviclab.config.yml --out generated/
 
-```yaml
-github_org: dataciviclab
-repos:
-  - dataset-incubator
-  - dataciviclab
-topics:
-  datasets:
-    summary: Incubazione dataset
-    repos: [dataset-incubator, dataciviclab]
-    paths: [dataset-incubator/, dataciviclab/analisi/]
+# Con stato git locale
+agent-context build --config dataciviclab.config.yml --out generated/ \
+  --workspace-root ~/dev/dataciviclab-workspace
 ```
 
-`workspace_root` resta fuori dalla config: usare `--workspace-root` o
-`DATACIVICLAB_WORKSPACE`. `GITHUB_TOKEN` serve per GitHub Discussions e refresh CI.
-
-Variabili MCP utili: `ACB_REPO`, `ACB_BRANCH`.
+Variabili ambiente utili:
+- `GITHUB_TOKEN` — per discussion, refresh, search issues
+- `DATACIVICLAB_WORKSPACE` — path workspace locale
+- `ACB_REPO`, `ACB_BRANCH` — override repo/branch MCP (default: `dataciviclab/agent-context-builder`, `context`)
 
 ## Degradazione controllata
 
-Il builder non deve crashare per contesto parziale:
+Nessun crash per contesto parziale:
 
 | Condizione | Comportamento |
 |---|---|
 | rate limit / 403 GitHub | campi `null`, errore in JSON |
-| repo privato senza token | repo saltato, warning registrato |
-| nessun token | discussion saltate |
+| nessun token | discussion e search issues saltate; topic_index search funziona |
+| repo upstream non disponibile | `available: false`, articolazioni interne populate |
 | repo locale assente | `available: false`, `reason: path_not_found` |
-| path non git | `available: false`, `reason: not_git_repo` |
 | local mode non attivo | `available: false`, `reason: local_disabled` |
 
 ## Sviluppo
 
 ```bash
 pip install -e ".[dev]"
 pytest
-ruff check .
+ruff check src/ tests/
 ```
 
 ## Licenza