jekyll-ai-related 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d8d5e15d03e0c8ed77ab9de0b6a6955e7ab78fee435529ade1dc1dfa9dc1679c
-  data.tar.gz: 6486621d77107539b5ae32af1bb2376f02b2f59f7074dc0a4ded1650c3db6d78
+  metadata.gz: '03779eb5ce75f69231a8a7563008c2ebe851bc21ef619763d42e119045830b1d'
+  data.tar.gz: 4f28fba97390ff1497dfe5309eec9cee958f9148356bcf5673613522fdd6a1ab
 SHA512:
-  metadata.gz: b10bdbef5642400506c067400ab7900a85611fe1c297a20a495a81051f258cacf727e19834884b43a6978009f795ca435d7f18189484bc3a361f9d372a1ae615
-  data.tar.gz: 4e8112831d3f36bfcb194613b791d404f8d9df1d3ad7254f1785b4834f0b42b3268d1a74b51aef9b67f2122ae0e6999236cf1f250491f9f1050663115faefd8a
+  metadata.gz: 91b81a9b34325df10bd2d7b649b5e0237590f2a1211e6e3f65307a1019826c4eb8702f90628d7ad7cc5f2b68f4abe2e531f73dd08e0b24d656ae980bfffd3558
+  data.tar.gz: 6e84604c67c77b0e7373f352bc0df6aa320b99ba160e186b3dd8f17ef43c879c8a65ad55c11ffce78b6504b1467448b77bc2ca245d1f63c7a7a79bdc0f882853

data/.github/workflows/release.yml

@@ -14,7 +14,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Create release and upload assets
-        uses: softprops/action-gh-release@v2
+        uses: softprops/action-gh-release@v3
         with:
           name: ${{ github.ref_name }}
           tag_name: ${{ github.ref_name }}

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    jekyll-ai-related (0.2.1)
+    jekyll-ai-related (0.3.0)
       httparty (~> 0.22)
       jekyll (>= 3.7, < 5.0)
       json (~> 2.7)
@@ -9,33 +9,33 @@ PATH
 GEM
   remote: https://rubygems.org/
   specs:
-    addressable (2.8.8)
+    addressable (2.9.0)
       public_suffix (>= 2.0.2, < 8.0)
     ast (2.4.3)
     base64 (0.3.0)
-    bigdecimal (4.0.1)
+    bigdecimal (4.1.2)
     colorator (1.1.0)
-    concurrent-ruby (1.3.6)
-    csv (3.3.5)
+    concurrent-ruby (1.3.8)
+    csv (3.3.6)
     em-websocket (0.5.3)
       eventmachine (>= 0.12.9)
       http_parser.rb (~> 0)
     eventmachine (1.2.7)
-    ffi (1.17.3)
-    ffi (1.17.3-x86_64-linux-gnu)
+    ffi (1.17.4)
+    ffi (1.17.4-x86_64-linux-gnu)
     forwardable-extended (2.6.0)
-    google-protobuf (4.33.5)
+    google-protobuf (4.35.1)
       bigdecimal
-      rake (>= 13)
-    google-protobuf (4.33.5-x86_64-linux-gnu)
+      rake (~> 13.3)
+    google-protobuf (4.35.1-x86_64-linux-gnu)
       bigdecimal
-      rake (>= 13)
+      rake (~> 13.3)
     http_parser.rb (0.8.1)
     httparty (0.24.2)
       csv
       mini_mime (>= 1.0.0)
       multi_xml (>= 0.5.2)
-    i18n (1.14.8)
+    i18n (1.15.2)
       concurrent-ruby (~> 1.0)
     jekyll (4.4.1)
       addressable (~> 2.4)
@@ -60,12 +60,12 @@ GEM
       sass-embedded (~> 1.75)
     jekyll-watch (2.2.1)
       listen (~> 3.0)
-    json (2.18.1)
+    json (2.21.1)
     kramdown (2.5.2)
       rexml (>= 3.4.4)
     kramdown-parser-gfm (1.1.0)
       kramdown (~> 2.0)
-    language_server-protocol (3.17.0.5)
+    language_server-protocol (3.17.0.6)
     liquid (4.0.4)
     listen (3.10.0)
       logger
@@ -74,23 +74,24 @@ GEM
     logger (1.7.0)
     mercenary (0.4.0)
     mini_mime (1.1.5)
