docs: update union member resolution documentation

Refactor union resolution to explicitly try reference members before
non-reference members. This replaces the previous error-message-based
fallback with a deterministic, structural approach.

- Update `parseValueWithReferences` and `resolveNestedReferences` to
  partition members by reference presence.
- Update documentation in `README.md`, `AGENTS.md`, and
  `syntax-rework-plan.md` to reflect this behavior.

README.md

@@ -143,7 +143,7 @@ The following TypeScript types are exported:
 | Tuple | `[Type1; Type2; ...]` | `[hello; 42; true]` |
 | Array | `Type[]` | `[1; 2; 3]` |
 | Array of Tuples | `[Type1; Type2][]` | `[[a; 1]; [b; 2]]` |
-| Union | `Type1 \| Type2` | `hello` or `42` (matches first valid member) |
+| Union | `Type1 \| Type2` | `hello` or `42` (reference members tried first) |
 | String Literal | `'on' \| 'off'` or `"red"` | `on` or `off` |
 | Reference | `@tablename` or `@tablename[]` | (resolved at CSV load time) |
 | Reverse Reference | `~tablename(fk)` | (resolved at CSV load time) |
@@ -153,6 +153,7 @@ The following TypeScript types are exported:
 - Semicolons `;` are used as separators instead of commas `,`
 - Tuple and array values **must** be wrapped in brackets `[]` (e.g. `[a; b]`)
 - `[single]` is a 1-tuple, not an array — use `Type[]` for arrays
+- In a union, **reference members are tried before non-reference members** (e.g. `@users | string` resolves `1` to the user object, falling back to a plain string when the reference doesn't match)
 - Special characters can be escaped with backslash: `\;`, `\[`, `\]`, `\\`
 - Empty arrays/tuples are not allowed
 - For CSV loading with reference resolution, see [csv-loader.md](./csv-loader.md)