After init: tuning & your first pages

You ran gtmesh init and started the operator loop, 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. The operator drives one short loop, reads one report, and fixes a handful of things it flags.

This page is the mental model behind that remediation loop — 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. The operator runs these steps for you and asks before each judgement call; read on so you can follow along and steer it.

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 pull demand # 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 committed graph is computed.

Step 2 — the patterns to look for

gtmesh doctor finds most of these for you. It’s the deterministic “linting for the mesh”: it runs the checks below over your plan + registry + raw keyword pull and prints each smell with the exact file/knob to fix and a docs link, ending with a recommended next command. Run it after apply; the table here is the mental model behind what it flags. Tune its thresholds with gtmesh config set doctor.<knob> <value> (see the CLI reference).

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

Config knobs are written with gtmesh config, which preserves the file’s comments, re-validates it, and rolls back a bad edit. A knob you don’t see in gtmesh.config.yaml still has a value — the file holds your decisions and the schema supplies the rest — so use gtmesh config describe [path] to see the whole set of keys, what each controls, and its default.

What you see in the plan	What it means	What to run
Unresolved list has real queries you do want pages for	No routing rule matched them	`gtmesh config add sections_map '{"when":{"match":"what is"},"then":{"section":"glossary"}}'` — add rules until only junk is left unresolved (Tuning §3)
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	`gtmesh config set identity.anchor parent_topic`, 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	`gtmesh config add adapters.ahrefs.exclude_substrings login` (drops at pull) or the `scope:` block (parks to backlog) — Tuning §6
No hubs — every page is a spoke, so no topic has an apex	Your conversion pages weren’t marked as hubs	Add `role` rules in `reference/signals.csv`, or declare apex pages with `gtmesh page add --role hub` (Tuning §4 & §7)
Lots of thin, near-duplicate pages from one topic	A stray keyword minted a fragment	`gtmesh config set classification.min_group_members 2` (Tuning §1)
One brand splits into many pages — spelling/phrasing variants each mint their own	An entity’s variants aren’t being consolidated	`gtmesh config set classification.entity_aware true` (list the variants in the entity’s `aliases`) so they collapse into one hub (Tuning › Entity-aware)
Far too many pages overall	The long tail is too long	`gtmesh config set 'scope.include[0].min_volume' 50` — raise the floor to park low-demand keywords

You can’t break anything by turning these knobs and re-planning. A bad config edit is refused and rolled back at the command; the worst case that gets through is that 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 page promote --under /<your-hub-slug>  # a hub + its cluster
# …or:
gtmesh page 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 page validate <slug>    # schema + editorial lint
gtmesh page 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 (the aeo: block) — the quality bar for drafts. The defaults are sensible; tune the numbers later if reviews feel off (gtmesh config set aeo.overall_threshold 80).
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 pull → 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, then gtmesh doctor to lint the mesh’s health.
Remediate what doctor flags, gtmesh page 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.

Next: the operator loops one slice at a time — remediate, promote a small batch, write, seal, look, repeat. When the mesh exists you stop bootstrapping and switch to the refresh loop (change an input, reconcile).