QVAC-24055 doc: flag built-in RAG vector store as prototype-only

docs/website/content/docs/ai-capabilities/rag.mdx

@@ -36,8 +36,12 @@ For how to use each function, see [SDK — API reference](/reference/api/).
 Create your RAG pipeline using [text embeddings](/ai-capabilities/text-embeddings), the functions above, and [completion](/ai-capabilities/text-generation).
 
 Regarding vector storage, you may use:
+- **External vector DB:** use [`embed()`](/reference/api#embed) to generate vectors and store them wherever you want (e.g., MongoDB, LanceDB, ChromaDB, SQLite-Vector). Choose this when you need custom persistence, filtering, or integration with an existing database.
 - **Built-in vector store:** use the RAG workspace functions ([`ragIngest()`](/reference/api#ragingest), [`ragSearch()`](/reference/api#ragsearch), etc.). QVAC persists the vectors for you, so this is the simplest path.
-- **External vector DB:** use the embedding primitives ([`ragChunk()`](/reference/api#ragchunk), [`embed()`](/reference/api#embed)) and store the vectors wherever you want (e.g., MongoDB, LanceDB, ChromaDB, SQLite-Vector). Choose this when you need custom persistence, filtering, or integration with an existing database.
+
+<Callout type="warn">
+**Built-in vector store is not production grade** and is intended for prototypes only. For production workloads, use one of the external vector DB paths shown below (MongoDB, SQLite, LanceDB, Chroma, etc.).
+</Callout>
 
 <Callout type="info">
 **Important:** when using an external vector DB, make sure its schema matches the embedding dimensionality produced by your model (e.g., GTE Large embeddings used in the example are 1024‑dimensional).
@@ -47,6 +51,10 @@ Regarding vector storage, you may use:
 
 ### Built-in vector store
 
+<Callout type="warn">
+**Prototype only** — for production, prefer an external vector DB (below).
+</Callout>
+
 The following script shows how to ingest documents into a built-in RAG workspace with `ragIngest()` and query them with `ragSearch()`, without setting up an external vector DB:
 
 <Tabs>

docs/website/content/docs/reference/api/index.mdx

@@ -906,6 +906,8 @@ const chunks = await ragChunk({
 
 ### `ragCloseWorkspace`
 
+> 🧪 **Prototype only**: The built-in RAG vector store is not production grade. For production, use an external vector DB (see the RAG guide).
+
 Closes a RAG workspace, releasing in-memory resources (Corestore, HyperDB adapter, RAG instance).
 
 **Workspace lifecycle:** Workspaces are implicitly opened.
@@ -935,6 +937,8 @@ await ragCloseWorkspace({ workspace: "my-docs", deleteOnClose: true });
 
 ### `ragDeleteEmbeddings`
 
+> 🧪 **Prototype only**: The built-in RAG vector store is not production grade. For production, use an external vector DB (see the RAG guide).
+
 Deletes document embeddings from the RAG vector database.
 
 **Workspace lifecycle:** This operation requires an existing workspace.
@@ -961,6 +965,8 @@ await ragDeleteEmbeddings({
 
 ### `ragDeleteWorkspace`
 
+> 🧪 **Prototype only**: The built-in RAG vector store is not production grade. For production, use an external vector DB (see the RAG guide).
+
 Deletes a RAG workspace and all its data.
 The workspace must not be currently loaded/in-use.
 
@@ -983,6 +989,8 @@ await ragDeleteWorkspace({ workspace: "my-docs" });
 
 ### `ragIngest`
 
+> 🧪 **Prototype only**: The built-in RAG vector store is not production grade. For production, use an external vector DB (see the RAG guide).
+
 Ingests documents into the RAG vector database.
 Full pipeline: chunk → embed → save
 
@@ -1023,6 +1031,8 @@ const result = await ragIngest({
 
 ### `ragListWorkspaces`
 
+> 🧪 **Prototype only**: The built-in RAG vector store is not production grade. For production, use an external vector DB (see the RAG guide).
+
 Lists all RAG workspaces with their open status.
 
 Returns all workspaces that exist on disk. The `open` field indicates whether
@@ -1049,6 +1059,8 @@ const workspaces = await ragListWorkspaces();
 
 ### `ragReindex`
 
+> 🧪 **Prototype only**: The built-in RAG vector store is not production grade. For production, use an external vector DB (see the RAG guide).
+
 Reindexes the RAG database to optimize search performance.
 For HyperDB, this rebalances centroids using k-means clustering.
 
@@ -1094,6 +1106,8 @@ const result = await ragReindex({
 
 ### `ragSaveEmbeddings`
 
+> 🧪 **Prototype only**: The built-in RAG vector store is not production grade. For production, use an external vector DB (see the RAG guide).
+
 Saves pre-embedded documents to the RAG vector database.
 Part of the segregated flow: chunk() → embed() → saveEmbeddings()
 
@@ -1131,6 +1145,8 @@ const result = await ragSaveEmbeddings({
 
 ### `ragSearch`
 
+> 🧪 **Prototype only**: The built-in RAG vector store is not production grade. For production, use an external vector DB (see the RAG guide).
+
 Searches for similar documents in the RAG vector database.
 
 **Workspace lifecycle:** This operation requires an existing workspace. If the workspace

docs/website/content/docs/reference/api/v0.16.x.mdx

@@ -887,6 +887,8 @@ const chunks = await ragChunk({
 
 ### `ragCloseWorkspace`
 
+> 🧪 **Prototype only**: The built-in RAG vector store is not production grade. For production, use an external vector DB (see the RAG guide).
+
 Closes a RAG workspace, releasing in-memory resources (Corestore, HyperDB adapter, RAG instance).
 
 **Workspace lifecycle:** Workspaces are implicitly opened.
@@ -916,6 +918,8 @@ await ragCloseWorkspace({ workspace: "my-docs", deleteOnClose: true });
 
 ### `ragDeleteEmbeddings`
 
+> 🧪 **Prototype only**: The built-in RAG vector store is not production grade. For production, use an external vector DB (see the RAG guide).
+
 Deletes document embeddings from the RAG vector database.
 
 **Workspace lifecycle:** This operation requires an existing workspace.
@@ -942,6 +946,8 @@ await ragDeleteEmbeddings({
 
 ### `ragDeleteWorkspace`
 
+> 🧪 **Prototype only**: The built-in RAG vector store is not production grade. For production, use an external vector DB (see the RAG guide).
+
 Deletes a RAG workspace and all its data.
 The workspace must not be currently loaded/in-use.
 
@@ -964,6 +970,8 @@ await ragDeleteWorkspace({ workspace: "my-docs" });
 
 ### `ragIngest`
 
+> 🧪 **Prototype only**: The built-in RAG vector store is not production grade. For production, use an external vector DB (see the RAG guide).
+
 Ingests documents into the RAG vector database.
 Full pipeline: chunk → embed → save
 
@@ -1004,6 +1012,8 @@ const result = await ragIngest({
 
 ### `ragListWorkspaces`
 
+> 🧪 **Prototype only**: The built-in RAG vector store is not production grade. For production, use an external vector DB (see the RAG guide).
+
 Lists all RAG workspaces with their open status.
 
 Returns all workspaces that exist on disk. The `open` field indicates whether
@@ -1030,6 +1040,8 @@ const workspaces = await ragListWorkspaces();
 
 ### `ragReindex`
 
+> 🧪 **Prototype only**: The built-in RAG vector store is not production grade. For production, use an external vector DB (see the RAG guide).
+
 Reindexes the RAG database to optimize search performance.
 For HyperDB, this rebalances centroids using k-means clustering.
 
@@ -1075,6 +1087,8 @@ const result = await ragReindex({
 
 ### `ragSaveEmbeddings`
 
+> 🧪 **Prototype only**: The built-in RAG vector store is not production grade. For production, use an external vector DB (see the RAG guide).
+
 Saves pre-embedded documents to the RAG vector database.
 Part of the segregated flow: chunk() → embed() → saveEmbeddings()
 
@@ -1112,6 +1126,8 @@ const result = await ragSaveEmbeddings({
 
 ### `ragSearch`
 
+> 🧪 **Prototype only**: The built-in RAG vector store is not production grade. For production, use an external vector DB (see the RAG guide).
+
 Searches for similar documents in the RAG vector database.
 
 **Workspace lifecycle:** This operation requires an existing workspace. If the workspace

docs/website/content/docs/reference/api/v0.17.x.mdx

@@ -889,6 +889,8 @@ const chunks = await ragChunk({
 
 ### `ragCloseWorkspace`
 
+> 🧪 **Prototype only**: The built-in RAG vector store is not production grade. For production, use an external vector DB (see the RAG guide).
+
 Closes a RAG workspace, releasing in-memory resources (Corestore, HyperDB adapter, RAG instance).
 
 **Workspace lifecycle:** Workspaces are implicitly opened.
@@ -918,6 +920,8 @@ await ragCloseWorkspace({ workspace: "my-docs", deleteOnClose: true });
 
 ### `ragDeleteEmbeddings`
 
+> 🧪 **Prototype only**: The built-in RAG vector store is not production grade. For production, use an external vector DB (see the RAG guide).
+
 Deletes document embeddings from the RAG vector database.
 
 **Workspace lifecycle:** This operation requires an existing workspace.
@@ -944,6 +948,8 @@ await ragDeleteEmbeddings({
 
 ### `ragDeleteWorkspace`
 
+> 🧪 **Prototype only**: The built-in RAG vector store is not production grade. For production, use an external vector DB (see the RAG guide).
+
 Deletes a RAG workspace and all its data.
 The workspace must not be currently loaded/in-use.
 
@@ -966,6 +972,8 @@ await ragDeleteWorkspace({ workspace: "my-docs" });
 
 ### `ragIngest`
 
+> 🧪 **Prototype only**: The built-in RAG vector store is not production grade. For production, use an external vector DB (see the RAG guide).
+
 Ingests documents into the RAG vector database.
 Full pipeline: chunk → embed → save
 
@@ -1006,6 +1014,8 @@ const result = await ragIngest({
 
 ### `ragListWorkspaces`
 
+> 🧪 **Prototype only**: The built-in RAG vector store is not production grade. For production, use an external vector DB (see the RAG guide).
+
 Lists all RAG workspaces with their open status.
 
 Returns all workspaces that exist on disk. The `open` field indicates whether
@@ -1032,6 +1042,8 @@ const workspaces = await ragListWorkspaces();
 
 ### `ragReindex`
 
+> 🧪 **Prototype only**: The built-in RAG vector store is not production grade. For production, use an external vector DB (see the RAG guide).
+
 Reindexes the RAG database to optimize search performance.
 For HyperDB, this rebalances centroids using k-means clustering.
 
@@ -1077,6 +1089,8 @@ const result = await ragReindex({
 
 ### `ragSaveEmbeddings`
 
+> 🧪 **Prototype only**: The built-in RAG vector store is not production grade. For production, use an external vector DB (see the RAG guide).
+
 Saves pre-embedded documents to the RAG vector database.
 Part of the segregated flow: chunk() → embed() → saveEmbeddings()
 
@@ -1114,6 +1128,8 @@ const result = await ragSaveEmbeddings({
 
 ### `ragSearch`
 
+> 🧪 **Prototype only**: The built-in RAG vector store is not production grade. For production, use an external vector DB (see the RAG guide).
+
 Searches for similar documents in the RAG vector database.
 
 **Workspace lifecycle:** This operation requires an existing workspace. If the workspace

docs/website/scripts/api-docs/extract.ts

@@ -528,6 +528,7 @@ function buildApiFunction(
     examples: string[];
     throws: Array<{ error: string; description: string }>;
     deprecated?: string;
+    prototype?: string;
     label?: string;
   };
   const rawOverloads: RawOverload[] = overloadSigs.map((s, idx) => {
@@ -588,8 +589,15 @@ function buildApiFunction(
     const deprecated = depTag
       ? extractComment(depTag.content) || "This overload is deprecated."
       : undefined;
+    // @prototype on a specific overload — surfaces a "Prototype only"
+    // callout scoped to this overload. Mirrors @deprecated.
+    const protoTag = sigBlockTags.find((t: any) => t.tag === "@prototype");
+    const prototype = protoTag
+      ? extractComment(protoTag.content) ||
+        "This overload is a prototype and is not production grade."
+      : undefined;
 
-    return { signature: sigText, description, examples, throws, deprecated, label };
+    return { signature: sigText, description, examples, throws, deprecated, prototype, label };
   });
 
   // De-dupe identical overload signatures (TypeDoc sometimes emits the
@@ -619,6 +627,7 @@ function buildApiFunction(
           if (ov.throws.length > 0) entry.throws = ov.throws;
           if (ov.examples.length > 0) entry.examples = ov.examples;
           if (ov.deprecated) entry.deprecated = ov.deprecated;
+          if (ov.prototype) entry.prototype = ov.prototype;
           if (ov.label) entry.label = ov.label;
           return entry;
         })
@@ -762,6 +771,16 @@ function buildApiFunction(
       if (comment?.isDeprecated) return "This function is deprecated.";
       return undefined;
     })(),
+    prototype: (() => {
+      const protoTag = blockTags.find((tag: any) => tag.tag === "@prototype");
+      if (protoTag) {
+        return (
+          extractComment(protoTag.content) ||
+          "This function is a prototype and is not production grade."
+        );
+      }
+      return undefined;
+    })(),
   };
 }
 

docs/website/scripts/api-docs/templates/single-page.njk

@@ -13,7 +13,7 @@ description: One-page reference of all public functions and objects exported by
 > For per-parameter and per-field details, hover symbols in your IDE or open
 > `node_modules/@qvac/sdk/dist`. This page is intentionally a high-level index.
 >
-> **Fields shown**: description, signature, throws, examples, deprecation.
+> **Fields shown**: description, signature, throws, examples, deprecation, prototype.
 > **Fields intentionally omitted**: parameter descriptions, return field descriptions
 > (covered by IDE hover and `.d.ts` declarations).
 >
@@ -29,6 +29,10 @@ description: One-page reference of all public functions and objects exported by
 {% if fn.deprecated %}
 > ⚠️ **Deprecated**: {{ fn.deprecated }}
 
+{% endif %}
+{% if fn.prototype %}
+> 🧪 **Prototype only**: {{ fn.prototype }}
+
 {% endif %}
 {% if fn.overloads and fn.overloads.length > 1 %}
 Has {{ fn.overloads.length }} overloads.
@@ -39,6 +43,10 @@ Has {{ fn.overloads.length }} overloads.
 {% if ov.deprecated %}
 > ⚠️ **Deprecated**: {{ ov.deprecated }}
 
+{% endif %}
+{% if ov.prototype %}
+> 🧪 **Prototype only**: {{ ov.prototype }}
+
 {% endif %}
 {% if ov.description %}
 {{ ov.description }}

docs/website/scripts/api-docs/types.ts

@@ -69,6 +69,13 @@ export interface ApiFunction {
   throws?: Array<{ error: string; description: string }>;
   examples?: string[];
   deprecated?: string;
+  /**
+   * Prototype marker (`@prototype <message>` in TSDoc). Mirrors `deprecated`
+   * in shape and rendering: when set, the single-page renderer emits a
+   * "Prototype only" blockquote above the description, warning consumers
+   * that the function is not production grade.
+   */
+  prototype?: string;
   /**
    * When the function declares multiple overloads, this is a per-overload
    * breakdown produced by the extractor (one entry per unique signature).
@@ -84,6 +91,8 @@ export interface ApiOverload {
   throws?: Array<{ error: string; description: string }>;
   examples?: string[];
   deprecated?: string;
+  /** See `ApiFunction.prototype`. Scoped to a single overload. */
+  prototype?: string;
   /** Optional human-friendly label, e.g. "Single text" or "Run / start". */
   label?: string;
 }

docs/website/tests/__snapshots__/api-docs-rendering.test.ts.snap

@@ -11,7 +11,7 @@ description: One-page reference of all public functions and objects exported by
 > For per-parameter and per-field details, hover symbols in your IDE or open
 > \`node_modules/@qvac/sdk/dist\`. This page is intentionally a high-level index.
 >
-> **Fields shown**: description, signature, throws, examples, deprecation.
+> **Fields shown**: description, signature, throws, examples, deprecation, prototype.
 > **Fields intentionally omitted**: parameter descriptions, return field descriptions
 > (covered by IDE hover and \`.d.ts\` declarations).
 >

docs/website/tests/api-docs-rendering.test.ts

@@ -277,4 +277,22 @@ describe('single-page template', () => {
     expect(mdx).toContain('### `oldThing`')
     expect(mdx).toContain('> ⚠️ **Deprecated**: Use newThing() instead.')
   })
+
+  it('renders a prototype callout for prototype-only functions', () => {
+    const prototypeFn: ApiFunction = {
+      ...minimalFn,
+      name: 'earlyThing',
+      prototype: 'Not production grade; use foo() instead in production.',
+    }
+    const mdx = env
+      .render('single-page.njk', {
+        ...renderArgs,
+        functions: [prototypeFn],
+      })
+      .trim()
+    expect(mdx).toContain('### `earlyThing`')
+    expect(mdx).toContain(
+      '> 🧪 **Prototype only**: Not production grade; use foo() instead in production.',
+    )
+  })
 })