Comparison

A · Cline rules · cline/cline B · AGENTS.md · cline/cline

What each file covers, counted
Dimension	Shared	Only in A	Only in B	Overlap
Sections	0	19	11	0%
Commands	0	3	11	0%
Section tags	2	3	7	17%

What each file covers

Sections

0 shared · 19 only in A · 11 only in B

− Debug Harness
− Quick start
− Build extension first if needed (protos + esbuild):
− Launch (skip-build if already built). Run with node, NOT bun — Playwright's
− Electron launch times out under bun:
− In another terminal:
− Data Isolation
− Browser Capture & OAuth
− OAuth API
− OAuth testing flow
− Navigating Views — Use Commands, Not Clicks
− Key commands
− Typical Session
− 1. Launch
− 2. Open sidebar + dismiss overlays (ALWAYS do this first)
− 3. Navigate to view
− 4. Check captured OAuth URLs if testing auth
− 5. Verify
− Caveats
+ Cline SDK — Development Reference
+ Repository Scope
+ Package Boundaries
+ Published SDK Packages
+ Dependency Direction
+ Change Routing
+ Verifying Changes
+ Practical Guidance
+ Keep Boundaries Clean
+ Refactor Standard
+ Documentation Responsibilities

Commands

0 shared · 3 only in A · 11 only in B

− bun run protos && IS_DEV=true bun esbuild.mjs
− node src/dev/debug-harness/server.ts --skip-build --auto-launch
− bun run dev:mcp-oauth-test-server
+ bun install --frozen-lockfile
+ bun run build:sdk
+ bun run types
+ bun run test
+ bun run check
+ 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
+ bun test sdk/...

Section tags

2 shared · 3 only in A · 7 only in B

− testing-strategy
− security
− api
+ setup
+ code-style
+ architecture
+ dependencies
+ deployment
+ monorepo
+ docs
build
test

Line diff

+77 added−97 removed33 unchanged25.4% identical

cline/cline · .clinerules/debug-harness.md

@@ −1 @@

1# Debug Harness

3HTTP-controlled debugger for the VSCode extension at `src/dev/debug-harness/server.ts`.

5## Quick start

7```bash

8# Build extension first if needed (protos + esbuild):

9bun run protos && IS_DEV=true bun esbuild.mjs

11# Launch (skip-build if already built). Run with node, NOT bun — Playwright's

12# Electron launch times out under bun:

13node src/dev/debug-harness/server.ts --skip-build --auto-launch

15# In another terminal:

16curl localhost:19229/api -d '{"method":"status"}'

17```

19## Data Isolation

21The debugee runs with `CLINE_DIR=~/.cline2` by default, separate from your real `~/.cline`.

22This prevents the debugee's logout from logging out the debugger, and vice versa.

23Override with `--cline-dir /tmp/test-dir`. Check with `status()` → `clineDir`.

25## Browser Capture & OAuth

27The debugee runs with `CLINE_CAPTURE_BROWSER=1`, which intercepts `openExternal()` in

28`src/utils/env.ts`. URLs are captured instead of opening a real browser:

30- Logged to `$CLINE_DIR/data/debug-captured-urls.jsonl`

31- POSTed in real-time to `/captured-url` on the harness server

32- Queryable via `oauth.captured_urls`

34### OAuth API

36- **`oauth.captured_urls`** `{clear?}` — URLs the debugee tried to open

37- **`oauth.read_stored_token`** — Check auth token presence in secrets.json

38- **`oauth.simulate_callback`** `{path, code?, state?, provider?, token?}` — Build vscode:// callback URI

39- **`oauth.read_captured_urls_file`** — Read on-disk JSONL of captured URLs

41### OAuth testing flow

43For **Cline OAuth** (SDK local callback): The SDK starts a local HTTP server, the auth URL

