@squidcloud/cli 1.0.487 → 1.0.489

package/dist/resources/claude/skills/squid-development/reference/ai.md

@@ -54,10 +54,25 @@ import {
 } from '@squidcloud/client';
 ```
 
+**Active chat models** (the constants above hold active models only; deprecated ones carry a
+`replacedBy` and are excluded unless asked for):
+
+| Provider | `*_CHAT_MODEL_NAMES` |
+|---|---|
+| OpenAI | `gpt-5.5-pro`, `gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.6-luna` |
+| Anthropic | `claude-fable-5`, `claude-haiku-4-5-20251001`, `claude-opus-5`, `claude-sonnet-5` |
+| Gemini | `gemini-3.1-pro`, `gemini-3.7-flash`, `gemini-3.5-flash-lite` |
+| Grok | `grok-4.6`, `grok-4-1-fast-reasoning`, `grok-4-1-fast-non-reasoning` |
+
+This list moves. **Don't hardcode a model name from this table into user code** — call
+`squid.ai().listChatModels()`, which also returns the app's custom integration models
+(`openai_compatible`, Bedrock, Vertex) and flags deprecated ones. See
+[Application Settings](#application-settings).
+
 **Model Categories:**
 - **Chat Models**: Used for AI Agents, AI Query, etc. (OpenAI, Anthropic, Gemini, Grok)
 - **Embedding Models**: Used for Knowledge Bases (OpenAI, Voyage)
-- **Image Generation Models**: Used for image creation (DALL-E, Stable Diffusion, Flux)
+- **Image Generation Models**: Used for image creation (OpenAI `gpt-image-*`, Stable Diffusion, Flux)
 - **Audio Models**: Transcription (Whisper, GPT-4o) and Text-to-Speech (TTS-1, GPT-4o-mini-tts)
 
 ## AI Agents
@@ -76,6 +91,7 @@ An AI Agent can:
 - Collaborate with other AI agents
 - Process voice input and generate voice output
 - Accept files as part of chat requests
+- Refuse prompts that contain PII before they reach the model (see Rejecting PII in prompts)
 
 ### Creating and Managing Agents
 
@@ -99,7 +115,7 @@ await myAgent.upsert({
   isPublic: false,  // Whether the agent is publicly accessible
   auditLog: true,   // Enable audit logging for compliance
   options: {
-    model: 'gpt-5-mini', // or 'claude-sonnet-4-5-20250929', 'gemini-3-flash'
+    model: 'gpt-5.6-terra', // or 'claude-sonnet-5', 'gemini-3.7-flash' - see Supported Models
     instructions: 'You are a helpful customer support assistant. Be concise and professional.',
     temperature: 0.7
   }
@@ -111,7 +127,7 @@ console.log(agentInfo.id, agentInfo.description, agentInfo.options.model);
 
 // Update specific properties
 await myAgent.updateInstructions('You are a technical support specialist.');
-await myAgent.updateModel('claude-sonnet-4-5-20250929');
+await myAgent.updateModel('claude-sonnet-5');
 await myAgent.updateGuardrails(['no-harmful-content']);
 
 // Delete an agent
@@ -140,8 +156,85 @@ await myAgent.updateConnectedAgents([
 // Update or delete custom guardrails
 await myAgent.updateCustomGuardrails('Never reveal sensitive information');
 await myAgent.deleteCustomGuardrail();
+
+// Refuse prompts that contain PII (see "Rejecting PII in prompts" below)
+await myAgent.updatePii({ onDetect: 'reject' });
+
+// Expose the agent itself as an MCP server (see "Agent as an MCP server" below)
+await myAgent.updateMcpServer({ enabled: true, requireApiKey: true });
+```
+
+### Agent as an MCP Server
+
+Any agent can be published as an MCP server at `/mcp/<agentId>` with **no backend code** — the server
+exposes a single `ask` tool that calls the agent. This is the inverse of `@mcpServer`, which exposes
+*your* backend tools to agents. Transport is the official MCP **Streamable HTTP** transport.
+`updateMcpServer` requires an API key.
+
+```typescript
+// AI-generate the server + tool descriptions from the agent's instructions and connected resources.
+// Returns them WITHOUT persisting - save them with updateMcpServer.
+const generated = await myAgent.generateMcpDescriptions();
+
+await myAgent.updateMcpServer({
+  enabled: true,
+  description: generated.description,        // served as `instructions` in the MCP initialize result
+  toolDescription: generated.toolDescription, // description of the `ask` tool in the tools manifest
+  requireApiKey: true,                        // require the agent's API key as a bearer token
+  oauthIntegrationId: 'auth0'                 // or OAuth-protect it with an auth integration
+});
+```
+
+**`AiAgentMcpServerConfig`:**
+- `enabled` — whether the agent is exposed as an MCP server.
+- `description` — defaults to the agent description when omitted.
+- `toolDescription` — defaults to a generic ask-the-agent description.
+- `requireApiKey` — when true, requests must present the agent's API key as
+  `Authorization: Bearer <agent API key>` or the `x-squid-agent-api-key` header.
+- `oauthIntegrationId` — OAuth-protects the endpoint with an auth integration's bearer tokens.
+- Combining `oauthIntegrationId` and `requireApiKey` accepts **either** credential.
+- **With neither set, the MCP endpoint is public.**
+
+### Rejecting PII in prompts
+
+`pii` refuses an incoming prompt that carries personal information **before it reaches the
+agent's model**. The prompt is not answered, no quota is consumed, and nothing is written to
+chat memory. The caller gets an error whose message starts with `PII_DETECTED_IN_PROMPT`.
+
+Do not confuse it with `guardrails.disablePii`, which is the opposite direction — that one asks
+the agent's own model not to *emit* PII in its answer, and is best-effort prompt text. Use `pii`
+when the requirement is that the data must not reach the model at all.
+
+```typescript
+await squid.ai().agent('support-agent').updatePii({
+  onDetect: 'reject',                    // 'off' (default) disables screening
+  entities: ['email', 'ssn'],            // omit for every kind
+  customRules: ['internal case numbers like CASE-12345'],
+  allowList: ['support@squid.cloud'],    // literal values that never count as PII
+  classifierModel: 'gpt-5.6-luna',       // default; small and fast
+});
 ```
 
