docs(onboarding): add first v1.1 starter wave

README.md

@@ -171,6 +171,7 @@ Start here for the deeper deployment details:
 - [Integrations](./docs/INTEGRATIONS.md)
 - [Onboarding](./docs/ONBOARDING.md)
 - [Examples](./docs/examples)
+- [First-wave AI-native starters](./docs/AI-NATIVE-MATRIX.md#first-wave-template-set-for-v110)
 - [Security review for `v1.0.0`](./docs/SECURITY-REVIEW-v1.0.0.md)
 - [Publishing](./docs/PUBLISHING.md)
 - [Troubleshooting](./docs/TROUBLESHOOTING.md)

docs/INTEGRATIONS.md

@@ -113,6 +113,47 @@ Starter snippet:
 
 - [examples/client-ai-native-app-profile.yaml](./examples/client-ai-native-app-profile.yaml)
 
+## First-wave agent and framework starters
+
+The first post-`1.0` expansion wave focuses on clients that can already use FoundryGate cleanly through the common OpenAI-compatible path.
+
+### SWE-AF
+
+- starter: [examples/swe-af-foundrygate.env.example](./examples/swe-af-foundrygate.env.example)
+- recommended header: `X-FoundryGate-Client: swe-af`
+- recommended profile name: `swe-af`
+
+### paperclip
+
+- starter: [examples/paperclip-foundrygate.env.example](./examples/paperclip-foundrygate.env.example)
+- recommended header: `X-FoundryGate-Client: paperclip`
+- recommended profile name: `paperclip`
+
+### ship-faster
+
+- starter: [examples/ship-faster-foundrygate.env.example](./examples/ship-faster-foundrygate.env.example)
+- recommended header: `X-FoundryGate-Client: ship-faster`
+- recommended profile name: `ship-faster`
+
+### LangChain
+
+- starter: [examples/langchain-foundrygate.env.example](./examples/langchain-foundrygate.env.example)
+- recommended header: `X-FoundryGate-Client: langchain`
+- recommended profile name: `langchain`
+
+### LangGraph
+
+- starter: [examples/langgraph-foundrygate.env.example](./examples/langgraph-foundrygate.env.example)
+- recommended header: `X-FoundryGate-Client: langgraph`
+- recommended profile name: `langgraph`
+
+These starters are intentionally small:
+
+- keep one local OpenAI-compatible base URL
+- keep one stable client tag
+- use client profiles only when the framework traffic really needs distinct routing behavior
+- validate with `POST /api/route` and `GET /api/traces` before adding policies or hooks
+
 ## Provider onboarding
 
 When onboarding a new provider:

docs/ONBOARDING.md

@@ -150,6 +150,23 @@ Starter files:
 - [examples/n8n-foundrygate-http-request.json](./examples/n8n-foundrygate-http-request.json)
 - [examples/cli-foundrygate-env.sh](./examples/cli-foundrygate-env.sh)
 - [examples/client-ai-native-app-profile.yaml](./examples/client-ai-native-app-profile.yaml)
+- [examples/swe-af-foundrygate.env.example](./examples/swe-af-foundrygate.env.example)
+- [examples/paperclip-foundrygate.env.example](./examples/paperclip-foundrygate.env.example)
+- [examples/ship-faster-foundrygate.env.example](./examples/ship-faster-foundrygate.env.example)
+- [examples/langchain-foundrygate.env.example](./examples/langchain-foundrygate.env.example)
+- [examples/langgraph-foundrygate.env.example](./examples/langgraph-foundrygate.env.example)
+
+### 3b. First-wave framework starters
+
+The first post-`1.0` framework wave keeps every client on the same OpenAI-compatible entry point and varies only the stable client tag:
+
+- `SWE-AF` -> `X-FoundryGate-Client: swe-af`
+- `paperclip` -> `X-FoundryGate-Client: paperclip`
+- `ship-faster` -> `X-FoundryGate-Client: ship-faster`
+- `LangChain` -> `X-FoundryGate-Client: langchain`
+- `LangGraph` -> `X-FoundryGate-Client: langgraph`
+
+Use the starter env files above first, then add explicit profile rules only if one framework needs different locality, provider, or cost behavior.
 
 ### 4. Add request hooks only if needed
 

docs/examples/langchain-foundrygate.env.example

@@ -0,0 +1,6 @@
+# Example FoundryGate environment for LangChain / LangGraph stacks.
+
+export OPENAI_API_KEY="local"
+export OPENAI_BASE_URL="http://127.0.0.1:8090/v1"
+export FOUNDRYGATE_CLIENT_HEADER="X-FoundryGate-Client: langchain"
+

docs/examples/langgraph-foundrygate.env.example

@@ -0,0 +1,6 @@
+# Example FoundryGate environment for LangGraph applications.
+
+export OPENAI_API_KEY="local"
+export OPENAI_BASE_URL="http://127.0.0.1:8090/v1"
+export FOUNDRYGATE_CLIENT_HEADER="X-FoundryGate-Client: langgraph"
+

docs/examples/paperclip-foundrygate.env.example

@@ -0,0 +1,6 @@
+# Example FoundryGate environment for Paperclip.
+
+export OPENAI_BASE_URL="http://127.0.0.1:8090/v1"
+export OPENAI_API_KEY="local"
+export FOUNDRYGATE_CLIENT_HEADER="X-FoundryGate-Client: paperclip"
+

docs/examples/ship-faster-foundrygate.env.example

@@ -0,0 +1,6 @@
+# Example FoundryGate environment for ship-faster.
+
+export OPENAI_BASE_URL="http://127.0.0.1:8090/v1"
+export OPENAI_API_KEY="local"
+export FOUNDRYGATE_CLIENT_HEADER="X-FoundryGate-Client: ship-faster"
+

docs/examples/swe-af-foundrygate.env.example

@@ -0,0 +1,6 @@
+# Example FoundryGate environment for SWE-AF.
+
+export OPENAI_BASE_URL="http://127.0.0.1:8090/v1"
+export OPENAI_API_KEY="local"
+export FOUNDRYGATE_CLIENT_HEADER="X-FoundryGate-Client: swe-af"
+

foundrygate/onboarding.py

@@ -348,6 +348,78 @@ def build_onboarding_report(
                 " truly needs them.",
             ],
         },