44is captured. To complete: open the captured URL in a real browser (it redirects back to the

45SDK's callback server), OR extract the callback port and `curl http://127.0.0.1:PORT/callback?code=...`.

47For **MCP/Provider OAuth** (vscode:// URI): The redirect goes to a vscode:// URI.

48`oauth.simulate_callback` only *builds* the URI — it does not deliver it, and the ESM

49extension host can't `require()` the handler. To actually deliver the callback, call the

50debug-only hook via `ext.evaluate` (with `awaitPromise: true`):

51`globalThis.__clineHandleUri("vscode://saoudrizwan.claude-dev/...?code=...&state=...")`.

52It runs the same `SharedUriHandler.handleUri` as VSCode's real URI handler and exists only

53when `CLINE_CAPTURE_BROWSER` is set (the harness always sets it; never ships in prod).

54For end-to-end MCP OAuth, get a real `code` from the local MCP OAuth test server

55(`bun run dev:mcp-oauth-test-server`).

57## Navigating Views — Use Commands, Not Clicks

59Don't try to find/click small sidebar icons. Use VSCode commands via command palette.

60Registered in `src/registry.ts`:

62| Command | View |

63|---------|------|

64| `cline.accountButtonClicked` | Account / sign-in |

65| `cline.historyButtonClicked` | Task history |

66| `cline.settingsButtonClicked` | Settings |

67| `cline.mcpButtonClicked` | MCP servers |

68| `cline.plusButtonClicked` | New task (chat) |

69| `cline.worktreesButtonClicked` | Worktrees |

71```bash

72curl localhost:19229/api -d '{"method":"ui.command_palette","params":{"command":"cline.accountButtonClicked"}}'

73```

75## Key commands

77All via `POST localhost:19229/api` with `{"method":"...", "params":{...}}`:

79- **`launch`** / **`shutdown`** — lifecycle

80- **`ui.screenshot`** — screenshot to `/tmp/cline-debug/`; returns `{path}` — **use `read_file` on the path to examine, do NOT `open` the file** (Preview.app covers the VSCode window)

81- **`ui.open_sidebar`** — open the Cline sidebar

82- **`ext.set_breakpoint`** `{file, line, condition?}` — breakpoint by source file (sourcemap-resolved)

83- **`ext.evaluate`** `{expression, callFrameId?}` — eval in extension host

84- **`ext.resume`** / **`ext.step_over`** / **`ext.step_into`** — stepping

85- **`ext.call_stack`** — inspect when paused

86- **`web.evaluate`** `{expression}` — eval in webview

87- **`web.post_message`** `{message}` — send postMessage to extension host via exposed vsCodeApi

88- **`wait_for_pause`** `{timeout?}` — block until breakpoint hit

89- **`ui.locator`** `{role?, testId?, text?, frame?}` — Playwright locator (auto-retries on stale sidebar frame)

90- **`ui.react_input`** `{text, selector?, clear?, submit?}` — set React textarea value via `execCommand('insertText')`; works reliably across multiple tasks

91- **`ui.send_message`** `{text, images?, files?, responseType?}` — send chat message bypassing the textarea entirely (via gRPC postMessage)

92- **`ui.command_palette`** `{command}` — run VSCode command

94## Typical Session

96```bash

97# 1. Launch

98curl localhost:19229/api -d '{"method":"launch","params":{"skipBuild":true}}'

100# 2. Open sidebar + dismiss overlays (ALWAYS do this first)

101curl localhost:19229/api -d '{"method":"ui.open_sidebar"}'

102curl localhost:19229/api -d '{"method":"web.evaluate","params":{"expression":"document.querySelectorAll(\".sr-only\").forEach(el => el.parentElement?.click())"}}'

103

104# 3. Navigate to view

105curl localhost:19229/api -d '{"method":"ui.command_palette","params":{"command":"cline.accountButtonClicked"}}'

106

107# 4. Check captured OAuth URLs if testing auth

108curl localhost:19229/api -d '{"method":"oauth.captured_urls"}'

109

110# 5. Verify

111curl localhost:19229/api -d '{"method":"ui.screenshot"}'

112```

113

114## Caveats

115

116- **⚠️ Dismiss promotional overlays FIRST**: On fresh launches, full-screen promo overlays block the sidebar. **Dismiss immediately after `ui.open_sidebar`**, before any other interaction or screenshot. May need to run twice:

117 ```bash

118 curl localhost:19229/api -d '{"method": "ui.open_sidebar"}'

119 curl localhost:19229/api -d '{"method": "web.evaluate", "params": {"expression": "document.querySelectorAll(\".sr-only\").forEach(el => el.parentElement?.click())"}}'

120 ```

121- **Screenshots — don't open the file**: `ui.screenshot` and `ui.sidebar_screenshot` save PNGs to `/tmp/cline-debug/` and return the `{path}`. Use `read_file` on that path to examine screenshots. Running `open <path>` launches Preview.app on macOS which covers the VSCode window.

122- **Scripts count = 0 after launch**: CDP connects after extension host starts, so scripts parsed during startup aren't tracked. Breakpoints still work via sourcemap resolution.

123- **Port 9230**: Extension host inspector. If another VSCode instance uses this port, the harness will fail to connect. Kill other debug instances first.

124- **macOS only** for now (Playwright Electron launch behavior).

125- **Webview CDP**: `connect_webview` may fail depending on Electron version. `web.evaluate` still works via Playwright's `frame.evaluate()` fallback.

126- **Sourcemap paths**: esbuild outputs relative paths like `../src/extension.ts` in the sourcemap. The resolver handles this, but if a file isn't found, use `ext.source_files` to see exact paths.

127- **OAuth with fake codes**: Browser capture intercepts the URL but doesn't provide a valid auth code. For real OAuth testing, open the captured URL in a browser. For unit testing, mock the token exchange.

128

129See `src/dev/debug-harness/README.md` for full API reference.

130

cline/cline · sdk/AGENTS.md

@@ +1 @@

1---

2description: Development reference for the Cline SDK workspace.

3globs: "*.ts,*.tsx,*.js,*.jsx,*.json,*.md"

4alwaysApply: true

5---

7# Cline SDK — Development Reference

9Quick-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).

11## Repository Scope

13This 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.

15Run 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.

17## Package Boundaries

19### Published SDK Packages

21- `@cline/shared`: shared contracts, schemas, path helpers, hook engine, extension registry, low-level utilities

22- `@cline/llms`: provider settings/config, model catalogs, provider manifests, gateway contracts, handler creation

23- `@cline/agents`: stateless agent loop, tool orchestration, hook/extension runtime, event streaming

24- `@cline/core`: stateful orchestration, session lifecycle, storage, config watching, plugin loading, default tools, telemetry. Exposes `@cline/core/hub` for discovery, the detached daemon entry, WebSocket clients, and session/UI client adapters, plus `@cline/core/hub/daemon-entry` for launching the shared daemon

26### Dependency Direction

28```mermaid

29flowchart TD

30 shared["@cline/shared"] --> llms["@cline/llms"] & agents["@cline/agents"] & core["@cline/core"]

31 llms --> agents & core

32 agents --> core

33 core --> apps["CLI / VS Code / Code App"]

34```

36Rules:

37- `shared` stays low-level and reusable

38- `agents` stays stateless — no session/storage/config concerns

39- `core` owns stateful orchestration, including the shared-hub daemon, server, and client adapters under `src/hub/`

41## Change Routing

43Route changes to the package that owns the concern:

45- model/provider schemas or handler behavior: `@cline/llms`

46- stateless loop, tool orchestration, streaming, hook/extension runtime: `@cline/agents`

47- session lifecycle, storage, config watching, default tools, plugin loading, telemetry, hub runtime services, hub discovery, hub daemon spawn, and session-oriented client helpers (`HubSessionClient`, `HubUIClient`, `connectToHub`): `@cline/core` (hub pieces live under `src/hub/`)

48- remote-config schemas, managed instruction materialization, blob upload metadata, and OpenTelemetry config normalization: `@cline/shared/src/remote-config`

49- host-specific UX or shell behavior: app package

51## Verifying Changes

53Before testing in a fresh worktree, install SDK dependencies from the SDK workspace root:

55```sh

56cd sdk

57bun install --frozen-lockfile

58```

60SDK package exports resolve sibling packages through compiled `dist/` files. If `dist/` is missing, build the SDK packages before running package tests:

62```sh

63bun run build:sdk

64```

66SDK-root commands for cross-package confidence:

68```sh

69bun run types # typecheck all packages

70bun run test # run all tests

71bun run check # lint + build + typecheck + check-publish

72```

74For focused verification, prefer workspace package scripts from the SDK root:

76```sh

77bun -F @cline/shared test

78bun -F @cline/llms test

79bun -F @cline/agents test

80bun -F @cline/core test:unit

81bun -F @cline/cli test:unit

82```

84If 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.

86If you touch hub/bootstrap/session flows, please update `ARCHITECTURE.md`.

88## Practical Guidance

90### Keep Boundaries Clean

92- Don't move stateful logic down into `agents`

93- For `@cline/llms` provider/model routing rules, follow [packages/llms/AGENTS.md](./packages/llms/AGENTS.md).

94- Don't put app-specific behavior into `core` unless it is truly shared host behavior

95- Keep remote-config primitives generic in `shared`; host-facing session integration belongs in `core`

97### Refactor Standard

99- Prefer direct architectural cleanup over compatibility shims

100- Move code to the layer that owns the concern and update all call sites

101- If a helper just projects watcher state, keep it with the config layer instead of creating thin runtime wrappers

102

103## Documentation Responsibilities

104

105- `README.md`: visitor-facing overview. Update when the repo story or package inventory changes.

106- `CONTRIBUTING.md`: onboarding, workflow, publishing. Update when contributor setup or release process changes.

107- `AGENTS.md` (this file): development reference. Update when package boundaries, dependency rules, or change routing changes.

108- `ARCHITECTURE.md`: design, boundaries, runtime flows. Update when system design or architectural constraints change.

109- `DOC.md`: API and behavior reference. Update when exported surfaces, lifecycle semantics, or runtime behavior changes.

110

@@ −1 +1 @@

1−# Debug Harness

1+---

2+description: Development reference for the Cline SDK workspace.

3+globs: "*.ts,*.tsx,*.js,*.jsx,*.json,*.md"

4+alwaysApply: true

5+---

3−HTTP-controlled debugger for the VSCode extension at `src/dev/debug-harness/server.ts`.

7+# Cline SDK — Development Reference

5−## Quick start

9+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).