-    multi_xml (0.8.1)
+    minitest (5.27.0)
+    multi_xml (0.9.1)
       bigdecimal (>= 3.1, < 5)
-    parallel (1.27.0)
-    parser (3.3.10.1)
+    parallel (1.28.0)
+    parser (3.3.12.0)
       ast (~> 2.4.1)
       racc
     pathutil (0.16.2)
       forwardable-extended (~> 2.6)
     prism (1.9.0)
-    public_suffix (7.0.2)
+    public_suffix (7.0.5)
     racc (1.8.1)
     rainbow (3.1.1)
-    rake (13.3.1)
+    rake (13.4.2)
     rb-fsevent (0.11.2)
     rb-inotify (0.11.1)
       ffi (~> 1.0)
-    regexp_parser (2.11.3)
+    regexp_parser (2.12.0)
     rexml (3.4.4)
     rouge (4.7.0)
     rubocop (1.57.2)
@@ -104,7 +105,7 @@ GEM
       rubocop-ast (>= 1.28.1, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 2.4.0, < 3.0)
-    rubocop-ast (1.49.0)
+    rubocop-ast (1.50.0)
       parser (>= 3.3.7.2)
       prism (~> 1.7)
     rubocop-jekyll (0.14.0)
@@ -115,10 +116,10 @@ GEM
       rubocop-ast (>= 1.31.1, < 2.0)
     ruby-progressbar (1.13.0)
     safe_yaml (1.0.5)
-    sass-embedded (1.97.3)
+    sass-embedded (1.102.0)
       google-protobuf (~> 4.31)
       rake (>= 13)
-    sass-embedded (1.97.3-x86_64-linux-gnu)
+    sass-embedded (1.102.0-x86_64-linux-gnu)
       google-protobuf (~> 4.31)
     terminal-table (3.0.2)
       unicode-display_width (>= 1.1.1, < 3)
@@ -132,6 +133,7 @@ PLATFORMS
 DEPENDENCIES
   bundler (~> 2.6)
   jekyll-ai-related!
+  minitest (~> 5.25)
   rake (~> 13.0)
   rubocop-jekyll (~> 0.14)
 

data/MIGRATE.md

@@ -1,6 +1,6 @@
 # Migrate
 
-Migration instructions when breaking changes are introduced.
+This file is the compatibility entry point for migration guidance. See the complete [migration and rebuild guide](docs/MIGRATIONS.md) for current procedures.
 
 ## From 0.1.0 to 0.2.0
 
@@ -18,6 +18,4 @@ If you are upgrading from `v0.1.0`, you need drop the data and re-run the plugin
 
 ### Environments support
 
