Before you start
Discovery is the interview that decides what your mesh is — which pages exist, how they’re grouped, and what they target. Twenty minutes of prep makes that interview far better. You don’t need to know SEO; you need to bring a few facts about your business and a way to check real demand.
The one hard requirement: demand data
GoToMesh is demand-first. It doesn’t build pages from your internal product list — it builds them from what people actually search for, validated with real numbers. That needs an Ahrefs API token:
export AHREFS_API_TOKEN=… # an Ahrefs API v3 token; never commit itWithout a token, discovery can’t validate demand — it falls back to guesswork, and you can ship a structure nobody searches for. If you don’t have Ahrefs access, treat that as a decision to make before you start, not a detail to sort out later. See Installation for setup.
What to gather
Have answers to these ready — discovery will ask, and better answers mean a better mesh:
| Bring | Why it’s used |
|---|---|
| What you sell or publish, in one line | Frames the whole mesh and seeds the keyword research. |
| Who it’s for (the audience) | Separates your intent from lookalike searches (e.g. B2B vs consumer). |
| Your primary market (a country) | Search volumes are per-country; this sets where demand is measured. |
| Your site type | non_commercial (a publisher/content site), commercial_catalog (you sell many products), or commercial_pages (a few service/product landings). It fixes the whole structure. |
| Your product / category / topic set | For a catalogue: what you sell. For a content site: the topics you want to own. For services: your core offerings. This is the raw list discovery validates demand against. |
| A few competitors (domains) | Discovery checks its proposed shape against the pages that actually earn them traffic. |
| Brand basics — name, URL, one-line description | Templated into your repo (README, config) so it doesn’t ship saying “Acme”. |
You do not need to design URLs, choose page types, or write keywords up front. Discovery proposes all of that. You bring the business facts and the demand access; it brings the structure.
The mindset shift: your labels are not search queries
This is the thing that surprises everyone. The names you use internally are usually not what people search for — and GoToMesh builds around the real query, not your label. From a real run on a pump catalogue:
| Your catalogue label | Searches/mo | The real query | Searches/mo |
|---|---|---|---|
| ”submersible and drainage pumps” | 0 | submersible pump | 4,100 |
| ”centrifugal pumps” | 400 | centrifugal pump | 1,200 |
So expect discovery to:
- Rename things — a page’s target keyword becomes the real query (the URL can still stay clean and on-brand).
- Cut or merge categories you sell but nobody searches for — a page no one looks for is dead weight.
- Filter noise — if you’re B2B, the broad term universe is often dominated by consumer searches (for “pump”: heat pumps, breast pumps, bike pumps). Discovery filters to your intent so you don’t chase the wrong demand.
None of this is the tool being difficult — it’s the tool refusing to build pages that can’t win. Going in expecting it makes the output make sense.
What you’ll walk away with
Discovery writes a single file, gtmesh-discovery.yaml — the proposed shape of
your mesh (see the discovery contract). You
review and edit it, then gtmesh init --from-discovery scaffolds the project.
From there, head to After discovery — what to do
with the repo you just got.
Next: the end-to-end walkthrough runs the whole pipeline start to finish.