Module 2 · Run Governed Queries

Goal: read the org’s context the way the product’s agent does, and execute approved query surfaces with typed parameters.

2.1 · The mount

Every sandbox is preloaded with the org’s Ontology at /sandbox/files/library, scoped to what your roles can see. Use the pre-imported helper instead of walking directories:

Prompt

refinery exec python 'import library; print(library.list_files(subdir=""))' --sandbox [my-task-name]

You’ll see: .tql models, docs, datasets. Two files are instructions, not data: ANA.md (the org’s standing rules — root + per-subdirectory, all binding) and ana-config.yaml (what auto-attaches, per connector/role). Read them before analyzing or your answers will differ from the product’s for the same question. Files certified golden win when sources disagree.

2.2 · Execute a governed surface

Prompt

refinery exec python 'import library; print(library.read_file("[path/to/query.tql]"))' --sandbox [my-task-name]
refinery connector db query [connector-id] --tql [path/to/query.tql] --param '[name]=[value]' --as result --sandbox [my-task-name]

You’ll see: read the file’s params block first — they’re typed, may be nullable, may have defaults; omit a key to take its default and never invent a name. A List<FilterInput> takes objects {"key","operator","value"} with word operators (equals, in, between…). --tql always runs the approved ontology copy — editing the mount changes nothing.

✅ Checkpoint

You read the root ANA.md and one subdirectory’s before touching its data
A governed .tql executed with a parameter you chose from its params block
You can say why editing a .tql in the mount doesn’t change what --tql runs

​2.1 · The mount

​2.2 · Execute a governed surface

​✅ Checkpoint

2.1 · The mount

2.2 · Execute a governed surface

✅ Checkpoint