OasAIStudio · Octane0411 · Mar 23, 2026 · Mar 23, 2026
diff --git a/README.md b/README.md
@@ -3,7 +3,7 @@
 
   <h1>Open Agent SDK</h1>
 
-  <p><strong>Minimal, production-ready TypeScript SDK for building tool-using AI agents.</strong></p>
+  <p><strong>Open agent runtime and first-party CLI for tool-using AI workflows.</strong></p>
 
   <p>
     <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-000000?style=for-the-badge&logo=opensourceinitiative&logoColor=white" alt="License: MIT"></a>
@@ -12,7 +12,9 @@
   </p>
 </div>
 
-Build agents with a ReAct loop, tool permissions, hooks, subagents, session persistence, and multi-provider support.
+Open Agent SDK gives you a ready-to-run terminal agent via `oas` and an embeddable TypeScript runtime for building your own agent products.
+
+The default story is product-first: start with the CLI when you want an end-to-end agent surface, then drop to the SDK when you need custom UX, policies, or infrastructure.
 
 For Codex OAuth, run `codex login` once, then use `provider: 'codex'` in the SDK or `oas --provider codex` in the CLI. The SDK will reuse your local Codex login state from `~/.codex/auth.json`.
 
@@ -44,9 +46,10 @@ More runnable demos: [Demo Gallery](./DEMO_GALLERY.md).
 
 ## Why Open Agent SDK
 
+- Product-shaped entry point: `oas` gives you a first-party terminal agent, while the SDK exposes the same runtime for embedding.
 - Production safety controls: permission modes (`default`, `plan`, `acceptEdits`, `bypassPermissions`) and per-tool gating via `canUseTool`.
 - Agent extensibility core: hooks, skills, subagents, and MCP-compatible tool integration.
-- Reproducible evaluation path: local SWE-bench and Terminal-bench harnesses in `benchmark/`.
+- Reproducible evaluation path: benchmark the CLI like an agent product and reuse the runtime in custom apps.
 
 See details in:
 - [API Reference](./docs/api-reference.md)
@@ -56,6 +59,7 @@ See details in:
 
 ## Concepts
 
+- `CLI surface`: `oas` runs the same core runtime exposed by the SDK.
 - `Agent loop`: multi-turn ReAct with tool execution.
 - `Tool permissions`: explicit allow/deny policy hooks.
 - `Hooks`: lifecycle/tool events for observability and control.
@@ -73,12 +77,17 @@ See details in:
 ## Evaluation
 
 - SWE-bench Lite smoke/batch runners: `benchmark/swebench/scripts/`
-- Terminal-bench Harbor adapter and runbook: `benchmark/terminalbench/`
+- Terminal-bench Harbor adapter and runbook for the CLI agent surface: `benchmark/terminalbench/`
 - Result summarization scripts and artifacts: see [BENCHMARKS.md](./BENCHMARKS.md)
 
 ## Integrations
 
-Current provider support in core SDK:
+Primary surfaces:
+
+- `oas` first-party CLI
+- TypeScript SDK API
+
+Current provider support in the runtime:
 
 - Codex OAuth
 - OpenAI
@@ -96,7 +105,7 @@ Ecosystem integrations:
 - Docs: https://docs.openagentsdk.dev
 - GitHub: https://github.com/OasAIStudio/open-agent-sdk
 - [Introduction](./docs/introduction.md)
-- [Comparison with Claude Agent SDK](./docs/claude-agent-sdk-comparison.md)
+- [Migration and Claude Agent SDK comparison](./docs/claude-agent-sdk-comparison.md)
 
 ## Monorepo Layout
 

diff --git a/docs/branding/pixel-banner-option23.svg b/docs/branding/pixel-banner-option23.svg
diff --git a/docs/branding/pixel-banner-option24.svg b/docs/branding/pixel-banner-option24.svg
diff --git a/docs/branding/pixel-banner.svg b/docs/branding/pixel-banner.svg
diff --git a/docs/claude-agent-sdk-comparison.md b/docs/claude-agent-sdk-comparison.md
@@ -1,17 +1,19 @@
 # Open Agent SDK vs Claude Agent SDK
 
