diff --git a/docs/quick-start.md b/docs/quick-start.md
index a9944c99..292f0826 100644
--- a/docs/quick-start.md
+++ b/docs/quick-start.md
@@ -95,6 +95,11 @@ with no API keys and no outbound network.
 === "Agno"
 
     ```python
+    from agent_assembly import init_assembly
+    from agent_assembly.adapters.agno import AgnoPatch
+
+    from src.policy import LocalPolicyEngine
+
     with init_assembly(
         gateway_url=gateway_url,
         api_key=api_key,
@@ -126,9 +131,21 @@ with no API keys and no outbound network.
         )
     ```
 
+    !!! note "Version compatibility"
+        Agno was previously published as **Phidata**; the rename replaced every `phi.*` import with `agno.*`.
+
+        - Before (Phidata): `from phi.agent import Agent`
+        - After (Agno): `from agno.agent import Agent`
+
+        Source: [Agno's official Phidata → Agno migration guide](https://docs.agno.com/how-to/phidata-to-agno).
+
 === "AutoGen"
 
     ```python
+    from agent_assembly import init_assembly
+
+    from src.policy import LocalPolicyEngine
+
     with init_assembly(
         gateway_url=gateway_url,
         api_key=api_key,
@@ -143,9 +160,23 @@ with no API keys and no outbound network.
         policy = LocalPolicyEngine()
     ```
 
+    !!! note "Version compatibility"
+        AutoGen's `v0.4` rewrite (2024) replaced the single `pyautogen` package's `autogen.agentchat` namespace with separate `autogen-agentchat` / `autogen-core` / `autogen-ext` packages, and `llm_config` with an explicit `model_client`.
+
+        - Before (v0.2, `pyautogen`): `from autogen.agentchat import AssistantAgent`
+        - After (v0.4+): `from autogen_agentchat.agents import AssistantAgent`
+
+        Source: [AutoGen's official v0.2 → v0.4 migration guide](https://microsoft.github.io/autogen/stable/user-guide/agentchat-user-guide/migration-guide.html).
+
 === "CrewAI"
 
     ```python
+    from agent_assembly import init_assembly
+    from agent_assembly.adapters.langchain import AssemblyCallbackHandler
+
+    from src.crew import CREW
+    from src.policy import DAILY_BUDGET_USD, CrewPolicyEngine, MockApprover
+
     with init_assembly(
         gateway_url=gateway_url,
         api_key=api_key,
@@ -175,6 +206,16 @@ with no API keys and no outbound network.
 === "Custom (no framework)"
 
     ```python
+    from agent_assembly import init_assembly
+
+    from src.policy import LocalPolicyEngine, governed
+    from src.tools import (
+        compute_sum,
+        fetch_stock_price,
+        send_http_request,
+        write_to_disk,
+    )
+
     with init_assembly(
         gateway_url=gateway_url,
         api_key=api_key,
@@ -200,6 +241,12 @@ with no API keys and no outbound network.
 === "Google ADK"
 
     ```python
+    from agent_assembly import init_assembly
+
+    from src.governance import govern_tool_class, ungovern_tool_class
+    from src.policy import LocalPolicyEngine
+    from src.tools import DemoTool
+
     # Govern the concrete demo tool class BEFORE init_assembly so the offline
     # LocalPolicyEngine stays wired as the interceptor (the patch is idempotent).
     govern_tool_class(DemoTool, LocalPolicyEngine())
@@ -211,11 +258,28 @@ with no API keys and no outbound network.
             agent_id="google-adk-demo-agent",
             mode="sdk-only",
         ) as ctx:
+            print(f"  Agent:    {ctx.client.agent_id}")
+            print(f"  Gateway:  {ctx.client.gateway_url}")
+            print(f"  Mode:     {ctx.network_mode} (offline demo)")
+            print()
+
+            print("Policy rules (local simulation of gateway policy):")
+            print("  DENY    — delete_records, write_file  (destructive operations)")
+            print("  PENDING — send_email                  (requires human approval)")
+            print("  ALLOW   — everything else")
+            print()
+    finally:
+        ungovern_tool_class(DemoTool)
     ```
 
 === "Haystack"
 
     ```python
+    from agent_assembly import init_assembly
+    from agent_assembly.adapters.haystack import HaystackPatch
+
+    from src.policy import LocalPolicyEngine
+
     with init_assembly(
         gateway_url=gateway_url,
         api_key=api_key,
@@ -245,9 +309,22 @@ with no API keys and no outbound network.
         installed = patch.apply()
     ```
 
+    !!! note "Version compatibility"
+        Haystack 2.0 replaced the `farm-haystack` package with `haystack-ai` and flattened node imports into `haystack.components.*`; the two package versions cannot coexist in one environment.
+
+        - Before (Haystack 1.x, `farm-haystack`): `from haystack.nodes import BM25Retriever`
+        - After (Haystack 2.x, `haystack-ai`): `from haystack.components.retrievers.in_memory import InMemoryBM25Retriever`
+
+        Source: [Haystack's official migration guide](https://docs.haystack.deepset.ai/docs/migration).
+
 === "LangChain"
 
     ```python
+    from agent_assembly import init_assembly
+    from agent_assembly.adapters.langchain import AssemblyCallbackHandler
+
+    from src.policy import LocalPolicyEngine
+
     with init_assembly(
         gateway_url=gateway_url,
         api_key=api_key,
@@ -263,9 +340,22 @@ with no API keys and no outbound network.
         handler = AssemblyCallbackHandler(interceptor=policy)
     ```
 
+    !!! note "Version compatibility"
+        LangChain's import surface moved twice: `langchain-core` split out of `langchain` across the `0.1` → `0.3` series (2024), and the `1.0` rewrite (2025) moved legacy chains/agents/tools out of `langchain` entirely into `langchain-classic`.
+
+        - Before (`<1.0`): `from langchain.agents import AgentExecutor, create_react_agent`
+        - After (`>=1.0`): `from langchain_classic.agents import AgentExecutor, create_react_agent` (requires the separate `langchain-classic` package)
+
+        This SDK's own quick-start sample hit exactly this break — see AAASM-4451. Sources: [LangChain's official v1 migration guide](https://docs.langchain.com/oss/python/migrate/langchain-v1) and the [LangChain v0.3 announcement](https://www.langchain.com/blog/announcing-langchain-v0-3).
+
 === "LangChain (Research Agent)"
 
     ```python
+    from agent_assembly import init_assembly
+    from agent_assembly.adapters.langchain import AssemblyCallbackHandler
+
+    from src.policy import DAILY_BUDGET_USD, BalancedPolicyEngine
+
     with init_assembly(
         gateway_url=gateway_url,
         api_key=api_key,
@@ -281,9 +371,23 @@ with no API keys and no outbound network.
         handler = AssemblyCallbackHandler(interceptor=policy)
     ```
 
+    !!! note "Version compatibility"
+        LangChain's import surface moved twice: `langchain-core` split out of `langchain` across the `0.1` → `0.3` series (2024), and the `1.0` rewrite (2025) moved legacy chains/agents/tools out of `langchain` entirely into `langchain-classic`.
+
+        - Before (`<1.0`): `from langchain.agents import AgentExecutor, create_react_agent`
+        - After (`>=1.0`): `from langchain_classic.agents import AgentExecutor, create_react_agent` (requires the separate `langchain-classic` package)
+
+        This SDK's own quick-start sample hit exactly this break — see AAASM-4451. Sources: [LangChain's official v1 migration guide](https://docs.langchain.com/oss/python/migrate/langchain-v1) and the [LangChain v0.3 announcement](https://www.langchain.com/blog/announcing-langchain-v0-3).
+
 === "LangGraph"
 
     ```python
+    from agent_assembly import init_assembly
+    from agent_assembly.adapters.langchain import AssemblyCallbackHandler
+    from agent_assembly.adapters.langgraph import LangGraphAdapter
+
+    from src.policy import LocalPolicyEngine
+
     with init_assembly(
         gateway_url=gateway_url,
         api_key=api_key,
@@ -305,9 +409,22 @@ with no API keys and no outbound network.
         adapter.register_hooks(handler)
     ```
 
+    !!! note "Version compatibility"
+        LangGraph `1.0` deprecated `langgraph.prebuilt.create_react_agent` in favor of LangChain's own agent constructor.
+
+        - Before (`<1.0`): `from langgraph.prebuilt import create_react_agent`
+        - After (`>=1.0`): `from langchain.agents import create_agent`
+
+        Source: [LangGraph's official v1 migration guide](https://docs.langchain.com/oss/python/migrate/langgraph-v1).
+
 === "LlamaIndex"
 
     ```python
+    from agent_assembly import init_assembly
+    from agent_assembly.adapters.llamaindex import LlamaIndexAdapter, LlamaIndexPatch
+
+    from src.policy import LocalPolicyEngine
+
     with init_assembly(
         gateway_url=gateway_url,
         api_key=api_key,
@@ -339,9 +456,24 @@ with no API keys and no outbound network.
         adapter.register_hooks(LocalPolicyEngine())
     ```
 
+    !!! note "Version compatibility"
+        LlamaIndex `v0.10.0` (February 2024) split the monolithic `llama_index` package into a slim `llama-index-core` plus versioned per-provider packages (`llama-index-llms-openai`, etc.). An automated `llamaindex-cli upgrade` tool is provided for the migration.
+
+        - Before (`<0.10`): `from llama_index.llms import OpenAI`
+        - After (`>=0.10`): `from llama_index.llms.openai import OpenAI` (from the separate `llama-index-llms-openai` package)
+
+        Source: [LlamaIndex's official v0.10 migration guide](https://www.llamaindex.ai/blog/llamaindex-v0-10-838e735948f8).
+
 === "Microsoft Agent Framework"
 
     ```python
+    from agent_assembly import init_assembly
+    from agent_assembly.adapters.microsoft_agent_framework import (
+        MicrosoftAgentFrameworkAdapter,
+    )
+
+    from src.policy import LocalPolicyEngine
+
     policy = LocalPolicyEngine()
 
     # Live path: install the governance hooks BEFORE init_assembly. The adapter
@@ -362,11 +494,29 @@ with no API keys and no outbound network.
             agent_id="microsoft-agent-framework-demo-agent",
             mode="sdk-only",
         ) as ctx:
+            print(f"  Agent:    {ctx.client.agent_id}")
+            print(f"  Gateway:  {ctx.client.gateway_url}")
+            print(f"  Mode:     {ctx.network_mode} (offline demo)")
+            print()
+
+            print("Policy rules (local simulation of gateway policy):")
+            print("  DENY    — delete_records, write_file  (destructive operations)")
+            print("  PENDING — send_email                  (requires human approval)")
+            print("  ALLOW   — everything else")
+            print()
+    finally:
+        if adapter is not None:
+            adapter.unregister_hooks()
     ```
 
 === "OpenAI Agents SDK"
 
     ```python
+    from agent_assembly import init_assembly
+    from agent_assembly.adapters.langchain import AssemblyCallbackHandler
+
+    from src.policy import LocalPolicyEngine
+
     with init_assembly(
         gateway_url=gateway_url,
         api_key=api_key,
@@ -385,6 +535,11 @@ with no API keys and no outbound network.
 === "Pydantic AI"
 
     ```python
+    from agent_assembly import init_assembly
+    from agent_assembly.adapters.pydantic_ai import PydanticAIAdapter
+
+    from src.policy import LocalPolicyEngine
+
     adapter = PydanticAIAdapter()
     adapter.set_process_agent_id("pydantic-ai-demo-agent")
     adapter.register_hooks(LocalPolicyEngine())
@@ -396,11 +551,28 @@ with no API keys and no outbound network.
             agent_id="pydantic-ai-demo-agent",
             mode="sdk-only",
         ) as ctx:
+            print(f"  Agent:    {ctx.client.agent_id}")
+            print(f"  Gateway:  {ctx.client.gateway_url}")
+            print(f"  Mode:     {ctx.network_mode} (offline demo)")
+            print()
+
+            print("Policy rules (local simulation of gateway policy):")
+            print("  DENY    — delete_records, write_file  (destructive operations)")
+            print("  PENDING — send_email                  (requires human approval)")
+            print("  ALLOW   — everything else")
+            print()
+    finally:
+        adapter.unregister_hooks()
     ```
 
 === "Semantic Kernel"
 
     ```python
+    from agent_assembly import init_assembly
+
+    from src.policy import LocalPolicyEngine
+    from src.tools import build_kernel
+
     with init_assembly(
         gateway_url=gateway_url,
         api_key=api_key,
@@ -419,6 +591,11 @@ with no API keys and no outbound network.
 === "smolagents"
 
     ```python
+    from agent_assembly import init_assembly
+    from agent_assembly.adapters.smolagents import SmolagentsPatch
+
+    from src.policy import LocalPolicyEngine
+
     policy = LocalPolicyEngine()
     patch = SmolagentsPatch(policy)
     patch.apply()
@@ -433,9 +610,21 @@ with no API keys and no outbound network.
     ) as ctx:
     ```
 
+    !!! note "Version compatibility"
+        smolagents `v1.14.0` (April 2025) renamed `HfApiModel` to `InferenceClientModel` to reflect that it wraps any Hugging Face Inference Provider, not just the HF Hub; backward-compatible re-export was restored in `v1.24.0`.
+
+        - Before (`<1.14`): `from smolagents import HfApiModel`
+        - After (`>=1.14`): `from smolagents import InferenceClientModel`
+
+        Source: [smolagents releases](https://github.com/huggingface/smolagents/releases).
+
 === "Strands Agents"
 
     ```python
+    from agent_assembly import init_assembly
+
+    from src.policy import LocalPolicyEngine
+
     with init_assembly(
         gateway_url=gateway_url,
         api_key=api_key,
diff --git a/quickstart_snippets/agno-tool-policy.py b/quickstart_snippets/agno-tool-policy.py
index 454b0894..482dd47f 100644
--- a/quickstart_snippets/agno-tool-policy.py
+++ b/quickstart_snippets/agno-tool-policy.py
@@ -1,3 +1,8 @@
+from agent_assembly import init_assembly
+from agent_assembly.adapters.agno import AgnoPatch
+
+from src.policy import LocalPolicyEngine
+
 with init_assembly(
     gateway_url=gateway_url,
     api_key=api_key,
diff --git a/quickstart_snippets/autogen-tool-policy.py b/quickstart_snippets/autogen-tool-policy.py
index 82b71661..f1c61c4f 100644
--- a/quickstart_snippets/autogen-tool-policy.py
+++ b/quickstart_snippets/autogen-tool-policy.py
@@ -1,3 +1,7 @@
+from agent_assembly import init_assembly
+
+from src.policy import LocalPolicyEngine
+
 with init_assembly(
     gateway_url=gateway_url,
     api_key=api_key,
diff --git a/quickstart_snippets/crewai-research-crew.py b/quickstart_snippets/crewai-research-crew.py
index ae693944..2b2fc581 100644
--- a/quickstart_snippets/crewai-research-crew.py
+++ b/quickstart_snippets/crewai-research-crew.py
@@ -1,3 +1,9 @@
+from agent_assembly import init_assembly
+from agent_assembly.adapters.langchain import AssemblyCallbackHandler
+
+from src.crew import CREW
+from src.policy import DAILY_BUDGET_USD, CrewPolicyEngine, MockApprover
+
 with init_assembly(
     gateway_url=gateway_url,
     api_key=api_key,
diff --git a/quickstart_snippets/custom-tool-policy.py b/quickstart_snippets/custom-tool-policy.py
index 3c83bf48..31438a3a 100644
--- a/quickstart_snippets/custom-tool-policy.py
+++ b/quickstart_snippets/custom-tool-policy.py
@@ -1,3 +1,13 @@
+from agent_assembly import init_assembly
+
+from src.policy import LocalPolicyEngine, governed
+from src.tools import (
+    compute_sum,
+    fetch_stock_price,
+    send_http_request,
+    write_to_disk,
+)
+
 with init_assembly(
     gateway_url=gateway_url,
     api_key=api_key,
diff --git a/quickstart_snippets/google-adk.py b/quickstart_snippets/google-adk.py
index 1efd391b..78629ce1 100644
--- a/quickstart_snippets/google-adk.py
+++ b/quickstart_snippets/google-adk.py
@@ -1,3 +1,9 @@
+from agent_assembly import init_assembly
+
+from src.governance import govern_tool_class, ungovern_tool_class
+from src.policy import LocalPolicyEngine
+from src.tools import DemoTool
+
 # Govern the concrete demo tool class BEFORE init_assembly so the offline
 # LocalPolicyEngine stays wired as the interceptor (the patch is idempotent).
 govern_tool_class(DemoTool, LocalPolicyEngine())
@@ -9,3 +15,15 @@
         agent_id="google-adk-demo-agent",
         mode="sdk-only",
     ) as ctx:
+        print(f"  Agent:    {ctx.client.agent_id}")
+        print(f"  Gateway:  {ctx.client.gateway_url}")
+        print(f"  Mode:     {ctx.network_mode} (offline demo)")
+        print()
+
+        print("Policy rules (local simulation of gateway policy):")
+        print("  DENY    — delete_records, write_file  (destructive operations)")
+        print("  PENDING — send_email                  (requires human approval)")
+        print("  ALLOW   — everything else")
+        print()
+finally:
+    ungovern_tool_class(DemoTool)
diff --git a/quickstart_snippets/haystack-tool-policy.py b/quickstart_snippets/haystack-tool-policy.py
index f0424de3..42e797b6 100644
--- a/quickstart_snippets/haystack-tool-policy.py
+++ b/quickstart_snippets/haystack-tool-policy.py
@@ -1,3 +1,8 @@
+from agent_assembly import init_assembly
+from agent_assembly.adapters.haystack import HaystackPatch
+
+from src.policy import LocalPolicyEngine
+
 with init_assembly(
     gateway_url=gateway_url,
     api_key=api_key,
diff --git a/quickstart_snippets/langchain-basic-agent.py b/quickstart_snippets/langchain-basic-agent.py
index 74b9afcf..8e2eaa7a 100644
--- a/quickstart_snippets/langchain-basic-agent.py
+++ b/quickstart_snippets/langchain-basic-agent.py
@@ -1,3 +1,8 @@
+from agent_assembly import init_assembly
+from agent_assembly.adapters.langchain import AssemblyCallbackHandler
+
+from src.policy import LocalPolicyEngine
+
 with init_assembly(
     gateway_url=gateway_url,
     api_key=api_key,
diff --git a/quickstart_snippets/langchain-research-agent.py b/quickstart_snippets/langchain-research-agent.py
index ff179593..9a9fe0ee 100644
--- a/quickstart_snippets/langchain-research-agent.py
+++ b/quickstart_snippets/langchain-research-agent.py
@@ -1,3 +1,8 @@
+from agent_assembly import init_assembly
+from agent_assembly.adapters.langchain import AssemblyCallbackHandler
+
+from src.policy import DAILY_BUDGET_USD, BalancedPolicyEngine
+
 with init_assembly(
     gateway_url=gateway_url,
     api_key=api_key,
diff --git a/quickstart_snippets/langgraph.py b/quickstart_snippets/langgraph.py
index ccffca96..347dbe9e 100644
--- a/quickstart_snippets/langgraph.py
+++ b/quickstart_snippets/langgraph.py
@@ -1,3 +1,9 @@
+from agent_assembly import init_assembly
+from agent_assembly.adapters.langchain import AssemblyCallbackHandler
+from agent_assembly.adapters.langgraph import LangGraphAdapter
+
+from src.policy import LocalPolicyEngine
+
 with init_assembly(
     gateway_url=gateway_url,
     api_key=api_key,
diff --git a/quickstart_snippets/llamaindex-tool-policy.py b/quickstart_snippets/llamaindex-tool-policy.py
index 672538dc..6cd1d72a 100644
--- a/quickstart_snippets/llamaindex-tool-policy.py
+++ b/quickstart_snippets/llamaindex-tool-policy.py
@@ -1,3 +1,8 @@
+from agent_assembly import init_assembly
+from agent_assembly.adapters.llamaindex import LlamaIndexAdapter, LlamaIndexPatch
+
+from src.policy import LocalPolicyEngine
+
 with init_assembly(
     gateway_url=gateway_url,
     api_key=api_key,
diff --git a/quickstart_snippets/manifest.json b/quickstart_snippets/manifest.json
index db69a595..d4a2c612 100644
--- a/quickstart_snippets/manifest.json
+++ b/quickstart_snippets/manifest.json
@@ -1,6 +1,6 @@
 {
   "schema_version": 1,
-  "source": "ai-agent-assembly/examples: snippets/manifest.json (AAASM-4512, PR examples#267)",
+  "source": "ai-agent-assembly/examples: snippets/manifest.json (AAASM-4512, PR examples#267). The optional 'version_compat_note' field on some entries is a python-sdk-local addition (AAASM-4590), not present upstream.",
   "sdk": "python",
   "frameworks": [
     {
@@ -8,14 +8,16 @@
       "label": "Agno",
       "status": "validated",
       "lang": "python",
-      "source_example": "python/agno-tool-policy/src/main.py"
+      "source_example": "python/agno-tool-policy/src/main.py",
+      "version_compat_note": "Agno was previously published as **Phidata**; the rename replaced every `phi.*` import with `agno.*`.\n\n- Before (Phidata): `from phi.agent import Agent`\n- After (Agno): `from agno.agent import Agent`\n\nSource: [Agno's official Phidata → Agno migration guide](https://docs.agno.com/how-to/phidata-to-agno)."
     },
     {
       "framework_id": "autogen-tool-policy",
       "label": "AutoGen",
       "status": "validated",
       "lang": "python",
-      "source_example": "python/autogen-tool-policy/src/main.py"
+      "source_example": "python/autogen-tool-policy/src/main.py",
+      "version_compat_note": "AutoGen's `v0.4` rewrite (2024) replaced the single `pyautogen` package's `autogen.agentchat` namespace with separate `autogen-agentchat` / `autogen-core` / `autogen-ext` packages, and `llm_config` with an explicit `model_client`.\n\n- Before (v0.2, `pyautogen`): `from autogen.agentchat import AssistantAgent`\n- After (v0.4+): `from autogen_agentchat.agents import AssistantAgent`\n\nSource: [AutoGen's official v0.2 → v0.4 migration guide](https://microsoft.github.io/autogen/stable/user-guide/agentchat-user-guide/migration-guide.html)."
     },
     {
       "framework_id": "crewai-research-crew",
@@ -43,35 +45,40 @@
       "label": "Haystack",
       "status": "validated",
       "lang": "python",
-      "source_example": "python/haystack-tool-policy/src/main.py"
+      "source_example": "python/haystack-tool-policy/src/main.py",
+      "version_compat_note": "Haystack 2.0 replaced the `farm-haystack` package with `haystack-ai` and flattened node imports into `haystack.components.*`; the two package versions cannot coexist in one environment.\n\n- Before (Haystack 1.x, `farm-haystack`): `from haystack.nodes import BM25Retriever`\n- After (Haystack 2.x, `haystack-ai`): `from haystack.components.retrievers.in_memory import InMemoryBM25Retriever`\n\nSource: [Haystack's official migration guide](https://docs.haystack.deepset.ai/docs/migration)."
     },
     {
       "framework_id": "langchain-basic-agent",
       "label": "LangChain",
       "status": "validated",
       "lang": "python",
-      "source_example": "python/langchain-basic-agent/src/main.py"
+      "source_example": "python/langchain-basic-agent/src/main.py",
+      "version_compat_note": "LangChain's import surface moved twice: `langchain-core` split out of `langchain` across the `0.1` → `0.3` series (2024), and the `1.0` rewrite (2025) moved legacy chains/agents/tools out of `langchain` entirely into `langchain-classic`.\n\n- Before (`<1.0`): `from langchain.agents import AgentExecutor, create_react_agent`\n- After (`>=1.0`): `from langchain_classic.agents import AgentExecutor, create_react_agent` (requires the separate `langchain-classic` package)\n\nThis SDK's own quick-start sample hit exactly this break — see AAASM-4451. Sources: [LangChain's official v1 migration guide](https://docs.langchain.com/oss/python/migrate/langchain-v1) and the [LangChain v0.3 announcement](https://www.langchain.com/blog/announcing-langchain-v0-3)."
     },
     {
       "framework_id": "langchain-research-agent",
       "label": "LangChain (Research Agent)",
       "status": "validated",
       "lang": "python",
-      "source_example": "python/langchain-research-agent/src/main.py"
+      "source_example": "python/langchain-research-agent/src/main.py",
+      "version_compat_note": "LangChain's import surface moved twice: `langchain-core` split out of `langchain` across the `0.1` → `0.3` series (2024), and the `1.0` rewrite (2025) moved legacy chains/agents/tools out of `langchain` entirely into `langchain-classic`.\n\n- Before (`<1.0`): `from langchain.agents import AgentExecutor, create_react_agent`\n- After (`>=1.0`): `from langchain_classic.agents import AgentExecutor, create_react_agent` (requires the separate `langchain-classic` package)\n\nThis SDK's own quick-start sample hit exactly this break — see AAASM-4451. Sources: [LangChain's official v1 migration guide](https://docs.langchain.com/oss/python/migrate/langchain-v1) and the [LangChain v0.3 announcement](https://www.langchain.com/blog/announcing-langchain-v0-3)."
     },
     {
       "framework_id": "langgraph",
       "label": "LangGraph",
       "status": "validated",
       "lang": "python",
-      "source_example": "python/langgraph/src/main.py"
+      "source_example": "python/langgraph/src/main.py",
+      "version_compat_note": "LangGraph `1.0` deprecated `langgraph.prebuilt.create_react_agent` in favor of LangChain's own agent constructor.\n\n- Before (`<1.0`): `from langgraph.prebuilt import create_react_agent`\n- After (`>=1.0`): `from langchain.agents import create_agent`\n\nSource: [LangGraph's official v1 migration guide](https://docs.langchain.com/oss/python/migrate/langgraph-v1)."
     },
     {
       "framework_id": "llamaindex-tool-policy",
       "label": "LlamaIndex",
       "status": "validated",
       "lang": "python",
-      "source_example": "python/llamaindex-tool-policy/src/main.py"
+      "source_example": "python/llamaindex-tool-policy/src/main.py",
+      "version_compat_note": "LlamaIndex `v0.10.0` (February 2024) split the monolithic `llama_index` package into a slim `llama-index-core` plus versioned per-provider packages (`llama-index-llms-openai`, etc.). An automated `llamaindex-cli upgrade` tool is provided for the migration.\n\n- Before (`<0.10`): `from llama_index.llms import OpenAI`\n- After (`>=0.10`): `from llama_index.llms.openai import OpenAI` (from the separate `llama-index-llms-openai` package)\n\nSource: [LlamaIndex's official v0.10 migration guide](https://www.llamaindex.ai/blog/llamaindex-v0-10-838e735948f8)."
     },
     {
       "framework_id": "microsoft-agent-framework-tool-policy",
@@ -106,7 +113,8 @@
       "label": "smolagents",
       "status": "validated",
       "lang": "python",
-      "source_example": "python/smolagents-tool-policy/src/main.py"
+      "source_example": "python/smolagents-tool-policy/src/main.py",
+      "version_compat_note": "smolagents `v1.14.0` (April 2025) renamed `HfApiModel` to `InferenceClientModel` to reflect that it wraps any Hugging Face Inference Provider, not just the HF Hub; backward-compatible re-export was restored in `v1.24.0`.\n\n- Before (`<1.14`): `from smolagents import HfApiModel`\n- After (`>=1.14`): `from smolagents import InferenceClientModel`\n\nSource: [smolagents releases](https://github.com/huggingface/smolagents/releases)."
     },
     {
       "framework_id": "strands-agents-tool-policy",
diff --git a/quickstart_snippets/microsoft-agent-framework-tool-policy.py b/quickstart_snippets/microsoft-agent-framework-tool-policy.py
index 6874538b..fee46e6b 100644
--- a/quickstart_snippets/microsoft-agent-framework-tool-policy.py
+++ b/quickstart_snippets/microsoft-agent-framework-tool-policy.py
@@ -1,3 +1,10 @@
+from agent_assembly import init_assembly
+from agent_assembly.adapters.microsoft_agent_framework import (
+    MicrosoftAgentFrameworkAdapter,
+)
+
+from src.policy import LocalPolicyEngine
+
 policy = LocalPolicyEngine()
 
 # Live path: install the governance hooks BEFORE init_assembly. The adapter
@@ -18,3 +25,16 @@
         agent_id="microsoft-agent-framework-demo-agent",
         mode="sdk-only",
     ) as ctx:
+        print(f"  Agent:    {ctx.client.agent_id}")
+        print(f"  Gateway:  {ctx.client.gateway_url}")
+        print(f"  Mode:     {ctx.network_mode} (offline demo)")
+        print()
+
+        print("Policy rules (local simulation of gateway policy):")
+        print("  DENY    — delete_records, write_file  (destructive operations)")
+        print("  PENDING — send_email                  (requires human approval)")
+        print("  ALLOW   — everything else")
+        print()
+finally:
+    if adapter is not None:
+        adapter.unregister_hooks()
diff --git a/quickstart_snippets/openai-agents-sdk.py b/quickstart_snippets/openai-agents-sdk.py
index 076c3bf9..8390909e 100644
--- a/quickstart_snippets/openai-agents-sdk.py
+++ b/quickstart_snippets/openai-agents-sdk.py
@@ -1,3 +1,8 @@
+from agent_assembly import init_assembly
+from agent_assembly.adapters.langchain import AssemblyCallbackHandler
+
+from src.policy import LocalPolicyEngine
+
 with init_assembly(
     gateway_url=gateway_url,
     api_key=api_key,
diff --git a/quickstart_snippets/pydantic-ai.py b/quickstart_snippets/pydantic-ai.py
index 20043aa5..da8a4bc4 100644
--- a/quickstart_snippets/pydantic-ai.py
+++ b/quickstart_snippets/pydantic-ai.py
@@ -1,3 +1,8 @@
+from agent_assembly import init_assembly
+from agent_assembly.adapters.pydantic_ai import PydanticAIAdapter
+
+from src.policy import LocalPolicyEngine
+
 adapter = PydanticAIAdapter()
 adapter.set_process_agent_id("pydantic-ai-demo-agent")
 adapter.register_hooks(LocalPolicyEngine())
@@ -9,3 +14,15 @@
         agent_id="pydantic-ai-demo-agent",
         mode="sdk-only",
     ) as ctx:
+        print(f"  Agent:    {ctx.client.agent_id}")
+        print(f"  Gateway:  {ctx.client.gateway_url}")
+        print(f"  Mode:     {ctx.network_mode} (offline demo)")
+        print()
+
+        print("Policy rules (local simulation of gateway policy):")
+        print("  DENY    — delete_records, write_file  (destructive operations)")
+        print("  PENDING — send_email                  (requires human approval)")
+        print("  ALLOW   — everything else")
+        print()
+finally:
+    adapter.unregister_hooks()
diff --git a/quickstart_snippets/semantic-kernel-tool-policy.py b/quickstart_snippets/semantic-kernel-tool-policy.py
index 7d5feb30..87152324 100644
--- a/quickstart_snippets/semantic-kernel-tool-policy.py
+++ b/quickstart_snippets/semantic-kernel-tool-policy.py
@@ -1,3 +1,8 @@
+from agent_assembly import init_assembly
+
+from src.policy import LocalPolicyEngine
+from src.tools import build_kernel
+
 with init_assembly(
     gateway_url=gateway_url,
     api_key=api_key,
diff --git a/quickstart_snippets/smolagents-tool-policy.py b/quickstart_snippets/smolagents-tool-policy.py
index e83897ad..7171b2bf 100644
--- a/quickstart_snippets/smolagents-tool-policy.py
+++ b/quickstart_snippets/smolagents-tool-policy.py
@@ -1,3 +1,8 @@
+from agent_assembly import init_assembly
+from agent_assembly.adapters.smolagents import SmolagentsPatch
+
+from src.policy import LocalPolicyEngine
+
 policy = LocalPolicyEngine()
 patch = SmolagentsPatch(policy)
 patch.apply()
diff --git a/quickstart_snippets/strands-agents-tool-policy.py b/quickstart_snippets/strands-agents-tool-policy.py
index 11f82087..3cba7408 100644
--- a/quickstart_snippets/strands-agents-tool-policy.py
+++ b/quickstart_snippets/strands-agents-tool-policy.py
@@ -1,3 +1,7 @@
+from agent_assembly import init_assembly
+
+from src.policy import LocalPolicyEngine
+
 with init_assembly(
     gateway_url=gateway_url,
     api_key=api_key,
diff --git a/scripts/generate_quickstart_tabs.py b/scripts/generate_quickstart_tabs.py
index 6e29e28d..04c7ee6c 100644
--- a/scripts/generate_quickstart_tabs.py
+++ b/scripts/generate_quickstart_tabs.py
@@ -23,6 +23,13 @@
 * Idempotent: running twice produces no diff. The drift check enforces this.
 * Data-driven: the tab list is exactly ``manifest.json``'s ``frameworks`` array,
   in listed order, so a framework added upstream appears once it is re-vendored.
+
+A framework entry may carry an optional ``version_compat_note`` (AAASM-4590):
+markdown text rendered as a nested "Version compatibility" admonition beneath that
+framework's code fence. This is a local extension of the vendored manifest schema
+(not part of the upstream ``examples`` copy) — the note isn't tied to a runnable
+example, it exists to warn readers about a real, citable import-path break in the
+framework's own version history. Add one only when there's a real source to cite.
 """
 
 from __future__ import annotations
@@ -59,11 +66,22 @@ def _indent_tab_body(line: str) -> str:
     return f"    {line}" if line else ""
 
 
-def render_tab(label: str, code: str) -> str:
-    """Render one ``=== "<label>"`` tab wrapping *code* in a python fence."""
+def render_tab(label: str, code: str, version_compat_note: str | None = None) -> str:
+    """Render one ``=== "<label>"`` tab wrapping *code* in a python fence.
+
+    *version_compat_note*, when the manifest entry carries one (AAASM-4590), is
+    rendered as a nested ``!!! note "Version compatibility"`` admonition beneath the
+    code fence — double-indented (tab body + admonition body) per mkdocs-material's
+    nesting convention. Only frameworks with a real, citable import-path break across
+    versions get one; see the manifest for the sources.
+    """
 
     body = ["```python", *code.splitlines(), "```"]
     lines = [f'=== "{label}"', "", *[_indent_tab_body(b) for b in body]]
+    if version_compat_note:
+        lines.append("")
+        lines.append(_indent_tab_body('!!! note "Version compatibility"'))
+        lines.extend(_indent_tab_body(_indent_tab_body(note_line)) for note_line in version_compat_note.splitlines())
     return "\n".join(lines)
 
 
@@ -85,7 +103,7 @@ def build_block(vendor_dir: Path) -> str:
         if not snippet_path.is_file():
             raise GenerateError(f"manifest lists '{framework_id}' but its snippet is missing: " f"{snippet_path}")
         code = snippet_path.read_text(encoding="utf-8").rstrip("\n")
-        tabs.append(render_tab(entry["label"], code))
+        tabs.append(render_tab(entry["label"], code, entry.get("version_compat_note")))
 
     return "\n".join([BEGIN_MARKER, "", "\n\n".join(tabs), "", END_MARKER])