Update AI Search Skills Reference with new features and api behavior

skills/cloudflare/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: cloudflare
-description: Comprehensive Cloudflare platform skill covering Workers, Pages, storage (KV, D1, R2), AI (Workers AI, Vectorize, Agents SDK), feature flags (Flagship), networking (Tunnel, Spectrum), security (WAF, DDoS), and infrastructure-as-code (Terraform, Pulumi). Use for any Cloudflare development task. Biases towards retrieval from Cloudflare docs over pre-trained knowledge.
+description: Comprehensive Cloudflare platform skill covering Workers, Pages, storage (KV, D1, R2), AI (Workers AI, AI Search, Vectorize, Agents SDK, AI Gateway), feature flags (Flagship), networking (Tunnel, Spectrum), security (WAF, DDoS), and infrastructure-as-code (Terraform, Pulumi). Use for any Cloudflare development task. Biases towards retrieval from Cloudflare docs over pre-trained knowledge.
 references:
   - workers
   - pages
@@ -65,7 +65,8 @@ Need storage?
 ├─ Object/file storage (S3-compatible) → r2/
 ├─ Versioned file trees (repos, build outputs, checkpoints) → artifacts/
 ├─ Message queue (async processing) → queues/
-├─ Vector embeddings (AI/semantic search) → vectorize/
+├─ Searchable documents / knowledge base (managed RAG) → ai-search/
+├─ Raw vector embeddings you compute yourself → vectorize/
 ├─ Strongly-consistent per-entity state → durable-objects/ (DO storage)
 ├─ Secrets management → secrets-store/
 ├─ Streaming ETL to R2 → pipelines/
@@ -78,11 +79,12 @@ Need storage?
 
 ```
 Need AI?
+
 ├─ Run inference (LLMs, embeddings, images) → workers-ai/
-├─ Vector database for RAG/search → vectorize/
 ├─ Build stateful AI agents → agents-sdk/
-├─ Gateway for any AI provider (caching, routing) → ai-gateway/
-└─ AI-powered search widget → ai-search/
+├─ Search/RAG over your own content → ai-search/
+├─ Vector database for RAG/search → vectorize/
+└─ AI Gateway for any AI provider (caching, routing, multi-provider) → ai-gateway/
 ```
 
 ### "I need networking/connectivity"

skills/cloudflare/references/agents-sdk/README.md

