From 3cc2f6c871e43deac215f45f78436b1f73970302 Mon Sep 17 00:00:00 2001
From: Rainer M Krug <Rainer@krugs.de>
Date: Wed, 1 Apr 2026 13:47:52 +0200
Subject: [PATCH 1/6] docs: align README with backend-neutral embedding support

---
 README.md | 16 +++++++---------
 1 file changed, 7 insertions(+), 9 deletions(-)

diff --git a/README.md b/README.md
index 67f1112..a195ee9 100644
--- a/README.md
+++ b/README.md
@@ -1,18 +1,18 @@
 # openalexVectorComp
 
-**Auto-tagging via TEI embeddings + Qdrant**, implemented in R.
+**Auto-tagging via embedding backends and reference scoring**, implemented in R.
 
 ## Version
 
-Current development version: **0.1.4**.
+Current development version: **0.2.0**.
 
 - Embeddings served by **TEI** (Text Embeddings Inference; Hugging Face).
-- Vector search by **Qdrant**.
+- Embeddings via a **backend-neutral interface** (`hf`, `openai`, `tei`).
 - Scoring: **prototype cosine-distance** + **reference-area ridge score**
   (`distance_ridge()` + `score_ridge()`) + threshold calibration.
 - Works great with DuckDB/Arrow pipelines.
 
-## 0.1.4 Highlights
+## 0.2.0 Highlights
 
 - Demo defaults now use a shared structure:
   - `demos/openalex`
@@ -41,14 +41,12 @@ Or build & install from the zip you downloaded.
 
 ## Runtime dependencies
 
-- TEI server running (CPU is fine):
+- For `provider = "tei"`:
   ```bash
   text-embeddings-router --model BAAI/bge-small-en-v1.5 --port 8080
   ```
-
-- Qdrant server (optional if you only use modeling; required for ANN search):
-  - Binary: `./qdrant`
-  - Docker: `docker run -p 6333:6333 -p 6334:6334 qdrant/qdrant`
+- For hosted embedding backends (`provider = "hf"` or `"openai"`), set
+  `OVC_API_TOKEN` in your environment.
 
 ## Vignettes
 

From 59adf25ffb0cf5c332ff950a6dd1c9fec1766755 Mon Sep 17 00:00:00 2001
From: Rainer M Krug <Rainer@krugs.de>
Date: Wed, 1 Apr 2026 14:16:47 +0200
Subject: [PATCH 2/6] ci: skip examples in PR check matrix

---
 .github/workflows/pr-checks.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/pr-checks.yml b/.github/workflows/pr-checks.yml
index a270217..3e02008 100644
--- a/.github/workflows/pr-checks.yml
+++ b/.github/workflows/pr-checks.yml
@@ -45,4 +45,4 @@ jobs:
       - name: Run R CMD check
         uses: r-lib/actions/check-r-package@v2
         with:
-          args: 'c("--no-manual", "--no-build-vignettes", "--no-multiarch")'
+          args: 'c("--no-manual", "--no-build-vignettes", "--no-multiarch", "--no-examples")'

From ad9441abdd2cd958a904a8411d32a5309efe1b7c Mon Sep 17 00:00:00 2001
From: Rainer M Krug <Rainer@krugs.de>
Date: Wed, 1 Apr 2026 14:17:50 +0200
Subject: [PATCH 3/6] docs: align DESCRIPTION and README with
 embedding-distance package scope

---
 DESCRIPTION | 11 ++++++-----
 README.md   |  2 +-
 2 files changed, 7 insertions(+), 6 deletions(-)

diff --git a/DESCRIPTION b/DESCRIPTION
index a4c62d6..614a2ca 100644
--- a/DESCRIPTION
+++ b/DESCRIPTION
@@ -1,6 +1,6 @@
 Package: openalexVectorComp
 Type: Package
