update skills

Co-authored-by: Ona <no-reply@ona.com>

Author: ldoguin

.github/workflows/validate.yml

@@ -0,0 +1,21 @@
+name: Validate Skills
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Self-test validator
+        run: bash scripts/test-validator.sh
+
+      - name: Validate skill structure
+        run: bash scripts/validate-skills.sh
+
+      - name: Check handoff blocks in sync with routing.yaml
+        run: bash scripts/sync-handoffs.sh

AGENTS.md

@@ -21,6 +21,16 @@ A collection of Couchbase agent skills for use in agentic workflows. Each skill
 | [`sqlpp-language`](skills/sqlpp-language/) | SQL++ syntax — MISSING vs NULL, META().id, UNNEST, ANY/SATISFIES, ARRAY, JOIN, MERGE, window functions |
 | [`error-handling`](skills/error-handling/) | AmbiguousTimeout vs UnambiguousTimeout, common exceptions, retry patterns, sdk-doctor, debug logging |
 | [`caching-patterns`](skills/caching-patterns/) | TTL, cache-aside, write-through, getAndTouch, session storage, rate limiting, ephemeral buckets |
+| [`testing-patterns`](skills/testing-patterns/) | Testing strategy, test data management, scope/collection isolation — concepts only (no language code) |
+| [`testing-patterns-python`](skills/testing-patterns-python/) | Unit testing with unittest.mock, integration testing with testcontainers, scope isolation — Python |
+| [`testing-patterns-java`](skills/testing-patterns-java/) | Unit testing with Mockito, integration testing with testcontainers, scope isolation — Java |
+| [`testing-patterns-go`](skills/testing-patterns-go/) | Unit testing with testify/mock, integration testing with testcontainers, scope isolation — Go |
+| [`testing-patterns-dotnet`](skills/testing-patterns-dotnet/) | Unit testing with Moq, integration testing with Testcontainers.Couchbase, scope isolation — .NET |
+| [`testing-patterns-nodejs`](skills/testing-patterns-nodejs/) | Unit testing with Jest, integration testing with testcontainers, scope isolation — Node.js |
+| [`testing-patterns-rust`](skills/testing-patterns-rust/) | Unit testing with mockall, integration testing with testcontainers-rs, scope isolation — Rust |
+| [`testing-patterns-scala`](skills/testing-patterns-scala/) | Unit testing with ScalaMock, integration testing with testcontainers-scala, scope isolation — Scala |
+| [`testing-patterns-php`](skills/testing-patterns-php/) | Unit testing with PHPUnit, integration testing with testcontainers, scope isolation — PHP |
+| [`testing-patterns-ruby`](skills/testing-patterns-ruby/) | Unit testing with RSpec doubles, integration testing with testcontainers-ruby, scope isolation — Ruby |
 
 ### Couchbase Capella (DBaaS)
 
@@ -37,6 +47,16 @@ A collection of Couchbase agent skills for use in agentic workflows. Each skill
 | [`server-query-optimizer`](skills/server-query-optimizer/) | Diagnose slow queries, recommend GSI indexes, analyze EXPLAIN output, aggregate pushdown |
 | [`eventing`](skills/eventing/) | Document-triggered functions — enrichment, cascade delete, timers, curl(), webhooks |
 | [`security`](skills/security/) | RBAC users, roles, least-privilege patterns, LDAP, SAML/SSO, TLS |
+| [`fle`](skills/fle/) | Field-Level Encryption — client-side field encryption, CryptoManager, supported SDKs, key management |
+| [`fle-python`](skills/fle-python/) | FLE with Python SDK — CryptoManager setup, encrypt/decrypt fields |
+| [`fle-java`](skills/fle-java/) | FLE with Java SDK — CryptoManager, @Encrypted annotation |
+| [`fle-go`](skills/fle-go/) | FLE with Go SDK — CryptoManager, EncryptingTranscoder |
+| [`fle-dotnet`](skills/fle-dotnet/) | FLE with .NET SDK — CryptoManager, [EncryptedField] attribute |
+| [`fle-nodejs`](skills/fle-nodejs/) | FLE with Node.js SDK — CryptoManager, encryptFields option |
+| [`fle-php`](skills/fle-php/) | FLE with PHP SDK — CryptoManager, encryptFields option |
+| [`fle-rust`](skills/fle-rust/) | FLE not supported in Rust SDK 1.0 — application-code alternatives |
+| [`fle-scala`](skills/fle-scala/) | FLE not supported in Scala SDK — application-code alternatives |
+| [`fle-ruby`](skills/fle-ruby/) | FLE not supported in Ruby SDK 3.x — application-code alternatives |
 | [`xdcr`](skills/xdcr/) | Cross-datacenter replication — setup, topologies, filtering, conflict resolution |
 | [`cluster-ops`](skills/cluster-ops/) | Replicas, failover, rebalance, MDS service topology, server groups |
 | [`kafka`](skills/kafka/) | Kafka Connect source/sink, DCP streaming, transactional outbox pattern |
