ravendb · ppekrol · May 29, 2026 · Mar 27, 2026 · Mar 30, 2026 · Apr 1, 2026
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -150,11 +150,103 @@ Each folder contains `_category_.json`:
 
 ---
 
+## Frontmatter Naming Convention
+**CRITICAL RULE**: All custom frontmatter fields MUST use `snake_case`. Never use camelCase for custom frontmatter.
+- ✅ Correct: `published_at`, `proficiency_level`, `external_url`, `img_alt`, `repository_url`, `license_url`
+- ❌ Wrong: `publishedAt`, `proficiencyLevel`, `externalUrl`, `imgAlt`, `repositoryUrl`, `licenseUrl`
+- Standard Docusaurus fields (e.g., `title`, `description`, `slug`) remain as-is.
+- Tag values in guides and samples MUST use `kebab-case` (e.g., `vector-search`, `azure-storage-queues-etl`).
+
+---
+
 ## Guides
 - Tags defined in `guides/tags.yml` (~40 predefined tags — do not invent new ones without adding there first).
-- Guide-specific frontmatter: `tags`, `description`, `icon`, `image`, `publishedAt` (ISO date), `externalUrl`.
+- Guide-specific frontmatter: `tags`, `description`, `icon`, `image`, `published_at` (ISO date), `external_url`, `proficiency_level`, `author`.
 - Indexed and sorted by `src/plugins/recent-guides-plugin.ts`.
 
+### Guides Frontmatter Example
+```yaml
+---
+title: "Guide Title"
+published_at: 2026-04-02
+author: "Author Name"
+tags: [ai, vector-search, getting-started]
+description: "Short description shown in cards."
+image: "/img/guides-example.webp"
+proficiency_level: "Beginner"
+---
+```
+
+For external guides (linking to blog posts):
+```yaml
+---
+title: "External Article Title"
+published_at: 2026-04-02
+tags: [integration]
+description: "Short description."
+external_url: "https://ravendb.net/articles/example"
+image: "https://ravendb.net/path/to/image.jpg"
+---
+```
+
+---
+
+## Samples
+- Production-ready code samples demonstrating RavenDB features and architecture patterns.
+- Located in `samples/` directory.
+- Three-category tag system: Challenges & Solutions, Features, Tech Stack.
+- Tags defined in `samples/tags/` YAML files — do not invent new ones without adding there first.
+- Indexed by `src/plugins/recent-samples-plugin.ts`.
+- Hub page at `/samples` with filtering by tags.
+
+### Sample Tag Categories
+1. **Challenges & Solutions** (`samples/tags/challenges-solutions.yml`) - Business problems the sample solves
+   - Examples: `semantic-search`, `integration-patterns`, `cloud-tax`, `gen-ai-data-enrichment`
+
+2. **Features** (`samples/tags/feature.yml`) - RavenDB features demonstrated
+   - Examples: `vector-search`, `document-refresh`, `include`, `azure-storage-queues-etl`
+
+3. **Tech Stack** (`samples/tags/tech-stack.yml`) - Technologies used
+   - Examples: `csharp`, `aspire`, `azure-functions`, `nodejs`, `nextjs`
+
+### Sample Frontmatter Example
+```yaml
+---
+title: "Sample Application Name"
+description: "Brief description for sample cards."
+challenges_solutions_tags: [semantic-search, integration-patterns]
+feature_tags: [vector-search, document-refresh, include]
+tech_stack_tags: [csharp, aspire, azure-functions]
+image: "/img/samples/my-sample/cover.webp"
+img_alt: "Screenshot of the application"
+category: "Ecommerce"
+license: "MIT License"
+license_url: "https://opensource.org/licenses/MIT"
+repository_url: "https://github.com/ravendb/sample-repo"
+demo_url: "https://demo.example.com"
+languages: ["C#"]
+gallery:
+  - src: "/img/samples/my-sample/screenshot-1.webp"
+    alt: "Main interface"
+  - src: "/img/samples/my-sample/screenshot-2.webp"
+    alt: "Admin dashboard"
+related_resources:
+  - type: documentation
+    documentation_type: docs
+    subtitle: "Vector Search Overview"
+    article_key: "ai-integration/vector-search/overview"
+  - type: guide
+    subtitle: "Related Guide Title"
+    article_key: "guide-slug"
+---
+```
+
+**Required fields**: `title`, `description`, `challenges_solutions_tags`, `feature_tags`, `tech_stack_tags`
+
+**Optional fields**: `image`, `img_alt`, `category`, `license`, `license_url`, `repository_url`, `demo_url`, `languages`, `gallery`, `related_resources`
+
+**SEO**: `repository_url` and `languages` feed `SoftwareSourceCode` JSON-LD schema for better search visibility.
+
 ---
 
 ## Icon System