610

7−```bash

8−# Build extension first if needed (protos + esbuild):

9−bun run protos && IS_DEV=true bun esbuild.mjs

11+## Repository Scope

1012

11−# Launch (skip-build if already built). Run with node, NOT bun — Playwright's

12−# Electron launch times out under bun:

13−node src/dev/debug-harness/server.ts --skip-build --auto-launch

13+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.

1414

15−# In another terminal:

16−curl localhost:19229/api -d '{"method":"status"}'

17−```

15+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.

1816

19−## Data Isolation

17+## Package Boundaries

2018

21−The debugee runs with `CLINE_DIR=~/.cline2` by default, separate from your real `~/.cline`.

22−This prevents the debugee's logout from logging out the debugger, and vice versa.

23−Override with `--cline-dir /tmp/test-dir`. Check with `status()` → `clineDir`.

19+### Published SDK Packages

2420

25−## Browser Capture & OAuth

21+- `@cline/shared`: shared contracts, schemas, path helpers, hook engine, extension registry, low-level utilities

22+- `@cline/llms`: provider settings/config, model catalogs, provider manifests, gateway contracts, handler creation

23+- `@cline/agents`: stateless agent loop, tool orchestration, hook/extension runtime, event streaming

24+- `@cline/core`: stateful orchestration, session lifecycle, storage, config watching, plugin loading, default tools, telemetry. Exposes `@cline/core/hub` for discovery, the detached daemon entry, WebSocket clients, and session/UI client adapters, plus `@cline/core/hub/daemon-entry` for launching the shared daemon