@@ -61,6 +81,9 @@ A collection of Couchbase agent skills for use in agentic workflows. Each skill
 
 #### SDK Connection (per language)
 
+> Each skill includes `references/deployment-scenarios.md` with language-specific Serverless, OLTP, OLAP, High-Traffic, and Multi-Node connection examples.
+
+
 | Skill | Description |
 |---|---|
 | [`server-connection-python`](skills/server-connection-python/) | Python SDK connection pools, timeouts, singleton, sub-document, durability |
@@ -86,6 +109,14 @@ A collection of Couchbase agent skills for use in agentic workflows. Each skill
 | [`transactions-nodejs`](skills/transactions-nodejs/) | ACID multi-document transactions with Node.js SDK — error handling, durability |
 | [`transactions-scala`](skills/transactions-scala/) | ACID multi-document transactions with Scala SDK — sync/async/reactive, error handling |
 | [`transactions-php`](skills/transactions-php/) | ACID multi-document transactions with PHP SDK — error handling, durability |
+| [`transactions-ruby`](skills/transactions-ruby/) | Transactions not supported in Ruby SDK 3.x — CAS, sub-document atomics, saga pattern alternatives |
+| [`transactions-rust`](skills/transactions-rust/) | Transactions not supported in Rust SDK 1.0 — CAS, sub-document atomics, saga pattern alternatives |
+
+#### Full-Text & Vector Search (concept)
+
+| Skill | Description |
+|---|---|
+| [`search-concepts`](skills/search-concepts/) | FTS, vector search, hybrid search, Flex Index, RAG pipeline — concepts and index setup |
 
 #### Full-Text & Vector Search (per language)
 
@@ -103,7 +134,7 @@ A collection of Couchbase agent skills for use in agentic workflows. Each skill
 
 #### Analytics (per language)
 
-> Rust SDK 1.0, Scala SDK, PHP SDK, and Ruby SDK do not support the Analytics service.
+> Rust SDK 1.0 does not support the Analytics service.
 
 | Skill | Description |
 |---|---|
@@ -113,6 +144,10 @@ A collection of Couchbase agent skills for use in agentic workflows. Each skill
 | [`analytics-go`](skills/analytics-go/) | OLAP queries, window functions, Analytics datasets with Go SDK |
 | [`analytics-dotnet`](skills/analytics-dotnet/) | OLAP queries, window functions, Analytics datasets with .NET SDK |
 | [`analytics-nodejs`](skills/analytics-nodejs/) | OLAP queries, window functions, Analytics datasets with Node.js SDK |
+| [`analytics-scala`](skills/analytics-scala/) | OLAP queries, window functions, Analytics datasets with Scala SDK |
+| [`analytics-php`](skills/analytics-php/) | OLAP queries, window functions, Analytics datasets with PHP SDK |
+| [`analytics-ruby`](skills/analytics-ruby/) | OLAP queries, window functions, Analytics datasets with Ruby SDK |
+| [`analytics-rust`](skills/analytics-rust/) | Analytics Service not supported in Rust SDK 1.0 — REST API and SQL++ query alternatives |
 
 #### SDK Patterns (per language)
 
@@ -179,6 +214,8 @@ metadata:
   last_verified: "2026-05"   # update to current YYYY-MM when you materially edit skill content
   min_server_version: "7.0"  # optional — minimum Couchbase Server version
   deprecated_by: other-skill # optional — set when this skill is superseded
+  deprecated_since: "8.0"    # optional — version from which deprecated_by applies
+  max_server_version: "7.6"  # optional — last version this skill applies to
   handoff:                    # generated from routing.yaml — do not edit manually
     - condition: "user asks about slow queries"
       skill: server-query-optimizer
@@ -194,10 +231,12 @@ metadata:
 | File | Shared by |
 |---|---|
 | [`shared/server/sdk-connection-concepts.md`](shared/server/sdk-connection-concepts.md) | all server-connection-* skills (9 languages) |
-| [`shared/server/deployment-scenarios.md`](shared/server/deployment-scenarios.md) | all server-connection-* skills — serverless, OLTP, OLAP, multi-node topology |
+| [`shared/server/durability.md`](shared/server/durability.md) | all server-connection-* skills (9 languages) — guidance on when to use each durability level |
+| [`shared/server/subdocument.md`](shared/server/subdocument.md) | all server-connection-* and sdk-patterns-* skills — lookup_in, mutate_in, array ops, counters |
 | [`shared/server/sql-syntax.md`](shared/server/sql-syntax.md) | all server-querying-* skills (9 languages) — SELECT, JOINs, MERGE, window functions |
 | [`shared/server/analytics-vs-query.md`](shared/server/analytics-vs-query.md) | all analytics-* skills (8 languages) — when to use Analytics vs Query Service |
 | [`shared/server/search-concepts.md`](shared/server/search-concepts.md) | all search-* skills (9 languages) — index prerequisites, hybrid search, RYOW, pagination, query types |