@@ -392,11 +484,31 @@ Each folder contains `_category_.json`:
 ### `cloud/` — RavenDB Cloud service documentation (~24 files)
 Account management, instance configuration, security (TLS, MFA, certificates), pricing/billing, scaling, backup/restore, migration, AWS/Azure Marketplace setup, and the cloud portal UI (home, products, billing, backups, support tabs).
 
-### `guides/` — Practical how-to guides (~63 files, flat structure)
-Community guides covering: connecting specific frameworks (ASP.NET Core, Next.js, SvelteKit, FastAPI), AI/ML integration, DevOps (Docker, Kubernetes/EKS, Helm, Ansible), observability (Datadog, Grafana/OpenTelemetry), data pipelines (Elasticsearch, Azure Queue, OLAP ETL), testing (unit test drivers for .NET/Java/Python), and troubleshooting specific problems. Tags defined in `guides/tags.yml`.
+### `guides/` — Practical how-to guides (~64 files, flat structure)
+Community guides covering: connecting specific frameworks (ASP.NET Core, Next.js, SvelteKit, FastAPI), AI/ML integration, DevOps (Docker, Kubernetes/EKS, Helm, Ansible), observability (Datadog, Grafana/OpenTelemetry), data pipelines (Elasticsearch, Azure Queue, OLAP ETL), testing (unit test drivers for .NET/Java/Python), and troubleshooting specific problems.
+
+**Frontmatter**: `title`, `published_at`, `author`, `tags`, `description`, `icon`, `image`, `proficiency_level`, `external_url` (for external guides).
+
+**Tags**: Defined in `guides/tags.yml` (~40 predefined tags — do not invent new ones without adding there first). All tag values use kebab-case.
+
+**Indexed by**: `src/plugins/recent-guides-plugin.ts`
+
+### `samples/` — Production-ready code samples (~1+ files)
+Production-ready code samples, architecture patterns, and starter kits demonstrating RavenDB features and integration scenarios. Hub page at `/samples` with tag-based filtering.
+
+**Frontmatter**: `title`, `description`, `challenges_solutions_tags`, `feature_tags`, `tech_stack_tags`, `image`, `img_alt`, `category`, `license`, `license_url`, `repository_url`, `languages`, `gallery`.
+
+**Tags**: Three categories defined in `samples/tags/`:
+- `challenges-solutions.yml` - Business problems solved (e.g., `semantic-search`, `integration-patterns`)
+- `feature.yml` - RavenDB features demonstrated (e.g., `vector-search`, `document-refresh`)
+- `tech-stack.yml` - Technologies used (e.g., `csharp`, `aspire`, `azure-functions`)
+
+All tag values use kebab-case.
+
+**Indexed by**: `src/plugins/recent-samples-plugin.ts`
 
 ### `templates/` — Authoring reference templates (~9 files)
-Style guide and live examples for documentation building blocks: ContentFrame/Panel layouts, icon gallery, themed images, tag reference, see-also cross-links, featured/new guide blocks.
+Style guide and live examples for documentation building blocks: ContentFrame/Panel layouts, icon gallery, themed images, tag reference, see-also cross-links, featured/new guide blocks, sample authoring templates.
 
 ---
 

diff --git a/cloud/home.mdx b/cloud/home.mdx
@@ -2,7 +2,7 @@
 slug: /
 pagination_next: null
 pagination_prev: null
-wrapperClassName: cloud-home-page
+wrapperClassName: cloudHomePage
 hide_table_of_contents: true
 ---
 

diff --git a/docs/ai-integration/ai-agents/start.mdx b/docs/ai-integration/ai-agents/start.mdx
@@ -3,6 +3,15 @@ title: "AI Agents: Start"
 sidebar_label: Start
 description: "Create conversational AI agent proxies that connect RavenDB clients to AI models for question answering, data analysis, and workflow automation."
 sidebar_position: 0
+see_also:
+  - title: "Sample: Human Resources Assistant"
+    link: "/samples/human-resources-assistant"
+    source: "samples"
+    path: "Samples > AI Agents"
+  - title: "Sample: Fit Assistant"
+    link: "/samples/fit-assistant"
+    source: "samples"
+    path: "Samples > AI Agents"
 ---
 
 import Admonition from '@theme/Admonition';
@@ -52,4 +61,3 @@ Watch our webinars to see AI agents in action and learn practical implementation
     <CardWithImageHorizontal title="How to use AI attachments and stop burning tokens on repetitive file uploads" description="Watch a tutorial on using attachments efficiently with AI agents." url="https://www.youtube.com/watch?v=QphtDGe23WE" imgSrc={webinarThumbnailPlaceholder} imgAlt="How to use AI attachments and stop burning tokens on repetitive file uploads" />
     <CardWithImageHorizontal title="How to use multi-agents and sub-agents without wasting tokens or risking any data" description="Watch a tutorial on the multi-agent and sub-agent pattern in RavenDB." url="https://www.youtube.com/watch?v=QxGYSfNrT5U" imgSrc={webinarThumbnailPlaceholder} imgAlt="How to use multi-agents and sub-agents without wasting tokens or risking any data" />
 </ColGrid>
