refactor: move plugin/skills to lancedb-agent-plugins repo (#4009)

Moving the skills and plugins to
https://github.com/lancedb/lancedb-agent-plugins

plugins/lancedb/.claude-plugin/plugin.json

@@ -1,21 +0,0 @@
-{
-  "name": "lancedb",
-  "description": "Write, review, debug, and document LanceDB pipelines in Python and TypeScript that work across local LanceDB OSS tables and remote LanceDB Enterprise/Cloud tables, with idiomatic query/search patterns and performance defaults for ingestion, indexing, filtering, and diagnostics.",
-  "version": "0.1.0",
-  "author": {
-    "name": "LanceDB"
-  },
-  "homepage": "https://www.lancedb.com",
-  "keywords": [
-    "lancedb",
-    "vector-search",
-    "full-text-search",
-    "hybrid-search",
-    "python",
-    "typescript",
-    "pipelines",
-    "ingestion",
-    "indexing",
-    "performance"
-  ]
-}

plugins/lancedb/.codex-plugin/plugin.json

@@ -1,33 +0,0 @@
-{
-  "name": "lancedb",
-  "version": "0.1.0",
-  "description": "Codex plugin for building LanceDB pipelines in Python and TypeScript.",
-  "author": {
-    "name": "LanceDB"
-  },
-  "keywords": [
-    "lancedb",
-    "vector-search",
-    "full-text-search",
-    "hybrid-search",
-    "python",
-    "typescript",
-    "pipelines"
-  ],
-  "skills": "./skills/",
-  "interface": {
-    "displayName": "LanceDB",
-    "shortDescription": "Build LanceDB pipelines in Python and TypeScript.",
-    "longDescription": "Write, review, debug, and document LanceDB pipelines in Python and TypeScript that work across local LanceDB OSS tables and remote LanceDB Enterprise/Cloud tables, with idiomatic query/search patterns and performance defaults for ingestion, indexing, filtering, and diagnostics.",
-    "developerName": "LanceDB",
-    "websiteURL": "https://www.lancedb.com",
-    "category": "Developer Tools",
-    "capabilities": [
-      "Developer Tools"
-    ],
-    "defaultPrompt": "Create a LanceDB table, embed sample text, and run a vector search.",
-    "composerIcon": "./assets/logo.png",
-    "logo": "./assets/logo.png",
-    "logoDark": "./assets/logo-dark.png"
-  }
-}

plugins/lancedb/skills/lancedb/SKILL.md

@@ -1,102 +0,0 @@
----
-name: lancedb
-description: Use when writing, reviewing, debugging, or documenting LanceDB pipelines in Python or TypeScript, especially code that should work across local LanceDB OSS tables and remote LanceDB Enterprise/Cloud tables. Helps avoid non-portable full-table materialization, choose idiomatic query/search patterns, apply LanceDB performance defaults for ingestion, indexing, filtering, and diagnostics, and resolve connections to the remote server for Enterprise-only operations such as jobs.
----
-
-# Building LanceDB Pipelines
-
-Use this skill to produce LanceDB pipelines that are portable between local and remote tables (for LanceDB Enterprise/Cloud) and idiomatic for the selected SDK.
-
-## LanceDB Table Modes
-
-LanceDB has two common execution modes:
-
-- **Local table**: embedded, open source, in-process LanceDB. The client opens data from a local path or object storage URI and executes queries in the application process.
-- **Remote table**: LanceDB Enterprise/Cloud table opened through a `db://...` URI. The data may be very large, commonly backed by object storage, and queried through a remote service.
-
-Do NOT assume local-only table helpers exist on remote tables. If the user asks for LanceDB Enterprise, Cloud, `db://...`, production remote access, or a remote table, focus on the remote table path: use `search()` / `query()`, keep reads bounded with `select()` and `limit()`, and avoid table-level full materialization APIs.
-
-## Workflow
-
-1. Identify the SDK: Python, TypeScript, or both.
-2. Identify the table mode: local/embedded OSS, remote Enterprise/Cloud, or portable across both. If the user says "LanceDB Enterprise", choose the remote table path. If the task involves jobs in any way (listing, inspecting, creating, or canceling jobs), it is always the remote path and requires a remote server connection — see "Connecting to the LanceDB remote server" below before doing anything else.
-3. Read the matching topic reference before writing or changing code:
-   - Column metadata authoring (both SDKs): `references/column_metadata.md`
-   - Branch operations (both SDKs): `references/branch_ops.md`
-   - Remote server connection resolution (jobs, raw REST): `references/remote_connect.md`
-   - Job operations REST API (list/describe/cancel/query_events): `references/remote_jobs.md`
-
-   There is no bundled per-language guide. For exact method names, signatures, and options, look them up in the canonical sources instead of relying on memory:
-   - Python: `docs/src/python/python.md` (the hand-maintained API reference) and the source under `python/python/lancedb/` when working inside the LanceDB repo; otherwise <https://lancedb.github.io/lancedb/python/python/>.
-   - TypeScript: the generated typedoc under `docs/src/js/` and the source under `nodejs/lancedb/` when working inside the LanceDB repo; otherwise <https://lancedb.github.io/lancedb/js/globals/>.
-4. Apply the SDK invariants in "Per-SDK Invariants" below. Read `column_metadata.md` when the task is documenting, tagging, classifying, or grouping table columns (field descriptions, `lancedb:tag:*` tags, logical column families). Read `branch_ops.md` when the task involves branch lifecycle (list/create/delete), writing to a non-main branch, or verifying a change stayed off main. Read `remote_connect.md` when the task involves jobs or direct REST access to an Enterprise deployment, and `remote_jobs.md` for the job REST methods themselves (list, describe, cancel, query_events).
-5. For Python schemas, favor Pydantic models and validate records before writing. Use PyArrow schemas when Arrow-native, streaming, or highly dynamic data makes them materially better suited.
-6. Prefer `search()` or `query()` builders with explicit `select()` and `limit()` for reads.
-7. Avoid table-level full materialization in remote or portable code. This is the main local-vs-remote read pitfall.
-8. After a successful embedded OSS ingestion, call `table.optimize()`. Do not call it for Enterprise/Cloud; remote maintenance is automatic.
-9. For remote Enterprise/Cloud writes, never drop-then-reuse or `mode="overwrite"` the same table name — see "Enterprise: never drop-then-reuse the same table name" below. This is the main local-vs-remote write pitfall.
-10. If reviewing an existing file or repo, run `scripts/check_materialization.py` on the relevant paths and inspect each finding before editing.
-11. Cross-check unfamiliar or non-trivial API claims against the source tree instead of relying on memory.
-
-## Core Portability Rule
-
-Do not write code that assumes a local table API will exist on a remote table. Remote tables can be very large, so whole-table materialization helpers are intentionally unavailable or unsafe.
-
-This does **not** mean result conversion is forbidden. Bounded query/search result collection is normal:
-
-- Python: `table.search(...).select([...]).limit(10).to_pandas()`
-- TypeScript: `await table.search(...).select([...]).limit(10).toArray()`
-
-The unsafe pattern is table-level or unbounded collection, plus local-only dataset escape hatches in remote code:
-
-- Python: `table.to_pandas()`, `table.to_arrow()`, `table.to_polars()`; `table.to_lance()` is local/OSS-only dataset access, not materialization
-- TypeScript: `await table.toArrow()`, `await table.query().toArray()` without `limit()`
-
-## Per-SDK Invariants
-
-Python:
-
-- Result collectors: default to `.to_list()` (plain dicts, no extra dependency) or `.to_arrow()` (PyArrow ships with LanceDB). Use `.to_pandas()` / `.to_polars()` only when the project already declares that dependency — do not assume pandas or polars is installed.
-- Plain scans differ by client: the sync client has no `.query()` method — use `table.search()` with no argument; the async client uses `await async_table.query()`.
-
-TypeScript:
-
-- Collect bounded results with `.toArray()` (objects) or `.toArrow()` (Arrow) after `select()` and `limit()`.
-- For large reads, stream batches instead of collecting: `for await (const batch of table.query().where(...).select(...).limit(...)) { ... }`.
-
-Both SDKs:
-
-- Ingest in bulk or in batches of thousands of rows; never write per-row in a loop — each write creates a version and fragment, slowing ingestion and later queries.
-- Build a vector index once brute-force search is too slow (rule of thumb: beyond roughly 100K vectors locally), and scalar indexes for filtered columns and merge/upsert keys. Use index defaults unless the task states recall/latency requirements.
-
-## Enterprise: never drop-then-reuse the same table name
-
-LanceDB Enterprise/Cloud splits a **control plane** (DDL: create/drop/rename) from a **data plane** (query nodes that serve reads). Query nodes cache the resolved dataset for a table name for up to `table_cache_ttl` — **default 300 seconds (5 minutes)**. After you drop or overwrite a table, the control plane updates immediately but the data plane keeps serving the *old* dataset until that cache entry expires. During the window the two planes disagree.
-
-The failure this causes: you `drop_table("t")` then immediately `create_table("t", ...)` (or `create_table("t", ..., mode="overwrite")`). The DDL returns success, but every query against `t` returns **`500 Internal Server Error`** (the query node resolves the stale/deleted dataset), and a fresh `describe` may still show the *old* schema/version. It looks like your write silently failed; it didn't — the name is cached.
-
-**`mode="overwrite"` has the same problem** — it is a drop+create of the same name under the hood.
-
-Rules for portable Enterprise ingestion:
-
-1. **Never reuse a table name you just dropped/overwrote within the cache TTL.** Do not use `mode="overwrite"` to replace an existing Enterprise table in place.
-2. To (re)load data, **write to a fresh table name** (e.g. `<table>_v2`, or a run-stamped suffix). A brand-new name has no cached data-plane entry, so writes and reads work immediately.
-3. Before creating, `list_tables()` and **fail loudly if the name already exists** rather than overwriting — prompt for a new name.
-4. To land on a specific final name that is currently occupied by an old table: drop the old table, **wait out the TTL (~5 min), then `rename_table(fresh_name, final_name)`**. Renaming onto a name whose old dataset is still cached hits the same race, so the wait is mandatory. `rename_table` is a supported control-plane op.
-5. When you hand a table name back to a human, tell them which step still needs the propagation wait (usually: "the old `t` was dropped; run the rename in ~5 minutes").
-
-This is Enterprise/Cloud-specific. Local/OSS tables have no separate data plane, so `mode="overwrite"` and immediate same-name reuse are fine there.
-
-## Connecting to the LanceDB remote server
-
-LanceDB Enterprise/Cloud deployments are served by a server implementing the lance-namespace OpenAPI spec (<https://github.com/lance-format/lance-namespace/blob/main/docs/src/spec.yaml>). Every remote (`db://...`) connection talks to such a server, and some operations exist only there. In particular, **all operations around jobs (listing, inspecting, creating, or canceling jobs) run server-side** — there is no local/OSS equivalent. Before any job work, or any direct REST call to an Enterprise deployment, read `references/remote_connect.md` to resolve the base URL, credentials, and database header and to validate the connection. Then use the four job REST methods documented in `references/remote_jobs.md` (list, describe, cancel, query_events).
-
-## Script
-
-Run the scanner when reviewing or modifying an existing codebase:
-
-```bash
-python skills/lancedb/scripts/check_materialization.py path/to/file_or_dir
-```
-
-The script reports likely unsafe full-table materialization in Python and TypeScript. Treat results as review prompts, not automatic proof of a bug.

plugins/lancedb/skills/lancedb/agents/openai.yaml

@@ -1,6 +0,0 @@
-interface:
-  display_name: "LanceDB"
-  short_description: "Build LanceDB pipelines in Python and TypeScript"
-  default_prompt: "Use $lancedb to create a table, embed sample text, and run a vector search."
-  icon_small: "./assets/icon.png"
-  icon_large: "./assets/icon.png"

plugins/lancedb/skills/lancedb/references/branch_ops.md

@@ -1,16 +0,0 @@
-# Branch Operations
-
-Branches are isolated, writable lines of history forked from `main` by default (or from another branch/version via `create`'s `from_ref`/`from_version`). There is no global "switch branch" state: `branches.create(...)` / `branches.checkout(...)` return a **table handle scoped to that branch**, and every read/write on that handle lands on the branch while the original main handle is unaffected. Unpinned handles track the branch's latest version and are writable; `checkout(name, version=...)` pins the handle to that version and is read-only.
-
-Don't work from memory — read the public docs for the current API:
-
-- **Branching guide (concepts + Python/TypeScript examples):** <https://docs.lancedb.com/tables/branching> — covers creating, writing to, reopening, and deleting branches; applying branch-tested changes back to main; diff/merge (Enterprise only); and building indexes on a branch.
-- **How branches relate to versions and tags:** <https://docs.lancedb.com/tables/versioning>
-- **Python API reference** (`Table.branches`, `Table.current_branch`, `Branches`/`AsyncBranches` with `list`/`create`/`checkout`/`delete`/`diff`/`merge`): <https://lancedb.github.io/lancedb/python/python/#lancedb.table.Branches>
-- **TypeScript API reference** (`Branches` class, same methods; `table.branches()` is async, `table.currentBranch()` returns `null` for main): <https://lancedb.github.io/lancedb/js/classes/Branches/>
-
-Notes the docs may not state prominently:
-
-- Branch lifecycle works on local/OSS and remote Cloud/Enterprise tables; **merging into main is Enterprise-only** (others raise `NotSupported`). A rejected merge is not an exception — inspect the returned `status` and `diff.mergeBlockers`.
-- To verify isolation after a branch write, read through both handles: the branch handle sees the change, the main handle must not.
-

plugins/lancedb/skills/lancedb/references/column_metadata.md

@@ -1,183 +0,0 @@
-# Column Metadata Authoring
-
-Write column-level descriptions, tags, and logical groupings onto a LanceDB table's schema. Use this when the user wants to document, annotate, tag, or classify what their table columns ARE (embeddings vs labels vs eval metrics, model provenance, version families, etc.).
-
-Works on local/OSS and remote Enterprise/Cloud tables alike — read the schema through the table handle, write through `update_field_metadata` (Python) / `updateFieldMetadata` (TypeScript).
-
-## Metadata key conventions
-
-All metadata uses namespaced keys:
-
-| Key | Purpose | Example value |
-|-----|---------|---------------|
-| `lancedb:description` | Human-readable explanation of what the column contains | `"CLIP ViT-L/14 image embedding, L2-normalized (768-dim)"` |
-| `lancedb:tag:<name>` | Flexible key-value tag; the suffix names the tag category | `lancedb:tag:field_type: "embedding"`, `lancedb:tag:model: "clip"`, `lancedb:tag:project_id: "foo"` |
-| `lancedb:logical-column` | Logical group/family this column belongs to | `"clip_features"` |
-
-Tags are open-ended — use whatever key suffix and value make sense given the user's intent. The tag suffix should describe *what is being classified* (e.g., `field_type`, `model`, `project_id`) and the value describes *how*. Multiple tags on the same column are fine — each is a separate key. All values are strings.
-
-## Step 1: Read the schema and existing metadata
-
-Read existing metadata before writing, to avoid redundant updates.
-
-Python — `table.schema` (sync property; async: `await table.schema()`) returns a `pyarrow.Schema`. **Arrow field metadata is bytes-keyed in Python**:
-
-```python
-schema = table.schema
-for field in schema:
-    meta = field.metadata or {}  # dict[bytes, bytes], e.g. {b"lancedb:description": b"..."}
-    print(field.name, field.type, field.nullable, meta)
-```
-
-TypeScript — `await table.schema()` returns an Arrow `Schema`; field metadata is a `Map<string, string>`:
-
-```typescript
-const schema = await table.schema();
-for (const field of schema.fields) {
-  console.log(field.name, field.type, field.nullable, field.metadata); // Map
-  // field.metadata.get("lancedb:description")
-}
-```
-
-For struct/nested fields, recurse into the field's children and address them as dot-paths (e.g., `parent.child`).
-
-If the user hasn't specified which columns to update, work with all columns.
-
-## Step 2: Generate metadata
-
-Decide what to generate based on the user's request.
-
-### Descriptions (`lancedb:description`)
-
-Base descriptions on:
-- The column name and Arrow type (e.g., `FixedSizeList` of floats → likely an embedding)
-- User-supplied context (upstream pipeline, sample values, domain knowledge)
-- Name patterns: `_embedding`/`_vec`/`_embed` → vector; `_label`/`_class` → label; `_score`/`_eval`/`_metric` → evaluation metric
-
-Be specific and concise. Good: `"Sentence-BERT embedding of the query text (768-dim)."` Not: `"An embedding column."`
-
-### Tags (`lancedb:tag:<name>`)
-
-Choose tag key names that match what the user asked to annotate. Common patterns:
-
-- Semantic field type → `lancedb:tag:field_type: "embedding"` / `"text"` / `"image"` / `"label"` / `"eval"` / `"id"` / `"metadata"`
-- Model or source → `lancedb:tag:model: "clip"` / `"bert"` / `"vit"`
-- Project affiliation → `lancedb:tag:project_id: "<name>"`
-- Version → `lancedb:tag:version: "v3"` (and `lancedb:tag:latest: "true"` for the newest)
-
-Use Arrow type as a hint: `FixedSizeList` + float → embedding; `Utf8`/`LargeUtf8` → text; `Binary` → image or blob.
-
-### Logical groupings (`lancedb:logical-column`)
-
-Look for naming patterns across columns:
-- `clip_v1`, `clip_v2`, `clip_v3` → logical column `"clip"`, latest is `v3`
-- `text_embed_20240101`, `text_embed_20240601` → logical column `"text_embed"`, latest is the most recent date suffix
-
-Write `lancedb:logical-column` on all members of a group. Mark the newest with `lancedb:tag:latest: "true"` (in addition to its version tag).
-
-## Step 3: Write the metadata
-
-Each update names a field by dot-path and carries a metadata map. Semantics (identical in both SDKs):
-
-- **Merge by default** (`replace` omitted/false) — preserves existing metadata the user didn't ask to change
-- `replace: true` swaps the field's entire metadata map — only if the user explicitly asks to overwrite
-- A value of `None`/`null` deletes that specific key
-- Batch all field updates into a single call when possible
-- Returns the new table version
-
-Python (sync and async take one dict per field, as varargs):
-
-```python
-res = table.update_field_metadata(
-    {
-        "path": "clip_v3",
-        "metadata": {
-            "lancedb:description": "CLIP ViT-L/14 image embedding, L2-normalized (1024-dim).",
-            "lancedb:tag:field_type": "embedding",
-            "lancedb:tag:model": "clip",
-            "lancedb:tag:version": "v3",
-            "lancedb:tag:latest": "true",
-            "lancedb:logical-column": "clip",
-        },
-    },
-    {
-        "path": "clip_v2",
-        "metadata": {
-            "lancedb:description": "CLIP ViT-B/32 image embedding (768-dim), superseded by v3.",
-            "lancedb:tag:field_type": "embedding",
-            "lancedb:tag:model": "clip",
-            "lancedb:tag:version": "v2",
-            "lancedb:logical-column": "clip",
-        },
-    },
-)
-print(res.version)  # new table version
-
-# merge semantics: add a key, delete one via None, keep the rest
-table.update_field_metadata(
-    {"path": "clip_v2", "metadata": {"lancedb:tag:archived": "true", "lancedb:tag:latest": None}}
-)
-```
-
-(`replace_field_metadata` is deprecated — use `update_field_metadata`.)
-
-TypeScript (takes an array of `FieldMetadataUpdate`):
-
-```typescript
-const res = await table.updateFieldMetadata([
-  {
-    path: "clip_v3",
-    metadata: {
-      "lancedb:description": "CLIP ViT-L/14 image embedding, L2-normalized (1024-dim).",
-      "lancedb:tag:field_type": "embedding",
-      "lancedb:tag:model": "clip",
-      "lancedb:tag:version": "v3",
-      "lancedb:tag:latest": "true",
-      "lancedb:logical-column": "clip",
-    },
-  },
-  {
-    path: "clip_v2",
-    metadata: {
-      "lancedb:description": "CLIP ViT-B/32 image embedding (768-dim), superseded by v3.",
-      "lancedb:tag:field_type": "embedding",
-      "lancedb:tag:model": "clip",
-      "lancedb:tag:version": "v2",
-      "lancedb:logical-column": "clip",
-    },
-  },
-]);
-console.log(res.version); // new table version
-
-// merge semantics: add a key, delete one via null, keep the rest
-await table.updateFieldMetadata([
-  { path: "clip_v2", metadata: { "lancedb:tag:archived": "true", "lancedb:tag:latest": null } },
-]);
-```
-
-## Step 4: Confirm
-
-Report back:
-- Which columns were updated and what was written
-- The new table version number (from the result)
-- Any columns skipped (e.g., already had up-to-date metadata)
-
-## Quick examples
-
-**"Write descriptions for all columns in the `product_embeddings` table"**
-1. Read `table.schema` → all fields + existing metadata
-2. Generate a `lancedb:description` for each column based on name + type
-3. One `update_field_metadata` call with all descriptions
-4. Report
-
-**"Tag the columns in `model_outputs` with their field type and model"**
-1. Read the schema
-2. For each field, classify by name + Arrow type → set `lancedb:tag:field_type` and `lancedb:tag:model` where applicable
-3. Write in one batched call
-4. Report
-
-**"Group the feature columns in `training_features` into logical families and mark the latest version"**
-1. Read the schema
-2. Find version patterns → assign `lancedb:logical-column` and `lancedb:tag:version`; mark newest with `lancedb:tag:latest: "true"`
-3. Write in one batched call
-4. Show the grouping

plugins/lancedb/skills/lancedb/references/remote_connect.md

@@ -1,45 +0,0 @@
-# Connecting to a LanceDB remote server
-
-LanceDB Enterprise/Cloud deployments are served by a server implementing the
-lance-namespace OpenAPI spec
-(<https://github.com/lance-format/lance-namespace/blob/main/docs/src/spec.yaml>).
-Every remote (`db://...`) connection talks to such a server, and some operations
-exist only there. In particular, all operations around jobs (listing, inspecting,
-creating, or canceling jobs) run server-side — there is no local/OSS equivalent, so
-resolve a server connection before attempting any job work. The job REST methods
-themselves are documented in `references/remote_jobs.md`.
-
-Every request needs two things:
-
-1. **Base URL** — the server endpoint
-2. **Credentials** — an API key (`x-api-key` header over REST), and usually a database name (`x-lancedb-database` header)
-
-## Resolution steps
-
-1. If the user already gave a URL and API key (or said which environment they're working against), use that.
-2. Otherwise, look for credentials already available in the environment:
-   - Env vars like `LANCEDB_URI` / `LANCEDB_HOST` / `LANCEDB_API_KEY`
-   - A server endpoint already running or port-forwarded locally (the REST default port is 2333, i.e. `http://localhost:2333`)
-3. If you didn't find both pieces, ask the user directly: **"What's your LanceDB endpoint's URL, and what's your API key?"** Also ask which database to use if it isn't obvious. Don't guess or probe further — the user knows their deployment.
-
-## Validating the connection
-
-Make a cheap authenticated request and check the status before starting real work:
-
-```bash
-curl -s -w "\n%{http_code}" "{base_url}/v1/table/?limit=1" \
-  -H "x-api-key: <key>" \
-  -H "x-lancedb-database: <database>"
-```
-
-- `200` — connection, key, and database header all good
-- `401` — API key missing or wrong
-- `400` mentioning a database header — this deployment expects `x-lancedb-database`
-
-## Non-REST equivalents
-
-The same credentials work through the SDKs and CLI:
-
-- Python SDK: `lancedb.connect("db://<database>", api_key="<key>", host_override="<base_url>")`
-- TypeScript SDK: `await lancedb.connect("db://<database>", { apiKey: "<key>", hostOverride: "<base_url>" })`
-- `lancedb` CLI: a `[profiles.<name>]` entry in `~/.lancedb/config.toml` with `http_server_url`, `api_key`, `database`

plugins/lancedb/skills/lancedb/references/remote_jobs.md

@@ -1,151 +0,0 @@
-# Job operations over the LanceDB remote server REST API
-
-Jobs are server-side background operations on LanceDB Enterprise/Cloud — index builds,
-column backfills, materialized view refreshes, and similar async work. Endpoints that
-trigger async work (e.g. the column backfill or materialized view refresh endpoints)
-return a `job_id`; these four methods are how you track and manage those jobs.
-
-Resolve the connection first — see `references/remote_connect.md`. All four methods
-are **POST** requests under `{base_url}/v1/jobs/` with JSON bodies, and take the usual
-`x-api-key` / `x-lancedb-database` headers. If every job call returns `501`, job APIs
-are disabled on that deployment (the server has no job registry configured) — report
-that rather than retrying.
-
-## 1. List jobs — `POST /v1/jobs/list`
-
-The body is optional; an empty body lists everything. All fields are filters:
-
-```json
-{
-  "limit": 100,
-  "table_name": "my_table",
-  "job_type": "...",
-  "job_subtype": "...",
-  "state": "...",
-  "page_token": "..."
-}
-```
-
-```bash
-curl -s -X POST "{base_url}/v1/jobs/list" \
-  -H "x-api-key: <key>" -H "x-lancedb-database: <database>" \
-  -H "content-type: application/json" \
-  -d '{"table_name": "my_table"}'
-```
-
-Response:
-
-```json
-{
-  "jobs": [
-    {
-      "job_id": "...",
-      "table": "my_table",
-      "job_type": "...",
-      "job_subtype": "...",
-      "state": "done",
-      "created_at_millis": 1720000000000
-    }
-  ],
-  "page_token": "..."
-}
-```
-
-A `page_token` in the response means there are more results — pass it back in the next
-request to continue. Note list rows use a lowercase `state` string, while describe uses
-an uppercase `job_state`.
-
-## 2. Describe a job — `POST /v1/jobs/describe`
-
-Body: `{"job_id": "<id>"}`. Returns full detail for one job:
-
-```json
-{
-  "job_id": "...",
-  "job_type": "...",
-  "job_subtype": "...",
-  "job_state": "IN_PROGRESS",
-  "creation_ms": 1720000000000,
-  "spec": {},
-  "status": {}
-}
-```
-
-`job_state` is one of `IN_PROGRESS`, `CANCELLED`, `FAILED`, `DONE`. `spec` and `status`
-are job-type-specific JSON objects (the job's input specification and its current
-progress/status). Returns `404` for an unknown job id.
-
-## 3. Cancel a job — `POST /v1/jobs/cancel`
-
-Body: `{"job_id": "<id>"}`; response echoes `{"job_id": "<id>"}`. Cancellation is a
-service-level operation requiring the same administrative authorization as the
-`/admin` routes — a database-scoped API key that can list and describe jobs may still
-get a permission error here. Other errors: `404` unknown job, `409` state conflict
-(e.g. already in a terminal state), `429` too much write contention (safe to retry).
-
-## 4. Query job event history — `POST /v1/jobs/query_events`
-
-Returns the event history (state transitions, progress updates) for one or more jobs.
-Body: `{"job_id": "<id>"}` for one job, or `{"job_ids": ["<id>", ...]}` for a batch.
-Optional fields: `limit` (max event rows), `limit_per_job` (per job in a batch query),
-and `filter` — a SQL-like expression over the columns `state`, `updated_by`,
-`owner_component`, and `claim_entity`. (`full_text_search` is reserved and currently
-rejected as not implemented.)
-
-The response is **not JSON** — it is an Arrow IPC stream
-(`content-type: application/vnd.apache.arrow.stream`). Decode it, e.g. in Python:
-
-```python
-import pyarrow.ipc
-import requests
-
-resp = requests.post(
-    f"{base_url}/v1/jobs/query_events",
-    headers={"x-api-key": key, "x-lancedb-database": database},
-    json={"job_id": job_id},
-)
-resp.raise_for_status()
-events = pyarrow.ipc.open_stream(resp.content).read_all()
-```
-
-## Feature engineering (Geneva) jobs
-
-Feature engineering jobs — UDF column backfills and materialized view refreshes run
-through Geneva — are tracked **separately** from the `/v1/jobs` registry above. Their
-records live in a `geneva_jobs` table inside the database itself (in the `__system`
-namespace), and you access them through a Python `geneva` connection rather than the
-REST endpoints above:
-
-```python
-import geneva
-from geneva.jobs import JobStateManager
-
-# Same credentials as lancedb.connect / the REST API
-conn = geneva.connect("db://<database>", api_key="<key>", host_override="<base_url>")
-jsm = JobStateManager(conn)
-
-# List jobs. NOTE: status defaults to "RUNNING"; pass status=None for all jobs.
-# Statuses: PENDING | RUNNING | DONE | FAILED | CANCELLED
-jobs = jsm.list_jobs(table_name="my_table", status=None)
-
-# Fetch one job by id (returns a list of JobRecord)
-records = jsm.get("<job_id>")
-```
-
-Each `JobRecord` has `table_name`, `column_name`, `job_id`, `job_type`, `status`,
-`launched_at`, `completed_at`, `config`, `launched_by`, `manifest_id`, `cluster_name`,
-`metrics` (progress counters), `events` (human-readable history), and `updated_at`.
-For filters `list_jobs` doesn't support (e.g. time ranges), query the underlying table
-directly: `jsm.get_table(True).search().where("launched_at >= TIMESTAMP '...'")` —
-pass `True` to check out the latest version, since other processes update job state.
-
-Stale-status caveat: nothing reaps dead Geneva jobs, so a job can sit in
-`RUNNING`/`PENDING` forever if its worker died. Treat a job as effectively `FAILED`
-when it has been running longer than ~36 hours, or its `updated_at` is more than ~2
-hours old (this matches the heuristic the Geneva console UI applies on read).
-
-## Workflow tips
-
-- To wait for async work (a backfill, an index build), poll `describe` until
-  `job_state` leaves `IN_PROGRESS`; on `FAILED`, pull `status` and `query_events` for
-  the failure detail.

plugins/lancedb/skills/lancedb/scripts/check_materialization.py

@@ -1,137 +0,0 @@
-#!/usr/bin/env python3
-"""Scan Python and TypeScript for likely unsafe LanceDB materialization."""
-
-from __future__ import annotations
-
-import argparse
-import re
-import sys
-from dataclasses import dataclass
-from pathlib import Path
-
-
-PY_FULL_TABLE = re.compile(r"\b\w+\.(to_pandas|to_arrow|to_polars)\s*\(")
-TS_TABLE_TO_ARROW = re.compile(r"\b\w+\.toArrow\s*\(")
-TS_QUERY_COLLECTOR = re.compile(r"\.query\s*\(\s*\)[\s\S]*?\.to(Array|Arrow)\s*\(")
-
-
-@dataclass
-class Finding:
-    path: Path
-    line: int
-    message: str
-    text: str
-
-
-def iter_files(paths: list[Path]) -> list[Path]:
-    files: list[Path] = []
-    for path in paths:
-        if path.is_dir():
-            files.extend(
-                p
-                for p in path.rglob("*")
-                if p.suffix in {".py", ".ts", ".tsx"} and "node_modules" not in p.parts
-            )
-        elif path.suffix in {".py", ".ts", ".tsx"}:
-            files.append(path)
-    return sorted(set(files))
-
-
-def line_number(text: str, offset: int) -> int:
-    return text.count("\n", 0, offset) + 1
-
-
-def scan_python(path: Path, text: str) -> list[Finding]:
-    findings: list[Finding] = []
-    for match in PY_FULL_TABLE.finditer(text):
-        line_start = text.rfind("\n", 0, match.start()) + 1
-        line_end = text.find("\n", match.start())
-        if line_end == -1:
-            line_end = len(text)
-        line = text[line_start:line_end].strip()
-        if ".search(" in line or ".query(" in line:
-            continue
-        findings.append(
-            Finding(
-                path,
-                line_number(text, match.start()),
-                f"Review Python `{match.group(1)}()` call; table-level materialization is not portable to remote tables.",
-                line,
-            )
-        )
-    return findings
-
-
-def statement_around(text: str, start: int, end: int) -> str:
-    before = max(text.rfind(";", 0, start), text.rfind("\n\n", 0, start))
-    after_candidates = [
-        pos for pos in (text.find(";", end), text.find("\n\n", end)) if pos != -1
-    ]
-    after = min(after_candidates) if after_candidates else len(text)
-    return text[before + 1 : after].strip()
-
-
-def scan_typescript(path: Path, text: str) -> list[Finding]:
-    findings: list[Finding] = []
-    for match in TS_TABLE_TO_ARROW.finditer(text):
-        stmt = statement_around(text, match.start(), match.end())
-        if ".query(" in stmt or ".search(" in stmt:
-            continue
-        findings.append(
-            Finding(
-                path,
-                line_number(text, match.start()),
-                "Review TypeScript `table.toArrow()`-style call; table-level materialization is not portable for large/remote tables.",
-                stmt.splitlines()[0].strip(),
-            )
-        )
-
-    for match in TS_QUERY_COLLECTOR.finditer(text):
-        stmt = statement_around(text, match.start(), match.end())
-        if ".limit(" in stmt:
-            continue
-        findings.append(
-            Finding(
-                path,
-                line_number(text, match.start()),
-                "Review unbounded TypeScript query collection; add `limit()` or stream batches.",
-                stmt.splitlines()[0].strip(),
-            )
-        )
-    return findings
-
-
-def scan_file(path: Path) -> list[Finding]:
-    text = path.read_text(encoding="utf-8", errors="replace")
-    if path.suffix == ".py":
-        return scan_python(path, text)
-    if path.suffix in {".ts", ".tsx"}:
-        return scan_typescript(path, text)
-    return []
-
-
-def main() -> int:
-    parser = argparse.ArgumentParser(description=__doc__)
-    parser.add_argument("paths", nargs="+", type=Path)
-    parser.add_argument(
-        "--no-fail", action="store_true", help="Always exit 0 after reporting findings."
-    )
-    args = parser.parse_args()
-
-    findings: list[Finding] = []
-    for path in iter_files(args.paths):
-        findings.extend(scan_file(path))
-
-    for finding in findings:
-        print(f"{finding.path}:{finding.line}: {finding.message}")
-        print(f"  {finding.text}")
-
-    if findings:
-        print(
-            f"\n{len(findings)} finding(s). Review manually; bounded query result conversion may be OK."
-        )
-    return 0 if args.no_fail or not findings else 1
-
-
-if __name__ == "__main__":
-    sys.exit(main())