-Title: Auto-tagging via TEI Embeddings and Qdrant (Prototype-Margin + Ridge Logistic)
+Title: Embedding Vectorization and Distance-Based Scoring Workflows
 Version: 0.2.0
 Authors@R: c(
     person(given = "Rainer", family = "Krug", role = c("aut", "cre"), email = "you@example.org"),
@@ -9,10 +9,11 @@ Authors@R: c(
 Author: Rainer Krug [aut, cre],
   ChatGPT Assistant [ctb]
 Maintainer: Rainer Krug <you@example.org>
-Description: R-first orchestration for auto-tagging based on text embeddings served by
-    a TEI (Text Embeddings Inference) server and vector search in Qdrant.
-    Provides prototype-margin scoring, ridge logistic classification, simple ensembling,
-    calibration/threshold selection, and utilities to ingest/query Qdrant.
+Description: R-first orchestration for text vectorization (embeddings),
+    embedding distance computation, and distance-based scoring workflows.
+    Supports backend-neutral embedding providers (HF, OpenAI, TEI),
+    prototype cosine-distance scoring, reference-area distance scoring,
+    and threshold calibration utilities.
 License: MIT + file LICENSE
 Encoding: UTF-8
 LazyData: true
diff --git a/README.md b/README.md
index a195ee9..fac547a 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,6 @@
 # openalexVectorComp
 
-**Auto-tagging via embedding backends and reference scoring**, implemented in R.
+**Embedding of Corpora**, implemented in R.
 
 ## Version
 

From 0d257f29f7fd627df6456782b88856598aed5a3f Mon Sep 17 00:00:00 2001
From: Rainer M Krug <Rainer@krugs.de>
Date: Wed, 1 Apr 2026 14:28:43 +0200
Subject: [PATCH 4/6] ci: disable vignette execution in PR check matrix

---
 .github/workflows/pr-checks.yml | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/.github/workflows/pr-checks.yml b/.github/workflows/pr-checks.yml
index 3e02008..3ac36b6 100644
--- a/.github/workflows/pr-checks.yml
+++ b/.github/workflows/pr-checks.yml
@@ -45,4 +45,5 @@ jobs:
       - name: Run R CMD check
         uses: r-lib/actions/check-r-package@v2
         with:
-          args: 'c("--no-manual", "--no-build-vignettes", "--no-multiarch", "--no-examples")'
+          build_args: 'c("--no-manual", "--no-build-vignettes")'
+          args: 'c("--no-manual", "--no-multiarch", "--no-examples", "--ignore-vignettes")'

From 171355ea435b538753dc5b659c383582fdfb841e Mon Sep 17 00:00:00 2001
From: Rainer M Krug <Rainer@krugs.de>
Date: Wed, 1 Apr 2026 14:43:20 +0200
Subject: [PATCH 5/6] docs: split release notes and move development continuity
 to root

---
 .Rbuildignore                                 |   1 +
 ...CONTINUITY.md => DEVELOPMENT_CONTINUITY.md |   0
 IMPLEMENTATION_NOTES.md                       | 533 ++----------------
 NEWS.md                                       |  69 +++
 README.md                                     |   2 +-
 5 files changed, 125 insertions(+), 480 deletions(-)
 rename inst/DEVELOPMENT_CONTINUITY.md => DEVELOPMENT_CONTINUITY.md (100%)
 create mode 100644 NEWS.md

diff --git a/.Rbuildignore b/.Rbuildignore
index 972d455..b42d6d3 100644
--- a/.Rbuildignore
+++ b/.Rbuildignore
@@ -1,6 +1,7 @@
 ^vignettes/\.quarto$
 ^vignettes/.*_files$
 ^IMPLEMENTATION_NOTES\.md$
+^DEVELOPMENT_CONTINUITY\.md$
 ^doc$
 ^Meta$
 ^inst/ASR$
diff --git a/inst/DEVELOPMENT_CONTINUITY.md b/DEVELOPMENT_CONTINUITY.md
similarity index 100%
rename from inst/DEVELOPMENT_CONTINUITY.md
rename to DEVELOPMENT_CONTINUITY.md
diff --git a/IMPLEMENTATION_NOTES.md b/IMPLEMENTATION_NOTES.md
index 8bfc955..c4e1de4 100644
--- a/IMPLEMENTATION_NOTES.md
+++ b/IMPLEMENTATION_NOTES.md
@@ -1,498 +1,73 @@
-# Implementation Notes (March 2026)
+# Implementation Notes
 
-## Release v0.1.3 (March 2026)
+Last updated: 2026-04-01
 
-- Documentation synchronized with current code and repository layout:
-  - `README.md` scoring description aligned to current implementation
-    (`distance_ridge()` + `score_ridge()` reference-area workflow).
-  - `vignettes/simplestart.qmd` paths updated from obsolete `inst/examples/*`
-    to existing `inst/ovc_demo/project/*` fixtures.
-  - `vignettes/package-overview.qmd` clarified `distances()` as non-exported
-    internal helper.
-  - OpenAI batch vignette and other technical vignettes spot-checked for API
-    naming consistency.
-- Package version bumped in `DESCRIPTION`:
-  - `Version: 0.1.2` -> `Version: 0.1.3`
-- Release commit scope includes current repository cleanup changes in this
-  branch, including removal of stale helper scripts under:
-  - `inst/qdrant functions/`
-- Release-check caveats:
-  - `R CMD check --no-manual --no-examples --no-tests .` may still emit
-    package-structure notes/warnings if local non-package artifacts are present
-    (for example temporary check directories).
+## Purpose and Scope
 
-## Scope
+This file is the implementation/release engineering log.
+It records what changed in code and operational behavior across releases.
+User-facing release highlights are tracked in `NEWS.md`.
 
-This note tracks all implementation/documentation changes made in this workstream
-for `openalexVectorComp` (not only backend refactors).
+It is intentionally different from:
+- `DEVELOPMENT_CONTINUITY.md` (living handover + design principles + decision continuity).
 
-## Change Log
+In short:
+- `DEVELOPMENT_CONTINUITY.md` = "how to continue development safely".
+- `IMPLEMENTATION_NOTES.md` = "what was implemented and shipped".
+- `NEWS.md` = "user-facing release highlights".
 
-### 1) Package/docs alignment after rename
+## Current Baseline (v0.2.0 branch state)
 
-- Updated references from `autotagr` to `openalexVectorComp` in key docs.
-- Removed obsolete vignette `vignettes/autotagr.Rmd`.
-- Removed obsolete TODO source `R/run_autotag.R.todo` that referenced
-  non-existent APIs.
-- Updated vignette code in `vignettes/simplestart.qmd` to match current
-  function signatures.
+- Package focus is embedding/vectorization plus distance/scoring workflows.
+- Backends are provider-pluggable (`hf`, `openai`, `tei`) through a shared backend config/dispatch interface.
+- OpenAI Batch workflow is explicit async:
+  - submit -> status -> collect
+  - pending state is expected and non-fatal.
+- Demo structure uses provider subfolders:
+  - `demos/openalex`
+  - `demos/openai`
+- pkgdown output/deploy target is `_site/`.
+- CI includes PR checks matrix and manual triggers.
 
-### 2) Documentation consistency fixes
+## Release-Focused Implementation Log
 
-- Corrected mismatches between function signatures and docs, including:
-  - `calibrate_threshold()` argument behavior/docs.
-  - `distance_reference_cosine()` output column naming/docs.
-  - `distance_ridge()` stale parameter docs.
-  - embedding orchestration behavior/docs.
-- Regenerated roxygen2 docs (`man/`, `NAMESPACE`) using source loading.
+### v0.1.3
 
-### 3) Pluggable backend refactor
+- Documentation sync to align with implemented API and current repository layout.
+- Clarified ridge/reference-area behavior in docs (`distance_ridge()` + `score_ridge()`).
+- Updated vignette paths and internal/exported function descriptions.
+- Version bump to `0.1.3`.
+- Included repository cleanup scope for stale `inst/qdrant functions/*` helpers.
 
-- Added backend adapter API split across provider-specific files:
-  - `R/embed_backend_core.R` (exported config/info/embed dispatch)
-  - `R/embed_backend_hf.R` (Hugging Face adapter)
-  - `R/embed_backend_openai.R` (OpenAI adapter)
-  - `R/embed_backend_tei.R` (TEI/local adapter)
-- Removed the previous single-file implementation (`R/embed_backend.R`).
-- Central dispatch now supports `provider = "hf"`, `"openai"`, or `"tei"`.
+### v0.1.4
 
-### 4) Authentication convention
+- Introduced stronger OpenAI demo/tutorial flow and async handling guidance.
+- Added two-phase demo workflow support:
+  - render does not hard-fail when batch is still pending,
+  - finalize step performs status/collect/compare later.
+- Added persistent direct-vs-batch comparison outputs under:
+  - `project/openai_batch_comparison/label=<label>/`.
+- Improved tutorial narrative consistency across demos.
 
-- Standardized provider token handling to one environment variable:
-  - `OVC_API_TOKEN`
-- Adapter sends this token as `Authorization: Bearer <token>` when present.
+### v0.2.0
 
-### 5) Defaults and endpoint behavior
+- Consolidated OpenAI batch helper/module naming and structure.
+- Added/updated CI workflows for PR check suites with caching and manual trigger support.
+- Added pkgdown GH Pages workflow alignment and `_site` destination usage.
+- Documentation cleanup to remove stale scope references and align README/package messaging with embedding + distance computation focus.
+- Added `DEVELOPMENT_CONTINUITY.md` as required pre-commit continuity artifact.
 
-- Default backend configuration now targets HF inference:
-  - `provider = "hf"`
-  - model default: `BAAI/bge-small-en-v1.5`
+## Operational Notes
 
-### 6) TEI simplification and pipeline behavior updates
+- OpenAI batch collection may complete after demo rendering; this is expected async behavior.
+- Batch/direct embedding comparisons can show tiny numeric differences due to floating-point serialization and runtime-level numerical variance.
+- These small differences are not typically semantic regressions when cosine similarity remains effectively 1.0.
 
-- Added generic embedding entry points:
-  - `embed_texts()` (single-call text embedding via configured backend)
-  - `embed_corpus()` (streaming corpus embedding pipeline)
-- Removed TEI-specific embedding entry points:
-  - `tei_embed_text()`
-  - `tei_embed()`
-- `embed_corpus()` now:
-  - switched to canonical text construction:
-    - `Title: {title}\nAbstract: {abstract}`
-    - title-only fallback when abstract is empty.
-  - added resumable behavior using `id + text_hash`:
-    - unchanged rows are skipped when `delete_existing = FALSE`.
-    - full rebuild when `delete_existing = TRUE`.
-  - output rows now include:
-    - `id`, `text_hash`, `provider`, `model_id`, `created_at`, `V1..Vd`.
+## Maintenance Rules
 
-### 7) Exports and documentation
+When behavior changes, update both files with non-overlapping intent:
 
-- Exports:
-  - backend core functions added to `NAMESPACE`.
-  - `prototype_centroid()` removed from public API; internal helper moved into
-    `R/distance_reference_cosine.R` as `centroid_prototype()`.
-- Documentation:
-  - maintained via roxygen2 and regenerated `man/` + `NAMESPACE`.
-  - added detailed Quarto vignette:
-    - `vignettes/backend-architecture.qmd`
-    - covers backend internals, dispatch order, sequence and flowchart diagrams,
-      and how to add new providers.
-  - added detailed TEI operations vignette:
-    - `vignettes/tei-server-operations.qmd`
-    - documents shell-based TEI process handling (start/stop/health), now that
-      lifecycle helpers were removed from package code.
-
-### 8) TEI server lifecycle simplification
-
-- Removed in-package TEI lifecycle/state helpers:
-  - `tei_start()`, `tei_stop()`, `tei_state()`, `tei_info()`,
-    `tei_default_embed_url()`
-- Removed package unload hook/state container by deleting `R/zzz.R`.
-- Removed dependency on `processx`.
-- TEI backend probing now uses internal lightweight HTTP `/info` probing in
-  `R/embed_backend_tei.R`.
-
-### 9) Test suite additions (HF integration)
-
-- Added `testthat` infrastructure:
-  - `tests/testthat.R`
-  - `Config/testthat/edition: 3` in `DESCRIPTION`
-  - `testthat (>= 3.0.0)` in `Suggests`
-- Added HF integration helpers:
-  - `tests/testthat/helper-hf.R`
-  - skips tests unless `OVC_API_TOKEN` is set and HF endpoint is reachable.
-- Added end-to-end integration tests:
-  - `tests/testthat/test-hf-end-to-end.R`
-  - covers:
-    - `embed_texts()`
-    - `embed_corpus()`
-    - `distance_reference_cosine()`
-    - `distance_ridge()`
-    - `calibrate_threshold()`
-
-### 10) HF router endpoint migration and probe hardening
-
-- Fixed HF adapter URL construction mismatch:
-  - router base URL now maps to `/models/{model}`
-  - legacy API base URL keeps `/pipeline/feature-extraction/{model}`
-- Updated HF test probe endpoint to:
-  - `https://router.huggingface.co/hf-inference/models/BAAI/bge-small-en-v1.5`
-- Probe request now uses:
-  - `inputs = "ping"` (single string payload)
-  - `req_error(is_error = function(resp) FALSE)` to inspect status codes
-- Skip policy now only skips on:
-  - network/transport errors
-  - auth rejection (`401`, `403`)
-  - provider outages (`5xx`)
-- Removed unconditional `skip_on_cran()` from HF helper so local integration
-  tests can run without requiring `NOT_CRAN=true`.
-- `4xx` payload/model mismatches no longer force an automatic skip, making
-  test behavior easier to diagnose.
-
-### 11) HF default model change
-
-- Switched the HF default model to `BAAI/bge-small-en-v1.5`.
-- Updated HF test helper backend and probe request to use this model.
-- Updated architecture vignette examples and default-model documentation
-  accordingly.
-
-### 12) Distance-function test expansion
-
-- Added offline unit/integration coverage in
-  `tests/testthat/test-distance-functions.R` for:
-  - `similarity_cosine()` and `distance_cosine()` (vector and matrix inputs)
-  - `fit_ridge()` model persistence and class checks
-  - `distance_reference_cosine()` output validity and positive-vs-negative separation
-  - `distance_ridge()` score range checks (`[0, 1]`) and separation checks
-  - internal `distances()` helper join behavior on overlapping `id` keys
-- Tests use a synthetic local Parquet embeddings dataset and do not require API
-  tokens or network access.
-
-### 13) Validation and faulty-input test expansion
-
-- Added `tests/testthat/test-validation-inputs.R` with negative/edge cases to
-  increase branch coverage in lower-covered modules:
-  - `embedding_backend_config()` validation:
-    - non-positive `timeout`
-    - negative `retries`
-    - non-positive `max_batch_size`
-  - backend dispatch validation:
-    - invalid backend objects/providers in `embedding_backend_info()` and
-      `embedding_backend_embed_texts()`
-    - non-character `texts` and empty-text behavior
-  - internal backend helper behavior:
-    - `.embedding_as_matrix()` inconsistent/unsupported formats
-    - `.embedding_batch_starts()` fallback for invalid batch size
-    - `.embedding_with_retry()` success-after-retries and terminal failure
-    - HF URL mapping branch coverage (`/models/...` vs legacy
-      `/pipeline/feature-extraction/...`)
-  - `embed_corpus()` input checks:
-    - empty `project_dir`
-    - invalid `batch_size`
-    - invalid backend object
-    - missing required corpus columns
-  - `fit_ridge()` / `distance_ridge()` failure modes:
-    - embeddings with no `V1..Vd` columns
-    - included ids absent from dataset
-  - `calibrate_threshold()` validation:
-    - missing score column
-    - malformed `labels_parquet` schema
-    - no labeled rows available for calibration
-
-### 14) Metadata file rename and sidecar behavior
-
-- Renamed embeddings metadata sidecar:
-  - from `_tei_info.yaml`
-  - to `embed_model.yaml`
-- Updated metadata handling in:
-  - `embed_corpus()` write path
-  - `distance_ridge()` read/copy path
-- Added backward compatibility in `distance_ridge()`:
-  - prefers `embed_model.yaml`
-  - falls back to legacy `_tei_info.yaml` for existing projects
-- Expanded metadata payload to better support reproducibility:
-  - `model.id`
-  - `model.requested_id`
-  - `model.embedding_dim`
-  - `backend.provider`
-  - `backend.base_url`
-  - `backend.embed_url`
-  - `backend.max_batch_size`
-  - `backend.timeout`
-  - `backend.retries`
-- Because `embed_model.yaml` is a non-parquet sidecar in dataset directories,
-  Arrow dataset openings now use:
-  - `factory_options = list(exclude_invalid_files = TRUE)`
-  in pipeline and plotting paths that scan these directories.
-
-### 15) Backend config YAML read/save API
-
-- Added exported helpers:
-  - `embedding_backend_read(fn = "embed_model.yaml")`
-  - `embedding_backend_save(backend, fn = "embed_model.yaml")`
-- `embedding_backend_save()` writes YAML in the same field shape as
-  `embedding_backend_config()` output:
-  - `provider`, `base_url`, `model`, `embed_url`, `max_batch_size`,
-    `timeout`, `retries`
-- `embedding_backend_read()` returns a normalized backend config by calling
-  `embedding_backend_config()` under the hood.
-- Backward compatibility:
-  - `embedding_backend_read()` also accepts legacy nested metadata format
-    (`model` + `backend` blocks) from earlier alpha revisions.
-- `embed_corpus()` now writes metadata through `embedding_backend_save()`.
-- `distance_ridge()` now reads metadata through `embedding_backend_read()` when
-  deriving model partition naming.
-
-### 16) Coverage-focused offline test expansion
-
-- Added `tests/testthat/test-embedding-offline.R` to increase branch coverage
-  without network/API tokens:
-  - `embed_texts()` forwarding behavior
-  - HF/OpenAI/TEI adapter batching paths
-  - adapter malformed-payload error paths
-  - `embed_corpus()` incremental behavior and `delete_existing` branch
-- Expanded `tests/testthat/test-validation-inputs.R` with a successful
-  `calibrate_threshold()` run using `labels_parquet`,
-  `metric = "precision_at_recall"`, and explicit thresholds.
-
-### 17) Plot function rename and tests
-
-- Renamed plotting API from TEI-specific names to backend-neutral names:
-  - `tei_plot_pca()` -> `plot_embeddings_pca()`
-  - `tei_plot_umap()` -> `plot_embeddings_umap()`
-- Renamed source file:
-  - `R/tei_plot.R` -> `R/plot_embeddings.R`
-- Regenerated docs/exports:
-  - removed `man/tei_plot_pca.Rd`, `man/tei_plot_umap.Rd`
-  - added `man/plot_embeddings_pca.Rd`, `man/plot_embeddings_umap.Rd`
-- Added `tests/testthat/test-plot-embeddings.R` covering:
-  - PCA and UMAP happy paths
-  - CSV/vector include/exclude id inputs
-  - sampling path in UMAP
-  - schema/embedding-column validation errors
-
-### 18) Pluggable text preparation in `embed_corpus()`
-
-- Added exported default cleaner:
-  - `clean_abstract_for_embedding()`
-  - returns contract columns `id`, `text`, `text_hash`
-  - optionally returns provenance fields:
-    - `text_quality`, `abstract_raw_present`, `abstract_kept`,
-      `discard_reason`, `cleaning_mode`
-- `embed_corpus()` now accepts:
-  - `text_preprocessor` (function)
-  - `cleaner_args` (list passed to preprocessor)
-- `embed_corpus()` now validates preprocessor outputs:
-  - must be a data frame
-  - must include `id`, `text`, `text_hash`
-  - no ids outside the current batch
-  - no duplicated ids
-  - drops empty/NA `id` or `text`
-- Resume/skip logic remains `id + text_hash`, but hash is now produced by the
-  preprocessor.
-- Output parquet now preserves extra preprocessor-provided provenance columns.
-- `embed_model.yaml` now includes a `text_preprocessor` section with:
-  - `name`
-  - `mode` (if set via `cleaner_args`)
-  - `no_abstract_policy` (if set via `cleaner_args`)
-
-### 19) Tests for new cleaner/preprocessor contract
-
-- Added `tests/testthat/test-clean-abstract-for-embedding.R`:
-  - happy path
-  - missing abstract policies
-  - duplicated title removal
-  - placeholder/boilerplate handling
-  - mode behavior differences
-  - hash stability
-- Expanded `tests/testthat/test-embedding-offline.R`:
-  - custom `text_preprocessor` usage
-  - `cleaner_args` passthrough verification
-  - contract error handling for bad preprocessor outputs
-  - metadata assertions for `embed_model.yaml` preprocessor block
-
-### 20) Detailed abstract-cleaning vignette
-
-- Added a dedicated Quarto vignette:
-  - `vignettes/abstract-cleaning.qmd`
-- Covers:
-  - cleaning rationale and pipeline stages
-  - mermaid flow diagram of cleaning/decision path
-  - mode/policy behavior (`lenient|balanced|strict`,
-    `keep_title_only|discard|conditional`)
-  - step-by-step examples, including before/after kept vs discarded outputs
-  - custom pattern overrides
-  - integration with `embed_corpus(text_preprocessor, cleaner_args)`
-  - preprocessor contract validation and provenance columns
-
-## Main Design Considerations
-
-The complexity does not mainly come from TEI itself.
-It comes from combining these concerns:
-
-- backend abstraction (config/info/embed separation),
-- resumable/idempotent writes (`id + text_hash`),
-- variable endpoint capabilities (model info, request limits),
-- robust long-run behavior (retry handling, metadata tracking).
-
-Supporting both local TEI and hosted inference APIs can increase variability, but
-resume/reliability requirements are the biggest complexity driver.
-
-## Simplification Tradeoff
-
-A simpler alternative would be:
-
-- one TEI embedding function with fixed arguments (`url`, `texts`, `batch_size`),
-- no backend registry/dispatch,
-- minimal/no retries,
-- no service probing in adapter,
-- keep resume logic only in pipeline layer.
-
-This is easier to maintain but less extensible for additional providers.
-
-## Process Notes
-
-- `roxygen2::roxygenise(load = "source")` was used because full package loading
-  in this environment can fail due to system restrictions around some dependencies.
-- Existing unrelated repo changes were preserved.
-- `inst/openalex_embedding_pipeline_v4.md` was intentionally left in place.
-
-## Ongoing Updates
-
-This file should be updated as additional changes are made in this branch so it
-remains a single place to review implementation decisions and rationale.
-
-### 21) Label-partitioned embeddings and pairwise prototype distances
-
-- `embed_corpus()` gained a new `label` argument (default `"corpus"`).
-- Embeddings path changed from `model/batch` to `model/label/batch`:
-  - `embeddings/model_id=<...>/label=<label>/batch=<n>/embeddings-*.parquet`
-- `delete_existing = TRUE` now deletes only the selected `label` subtree.
-- Resume hash loading now reads only the selected `label` partition.
-- Dry-run preview filename is now model-independent and corpus-based:
-  - `<corpus_name>_dryrun.parquet`
-- `embed_model.yaml` now stores `embedding_label` for traceability.
-
-- `distance_reference_cosine()` was redesigned from `included/excluded` centroid margin
-  to label-based cosine distance computation:
-  - inputs: `corpus_label`, `reference_label`
-  - computes pairwise matrix between all `reference` and `corpus` vectors
-  - output path:
-    - `distance_reference_cosine/model_id=<...>/corpus_label=<...>/reference_label=<...>/pairwise-cosine.parquet`
-  - includes `max_cells` guard for memory safety.
-
-### 22) Ridge refactor to reference-area scoring
-
-- `fit_ridge()` was redesigned to fit a reference-area model instead of binary
-  ridge logistic classification.
-- New fit contract:
-  - inputs: embeddings dataset + `reference_label`
-  - computes:
-    - centroid `mu`
-    - covariance `Sigma` (with fallback for very small reference sets)
-    - regularized inverse covariance `Sigma_inv`
-  - saves a fit object with class `ovc_reference_area_fit`.
-
-- `distance_ridge()` now:
-  - fits (or loads) reference-area model
-  - computes squared Mahalanobis distance `area_distance` for
-    `corpus_label` vectors
-  - writes parquet with columns:
-    - `id`
-    - `area_distance`
-  - output path:
-    - `distance_ridge/model_id=<...>/corpus_label=<...>/reference_label=<...>/batch=<n>/ridge-area-*.parquet`
-
-- Added `score_ridge()`:
-  - reads `distance_ridge()` output
-  - computes `relevance_score = exp(-alpha * area_distance)` (default
-    `alpha = 0.5`)
-  - writes scored parquet under `score_ridge/...`.
-
-- Metadata copy for distance outputs now includes ridge-mode context fields:
-  - `ridge_mode: reference_area`
-  - `reference_label`
-  - `corpus_label`
-  - `regularization`
-
-### 23) Calibration flow alignment
-
-- `calibrate_threshold()` was fixed to only read `included`/`excluded` CSVs
-  when `labels_parquet` is not provided.
-- This enables labels-only calibration for the new ridge workflow.
-
-### 24) `distance_reference_cosine()` distance-only matrix with centroid axis
-
-- `distance_reference_cosine()` was further simplified to be distance-only and
-  single-file:
-  - removed selectable `output` mode argument.
-  - removed separate `centroid-cosine.parquet` output.
-- Current output is always:
-  - `pairwise-cosine.parquet` under
-    `distance_reference_cosine/model_id=<...>/corpus_label=<...>/reference_label=<...>/`.
-- Output schema now encodes both pairwise and centroid distances in one wide
-  matrix:
-  - first column: `id` (corpus ids + one `"centroid"` row for corpus centroid),
-  - remaining columns: reference ids + one `"centroid"` column for reference
-    centroid.
-- Cell semantics:
-  - regular cells: `dist(corpus_i, reference_j)`,
-  - centroid column: `dist(corpus_i, reference_centroid)`,
-  - centroid row: `dist(corpus_centroid, reference_j)`,
-  - centroid corner: `dist(corpus_centroid, reference_centroid)`.
-
-### 25) `score_reference_cosine()` for full-matrix cosine scoring
-
-- Added exported `score_reference_cosine()` to transform the full output matrix
-  from `distance_reference_cosine()`.
-- Supports scoring methods:
-  - `linear` (default): `score = 1 - distance`
-  - `exponential`: `score = exp(-alpha * distance)`
-- Preserves matrix shape (`id` + all value columns) and writes scored output
-  under `score_reference_cosine/...`.
-- Implementation simplified to lazy Arrow/dplyr selection + single
-  materialization/write (no synthetic batch partition output).
-
-### 26) User-facing demo project runner + Quarto template
-
-- Added exported `run_demo_openalex_quarto()`:
-  - default demo location: `file.path(getwd(), "demo_project")`
-  - creates and preserves:
-    - `demo_backend.yaml` in `demo_dir/`
-    - `openalex_demo_analysis.qmd` in `demo_dir/`
-    - `project/corpus/` in `demo_dir/`
-    - `project/reference_corpus/` in `demo_dir/`
-  - optional `render = TRUE` runs `quarto render` inside `demo_dir`.
-- Added install-time demo fixtures in `inst/ovc_demo/`:
-  - `project/corpus/corpus_small.parquet` (<= 100 rows, `id/title/abstract`)
-  - `project/reference_corpus/reference_small.parquet` (<= 10 rows, `id/title/abstract`)
-- Added Quarto analysis template in `inst/ovc_demo/openalex_demo_analysis.qmd`
-  covering:
-  - `embed_corpus(label = "corpus")`
-  - `embed_corpus(label = "reference")` via temporary corpus swap
-  - `distance_reference_cosine()`
-  - `score_reference_cosine()`
-  - `distance_ridge()`
-  - `score_ridge()`
-- Added tests in `tests/testthat/test-demo-runner.R` for setup, overwrite
-  handling, fixture/schema caps, template call coverage, and optional render.
-
-### 27) Pure-R OpenAI Batch orchestration (submit/status/collect)
-
-- Added asynchronous OpenAI Batch functions:
-  - `embed_corpus_submit_openai_batch()`
-  - `embed_corpus_status_openai_batch()`
-  - `embed_corpus_collect_openai_batch()`
-- Implemented in pure R (`httr2`) with no Python/CLI dependency.
-- Submission now performs preflight planning before remote API calls:
-  - hard caps enforced: `max_requests_per_job <= 50000`, `max_job_bytes <= 200MB`
-  - conservative defaults: `max_requests_per_job = 20000`, `max_job_bytes = 150MB`
-  - auto-splits jobs by count/bytes with warning
-  - single oversized request line fails early with clear id/bytes error.
-- Added local batch state and workspace:
-  - `openai_batch_state_label=<label>.json`
-  - `openai_batch/model_id=<...>/label=<...>/batch=<n>/requests.jsonl|manifest.parquet|output.jsonl`
-- Collected outputs are written to the canonical embeddings layout:
-  - `embeddings/model_id=<...>/label=<...>/batch=<n>/embeddings-*.parquet`
-  ensuring downstream compatibility with distance/score/plotting flows.
+1. Update `IMPLEMENTATION_NOTES.md` for shipped implementation scope.
+2. Update `DEVELOPMENT_CONTINUITY.md` for design rationale, decisions, and handover continuity.
+3. Update `NEWS.md` for user-facing release notes.
+4. Ensure README/vignettes match.
diff --git a/NEWS.md b/NEWS.md
new file mode 100644
index 0000000..900ba5d
--- /dev/null
+++ b/NEWS.md
@@ -0,0 +1,69 @@
+# openalexVectorComp news
+
+## 0.2.0
+
+### New Features
+
+- Added explicit two-phase async OpenAI demo flow (`run_demo_openai_quarto()`
+  plus `finalize_demo_openai_batch()` follow-up).
+- Standardized demo defaults to `demos/openalex` and `demos/openai`.
+- Consolidated OpenAI batch helper naming and module organization.
+
+### Bug Fixes
+
+- Improved non-blocking async demo behavior so pending batch jobs do not
+  terminate the render workflow.
+- Updated CI workflow arguments to avoid unintended vignette/example execution
+  during matrix checks.
+
+### Documentation
+
+- Improved tutorial-style demo narratives and direct-vs-batch comparison
+  guidance.
+- Updated docs to align package scope with embedding + distance/scoring
+  workflows.
+- Updated pkgdown workflow/output alignment with `_site` deployment.
+
+### Breaking Changes
+
+- None.
+
+## 0.1.4
+
+### New Features
+
+- Added finalize workflow for status/collect/compare when batch jobs complete.
+- Added persisted direct-vs-batch comparison outputs.
+
+### Bug Fixes
+
+- Added robust non-blocking OpenAI batch demo behavior.
+
+### Documentation
+
+- Improved demo readability and tutorial consistency.
+
+### Breaking Changes
+
+- None.
+
+## 0.1.3
+
+### New Features
+
+- None.
+
+### Bug Fixes
+
+- Included cleanup of stale qdrant helper files.
+
+### Documentation
+
+- Synchronized documentation with current API and repository layout.
+- Clarified ridge/reference-area scoring behavior in docs.
+- Updated vignette paths and exported/internal function descriptions.
+- Bumped version to `0.1.3`.
+
+### Breaking Changes
+
+- None.
diff --git a/README.md b/README.md
index fac547a..058394d 100644
--- a/README.md
+++ b/README.md
@@ -26,7 +26,7 @@ Current development version: **0.2.0**.
 
 ## Development Continuity
 
-See `inst/DEVELOPMENT_CONTINUITY.md` for design principles, architectural
+See `DEVELOPMENT_CONTINUITY.md` for design principles, architectural
 decisions, and the required pre-commit update checklist that keeps development
 context continuous for both humans and AI agents.
 

From b481cf0b5be3c24b55d8890fc979d1430a8fbb2a Mon Sep 17 00:00:00 2001
From: Rainer M Krug <Rainer@krugs.de>
Date: Wed, 1 Apr 2026 15:00:08 +0200
Subject: [PATCH 6/6] release: v0.3.0 API rename, R file refactor, and
 docs/version sync

- Rename verbose public API functions to concise verb-first names:\n  * embed_corpus_submit_openai_batch() -> batch_submit_openai()\n  * embed_corpus_status_openai_batch() -> batch_status_openai()\n  * embed_corpus_collect_openai_batch() -> batch_collect_openai()\n  * finalize_demo_openai_batch() -> demo_finalize_openai_batch()\n  * run_demo_openai_quarto() -> run_demo_openai()\n  * run_demo_openalex_quarto() -> run_demo_openalex()\n  * embedding_backend_config()/info()/embed_texts()/read()/save()\n    -> backend_config()/backend_info()/backend_embed_texts()/backend_read()/backend_save()\n- Rename R source files to match new API/module vocabulary:\n  * embed_backend_* -> backend_*\n  * embed_corpus_*_openai_batch -> batch_*_openai\n  * embed_corpus_openai_batch_helpers.R -> batch_openai_helpers.R\n  * embed_openai_batch_helper.R -> batch_openai_http.R\n  * run_demos.R -> demo_run.R\n- Update all internal call sites, tests, demo templates, and vignettes to new names.\n- Regenerate roxygen outputs (NAMESPACE + man pages): remove old Rd files and add new ones for renamed exports.\n- Update NEWS with breaking-change migration table (old -> new API).\n- Bump package/documentation version references to 0.3.0 in:\n  * DESCRIPTION\n  * README\n  * NEWS\n  * IMPLEMENTATION_NOTES\n  * DEVELOPMENT_CONTINUITY\n\nNotes:\n- This is an immediate breaking rename with no compatibility wrappers, per release plan assumptions.\n- Behavior/signatures remain otherwise unchanged beyond function/file names.
---
 DESCRIPTION                                   |  2 +-
 DEVELOPMENT_CONTINUITY.md                     | 14 +++----
 IMPLEMENTATION_NOTES.md                       |  4 +-
 NAMESPACE                                     | 22 +++++------
 NEWS.md                                       | 22 +++++++++--
 R/{embed_backend_core.R => backend_core.R}    | 38 +++++++++----------
 R/{embed_backend_hf.R => backend_hf.R}        |  0
 ...mbed_backend_openai.R => backend_openai.R} |  0
 R/{embed_backend_tei.R => backend_tei.R}      |  0
 ..._openai_batch.R => batch_collect_openai.R} |  6 +--
 ...batch_helpers.R => batch_openai_helpers.R} |  0
 ...nai_batch_helper.R => batch_openai_http.R} |  0
 ...s_openai_batch.R => batch_status_openai.R} |  6 +--
 ...t_openai_batch.R => batch_submit_openai.R} | 10 ++---
 R/{run_demos.R => demo_run.R}                 | 34 ++++++++---------
 R/distance_ridge.R                            |  2 +-
 R/embed_corpus.R                              | 10 ++---
 R/embed_texts.R                               |  6 +--
 README.md                                     | 20 +++++-----
 inst/ovc_demo/openai_demo_analysis.qmd        | 26 ++++++-------
 inst/ovc_demo/openalex_demo_analysis.qmd      | 26 ++++++-------
 ...ng_backend_config.Rd => backend_config.Rd} |  8 ++--
 ..._embed_texts.Rd => backend_embed_texts.Rd} | 10 ++---
 ...edding_backend_info.Rd => backend_info.Rd} | 10 ++---
 ...edding_backend_read.Rd => backend_read.Rd} | 12 +++---
 man/backend_save.Rd                           | 20 ++++++++++
 ...penai_batch.Rd => batch_collect_openai.Rd} | 12 +++---
 ...openai_batch.Rd => batch_status_openai.Rd} | 12 ++----
 ...openai_batch.Rd => batch_submit_openai.Rd} | 12 +++---
 ...batch.Rd => demo_finalize_openai_batch.Rd} | 12 +++---
 man/embed_corpus.Rd                           |  4 +-
 man/embed_texts.Rd                            |  4 +-
 man/embedding_backend_save.Rd                 | 23 -----------
 ...mo_openai_quarto.Rd => run_demo_openai.Rd} | 10 ++---
 ...penalex_quarto.Rd => run_demo_openalex.Rd} | 10 ++---
 tests/testthat/helper-hf.R                    |  2 +-
 tests/testthat/test-demo-openai-finalize.R    | 32 ++++++++--------
 tests/testthat/test-demo-runner.R             | 26 ++++++-------
 tests/testthat/test-distance-functions.R      |  4 +-
 tests/testthat/test-embedding-offline.R       | 12 +++---
 tests/testthat/test-openai-batch.R            | 18 ++++-----
 tests/testthat/test-validation-inputs.R       | 38 +++++++++----------
 vignettes/backend-architecture.qmd            | 32 ++++++++--------
 vignettes/openai-batch-async.qmd              | 20 +++++-----
 vignettes/package-overview.qmd                | 16 ++++----
 vignettes/simplestart.qmd                     |  6 +--
 vignettes/tei-server-operations.qmd           |  4 +-
 47 files changed, 312 insertions(+), 305 deletions(-)
 rename R/{embed_backend_core.R => backend_core.R} (87%)
 rename R/{embed_backend_hf.R => backend_hf.R} (100%)
 rename R/{embed_backend_openai.R => backend_openai.R} (100%)
 rename R/{embed_backend_tei.R => backend_tei.R} (100%)
 rename R/{embed_corpus_collect_openai_batch.R => batch_collect_openai.R} (95%)
 rename R/{embed_corpus_openai_batch_helpers.R => batch_openai_helpers.R} (100%)
 rename R/{embed_openai_batch_helper.R => batch_openai_http.R} (100%)
 rename R/{embed_corpus_status_openai_batch.R => batch_status_openai.R} (91%)
 rename R/{embed_corpus_submit_openai_batch.R => batch_submit_openai.R} (96%)
 rename R/{run_demos.R => demo_run.R} (94%)
 rename man/{embedding_backend_config.Rd => backend_config.Rd} (87%)
 rename man/{embedding_backend_embed_texts.Rd => backend_embed_texts.Rd} (58%)
 rename man/{embedding_backend_info.Rd => backend_info.Rd} (52%)
 rename man/{embedding_backend_read.Rd => backend_read.Rd} (56%)
 create mode 100644 man/backend_save.Rd
 rename man/{embed_corpus_collect_openai_batch.Rd => batch_collect_openai.Rd} (57%)
 rename man/{embed_corpus_status_openai_batch.Rd => batch_status_openai.Rd} (62%)
 rename man/{embed_corpus_submit_openai_batch.Rd => batch_submit_openai.Rd} (83%)
 rename man/{finalize_demo_openai_batch.Rd => demo_finalize_openai_batch.Rd} (72%)
 delete mode 100644 man/embedding_backend_save.Rd
 rename man/{run_demo_openai_quarto.Rd => run_demo_openai.Rd} (84%)
 rename man/{run_demo_openalex_quarto.Rd => run_demo_openalex.Rd} (86%)

