sites

Overview ¶

Command sites prints the change-site checklist for a Pulse change: every file + symbol a change must touch, the gate tests to rerun and the goldens to regenerate. It is a development tool only (never imported, never shipped) — run it before reading code for a story.

go run ./internal/tools/sites op MAT_PCA          # an existing operator
go run ./internal/tools/sites new-op overlay      # a NEW operator of a category
go run ./internal/tools/sites slot request matrices
go run ./internal/tools/sites categories          # list categories + operators
make sites ARGS="op OVERLAY_MARKOV"

Flags (anywhere on the line): --json (machine output), --all (also list history/roadmap files and single-operator sites), --root DIR.

Everything is derived from code, never from a hand-maintained site list, so it stays current:

• operators come from the types registries (types.All*Types, types.AllOverlayKinds, synth.AllDistributions) read by AST;
• an operator's sites are the classified occurrences of its identifier (plus every Go const aliasing its wire name, e.g. types.OverlayKindMarkov, plus its atomic-skill stem) across the tracked tree, each resolved to its enclosing Go declaration or Markdown heading;
• new-op templates are the sites shared by the existing operators of the category, with per-operator file names folded into <snake> / <kebab> placeholders;
• gates are the test functions that name the operator, iterate the category registry, or reference a category-wide table;
• slot sites are go/types-resolved references to the types.Request / types.Response field, plus its wire-name string literals and the update-demand rows that name it.

Only the inherently manual part — which contract to read — is a table (categoryTable.Manual / slotManual), and its paths are pinned by this package's tests.