+| [`shared/server/testing-mock-examples.md`](shared/server/testing-mock-examples.md) | all testing-patterns-* skills (9 languages) — mock pattern reference |
 | [`shared/mobile/cbl-core.md`](shared/mobile/cbl-core.md) | mobile-android, mobile-ios |
 | [`shared/mobile/sync-architecture.md`](shared/mobile/sync-architecture.md) | mobile-sync-android, mobile-sync-ios |
 | [`shared/mobile/conflict-resolution-concepts.md`](shared/mobile/conflict-resolution-concepts.md) | mobile-conflict-resolution-android, mobile-conflict-resolution-ios |
@@ -206,6 +245,12 @@ metadata:
 | [`shared/mobile/testing-concepts.md`](shared/mobile/testing-concepts.md) | mobile-testing-android, mobile-testing-ios |
 | [`shared/mobile/vector-search-concepts.md`](shared/mobile/vector-search-concepts.md) | mobile-vector-search-android, mobile-vector-search-ios |
 
+### `references/` vs `shared/` policy
+
+- **`shared/`** — content that is language-agnostic and applies to multiple skill families. Add here when the same concepts or multi-language examples would otherwise be duplicated across 3+ skills. Link from SKILL.md with `../../shared/...`.
+- **`references/`** inside a skill — content that is specific to that skill's language or narrow topic (e.g., language-specific bulk-ops patterns, reactive API details). Do not put multi-language content here; promote it to `shared/` instead.
+- **Rule**: if a `references/` file is identical or near-identical across two or more language skills, it belongs in `shared/`.
+
 ## Discovery Manifest
 
 [`discovery.yaml`](discovery.yaml) — canonical source for first-turn routing. Each entry defines `skill`, `priority` (`primary`/`secondary`), `use_when`, and `triggers`. The validator enforces no duplicate triggers across skills and a minimum of 3 triggers per skill. Do **not** add these fields to individual SKILL.md files.
@@ -229,6 +274,8 @@ Runnable helper scripts in `scripts/`:
 |---|---|
 | [`validate-skills.sh`](scripts/validate-skills.sh) | Validate all skills for structural correctness (no cluster needed) |
 | [`sync-handoffs.sh`](scripts/sync-handoffs.sh) | Sync SKILL.md handoff: blocks from routing.yaml (dry-run by default; `--apply` to write) |
+| [`eval.sh`](scripts/eval.sh) | List eval cases (`--dry-run`) or run them against an LLM (`--execute`, not yet implemented) |
+| [`test-validator.sh`](scripts/test-validator.sh) | Self-test for validate-skills.sh — runs assertions against a minimal fixture tree |
 | [`check-cluster.sh`](scripts/check-cluster.sh) | Verify cluster connectivity and run SQL++ smoke tests against travel-sample |
 | [`explain-query.sh`](scripts/explain-query.sh) | Run EXPLAIN and highlight plan warnings |
 | [`create-gsi-index.sh`](scripts/create-gsi-index.sh) | Create a GSI index via REST API |
@@ -286,7 +333,20 @@ cases:
 
 Keep `input` realistic — use actual user phrasings, not test descriptions. Keep `expect` terms specific enough to distinguish correct from incorrect responses.
 
-> **Eval execution status:** The `examples.md` frontmatter is a specification for LLM-based evaluation — it defines what a correct agent response must contain. `validate-skills.sh` checks structural validity (required fields, recognised language identifiers) but does not execute the cases against an LLM. `check-cluster.sh` tests cluster connectivity via SQL++ smoke tests only and does not read `examples.md`. To run a full eval, send each `input` to an LLM with the skill loaded and assert that `expect` terms appear and `reject` terms do not appear in the response.
+**Markdown body** (after the closing `---`): the body is human-readable documentation of the same cases. Each example follows this structure:
+
+```markdown
+## Example N
+
+**Input:** <same text as the frontmatter input field>
+
+**Output:**
+<representative ideal response, including code blocks where relevant>
+```
+
+The body is not parsed by tooling — it exists for human review and as a reference when writing or updating eval cases. Keep it in sync with the frontmatter cases (same order, same inputs).
+
+> **Eval execution status:** The `examples.md` frontmatter is a specification for LLM-based evaluation — it defines what a correct agent response must contain. `validate-skills.sh` checks structural validity (required fields, recognised language identifiers) but does not execute the cases against an LLM. `check-cluster.sh` tests cluster connectivity via SQL++ smoke tests only and does not read `examples.md`. Use `scripts/eval.sh --dry-run` to list all cases; `--execute` (not yet implemented) will run them against an LLM.
 
 ## Skill Layout