From 149cf1052ac561b5b879bd5417cb2b1a8f9d2f02 Mon Sep 17 00:00:00 2001
From: Brendan Clement <brendan.clement@lancedb.com>
Date: Wed, 28 Oct 2026 08:16:42 -0700
Subject: [PATCH] fix(ci): bundle Vale rules to avoid private release downloads
 (#4707)

The prose check fails because it downloads its Vale rules from the
now-private docs repository.

Keep the five unchanged rules from `vale-lancedb-v0.1.0` in this
repository and disable `vale sync` in CI. This also works for
contributors without access to the docs repository. The update
instructions record the release and archive checksum.
---
 .github/vale/README.md                        | 17 ++++++++
 .github/vale/styles/LanceDB/Dashes.yml        | 40 +++++++++++++++++++
 .github/vale/styles/LanceDB/PlainLanguage.yml | 32 +++++++++++++++
 .github/vale/styles/LanceDB/ProductNames.yml  | 34 ++++++++++++++++
 .github/vale/styles/LanceDB/VagueHeadings.yml | 19 +++++++++
 .github/vale/styles/LanceDB/VaguePhrases.yml  | 31 ++++++++++++++
 .github/workflows/docs-style.yml              |  8 ++--
 .vale.ini                                     | 11 ++---
 CONTRIBUTING.md                               |  9 ++---
 9 files changed, 187 insertions(+), 14 deletions(-)
 create mode 100644 .github/vale/README.md
 create mode 100644 .github/vale/styles/LanceDB/Dashes.yml
 create mode 100644 .github/vale/styles/LanceDB/PlainLanguage.yml
 create mode 100644 .github/vale/styles/LanceDB/ProductNames.yml
 create mode 100644 .github/vale/styles/LanceDB/VagueHeadings.yml
 create mode 100644 .github/vale/styles/LanceDB/VaguePhrases.yml

diff --git a/.github/vale/README.md b/.github/vale/README.md
new file mode 100644
index 000000000..ad0573fdb
--- /dev/null
+++ b/.github/vale/README.md
@@ -0,0 +1,17 @@
+# LanceDB prose rules
+
+These five rule files are copied unchanged from the `LanceDB.zip` asset of
+`lancedb/docs` release `vale-lancedb-v0.1.0`. The archive SHA-256 is
+`0730a43e919774121068811d5687c61dfc7a0421cff78e1393f5e565b622cb0f`.
+
+Keeping the rules here lets contributors and CI run Vale without access to the
+source repository. The root `.vale.ini` preserves the release's MDX settings
+and built-in repeated-word check. No `vale sync` is needed.
+
+The rules check product names, dashes, plain language, vague headings and vague
+phrases. Findings are suggestions and do not fail the CI check.
+
+To update, a maintainer downloads the next published package, verifies its
+checksum and replaces `styles/LanceDB` with the release's files. Check the
+package's `.vale.ini` for configuration changes, and update the version and
+checksum here in the same PR.
diff --git a/.github/vale/styles/LanceDB/Dashes.yml b/.github/vale/styles/LanceDB/Dashes.yml
new file mode 100644
index 000000000..7bb10c96f
--- /dev/null
+++ b/.github/vale/styles/LanceDB/Dashes.yml
@@ -0,0 +1,40 @@
+extends: existence
+message: "Avoid '%s' in prose. Use a comma, a colon, parentheses or two sentences."
+link: https://github.com/lancedb/docs/blob/main/STYLE.md#punctuation
+level: warning
+nonword: true
+# An em dash in prose, and a double hyphen or en dash used as one, with a
+# space on each side. A table cell holding only an em dash, meaning "none",
+# ranges such as 1–3 and flags such as --force are left alone, and code is
+# never prose.
+raw:
+  - '(?<!^\s*)—|—(?!\s*$)|(?<=\s)(?:--|–)(?=\s|$)'
+tests:
+  - name: flags an em dash
+    input: Indexes are optional—queries work without them.
+    want: |
+      1:21:LanceDB.Dashes:Avoid '—' in prose. Use a comma, a colon, parentheses or two sentences.
+  - name: flags a double hyphen used as a dash
+    input: It has one page per statement, syntax first -- and every SDK operation has a SQL form.
+    want: |
+      1:45:LanceDB.Dashes:Avoid '--' in prose. Use a comma, a colon, parentheses or two sentences.
+  - name: flags a spaced en dash
+    input: Compaction is cheap – it rewrites only small fragments.
+    want: |
+      1:21:LanceDB.Dashes:Avoid '–' in prose. Use a comma, a colon, parentheses or two sentences.
+  - name: leaves an empty table cell alone
+    input: |
+      | Provider | Text | Images |
+      | --- | --- | --- |
+      | OpenAI | ✓ | — |
+      | Gemini | ✓ | per request — batched |
+    want: |
+      4:28:LanceDB.Dashes:Avoid '—' in prose. Use a comma, a colon, parentheses or two sentences.
+  - name: leaves ranges, flags and code alone
+    input: |
+      Use 1–3 replicas and pass --force to overwrite. Run `lancedb --version`.
+
+      ```bash
+      uv run pytest -- -k search
+      ```
+    want: ''
diff --git a/.github/vale/styles/LanceDB/PlainLanguage.yml b/.github/vale/styles/LanceDB/PlainLanguage.yml
new file mode 100644
index 000000000..563e834e2
--- /dev/null
+++ b/.github/vale/styles/LanceDB/PlainLanguage.yml
@@ -0,0 +1,32 @@
+extends: substitution
+message: "Consider '%s' instead of '%s'."
+link: https://github.com/lancedb/docs/blob/main/STYLE.md#say-it-directly
+level: suggestion
+ignorecase: true
+# Keep this list small. Technical nouns such as GPU utilization stay intact.
+swap:
+  utilize: use
+  utilizes: uses
+  utilized: used
+  utilizing: using
+  in order to: to
+tests:
+  - name: suggests familiar verbs
+    input: Utilize the index. The query utilizes it. We utilized it. Try utilizing it.
+    want: |
+      1:1:LanceDB.PlainLanguage:Consider 'use' instead of 'Utilize'.
+      1:30:LanceDB.PlainLanguage:Consider 'uses' instead of 'utilizes'.
+      1:46:LanceDB.PlainLanguage:Consider 'used' instead of 'utilized'.
+      1:63:LanceDB.PlainLanguage:Consider 'using' instead of 'utilizing'.
+  - name: shortens an unnecessary phrase
+    input: Create an index in order to search faster.
+    want: |
+      1:17:LanceDB.PlainLanguage:Consider 'to' instead of 'in order to'.
+  - name: preserves technical terms and identifiers
+    input: |
+      Measure GPU utilization and resource underutilization. Keep the rows in order. Call `utilize()` and `in order to` only as literal examples.
+
+      ```python
+      utilized = "in order to"
+      ```
+    want: ''
diff --git a/.github/vale/styles/LanceDB/ProductNames.yml b/.github/vale/styles/LanceDB/ProductNames.yml
new file mode 100644
index 000000000..e4621a521
--- /dev/null
+++ b/.github/vale/styles/LanceDB/ProductNames.yml
@@ -0,0 +1,34 @@
+extends: substitution
+message: "Use '%s' instead of '%s'."
+link: https://github.com/lancedb/docs/blob/main/STYLE.md#names
+level: warning
+ignorecase: false
+# Case-sensitive. A lowercase package, repository or domain name, such as
+# lancedb or github.com, is left alone; write identifiers in code font.
+swap:
+  '(?:Lancedb|LanceDb|lanceDB|LANCEDB|Lance DB)': LanceDB
+  'LanceDB (?:cloud|CLOUD)': LanceDB Cloud
+  'LanceDB (?:enterprise|ENTERPRISE)': LanceDB Enterprise
+  'LanceDB (?:oss|Oss)': LanceDB OSS
+  '(?:HuggingFace|Huggingface|Hugging face)': Hugging Face
+  Langchain: LangChain
+  Typescript: TypeScript
+  VoyageAI: Voyage AI
+tests:
+  - name: corrects the product name
+    input: Install Lancedb and connect to LanceDB cloud or LanceDB enterprise.
+    want: |
+      1:9:LanceDB.ProductNames:Use 'LanceDB' instead of 'Lancedb'.
+      1:32:LanceDB.ProductNames:Use 'LanceDB Cloud' instead of 'LanceDB cloud'.
+      1:49:LanceDB.ProductNames:Use 'LanceDB Enterprise' instead of 'LanceDB enterprise'.
+  - name: corrects names seen misspelled in the current pages
+    input: Load a HuggingFace model, build a Langchain retriever in Typescript and call VoyageAI.
+    want: |
+      1:8:LanceDB.ProductNames:Use 'Hugging Face' instead of 'HuggingFace'.
+      1:35:LanceDB.ProductNames:Use 'LangChain' instead of 'Langchain'.
+      1:58:LanceDB.ProductNames:Use 'TypeScript' instead of 'Typescript'.
+      1:78:LanceDB.ProductNames:Use 'Voyage AI' instead of 'VoyageAI'.
+  - name: leaves package names, identifiers and code alone
+    input: |
+      The lancedb package exposes `HuggingFaceEmbeddings` and LanceDBConnection; see `Typescript` in code.
+    want: ''
diff --git a/.github/vale/styles/LanceDB/VagueHeadings.yml b/.github/vale/styles/LanceDB/VagueHeadings.yml
new file mode 100644
index 000000000..e100891b0
--- /dev/null
+++ b/.github/vale/styles/LanceDB/VagueHeadings.yml
@@ -0,0 +1,19 @@
+extends: existence
+message: "'%s' doesn't say what the section covers. Name the task or topic instead."
+link: https://github.com/lancedb/docs/blob/main/STYLE.md#headings
+level: suggestion
+scope: heading
+ignorecase: true
+tokens:
+  - then what
+tests:
+  - name: flags a heading that names no topic
+    input: |
+      ## Then what {#next}
+
+      Choose the output according to how you will use it.
+    want: |
+      1:4:LanceDB.VagueHeadings:'Then what' doesn't say what the section covers. Name the task or topic instead.
+  - name: leaves the phrase alone in body text
+    input: Then what happens to the old fragments? Cleanup removes them.
+    want: ''
diff --git a/.github/vale/styles/LanceDB/VaguePhrases.yml b/.github/vale/styles/LanceDB/VaguePhrases.yml
new file mode 100644
index 000000000..43d00f9e0
--- /dev/null
+++ b/.github/vale/styles/LanceDB/VaguePhrases.yml
@@ -0,0 +1,31 @@
+extends: existence
+message: "'%s' talks about the writing, not the subject. State the point directly."
+link: https://github.com/lancedb/docs/blob/main/STYLE.md#say-it-directly
+level: suggestion
+ignorecase: false
+scope: sentence
+tokens:
+  # The page's role instead of its content, as in "This page is the concept".
+  - '^[Tt]his page is the concept'
+  # A filler sentence opener, listed in skills/docs-writer/SKILL.md.
+  - '^That matters'
+tests:
+  - name: flags a page describing its own role
+    input: This page is the concept; the SQL reference is the specification.
+    want: |
+      1:1:LanceDB.VaguePhrases:'This page is the concept' talks about the writing, not the subject. State the point directly.
+  - name: flags the filler opener
+    input: That matters for partner workloads because names repeat.
+    want: |
+      1:1:LanceDB.VaguePhrases:'That matters' talks about the writing, not the subject. State the point directly.
+  - name: leaves ordinary uses alone
+    input: This page describes compaction. It is the operation that matters for video.
+    want: ''
+  - name: leaves specific descriptions and embedded phrases alone
+    input: |
+      This page is the entry point for the Python API. This page is the conceptual overview of the table model. The heading "That matters" is quoted here. Only the setting That matters is highlighted.
+    want: ''
+  - name: catches a filler opener after another sentence
+    input: Names repeat. That matters for partner workloads.
+    want: |
+      1:15:LanceDB.VaguePhrases:'That matters' talks about the writing, not the subject. State the point directly.
diff --git a/.github/workflows/docs-style.yml b/.github/workflows/docs-style.yml
index f0bac9cd0..6be8b0f8f 100644
--- a/.github/workflows/docs-style.yml
+++ b/.github/workflows/docs-style.yml
@@ -1,14 +1,13 @@
 name: Docs prose style
 
-# Vale checks the mechanical rules in the LanceDB style guide
-# (lancedb/docs, STYLE.md) with the package pinned in .vale.ini. Its findings
-# are advisory annotations on the lines a pull request adds or changes and
-# never fail the job; an install, sync or configuration error still does.
+# Style findings are advisory; installation and configuration errors fail.
 on:
   pull_request:
     paths:
       - "docs/web/**/*.mdx"
       - ".vale.ini"
+      - ".github/vale/**"
+      - ".github/workflows/docs-style.yml"
 
 permissions:
   contents: read
@@ -40,6 +39,7 @@ jobs:
         uses: vale-cli/vale-action@518a9136acc6e6668ce7c00d367051e0941e87ff # v3.0.0
         with:
           version: none
+          sync: false
           files: docs/web
           reporter: github-pr-annotations
           filter_mode: added
diff --git a/.vale.ini b/.vale.ini
index 13b421863..bbac95eb3 100644
--- a/.vale.ini
+++ b/.vale.ini
@@ -1,5 +1,6 @@
-# Prose style for the pages in docs/web: the shared LanceDB package, pinned by
-# release. The rules and guide live in lancedb/docs (STYLE.md and vale/).
-# Run `vale sync` once, then `vale docs/web/<page>.mdx`.
-StylesPath = .vale/styles
-Packages = https://github.com/lancedb/docs/releases/download/vale-lancedb-v0.1.0/LanceDB.zip
+StylesPath = .github/vale/styles
+MinAlertLevel = suggestion
+
+[*.mdx]
+BasedOnStyles = LanceDB
+Vale.Repetition = warning
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index fa854317d..4a73f8b35 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -88,13 +88,12 @@ npm i -g mint      # https://mintlify.com/docs/installation
 cd docs/web && mint dev
 ```
 
-Wording, names and punctuation follow the
-[LanceDB style guide](https://github.com/lancedb/docs/blob/main/STYLE.md).
-[Vale](https://vale.sh) checks part of it, and pull requests show its
-suggestions on the lines they change. To check a page yourself:
+[Vale](https://vale.sh) checks wording, names and punctuation using the
+[bundled LanceDB rules](.github/vale/README.md). Pull requests show suggestions
+on the lines they change. With Vale 3.24.0 installed, check a page with:
 
 ```bash
-vale sync && vale docs/web/indexing/vector-index.mdx
+vale docs/web/indexing/vector-index.mdx
 ```
 
 This repository holds a page at every path the site publishes, so the whole