strands-agents · zastrowm · May 28, 2026 · May 27, 2026 · May 28, 2026 · May 28, 2026
diff --git a/.agents/references/code-verification.md b/.agents/references/code-verification.md
@@ -68,11 +68,11 @@ If the clones aren't present, run `npm run sdk:clone` from `site/`, or fall back
 If the local clones aren't available, fetch source through the GitHub API:
 
 ```bash
-# Python SDK
-gh api repos/strands-agents/sdk-python/contents/src/strands/[path]
+# Python SDK (now local at strands-py/src/strands/)
+gh api repos/strands-agents/sdk-python/contents/strands-py/src/strands/[path]
 
-# TypeScript SDK
-gh api repos/strands-agents/sdk-typescript/contents/strands-ts/src/[path]
+# TypeScript SDK (now local at strands-ts/src/)
+gh api repos/strands-agents/sdk-python/contents/strands-ts/src/[path]
 ```
 
 ## Tier 3: Installed Package Introspection

diff --git a/.agents/skills/strands-review/SKILL.md b/.agents/skills/strands-review/SKILL.md
@@ -10,20 +10,6 @@ same findings as the remote `/strands review` agent. If the upstream changes,
 re-sync from the source URL above. Do not edit the body to fit local
 conventions — divergence here defeats the purpose of the skill.
 
-NOTE: an SDK monorepo merge is imminent (sdk-typescript + sdk-python +
-devtools). Once that lands, the upstream SOP lives in-tree at something like
-`devtools/strands-command/agent-sops/task-reviewer.sop.md` instead of a
-separate repo. At that point:
-  - Replace this file with a symlink to the in-tree SOP (or `include` it via
-    a build step) so re-sync is automatic and drift is impossible.
-  - The `source:` URL in frontmatter becomes a relative repo path.
-  - The "re-sync from source URL" instruction below becomes obsolete — a
-    `git pull` is the sync.
-Until then, re-sync manually:
-  curl -sL https://raw.githubusercontent.com/strands-agents/devtools/main/strands-command/agent-sops/task-reviewer.sop.md \
-    > .agents/skills/strands-review/SKILL.md.body
-  # then splice the new body in below this comment block
-
 Tool-name mapping (the SOP names upstream Strands tools; locally use these):
 - `get_pr_files`            -> `gh pr view <pr> --json files` / `gh pr diff <pr>`
 - `add_pr_comment` (inline) -> `gh api repos/{owner}/{repo}/pulls/{pr}/comments`
@@ -48,7 +34,7 @@ Initialize the review environment by checking out the main branch for guidance.
 - You MUST checkout the main branch first to read repository review guidance
 - You MUST create a progress notebook to track your review process using markdown checklists
 - You MUST read repository guidelines from `README.md`, `CONTRIBUTING.md`, and `AGENTS.md` (if present)
-- You MUST read API bar raising guidelines from https://github.com/strands-agents/docs/blob/main/team/API_BAR_RAISING.md
+- You MUST read API bar raising guidelines from `team/API_BAR_RAISING.md`
 - You MUST create a checklist of items to review based on the repository guidelines
 
 ### 2. Analyze Pull Request Context
