How it works

Every entry is what a live Flow Production Tracking site answered when a script asked it one question. Nothing here comes from the documentation.

What is on it

page	answers	holds
Entity types	What is required to create one, what does it link to, how is it identified	19 types
Field types	What does this data type read, write and clear as, and what can I filter it with	24 types, each with an operator vocabulary and a value matrix
Endpoints	What does this call take, and what does it answer	69 calls, each with a recorded response and its status codes
Filters	Which relations does this type accept, and what value does each one take	Generated from the field-type cards, so it cannot drift from them
Recipes	How do I do this, and what does it return	14 tasks, each with the real response and the errors hit on the way
Findings	What does it do here, where the docs are silent or wrong	54 questions, grouped by the phase they bite in

Read it

Nothing to install. Clone it and give an agent one line.

git clone https://github.com/ksallee/sg-groundtruth

Read sg-groundtruth/corpus/INDEX.md first.
Open the door it names for the rules, and an entry only when a rule needs its evidence.

8 KB, generated: every entry by name, and which door answers the thing you already hold. A door under corpus/doors/ carries one line per entry and that entry's rules, copied whole. The entries behind them are much larger.

Fetch it

Or do not clone at all. Every page here has a markdown twin at its own URL with .md appended, and /llms.txt is the map: every entry by name, and the door to open for each way in.

Read https://sg-groundtruth.vercel.app/llms.txt first.
Open the door it names for the rules, and an entry only when a rule needs its evidence.

url	is
`/llms.txt`	25 KB. The map: every entry by name with the URL of its markdown, and the door to open for each way in
`/doors/field_types.md`	One door: a line per entry and that entry's rules, copied whole. Every door is on /doors
`/findings.md`	One section, under the grouping its page draws
`/findings/026_result_order.md`	One entry, which is `corpus/findings/026_result_order.md` byte for byte

The frontmatter is on a twin because it is what a client selects on: scope, phase, endpoints, tags, coverage. A twin is the shipped file and never the merged one, so it is the api level whatever the reading level on the page says. /sitemap.xml lists the rendered pages.

Mount it over MCP

The same corpus as 6 tools, so an agent looks up one entry instead of loading the index. Standard library only. Call filter_operators before building anything that filters.

PYTHONPATH=src python -m sg_groundtruth.mcp

PYTHONPATH is not optional: the package is not installed. Registration, for Claude Code and any other stdio client: docs/mcp.md.

Call the API with it

FPT is the client every probe here uses, so the corpus was measured through it. It holds a bearer, re-authenticates when it expires, and raises FPTError on a non-2xx with the body intact.

pip install sg-groundtruth

from sg_groundtruth.client import FPT

fpt = FPT.from_env()                  # FPT_API_SITE_URL, _SCRIPT_NAME, _API_KEY
page = fpt.get("/entity/versions")    # the parsed body: data, links

75 lines, requests and nothing else. get, post, put and delete take a path and pass every other keyword to requests, so params, json and files work as they do there. The wheel is the client and the tools, never the corpus: that is read from a clone, because every entry names the probe that produced it and re-running it is the point.

Put your own site in it

These pages cover any Flow PT site. One command measures yours: custom entities, field names, status vocabularies, projects.

cd sg-groundtruth
claude

/sg-groundtruth-setup

The command loads with the session, so start the agent inside the clone.

step	what happens
1	Asks what you want run. It measures nothing silently
2	Checks the toolchain
3	Asks for five values, and says what each is for
4	Proves them with two read-only probes
5	Writes your site's documentation to `corpus.local/`
6	Serves it on localhost, then hands you the four commands above

Writes to your site	Nothing, unless a probe is run with `--write`
Project it may write into	The sandbox you name, and no other
Where your data goes	`corpus.local/`, gitignored, never leaves your machine

Add to it

command	what it does
`/probe <question>`	Asks one question against your own site and records what came back.
`/recipe <task>`	Records a call you got working, its real response, and the errors you hit.
`/sg-groundtruth-adopt <path>`	Reads code that already calls this API. Each distinct call becomes a recipe, and each retry loop, sleep and swallowed error becomes a probe.
`/inspect-site [project]`	Measures one project and proposes a profile, with the evidence beside it.

Probes

A probe asks one question, prints what the API answered, and deletes anything it created. It never writes the corpus: an agent reads the output and writes the entry.

python probes/017_filter_operators.py

Every entry names the probe that produced it. Run it against your own site to check.

Scopes

Every file declares a scope.

scope	true of	public
`api`	Any Flow PT site: status codes, error strings, value shapes, operator vocabularies	Yes. The default, and all a public build has
`site`	One site: which custom entities are enabled, which fields exist, `valid_values`, `/preferences`	No
`project`	One project inside it: `hidden_values`, page columns, fill rates	No

valid_values is byte-identical at every scope. Only hidden_values varies by project, so "which statuses can I use" has no site-level answer (probe 009).

Badges mark the scope: blue api, orange site, green project. A public build has only api.

The overlay

/sg-groundtruth-setup writes corpus.local/. These pages read it and render its sections beside the api ones. It is gitignored, so it cannot reach a deployment.

Drop a markdown file in the matching directory. Nothing has to be registered.

corpus.local/site/findings/<nnn>_<slug>.md               one Flow PT site
corpus.local/site/findings/field_types/<type>.md
corpus.local/site/findings/entity_types/<Type>.md
corpus.local/site/recipes/<nnn>_<slug>.md
corpus.local/projects/<id>/findings/<nnn>_<slug>.md       one project inside it
corpus.local/projects/<id>/findings/field_types/<type>.md
corpus.local/projects/<id>/findings/entity_types/<Type>.md
corpus.local/projects/<id>/recipes/<nnn>_<slug>.md

Frontmatter is the shape the shipped corpus uses. The scope must match the directory, so a local measurement cannot ship as a general fact. A scope: project file also names its project. Every field: site/README.md.

MCP servers for Flow PT

These call the API. This corpus says what the API does. An agent given both has to be told which is which.

Each is MIT licensed and maintained. What is recorded was read from their source at a pinned commit, in RESEARCH-mcp.md. Nothing was installed and no agent was measured using one.

server	what it is
fpt-mcp	Python. Bundles its own REST reference. This corpus adds the operator vocabulary per data type, and the condition that ends a paged read.
ShotgunMcpGo	Go. Per-data_type operator and value tables. The matrix here was measured against a live site, and covers the color type and the read shapes for float and status_list.
shotgrid-mcp-server	Python, on PyPI, wrapping shotgun_api3. Its status resource exposes a field's valid values. The usable set is those minus hidden_values, which it does not subtract for you (field_types/status_list).