+        "swe-af": {
+            "recommended": "swe-af" in profile_names,
+            "header": "X-FoundryGate-Client: swe-af",
+            "profile": "swe-af",
+            "snippet": [
+                "export OPENAI_BASE_URL=http://127.0.0.1:8090/v1",
+                "export OPENAI_API_KEY=local",
+            ],
+            "notes": [
+                "Treat SWE-AF like another OpenAI-compatible agent client first, not a"
+                " special runtime.",
+                "Keep a stable client header so coding and delegated subflows remain"
+                " attributable in traces.",
+            ],
+        },
+        "paperclip": {
+            "recommended": "paperclip" in profile_names,
+            "header": "X-FoundryGate-Client: paperclip",
+            "profile": "paperclip",
+            "snippet": [
+                "export OPENAI_BASE_URL=http://127.0.0.1:8090/v1",
+                "export OPENAI_API_KEY=local",
+            ],
+            "notes": [
+                "Start with the common OpenAI-compatible path before inventing a deeper adapter.",
+                "Use client profiles only when paperclip traffic should differ from"
+                " other app traffic.",
+            ],
+        },
+        "ship-faster": {
+            "recommended": "ship-faster" in profile_names,
+            "header": "X-FoundryGate-Client: ship-faster",
+            "profile": "ship-faster",
+            "snippet": [
+                "export OPENAI_BASE_URL=http://127.0.0.1:8090/v1",
+                "export OPENAI_API_KEY=local",
+            ],
+            "notes": [
+                "Use one short client tag first; add more profile splits only when the"
+                " workflow actually needs them.",
+                "Prefer hook-based overrides only for narrow rollout or locality constraints.",
+            ],
+        },
+        "langchain": {
+            "recommended": "langchain" in profile_names,
+            "header": "X-FoundryGate-Client: langchain",
+            "profile": "langchain",
+            "snippet": [
+                "export OPENAI_BASE_URL=http://127.0.0.1:8090/v1",
+                "export OPENAI_API_KEY=local",
+            ],
+            "notes": [
+                "LangChain should stay on the OpenAI-compatible path unless a"
+                " framework-specific blocker appears.",
+                "Use route previews before splitting chain traffic into multiple custom profiles.",
+            ],
+        },
+        "langgraph": {
+            "recommended": "langgraph" in profile_names,
+            "header": "X-FoundryGate-Client: langgraph",
+            "profile": "langgraph",
+            "snippet": [
+                "export OPENAI_BASE_URL=http://127.0.0.1:8090/v1",
+                "export OPENAI_API_KEY=local",
+            ],
+            "notes": [
+                "Keep LangGraph on the shared gateway path and use client tags to"
+                " distinguish graph traffic from generic LangChain traffic.",
+                "Only add dedicated policies when graph workloads need stricter"
+                " locality or cost boundaries.",
+            ],
+        },
     }
 
     return {