-This document summarizes the current comparison at the time of writing for the `0.1.0-alpha.x` line.
+This page is for migration and market context, not the primary product overview. At the `0.1.0-alpha.x` line, Open Agent SDK is positioned as an open agent runtime with a first-party CLI (`oas`) and an embeddable TypeScript SDK.
 
 ## Scope
 
 - Focuses on SDK capabilities relevant to application developers
 - Reflects the current implementation in this repository
 - Does not attempt to evaluate model quality or vendor service quality
+- Should be read as migration guidance, not as a drop-in parity claim
 
 ## Feature Comparison
 
 | Area | Open Agent SDK | Claude Agent SDK |
 |------|----------------|------------------|
+| Primary entry point | First-party CLI + embeddable TypeScript runtime | Vendor-maintained SDK |
 | Source model | Open source (MIT) | Closed source |
 | Provider strategy | Multi-provider (OpenAI / Google / Anthropic) | Primarily Anthropic ecosystem |
 | Agent loop model | Aligned: ReAct-style loop with tool execution | ReAct-style loop with tool execution |
@@ -25,13 +27,15 @@ This document summarizes the current comparison at the time of writing for the `
 ## Compatibility Notes
 
 - Open Agent SDK intentionally adopts familiar concepts from Claude Agent SDK: sessions, tool-first execution, permission gating, and extensibility hooks.
+- The main product story is different: Open Agent SDK centers a first-party agent surface (`oas`) and exposes the runtime underneath.
 - API-level parity is not guaranteed for every release. Treat compatibility as directional, not binary.
 - For migration-critical scenarios, validate specific APIs in your target version before rollout.
 
 ## Current Positioning
 
 Open Agent SDK is best suited for teams that need:
 
+- A ready-to-run terminal agent plus an embeddable runtime
 - Source-level control and customizability
 - Flexibility to run across providers
 - A transparent agent runtime that can be adapted to internal infrastructure

diff --git a/docs/introduction.md b/docs/introduction.md
@@ -4,10 +4,20 @@
 
 ## Overview
 
-Open Agent SDK is an open-source TypeScript framework for building AI agents. It provides a developer experience similar to Claude Agent SDK but with full transparency and no vendor lock-in.
+Open Agent SDK is an open agent runtime for tool-using workflows. It ships with a first-party terminal agent, `oas`, and exposes the same core as a TypeScript SDK when you need to embed, customize, or self-host more of the runtime.
+
+## Primary Surfaces
+
+- **`oas` CLI**: the default entry point for running and benchmarking a complete terminal agent
+- **TypeScript SDK**: the embeddable runtime surface for custom apps, automation, and internal products
 
 ## What Makes It Different?
 
+### 🧭 Product-First Shape
+- Start with a working terminal agent instead of only a low-level library
+- Reuse the same runtime beneath the CLI in your own product surfaces
+- Keep benchmark and product messaging centered on an actual agent surface
+
 ### 🔓 Open Source & Transparent
 - Full source code visibility
 - MIT License
@@ -280,10 +290,13 @@ const session = createSession({
 });
 ```
 
-## Comparison with Claude Agent SDK
+## Comparison and Migration Context
+
+Claude Agent SDK is a useful migration reference for this project, but it is not the primary way to understand Open Agent SDK. The main product shape here is `oas` plus an embeddable runtime.
 
 | Feature | Open Agent SDK | Claude Agent SDK |
 |---------|---------------|------------------|
+| Primary Surface | First-party CLI + embeddable runtime | Vendor-maintained SDK |
 | Open Source | ✅ Yes | ❌ No |
 | Multi-Provider | ✅ OpenAI/Gemini/Anthropic | ❌ Anthropic only |
 | Agent Loop | ✅ | ✅ |