-
diff --git a/docs/ai-integration/gen-ai-integration/start.mdx b/docs/ai-integration/gen-ai-integration/start.mdx
@@ -3,6 +3,15 @@ title: "GenAI tasks: Start"
 sidebar_label: Start
 description: "Build intelligent workflows with GenAI tasks that continuously monitor collections and process documents as they are added or modified."
 sidebar_position: 0
+see_also:
+  - title: "Sample: BrainSlop"
+    link: "/samples/brain-slop"
+    source: "samples"
+    path: "Samples > GenAI Workflows"
+  - title: "Sample: Verity"
+    link: "/samples/verity"
+    source: "samples"
+    path: "Samples > GenAI Workflows"
 ---
 
 import Admonition from '@theme/Admonition';

diff --git a/docs/ai-integration/vector-search/overview.mdx b/docs/ai-integration/vector-search/overview.mdx
@@ -3,6 +3,15 @@ title: "Vector Search - Overview"
 sidebar_label: "Overview"
 description: "RavenDB serves as a vector database, combining traditional document storage with semantic vector search for AI-powered applications."
 sidebar_position: 1
+see_also:
+  - title: "Sample: The Library of Ravens"
+    link: "/samples/the-ravens-library"
+    source: "samples"
+    path: "Samples > Semantic Search"
+  - title: "Sample: Human Resources Assistant"
+    link: "/samples/human-resources-assistant"
+    source: "samples"
+    path: "Samples > Semantic Search"
 ---
 
 import Admonition from '@theme/Admonition';
@@ -238,4 +247,4 @@ It explains how to define the index, configure indexing & query-time parameters,
 
 </Admonition>
 
-</Panel>
+</Panel>
diff --git a/docs/client-api/session/querying/text-search/full-text-search.mdx b/docs/client-api/session/querying/text-search/full-text-search.mdx
@@ -25,6 +25,10 @@ see_also:
        link: "indexes/querying/searching"
        source: "docs"
        path: "Indexes > Querying"
+     - title: "Hugin"
+       link: "/samples/hugin"
+       source: "samples"
+       path: "Samples > Offline Search"
 ---
 
 import LanguageSwitcher from "@site/src/components/LanguageSwitcher";
@@ -55,4 +59,3 @@ import FullTextSearchNodejs from './content/_full-text-search-nodejs.mdx';
 </LanguageContent>
 
 
-
diff --git a/docs/home.mdx b/docs/home.mdx
@@ -3,7 +3,7 @@ slug: /
 title: "Guides, API Reference & Tutorials"
 pagination_next: null
 pagination_prev: null
-wrapperClassName: docs-home-page
+wrapperClassName: docsHomePage
 hide_table_of_contents: true
 description: "Official RavenDB documentation. Guides for installation, client APIs, indexing, querying, AI integration, clustering, security, and the Studio UI across all supported versions."
 keywords:

diff --git a/docs/indexes/search-engine/corax.mdx b/docs/indexes/search-engine/corax.mdx
@@ -3,6 +3,11 @@ title: "Search Engine: Corax"
 sidebar_label: Corax
 description: "Corax is RavenDB's native search engine, offering faster indexing and querying performance as an alternative to the Lucene engine."
 sidebar_position: 0
+see_also:
+     - title: "Hugin"
+       link: "/samples/hugin"
+       source: "samples"
+       path: "Samples > Offline Search"
 ---
 
 import Admonition from '@theme/Admonition';
@@ -600,4 +605,3 @@ process will add unnecessary overhead.
 
 
 
-
diff --git a/docs/server/ongoing-tasks/etl/olap.mdx b/docs/server/ongoing-tasks/etl/olap.mdx
@@ -3,6 +3,11 @@ title: "Ongoing Tasks: OLAP ETL"
 sidebar_label: OLAP ETL
 description: "Export RavenDB data to Apache Parquet files on S3, Azure, or local storage using OLAP ETL tasks for analytics and data warehouse workloads."
 sidebar_position: 3
+see_also:
+  - title: "Sample: Fit Assistant"
+    link: "/samples/fit-assistant"
+    source: "samples"
+    path: "Samples > Reporting Offload"
 ---
 
 import Admonition from '@theme/Admonition';
@@ -437,4 +442,3 @@ instead of rows being stored together (the same fields from multiple documents,
 whole documents). This makes queries more efficient.  
 
 
