Skip to Content
DocumentationFeaturesCommandsstage

gtmesh stage

Works the demand staging area — the git-ignored .gtmesh/staging/ that a pull with --stage writes to and plan ignores. It lets you separate research to figure out the config from demand that feeds the build: explore the landscape, then admit exactly the terms you keep.

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

Why it exists

Without staging, a pull lands in the committed bag (data/raw/) and the next plan catalogues all of it — so the act of looking at demand floods the registry. Worse, to keep only some terms you’d pull a batch to explore, then re-pull just the keepers to get them into the build — paying the provider twice. stage fixes both: pull once into staging, then admit --keyword "<the keepers>" promotes the subset with no second pull.

Staging is local and git-ignored (like .gtmesh/plan.json). The contract stays what’s committed = admitted decisions: exploration never enters git; the admitted bag file is the committed evidence.

Subcommands

stage list

Prints staged (not-yet-admitted) demand — term, volume, cluster — with a resolves-to-entity hint: → <entity> when the term resolves against the mesh’s entity set, → unresolved otherwise. That answers would this fold into a hub, or strand? at admit time, without a plan round-trip. The hint is a pure entity resolve — best-effort, so a malformed entity source degrades the hint but never crashes the listing (validate/doctor are where input errors are flagged loudly).

stage admit

Promotes a per-term slice from staging into the bag (data/raw/) as a new immutable file, then removes it from staging. It catalogues on the next plan. One bag file per (adapter, cluster), so admitted demand keeps the grouping classification expects.

OptionDescription
--keyword <kw>The workhorse — repeatable. Admit exactly this keyword. The real selection is judgment a threshold can’t express (“sump pump is 4,300 but consumer → drop”), so lead with this
--match <pattern>Admit staged terms matching a substring or /regex/
--min-vol <n>Admit staged terms with at least this volume
--allAdmit everything staged

Selectors combine as: explicit --keyword is always included, plus any staged term passing all provided --match/--min-vol filters. A --keyword that isn’t staged is a hard error (a named keeper can’t silently vanish); a selection that matches nothing is a loud no-op.

admit is deliberately distinct from lifecycle promote: two different “move forward”s — demand→pool here, a page→lifecycle there.

stage drop

Discards staged terms without admitting them (the “throw it back”). It takes the same four selectors as admit — one declaration, so a flag reads and behaves identically on both; --all drops everything staged.

Reads & writes

  • Reads: .gtmesh/staging/keywords/** (staged pulls); the mesh’s entities for the list hint.
  • Writes: admit writes a committed immutable file into data/raw/keywords/<adapter>/ and rewrites staging (drained files are removed); drop rewrites/removes staging. list writes nothing.
  • Commits: the admitted bag file is committed evidence; staging is git-ignored.
Last updated on
pullreference