diff --git a/.agents/skills/graphile-file-urls/SKILL.md b/.agents/skills/graphile-file-urls/SKILL.md
new file mode 100644
index 0000000000..a3ef2bb60b
--- /dev/null
+++ b/.agents/skills/graphile-file-urls/SKILL.md
@@ -0,0 +1,81 @@
+---
+name: graphile-file-urls
+description: Read URLs for a file-reference column (an `image` or `upload` jsonb domain column, scalar or array) from GraphQL — `
Url(width)` and `Versions` returning `FileVersion`, added by graphile-presigned-url-plugin. Use when asked to "show an image at a size", "get a thumbnail URL", "get the URL of an uploaded file on a row", "srcset", "why is photoUrl null", or when adding a new file-reference domain (`fileRefDomains`).
+compatibility: PostGraphile v5, graphile-presigned-url-plugin, graphile-storage-registry
+metadata:
+ author: constructive-io
+ version: "1.0.0"
+---
+
+# File-reference column URLs
+
+Source: `graphile/graphile-presigned-url-plugin/src/file-ref-urls.ts`
+(`createFileRefUrlsPlugin`, installed by `PresignedUrlPreset`).
+
+## What you get
+
+For every column whose type is a jsonb domain named in `FILE_REF_DOMAINS`
+(`['image', 'upload']`, `graphile/graphile-storage-registry/src/naming.ts`), or
+an array of one, the row type gains two fields:
+
+```graphql
+type Product {
+ photo: JSON
+ photoUrl(width: Int): String # image or upload column
+ photoVersions: [FileVersion!]
+ gallery: [JSON]
+ galleryUrl(width: Int): [String] # array column: one entry per element
+ galleryVersions: [[FileVersion!]]
+}
+
+type FileVersion {
+ name: String
+ key: String!
+ width: Int
+ height: Int
+ format: String
+ size: Int
+ url: String!
+}
+```
+
+- `Url` without `width`: the source file's URL.
+- `Url(width: N)`: the narrowest rendered version at least `N` wide; when
+ no version is that wide (or the document has none, as on an `upload`
+ column), the source URL.
+- `Versions`: the versions in the document, narrowest first, each with a
+ URL. Empty when there are none. Use it for `srcset`.
+- `null` when the file id is unknown, hidden from the reader by RLS, not live,
+ or its bucket is not reconciled.
+
+```graphql
+{ products { nodes { photoUrl(width: 480) photoVersions { width url } resumeUrl } } }
+```
+
+Use these on business tables. `downloadUrl` is the field on a files-table row;
+it is still there and behaves the same for bucket handling (public bucket with
+`publicUrlPrefix` → direct URL, private → presigned GET).
+
+## Rules the resolver keeps
+
+- The file row is read by the document's `id` under the reader's RLS. The
+ document's own `key`, bucket and filename are ignored.
+- A version is signed only if its key is a direct child of that row's
+ `.versions/` (`isVersionKeyOf`). Anything else in the document's
+ `versions` is dropped.
+- `.versions/` is reserved: a client-supplied upload key containing it is
+ refused with `INVALID_KEY` (`src/custom-key.ts`).
+- Lookups are batched per request: one files query per storage module for all
+ rows of a list, not one per row.
+
+## Adding a file type
+
+Pass the full list as the plugin option `fileRefDomains` (`src/types.ts`), or
+add the name to `FILE_REF_DOMAINS`. The domain must be a jsonb domain whose
+document carries the files row `id`. Do not add a per-type plugin.
+
+## Where versions come from
+
+The database writes them: constructive-db's `ProcessImageVersions` lane stores
+`versions` inside the image document. This plugin only reads the document; a
+column with no versions still resolves `Url` to the source.
diff --git a/.agents/skills/graphile-search/SKILL.md b/.agents/skills/graphile-search/SKILL.md
index 54e028c88e..9b5a737247 100644
--- a/.agents/skills/graphile-search/SKILL.md
+++ b/.agents/skills/graphile-search/SKILL.md
@@ -267,6 +267,7 @@ This avoids the problem of BM25/pgvector producing unbounded scores that can't b
| `includeChunks` field missing | No `@hasChunks` tables in schema | Add `@hasChunks` smart tag to parent table codec |
| `Unknown type "FullText"` | TsvectorCodecPlugin not loaded | Use `UnifiedSearchPreset()` which includes all codecs |
| `Unknown type "Vector"` | VectorCodecPlugin not loaded | Use `UnifiedSearchPreset()` which includes all codecs |
+| Vector search returns nothing after changing the embedding model | Rows are stamped with the old model in the `@embeddingModelOf` column | Re-embed the rows; see `references/pgvector-adapter.md` |
| Duplicate type errors | Multiple search presets | Use only `UnifiedSearchPreset()`, not individual presets |
## Related Skills
diff --git a/.agents/skills/graphile-search/references/pgvector-adapter.md b/.agents/skills/graphile-search/references/pgvector-adapter.md
index e35ab95b4d..3c04235eed 100644
--- a/.agents/skills/graphile-search/references/pgvector-adapter.md
+++ b/.agents/skills/graphile-search/references/pgvector-adapter.md
@@ -189,6 +189,36 @@ query {
}
```
+## Model-Aware Search (`@embeddingModel` / `@embeddingModelOf`)
+
+Vectors of two models are not comparable. The adapter reads two smart tags
+(`graphile/graphile-search/src/adapters/pgvector.ts`, `detectColumns`):
+
+| Tag | On | Meaning |
+|-----|----|---------|
+| `@embeddingModel ` | the vector column | the model the column's definition names |
+| `@embeddingModelOf ` | a sibling text column | records, per row, the model that produced that row's vector |
+
+constructive-db's `SearchVector` generator emits both (`_model` carries
+`@embeddingModelOf`; `@embeddingModel` only when the node names a model).
+
+- The vector filter input has a `model` field. On a column with a model
+ column, when `model` is given only rows whose stamp equals it are compared;
+ rows stamped with another model (or not stamped) are skipped until they are
+ embedded again with that model.
+- With `graphile-llm`, a search `text` is embedded once per model its columns
+ use (`@embeddingModel`, else the request's model) and `model` is filled in
+ server-side (`graphile/graphile-llm/src/embed-inputs.ts`). A column whose
+ embedding failed sits the search out; it is never searched with another
+ model's vector.
+- On write, `graphile-llm`'s `Text` mutation input embeds with the
+ column's `@embeddingModel` and, when the `@embeddingModelOf` column is in
+ the mutation input, writes the model used into it
+ (`graphile/graphile-llm/src/plugins/text-mutation-plugin.ts`).
+- Passing a raw `vector` yourself: pass `model` too, or rows of every model
+ are compared.
+- A column with neither tag behaves as before.
+
## VectorCodecPlugin
The `VectorCodecPlugin` (included in `UnifiedSearchPreset`) teaches PostGraphile about the `vector` PostgreSQL type:
diff --git a/AGENTS.md b/AGENTS.md
index 8857e1771f..f3d8956001 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -175,6 +175,7 @@ The `.agents/skills/` directory contains tooling-focused skills for this monorep
| `constructive-testing` | PostgreSQL testing frameworks — pgsql-test, drizzle-orm-test, supabase-test | Writing database tests, testing RLS policies, seeding test data |
| `constructive-cli` | Generated CLI commands — how the CLI is generated from GraphQL schemas, codegen options, multi-target CLI | Generating CLI tools, running generated CLI, understanding codegen pipeline |
| `graphile-search` | Unified PostGraphile v5 search plugin — tsvector, BM25, pg_trgm, pgvector adapters, composite searchScore | Adding search to GraphQL, configuring search adapters, querying search via SDK |
+| `graphile-file-urls` | `Url(width)` / `Versions` / `FileVersion` on `image` and `upload` columns (graphile-presigned-url-plugin) | Reading a sized image URL or an uploaded file's URL from a business-table row, adding a file-reference domain |
## Tips