From 6ab80f42b4f496009f32b8f7e50b9ee424c580c7 Mon Sep 17 00:00:00 2001
From: arpan404 <itsmearpan1@gmail.com>
Date: Mon, 8 Jun 2026 00:52:15 +0545
Subject: [PATCH] Update docs and examples to gpt-5.5

- Refresh model references across docs, snippets, and examples
- Update default model and fallback examples to gpt-5.5
---
 docs/index.mdx                                |  2 +-
 docs/library/a2a.mdx                          |  2 +-
 docs/library/agent-skills.mdx                 |  4 +-
 docs/library/agentic-behavior.mdx             |  8 +--
 docs/library/agentic-levels.mdx               |  6 +--
 docs/library/agents.mdx                       | 14 ++---
 docs/library/building-with-ai.mdx             |  8 +--
 docs/library/checkpoint-schema.mdx            |  2 +-
 docs/library/core-runner.mdx                  |  2 +-
 docs/library/deployment.mdx                   |  2 +-
 docs/library/environment-variables.mdx        |  2 +-
 docs/library/evals.mdx                        |  2 +-
 docs/library/failure-policy-matrix.mdx        |  2 +-
 docs/library/how-to-use-afk.mdx               |  4 +-
 docs/library/learn-in-15-minutes.mdx          | 10 ++--
 docs/library/llm-interaction.mdx              |  4 +-
 docs/library/mcp-server.mdx                   |  2 +-
 docs/library/memory.mdx                       |  2 +-
 docs/library/mental-model.mdx                 |  2 +-
 docs/library/migration.mdx                    | 14 ++---
 docs/library/performance.mdx                  |  6 +--
 docs/library/quickstart.mdx                   |  4 +-
 docs/library/run-event-contract.mdx           |  2 +-
 .../snippets/01_minimal_chat_agent.mdx        |  4 +-
 docs/library/snippets/02_policy_with_hitl.mdx |  2 +-
 .../snippets/03_subagents_with_router.mdx     | 10 ++--
 .../snippets/04_resume_and_compact.mdx        |  2 +-
 .../05_direct_llm_structured_output.mdx       |  4 +-
 .../snippets/06_tool_registry_security.mdx    |  2 +-
 .../snippets/07_tool_hooks_and_middleware.mdx |  6 +--
 .../snippets/08_prebuilt_runtime_tools.mdx    |  6 +--
 .../snippets/09_system_prompt_loader.mdx      | 16 +++---
 .../10_streaming_chat_with_memory.mdx         |  2 +-
 docs/library/snippets/11_cost_monitoring.mdx  |  6 +--
 .../snippets/12_mcp_client_integration.mdx    |  6 +--
 .../snippets/13_multi_model_fallback.mdx      | 52 +++++++++----------
 .../library/snippets/14_production_client.mdx |  8 +--
 docs/library/streaming.mdx                    |  2 +-
 docs/library/system-prompts.mdx               | 10 ++--
 docs/library/task-queues.mdx                  |  2 +-
 docs/library/tools-system-walkthrough.mdx     |  2 +-
 docs/library/tools.mdx                        |  6 +--
 docs/library/troubleshooting.mdx              | 24 ++++-----
 docs/llms/adapters.mdx                        |  6 +--
 docs/llms/agent-integration.mdx               | 14 ++---
 docs/llms/contracts.mdx                       |  4 +-
 docs/llms/control-and-session.mdx             | 20 +++----
 docs/llms/index.mdx                           | 18 +++----
 examples/cookbooks/multi_agent.py             |  2 +-
 49 files changed, 171 insertions(+), 171 deletions(-)

diff --git a/docs/index.mdx b/docs/index.mdx
index d5348b8..a5b1bee 100644
--- a/docs/index.mdx
+++ b/docs/index.mdx
@@ -55,7 +55,7 @@ from afk.core import Runner
 
 agent = Agent(
     name="assistant",
-    model="gpt-4.1-mini",
+    model="gpt-5.5",
     instructions="Answer directly with concrete detail.",
 )
 
diff --git a/docs/library/a2a.mdx b/docs/library/a2a.mdx
index fc4a9e3..b157218 100644
--- a/docs/library/a2a.mdx
+++ b/docs/library/a2a.mdx
@@ -116,7 +116,7 @@ from afk.agents import Agent, A2AServiceHost, APIKeyA2AAuthProvider
 from afk.core import Runner
 
 # Define the agent