-
diff --git a/docs/server/ongoing-tasks/etl/queue-etl/overview.mdx b/docs/server/ongoing-tasks/etl/queue-etl/overview.mdx
@@ -3,6 +3,15 @@ title: "Queue ETL Overview"
 sidebar_label: Overview
 description: "Send RavenDB document changes to message queues like Kafka, RabbitMQ, Amazon SQS, and Azure Queue using queue ETL tasks."
 sidebar_position: 0
+see_also:
+  - title: "Sample: Fit Assistant"
+    link: "/samples/fit-assistant"
+    source: "samples"
+    path: "Samples > Durable Event Delivery"
+  - title: "Sample: Verity"
+    link: "/samples/verity"
+    source: "samples"
+    path: "Samples > Durable Event Delivery"
 ---
 
 import Admonition from '@theme/Admonition';
@@ -138,4 +147,3 @@ to see various statistics related to data extraction, transformation, and loadin
 
 
 
-
diff --git a/docs/server/storage/documents-compression.mdx b/docs/server/storage/documents-compression.mdx
@@ -29,6 +29,10 @@ see_also:
        link: "studio/database/settings/database-record"
        source: "docs"
        path: "Studio > Database Management > Settings"
+     - title: "Hugin"
+       link: "/samples/hugin"
+       source: "samples"
+       path: "Samples > Offline Search"
 ---
 
 import LanguageSwitcher from "@site/src/components/LanguageSwitcher";
@@ -49,4 +53,3 @@ import DocumentsCompressionNodejs from './content/_documents-compression-nodejs.
 </LanguageContent>
 
 
-
diff --git a/docs/start/test-driver.mdx b/docs/start/test-driver.mdx
@@ -17,6 +17,10 @@ see_also:
        link: "server/troubleshooting/collect-info"
        source: "docs"
        path: "Server > Troubleshooting"
+     - title: "Sample: YABT"
+       link: "/samples/yabt"
+       source: "samples"
+       path: "Samples > Tested Application Architecture"
 ---
 
 import LanguageSwitcher from "@site/src/components/LanguageSwitcher";
@@ -37,4 +41,3 @@ import TestDriverJava from './content/_test-driver-java.mdx';
 </LanguageContent>
 
 
-
diff --git a/docusaurus.config.ts b/docusaurus.config.ts
@@ -117,6 +117,15 @@ const config: Config = {
                 showLastUpdateTime: true,
             },
         ],
+        [
+            "content-docs",
+            {
+                id: "samples",
+                path: "samples",
+                routeBasePath: "samples",
+                sidebarPath: require.resolve("./sidebarsSamples.js"),
+            },
+        ],
         [
             "@docusaurus/plugin-ideal-image",
             {
@@ -129,6 +138,7 @@ const config: Config = {
         ],
         require.resolve("./src/plugins/recent-guides-plugin"),
         require.resolve("./src/plugins/versioned-seo-plugin"),
+        require.resolve("./src/plugins/recent-samples-plugin"),
     ],
     headTags: [
         {

diff --git a/eslint.config.js b/eslint.config.js
@@ -74,7 +74,7 @@ module.exports = [
             "@typescript-eslint/no-explicit-any": "off",
             "@typescript-eslint/prefer-namespace-keyword": "off",
 
-            "no-console": "warn",
+            "no-console": ["warn", { allow: ["warn", "error"] }],
             "no-debugger": "error",
             "no-alert": "warn",
             "no-var": "error",
@@ -101,6 +101,12 @@ module.exports = [
             "no-undef": "off",
         },
     },
+    {
+        files: ["**/*.ts", "**/*.tsx"],
+        rules: {
+            "no-undef": "off",
+        },
+    },
     {
         ignores: [
             "node_modules/",

diff --git a/guides/ai-agents-attachments.mdx b/guides/ai-agents-attachments.mdx
@@ -3,9 +3,9 @@ title: "Beyond Text: Adding File Attachments to RavenDB AI Agents"
 tags: [ai, attachments, csharp, demo, use-case]
 icon: "ai-agents"
 description: "Learn how to attach binary files such as PDFs and images to RavenDB AI Agent conversations, reducing token usage while keeping files accessible across the conversation lifecycle."
-publishedAt: 2026-04-15
+published_at: 2026-04-15
 author: "Paweł Lachowski"
-proficiencyLevel: "Intermediate"
+proficiency_level: "Intermediate"
 see_also:
   - title: "AI Agents Overview"
     link: "ai-integration/ai-agents/overview"
@@ -15,6 +15,10 @@ see_also:
     link: "document-extensions/attachments/overview"
     source: "docs"
     path: "Document Extensions > Attachments"
+  - title: "Sample: Human Resources Assistant"
+    link: "/samples/human-resources-assistant"
+    source: "samples"
+    path: "Samples > AI Agents"
 ---
 
 import Admonition from '@theme/Admonition';