Docs: `reference_query` is static — no per-instance placeholder substitution

[mitselek]

TL;DR

reference_query set on a property type definition is parsed as a static string. There is no per-instance variable substitution (no {{_parent}}, {{currentEntity.X}}, etc.).

Source

entu/webapp/app/components/my/select/reference.vue:50-52:

if (props.query) {
  filter = { ...queryStringToObject(props.query), ...filter }
}

The query string is parsed once with queryStringToObject and merged with the base filter verbatim.

Implication

Cannot use reference_query to filter the picker contextually — e.g., "show only members of this lending's grandparent organization" doesn't work, because there's no way to inject the current entity's grandparent ID into the query.

Apps that need contextual filtering must do it at the app layer (their own UI or BFF) rather than rely on reference_query. The Entu webapp's built-in picker offers only the static-filtered list.

Suggested doc note

At the reference_query documentation (currently in entity-types or properties docs): explicitly state that the value is static and no placeholder substitution is supported.

Related: polyphony case study D7 — https://github.com/entu/research/blob/main/docs/case-studies/2026-05-polyphony-on-entu.md

[mitselek]

Adding a clarification I missed in the original issue body — worth surfacing in the eventual docs note too:

The picker still applies access-rights filtering on top of reference_query. Users only see entities they have _viewer (or higher) on. The static reference_query layers ON TOP of rights, not instead of them. So the limitation is about expressiveness (you can't narrow the picker by per-instance context like "only members of THIS lending's grandparent org"), not about security (leakage prevention — the picker cannot surface entities the user shouldn't see).

When updating the docs, worth making both points explicit:

1. reference_query is a static string; no {{_parent}} / {{currentEntity.X}} substitution
2. Access-rights filtering applies on top of reference_query — the picker is rights-safe even when reference_query can't contextually narrow

This avoids readers worrying that the static-only limitation could leak entities (it doesn't — rights still filter).

Captured the same nuance in the polyphony case study Section D7:
https://github.com/entu/research/blob/main/docs/case-studies/2026-05-polyphony-on-entu.md#d7-reference_query-is-static--no-per-instance-placeholder-substitution--entuwww5