Instruction Enforcement

Author: azzazzel

.agents/PINECONE-go.md

@@ -4,6 +4,21 @@
 
 This guide provides Go-specific patterns, examples, and best practices for the Pinecone SDK.
 
+## 🚨 MANDATORY RULES - Read First
+
+**⚠️ CRITICAL: These rules MUST be followed. Violations will cause runtime errors or data issues.**
+
+1. **MUST use namespaces** - Every operation MUST use `.WithNamespace()` method
+2. **MUST wait 10+ seconds** - After upserting records, MUST wait 10+ seconds before searching
+3. **MUST match field_map** - Record field names MUST match the right side of `--field_map` used when creating index
+4. **MUST respect batch limits** - Text records: MAX 96 per batch, Vector records: MAX 1000 per batch
+5. **MUST use flat metadata** - No nested objects allowed, only flat key-value pairs
+6. **MUST use safe type assertions** - Use `ok` check: `val, ok := field.(string)`
+7. **MUST pass context** - All operations require `context.Context` parameter
+8. **MUST verify before installing** - Check if SDK/CLI already installed before prompting installation
+
+**Before proceeding with any operation, verify these rules are followed. See detailed sections below for implementation.**
+
 ## Installation & Setup
 
 > **⚠️ IMPORTANT**: See [PINECONE.md](./PINECONE.md#-mandatory-always-use-latest-version) for the mandatory requirement to always use the latest version when creating projects.
@@ -467,9 +482,11 @@ if err != nil {
 
 ### Semantic Search with Reranking (Best Practice)
 
+**Note**: Reranking is a best practice for production quality results. Quickstarts include reranking to demonstrate usage.
+
 ```go
 func searchWithRerank(indexConn *pinecone.IndexConnection, namespace string, queryText string, topK int) (*pinecone.SearchRecordsResponse, error) {
-    // Standard search pattern - always rerank for production
+    // Best practice: Use reranking for production quality results. This pattern is shown in quickstarts.
     ctx := context.Background()
     results, err := indexConn.WithNamespace(namespace).SearchRecords(ctx, &pinecone.SearchRecordsRequest{
         Query: &pinecone.SearchRecordsRequestQuery{

.agents/PINECONE-java.md

@@ -4,6 +4,20 @@
 
 This guide provides Java-specific patterns, examples, and best practices for the Pinecone SDK.
 
+## 🚨 MANDATORY RULES - Read First
+
+**⚠️ CRITICAL: These rules MUST be followed. Violations will cause runtime errors or data issues.**
+
+1. **MUST use namespaces** - Every upsert, search, fetch, delete operation MUST specify a namespace parameter
+2. **MUST wait 10+ seconds** - After upserting records, MUST wait 10+ seconds before searching
+3. **MUST match field_map** - Record field names MUST match the right side of `--field_map` used when creating index
+4. **MUST respect batch limits** - Text records: MAX 96 per batch, Vector records: MAX 1000 per batch
+5. **MUST use flat metadata** - No nested objects allowed, only flat key-value pairs
+6. **MUST handle exceptions** - All operations can throw exceptions, MUST use try-catch
+7. **MUST verify before installing** - Check if SDK/CLI already installed before prompting installation
+
+**Before proceeding with any operation, verify these rules are followed. See detailed sections below for implementation.**
+
 ## Installation & Setup
 
 > **⚠️ IMPORTANT**: See [PINECONE.md](./PINECONE.md#-mandatory-always-use-latest-version) for the mandatory requirement to always use the latest version when creating projects.
@@ -363,14 +377,16 @@ List<String> docsOnly = listAllIds("user_123", "doc_");
 
 ### Semantic Search with Reranking (Best Practice)
 
+**Note**: Reranking is a best practice for production quality results. Quickstarts include reranking to demonstrate usage.
+
 ```java
 import io.pinecone.clients.Index;
 import org.openapitools.db_data.client.model.SearchRecordsRequestRerank;
 import org.openapitools.db_data.client.model.SearchRecordsResponse;
 import java.util.*;
 
 public SearchRecordsResponse searchWithRerank(String namespace, String queryText, int topK) {
-    // Standard search pattern - always rerank for production
+    // Best practice: Use reranking for production quality results. This pattern is shown in quickstarts.
 
     // Configure reranking
     SearchRecordsRequestRerank rerank = new SearchRecordsRequestRerank()
@@ -985,7 +1001,7 @@ SearchRecordsResponse basicResults = index.searchRecordsByText(
     queryText, namespace, Arrays.asList("content"), 5, null, null
 );
 
-// ✅ BETTER - always rerank in production
+// ✅ BETTER - use reranking for best results (best practice)
 SearchRecordsRequestRerank rerank = new SearchRecordsRequestRerank()
     .model("bge-reranker-v2-m3")
     .topN(5)

.agents/PINECONE-python.md

@@ -4,6 +4,20 @@
 
 This guide provides Python-specific patterns, examples, and best practices for the Pinecone SDK.
 
+## 🚨 MANDATORY RULES - Read First
+
+**⚠️ CRITICAL: These rules MUST be followed. Violations will cause runtime errors or data issues.**
+
+1. **MUST use namespaces** - Every upsert, search, fetch, delete operation MUST specify a namespace
+2. **MUST wait 10+ seconds** - After upserting records, MUST wait 10+ seconds before searching
+3. **MUST match field_map** - Record field names MUST match the right side of `--field_map` used when creating index
+4. **MUST respect batch limits** - Text records: MAX 96 per batch, Vector records: MAX 1000 per batch
+5. **MUST use flat metadata** - No nested objects allowed, only flat key-value pairs
+6. **MUST use `pinecone` package** - NOT `pinecone-client` (deprecated, causes errors)
+7. **MUST verify before installing** - Check if SDK/CLI already installed before prompting installation
+
+**Before proceeding with any operation, verify these rules are followed. See detailed sections below for implementation.**
+
 ## Installation & Setup
 
 > **⚠️ IMPORTANT**: See [PINECONE.md](./PINECONE.md#-mandatory-always-use-latest-version) for the mandatory requirement to always use the latest version when creating projects.
@@ -269,6 +283,13 @@ for hit in reranked_results.result.hits:
 
 ### Upserting Records
 
+**⚠️ Before upserting, verify:**
+
+1. Namespace is specified (MANDATORY)
+2. Field names match `--field_map` used when creating index (MANDATORY)
+3. Batch size ≤ 96 records for text, ≤ 1000 for vectors (MANDATORY)
+4. Metadata is flat (no nested objects) (MANDATORY)
+
 ```python
 # Indexes with integrated embeddings
 records = [
@@ -370,9 +391,17 @@ docs_only = list_all_ids(index, "user_123", prefix="doc_")
 
 ### Semantic Search with Reranking (Best Practice)
 
+**⚠️ Before searching, verify:**
+
+1. Namespace is specified (MANDATORY)
+2. Wait 10+ seconds after upserting before searching (MANDATORY)
+3. Field name in query matches `--field_map` (MANDATORY)
+
+**Note**: Reranking is a best practice for production quality results. Quickstarts include reranking to demonstrate usage.
+
 ```python
 def search_with_rerank(index, namespace, query_text, top_k=5):
-    """Standard search pattern - always rerank for production"""
+    """Best practice: Use reranking for production quality results. This pattern is shown in quickstarts."""
     results = index.search(
         namespace=namespace,
         query={

.agents/PINECONE-quickstart.md

@@ -226,18 +226,66 @@ The following sample data should be used for the Quick Test across all languages
 
 ```json
 [
-  { "_id": "rec1", "content": "The Eiffel Tower was completed in 1889 and stands in Paris, France.", "category": "history" },
-  { "_id": "rec2", "content": "Photosynthesis allows plants to convert sunlight into energy.", "category": "science" },
-  { "_id": "rec5", "content": "Shakespeare wrote many famous plays, including Hamlet and Macbeth.", "category": "literature" },
-  { "_id": "rec7", "content": "The Great Wall of China was built to protect against invasions.", "category": "history" },
-  { "_id": "rec15", "content": "Leonardo da Vinci painted the Mona Lisa.", "category": "art" },
-  { "_id": "rec17", "content": "The Pyramids of Giza are among the Seven Wonders of the Ancient World.", "category": "history" },
-  { "_id": "rec21", "content": "The Statue of Liberty was a gift from France to the United States.", "category": "history" },
-  { "_id": "rec26", "content": "Rome was once the center of a vast empire.", "category": "history" },
-  { "_id": "rec33", "content": "The violin is a string instrument commonly used in orchestras.", "category": "music" },
-  { "_id": "rec38", "content": "The Taj Mahal is a mausoleum built by Emperor Shah Jahan.", "category": "history" },
-  { "_id": "rec48", "content": "Vincent van Gogh painted Starry Night.", "category": "art" },
-  { "_id": "rec50", "content": "Renewable energy sources include wind, solar, and hydroelectric power.", "category": "energy" }
+  {
+    "_id": "rec1",
+    "content": "The Eiffel Tower was completed in 1889 and stands in Paris, France.",
+    "category": "history"
+  },
+  {
+    "_id": "rec2",
+    "content": "Photosynthesis allows plants to convert sunlight into energy.",
+    "category": "science"
+  },
+  {
+    "_id": "rec5",
+    "content": "Shakespeare wrote many famous plays, including Hamlet and Macbeth.",
+    "category": "literature"
+  },
+  {
+    "_id": "rec7",
+    "content": "The Great Wall of China was built to protect against invasions.",
+    "category": "history"
+  },
+  {
+    "_id": "rec15",
+    "content": "Leonardo da Vinci painted the Mona Lisa.",
+    "category": "art"
+  },
+  {
+    "_id": "rec17",
+    "content": "The Pyramids of Giza are among the Seven Wonders of the Ancient World.",
+    "category": "history"
+  },
+  {
+    "_id": "rec21",
+    "content": "The Statue of Liberty was a gift from France to the United States.",
+    "category": "history"
+  },
+  {
+    "_id": "rec26",
+    "content": "Rome was once the center of a vast empire.",
+    "category": "history"
+  },
+  {
+    "_id": "rec33",
+    "content": "The violin is a string instrument commonly used in orchestras.",
+    "category": "music"
+  },
+  {
+    "_id": "rec38",
+    "content": "The Taj Mahal is a mausoleum built by Emperor Shah Jahan.",
+    "category": "history"
+  },
+  {
+    "_id": "rec48",
+    "content": "Vincent van Gogh painted Starry Night.",
+    "category": "art"
+  },
+  {
+    "_id": "rec50",
+    "content": "Renewable energy sources include wind, solar, and hydroelectric power.",
+    "category": "energy"
+  }
 ]
 ```
 
@@ -284,7 +332,7 @@ pc index create -n agentic-quickstart-search -m cosine -c aws -r us-east-1 --mod
 ### Production Patterns
 
 - Always use shielded namespaces
-- Always rerank results
+- Use reranking for best results (included in quickstart examples)
 - Implement exponential backoff retry
 - Handle edge cases gracefully
 
@@ -438,4 +486,4 @@ For comprehensive troubleshooting guidance, see [PINECONE-troubleshooting.md](./
 
 ---
 
-**Remember**: Always use namespaces, always rerank, always handle errors with retry logic.
+**Remember**: Always use namespaces, use reranking for best results (shown in examples), always handle errors with retry logic.

.agents/PINECONE-troubleshooting.md

@@ -259,4 +259,4 @@ If you're still experiencing issues:
 
 ---
 
-**Remember**: Always use namespaces, always rerank, always handle errors with retry logic, and account for eventual consistency delays.
+**Remember**: Always use namespaces, use reranking for best results (shown in quickstarts), always handle errors with retry logic, and account for eventual consistency delays.

.agents/PINECONE-typescript.md

@@ -4,6 +4,21 @@
 
 This guide provides TypeScript/Node.js-specific patterns, examples, and best practices for the Pinecone SDK.
 
+## 🚨 MANDATORY RULES - Read First
+
+**⚠️ CRITICAL: These rules MUST be followed. Violations will cause runtime errors or data issues.**
+
+1. **MUST use namespaces** - Every upsert, search, fetch, delete operation MUST use `.namespace()` method
+2. **MUST wait 10+ seconds** - After upserting records, MUST wait 10+ seconds before searching
+3. **MUST match field_map** - Record field names MUST match the right side of `--field_map` used when creating index
+4. **MUST respect batch limits** - Text records: MAX 96 per batch, Vector records: MAX 1000 per batch
+5. **MUST use flat metadata** - No nested objects allowed, only flat key-value pairs
+6. **MUST cast `hit.fields`** - TypeScript requires explicit casting: `hit.fields as Record<string, any>`
+7. **MUST use `await`** - All SDK operations are async, MUST use `await` keyword
+8. **MUST verify before installing** - Check if SDK/CLI already installed before prompting installation
+
+**Before proceeding with any operation, verify these rules are followed. See detailed sections below for implementation.**
+
 ## Installation & Setup
 
 > **⚠️ IMPORTANT**: See [PINECONE.md](./PINECONE.md#-mandatory-always-use-latest-version) for the mandatory requirement to always use the latest version when creating projects.
@@ -373,14 +388,16 @@ const docsOnly = await listAllIds(index, "user_123", "doc_");
 
 ### Semantic Search with Reranking (Best Practice)
 
+**Note**: Reranking is a best practice for production quality results. Quickstarts include reranking to demonstrate usage.
+
 ```typescript
 async function searchWithRerank(
   index: any,
   namespace: string,
   queryText: string,
   topK: number = 5
 ) {
-  // Standard search pattern - always rerank for production
+  // Best practice: Use reranking for production quality results. This pattern is shown in quickstarts.
   const results = await index.namespace(namespace).searchRecords({
     query: {
       topK: topK * 2, // more candidates for reranking
@@ -908,7 +925,7 @@ const results = await index.namespace("ns").searchRecords({
   query: { topK: 5, inputs: { text: "query" } },
 });
 
-// ✅ BETTER - always rerank in production
+// ✅ BETTER - use reranking for best results (best practice)
 const rerankedResults = await index.namespace("ns").searchRecords({
   query: {
     topK: 10,

.agents/PINECONE.md

@@ -146,12 +146,21 @@ For detailed CLI installation, authentication, and command reference, see [PINEC
 
 ### Upserting records (text with integrated embeddings)
 
-**Always use namespaces for data isolation:**
+**⚠️ MANDATORY: Always use namespaces for data isolation. Every upsert operation MUST specify a namespace.**
+
+**Namespace patterns:**
 
 - Multi-user apps: `user_123`
 - Session-based: `session_456`
 - Content-based: `knowledge_base`, `chat_history`
 
+**Before upserting, verify:**
+
+1. Namespace is specified (MANDATORY)
+2. Field names match `--field_map` from index creation (MANDATORY)
+3. Batch size limits respected (MANDATORY)
+4. Metadata is flat structure (MANDATORY)
+
 ### Updating records
 
 Use the same upsert operation with existing IDs. Only changed fields need to be included for partial updates.
@@ -168,11 +177,13 @@ Use paginated listing with optional prefix filters for efficient ID retrieval.
 
 ### Semantic search with reranking (best practice)
 
-**Always rerank for production quality:**
+**Best practice**: Reranking improves search quality. Quickstarts include reranking to demonstrate usage.
+
+**Recommended pattern:**
 
-- Get 2x candidates initially
+- Get 2x candidates initially (e.g., if you want 5 results, request 10)
 - Rerank with `bge-reranker-v2-m3` model
-- Return final count
+- Return final count (reranked results)
 
 ### Lexical search (keyword-based)
 
@@ -211,8 +222,8 @@ Use for exact keyword matching with optional required terms and reranking.
 
 ### 4. **Skipping Reranking** (reduces search quality)
 
-- ⚠️ OK but not optimal
-- ✅ Always rerank in production
+- ⚠️ **OK but not optimal** - Search works without reranking
+- ✅ **Best practice** - Use reranking in production with `bge-reranker-v2-m3` for better results
 
 ### 5. **Hardcoded API Keys**
 
@@ -281,4 +292,4 @@ For advanced features not covered in this quick reference:
 - **Error handling**: [https://docs.pinecone.io/guides/production/error-handling](https://docs.pinecone.io/guides/production/error-handling)
 - **Database limits**: [https://docs.pinecone.io/reference/api/database-limits](https://docs.pinecone.io/reference/api/database-limits)
 
-**Remember**: Always use namespaces, always rerank, always handle errors with retry logic.
+**Remember**: Always use namespaces, use reranking for best results (shown in quickstarts), always handle errors with retry logic.