-analyzer = Agent(name="analyzer", model="gpt-4.1-mini", instructions="Analyze data.")
+analyzer = Agent(name="analyzer", model="gpt-5.5", instructions="Analyze data.")
 
 # Create auth provider
 auth = APIKeyA2AAuthProvider(
diff --git a/docs/library/agent-skills.mdx b/docs/library/agent-skills.mdx
index cf4e576..423c747 100644
--- a/docs/library/agent-skills.mdx
+++ b/docs/library/agent-skills.mdx
@@ -103,7 +103,7 @@ from afk.agents import Agent
 
 agent = Agent(
     name="devops-agent",
-    model="gpt-4.1-mini",
+    model="gpt-5.5",
     instructions="""
     You are a DevOps assistant. Use your skills to help with
     deployment, monitoring, and infrastructure tasks.
@@ -181,7 +181,7 @@ The agent autonomously decides which skills to read based on the user's question
     ```python
     agent = Agent(
         name="reader",
-        model="gpt-4.1-mini",
+        model="gpt-5.5",
         skills_dir="skills/",
         skill_tools=["list_skills", "read_skill_md", "read_skill_file"],
         # ← No run_skill_command
diff --git a/docs/library/agentic-behavior.mdx b/docs/library/agentic-behavior.mdx
index fdc8f2c..c0a7ff6 100644
--- a/docs/library/agentic-behavior.mdx
+++ b/docs/library/agentic-behavior.mdx
@@ -13,14 +13,14 @@ from afk.agents import Agent
 from afk.core import Runner
 
 # Specialist agents
-researcher = Agent(name="researcher", model="gpt-4.1-mini", instructions="Find facts.")
-writer = Agent(name="writer", model="gpt-4.1-mini", instructions="Write summaries.")
-reviewer = Agent(name="reviewer", model="gpt-4.1-mini", instructions="Review for accuracy.")
+researcher = Agent(name="researcher", model="gpt-5.5", instructions="Find facts.")
+writer = Agent(name="writer", model="gpt-5.5", instructions="Write summaries.")
+reviewer = Agent(name="reviewer", model="gpt-5.5", instructions="Review for accuracy.")
 
 # Coordinator
 coordinator = Agent(
     name="coordinator",
-    model="gpt-4.1-mini",
+    model="gpt-5.5",
     instructions="""
     1. Ask 'researcher' for facts
     2. Ask 'writer' to summarize
diff --git a/docs/library/agentic-levels.mdx b/docs/library/agentic-levels.mdx
index 8432b94..729d155 100644
--- a/docs/library/agentic-levels.mdx
+++ b/docs/library/agentic-levels.mdx
@@ -12,7 +12,7 @@ AFK applications progress through five levels of capability. Each level adds fea
     One agent, one model, no tools. The simplest possible setup.
 
     ```python
-    agent = Agent(name="classifier", model="gpt-4.1-mini", instructions="Classify as positive/negative/neutral.")
+    agent = Agent(name="classifier", model="gpt-5.5", instructions="Classify as positive/negative/neutral.")
     result = runner.run_sync(agent, user_message="Great product!")
     ```
 
@@ -31,7 +31,7 @@ AFK applications progress through five levels of capability. Each level adds fea
     @tool(args_model=SearchArgs, name="search", description="Search knowledge base.")
     def search(args: SearchArgs) -> dict: ...
 
-    agent = Agent(name="helper", model="gpt-4.1-mini", tools=[search])
+    agent = Agent(name="helper", model="gpt-5.5", tools=[search])
     ```
 
     **AFK features added:** `@tool`, Pydantic models, `FailSafeConfig`
@@ -48,7 +48,7 @@ AFK applications progress through five levels of capability. Each level adds fea
     ```python
     coordinator = Agent(
         name="coordinator",
-        model="gpt-4.1-mini",
+        model="gpt-5.5",
         subagents=[researcher, writer, reviewer],
     )
     ```
diff --git a/docs/library/agents.mdx b/docs/library/agents.mdx
index e6baea8..e8fec8a 100644
--- a/docs/library/agents.mdx
+++ b/docs/library/agents.mdx
@@ -12,7 +12,7 @@ from afk.agents import Agent
 
 agent = Agent(
     name="assistant",                          # ← Identity (used in logs, telemetry)
-    model="gpt-4.1-mini",                      # ← Which LLM to use
+    model="gpt-5.5",                      # ← Which LLM to use
     instructions="Be helpful and concise.",     # ← System prompt
 )
 ```
@@ -61,7 +61,7 @@ Those are the fields most examples should set. `model` is the only required cons
     ```python
     agent = Agent(
         name="classifier",
-        model="gpt-4.1-mini",
+        model="gpt-5.5",
         instructions="""
         Classify the input into one of: positive, negative, neutral.
         Output only the label.
@@ -81,19 +81,19 @@ Those are the fields most examples should set. `model` is the only required cons
     ```python
     researcher = Agent(
         name="researcher",
-        model="gpt-4.1-mini",
+        model="gpt-5.5",
         instructions="Find relevant facts. Be thorough.",
     )
 
     writer = Agent(
         name="writer",
-        model="gpt-4.1-mini",
+        model="gpt-5.5",
         instructions="Write clear, concise summaries.",
     )
 
     coordinator = Agent(
         name="coordinator",
-        model="gpt-4.1-mini",
+        model="gpt-5.5",
         instructions="""
         You manage a team:
         - Delegate research to 'researcher'
@@ -139,7 +139,7 @@ from afk.agents import Agent, FailSafeConfig
 
 agent = Agent(
     name="safe-agent",
-    model="gpt-4.1-mini",
+    model="gpt-5.5",
     instructions="...",
     tools=[...],
     fail_safe=FailSafeConfig(
@@ -155,7 +155,7 @@ agent = Agent(
         subagent_failure_policy="continue",               # "continue" | "retry_then_fail" | "skip_action"
 
         # Fallback model chain for LLM resilience
-        fallback_model_chain=["gpt-4.1-mini", "gpt-4.1-nano"],
+        fallback_model_chain=["gpt-5.5", "gpt-5.5"],
     ),
 )
 ```
diff --git a/docs/library/building-with-ai.mdx b/docs/library/building-with-ai.mdx
index fd1a3de..3bb2261 100644
--- a/docs/library/building-with-ai.mdx
+++ b/docs/library/building-with-ai.mdx
@@ -32,7 +32,7 @@ flowchart LR
     ```python
     agent = Agent(
         name="classifier",
-        model="gpt-4.1-mini",
+        model="gpt-5.5",
         instructions="""
         Classify the support ticket into exactly one category:
         billing, technical, account, feature-request, other.
@@ -58,7 +58,7 @@ flowchart LR
 
     agent = Agent(
         name="rag-agent",
-        model="gpt-4.1-mini",
+        model="gpt-5.5",
         instructions="""
         Always search the knowledge base before answering.
         Cite sources. If no relevant docs found, say so.
@@ -84,7 +84,7 @@ flowchart LR
 
     agent = Agent(
         name="coder",
-        model="gpt-4.1",
+        model="gpt-5.5",
         instructions="""
         Write code, then run the tests to verify.
         Fix any failures before presenting the final version.
@@ -110,7 +110,7 @@ flowchart LR
     ```python
     coordinator = Agent(
         name="coordinator",
-        model="gpt-4.1-mini",
+        model="gpt-5.5",
         instructions="""
         Route each request to the appropriate specialist:
         - Technical questions → 'engineer'
diff --git a/docs/library/checkpoint-schema.mdx b/docs/library/checkpoint-schema.mdx
index 24b18ec..b6eaa39 100644
--- a/docs/library/checkpoint-schema.mdx
+++ b/docs/library/checkpoint-schema.mdx
@@ -78,7 +78,7 @@ flowchart TB
 from afk.agents import Agent
 from afk.core import Runner
 
-agent = Agent(name="analyst", model="gpt-4.1-mini", instructions="Analyze data.")
+agent = Agent(name="analyst", model="gpt-5.5", instructions="Analyze data.")
 runner = Runner()
 
 # Start a run that might be interrupted
diff --git a/docs/library/core-runner.mdx b/docs/library/core-runner.mdx
index da4f807..f14317c 100644
--- a/docs/library/core-runner.mdx
+++ b/docs/library/core-runner.mdx
@@ -11,7 +11,7 @@ The **Runner** is the execution engine that runs agents. It manages the step loo
 from afk.agents import Agent
 from afk.core import Runner
 
-agent = Agent(name="demo", model="gpt-4.1-mini", instructions="Be helpful.")
+agent = Agent(name="demo", model="gpt-5.5", instructions="Be helpful.")
 runner = Runner()
 
 # Synchronous (simplest)
diff --git a/docs/library/deployment.mdx b/docs/library/deployment.mdx
index 381f5b3..88956b2 100644
--- a/docs/library/deployment.mdx
+++ b/docs/library/deployment.mdx
@@ -120,7 +120,7 @@ Create `config/production.yaml`:
 
 ```yaml
 agent:
-  default_model: gpt-4.1-mini
+  default_model: gpt-5.5
   default_fail_safe:
     max_steps: 20
     max_tool_calls: 10
diff --git a/docs/library/environment-variables.mdx b/docs/library/environment-variables.mdx
index 1d39895..c53d1a6 100644
--- a/docs/library/environment-variables.mdx
+++ b/docs/library/environment-variables.mdx
@@ -17,7 +17,7 @@ These variables configure the default LLM provider and behavior. They are read b
 | ------------------------------- | -------------- | ------------------------------------------------------------ |
 | `AFK_LLM_PROVIDER`              | `litellm`      | Default provider id (`openai`, `litellm`, `anthropic_agent`) |
 | `AFK_LLM_PROVIDER_ORDER`        | _(none)_       | Comma-separated provider preference order for routing helpers |
-| `AFK_LLM_MODEL`                 | `gpt-4.1-mini` | Default model name                                           |
+| `AFK_LLM_MODEL`                 | `gpt-5.5` | Default model name                                           |
 | `AFK_EMBED_MODEL`               | _(none)_       | Embedding model for vector operations                        |
 | `AFK_LLM_API_BASE_URL`          | _(none)_       | Provider API base URL                                        |
 | `AFK_LLM_API_KEY`               | _(none)_       | Provider API key                                             |
diff --git a/docs/library/evals.mdx b/docs/library/evals.mdx
index 2bb9f76..349dc89 100644
--- a/docs/library/evals.mdx
+++ b/docs/library/evals.mdx
@@ -14,7 +14,7 @@ from afk.evals import EvalCase, EvalSuiteConfig, StateCompletedAssertion, run_su
 
 agent = Agent(
     name="classifier",
-    model="gpt-4.1-mini",
+    model="gpt-5.5",
     instructions="Classify as: billing, technical, account, other. Output only the label.",
 )
 
diff --git a/docs/library/failure-policy-matrix.mdx b/docs/library/failure-policy-matrix.mdx
index dcae997..63e6342 100644
--- a/docs/library/failure-policy-matrix.mdx
+++ b/docs/library/failure-policy-matrix.mdx
@@ -65,7 +65,7 @@ agent = Agent(
     ...,
     fail_safe=FailSafeConfig(
         llm_failure_policy="degrade",              # "fail" or "degrade"
-        fallback_model_chain=["gpt-4.1-mini"],     # Try cheaper model
+        fallback_model_chain=["gpt-5.5"],     # Try cheaper model
     ),
 )
 ```
diff --git a/docs/library/how-to-use-afk.mdx b/docs/library/how-to-use-afk.mdx
index 45bd536..6f21841 100644
--- a/docs/library/how-to-use-afk.mdx
+++ b/docs/library/how-to-use-afk.mdx
@@ -15,7 +15,7 @@ from afk.core import Runner
 
 agent = Agent(
     name="ticket-classifier",
-    model="gpt-4.1-mini",
+    model="gpt-5.5",
     instructions="""
     Classify the support ticket as exactly one of:
     billing, technical, account, or other.
@@ -55,7 +55,7 @@ def lookup_ticket(args: TicketArgs) -> dict:
 
 agent = Agent(
     name="ticket-agent",
-    model="gpt-4.1-mini",
+    model="gpt-5.5",
     instructions="Look up tickets before answering. Never modify data.",
     tools=[lookup_ticket],
     fail_safe=FailSafeConfig(
diff --git a/docs/library/learn-in-15-minutes.mdx b/docs/library/learn-in-15-minutes.mdx
index ca8a1ae..b0a6f1c 100644
--- a/docs/library/learn-in-15-minutes.mdx
+++ b/docs/library/learn-in-15-minutes.mdx
@@ -13,7 +13,7 @@ from afk.core import Runner
 
 agent = Agent(
     name="tutor",
-    model="gpt-4.1-mini",
+    model="gpt-5.5",
     instructions="Explain programming concepts in plain language.",
 )
 
@@ -53,7 +53,7 @@ def search_docs(args: LookupArgs) -> dict:
 
 agent = Agent(
     name="research-tutor",
-    model="gpt-4.1-mini",
+    model="gpt-5.5",
     instructions="Search docs before answering user questions.",
     tools=[search_docs],
 )
@@ -82,7 +82,7 @@ from afk.core import Runner
 
 agent = Agent(
     name="streamer",
-    model="gpt-4.1-mini",
+    model="gpt-5.5",
     instructions="Explain topics clearly.",
 )
 
@@ -118,7 +118,7 @@ from afk.core import Runner
 
 agent = Agent(
     name="memory-tutor",
-    model="gpt-4.1-mini",
+    model="gpt-5.5",
     instructions="Remember the user's earlier questions in this thread.",
 )
 
@@ -157,7 +157,7 @@ from afk.core import Runner, RunnerConfig
 
 agent = Agent(
     name="bounded-agent",
-    model="gpt-4.1-mini",
+    model="gpt-5.5",
     instructions="Help users, but stop if the task becomes too large.",
     fail_safe=FailSafeConfig(
         max_steps=8,
diff --git a/docs/library/llm-interaction.mdx b/docs/library/llm-interaction.mdx
index 5f2a3a4..7606dc1 100644
--- a/docs/library/llm-interaction.mdx
+++ b/docs/library/llm-interaction.mdx
@@ -31,7 +31,7 @@ Each step in this flow is described in detail below.
 
 At each step of the agent loop, the runner builds an `LLMRequest` and sends it to the configured LLM provider. Here is what goes into the request:
 
-**Model resolution.** The agent's `model` field (e.g., `"gpt-4.1-mini"`) is resolved through the model resolution chain. This maps the requested model name to a provider, adapter, and normalized model identifier. Custom `model_resolver` functions can override this mapping.
+**Model resolution.** The agent's `model` field (e.g., `"gpt-5.5"`) is resolved through the model resolution chain. This maps the requested model name to a provider, adapter, and normalized model identifier. Custom `model_resolver` functions can override this mapping.
 
 **Message history.** The runner maintains a list of `Message` objects representing the conversation history. This includes:
 - A `system` message containing the agent's instructions, skill manifests, and (when enabled) an untrusted-data preamble.
@@ -48,7 +48,7 @@ At each step of the agent loop, the runner builds an `LLMRequest` and sends it t
 ```python
 # Simplified view of what the runner builds
 request = LLMRequest(
-    model="gpt-4.1-mini",
+    model="gpt-5.5",
     request_id=f"{run_id}:step:{step}",
     messages=messages,           # Full conversation history
     tools=tool_definitions,      # OpenAI-format function tools
diff --git a/docs/library/mcp-server.mdx b/docs/library/mcp-server.mdx
index 5dd64e8..03acd7c 100644
--- a/docs/library/mcp-server.mdx
+++ b/docs/library/mcp-server.mdx
@@ -111,7 +111,7 @@ Discover and use tools from any MCP server:
 
     agent = Agent(
         name="assistant",
-        model="gpt-4.1-mini",
+        model="gpt-5.5",
         instructions="Use available tools to help the user.",
         tools=tools,  # ← MCP tools work like local tools
     )
diff --git a/docs/library/memory.mdx b/docs/library/memory.mdx
index 2b344bf..f232104 100644
--- a/docs/library/memory.mdx
+++ b/docs/library/memory.mdx
@@ -12,7 +12,7 @@ import asyncio
 from afk.agents import Agent
 from afk.core import Runner
 
-agent = Agent(name="tutor", model="gpt-4.1-mini", instructions="You are a Python tutor.")
+agent = Agent(name="tutor", model="gpt-5.5", instructions="You are a Python tutor.")
 
 async def main():
     runner = Runner()
diff --git a/docs/library/mental-model.mdx b/docs/library/mental-model.mdx
index 1162648..760e199 100644
--- a/docs/library/mental-model.mdx
+++ b/docs/library/mental-model.mdx
@@ -54,7 +54,7 @@ flowchart LR
     # The Decision Loop is shaped by these fields
     agent = Agent(
         instructions="...",    # ← What the model knows
-        model="gpt-4.1-mini", # ← How the model thinks
+        model="gpt-5.5", # ← How the model thinks
         tools=[...],           # ← What the model can do
     )
     ```
diff --git a/docs/library/migration.mdx b/docs/library/migration.mdx
index 12effff..fa3e38a 100644
--- a/docs/library/migration.mdx
+++ b/docs/library/migration.mdx
@@ -26,7 +26,7 @@ This guide helps you migrate existing agent code from other frameworks to AFK.
 from langchain_openai import ChatOpenAI
 from langchain.agents import initialize_agent, Tool
 
-llm = ChatOpenAI(model="gpt-4")
+llm = ChatOpenAI(model="gpt-5.5")
 
 def search(query: str) -> str:
     return f"Results for: {query}"
@@ -56,7 +56,7 @@ def search(args: SearchArgs) -> dict:
 
 agent = Agent(
     name="assistant",
-    model="gpt-4.1-mini",
+    model="gpt-5.5",
     instructions="Use the search tool to find information.",
     tools=[search],
 )
@@ -215,7 +215,7 @@ stack = MiddlewareStack(
 client = (
     LLMBuilder()
     .provider("openai")
-    .model("gpt-4.1-mini")
+    .model("gpt-5.5")
     .with_middlewares(stack)
     .build()
 )
@@ -300,7 +300,7 @@ assistant = client.beta.assistants.create(
     name="Helper",
     instructions="You are a helpful assistant.",
     tools=[{"type": "function", "function": {...}}],
-    model="gpt-4",
+    model="gpt-5.5",
 )
 
 thread = client.beta.threads.create()
@@ -329,7 +329,7 @@ def help(args) -> dict:
 
 agent = Agent(
     name="helper",
-    model="gpt-4.1-mini",
+    model="gpt-5.5",
     instructions="You are a helpful assistant.",
     tools=[help],
 )
@@ -370,7 +370,7 @@ def call_with_retry(func, max_attempts=3):
 client = (
     LLMBuilder()
     .provider("openai")
-    .model("gpt-4.1-mini")
+    .model("gpt-5.5")
     .profile("production")
     .build()
 )
@@ -402,7 +402,7 @@ class CircuitBreaker:
 client = (
     LLMBuilder()
     .provider("openai")
-    .model("gpt-4.1-mini")
+    .model("gpt-5.5")
     .profile("production")
     .build()
 )
diff --git a/docs/library/performance.mdx b/docs/library/performance.mdx
index 39c7ccf..af097b9 100644
--- a/docs/library/performance.mdx
+++ b/docs/library/performance.mdx
@@ -14,13 +14,13 @@ from afk.agents import Agent
 
 classifier = Agent(
     name="classifier",
-    model="gpt-4.1-nano",
+    model="gpt-5.5",
     instructions="Classify the request. Return only one label.",
 )
 
 analyst = Agent(
     name="analyst",
-    model="gpt-4.1",
+    model="gpt-5.5",
     instructions="Perform detailed technical analysis.",
 )
 ```
@@ -95,7 +95,7 @@ from afk.agents import Agent, FailSafeConfig
 
 agent = Agent(
     name="bounded-agent",
-    model="gpt-4.1-mini",
+    model="gpt-5.5",
     instructions="Answer concisely and use tools only when needed.",
     fail_safe=FailSafeConfig(
         max_total_cost_usd=0.10,
diff --git a/docs/library/quickstart.mdx b/docs/library/quickstart.mdx
index 467d4e7..15ace04 100644
--- a/docs/library/quickstart.mdx
+++ b/docs/library/quickstart.mdx
@@ -29,7 +29,7 @@ from afk.core import Runner
 
 agent = Agent(
     name="assistant",
-    model="gpt-4.1-mini",
+    model="gpt-5.5",
     instructions="Answer directly. Keep responses under 120 words.",
 )
 
@@ -75,7 +75,7 @@ def lookup_order(args: OrderArgs) -> dict:
 
 agent = Agent(
     name="support-agent",
-    model="gpt-4.1-mini",
+    model="gpt-5.5",
     instructions="Use lookup_order when the user asks about an order.",
     tools=[lookup_order],
     fail_safe=FailSafeConfig(
diff --git a/docs/library/run-event-contract.mdx b/docs/library/run-event-contract.mdx
index 00fa03a..cb8da57 100644
--- a/docs/library/run-event-contract.mdx
+++ b/docs/library/run-event-contract.mdx
@@ -74,7 +74,7 @@ The primary way to consume events is through the run handle's `events` async ite
 from afk.agents import Agent
 from afk.core import Runner
 
-agent = Agent(name="demo", model="gpt-4.1-mini", instructions="Be helpful.")
+agent = Agent(name="demo", model="gpt-5.5", instructions="Be helpful.")
 runner = Runner()
 
 handle = await runner.run_handle(agent, user_message="Hello")
diff --git a/docs/library/snippets/01_minimal_chat_agent.mdx b/docs/library/snippets/01_minimal_chat_agent.mdx
index dc2fd0a..2bed4ac 100644
--- a/docs/library/snippets/01_minimal_chat_agent.mdx
+++ b/docs/library/snippets/01_minimal_chat_agent.mdx
@@ -11,7 +11,7 @@ If you are new to AFK, start here. Every other example builds on this foundation
 from afk.agents import Agent
 from afk.core import Runner
 
-agent = Agent(name="chat", model="gpt-4.1-mini", instructions="Answer directly with concrete detail.")
+agent = Agent(name="chat", model="gpt-5.5", instructions="Answer directly with concrete detail.")
 runner = Runner()
 result = runner.run_sync(agent, user_message="Define error budget in SRE.")
 print(result.final_text)
@@ -43,6 +43,6 @@ The `AgentResult` dataclass returned by `run_sync` includes:
 
 ## Expected behavior
 
-When you run this example, the runner makes a single LLM call to `gpt-4.1-mini` with the system instructions and user message. Since no tools are registered, the model responds with text only. The run completes in one step with `state="completed"`, and `final_text` contains a concise definition of error budgets in SRE.
+When you run this example, the runner makes a single LLM call to `gpt-5.5` with the system instructions and user message. Since no tools are registered, the model responds with text only. The run completes in one step with `state="completed"`, and `final_text` contains a concise definition of error budgets in SRE.
 
 No network calls, API keys, or external services are required beyond access to the specified LLM provider (configured via environment variables like `OPENAI_API_KEY`).
diff --git a/docs/library/snippets/02_policy_with_hitl.mdx b/docs/library/snippets/02_policy_with_hitl.mdx
index 320973a..6eb4fb8 100644
--- a/docs/library/snippets/02_policy_with_hitl.mdx
+++ b/docs/library/snippets/02_policy_with_hitl.mdx
@@ -29,7 +29,7 @@ policy = PolicyEngine(rules=[
 
 agent = Agent(
     name="change-manager",
-    model="gpt-4.1-mini",
+    model="gpt-5.5",
     instructions="You manage infrastructure changes. Always use available tools.",
 )
 
diff --git a/docs/library/snippets/03_subagents_with_router.mdx b/docs/library/snippets/03_subagents_with_router.mdx
index cf44d02..dd28514 100644
--- a/docs/library/snippets/03_subagents_with_router.mdx
+++ b/docs/library/snippets/03_subagents_with_router.mdx
@@ -30,24 +30,24 @@ from afk.core import Runner
 # Define specialist subagents
 triage = Agent(
     name="triage",
-    model="gpt-4.1-mini",
+    model="gpt-5.5",
     instructions="Classify incident severity as SEV1, SEV2, SEV3, or SEV4 based on the description.",
 )
 analysis = Agent(
     name="analysis",
-    model="gpt-4.1-mini",
+    model="gpt-5.5",
     instructions="Identify the most likely root causes for the described incident.",
 )
 comms = Agent(
     name="comms",
-    model="gpt-4.1-mini",
+    model="gpt-5.5",
     instructions="Draft a concise stakeholder update email summarizing the incident and current status.",
 )
 
 # Define the coordinator agent
 lead = Agent(
     name="lead",
-    model="gpt-4.1-mini",
+    model="gpt-5.5",
     instructions="Delegate to specialists and synthesize their outputs into a final response.",
     subagents=[triage, analysis, comms],
 )
@@ -99,7 +99,7 @@ from afk.agents import FailSafeConfig
 
 lead = Agent(
     name="lead",
-    model="gpt-4.1-mini",
+    model="gpt-5.5",
     instructions="Delegate to specialists. If any specialist fails, work with available results.",
     subagents=[triage, analysis, comms],
     fail_safe=FailSafeConfig(
diff --git a/docs/library/snippets/04_resume_and_compact.mdx b/docs/library/snippets/04_resume_and_compact.mdx
index b78669a..072b593 100644
--- a/docs/library/snippets/04_resume_and_compact.mdx
+++ b/docs/library/snippets/04_resume_and_compact.mdx
@@ -18,7 +18,7 @@ from afk.core import Runner, RunnerConfig
 
 agent = Agent(
     name="research-bot",
-    model="gpt-4.1-mini",
+    model="gpt-5.5",
     instructions="You help users research topics thoroughly.",
 )
 
diff --git a/docs/library/snippets/05_direct_llm_structured_output.mdx b/docs/library/snippets/05_direct_llm_structured_output.mdx
index 6b798a6..d55b9a7 100644
--- a/docs/library/snippets/05_direct_llm_structured_output.mdx
+++ b/docs/library/snippets/05_direct_llm_structured_output.mdx
@@ -20,7 +20,7 @@ class Summary(BaseModel):
     bullets: list[str]
 
 # Build an LLM client using the fluent builder
-client = LLMBuilder().provider("openai").model("gpt-4.1-mini").profile("production").build()
+client = LLMBuilder().provider("openai").model("gpt-5.5").profile("production").build()
 
 # Make a structured request
 resp = await client.chat(
@@ -39,7 +39,7 @@ print(resp.text)                 # The raw text response
 client = (
     LLMBuilder()
     .provider("openai")          # Which LLM provider to use
-    .model("gpt-4.1-mini")      # Which model
+    .model("gpt-5.5")      # Which model
     .profile("production")       # Apply a preset profile (retry, timeout, etc.)
     .build()                     # Return the configured LLMClient
 )
diff --git a/docs/library/snippets/06_tool_registry_security.mdx b/docs/library/snippets/06_tool_registry_security.mdx
index 4e908e7..69604ea 100644
--- a/docs/library/snippets/06_tool_registry_security.mdx
+++ b/docs/library/snippets/06_tool_registry_security.mdx
@@ -77,7 +77,7 @@ policy = PolicyEngine(rules=[
 
 agent = Agent(
     name="resource-manager",
-    model="gpt-4.1-mini",
+    model="gpt-5.5",
     instructions="Manage resources using the available tools. Always look up a resource before modifying it.",
     tools=[get_resource, delete_resource],
     fail_safe=FailSafeConfig(
diff --git a/docs/library/snippets/07_tool_hooks_and_middleware.mdx b/docs/library/snippets/07_tool_hooks_and_middleware.mdx
index bd55d42..ac74d33 100644
--- a/docs/library/snippets/07_tool_hooks_and_middleware.mdx
+++ b/docs/library/snippets/07_tool_hooks_and_middleware.mdx
@@ -177,7 +177,7 @@ async def add_request_metadata(call_next, req: LLMRequest) -> LLMResponse:
 client = (
     LLMBuilder()
     .provider("openai")
-    .model("gpt-4.1-mini")
+    .model("gpt-5.5")
     .profile("production")
     .with_middlewares(MiddlewareStack(
         chat=[add_request_metadata],
@@ -234,7 +234,7 @@ stack = MiddlewareStack(
 client = (
     LLMBuilder()
     .provider("openai")
-    .model("gpt-4.1-mini")
+    .model("gpt-5.5")
     .with_middlewares(stack)
     .build()
 )
@@ -243,7 +243,7 @@ client = (
 The timeout middleware respects `TimeoutPolicy` from the request if provided:
 ```python
 req = LLMRequest(
-    model="gpt-4.1-mini",
+    model="gpt-5.5",
     messages=[...],
     timeout_policy=TimeoutPolicy(request_timeout_s=45.0),  # Override config
 )
diff --git a/docs/library/snippets/08_prebuilt_runtime_tools.mdx b/docs/library/snippets/08_prebuilt_runtime_tools.mdx
index 774075e..8c0bd01 100644
--- a/docs/library/snippets/08_prebuilt_runtime_tools.mdx
+++ b/docs/library/snippets/08_prebuilt_runtime_tools.mdx
@@ -22,7 +22,7 @@ runtime_tools = build_runtime_tools(root_dir=Path("./workspace"))
 
 agent = Agent(
     name="file-assistant",
-    model="gpt-4.1-mini",
+    model="gpt-5.5",
     instructions=(
         "You help users explore and read files in the workspace directory. "
         "Use list_directory to browse the directory structure and read_file "
@@ -97,7 +97,7 @@ policy = PolicyEngine(
 
 agent = Agent(
     name="ops-assistant",
-    model="gpt-4.1-mini",
+    model="gpt-5.5",
     instructions="Use approved runtime tools only. Never read sensitive configuration without approval.",
     tools=build_runtime_tools(root_dir=Path("./project")),
 )
@@ -137,7 +137,7 @@ all_tools = build_runtime_tools(root_dir=Path("./workspace")) + [grep_files]
 
 agent = Agent(
     name="dev-assistant",
-    model="gpt-4.1-mini",
+    model="gpt-5.5",
     instructions="Help developers explore and search the codebase.",
     tools=all_tools,
 )
diff --git a/docs/library/snippets/09_system_prompt_loader.mdx b/docs/library/snippets/09_system_prompt_loader.mdx
index 7bdadf9..e4eb7f0 100644
--- a/docs/library/snippets/09_system_prompt_loader.mdx
+++ b/docs/library/snippets/09_system_prompt_loader.mdx
@@ -35,14 +35,14 @@ from afk.agents import Agent
 # Option 1: Inline instructions (highest priority)
 agent = Agent(
     name="ChatAgent",
-    model="gpt-4.1-mini",
+    model="gpt-5.5",
     instructions="Answer customer questions concisely.",
 )
 
 # Option 2: Explicit instruction file
 agent = Agent(
     name="ChatAgent",
-    model="gpt-4.1-mini",
+    model="gpt-5.5",
     instruction_file="chat_agent_system.md",   # Loaded from prompts_dir
     prompts_dir=".agents/prompt",
 )
@@ -51,7 +51,7 @@ agent = Agent(
 # Loads .agents/prompt/CHAT_AGENT.md automatically
 agent = Agent(
     name="ChatAgent",
-    model="gpt-4.1-mini",
+    model="gpt-5.5",
     prompts_dir=".agents/prompt",
 )
 ```
@@ -79,14 +79,14 @@ The prompts directory is resolved through its own priority chain:
 
 ```python
 # Explicit
-agent = Agent(name="Bot", model="gpt-4.1-mini", prompts_dir="/opt/prompts")
+agent = Agent(name="Bot", model="gpt-5.5", prompts_dir="/opt/prompts")
 
 # Environment variable
 # export AFK_AGENT_PROMPTS_DIR=/opt/prompts
-agent = Agent(name="Bot", model="gpt-4.1-mini")
+agent = Agent(name="Bot", model="gpt-5.5")
 
 # Default: .agents/prompt/
-agent = Agent(name="Bot", model="gpt-4.1-mini")
+agent = Agent(name="Bot", model="gpt-5.5")
 ```
 
 ## Jinja2 templating
@@ -117,7 +117,7 @@ from afk.core import Runner, RunnerConfig
 
 agent = Agent(
     name="SupportAgent",
-    model="gpt-4.1-mini",
+    model="gpt-5.5",
     prompts_dir=".agents/prompt",
 )
 
@@ -166,7 +166,7 @@ The prompt loader enforces strict path containment. The resolved prompt file pat
 # This would raise PromptAccessError:
 agent = Agent(
     name="Agent",
-    model="gpt-4.1-mini",
+    model="gpt-5.5",
     instruction_file="../../etc/passwd",   # Escapes prompts root
     prompts_dir=".agents/prompt",
 )
diff --git a/docs/library/snippets/10_streaming_chat_with_memory.mdx b/docs/library/snippets/10_streaming_chat_with_memory.mdx
index 8343459..1a8d4b4 100644
--- a/docs/library/snippets/10_streaming_chat_with_memory.mdx
+++ b/docs/library/snippets/10_streaming_chat_with_memory.mdx
@@ -16,7 +16,7 @@ from afk.core import Runner, RunnerConfig
 
 agent = Agent(
     name="chat-assistant",
-    model="gpt-4.1-mini",
+    model="gpt-5.5",
     instructions="""
     You are a helpful assistant. Remember context from earlier in the conversation.
     Be concise but thorough. If the user refers to something from a previous message,
diff --git a/docs/library/snippets/11_cost_monitoring.mdx b/docs/library/snippets/11_cost_monitoring.mdx
index 367354b..b29d16e 100644
--- a/docs/library/snippets/11_cost_monitoring.mdx
+++ b/docs/library/snippets/11_cost_monitoring.mdx
@@ -16,7 +16,7 @@ from afk.agents import Agent, FailSafeConfig
 
 agent = Agent(
     name="budget-agent",
-    model="gpt-4.1-mini",
+    model="gpt-5.5",
     instructions="Be helpful and concise.",
     fail_safe=FailSafeConfig(
         max_total_cost_usd=0.50,        # Hard cost ceiling
@@ -59,7 +59,7 @@ from afk.core import Runner
 
 agent = Agent(
     name="analyst",
-    model="gpt-4.1",
+    model="gpt-5.5",
     instructions="Provide detailed analysis.",
     fail_safe=FailSafeConfig(
         max_total_cost_usd=1.00,
@@ -114,7 +114,7 @@ async def batch_process(items: list[str], budget_usd: float):
         remaining = budget_usd - cumulative_cost
         agent = Agent(
             name="batch-processor",
-            model="gpt-4.1-mini",
+            model="gpt-5.5",
             instructions="Process the item concisely.",
             fail_safe=FailSafeConfig(
                 max_total_cost_usd=min(remaining, 0.10),  # Per-item cap
diff --git a/docs/library/snippets/12_mcp_client_integration.mdx b/docs/library/snippets/12_mcp_client_integration.mdx
index fac0039..c2c8c5a 100644
--- a/docs/library/snippets/12_mcp_client_integration.mdx
+++ b/docs/library/snippets/12_mcp_client_integration.mdx
@@ -31,7 +31,7 @@ async def main():
     # 3. Attach MCP tools to an agent — they work like local tools
     agent = Agent(
         name="mcp-assistant",
-        model="gpt-4.1-mini",
+        model="gpt-5.5",
         instructions="""
         Use the available tools to help the user.
         Always explain what tool you're using and why.
@@ -70,7 +70,7 @@ from afk.agents import Agent
 # The agent connects to MCP servers automatically during startup
 agent = Agent(
     name="connected-agent",
-    model="gpt-4.1-mini",
+    model="gpt-5.5",
     instructions="Use available tools to help the user.",
     mcp_servers=[
         "https://tools.example.com:3001",             # Simple URL
@@ -110,7 +110,7 @@ async def build_agent():
     # Combine local + external tools
     agent = Agent(
         name="hybrid-agent",
-        model="gpt-4.1-mini",
+        model="gpt-5.5",
         instructions="Use search tools for research and summarize for concise output.",
         tools=[summarize] + mcp_tools,  # ← Mix freely
     )
diff --git a/docs/library/snippets/13_multi_model_fallback.mdx b/docs/library/snippets/13_multi_model_fallback.mdx
index 9de71ef..66310ba 100644
--- a/docs/library/snippets/13_multi_model_fallback.mdx
+++ b/docs/library/snippets/13_multi_model_fallback.mdx
@@ -14,13 +14,13 @@ from afk.agents import Agent, FailSafeConfig
 
 agent = Agent(
     name="resilient-agent",
-    model="gpt-4.1",                    # Primary model
+    model="gpt-5.5",                    # Primary model
     instructions="Be helpful and thorough.",
     fail_safe=FailSafeConfig(
         # Fallback chain: try these models in order if the primary fails
         fallback_model_chain=[
-            "gpt-4.1-mini",              # First fallback: cheaper, faster
-            "gpt-4.1-nano",              # Last resort: fastest, cheapest
+            "gpt-5.5",              # First fallback: cheaper, faster
+            "gpt-5.5",              # Last resort: fastest, cheapest
         ],
 
         # When LLM calls fail, retry then degrade
@@ -32,11 +32,11 @@ agent = Agent(
 )
 ```
 
-When `gpt-4.1` fails (timeout, rate limit, outage):
+When `gpt-5.5` fails (timeout, rate limit, outage):
 
 1. AFK retries with the primary model (controlled by retry policy)
-2. If retries exhaust, it falls through to `gpt-4.1-mini`
-3. If that also fails, it tries `gpt-4.1-nano`
+2. If retries exhaust, it falls through to `gpt-5.5`
+3. If that also fails, it tries `gpt-5.5`
 4. If all models fail, the `llm_failure_policy` determines the outcome
 
 ## Cost-optimized fallback
@@ -50,13 +50,13 @@ from afk.core import Runner
 # Start cheap, escalate if quality is insufficient
 simple_agent = Agent(
     name="classifier",
-    model="gpt-4.1-nano",              # Start with cheapest
+    model="gpt-5.5",              # Start with cheapest
     instructions="""
     Classify the support ticket. Output exactly one label:
     billing, technical, account, other.
     """,
     fail_safe=FailSafeConfig(
-        fallback_model_chain=["gpt-4.1-mini", "gpt-4.1"],
+        fallback_model_chain=["gpt-5.5", "gpt-5.5"],
         max_total_cost_usd=0.05,
     ),
 )
@@ -64,13 +64,13 @@ simple_agent = Agent(
 # Complex tasks get the big model with fallbacks
 analysis_agent = Agent(
     name="analyst",
-    model="gpt-4.1",                   # Start with most capable
+    model="gpt-5.5",                   # Start with most capable
     instructions="""
     Provide detailed technical analysis with code examples.
     Be thorough and precise.
     """,
     fail_safe=FailSafeConfig(
-        fallback_model_chain=["gpt-4.1-mini"],
+        fallback_model_chain=["gpt-5.5"],
         llm_failure_policy="retry_then_degrade",
         max_total_cost_usd=2.00,
     ),
@@ -94,10 +94,10 @@ AFK's built-in circuit breaker works with fallback chains. When a model triggers
 ```python
 agent = Agent(
     name="breaker-demo",
-    model="gpt-4.1",
+    model="gpt-5.5",
     instructions="...",
     fail_safe=FailSafeConfig(
-        fallback_model_chain=["gpt-4.1-mini", "gpt-4.1-nano"],
+        fallback_model_chain=["gpt-5.5", "gpt-5.5"],
 
         # Circuit breaker settings
         breaker_failure_threshold=5,     # Open after 5 consecutive failures
@@ -112,10 +112,10 @@ agent = Agent(
 
 ```mermaid
 flowchart LR
-    A["gpt-4.1 fails 5x"] --> B["Circuit opens"]
-    B --> C["Skip to gpt-4.1-mini"]
+    A["gpt-5.5 fails 5x"] --> B["Circuit opens"]
+    B --> C["Skip to gpt-5.5"]
     C --> D["30s cooldown"]
-    D --> E["gpt-4.1 retried"]
+    D --> E["gpt-5.5 retried"]
     E -->|"succeeds"| F["Circuit closes"]
     E -->|"fails again"| B
 ```
@@ -130,27 +130,27 @@ from afk.agents import Agent, FailSafeConfig
 # Cheap model for simple classification
 router = Agent(
     name="router",
-    model="gpt-4.1-nano",
+    model="gpt-5.5",
     instructions="Route to the correct specialist.",
-    fail_safe=FailSafeConfig(fallback_model_chain=["gpt-4.1-mini"]),
+    fail_safe=FailSafeConfig(fallback_model_chain=["gpt-5.5"]),
     subagents=[
         # Powerful model for complex analysis
         Agent(
             name="analyst",
-            model="gpt-4.1",
+            model="gpt-5.5",
             instructions="Provide deep technical analysis.",
             fail_safe=FailSafeConfig(
-                fallback_model_chain=["gpt-4.1-mini"],
+                fallback_model_chain=["gpt-5.5"],
                 max_total_cost_usd=1.00,
             ),
         ),
         # Mid-tier model for summarization
         Agent(
             name="summarizer",
-            model="gpt-4.1-mini",
+            model="gpt-5.5",
             instructions="Summarize findings concisely.",
             fail_safe=FailSafeConfig(
-                fallback_model_chain=["gpt-4.1-nano"],
+                fallback_model_chain=["gpt-5.5"],
                 max_total_cost_usd=0.25,
             ),
         ),
@@ -177,11 +177,11 @@ print(f"Total cost: ${result.total_cost_usd or 0:.4f}")
 
 | Scenario                 | Primary Model  | Fallback Chain                  |
 | ------------------------ | -------------- | ------------------------------- |
-| **Classification**       | `gpt-4.1-nano` | `gpt-4.1-mini`                  |
-| **General chat**         | `gpt-4.1-mini` | `gpt-4.1-nano`                  |
-| **Complex analysis**     | `gpt-4.1`      | `gpt-4.1-mini` → `gpt-4.1-nano` |
-| **Code generation**      | `gpt-4.1`      | `gpt-4.1-mini`                  |
-| **Cost-sensitive batch** | `gpt-4.1-nano` | _(none)_                        |
+| **Classification**       | `gpt-5.5` | `gpt-5.5`                  |
+| **General chat**         | `gpt-5.5` | `gpt-5.5`                  |
+| **Complex analysis**     | `gpt-5.5`      | `gpt-5.5` → `gpt-5.5` |
+| **Code generation**      | `gpt-5.5`      | `gpt-5.5`                  |
+| **Cost-sensitive batch** | `gpt-5.5` | _(none)_                        |
 
 ## What to read next
 
diff --git a/docs/library/snippets/14_production_client.mdx b/docs/library/snippets/14_production_client.mdx
index 68cb010..b6e4fc2 100644
--- a/docs/library/snippets/14_production_client.mdx
+++ b/docs/library/snippets/14_production_client.mdx
@@ -41,7 +41,7 @@ stack = MiddlewareStack(
 production_client = (
     LLMBuilder()
     .provider("openai")
-    .model("gpt-4.1-mini")
+    .model("gpt-5.5")
     .profile("production")
     .with_middlewares(stack)
     .build()
@@ -54,7 +54,7 @@ production_client = (
 from afk.llms import TimeoutPolicy
 
 req = LLMRequest(
-    model="gpt-4.1-mini",
+    model="gpt-5.5",
     messages=[...],
     timeout_policy=TimeoutPolicy(request_timeout_s=120.0),  # Override default
 )
@@ -166,7 +166,7 @@ class ProductionSetup:
         self.llm_client = (
             LLMBuilder()
             .provider("openai")
-            .model("gpt-4.1-mini")
+            .model("gpt-5.5")
             .profile("production")
             .with_middlewares(stack)
             .build()
@@ -188,7 +188,7 @@ class ProductionSetup:
 async def main():
     agent = Agent(
         name="assistant",
-        model="gpt-4.1-mini",
+        model="gpt-5.5",
         instructions="You are a helpful assistant.",
     )
     
diff --git a/docs/library/streaming.mdx b/docs/library/streaming.mdx
index d3b2aea..767ecc1 100644
--- a/docs/library/streaming.mdx
+++ b/docs/library/streaming.mdx
@@ -12,7 +12,7 @@ import asyncio
 from afk.agents import Agent
 from afk.core import Runner
 
-agent = Agent(name="explainer", model="gpt-4.1-mini", instructions="Explain clearly.")
+agent = Agent(name="explainer", model="gpt-5.5", instructions="Explain clearly.")
 
 async def main():
     runner = Runner()
diff --git a/docs/library/system-prompts.mdx b/docs/library/system-prompts.mdx
index ea02977..abdc6d0 100644
--- a/docs/library/system-prompts.mdx
+++ b/docs/library/system-prompts.mdx
@@ -14,7 +14,7 @@ System prompts define what your agent knows and how it behaves. AFK supports thr
     ```python
     agent = Agent(
         name="assistant",
-        model="gpt-4.1-mini",
+        model="gpt-5.5",
         instructions="You are a helpful assistant. Be concise and accurate.",
     )
     ```
@@ -26,7 +26,7 @@ System prompts define what your agent knows and how it behaves. AFK supports thr
     ```python
     agent = Agent(
         name="analyst",
-        model="gpt-4.1-mini",
+        model="gpt-5.5",
         instruction_file="prompts/analyst.md",
     )
     ```
@@ -46,7 +46,7 @@ System prompts define what your agent knows and how it behaves. AFK supports thr
     AFK automatically looks for an instruction file based on the agent's name:
 
     ```python
-    agent = Agent(name="writer", model="gpt-4.1-mini")
+    agent = Agent(name="writer", model="gpt-5.5")
     # AFK looks for: prompts/writer.md, prompts/writer.txt, writer.md, etc.
     ```
 
@@ -84,7 +84,7 @@ Use `{{ variable }}` syntax to inject dynamic values into prompts:
 ```python
 agent = Agent(
     name="support-agent",
-    model="gpt-4.1-mini",
+    model="gpt-5.5",
     instructions="""
     You are a support agent for {{ company_name }}.
     Today's date is {{ current_date }}.
@@ -119,7 +119,7 @@ Templates work in instruction files too:
 ```python
 agent = Agent(
     name="reviewer",
-    model="gpt-4.1-mini",
+    model="gpt-5.5",
     instruction_file="prompts/reviewer.md",
     context={
         "language": "Python",
diff --git a/docs/library/task-queues.mdx b/docs/library/task-queues.mdx
index caa9447..3cbb2d1 100644
--- a/docs/library/task-queues.mdx
+++ b/docs/library/task-queues.mdx
@@ -12,7 +12,7 @@ from afk.queues import InMemoryTaskQueue, RUNNER_CHAT_CONTRACT, TaskWorker
 from afk.agents import Agent
 from afk.core import Runner
 
-agent = Agent(name="analyzer", model="gpt-4.1-mini", instructions="Analyze data.")
+agent = Agent(name="analyzer", model="gpt-5.5", instructions="Analyze data.")
 
 # Push a task
 queue = InMemoryTaskQueue()
diff --git a/docs/library/tools-system-walkthrough.mdx b/docs/library/tools-system-walkthrough.mdx
index 729c060..2156ffb 100644
--- a/docs/library/tools-system-walkthrough.mdx
+++ b/docs/library/tools-system-walkthrough.mdx
@@ -96,7 +96,7 @@ def search_docs(args: SearchArgs, ctx: ToolContext) -> dict:
 # 2. Create an agent with the tool
 agent = Agent(
     name="ops-assistant",
-    model="gpt-4.1-mini",
+    model="gpt-5.5",
     instructions="Use search_docs when the user asks for references.",
     tools=[search_docs],
 )
diff --git a/docs/library/tools.mdx b/docs/library/tools.mdx
index 360eade..83feabc 100644
--- a/docs/library/tools.mdx
+++ b/docs/library/tools.mdx
@@ -223,7 +223,7 @@ from afk.agents import Agent, PolicyEngine, PolicyRule
 
 agent = Agent(
     name="ops",
-    model="gpt-4.1-mini",
+    model="gpt-5.5",
     tools=[list_files, delete_file],
     policy_engine=PolicyEngine(rules=[
         PolicyRule(
@@ -430,7 +430,7 @@ tools = build_runtime_tools(root_dir="/workspace/project")
 
 agent = Agent(
     name="explorer",
-    model="gpt-4.1-mini",
+    model="gpt-5.5",
     instructions="Explore the project directory structure.",
     tools=tools,
 )
@@ -456,7 +456,7 @@ from afk.agents.types import SkillToolPolicy
 
 agent = Agent(
     name="maintainer",
-    model="gpt-4.1-mini",
+    model="gpt-5.5",
     skills=["maintainer"],
     skill_tool_policy=SkillToolPolicy(
         command_allowlist=["rg", "git", "python"],
diff --git a/docs/library/troubleshooting.mdx b/docs/library/troubleshooting.mdx
index 7112a42..de7ece5 100644
--- a/docs/library/troubleshooting.mdx
+++ b/docs/library/troubleshooting.mdx
@@ -24,7 +24,7 @@ from afk.agents import FailSafeConfig
 # Add hard limits to prevent runaway loops
 agent = Agent(
     name="safe-agent",
-    model="gpt-4.1-mini",
+    model="gpt-5.5",
     instructions="Complete the task in at most 3 tool calls. If you can't solve it, say so.",
     fail_safe=FailSafeConfig(
         max_tool_calls=5,  # Stop after 5 calls
@@ -57,7 +57,7 @@ runner = Runner(telemetry="console")
 ```python
 agent = Agent(
     name="helpful",
-    model="gpt-4.1-mini",
+    model="gpt-5.5",
     instructions="""
     You have access to the following tools:
     - search_docs: Use this to find information in the knowledge base
@@ -89,13 +89,13 @@ from afk.llms import LLMBuilder, LLMRequest, Message
 client = (
     LLMBuilder()
     .provider("openai")
-    .model("gpt-4.1-mini")
+    .model("gpt-5.5")
     .build()
 )
 
 response = await client.chat(
     LLMRequest(
-        model="gpt-4.1-mini",
+        model="gpt-5.5",
         messages=[Message(role="user", content="Classify this ticket")],
         temperature=0.0,
     )
@@ -184,7 +184,7 @@ from afk.llms import LLMSettings, RateLimitPolicy, create_llm_client
 
 client = create_llm_client(
     provider="openai",
-    settings=LLMSettings(default_model="gpt-4.1-mini"),
+    settings=LLMSettings(default_model="gpt-5.5"),
     rate_limit_policy=RateLimitPolicy(requests_per_second=0.5, burst=5),
 )
 
@@ -193,7 +193,7 @@ from afk.llms import RetryPolicy
 
 client = create_llm_client(
     provider="openai",
-    settings=LLMSettings(default_model="gpt-4.1-mini"),
+    settings=LLMSettings(default_model="gpt-5.5"),
     retry_policy=RetryPolicy(max_retries=5, backoff_base_s=2.0),
 )
 ```
@@ -212,7 +212,7 @@ from afk.llms import TimeoutPolicy
 
 client = create_llm_client(
     provider="openai",
-    settings=LLMSettings(default_model="gpt-4.1-mini"),
+    settings=LLMSettings(default_model="gpt-5.5"),
     timeout_policy=TimeoutPolicy(request_timeout_s=120.0),
 )
 
@@ -238,16 +238,16 @@ config = TimeoutConfig(
 client = (
     LLMBuilder()
     .provider("openai")
-    .model("gpt-4.1-mini")  # Check exact model name
+    .model("gpt-5.5")  # Check exact model name
     .build()
 )
 
 # Use fallback for resilience
 agent = Agent(
     name="resilient",
-    model="gpt-4.1",  # Primary model
+    model="gpt-5.5",  # Primary model
     fail_safe=FailSafeConfig(
-        fallback_model_chain=["gpt-4.1-mini", "gpt-4.1-nano"],
+        fallback_model_chain=["gpt-5.5", "gpt-5.5"],
     ),
 )
 ```
@@ -319,7 +319,7 @@ except asyncio.TimeoutError:
 # ALWAYS set cost limits
 agent = Agent(
     name="safe",
-    model="gpt-4.1-mini",
+    model="gpt-5.5",
     fail_safe=FailSafeConfig(
         max_total_cost_usd=0.50,  # Stop at $0.50
     ),
@@ -350,7 +350,7 @@ await runner.compact_thread(
 client = (
     LLMBuilder()
     .provider("openai")
-    .model("gpt-4.1")  # Larger context than gpt-4.1-mini
+    .model("gpt-5.5")  # Larger context than gpt-5.5
     .build()
 )
 ```
diff --git a/docs/llms/adapters.mdx b/docs/llms/adapters.mdx
index 9004cbd..27a4240 100644
--- a/docs/llms/adapters.mdx
+++ b/docs/llms/adapters.mdx
@@ -38,10 +38,10 @@ Providers translate between AFK's normalized contracts (`LLMRequest`/`LLMRespons
 from afk.llms import LLMBuilder
 
 # OpenAI
-openai_client = LLMBuilder().provider("openai").model("gpt-4.1-mini").build()
+openai_client = LLMBuilder().provider("openai").model("gpt-5.5").build()
 
 # Anthropic
-anthropic_client = LLMBuilder().provider("anthropic").model("claude-opus-4-5").build()
+anthropic_client = LLMBuilder().provider("anthropic").model("opus-4.8").build()
 
 # LiteLLM (any provider)
 gemini_client = LLMBuilder().provider("litellm").model("gemini/gemini-2.5-pro").build()
@@ -99,7 +99,7 @@ Use provider-specific settings for custom endpoints, proxy URLs, or credentials:
 client = (
     LLMBuilder()
     .provider("openai")
-    .model("gpt-4.1-mini")
+    .model("gpt-5.5")
     .with_provider_settings("openai", {"base_url": "https://proxy.example.com/v1"})
     .build()
 )
diff --git a/docs/llms/agent-integration.mdx b/docs/llms/agent-integration.mdx
index cbc86dc..980faca 100644
--- a/docs/llms/agent-integration.mdx
+++ b/docs/llms/agent-integration.mdx
@@ -16,7 +16,7 @@ Agents can specify their model in two ways:
     ```python
     agent = Agent(
         name="demo",
-        model="gpt-4.1-mini",
+        model="gpt-5.5",
         instructions="Answer directly.",
     )
     ```
@@ -36,7 +36,7 @@ Agents can specify their model in two ways:
     client = (
         LLMBuilder()
         .provider("openai")
-        .model("gpt-4.1-mini")
+        .model("gpt-5.5")
         .profile("production")
         .build()
     )
@@ -132,11 +132,11 @@ Treat these as example starting points. Confirm current model names, prices, and
 
 | Task                       | Starting model                  | Why                                 |
 | -------------------------- | ------------------------------ | ----------------------------------- |
-| Simple Q&A, classification | `gpt-4.1-nano`                 | Fast, cheap, good enough            |
-| General purpose with tools | `gpt-4.1-mini`                 | Best balance of cost and capability |
-| Complex reasoning, coding  | `gpt-4.1` or `claude-opus-4-5` | Better at multi-step reasoning      |
-| Cost-sensitive batch       | `gpt-4.1-nano`                 | Lowest cost per token               |
-| Higher quality generation  | `gpt-4.1` + low temperature    | More capability, less variation     |
+| Simple Q&A, classification | `gpt-5.5`                 | Fast, cheap, good enough            |
+| General purpose with tools | `gpt-5.5`                 | Best balance of cost and capability |
+| Complex reasoning, coding  | `gpt-5.5` or `opus-4.8` | Better at multi-step reasoning      |
+| Cost-sensitive batch       | `gpt-5.5`                 | Lowest cost per token               |
+| Higher quality generation  | `gpt-5.5` + low temperature    | More capability, less variation     |
 
 ## Next steps
 
diff --git a/docs/llms/contracts.mdx b/docs/llms/contracts.mdx
index 92d2472..3b65ed1 100644
--- a/docs/llms/contracts.mdx
+++ b/docs/llms/contracts.mdx
@@ -41,7 +41,7 @@ The adapter translates between AFK's normalized contracts and the provider's nat
             Message(role="system", content="You are a helpful assistant."),
             Message(role="user", content="What is Python?"),
         ],
-        model="gpt-4.1-mini",
+        model="gpt-5.5",
         temperature=0.7,
         max_tokens=500,
     )
@@ -90,7 +90,7 @@ class Sentiment(BaseModel):
 
 request = LLMRequest(
     messages=[Message(role="user", content="I love this product!")],
-    model="gpt-4.1-mini",
+    model="gpt-5.5",
     response_format=Sentiment,   # ← Forces structured JSON output
 )
 
diff --git a/docs/llms/control-and-session.mdx b/docs/llms/control-and-session.mdx
index 41628a9..aadcae0 100644
--- a/docs/llms/control-and-session.mdx
+++ b/docs/llms/control-and-session.mdx
@@ -30,10 +30,10 @@ Use `profile()` to apply a curated set of policies:
 from afk.llms import LLMBuilder
 
 # Development: no retry, no caching, fast failures
-dev = LLMBuilder().provider("openai").model("gpt-4.1-mini").profile("development").build()
+dev = LLMBuilder().provider("openai").model("gpt-5.5").profile("development").build()
 
 # Production: retry, circuit breaker, rate limiting, caching
-prod = LLMBuilder().provider("openai").model("gpt-4.1-mini").profile("production").build()
+prod = LLMBuilder().provider("openai").model("gpt-5.5").profile("production").build()
 ```
 
 | Profile       | Retry                           | Cache               | Rate Limit | Circuit Breaker        | Timeout |
@@ -55,7 +55,7 @@ Configure each policy independently with `create_llm_client()`:
 
     client = create_llm_client(
         provider="openai",
-        settings=LLMSettings(default_model="gpt-4.1-mini"),
+        settings=LLMSettings(default_model="gpt-5.5"),
         retry_policy=RetryPolicy(max_retries=3, backoff_base_s=1.0),
     )
     ```
@@ -76,7 +76,7 @@ Configure each policy independently with `create_llm_client()`:
 
     client = create_llm_client(
         provider="openai",
-        settings=LLMSettings(default_model="gpt-4.1-mini"),
+        settings=LLMSettings(default_model="gpt-5.5"),
         circuit_breaker_policy=CircuitBreakerPolicy(
             failure_threshold=5,
             cooldown_s=30.0,
@@ -102,7 +102,7 @@ Configure each policy independently with `create_llm_client()`:
 
     client = create_llm_client(
         provider="openai",
-        settings=LLMSettings(default_model="gpt-4.1-mini"),
+        settings=LLMSettings(default_model="gpt-5.5"),
         rate_limit_policy=RateLimitPolicy(requests_per_second=1.0, burst=10),
     )
     ```
@@ -116,7 +116,7 @@ Configure each policy independently with `create_llm_client()`:
 
     client = create_llm_client(
         provider="openai",
-        settings=LLMSettings(default_model="gpt-4.1-mini"),
+        settings=LLMSettings(default_model="gpt-5.5"),
         cache_policy=CachePolicy(enabled=True, ttl_s=300, namespace="docs"),
     )
     ```
@@ -135,7 +135,7 @@ Configure each policy independently with `create_llm_client()`:
 
     client = create_llm_client(
         provider="openai",
-        settings=LLMSettings(default_model="gpt-4.1-mini"),
+        settings=LLMSettings(default_model="gpt-5.5"),
         timeout_policy=TimeoutPolicy(request_timeout_s=60.0),
     )
     ```
@@ -152,12 +152,12 @@ from afk.agents import Agent, FailSafeConfig
 
 agent = Agent(
     name="resilient",
-    model="gpt-4.1",
+    model="gpt-5.5",
     fail_safe=FailSafeConfig(
-        fallback_model_chain=["gpt-4.1-mini", "gpt-4.1-nano"],
+        fallback_model_chain=["gpt-5.5", "gpt-5.5"],
     ),
 )
-# If gpt-4.1 fails → try gpt-4.1-mini → try gpt-4.1-nano
+# If gpt-5.5 fails → try gpt-5.5 → try gpt-5.5
 ```
 
 ## Tuning cheat sheet
diff --git a/docs/llms/index.mdx b/docs/llms/index.mdx
index 6c1d052..01e1b77 100644
--- a/docs/llms/index.mdx
+++ b/docs/llms/index.mdx
@@ -15,7 +15,7 @@ from afk.llms import LLMBuilder
 client = (
     LLMBuilder()
     .provider("openai")
-    .model("gpt-4.1-mini")
+    .model("gpt-5.5")
     .build()
 )
 ```
@@ -32,7 +32,7 @@ client = (
   <Step title="Set the model">
 
     ```python
-    builder = builder.model("gpt-4.1-mini")
+    builder = builder.model("gpt-5.5")
     ```
 
   </Step>
@@ -85,7 +85,7 @@ stack = MiddlewareStack(
 client = (
     LLMBuilder()
     .provider("openai")
-    .model("gpt-4.1-mini")
+    .model("gpt-5.5")
     .with_middlewares(stack)
     .build()
 )
@@ -107,7 +107,7 @@ async def tracing_middleware(call_next, req: LLMRequest) -> LLMResponse:
 client = (
     LLMBuilder()
     .provider("openai")
-    .model("gpt-4.1-mini")
+    .model("gpt-5.5")
     .with_middlewares(MiddlewareStack(
         chat=[tracing_middleware],
         embed=[],
@@ -147,9 +147,9 @@ Use these as starting points, then verify model availability, pricing, and conte
 
 | Scenario                   | Starting point                                  |
 | -------------------------- | ----------------------------------------------- |
-| General purpose            | OpenAI `gpt-4.1-mini`                           |
-| Complex reasoning          | OpenAI `gpt-4.1` or Anthropic `claude-opus-4-5` |
-| Cost-sensitive             | OpenAI `gpt-4.1-nano`                           |
+| General purpose            | OpenAI `gpt-5.5`                           |
+| Complex reasoning          | OpenAI `gpt-5.5` or Anthropic `opus-4.8` |
+| Cost-sensitive             | OpenAI `gpt-5.5`                           |
 | Non-OpenAI/Anthropic model | LiteLLM adapter                                 |
 | Custom or self-hosted      | Custom adapter                                  |
 
@@ -159,10 +159,10 @@ You rarely build `LLMClient` directly. Agents resolve their model automatically:
 
 ```python
 # Option 1: Model name (auto-resolved)
-agent = Agent(name="demo", model="gpt-4.1-mini", instructions="Answer directly.")
+agent = Agent(name="demo", model="gpt-5.5", instructions="Answer directly.")
 
 # Option 2: Pre-built client (full control)
-client = LLMBuilder().provider("openai").model("gpt-4.1-mini").profile("production").build()
+client = LLMBuilder().provider("openai").model("gpt-5.5").profile("production").build()
 agent = Agent(name="demo", model=client, instructions="Answer directly.")
 ```
 
diff --git a/examples/cookbooks/multi_agent.py b/examples/cookbooks/multi_agent.py
index cf448aa..f02a923 100644
--- a/examples/cookbooks/multi_agent.py
+++ b/examples/cookbooks/multi_agent.py
@@ -21,7 +21,7 @@ def search_docs(query: str) -> ToolResult[str]:
 def run_query(sql: str) -> ToolResult[str]:
     """Simulate a database query."""
     return ToolResult(output=f"Query result for: {sql}")
-
+  
 
 async def main() -> None:
     # Specialized subagents