2625

27−The debugee runs with `CLINE_CAPTURE_BROWSER=1`, which intercepts `openExternal()` in

28−`src/utils/env.ts`. URLs are captured instead of opening a real browser:

26+### Dependency Direction

2927

30−- Logged to `$CLINE_DIR/data/debug-captured-urls.jsonl`

31−- POSTed in real-time to `/captured-url` on the harness server

32−- Queryable via `oauth.captured_urls`

28+```mermaid

29+flowchart TD

30+ shared["@cline/shared"] --> llms["@cline/llms"] & agents["@cline/agents"] & core["@cline/core"]

31+ llms --> agents & core

32+ agents --> core

33+ core --> apps["CLI / VS Code / Code App"]

34+```

3335

34−### OAuth API

36+Rules:

37+- `shared` stays low-level and reusable

38+- `agents` stays stateless — no session/storage/config concerns

39+- `core` owns stateful orchestration, including the shared-hub daemon, server, and client adapters under `src/hub/`

3540

36−- **`oauth.captured_urls`** `{clear?}` — URLs the debugee tried to open

37−- **`oauth.read_stored_token`** — Check auth token presence in secrets.json

38−- **`oauth.simulate_callback`** `{path, code?, state?, provider?, token?}` — Build vscode:// callback URI

39−- **`oauth.read_captured_urls_file`** — Read on-disk JSONL of captured URLs

41+## Change Routing

4042

41−### OAuth testing flow

43+Route changes to the package that owns the concern:

4244

43−For **Cline OAuth** (SDK local callback): The SDK starts a local HTTP server, the auth URL

