docs: clarify SDK agent test workflow (#10860)

sdk/AGENTS.md

@@ -8,6 +8,12 @@ alwaysApply: true
 
 Quick-reference for active development. For onboarding, workspace setup, publishing, and detailed workflow see [CONTRIBUTING.md](./CONTRIBUTING.md). For architecture and runtime flows see [ARCHITECTURE.md](./ARCHITECTURE.md). For API details see [DOC.md](./DOC.md).
 
+## Repository Scope
+
+This file applies to the SDK workspace rooted at this directory (`sdk/`). In this repo, "root" means the SDK workspace root unless explicitly stated otherwise. Ignore the legacy repository root for SDK development except for Git operations or repo-wide searches that are explicitly needed.
+
+Run SDK commands from `sdk/`, not from the legacy repository root. Do not run direct root-level commands such as `bun test sdk/...`; they bypass the SDK workspace setup and can fail to resolve `workspace:*` packages correctly.
+
 ## Package Boundaries
 
 ### Published SDK Packages
@@ -44,7 +50,20 @@ Route changes to the package that owns the concern:
 
 ## Verifying Changes
 
-Root commands for cross-package confidence:
+Before testing in a fresh worktree, install SDK dependencies from the SDK workspace root:
+
+```sh
+cd sdk
+bun install --frozen-lockfile
+```
+
+SDK package exports resolve sibling packages through compiled `dist/` files. If `dist/` is missing, build the SDK packages before running package tests:
+
+```sh
+bun run build:sdk
+```
+
+SDK-root commands for cross-package confidence:
 
 ```sh
 bun run types       # typecheck all packages
@@ -52,6 +71,18 @@ bun run test        # run all tests
 bun run check       # lint + build + typecheck + check-publish
 ```
 
+For focused verification, prefer workspace package scripts from the SDK root:
+
+```sh
+bun -F @cline/shared test
+bun -F @cline/llms test
+bun -F @cline/agents test
+bun -F @cline/core test:unit
+bun -F @cline/cli test:unit
+```
+
+If a focused test command fails with a missing `@cline/*` export or missing `dist/` file, build the relevant dependency package or run `bun run build:sdk`, then rerun the same test command. Treat that as a workspace setup issue, not as evidence of a source-code bug.
+
 If you touch hub/bootstrap/session flows, please update `ARCHITECTURE.md`.
 
 ## Practical Guidance