@@ -97,7 +83,7 @@ If the PR introduces or modifies public APIs, evaluate the API design from a cus
   - Example code snippets demonstrating usage
   - Complete API signatures with default parameter values
   - Module exports (what's exported from each module)
-- You MUST evaluate the API against SDK tenets (https://github.com/strands-agents/docs/blob/main/team/TENETS.md) and decision records (https://github.com/strands-agents/docs/blob/main/team/DECISIONS.md)
+- You MUST evaluate the API against SDK tenets (`team/TENETS.md`) and decision records (`team/DECISIONS.md`)
 - You MUST verify the API addresses documented use cases
 - You MUST check if default parameters/behavior represent the most common usage
 - You MUST assess the level of abstraction and extensibility:

diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml
@@ -5,5 +5,5 @@ contact_links:
     url: https://github.com/strands-agents/sdk-python/discussions
     about: Please ask and answer questions here
   - name: Strands Agents SDK Documentation
-    url: https://github.com/strands-agents/docs
+    url: https://strandsagents.com
     about: Visit our documentation for help
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
@@ -7,7 +7,7 @@
 
 ## Documentation PR
 
-<!-- Link to related associated PR in the agent-docs repo -->
+<!-- If this PR requires documentation changes, include them in this PR under site/ -->
 
 ## Type of Change
 

diff --git a/AGENTS.md b/AGENTS.md
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -50,7 +50,17 @@ When proposing solutions or reviewing code, we reference these principles to gui
 
 ## Development Environment
 
-This project uses [hatchling](https://hatch.pypa.io/latest/build/#hatchling) as the build backend and [hatch](https://hatch.pypa.io/latest/) for development workflow management.
+This is a monorepo containing the Python SDK, TypeScript SDK, and documentation site. Each has its own toolchain:
+
+| Area | Directory | Toolchain |
+|------|-----------|-----------|
+| Python SDK | `strands-py/` | hatch |
+| TypeScript SDK | `strands-ts/` | npm workspace |
+| Docs site | `site/` | Astro (npm) |
+
+### Python SDK
+
+The Python SDK uses [hatchling](https://hatch.pypa.io/latest/build/#hatchling) as the build backend and [hatch](https://hatch.pypa.io/latest/) for development workflow management.
 
 All `hatch` commands should be run from the `strands-py/` subdirectory (where `pyproject.toml` lives):
 
@@ -131,14 +141,41 @@ If you're using an IDE like VS Code or PyCharm, consider configuring it to use t
 For additional details on styling, please see our dedicated [Style Guide](./strands-py/docs/STYLE_GUIDE.md).
 
 
+### TypeScript SDK
+
+The TypeScript SDK uses an npm workspace rooted at the repository root.
+
+```bash
+npm ci              # install dependencies (from repo root)
+npm run build       # build
+npm test            # run unit tests
+npm run lint        # lint
+npm run type-check  # type checking
+```
+
+### Documentation Site
+
+The documentation site uses Astro with the Starlight theme.
+
+```bash
+cd site
+npm install
+npm run dev                # local dev server at http://localhost:4321/
+npm run build              # production build
+npm run typecheck          # type checking
+npm run typecheck:snippets # type check code examples
+```
+
+For docs contribution guidelines, see [site/CONTRIBUTING.md](./site/CONTRIBUTING.md).
+
 ## Contributing via Pull Requests
 Contributions via pull requests are much appreciated. Before sending us a pull request, please ensure that:
 
 1. You are working against the latest source on the *main* branch.
 2. You check existing open, and recently merged, pull requests to make sure someone else hasn't addressed the problem already.
 3. You open an issue to discuss any significant work - we would hate for your time to be wasted.
 
-For guidance on writing effective PR descriptions, see our [PR Description Guidelines](./strands-py/docs/PR.md).
+For guidance on writing effective PR descriptions, see our PR Description Guidelines ([Python](./strands-py/docs/PR.md), [TypeScript](./dev-docs/PR.md)).
 
 To send us a pull request, please:
 
@@ -164,4 +201,4 @@ If you discover a potential security issue in this project we ask that you notif
 
 ## Licensing
 
-See the [LICENSE](./LICENSE) file for our project's licensing. We will ask you to confirm the licensing of your contribution.
+See the [LICENSE.APACHE](./LICENSE.APACHE) and [LICENSE.MIT](./LICENSE.MIT) files for our project's licensing. We will ask you to confirm the licensing of your contribution.
diff --git a/README.md b/README.md
@@ -26,7 +26,6 @@
   <p>
     <a href="https://strandsagents.com/">Documentation</a>
     ◆ <a href="https://github.com/strands-agents/samples">Samples</a>
-    ◆ <a href="https://github.com/strands-agents/sdk-python">Python SDK</a>
     ◆ <a href="https://github.com/strands-agents/tools">Tools</a>
     ◆ <a href="https://github.com/strands-agents/agent-builder">Agent Builder</a>
     ◆ <a href="https://github.com/strands-agents/mcp-server">MCP Server</a>
@@ -35,6 +34,18 @@
 
 Strands Agents is a simple yet powerful SDK that takes a model-driven approach to building and running AI agents. From simple conversational assistants to complex autonomous workflows, from local development to production deployment, Strands Agents scales with your needs.
 
+This monorepo contains the Python SDK, TypeScript SDK, documentation site, and supporting packages:
+
+| Directory | Description |
+|-----------|-------------|
+| `strands-py/` | Python SDK — agent loop, model providers, tools ([PyPI](https://pypi.org/project/strands-agents/)) |
+| `strands-ts/` | TypeScript SDK — agent loop, model providers, tools ([npm](https://www.npmjs.com/package/@strands/agent)) |
+| `strands-wasm/` | WebAssembly bindings for running Python tools from TypeScript agents |
+| `strands-py-wasm/` | Python host for WASM components (bridges WIT interfaces to Python) |
+| `strandly/` | Developer CLI for local builds, codegen, and workspace tooling |
+| `site/` | Documentation site built with Astro/Starlight ([strandsagents.com](https://strandsagents.com)) |
+| `designs/` | Design proposals for significant features (RFC-style) |
+
 ## Feature Overview
 
 - **Lightweight & Flexible**: Simple agent loop that just works and is fully customizable
@@ -310,16 +321,29 @@ For detailed guidance & examples, explore our documentation:
 
 ## Development
 
-Source code lives in the `strands-py/` subdirectory. To develop locally:
+Git operations (commits, branches, PRs) are done from the repo root. Each package has its own toolchain:
 
+**Python SDK** (`strands-py/`):
 ```bash
 cd strands-py
 pip install hatch
 hatch test        # run unit tests
 hatch fmt         # format & lint
 ```
 
-Git operations (commits, branches, PRs) are still done from the repo root as normal.
+**TypeScript SDK** (`strands-ts/`):
+```bash
+npm ci            # install from repo root
+npm run build     # build
+npm test          # run unit tests
+```
+
+**Documentation site** (`site/`):
+```bash
+cd site
+npm install
+npm run dev       # local dev server at http://localhost:4321/
+```
 
 ## Contributing ❤️
 

diff --git a/designs/README.md b/designs/README.md
@@ -23,7 +23,7 @@ Skip the design process for bug fixes, small improvements, documentation updates
 ## How to submit a feature proposal
 
 1. **Check the [roadmap](https://github.com/orgs/strands-agents/projects/8/views/1)** — See if your idea aligns with our direction
-2. **Fork the [sdk-python repository](https://github.com/strands-agents/sdk-python)**
+2. **Create a branch in this repository**
 3. **Create your design** — Add a new file: `designs/NNNN-feature-name.md` using the template below
 4. **Submit a pull request** — We'll review and discuss
 5. **Iterate based on feedback** — Address comments and questions

diff --git a/site/AGENTS.md b/site/AGENTS.md
@@ -1,9 +1,9 @@
-# Agent Development Guide - strands-agents/private-docs-staging
+# Agent Development Guide - Documentation Site
 
-This document provides guidance specifically for AI agents working on the strands-agents/private-docs-staging codebase. For human contributor guidelines, see [CONTRIBUTING.md](CONTRIBUTING.md).
+This document provides guidance for AI agents working on the Strands Agents documentation site (the `site/` directory). For human contributor guidelines, see [CONTRIBUTING.md](CONTRIBUTING.md).
 
 ## Purpose and Scope
-The goal of this repository is to revamp this documentation repo so that it provides clear and well organized documentation on how to develop with Strands SDK with either Python or Typescript.
+This directory contains the documentation site for Strands Agents, providing guides on how to develop with the SDK in both Python and TypeScript.
 
 **AGENTS.md** contains agent-specific repository information including:
 - Directory structure with summaries of what is included in each directory
@@ -17,10 +17,10 @@ The goal of this repository is to revamp this documentation repo so that it prov
 
 When working on SDK features or documentation, familiarize yourself with these team processes:
 
-* **[Feature Lifecycle Process](team/FEATURE_LIFECYCLE.md)**: How features are added, versioned, deprecated, and graduated from experimental status
-* **[API Bar Raising](team/API_BAR_RAISING.md)**: Standards for API design quality
-* **[Decisions](team/DECISIONS.md)**: Key architectural and design decisions
-* **[Tenets](team/TENETS.md)**: Core principles guiding SDK development
+* **[Feature Lifecycle Process](../team/FEATURE_LIFECYCLE.md)**: How features are added, versioned, deprecated, and graduated from experimental status
+* **[API Bar Raising](../team/API_BAR_RAISING.md)**: Standards for API design quality
+* **[Decisions](../team/DECISIONS.md)**: Key architectural and design decisions
+* **[Tenets](../team/TENETS.md)**: Core principles guiding SDK development
 
 These documents define the standards and processes that ensure consistency and quality across the Strands SDK.
 
@@ -212,7 +212,7 @@ import type { Options, Config } from '../types'
 - [TSDoc Reference](https://tsdoc.org/)
 - [Conventional Commits](https://www.conventionalcommits.org/)
 - [Strands Agents Documentation](https://strandsagents.com/)
-- [Typescript SDK](https://github.com/strands-agents/sdk-typescript/)
+- [TypeScript SDK](../strands-ts/)
 
 # TypeScript Code Examples Guide
 

diff --git a/site/CONTRIBUTING.md b/site/CONTRIBUTING.md
@@ -73,7 +73,7 @@ reported the issue. Please try to include as much information as you can. Detail
 Looking at the existing issues is a great way to find something to contribute to. We label issues that are well-defined and ready for community contributions with the "ready for contribution" label. As our projects, by default, use the default GitHub issue labels (enhancement/bug/duplicate/help wanted/invalid/question/wontfix), looking at any 'help wanted' issues is a great place to start.
 
 Check our "Ready for Contribution" issues for items you can work on:
-- [SDK Python Issues](https://github.com/strands-agents/sdk-python/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22ready%20for%20contribution%22)
+- [SDK Issues](https://github.com/strands-agents/sdk-python/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22ready%20for%20contribution%22)
 - [Tools Issues](https://github.com/strands-agents/tools/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22ready%20for%20contribution%22)
 
 Before starting work on any issue:

diff --git a/site/src/content/docs/contribute/contributing/core-sdk.mdx b/site/src/content/docs/contribute/contributing/core-sdk.mdx
@@ -12,8 +12,7 @@ This guide walks you through contributing to sdk-python and sdk-typescript. We'l
 
 Looking for a place to start? Check our issues labeled "ready for contribution"—these are well-defined and ready for community work.
 
-- [Python SDK issues](https://github.com/strands-agents/sdk-python/issues?q=is%3Aissue+state%3Aopen+label%3A%22ready+for+contribution%22)
-- [TypeScript SDK issues](https://github.com/strands-agents/sdk-typescript/issues?q=is%3Aissue+state%3Aopen+label%3A%22ready+for+contribution%22)
+- [SDK issues](https://github.com/strands-agents/sdk-python/issues?q=is%3Aissue+state%3Aopen+label%3A%22ready+for+contribution%22)
 
 Before starting work on any issue, check if someone is already assigned or working on it.
 
@@ -50,7 +49,7 @@ First, we'll clone the repository and set up the virtual environment.
 
 ```bash
 git clone https://github.com/strands-agents/sdk-python.git
-cd sdk-python
+cd sdk-python/strands-py
 ```
 
 We use [hatch](https://hatch.pypa.io/) for Python development. Hatch manages virtual environments, dependencies, testing, and formatting. Enter the virtual environment and install pre-commit hooks.
@@ -86,15 +85,15 @@ hatch run prepare           # Run all checks before committing
 
 - Use `hatch run test-integ` to run integration tests with real model providers
 - Run `hatch test --all` to test across Python 3.10-3.13
-- Check [CONTRIBUTING.md](https://github.com/strands-agents/sdk-python/blob/main/CONTRIBUTING.md) for detailed development workflow
+- Check [CONTRIBUTING.md](https://github.com/strands-agents/sdk-python/blob/main/CONTRIBUTING.md) for the full development workflow
 </Tab>
 <Tab label="TypeScript">
 
 First, we'll clone the repository and install dependencies.
 
 ```bash
-git clone https://github.com/strands-agents/sdk-typescript.git
-cd sdk-typescript
+git clone https://github.com/strands-agents/sdk-python.git
+cd sdk-python
 npm install
 ```
 
@@ -122,7 +121,7 @@ npm run format              # Format code with Prettier
 
 - Use `npm run test:integ` to run integration tests
 - Run `npm run test:all` to test in both Node.js and browser environments
-- Check [CONTRIBUTING.md](https://github.com/strands-agents/sdk-typescript/blob/main/CONTRIBUTING.md) for detailed requirements
+- Check [CONTRIBUTING.md](https://github.com/strands-agents/sdk-python/blob/main/CONTRIBUTING.md) for the full development workflow
 </Tab>
 </Tabs>
 
@@ -144,4 +143,4 @@ The pre-commit hooks help catch issues before you push, but you can also run che
 ## Related guides
 
 - [Feature proposals](./feature-proposals.md) — For significant features requiring discussion
-- [Team documentation](https://github.com/strands-agents/docs/tree/main/team) — Our tenets, decisions, and API review process
+- [Team documentation](https://github.com/strands-agents/sdk-python/tree/main/team) — Our tenets, decisions, and API review process
diff --git a/site/src/content/docs/contribute/contributing/documentation.mdx b/site/src/content/docs/contribute/contributing/documentation.mdx
@@ -4,7 +4,7 @@ sidebar:
   label: "Documentation"
 ---
 
-Good documentation helps developers succeed with Strands. We welcome contributions that make our docs clearer, more complete, or more helpful. Our documentation lives in the [docs repository](https://github.com/strands-agents/docs).
+Good documentation helps developers succeed with Strands. We welcome contributions that make our docs clearer, more complete, or more helpful. Our documentation lives in the `site/` directory of the [Strands SDK repository](https://github.com/strands-agents/sdk-python).
 
 ## What we accept
 
@@ -23,9 +23,9 @@ We're looking for contributions that improve the developer experience. Documenta
 Let's get the docs running locally so you can preview your changes as you work. The docs are built with [Astro](https://astro.build/) and the [Starlight](https://starlight.astro.build/) theme.
 
 ```bash
-# Clone the docs repository
-git clone https://github.com/strands-agents/docs.git
-cd docs
+# Clone the repository
+git clone https://github.com/strands-agents/sdk-python.git
+cd sdk-python/site
 
 # Install dependencies
 npm install
@@ -42,7 +42,7 @@ The development server automatically reloads when you save changes, so you can s
 
 The submission process varies based on the size of your change. Small fixes can go straight to PR, while larger changes benefit from discussion first.
 
-1. **Fork the docs repository** on GitHub
+1. **Fork the repository** on GitHub
 2. **Create a branch** with a descriptive name like `docs/clarify-tools-usage` or `docs/fix-typo-agent-loop`
 3. **Make your changes** in your favorite editor
 4. **Preview locally** with `npm run dev` to verify formatting and links work correctly