+| Field | Meaning |
+|---|---|
+| `onDetect` | `'reject'` refuses the prompt; `'off'` (default) disables screening |
+| `entities` | Kinds to screen for: `email`, `phoneNumber`, `creditCard`, `ssn`, `iban`, `passport`. Omitted means all |
+| `customRules` | App-specific PII in plain language — anything a model can recognize from a description |
+| `allowList` | Exact values that must never be flagged |
+| `classifierModel` | Model doing the screening. Defaults to `gpt-5.6-luna` |
+
+Things to know before enabling it:
+
+- **Every prompt costs one extra model call.** Screening runs ahead of the agent's own model, so
+  it adds latency and tokens to each turn.
+- **It is prompt-side only.** Tool results and knowledge-base chunks can still bring PII into the
+  model. Don't describe it to a user as an end-to-end guarantee.
+- **It is fail-closed.** If the classifier is unreachable the turn is rejected with
+  `PII_SCREENING_UNAVAILABLE` rather than admitted unscreened.
+- **It cannot be overridden per request.** Passing `pii` in `ask`/`chat` options is ignored; the
+  stored agent's value always wins, so a caller cannot opt out of its own screening.
+- **Rejections are audited with the prompt redacted** — matched kinds are recorded, never values.
+
 ### Agent Lifecycle
 
 1. **Creation** - Use `upsert()` to create a new agent with an ID
@@ -165,6 +258,8 @@ Agents become powerful when connected to resources:
 - **Backend functions** (`functions`) - Custom logic via `@aiFunction` decorators
 - **Integrations** (`connectedIntegrations`) - Database/API queries
 - **Knowledge bases** (`connectedKnowledgeBases`) - RAG (Retrieval Augmented Generation)
