Discovery & harvest

Some inputs can’t be computed deterministically — figuring out a mesh’s shape, or which terms belong in a glossary, takes open-ended research. GoToMesh has two research mechanisms for exactly this. Both run outside the deterministic engine and hand it committed, human-reviewed files.

What it is

• The operator skill establishes the mesh shape. After gtmesh init scaffolds the repo, you open it in Claude Code and run the repo-local operator skill. It interviews you, validates real keyword demand first, then builds the mesh’s structure — the site type (kind), sections, domain axes, page types, harvest classes, and reference tables — through the deterministic CLI verbs (gtmesh config set/add, gtmesh reference + authored CSVs, gtmesh plan, gtmesh apply), with a human gate on every judgement call.
• Entity-class harvest fills the terms of a class. You run gtmesh harvest <class>; it validates the class and prints a prompt. The harvest skill brainstorms candidates per taxonomy family, ranks them against a demand corpus, validates demand via the keyword provider, scores the cut, and writes seeds/<class>.csv — then stops for your review.

Why it matters

This is one of the load-bearing invariants: discovery is import, not plan. The networked, model-driven research is firewalled off from the engine. The engine only ever consumes the lean, predictable files these mechanisms emit (config, reference tables, seed lists) — so the deterministic loop stays deterministic, and the one place judgement enters is a change you review and commit.

Each is human-gated by design. The operator seeks your approval before each config/reference change; you curate seeds/<class>.csv before cataloguing. Curation is the point, not a chore the tool skips.

How it works

A seed file carries term plus optional provenance (target_keyword, family, section, page_type, source, funnel, …) and never metrics — volume and difficulty live in the data bag (data/raw/) and refresh on cadence via gtmesh pull demand --source seeds. Each class with seeds must also be a discovery: class in gtmesh.config.yaml, or plan won’t load its term list.

Staging — explore demand without flooding the registry

Discovery is demand-first: you validate real keyword demand before committing structure. But a plain pull lands in the bag and the next plan catalogues all of it — so exploring the landscape floods the registry, and keeping only a slice used to mean pulling a batch to explore and then re-pulling just the keepers (paying the provider twice).

Demand staging closes that gap. Pull with --stage and the demand lands in the git-ignored .gtmesh/staging/ that plan ignores; then admit the terms you keep — in one pull, no re-pull:

gtmesh pull demand --topic pumps --stage            # explore: pull into staging (plan ignores it)
gtmesh stage list                                 # term, volume, + a resolves-to-entity hint
gtmesh stage admit --keyword "food grade pump" --keyword "macerator pump"   # keep exactly the keepers
gtmesh plan                                       # only the admitted slice catalogues
gtmesh stage drop --all                           # discard the rest

stage list’s resolves-to-entity hint (→ <entity> / → unresolved) shows would this fold into a hub, or strand? before you admit — the judgement call the volume number can’t make. The --keyword list is the workhorse: the real selection is judgement a threshold can’t express (“sump pump is 4,300 but consumer → drop”). Staging is local scratch — the git contract stays what’s committed = admitted decisions.

Key files & flags

Related

• Walkthrough — init, then the operator loop, end to end
• harvest — fill an entity class’s terms