@@ -299,12 +312,17 @@ const session = createSession({
 
 ## Getting Started
 
-1. **Installation**
+1. **Choose your entry point**
+   ```bash
+   npx open-agent-sdk@alpha init my-agent
+   ```
+
+2. **Install the SDK when you want to embed the runtime**
    ```bash
    npm install open-agent-sdk@alpha
    ```
 
-2. **Quick Example**
+3. **SDK Example**
    ```bash
    codex login
    ```
@@ -320,7 +338,7 @@ const session = createSession({
    console.log(result.result);
    ```
 
-3. **Next Steps**
+4. **Next Steps**
    - Check out the [API Reference](./api-reference.md)
    - Explore [examples](../examples/)
    - Join the [community discussions](https://github.com/Octane0411/open-agent-sdk/discussions)

diff --git a/package.json b/package.json
@@ -2,7 +2,7 @@
   "name": "open-agent-sdk-monorepo",
   "version": "0.1.0-alpha.1",
   "private": true,
-  "description": "Open source agent SDK compatible with Claude Agent SDK (monorepo root)",
+  "description": "Open agent runtime monorepo with a first-party CLI and TypeScript SDK",
   "scripts": {
     "build": "cd packages/core && bun run build",
     "docs:dev": "cd packages/docs && bun run dev",

diff --git a/packages/cli/package.json b/packages/cli/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@open-agent-sdk/cli",
   "version": "0.1.0-alpha.1",
-  "description": "CLI agent built on open-agent-sdk",
+  "description": "First-party CLI for the Open Agent SDK runtime",
   "bin": {
     "oas": "./src/index.ts"
   },

diff --git a/packages/core/package.json b/packages/core/package.json
@@ -1,7 +1,7 @@
 {
   "name": "open-agent-sdk",
   "version": "0.1.0-alpha.1",
-  "description": "Open source agent SDK compatible with Claude Agent SDK",
+  "description": "Open agent runtime and TypeScript SDK for tool-using AI agents",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "bin": {

diff --git a/packages/docs/src/content/docs/getting-started/quickstart.mdx b/packages/docs/src/content/docs/getting-started/quickstart.mdx
@@ -1,8 +1,19 @@
 ---
 title: Quickstart
-description: Run your first prompt and session with Open Agent SDK.
+description: Start with the CLI, then embed the runtime through the SDK.
 ---
 
+## CLI first
+
+```bash
+npx open-agent-sdk@alpha init my-agent
+cd my-agent
+npm install
+npm run dev
+```
+
+Use the scaffolded project when you want a ready-to-run agent surface first.
+
 ## One-shot prompt
 
 Run `codex login` once first if you want to use Codex OAuth.

diff --git a/packages/docs/src/content/docs/index.mdx b/packages/docs/src/content/docs/index.mdx
@@ -1,14 +1,15 @@
 ---
 title: Open Agent SDK Documentation
-description: Open-source docs for Claude Agent SDK-style APIs, TypeScript integration, and multi-provider agent workflows.
+description: Docs for the Open Agent SDK runtime, first-party CLI, and TypeScript APIs for multi-provider agent workflows.
 ---
 
-Open Agent SDK is an open-source TypeScript agent SDK implemented around Claude Agent SDK API patterns, with broader provider and extension options for production teams.
+Open Agent SDK is an open agent runtime with two public entry points: the first-party `oas` CLI for complete terminal-agent workflows and the TypeScript SDK for embedding the same runtime in your own product.
 
 Use this documentation to move from install to production-ready workflows:
 
-- Learn the runtime model and API surface quickly
+- Learn the CLI and runtime model quickly
 - Implement tools, sessions, permissions, and hooks with confidence
+- Embed or extend the runtime without rewriting agent logic
 - Migrate Claude Agent SDK-style code with minimal friction
 
 ## Quick links
@@ -23,8 +24,9 @@ Use this documentation to move from install to production-ready workflows:
 
 ## Why teams adopt Open Agent SDK
 
+- **Product-shaped entry points:** Start with `oas`, then embed the same runtime through the SDK
 - **Open-source by default:** MIT-licensed core and transparent implementation
-- **Claude-style API ergonomics:** Familiar mental model and aligned workflow patterns
+- **Migration-friendly API ergonomics:** Familiar mental model and aligned workflow patterns
 - **Provider flexibility:** Integrate OpenAI, Gemini, and Anthropic without architecture rewrites
 - **Production controls:** First-class tooling for sessions, permissions, hooks, and MCP