+- **Source repositories** (a `github`/`bitbucket` integration with code analysis enabled) - see
+  [Source-Code Analysis](#source-code-analysis)
 
 #### Connected Agents
 
@@ -258,6 +353,8 @@ const response = await agent.ask('What is our return policy?', {
 });
 ```
 
+Knowledge bases with a knowledge graph give the agent graph retrieval and a `queryKnowledgeGraph` tool automatically — see [Knowledge Graph (GraphRAG)](#knowledge-graph-graphrag).
+
 ### Agent Chat Methods
 
 ```typescript
@@ -268,13 +365,20 @@ const agent = squid.ai().agent('my-agent');
 // - NO connected resources: streams token-by-token
 // - HAS connected resources: emits ONCE with complete response
 const chatObs = agent.chat('What is your return policy?', {
-  // Memory management
+  // Memory management. `memoryOptions` is the only way to name a conversation and control
+  // history: `memoryId` names it, `memoryMode` controls whether history is read and written.
   memoryOptions: {
     memoryMode: 'read-write', // 'none' | 'read-only' | 'read-write'
     memoryId: 'user-123',     // Unique per user/session
     expirationMinutes: 1440   // 24 hours
   },
 
+  // Usage tracking: reported as `annotation.<key>` tags on Squid AI usage metrics, so token
+  // usage can be filtered/grouped by them. Inherited by nested connected-agent calls.
+  // Limits: max 10 entries, keys <= 64 chars, values <= 256 chars; excess is dropped/truncated.
+  // Set app-wide defaults with squid.setMetricAnnotations({...}); per-call values merge on top.
+  metricAnnotations: { feature: 'support-bot', requestSource: 'mobile' },
+
   // Connected resources (can also be set on agent.upsert)
   connectedAgents: [{ agentId: 'specialist-agent', description: 'Handles X' }],
   functions: ['function1', 'function2'],
@@ -282,7 +386,7 @@ const chatObs = agent.chat('What is your return policy?', {
   connectedKnowledgeBases: [{ knowledgeBaseId: 'kb1', description: 'When to use this KB' }],
 
   // Model & generation
-  model: 'gpt-5-mini', // Override agent's default model
+  model: 'gpt-5.6-terra', // Override agent's default model
   temperature: 0.7,
   maxTokens: 4000,
   maxOutputTokens: 2000,
@@ -305,6 +409,15 @@ const chatObs = agent.chat('What is your return policy?', {
     maxAiCallStackSize: 5
   },
 
+  // Refuse incoming prompts that carry PII (stored on the agent; ignored if passed per request)
+  pii: {
+    onDetect: 'reject',
+    entities: ['email', 'phoneNumber', 'creditCard', 'ssn', 'iban', 'passport'],
+    customRules: ['internal case numbers like CASE-12345'],
+    allowList: ['support@squid.cloud'],
+    classifierModel: 'gpt-5.6-luna'
+  },
+
   // Files & voice
   fileUrls: [
     { id: 'file1', type: 'image', purpose: 'context', url: 'https://...', description: 'Product image' }
@@ -320,7 +433,7 @@ const chatObs = agent.chat('What is your return policy?', {
   useCodeInterpreter: 'llm', // 'none' | 'llm' (OpenAI/Gemini only)
   executionPlanOptions: {
     enabled: true,
-    model: 'gpt-5-mini',
+    model: 'gpt-5.6-terra',
     reasoningEffort: 'high',
     allowClarificationQuestions: false
   },
@@ -456,14 +569,221 @@ const context = await kb.getContext('doc-123');
 const allContexts = await kb.listContexts(1000); // truncateTextAfter
 const contextIds = await kb.listContextIds();
 
+// List a PAGE of contexts (prefer this over listContexts for large KBs)
+const page = await kb.listContextsPage({
+  offset: 0,
+  limit: 50,
+  truncateTextAfter: 500,
+  search: 'invoice'   // case-insensitive substring match on id/title only
+});
+
 // Download context
 const download = await kb.downloadContext('doc-123');
 
 // Delete contexts
 await kb.deleteContext('doc-123');
 await kb.deleteContexts(['doc-1', 'doc-2']);
+
+// AI-generate descriptions for the KB's metadata fields (helps metadata filtering quality).
+// Returns { fields } WITHOUT persisting - save them yourself via upsertKnowledgeBase.
+// By default only fields with an empty description are generated.
+const { fields } = await kb.generateMetadataFieldDescriptions({
+  fieldNames: ['category'],   // optional; omitted => all declared fields
+  overwriteExisting: false    // true regenerates fields that already have a description
+});
+```
+
+`upsertContexts` accepts an options object with an `onUploaded` callback, fired once the payload has
+been uploaded and accepted — server-side extraction and embedding continue after it, and the promise
+still resolves only when ingestion completes:
+
+```typescript
+await kb.upsertContexts(contexts, files, { onUploaded: () => setStatus('Uploaded, indexing…') });
+```
+
+### Metadata Filters
+
+A MongoDB-style grammar shared across KB context filtering, metrics tag filtering, and matchmaking
+(the types live in `@squidcloud/client`). Used by `kb.search`, `kb.grep`, and the chat option
+`contextMetadataFilterForKnowledgeBase`.
+
+```typescript
+// A bare scalar is shorthand for $eq
+{ category: 'user-guide' }
+
+// Field operators: $eq, $ne, $gt, $gte, $lt, $lte, $in, $nin, $exists
+{ version: { $gte: 2 }, status: { $in: ['published', 'review'] }, archivedAt: { $exists: false } }
+
+// Boolean combinators
+{ $or: [{ category: 'faq' }, { $and: [{ category: 'guide' }, { version: { $gte: 2 } }] }] }
+```
+
+**`$underPath` (knowledge bases only)** — segment-safe subtree match on a hierarchical string field
+such as `folderPath`:
+
+```typescript
+{ folderPath: { $underPath: 'reports/2023' } }
+```
+
+Matches `reports/2023` and `reports/2023/q1/deck`, but never the lexical sibling
+`reports/2023 drafts` — the `/` separator supplies the segment boundary, so subtree scoping cannot
+leak into a sibling that merely shares a prefix. Leading/trailing `/` in the operand are stripped, an
+empty operand matches every document that *has* the field, and matching is **case-sensitive**.
+
+The canonical `folderPath` form: POSIX `/` separators, no leading/trailing slash, `''` (not
+`undefined`) for the upload root, case preserved, NFC-normalized. `folderPath` is an ordinary
+metadata key, not a reserved one.
+
+`$underPath` is deliberately absent from the shared filter type that metrics and matchmaking consume
+— they reject unknown operators at runtime.
+
+### Literal Scan (grep)
+
+`grep()` scans the KB's **raw extracted text** (pre-chunking, so spreadsheet rows appear verbatim)
+for a literal string and returns every matching line with its file and locator. Use it when you need
+characters, not meaning: IDs, error codes, SKUs, exact phrases.
+
+```typescript
+const hits = await kb.grep('ERR_0000_4F2A', {
+  metadataFilter: { category: 'runbooks' },  // same grammar as chunk search, incl. $and/$or/$underPath
+  maxMatches: 100
+});
+```
+
+- The pattern is **always literal** — every regex metacharacter is escaped — and may span lines.
+- Matching is case-insensitive **for ASCII letters only**: `acme` finds `ACME`, but `café` does not
+  find `CAFÉ`. Search the exact casing for non-ASCII text.
+- `metadataFilter` selects contexts **before** any text is matched.
+
+### Knowledge Graph (GraphRAG)
+
+A graph-enabled knowledge base extracts an entity/relationship graph at ingest and layers concepts on top (document nodes, themes clustered from the entity graph, facet trees from context metadata). Retrieval can then follow links across documents — answering questions whose supporting facts are split over several files — and agents can navigate corpus structure instead of only quoting passages.
+
+Requirements: `vectorDbType: 'mongoAtlas'` (immutable after creation — a `postgres` KB can never gain a graph). `graphRag` itself is mutable: enabling it on an existing Atlas KB auto-backfills the graph; disabling only makes graph search unavailable and RETAINS the extracted graph data, so re-enabling is cheap (a structural build folds in never-indexed contexts, reusing prior extraction). To actually reclaim the graph data, call `rebuildGraph()` while `graphRag.enabled` is false — that is the explicit cleanup path; otherwise only deleting the KB drops it. Extraction runs an LLM over every chunk at ingest — budget before enabling on a large corpus, and track spend via `getGraphStatus()`.
+
+```typescript
+// Enable at creation, or later by upserting with the current config spread — upserting
+// graphRag replaces the whole object, so omitted fields are lost.
+await kb.upsertKnowledgeBase({
+  description: 'Company filings',
+  vectorDbType: 'mongoAtlas', // Required for the graph.
+  graphRag: {
+    enabled: true,
+    // Optional extraction hint; proper nouns (orgs, people, places) extract far more
+    // reliably than generic product categories.
+    entityTypes: ['ORGANIZATION', 'PRODUCT', 'LOCATION'],
+    // Other fields: extractionModel, autoBuildDebounceMs (quiet window before automatic
+    // concept builds, default 5 min), concepts: { facets: 'auto' | [fields], pathFacets:
+    // [{ field: 'folderPath', type: 'path' }] } (folder tree from a path metadata field).
+  },
+});
+
+// Graph search: seeds entities from the prompt via vector search, walks relationships,
+// maps reached entities back to chunks, fuses with hybrid search. 'graph' is the DEFAULT
+// searchMode on a graph-enabled KB, so it can be omitted. Passing it explicitly on a KB
+// without GraphRAG throws GRAPH_SEARCH_NOT_ENABLED — no silent fallback to hybrid.
+const graphChunks = await kb.search({
+  prompt: 'Which drugs does Aldous Corporation sell?',
+  searchMode: 'graph',
+  graphOptions: { seedLimit: 8, maxHops: 2 }, // Defaults shown; caps 25 and 3.
+});
+
+// Like search() but returns the full response, including the traversed subgraph
+// (entities + relationships) — for debugging retrieval or explaining results.
+const response = await kb.searchWithGraphContext({
+  prompt: 'Which drugs does Aldous Corporation sell?',
+  searchMode: 'graph',
+  graphOptions: { includeGraphContext: true },
+});
+
+// Scope ANY search mode to the documents under one theme or facet; composes with
+// contextMetadataFilter. Value: a concept name (resolved server-side) or a facet nodeId.
+// Unresolvable concepts fail with CONCEPT_NOT_FOUND plus the nearest matching names.
+await kb.search({ prompt: 'What was the purchase price?', graphFilter: { underConcept: 'Acquisitions' } });
+
+// Structure queries — one round trip each. Ops: 'overview' (themes/facets/counts map),
+// 'resolve' | 'describe' | 'subtree' | 'docsUnder' | 'neighborhood' (take ref),
+// 'conceptsOf' (takes contextId), 'pathBetween' (ref + refB -> relationship chain, or the
+// concepts both sit under when no chain exists), 'globalSummary' (takes query).
+const overview = await kb.queryGraph({ op: 'overview' });
+const path = await kb.queryGraph({ op: 'pathBetween', ref: 'Aldous Corporation', refB: 'Zalofen' });
+
+// Build state, coverage and cost: contextsIndexed/contextsTotal, entityCount,
+// relationshipCount, topics/facets, structureStale/staleDocCount, buildJob,
+// nextAutoBuildAt, ingestUsage/lastRebuildUsage (LLM tokens + estimated USD).
+const status = await kb.getGraphStatus();
+
+// Force a concept-layer build now instead of waiting for the debounced automatic build.
+// Default mode 'structural' reuses extracted entities (cheap). mode: 'full' wipes the
+// graph and re-extracts every chunk with the LLM — cost on the order of the initial
+// ingest; only needed after changing entityTypes or extractionModel.
+await kb.rebuildGraph();
+
+// Bounded entity-graph slice for visualization (highest-degree entities and their
+// relationships). nodeLimit default 200, max 1000; pass topicId to restrict to one theme.
+const subgraph = await kb.exploreGraph({ nodeLimit: 100 });
+```
+
+Gotchas:
+- Entity extraction is triggered by ingestion but runs asynchronously off the request path: `upsertContexts()` resolving does NOT mean the graph is ready — poll `getGraphStatus()` until `contextsIndexed === contextsTotal` before relying on graph retrieval for just-ingested documents. Poll with a timeout rather than an unbounded `while` loop: that equality can legitimately never hold, because contexts past the graph chunk cap (next bullet) are never stamped, and a pod restart mid-extraction leaves the remaining contexts unstamped until the debounced auto-build sweep re-extracts them. Treat a shortfall that stops moving as one of those cases, not as work still in flight — `graphIndexingSkippedContextIds` from the upsert identifies the cap case. No rebuild is needed for extraction; what lags further is the concept layer (themes/facets read by `queryGraph`), rebuilt after a quiet window (default 5 min, `autoBuildDebounceMs`) or a manual `rebuildGraph()`. Only one rebuild runs per KB at a time (`JOB_ALREADY_EXISTS`).
+- Per-KB graph chunk cap (a deployment-level limit whose value can change — detect it via the signals, don't design around a fixed number): contexts beyond it stay fully vector/keyword-searchable but are not graph-indexed. Upsert results flag them — the batch `upsertContexts()` returns `graphIndexingSkippedContextIds`, only the singular `upsertContext()` sets the `graphIndexingSkipped` boolean — and `getGraphStatus()` shows `contextsIndexed < contextsTotal`.
+- Only facet nodeIds and document contextIds are stable handles. Theme and entity ids churn on every rebuild — resolve names each time instead of persisting ids.
+- Agents connected to a graph-enabled KB pick it up automatically: `'graph'` becomes the search tool's default mode, the tool description carries a compact graph overview, and the agent gets a `queryKnowledgeGraph` tool backed by the ops above (agent status broadcast: `'Querying Knowledge Base Graph'`). Exception: an active app/per-KB metadata visibility filter suppresses the graph navigation surface (overview block, `underConcept`, the `queryKnowledgeGraph` tool) so out-of-scope concepts/entities cannot leak; graph search mode stays available, filter-scoped.
+
+### Bulk Ingestion
+
+A durable, asynchronous lane for high-volume ingestion that runs contexts through provider batch APIs
+instead of inline. Unlike `upsertContexts`, `bulkUpsertContexts` returns as soon as the request is
+**staged** and never awaits completion.
+
+```typescript
+// 1. Stage contexts (files passed positionally for `type: 'file'` contexts)
+const { jobId, contextIds, duplicates } = await kb.bulkUpsertContexts(contexts, files);
+// contextIds is index-aligned with `contexts`. A context rejected as a content duplicate - the KB
+// already holds identical content, or an earlier context in this same call did - still occupies its
+// slot, so cross-reference `duplicates` by contextId to see what was actually staged.
+
+// 2a. Watch it
+kb.observeBulkIngestionJob(jobId).subscribe(s => console.log(s.state, s.counts, s.files));
+
+// 2b. …or poll it
+const status = await kb.getBulkIngestionJob(jobId);
+// { state, counts, providerBatchIds, files }
+
+// Cancel: already-finalized contexts are kept; the job goes to `cancelled` once in-flight work drains
+await kb.cancelBulkIngestionJob(jobId);
+```
+
+**Large file sets — upload straight to storage.** The multipart path caps at **50 files, 100 MB per
+file, and 256 MB of request body** (the body is buffered in memory server-side), so a single 150 MB
+PDF is rejected there no matter how few files accompany it. Past any of the three, mint presigned
+URLs and reference `stagedObjectKey` instead: core never holds the bytes and none of the multipart
+caps apply. Two staging limits still bound every call whatever path the files arrived by: **10,000
+contexts** and **256 MB of extracted content** — extracted, so base64 image payloads (~1.33x the raw
+image bytes) count and a body that passed the multipart check can still be rejected during staging.
+Split large corpora across jobs, which is what the CLI's `--batchSize` of 200 does:
+
+```typescript
+const { uploads } = await kb.createBulkUploadUrls(fileNames);  // max 500 names per call
+for (const u of uploads) {
+  // requiredHeaders is empty on S3, but Azure Blob rejects the PUT with 400 MissingRequiredHeader without it
+  await fetch(u.uploadUrl, { method: 'PUT', body: bytes, headers: u.requiredHeaders });
+}
+await kb.bulkUpsertContexts(uploads.map(u => ({ type: 'file', stagedObjectKey: u.stagedObjectKey, /* ... */ })));
 ```
 
+**`observeBulkIngestionJob` semantics:**
+- Completes on a terminal state (`completed`, `failed`, `cancelled`). A terminal `failed`/`cancelled`
+  arrives as a **normal emitted value** — the observable only errors on transport failure.
+- Cold: each subscription registers its own server-side push. Share it (rxjs `share()`) for multiple
+  consumers.
+- Re-subscribes automatically if the client connection id changes mid-subscription.
+- If the app or KB is deleted mid-flight the job row is purged without a terminal push, so the
+  observable never completes — bound it (rxjs `timeout()`) when deletion is possible.
+
+The CLI wraps this whole flow: `squid kb-upload --dir ./docs --knowledgeBase my-kb` (see
+[backend.md](backend.md#cli-commands)).
+
 ### Spreadsheet Understanding
 
 Spreadsheet files (`.csv`, `.tsv`, `.xlsx`, `.xlsm`, `.xls`, `.xlsb`) uploaded as file context take a dedicated ingestion lane: instead of chunking raw cell text, Squid extracts the workbook structure (sheets, headers, hidden sheets; charts and pivot tables where the format exposes them — absent for CSV/TSV and `.xls`, pivots also absent for `.xlsb`) and embeds a generated whole-workbook summary, so search results describe what a workbook contains.
@@ -498,10 +818,10 @@ REST API: [AI Image API](https://docs.getsquid.ai/reference-docs/api/#tag/AI-Ima
 ### Image Generation
 
 ```typescript
-// Generate image
+// Generate image - `modelName` is required
 const imageUrl = await squid.ai().image().generate(
   'A futuristic city',
-  { size: '1024x1024', quality: 'hd' }
+  { modelName: 'gpt-image-1', size: '1024x1024', quality: 'high' }
 );
 
 // Remove background
@@ -574,7 +894,7 @@ const settings = await aiClient.getApplicationAiSettings();
 
 // Set application AI settings
 await aiClient.setApplicationAiSettings({
-  defaultModel: 'gpt-5-mini',
+  defaultModel: 'gpt-5.6-terra',
   // ... other settings
 });
 
@@ -583,8 +903,20 @@ await aiClient.setAiProviderApiKeySecret(
   'openai', // providerType
   'OPENAI_API_KEY' // secret key name
 );
+
+// List the chat models available to this application (Squid vendor models + custom integration models)
+const models = await aiClient.listChatModels();
+// Deprecated models (those carrying `replacedBy`) are excluded by default:
+const withDeprecated = await aiClient.listChatModels({ includeDeprecated: true });
+
+// List the AI functions the application exposes
+const functions = await aiClient.listFunctions();
 ```
 
+**Prefer `listChatModels()` over hardcoding a model name** — it reflects what the app can actually
+use, including custom `openai_compatible`/Bedrock/Vertex integration models, and marks deprecated
+models via `replacedBy`.
+
 ## Backend Decorators
 
 ### @aiFunction
@@ -640,6 +972,36 @@ async bookHotel(args: BookingArgs): Promise<string> {
 
 For `@secureAiAgent` and `@secureAiQuery`, see [security.md](security.md#ai-security).
 
+## Source-Code Analysis
+
+An agent can answer questions about real repositories. Enable code analysis on a `github` or
+`bitbucket` integration; the agent then gets an `analyzeCode` tool that clones the selected
+repositories into an isolated workspace and runs a CLI coding agent over them.
+
+```typescript
+// 1. Discover the repositories an integration can reach (admin client - requires an API key)
+const integrations = squid.admin().integrations();
+const { repositories } = await integrations.discoverSourceRepositories('my-github');
+// repositories: { provider, providerRepositoryId, fullName, cloneUrl, webUrl, defaultBranch }[]
+
+// Or, before the integration is saved:
+const draft = await integrations.discoverSourceRepositoriesFromDraft(integrationInfo);
+
+// 2. Select repositories on the integration and configure the agent's analysis options
+//    (AiAgentSourceCodeIntegrationOptions):
+//    codeAnalysisEnabled, analyzerModel, analyzerModelId, analyzerReasoningEffort, analyzerInstructions
+```
+
+**Constants** (exported from both `@squidcloud/client` and `@squidcloud/backend`):
+- `SOURCE_CODE_ANALYZE_FUNCTION_ID` = `'analyzeCode'` — the AI function id
+- `SOURCE_CODE_ANALYZER_MODELS` = `['claude-code', 'codex']` — the CLI providers
+- `SOURCE_CONTROL_PROVIDERS` / `SOURCE_CODE_INTEGRATION_TYPES` = `['github', 'bitbucket']`
+- `SOURCE_CODE_MAX_REPOSITORIES` = 20
+- `SOURCE_CODE_MAX_SUPPLEMENTAL_INSTRUCTIONS_LENGTH` = 20,000 characters per instruction field
+
+Selecting repositories and enabling analysis is usually done in the Console — the SDK path exists for
+automation.
+
 ## MCP (Model Context Protocol)
 
 Squid supports MCP for extending agent capabilities.
@@ -787,7 +1149,7 @@ configureAiFunctions(request: AiFunctionsConfiguratorRequest): AiFunctionsConfig
 ## Best Practices
 
 1. **NEVER invoke LLMs directly** - Do NOT import `openai`, `@anthropic-ai/sdk`, or call LLM APIs directly. ALWAYS use Squid AI Agents via `squid.ai().agent()`. Squid agents provide built-in security, memory, streaming, function calling, guardrails, and model management. If you need an LLM call, create/use an AI agent.
-2. **Use memoryOptions for AI conversations** - Not deprecated chatId
+2. **Use memoryOptions for AI conversations** - `memoryOptions.memoryId` names the conversation, `memoryOptions.memoryMode` controls history
 3. **Agent IDs are permanent** - Plan naming carefully, cannot be changed after creation
 4. **Memory is enabled by default** - Set `memoryMode: 'none'` to disable conversation history
 5. **Streaming behavior differs with connected resources** - No resources: streams token-by-token; Has resources: emits once with complete response

package/dist/resources/claude/skills/squid-development/reference/api.md

@@ -13,6 +13,15 @@ All API endpoints require an API key. Include it in the request headers:
 Authorization: Bearer YOUR_API_KEY
 ```
 
+Two security schemes exist:
+
+| Scheme | Header | Scope |
+|---|---|---|
+| `apiKeyAuth` | `x-app-api-key` | The application API key. Accepted everywhere. |
+| `agentApiKeyAuth` | `x-squid-agent-api-key` | An **agent-scoped** key, accepted by the agent `ask` endpoints and by an agent's MCP endpoint when `requireApiKey` is set. |
+
+Get an agent key with `squid.ai().agent(id).getApiKey()` / `regenerateApiKey()`.
+
 ## API Categories
 
 ### [Agent API](https://docs.getsquid.ai/reference-docs/api/#tag/Agent)
@@ -26,12 +35,27 @@ Manage AI agents. SDK: [ai.md](ai.md)
 - `POST /agent/updateGuardrails` - Configure guardrails
 - `POST /agent/updateCustomGuardrails` - Set custom guardrails
 - `POST /agent/deleteCustomGuardrails` - Remove custom guardrails
+- `POST /agent/setAgentOptionInPath` - Set any agent option by path; how the SDK's `updatePii()` writes the `pii` policy (no dedicated PII endpoint)
 - `POST /agent/ask` - Send prompt, get response
 - `POST /agent/askWithAnnotations` - Get response with annotations
+- `GET /agent/listAgents` - List the application's agents
 - `GET /agent/revisions/{agentId}` - List revisions
 - `POST /agent/restoreRevision` - Restore revision
 - `POST /agent/deleteRevision` - Delete revision
 
+The `ask` / `askWithAnnotations` endpoints accept `agentApiKeyAuth` in addition to `apiKeyAuth`.
+
+Exposing an agent as an MCP server (`updateMcpServer()`) and generating its MCP descriptions
+(`generateMcpDescriptions()`) are SDK-only — they are not part of the published REST surface.
+
+### AiFunction API
+List the AI functions the application exposes. SDK: [ai.md](ai.md)
+- `GET /ai/function/listFunctions` - List AI functions
+
+### AiSettings API
+Application-level AI settings. SDK: [ai.md](ai.md)
+- `GET /ai/settings/listChatModels?includeDeprecated=false` - Chat models available to the app (Squid vendor models + custom integration models)
+
 ### [AI Audio API](https://docs.getsquid.ai/reference-docs/api/#tag/AI-Audio)
 Transcribe audio, text-to-speech. SDK: [ai.md](ai.md)
 - `POST /audio/transcribe` - Transcribe audio to text
@@ -51,7 +75,17 @@ Manage knowledge bases for RAG. SDK: [ai.md](ai.md)
 - `POST /knowledge-base/deleteContexts` - Delete contexts
 - `GET /knowledge-base/getContext/{knowledgeBaseId}/{contextId}` - Get context
 - `GET /knowledge-base/listContexts/{knowledgeBaseId}` - List contexts
-- `POST /knowledge-base/search` - Semantic search
+- `GET /knowledge-base/listContextsPage/{knowledgeBaseId}` - List a page of contexts (offset/limit/search)
+- `GET /knowledge-base/listKnowledgeBases` - List the application's knowledge bases
+- `POST /knowledge-base/search` - Search (vector/hybrid/keyword/graph via `searchMode`; graph fields in the response when requested)
+- `POST /knowledge-base/queryGraph` - Query graph structure (overview, resolve, describe, subtree, docsUnder, conceptsOf, neighborhood, pathBetween, globalSummary)
+- `GET /knowledge-base/getGraphStatus/{knowledgeBaseId}` - Graph build status, coverage, and LLM cost
+- `POST /knowledge-base/rebuildGraph` - Enqueue a graph rebuild (`structural` or `full`)
+- `POST /knowledge-base/exploreGraph` - Bounded entity-graph slice for visualization
+
+Literal scan (`kb.grep()`) and bulk ingestion (`kb.bulkUpsertContexts()` and friends) are SDK-only —
+they are not part of the published REST surface. For bulk ingestion from a machine, use the
+`squid kb-upload` CLI command.
 
 ### [Matchmaking API](https://docs.getsquid.ai/reference-docs/api/#tag/Matchmaking) *(deprecated)*
 Use `knowledgeBase().searchContextsWith*()` instead.
@@ -85,3 +119,14 @@ Create PDFs, extract data from documents. SDK: [client.md](client.md)
 | Knowledge Bases | `squid.ai().knowledgeBase()` | KnowledgeBase API |
 | Web Utilities | `squid.web()` | Web Utilities API |
 | Extraction | `squid.extraction()` | Extraction Utilities API |
+| Chat models / AI functions | `squid.ai().listChatModels()` / `listFunctions()` | AiSettings API / AiFunction API |
+| Events | `squid.events().emit()` | SDK only |
+| LangGraph | `squid.langGraph(id)` | SDK only |
+| KB literal scan, bulk ingestion | `kb.grep()`, `kb.bulkUpsertContexts()` | SDK only (bulk also via `squid kb-upload`) |
+
+## Chat Options: Naming a Conversation
+
+The agent endpoints take conversation identity and history control under `memoryOptions`:
+`memoryOptions.memoryId` names the conversation, and `memoryOptions.memoryMode`
+(`'none' | 'read-only' | 'read-write'`) controls whether history is read and written. An unrecognized
+option key is rejected with a **400** naming the option that carries it.