@@ -86,4 +86,4 @@ export class MyAgent extends Agent<Env> {
 - durable-objects - Agent infrastructure
 - d1 - External database integration
 - workers-ai - AI model integration
-- vectorize - Vector search for RAG patterns
+- ai-search - Managed search/RAG

skills/cloudflare/references/ai-search/README.md

@@ -1,138 +1,135 @@
-# Cloudflare AI Search Reference
+# Cloudflare AI Search
 
-Expert guidance for implementing Cloudflare AI Search (formerly AutoRAG), Cloudflare's managed semantic search and RAG service.
+Managed retrieval over your own content. Ingestion, chunking, embedding, storage, and ranking are handled for you; you get scored chunks back.
 
-## Overview
+**Formerly AutoRAG.** `env.AI.autorag()` still works but is frozen. See [gotchas.md](./gotchas.md#the-legacy-binding-trap).
 
-**AI Search** is a managed RAG (Retrieval-Augmented Generation) pipeline that combines:
-- Automatic semantic indexing of your content
-- Vector similarity search
-- Built-in LLM generation
-
-**Key value propositions:**
-- **Zero vector management** - No manual embedding, indexing, or storage
-- **Auto-indexing** - Content automatically re-indexed every 6 hours
-- **Built-in generation** - Optional AI response generation from retrieved context
-- **Multi-source** - Index from R2 buckets or website crawls
-
-**Data source options:**
-- **R2 bucket** - Index files from Cloudflare R2 (supports MD, TXT, HTML, PDF, DOC, CSV, JSON)
-- **Website** - Crawl and index website content (requires Cloudflare-hosted domain)
-
-**Indexing lifecycle:**
-- Automatic 6-hour refresh cycle
-- Manual "Force Sync" available (30s rate limit)
-- Not designed for real-time updates
+[The docs](https://developers.cloudflare.com/ai-search/) are authoritative over these files.
 
 ## Quick Start
 
-**1. Create AI Search instance in dashboard:**
-- Go to Cloudflare Dashboard → AI Search → Create
-- Choose data source (R2 or website)
-- Configure instance name and settings
-
-**2. Configure Worker:**
-
 ```jsonc
 // wrangler.jsonc
 {
-  "ai": {
-    "binding": "AI"
-  }
+  "compatibility_date": "2026-03-27",   // or later
+  "ai_search_namespaces": [{ "binding": "AI_SEARCH", "namespace": "default" }]
 }
 ```
 
-**3. Use in Worker:**
-
 ```typescript
+interface Env { AI_SEARCH: AiSearchNamespace }
+
 export default {
-  async fetch(request, env) {
-    const answer = await env.AI.autorag("my-search-instance").aiSearch({
-      query: "How do I configure caching?",
-      model: "@cf/meta/llama-3.3-70b-instruct-fp8-fast"
+  async fetch(request, env: Env) {
+    const { chunks } = await env.AI_SEARCH.get("my-instance").search({
+      messages: [{ role: "user", content: "How do I configure caching?" }],
     });
-
-    return Response.json({ answer: answer.response });
-  }
+    return Response.json(chunks.map((c) => ({ source: c.item.key, text: c.text })));
+  },
 };
 ```
 
-## When to Use AI Search
-
-### AI Search vs Vectorize
-
-| Factor | AI Search | Vectorize |
-|--------|-----------|-----------|
-| **Management** | Fully managed | Manual embedding + indexing |
-| **Use when** | Want zero-ops RAG pipeline | Need custom embeddings/control |
-| **Indexing** | Automatic (6hr cycle) | Manual via API |
-| **Generation** | Built-in optional | Bring your own LLM |
-| **Data sources** | R2 or website | Manual insert |
-| **Best for** | Docs, support, enterprise search | Custom ML pipelines, real-time |
-
-### AI Search vs Direct Workers AI
-
-| Factor | AI Search | Workers AI (direct) |
-|--------|-----------|---------------------|
-| **Context** | Automatic retrieval | Manual context building |
-| **Use when** | Need RAG (search + generate) | Simple generation tasks |
-| **Indexing** | Built-in | Not applicable |
-| **Best for** | Knowledge bases, docs | Simple chat, transformations |
-
-### search() vs aiSearch()
-
-| Method | Returns | Use When |
-|--------|---------|----------|
-| `search()` | Search results only | Building custom UI, need raw chunks |
-| `aiSearch()` | AI response + results | Need ready-to-use answer (chatbot, Q&A) |
-
-### Real-time Updates Consideration
-
-**AI Search is NOT ideal if:**
-- Need real-time content updates (<6 hours)
-- Content changes multiple times per hour
-- Strict freshness requirements
-
-**AI Search IS ideal if:**
-- Content relatively stable (docs, policies, knowledge bases)
-- 6-hour refresh acceptable
-- Prefer zero-ops over real-time
-
-## Platform Limits
-
-| Limit | Value |
-|-------|-------|
-| Max instances per account | 10 |
-| Max files per instance | 100,000 |
-| Max file size | 4 MB |
-| Index frequency | Every 6 hours |
-| Force Sync rate limit | Once per 30 seconds |
-| Filter nesting depth | 2 levels |
-| Filters per compound | 10 |
-| Score threshold range | 0.0 - 1.0 |
-
-## Reading Order
-
-Navigate these references based on your task:
-
-| Task | Read | Est. Time |
-|------|------|-----------|
-| **Understand AI Search** | README only | 5 min |
-| **Implement basic search** | README → api.md | 10 min |
-| **Configure data source** | README → configuration.md | 10 min |
-| **Production patterns** | patterns.md | 15 min |
-| **Debug issues** | gotchas.md | 10 min |
-| **Full implementation** | README → api.md → patterns.md | 30 min |
+**`compatibility_date` must be `2026-03-27` or later.** An older one is the usual cause of "the binding is undefined." Add `"remote": true` for `wrangler dev`; there is no local emulator.
 
 ## In This Reference
 
-- **[api.md](api.md)** - API endpoints, methods, TypeScript interfaces
-- **[configuration.md](configuration.md)** - Setup, data sources, wrangler config
-- **[patterns.md](patterns.md)** - Common patterns, decision guidance, code examples
-- **[gotchas.md](gotchas.md)** - Troubleshooting, code-level gotchas, limits
+Read in this order.
+
+| File | When | Covers |
+|---|---|---|
+| [configuration.md](./configuration.md#decide-before-you-create) | Before creating an instance | Data sources, path filtering, indexing, models, metadata. The embedding model and data source are fixed for the life of an instance |
+| [api.md](./api.md) | While implementing | Bindings, `search()`, filters, boosting, Items API, failure surfaces, REST and CLI |
+| [patterns.md](./patterns.md) | Designing the integration | Agent tools, RAG you own, multitenancy, agent memory, retrieval tuning |
+| [gotchas.md](./gotchas.md) | Results are empty or wrong | Migration traps, silent failures, limits, error codes |
+
+## Default to `search()`
+
+`search()` returns scored chunks. `chatCompletions()` runs a model over those chunks inside AI Search and returns prose.
+
+Use `chatCompletions()` only when the generated answer *is* the shipped artifact: an embedded FAQ box, a public endpoint. Everywhere else use `search()` and generate yourself. `chatCompletions()` exposes only `model:`, so you get no control over the prompt, no tool calling, no multi-turn state, and no chance to filter or dedupe chunks before generation.
+
+## Building an agent? Use the Agents SDK
+
+**The Agents SDK owns the loop; AI Search is one tool it calls.** An agent built on `chatCompletions()` has no memory, no tools, and no loop.
+
+```typescript
+searchDocs = tool({
+  description: "Search the product documentation.",
+  parameters: z.object({ query: z.string() }),
+  execute: async ({ query }) => {
+    const { chunks } = await this.env.AI_SEARCH.get("product-docs").search({
+      messages: [{ role: "user", content: query }],
+    });
+    return chunks.map((c) => ({ source: c.item.key, text: c.text }));
+  },
+});
+```
+
+Full example in [patterns.md](./patterns.md#search-as-an-agent-tool). See [agents-sdk](../agents-sdk/).
+
+## Object Model
+
+```
+Account → Namespace → Instance → Items
+```
+
+The **instance** is the searchable unit. Names collide only within a namespace, so `docs` can exist in both `blog` and `support`. A `default` namespace always exists.
+
+**An instance is an ordinary API object, not provisioned infrastructure.** `create()` is a normal call and the per-account ceiling is high, so one instance per tenant or per agent is viable, and usually better than one shared index filtered by `tenantId`. See [patterns.md](./patterns.md#multitenancy).
+
+## Two Bindings
+
+| Binding | Access | Use when |
+|---------|--------|----------|
+| `ai_search_namespaces` | Every instance in a namespace | **Default.** Runtime instance choice, `create()` / `list()` / `delete()`, cross-instance search, per-tenant isolation |
+| `ai_search` | One instance, fixed at deploy time | The Worker only ever reads one instance that already exists |
+
+The namespace handle is a strict superset; switching to it later means a config change, a code change, and a redeploy. See [api.md](./api.md#bindings).
+
+## Search Modes
+
+| Mode | Finds | To use it |
+|------|-------|-----------|
+| `vector` | Semantic: "how to ship my app" matches "deployment guide" | On by default |
+| `keyword` | Exact terms via BM25: `ERR_CONNECTION_REFUSED` | Enable `index_method.keyword` |
+| `hybrid` | Both, fused | Enable both index methods |
+
+New instances index **vector only**. Querying with `retrieval_type: "hybrid"` requires both index methods enabled at index time, which triggers a full reindex and lowers the file ceiling. See [gotchas.md](./gotchas.md#retrieval-can-only-use-an-index-you-built).
+
+## Data Sources
+
+An instance combines built-in storage with at most one external source. Pick by where the content already lives.
+
+| Content lives | Use | Freshness |
+|---|---|---|
+| Nowhere yet, or you own the write path | **Built-in storage** | Immediate, per file |
+| An R2 bucket already | **R2** | Hours-scale sync |
+| A website you own | **Crawl** | Hours-scale sync |
+
+Built-in storage indexes each file as it arrives through the [Items API](./api.md#items-api), so write-then-read works. That makes AI Search usable as agent memory: see [patterns.md](./patterns.md#per-agent-knowledge-isolation).
+
+Details in [configuration.md](./configuration.md#data-sources).
+
+## When to Use Something Else
+
+**Skip AI Search when** the corpus is small and structured enough that ordinary querying wins.
+
+**Use [vectorize](../vectorize/) instead when** you need your own chunking or embeddings, or vectors not derived from documents (image embeddings, user-preference vectors, recommendation features).
+
+| | AI Search | Vectorize |
+|---|---|---|
+| Chunking and embedding | Managed | Yours |
+| Keyword/BM25 and hybrid fusion | Built in | Not available |
+| Reranking, query rewriting, caching | Built in, toggleable | Yours to build |
+| Ingest | Text, code, PDF, Office, images | Vectors only |
+
+Limits that shape a design are in [gotchas.md](./gotchas.md#limits). Do not pin numbers from memory.
 
 ## See Also
 
-- [Cloudflare AI Search Docs](https://developers.cloudflare.com/ai-search/)
-- [Workers AI Docs](https://developers.cloudflare.com/workers-ai/)
-- [Vectorize Docs](https://developers.cloudflare.com/vectorize/)
+- [AI Search docs](https://developers.cloudflare.com/ai-search/) - full option lists and current defaults
+- [llms.txt](https://developers.cloudflare.com/ai-search/llms.txt) - index of every doc page, for retrieval
+- [agents-sdk](../agents-sdk/) - the right home for agent loops
+- [vectorize](../vectorize/) - the unmanaged alternative
+- [workers-ai](../workers-ai/) - models for your own generation step
+- [ai-gateway](../ai-gateway/) - routing and observability for model calls