Blueprint 1.6.1 // guida d'uso
Querymantic
Trasforma un export di keyword in una mappa della domanda reale dietro le risposte AI. Offline, deterministico, ogni numero risale alla sua riga.
Tu lasci nello spazio di lavoro i tuoi export di keyword. Querymantic li legge, esegue un'analisi deterministica e scrive un solo file strutturato su cui costruire. Non fa nessuna chiamata esterna e non carica niente a runtime: niente API, niente account, niente telemetria.
Legge CSV o TSV da Semrush, Ahrefs, Google Search Console, Moz, Ubersuggest o un CSV generico, e li normalizza in un solo schema. Sopra il motore vendorizzato aggiunge sette moduli di analisi e una guida d'uso pensata per la strategia SEO, GEO e di ricerca AI. Il risultato è run.json, lo stato unico della run, con l'impronta degli input: ogni cifra è riproducibile e verificabile.
Sei motivi pratici per cui Querymantic cambia il modo in cui lavori la domanda, prima ancora di aprire un modulo.
Offline, nessuna API, nessun account, nessuna telemetria. Analizzi i dati di un cliente senza spedirli a un servizio di terzi.
Stesso file, stesso risultato, e ogni cifra risale alla riga che l'ha prodotta. Davanti a un cliente non porti una scatola nera, porti una prova.
La raggiera di sotto query a volume zero decide le citazioni AI e resta nascosta agli strumenti classici. Querymantic la porta in superficie.
Legge gli export di Semrush, Ahrefs, Search Console, Moz, Ubersuggest, SeoZoom o un CSV qualsiasi. Nessun abbonamento nuovo da aprire.
Da una sola run escono dashboard, deck, audit Word e fogli Excel brandizzati, pronti per il cliente in pochi minuti.
Il quinto layer legge l'intento italiano che un motore nato in inglese classificherebbe male, e lo corregge prima dell'analisi.
La ricerca keyword classica cercava la parola grossa da intercettare per prendere il clic. I motori di risposta AI non funzionano così. Quando un utente fa una domanda, il motore la scompone al suo interno in una raggiera di sotto domande, il fan-out, e costruisce la risposta coprendole una a una. Per essere citati dentro quella risposta non serve vincere il termine di testa. Serve coprire la raggiera.
I tool di keyword ti mostrano la testa. Il motore AI lavora sull'intera raggiera, e quasi tutte quelle sotto query riportano volume zero. È per questo che gli strumenti classici non le mostrano mai.
La regola da non scordare
Se da un export ben pulito restano cinquanta sotto query a volume zero, pertinenti al tema, non sono da buttare. Una per una non valgono niente. Insieme sono la raggiera. Il valore non sta nel volume della singola parola, sta nella struttura che le lega.
Quindi non si filtra l'export per volume prima dell'analisi. Quella coda lunga porta il segnale del fan-out, e va tenuta tutta.
Non devi imparare comandi a memoria. Una volta installato il plugin, dentro Claude Code e Claude Cowork basta lasciare un export nello spazio di lavoro e descrivere a parole cosa vuoi.
Lasci l'export nella cartella e scrivi cosa vuoi, in linguaggio naturale. La sezione dei prompt qui sotto ne raccoglie una buona scorta, divisi per obiettivo.
Dentro Claude Code e Cowork due comandi avvolgono la stessa pipeline: /querymantic-analyze per l'analisi e /querymantic-audit per l'audit completo.
Dalla cartella del plugin, con Python 3.10 o più recente, senza altre dipendenze per il nucleo.
Ogni comando con --help elenca tutte le opzioni. I tre sottocomandi sono run, forge e validate.
Copiali, adattali, incollali dentro Claude Code o Cowork con il tuo export nello spazio di lavoro. Sono in linguaggio naturale: descrivi l'obiettivo, ci pensa il plugin a scegliere i moduli.
Niente codice, niente comandi. Trascini il file e parli come parleresti a una persona. Querymantic fa il resto.
Il primo sguardo sulla domanda, quando apri un export nuovo.
Tutte le lenti in una volta, per una vista a 360 gradi.
Quando vuoi un solo modulo, mirato.
Il motore nasce in inglese, la sua lingua principale, e legge bene anche francese, tedesco e spagnolo. Querymantic aggiunge l'italiano come quinta lingua. Con un export non inglese conviene dichiarare la lingua, così l'intento viene letto giusto.
I prompt che ti tengono onesto sul fan-out.
Quando l'analisi deve uscire come documento.
Per controllare che ogni numero regga.
Ogni modulo risponde a una domanda precisa e scrive il proprio spazio dentro run.json. Tutti offline, tutti tracciabili.
01 // copertura
Il mio cluster copre le sotto query in cui il motore scomporrebbe la richiesta? Trova i gatekeeper e gli archetipi di domanda mancanti. È la lente centrale.
02 // citabilità
Quanto è pronto questo cluster a essere citato nelle risposte AI? Lo traduce in una checklist editoriale, cluster per cluster.
03 // autorità
Quali entità possiedo davvero e quali solo domando. Mappa l'autorità topica e i buchi di entità da chiudere.
04 // trend
La domanda è in crescita, calo, stagionale o piatta. Vuole la serie mensile in input (--series): senza, i cluster tornano unknown.
05 // priorità
La banda di clic organici conquistabili per cluster. Dà sempre una banda con un minimo e un massimo, perché un singolo valore mentirebbe sulla precisione. Così la priorità segue i clic veri e non il volume grezzo.
06 // opt-in
Porta dentro i dati osservati da Search Console e le citazioni reali, e confronta il misurato con l'atteso. Spento di default: non gira senza quei dati.
07 // consegna
Trasforma una run nei deliverable per il cliente: dashboard HTML senza script, deck .pptx, audit .docx, workbook .xlsx, tutti brandizzabili. Un formato senza la sua libreria viene saltato e messo a verbale, mai finto.
Sopra le quattro lingue del motore, inglese, francese, tedesco e spagnolo, Querymantic aggiunge l'italiano come quinta lingua: rileva e riclassifica l'intento italiano prima che gli altri moduli girino.
Querymantic apre il lavoro e ne disegna la struttura, prima che tu scriva una riga. L'ordine conta.
--series classifica il trend, senza torna unknown e non è un bug.Onestà di metodo
I numeri della raggiera sono un modello deterministico del fan-out, calcolato dal corpus. Non sono il fan-out reale osservato da ChatGPT o da una AI Overview. Sono una stima che regge alla riprova, con i suoi parametri dichiarati, e come stima vanno trattati. Mai presentarli in un articolo come fatti certi sparati dal motore AI.
Il conteggio delle sotto query per cluster è un tetto configurabile, etichettato come stima secondaria, non come dato di un motore di ricerca.
Un formato di output senza la sua libreria opzionale viene saltato e registrato, mai prodotto finto. Quello che la guida documenta funziona, il resto vive nella roadmap come tale.
Sprint 2
La parte tecnica
Qui si apre il cofano. Struttura di run.json, gli slot dei moduli, l'ordine giusto delle lenti, le opzioni avanzate della riga di comando e il manifesto di provenienza che tiene onesti i numeri. Serve se vuoi pilotare Querymantic a mano o capire da dove esce ogni cifra.
Ogni run scrive un solo file, run.json, ed è la fonte di verità di quell'analisi. Ha tre chiavi al primo livello, e ognuna ha un compito preciso.
È l'anagrafe della run. Contiene schema_version e plugin_version, il momento di generazione, la lista degli input e soprattutto input_hash, l'impronta sha256 dei file di partenza. Cambi un file di input, cambia l'impronta: è così che ogni risultato resta riproducibile e verificabile.
L'analisi del motore keyword-intelligence vendorizzato. Qui vivono i campi stabili su cui tutto poggia: il riepilogo del corpus, le metriche e i punteggi per keyword, i cluster topici e i gap. Il motore risponde a una domanda: quale domanda esiste e com'è strutturata.
Uno spazio per ogni modulo. Ognuno legge lo stato, scrive il proprio slot e non tocca quello degli altri. Gli slot disponibili sono otto, nell'ordine in cui ha senso eseguirli.
I moduli si scelgono con --modules e girano nell'ordine in cui li elenchi. L'ordine pesa: alcuni moduli leggono il lavoro di altri, quindi se li metti storti leggono dati grezzi al posto di quelli corretti.
Due dipendenze da rispettare
Su un export italiano, language_layer va elencato per primo, prima delle lenti di analisi, così tutti gli altri leggono lingua e intento già corretti.
Poi entity_web va prima di fan_out_radar: il Radar usa il grafo delle entità quando c'è, e funziona comunque anche senza, in forma ridotta.
Un ordine completo e sicuro su corpus italiano, come lo suggerisce lo stesso codice del modulo:
Se non passi --modules, gira l'insieme predefinito. Lo elenchi solo quando vuoi un sottoinsieme o un ordine tuo.
Tre sottocomandi, run, forge e validate. Le opzioni che contano, raggruppate per cosa fanno.
--inputscartella o file CSV/TSV da analizzare.--outputdove scrivere run.json.--modulesi moduli da applicare, nell'ordine dato.--labelun'etichetta per riconoscere la run.--client-domainattiva la gap analysis contro il dominio del cliente.--brand-listsepara la domanda brand da quella non brand.--seriesporta la serie mensile, necessaria a Demand Pulse per classificare il trend.--seozoom-yearaggancia l'anno alle colonne mensili di un export SeoZoom, così i periodi diventano date vere. Senza, restano etichette neutre, perché l'anno non si inventa.--livewireaccende Live Wire, l'unico modulo che guarda dati osservati. Spento di default.--formatsquali deliverable rendere: html, pptx, docx, xlsx.--outla cartella di destinazione degli artefatti.--brandil file di brand con cui colorare e marcare gli output.Ogni sottocomando con --help mostra la lista completa. Un formato senza la sua libreria opzionale viene saltato e registrato, mai prodotto finto.
Accanto agli output di esempio vive un manifesto, _provenance.json. Serve a una cosa sola: impedire che gli output committati come prova invecchino in silenzio quando cambia il codice che li genera. È la guardia che tiene onesta la guida stessa.
Ha tre parti, tutte leggibili a occhio.
artifactslo sha256 di ogni file di output considerato prova.sourceslo sha256 di ogni sorgente che determina quei byte: il codice dei moduli, il motore, i campioni di input, il gazetteer, il template di brand, la versione del plugin.perimeterla dichiarazione esplicita di cosa è dentro e cosa è fuori, con la motivazione scritta voce per voce.Il limite, dichiarato per iscritto
Fuori dal perimetro stanno l'interprete e il sistema operativo, perché un OS o un Python diverso può riprodurre gli stessi numeri con differenze all'ultimo bit dei decimali, e un controllo sui byte le segnerebbe come errori. Per questo il manifesto firma le sorgenti, non i byte di output tra piattaforme diverse.
Le librerie terze che rendono i byte, come quelle per pptx e xlsx, entrano nel perimetro tramite i loro pin dichiarati: un cambio di versione fa scattare la guardia. Resta un solo varco, nominato apertamente nel manifesto: un ambiente le cui versioni installate divergono dai pin può cambiare i byte senza muovere alcuna firma di sorgente. Lo copre, su richiesta, il controllo --check-committed nell'ambiente locale fissato.
Una sola idea tiene insieme tutto. Il motore dice quale domanda esiste e com'è fatta. I moduli dicono cosa farne. Lo stato unico, run.json, lega i due, e ogni modulo è un passo puro: legge lo stato, scrive il proprio slot, non tocca altro.
Il determinismo è imposto in integrazione continua: stesso input, stesso output, byte per byte, su Python 3.10 e 3.12. Da qui viene la promessa che fa da spina dorsale a Querymantic, e che adesso sai verificare con le tue mani aprendo run.json e seguendo le impronte.
La ricerca keyword a clic ha smesso di bastare. I motori di risposta scompongono ogni domanda in una raggiera di sotto query, e la pagina che vince è quella che copre la raggiera. Querymantic la rende visibile, offline, con ogni numero che torna alla sua riga.
Da qui la pratica è semplice. Getti la rete larga, tieni la coda intera, leggi i gatekeeper del Fan-Out Radar e ci costruisci sopra la struttura del contenuto. I numeri che ottieni restano un modello, con i loro parametri dichiarati, e questo ti tiene onesto quando scrivi. Lo Sprint 2 ti ha dato le leve per pilotare il tutto a mano e per controllare ogni cifra da te.
Questo Blueprint è un punto di partenza da piegare al tuo lavoro. Provalo su un export vero, apri run.json, segui le impronte. La domanda che nessuno digita è lì, e adesso sai dove guardare.