-This version also introduces the concept of *environments*. It reads `JEKYLL_ENV` env var to allow you to have different tables and functions for different environments.
-
-You need to set `JEKYLL_ENV` every time you run the plugin to use this feature. It can be set to anything, like `ci`, `dev`, or `production`. Not setting the env var will make the plugin behave like version `0.1.0`.
+This version also introduced environment-specific table and function names through `JEKYLL_ENV`. See the [environment migration guidance](docs/MIGRATIONS.md#environment-migration) for setup and safety details.

data/README.md

@@ -4,62 +4,52 @@
 [![GitHub Release](https://img.shields.io/github/v/release/pirafrank/jekyll-ai-related)](https://github.com/pirafrank/jekyll-ai-related/releases/latest)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 
-A [Jekyll](https://jekyllrb.com/) [command](https://jekyllrb.com/docs/plugins/commands/) plugin to generate list of related posts using AI.
+A [Jekyll](https://jekyllrb.com/) command plugin that uses OpenAI embeddings and Supabase/pgvector to generate related-post data for your blog.
 
-The plugin uses uses OpenAI API to generate embeddings from posts content, and stores them on Supabase vector database. A query on Supabase provides a similarity score between the post and all other posts on the site. The plugin then selects the most similar posts to generate the list of related posts.
+The plugin writes related-post results to `_data`, so normal `jekyll build` runs do not call OpenAI or Supabase. Run `jekyll related` when posts are added or changed, or run it in your CI pipeline.
 
-To avoid unnecessary API calls or slowing down the website generation, the plugin stores the list of related posts in the site's `_data` folder. This way you can `jekyll build` without calling the plugin or making API calls, while still having the list of related posts available as site data. You only need to re-run it when you add or update posts.
+## Quick start
 
-## Getting started
+### Requirements
 
-1. Setup Supabase
-2. Install the plugin
-3. Configure the plugin
-4. Run the plugin
+- Ruby `>= 3.2`
+- Jekyll `>= 3.7` and `< 5.0`
+- An OpenAI API key
+- A Supabase project with pgvector available
 
-## Requirements
+### 1. Create the database objects
 
-- OpenAI account and API key
-- Supabase account and API key
-- Supabase URL of the project where the DB is located
+Run [`sql/supabase/create.sql`](sql/supabase/create.sql) in the Supabase SQL editor. This creates the default `page_embeddings` table and `cosine_similarity` function.
 
-### Supabase setup
+For existing installations, follow the [migration guide](docs/MIGRATIONS.md), especially the v0.3.0 `embedding_fingerprint` column migration. See [Supabase setup](docs/SUPABASE.md) for environment-specific tables and maintenance.
 
-Use the `create.sql` script in the `sql\supabase` folder of this repo to create the required table and functions on your Supabase project. You can run the script in the SQL editor of the Supabase dashboard.
+### 2. Install the plugin
 
-You can always revert the changes by running the `drop.sql` script.
+Add the gem to the Jekyll site's `Gemfile`:
 
-## Installation
-
-1. Add the plugin to you Jekyll site's `Gemfile` in the `:jekyll_plugins` group:
-
-```Gemfile
+```ruby
 group :jekyll_plugins do
-  gem 'jekyll-ai-related'
+  gem "jekyll-ai-related"
 end
 ```
 
-2. Run `bundle install`
+Then install it:
 
-### Install from git
+```sh
+bundle install
+```
 
-Alternatively, you can get code straight from this repository. Code from `main` branch should be stable enough but may contain unreleased software with bugs or breaking changes. Unreleased software should be considered of beta quality.
+To use the unreleased `main` branch instead:
 
-```Gemfile
+```ruby
 group :jekyll_plugins do
-  gem 'jekyll-ai-related', git: 'https://github.com/pirafrank/jekyll-ai-related', branch: 'main'
+  gem "jekyll-ai-related", git: "https://github.com/pirafrank/jekyll-ai-related", branch: "main"
 end
 ```
 
-## Update
+### 3. Configure the site
 
-```sh
-bundle update jekyll-ai-related
-```
-
-## Configuration
-
-Sample configuration to add to your `_config.yml`:
+Add the plugin configuration to `_config.yml`:
 
 ```yaml
 jekyll-ai-related:
@@ -75,153 +65,74 @@ jekyll-ai-related:
   db_function: cosine_similarity
 ```
 
-Configuration is optional. The plugin will use the default values if not provided.
-
-### Configuration options
-
-| Option | Type | Description | Default Value |
-| --- | --- | --- | --- |
-| `post_unique_field` | string | A field that uniquely identifies a post | `slug` |
-| `post_updated_field` | string | A field that indicates when the post was last updated | `date` |
-| `output_path` | string | The subdir inside `_data` where related posts will be stored | `related_posts` |
-| `include_drafts` | boolean | Whether to include drafts in the list of related posts | `false` |
-| `include_future` | boolean | Whether to include future posts in the list of related posts | `false` |
-| `related_posts_limit` | integer | The maximum number of related posts to extract per post | `3` |
-| `related_posts_score_threshold` | float | The minimum similarity score to consider a post related | `0.5` |
-| `precision` | integer | The number of decimal digits to round similarity scores to | `3` |
-| `db_table` | string | The name of the table where the embeddings are stored | `page_embeddings` |
-| `db_function` | string | The name of the function to calculate similarity scores | `cosine_similarity` |
-
-> [!NOTE]
-> `related_posts_limit` and `related_posts_score_threshold` are used to filter the list of related posts. The plugin will return the top `related_posts_limit` posts with a similarity score greater than `related_posts_score_threshold`. A post may have 0 or more than `related_posts_limit` related posts, but only the top `related_posts_limit` will be returned, if any.
-
-### Advanced configuration
-
-You can customize the unique and updated fields, for example if you have a plugin that generates a unique ID for each post, or if you have a custom field that indicates when the post was last updated.
-
-Check the [post-metadata.rb](https://github.com/pirafrank/fpiracom/blob/8cc17a5801a73f7c8cbad4cbee099db18389b187/_plugins/post-metadata.rb) plugin of mine for an example. You can download and place it in your `_plugins` folder. It will add metadata to each `post` object and makes it accessible anywhere the `post` object is.
-
-If you do so, you could use the following configuration:
-
-```yaml
-jekyll-ai-related:
-  post_unique_field: uid
-  post_updated_field: most_recent_edit
-```
-
-## Usage
-
-To run, the plugin needs the OpenAI and Supabase API keys, and Supabase URL. The plugin expects them as environment variables.
+These defaults are optional. Set the required credentials in the environment:
 
 ```sh
 export OPENAI_API_KEY="your_openai_api_key"
-export SUPABASE_URL="your_supabase_url"
+export SUPABASE_URL="https://your-project.supabase.co"
 export SUPABASE_KEY="your_supabase_api_key"
 ```
 
-Never write API keys in your code or configuration files you commit.
+Never commit API keys. See the [configuration reference](docs/CONFIGURATION.md) for all settings and custom post fields.
 
-Then you can run the plugin with:
+### 4. Generate related posts
 
 ```sh
 bundle exec jekyll related
 ```
 
-> [!IMPORTANT]
-> Re-run the plugin whenever you add or update posts to update the list of related posts. Only posts with a `post_updated_field` date greater than the last run will be processed.
-
-### Options
-
-You can pass options to the plugin to change its behavior. Options are passed after the command name. Not specifying an option is the same as specifying the default value.
-
-| Option | Description | Default |
-| --- | --- | --- |
-| `--debug` | Most verbose. Sets log level to Debug. | Jekyll default |
-| `--quiet` | Do not print Info logs. Sets log level to Error. | Jekyll default |
-| `--future` | Generate embeddings and find related posts also for those with a future date. | `false` |
-| `--drafts` | Generate embeddings and find related posts also for drafts. | `false` |
-| `--dry-run` | Do not update the database, do not write related posts to disk. | `false` |
-
-Example:
+A useful validation run is:
 
 ```sh
-bundle exec jekyll related --dry-run --future
+bundle exec jekyll related --dry-run --debug
 ```
 
-### Environments
-
-Jekyll AI Related can optionally use the `JEKYLL_ENV` environment variable to determine where is running. This allows you to have separate tables and functions for different environments, for example for development and production.
-
-When `JEKYLL_ENV` is set, the plugin will append its value to `db_table` and `db_function` configuration options, separated by a `_` character. If it is not set, the plugin won't append anything. You must set `JEKYLL_ENV` every time you run the plugin to use environments.
-
-> [!IMPORTANT]
-> You need to make sure you have the corresponding tables and functions on your Supabase project. Edit the committed SQL script accordingly. They work with no modification when `JEKYLL_ENV` is not set.
+Dry-run mode does not update Supabase or write YAML files, but it may call OpenAI for cache misses. Use a normal run to populate the database and generate output.
 
-For example, if you `export JEKYLL_ENV=production` and have the configuration below
+Generated data is written under `_data/related_posts/`, for example:
 
-```yaml
-jekyll-ai-related:
-  db_table: cool_table_name
-  db_function: cool_function_name
+```text
+_data/related_posts/my-post.yml
 ```
 
-the plugin will use:
-
-- `cool_table_name_production` as the database table name,
-- `cool_function_name_production` as the database function name.
-
-> [!TIP]
-> Explicitly declare `JEKYLL_ENV=production` to avoid overwriting production data by mistake.
-
-## Jekyll integration
+See the [integration guide](docs/INTEGRATION.md) for using the data in Liquid templates.
 
-The plugin generates a list of related posts for each post in the site. Yet it won't edit your posts or layouts to display the list. It's up to you to integrate it in your site.
+## Environments
 
-You can access the list in the `site.data.YOUR_output_path_NAME` object. For example, with the default settings you can access it with `site.data.related_posts[post.slug]`.
+Set `JEKYLL_ENV` to isolate development, staging, and production data:
 
-Here's a snippet to add it to the bottom of your `_layouts/post.html` layout file. It works with the default configuration.
-
-```html
-{% if site.data.related_posts[page.slug] %}
-<div class="related-posts">
-  <h3>Related Posts</h3>
-  <ul>
-    {% for post in site.data.related_posts[page.slug] %}
-    <li>
-      <a href="{{ post.url }}">{{ post.title }}</a>
-      <br/>{{ post.date | date: "%B %d, %Y" }}
-    </li>
-    {% endfor %}
-  </ul>
-</div>
-{% endif %}
+```sh
+JEKYLL_ENV=production bundle exec jekyll related
 ```
 
-> [!NOTE]
-> The plugin writes posts in descending order of similarity score, from most similar to least similar. You can change the order by reversing the loop in the snippet above.
-
-## Development
-
-Clone and run `bundle install` to get started.
+The environment suffix is appended to the configured table and RPC function names, so the corresponding Supabase objects must already exist. See [Supabase setup](docs/SUPABASE.md) for details.
 
-Code lives in `lib/jekyll` directory. `lib/jekyll/commands/generator.rb` is the entry point of the plugin, as per Jekyll documentation. More details [here](https://jekyllrb.com/docs/plugins/commands/).
+## Documentation
 
-## Contributing
+The [documentation index](docs/README.md) groups the complete guides by setup, operation, implementation, and development.
 
-[Bug reports](https://github.com/pirafrank/jekyll-ai-related/issues) and [pull requests](https://github.com/pirafrank/jekyll-ai-related/pulls) are welcome on GitHub.
+- [Getting started](docs/GETTING_STARTED.md)
+- [Configuration](docs/CONFIGURATION.md)
+- [Migrations](docs/MIGRATIONS.md)
+- [Workflow and operations](docs/WORKFLOW.md)
+- [Troubleshooting](docs/TROUBLESHOOTING.md)
+- [Architecture and embeddings](docs/ARCHITECTURE.md), [embedding details](docs/EMBEDDINGS.md)
+- [Development](docs/DEVELOPMENT.md)
+- [Security](docs/SECURITY.md)
 
-## Code of Conduct
-
-Everyone interacting in the project's codebase, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/pirafrank/jekyll-ai-related/blob/main/CODE_OF_CONDUCT.md).
-
-## Guarantee
+## Development
 
-This plugin is provided as is, without any guarantee. Use at your own risk.
+```sh
+bundle install
+bundle exec rake test
+bundle exec rake lint
+bundle exec rake build
+```
 
-## Disclaimer
+See [Development](docs/DEVELOPMENT.md) for the repository layout, validation workflow, and release process.
 
-This plugin uses OpenAI API and Supabase, and you are responsible for complying with their respective terms of service. This plugin is not affiliated with OpenAI or Supabase.
+## Contributing and license
 
-## License
+[Bug reports](https://github.com/pirafrank/jekyll-ai-related/issues) and [pull requests](https://github.com/pirafrank/jekyll-ai-related/pulls) are welcome. The project is available under the [MIT License](https://opensource.org/licenses/MIT).
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+This plugin uses OpenAI and Supabase services. Users are responsible for complying with their respective terms of service. The plugin is not affiliated with either service.

data/Rakefile

@@ -2,6 +2,7 @@
 
 require "bundler/gem_tasks"
 require "rubocop/rake_task"
+require "rake/testtask"
 
 RuboCop::RakeTask.new
 
@@ -9,6 +10,12 @@ task :default do
   sh "rake -AT"
 end
 
+Rake::TestTask.new(:test) do |t|
+  t.libs << "lib"
+  t.libs << "test"
+  t.pattern = "test/**/*_test.rb"
+end
+
 task lint: :rubocop
 
 task :changelog do

data/docs/ARCHITECTURE.md

@@ -0,0 +1,96 @@
+# Architecture
+
+Jekyll AI Related is a Ruby gem that adds the `jekyll related` command to Jekyll. The command reads the site's posts, reuses cached embeddings when possible or generates them through OpenAI, stores vectors and post metadata in Supabase/Postgres, performs a similarity search, and writes the resulting related-post lists into the site's `_data` directory.
+
+The generated YAML is deliberately local to the site. A normal `jekyll build` can therefore consume related-post data without calling OpenAI or Supabase; the command is run separately when content changes.
+
+## System boundary
+
+```text
+Jekyll site                         External services                 Generated site data
+-----------                         ------------------                 -------------------
+posts + front matter
+        |
+        v
+`jekyll related` --> OpenAI embeddings API
+        |                    |
+        |                    v
+        +------------> Supabase REST API
+                         (Postgres + pgvector)
+                                |
+                                v
+                         similarity results
+                                |
+                                v
+                         `_data/<path>/*.yml`
+                                |
+                                v
+                 normal Jekyll templates / `site.data`
+```
+
+The repository contains the gem code under `lib/`, the Supabase bootstrap SQL under `sql/supabase/`, and packaging/release configuration. There are no application controllers, web server, runtime database connections, or test suite in this repository; the plugin runs as a batch command during content maintenance.
+
+## Runtime components
+
+- `lib/jekyll-ai-related.rb` loads Jekyll and the processor.
+- `lib/jekyll/commands/generator.rb` registers the `related` Jekyll command and translates CLI flags into options.
+- `lib/jekyll/embeddings-generator/init.rb` builds and validates configuration, then creates and reads a Jekyll site. `site.generate` is called so other Jekyll generator plugins can enrich post data before processing.
+- `lib/jekyll/processor.rb` coordinates the two phases: embedding persistence and related-post generation.
+- `embeddings/generate.rb` calls `https://api.openai.com/v1/embeddings` using the `text-embedding-3-small` model.
+- `embeddings/store.rb` communicates with Supabase using its REST/PostgREST endpoints. It handles existence checks, upserts, vector retrieval, and the similarity RPC call.
+- `models/data.rb` creates the database payload. `models/metadata.rb` creates the JSON metadata stored beside each vector.
+- `sql/supabase/create.sql` enables pgvector, creates the table and IVFFlat cosine index, and defines the stored procedure used by the plugin.
+
+## Command lifecycle
+
+1. Jekyll loads the gem and exposes `bundle exec jekyll related`.
+2. The command combines `_config.yml`, CLI flags, environment variables, and defaults. It validates `OPENAI_API_KEY`, `SUPABASE_URL`, and `SUPABASE_KEY`.
+3. A fresh Jekyll site is built with the configured draft and future-post settings. The site is read and generators are run.
+4. For every included post, the plugin extracts `post.content` and metadata, computes a model/content fingerprint, and fetches the existing Supabase record.
+5. The plugin reuses the stored embedding when the fingerprint and vector are present; otherwise it calls OpenAI. It upserts when the row is missing, the fingerprint changed, or the configured update value is newer.
+6. For every included post, it fetches that post's stored embedding and submits a SQL query through the configured Supabase RPC function. The query excludes the current post, applies the score threshold, sorts by cosine distance, and limits the result count.
+7. Non-empty results are serialized as YAML to `_data/<output_path>/<safe-uid>.yml`. Existing files for the same post are overwritten; an empty result does not remove an older file.
+
+The two phases are sequential. If related-post lookup fails for one post, the error is logged and processing continues with the next post.
+
+## Configuration and naming
+
+The `jekyll-ai-related` section of `_config.yml` supports:
+
+| Setting | Default | Role |
+| --- | --- | --- |
+| `post_unique_field` | `slug` | Post field used as the database `uid` and output filename key |
+| `post_updated_field` | `date` | Post field used for update comparison |
+| `output_path` | `related_posts` | Subdirectory under `_data` |
+| `include_drafts` | `false` | Include drafts in the generated Jekyll site |
+| `include_future` | `false` | Include future-dated posts |
+| `related_posts_limit` | `3` | Maximum result count per post |
+| `related_posts_score_threshold` | `0.5` | Minimum cosine similarity |
+| `precision` | `3` | Decimal places used for returned similarity values |
+| `db_table` | `page_embeddings` | Supabase table name |
+| `db_function` | `cosine_similarity` | Supabase RPC function name |
+
+`JEKYLL_ENV`, when present, is appended to both database names with an underscore. For example, `JEKYLL_ENV=production` changes the defaults to `page_embeddings_production` and `cosine_similarity_production`. The corresponding objects must exist in Supabase; the plugin does not create environment-specific objects automatically.
+
+CLI flags can enable drafts, future posts, and dry-run mode for a single invocation. `--debug` and `--quiet` adjust Jekyll logging.
+
+## Output contract
+
+For the default configuration, a post with slug `my-post` produces:
+
+```text
+_data/related_posts/my-post.yml
+```
+
+The YAML value is an array of result objects returned by Supabase. Each result contains `title`, `uid`, `most_recent_edit`, `url`, `date`, and a rounded `similarity` value. Templates access it as `site.data.related_posts[page.slug]`.
+
+The filename is lowercased and every character outside `[a-z0-9-_]` is replaced by `-`. The database lookup still uses the original configured post value, so the filename is only a filesystem-safe representation.
+
+## Operational characteristics
+
+- API keys are read only from environment variables and are sent in the OpenAI and Supabase HTTP headers.
+- The command is not part of the normal build path. Keep generated `_data` files available to the site build, and schedule `jekyll related` after creating or editing posts.
+- OpenAI is called only for cache misses: new posts, changed rendered content, legacy rows without a fingerprint, or after an embedding model change. Supabase reads and similarity searches still run for every included post.
+- `--dry-run` still reads from both services and may generate embeddings for cache misses; it skips Supabase updates and local file writes. It is therefore useful for exercising the flow, but it is not an offline mode.
+- The included SQL uses an IVFFlat index with `vector_cosine_ops` and `lists = 100`. The vector dimension must remain compatible with the selected OpenAI model and the table definition.
+- The plugin uses raw SQL text assembled in Ruby and executes it through a `SECURITY DEFINER` PostgreSQL function. Table/function names and the SQL setup should be treated as trusted deployment configuration.

data/docs/CONFIGURATION.md

@@ -0,0 +1,81 @@
+# Configuration reference
+
+Configuration is read from the `jekyll-ai-related` section of `_config.yml`.
+
+```yaml
+jekyll-ai-related:
+  post_unique_field: slug
+  post_updated_field: date
+  output_path: related_posts
+  include_drafts: false
+  include_future: false
+  related_posts_limit: 3
+  related_posts_score_threshold: 0.5
+  precision: 3
+  db_table: page_embeddings
+  db_function: cosine_similarity
+```
+
+| Setting | Type | Default | Description |
+| --- | --- | --- | --- |
+| `post_unique_field` | string | `slug` | Post field used as the database `uid` and output filename key. |
+| `post_updated_field` | string | `date` | Post field compared with the stored `most_recent_edit`. |
+| `output_path` | string | `related_posts` | Directory under `_data` for generated YAML. |
+| `include_drafts` | boolean | `false` | Include drafts when building the processing site. |
+| `include_future` | boolean | `false` | Include future-dated posts. |
+| `related_posts_limit` | integer | `3` | Maximum number of results per source post. |
+| `related_posts_score_threshold` | number | `0.5` | Minimum cosine similarity. |
+| `precision` | integer | `3` | Decimal places used in returned similarity values. |
+| `db_table` | string | `page_embeddings` | Supabase table containing vectors. |
+| `db_function` | string | `cosine_similarity` | Supabase RPC function used for the search. |
+
+> [!NOTE]
+> `related_posts_limit` and `related_posts_score_threshold` work together: the plugin returns up to `related_posts_limit` posts whose similarity is greater than `related_posts_score_threshold`. A post can have no qualifying related posts, and the threshold can result in fewer results than the limit.
+
+CLI flags are invocation-level overrides for drafts, future posts, and dry run:
+
+```text
+--drafts       include drafts
+--future       include future posts
+--dry-run      skip database updates and file writes
+--debug        enable debug logging
+--quiet        suppress info logging
+```
+
+For drafts and future posts, a true value in `_config.yml` or the corresponding CLI flag enables inclusion. `--dry-run` is not an offline mode.
+
+## Environment naming
+
+If `JEKYLL_ENV` is set, its value is appended to both database names:
+
+```sh
+JEKYLL_ENV=production
+```
+
+With the defaults, the plugin uses `page_embeddings_production` and `cosine_similarity_production`. The suffixed objects must already exist.
+
+## Credentials
+
+Credentials are not Jekyll configuration values. They are required environment variables:
+
+- `OPENAI_API_KEY`
+- `SUPABASE_URL`
+- `SUPABASE_KEY`
+
+Missing credentials stop configuration validation before processing posts.
+
+## Precedence and important behavior
+
+Configuration values come from `_config.yml` and defaults; CLI flags can enable drafts, future posts, and dry run for the current command. `post_unique_field` and `post_updated_field` must exist on every processed post. The plugin computes a content fingerprint before calling OpenAI and reuses stored vectors when the fingerprint matches. Metadata-only changes still trigger a database upsert when the configured update timestamp is newer than the stored value.
+
+## Advanced custom fields
+
+Sites can use custom post metadata for identity and freshness. For example, a plugin that adds a unique `uid` and a `most_recent_edit` field can use:
+
+```yaml
+jekyll-ai-related:
+  post_unique_field: uid
+  post_updated_field: most_recent_edit
+```
+
+The fields must be available on the post after Jekyll's generators have run. `uid` must be unique across the configured Supabase table, and `most_recent_edit` must be comparable with the stored timestamp.