After discovery: tuning & your first pages

You ran gtmesh init --from-discovery and now you’re looking at a repo with dozens of files. This is the moment most people feel stuck. Here’s the reassuring truth: you don’t tune most of it. Almost everything is sensible defaults you’ll rarely touch. You drive one short loop, read one report, and fix a handful of things it flags.

This page is that handoff — what to look at first, the patterns that tell you something needs attention, which file fixes each, and how to build your first pages without risk.

Step 1 — see the shape (this is safe)

Nothing you run here changes your live site. plan is read-only and free; run it as many times as you like.

Pull demand, then plan


gtmesh extract        # pull the keyword data into data/raw/ (uses your Ahrefs token)
gtmesh plan           # print the diff — what pages SHOULD exist, read-only

Read two things in the plan

“Catalogue / create — by page type” — the shape. Does the count of each page type look about right? (200 comparison pages and 3 product pages is a smell.)
“Unresolved — N page(s) need a config rule” — every keyword the engine could not confidently route. This is your to-do list. The engine never guesses; anything it can’t place, it shows you here.

The loop is: read the plan → adjust one input → gtmesh plan again. Re-planning costs nothing and changes nothing, so iterate freely until the plan looks right. You only ever change inputs (config + reference files); the registry is computed.

Step 2 — the patterns to look for

You’re scanning the plan for a few recognisable situations. For each, here’s what it means and the one file you change. The full knob-by-knob detail is in Tuning — this table is the “which pattern → which file” shortcut.

What you see in the plan	What it means	What to change
Unresolved list has real queries you do want pages for	No routing rule matched them	Add a `when → then` rule in `sections_map` (Tuning §3) until only junk is left unresolved
A page you expected is missing, or has ~0 volume	Nobody searches that term — demand didn’t validate it	Cut or merge it, or it’s named wrong: re-target its `primary_keyword` to the real query (see Before you start)
The URL or title reads off the wrong keyword	The slug anchored to a divergent label	`identity.anchor`, or a `rename` group-edit to move a committed URL (mental models)
Junk / consumer pages on a B2B site (logins, “jobs”, consumer variants)	Noise in the keyword universe	`exclude_substrings` (drops at extract) or `scope.yaml` (parks to backlog) — Tuning §6
No hubs — everything is a low-tier spoke	Your conversion pages weren’t marked as hubs	Add role/tier rules in `reference/signals.csv`, or declare apex pages in `reference/seed-pages.csv` (Tuning §4 & §7)
Lots of thin, near-duplicate pages from one topic	A stray keyword minted a fragment	Set `classification.min_group_members: 2` (Tuning §1)
Far too many pages overall	The long tail is too long	Raise the volume floor in `scope.yaml` to park low-demand rows

You can’t break anything by editing these and re-planning. The worst case is the plan looks wrong and you adjust again. Nothing ships until you deliberately promote and publish (Step 3).

Step 3 — scaffold your first pages safely

When the plan looks right, don’t build everything at once. Writing is the one expensive, human-facing step — so prove the setup on a small batch first.

Catalogue everything (still builds no pages)


gtmesh apply          # records every page in the registry; creates no page bodies

Promote ONE small batch

Pick a single hub and the pages that feed it, or one small section:


gtmesh promote --under /<your-hub-slug>     # a hub + its cluster
# …or:
gtmesh promote --section <one-section>
gtmesh apply                                 # scaffolds just those pages → writing

Write, validate, and eyeball one page

Run the article-writer skill on a single page, then check it:


gtmesh validate <slug>    # schema + editorial lint
gtmesh seal <slug>        # only if valid → review

Open the page. Is the brief sensible? Is the structure right? Are the up-links and siblings pointing where you’d expect? If yes, you’ve validated the whole pipeline on one page.

Now promote the next batch

Repeat with a larger batch. You’ve caught any config problem on one page instead of a hundred.

The golden rule: promote small, look, then promote more. promote is the gate precisely so you never mass-produce pages you haven’t sanity-checked.

What you can safely ignore (for now)

Not everything needs your attention on day one. These ship as working defaults and can wait — or stay untouched:

The AEO / citability gate (aeo: in config) — the quality bar for drafts. The defaults are sensible; tune the numbers later if reviews feel off.
Images — pages publish fine with no images; add them when you’re ready.
Schemas, templates, voice files — the defaults work. Tune foundation/voice.md when you have a house style to enforce.
Scoring weights, rubrics, transforms — advanced levers. Leave them until the shape and the first pages are solid.

Your first session, in order

gtmesh extract → gtmesh plan, and read the Unresolved list.
Fix the obvious routing/demand issues (Step 2), re-planning until it looks right.
gtmesh apply to catalogue.
gtmesh promote --under … one hub, gtmesh apply, write + seal one page, and look at it.
Happy? Promote the rest in batches. Then you’re into the steady-state refresh loop.

Lost about what a command does or what a status means? The CLI Reference and the glossary are the lookups; Lifecycle explains what each kind of change does to a page once it’s built.