Blueprint 1.6.1 // user guide
Querymantic
Turn a keyword export into a map of the real demand behind AI answers. Offline, deterministic, every number traces back to its row.
You drop your keyword exports into the workspace. Querymantic reads them, runs a deterministic analysis, and writes one structured file you build on. It makes no external calls and loads nothing at runtime. No API, no account, no telemetry.
It reads CSV or TSV from Semrush, Ahrefs, Google Search Console, Moz, Ubersuggest, or a generic CSV, and normalizes them into one schema. On top of the vendored engine it adds seven analysis modules and a guide built for SEO, GEO, and AI-search strategy. The output is run.json, the single state of the run, with a fingerprint of the inputs. Every figure is reproducible and checkable.
Six practical reasons Querymantic changes how you work demand, before you even open a module.
Offline, no API, no account, no telemetry. You can analyze a client's data without shipping it to a third-party service.
Same file, same result, and every figure traces back to the row that produced it. In front of a client you can show where each number comes from.
The fan-out of zero-volume sub-queries decides AI citations and stays hidden from classic tools. Querymantic brings it to the surface.
It reads exports from Semrush, Ahrefs, Search Console, Moz, Ubersuggest, SeoZoom, or any CSV. No new subscription to open.
From one run you get dashboards, decks, Word audits, and Excel sheets, branded and ready for the client in minutes.
The fifth layer reads Italian intent that an English-born engine would mislabel, and fixes it before the analysis.
Classic keyword research hunted for the big term to rank for and win the click. AI answer engines work differently. When a user asks a question, the engine breaks it into a fan of sub-questions, the fan-out, and builds the answer by covering them one by one. To get cited inside that answer you do not win the head term. You cover the fan-out.
Keyword tools show you the head. The AI engine works the whole fan-out, and almost every one of those sub-queries reads as zero volume. That is why classic tools never show them.
The rule to remember
If a clean export leaves you fifty zero-volume sub-queries that fit the topic, keep them. One by one they are worth nothing. Together they are the fan-out. The value sits in the structure that links them. A single word's volume says little.
So you do not filter the export by volume before the analysis. That long tail carries the fan-out signal, and you keep all of it.
You do not memorize commands. Once the plugin is installed, inside Claude Code and Claude Cowork you drop an export in the workspace and describe what you want.
Drop the export in the folder and write what you want, in plain language. The prompt section below has a good stock of them, grouped by goal.
Inside Claude Code and Cowork two commands wrap the same pipeline: /querymantic-analyze for analysis and /querymantic-audit for the full audit.
From the plugin folder, with Python 3.10 or newer, no extra dependencies for the core.
Each command with --help lists every option. The three subcommands are run, forge, and validate.
Copy them, adapt them, paste them into Claude Code or Cowork with your export in the workspace. They are plain language. You describe the goal, the plugin picks the modules.
No code, no commands. You drag in the file and talk the way you would talk to a person. Querymantic does the rest.
The first look at demand, when you open a new export.
All the lenses at once, for a full view.
When you want one module, focused.
The engine is born in English, its main language, and reads French, German, and Spanish well. Querymantic adds Italian as a fifth language. With a non-English export, name the language so intent reads right.
The prompts that keep you honest about the fan-out.
When the analysis has to ship as a document.
To confirm every number holds.
Each module answers one question and writes its own space inside run.json. All offline, all traceable.
01 // coverage
Does my cluster cover the sub-queries the engine would break the request into? It finds the gatekeepers and the missing archetypes. This is the core lens.
02 // citability
How ready is this cluster to get cited in AI answers? It turns that into an editorial checklist, cluster by cluster.
03 // authority
Which entities I own and which I only ask for. It maps topical authority and the entity gaps to close.
04 // trend
Whether demand is rising, falling, seasonal, or flat. It wants the monthly series as input (--series). Without it, clusters come back unknown.
05 // priority
The band of winnable organic clicks per cluster. Always a band with a low and a high, because a single value would lie about its own precision. Priority follows real clicks over raw volume.
06 // opt-in
It pulls in observed data from Search Console and real citations, and compares measured against expected. Off by default. It will not run without that data.
07 // delivery
It turns a run into client deliverables: script-free HTML dashboards, .pptx decks, .docx audits, .xlsx workbooks, all brandable. A format without its library gets skipped and logged, never faked.
On top of the engine's four languages, English, French, German, and Spanish, Querymantic adds Italian as a fifth language: it detects and reclassifies Italian intent before the other modules run.
Querymantic opens the work and draws its structure before you write a line. The order counts.
--series it classifies the trend, without it returns unknown, and that is not a bug.Method honesty
The fan-out numbers are a deterministic model of the fan-out, computed from the corpus. They are not the real fan-out observed from ChatGPT or an AI Overview. They are an estimate that holds up to a re-check, with declared parameters, and you treat them as an estimate. Never present them in an article as hard facts from the engine.
The sub-query count per cluster is a configurable ceiling, labeled as a secondary estimate, not a figure from a search engine.
An output format without its optional library gets skipped and logged, never faked. What this guide documents works. The rest lives in the roadmap as exactly that.
Sprint 2
The technical part
Here you open the hood. The run.json structure, the module slots, the right order of the lenses, the advanced command-line options, and the provenance manifest that keeps the numbers honest. You need it if you want to drive Querymantic by hand or understand where every figure comes from.
Every run writes one file, run.json, and it is the source of truth for that analysis. It has three keys at the top level, and each one has a precise job.
It is the run's registry. It holds schema_version and plugin_version, the generation time, the list of inputs, and above all input_hash, the sha256 fingerprint of the source files. Change an input file and the fingerprint changes. That is how every result stays reproducible and checkable.
The analysis from the vendored keyword-intelligence engine. The stable fields everything builds on live here: the corpus overview, per-keyword metrics and scores, topical clusters, and gaps. The engine answers one question. What demand exists and how it is structured.
One space per module. Each one reads the state, writes its own slot, and leaves the others alone. There are eight slots, in the order that makes sense to run them.
You pick modules with --modules and they run in the order you list them. The order carries weight. Some modules read the work of others, so if you place them wrong they read raw data instead of the corrected kind.
Two dependencies to respect
On an Italian export, list language_layer first, before the analysis lenses, so everything else reads language and intent already corrected.
Then entity_web goes before fan_out_radar: the Radar uses the entity graph when it is there, and still works without it, in reduced form.
A full, safe order on an Italian corpus, the way the module's own code suggests:
Without --modules, the default set runs. You list it only when you want a subset or your own order.
Three subcommands, run, forge, and validate. The options that matter, grouped by what they do.
--inputsfolder or CSV/TSV file to analyze.--outputwhere to write run.json.--modulesthe modules to apply, in the given order.--labela label to recognize the run.--client-domainturns on gap analysis against the client's domain.--brand-listsplits brand demand from non-brand.--seriesbrings the monthly series, which Demand Pulse needs to classify the trend.--seozoom-yearties the year to a SeoZoom export's monthly columns, so periods become real dates. Without it they stay neutral labels, because you do not invent the year.--livewireturns on Live Wire, the one module that looks at observed data. Off by default.--formatswhich deliverables to render: html, pptx, docx, xlsx.--outthe destination folder for the artifacts.--brandthe brand file used to color and mark the outputs.Each subcommand with --help shows the full list. A format without its optional library gets skipped and logged, never faked.
Next to the sample outputs lives a manifest, _provenance.json. It serves one purpose. To stop the outputs committed as proof from going stale in silence when the code that generates them changes. It is the guard that keeps the guide itself honest.
It has three parts, all readable at a glance.
artifactsthe sha256 of each output file treated as proof.sourcesthe sha256 of each source that determines those bytes: the module code, the engine, the input samples, the gazetteer, the brand template, the plugin version.perimeterthe explicit statement of what is in and what is out, with the reason written line by line.The limit, written down
Outside the perimeter sit the interpreter and the operating system, because a different OS or Python can reproduce the same numbers with last-bit differences in the decimals, and a byte check would mark them as errors. So the manifest signs the sources, not the output bytes across different platforms.
The third-party libraries that render the bytes, like the ones for pptx and xlsx, enter the perimeter through their declared pins. A version change trips the guard. One gap stays, named openly in the manifest: an environment whose installed versions drift from the pins can change the bytes without moving any source signature. The --check-committed control covers it, on request, in the fixed local environment.
One idea holds it all together. The engine says what demand exists and how it is shaped. The modules say what to do with it. The single state, run.json, links the two, and each module is a pure step. It reads the state, writes its own slot, touches nothing else.
Determinism is enforced in continuous integration: same input, same output, byte for byte, on Python 3.10 and 3.12. That is where the promise at the backbone of Querymantic comes from, and now you can check it with your own hands by opening run.json and following the fingerprints.
Click-based keyword research has stopped being enough. Answer engines break every question into a fan of sub-queries, and the page that wins is the one that covers the fan-out. Querymantic makes it visible, offline, with every number tracing back to its row.
From here the practice is simple. Cast the net wide, keep the whole tail, read the Fan-Out Radar gatekeepers, and build the content structure on them. The numbers you get are a model, with declared parameters, and that keeps you honest when you write. Sprint 2 gave you the levers to drive all of it by hand and to check every figure yourself.
This Blueprint is a starting point to bend to your work. Try it on a real export, open run.json, follow the fingerprints. The demand nobody types is right there, and now you know where to look.