44−is captured. To complete: open the captured URL in a real browser (it redirects back to the

45−SDK's callback server), OR extract the callback port and `curl http://127.0.0.1:PORT/callback?code=...`.

45+- model/provider schemas or handler behavior: `@cline/llms`

46+- stateless loop, tool orchestration, streaming, hook/extension runtime: `@cline/agents`

47+- session lifecycle, storage, config watching, default tools, plugin loading, telemetry, hub runtime services, hub discovery, hub daemon spawn, and session-oriented client helpers (`HubSessionClient`, `HubUIClient`, `connectToHub`): `@cline/core` (hub pieces live under `src/hub/`)

48+- remote-config schemas, managed instruction materialization, blob upload metadata, and OpenTelemetry config normalization: `@cline/shared/src/remote-config`

49+- host-specific UX or shell behavior: app package

4650

47−For **MCP/Provider OAuth** (vscode:// URI): The redirect goes to a vscode:// URI.

48−`oauth.simulate_callback` only *builds* the URI — it does not deliver it, and the ESM

49−extension host can't `require()` the handler. To actually deliver the callback, call the

50−debug-only hook via `ext.evaluate` (with `awaitPromise: true`):

51−`globalThis.__clineHandleUri("vscode://saoudrizwan.claude-dev/...?code=...&state=...")`.

52−It runs the same `SharedUriHandler.handleUri` as VSCode's real URI handler and exists only

53−when `CLINE_CAPTURE_BROWSER` is set (the harness always sets it; never ships in prod).

54−For end-to-end MCP OAuth, get a real `code` from the local MCP OAuth test server

55−(`bun run dev:mcp-oauth-test-server`).

51+## Verifying Changes

5652

57−## Navigating Views — Use Commands, Not Clicks

53+Before testing in a fresh worktree, install SDK dependencies from the SDK workspace root:

5854

59−Don't try to find/click small sidebar icons. Use VSCode commands via command palette.

60−Registered in `src/registry.ts`:

55+```sh

56+cd sdk

57+bun install --frozen-lockfile

58+```

6159

62−| Command | View |

63−|---------|------|

64−| `cline.accountButtonClicked` | Account / sign-in |

65−| `cline.historyButtonClicked` | Task history |

66−| `cline.settingsButtonClicked` | Settings |

67−| `cline.mcpButtonClicked` | MCP servers |

68−| `cline.plusButtonClicked` | New task (chat) |

69−| `cline.worktreesButtonClicked` | Worktrees |

60+SDK package exports resolve sibling packages through compiled `dist/` files. If `dist/` is missing, build the SDK packages before running package tests:

7061

71−```bash

72−curl localhost:19229/api -d '{"method":"ui.command_palette","params":{"command":"cline.accountButtonClicked"}}'

62+```sh

63+bun run build:sdk

7364 ```

7465

75−## Key commands

66+SDK-root commands for cross-package confidence:

7667

77−All via `POST localhost:19229/api` with `{"method":"...", "params":{...}}`:

68+```sh

69+bun run types # typecheck all packages

70+bun run test # run all tests

71+bun run check # lint + build + typecheck + check-publish

72+```

7873

79−- **`launch`** / **`shutdown`** — lifecycle

80−- **`ui.screenshot`** — screenshot to `/tmp/cline-debug/`; returns `{path}` — **use `read_file` on the path to examine, do NOT `open` the file** (Preview.app covers the VSCode window)

81−- **`ui.open_sidebar`** — open the Cline sidebar

82−- **`ext.set_breakpoint`** `{file, line, condition?}` — breakpoint by source file (sourcemap-resolved)

83−- **`ext.evaluate`** `{expression, callFrameId?}` — eval in extension host

84−- **`ext.resume`** / **`ext.step_over`** / **`ext.step_into`** — stepping

85−- **`ext.call_stack`** — inspect when paused

86−- **`web.evaluate`** `{expression}` — eval in webview

87−- **`web.post_message`** `{message}` — send postMessage to extension host via exposed vsCodeApi

88−- **`wait_for_pause`** `{timeout?}` — block until breakpoint hit

89−- **`ui.locator`** `{role?, testId?, text?, frame?}` — Playwright locator (auto-retries on stale sidebar frame)

90−- **`ui.react_input`** `{text, selector?, clear?, submit?}` — set React textarea value via `execCommand('insertText')`; works reliably across multiple tasks

91−- **`ui.send_message`** `{text, images?, files?, responseType?}` — send chat message bypassing the textarea entirely (via gRPC postMessage)

92−- **`ui.command_palette`** `{command}` — run VSCode command

74+For focused verification, prefer workspace package scripts from the SDK root:

9375

94−## Typical Session

76+```sh

77+bun -F @cline/shared test

78+bun -F @cline/llms test

79+bun -F @cline/agents test

80+bun -F @cline/core test:unit

81+bun -F @cline/cli test:unit

82+```

9583

96−```bash

97−# 1. Launch

98−curl localhost:19229/api -d '{"method":"launch","params":{"skipBuild":true}}'

84+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.

9985

100−# 2. Open sidebar + dismiss overlays (ALWAYS do this first)

101−curl localhost:19229/api -d '{"method":"ui.open_sidebar"}'

102−curl localhost:19229/api -d '{"method":"web.evaluate","params":{"expression":"document.querySelectorAll(\".sr-only\").forEach(el => el.parentElement?.click())"}}'

86+If you touch hub/bootstrap/session flows, please update `ARCHITECTURE.md`.

10387

104−# 3. Navigate to view

105−curl localhost:19229/api -d '{"method":"ui.command_palette","params":{"command":"cline.accountButtonClicked"}}'

88+## Practical Guidance

10689

107−# 4. Check captured OAuth URLs if testing auth

108−curl localhost:19229/api -d '{"method":"oauth.captured_urls"}'

90+### Keep Boundaries Clean

10991

110−# 5. Verify

111−curl localhost:19229/api -d '{"method":"ui.screenshot"}'

112−```

92+- Don't move stateful logic down into `agents`

93+- For `@cline/llms` provider/model routing rules, follow [packages/llms/AGENTS.md](./packages/llms/AGENTS.md).

94+- Don't put app-specific behavior into `core` unless it is truly shared host behavior

95+- Keep remote-config primitives generic in `shared`; host-facing session integration belongs in `core`

11396

114−## Caveats

97+### Refactor Standard

11598

116−- **⚠️ Dismiss promotional overlays FIRST**: On fresh launches, full-screen promo overlays block the sidebar. **Dismiss immediately after `ui.open_sidebar`**, before any other interaction or screenshot. May need to run twice:

117− ```bash

118− curl localhost:19229/api -d '{"method": "ui.open_sidebar"}'

119− curl localhost:19229/api -d '{"method": "web.evaluate", "params": {"expression": "document.querySelectorAll(\".sr-only\").forEach(el => el.parentElement?.click())"}}'

120− ```

121−- **Screenshots — don't open the file**: `ui.screenshot` and `ui.sidebar_screenshot` save PNGs to `/tmp/cline-debug/` and return the `{path}`. Use `read_file` on that path to examine screenshots. Running `open <path>` launches Preview.app on macOS which covers the VSCode window.

122−- **Scripts count = 0 after launch**: CDP connects after extension host starts, so scripts parsed during startup aren't tracked. Breakpoints still work via sourcemap resolution.

123−- **Port 9230**: Extension host inspector. If another VSCode instance uses this port, the harness will fail to connect. Kill other debug instances first.

124−- **macOS only** for now (Playwright Electron launch behavior).

125−- **Webview CDP**: `connect_webview` may fail depending on Electron version. `web.evaluate` still works via Playwright's `frame.evaluate()` fallback.

126−- **Sourcemap paths**: esbuild outputs relative paths like `../src/extension.ts` in the sourcemap. The resolver handles this, but if a file isn't found, use `ext.source_files` to see exact paths.

127−- **OAuth with fake codes**: Browser capture intercepts the URL but doesn't provide a valid auth code. For real OAuth testing, open the captured URL in a browser. For unit testing, mock the token exchange.

99+- Prefer direct architectural cleanup over compatibility shims

100+- Move code to the layer that owns the concern and update all call sites

101+- If a helper just projects watcher state, keep it with the config layer instead of creating thin runtime wrappers

128102

129−See `src/dev/debug-harness/README.md` for full API reference.

103+## Documentation Responsibilities

104+

105+- `README.md`: visitor-facing overview. Update when the repo story or package inventory changes.

106+- `CONTRIBUTING.md`: onboarding, workflow, publishing. Update when contributor setup or release process changes.

107+- `AGENTS.md` (this file): development reference. Update when package boundaries, dependency rules, or change routing changes.

108+- `ARCHITECTURE.md`: design, boundaries, runtime flows. Update when system design or architectural constraints change.

109+- `DOC.md`: API and behavior reference. Update when exported surfaces, lifecycle semantics, or runtime behavior changes.

130110