diff --git a/DESCRIPTION b/DESCRIPTION
index 614a2ca..30edc48 100644
--- a/DESCRIPTION
+++ b/DESCRIPTION
@@ -1,7 +1,7 @@
 Package: openalexVectorComp
 Type: Package
 Title: Embedding Vectorization and Distance-Based Scoring Workflows
-Version: 0.2.0
+Version: 0.3.0
 Authors@R: c(
     person(given = "Rainer", family = "Krug", role = c("aut", "cre"), email = "you@example.org"),
     person(given = "ChatGPT", family = "Assistant", role = "ctb")
diff --git a/DEVELOPMENT_CONTINUITY.md b/DEVELOPMENT_CONTINUITY.md
index bb448bf..f356ac1 100644
--- a/DEVELOPMENT_CONTINUITY.md
+++ b/DEVELOPMENT_CONTINUITY.md
@@ -43,20 +43,20 @@ Core flow:
 5. Optional threshold calibration (`calibrate_threshold()`).
 
 OpenAI batch flow:
-1. Submit (`embed_corpus_submit_openai_batch()`).
-2. Refresh status (`embed_corpus_status_openai_batch()`).
-3. Collect completed jobs (`embed_corpus_collect_openai_batch()`).
+1. Submit (`batch_submit_openai()`).
+2. Refresh status (`batch_status_openai()`).
+3. Collect completed jobs (`batch_collect_openai()`).
 4. Demo convenience wrapper:
-- `finalize_demo_openai_batch()` = status + collect + direct-vs-batch compare.
+- `demo_finalize_openai_batch()` = status + collect + direct-vs-batch compare.
 
-## 3. Current Demo Conventions (0.1.4)
+## 3. Current Demo Conventions (0.3.0)
 
 Default demo locations:
 - `demos/openalex`
 - `demos/openai`
 
 OpenAI demo behavior:
-- `run_demo_openai_quarto(..., render = TRUE)` may complete before batch does.
+- `run_demo_openai(..., render = TRUE)` may complete before batch does.
 - User is given explicit follow-up commands for status/finalize.
 - Batch comparison outputs are written to:
   `project/openai_batch_comparison/label=corpus_batch/`.
@@ -79,7 +79,7 @@ Template:
 - Date: 2026-04-01
 - Scope: OpenAI demo and batch comparison robustness
 - Decision: Implement two-phase OpenAI batch demo flow with
-  `finalize_demo_openai_batch()`.
+  `demo_finalize_openai_batch()`.
 - Why: Batch completion is asynchronous; render should not fail on pending jobs.
 - Alternatives considered: long blocking poll in render; hard-fail on timeout.
 - Impact: Clearer async semantics; stable demo render; persisted comparison
diff --git a/IMPLEMENTATION_NOTES.md b/IMPLEMENTATION_NOTES.md
index c4e1de4..519417b 100644
--- a/IMPLEMENTATION_NOTES.md
+++ b/IMPLEMENTATION_NOTES.md
@@ -16,7 +16,7 @@ In short:
 - `IMPLEMENTATION_NOTES.md` = "what was implemented and shipped".
 - `NEWS.md` = "user-facing release highlights".
 
-## Current Baseline (v0.2.0 branch state)
+## Current Baseline (v0.3.0 branch state)
 
 - Package focus is embedding/vectorization plus distance/scoring workflows.
 - Backends are provider-pluggable (`hf`, `openai`, `tei`) through a shared backend config/dispatch interface.
@@ -49,7 +49,7 @@ In short:
   - `project/openai_batch_comparison/label=<label>/`.
 - Improved tutorial narrative consistency across demos.
 
-### v0.2.0
+### v0.3.0
 
 - Consolidated OpenAI batch helper/module naming and structure.
 - Added/updated CI workflows for PR check suites with caching and manual trigger support.
diff --git a/NAMESPACE b/NAMESPACE
index 6c3a796..e3bfb88 100644
--- a/NAMESPACE
+++ b/NAMESPACE
@@ -1,26 +1,26 @@
 # Generated by roxygen2: do not edit by hand
 
+export(backend_config)
+export(backend_embed_texts)
+export(backend_info)
+export(backend_read)
+export(backend_save)
+export(batch_collect_openai)
+export(batch_status_openai)
+export(batch_submit_openai)
 export(calibrate_threshold)
 export(clean_abstract_for_embedding)
+export(demo_finalize_openai_batch)
 export(distance_cosine)
 export(distance_reference_cosine)
 export(distance_ridge)
 export(embed_corpus)
-export(embed_corpus_collect_openai_batch)
-export(embed_corpus_status_openai_batch)
-export(embed_corpus_submit_openai_batch)
 export(embed_texts)
-export(embedding_backend_config)
-export(embedding_backend_embed_texts)
-export(embedding_backend_info)
-export(embedding_backend_read)
-export(embedding_backend_save)
-export(finalize_demo_openai_batch)
 export(fit_ridge)
 export(plot_embeddings_pca)
 export(plot_embeddings_umap)
-export(run_demo_openai_quarto)
-export(run_demo_openalex_quarto)
+export(run_demo_openai)
+export(run_demo_openalex)
 export(score_reference_cosine)
 export(score_ridge)
 export(similarity_cosine)
diff --git a/NEWS.md b/NEWS.md
index 900ba5d..f3f5b9c 100644
--- a/NEWS.md
+++ b/NEWS.md
@@ -1,11 +1,11 @@
 # openalexVectorComp news
 
-## 0.2.0
+## 0.3.0
 
 ### New Features
 
-- Added explicit two-phase async OpenAI demo flow (`run_demo_openai_quarto()`
-  plus `finalize_demo_openai_batch()` follow-up).
+- Added explicit two-phase async OpenAI demo flow (`run_demo_openai()`
+  plus `demo_finalize_openai_batch()` follow-up).
 - Standardized demo defaults to `demos/openalex` and `demos/openai`.
 - Consolidated OpenAI batch helper naming and module organization.
 
@@ -26,7 +26,21 @@
 
 ### Breaking Changes
 
-- None.
+- Immediate API rename cleanup (no compatibility wrappers). Function mapping:
+
+| Old name | New name |
+|---|---|
+| `embed_corpus_submit_openai_batch()` | `batch_submit_openai()` |
+| `embed_corpus_status_openai_batch()` | `batch_status_openai()` |
+| `embed_corpus_collect_openai_batch()` | `batch_collect_openai()` |
+| `finalize_demo_openai_batch()` | `demo_finalize_openai_batch()` |
+| `run_demo_openai_quarto()` | `run_demo_openai()` |
+| `run_demo_openalex_quarto()` | `run_demo_openalex()` |
+| `embedding_backend_config()` | `backend_config()` |
+| `embedding_backend_info()` | `backend_info()` |
+| `embedding_backend_embed_texts()` | `backend_embed_texts()` |
+| `embedding_backend_read()` | `backend_read()` |
+| `embedding_backend_save()` | `backend_save()` |
 
 ## 0.1.4
 
diff --git a/R/embed_backend_core.R b/R/backend_core.R
similarity index 87%
rename from R/embed_backend_core.R
rename to R/backend_core.R
index feef00a..eaa7e11 100644
--- a/R/embed_backend_core.R
+++ b/R/backend_core.R
@@ -13,7 +13,7 @@
 #'
 #' @return A named list with backend configuration.
 #' @export
-embedding_backend_config <- function(
+backend_config <- function(
   provider = c("hf", "openai", "tei"),
   base_url = NULL,
   model = NULL,
@@ -74,14 +74,14 @@ embedding_backend_config <- function(
 #'
 #' Returns normalized backend metadata used by the pipeline.
 #'
-#' @param backend Backend configuration from [embedding_backend_config()].
+#' @param backend Backend configuration from [backend_config()].
 #'
 #' @return A list with fields `provider`, `model_id`, `dim`, `max_batch_size`,
 #'   and `raw`.
 #' @export
-embedding_backend_info <- function(backend = embedding_backend_config()) {
+backend_info <- function(backend = backend_config()) {
   if (!is.list(backend) || is.null(backend$provider)) {
-    stop("`backend` must be a configuration object from embedding_backend_config().")
+    stop("`backend` must be a configuration object from backend_config().")
   }
   switch(backend$provider,
     hf = .embedding_info_hf(backend),
@@ -98,13 +98,13 @@ embedding_backend_info <- function(backend = embedding_backend_config()) {
 #' adapter sends it as a bearer token.
 #'
 #' @param texts Character vector of input texts.
-#' @param backend Backend configuration from [embedding_backend_config()].
+#' @param backend Backend configuration from [backend_config()].
 #'
 #' @return Numeric matrix with one row per text and columns `V1..Vd`.
 #' @export
-embedding_backend_embed_texts <- function(
+backend_embed_texts <- function(
   texts,
-  backend = embedding_backend_config()
+  backend = backend_config()
 ) {
   if (!is.character(texts)) {
     stop("`texts` must be a character vector.")
@@ -113,7 +113,7 @@ embedding_backend_embed_texts <- function(
     return(matrix(numeric(0), nrow = 0))
   }
   if (!is.list(backend) || is.null(backend$provider)) {
-    stop("`backend` must be a configuration object from embedding_backend_config().")
+    stop("`backend` must be a configuration object from backend_config().")
   }
   switch(backend$provider,
     hf = .embedding_embed_texts_hf(texts, backend),
@@ -126,25 +126,25 @@ embedding_backend_embed_texts <- function(
 #' Read backend configuration from YAML
 #'
 #' Reads backend configuration from a YAML file and returns a normalized object
-#' in the same format as [embedding_backend_config()].
+#' in the same format as [backend_config()].
 #'
 #' Supports both the current flat format and legacy nested metadata format.
 #'
 #' @param fn Path to YAML file. Defaults to `"embed_model.yaml"`.
 #'
 #' @return A backend configuration list compatible with
-#'   [embedding_backend_config()].
+#'   [backend_config()].
 #' @export
-embedding_backend_read <- function(fn = "embed_model.yaml") {
+backend_read <- function(fn = "embed_model.yaml") {
   `%||%` <- function(x, y) if (is.null(x)) y else x
   meta <- yaml::read_yaml(fn)
   if (!is.list(meta)) {
     stop("`fn` does not contain a valid YAML object.")
   }
 
-  # Current flat format (same shape as embedding_backend_config()).
+  # Current flat format (same shape as backend_config()).
   if (!is.null(meta$provider)) {
-    cfg <- embedding_backend_config(
+    cfg <- backend_config(
       provider = meta$provider,
       base_url = meta$base_url %||% NULL,
       model = meta$model %||% NULL,
@@ -164,7 +164,7 @@ embedding_backend_read <- function(fn = "embed_model.yaml") {
   # Legacy nested format created earlier in this alpha cycle.
   if (!is.null(meta$backend) && !is.null(meta$backend$provider)) {
     model <- meta$model$requested_id %||% meta$model$id %||% NULL
-    cfg <- embedding_backend_config(
+    cfg <- backend_config(
       provider = meta$backend$provider,
       base_url = meta$backend$base_url %||% NULL,
       model = model,
@@ -187,19 +187,19 @@ embedding_backend_read <- function(fn = "embed_model.yaml") {
 #' Save backend configuration to YAML
 #'
 #' Writes a backend configuration (same shape as returned by
-#' [embedding_backend_config()]) to YAML.
+#' [backend_config()]) to YAML.
 #'
-#' @param backend Backend configuration from [embedding_backend_config()].
+#' @param backend Backend configuration from [backend_config()].
 #' @param fn Output YAML file path. Defaults to `"embed_model.yaml"`.
 #'
 #' @return Invisibly returns `fn`.
 #' @export
-embedding_backend_save <- function(
-  backend = embedding_backend_config(),
+backend_save <- function(
+  backend = backend_config(),
   fn = "embed_model.yaml"
 ) {
   if (!is.list(backend) || is.null(backend$provider)) {
-    stop("`backend` must be a configuration object from embedding_backend_config().")
+    stop("`backend` must be a configuration object from backend_config().")
   }
   data <- list(
     provider = backend$provider,
diff --git a/R/embed_backend_hf.R b/R/backend_hf.R
similarity index 100%
rename from R/embed_backend_hf.R
rename to R/backend_hf.R
diff --git a/R/embed_backend_openai.R b/R/backend_openai.R
similarity index 100%
rename from R/embed_backend_openai.R
rename to R/backend_openai.R
diff --git a/R/embed_backend_tei.R b/R/backend_tei.R
similarity index 100%
rename from R/embed_backend_tei.R
rename to R/backend_tei.R
diff --git a/R/embed_corpus_collect_openai_batch.R b/R/batch_collect_openai.R
similarity index 95%
rename from R/embed_corpus_collect_openai_batch.R
rename to R/batch_collect_openai.R
index 19bda93..28fbea0 100644
--- a/R/embed_corpus_collect_openai_batch.R
+++ b/R/batch_collect_openai.R
@@ -1,16 +1,16 @@
 #' Collect completed OpenAI batch embedding jobs
 #'
 #' @param project_dir Project root directory.
-#' @param backend Backend configuration from [embedding_backend_config()]. Must
+#' @param backend Backend configuration from [backend_config()]. Must
 #'   use `provider = "openai"`.
 #' @param label Embedding label partition to collect into.
 #' @param verbose Logical; print progress messages.
 #'
 #' @return Invisibly returns a list with collection summary.
 #' @export
-embed_corpus_collect_openai_batch <- function(
+batch_collect_openai <- function(
   project_dir,
-  backend = embedding_backend_config(provider = "openai"),
+  backend = backend_config(provider = "openai"),
   label = "corpus",
   verbose = TRUE
 ) {
diff --git a/R/embed_corpus_openai_batch_helpers.R b/R/batch_openai_helpers.R
similarity index 100%
rename from R/embed_corpus_openai_batch_helpers.R
rename to R/batch_openai_helpers.R
diff --git a/R/embed_openai_batch_helper.R b/R/batch_openai_http.R
similarity index 100%
rename from R/embed_openai_batch_helper.R
rename to R/batch_openai_http.R
diff --git a/R/embed_corpus_status_openai_batch.R b/R/batch_status_openai.R
similarity index 91%
rename from R/embed_corpus_status_openai_batch.R
rename to R/batch_status_openai.R
index 36db5f8..67f22c4 100644
--- a/R/embed_corpus_status_openai_batch.R
+++ b/R/batch_status_openai.R
@@ -7,7 +7,7 @@
 #'
 #' @return A data frame with one row per tracked job.
 #' @export
-embed_corpus_status_openai_batch <- function(
+batch_status_openai <- function(
   project_dir,
   label = "corpus",
   refresh_remote = TRUE
@@ -26,7 +26,7 @@ embed_corpus_status_openai_batch <- function(
   state <- .ovc_openai_state_read(state_file)
 
   if (isTRUE(refresh_remote) && length(state$jobs)) {
-    backend <- embedding_backend_config(
+    backend <- backend_config(
       provider = "openai",
       base_url = .ovc_or(state$backend$base_url, NULL),
       model = .ovc_or(state$model_id, NULL),
@@ -50,7 +50,7 @@ embed_corpus_status_openai_batch <- function(
 #' Collect completed OpenAI batch embedding jobs
 #'
 #' @param project_dir Project root directory.
-#' @param backend Backend configuration from [embedding_backend_config()]. Must
+#' @param backend Backend configuration from [backend_config()]. Must
 #'   use `provider = "openai"`.
 #' @param label Embedding label partition to collect into.
 #' @param verbose Logical; print progress messages.
diff --git a/R/embed_corpus_submit_openai_batch.R b/R/batch_submit_openai.R
similarity index 96%
rename from R/embed_corpus_submit_openai_batch.R
rename to R/batch_submit_openai.R
index 848914c..1bc51ce 100644
--- a/R/embed_corpus_submit_openai_batch.R
+++ b/R/batch_submit_openai.R
@@ -4,7 +4,7 @@
 #' into compliant OpenAI batch jobs, submits them, and returns immediately.
 #'
 #' @param project_dir Project root directory.
-#' @param backend Backend configuration from [embedding_backend_config()]. Must
+#' @param backend Backend configuration from [backend_config()]. Must
 #'   use `provider = "openai"`.
 #' @param corpus_name Folder name under `project_dir` containing the corpus
 #'   dataset. Defaults to `"corpus"`.
@@ -27,9 +27,9 @@
 #'
 #' @return Invisibly returns a list with state path and submission summary.
 #' @export
-embed_corpus_submit_openai_batch <- function(
+batch_submit_openai <- function(
   project_dir,
-  backend = embedding_backend_config(provider = "openai"),
+  backend = backend_config(provider = "openai"),
   corpus_name = "corpus",
   label = corpus_name,
   batch_size = 5000,
@@ -62,7 +62,7 @@ embed_corpus_submit_openai_batch <- function(
   max_requests_per_job <- as.integer(max_requests_per_job)
   max_job_bytes <- as.numeric(max_job_bytes)
 
-  info <- embedding_backend_info(backend)
+  info <- backend_info(backend)
   model_id <- .ovc_or(info$model_id, backend$model)
   model_part <- gsub("/", "_", model_id, fixed = TRUE)
   label_part <- gsub("/", "_", label, fixed = TRUE)
@@ -92,7 +92,7 @@ embed_corpus_submit_openai_batch <- function(
   backend_meta$model <- model_id
   backend_meta$max_batch_size <- .ovc_or(info$max_batch_size, backend$max_batch_size)
   meta_path <- file.path(model_dir, "embed_model.yaml")
-  embedding_backend_save(backend = backend_meta, fn = meta_path)
+  backend_save(backend = backend_meta, fn = meta_path)
   meta <- yaml::read_yaml(meta_path)
   meta$embedding_label <- label
   meta$submission_mode <- "openai_batch"
diff --git a/R/run_demos.R b/R/demo_run.R
similarity index 94%
rename from R/run_demos.R
rename to R/demo_run.R
index 05c9b6a..606d8bc 100644
--- a/R/run_demos.R
+++ b/R/demo_run.R
@@ -13,7 +13,7 @@
 #'   `file.path(getwd(), "demos", "openalex")`.
 #' @param render Logical; if `TRUE` (default), run `quarto render` on the
 #'   copied template.
-#' @param backend Optional backend config from [embedding_backend_config()]. If
+#' @param backend Optional backend config from [backend_config()]. If
 #'   `NULL`, defaults to Hugging Face (`provider = "hf"`,
 #'   model `"BAAI/bge-small-en-v1.5"`).
 #' @param max_corpus Maximum number of corpus fixture rows to copy.
@@ -25,7 +25,7 @@
 #'
 #' @return Invisibly returns a list with project paths and render status.
 #' @export
-run_demo_openalex_quarto <- function(
+run_demo_openalex <- function(
   demo_dir = file.path(getwd(), "demos", "openalex"),
   render = TRUE,
   backend = NULL,
@@ -80,14 +80,14 @@ run_demo_openalex_quarto <- function(
   project_dir <- file.path(demo_dir, "project")
 
   if (is.null(backend)) {
-    backend <- embedding_backend_config(
+    backend <- backend_config(
       provider = "hf",
       model = "BAAI/bge-small-en-v1.5"
     )
   }
   if (!is.list(backend) || is.null(backend$provider)) {
     stop(
-      "`backend` must be NULL or a backend config from `embedding_backend_config()`."
+      "`backend` must be NULL or a backend config from `backend_config()`."
     )
   }
 
@@ -138,7 +138,7 @@ run_demo_openalex_quarto <- function(
     stop("Failed to copy Quarto template to `", qmd_path, "`.")
   }
 
-  embedding_backend_save(backend = backend, fn = backend_yaml)
+  backend_save(backend = backend, fn = backend_yaml)
 
   if (verbose) {
     message("Demo workspace prepared at ", demo_dir)
@@ -182,7 +182,7 @@ run_demo_openalex_quarto <- function(
 
 #' Create and optionally run an OpenAI-based demo project via Quarto
 #'
-#' Uses the same demo structure as [run_demo_openalex_quarto()], but configures
+#' Uses the same demo structure as [run_demo_openalex()], but configures
 #' an OpenAI backend and requires an explicit API key argument. The key is set
 #' in `OVC_API_TOKEN` for the duration of the call.
 #'
@@ -202,7 +202,7 @@ run_demo_openalex_quarto <- function(
 #'
 #' @return Invisibly returns a list with project paths and render status.
 #' @export
-run_demo_openai_quarto <- function(
+run_demo_openai <- function(
   api_key,
   demo_dir = file.path(getwd(), "demos", "openai"),
   render = TRUE,
@@ -231,12 +231,12 @@ run_demo_openai_quarto <- function(
   )
   Sys.setenv(OVC_API_TOKEN = trimws(api_key))
 
-  backend <- embedding_backend_config(
+  backend <- backend_config(
     provider = "openai",
     model = trimws(model)
   )
 
-  out <- run_demo_openalex_quarto(
+  out <- run_demo_openalex(
     demo_dir = demo_dir,
     render = render,
     backend = backend,
@@ -248,14 +248,14 @@ run_demo_openai_quarto <- function(
   )
 
   status_cmd <- paste0(
-    "openalexVectorComp::embed_corpus_status_openai_batch(\n",
+    "openalexVectorComp::batch_status_openai(\n",
     "  project_dir = \"", out$project_dir, "\",\n",
     "  label = \"corpus_batch\",\n",
     "  refresh_remote = TRUE\n",
     ")"
   )
   finalize_cmd <- paste0(
-    "openalexVectorComp::finalize_demo_openai_batch(\n",
+    "openalexVectorComp::demo_finalize_openai_batch(\n",
     "  demo_dir = \"", out$demo_dir, "\",\n",
     "  api_key = keyring::key_get(\"API_openai_ipbes\"),\n",
     "  label = \"corpus_batch\"\n",
@@ -281,18 +281,18 @@ run_demo_openai_quarto <- function(
 #' `project/openai_batch_comparison/label=<label>/`.
 #'
 #' @param demo_dir Demo workspace directory created by
-#'   [run_demo_openai_quarto()] or [run_demo_openalex_quarto()].
+#'   [run_demo_openai()] or [run_demo_openalex()].
 #' @param api_key Optional OpenAI API key. If provided, it is set in
 #'   `OVC_API_TOKEN` for the duration of this call.
 #' @param label Batch embedding label to finalize. Defaults to `"corpus_batch"`.
 #' @param refresh_remote Logical; forwarded to
-#'   [embed_corpus_status_openai_batch()].
+#'   [batch_status_openai()].
 #' @param verbose Logical; print progress messages.
 #'
 #' @return Invisibly returns a list containing status/collect summaries,
 #'   comparison readiness, and output paths.
 #' @export
-finalize_demo_openai_batch <- function(
+demo_finalize_openai_batch <- function(
   demo_dir,
   api_key = NULL,
   label = "corpus_batch",
@@ -339,7 +339,7 @@ finalize_demo_openai_batch <- function(
     stop("Missing demo project directory: ", project_dir)
   }
 
-  backend <- embedding_backend_read(backend_yaml)
+  backend <- backend_read(backend_yaml)
   provider <- tolower(as.character(if (is.null(backend$provider)) "" else backend$provider))
   if (!identical(provider, "openai")) {
     stop("`demo_backend.yaml` must configure provider = 'openai'.")
@@ -356,7 +356,7 @@ finalize_demo_openai_batch <- function(
   }
   model_id_dir <- if (length(model_dirs) == 1L) model_dirs[[1]] else ""
 
-  status_df <- embed_corpus_status_openai_batch(
+  status_df <- batch_status_openai(
     project_dir = project_dir,
     label = label,
     refresh_remote = refresh_remote
@@ -372,7 +372,7 @@ finalize_demo_openai_batch <- function(
     failed_jobs = 0L
   )
   if (file.exists(state_file)) {
-    collect_info <- embed_corpus_collect_openai_batch(
+    collect_info <- batch_collect_openai(
       project_dir = project_dir,
       backend = backend,
       label = label,
diff --git a/R/distance_ridge.R b/R/distance_ridge.R
index 8527d63..96dad0e 100644
--- a/R/distance_ridge.R
+++ b/R/distance_ridge.R
@@ -90,7 +90,7 @@ distance_ridge <- function(
       meta_path <- file.path(model_dir_emb, legacy_meta_name)
     }
     if (file.exists(meta_path)) {
-      meta <- try(embedding_backend_read(meta_path), silent = TRUE)
+      meta <- try(backend_read(meta_path), silent = TRUE)
       if (!inherits(meta, "try-error")) {
         mid <- meta$model %||% NULL
         if (!is.null(mid) && nzchar(mid)) {
diff --git a/R/embed_corpus.R b/R/embed_corpus.R
index d017c5a..ab143d6 100644
--- a/R/embed_corpus.R
+++ b/R/embed_corpus.R
@@ -7,7 +7,7 @@
 #' @param project_dir Project root directory. Must contain
 #'   `project_dir/<corpus_name>` with columns `id`, `title`, `abstract`.
 #' @param backend Backend configuration created with
-#'   [embedding_backend_config()].
+#'   [backend_config()].
 #' @param corpus_name Folder name under `project_dir` containing the corpus
 #'   parquet dataset. Defaults to `"corpus"`.
 #' @param batch_size Number of corpus rows per Arrow scan batch.
@@ -36,7 +36,7 @@
 #' @export
 embed_corpus <- function(
   project_dir = NULL,
-  backend = embedding_backend_config(),
+  backend = backend_config(),
   corpus_name = "corpus",
   batch_size = 5000,
   delete_existing = FALSE,
@@ -56,7 +56,7 @@ embed_corpus <- function(
     stop("`batch_size` must be a positive number.")
   }
   if (!is.list(backend) || is.null(backend$provider)) {
-    stop("`backend` must come from embedding_backend_config().")
+    stop("`backend` must come from backend_config().")
   }
   if (!is.character(corpus_name) || length(corpus_name) != 1 || !nzchar(trimws(corpus_name))) {
     stop("`corpus_name` must be a non-empty character string.")
@@ -94,7 +94,7 @@ embed_corpus <- function(
     dir.create(emb_root, recursive = TRUE)
   }
 
-  info <- embedding_backend_info(backend)
+  info <- backend_info(backend)
   model_id <- info$model_id %||% backend$model
   if (is.null(model_id) || !nzchar(model_id)) {
     stop("Could not determine model id from backend info.")
@@ -121,7 +121,7 @@ embed_corpus <- function(
     backend_meta <- backend
     backend_meta$model <- model_id
     backend_meta$max_batch_size <- info$max_batch_size %||% backend$max_batch_size
-    embedding_backend_save(backend = backend_meta, fn = meta_path)
+    backend_save(backend = backend_meta, fn = meta_path)
 
     preproc_name <- if (identical(text_preprocessor, clean_abstract_for_embedding)) {
       "clean_abstract_for_embedding"
diff --git a/R/embed_texts.R b/R/embed_texts.R
index ff8a559..8351e37 100644
--- a/R/embed_texts.R
+++ b/R/embed_texts.R
@@ -6,16 +6,16 @@
 #' @param texts Character vector of texts to embed. Empty inputs return a
 #'   0-row matrix; missing values are not supported.
 #' @param backend Backend configuration created with
-#'   [embedding_backend_config()].
+#'   [backend_config()].
 #'
 #' @return A numeric matrix with one row per input text and one column per
 #'   embedding dimension.
 #' @export
 embed_texts <- function(
   texts,
-  backend = embedding_backend_config()
+  backend = backend_config()
 ) {
-  embedding_backend_embed_texts(
+  backend_embed_texts(
     texts = texts,
     backend = backend
   )
diff --git a/README.md b/README.md
index 058394d..f281c4b 100644
--- a/README.md
+++ b/README.md
@@ -4,7 +4,7 @@
 
 ## Version
 
-Current development version: **0.2.0**.
+Current development version: **0.3.0**.
 
 - Embeddings served by **TEI** (Text Embeddings Inference; Hugging Face).
 - Embeddings via a **backend-neutral interface** (`hf`, `openai`, `tei`).
@@ -12,7 +12,7 @@ Current development version: **0.2.0**.
   (`distance_ridge()` + `score_ridge()`) + threshold calibration.
 - Works great with DuckDB/Arrow pipelines.
 
-## 0.2.0 Highlights
+## 0.3.0 Highlights
 
 - Demo defaults now use a shared structure:
   - `demos/openalex`
@@ -61,7 +61,7 @@ Start with `vignettes/simplestart.qmd`, then see:
 Create a full demo in `getwd()/demos/openalex` (fixtures + Quarto analysis):
 
 ```r
-run_demo_openalex_quarto(
+run_demo_openalex(
   demo_dir = file.path(getwd(), "demos", "openalex"),
   render = FALSE
 )
@@ -75,7 +75,7 @@ artifacts are written under `demo_dir/project/`.
 OpenAI-specific demo (same structure, explicit API key argument):
 
 ```r
-run_demo_openai_quarto(
+run_demo_openai(
   api_key = Sys.getenv("OVC_API_TOKEN"),
   demo_dir = file.path(getwd(), "demos", "openai"),
   render = FALSE
@@ -83,11 +83,11 @@ run_demo_openai_quarto(
 ```
 
 The OpenAI demo now follows a two-phase async flow:
-1. `run_demo_openai_quarto(..., render = TRUE)` submits batch and continues.
+1. `run_demo_openai(..., render = TRUE)` submits batch and continues.
 2. If batch is still pending, finalize later:
 
 ```r
-finalize_demo_openai_batch(
+demo_finalize_openai_batch(
   demo_dir = file.path(getwd(), "demos", "openai"),
   api_key = Sys.getenv("OVC_API_TOKEN"),
   label = "corpus_batch"
@@ -102,26 +102,26 @@ This writes comparison outputs to:
 For long-running OpenAI embedding jobs, use the async batch helpers:
 
 ```r
-backend <- embedding_backend_config(
+backend <- backend_config(
   provider = "openai",
   model = "text-embedding-3-small"
 )
 
 # 1) submit and return immediately
-embed_corpus_submit_openai_batch(
+batch_submit_openai(
   project_dir = "my_project",
   backend = backend,
   label = "corpus"
 )
 
 # 2) check job status
-embed_corpus_status_openai_batch(
+batch_status_openai(
   project_dir = "my_project",
   label = "corpus"
 )
 
 # 3) collect completed jobs and write canonical embeddings parquet
-embed_corpus_collect_openai_batch(
+batch_collect_openai(
   project_dir = "my_project",
   backend = backend,
   label = "corpus"
diff --git a/inst/ovc_demo/openai_demo_analysis.qmd b/inst/ovc_demo/openai_demo_analysis.qmd
index 0dd8c8a..4e80171 100644
--- a/inst/ovc_demo/openai_demo_analysis.qmd
+++ b/inst/ovc_demo/openai_demo_analysis.qmd
@@ -99,7 +99,7 @@ been called yet.
 ```{r setup-environment}
 library(openalexVectorComp)
 
-backend <- embedding_backend_read(file.path(".", "demo_backend.yaml"))
+backend <- backend_read(file.path(".", "demo_backend.yaml"))
 provider <- tolower(as.character(if (is.null(backend$provider)) "" else backend$provider))
 stopifnot(identical(provider, "openai"))
 
@@ -118,7 +118,7 @@ In your own projects, this table is the first thing to check when outputs look
 unexpected.
 
 ```{r model-configuration-info}
-info <- embedding_backend_info(backend)
+info <- backend_info(backend)
 
 data.frame(
   field = c("provider", "model", "model_id", "base_url"),
@@ -256,16 +256,16 @@ must tolerate "not ready yet" states.
 
 The async workflow has three separate responsibilities:
 
-- `embed_corpus_submit_openai_batch()`: creates batch request files, uploads
+- `batch_submit_openai()`: creates batch request files, uploads
   them, and returns quickly with tracked job ids.
-- `embed_corpus_status_openai_batch()`: refreshes and reports remote job
+- `batch_status_openai()`: refreshes and reports remote job
   states (`in_progress`, `completed`, `failed`, ...), but does not write
   embeddings.
-- `embed_corpus_collect_openai_batch()`: downloads completed batch outputs and
+- `batch_collect_openai()`: downloads completed batch outputs and
   writes canonical embedding parquet files under
   `project/embeddings/model_id=.../label=corpus_batch/...`.
 
-`finalize_demo_openai_batch()` wraps the status + collect + comparison steps
+`demo_finalize_openai_batch()` wraps the status + collect + comparison steps
 for convenience. If jobs are still pending, it returns a non-error
 `comparison_ready = FALSE`.
 
@@ -278,13 +278,13 @@ Interpretation guide:
 ::: {.callout-tip}
 Use these commands after render to check and finalize batch jobs:
 ```r
-openalexVectorComp::embed_corpus_status_openai_batch(
+openalexVectorComp::batch_status_openai(
   project_dir = "./project",
   label = "corpus_batch",
   refresh_remote = TRUE
 )
 
-openalexVectorComp::finalize_demo_openai_batch(
+openalexVectorComp::demo_finalize_openai_batch(
   demo_dir = ".",
   api_key = keyring::key_get("API_openai_ipbes"),
   label = "corpus_batch"
@@ -295,7 +295,7 @@ openalexVectorComp::finalize_demo_openai_batch(
 ```{r openai-batch-compare}
 batch_label <- "corpus_batch"
 
-submit_info <- embed_corpus_submit_openai_batch(
+submit_info <- batch_submit_openai(
   project_dir = project_dir,
   backend = backend,
   corpus_name = "corpus",
@@ -311,13 +311,13 @@ status_df <- data.frame()
 collect_info <- NULL
 
 for (i in seq_len(max_polls)) {
-  status_df <- embed_corpus_status_openai_batch(
+  status_df <- batch_status_openai(
     project_dir = project_dir,
     label = batch_label,
     refresh_remote = TRUE
   )
 
-  collect_info <- embed_corpus_collect_openai_batch(
+  collect_info <- batch_collect_openai(
     project_dir = project_dir,
     backend = backend,
     label = batch_label,
@@ -337,7 +337,7 @@ for (i in seq_len(max_polls)) {
 status_df
 collect_info
 
-finalize_out <- finalize_demo_openai_batch(
+finalize_out <- demo_finalize_openai_batch(
   demo_dir = ".",
   label = batch_label,
   refresh_remote = TRUE,
@@ -347,7 +347,7 @@ finalize_out <- finalize_demo_openai_batch(
 if (!isTRUE(finalize_out$comparison_ready)) {
   message(finalize_out$message)
   message(
-    "Run later: openalexVectorComp::finalize_demo_openai_batch(",
+    "Run later: openalexVectorComp::demo_finalize_openai_batch(",
     "\"", normalizePath(getwd(), mustWork = FALSE), "\"",
     ", api_key = keyring::key_get(\"API_openai_ipbes\"))"
   )
diff --git a/inst/ovc_demo/openalex_demo_analysis.qmd b/inst/ovc_demo/openalex_demo_analysis.qmd
index 9445b1a..a6926c5 100644
--- a/inst/ovc_demo/openalex_demo_analysis.qmd
+++ b/inst/ovc_demo/openalex_demo_analysis.qmd
@@ -86,7 +86,7 @@ when setup is incomplete.
 ```{r setup-environment}
 library(openalexVectorComp)
 
-backend <- embedding_backend_read(file.path(".", "demo_backend.yaml"))
+backend <- backend_read(file.path(".", "demo_backend.yaml"))
 
 project_dir <- file.path(".", "project")
 corpus_dir <- file.path(project_dir, "corpus")
@@ -101,7 +101,7 @@ stopifnot(dir.exists(reference_dir))
 This table is your first checkpoint when results look unexpected.
 
 ```{r model-configuration-info}
-info <- embedding_backend_info(backend)
+info <- backend_info(backend)
 
 data.frame(
   field = c("provider", "model", "model_id", "base_url"),
@@ -245,24 +245,24 @@ command for later.
 
 The batch helpers have different roles:
 
-- `embed_corpus_submit_openai_batch()`: enqueue jobs and return quickly.
-- `embed_corpus_status_openai_batch()`: refresh/report remote job states.
-- `embed_corpus_collect_openai_batch()`: download completed outputs and write
+- `batch_submit_openai()`: enqueue jobs and return quickly.
+- `batch_status_openai()`: refresh/report remote job states.
+- `batch_collect_openai()`: download completed outputs and write
   local batch embedding parquet files.
 
-`finalize_demo_openai_batch()` combines status + collect + compare and returns
+`demo_finalize_openai_batch()` combines status + collect + compare and returns
 `comparison_ready = FALSE` instead of error when not ready yet.
 
 ::: {.callout-tip}
 After render, check and finalize OpenAI batch jobs with:
 ```r
-openalexVectorComp::embed_corpus_status_openai_batch(
+openalexVectorComp::batch_status_openai(
   project_dir = "./project",
   label = "corpus_batch",
   refresh_remote = TRUE
 )
 
-openalexVectorComp::finalize_demo_openai_batch(
+openalexVectorComp::demo_finalize_openai_batch(
   demo_dir = ".",
   api_key = keyring::key_get("API_openai_ipbes"),
   label = "corpus_batch"
@@ -278,7 +278,7 @@ if (!identical(provider_name, "openai")) {
 } else {
   batch_label <- "corpus_batch"
 
-  submit_info <- embed_corpus_submit_openai_batch(
+  submit_info <- batch_submit_openai(
     project_dir = project_dir,
     backend = backend,
     corpus_name = "corpus",
@@ -294,13 +294,13 @@ if (!identical(provider_name, "openai")) {
   collect_info <- NULL
 
   for (i in seq_len(max_polls)) {
-    status_df <- embed_corpus_status_openai_batch(
+    status_df <- batch_status_openai(
       project_dir = project_dir,
       label = batch_label,
       refresh_remote = TRUE
     )
 
-    collect_info <- embed_corpus_collect_openai_batch(
+    collect_info <- batch_collect_openai(
       project_dir = project_dir,
       backend = backend,
       label = batch_label,
@@ -320,7 +320,7 @@ if (!identical(provider_name, "openai")) {
   status_df
   collect_info
 
-  finalize_out <- finalize_demo_openai_batch(
+  finalize_out <- demo_finalize_openai_batch(
     demo_dir = ".",
     label = batch_label,
     refresh_remote = TRUE,
@@ -330,7 +330,7 @@ if (!identical(provider_name, "openai")) {
   if (!isTRUE(finalize_out$comparison_ready)) {
     message(finalize_out$message)
     message(
-      "Run later: openalexVectorComp::finalize_demo_openai_batch(\"",
+      "Run later: openalexVectorComp::demo_finalize_openai_batch(\"",
       normalizePath(getwd(), mustWork = FALSE),
       "\", api_key = keyring::key_get(\"API_openai_ipbes\"))"
     )
diff --git a/man/embedding_backend_config.Rd b/man/backend_config.Rd
similarity index 87%
rename from man/embedding_backend_config.Rd
rename to man/backend_config.Rd
index 1178f0c..4ec0625 100644
--- a/man/embedding_backend_config.Rd
+++ b/man/backend_config.Rd
@@ -1,10 +1,10 @@
 % Generated by roxygen2: do not edit by hand
-% Please edit documentation in R/embed_backend_core.R
-\name{embedding_backend_config}
-\alias{embedding_backend_config}
+% Please edit documentation in R/backend_core.R
+\name{backend_config}
+\alias{backend_config}
 \title{Build embedding backend configuration}
 \usage{
-embedding_backend_config(
+backend_config(
   provider = c("hf", "openai", "tei"),
   base_url = NULL,
   model = NULL,
diff --git a/man/embedding_backend_embed_texts.Rd b/man/backend_embed_texts.Rd
similarity index 58%
rename from man/embedding_backend_embed_texts.Rd
rename to man/backend_embed_texts.Rd
index eaf8b8e..7a43cd8 100644
--- a/man/embedding_backend_embed_texts.Rd
+++ b/man/backend_embed_texts.Rd
@@ -1,15 +1,15 @@
 % Generated by roxygen2: do not edit by hand
-% Please edit documentation in R/embed_backend_core.R
-\name{embedding_backend_embed_texts}
-\alias{embedding_backend_embed_texts}
+% Please edit documentation in R/backend_core.R
+\name{backend_embed_texts}
+\alias{backend_embed_texts}
 \title{Embed texts via configured backend}
 \usage{
-embedding_backend_embed_texts(texts, backend = embedding_backend_config())
+backend_embed_texts(texts, backend = backend_config())
 }
 \arguments{
 \item{texts}{Character vector of input texts.}
 
-\item{backend}{Backend configuration from \code{\link[=embedding_backend_config]{embedding_backend_config()}}.}
+\item{backend}{Backend configuration from \code{\link[=backend_config]{backend_config()}}.}
 }
 \value{
 Numeric matrix with one row per text and columns \code{V1..Vd}.
diff --git a/man/embedding_backend_info.Rd b/man/backend_info.Rd
similarity index 52%
rename from man/embedding_backend_info.Rd
rename to man/backend_info.Rd
index 75dfbd3..4743aec 100644
--- a/man/embedding_backend_info.Rd
+++ b/man/backend_info.Rd
@@ -1,13 +1,13 @@
 % Generated by roxygen2: do not edit by hand
-% Please edit documentation in R/embed_backend_core.R
-\name{embedding_backend_info}
-\alias{embedding_backend_info}
+% Please edit documentation in R/backend_core.R
+\name{backend_info}
+\alias{backend_info}
 \title{Get embedding backend model/service information}
 \usage{
-embedding_backend_info(backend = embedding_backend_config())
+backend_info(backend = backend_config())
 }
 \arguments{
-\item{backend}{Backend configuration from \code{\link[=embedding_backend_config]{embedding_backend_config()}}.}
+\item{backend}{Backend configuration from \code{\link[=backend_config]{backend_config()}}.}
 }
 \value{
 A list with fields \code{provider}, \code{model_id}, \code{dim}, \code{max_batch_size},
diff --git a/man/embedding_backend_read.Rd b/man/backend_read.Rd
similarity index 56%
rename from man/embedding_backend_read.Rd
rename to man/backend_read.Rd
index ded79bc..30e2a50 100644
--- a/man/embedding_backend_read.Rd
+++ b/man/backend_read.Rd
@@ -1,21 +1,21 @@
 % Generated by roxygen2: do not edit by hand
-% Please edit documentation in R/embed_backend_core.R
-\name{embedding_backend_read}
-\alias{embedding_backend_read}
+% Please edit documentation in R/backend_core.R
+\name{backend_read}
+\alias{backend_read}
 \title{Read backend configuration from YAML}
 \usage{
-embedding_backend_read(fn = "embed_model.yaml")
+backend_read(fn = "embed_model.yaml")
 }
 \arguments{
 \item{fn}{Path to YAML file. Defaults to \code{"embed_model.yaml"}.}
 }
 \value{
 A backend configuration list compatible with
-\code{\link[=embedding_backend_config]{embedding_backend_config()}}.
+\code{\link[=backend_config]{backend_config()}}.
 }
 \description{
 Reads backend configuration from a YAML file and returns a normalized object
-in the same format as \code{\link[=embedding_backend_config]{embedding_backend_config()}}.
+in the same format as \code{\link[=backend_config]{backend_config()}}.
 }
 \details{
 Supports both the current flat format and legacy nested metadata format.
diff --git a/man/backend_save.Rd b/man/backend_save.Rd
new file mode 100644
index 0000000..adcce26
--- /dev/null
+++ b/man/backend_save.Rd
@@ -0,0 +1,20 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/backend_core.R
+\name{backend_save}
+\alias{backend_save}
+\title{Save backend configuration to YAML}
+\usage{
+backend_save(backend = backend_config(), fn = "embed_model.yaml")
+}
+\arguments{
+\item{backend}{Backend configuration from \code{\link[=backend_config]{backend_config()}}.}
+
+\item{fn}{Output YAML file path. Defaults to \code{"embed_model.yaml"}.}
+}
+\value{
+Invisibly returns \code{fn}.
+}
+\description{
+Writes a backend configuration (same shape as returned by
+\code{\link[=backend_config]{backend_config()}}) to YAML.
+}
diff --git a/man/embed_corpus_collect_openai_batch.Rd b/man/batch_collect_openai.Rd
similarity index 57%
rename from man/embed_corpus_collect_openai_batch.Rd
rename to man/batch_collect_openai.Rd
index 5c45e64..883426e 100644
--- a/man/embed_corpus_collect_openai_batch.Rd
+++ b/man/batch_collect_openai.Rd
@@ -1,12 +1,12 @@
 % Generated by roxygen2: do not edit by hand
-% Please edit documentation in R/embed_corpus_collect_openai_batch.R
-\name{embed_corpus_collect_openai_batch}
-\alias{embed_corpus_collect_openai_batch}
+% Please edit documentation in R/batch_collect_openai.R
+\name{batch_collect_openai}
+\alias{batch_collect_openai}
 \title{Collect completed OpenAI batch embedding jobs}
 \usage{
-embed_corpus_collect_openai_batch(
+batch_collect_openai(
   project_dir,
-  backend = embedding_backend_config(provider = "openai"),
+  backend = backend_config(provider = "openai"),
   label = "corpus",
   verbose = TRUE
 )
@@ -14,7 +14,7 @@ embed_corpus_collect_openai_batch(
 \arguments{
 \item{project_dir}{Project root directory.}
 
-\item{backend}{Backend configuration from \code{\link[=embedding_backend_config]{embedding_backend_config()}}. Must
+\item{backend}{Backend configuration from \code{\link[=backend_config]{backend_config()}}. Must
 use \code{provider = "openai"}.}
 
 \item{label}{Embedding label partition to collect into.}
diff --git a/man/embed_corpus_status_openai_batch.Rd b/man/batch_status_openai.Rd
similarity index 62%
rename from man/embed_corpus_status_openai_batch.Rd
rename to man/batch_status_openai.Rd
index 3a53b28..9b98505 100644
--- a/man/embed_corpus_status_openai_batch.Rd
+++ b/man/batch_status_openai.Rd
@@ -1,14 +1,10 @@
 % Generated by roxygen2: do not edit by hand
-% Please edit documentation in R/embed_corpus_status_openai_batch.R
-\name{embed_corpus_status_openai_batch}
-\alias{embed_corpus_status_openai_batch}
+% Please edit documentation in R/batch_status_openai.R
+\name{batch_status_openai}
+\alias{batch_status_openai}
 \title{Inspect OpenAI batch state for a label}
 \usage{
-embed_corpus_status_openai_batch(
-  project_dir,
-  label = "corpus",
-  refresh_remote = TRUE
-)
+batch_status_openai(project_dir, label = "corpus", refresh_remote = TRUE)
 }
 \arguments{
 \item{project_dir}{Project root directory.}
diff --git a/man/embed_corpus_submit_openai_batch.Rd b/man/batch_submit_openai.Rd
similarity index 83%
rename from man/embed_corpus_submit_openai_batch.Rd
rename to man/batch_submit_openai.Rd
index b78ac6d..5f8cc9e 100644
--- a/man/embed_corpus_submit_openai_batch.Rd
+++ b/man/batch_submit_openai.Rd
@@ -1,12 +1,12 @@
 % Generated by roxygen2: do not edit by hand
-% Please edit documentation in R/embed_corpus_submit_openai_batch.R
-\name{embed_corpus_submit_openai_batch}
-\alias{embed_corpus_submit_openai_batch}
+% Please edit documentation in R/batch_submit_openai.R
+\name{batch_submit_openai}
+\alias{batch_submit_openai}
 \title{Submit OpenAI Batch jobs for corpus embeddings (asynchronous)}
 \usage{
-embed_corpus_submit_openai_batch(
+batch_submit_openai(
   project_dir,
-  backend = embedding_backend_config(provider = "openai"),
+  backend = backend_config(provider = "openai"),
   corpus_name = "corpus",
   label = corpus_name,
   batch_size = 5000,
@@ -23,7 +23,7 @@ embed_corpus_submit_openai_batch(
 \arguments{
 \item{project_dir}{Project root directory.}
 
-\item{backend}{Backend configuration from \code{\link[=embedding_backend_config]{embedding_backend_config()}}. Must
+\item{backend}{Backend configuration from \code{\link[=backend_config]{backend_config()}}. Must
 use \code{provider = "openai"}.}
 
 \item{corpus_name}{Folder name under \code{project_dir} containing the corpus
diff --git a/man/finalize_demo_openai_batch.Rd b/man/demo_finalize_openai_batch.Rd
similarity index 72%
rename from man/finalize_demo_openai_batch.Rd
rename to man/demo_finalize_openai_batch.Rd
index ddc008b..39231b6 100644
--- a/man/finalize_demo_openai_batch.Rd
+++ b/man/demo_finalize_openai_batch.Rd
@@ -1,10 +1,10 @@
 % Generated by roxygen2: do not edit by hand
-% Please edit documentation in R/run_demos.R
-\name{finalize_demo_openai_batch}
-\alias{finalize_demo_openai_batch}
+% Please edit documentation in R/demo_run.R
+\name{demo_finalize_openai_batch}
+\alias{demo_finalize_openai_batch}
 \title{Finalize OpenAI demo batch jobs and compare direct vs batch embeddings}
 \usage{
-finalize_demo_openai_batch(
+demo_finalize_openai_batch(
   demo_dir,
   api_key = NULL,
   label = "corpus_batch",
@@ -14,7 +14,7 @@ finalize_demo_openai_batch(
 }
 \arguments{
 \item{demo_dir}{Demo workspace directory created by
-\code{\link[=run_demo_openai_quarto]{run_demo_openai_quarto()}} or \code{\link[=run_demo_openalex_quarto]{run_demo_openalex_quarto()}}.}
+\code{\link[=run_demo_openai]{run_demo_openai()}} or \code{\link[=run_demo_openalex]{run_demo_openalex()}}.}
 
 \item{api_key}{Optional OpenAI API key. If provided, it is set in
 \code{OVC_API_TOKEN} for the duration of this call.}
@@ -22,7 +22,7 @@ finalize_demo_openai_batch(
 \item{label}{Batch embedding label to finalize. Defaults to \code{"corpus_batch"}.}
 
 \item{refresh_remote}{Logical; forwarded to
-\code{\link[=embed_corpus_status_openai_batch]{embed_corpus_status_openai_batch()}}.}
+\code{\link[=batch_status_openai]{batch_status_openai()}}.}
 
 \item{verbose}{Logical; print progress messages.}
 }
diff --git a/man/embed_corpus.Rd b/man/embed_corpus.Rd
index d3b7b7a..58bf547 100644
--- a/man/embed_corpus.Rd
+++ b/man/embed_corpus.Rd
@@ -6,7 +6,7 @@
 \usage{
 embed_corpus(
   project_dir = NULL,
-  backend = embedding_backend_config(),
+  backend = backend_config(),
   corpus_name = "corpus",
   batch_size = 5000,
   delete_existing = FALSE,
@@ -23,7 +23,7 @@ embed_corpus(
 \verb{project_dir/<corpus_name>} with columns \code{id}, \code{title}, \code{abstract}.}
 
 \item{backend}{Backend configuration created with
-\code{\link[=embedding_backend_config]{embedding_backend_config()}}.}
+\code{\link[=backend_config]{backend_config()}}.}
 
 \item{corpus_name}{Folder name under \code{project_dir} containing the corpus
 parquet dataset. Defaults to \code{"corpus"}.}
diff --git a/man/embed_texts.Rd b/man/embed_texts.Rd
index e0ea88e..ec0f1d5 100644
--- a/man/embed_texts.Rd
+++ b/man/embed_texts.Rd
@@ -4,14 +4,14 @@
 \alias{embed_texts}
 \title{Embed texts through a configured backend}
 \usage{
-embed_texts(texts, backend = embedding_backend_config())
+embed_texts(texts, backend = backend_config())
 }
 \arguments{
 \item{texts}{Character vector of texts to embed. Empty inputs return a
 0-row matrix; missing values are not supported.}
 
 \item{backend}{Backend configuration created with
-\code{\link[=embedding_backend_config]{embedding_backend_config()}}.}
+\code{\link[=backend_config]{backend_config()}}.}
 }
 \value{
 A numeric matrix with one row per input text and one column per
diff --git a/man/embedding_backend_save.Rd b/man/embedding_backend_save.Rd
deleted file mode 100644
index 4bfdeee..0000000
--- a/man/embedding_backend_save.Rd
+++ /dev/null
@@ -1,23 +0,0 @@
-% Generated by roxygen2: do not edit by hand
-% Please edit documentation in R/embed_backend_core.R
-\name{embedding_backend_save}
-\alias{embedding_backend_save}
-\title{Save backend configuration to YAML}
-\usage{
-embedding_backend_save(
-  backend = embedding_backend_config(),
-  fn = "embed_model.yaml"
-)
-}
-\arguments{
-\item{backend}{Backend configuration from \code{\link[=embedding_backend_config]{embedding_backend_config()}}.}
-
-\item{fn}{Output YAML file path. Defaults to \code{"embed_model.yaml"}.}
-}
-\value{
-Invisibly returns \code{fn}.
-}
-\description{
-Writes a backend configuration (same shape as returned by
-\code{\link[=embedding_backend_config]{embedding_backend_config()}}) to YAML.
-}
diff --git a/man/run_demo_openai_quarto.Rd b/man/run_demo_openai.Rd
similarity index 84%
rename from man/run_demo_openai_quarto.Rd
rename to man/run_demo_openai.Rd
index 51e948f..925f6a5 100644
--- a/man/run_demo_openai_quarto.Rd
+++ b/man/run_demo_openai.Rd
@@ -1,10 +1,10 @@
 % Generated by roxygen2: do not edit by hand
-% Please edit documentation in R/run_demos.R
-\name{run_demo_openai_quarto}
-\alias{run_demo_openai_quarto}
+% Please edit documentation in R/demo_run.R
+\name{run_demo_openai}
+\alias{run_demo_openai}
 \title{Create and optionally run an OpenAI-based demo project via Quarto}
 \usage{
-run_demo_openai_quarto(
+run_demo_openai(
   api_key,
   demo_dir = file.path(getwd(), "demos", "openai"),
   render = TRUE,
@@ -43,7 +43,7 @@ already exist. If \code{TRUE}, refresh demo-managed files.}
 Invisibly returns a list with project paths and render status.
 }
 \description{
-Uses the same demo structure as \code{\link[=run_demo_openalex_quarto]{run_demo_openalex_quarto()}}, but configures
+Uses the same demo structure as \code{\link[=run_demo_openalex]{run_demo_openalex()}}, but configures
 an OpenAI backend and requires an explicit API key argument. The key is set
 in \code{OVC_API_TOKEN} for the duration of the call.
 }
diff --git a/man/run_demo_openalex_quarto.Rd b/man/run_demo_openalex.Rd
similarity index 86%
rename from man/run_demo_openalex_quarto.Rd
rename to man/run_demo_openalex.Rd
index ed4ea77..ceaca9f 100644
--- a/man/run_demo_openalex_quarto.Rd
+++ b/man/run_demo_openalex.Rd
@@ -1,10 +1,10 @@
 % Generated by roxygen2: do not edit by hand
-% Please edit documentation in R/run_demos.R
-\name{run_demo_openalex_quarto}
-\alias{run_demo_openalex_quarto}
+% Please edit documentation in R/demo_run.R
+\name{run_demo_openalex}
+\alias{run_demo_openalex}
 \title{Create and optionally run a self-contained demo project via Quarto}
 \usage{
-run_demo_openalex_quarto(
+run_demo_openalex(
   demo_dir = file.path(getwd(), "demos", "openalex"),
   render = TRUE,
   backend = NULL,
@@ -22,7 +22,7 @@ run_demo_openalex_quarto(
 \item{render}{Logical; if \code{TRUE} (default), run \verb{quarto render} on the
 copied template.}
 
-\item{backend}{Optional backend config from \code{\link[=embedding_backend_config]{embedding_backend_config()}}. If
+\item{backend}{Optional backend config from \code{\link[=backend_config]{backend_config()}}. If
 \code{NULL}, defaults to Hugging Face (\code{provider = "hf"},
 model \code{"BAAI/bge-small-en-v1.5"}).}
 
diff --git a/tests/testthat/helper-hf.R b/tests/testthat/helper-hf.R
index d8500e0..fa5ad49 100644
--- a/tests/testthat/helper-hf.R
+++ b/tests/testthat/helper-hf.R
@@ -65,7 +65,7 @@ ovc_skip_if_no_hf <- function() {
 }
 
 ovc_hf_backend <- function(max_batch_size = 8L) {
-  embedding_backend_config(
+  backend_config(
     provider = "hf",
     model = "BAAI/bge-small-en-v1.5",
     max_batch_size = as.integer(max_batch_size),
diff --git a/tests/testthat/test-demo-openai-finalize.R b/tests/testthat/test-demo-openai-finalize.R
index 3ae67ca..254b41d 100644
--- a/tests/testthat/test-demo-openai-finalize.R
+++ b/tests/testthat/test-demo-openai-finalize.R
@@ -3,8 +3,8 @@ make_demo_openai_workspace <- function() {
   dir.create(td, recursive = TRUE, showWarnings = FALSE)
   proj <- file.path(td, "demo_project_openai")
   dir.create(file.path(proj, "project"), recursive = TRUE, showWarnings = FALSE)
-  openalexVectorComp::embedding_backend_save(
-    openalexVectorComp::embedding_backend_config(
+  openalexVectorComp::backend_save(
+    openalexVectorComp::backend_config(
       provider = "openai",
       model = "text-embedding-3-small"
     ),
@@ -20,10 +20,10 @@ write_demo_label_embeddings <- function(project_dir, label, df) {
   arrow::write_parquet(df, file.path(label_dir, "embeddings-00001.parquet"))
 }
 
-testthat::test_that("finalize_demo_openai_batch returns pending without state", {
+testthat::test_that("demo_finalize_openai_batch returns pending without state", {
   demo_dir <- make_demo_openai_workspace()
 
-  out <- openalexVectorComp::finalize_demo_openai_batch(
+  out <- openalexVectorComp::demo_finalize_openai_batch(
     demo_dir = demo_dir,
     label = "corpus_batch",
     refresh_remote = TRUE,
@@ -34,13 +34,13 @@ testthat::test_that("finalize_demo_openai_batch returns pending without state",
   testthat::expect_match(out$message, "No batch submission state found")
 })
 
-testthat::test_that("finalize_demo_openai_batch errors for non-openai backend yaml", {
+testthat::test_that("demo_finalize_openai_batch errors for non-openai backend yaml", {
   td <- tempfile("ovc_demo_finalize_hf_")
   dir.create(td, recursive = TRUE, showWarnings = FALSE)
   demo_dir <- file.path(td, "demo_project_hf")
   dir.create(file.path(demo_dir, "project"), recursive = TRUE, showWarnings = FALSE)
-  openalexVectorComp::embedding_backend_save(
-    openalexVectorComp::embedding_backend_config(
+  openalexVectorComp::backend_save(
+    openalexVectorComp::backend_config(
       provider = "hf",
       model = "BAAI/bge-small-en-v1.5"
     ),
@@ -48,12 +48,12 @@ testthat::test_that("finalize_demo_openai_batch errors for non-openai backend ya
   )
 
   testthat::expect_error(
-    openalexVectorComp::finalize_demo_openai_batch(demo_dir = demo_dir, verbose = FALSE),
+    openalexVectorComp::demo_finalize_openai_batch(demo_dir = demo_dir, verbose = FALSE),
     "provider = 'openai'"
   )
 })
 
-testthat::test_that("finalize_demo_openai_batch writes comparison outputs when batch embeddings are present", {
+testthat::test_that("demo_finalize_openai_batch writes comparison outputs when batch embeddings are present", {
   demo_dir <- make_demo_openai_workspace()
   project_dir <- file.path(demo_dir, "project")
 
@@ -97,16 +97,16 @@ testthat::test_that("finalize_demo_openai_batch writes comparison outputs when b
   )
 
   out <- testthat::with_mocked_bindings(
-    openalexVectorComp::finalize_demo_openai_batch(
+    openalexVectorComp::demo_finalize_openai_batch(
       demo_dir = demo_dir,
       label = "corpus_batch",
       refresh_remote = TRUE,
       verbose = FALSE
     ),
-    embed_corpus_status_openai_batch = function(project_dir, label, refresh_remote) {
+    batch_status_openai = function(project_dir, label, refresh_remote) {
       data.frame(batch_index = integer(), job_id = character(), status = character(), stringsAsFactors = FALSE)
     },
-    embed_corpus_collect_openai_batch = function(project_dir, backend, label, verbose) {
+    batch_collect_openai = function(project_dir, backend, label, verbose) {
       list(
         state_file = state_file,
         checked_jobs = 0L,
@@ -117,7 +117,7 @@ testthat::test_that("finalize_demo_openai_batch writes comparison outputs when b
         failed_jobs = 0L
       )
     },
-    embed_corpus_submit_openai_batch = function(...) {
+    batch_submit_openai = function(...) {
       stop("submit should not be called by finalize")
     },
     .package = "openalexVectorComp"
@@ -130,7 +130,7 @@ testthat::test_that("finalize_demo_openai_batch writes comparison outputs when b
   testthat::expect_equal(nrow(cmp), 2L)
 })
 
-testthat::test_that("finalize_demo_openai_batch accepts api_key argument for token-scoped call", {
+testthat::test_that("demo_finalize_openai_batch accepts api_key argument for token-scoped call", {
   demo_dir <- make_demo_openai_workspace()
 
   old <- Sys.getenv("OVC_API_TOKEN", unset = "")
@@ -141,14 +141,14 @@ testthat::test_that("finalize_demo_openai_batch accepts api_key argument for tok
   Sys.unsetenv("OVC_API_TOKEN")
 
   out <- testthat::with_mocked_bindings(
-    openalexVectorComp::finalize_demo_openai_batch(
+    openalexVectorComp::demo_finalize_openai_batch(
       demo_dir = demo_dir,
       api_key = "temp-test-key",
       label = "corpus_batch",
       refresh_remote = TRUE,
       verbose = FALSE
     ),
-    embed_corpus_status_openai_batch = function(project_dir, label, refresh_remote) {
+    batch_status_openai = function(project_dir, label, refresh_remote) {
       testthat::expect_identical(Sys.getenv("OVC_API_TOKEN"), "temp-test-key")
       data.frame()
     },
diff --git a/tests/testthat/test-demo-runner.R b/tests/testthat/test-demo-runner.R
index 2faa226..0383213 100644
--- a/tests/testthat/test-demo-runner.R
+++ b/tests/testthat/test-demo-runner.R
@@ -4,12 +4,12 @@ resolve_inst_file <- function(rel) {
   file.path("inst", rel)
 }
 
-testthat::test_that("run_demo_openalex_quarto prepares demo project with fixtures and template", {
+testthat::test_that("run_demo_openalex prepares demo project with fixtures and template", {
   td <- tempfile("ovc_demo_")
   dir.create(td, recursive = TRUE, showWarnings = FALSE)
   proj <- file.path(td, "demo_project")
 
-  out <- run_demo_openalex_quarto(
+  out <- run_demo_openalex(
     demo_dir = proj,
     render = FALSE,
     backend = ovc_hf_backend(max_batch_size = 4L),
@@ -41,20 +41,20 @@ testthat::test_that("run_demo_openalex_quarto prepares demo project with fixture
   testthat::expect_match(qmd_text, "score_reference_cosine\\(")
   testthat::expect_match(qmd_text, "distance_ridge\\(")
   testthat::expect_match(qmd_text, "score_ridge\\(")
-  testthat::expect_match(qmd_text, "finalize_demo_openai_batch\\(")
-  testthat::expect_match(qmd_text, "Run later: openalexVectorComp::finalize_demo_openai_batch")
+  testthat::expect_match(qmd_text, "demo_finalize_openai_batch\\(")
+  testthat::expect_match(qmd_text, "Run later: openalexVectorComp::demo_finalize_openai_batch")
 
   testthat::expect_identical(normalizePath(out$demo_dir), normalizePath(proj))
   testthat::expect_identical(normalizePath(out$project_dir), normalizePath(file.path(proj, "project")))
   testthat::expect_false(out$rendered)
 })
 
-testthat::test_that("run_demo_openalex_quarto enforces overwrite policy", {
+testthat::test_that("run_demo_openalex enforces overwrite policy", {
   td <- tempfile("ovc_demo_overwrite_")
   dir.create(td, recursive = TRUE, showWarnings = FALSE)
   proj <- file.path(td, "demo_project")
 
-  run_demo_openalex_quarto(
+  run_demo_openalex(
     demo_dir = proj,
     render = FALSE,
     backend = ovc_hf_backend(max_batch_size = 4L),
@@ -63,7 +63,7 @@ testthat::test_that("run_demo_openalex_quarto enforces overwrite policy", {
   )
 
   testthat::expect_error(
-    run_demo_openalex_quarto(
+    run_demo_openalex(
       demo_dir = proj,
       render = FALSE,
       backend = ovc_hf_backend(max_batch_size = 4L),
@@ -74,7 +74,7 @@ testthat::test_that("run_demo_openalex_quarto enforces overwrite policy", {
   )
 
   testthat::expect_no_error(
-    run_demo_openalex_quarto(
+    run_demo_openalex(
       demo_dir = proj,
       render = FALSE,
       backend = ovc_hf_backend(max_batch_size = 4L),
@@ -118,7 +118,7 @@ testthat::test_that("optional demo render works when quarto and token are availa
   dir.create(td, recursive = TRUE, showWarnings = FALSE)
   proj <- file.path(td, "demo_project")
 
-  out <- run_demo_openalex_quarto(
+  out <- run_demo_openalex(
     demo_dir = proj,
     render = TRUE,
     backend = ovc_hf_backend(max_batch_size = 4L),
@@ -132,13 +132,13 @@ testthat::test_that("optional demo render works when quarto and token are availa
   testthat::expect_true(file.exists(file.path(proj, "openalex_demo_analysis.html")))
 })
 
-testthat::test_that("run_demo_openai_quarto requires api_key and configures OpenAI backend", {
+testthat::test_that("run_demo_openai requires api_key and configures OpenAI backend", {
   td <- tempfile("ovc_demo_openai_")
   dir.create(td, recursive = TRUE, showWarnings = FALSE)
   proj <- file.path(td, "demo_project_openai")
 
   testthat::expect_error(
-    run_demo_openai_quarto(
+    run_demo_openai(
       api_key = "",
       demo_dir = proj,
       render = FALSE,
@@ -147,7 +147,7 @@ testthat::test_that("run_demo_openai_quarto requires api_key and configures Open
     "api_key"
   )
 
-  out <- run_demo_openai_quarto(
+  out <- run_demo_openai(
     api_key = "test-key",
     demo_dir = proj,
     render = FALSE,
@@ -160,7 +160,7 @@ testthat::test_that("run_demo_openai_quarto requires api_key and configures Open
   testthat::expect_true(file.exists(file.path(proj, "openai_demo_analysis.qmd")))
   testthat::expect_true(file.exists(file.path(proj, "demo_backend.yaml")))
 
-  backend <- openalexVectorComp::embedding_backend_read(
+  backend <- openalexVectorComp::backend_read(
     file.path(proj, "demo_backend.yaml")
   )
   testthat::expect_identical(tolower(as.character(backend$provider)), "openai")
diff --git a/tests/testthat/test-distance-functions.R b/tests/testthat/test-distance-functions.R
index f61576f..3497624 100644
--- a/tests/testthat/test-distance-functions.R
+++ b/tests/testthat/test-distance-functions.R
@@ -29,8 +29,8 @@ make_distance_test_project <- function() {
     partitioning = c("label", "batch")
   )
 
-  openalexVectorComp::embedding_backend_save(
-    backend = openalexVectorComp::embedding_backend_config(
+  openalexVectorComp::backend_save(
+    backend = openalexVectorComp::backend_config(
       provider = "hf",
       model = "BAAI/bge-small-en-v1.5"
     ),
diff --git a/tests/testthat/test-embedding-offline.R b/tests/testthat/test-embedding-offline.R
index 8b23add..6ae3ef0 100644
--- a/tests/testthat/test-embedding-offline.R
+++ b/tests/testthat/test-embedding-offline.R
@@ -20,7 +20,7 @@ testthat::test_that("embed_texts forwards to embedding backend adapter", {
       texts = c("a", "b"),
       backend = list(provider = "hf")
     ),
-    embedding_backend_embed_texts = function(texts, backend) {
+    backend_embed_texts = function(texts, backend) {
       seen <<- list(texts = texts, backend = backend)
       matrix(c(1, 2, 3, 4), nrow = 2, byrow = TRUE)
     },
@@ -197,7 +197,7 @@ testthat::test_that("OpenAI adapter accepts data.frame-shaped `data` payload", {
 
 testthat::test_that("embed_corpus respects delete_existing and skip unchanged rows", {
   proj <- make_tmp_corpus_project()
-  backend <- openalexVectorComp::embedding_backend_config(provider = "hf")
+  backend <- openalexVectorComp::backend_config(provider = "hf")
 
   model_dir <- testthat::with_mocked_bindings(
     openalexVectorComp::embed_corpus(
@@ -274,7 +274,7 @@ testthat::test_that("embed_corpus respects delete_existing and skip unchanged ro
 
 testthat::test_that("embed_corpus label partitions can coexist and delete_existing is label-scoped", {
   proj <- make_tmp_corpus_project()
-  backend <- openalexVectorComp::embedding_backend_config(provider = "hf")
+  backend <- openalexVectorComp::backend_config(provider = "hf")
 
   model_dir <- testthat::with_mocked_bindings(
     openalexVectorComp::embed_corpus(
@@ -354,7 +354,7 @@ testthat::test_that("embed_corpus label partitions can coexist and delete_existi
 
 testthat::test_that("embed_corpus accepts custom text_preprocessor and cleaner_args", {
   proj <- make_tmp_corpus_project()
-  backend <- openalexVectorComp::embedding_backend_config(provider = "hf")
+  backend <- openalexVectorComp::backend_config(provider = "hf")
   seen_suffix <- NULL
 
   my_preprocessor <- function(df, suffix = "X") {
@@ -422,7 +422,7 @@ testthat::test_that("embed_corpus accepts custom text_preprocessor and cleaner_a
 
 testthat::test_that("embed_corpus validates text_preprocessor output contract", {
   proj <- make_tmp_corpus_project()
-  backend <- openalexVectorComp::embedding_backend_config(provider = "hf")
+  backend <- openalexVectorComp::backend_config(provider = "hf")
 
   bad_missing <- function(df) data.frame(id = df$id, text = "x", stringsAsFactors = FALSE)
   testthat::expect_error(
@@ -464,7 +464,7 @@ testthat::test_that("embed_corpus validates text_preprocessor output contract",
 
 testthat::test_that("embed_corpus dry_run preprocesses but does not write embeddings", {
   proj <- make_tmp_corpus_project()
-  backend <- openalexVectorComp::embedding_backend_config(provider = "hf")
+  backend <- openalexVectorComp::backend_config(provider = "hf")
   called <- FALSE
 
   model_dir <- testthat::with_mocked_bindings(
diff --git a/tests/testthat/test-openai-batch.R b/tests/testthat/test-openai-batch.R
index 5bf3194..3b15e9c 100644
--- a/tests/testthat/test-openai-batch.R
+++ b/tests/testthat/test-openai-batch.R
@@ -14,7 +14,7 @@ make_openai_batch_project <- function(n = 6) {
 }
 
 fake_openai_backend <- function() {
-  openalexVectorComp::embedding_backend_config(
+  openalexVectorComp::backend_config(
     provider = "openai",
     base_url = "https://api.openai.com/v1",
     model = "text-embedding-3-small",
@@ -30,7 +30,7 @@ testthat::test_that("submit splits jobs by request count", {
   uploaded_lines <- integer()
 
   out <- testthat::with_mocked_bindings(
-    openalexVectorComp::embed_corpus_submit_openai_batch(
+    openalexVectorComp::batch_submit_openai(
       project_dir = proj,
       backend = backend,
       max_requests_per_job = 2,
@@ -74,7 +74,7 @@ testthat::test_that("submit splits jobs by byte size", {
 
   uploads <- 0L
   out <- testthat::with_mocked_bindings(
-    openalexVectorComp::embed_corpus_submit_openai_batch(
+    openalexVectorComp::batch_submit_openai(
       project_dir = proj,
       backend = backend,
       max_requests_per_job = 50000,
@@ -109,7 +109,7 @@ testthat::test_that("single oversized request line errors before submission", {
   uploads <- 0L
   testthat::expect_error(
     testthat::with_mocked_bindings(
-      openalexVectorComp::embed_corpus_submit_openai_batch(
+      openalexVectorComp::batch_submit_openai(
         project_dir = proj,
         backend = backend,
         max_job_bytes = 500,
@@ -134,7 +134,7 @@ testthat::test_that("limit validation rejects invalid caps", {
   backend <- fake_openai_backend()
 
   testthat::expect_error(
-    openalexVectorComp::embed_corpus_submit_openai_batch(
+    openalexVectorComp::batch_submit_openai(
       project_dir = proj,
       backend = backend,
       max_requests_per_job = 50001,
@@ -143,7 +143,7 @@ testthat::test_that("limit validation rejects invalid caps", {
     "<= 50000"
   )
   testthat::expect_error(
-    openalexVectorComp::embed_corpus_submit_openai_batch(
+    openalexVectorComp::batch_submit_openai(
       project_dir = proj,
       backend = backend,
       max_job_bytes = 210 * 1024^2,
@@ -158,7 +158,7 @@ testthat::test_that("collect ingests completed jobs and is idempotent", {
   backend <- fake_openai_backend()
 
   submit <- testthat::with_mocked_bindings(
-    openalexVectorComp::embed_corpus_submit_openai_batch(
+    openalexVectorComp::batch_submit_openai(
       project_dir = proj,
       backend = backend,
       max_requests_per_job = 50000,
@@ -191,7 +191,7 @@ testthat::test_that("collect ingests completed jobs and is idempotent", {
 
   downloaded <- 0L
   out1 <- testthat::with_mocked_bindings(
-    openalexVectorComp::embed_corpus_collect_openai_batch(
+    openalexVectorComp::batch_collect_openai(
       project_dir = proj,
       backend = backend,
       label = "corpus",
@@ -216,7 +216,7 @@ testthat::test_that("collect ingests completed jobs and is idempotent", {
   testthat::expect_length(files, 1L)
 
   out2 <- testthat::with_mocked_bindings(
-    openalexVectorComp::embed_corpus_collect_openai_batch(
+    openalexVectorComp::batch_collect_openai(
       project_dir = proj,
       backend = backend,
       label = "corpus",
diff --git a/tests/testthat/test-validation-inputs.R b/tests/testthat/test-validation-inputs.R
index 49a73e8..cca9b42 100644
--- a/tests/testthat/test-validation-inputs.R
+++ b/tests/testthat/test-validation-inputs.R
@@ -40,27 +40,27 @@ make_tmp_embeddings_no_vcols <- function() {
   emb_dir
 }
 
-testthat::test_that("embedding_backend_config validates numeric inputs", {
+testthat::test_that("backend_config validates numeric inputs", {
   testthat::expect_error(
-    embedding_backend_config(timeout = 0),
+    backend_config(timeout = 0),
     "`timeout` must be a positive number."
   )
   testthat::expect_error(
-    embedding_backend_config(timeout = -5),
+    backend_config(timeout = -5),
     "`timeout` must be a positive number."
   )
   testthat::expect_error(
-    embedding_backend_config(retries = -1),
+    backend_config(retries = -1),
     "`retries` must be >= 0."
   )
   testthat::expect_error(
-    embedding_backend_config(max_batch_size = 0),
+    backend_config(max_batch_size = 0),
     "`max_batch_size` must be a positive integer."
   )
 })
 
-testthat::test_that("embedding_backend_save/read round-trip and legacy compatibility", {
-  cfg <- embedding_backend_config(
+testthat::test_that("backend_save/read round-trip and legacy compatibility", {
+  cfg <- backend_config(
     provider = "hf",
     base_url = "https://router.huggingface.co/hf-inference",
     model = "BAAI/bge-small-en-v1.5",
@@ -69,10 +69,10 @@ testthat::test_that("embedding_backend_save/read round-trip and legacy compatibi
     retries = 4
   )
   fn <- tempfile(fileext = ".yaml")
-  saved <- embedding_backend_save(backend = cfg, fn = fn)
+  saved <- backend_save(backend = cfg, fn = fn)
   testthat::expect_identical(saved, fn)
 
-  back <- embedding_backend_read(fn)
+  back <- backend_read(fn)
   testthat::expect_identical(back$provider, cfg$provider)
   testthat::expect_identical(back$base_url, cfg$base_url)
   testthat::expect_identical(back$model, cfg$model)
@@ -95,14 +95,14 @@ testthat::test_that("embedding_backend_save/read round-trip and legacy compatibi
     ),
     legacy_fn
   )
-  legacy <- embedding_backend_read(legacy_fn)
+  legacy <- backend_read(legacy_fn)
   testthat::expect_identical(legacy$provider, "tei")
   testthat::expect_identical(legacy$model, "legacy-model")
   testthat::expect_identical(legacy$embed_url, "http://localhost:3000/embed")
 })
 
 testthat::test_that("embedding backend config applies tei_url override", {
-  cfg <- embedding_backend_config(
+  cfg <- backend_config(
     provider = "tei",
     base_url = "http://localhost:9999/",
     tei_url = "http://localhost:3000/embed///"
@@ -111,24 +111,24 @@ testthat::test_that("embedding backend config applies tei_url override", {
   testthat::expect_identical(cfg$base_url, "http://localhost:3000/embed")
 })
 
-testthat::test_that("embedding_backend_info and embed_texts validate backend/texts", {
+testthat::test_that("backend_info and embed_texts validate backend/texts", {
   testthat::expect_error(
-    embedding_backend_info(backend = list()),
+    backend_info(backend = list()),
     "`backend` must be a configuration object"
   )
   testthat::expect_error(
-    embedding_backend_info(backend = list(provider = "nope")),
+    backend_info(backend = list(provider = "nope")),
     "Unsupported backend provider"
   )
   testthat::expect_error(
-    embedding_backend_embed_texts(texts = 123),
+    backend_embed_texts(texts = 123),
     "`texts` must be a character vector."
   )
   testthat::expect_error(
-    embedding_backend_embed_texts(texts = "a", backend = list(provider = "nope")),
+    backend_embed_texts(texts = "a", backend = list(provider = "nope")),
     "Unsupported backend provider"
   )
-  out <- embedding_backend_embed_texts(texts = character())
+  out <- backend_embed_texts(texts = character())
   testthat::expect_true(is.matrix(out))
   testthat::expect_equal(nrow(out), 0)
 })
@@ -200,7 +200,7 @@ testthat::test_that("embed_corpus validates key inputs", {
   )
   testthat::expect_error(
     embed_corpus(project_dir = tempdir(), backend = list(), verbose = FALSE),
-    "`backend` must come from embedding_backend_config"
+    "`backend` must come from backend_config"
   )
   testthat::expect_error(
     embed_corpus(project_dir = tempdir(), corpus_name = "", verbose = FALSE),
@@ -239,7 +239,7 @@ testthat::test_that("embed_corpus validates key inputs", {
   )
   arrow::write_dataset(ok, path = file.path(td2, "papers"), format = "parquet")
 
-  backend <- embedding_backend_config(provider = "hf", model = "BAAI/bge-small-en-v1.5")
+  backend <- backend_config(provider = "hf", model = "BAAI/bge-small-en-v1.5")
   model_dir <- testthat::with_mocked_bindings(
     embed_corpus(
       project_dir = td2,
diff --git a/vignettes/backend-architecture.qmd b/vignettes/backend-architecture.qmd
index 41e6877..2264f22 100644
--- a/vignettes/backend-architecture.qmd
+++ b/vignettes/backend-architecture.qmd
@@ -31,9 +31,9 @@ The focus is implementation details, not end-user quickstart usage.
 Backend logic is split into one core file and provider-specific files:
 
 - `R/embed_backend_core.R`:
-  - `embedding_backend_config()`
-  - `embedding_backend_info()`
-  - `embedding_backend_embed_texts()`
+  - `backend_config()`
+  - `backend_info()`
+  - `backend_embed_texts()`
   - shared helpers (`.embedding_with_retry()`, `.embedding_request_base()`, ...)
 - `R/embed_backend_hf.R`:
   - `.embedding_info_hf()`
@@ -50,8 +50,8 @@ Backend logic is split into one core file and provider-specific files:
 ```{mermaid}
 
 flowchart TD
-  A[embedding_backend_config] --> B[embedding_backend_info]
-  A --> C[embedding_backend_embed_texts]
+  A[backend_config] --> B[backend_info]
+  A --> C[backend_embed_texts]
   C --> D{provider}
   D -->|hf| E[.embedding_embed_texts_hf]
   D -->|openai| F[.embedding_embed_texts_openai]
@@ -76,13 +76,13 @@ sequenceDiagram
   participant FS as parquet_output
 
   User->>embed_corpus: embed_corpus(project_dir, backend=...)
-  embed_corpus->>Core: embedding_backend_config(...) (if backend is NULL)
-  embed_corpus->>Core: embedding_backend_info(backend)
+  embed_corpus->>Core: backend_config(...) (if backend is NULL)
+  embed_corpus->>Core: backend_info(backend)
   embed_corpus->>FS: Load existing hashes (id + text_hash)
   loop Arrow scan batches
     embed_corpus->>embed_corpus: Build canonical text
     embed_corpus->>embed_corpus: Filter unchanged rows
-    embed_corpus->>Core: embedding_backend_embed_texts(texts, backend)
+    embed_corpus->>Core: backend_embed_texts(texts, backend)
     Core->>Provider: provider dispatch
     Provider->>API: batched HTTP requests
     API-->>Provider: vectors
@@ -179,14 +179,14 @@ This keeps auth handling provider-agnostic.
 ```{r}
 library(openalexVectorComp)
 
-backend <- embedding_backend_config(
+backend <- backend_config(
   provider = "hf",
   model = "BAAI/bge-small-en-v1.5",
   max_batch_size = 64
 )
 
-info <- embedding_backend_info(backend)
-emb <- embedding_backend_embed_texts(
+info <- backend_info(backend)
+emb <- backend_embed_texts(
   texts = c("Title: A\nAbstract: B", "Title: C\nAbstract: D"),
   backend = backend
 )
@@ -196,7 +196,7 @@ dim(emb)
 ## 2) OpenAI backend
 
 ```{r}
-backend <- embedding_backend_config(
+backend <- backend_config(
   provider = "openai",
   model = "text-embedding-3-small",
   max_batch_size = 256
@@ -206,7 +206,7 @@ backend <- embedding_backend_config(
 ## 3) Local TEI backend
 
 ```{r}
-backend <- embedding_backend_config(
+backend <- backend_config(
   provider = "tei",
   base_url = "http://localhost:3000",
   max_batch_size = 128
@@ -219,16 +219,16 @@ Assume new provider name `"acme"`.
 
 ## Step 1: add dispatch entry in core
 
-In `embedding_backend_config()`:
+In `backend_config()`:
 
 - include `"acme"` in `provider = c(...)`
 - define provider defaults in `switch(provider, ...)`
 
-In `embedding_backend_info()`:
+In `backend_info()`:
 
 - add branch: `acme = .embedding_info_acme(backend)`
 
-In `embedding_backend_embed_texts()`:
+In `backend_embed_texts()`:
 
 - add branch: `acme = .embedding_embed_texts_acme(texts, backend)`
 
diff --git a/vignettes/openai-batch-async.qmd b/vignettes/openai-batch-async.qmd
index 75650f4..dfb6972 100644
--- a/vignettes/openai-batch-async.qmd
+++ b/vignettes/openai-batch-async.qmd
@@ -25,9 +25,9 @@ results later.
 
 In `openalexVectorComp`, this is implemented as three explicit steps:
 
-1. `embed_corpus_submit_openai_batch()`
-2. `embed_corpus_status_openai_batch()`
-3. `embed_corpus_collect_openai_batch()`
+1. `batch_submit_openai()`
+2. `batch_status_openai()`
+3. `batch_collect_openai()`
 
 This design is operationally safer than waiting for one long blocking process.
 
@@ -64,7 +64,7 @@ flowchart TD
 ```{r}
 library(openalexVectorComp)
 
-backend <- embedding_backend_config(
+backend <- backend_config(
   provider = "openai",
   model = "text-embedding-3-small"
 )
@@ -74,11 +74,11 @@ Sys.getenv("OVC_API_TOKEN")
 
 # Step 1: Submit jobs
 
-`embed_corpus_submit_openai_batch()` preprocesses rows, applies skip logic,
+`batch_submit_openai()` preprocesses rows, applies skip logic,
 performs preflight checks, auto-splits by limits, then submits jobs.
 
 ```{r}
-submit_info <- embed_corpus_submit_openai_batch(
+submit_info <- batch_submit_openai(
   project_dir = "my_project",
   backend = backend,
   corpus_name = "corpus",
@@ -114,10 +114,10 @@ Before any remote submission:
 
 # Step 2: Check status
 
-Use `embed_corpus_status_openai_batch()` to inspect queued jobs.
+Use `batch_status_openai()` to inspect queued jobs.
 
 ```{r}
-status_df <- embed_corpus_status_openai_batch(
+status_df <- batch_status_openai(
   project_dir = "my_project",
   label = "corpus",
   refresh_remote = TRUE
@@ -142,11 +142,11 @@ Only `completed` jobs are eligible for collection.
 
 # Step 3: Collect completed jobs
 
-`embed_corpus_collect_openai_batch()` downloads completed outputs,
+`batch_collect_openai()` downloads completed outputs,
 joins by `custom_id`, validates mapping, and writes canonical embeddings parquet.
 
 ```{r}
-collect_info <- embed_corpus_collect_openai_batch(
+collect_info <- batch_collect_openai(
   project_dir = "my_project",
   backend = backend,
   label = "corpus",
diff --git a/vignettes/package-overview.qmd b/vignettes/package-overview.qmd
index 1c99402..3b1f934 100644
--- a/vignettes/package-overview.qmd
+++ b/vignettes/package-overview.qmd
@@ -64,11 +64,11 @@ The package API is organized into these groups.
 
 ## 1) Embedding backend abstraction
 
-- `embedding_backend_config()`
-- `embedding_backend_info()`
-- `embedding_backend_embed_texts()`
-- `embedding_backend_read()`
-- `embedding_backend_save()`
+- `backend_config()`
+- `backend_info()`
+- `backend_embed_texts()`
+- `backend_read()`
+- `backend_save()`
 - `embed_texts()`
 
 These functions isolate provider-specific details and expose a stable interface.
@@ -130,7 +130,7 @@ flowchart TB
 
 Typical workflow for one project:
 
-1. Configure backend (`embedding_backend_config()`).
+1. Configure backend (`backend_config()`).
 2. Embed corpus (`embed_corpus()`).
 3. Compute distance signal (`distance_reference_cosine()` and/or `distance_ridge()`), then score (e.g. `score_reference_cosine()`, `score_ridge()`).
 4. Calibrate operating threshold (`calibrate_threshold()`).
@@ -148,7 +148,7 @@ sequenceDiagram
   participant SR as score_ridge
   participant CT as calibrate_threshold
 
-  U->>BC: embedding_backend_config(...)
+  U->>BC: backend_config(...)
   U->>EC: embed_corpus(project_dir, backend)
   EC->>ES: write embeddings parquet
   U->>DP: distance_reference_cosine(...)
@@ -240,7 +240,7 @@ flowchart LR
 ```r
 library(openalexVectorComp)
 
-backend <- embedding_backend_config(
+backend <- backend_config(
   provider = "hf",
   model = "BAAI/bge-small-en-v1.5",
   max_batch_size = 64
diff --git a/vignettes/simplestart.qmd b/vignettes/simplestart.qmd
index 90e9f16..ef6ccd6 100644
--- a/vignettes/simplestart.qmd
+++ b/vignettes/simplestart.qmd
@@ -62,7 +62,7 @@ The fixture already contains:
 #| label: embed-corpus
 embed_corpus(
   project_dir = "inst/ovc_demo/project",
-  backend = embedding_backend_config(
+  backend = backend_config(
     provider = "tei",
     base_url = "http://localhost:3000"
   ),
@@ -73,7 +73,7 @@ embed_corpus(
 
 embed_corpus(
   project_dir = "inst/ovc_demo/project",
-  backend = embedding_backend_config(
+  backend = backend_config(
     provider = "tei",
     base_url = "http://localhost:3000"
   ),
@@ -140,7 +140,7 @@ ridge_score_dir <- score_ridge(
 - Can’t find `text-embeddings-router`:
   - Install the binary and ensure it is on PATH.
 - Port in use:
-  - Start TEI on another port and update `backend = embedding_backend_config(provider = "tei", base_url = "http://localhost:3001")`.
+  - Start TEI on another port and update `backend = backend_config(provider = "tei", base_url = "http://localhost:3001")`.
 - Slow embedding or timeouts:
   - Reduce `batch_size`, and verify the server’s `/info` limits.
 
diff --git a/vignettes/tei-server-operations.qmd b/vignettes/tei-server-operations.qmd
index 7f4f8b0..6e28dc1 100644
--- a/vignettes/tei-server-operations.qmd
+++ b/vignettes/tei-server-operations.qmd
@@ -63,7 +63,7 @@ curl -s -X POST http://localhost:3000/embed \
 ```{r}
 library(openalexVectorComp)
 
-backend <- embedding_backend_config(
+backend <- backend_config(
   provider = "tei",
   base_url = "http://localhost:3000"
 )
@@ -108,7 +108,7 @@ Use another port and update backend config accordingly.
 ## Empty/invalid responses
 
 - Check `curl` smoke test directly against `/embed`.
-- Reduce `max_batch_size` in `embedding_backend_config()`.
+- Reduce `max_batch_size` in `backend_config()`.
 
 ## Slow throughput