Skip to content

docs(skills): file-reference column URLs and model-aware vector search - #2009

Merged
pyramation merged 2 commits into
mainfrom
docs/skills-file-ref-urls-model-search
Nov 16, 2026
Merged

pyramation merged 2 commits into
mainfrom
docs/skills-file-ref-urls-model-search

Conversation

@pyramation

@pyramation pyramation commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Summary

The hand-written skills said nothing about what #2008 shipped. Skills and the AGENTS.md skill table only; no code, no generated cli-* / hooks-* / orm-* skills touched.

New skill graphile-file-urls — how to read a URL for an image or upload column (scalar or array) on a business-table row:

  • <col>Url(width), <col>Versions, the FileVersion type, what width picks, when the result is null, how it relates to downloadUrl.
  • The rules the resolver keeps (row by id under reader RLS; only direct children of <source-key>.versions/ are signed; .versions/ refused in client upload keys; batched per request).
  • Adding a file type through fileRefDomains / FILE_REF_DOMAINS.
  • Source: graphile/graphile-presigned-url-plugin/src/file-ref-urls.ts, src/types.ts, src/custom-key.ts, graphile/graphile-storage-registry/src/naming.ts.

graphile-search/references/pgvector-adapter.md — new section "Model-Aware Search": the @embeddingModel and @embeddingModelOf tags, the model filter field, one embedding per model, a failed column sits the search out, raw vector callers should pass model.

  • Source: graphile/graphile-search/src/adapters/pgvector.ts (detectColumns, buildFilterApply), graphile/graphile-search/src/plugin.ts, graphile/graphile-llm/src/embed-inputs.ts, graphile/graphile-llm/src/plugins/text-mutation-plugin.ts.

graphile-search/SKILL.md — one pitfall row pointing at that section.

AGENTS.md — the new skill in the Tooling Skills table.

Audit, no change needed

  • No hand-written skill here made a now-wrong statement (none mention downloadUrl, versions, or a model name).
  • Generated hooks-storage / orm-storage / cli-storage describe the storage API target, not business-table columns, so <col>Url does not appear there; nothing to regenerate for this.
  • constructive-starter-kits.zip is the only .zip sibling and that skill is unchanged.

Link to Devin session: https://app.devin.ai/sessions/d7ca5693b59842008312a29e09ddacb2
Open in Devin Desktop: https://app.devin.ai/desktop/session/d7ca5693b59842008312a29e09ddacb2?variant=devin
Requested by: @pyramation


🟢 Devin Review found nothing to fix · View findings

Devin Review

@devin-ai-integration

Copy link
Copy Markdown
Contributor

I'll fix CI failures and address comments from users with write access. I'll skip comments containing "(aside)".

  • Disable automatic comment, CI, and merge conflict monitoring

@luxor-code-review

luxor-code-review Bot commented Nov 16, 2026 •

Copy link
Copy Markdown

Review complete. No blocking issues — approved ✅; 2 nitpicks below.

🧹 Nitpicks (2) — 🟢 2 low
  • 🟢 Re-embed troubleshooting pointer dead-ends (SKILL.md:270) — The troubleshooting row for 'vector search returns nothing after changing the embedding model' tells readers to re-embed the rows and points to references/pgvector-adapter.md (.agents/skills/graphile-search/SKILL.md:270).
  • 🟢 Doc overstates stamp-filter guarantee (pgvector-adapter.md:205) — The doc states that on a column with a model column "only rows whose stamp equals model are compared" without noting this holds only when model is actually supplied (.agents/skills/graphile-search/references/pgvector-adapter.md:206).

This PR adds two agent skill docs: the graphile-file-urls skill guide and a pgvector adapter reference for graphile-search, plus an AGENTS.md index row. The new Model-Aware Search section documents @embeddingModel/@embeddingModelOf stamping and its effect on vector search filtering.

Files Change
.agents/skills/graphile-search/SKILL.md Adds pgvector adapter section with model-aware search usage and a troubleshooting table.
.agents/skills/graphile-search/references/pgvector-adapter.md New reference documenting the pgvector adapter, smart tags, and model-stamp filtering semantics.
.agents/skills/graphile-file-urls/SKILL.md New skill guide for file URL GraphQL fields.
AGENTS.md Index row for the new graphile-file-urls skill.

Two low-severity documentation gaps were found: a troubleshooting pointer that dead-ends, and a stamp-filter guarantee stated without its omitted-model caveat.

Reviewed commit: 009e614

@devin-ai-integration devin-ai-integration Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no bugs or issues to report.

Devin Review

@pyramation
pyramation merged commit bb81b9a into main Nov 16, 2026
3 checks passed
@pyramation
pyramation deleted the docs/skills-file-ref-urls-model-search branch November 16, 2026 23:58
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant