pattern-zones-co · matthew-petty · Dec 25, 2025 · Dec 25, 2025
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -15,14 +15,15 @@ bun run openapi:check    # Verify spec is up to date
 
 ## Running Examples
 
-With a gateway running, you can test SDK examples:
+With a gateway running, you can test SDK examples from the SDK directories:
 
 ```bash
-bun run docs/examples/typescript/hello.ts
-bun run docs/examples/typescript/conversation.ts
+cd packages/sdks/typescript
+bun run example:hello
+bun run example:conversation
 ```
 
-See [docs/examples/](docs/examples/) for all available examples.
+The npm scripts load `.env` from the project root. See each SDK's `examples/` directory for all available examples.
 
 ## Pre-commit Hooks
 

diff --git a/docs/examples/README.md b/docs/examples/README.md
@@ -1,54 +1,8 @@
 # SDK Examples
 
-Examples demonstrating how to use Koine SDKs.
+Examples demonstrating how to use Koine SDKs are located in their respective SDK package directories:
 
-## Prerequisites
+- **TypeScript**: [`packages/sdks/typescript/examples/`](../../packages/sdks/typescript/examples/)
+- **Python**: [`packages/sdks/python/examples/`](../../packages/sdks/python/examples/)
 
-1. **Docker gateway running**: Start the gateway with:
-   ```bash
-   docker run -d --env-file .env -p 3100:3100 ghcr.io/pattern-zones-co/koine:latest
-   ```
-
-2. **Environment configured**: Ensure your `.env` file has:
-   ```
-   CLAUDE_CODE_GATEWAY_API_KEY=your-api-key
-   GATEWAY_PORT=3100  # optional, defaults to 3100
-   ```
-
-## TypeScript Examples
-
-Using `@patternzones/koine-sdk`. Run from the project root:
-
-```bash
-bun run docs/examples/typescript/hello.ts
-bun run docs/examples/typescript/extract-recipe.ts
-bun run docs/examples/typescript/stream.ts
-bun run docs/examples/typescript/conversation.ts
-```
-
-| Example | Description |
-|---------|-------------|
-| `hello.ts` | Basic `generateText` usage |
-| `extract-recipe.ts` | Structured output with Zod schemas |
-| `stream.ts` | Real-time streaming with `streamText` |
-| `conversation.ts` | Multi-turn conversations with `sessionId` |
-
-## Python Examples
-
-Using `koine-sdk`. First install the SDK with dev dependencies, then run from the SDK directory:
-
-```bash
-cd packages/sdks/python
-uv pip install -e ".[dev]"
-uv run python ../../../docs/examples/python/hello.py
-uv run python ../../../docs/examples/python/extract_recipe.py
-uv run python ../../../docs/examples/python/stream.py
-uv run python ../../../docs/examples/python/conversation.py
-```
-
-| Example | Description |
-|---------|-------------|
-| `hello.py` | Basic `generate_text` usage |
-| `extract_recipe.py` | Structured output with Pydantic schemas |
-| `stream.py` | Real-time streaming with `stream_text` |
-| `conversation.py` | Multi-turn conversations with `session_id` |
+See each SDK's README for prerequisites and instructions on running the examples.
diff --git a/docs/sdk-guide.md b/docs/sdk-guide.md
@@ -208,7 +208,7 @@ result2 = await generate_text(
 
 ### TypeScript
 
-See [docs/examples/typescript/](examples/typescript/) for complete, runnable examples:
+See [`packages/sdks/typescript/examples/`](../packages/sdks/typescript/examples/) for complete, runnable examples:
 
 - `hello.ts` — Basic text generation
 - `extract-recipe.ts` — Structured output with Zod schemas
@@ -217,7 +217,7 @@ See [docs/examples/typescript/](examples/typescript/) for complete, runnable exa
 
 ### Python
 
-See [docs/examples/python/](examples/python/) for complete, runnable examples:
+See [`packages/sdks/python/examples/`](../packages/sdks/python/examples/) for complete, runnable examples:
 
 - `hello.py` — Basic text generation
 - `extract_recipe.py` — Structured output with Pydantic schemas

diff --git a/packages/sdks/python/README.md b/packages/sdks/python/README.md
@@ -79,15 +79,15 @@ See the [SDK Guide](https://github.com/pattern-zones-co/koine/blob/main/docs/sdk
 
 ## Examples
 
-Runnable examples are available in [docs/examples/python/](https://github.com/pattern-zones-co/koine/tree/main/docs/examples/python):
+Runnable examples are available in the [`examples/`](https://github.com/pattern-zones-co/koine/tree/main/packages/sdks/python/examples) directory. Run from the SDK directory:
 
 ```bash
 cd packages/sdks/python
 uv pip install -e ".[dev]"
-uv run python ../../../docs/examples/python/hello.py           # Basic text generation
-uv run python ../../../docs/examples/python/extract_recipe.py  # Structured output with Pydantic
-uv run python ../../../docs/examples/python/stream.py          # Real-time streaming
-uv run python ../../../docs/examples/python/conversation.py    # Multi-turn sessions
+uv run python examples/hello.py           # Basic text generation
+uv run python examples/extract_recipe.py  # Structured output with Pydantic
+uv run python examples/stream.py          # Real-time streaming
+uv run python examples/conversation.py    # Multi-turn sessions
 ```
 
 ## License

diff --git a/docs/examples/python/conversation.py → ...ages/sdks/python/examples/conversation.py b/docs/examples/python/conversation.py → ...ages/sdks/python/examples/conversation.py
@@ -5,7 +5,7 @@
 The model remembers information from previous turns in the conversation.
 
 Run from packages/sdks/python:
-    uv run python ../../../docs/examples/python/conversation.py
+    uv run python examples/conversation.py
 """
 
 import asyncio

diff --git a/docs/examples/python/extract_recipe.py → ...es/sdks/python/examples/extract_recipe.py b/docs/examples/python/extract_recipe.py → ...es/sdks/python/examples/extract_recipe.py
@@ -4,7 +4,7 @@
 Demonstrates structured data extraction using Pydantic models for type-safe output.
 
 Run from packages/sdks/python:
-    uv run python ../../../docs/examples/python/extract_recipe.py
+    uv run python examples/extract_recipe.py
 """
 
 import asyncio

diff --git a/docs/examples/python/hello.py → packages/sdks/python/examples/hello.py b/docs/examples/python/hello.py → packages/sdks/python/examples/hello.py
@@ -4,7 +4,7 @@
 Demonstrates the simplest use case: asking a question and getting a text response.
 
 Run from packages/sdks/python:
-    uv run python ../../../docs/examples/python/hello.py
+    uv run python examples/hello.py
 """
 
 import asyncio

diff --git a/docs/examples/python/stream.py → packages/sdks/python/examples/stream.py b/docs/examples/python/stream.py → packages/sdks/python/examples/stream.py
@@ -5,7 +5,7 @@
 Text appears progressively as tokens arrive from the API.
 
 Run from packages/sdks/python:
-    uv run python ../../../docs/examples/python/stream.py
+    uv run python examples/stream.py
 """
 
 import asyncio

diff --git a/packages/sdks/typescript/README.md b/packages/sdks/typescript/README.md
@@ -78,13 +78,14 @@ See the [SDK Guide](https://github.com/pattern-zones-co/koine/blob/main/docs/sdk
 
 ## Examples
 
-Runnable examples are available in [docs/examples/typescript/](https://github.com/pattern-zones-co/koine/tree/main/docs/examples/typescript):
+Runnable examples are available in the [`examples/`](https://github.com/pattern-zones-co/koine/tree/main/packages/sdks/typescript/examples) directory. Run from the SDK directory using the npm scripts (which load `.env` from the project root):
 
 ```bash
-bun run docs/examples/typescript/hello.ts          # Basic text generation
-bun run docs/examples/typescript/extract-recipe.ts # Structured output with Zod
-bun run docs/examples/typescript/stream.ts         # Real-time streaming
-bun run docs/examples/typescript/conversation.ts   # Multi-turn sessions
+cd packages/sdks/typescript
+bun run example:hello        # Basic text generation
+bun run example:recipe       # Structured output with Zod
+bun run example:stream       # Real-time streaming
+bun run example:conversation # Multi-turn sessions
 ```
 
 ## License

diff --git a/docs/examples/typescript/conversation.ts → .../sdks/typescript/examples/conversation.ts b/docs/examples/typescript/conversation.ts → .../sdks/typescript/examples/conversation.ts
@@ -4,8 +4,8 @@
  * Demonstrates how to maintain context across multiple requests using sessionId.
  * The model remembers information from previous turns in the conversation.
  *
- * Run from project root:
- *   bun run docs/examples/typescript/conversation.ts
+ * Run from packages/sdks/typescript:
+ *   bun run example:conversation
  */
 
 import {

diff --git a/docs/examples/typescript/extract-recipe.ts → ...dks/typescript/examples/extract-recipe.ts b/docs/examples/typescript/extract-recipe.ts → ...dks/typescript/examples/extract-recipe.ts
@@ -3,8 +3,8 @@
  *
  * Demonstrates structured data extraction using Zod schemas for type-safe output.
  *
- * Run from project root:
- *   bun run docs/examples/typescript/extract-recipe.ts
+ * Run from packages/sdks/typescript:
+ *   bun run example:recipe
  */
 
 import {

diff --git a/docs/examples/typescript/hello.ts → packages/sdks/typescript/examples/hello.ts b/docs/examples/typescript/hello.ts → packages/sdks/typescript/examples/hello.ts
@@ -3,8 +3,8 @@
  *
  * Demonstrates the simplest use case: asking a question and getting a text response.
  *
- * Run from project root:
- *   bun run docs/examples/typescript/hello.ts
+ * Run from packages/sdks/typescript:
+ *   bun run example:hello
  */
 
 import {

diff --git a/docs/examples/typescript/stream.ts → packages/sdks/typescript/examples/stream.ts b/docs/examples/typescript/stream.ts → packages/sdks/typescript/examples/stream.ts
@@ -4,8 +4,8 @@
  * Demonstrates streaming responses with typewriter effect.
  * Text appears progressively as tokens arrive from the API.
  *
- * Run from project root:
- *   bun run docs/examples/typescript/stream.ts
+ * Run from packages/sdks/typescript:
+ *   bun run example:stream
  */
 
 import {

diff --git a/packages/sdks/typescript/package.json b/packages/sdks/typescript/package.json
@@ -23,7 +23,11 @@
 		"test": "vitest",
 		"test:run": "vitest run",
 		"test:coverage": "vitest run --coverage",
-		"lint": "biome check ."
+		"lint": "biome check .",
+		"example:hello": "bun --env-file=../../../.env run examples/hello.ts",
+		"example:stream": "bun --env-file=../../../.env run examples/stream.ts",
+		"example:recipe": "bun --env-file=../../../.env run examples/extract-recipe.ts",
+		"example:conversation": "bun --env-file=../../../.env run examples/conversation.ts"
 	},
 	"dependencies": {
 		"zod": "3.25.76",