Before you start

After gtmesh init scaffolds your repo, you open it in Claude Code and run the repo-local operator skill. The operator interviews you to decide 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 it

Without a token, the operator can’t validate demand — it falls back to guesswork, and you can ship a structure nobody searches for. A missing AHREFS_API_TOKEN is a blocking decision the operator surfaces up front, not a detail to sort out later. If you don’t have Ahrefs access, treat that as a decision to make before you start. See Installation for setup.

What to gather

Have answers to these ready — the operator 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 the operator validates demand against.
A few competitors (domains)	The operator 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. The operator 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 the operator 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). The operator 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 happens next

You run gtmesh init to scaffold the repo, then open it in Claude Code and run the operator skill. The operator takes the facts above into its interview, then drives the build loop conversationally — validating demand, building config and reference tables through the deterministic CLI verbs, planning, resolving what the plan flags, and applying — with a human approval gate on every judgement call. From there, head to After init — what to do with the repo you just got.

Next: the end-to-end walkthrough runs the whole pipeline start to finish.