Merge branch 'main' into docs/explain-changes-feature-page

- Create docs/features/explain-changes.mdx with full feature documentation
- Add page to Features navigation group in docs.json
- Update redirect for /features/slash-commands/explain-changes
- Fix link in using-commands.mdx to point to new dedicated page

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -26,12 +26,6 @@ body:
       placeholder: 'e.g., 1.2.3'
     validations:
       required: true
-  - type: checkboxes
-    id: beta
-    attributes:
-      label: Beta version
-      options:
-        - label: I am using a beta version of Cline
   - type: textarea
     id: what-happened
     attributes:

.github/workflows/cli-tui-tests.yml

@@ -0,0 +1,83 @@
+name: CLI TUI Tests
+
+on:
+  pull_request:
+    branches:
+      - main
+  workflow_dispatch:
+  workflow_call:
+
+permissions:
+  contents: read
+
+jobs:
+  cli-tui-tests:
+    name: CLI TUI Tests
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+
+      - name: Install dependencies
+        run: npm ci
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Build CLI
+        run: npm run cli:build
+
+      - name: Run TUI Tests
+        id: tui_tests
+        run: |
+          npm run test:e2e:cli:tui 2>&1 | tee tui-test-output.log
+          exit_code=${PIPESTATUS[0]}
+          echo "tui_exit_code=$exit_code" >> $GITHUB_OUTPUT
+          exit $exit_code
+
+      - name: Write failure summary
+        if: always() && steps.tui_tests.outcome != 'success' && steps.tui_tests.outcome != 'skipped'
+        run: |
+          echo "## ❌ CLI TUI Tests Failed" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "**Step outcome:** \`${{ steps.tui_tests.outcome }}\`" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "### Test Output" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo '```' >> $GITHUB_STEP_SUMMARY
+          if [ -f tui-test-output.log ]; then
+            cat tui-test-output.log >> $GITHUB_STEP_SUMMARY
+          else
+            echo "(no test output captured — process may have been killed before output was flushed)" >> $GITHUB_STEP_SUMMARY
+          fi
+          echo '```' >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "### Debugging" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "- **TUI traces** are attached as artifacts below — download and inspect them to see terminal state at the point of failure." >> $GITHUB_STEP_SUMMARY
+          echo "- **To view a trace replay/Run a TUI Trace: ** run \`npx tui-test show-trace path/to/trace/file\` in your terminal" >> $GITHUB_STEP_SUMMARY
+          echo "- **Full test log** is also attached as an artifact." >> $GITHUB_STEP_SUMMARY
+          echo "- Tests run with \`retries: 2\` so any failure shown is a consistent failure, not a flake." >> $GITHUB_STEP_SUMMARY
+
+      - name: Upload TUI traces
+        if: always() && steps.tui_tests.outcome != 'success' && steps.tui_tests.outcome != 'skipped'
+        uses: actions/upload-artifact@v4
+        with:
+          name: tui-test-traces
+          path: tests/e2e/cli/tui-traces/
+          retention-days: 14
+          if-no-files-found: warn
+
+      - name: Upload test log
+        if: always() && steps.tui_tests.outcome != 'success' && steps.tui_tests.outcome != 'skipped'
+        uses: actions/upload-artifact@v4
+        with:
+          name: tui-test-log
+          path: tui-test-output.log
+          retention-days: 14
+          if-no-files-found: warn

.github/workflows/cline-evals-regression.yml

@@ -1,14 +1,21 @@
 name: Smoke Tests
 
-# Temporarily disabled: this workflow built and linked the legacy CLI
-# (`cd cli && npm install && npm run build && npm link`) before running the
-# smoke-test scenarios. The legacy CLI publish chain has been retired in
-# favor of the SDK CLI at `sdk/apps/cli/`. The scenarios under
-# `evals/smoke-tests/scenarios/` are CLI-agnostic and should be re-enabled
-# once the build step is repointed at the new SDK CLI. Until then, only
-# manual `workflow_dispatch` runs are accepted (and will fail in their
-# current form).
 on:
+  push:
+    branches: [main]
+    paths:
+      - 'src/core/**'
+      - 'src/shared/**'
+      - 'proto/**'
+      - 'evals/**'
+      - '.github/workflows/cline-evals-regression.yml'
+  pull_request:
+    paths:
+      - 'src/core/**'
+      - 'src/shared/**'
+      - 'proto/**'
+      - 'evals/**'
+      - '.github/workflows/cline-evals-regression.yml'
   workflow_dispatch:
 
 permissions:

.github/workflows/label-jetbrains-issues.yml

@@ -51,15 +51,3 @@ jobs:
                 });
               }
             }
-
-            // Check if beta version checkbox is checked
-            if (body.includes('- [X] I am using a beta version of Cline') || body.includes('- [x] I am using a beta version of Cline')) {
-              if (!labels.includes('beta')) {
-                await github.rest.issues.addLabels({
-                  owner: context.repo.owner,
-                  repo: context.repo.repo,
-                  issue_number: context.issue.number,
-                  labels: ['beta']
-                });
-              }
-            }

.github/workflows/npm-main.yaml

@@ -0,0 +1,111 @@
+name: Publish NPM Release
+
+on:
+  workflow_call:
+    inputs:
+      confirm_publish:
+        description: 'Type "publish" to confirm you want to publish to NPM'
+        required: true
+        type: string
+
+permissions:
+  contents: write # Required for pushing tags
+  id-token: write # Required for npm trusted publishing (OIDC)
+  checks: write # Required by test workflow
+  pull-requests: write # Required by test workflow
+
+jobs:
+  test:
+    uses: ./.github/workflows/test.yml
+
+  publish-npm-release:
+    needs: test
+    name: Publish Cline CLI to NPM
+    if: github.repository == 'cline/cline' && github.ref == 'refs/heads/main' && inputs.confirm_publish == 'publish'
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "24.x"
+          registry-url: "https://registry.npmjs.org"
+
+      - name: Install root dependencies and CLI dependencies
+        run: npm ci --include=optional # this will also install cli deps because "cli" in included in root package.json workspaces field
+
+      - name: Generate Protos
+        run: npm run protos
+
+      - name: Read release version
+        id: version
+        run: |
+          # Read version from cli/package.json
+          VERSION=$(node -p "require('./cli/package.json').version")
+          echo "Release version: $VERSION"
+          echo "version=$VERSION" >> $GITHUB_OUTPUT
+
+      - name: Build standalone NPM package
+        env:
+          TELEMETRY_SERVICE_API_KEY: ${{ secrets.TELEMETRY_SERVICE_API_KEY }}
+          ERROR_SERVICE_API_KEY: ${{ secrets.ERROR_SERVICE_API_KEY }}
+          CLINE_ENVIRONMENT: production
+          OTEL_TELEMETRY_ENABLED: "1"
+          OTEL_METRICS_EXPORTER: otlp
+          OTEL_LOGS_EXPORTER: otlp
+          OTEL_EXPORTER_OTLP_PROTOCOL: ${{ secrets.OTEL_EXPORTER_OTLP_PROTOCOL }}
+          OTEL_EXPORTER_OTLP_ENDPOINT: ${{ secrets.OTEL_EXPORTER_OTLP_ENDPOINT }}
+          OTEL_EXPORTER_OTLP_HEADERS: ${{ secrets.OTEL_EXPORTER_OTLP_HEADERS }}
+        run: node scripts/package-npm.mjs
+
+      - name: Verify build output
+        run: |
+          echo "Checking dist-standalone directory..."
+          ls -la dist-standalone/
+
+          echo "Verifying CLI binaries..."
+          ls -lh cli/bin/cline-* || echo "Warning: CLI binaries not found"
+
+          echo "Checking package.json in dist-standalone..."
+          cat dist-standalone/package.json | grep version
+
+      - name: Publish to NPM with latest tag
+        run: |
+          echo "Publishing version ${{ steps.version.outputs.version }} to NPM with tag 'latest'..."
+          cd dist-standalone
+          npm publish --tag latest --access public
+
+      - name: Tag release
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git tag "v${{ steps.version.outputs.version }}-cli"
+          git push origin "v${{ steps.version.outputs.version }}-cli"
+
+      - name: Summary
+        run: |
+          echo "✅ Successfully published cline@${{ steps.version.outputs.version }} to NPM with tag 'latest'"
+          echo ""
+          echo "📦 Install with: npm install -g cline"
+          echo "🔗 NPM: https://www.npmjs.com/package/cline/v/${{ steps.version.outputs.version }}"
+
+      - name: Post release to Slack
+        uses: slackapi/slack-github-action@v3.0.1
+        with:
+          method: chat.postMessage
+          token: ${{ secrets.SLACK_RELEASE_BOT_TOKEN }}
+          payload: |
+            channel: "C0APVKGGZFC"
+            text: "Cline CLI v${{ steps.version.outputs.version }}"
+            blocks:
+              - type: "section"
+                text:
+                  type: "mrkdwn"
+                  text: "*Cline CLI v${{ steps.version.outputs.version }}*"
+              - type: "context"
+                elements:
+                  - type: "mrkdwn"
+                    text: "<https://www.npmjs.com/package/cline/v/${{ steps.version.outputs.version }}|View on npm>"

.github/workflows/npm-nightly.yaml

@@ -0,0 +1,134 @@
+name: Publish NPM Nightly
+
+on:
+  workflow_call:
+    inputs:
+      force_publish:
+        description: "Force publish even if there are no commits in the last 24 hours"
+        required: false
+        type: boolean
+        default: false
+
+permissions:
+  contents: read
+  id-token: write # Required for npm trusted publishing (OIDC)
+  checks: write # Required by test workflow
+  pull-requests: write # Required by test workflow
+
+jobs:
+  test:
+    uses: ./.github/workflows/test.yml
+
+  publish-npm-nightly:
+    needs: test
+    name: Publish Cline CLI (Nightly) to NPM
+    if: github.repository == 'cline/cline' && github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Check for recent commits
+        id: check_commits
+        run: |
+          if [ "${{ inputs.force_publish }}" = "true" ]; then
+            echo "force_publish enabled, proceeding with publish"
+            echo "skip=false" >> $GITHUB_OUTPUT
+            exit 0
+          fi
+
+          if [ $(git rev-list --count HEAD --since="24 hours ago") -eq 0 ]; then
+            echo "No commits in last 24 hours, skipping publish"
+            echo "skip=true" >> $GITHUB_OUTPUT
+          else
+            echo "Found recent commits, proceeding with publish"
+            echo "skip=false" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Setup Node.js
+        if: steps.check_commits.outputs.skip != 'true'
+        uses: actions/setup-node@v4
+        with:
+          node-version: "24.x"
+          registry-url: "https://registry.npmjs.org"
+
+      - name: Install root dependencies and CLI dependencies
+        if: steps.check_commits.outputs.skip != 'true'
+        run: npm ci --include=optional # this will also install cli deps because "cli" in included in root package.json workspaces field
+
+      - name: Generate Protos
+        if: steps.check_commits.outputs.skip != 'true'
+        run: npm run protos
+
+      - name: Generate nightly version with timestamp
+        if: steps.check_commits.outputs.skip != 'true'
+        id: version
+        run: |
+          # Read base version from cli/package.json (e.g., "2.0.0")
+          BASE_VERSION=$(node -p "require('./cli/package.json').version")
+
+          # Generate timestamp (Unix epoch seconds)
+          TIMESTAMP=$(date +%s)
+
+          # Create unique nightly version: 1.0.9-nightly.1736365200
+          VERSION="${BASE_VERSION}-nightly.${TIMESTAMP}"
+
+          echo "Base version: $BASE_VERSION"
+          echo "Generated nightly version: $VERSION"
+          echo "version=$VERSION" >> $GITHUB_OUTPUT
+
+      - name: Update cli/package.json with nightly version
+        if: steps.check_commits.outputs.skip != 'true'
+        run: |
+          # Update version with timestamp-based nightly version
+          node -e "
+            const fs = require('fs');
+            const pkg = JSON.parse(fs.readFileSync('cli/package.json', 'utf8'));
+            pkg.version = '${{ steps.version.outputs.version }}';
+            fs.writeFileSync('cli/package.json', JSON.stringify(pkg, null, '\t'));
+          "
+
+          echo "Using version ${{ steps.version.outputs.version }} for build"
+          cat cli/package.json | grep '"version"'
+
+      - name: Build and package CLI
+        if: steps.check_commits.outputs.skip != 'true'
+        env:
+          TELEMETRY_SERVICE_API_KEY: ${{ secrets.TELEMETRY_SERVICE_API_KEY }}
+          ERROR_SERVICE_API_KEY: ${{ secrets.ERROR_SERVICE_API_KEY }}
+          CLINE_ENVIRONMENT: production
+          OTEL_TELEMETRY_ENABLED: "1"
+          OTEL_METRICS_EXPORTER: otlp
+          OTEL_LOGS_EXPORTER: otlp
+          OTEL_EXPORTER_OTLP_PROTOCOL: ${{ secrets.OTEL_EXPORTER_OTLP_PROTOCOL }}
+          OTEL_EXPORTER_OTLP_ENDPOINT: ${{ secrets.OTEL_EXPORTER_OTLP_ENDPOINT }}
+          OTEL_EXPORTER_OTLP_HEADERS: ${{ secrets.OTEL_EXPORTER_OTLP_HEADERS }}
+        run: node scripts/package-npm.mjs
+
+      - name: Verify build output
+        if: steps.check_commits.outputs.skip != 'true'
+        run: |
+          echo "Checking dist-standalone directory..."
+          ls -la dist-standalone/
+
+          echo "Verifying CLI binaries..."
+          ls -lh cli/bin/cline-* || echo "Warning: CLI binaries not found"
+
+          echo "Checking package.json in dist-standalone..."
+          cat dist-standalone/package.json | grep version
+
+      - name: Publish to NPM with nightly tag
+        if: steps.check_commits.outputs.skip != 'true'
+        run: |
+          echo "Publishing version ${{ steps.version.outputs.version }} to NPM with tag 'nightly'..."
+          cd dist-standalone
+          npm publish --tag nightly --access public
+
+      - name: Summary
+        if: steps.check_commits.outputs.skip != 'true'
+        run: |
+          echo "✅ Successfully published cline@${{ steps.version.outputs.version }} to NPM with tag 'nightly'"
+          echo ""
+          echo "📦 Install with: npm install -g cline@nightly"
+          echo "🔗 NPM: https://www.npmjs.com/package/cline/v/${{ steps.version.outputs.version }}"

.github/workflows/pack-cli.yml

@@ -0,0 +1,215 @@
+# Build and Pack CLI
+#
+# Builds a CLI tarball from any branch/commit and publishes it as a GitHub Release.
+# Requires write access to the repository (maintainers/collaborators only).
+#
+# Security: Split into two jobs to isolate untrusted build code from write tokens.
+# The build job runs arbitrary ref code with zero permissions. The release job
+# only runs trusted GitHub Actions with write scope.
+#
+# Usage (helper script, auto-detects current branch):
+#   ./scripts/build-cli-artifact.sh
+#   ./scripts/build-cli-artifact.sh feature/my-changes
+#   ./scripts/build-cli-artifact.sh feature/my-changes 1234  # comments on PR
+#
+# Usage (gh CLI directly):
+#   gh workflow run pack-cli.yml -f ref=main
+#   gh workflow run pack-cli.yml -f ref=abc123 -f pr_number=1234
+#
+# Install the built CLI (no auth required):
+#   npm install -g https://github.com/cline/cline/releases/download/cli-build-<sha>/cline-<ver>.tgz
+#
+# Find releases:
+#   gh release list --limit 10
+
+name: Build and Pack CLI
+
+permissions:
+  contents: read
+
+on:
+  workflow_dispatch:
+    inputs:
+      ref:
+        description: 'Branch, tag, or commit SHA to build (leave empty for default branch)'
+        required: false
+        type: string
+      pr_number:
+        description: 'PR number to comment on with install instructions (optional)'
+        required: false
+        type: number
+
+jobs:
+  # ── Build job: runs untrusted ref code with ZERO permissions ──
+  build:
+    name: Build CLI
+    runs-on: ubuntu-latest
+    permissions: {}
+    outputs:
+      commit_sha: ${{ steps.commit.outputs.sha }}
+      tarball: ${{ steps.pack.outputs.tarball }}
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ inputs.ref || github.ref }}
+          persist-credentials: false
+
+      - name: Get commit SHA
+        id: commit
+        run: |
+          COMMIT_SHA=$(git rev-parse --short HEAD)
+          echo "sha=$COMMIT_SHA" >> $GITHUB_OUTPUT
+          echo "Building from commit: $COMMIT_SHA"
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20.x"
+
+      - name: Install dependencies
+        run: npm ci --include=optional
+
+      - name: Generate Protos
+        run: npm run protos
+
+      - name: Build standalone package
+        run: node scripts/package-npm.mjs
+
+      - name: Create Tarball
+        id: pack
+        run: |
+          cd dist-standalone
+          TARBALL=$(npm pack)
+          echo "tarball=$TARBALL" >> $GITHUB_OUTPUT
+          echo "Created tarball: $TARBALL"
+
+      - name: Upload artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: cli-tarball
+          path: dist-standalone/*.tgz
+
+  # ── Release job: only trusted Actions code, with write permissions ──
+  release:
+    name: Release CLI
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+      issues: write
+    steps:
+      - name: Download artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: cli-tarball
+          path: dist-standalone
+
+      - name: Create GitHub Release
+        id: create_release
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const fs = require('fs');
+            const path = require('path');
+            const commit = '${{ needs.build.outputs.commit_sha }}';
+            const tarball = '${{ needs.build.outputs.tarball }}';
+
+            // Delete existing release/tag if re-running for the same commit
+            const tagName = `cli-build-${commit}`;
+            try {
+              const existing = await github.rest.repos.getReleaseByTag({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                tag: tagName
+              });
+              await github.rest.repos.deleteRelease({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                release_id: existing.data.id
+              });
+              await github.rest.git.deleteRef({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                ref: `tags/${tagName}`
+              });
+              core.info(`Deleted existing release for ${tagName}`);
+            } catch (e) {
+              // Release doesn't exist yet, that's fine
+            }
+
+            // Create a release
+            const release = await github.rest.repos.createRelease({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              tag_name: tagName,
+              name: `CLI Build (${commit})`,
+              body: `Automated CLI build from commit ${commit}\n\nInstall with:\n\`\`\`bash\nnpm install -g https://github.com/${context.repo.owner}/${context.repo.repo}/releases/download/${tagName}/${tarball}\n\`\`\``,
+              draft: false,
+              prerelease: true
+            });
+
+            // Upload the tarball as a release asset
+            const tarballPath = path.join('dist-standalone', tarball);
+            const tarballData = fs.readFileSync(tarballPath);
+
+            await github.rest.repos.uploadReleaseAsset({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              release_id: release.data.id,
+              name: tarball,
+              data: tarballData
+            });
+
+            const downloadUrl = `https://github.com/${context.repo.owner}/${context.repo.repo}/releases/download/${tagName}/${tarball}`;
+            core.setOutput('release_url', release.data.html_url);
+            core.setOutput('download_url', downloadUrl);
+
+      - name: Comment on PR with download instructions
+        if: inputs.pr_number != ''
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const commit = '${{ needs.build.outputs.commit_sha }}';
+            const releaseUrl = '${{ steps.create_release.outputs.release_url }}';
+            const downloadUrl = '${{ steps.create_release.outputs.download_url }}';
+            const prNumber = ${{ inputs.pr_number || 0 }};
+            if (!prNumber) return;
+
+            const comment = `## 📦 CLI Build Ready
+
+            A CLI build has been created for commit \`${commit}\`.
+
+            ### Install Directly from URL (No Authentication Required!)
+
+            \`\`\`bash
+            npm install -g ${downloadUrl}
+            \`\`\`
+
+            ### Alternative: Download and Install
+
+            \`\`\`bash
+            curl -L ${downloadUrl} -o cline.tgz
+            npm install -g ./cline.tgz
+            \`\`\`
+
+            📦 [View Release](${releaseUrl})
+            `;
+
+            await github.rest.issues.createComment({
+              issue_number: prNumber,
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              body: comment
+            });
+
+      - name: Summary
+        run: |
+          echo "✅ CLI build complete!"
+          echo ""
+          echo "📦 Release: ${{ steps.create_release.outputs.release_url }}"
+          echo "🔗 Download URL: ${{ steps.create_release.outputs.download_url }}"
+          echo ""
+          echo "Install from anywhere (no authentication required):"
+          echo "  npm install -g ${{ steps.create_release.outputs.download_url }}"

.github/workflows/publish-cli-trusted.yaml

@@ -0,0 +1,60 @@
+name: Publish CLI (Trusted)
+
+on:
+  schedule:
+    - cron: "0 12 * * *" # 4 AM PST (UTC-8) = 12 UTC
+  workflow_dispatch:
+    inputs:
+      publish_target:
+        description: "Which publish flow to run"
+        required: true
+        default: "main"
+        type: choice
+        options:
+          - main
+          - nightly
+      confirm_publish:
+        description: 'Required when publish_target=main. Type "publish" to confirm release publish.'
+        required: false
+        type: string
+      force_nightly_publish:
+        description: "Force nightly publish even with no commits in last 24h"
+        required: false
+        type: boolean
+        default: false
+
+permissions:
+  id-token: write # Required for npm trusted publishing (OIDC)
+  contents: write # Required because npm-main creates/pushes git tags
+  checks: write # Required by nested reusable test workflow
+  pull-requests: write # Required by nested reusable test workflow
+
+jobs:
+  cli-tui-tests:
+    uses: ./.github/workflows/cli-tui-tests.yml
+
+  publish-main:
+    needs: cli-tui-tests
+    if: |
+      github.repository == 'cline/cline' && (
+        github.event_name == 'workflow_dispatch' &&
+        github.event.inputs.publish_target == 'main' &&
+        github.event.inputs.confirm_publish == 'publish' &&
+        !endsWith(github.actor, '[bot]')
+      )
+    uses: ./.github/workflows/npm-main.yaml
+    secrets: inherit
+    with:
+      confirm_publish: ${{ github.event.inputs.confirm_publish }}
+
+  publish-nightly:
+    needs: cli-tui-tests
+    if: |
+      github.repository == 'cline/cline' && (
+        github.event_name == 'schedule' ||
+        (github.event_name == 'workflow_dispatch' && github.event.inputs.publish_target == 'nightly')
+      )
+    uses: ./.github/workflows/npm-nightly.yaml
+    secrets: inherit
+    with:
+      force_publish: ${{ github.event_name == 'workflow_dispatch' && github.event.inputs.force_nightly_publish == 'true' }}

.github/workflows/publish-cli.yaml

@@ -1,394 +0,0 @@
-name: Publish CLI to NPM
-
-on:
-  schedule:
-    - cron: "0 12 * * *"
-  workflow_dispatch:
-    inputs:
-      publish_target:
-        description: "Which publish flow to run"
-        required: true
-        default: "main"
-        type: choice
-        options:
-          - main
-          - nightly
-      git_tag:
-        description: "Existing release tag to publish when publish_target=main, for example cli-v0.1.0"
-        required: false
-        type: string
-      confirm_publish:
-        description: 'Required when publish_target=main. Type "publish" to confirm release publish.'
-        required: false
-        type: string
-      force_nightly_publish:
-        description: "Force nightly publish even with no commits in last 24h"
-        required: false
-        type: boolean
-        default: false
-
-permissions:
-  contents: read
-  id-token: write
-
-defaults:
-  run:
-    working-directory: sdk
-
-jobs:
-  publish-main:
-    name: Publish cline
-    permissions:
-      contents: write
-      id-token: write
-    if: |
-      github.repository == 'cline/cline' &&
-      github.ref == 'refs/heads/main' &&
-      github.event_name == 'workflow_dispatch' &&
-      github.event.inputs.publish_target == 'main' &&
-      github.event.inputs.confirm_publish == 'publish' &&
-      !endsWith(github.actor, '[bot]')
-    runs-on: ubuntu-latest
-
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@v4
-        with:
-          ref: ${{ github.event.inputs.git_tag }}
-          fetch-depth: 0
-          fetch-tags: true
-
-      - name: Setup Bun
-        uses: oven-sh/setup-bun@v2
-        with:
-          bun-version: "1.3.13"
-
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: "24.x"
-          registry-url: "https://registry.npmjs.org"
-
-      - name: Verify publish tooling
-        run: |
-          NPM_VERSION=$(npm --version)
-          echo "npm ${NPM_VERSION}"
-          IFS=. read -r major minor patch <<EOF
-          ${NPM_VERSION}
-          EOF
-          if [ "$major" -lt 11 ] || { [ "$major" -eq 11 ] && [ "$minor" -lt 5 ]; } || { [ "$major" -eq 11 ] && [ "$minor" -eq 5 ] && [ "$patch" -lt 1 ]; }; then
-            echo "npm 11.5.1 or newer is required for trusted publishing"
-            exit 1
-          fi
-
-      - name: Install dependencies
-        run: bun install
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-
-      - name: Validate release tag
-        id: version
-        run: |
-          TAG="${{ github.event.inputs.git_tag }}"
-
-          if [ -z "$TAG" ]; then
-            echo "git_tag is required when publish_target=main"
-            exit 1
-          fi
-
-          if ! printf "%s\n" "$TAG" | grep -Eq '^cli-v[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.-]+)?$'; then
-            echo "git_tag must look like cli-vX.Y.Z, got: ${TAG}"
-            exit 1
-          fi
-
-          VERSION="${TAG#cli-v}"
-          PACKAGE_VERSION=$(node -p "require('./apps/cli/package.json').version")
-
-          if [ "$PACKAGE_VERSION" != "$VERSION" ]; then
-            echo "sdk/apps/cli/package.json version ${PACKAGE_VERSION} does not match ${TAG}"
-            exit 1
-          fi
-
-          if ! printf "%s\n" "$VERSION" | grep -Eq '^[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.-]+)?$'; then
-            echo "sdk/apps/cli/package.json has invalid version: ${VERSION}"
-            exit 1
-          fi
-
-          TAG_COMMIT=$(git rev-parse "${TAG}^{commit}")
-          HEAD_COMMIT=$(git rev-parse HEAD)
-          if [ "$TAG_COMMIT" != "$HEAD_COMMIT" ]; then
-            echo "${TAG} does not point at the checked out commit"
-            exit 1
-          fi
-
-          git fetch origin +main:refs/remotes/origin/main
-          if ! git merge-base --is-ancestor "$HEAD_COMMIT" origin/main; then
-            echo "${TAG} is not reachable from origin/main"
-            exit 1
-          fi
-
-          echo "version=${VERSION}" >> "$GITHUB_OUTPUT"
-          echo "tag=${TAG}" >> "$GITHUB_OUTPUT"
-
-      - name: Build SDK packages
-        run: bun run build:sdk
-
-      - name: Run tests
-        run: bun run test
-
-      - name: Build platform binaries
-        run: bun script/build.ts --install-native-variants --skip-sdk-build
-        working-directory: sdk/apps/cli
-
-      - name: Verify build output
-        run: |
-          VERSION="${{ steps.version.outputs.version }}"
-          EXPECTED=(
-            "@cline/cli-darwin-arm64"
-            "@cline/cli-darwin-x64"
-            "@cline/cli-linux-arm64"
-            "@cline/cli-linux-x64"
-            "@cline/cli-windows-arm64"
-            "@cline/cli-windows-x64"
-          )
-
-          for package_name in "${EXPECTED[@]}"; do
-            dir="apps/cli/dist/${package_name#@cline/}"
-            if [ ! -f "$dir/package.json" ]; then
-              echo "Missing package manifest: $dir/package.json"
-              exit 1
-            fi
-            actual_name=$(node -p "require('./$dir/package.json').name")
-            actual_version=$(node -p "require('./$dir/package.json').version")
-            if [ "$actual_name" != "$package_name" ]; then
-              echo "Expected $package_name, got $actual_name"
-              exit 1
-            fi
-            if [ "$actual_version" != "$VERSION" ]; then
-              echo "Expected $package_name@$VERSION, got $actual_version"
-              exit 1
-            fi
-            ls -lh "$dir/bin/"
-          done
-
-      - name: Publish to NPM with latest tag
-        env:
-          NPM_CONFIG_PROVENANCE: "true"
-        run: bun script/publish-npm.ts --tag latest
-        working-directory: sdk/apps/cli
-
-      - name: Get Previous CLI Tag
-        id: prev_tag
-        run: |
-          CURRENT_TAG="${{ steps.version.outputs.tag }}"
-          PREV_TAG=$(git describe --tags --abbrev=0 --match 'cli-v*' "$CURRENT_TAG^" 2>/dev/null || echo "")
-          echo "prev_tag=$PREV_TAG" >> $GITHUB_OUTPUT
-
-      - name: Get Changelog Entry
-        id: changelog
-        run: |
-          # Grab content between the first "## " header and the next one in apps/cli/CHANGELOG.md
-          CONTENT=$(awk '/^## [0-9]/{if(found) exit; found=1; next} found{print}' apps/cli/CHANGELOG.md)
-          echo "content<<EOF" >> $GITHUB_OUTPUT
-          echo "$CONTENT" >> $GITHUB_OUTPUT
-          echo "EOF" >> $GITHUB_OUTPUT
-
-      - name: Create GitHub Release
-        uses: softprops/action-gh-release@v1
-        with:
-          tag_name: ${{ steps.version.outputs.tag }}
-          name: "CLI v${{ steps.version.outputs.version }}"
-          body: |
-            ${{ steps.changelog.outputs.content }}
-            ${{ steps.prev_tag.outputs.prev_tag != '' && format('Full Changelog: https://github.com/{0}/compare/{1}...{2}', github.repository, steps.prev_tag.outputs.prev_tag, steps.version.outputs.tag) || '' }}
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-
-      - name: Summary
-        run: |
-          VERSION="${{ steps.version.outputs.version }}"
-          echo "Published cline@${VERSION} to npm with dist-tag 'latest'"
-          echo "Install with: npm install -g cline"
-
-      - name: Post release to Slack
-        uses: slackapi/slack-github-action@v3.0.1
-        with:
-          method: chat.postMessage
-          token: ${{ secrets.SLACK_RELEASE_BOT_TOKEN }}
-          payload: |
-            channel: "C0APVKGGZFC"
-            text: "Cline CLI v${{ steps.version.outputs.version }}"
-            blocks:
-              - type: "section"
-                text:
-                  type: "mrkdwn"
-                  text: "Cline CLI v${{ steps.version.outputs.version }}"
-              - type: "section"
-                text:
-                  type: "mrkdwn"
-                  text: ${{ toJSON(steps.changelog.outputs.content) }}
-              - type: "context"
-                elements:
-                  - type: "mrkdwn"
-                    text: "<https://www.npmjs.com/package/cline/v/${{ steps.version.outputs.version }}|View on npm>${{ steps.prev_tag.outputs.prev_tag != '' && format(' | Full Changelog: https://github.com/{0}/compare/{1}...{2}', github.repository, steps.prev_tag.outputs.prev_tag, steps.version.outputs.tag) || '' }}"
-
-  publish-nightly:
-    name: Publish cline nightly
-    permissions:
-      contents: read
-      id-token: write
-    if: |
-      github.repository == 'cline/cline' &&
-      github.ref == 'refs/heads/main' &&
-      (
-        github.event_name == 'schedule' ||
-        (
-          github.event_name == 'workflow_dispatch' &&
-          github.event.inputs.publish_target == 'nightly'
-        )
-      )
-    runs-on: ubuntu-latest
-
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-
-      - name: Check for recent commits
-        id: check_commits
-        env:
-          FORCE_PUBLISH: ${{ github.event_name == 'workflow_dispatch' && github.event.inputs.force_nightly_publish == 'true' }}
-        run: |
-          if [ "$FORCE_PUBLISH" = "true" ]; then
-            echo "force_nightly_publish enabled, proceeding with publish"
-            echo "skip=false" >> "$GITHUB_OUTPUT"
-            exit 0
-          fi
-
-          if [ "$(git rev-list --count HEAD --since='24 hours ago')" -eq 0 ]; then
-            echo "No commits in last 24 hours, skipping publish"
-            echo "skip=true" >> "$GITHUB_OUTPUT"
-          else
-            echo "Found recent commits, proceeding with publish"
-            echo "skip=false" >> "$GITHUB_OUTPUT"
-          fi
-
-      - name: Setup Bun
-        if: steps.check_commits.outputs.skip != 'true'
-        uses: oven-sh/setup-bun@v2
-        with:
-          bun-version: "1.3.13"
-
-      - name: Setup Node.js
-        if: steps.check_commits.outputs.skip != 'true'
-        uses: actions/setup-node@v4
-        with:
-          node-version: "24.x"
-          registry-url: "https://registry.npmjs.org"
-
-      - name: Verify publish tooling
-        if: steps.check_commits.outputs.skip != 'true'
-        run: |
-          NPM_VERSION=$(npm --version)
-          echo "npm ${NPM_VERSION}"
-          IFS=. read -r major minor patch <<EOF
-          ${NPM_VERSION}
-          EOF
-          if [ "$major" -lt 11 ] || { [ "$major" -eq 11 ] && [ "$minor" -lt 5 ]; } || { [ "$major" -eq 11 ] && [ "$minor" -eq 5 ] && [ "$patch" -lt 1 ]; }; then
-            echo "npm 11.5.1 or newer is required for trusted publishing"
-            exit 1
-          fi
-
-      - name: Install dependencies
-        if: steps.check_commits.outputs.skip != 'true'
-        run: bun install
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-
-      - name: Build SDK packages
-        if: steps.check_commits.outputs.skip != 'true'
-        run: bun run build:sdk
-
-      - name: Run tests
-        if: steps.check_commits.outputs.skip != 'true'
-        run: bun run test
-
-      - name: Generate nightly version
-        if: steps.check_commits.outputs.skip != 'true'
-        id: version
-        run: |
-          BASE_VERSION=$(node -p "require('./apps/cli/package.json').version")
-          TIMESTAMP=$(date +%s)
-          VERSION="${BASE_VERSION}-nightly.${TIMESTAMP}"
-
-          echo "Base version: ${BASE_VERSION}"
-          echo "Generated nightly version: ${VERSION}"
-          echo "base_version=${BASE_VERSION}" >> "$GITHUB_OUTPUT"
-          echo "version=${VERSION}" >> "$GITHUB_OUTPUT"
-
-      - name: Update nightly package version
-        if: steps.check_commits.outputs.skip != 'true'
-        run: |
-          VERSION="${{ steps.version.outputs.version }}"
-          node -e '
-            const fs = require("node:fs");
-            const path = "apps/cli/package.json";
-            const pkg = JSON.parse(fs.readFileSync(path, "utf8"));
-            pkg.version = process.env.VERSION;
-            fs.writeFileSync(path, `${JSON.stringify(pkg, null, "\t")}\n`);
-          '
-          cat apps/cli/package.json | grep '"version"'
-        env:
-          VERSION: ${{ steps.version.outputs.version }}
-
-      - name: Build platform binaries
-        if: steps.check_commits.outputs.skip != 'true'
-        run: bun script/build.ts --install-native-variants --skip-sdk-build
-        working-directory: sdk/apps/cli
-
-      - name: Verify build output
-        if: steps.check_commits.outputs.skip != 'true'
-        run: |
-          VERSION="${{ steps.version.outputs.version }}"
-          EXPECTED=(
-            "@cline/cli-darwin-arm64"
-            "@cline/cli-darwin-x64"
-            "@cline/cli-linux-arm64"
-            "@cline/cli-linux-x64"
-            "@cline/cli-windows-arm64"
-            "@cline/cli-windows-x64"
-          )
-
-          for package_name in "${EXPECTED[@]}"; do
-            dir="apps/cli/dist/${package_name#@cline/}"
-            if [ ! -f "$dir/package.json" ]; then
-              echo "Missing package manifest: $dir/package.json"
-              exit 1
-            fi
-            actual_name=$(node -p "require('./$dir/package.json').name")
-            actual_version=$(node -p "require('./$dir/package.json').version")
-            if [ "$actual_name" != "$package_name" ]; then
-              echo "Expected $package_name, got $actual_name"
-              exit 1
-            fi
-            if [ "$actual_version" != "$VERSION" ]; then
-              echo "Expected $package_name@$VERSION, got $actual_version"
-              exit 1
-            fi
-            ls -lh "$dir/bin/"
-          done
-
-      - name: Publish to NPM with nightly tag
-        if: steps.check_commits.outputs.skip != 'true'
-        env:
-          NPM_CONFIG_PROVENANCE: "true"
-        run: bun script/publish-npm.ts --tag nightly
-        working-directory: sdk/apps/cli
-
-      - name: Summary
-        if: steps.check_commits.outputs.skip != 'true'
-        run: |
-          VERSION="${{ steps.version.outputs.version }}"
-          echo "Published cline@${VERSION} to npm with dist-tag 'nightly'"
-          echo "Install with: npm install -g cline@nightly"

.github/workflows/publish-new-sdk-extension-nightly.yml

@@ -1,72 +0,0 @@
-name: "Publish New SDK Extension Nightly"
-
-on:
-    schedule:
-        - cron: '0 12 * * *' # 4 AM PST (UTC-8) = 12 UTC
-    workflow_dispatch:
-
-permissions:
-    contents: read
-    packages: write
-    checks: write
-    pull-requests: write
-
-env:
-    # Keep the publish source pinned to one reviewed branch instead of accepting arbitrary refs.
-    SDK_NIGHTLY_REF: dpc/sdk-migration-simpler-login
-
-jobs:
-    publish:
-        name: Publish Cline New SDK Extension Nightly
-        if: github.repository == 'cline/cline' && github.ref == 'refs/heads/main'
-        runs-on: ubuntu-latest
-        environment: PublishNightly
-
-        steps:
-            - name: Checkout trusted SDK nightly branch
-              uses: actions/checkout@v4
-              with:
-                  ref: ${{ env.SDK_NIGHTLY_REF }}
-                  lfs: true
-                  persist-credentials: false
-
-            - name: Setup Node.js
-              uses: actions/setup-node@v4
-              with:
-                  # Keep publish environment aligned with test workflow/tooling lockfile expectations.
-                  # Newer LTS (Node 24 / npm 11) can make `npm list` fail with ELSPROBLEMS during vsce packaging.
-                  node-version: 22
-
-            - name: Install root dependencies
-              run: npm ci --include=optional
-
-            - name: Install webview-ui dependencies
-              run: cd webview-ui && npm ci --include=optional
-
-            - name: Install Publishing Tools
-              run: npm install -g @vscode/vsce ovsx
-
-            - name: Verify LFS media assets are resolved
-              run: |
-                  for FILE in webview-ui/src/assets/cline_kanban_demo.mp4 webview-ui/src/assets/cline_kanban_demo.webm; do
-                    if grep -q "git-lfs.github.com/spec/v1" "$FILE"; then
-                      echo "Error: $FILE is still a Git LFS pointer in CI checkout"
-                      exit 1
-                    fi
-                  done
-
-            - name: Publish SDK nightly extension
-              env:
-                  VSCE_PAT: ${{ secrets.VSCE_PAT }}
-                  OVSX_PAT: ${{ secrets.OVSX_PAT }}
-                  TELEMETRY_SERVICE_API_KEY: ${{ secrets.TELEMETRY_SERVICE_API_KEY }}
-                  ERROR_SERVICE_API_KEY: ${{ secrets.ERROR_SERVICE_API_KEY }}
-                  CLINE_ENVIRONMENT: production
-                  # OpenTelemetry production defaults (can be overridden at runtime)
-                  OTEL_TELEMETRY_ENABLED: ${{ secrets.OTEL_TELEMETRY_ENABLED }}
-                  OTEL_LOGS_EXPORTER: otlp
-                  OTEL_METRICS_EXPORTER: otlp
-                  OTEL_EXPORTER_OTLP_PROTOCOL: ${{ secrets.OTEL_EXPORTER_OTLP_PROTOCOL }}
-                  OTEL_EXPORTER_OTLP_ENDPOINT: ${{ secrets.OTEL_EXPORTER_OTLP_ENDPOINT }}
-                  OTEL_EXPORTER_OTLP_HEADERS: ${{ secrets.OTEL_EXPORTER_OTLP_HEADERS }}
-              run: npm run publish:marketplace:nightly

.github/workflows/publish-nightly.yml

@@ -1,105 +1,77 @@
 name: "Publish Nightly Release"
 
 on:
+  schedule:
+    - cron: '0 12 * * *'  # 4 AM PST (UTC-8) = 12 UTC
   workflow_dispatch:
 
-run-name: "Publish Nightly from ${{ github.ref_name }} @ ${{ github.sha }}"
-
-# Prevent concurrent publish runs on the same branch. The nightly publish script
-# generates the extension version from a seconds-resolution timestamp, so parallel
-# runs on the same ref can collide on the same version and cause publish failures
-# or inconsistent tagging. Runs on different branches proceed independently.
-concurrency:
-  group: publish-nightly-${{ github.ref }}
-  cancel-in-progress: false
-
-permissions: {}
+permissions:
+    contents: write
+    packages: write
+    checks: write
+    pull-requests: write
 
 jobs:
-  test:
-    if: github.repository == 'cline/cline' && (github.ref == 'refs/heads/main' || github.ref == 'refs/heads/dpc/sdk-migration-simpler-login')
-    permissions:
-      contents: read
-    uses: ./.github/workflows/test.yml
+    test:
+        uses: ./.github/workflows/test.yml
 
-  publish:
-    needs: test
-    permissions:
-      contents: write
-    name: Publish Cline (Nightly) Extension
-    if: github.repository == 'cline/cline' && (github.ref == 'refs/heads/main' || github.ref == 'refs/heads/dpc/sdk-migration-simpler-login')
-    runs-on: ubuntu-latest
-    environment: PublishNightly
+    publish:
+        needs: test
+        name: Publish Cline (Nightly) Extension
+        if: github.repository == 'cline/cline'
+        runs-on: ubuntu-latest
+        environment: PublishNightly
 
-    steps:
-      - name: Checkout selected branch
-        uses: actions/checkout@v4
-        with:
-          ref: ${{ github.sha }}
-          lfs: true
-          persist-credentials: false
+        steps:
+            - uses: actions/checkout@v4
+              with:
+                  lfs: true
 
-      - name: Show build source
-        run: |
-          echo "Building ref: $GITHUB_REF"
-          echo "Building sha: $GITHUB_SHA"
-          git --no-pager log -1 --oneline
+            - name: Check for recent commits
+              run: |
+                if [ $(git rev-list --count HEAD --since="24 hours ago") -eq 0 ]; then
+                  echo "No commits in last 24 hours, exiting"
+                  exit 0
+                fi
+                echo "Found recent commits, proceeding with build"
+                
+            - name: Setup Node.js
+              uses: actions/setup-node@v4
+              with:
+                  # Keep publish environment aligned with test workflow/tooling lockfile expectations.
+                  # Newer LTS (Node 24 / npm 11) can make `npm list` fail with ELSPROBLEMS during vsce packaging.
+                  node-version: 22
 
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
-        with:
-          # Keep publish environment aligned with test workflow/tooling lockfile expectations.
-          # Newer LTS (Node 24 / npm 11) can make `npm list` fail with ELSPROBLEMS during vsce packaging.
-          node-version: 22
+            - name: Install root dependencies
+              run: npm ci --include=optional
 
-      - name: Install root dependencies
-        run: npm ci --include=optional
+            - name: Install webview-ui dependencies
+              run: cd webview-ui && npm ci --include=optional
 
-      - name: Install webview-ui dependencies
-        run: cd webview-ui && npm ci --include=optional
+            - name: Install Publishing Tools
+              run: npm install -g @vscode/vsce ovsx
 
-      - name: Install Publishing Tools
-        run: npm install -g @vscode/vsce ovsx
+            - name: Verify LFS media assets are resolved
+              run: |
+                  for FILE in webview-ui/src/assets/cline_kanban_demo.mp4 webview-ui/src/assets/cline_kanban_demo.webm; do
+                    if grep -q "git-lfs.github.com/spec/v1" "$FILE"; then
+                      echo "Error: $FILE is still a Git LFS pointer in CI checkout"
+                      exit 1
+                    fi
+                  done
 
-      - name: Verify LFS media assets are resolved
-        run: |
-          for FILE in webview-ui/src/assets/cline_kanban_demo.mp4 webview-ui/src/assets/cline_kanban_demo.webm; do
-            if grep -q "git-lfs.github.com/spec/v1" "$FILE"; then
-              echo "Error: $FILE is still a Git LFS pointer in CI checkout"
-              exit 1
-            fi
-          done
-
-      - name: Publish Nightly Extension
-        env:
-          VSCE_PAT: ${{ secrets.VSCE_PAT }}
-          OVSX_PAT: ${{ secrets.OVSX_PAT }}
-          TELEMETRY_SERVICE_API_KEY: ${{ secrets.TELEMETRY_SERVICE_API_KEY }}
-          ERROR_SERVICE_API_KEY: ${{ secrets.ERROR_SERVICE_API_KEY }}
-          CLINE_ENVIRONMENT: production
-          # OpenTelemetry production defaults (can be overridden at runtime)
-          OTEL_TELEMETRY_ENABLED: ${{ secrets.OTEL_TELEMETRY_ENABLED }}
-          OTEL_LOGS_EXPORTER: otlp
-          OTEL_METRICS_EXPORTER: otlp
-          OTEL_EXPORTER_OTLP_PROTOCOL: ${{ secrets.OTEL_EXPORTER_OTLP_PROTOCOL }}
-          OTEL_EXPORTER_OTLP_ENDPOINT: ${{ secrets.OTEL_EXPORTER_OTLP_ENDPOINT }}
-          OTEL_EXPORTER_OTLP_HEADERS: ${{ secrets.OTEL_EXPORTER_OTLP_HEADERS }}
-        run: npm run publish:marketplace:nightly
-
-      - name: Tag published commit
-        env:
-          GH_TOKEN: ${{ github.token }}
-        run: |
-          SAFE_REF=$(echo "$GITHUB_REF_NAME" | tr '/[:upper:]' '-[:lower:]' | tr -cd 'a-z0-9._-')
-          SHORT_SHA=$(git rev-parse --short=12 HEAD)
-          TIMESTAMP=$(date -u +"%Y%m%d%H%M%S")
-          TAG="nightly-${SAFE_REF}-${TIMESTAMP}-${SHORT_SHA}"
-
-          git config user.name "github-actions[bot]"
-          git config user.email "github-actions[bot]@users.noreply.github.com"
-          git tag -a "$TAG" -m "Cline Nightly published from ${GITHUB_REF_NAME} at ${GITHUB_SHA}"
-          # Use an explicit HTTPS remote with GH_TOKEN because checkout was run with
-          # persist-credentials: false, so actions/checkout did not persist a git credential helper.
-          git push "https://x-access-token:${GH_TOKEN}@github.com/${GITHUB_REPOSITORY}.git" "refs/tags/${TAG}"
-
-          echo "Tagged published commit: $TAG"
+            - name: Publish Extension as Pre-release
+              env:
+                  VSCE_PAT: ${{ secrets.VSCE_PAT }}
+                  OVSX_PAT: ${{ secrets.OVSX_PAT }}
+                  TELEMETRY_SERVICE_API_KEY: ${{ secrets.TELEMETRY_SERVICE_API_KEY }}
+                  ERROR_SERVICE_API_KEY: ${{ secrets.ERROR_SERVICE_API_KEY }}
+                  CLINE_ENVIRONMENT: production
+                  # OpenTelemetry production defaults (can be overridden at runtime)
+                  OTEL_TELEMETRY_ENABLED: ${{ secrets.OTEL_TELEMETRY_ENABLED }}
+                  OTEL_LOGS_EXPORTER: otlp
+                  OTEL_METRICS_EXPORTER: otlp
+                  OTEL_EXPORTER_OTLP_PROTOCOL: ${{ secrets.OTEL_EXPORTER_OTLP_PROTOCOL }}
+                  OTEL_EXPORTER_OTLP_ENDPOINT: ${{ secrets.OTEL_EXPORTER_OTLP_ENDPOINT }}
+                  OTEL_EXPORTER_OTLP_HEADERS: ${{ secrets.OTEL_EXPORTER_OTLP_HEADERS }}
+              run: npm run publish:marketplace:nightly

.github/workflows/publish-sdk.yaml

@@ -1,269 +0,0 @@
-name: Publish Main SDK Packages
-
-on:
-  workflow_dispatch:
-    inputs:
-      channel:
-        description: "Publish channel"
-        required: true
-        type: choice
-        options:
-          - nightly
-          - latest
-        default: nightly
-      force_publish:
-        description: "Force publish even if there are no commits in the last 24 hours"
-        required: false
-        type: boolean
-        default: false
-      confirm_publish:
-        description: 'Required when channel=latest. Type "publish" to confirm release publish.'
-        required: false
-        type: string
-  schedule:
-    # Run nightly at 2:00 AM UTC
-    - cron: "0 2 * * *"
-
-defaults:
-  run:
-    working-directory: sdk
-
-jobs:
-  test:
-    permissions:
-      contents: read
-    uses: ./.github/workflows/sdk-test.yml
-
-  publish-sdk:
-    needs: test
-    name: Publish SDK Packages
-    permissions:
-      contents: write
-      id-token: write
-    if: |
-      github.repository == 'cline/cline' &&
-      github.ref == 'refs/heads/main' &&
-      (
-        github.event_name != 'workflow_dispatch' ||
-        inputs.channel != 'latest' ||
-        (
-          inputs.confirm_publish == 'publish' &&
-          !endsWith(github.actor, '[bot]')
-        )
-      )
-    runs-on: ubuntu-latest
-
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@v4
-
-      - name: Determine publish channel
-        id: channel
-        run: |
-          # Default to nightly for scheduled runs
-          if [ "${{ github.event_name }}" = "schedule" ]; then
-            echo "channel=nightly" >> $GITHUB_OUTPUT
-          else
-            echo "channel=${{ inputs.channel }}" >> $GITHUB_OUTPUT
-          fi
-
-      - name: Check for recent commits
-        id: check_commits
-        run: |
-          CHANNEL="${{ steps.channel.outputs.channel }}"
-
-          # Always publish for latest (production) releases
-          if [ "$CHANNEL" = "latest" ]; then
-            echo "Production release requested, proceeding with publish"
-            echo "skip=false" >> $GITHUB_OUTPUT
-            exit 0
-          fi
-
-          if [ "${{ inputs.force_publish }}" = "true" ]; then
-            echo "force_publish enabled, proceeding with publish"
-            echo "skip=false" >> $GITHUB_OUTPUT
-            exit 0
-          fi
-
-          if [ "$(git rev-list --count HEAD --since="24 hours ago")" -eq 0 ]; then
-            echo "No commits in last 24 hours, skipping publish"
-            echo "skip=true" >> $GITHUB_OUTPUT
-          else
-            echo "Found recent commits, proceeding with publish"
-            echo "skip=false" >> $GITHUB_OUTPUT
-          fi
-
-      - name: Verify trusted publishing context
-        if: steps.check_commits.outputs.skip != 'true'
-        run: |
-          if [ -z "${ACTIONS_ID_TOKEN_REQUEST_TOKEN:-}" ] || [ -z "${ACTIONS_ID_TOKEN_REQUEST_URL:-}" ]; then
-            echo "GitHub OIDC request environment is unavailable. Ensure this job has id-token: write for npm trusted publishing."
-            exit 1
-          fi
-          echo "GitHub OIDC request environment is available for npm trusted publishing."
-
-      - name: Setup Bun
-        if: steps.check_commits.outputs.skip != 'true'
-        uses: oven-sh/setup-bun@v2
-        with:
-          bun-version: "1.3.13"
-
-      - name: Setup Node.js
-        if: steps.check_commits.outputs.skip != 'true'
-        uses: actions/setup-node@v4
-        with:
-          node-version: "24.x"
-          registry-url: "https://registry.npmjs.org"
-
-      - name: Verify publish tooling
-        if: steps.check_commits.outputs.skip != 'true'
-        run: |
-          NPM_VERSION=$(npm --version)
-          echo "npm ${NPM_VERSION}"
-          IFS=. read -r major minor patch <<EOF
-          ${NPM_VERSION}
-          EOF
-          if [ "$major" -lt 11 ] || { [ "$major" -eq 11 ] && [ "$minor" -lt 5 ]; } || { [ "$major" -eq 11 ] && [ "$minor" -eq 5 ] && [ "$patch" -lt 1 ]; }; then
-            echo "npm 11.5.1 or newer is required for trusted publishing"
-            exit 1
-          fi
-
-      - name: Install dependencies
-        if: steps.check_commits.outputs.skip != 'true'
-        run: bun install
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-
-      - name: Build SDK
-        if: steps.check_commits.outputs.skip != 'true'
-        run: bun run build:sdk
-
-      - name: Generate shared version
-        if: steps.check_commits.outputs.skip != 'true'
-        id: version
-        run: |
-          CHANNEL="${{ steps.channel.outputs.channel }}"
-          BASE_VERSION=$(node -p "require('./packages/llms/package.json').version")
-
-          if [ "$CHANNEL" = "nightly" ]; then
-            TIMESTAMP=$(date +%s)
-            VERSION="${BASE_VERSION}-nightly.${TIMESTAMP}"
-          else
-            VERSION="$BASE_VERSION"
-          fi
-
-          echo "Base version: $BASE_VERSION"
-          echo "Channel: $CHANNEL"
-          echo "Publish version: $VERSION"
-          echo "version=$VERSION" >> $GITHUB_OUTPUT
-
-      - name: Update all package versions and lockfile
-        if: steps.check_commits.outputs.skip != 'true'
-        run: bun scripts/version.ts "${{ steps.version.outputs.version }}"
-
-      - name: Verify publishability
-        if: steps.check_commits.outputs.skip != 'true'
-        run: bun scripts/check-publish.ts
-
-      - name: Prepare package tarball directory
-        if: steps.check_commits.outputs.skip != 'true'
-        run: mkdir -p "$RUNNER_TEMP/sdk-npm-packs"
-
-      # Pack with Bun so workspace/catalog protocols are resolved in the tarball,
-      # then publish that tarball with npm so npm trusted publishing can use GitHub OIDC.
-      # Publish sequentially in dependency order: shared → llms → agents → core → sdk
-      - name: Publish @cline/shared
-        if: steps.check_commits.outputs.skip != 'true'
-        env:
-          NPM_CONFIG_PROVENANCE: "true"
-        run: |
-          CHANNEL="${{ steps.channel.outputs.channel }}"
-          echo "Publishing @cline/shared@${{ steps.version.outputs.version }} with tag '${CHANNEL}'..."
-          cd packages/shared
-          TARBALL=$(bun pm pack --destination "$RUNNER_TEMP/sdk-npm-packs" --quiet)
-          npm publish "$RUNNER_TEMP/sdk-npm-packs/$(basename "$TARBALL")" --tag "$CHANNEL" --access public
-
-      - name: Publish @cline/llms
-        if: steps.check_commits.outputs.skip != 'true'
-        env:
-          NPM_CONFIG_PROVENANCE: "true"
-        run: |
-          CHANNEL="${{ steps.channel.outputs.channel }}"
-          echo "Publishing @cline/llms@${{ steps.version.outputs.version }} with tag '${CHANNEL}'..."
-          cd packages/llms
-          TARBALL=$(bun pm pack --destination "$RUNNER_TEMP/sdk-npm-packs" --quiet)
-          npm publish "$RUNNER_TEMP/sdk-npm-packs/$(basename "$TARBALL")" --tag "$CHANNEL" --access public
-
-      - name: Publish @cline/agents
-        if: steps.check_commits.outputs.skip != 'true'
-        env:
-          NPM_CONFIG_PROVENANCE: "true"
-        run: |
-          CHANNEL="${{ steps.channel.outputs.channel }}"
-          echo "Publishing @cline/agents@${{ steps.version.outputs.version }} with tag '${CHANNEL}'..."
-          cd packages/agents
-          TARBALL=$(bun pm pack --destination "$RUNNER_TEMP/sdk-npm-packs" --quiet)
-          npm publish "$RUNNER_TEMP/sdk-npm-packs/$(basename "$TARBALL")" --tag "$CHANNEL" --access public
-
-      - name: Publish @cline/core
-        if: steps.check_commits.outputs.skip != 'true'
-        env:
-          NPM_CONFIG_PROVENANCE: "true"
-        run: |
-          CHANNEL="${{ steps.channel.outputs.channel }}"
-          echo "Publishing @cline/core@${{ steps.version.outputs.version }} with tag '${CHANNEL}'..."
-          cd packages/core
-          TARBALL=$(bun pm pack --destination "$RUNNER_TEMP/sdk-npm-packs" --quiet)
-          npm publish "$RUNNER_TEMP/sdk-npm-packs/$(basename "$TARBALL")" --tag "$CHANNEL" --access public
-
-      - name: Publish @cline/sdk
-        if: steps.check_commits.outputs.skip != 'true'
-        env:
-          NPM_CONFIG_PROVENANCE: "true"
-        run: |
-          CHANNEL="${{ steps.channel.outputs.channel }}"
-          echo "Publishing @cline/sdk@${{ steps.version.outputs.version }} with tag '${CHANNEL}'..."
-          cd packages/sdk
-          TARBALL=$(bun pm pack --destination "$RUNNER_TEMP/sdk-npm-packs" --quiet)
-          npm publish "$RUNNER_TEMP/sdk-npm-packs/$(basename "$TARBALL")" --tag "$CHANNEL" --access public
-
-      - name: Create package tags for production publish
-        if: steps.check_commits.outputs.skip != 'true' && steps.channel.outputs.channel == 'latest'
-        run: |
-          VERSION="${{ steps.version.outputs.version }}"
-
-          git config user.name "github-actions[bot]"
-          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
-
-          for PKG in shared llms agents core sdk; do
-            TAG="sdk/${PKG}/v${VERSION}"
-            if git rev-parse -q --verify "refs/tags/${TAG}" >/dev/null; then
-              echo "Tag already exists locally: ${TAG}"
-            else
-              git tag -a "${TAG}" -m "@cline/${PKG}@${VERSION}"
-              echo "Created tag: ${TAG}"
-            fi
-
-            # Ensure remote has the tag; this is idempotent if tag already exists remotely.
-            git push origin "refs/tags/${TAG}"
-          done
-
-      - name: Summary
-        if: steps.check_commits.outputs.skip != 'true'
-        run: |
-          VERSION="${{ steps.version.outputs.version }}"
-          CHANNEL="${{ steps.channel.outputs.channel }}"
-          echo "Published SDK packages with tag '${CHANNEL}':"
-          echo "  - @cline/shared@${VERSION}"
-          echo "  - @cline/llms@${VERSION}"
-          echo "  - @cline/agents@${VERSION}"
-          echo "  - @cline/core@${VERSION}"
-          echo "  - @cline/sdk@${VERSION}"
-          if [ "$CHANNEL" = "latest" ]; then
-            echo "Created git tags:"
-            echo "  - sdk/shared/v${VERSION}"
-            echo "  - sdk/llms/v${VERSION}"
-            echo "  - sdk/agents/v${VERSION}"
-            echo "  - sdk/core/v${VERSION}"
-            echo "  - sdk/sdk/v${VERSION}"
-          fi

.github/workflows/publish.yml

@@ -47,10 +47,9 @@ jobs:
 
             - name: Resolve Release Tag
               id: resolve_tag
-              env:
-                  TAG: ${{ github.event.inputs.tag }}
-                  AUTO_CREATE: ${{ github.event.inputs.auto_create_tag_from_main }}
               run: |
+                  TAG="${{ github.event.inputs.tag }}"
+                  AUTO_CREATE="${{ github.event.inputs.auto_create_tag_from_main }}"
                   TESTED_SHA="${{ github.sha }}"
                   WORKFLOW_REF="${{ github.ref }}"
 
@@ -158,19 +157,11 @@ jobs:
                   OTEL_EXPORTER_OTLP_PROTOCOL: ${{ secrets.OTEL_EXPORTER_OTLP_PROTOCOL }}
                   OTEL_EXPORTER_OTLP_ENDPOINT: ${{ secrets.OTEL_EXPORTER_OTLP_ENDPOINT }}
                   OTEL_EXPORTER_OTLP_HEADERS: ${{ secrets.OTEL_EXPORTER_OTLP_HEADERS }}
-                  RELEASE_TYPE: ${{ github.event.inputs.release-type }}
               run: |
-                  # Swap README.marketplace.md into README.md so both the GitHub
-                  # release artifact (vsce package below) and the marketplace
-                  # publish (npm run publish:marketplace below, which swaps
-                  # internally as an idempotent no-op) ship the same README.
-                  node scripts/marketplace-readme.mjs swap-in
-                  trap 'node scripts/marketplace-readme.mjs restore' EXIT
-
                   # Required to generate the .vsix
                   vsce package  --allow-package-secrets sendgrid --out "cline-${{ steps.get_version.outputs.version }}.vsix"
 
-                  if [ "$RELEASE_TYPE" = "pre-release" ]; then
+                  if [ "${{ github.event.inputs.release-type }}" = "pre-release" ]; then
                     npm run publish:marketplace:prerelease
                     echo "Successfully published pre-release version ${{ steps.get_version.outputs.version }} to VS Code Marketplace and Open VSX Registry"
                   else

.github/workflows/sdk-test.yml

@@ -1,112 +0,0 @@
-name: SDK Tests
-
-on:
-    push:
-        branches:
-            - main
-        paths:
-            - "sdk/**"
-            - ".github/workflows/sdk-test.yml"
-    workflow_dispatch:
-    pull_request:
-        branches:
-            - main
-        paths:
-            - "sdk/**"
-            - ".github/workflows/sdk-test.yml"
-    workflow_call:
-
-permissions:
-    contents: read
-
-defaults:
-    run:
-        working-directory: sdk
-
-jobs:
-    quality-checks:
-        runs-on: ubuntu-latest
-        name: Quality Checks
-        steps:
-            - name: Checkout code
-              uses: actions/checkout@v4
-
-            - name: Setup Bun
-              uses: oven-sh/setup-bun@v2
-              with:
-                  bun-version: "1.3.13"
-
-            - name: Install dependencies
-              run: bun install
-              env:
-                  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-
-            - name: Typecheck
-              run: |
-                  bun run build:sdk
-                  bun run -F @cline/cli build
-                  bun run types
-
-            - name: Lint & Format
-              run: bun run lint
-
-    test:
-        needs: quality-checks
-        strategy:
-            fail-fast: false
-            matrix:
-                include:
-                    - os: ubuntu-latest
-                      node-version: "24.x"
-                    - os: windows-latest
-                      node-version: "24.x"
-        runs-on: ${{ matrix.os }}
-        name: Test (${{ matrix.os }}, Node ${{ matrix.node-version }})
-        steps:
-            - name: Checkout code
-              uses: actions/checkout@v4
-
-            - name: Setup Bun
-              uses: oven-sh/setup-bun@v2
-              with:
-                  bun-version: "1.3.13"
-
-            - name: Setup Node.js
-              uses: actions/setup-node@v4
-              with:
-                  node-version: ${{ matrix.node-version }}
-
-            - name: Install dependencies
-              run: bun install
-              env:
-                  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-
-            - name: Build SDK
-              id: build_sdk_step
-              run: bun run build:sdk
-
-            - name: Build CLI
-              id: build_cli_step
-              if: ${{ !cancelled() && steps.build_sdk_step.outcome == 'success' }}
-              run: bun -F @cline/cli build
-
-            - name: Run Tests
-              if: ${{ !cancelled() && steps.build_sdk_step.outcome == 'success' && steps.build_cli_step.outcome == 'success' && matrix.os != 'windows-latest' }}
-              run: bun run test
-
-            - name: Run SDK Tests (Windows)
-              if: ${{ !cancelled() && steps.build_sdk_step.outcome == 'success' && steps.build_cli_step.outcome == 'success' && matrix.os == 'windows-latest' }}
-              run: bun -F './packages/**' test
-
-            - name: Smoke test SQLite under Node
-              if: ${{ !cancelled() && steps.build_sdk_step.outcome == 'success' && matrix.os != 'windows-latest' }}
-              timeout-minutes: 10
-              run: bun scripts/ci-node-smoke.ts
-
-            - name: Run TUI e2e tests
-              if: ${{ !cancelled() && steps.build_sdk_step.outcome == 'success' && steps.build_cli_step.outcome == 'success' && matrix.os == 'ubuntu-latest' && matrix.node-version == '24.x' }}
-              run: bun -F @cline/cli test:e2e:cli:tui
-
-            - name: Verify packages are publishable
-              if: ${{ !cancelled() && steps.build_sdk_step.outcome == 'success' && steps.build_cli_step.outcome == 'success' && matrix.os == 'ubuntu-latest' && matrix.node-version == '24.x' }}
-              run: bun scripts/check-publish.ts

.github/workflows/test.yml

@@ -13,6 +13,8 @@ on:
 # Set default permissions for all jobs
 permissions:
     contents: read # Needed to check out code
+    checks: write # Needed to report test results
+    pull-requests: write # Needed to add comments/annotations to PRs
 
 jobs:
     quality-checks:
@@ -44,8 +46,6 @@ jobs:
 
     test:
         needs: quality-checks
-        env:
-            VSCODE_TEST_VERSION: 1.103.0
         strategy:
             fail-fast: false
             matrix:
@@ -81,13 +81,6 @@ jobs:
               run: |
                   npm config set script-shell "C:\\Program Files\\Git\\bin\\bash.exe"
 
-            - name: Cache VS Code test runtime
-              if: runner.os == 'Windows'
-              uses: actions/cache@v4
-              with:
-                  path: .vscode-test
-                  key: vscode-test-runtime-${{ runner.os }}-${{ env.VSCODE_TEST_VERSION }}
-
             # Build the extension and tests (without redundant checks)
             - name: Build Tests and Extension
               id: build_step
@@ -113,21 +106,7 @@ jobs:
             - name: Extension Integration Tests - Non-Linux
               id: integration_tests_non_linux
               if: ${{ !cancelled() && steps.build_step.outcome == 'success' && runner.os != 'Linux' }}
-              run: |
-                  for attempt in 1 2 3; do
-                    echo "Running extension integration tests (attempt ${attempt}/3)"
-                    if npm run test:integration; then
-                      exit 0
-                    fi
-
-                    if [ "$attempt" -eq 3 ]; then
-                      echo "Extension integration tests failed after 3 attempts"
-                      exit 1
-                    fi
-
-                    echo "Extension integration tests failed; retrying after short delay"
-                    sleep 5
-                  done
+              run: npm run test:integration
 
             - name: Webview Tests with Coverage
               id: webview_tests

.gitignore

@@ -56,7 +56,3 @@ evals/smoke-tests/results/
 secrets.json
 tui-traces
 tests/**/cache
-
-# Backup created by scripts/marketplace-readme.mjs while publishing.
-# Should never be committed: only exists if a publish aborts mid-swap.
-.README.github.bak

.vscode-test.mjs

@@ -1,6 +1,5 @@
 import { defineConfig } from "@vscode/test-cli"
 import path from "path"
-const vscodeTestVersion = process.env.VSCODE_TEST_VERSION ?? "stable"
 
 export default defineConfig({
 	files: "{out/**/*.test.js,src/**/*.test.js,!src/test/e2e/**/*.test.js,!out/src/test/e2e/**/*.test.js}",
@@ -13,7 +12,7 @@ export default defineConfig({
 		require: ["./test-setup.js"],
 	},
 	workspaceFolder: "test-workspace",
-	version: vscodeTestVersion,
+	version: "stable",
 	extensionDevelopmentPath: path.resolve("./"),
 	launchArgs: ["--disable-extensions"],
 })

.vscodeignore

@@ -25,15 +25,6 @@ eslint-rules/**
 # cli
 cli/**
 
-# sdk (separate monorepo with its own build/release pipeline)
-sdk/**
-
-# Source-of-truth for the marketplace README (the .vsix only ever sees the
-# README.md that scripts/marketplace-readme.mjs swaps into place). The backup
-# only exists if a publish aborts mid-swap; neither should ship in the .vsix.
-README.marketplace.md
-.README.github.bak
-
 # Custom
 **/demo.gif
 .nvmrc

CHANGELOG.md

@@ -1,104 +1,5 @@
 # Changelog
 
-## [3.83.0]
-
-### Fixed
-
-- Show a clear "Searching..." state in the @-mention file picker
-- Improve @-mention file search performance
-- Allow `write_to_file` to create or overwrite files with empty content.
-- Fix validation failures for MCP servers that require an object.
-- Enable OpenRouter prompt cache control for Qwen models.
-- Update Axios and SAP Connectivity dependencies
-
-### Changed
-
-- Use the VS Code-specific `README.marketplace.md` when packaging and publishing the VS Code extension
-- Add telemetry to @-mention search to help diagnose local, remote, and multi-root workspace search behavior.
-
-## [3.82.0]
-
-### Added
-
-- Restore VS Code foreground terminal support and settings.
-- Add latest OpenAI, SAP AI Core, and Z AI models.
-
-### Fixed
-
-- Fix hook template JSON escaping.
-- Improve ripgrep file search error handling.
-
-### Changed
-
-- Remove hardcoded model lists from docs.
-
-## [3.81.0]
-
-### Added
-
-- Add GPT-5.5 model support for OpenAI Codex subscription users.
-
-### Fixed
-
-- Remove hardcoded "What’s New" fallback items in webview; only remote-configured welcome banners are shown.
-
-### Changed
-
-- Improve cline-core memory diagnostics used by the extension runtime:
-  - enable near-heap-limit heap snapshots
-  - add periodic memory usage logging
-  - log discovered heap snapshots on abnormal exits for easier OOM debugging
-
-## [3.80.0]
-
-### Added
-
-- Wire up remote `globalSkills` from enterprise remote config with full UI, toggle support, and system prompt integration — enterprise-managed skills now appear under a dedicated "Enterprise Skills" section and support `alwaysEnabled` enforcement
-- Onboarding flow now uses dynamically fetched recommended models instead of a hardcoded list, with a fallback to the welcome view on failure
-- Add dedicated "Quota Exceeded" error message in the chat error UI when Cline account spend caps are hit
-
-### Fixed
-
-- Fix OOM crashes during long conversations by setting `--max-old-space-size=8192` for the cline-core Node.js process (was defaulting to ~2 GB)
-- Show detailed error information in the chat error row instead of a generic caught error message
-- Update `axios` to 1.15.0 across all packages
-
-### Changed
-
-- Remove foreground terminal mode — all task command execution now defaults to background mode, removing the VS Code integrated terminal dependency and related settings UI
-- Remove old hardcoded announcement banners
-
-## [3.79.0]
-
-### Added
-
-- Add Claude Opus 4.7 model support
-- Add Azure Blob Storage as a storage provider
-- Add `globalSkills` to remote config
-- Inline value reuse in user-level remote-config discovery
-
-### Fixed
-
-- Fix cache reflection for Cline and Vercel API handlers
-- Fix stuck `command_output` ask when terminal command ends unexpectedly
-- Add `use_subagents` to system prompt for GLM, Hermes, and XS models
-- Fix action injection security risk
-
-### Changed
-
-- Remove deprecated evals tool
-
-## [3.78.0]
-
-### Added
-
-- Add a dedicated "Spend Limit Reached" error UI when spend caps are hit
-- Docs updates
-
-### Fixed
-
-- Show actual `read_file` line ranges in chat UI
-
 ## [3.77.0]
 
 ### Added

CONTRIBUTING.md

@@ -42,14 +42,15 @@ We also welcome contributions to our [documentation](https://github.com/cline/cl
     ```bash
     code cline
     ```
-3. Install [bun](https://bun.com)
-4. Install the necessary dependencies for the extension and webview-gui:
+3. Install the necessary dependencies for the extension and webview-gui:
     ```bash
     npm run install:all
-    cd sdk && bun run build && cd ..
     ```
-5. Generate Protocol Buffer files (required before first build):
-6. Launch by pressing `F5` (or `Run`->`Start Debugging`) to open a new VSCode window with the extension loaded. (You may need to install the [esbuild problem matchers extension](https://marketplace.visualstudio.com/items?itemName=connor4312.esbuild-problem-matchers) if you run into issues building the project.)
+4. Generate Protocol Buffer files (required before first build):
+    ```bash
+    npm run protos
+    ```
+5. Launch by pressing `F5` (or `Run`->`Start Debugging`) to open a new VSCode window with the extension loaded. (You may need to install the [esbuild problem matchers extension](https://marketplace.visualstudio.com/items?itemName=connor4312.esbuild-problem-matchers) if you run into issues building the project.)
 
 
 

README.marketplace.md

@@ -1,146 +0,0 @@
-<div align="center"><sub>
-English | <a href="https://github.com/cline/cline/blob/main/locales/es/README.md" target="_blank">Español</a> | <a href="https://github.com/cline/cline/blob/main/locales/de/README.md" target="_blank">Deutsch</a> | <a href="https://github.com/cline/cline/blob/main/locales/ja/README.md" target="_blank">日本語</a> | <a href="https://github.com/cline/cline/blob/main/locales/zh-cn/README.md" target="_blank">简体中文</a> | <a href="https://github.com/cline/cline/blob/main/locales/zh-tw/README.md" target="_blank">繁體中文</a> | <a href="https://github.com/cline/cline/blob/main/locales/ko/README.md" target="_blank">한국어</a>
-</sub></div>
-
-# Cline
-<div align="center">
-<table>
-<tbody>
-<td align="center">
-<a href="https://marketplace.visualstudio.com/items?itemName=saoudrizwan.claude-dev" target="_blank"><strong>Download on VS Marketplace</strong></a>
-</td>
-<td align="center">
-<a href="https://discord.gg/cline" target="_blank"><strong>Discord</strong></a>
-</td>
-<td align="center">
-<a href="https://www.reddit.com/r/cline/" target="_blank"><strong>r/cline</strong></a>
-</td>
-<td align="center">
-<a href="https://github.com/cline/cline/discussions/categories/feature-requests?discussions_q=is%3Aopen+category%3A%22Feature+Requests%22+sort%3Atop" target="_blank"><strong>Feature Requests</strong></a>
-</td>
-<td align="center">
-<a href="https://docs.cline.bot/getting-started/for-new-coders" target="_blank"><strong>Getting Started</strong></a>
-</td>
-</tbody>
-</table>
-</div>
-
-Meet Cline, an AI assistant that can use your **CLI** a**N**d **E**ditor.
-
-Thanks to [Claude Sonnet's agentic coding capabilities](https://www.anthropic.com/claude/sonnet), Cline can handle complex software development tasks step-by-step. With tools that let him create & edit files, explore large projects, use the browser, and execute terminal commands (after you grant permission), he can assist you in ways that go beyond code completion or tech support. Cline can even use the Model Context Protocol (MCP) to create new tools and extend his own capabilities. While autonomous AI scripts traditionally run in sandboxed environments, this extension provides a human-in-the-loop GUI to approve every file change and terminal command, providing a safe and accessible way to explore the potential of agentic AI.
-
-1. Enter your task and add images to convert mockups into functional apps or fix bugs with screenshots.
-2. Cline starts by analyzing your file structure & source code ASTs, running regex searches, and reading relevant files to get up to speed in existing projects. By carefully managing what information is added to context, Cline can provide valuable assistance even for large, complex projects without overwhelming the context window.
-3. Once Cline has the information he needs, he can:
-    - Create and edit files + monitor linter/compiler errors along the way, letting him proactively fix issues like missing imports and syntax errors on his own.
-    - Execute commands directly in your terminal and monitor their output as he works, letting him e.g., react to dev server issues after editing a file.
-    - For web development tasks, Cline can launch the site in a headless browser, click, type, scroll, and capture screenshots + console logs, allowing him to fix runtime errors and visual bugs.
-4. When a task is completed, Cline will present the result to you with a terminal command like `open -a "Google Chrome" index.html`, which you run with a click of a button.
-
-> [!TIP]
-> Follow [this guide](https://docs.cline.bot/features/customization/opening-cline-in-sidebar) to open Cline on the right side of your editor. This lets you use Cline side-by-side with your file explorer, and see how he changes your workspace more clearly.
-
----
-
-<img align="right" width="340" src="https://github.com/user-attachments/assets/3cf21e04-7ce9-4d22-a7b9-ba2c595e88a4">
-
-### Use any API and Model
-
-Cline supports API providers like OpenRouter, Anthropic, OpenAI, Google Gemini, AWS Bedrock, Azure, GCP Vertex, Cerebras and Groq. You can also configure any OpenAI compatible API, or use a local model through LM Studio/Ollama. If you're using OpenRouter, the extension fetches their latest model list, allowing you to use the newest models as soon as they're available.
-
-The extension also keeps track of total tokens and API usage cost for the entire task loop and individual requests, keeping you informed of spend every step of the way.
-
-<!-- Transparent pixel to create line break after floating image -->
-
-<img width="2000" height="0" src="https://github.com/user-attachments/assets/ee14e6f7-20b8-4391-9091-8e8e25561929"><br>
-
-<img align="left" width="370" src="https://github.com/user-attachments/assets/81be79a8-1fdb-4028-9129-5fe055e01e76">
-
-### Run Commands in Terminal
-
-Thanks to the new [shell integration updates in VSCode v1.93](https://code.visualstudio.com/updates/v1_93#_terminal-shell-integration-api), Cline can execute commands directly in your terminal and receive the output. This allows him to perform a wide range of tasks, from installing packages and running build scripts to deploying applications, managing databases, and executing tests, all while adapting to your dev environment & toolchain to get the job done right.
-
-For long running processes like dev servers, use the "Proceed While Running" button to let Cline continue in the task while the command runs in the background. As Cline works he’ll be notified of any new terminal output along the way, letting him react to issues that may come up, such as compile-time errors when editing files.
-
-<!-- Transparent pixel to create line break after floating image -->
-
-<img width="2000" height="0" src="https://github.com/user-attachments/assets/ee14e6f7-20b8-4391-9091-8e8e25561929"><br>
-
-<img align="right" width="400" src="https://github.com/user-attachments/assets/c5977833-d9b8-491e-90f9-05f9cd38c588">
-
-### Create and Edit Files
-
-Cline can create and edit files directly in your editor, presenting you a diff view of the changes. You can edit or revert Cline's changes directly in the diff view editor, or provide feedback in chat until you're satisfied with the result. Cline also monitors linter/compiler errors (missing imports, syntax errors, etc.) so he can fix issues that come up along the way on his own.
-
-All changes made by Cline are recorded in your file's Timeline, providing an easy way to track and revert modifications if needed.
-
-<!-- Transparent pixel to create line break after floating image -->
-
-<img width="2000" height="0" src="https://github.com/user-attachments/assets/ee14e6f7-20b8-4391-9091-8e8e25561929"><br>
-
-<img align="left" width="370" src="https://github.com/user-attachments/assets/bc2e85ba-dfeb-4fe6-9942-7cfc4703cbe5">
-
-### Use the Browser
-
-With Claude Sonnet's new [Computer Use](https://www.anthropic.com/news/3-5-models-and-computer-use) capability, Cline can launch a browser, click elements, type text, and scroll, capturing screenshots and console logs at each step. This allows for interactive debugging, end-to-end testing, and even general web use! This gives him autonomy to fixing visual bugs and runtime issues without you needing to handhold and copy-pasting error logs yourself.
-
-Try asking Cline to "test the app", and watch as he runs a command like `npm run dev`, launches your locally running dev server in a browser, and performs a series of tests to confirm that everything works. [See a demo here.](https://x.com/sdrzn/status/1850880547825823989)
-
-<!-- Transparent pixel to create line break after floating image -->
-
-<img width="2000" height="0" src="https://github.com/user-attachments/assets/ee14e6f7-20b8-4391-9091-8e8e25561929"><br>
-
-<img align="right" width="350" src="https://github.com/user-attachments/assets/ac0efa14-5c1f-4c26-a42d-9d7c56f5fadd">
-
-### "add a tool that..."
-
-Thanks to the [Model Context Protocol](https://github.com/modelcontextprotocol), Cline can extend his capabilities through custom tools. While you can use [community-made servers](https://github.com/modelcontextprotocol/servers), Cline can instead create and install tools tailored to your specific workflow. Just ask Cline to "add a tool" and he will handle everything, from creating a new MCP server to installing it into the extension. These custom tools then become part of Cline's toolkit, ready to use in future tasks.
-
--   "add a tool that fetches Jira tickets": Retrieve ticket ACs and put Cline to work
--   "add a tool that manages AWS EC2s": Check server metrics and scale instances up or down
--   "add a tool that pulls the latest PagerDuty incidents": Fetch details and ask Cline to fix bugs
-
-<!-- Transparent pixel to create line break after floating image -->
-
-<img width="2000" height="0" src="https://github.com/user-attachments/assets/ee14e6f7-20b8-4391-9091-8e8e25561929"><br>
-
-<img align="left" width="360" src="https://github.com/user-attachments/assets/7fdf41e6-281a-4b4b-ac19-020b838b6970">
-
-### Add Context
-
-**`@url`:** Paste in a URL for the extension to fetch and convert to markdown, useful when you want to give Cline the latest docs
-
-**`@problems`:** Add workspace errors and warnings ('Problems' panel) for Cline to fix
-
-**`@file`:** Adds a file's contents so you don't have to waste API requests approving read file (+ type to search files)
-
-**`@folder`:** Adds folder's files all at once to speed up your workflow even more
-
-<!-- Transparent pixel to create line break after floating image -->
-
-<img width="2000" height="0" src="https://github.com/user-attachments/assets/ee14e6f7-20b8-4391-9091-8e8e25561929"><br>
-
-<img align="right" width="350" src="https://github.com/user-attachments/assets/140c8606-d3bf-41b9-9a1f-4dbf0d4c90cb">
-
-### Checkpoints: Compare and Restore
-
-As Cline works through a task, the extension takes a snapshot of your workspace at each step. You can use the 'Compare' button to see a diff between the snapshot and your current workspace, and the 'Restore' button to roll back to that point.
-
-For example, when working with a local web server, you can use 'Restore Workspace Only' to quickly test different versions of your app, then use 'Restore Task and Workspace' when you find the version you want to continue building from. This lets you safely explore different approaches without losing progress.
-
-<!-- Transparent pixel to create line break after floating image -->
-
-<img width="2000" height="0" src="https://github.com/user-attachments/assets/ee14e6f7-20b8-4391-9091-8e8e25561929"><br>
-
-## Contributing
-
-To contribute to the project, start with our [Contributing Guide](CONTRIBUTING.md) to learn the basics. You can also join our [Discord](https://discord.gg/cline) to chat with other contributors in the `#contributors` channel. If you're looking for full-time work, check out our open positions on our [careers page](https://cline.bot/join-us)!
-
-## Enterprise
-
-Get the same Cline experience with enterprise-grade controls: SSO (SAML/OIDC), global policies and configuration, observability with audit trails, private networking (VPC/private link), and self-hosted or on-prem deployments, and enterprise support. Learn more at our [enterprise page](https://cline.bot/enterprise) or [talk to us](https://cline.bot/contact-sales).
-
-
-## License
-
-[Apache 2.0 © 2026 Cline Bot Inc.](./LICENSE)

README.md

@@ -1,20 +1,18 @@
-<p align="center">
-  <img src="assets/icons/icon.png" width="80" alt="Cline" />
-</p>
+<div align="center"><sub>
+English | <a href="https://github.com/cline/cline/blob/main/locales/es/README.md" target="_blank">Español</a> | <a href="https://github.com/cline/cline/blob/main/locales/de/README.md" target="_blank">Deutsch</a> | <a href="https://github.com/cline/cline/blob/main/locales/ja/README.md" target="_blank">日本語</a> | <a href="https://github.com/cline/cline/blob/main/locales/zh-cn/README.md" target="_blank">简体中文</a> | <a href="https://github.com/cline/cline/blob/main/locales/zh-tw/README.md" target="_blank">繁體中文</a> | <a href="https://github.com/cline/cline/blob/main/locales/ko/README.md" target="_blank">한국어</a>
+</sub></div>
 
-<h1 align="center">Cline</h1>
+# Cline
 
 <p align="center">
-The open source coding agent in your IDE and terminal.
+  <img src="https://media.githubusercontent.com/media/cline/cline/main/assets/docs/demo.gif" width="100%" />
 </p>
 
-<div align="center">
-
 <div align="center">
 <table>
 <tbody>
 <td align="center">
-<a href="https://docs.cline.bot" target="_blank"><strong>Docs</strong></a>
+<a href="https://marketplace.visualstudio.com/items?itemName=saoudrizwan.claude-dev" target="_blank"><strong>Download on VS Marketplace</strong></a>
 </td>
 <td align="center">
 <a href="https://discord.gg/cline" target="_blank"><strong>Discord</strong></a>
@@ -26,209 +24,127 @@ The open source coding agent in your IDE and terminal.
 <a href="https://github.com/cline/cline/discussions/categories/feature-requests?discussions_q=is%3Aopen+category%3A%22Feature+Requests%22+sort%3Atop" target="_blank"><strong>Feature Requests</strong></a>
 </td>
 <td align="center">
-<a href="https://cline.bot/join-us" target="_blank"><strong>Join us!</strong></a>
+<a href="https://docs.cline.bot/getting-started/for-new-coders" target="_blank"><strong>Getting Started</strong></a>
 </td>
 </tbody>
 </table>
 </div>
 
-</div>
+Meet Cline, an AI assistant that can use your **CLI** a**N**d **E**ditor.
 
-<br>
+Thanks to [Claude Sonnet's agentic coding capabilities](https://www.anthropic.com/claude/sonnet), Cline can handle complex software development tasks step-by-step. With tools that let him create & edit files, explore large projects, use the browser, and execute terminal commands (after you grant permission), he can assist you in ways that go beyond code completion or tech support. Cline can even use the Model Context Protocol (MCP) to create new tools and extend his own capabilities. While autonomous AI scripts traditionally run in sandboxed environments, this extension provides a human-in-the-loop GUI to approve every file change and terminal command, providing a safe and accessible way to explore the potential of agentic AI.
 
-<div align="center">
-<table>
-<tr>
-<td align="center" width="50%">
+1. Enter your task and add images to convert mockups into functional apps or fix bugs with screenshots.
+2. Cline starts by analyzing your file structure & source code ASTs, running regex searches, and reading relevant files to get up to speed in existing projects. By carefully managing what information is added to context, Cline can provide valuable assistance even for large, complex projects without overwhelming the context window.
+3. Once Cline has the information he needs, he can:
+    - Create and edit files + monitor linter/compiler errors along the way, letting him proactively fix issues like missing imports and syntax errors on his own.
+    - Execute commands directly in your terminal and monitor their output as he works, letting him e.g., react to dev server issues after editing a file.
+    - For web development tasks, Cline can launch the site in a headless browser, click, type, scroll, and capture screenshots + console logs, allowing him to fix runtime errors and visual bugs.
+4. When a task is completed, Cline will present the result to you with a terminal command like `open -a "Google Chrome" index.html`, which you run with a click of a button.
 
-### CLI
-
-Run Cline in your terminal.
-Interactive chat or fully headless
-for CI/CD and scripting.
-
-```
-npm i -g cline
-```
-
-<a href="./sdk/apps/cli/README.md">Learn more</a>
-<br><br>
-
-</td>
-<td align="center" width="50%">
-
-### Kanban
-
-Run many agents in parallel from a
-web-based task board. Each card gets its own
-worktree, auto-commit, and dependency chains.
-
-```
-npm i -g kanban
-```
-
-<a href="https://github.com/cline/kanban">Learn more</a>
-<br><br>
-
-</td>
-</tr>
-<tr>
-<td align="center" width="50%">
-
-### VS Code Extension
-
-AI coding assistant in your editor.
-Create files, run commands, browse the web,
-and use tools with human-in-the-loop approval.
-
-<a href="https://marketplace.visualstudio.com/items?itemName=saoudrizwan.claude-dev">Install from VS Marketplace</a>
-<br><br>
-
-</td>
-<td align="center" width="50%">
-
-### JetBrains Plugin
-
-The same Cline experience in IntelliJ IDEA,
-PyCharm, WebStorm, GoLand, and the rest of
-the JetBrains family.
-
-<a href="https://plugins.jetbrains.com/plugin/28247-cline">Install from JetBrains Marketplace</a>
-<br><br>
-
-</td>
-</tr>
-</table>
-</div>
-
-<div align="center">
-<table>
-<tr>
-<td align="center">
-
-### SDK
-
-Build your own AI agents and integrations powered by the same engine that runs the CLI, Kanban, VS Code extension, and JetBrains plugin. Custom tools, multi-agent teams, connectors, scheduled automations, and more.
-
-```
-npm install @cline/sdk
-```
-
-<a href="https://docs.cline.bot/cline-sdk/overview">Documentation</a>
-<br><br>
-
-</td>
-</tr>
-</table>
-</div>
+> [!TIP]
+> Follow [this guide](https://docs.cline.bot/features/customization/opening-cline-in-sidebar) to open Cline on the right side of your editor. This lets you use Cline side-by-side with your file explorer, and see how he changes your workspace more clearly.
 
 ---
 
-## Index
+<img align="right" width="340" src="https://github.com/user-attachments/assets/3cf21e04-7ce9-4d22-a7b9-ba2c595e88a4">
 
-| Product | Description | Location |
-|---------|------------|--------------|
-| **SDK** | Node.js programmatic agent API and extension exports. | [`sdk/`](https://github.com/cline/cline/tree/main/sdk) |
-| **CLI** | Terminal UI, headless mode, shell commands, and CLI-specific flows. | [`sdk/apps/cli/`](https://github.com/cline/cline/tree/main/sdk/apps/cli) |
-| **VS Code Extension** | The Marketplace extension and extension host integration. | [`/`](https://github.com/cline/cline/tree/main) (WIP migrating) |
-| **JetBrains Plugin** | JetBrains-hosted client that talks to the shared agent core. | Currently we are not open-sourcing JetBrains plugins |
-| **Kanban** | Web-based multi-agent task board. | [`cline/kanban`](https://github.com/cline/kanban) |
-| **Docs site** | Public documentation pages. | [`docs/`](https://docs.cline.bot/) |
+### Use any API and Model
 
-## Edits Code Across Your Project
+Cline supports API providers like OpenRouter, Anthropic, OpenAI, Google Gemini, AWS Bedrock, Azure, GCP Vertex, Cerebras and Groq. You can also configure any OpenAI compatible API, or use a local model through LM Studio/Ollama. If you're using OpenRouter, the extension fetches their latest model list, allowing you to use the newest models as soon as they're available.
 
-Cline reads your project structure, understands the relationships between files, and makes coordinated changes across your codebase. It monitors linter and compiler errors as it works, fixing issues like missing imports, type mismatches, and syntax errors before you even see them. In VS Code and JetBrains, every edit shows up as a diff you can review, modify, or revert. All changes are tracked with checkpoints, so you can easily undo the agent's work.
+The extension also keeps track of total tokens and API usage cost for the entire task loop and individual requests, keeping you informed of spend every step of the way.
 
-## Runs Bash Commands
+<!-- Transparent pixel to create line break after floating image -->
 
-Cline executes commands directly in your terminal and watches the output in real time. Install packages, run build scripts, execute tests, deploy applications, manage databases. For long-running processes like dev servers, Cline continues working in the background and reacts to new output as it appears, catching compile errors, test failures, and server crashes as they happen.
+<img width="2000" height="0" src="https://github.com/user-attachments/assets/ee14e6f7-20b8-4391-9091-8e8e25561929"><br>
 
-## Plan and Act
+<img align="left" width="370" src="https://github.com/user-attachments/assets/81be79a8-1fdb-4028-9129-5fe055e01e76">
 
-Toggle between Plan mode and Act mode. In Plan mode, Cline explores your codebase, asks clarifying questions, and lays out a strategy. Once you're aligned, switch to Act mode and Cline executes the plan. Every file edit and terminal command requires your approval, so you stay in control of what actually changes. Or toggle auto-approve and let Cline run autonomously.
+### Run Commands in Terminal
 
-## Rules and Skills
+Thanks to the new [shell integration updates in VSCode v1.93](https://code.visualstudio.com/updates/v1_93#_terminal-shell-integration-api), Cline can execute commands directly in your terminal and receive the output. This allows him to perform a wide range of tasks, from installing packages and running build scripts to deploying applications, managing databases, and executing tests, all while adapting to your dev environment & toolchain to get the job done right.
 
-Define project-specific rules in `.clinerules` files that guide how Cline works in your codebase: coding standards, architecture conventions, deployment procedures, testing requirements. Rules are picked up automatically by the CLI, VS Code extension, and JetBrains plugin. Use skills to let the model load specific rules when needed. 
+For long running processes like dev servers, use the "Proceed While Running" button to let Cline continue in the task while the command runs in the background. As Cline works he’ll be notified of any new terminal output along the way, letting him react to issues that may come up, such as compile-time errors when editing files.
 
-## Works With Every Model
+<!-- Transparent pixel to create line break after floating image -->
 
-Cline is not locked to a single AI provider. Use whichever model fits your workflow:
+<img width="2000" height="0" src="https://github.com/user-attachments/assets/ee14e6f7-20b8-4391-9091-8e8e25561929"><br>
 
-| Provider | Models |
-|----------|--------|
-| Anthropic | Claude Opus, Sonnet, Haiku |
-| OpenAI | GPT series model |
-| Google | Gemini series model |
-| OpenRouter | 200+ models from any provider |
-| Vercel AI Gateway | Models through Vercel AI Gateway |
-| AWS Bedrock | Claude, Llama, and more |
-| Azure / GCP Vertex | All hosted models |
-| Cerebras / Groq | Fast inference models |
-| Ollama / LM Studio | Run local models on your machine |
-| Any OpenAI-compatible API | Self-hosted or third-party endpoints |
+<img align="right" width="400" src="https://github.com/user-attachments/assets/c5977833-d9b8-491e-90f9-05f9cd38c588">
 
-## Extend With Plugins or MCP Servers
+### Create and Edit Files
 
-Extend Cline's capabilities with plugins. Using the SDK, register tools and lifecycle hooks programmatically through the plugin system for logging, auditing, policy enforcement, or adding domain-specific capabilities. Simple plugin example below.
+Cline can create and edit files directly in your editor, presenting you a diff view of the changes. You can edit or revert Cline's changes directly in the diff view editor, or provide feedback in chat until you're satisfied with the result. Cline also monitors linter/compiler errors (missing imports, syntax errors, etc.) so he can fix issues that come up along the way on his own.
 
-```typescript
-import { Agent, createTool } from "@cline/sdk"
+All changes made by Cline are recorded in your file's Timeline, providing an easy way to track and revert modifications if needed.
 
-const deployTool = createTool({
-  name: "deploy",
-  description: "Deploy the current branch to staging.",
-  inputSchema: { type: "object", properties: { env: { type: "string" } }, required: ["env"] },
-  execute: async (input) => {
-    // your deployment logic
-  },
-})
+<!-- Transparent pixel to create line break after floating image -->
 
-const agent = new Agent({ tools: [deployTool], /* ... */ })
-```
-...or use [MCP servers](https://github.com/modelcontextprotocol) to connect to databases, query APIs, manage cloud infrastructure, and interact with external systems. Use [community-built servers](https://github.com/modelcontextprotocol/servers) or ask Cline to create custom tools on the fly. In the CLI, manage servers with `cline mcp`.
+<img width="2000" height="0" src="https://github.com/user-attachments/assets/ee14e6f7-20b8-4391-9091-8e8e25561929"><br>
 
-## Multi-Agent Teams
+<img align="left" width="370" src="https://github.com/user-attachments/assets/bc2e85ba-dfeb-4fe6-9942-7cfc4703cbe5">
 
-Coordinate multiple agents working together on complex tasks. A coordinator agent breaks the work into subtasks and delegates to specialist agents, each with their own tools and context. Team state persists across sessions so you can pick up where you left off.
+### Use the Browser
 
-```bash
-cline --team-name auth-sprint "Plan and implement user authentication with tests"
-```
+With Claude Sonnet's new [Computer Use](https://www.anthropic.com/news/3-5-models-and-computer-use) capability, Cline can launch a browser, click elements, type text, and scroll, capturing screenshots and console logs at each step. This allows for interactive debugging, end-to-end testing, and even general web use! This gives him autonomy to fixing visual bugs and runtime issues without you needing to handhold and copy-pasting error logs yourself.
 
-## Scheduled Agents
+Try asking Cline to "test the app", and watch as he runs a command like `npm run dev`, launches your locally running dev server in a browser, and performs a series of tests to confirm that everything works. [See a demo here.](https://x.com/sdrzn/status/1850880547825823989)
 
-Run agents on cron schedules for recurring automations. Daily PR summaries, weekly dependency checks, codebase health reports. Schedules persist across restarts and run independently of any terminal session.
+<!-- Transparent pixel to create line break after floating image -->
 
-```bash
-cline schedule create "PR summary" \
-  --cron "0 9 * * MON-FRI" \
-  --prompt "List all open PRs and their review status" \
-  --workspace /path/to/repo
-```
+<img width="2000" height="0" src="https://github.com/user-attachments/assets/ee14e6f7-20b8-4391-9091-8e8e25561929"><br>
 
-## Connect to Slack, Telegram, Discord, and More
+<img align="right" width="350" src="https://github.com/user-attachments/assets/ac0efa14-5c1f-4c26-a42d-9d7c56f5fadd">
 
-Chat with your agent from any messaging platform: Telegram, Slack, Discord, Google Chat, WhatsApp, and Linear. Each conversation thread maps to an agent session with full context. Set up access control to restrict who can interact with your agent.
+### "add a tool that..."
 
-```bash
-cline connect telegram -m my_bot -k $BOT_TOKEN
-cline connect slack --token $SLACK_TOKEN --signing-secret $SECRET --base-url $URL
-```
+Thanks to the [Model Context Protocol](https://github.com/modelcontextprotocol), Cline can extend his capabilities through custom tools. While you can use [community-made servers](https://github.com/modelcontextprotocol/servers), Cline can instead create and install tools tailored to your specific workflow. Just ask Cline to "add a tool" and he will handle everything, from creating a new MCP server to installing it into the extension. These custom tools then become part of Cline's toolkit, ready to use in future tasks.
 
-## Headless CLI for CI/CD
+-   "add a tool that fetches Jira tickets": Retrieve ticket ACs and put Cline to work
+-   "add a tool that manages AWS EC2s": Check server metrics and scale instances up or down
+-   "add a tool that pulls the latest PagerDuty incidents": Fetch details and ask Cline to fix bugs
 
-Run Cline with zero interaction for scripting and automation. Pipe input, get JSON output, chain commands, integrate into CI/CD pipelines.
+<!-- Transparent pixel to create line break after floating image -->
 
-```bash
-cline "Run tests and fix any failures"
-git diff origin/main | cline  "Review these changes for issues"
-cline --json "List all TODO comments" | jq -r 'select(.type == "agent_event" and .event.text) | .event.text'
-```
+<img width="2000" height="0" src="https://github.com/user-attachments/assets/ee14e6f7-20b8-4391-9091-8e8e25561929"><br>
+
+<img align="left" width="360" src="https://github.com/user-attachments/assets/7fdf41e6-281a-4b4b-ac19-020b838b6970">
+
+### Add Context
+
+**`@url`:** Paste in a URL for the extension to fetch and convert to markdown, useful when you want to give Cline the latest docs
+
+**`@problems`:** Add workspace errors and warnings ('Problems' panel) for Cline to fix
+
+**`@file`:** Adds a file's contents so you don't have to waste API requests approving read file (+ type to search files)
+
+**`@folder`:** Adds folder's files all at once to speed up your workflow even more
+
+<!-- Transparent pixel to create line break after floating image -->
+
+<img width="2000" height="0" src="https://github.com/user-attachments/assets/ee14e6f7-20b8-4391-9091-8e8e25561929"><br>
+
+<img align="right" width="350" src="https://github.com/user-attachments/assets/140c8606-d3bf-41b9-9a1f-4dbf0d4c90cb">
+
+### Checkpoints: Compare and Restore
+
+As Cline works through a task, the extension takes a snapshot of your workspace at each step. You can use the 'Compare' button to see a diff between the snapshot and your current workspace, and the 'Restore' button to roll back to that point.
+
+For example, when working with a local web server, you can use 'Restore Workspace Only' to quickly test different versions of your app, then use 'Restore Task and Workspace' when you find the version you want to continue building from. This lets you safely explore different approaches without losing progress.
+
+<!-- Transparent pixel to create line break after floating image -->
+
+<img width="2000" height="0" src="https://github.com/user-attachments/assets/ee14e6f7-20b8-4391-9091-8e8e25561929"><br>
 
 ## Contributing
 
-Start with the [Contributing Guide](CONTRIBUTING.md). Join our [Discord](https://discord.gg/cline) and head to the `#contributors` channel to connect with other contributors. Check our [careers page](https://cline.bot/join-us) for full-time roles.
+To contribute to the project, start with our [Contributing Guide](CONTRIBUTING.md) to learn the basics. You can also join our [Discord](https://discord.gg/cline) to chat with other contributors in the `#contributors` channel. If you're looking for full-time work, check out our open positions on our [careers page](https://cline.bot/join-us)!
+
+## Enterprise
+
+Get the same Cline experience with enterprise-grade controls: SSO (SAML/OIDC), global policies and configuration, observability with audit trails, private networking (VPC/private link), and self-hosted or on-prem deployments, and enterprise support. Learn more at our [enterprise page](https://cline.bot/enterprise) or [talk to us](https://cline.bot/contact-sales).
+
 
 ## License
 

SECURITY.md

@@ -8,7 +8,9 @@ We actively patch only the most recent minor release of Cline. Older versions re
 
 We appreciate your efforts to responsibly disclose your findings and will make every effort to acknowledge your contributions.
 
-To report a security issue, please submit your report through our [Bugcrowd Vulnerability Disclosure Program](https://bugcrowd.com/engagements/clinebot-vdp-ess). Bugcrowd will manage communication and triage on our behalf.
+To report a security issue, please use the GitHub Security Advisory ["Report a Vulnerability"](https://github.com/cline/cline/security/advisories/new) tab.
+
+The team will send a response indicating the next steps in handling your report. After the initial reply, the security team will keep you informed of the progress towards a fix and full announcement, and may ask for additional information or guidance.
 
 When reporting, please include:
 
@@ -16,10 +18,10 @@ When reporting, please include:
 - Steps to reproduce or a proof of concept
 - Any logs, stack traces, or screenshots that might help us understand the problem
 
-Please keep the details private until a resolution has been reached.
+We acknowledge reports within 48 hours and aim to release a fix or mitigation within 30 days. While we work on a resolution, please keep the details private.
 
 ## Escalation
 
-If you are unable to submit through Bugcrowd, you may send an email to security@cline.bot.
+If you do not receive an acknowledgement of your report within 5 business days, you may send an email to security@cline.bot.
 
 Thank you for helping us keep Cline users safe.

cli/CHANGELOG.md

@@ -1,74 +1,5 @@
 # cline
 
-## [2.18.0]
-
-### Added
-
-- Restore foreground terminal support and settings.
-- Add latest OpenAI, SAP AI Core, and Z AI models.
-
-### Fixed
-
-- Fix hook template JSON escaping.
-- Improve ripgrep file search error handling.
-
-### Changed
-
-- Remove hardcoded model lists from docs.
-
-## [2.17.0]
-
-### Added
-
-- Add GPT-5.5 model support for OpenAI Codex subscription users.
-
-### Changed
-
-- Improve `cline-core` runtime memory diagnostics used by CLI:
-  - enable near-heap-limit heap snapshots
-  - add periodic memory usage logging
-  - log discovered heap snapshots on abnormal exits for easier OOM debugging
-
-## [2.16.0]
-
-### Added
-
-- Wire up remote `globalSkills` from enterprise remote config with full toggle support and system prompt integration — enterprise-managed skills now support `alwaysEnabled` enforcement
-- Add dedicated "Quota Exceeded" error message when Cline account spend caps are hit
-
-### Fixed
-
-- Fix OOM crashes during long conversations by setting `--max-old-space-size=8192` for the cline-core Node.js process (was defaulting to ~2 GB)
-- Show detailed error information instead of a generic caught error message
-- Update `axios` to 1.15.0 across all packages
-
-### Changed
-
-- Remove dead ACP terminal setter stubs as part of foreground terminal mode removal
-
-## [2.15.0]
-
-### Added
-
-- Add Claude Opus 4.7 model support
-- Inline value reuse in user-level remote-config discovery
-- Add `globalSkills` to remote config
-
-### Fixed
-
-- Stabilize Windows CI test path handling
-
-## [2.14.0]
-
-### Added
-
-- Simplify unified `cline update` flow for `cline` and `kanban`
-- Docs updates
-
-### Fixed
-
-- Update Kanban migration view copy
-
 ## [2.12.0]
 
 ### Added

cli/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "cline",
-	"version": "2.18.0",
+	"version": "2.13.0",
 	"description": "Autonomous coding agent CLI - capable of creating/editing files, running commands, using the browser, and more",
 	"main": "dist/lib.mjs",
 	"types": "dist/lib.d.ts",

cli/src/acp/ACPHostBridgeClientProvider.ts

@@ -369,12 +369,6 @@ class ACPWorkspaceServiceClient implements WorkspaceServiceClientInterface {
 		Logger.debug("[ACPWorkspaceServiceClient] openFolder called (stub)", { path: request.path })
 		return proto.host.OpenFolderResponse.create({ success: true })
 	}
-
-	async searchWorkspaceItems(
-		_request: proto.host.SearchWorkspaceItemsRequest,
-	): Promise<proto.host.SearchWorkspaceItemsResponse> {
-		throw new Error("searchWorkspaceItems is not implemented on the ACP host")
-	}
 }
 
 /**

cli/src/components/ChatView.test.tsx

@@ -183,7 +183,6 @@ vi.mock("@shared/getApiMetrics", () => ({
 
 vi.mock("child_process", () => ({
 	exec: vi.fn(),
-	execFile: vi.fn(),
 	execSync: vi.fn(() => "main"),
 }))
 

cli/src/components/KanbanMigrationView.test.tsx

@@ -8,11 +8,11 @@ describe("KanbanMigrationView", () => {
 		const onSelect = vi.fn()
 		const { lastFrame } = render(createElement(KanbanMigrationView, { isRawModeSupported: true, onSelect }))
 
-		expect(lastFrame()).toContain("Introducing Cline Kanban!")
+		expect(lastFrame()).toContain("Cline is moving out of the terminal. Introducing Cline Kanban.")
 		expect(lastFrame()).toContain("Open the new experience")
 		expect(lastFrame()).toContain("Launch Cline Kanban and start there by default.")
 		expect(lastFrame()).toContain("cline --tui")
-		expect(lastFrame()).toContain("You can always run cline --tui for the terminal experience.")
+		expect(lastFrame()).toContain("Close and rerun with cline --tui if you want the old CLI.")
 		expect(lastFrame()).toContain("Exit")
 	})
 

cli/src/components/KanbanMigrationView.tsx

@@ -30,7 +30,7 @@ const InternalKanbanMigrationView: React.FC<Pick<KanbanMigrationViewProps, "onSe
 			},
 			{
 				label: "Exit",
-				description: "You can always run cline --tui for the terminal experience.",
+				description: "Close and rerun with cline --tui if you want the old CLI.",
 				value: "exit",
 			},
 		],
@@ -60,7 +60,7 @@ const InternalKanbanMigrationView: React.FC<Pick<KanbanMigrationViewProps, "onSe
 			<StaticRobotFrame />
 			<Text> </Text>
 			<Text bold color="white">
-				Introducing Cline Kanban!
+				Cline is moving out of the terminal. Introducing Cline Kanban.
 			</Text>
 			<Text color="gray">A board for orchestrating coding agents across worktrees, right from your browser.</Text>
 			<Text> </Text>

cli/src/components/SkillsPanelContent.test.tsx

@@ -38,46 +38,6 @@ import { SkillsPanelContent } from "./SkillsPanelContent"
 // Helper to wait for async state updates
 const delay = (ms = 60) => new Promise((resolve) => setTimeout(resolve, ms))
 
-type WaitForConditionOptions = {
-	timeoutMs?: number
-	intervalMs?: number
-	errorMessage: string
-}
-
-const waitForCondition = async (
-	condition: () => boolean,
-	{ timeoutMs = 1000, intervalMs = 25, errorMessage }: WaitForConditionOptions,
-) => {
-	const start = Date.now()
-	while (Date.now() - start < timeoutMs) {
-		if (condition()) {
-			return
-		}
-		await delay(intervalMs)
-	}
-	throw new Error(errorMessage)
-}
-
-const waitForFrameToInclude = async (lastFrame: () => string | undefined, text: string) =>
-	waitForCondition(() => (lastFrame() || "").includes(text), {
-		errorMessage: `Expected frame to include: ${text}`,
-	})
-
-const waitForFrameToExclude = async (lastFrame: () => string | undefined, text: string) =>
-	waitForCondition(() => !(lastFrame() || "").includes(text), {
-		errorMessage: `Expected frame to exclude: ${text}`,
-	})
-
-const waitForMockToBeCalled = async (mockFn: { mock: { calls: unknown[] } }) =>
-	waitForCondition(() => mockFn.mock.calls.length > 0, {
-		errorMessage: "Expected mock to be called",
-	})
-
-const waitForSkillsPanelReady = async (lastFrame: () => string | undefined, expectedText: string) => {
-	await waitForFrameToExclude(lastFrame, "Loading skills...")
-	await waitForFrameToInclude(lastFrame, expectedText)
-}
-
 describe("SkillsPanelContent", () => {
 	const mockController = {} as any
 	const mockOnClose = vi.fn()
@@ -104,11 +64,11 @@ describe("SkillsPanelContent", () => {
 				localSkills: [],
 			})
 
-			const { stdin, lastFrame } = render(<SkillsPanelContent {...defaultProps} />)
-			await waitForSkillsPanelReady(lastFrame, "No skills installed.")
+			const { stdin } = render(<SkillsPanelContent {...defaultProps} />)
+			await delay()
 
 			stdin.write("\x1B") // Escape
-			await waitForMockToBeCalled(mockOnClose)
+			await delay()
 
 			expect(mockOnClose).toHaveBeenCalled()
 		})
@@ -119,11 +79,11 @@ describe("SkillsPanelContent", () => {
 				localSkills: [],
 			})
 
-			const { stdin, lastFrame } = render(<SkillsPanelContent {...defaultProps} />)
-			await waitForSkillsPanelReady(lastFrame, "test-skill")
+			const { stdin } = render(<SkillsPanelContent {...defaultProps} />)
+			await delay()
 
 			stdin.write("\r") // Enter
-			await waitForMockToBeCalled(mockOnUseSkill)
+			await delay()
 
 			expect(mockOnUseSkill).toHaveBeenCalledWith("/test/path/SKILL.md")
 		})
@@ -134,11 +94,11 @@ describe("SkillsPanelContent", () => {
 				localSkills: [],
 			})
 
-			const { stdin, lastFrame } = render(<SkillsPanelContent {...defaultProps} />)
-			await waitForSkillsPanelReady(lastFrame, "test-skill")
+			const { stdin } = render(<SkillsPanelContent {...defaultProps} />)
+			await delay()
 
 			stdin.write(" ") // Space
-			await waitForMockToBeCalled(mockToggleSkill)
+			await delay()
 
 			expect(mockToggleSkill).toHaveBeenCalledWith(
 				mockController,
@@ -156,17 +116,17 @@ describe("SkillsPanelContent", () => {
 				localSkills: [],
 			})
 
-			const { stdin, lastFrame } = render(<SkillsPanelContent {...defaultProps} />)
-			await waitForSkillsPanelReady(lastFrame, "skill")
+			const { stdin } = render(<SkillsPanelContent {...defaultProps} />)
+			await delay()
 
 			// Navigate down to marketplace (past the one skill)
 			// Use vim-style navigation here because it's more deterministic in the
 			// full suite than raw arrow escape sequences on Windows.
 			stdin.write("j")
-			await waitForFrameToInclude(lastFrame, "❯ Browse more skills at https://skills.sh/")
+			await delay()
 
 			stdin.write("\r") // Enter
-			await waitForMockToBeCalled(mockExec)
+			await delay()
 
 			// Should have called exec with open command
 			expect(mockExec).toHaveBeenCalled()
@@ -183,16 +143,16 @@ describe("SkillsPanelContent", () => {
 				localSkills: [],
 			})
 
-			const { stdin, lastFrame } = render(<SkillsPanelContent {...defaultProps} />)
-			await waitForSkillsPanelReady(lastFrame, "skill-1")
+			const { stdin } = render(<SkillsPanelContent {...defaultProps} />)
+			await delay()
 
 			// Navigate down
 			stdin.write("\x1B[B") // Down arrow
-			await waitForFrameToInclude(lastFrame, "❯ ● skill-2")
+			await delay()
 
 			// Press Enter - should use second skill
 			stdin.write("\r")
-			await waitForMockToBeCalled(mockOnUseSkill)
+			await delay()
 
 			expect(mockOnUseSkill).toHaveBeenCalledWith("/path2")
 		})
@@ -206,16 +166,16 @@ describe("SkillsPanelContent", () => {
 				localSkills: [],
 			})
 
-			const { stdin, lastFrame } = render(<SkillsPanelContent {...defaultProps} />)
-			await waitForSkillsPanelReady(lastFrame, "skill-1")
+			const { stdin } = render(<SkillsPanelContent {...defaultProps} />)
+			await delay()
 
 			// Navigate down with j
 			stdin.write("j")
-			await waitForFrameToInclude(lastFrame, "❯ ● skill-2")
+			await delay()
 
 			// Press Enter - should use second skill
 			stdin.write("\r")
-			await waitForMockToBeCalled(mockOnUseSkill)
+			await delay()
 
 			expect(mockOnUseSkill).toHaveBeenCalledWith("/path2")
 		})
@@ -228,11 +188,10 @@ describe("SkillsPanelContent", () => {
 			mockToggleSkill.mockRejectedValueOnce(new Error("toggle failed"))
 
 			const { stdin, lastFrame } = render(<SkillsPanelContent {...defaultProps} />)
-			await waitForSkillsPanelReady(lastFrame, "test-skill")
+			await delay()
 
 			stdin.write(" ") // Space to toggle
-			await waitForMockToBeCalled(mockToggleSkill)
-			await waitForFrameToInclude(lastFrame, "● test-skill")
+			await delay(100)
 
 			// toggleSkill was called with enabled: false (toggled from true)
 			expect(mockToggleSkill).toHaveBeenCalledWith(mockController, expect.objectContaining({ enabled: false }))
@@ -247,15 +206,15 @@ describe("SkillsPanelContent", () => {
 				localSkills: [],
 			})
 
-			const { stdin, lastFrame } = render(<SkillsPanelContent {...defaultProps} />)
-			await waitForSkillsPanelReady(lastFrame, "only-skill")
+			const { stdin } = render(<SkillsPanelContent {...defaultProps} />)
+			await delay()
 
 			// Navigate up from first item (should wrap to last - marketplace)
 			stdin.write("\x1B[A") // Up arrow
-			await waitForFrameToInclude(lastFrame, "❯ Browse more skills at https://skills.sh/")
+			await delay()
 
 			stdin.write("\r") // Enter
-			await waitForMockToBeCalled(mockExec)
+			await delay()
 
 			// Should have opened marketplace (wrapped to last item)
 			expect(mockExec).toHaveBeenCalled()
@@ -264,9 +223,8 @@ describe("SkillsPanelContent", () => {
 
 	describe("skill loading", () => {
 		it("should call refreshSkills on mount", async () => {
-			const { lastFrame } = render(<SkillsPanelContent {...defaultProps} />)
-			await waitForMockToBeCalled(mockRefreshSkills)
-			await waitForFrameToExclude(lastFrame, "Loading skills...")
+			render(<SkillsPanelContent {...defaultProps} />)
+			await delay()
 
 			expect(mockRefreshSkills).toHaveBeenCalled()
 		})

cli/src/components/SkillsPanelContent.tsx

@@ -6,7 +6,7 @@
 import { exec } from "node:child_process"
 import os from "node:os"
 import { Box, Text, useInput } from "ink"
-import React, { useCallback, useEffect, useMemo, useRef, useState } from "react"
+import React, { useCallback, useEffect, useMemo, useState } from "react"
 import type { Controller } from "@/core/controller"
 import { refreshSkills } from "@/core/controller/file/refreshSkills"
 import { toggleSkill } from "@/core/controller/file/toggleSkill"
@@ -38,14 +38,6 @@ export const SkillsPanelContent: React.FC<SkillsPanelContentProps> = ({ controll
 	const [localSkills, setLocalSkills] = useState<SkillInfo[]>([])
 	const [selectedIndex, setSelectedIndex] = useState(0)
 	const [isLoading, setIsLoading] = useState(true)
-	const inputStateRef = useRef({
-		isLoading: true,
-		selectedIndex: 0,
-		skillEntries: [] as Array<{ skill: SkillInfo; isGlobal: boolean }>,
-	})
-	const handleToggleRef = useRef<() => Promise<void>>(async () => {})
-	const handleUseRef = useRef<() => void>(() => {})
-	const openMarketplaceRef = useRef<() => void>(() => {})
 
 	// Load skills on mount
 	useEffect(() => {
@@ -66,12 +58,8 @@ export const SkillsPanelContent: React.FC<SkillsPanelContentProps> = ({ controll
 	// Build flat list of skills with source info (global first, then local, alphabetical within each)
 	const skillEntries = useMemo(() => {
 		const entries: { skill: SkillInfo; isGlobal: boolean }[] = []
-		globalSkills.forEach((skill) => {
-			entries.push({ skill, isGlobal: true })
-		})
-		localSkills.forEach((skill) => {
-			entries.push({ skill, isGlobal: false })
-		})
+		globalSkills.forEach((skill) => entries.push({ skill, isGlobal: true }))
+		localSkills.forEach((skill) => entries.push({ skill, isGlobal: false }))
 		return entries.sort((a, b) => {
 			if (a.isGlobal !== b.isGlobal) return a.isGlobal ? -1 : 1
 			return a.skill.name.localeCompare(b.skill.name)
@@ -129,14 +117,6 @@ export const SkillsPanelContent: React.FC<SkillsPanelContentProps> = ({ controll
 			}
 		})
 	}, [])
-	handleToggleRef.current = handleToggle
-	handleUseRef.current = handleUse
-	openMarketplaceRef.current = openMarketplace
-	inputStateRef.current = {
-		isLoading,
-		selectedIndex,
-		skillEntries,
-	}
 
 	// Total items = skills + 1 for marketplace link
 	const totalItems = skillEntries.length + 1
@@ -152,14 +132,6 @@ export const SkillsPanelContent: React.FC<SkillsPanelContentProps> = ({ controll
 				return
 			}
 
-			const { isLoading, selectedIndex, skillEntries } = inputStateRef.current
-			if (isLoading) {
-				return
-			}
-
-			const totalItems = skillEntries.length + 1
-			const isMarketplaceSelected = selectedIndex === skillEntries.length
-
 			// Navigation
 			if (key.upArrow || input === "k") {
 				setSelectedIndex((i) => (i > 0 ? i - 1 : totalItems - 1))
@@ -173,14 +145,14 @@ export const SkillsPanelContent: React.FC<SkillsPanelContentProps> = ({ controll
 			// Actions
 			if (isEnterKey(input, key)) {
 				if (isMarketplaceSelected) {
-					openMarketplaceRef.current()
+					openMarketplace()
 				} else {
-					handleUseRef.current()
+					handleUse()
 				}
 				return
 			}
 			if (input === " " && !isMarketplaceSelected) {
-				void handleToggleRef.current()
+				handleToggle()
 				return
 			}
 		},
@@ -276,7 +248,7 @@ const SkillRow: React.FC<{ skill: SkillInfo; isSelected: boolean }> = ({ skill,
 			{skill.description && (
 				<Box marginLeft={4}>
 					<Text color="gray">
-						{skill.description.length > 60 ? `${skill.description.slice(0, 57)}...` : skill.description}
+						{skill.description.length > 60 ? skill.description.slice(0, 57) + "..." : skill.description}
 					</Text>
 				</Box>
 			)}

cli/src/controllers/index.ts

@@ -296,12 +296,6 @@ export class CliWorkspaceServiceClient implements WorkspaceServiceClientInterfac
 		printInfo(`📂 Opening folder: ${path}`)
 		return proto.host.OpenFolderResponse.create({ success: true })
 	}
-
-	async searchWorkspaceItems(
-		_request: proto.host.SearchWorkspaceItemsRequest,
-	): Promise<proto.host.SearchWorkspaceItemsResponse> {
-		throw new Error("searchWorkspaceItems is not implemented on the CLI host")
-	}
 }
 
 /**

docs/api/authentication.mdx

@@ -69,7 +69,7 @@ cline auth
 cline auth -p cline -k "YOUR_API_KEY" -m anthropic/claude-sonnet-4-6
 ```
 
-See the [CLI Reference](/cli/cli-reference#cline-auth) for all auth options.
+See the [CLI Reference](/cline-cli/cli-reference#cline-auth) for all auth options.
 
 ## Security Best Practices
 

docs/api/models.mdx

@@ -21,7 +21,32 @@ For example:
 
 Pass this string as the `model` parameter in your [Chat Completions](/api/chat-completions) request.
 
-Example:
+## Popular Models
+
+| Model ID | Provider | Context Window | Reasoning | Best For |
+|----------|----------|---------------|-----------|----------|
+| `anthropic/claude-sonnet-4-6` | Anthropic | 200K | Yes | General coding, analysis, complex tasks |
+| `anthropic/claude-sonnet-4-5` | Anthropic | 200K | Yes | Balanced performance and cost |
+| `openai/gpt-4o` | OpenAI | 128K | No | Multimodal tasks, fast responses |
+| `google/gemini-2.5-pro` | Google | 1M | Yes | Very long context, document analysis |
+| `deepseek/deepseek-chat` | DeepSeek | 64K | No | Cost-effective coding tasks |
+| `x-ai/grok-3` | xAI | 128K | Yes | Reasoning-heavy tasks |
+
+<Note>
+  Model availability and pricing change over time. Check [app.cline.bot](https://app.cline.bot) for the latest catalog.
+</Note>
+
+## Free Models
+
+These models are available at no cost. They are a good starting point for experimentation and lightweight tasks:
+
+| Model ID | Provider | Context Window |
+|----------|----------|---------------|
+| `minimax/minimax-m2.5` | MiniMax | 1M |
+| `kwaipilot/kat-coder-pro` | Kwaipilot | 32K |
+| `z-ai/glm-5` | Z-AI | 128K |
+
+Free models have the same API interface as paid models. Just use their model ID:
 
 ```bash
 curl -X POST https://api.cline.bot/api/v1/chat/completions \
@@ -54,7 +79,7 @@ Models with reasoning support include most Claude, Gemini 2.5, and Grok 3 models
 | Multi-modal (text + images) | `openai/gpt-4o` or `anthropic/claude-sonnet-4-6` |
 | Complex reasoning | Any model with reasoning support |
 
-For setup and account flow details, see the [Cline provider guide](/getting-started/cline-provider).
+For a deeper comparison of model capabilities and pricing, see the [Model Selection Guide](/core-features/model-selection-guide).
 
 ## Image Support
 
@@ -83,7 +108,7 @@ Not all models support images. Check the model's `supportsImages` capability bef
   <Card title="Chat Completions" icon="message" href="/api/chat-completions">
     Use these models in your API requests.
   </Card>
-  <Card title="Cline provider" icon="scale-balanced" href="/getting-started/cline-provider">
-    Fastest setup path with built-in authentication and billing.
+  <Card title="Model Selection Guide" icon="scale-balanced" href="/core-features/model-selection-guide">
+    In-depth comparison for choosing the right model.
   </Card>
 </CardGroup>

docs/api/reference.mdx

@@ -0,0 +1,257 @@
+---
+title: "Cline API Reference"
+sidebarTitle: "API Reference"
+description: "Reference for the Cline Chat Completions API, an OpenAI-compatible endpoint for programmatic access."
+---
+
+The Cline API provides an OpenAI-compatible Chat Completions endpoint. You can use it from the Cline extension, the CLI, or any HTTP client that speaks the OpenAI format.
+
+## Base URL
+
+```
+https://api.cline.bot/api/v1
+```
+
+## Authentication
+
+All requests require a Bearer token in the `Authorization` header. You can use either:
+
+- **API key** created at [app.cline.bot](https://app.cline.bot) (Settings > API Keys)
+- **Account auth token** (used automatically by the Cline extension and CLI when you sign in)
+
+```bash
+Authorization: Bearer YOUR_API_KEY
+```
+
+### Getting an API Key
+
+<Steps>
+  <Step title="Go to app.cline.bot">
+    Open [app.cline.bot](https://app.cline.bot) and sign in.
+  </Step>
+  <Step title="Open Settings > API Keys">
+    Navigate to **Settings**, then **API Keys**.
+  </Step>
+  <Step title="Create and copy your key">
+    Create a new key and copy it. Store it securely. You will not be able to see it again.
+  </Step>
+</Steps>
+
+## Chat Completions
+
+Create a chat completion with streaming support. This endpoint follows the [OpenAI Chat Completions](https://platform.openai.com/docs/api-reference/chat/create) format.
+
+### Request
+
+```
+POST /chat/completions
+```
+
+**Headers:**
+
+| Header | Required | Description |
+|--------|----------|-------------|
+| `Authorization` | Yes | `Bearer YOUR_API_KEY` |
+| `Content-Type` | Yes | `application/json` |
+| `HTTP-Referer` | No | Your application URL |
+| `X-Title` | No | Your application name |
+
+**Body parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `model` | string | Yes | Model ID in `provider/model` format (e.g., `anthropic/claude-sonnet-4-6`) |
+| `messages` | array | Yes | Array of message objects with `role` and `content` |
+| `stream` | boolean | No | Enable SSE streaming (default: `true`) |
+| `tools` | array | No | Tool definitions in OpenAI function calling format |
+| `temperature` | number | No | Sampling temperature |
+
+### Example Request
+
+```bash
+curl -X POST https://api.cline.bot/api/v1/chat/completions \
+  -H "Authorization: Bearer YOUR_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "anthropic/claude-sonnet-4-6",
+    "messages": [
+      {"role": "system", "content": "You are a helpful assistant."},
+      {"role": "user", "content": "Explain what a context window is in 2 sentences."}
+    ],
+    "stream": true
+  }'
+```
+
+### Response (Streaming)
+
+When `stream: true`, the response is a series of [Server-Sent Events](https://developer.mozilla.org/en-US/docs/Web/API/Server-Sent_Events). Each event contains a JSON chunk:
+
+```json
+data: {"id":"gen-abc123","choices":[{"delta":{"content":"A context"},"index":0}],"model":"anthropic/claude-sonnet-4-6"}
+
+data: {"id":"gen-abc123","choices":[{"delta":{"content":" window is"},"index":0}],"model":"anthropic/claude-sonnet-4-6"}
+
+data: [DONE]
+```
+
+The final chunk includes a `usage` object with token counts and cost:
+
+```json
+{
+  "usage": {
+    "prompt_tokens": 25,
+    "completion_tokens": 42,
+    "prompt_tokens_details": {
+      "cached_tokens": 0
+    },
+    "cost": 0.000315
+  }
+}
+```
+
+### Response (Non-Streaming)
+
+When `stream: false`, the response is a single JSON object:
+
+```json
+{
+  "id": "gen-abc123",
+  "model": "anthropic/claude-sonnet-4-6",
+  "choices": [
+    {
+      "message": {
+        "role": "assistant",
+        "content": "A context window is the maximum amount of text..."
+      },
+      "finish_reason": "stop",
+      "index": 0
+    }
+  ],
+  "usage": {
+    "prompt_tokens": 25,
+    "completion_tokens": 42
+  }
+}
+```
+
+## Models
+
+Model IDs use the `provider/model-name` format, the same format used by [OpenRouter](https://openrouter.ai). Some examples:
+
+| Model ID | Description |
+|----------|-------------|
+| `anthropic/claude-sonnet-4-6` | Claude Sonnet 4.6 |
+| `anthropic/claude-sonnet-4-5` | Claude Sonnet 4.5 |
+| `google/gemini-2.5-pro` | Gemini 2.5 Pro |
+| `openai/gpt-4o` | GPT-4o |
+
+### Free Models
+
+The following models are available at no cost:
+
+| Model ID | Provider |
+|----------|----------|
+| `minimax/minimax-m2.5` | MiniMax |
+| `kwaipilot/kat-coder-pro` | Kwaipilot |
+| `z-ai/glm-5` | Z-AI |
+
+<Note>
+  Model availability and pricing may change. Check [app.cline.bot](https://app.cline.bot) for the latest list.
+</Note>
+
+## Error Handling
+
+Errors follow the OpenAI error format:
+
+```json
+{
+  "error": {
+    "code": 401,
+    "message": "Invalid API key",
+    "metadata": {}
+  }
+}
+```
+
+Common error codes:
+
+| Code | Meaning |
+|------|---------|
+| `401` | Invalid or missing API key |
+| `402` | Insufficient credits |
+| `429` | Rate limit exceeded |
+| `500` | Server error |
+| `error` (finish_reason) | Mid-stream error from the upstream model provider |
+
+## Using with Cline
+
+The easiest way to use the Cline API is through the Cline extension or CLI, which handle authentication and streaming for you.
+
+### VS Code / JetBrains
+
+Select **Cline** as your provider in the model picker dropdown. Sign in with your Cline account and your API key is managed automatically.
+
+### Cline CLI
+
+Configure the CLI with your API key in one command:
+
+```bash
+cline auth -p cline -k "YOUR_API_KEY" -m anthropic/claude-sonnet-4-6
+```
+
+Then run tasks normally:
+
+```bash
+cline "Write a one-line hello world in Python."
+```
+
+See the [CLI Reference](/cline-cli/cli-reference) for all available commands and options.
+
+## Using with Other Tools
+
+Because the Cline API is OpenAI-compatible, you can use it with any library or tool that supports custom OpenAI endpoints.
+
+### Python (OpenAI SDK)
+
+```python
+from openai import OpenAI
+
+client = OpenAI(
+    base_url="https://api.cline.bot/api/v1",
+    api_key="YOUR_API_KEY",
+)
+
+response = client.chat.completions.create(
+    model="anthropic/claude-sonnet-4-6",
+    messages=[{"role": "user", "content": "Hello!"}],
+)
+print(response.choices[0].message.content)
+```
+
+### Node.js (OpenAI SDK)
+
+```typescript
+import OpenAI from "openai"
+
+const client = new OpenAI({
+  baseURL: "https://api.cline.bot/api/v1",
+  apiKey: "YOUR_API_KEY",
+})
+
+const response = await client.chat.completions.create({
+  model: "anthropic/claude-sonnet-4-6",
+  messages: [{ role: "user", content: "Hello!" }],
+})
+console.log(response.choices[0].message.content)
+```
+
+## Related
+
+<CardGroup cols={2}>
+  <Card title="CLI Reference" icon="terminal" href="/cline-cli/cli-reference">
+    Full command reference for the Cline CLI, including auth setup.
+  </Card>
+  <Card title="Enterprise API" icon="building" href="/enterprise-solutions/api-reference">
+    Admin endpoints for user management, organizations, billing, and API keys.
+  </Card>
+</CardGroup>

docs/api/sdk-examples.mdx

@@ -214,7 +214,7 @@ console.log(data.choices[0].message.content)
 
 ## Cline CLI
 
-The [Cline CLI](/cli/cli-reference) is the fastest way to use the Cline API from your terminal. It handles authentication, streaming, and tool execution for you.
+The [Cline CLI](/cline-cli/cli-reference) is the fastest way to use the Cline API from your terminal. It handles authentication, streaming, and tool execution for you.
 
 ### Setup
 
@@ -242,7 +242,7 @@ cline -m google/gemini-2.5-pro "Analyze this codebase."
 cline -y "Run tests and fix failures."
 ```
 
-See the [CLI Reference](/cli/cli-reference) for all commands and options.
+See the [CLI Reference](/cline-cli/cli-reference) for all commands and options.
 
 ## VS Code / JetBrains
 
@@ -269,7 +269,7 @@ For setup instructions, see [Installing Cline](/getting-started/installing-cline
   <Card title="Models" icon="brain" href="/api/models">
     Browse available models.
   </Card>
-  <Card title="CLI Reference" icon="terminal" href="/cli/cli-reference">
+  <Card title="CLI Reference" icon="terminal" href="/cline-cli/cli-reference">
     Complete Cline CLI command reference.
   </Card>
 </CardGroup>

docs/cli/agent-teams.mdx

@@ -1,57 +0,0 @@
----
-title: "Agent Teams"
-sidebarTitle: "Agent Teams"
-description: "Coordinate multiple agents working together on complex tasks from the CLI."
----
-<Warning>
-  This feature currently only applies to Cline SDK, CLI, and Kanban. This feature is not applicable on VSCode and JetBrains Extension for now.
-</Warning>
-
-
-Agent teams let you break complex work across multiple agents that coordinate through a shared task board. One agent acts as the coordinator, delegating subtasks to specialist agents.
-
-## Starting a Team
-
-```bash
-cline --team-name auth-sprint "Plan and implement user authentication with tests"
-```
-
-The `--team-name` flag enables team mode. The coordinator agent gets additional tools for spawning teammates and delegating tasks.
-
-## Resuming Team Work
-
-Team state persists across sessions. Resume where you left off:
-
-```bash
-cline --team-name auth-sprint "Continue with incomplete tasks"
-```
-
-## Interactive Mode
-
-In interactive mode, use the `/team` slash command:
-
-```
-/team Plan and implement a REST API with tests
-```
-
-## Team State
-
-Team state is stored at `~/.cline/data/teams/[team-name]/` and includes:
-
-- Task board with current tasks and status
-- Inter-agent mailbox
-- Mission log with activity history
-
-## Disabling Teams
-
-Teams are enabled by default. Disable them with:
-
-```bash
-cline --no-teams "your prompt"
-```
-
-## Sub-Agents
-
-For simpler delegation within a single session (no persistent state), use [sub-agents](/features/subagents). Sub-agents run in parallel for read-only research and return focused reports to the main agent.
-
-See the [SDK Multi-Agent Teams guide](/sdk/guides/multi-agent-teams) for the programmatic API.

docs/cli/cli-reference.mdx

@@ -1,305 +0,0 @@
----
-title: "CLI Reference"
-description: "Complete command reference for Cline CLI including all commands, flags, and configuration options."
----
-
-```bash
-cline --help           # Show all commands
-cline <command> --help # Show help for a specific command
-```
-
-## Synopsis
-
-```bash
-cline [options] [command] [prompt]
-```
-
-## Help Menu (Source of Truth)
-
-```text
-Usage: cline [options] [command] [prompt]
-
-Cline CLI - AI coding assistant in your terminal
-
-Arguments:
-  prompt                       Your prompt. Default to start in act mode with auto-approve enabled.
-
-Options:
-  -V, --version                Output the version number
-  -p, --plan                   Run in plan mode
-  --json                       Output messages as JSON instead of styled text
-  --auto-approve <boolean>     Set tool auto-approval for all tools (default: true)
-  -t, --timeout <seconds>      Optional timeout in seconds (default: 0 for no timeout)
-  -m, --model <model-id>       Model to use for the session with the selected provider
-  -v, --verbose                Show verbose output
-  -c, --cwd <path>             Working directory
-  --config <path>              Configuration directory (default: ~/.cline/data/settings)
-  --data-dir <path>            Use isolated local state at this directory path (default: ~/.cline)
-  --thinking <level>           Set reasoning effort level between none|low|medium|high|xhigh (default: medium)
-  --retries <count>            Maximum consecutive mistakes (retries) before halting
-  --hooks-dir <path>           Directory path to additional hooks for runtime hook injection (default: ~/.cline/hooks)
-  --acp                        Run in Agent Client Protocol (ACP) mode for editor integration
-  -i, --tui                    Open the terminal user interface (TUI) for interactive sessions
-  --id <session-id>            Resume an existing session by ID
-  -k, --key <api-key>          API key override for this run
-  -P, --provider <id>          Provider id (default: cline)
-  -s, --system <system-prompt> Override the default system prompt
-  -z, --zen                    Start a session that runs in the background hub
-  -h, --help                   display help for command
-
-Commands:
-  auth [options] [provider]    Authenticate a provider and configure what model is used
-  config [options]             Show current configuration
-  connect [options] [adapter]  Connect to an editor or IDE adapter
-  mcp                          Manage MCP servers
-  dev                          Developer tools and utilities
-  doctor                       Diagnose and fix configuration issues
-  history|h [options]          List session history or manage saved sessions
-  hook                         Handle a hook payload from stdin
-  plugin                       Manage Cline Plugins
-  schedule                     Manage scheduled tasks
-  hub                          Manage the local hub daemon
-  update [options]             Check for updates and install if available
-  version                      Show Cline CLI version number
-  kanban                       Launch the kanban app and exit
-```
-
-## Global Options
-
-| Option | Description |
-|--------|-------------|
-| `-V, --version` | Output the version number |
-| `-p, --plan` | Run in plan mode |
-| `--json` | Output messages as JSON instead of styled text |
-| `--auto-approve <boolean>` | Set tool auto-approval for all tools (default: `true`) |
-| `-t, --timeout <seconds>` | Optional timeout in seconds (default: `0` for no timeout) |
-| `-m, --model <model-id>` | Model to use for the session with the selected provider |
-| `-v, --verbose` | Show verbose output |
-| `-c, --cwd <path>` | Working directory |
-| `--config <path>` | Configuration directory (default: `~/.cline/data/settings`) |
-| `--data-dir <path>` | Use isolated local state at this directory path (default: `~/.cline`) |
-| `--thinking <level>` | Set reasoning effort: `none\|low\|medium\|high\|xhigh` (default `medium`) |
-| `--retries <count>` | Maximum consecutive mistakes (retries) before halting |
-| `--hooks-dir <path>` | Directory path to additional hooks for runtime hook injection (default: `~/.cline/hooks`) |
-| `--acp` | Run in Agent Client Protocol (ACP) mode for editor integration |
-| `-i, --tui` | Open the terminal user interface (TUI) for interactive sessions |
-| `--id <session-id>` | Resume an existing session by ID |
-| `-k, --key <api-key>` | API key override for this run |
-| `-P, --provider <id>` | Provider id (default: `cline`) |
-| `-s, --system <system-prompt>` | Override the default system prompt |
-| `-z, --zen` | Start a session that runs in the background hub |
-| `-h, --help` | Display help for command |
-
-## Commands
-
-### `cline` (default)
-
-Start a task or enter interactive mode.
-
-```bash
-cline
-cline "your prompt here"
-cline "Run tests and fix failures"
-echo "prompt" | cline
-```
-
-### `auth [options] [provider]`
-
-Configure authentication with an AI provider.
-
-```bash
-cline auth
-```
-
-### `config [options]`
-
-Show current configuration.
-
-```bash
-cline config
-```
-
-### `connect [options] [adapter]`
-
-Connect to messaging platforms. See [Connectors](/cli/connectors).
-
-```bash
-cline connect
-cline connect [adapter]
-```
-
-### `mcp`
-
-Manage MCP servers. See [MCP](/mcp/mcp-overview).
-
-```bash
-cline mcp
-```
-
-### `dev`
-
-Developer tools and utilities.
-
-```bash
-cline dev
-```
-
-### `doctor`
-
-Diagnose and fix configuration issues.
-
-```bash
-cline doctor
-```
-
-### `history|h [options]`
-
-List session history or manage saved sessions.
-
-```bash
-cline history
-cline h
-```
-
-### `hook`
-
-Handle a hook payload from stdin.
-
-```bash
-cat payload.json | cline hook
-```
-
-### `plugin`
-
-Manage Cline plugins. Install plugins from npm, git repositories, or local paths. See [Plugins](/customization/plugins) for full details and the plugin manifest format.
-
-```bash
-cline plugin install <source>  # Install a plugin
-cline plugin i <source>        # Shorthand alias
-```
-
-| Option | Description |
-|--------|-------------|
-| `--npm` | Treat source as an npm package |
-| `--git` | Treat source as a git repository |
-| `--force` | Replace an existing install for the same source |
-| `--json` | Output result as JSON |
-| `--cwd <path>` | Install to `<path>/.cline/plugins` instead of the global directory |
-
-Try it with the [TypeScript Navigation Plugin](https://github.com/cline/typescript-lsp-plugin):
-
-```bash
-cline plugin install https://github.com/cline/typescript-lsp-plugin.git
-```
-
-### `schedule`
-
-Manage scheduled agents. See [Scheduling](/cli/scheduling).
-
-```bash
-cline schedule
-```
-
-### `hub`
-
-Manage the local hub daemon.
-
-```bash
-cline hub
-```
-
-### `update [options]`
-
-Check for updates and install if available.
-
-```bash
-cline update
-```
-
-### `version`
-
-Show Cline CLI version number.
-
-```bash
-cline version
-cline -V
-```
-
-### `kanban`
-
-Launch the kanban app and exit.
-
-```bash
-cline kanban
-```
-
-## Environment Variables
-
-| Variable | Description |
-|----------|-------------|
-| `CLINE_DATA_DIR` | Custom configuration directory (replaces `~/.cline/data/`) |
-| `CLINE_HUB_ADDRESS` | Override hub address (default: `127.0.0.1:25463`) |
-| `CLINE_SESSION_BACKEND_MODE` | Force backend mode (`local`, `hub`, `remote`, `auto`) |
-| `CLINE_SANDBOX_DATA_DIR` | Sandbox session storage directory |
-| `CLINE_SANDBOX` | Enable sandbox mode |
-| `CLINE_HOOKS_DIR` | Additional hooks directory |
-| `CLINE_BUILD_ENV` | Set to `development` for debug features |
-| `CLINE_DEBUG_PORT_BASE` | Base port for Node.js inspector |
-| `CLINE_COMMAND_PERMISSIONS` | JSON policy restricting shell commands (see below) |
-
-### CLINE_COMMAND_PERMISSIONS
-
-Restrict which shell commands the agent can execute:
-
-```bash
-export CLINE_COMMAND_PERMISSIONS='{"allow": ["npm *", "git *"], "deny": ["rm -rf *", "sudo *"]}'
-```
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `allow` | `string[]` | Glob patterns for allowed commands. If set, only matching commands are permitted. |
-| `deny` | `string[]` | Glob patterns for denied commands. Deny rules always take precedence. |
-| `allowRedirects` | `boolean` | Whether to allow shell redirects (`>`, `>>`, `<`). Default: `false`. |
-
-## JSON Output Format
-
-When using `--json`, each message is a JSON object on its own line:
-
-```json
-{"type": "say", "text": "I'll create the file now.", "ts": 1760501486669, "say": "text"}
-```
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `type` | `"ask"` or `"say"` | Message category |
-| `text` | `string` | Message content |
-| `ts` | `number` | Unix timestamp in milliseconds |
-| `say` | `string` | Subtype when `type` is `"say"` |
-| `ask` | `string` | Subtype when `type` is `"ask"` |
-| `reasoning` | `string` | Model reasoning (if available) |
-| `partial` | `boolean` | `true` while streaming |
-
-## Configuration Files
-
-```
-~/.cline/
-  data/
-    settings/
-      providers.json             # API keys and provider config
-      rules/                     # Global rules
-      skills/                    # Global skills
-    teams/                       # Team state
-    sessions/                    # Session database (SQLite)
-    logs/
-      hub-daemon.log             # Hub logs
-  plugins/                       # Global plugins
-    _installed/                  # Managed by `cline plugin install`
-
-.cline/                          # Project root
-  rules/                         # Project rules
-  skills/                        # Project skills
-  hooks/                         # Lifecycle hooks
-  plugins/                       # Project plugins
-  mcp.json                       # MCP server config
-  agents.yaml                    # Agent definitions
-```

docs/cli/connectors.mdx

@@ -1,156 +0,0 @@
----
-title: "Connectors"
-sidebarTitle: "Connectors"
-description: "Connect the CLI to Telegram, Slack, Discord, Google Chat, WhatsApp, etc."
----
-<Warning>
-  This feature currently only applies to Cline CLI.
-</Warning>
-
-Connectors let you chat with your agent from messaging platforms. Each incoming message creates or continues an agent session, and the agent's response is sent back to the conversation.
-
-## Setup Wizard
-
-Run `cline connect` to open an interactive wizard that guides you through platform selection, credential entry, security configuration, and advanced options (provider, model, system prompt, agent mode).
-
-```bash
-cline connect
-```
-
-## Supported Platforms
-
-| Platform | Direct Command | Required Credentials |
-|----------|---------------|---------------------|
-| Telegram | `cline connect telegram` | Bot username, bot token |
-| Slack | `cline connect slack` | Bot token, signing secret, base URL |
-| Discord | `cline connect discord` | Application ID, bot token, public key, base URL |
-| Google Chat | `cline connect gchat` | Service account credentials JSON, base URL |
-| WhatsApp | `cline connect whatsapp` | Phone number ID, access token, app secret, verify token, base URL |
-| Linear | `cline connect linear` | API key, webhook signing secret, base URL |
-
-## Telegram
-
-<Steps>
-  <Step title="Create a Telegram bot">
-    Open Telegram and start a chat with [@BotFather](https://t.me/BotFather). Send `/newbot` and follow the prompts:
-
-    1. Enter a display name (e.g., "Cline")
-    2. Enter a username ending in `bot` (e.g., `cline_myname_bot`). Must be unique across Telegram.
-    3. BotFather responds with your bot token (looks like `7123456789:AAH...`)
-  </Step>
-
-  <Step title="Start the connector">
-    ```bash
-    cline connect telegram -m <BOT-USERNAME> -k <BOT-TOKEN>
-    ```
-  </Step>
-
-  <Step title="Chat with your bot">
-    Open Telegram, search for your bot's username, and send a message. The agent processes it and replies in the chat.
-  </Step>
-</Steps>
-
-### Security
-
-By default, anyone who finds your bot can message it and it will execute tasks on your machine. Lock it down with the `--hook-command` flag.
-
-<Steps>
-  <Step title="Get your Telegram user ID">
-    Message [@userinfobot](https://t.me/userinfobot) on Telegram. It replies with your user ID immediately.
-  </Step>
-
-  <Step title="Start with access control">
-    Replace `12345` with your actual Telegram user ID:
-
-    ```bash
-    cline connect telegram -m <BOT-USERNAME> -k <BOT-TOKEN> \
-      --hook-command 'jq -r ".payload.actor.participantKey" | grep -q "telegram:id:12345" && echo "{\"action\":\"allow\"}" || echo "{\"action\":\"deny\",\"message\":\"unauthorized\"}"'
-    ```
-  </Step>
-</Steps>
-
-The `--hook-command` receives each incoming message with sender info via stdin. Your script returns `{"action": "allow"}` or `{"action": "deny", "message": "reason"}`. Without `--hook-command`, everything is auto-approved.
-
-## Slack
-
-Requires a bot token, signing secret, and public base URL.
-
-```bash
-cline connect slack --token <BOT-TOKEN> --signing-secret <SECRET> --base-url <URL>
-```
-
-Each Slack thread maps to an agent session, so the agent maintains conversation context within a thread.
-
-## Discord
-
-Requires an application ID, bot token, public key, and public base URL.
-
-```bash
-cline connect discord --app-id <ID> --token <TOKEN> --public-key <KEY> --base-url <URL>
-```
-
-## Google Chat
-
-Requires a service account credentials JSON file and public base URL.
-
-```bash
-cline connect gchat --credentials <JSON> --base-url <URL>
-```
-
-## WhatsApp
-
-Requires a phone number ID, access token, app secret, webhook verify token, and public base URL.
-
-```bash
-cline connect whatsapp --phone-id <ID> --token <TOKEN> --app-secret <SECRET> --base-url <URL>
-```
-
-## Linear
-
-Requires an API key, webhook signing secret, and public base URL.
-
-```bash
-cline connect linear --api-key <KEY> --signing-secret <SECRET> --base-url <URL>
-```
-
-## Managing Connectors
-
-```bash
-# Stop all connectors
-cline connect --stop
-
-# Stop a specific connector
-cline connect telegram --stop
-```
-
-## Hook Command Protocol
-
-The `--hook-command` pattern works across all connectors. The script receives a JSON payload via stdin:
-
-```json
-{
-  "payload": {
-    "actor": {
-      "participantKey": "telegram:id:12345",
-      "displayName": "User Name"
-    },
-    "message": "The incoming message text"
-  }
-}
-```
-
-Return `{"action": "allow"}` or `{"action": "deny", "message": "reason"}`.
-
-## Running Multiple Connectors
-
-Multiple connectors can run simultaneously. They all share the same hub:
-
-```bash
-# Terminal 1
-cline connect telegram -m my_bot -k $TELEGRAM_TOKEN
-
-# Terminal 2
-cline connect slack --token $SLACK_TOKEN --signing-secret $SECRET --base-url $URL
-```
-
-Connectors require the hub. Start it with `cline hub start` if it doesn't auto-start.

docs/cli/scheduling.mdx

@@ -1,110 +0,0 @@
----
-title: "Scheduling"
-sidebarTitle: "Scheduling"
-description: "Run agents on cron schedules for recurring automations like daily summaries and code reviews."
----
-<Warning>
-  This feature currently only applies to Cline SDK, CLI, and Kanban. This feature is not applicable on VSCode and JetBrains Extension for now.
-</Warning>
-
-The CLI supports running agents on cron schedules through the hub. Scheduled agents persist across process restarts and run independently of any terminal session.
-
-## Schedule Wizard
-
-Run `cline schedule` to open an interactive menu for creating and managing schedules, browsing execution history, and viewing performance statistics.
-
-```bash
-cline schedule
-```
-
-The wizard provides:
-
-| Action | Description |
-|--------|-------------|
-| Create new schedule | Set up a recurring task with cron timing and prompt |
-| List schedules | View all schedules with status and next run time |
-| Upcoming runs | Preview the next 10 scheduled executions |
-| Active executions | Show currently running tasks |
-| Trigger now | Immediately run a selected schedule |
-| Pause / Resume | Suspend or restart a schedule |
-| Execution history | View past runs with status, duration, tokens, and cost |
-| Statistics | Success rate, average duration, last failure |
-| Delete | Remove a schedule |
-
-## Creating Schedules with Flags
-
-```bash
-cline schedule create "PR summary" \
-  --cron "0 9 * * MON-FRI" \
-  --prompt "List all open PRs and their review status" \
-  --workspace /path/to/repo \
-  --model anthropic/claude-sonnet-4-6
-```
-
-## Managing Schedules
-
-```bash
-cline schedule list
-cline schedule trigger <schedule-id>
-cline schedule pause <schedule-id>
-cline schedule resume <schedule-id>
-cline schedule delete <schedule-id>
-cline schedule executions <schedule-id>
-```
-
-## Cron Expression Reference
-
-| Expression | Schedule |
-|-----------|----------|
-| `*/5 * * * *` | Every 5 minutes |
-| `*/15 * * * *` | Every 15 minutes |
-| `0 * * * *` | Every hour |
-| `0 */6 * * *` | Every 6 hours |
-| `0 0 * * *` | Daily at midnight |
-| `0 9 * * *` | Daily at 9am |
-| `0 9 * * 1-5` | Every weekday at 9am |
-| `0 9 * * 1` | Every Monday at 9am |
-| `0 0 1 * *` | First of every month |
-
-## Examples
-
-### Daily Standup Summary
-
-```bash
-cline schedule create "Standup prep" \
-  --cron "0 8 * * MON-FRI" \
-  --prompt "Summarize: (1) PRs merged yesterday, (2) PRs currently in review, (3) open issues assigned to team members." \
-  --workspace /path/to/repo
-```
-
-### Weekly Dependency Check
-
-```bash
-cline schedule create "Dependency check" \
-  --cron "0 10 * * MON" \
-  --prompt "Check for outdated npm dependencies. For any with security vulnerabilities, create a branch with the update and open a PR." \
-  --workspace /path/to/project
-```
-
-### Codebase Health Report
-
-```bash
-cline schedule create "Code health" \
-  --cron "0 6 * * MON" \
-  --prompt "Analyze the codebase for: (1) files with no test coverage, (2) TODO/FIXME comments older than 30 days, (3) functions longer than 100 lines." \
-  --workspace /path/to/project
-```
-
-## Routing Results
-
-Combine schedules with [connectors](/cli/connectors) to send results to messaging platforms:
-
-```bash
-cline connect telegram -m my_bot -k $BOT_TOKEN
-
-cline schedule create "Morning briefing" \
-  --cron "0 8 * * *" \
-  --prompt "Summarize overnight activity in the repo"
-```
-
-Scheduling requires the hub. It starts automatically when you create a schedule.

docs/cline-cli/acp-editor-integrations.mdx

@@ -198,11 +198,11 @@ If Cline can't access files or run commands:
 ## Learn More
 
 <Columns cols={2}>
-  <Card title="CLI Overview" icon="terminal" href="/usage/cli-overview">
+  <Card title="CLI Overview" icon="terminal" href="/cline-cli/overview">
     Learn about Cline CLI's core capabilities and use cases.
   </Card>
   
-  <Card title="Headless Mode" icon="robot" href="/usage/cli-overview#headless-mode">
+  <Card title="Headless Mode" icon="robot" href="/cline-cli/three-core-flows">
     Run Cline autonomously in scripts, CI/CD pipelines, and automated workflows.
   </Card>
   

docs/cline-cli/cli-reference.mdx

@@ -0,0 +1,428 @@
+---
+title: "CLI Reference"
+description: "Complete command reference for Cline CLI including all commands, flags, and configuration options"
+---
+
+This page documents all available commands, flags, and configuration options for Cline CLI. For quick help in your terminal, use:
+
+```bash
+cline --help          # Show all commands
+cline task --help     # Show task command options
+cline auth --help     # Show auth command options
+man cline             # View the full manual page (if installed)
+```
+
+## Synopsis
+
+```bash
+cline [prompt] [options]
+cline <command> [options] [arguments]
+```
+
+## Global Options
+
+These options work with any command:
+
+| Option | Description |
+|--------|-------------|
+| `--config <path>` | Use a custom configuration directory instead of `~/.cline/data/` |
+| `-c, --cwd <path>` | Set the working directory for the task |
+| `-v, --verbose` | Show detailed output including model reasoning |
+| `--help` | Show help for the command |
+
+## Modes of Operation
+
+Cline CLI automatically detects the best output mode based on how you invoke it:
+
+| Mode | When Activated | Description |
+|------|----------------|-------------|
+| **Interactive** | `cline` with no args, TTY connected | Rich terminal UI with real-time streaming, keyboard shortcuts, and visual feedback. |
+| **Task** | `cline "prompt"` with TTY connected | Interactive UI starts immediately with your task. |
+| **Plain Text** | stdin piped, stdout redirected, or `--yolo`/`--json` flags | Clean text output without UI, suitable for scripting and CI/CD. |
+
+## Agent Behavior
+
+Cline operates in two primary modes that control how it approaches tasks:
+
+| Mode | Description |
+|------|-------------|
+| **Act Mode** (default) | Cline actively uses tools to accomplish tasks. It can read files, write code, execute commands, use a headless browser, and more. |
+| **Plan Mode** | Cline gathers information and creates a detailed plan before implementation. It explores the codebase, asks clarifying questions, and presents a strategy for your approval before switching to Act Mode. |
+
+Use `-a, --act` or `-p, --plan` flags to explicitly set the mode.
+
+## Commands
+
+### cline (default)
+
+Run Cline without a subcommand to start a task or enter interactive mode.
+
+```bash
+# Interactive mode (no arguments)
+cline
+
+# Start a task directly
+cline "your prompt here"
+
+# Resume the latest task for the current directory
+cline --continue
+```
+
+**Options:**
+
+| Option | Description |
+|--------|-------------|
+| `-a, --act` | Start in Act mode (default). Cline executes actions directly. |
+| `-p, --plan` | Start in Plan mode. Cline analyzes and creates a strategy before acting. |
+| `-y, --yolo` | YOLO mode: auto-approve all actions, use plain text output, exit when complete. Ideal for CI/CD. |
+| `-m, --model <id>` | Use a specific model (e.g., `claude-sonnet-4-5-20250929`, `gpt-4o`). |
+| `-i, --images <paths...>` | Include image files with the prompt. |
+| `--thinking` | Enable extended thinking with a 1024 token budget. |
+| `--json` | Output messages as JSON (one object per line). Forces plain text mode. |
+| `--timeout <seconds>` | Maximum execution time before the task is stopped. |
+| `--continue` | Resume the most recent task from the current working directory. |
+
+**Mode Behavior:**
+
+| Invocation | Output Mode | Why |
+|------------|-------------|-----|
+| `cline` | Interactive UI | No arguments, TTY connected |
+| `cline "prompt"` | Interactive UI | TTY connected |
+| `cline -y "prompt"` | Plain text | YOLO flag forces plain text |
+| `cline --json "prompt"` | JSON | JSON flag forces plain text |
+| `cat file \| cline "prompt"` | Plain text | stdin is piped |
+| `cline "prompt" > out.txt` | Plain text | stdout is redirected |
+
+---
+
+### cline task (alias: t)
+
+Run a task with a prompt. This is equivalent to `cline "prompt"`.
+
+```bash
+cline task "Create a REST API endpoint"
+cline t "Fix the bug in utils.js"
+```
+
+**Options:** Same as the default command above.
+
+---
+
+### cline auth
+
+Configure authentication with an AI provider.
+
+```bash
+# Interactive wizard
+cline auth
+
+# Quick setup with flags
+cline auth -p anthropic -k sk-ant-api-xxxxx -m claude-sonnet-4-5-20250929
+```
+
+**Options:**
+
+| Option | Description |
+|--------|-------------|
+| `-p, --provider <id>` | Provider ID. See [Supported Providers](#supported-providers) below. |
+| `-k, --apikey <key>` | API key for the provider. |
+| `-m, --modelid <id>` | Model ID to use (e.g., `claude-sonnet-4-5-20250929`, `gpt-4o`). |
+| `-b, --baseurl <url>` | Base URL for OpenAI-compatible providers. |
+
+**Supported Providers:**
+
+| Provider ID | Description |
+|-------------|-------------|
+| `anthropic` | Anthropic Claude (direct API) |
+| `openai-native` | OpenAI GPT models |
+| `openai-codex` | ChatGPT subscription via OAuth |
+| `openrouter` | OpenRouter (access multiple providers) |
+| `bedrock` | AWS Bedrock |
+| `gemini` | Google Gemini |
+| `xai` | X AI (Grok) |
+| `cerebras` | Cerebras (fast inference) |
+| `deepseek` | DeepSeek |
+| `ollama` | Ollama (local models) |
+| `lmstudio` | LM Studio (local models) |
+| `openai` | OpenAI-compatible API (custom base URL) |
+
+---
+
+### cline history (alias: h)
+
+Browse task history with pagination.
+
+```bash
+# Show recent tasks (default: 10)
+cline history
+
+# Show more tasks
+cline history -n 20
+
+# Paginate through history
+cline history -n 10 -p 2
+```
+
+**Options:**
+
+| Option | Description |
+|--------|-------------|
+| `-n, --limit <number>` | Number of tasks to show (default: 10) |
+| `-p, --page <number>` | Page number, 1-based (default: 1) |
+
+---
+
+### cline config
+
+View and manage configuration settings.
+
+```bash
+cline config
+```
+
+Opens an interactive configuration view with tabs for:
+- **Settings** - Global and workspace-specific settings
+- **Rules** - `.clinerules` files and imported rules
+- **Workflows** - Available workflows (appear as slash commands)
+- **Hooks** - Configured hook scripts
+- **Skills** - Enabled skills
+
+---
+
+### cline update
+
+Check for updates and install the latest version.
+
+```bash
+cline update
+```
+
+---
+
+### cline version
+
+Show the installed CLI version.
+
+```bash
+cline version
+```
+
+---
+
+### cline dev
+
+Developer tools for debugging.
+
+```bash
+# Open the log file
+cline dev log
+```
+
+## Environment Variables
+
+### CLINE_DIR
+
+Override the default configuration directory:
+
+```bash
+export CLINE_DIR=/path/to/custom/config
+cline "your task"
+```
+
+When set, all Cline data (settings, secrets, task history) is stored in this directory instead of `~/.cline/data/`.
+
+**Use cases:**
+- Running isolated Cline instances with different settings
+- CI/CD environments with custom state directories
+- Testing configuration changes without affecting your main setup
+
+### CLINE_COMMAND_PERMISSIONS
+
+Restrict which shell commands Cline can execute:
+
+```bash
+export CLINE_COMMAND_PERMISSIONS='{"allow": ["npm *", "git *"], "deny": ["rm -rf *"]}'
+```
+
+**Format:**
+
+```json
+{
+  "allow": ["pattern1", "pattern2"],
+  "deny": ["pattern3"],
+  "allowRedirects": true
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `allow` | `string[]` | Glob patterns for allowed commands. If set, **only** matching commands are permitted. |
+| `deny` | `string[]` | Glob patterns for denied commands. Deny rules **always take precedence** over allow rules. |
+| `allowRedirects` | `boolean` | Whether to allow shell redirects (`>`, `>>`, `<`). Default: `false`. |
+
+**Examples:**
+
+```bash
+# Allow only npm and git commands (deny everything else)
+export CLINE_COMMAND_PERMISSIONS='{"allow": ["npm *", "git *"]}'
+
+# Allow dev commands but explicitly deny dangerous ones
+export CLINE_COMMAND_PERMISSIONS='{"allow": ["npm *", "git *", "node *"], "deny": ["rm -rf *", "sudo *"]}'
+
+# Allow file reading with redirects
+export CLINE_COMMAND_PERMISSIONS='{"allow": ["cat *", "echo *"], "allowRedirects": true}'
+```
+
+**How commands are evaluated:**
+
+1. Check for dangerous characters (backticks outside single quotes, unquoted newlines)
+2. Parse command into segments split by operators (`&&`, `||`, `|`, `;`)
+3. If redirects are detected and `allowRedirects` is not true, command is denied
+4. Each segment is validated against deny rules first, then allow rules
+5. Subshell contents (`$(...)` and `(...)`) are recursively validated
+6. All segments must pass for the command to be allowed
+
+## JSON Output Format
+
+When using `--json`, each message is output as a JSON object (one per line):
+
+```json
+{
+  "type": "say",
+  "text": "I'll create the file now.",
+  "ts": 1760501486669,
+  "say": "text"
+}
+```
+
+**Required fields:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `type` | `"ask"` \| `"say"` | Message category |
+| `text` | `string` | Human-readable message content |
+| `ts` | `number` | Unix timestamp in milliseconds |
+
+**Optional fields:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `say` | `string` | Subtype when `type` is `"say"` (e.g., `"text"`, `"tool"`) |
+| `ask` | `string` | Subtype when `type` is `"ask"` (e.g., `"tool"`, `"followup"`) |
+| `reasoning` | `string` | Model reasoning (omitted when empty) |
+| `partial` | `boolean` | `true` while streaming (omitted when complete) |
+| `images` | `string[]` | Image URIs (omitted when empty) |
+| `files` | `string[]` | File paths (omitted when empty) |
+
+## Configuration Files
+
+Cline stores all data in `~/.cline/` by default:
+
+```text
+~/.cline/
+├── data/                    # Configuration directory
+│   ├── globalState.json     # Global settings
+│   ├── secrets.json         # API keys (stored securely)
+│   ├── workspace/           # Workspace-specific state
+│   └── tasks/               # Task history and conversations
+└── log/                     # Debug logs (view with cline dev log)
+```
+
+## Examples
+
+### Interactive Development
+
+```bash
+# Start interactive mode
+cline
+
+# Start with a task and use interactive UI
+cline "Help me refactor this codebase"
+```
+
+### Direct Task Execution
+
+```bash
+# Run a task directly
+cline "Add error handling to utils.js"
+
+# Start in Plan mode to review strategy first
+cline -p "Design a caching layer for the API"
+
+# Use a specific model
+cline -m gpt-4o "Explain this code"
+```
+
+### Piped Input
+
+```bash
+# Pipe file contents
+cat README.md | cline "Summarize this document"
+
+# Review git changes
+git diff | cline "Review these changes"
+
+# Analyze test output
+npm test 2>&1 | cline "Fix any failing tests"
+```
+
+### Automation and CI/CD
+
+```bash
+# YOLO mode for automated workflows
+cline -y "Run tests and fix failures"
+
+# JSON output for scripting
+cline --json "List all TODO comments" | jq '.text'
+
+# With timeout
+cline -y --timeout 600 "Run the full test suite"
+
+# Chain commands
+git diff | cline -y "explain" | cline -y "write a commit message"
+```
+
+### Authentication
+
+```bash
+# Interactive wizard
+cline auth
+
+# Quick setup: Anthropic
+cline auth -p anthropic -k sk-ant-api-xxxxx -m claude-sonnet-4-5-20250929
+
+# Quick setup: OpenAI
+cline auth -p openai-native -k sk-xxxxx -m gpt-4o
+
+# Quick setup: OpenRouter
+cline auth -p openrouter -k sk-or-xxxxx
+
+# OpenAI-compatible with custom URL
+cline auth -p openai -k your-key -b https://api.example.com/v1
+```
+
+## Support
+
+- **Report bugs:** https://github.com/cline/cline/issues
+- **Discord community:** https://discord.gg/cline
+- **Documentation:** https://docs.cline.bot
+
+## See Also
+
+<Columns cols={2}>
+  <Card title="Installation & Setup" icon="download" href="/cline-cli/installation">
+    Install Cline CLI and configure authentication.
+  </Card>
+  
+  <Card title="Interactive Mode" icon="terminal" href="/cline-cli/interactive-mode">
+    Keyboard shortcuts, slash commands, and file mentions.
+  </Card>
+  
+  <Card title="Headless Mode" icon="robot" href="/cline-cli/three-core-flows">
+    Run Cline autonomously in scripts, CI/CD pipelines, and automated workflows.
+  </Card>
+  
+  <Card title="Configuration" icon="gear" href="/cline-cli/configuration">
+    Environment variables and advanced settings.
+  </Card>
+</Columns>

docs/cline-cli/configuration.mdx

@@ -0,0 +1,330 @@
+---
+title: "Configuration"
+description: "Manage Cline CLI settings with cline config, environment variables, and configuration files"
+---
+
+Cline CLI provides multiple ways to configure settings, from the interactive `cline config` command to environment variables for automation.
+
+## The Config Command
+
+Launch the configuration interface:
+
+```bash
+cline config
+```
+
+This opens an interactive view with tabs for different configuration categories.
+
+## Configuration Tabs
+
+Navigate between tabs using arrow keys.
+
+### Settings Tab
+
+View and edit global and workspace-specific settings:
+
+- **Global State**: Settings that apply across all workspaces
+- **Workspace State**: Settings specific to the current directory
+
+### Rules Tab
+
+Manage Cline rules that guide AI behavior:
+
+- **`.clinerules` files**: Project-specific rules in your workspace
+- **Cursor rules**: Import rules from Cursor editor format
+- **Windsurf rules**: Import rules from Windsurf editor format
+
+Rules help Cline understand your project's conventions, coding standards, and preferences.
+
+### Workflows Tab
+
+View and manage [workflows](/customization/workflows):
+
+- List available workflows
+- View workflow definitions
+- Workflows appear as slash commands in interactive mode
+
+### Hooks Tab
+
+Configure [hooks](/customization/hooks) for custom logic integration:
+
+- Enable/disable hooks globally
+- View configured hook scripts
+- Hooks run at key points in Cline's workflow
+
+<Note>
+Hooks must be enabled via settings. Use `cline config` to toggle `hooks-enabled`.
+</Note>
+
+### Skills Tab
+
+Manage [skills](/customization/skills) that extend Cline's capabilities:
+
+- View available skills
+- Enable/disable specific skills
+- Skills provide specialized instructions for specific tasks
+
+## Configuration Directory
+
+Cline stores configuration in `~/.cline/data/`:
+
+```text
+~/.cline/
+├── data/                    # Configuration directory
+│   ├── globalState.json     # Global settings
+│   ├── secrets.json         # API keys (encrypted)
+│   ├── settings/            # Settings files
+│   │   └── cline_mcp_settings.json  # MCP server configuration
+│   ├── workspace/           # Workspace-specific state
+│   └── tasks/               # Task history and data
+└── log/                     # Log files
+```
+
+### Viewing Logs
+
+For debugging, view the log file:
+
+```bash
+cline dev log
+```
+
+This opens the log file in your default editor.
+
+## Environment Variables
+
+### CLINE_DIR
+
+Override the default configuration directory:
+
+```bash
+export CLINE_DIR=/custom/path/to/cline
+cline "your task"
+```
+
+When set, all Cline data is stored in this directory instead of `~/.cline/data/`.
+
+**Use cases:**
+- Running multiple isolated Cline configurations
+- Team-shared configurations
+- CI/CD with custom state directories
+
+### CLINE_COMMAND_PERMISSIONS
+
+Restrict which shell commands Cline can execute:
+
+```bash
+export CLINE_COMMAND_PERMISSIONS='{"allow": ["npm *", "git *"], "deny": ["rm -rf *"]}'
+```
+
+**Format:**
+
+```json
+{
+  "allow": ["pattern1", "pattern2"],
+  "deny": ["pattern3"],
+  "allowRedirects": true
+}
+```
+
+**Fields:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `allow` | `string[]` | Glob patterns for allowed commands. If set, only matching commands are permitted. |
+| `deny` | `string[]` | Glob patterns for denied commands. Deny rules take precedence over allow. |
+| `allowRedirects` | `boolean` | Whether to allow shell redirects (`>`, `>>`, `<`). Default: `false` |
+
+**Examples:**
+
+```bash
+# Allow only npm and git commands
+export CLINE_COMMAND_PERMISSIONS='{"allow": ["npm *", "git *"]}'
+
+# Allow dev commands but deny dangerous ones
+export CLINE_COMMAND_PERMISSIONS='{"allow": ["npm *", "git *", "node *"], "deny": ["rm -rf *", "sudo *"]}'
+
+# Allow file operations with redirects
+export CLINE_COMMAND_PERMISSIONS='{"allow": ["cat *", "echo *"], "allowRedirects": true}'
+```
+
+<Warning>
+When `allow` is set, all commands not matching the allow patterns are denied. Use this for security-sensitive environments.
+</Warning>
+
+## Using --config Flag
+
+Run Cline with a custom configuration directory:
+
+```bash
+cline --config /path/to/custom/config "your task"
+```
+
+This is useful for:
+- Running isolated Cline instances
+- Testing different configurations
+- Separating work and personal setups
+
+**Example: Multiple configurations**
+
+```bash
+# Work configuration
+cline --config ~/.cline-work "review this PR"
+
+# Personal projects
+cline --config ~/.cline-personal "help me with this side project"
+```
+
+## MCP Server Configuration
+
+Cline CLI supports [MCP (Model Context Protocol)](/mcp/mcp-overview) servers, giving you access to external tools and data sources directly from the terminal. The CLI uses the same MCP configuration format as the VS Code extension.
+
+### Setting Up MCP Servers
+
+You can add MCP servers from the CLI:
+
+```bash
+# STDIO server
+cline mcp add kanban -- kanban mcp
+
+# Remote HTTP server
+cline mcp add linear https://mcp.linear.app/mcp --type http
+```
+
+These commands update:
+
+```
+~/.cline/data/settings/cline_mcp_settings.json
+```
+
+You can still edit this file directly. It uses the same JSON format as the VS Code extension:
+
+```json
+{
+  "mcpServers": {
+    "my-server": {
+      "command": "node",
+      "args": ["/path/to/server.js"],
+      "env": {
+        "API_KEY": "your_api_key"
+      },
+      "alwaysAllow": ["tool1", "tool2"],
+      "disabled": false
+    }
+  }
+}
+```
+
+For the full configuration reference including STDIO and SSE transport types, see [Adding and Configuring MCP Servers](/mcp/adding-and-configuring-servers).
+
+<Note>
+The CLI does not yet have a `/mcp` slash command for interactive management inside the terminal UI. Use `cline mcp add` or edit `cline_mcp_settings.json` directly.
+</Note>
+
+### Custom Config Directory
+
+If you use the `CLINE_DIR` environment variable or `--config` flag, the MCP settings file will be located at `<your-config-dir>/data/settings/cline_mcp_settings.json` instead.
+
+## Configuration for Local Providers
+
+### Ollama
+
+Configure context window size for Ollama:
+
+```bash
+# In settings or via config
+cline config
+# Navigate to Settings tab, find ollama-api-options-ctx-num
+```
+
+Or set via environment:
+
+```bash
+# Set context window to 32K tokens
+cline -m ollama/llama3 "your task"
+```
+
+### LM Studio
+
+Configure max tokens for LM Studio:
+
+```bash
+cline config
+# Navigate to Settings tab, find lm-studio-max-tokens
+```
+
+## Importing Configuration
+
+### From VS Code Extension
+
+If you use the Cline VS Code extension, the CLI automatically detects and can share some settings. However, the CLI maintains its own configuration for terminal-specific features.
+
+### From Other CLI Tools
+
+See [Installation & Setup](/cline-cli/installation#option-3-import-from-existing-tools) for importing configurations from:
+- Codex CLI
+- OpenCode
+
+## Configuration Best Practices
+
+### For Development
+
+Use the default configuration with workspace-specific rules:
+
+```bash
+# Add project-specific rules
+echo "Use TypeScript strict mode" > .clinerules/typescript.md
+```
+
+### For CI/CD
+
+Use environment variables and `--yolo` mode:
+
+```bash
+export CLINE_COMMAND_PERMISSIONS='{"allow": ["npm test", "npm run build"]}'
+cline -y "run tests and fix any failures"
+```
+
+### For Teams
+
+Share configuration via version control:
+
+```bash
+# Commit .clinerules/ to your repo
+git add .clinerules/
+git commit -m "Add Cline rules for team"
+```
+
+## Troubleshooting
+
+### Configuration Not Persisting
+
+1. Check write permissions on `~/.cline/data/`
+2. Ensure `CLINE_DIR` isn't set to a read-only location
+3. Verify the config directory exists
+
+### Environment Variables Not Working
+
+1. Ensure variables are exported: `export CLINE_DIR=/path`
+2. Check for typos in variable names
+3. Verify JSON syntax for `CLINE_COMMAND_PERMISSIONS`
+
+### Reset Configuration
+
+To start fresh, remove the configuration directory:
+
+```bash
+rm -rf ~/.cline/data/
+cline auth  # Re-authenticate
+```
+
+## Next Steps
+
+<Columns cols={2}>
+  <Card title="Headless Mode" icon="robot" href="/cline-cli/three-core-flows">
+    Run Cline autonomously in scripts, CI/CD pipelines, and automated workflows.
+  </Card>
+  
+  <Card title="CLI Reference" icon="terminal" href="/cline-cli/cli-reference">
+    Complete command documentation with all flags and options.
+  </Card>
+</Columns>

docs/cline-cli/getting-started.mdx

@@ -0,0 +1,457 @@
+---
+title: "Getting Started"
+description: "Run Cline AI coding agents directly in your terminal with an interactive CLI or automated workflows"
+---
+
+## What is Cline CLI?
+
+Cline CLI brings the full power of Cline to your terminal. Whether you prefer an interactive experience or automated workflows for CI/CD pipelines, the CLI adapts to your needs.
+
+The CLI supports macOS, Linux, and Windows, and works with all the same AI providers as the VS Code extension.
+
+## Two Ways to Use Cline CLI
+
+The CLI operates in two distinct modes, automatically selecting the appropriate one based on how you invoke it:
+
+### Interactive Mode
+
+Interactive mode is designed for **hands-on development sessions** where you want to collaborate with Cline in real-time. It provides a rich terminal interface that feels like chatting with an AI assistant.
+
+**When it activates:** Running `cline` without arguments, or when stdin is a TTY (terminal).
+
+```bash
+cline
+```
+
+Key features:
+
+- **Real-time conversation** - Type messages, see Cline's responses, and iterate on tasks
+- **Visual feedback** - Animated welcome screen, syntax-highlighted code, and progress indicators
+- **File mentions** with `@` - Reference workspace files with fuzzy search autocomplete
+- **Slash commands** with `/` - Quick access to `/settings`, `/history`, `/models`, and workflows
+- **Keyboard shortcuts** - `Tab` to toggle Plan/Act, `Shift+Tab` for auto-approve all
+- **Session summaries** - See tasks completed, files modified, and token usage on exit
+- **Settings panel** - Configure providers, models, and features without leaving the CLI
+
+Interactive mode keeps you in control. You review Cline's plan, approve or modify actions, and guide the conversation.
+
+[Learn more about interactive mode →](/cline-cli/interactive-mode)
+
+### Headless Mode (Non-Interactive)
+
+Headless mode is designed for **automation, scripting, and CI/CD pipelines** where human interaction isn't possible or desired.
+
+**When it activates:** Using the `-y`/`--yolo` flag, `--json` flag, piping input/output, or when stdin is not a TTY.
+
+```bash
+# Headless with auto-approval (YOLO mode)
+cline -y "Run tests and fix any failures"
+
+# Headless with JSON output for parsing
+cline --json "List all TODO comments" | jq '.text'
+
+# Headless via piped input
+cat README.md | cline "Summarize this document"
+
+# Chain multiple headless commands
+git diff | cline -y "explain these changes" | cline -y "write a commit message"
+```
+
+Key features:
+
+- **No visual interface** - Clean text or JSON output suitable for scripting
+- **Automatic execution** - With `-y`, Cline approves all actions and runs autonomously
+- **Process control** - Exits automatically when the task completes
+- **Piped workflows** - Read from stdin, write to stdout, chain with other commands
+- **Machine-readable output** - Use `--json` to get structured output for parsing
+
+<Warning>
+Headless mode with `-y` gives Cline full autonomy. Run on a clean git branch so you can easily revert changes if needed.
+</Warning>
+
+### Mode Detection Summary
+
+Cline automatically detects which mode to use based on your invocation. This table shows how different command patterns trigger each mode, helping you predict behavior in scripts and interactive sessions.
+
+| Invocation | Mode | Reason |
+|------------|------|--------|
+| `cline` | Interactive | No arguments, TTY connected |
+| `cline "task"` | Interactive | TTY connected |
+| `cline -y "task"` | Headless | YOLO flag forces headless |
+| `cline --json "task"` | Headless | JSON flag forces headless |
+| `cat file \| cline "task"` | Headless | stdin is piped |
+| `cline "task" > output.txt` | Headless | stdout is redirected |
+
+[Learn more about headless mode →](/cline-cli/three-core-flows)
+
+## Supported Model Providers
+
+Cline CLI supports all providers available in the VS Code extension:
+
+- **Anthropic** (Claude)
+- **OpenAI** (GPT-4o, GPT-4)
+- **OpenAI Codex** (ChatGPT subscription)
+- **OpenRouter**
+- **AWS Bedrock**
+- **Google Gemini**
+- **X AI (Grok)**
+- **Cerebras**
+- **DeepSeek**
+- **Ollama** (local models)
+- **LM Studio** (local models)
+- **OpenAI Compatible** (any compatible API)
+
+During setup, authenticate with `cline auth` to configure your preferred provider. [See authentication →](#authenticate)
+
+## What You Can Build
+
+### Automated Code Maintenance
+
+Keep your codebase healthy with automated fixes. Cline scans for issues and applies corrections across multiple files.
+
+```bash
+cline -y "Fix all ESLint errors in src/"
+```
+Finds and fixes linting violations throughout your source directory.
+
+```bash
+cline -y "Update all deprecated React lifecycle methods"
+```
+Migrates legacy code patterns to modern equivalents (e.g., `componentWillMount` → `useEffect`).
+
+```bash
+cline -y "Update dependencies with known vulnerabilities"
+```
+Identifies outdated packages with security issues and updates them to safe versions.
+
+### CI/CD Integration
+
+Integrate Cline into your continuous integration pipelines for automated code review and documentation.
+
+```bash
+git diff origin/main | cline -y "Review these changes for issues"
+```
+Pipes your PR diff to Cline for automated code review, catching bugs and style issues before merge.
+
+```bash
+git log --oneline v1.0..v1.1 | cline -y "Write release notes"
+```
+Generates human-readable release notes from your commit history between two tags.
+
+```bash
+cline -y "Run tests and fix failures" --timeout 600
+```
+Executes your test suite, analyzes failures, and attempts fixes with a 10-minute timeout.
+
+### Development Workflows
+
+From quick edits to complex refactors, Cline adapts to your workflow.
+
+```bash
+cline
+```
+Launches interactive mode for exploratory development and back-and-forth collaboration.
+
+```bash
+cline "Refactor this function to use async/await"
+```
+Executes a focused task directly from the command line with approval prompts at key steps.
+
+```bash
+cline "Based on @src/api.ts, add error handling to all endpoints"
+```
+Uses file mentions (`@`) to give Cline context about specific files in your workspace.
+
+### Custom Shell Pipelines
+
+Chain Cline with other CLI tools to build powerful automation workflows.
+
+```bash
+gh pr diff 123 | cline -y "Review this PR"
+```
+Fetches a GitHub PR diff and pipes it directly to Cline for review.
+
+```bash
+cline --json "List all TODO comments" | jq '.text'
+```
+Outputs structured JSON that you can process with tools like `jq` for scripting.
+
+```bash
+git diff | cline -y "explain" | cline -y "write a haiku about these changes"
+```
+Chains multiple Cline invocations together for creative multi-step workflows.
+
+## Features at a Glance
+
+| Feature | Interactive Mode | Non-Interactive Mode |
+|---------|------------------|----------------------|
+| Interactive chat | ✓ | - |
+| File mentions (@) | ✓ | ✓ (inline) |
+| Slash commands (/) | ✓ | - |
+| Settings panel | ✓ | `cline config` |
+| Plan/Act toggle | ✓ (Tab) | `-p` / `-a` flags |
+| Auto-approve | ✓ (Shift+Tab) | `-y` flag |
+| Session summary | ✓ | - |
+| JSON output | - | `--json` |
+| Piped input | - | ✓ |
+
+---
+
+## Installation & Setup
+
+In just a few minutes, you can install the CLI, authenticate with your preferred AI provider, and start running tasks from any directory on your machine.
+
+### Prerequisites
+
+Cline CLI requires **Node.js version 20 or higher**. We recommend Node.js 22 for the best experience.
+
+Check your Node.js version:
+
+```bash
+node --version
+```
+
+If you need to install or update Node.js, visit [nodejs.org](https://nodejs.org) or use a version manager like [nvm](https://github.com/nvm-sh/nvm).
+
+### Install Cline CLI
+
+Install globally via npm:
+
+```bash
+npm install -g cline
+```
+
+Verify the installation:
+
+```bash
+cline version
+```
+
+<Tip>
+To install a specific version, use `npm install -g cline@2.0.0`. Check [npm](https://www.npmjs.com/package/cline) for available versions.
+</Tip>
+
+### Authenticate
+
+After installation, run the authentication wizard:
+
+```bash
+cline auth
+```
+
+This launches an interactive wizard with multiple options. Choose the method that works best for your workflow.
+
+#### Option 1: Sign in with Cline (Recommended)
+
+Select **"Sign in with Cline"** to authenticate with your Cline account via OAuth. Your browser opens automatically to complete sign-in.
+
+#### Option 2: Sign in with ChatGPT Subscription
+
+If you have a ChatGPT Plus or Pro subscription, select **"Sign in with ChatGPT Subscription"**. This uses OpenAI's Codex OAuth to authenticate with your existing subscription.
+
+#### Option 3: Import from Existing Tools
+
+Already using another AI coding CLI? Cline can import your existing configuration:
+
+- **Import from Codex CLI** - Imports credentials from `~/.codex/auth.json`
+- **Import from OpenCode** - Imports configuration from `~/.local/share/opencode/auth.json`
+
+#### Option 4: Bring Your Own API Key
+
+Select **"Bring your own API key"** to manually configure any supported provider. Or skip the wizard entirely with flags:
+
+```bash
+# Anthropic (Claude)
+cline auth -p anthropic -k sk-ant-api-xxxxx -m claude-sonnet-4-5-20250929
+
+# OpenAI
+cline auth -p openai-native -k sk-xxxxx -m gpt-4o
+
+# OpenRouter
+cline auth -p openrouter -k sk-or-xxxxx -m anthropic/claude-sonnet-4-5-20250929
+
+# OpenAI-compatible provider with custom base URL
+cline auth -p openai -k your-api-key -b https://api.example.com/v1
+```
+
+**Quick Setup Flags:**
+
+| Flag | Description |
+|------|-------------|
+| `-p, --provider <id>` | Provider ID (e.g., `anthropic`, `openai-native`, `openrouter`) |
+| `-k, --apikey <key>` | Your API key |
+| `-m, --modelid <id>` | Model ID (e.g., `claude-sonnet-4-5-20250929`, `gpt-4o`) |
+| `-b, --baseurl <url>` | Base URL for OpenAI-compatible providers |
+
+<Tip>
+Flags are especially useful for scripting, CI/CD environments, or setting up multiple machines.
+</Tip>
+
+#### Supported Providers
+
+| Provider | Provider ID | Notes |
+|----------|-------------|-------|
+| Anthropic | `anthropic` | Direct Claude API access |
+| OpenAI | `openai-native` | GPT-4o, GPT-4, etc. |
+| OpenAI Codex | `openai-codex` | ChatGPT subscription OAuth |
+| OpenRouter | `openrouter` | Access multiple providers |
+| AWS Bedrock | `bedrock` | Claude via AWS |
+| Google Gemini | `gemini` | Gemini Pro, etc. |
+| X AI (Grok) | `xai` | Grok models |
+| Cerebras | `cerebras` | Fast inference |
+| DeepSeek | `deepseek` | DeepSeek models |
+| Ollama | `ollama` | Local models |
+| LM Studio | `lmstudio` | Local models |
+| OpenAI Compatible | `openai` | Any OpenAI-compatible API |
+
+### Verify Your Setup
+
+Confirm everything is working with a simple test:
+
+```bash
+cline "What is 2 + 2?"
+```
+
+If Cline responds with an answer, your installation and authentication are complete.
+
+Check your current configuration:
+
+```bash
+cline config
+```
+
+### Quick Start
+
+Now you're ready to use Cline. Choose how you want to work:
+
+#### Interactive Mode
+
+Launch the interactive CLI for development:
+
+```bash
+cline
+```
+
+You'll see the Cline welcome screen. Type your task and press Enter. Use:
+- `Tab` to toggle between Plan and Act modes
+- `Shift+Tab` to enable auto-approve
+- `/help` for available commands
+
+[Learn more about interactive mode →](/cline-cli/interactive-mode)
+
+#### Direct Task Execution
+
+Run a task directly from your shell:
+
+```bash
+cline "Add error handling to utils.js"
+```
+
+For non-interactive execution (perfect for scripts and CI/CD):
+
+```bash
+cline -y "Run tests and fix any failures"
+```
+
+[Learn more about headless mode →](/cline-cli/three-core-flows)
+
+### Switching Providers
+
+To change your configured provider at any time:
+
+```bash
+cline auth
+```
+
+You can also use the settings panel in interactive mode:
+
+```bash
+cline
+# Then type: /settings
+# Navigate to the API tab
+```
+
+### Updating
+
+Check for updates and install the latest version:
+
+```bash
+cline update
+```
+
+Or update manually via npm:
+
+```bash
+npm update -g cline
+```
+
+### Troubleshooting
+
+#### Command Not Found
+
+If `cline` is not found after installation:
+
+1. Ensure npm global bin is in your PATH:
+   ```bash
+   npm bin -g
+   ```
+
+2. Add the path to your shell configuration (`.bashrc`, `.zshrc`, etc.):
+   ```bash
+   export PATH="$PATH:$(npm bin -g)"
+   ```
+
+3. Restart your terminal or source your shell config.
+
+#### Permission Errors
+
+If you get permission errors during installation:
+
+```bash
+# Option 1: Use a Node version manager (recommended)
+# nvm, fnm, or volta handle permissions automatically
+
+# Option 2: Fix npm permissions
+# See: https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally
+```
+
+#### OAuth Flow Issues
+
+If the browser doesn't open automatically during OAuth:
+1. Copy the URL from the terminal
+2. Paste it in your browser manually
+3. Complete the sign-in flow
+4. Return to the terminal
+
+#### API Key Validation
+
+If your API key is rejected:
+1. Verify the key is correct and hasn't expired
+2. Check that you've selected the correct provider
+3. Ensure your API account has the necessary permissions
+
+**Provider-specific tips:**
+- **Anthropic**: Keys start with `sk-ant-`
+- **OpenAI**: Keys start with `sk-`
+- **AWS Bedrock**: Requires AWS credentials configured separately. See [AWS Bedrock documentation](/provider-config/aws-bedrock/api-key).
+
+### Uninstallation
+
+To remove Cline CLI:
+
+```bash
+npm uninstall -g cline
+```
+
+To also remove configuration data:
+
+```bash
+rm -rf ~/.cline
+```
+
+## Next Steps
+
+- **[Interactive Mode](/cline-cli/interactive-mode)** - Master the interactive CLI with shortcuts and slash commands
+- **[Headless Mode](/cline-cli/three-core-flows)** - Run Cline autonomously in scripts, CI/CD pipelines, and automated workflows
+- **[Configuration](/cline-cli/configuration)** - Configure settings, rules, workflows, and environment variables
+- **[CLI Reference](/cline-cli/cli-reference)** - Complete command documentation with all flags and options

docs/cline-cli/installation.mdx

@@ -0,0 +1,278 @@
+---
+title: "Installation & Setup"
+description: "Install Cline CLI on macOS, Linux, or Windows and configure your AI provider"
+---
+
+Cline CLI brings the full power of Cline to your terminal. In just a few minutes, you can install the CLI, authenticate with your preferred AI provider, and start running tasks from any directory on your machine.
+
+## Prerequisites
+
+Cline CLI requires **Node.js version 20 or higher**. We recommend Node.js 22 for the best experience.
+
+Check your Node.js version:
+
+```bash
+node --version
+```
+
+If you need to install or update Node.js, visit [nodejs.org](https://nodejs.org) or use a version manager like [nvm](https://github.com/nvm-sh/nvm).
+
+## Install Cline CLI
+
+Install globally via npm:
+
+```bash
+npm install -g cline
+```
+
+Verify the installation:
+
+```bash
+cline version
+```
+
+<Tip>
+To install a specific version, use `npm install -g cline@2.0.0`. Check [npm](https://www.npmjs.com/package/cline) for available versions.
+</Tip>
+
+## Authenticate
+
+After installation, run the authentication wizard:
+
+```bash
+cline auth
+```
+
+This launches an interactive wizard with multiple options. Choose the method that works best for your workflow.
+
+### Option 1: Sign in with Cline (Recommended)
+
+Select **"Sign in with Cline"** to authenticate with your Cline account via OAuth. Your browser opens automatically to complete sign-in.
+
+### Option 2: Sign in with ChatGPT Subscription
+
+If you have a ChatGPT Plus or Pro subscription, select **"Sign in with ChatGPT Subscription"**. This uses OpenAI's Codex OAuth to authenticate with your existing subscription.
+
+### Option 3: Import from Existing Tools
+
+Already using another AI coding CLI? Cline can import your existing configuration:
+
+- **Import from Codex CLI** - Imports credentials from `~/.codex/auth.json`
+- **Import from OpenCode** - Imports configuration from `~/.local/share/opencode/auth.json`
+
+### Option 4: Bring Your Own API Key
+
+Select **"Bring your own API key"** to manually configure any supported provider. Or skip the wizard entirely with flags:
+
+```bash
+# Anthropic (Claude)
+cline auth -p anthropic -k sk-ant-api-xxxxx -m claude-sonnet-4-5-20250929
+
+# OpenAI
+cline auth -p openai-native -k sk-xxxxx -m gpt-4o
+
+# OpenRouter
+cline auth -p openrouter -k sk-or-xxxxx -m anthropic/claude-sonnet-4-5-20250929
+
+# Moonshot
+cline auth -p moonshot -k sk-xxxxx -m kimi-k2.5
+
+# OpenAI-compatible provider with custom base URL
+cline auth -p openai -k your-api-key -b https://api.example.com/v1
+```
+
+**Quick Setup Flags:**
+
+| Flag | Description |
+|------|-------------|
+| `-p, --provider <id>` | Provider ID (e.g., `anthropic`, `openai-native`, `openrouter`, `moonshot`) |
+| `-k, --apikey <key>` | Your API key |
+| `-m, --modelid <id>` | Model ID (e.g., `claude-sonnet-4-5-20250929`, `gpt-4o`) |
+| `-b, --baseurl <url>` | Base URL for OpenAI-compatible providers |
+
+<Tip>
+Flags are especially useful for scripting, CI/CD environments, or setting up multiple machines.
+</Tip>
+
+### Supported Providers
+
+| Provider | Provider ID | Notes |
+|----------|-------------|-------|
+| Anthropic | `anthropic` | Direct Claude API access |
+| OpenAI | `openai-native` | GPT-4o, GPT-4, etc. |
+| OpenAI Codex | `openai-codex` | ChatGPT subscription OAuth |
+| OpenRouter | `openrouter` | Access multiple providers |
+| AWS Bedrock | `bedrock` | Claude via AWS |
+| Google Gemini | `gemini` | Gemini Pro, etc. |
+| X AI (Grok) | `xai` | Grok models |
+| Cerebras | `cerebras` | Fast inference |
+| DeepSeek | `deepseek` | DeepSeek models |
+| Moonshot | `moonshot` | Kimi models via Moonshot AI |
+| Ollama | `ollama` | Local models |
+| LM Studio | `lmstudio` | Local models |
+| OpenAI Compatible | `openai` | Any OpenAI-compatible API |
+
+## Verify Your Setup
+
+Confirm everything is working with a simple test:
+
+```bash
+cline "What is 2 + 2?"
+```
+
+If Cline responds with an answer, your installation and authentication are complete.
+
+Check your current configuration:
+
+```bash
+cline config
+```
+
+## Quick Start
+
+Now you're ready to use Cline. Choose how you want to work:
+
+### Interactive Mode
+
+Launch the interactive CLI for development:
+
+```bash
+cline
+```
+
+You'll see the Cline welcome screen. Type your task and press Enter. Use:
+- `Tab` to toggle between Plan and Act modes
+- `Shift+Tab` to enable auto-approve
+- `/help` for available commands
+
+[Learn more about interactive mode →](/cline-cli/interactive-mode)
+
+### Direct Task Execution
+
+Run a task directly from your shell:
+
+```bash
+cline "Add error handling to utils.js"
+```
+
+For non-interactive execution (perfect for scripts and CI/CD):
+
+```bash
+cline -y "Run tests and fix any failures"
+```
+
+[Learn more about headless mode →](/cline-cli/three-core-flows)
+
+## Switching Providers
+
+To change your configured provider at any time:
+
+```bash
+cline auth
+```
+
+You can also use the settings panel in interactive mode:
+
+```bash
+cline
+# Then type: /settings
+# Navigate to the API tab
+```
+
+## Updating
+
+Check for updates and install the latest version:
+
+```bash
+cline update
+```
+
+Or update manually via npm:
+
+```bash
+npm update -g cline
+```
+
+## Troubleshooting
+
+### Command Not Found
+
+If `cline` is not found after installation:
+
+1. Ensure npm global bin is in your PATH:
+   ```bash
+   npm bin -g
+   ```
+
+2. Add the path to your shell configuration (`.bashrc`, `.zshrc`, etc.):
+   ```bash
+   export PATH="$PATH:$(npm bin -g)"
+   ```
+
+3. Restart your terminal or source your shell config.
+
+### Permission Errors
+
+If you get permission errors during installation:
+
+```bash
+# Option 1: Use a Node version manager (recommended)
+# nvm, fnm, or volta handle permissions automatically
+
+# Option 2: Fix npm permissions
+# See: https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally
+```
+
+### OAuth Flow Issues
+
+If the browser doesn't open automatically during OAuth:
+1. Copy the URL from the terminal
+2. Paste it in your browser manually
+3. Complete the sign-in flow
+4. Return to the terminal
+
+### API Key Validation
+
+If your API key is rejected:
+1. Verify the key is correct and hasn't expired
+2. Check that you've selected the correct provider
+3. Ensure your API account has the necessary permissions
+
+**Provider-specific tips:**
+- **Anthropic**: Keys start with `sk-ant-`
+- **OpenAI**: Keys start with `sk-`
+- **AWS Bedrock**: Requires AWS credentials configured separately. See [AWS Bedrock documentation](/provider-config/aws-bedrock/api-key).
+
+## Uninstallation
+
+To remove Cline CLI:
+
+```bash
+npm uninstall -g cline
+```
+
+To also remove configuration data:
+
+```bash
+rm -rf ~/.cline
+```
+
+## Next Steps
+
+<Columns cols={2}>
+  <Card title="Interactive Mode" icon="terminal" href="/cline-cli/interactive-mode">
+    Master the interactive CLI with shortcuts and slash commands.
+  </Card>
+  
+  <Card title="Headless Mode" icon="robot" href="/cline-cli/three-core-flows">
+    Run Cline autonomously in scripts, CI/CD pipelines, and automated workflows.
+  </Card>
+  
+  <Card title="Configuration" icon="gear" href="/cline-cli/configuration">
+    Configure settings, rules, workflows, and environment variables.
+  </Card>
+  
+  <Card title="CLI Reference" icon="book" href="/cline-cli/cli-reference">
+    Complete command documentation with all flags and options.
+  </Card>
+</Columns>

docs/cline-cli/interactive-mode.mdx

@@ -0,0 +1,252 @@
+---
+title: "Interactive Mode"
+description: "Master the interactive CLI with keyboard shortcuts, slash commands, and file mentions"
+---
+
+Interactive mode is the primary way to work with Cline CLI when you want a collaborative, conversational experience. Unlike headless mode (which runs a single task and exits), interactive mode keeps a session open where you can have back-and-forth conversations with Cline, refine your requests, and guide the AI as it works.
+
+## Why Use Interactive Mode?
+
+Interactive mode is ideal when you:
+
+- **Don't know exactly what you need yet** - Explore a codebase, ask questions, and let Cline help you understand the architecture before making changes
+- **Want to review before acting** - Toggle Plan mode to see Cline's strategy, then switch to Act mode when you're ready
+- **Need iterative refinement** - Build on previous responses, ask follow-up questions, and guide Cline to the right solution
+- **Prefer human oversight** - Review each action, approve file changes, and maintain control over what Cline does
+- **Working on complex tasks** - Multi-step refactoring, debugging sessions, or feature development that requires judgment calls
+
+For automated workflows, scripts, or CI/CD pipelines, see [headless mode](/cline-cli/overview#headless-mode-non-interactive) instead.
+
+## Prerequisites
+
+Before using interactive mode, you need to have Cline CLI installed and authenticated. If you haven't done this yet, follow the [Installation & Setup guide](/cline-cli/installation) first.
+
+## Launching Interactive Mode
+
+Start interactive mode by running `cline` without any arguments:
+
+```bash
+cline
+```
+
+You'll see an animated welcome screen with the Cline robot. Start typing your task in the input field at the bottom of the screen.
+
+## Keyboard Shortcuts
+
+Keyboard shortcuts are the primary way to navigate and control the interactive CLI. Since there's no mouse interaction in the terminal, learning these shortcuts will help you work efficiently and switch between modes, manage input, and control your session without breaking your flow.
+
+### Mode Controls
+
+| Shortcut | Action |
+|----------|--------|
+| `Tab` | Toggle between Plan and Act mode |
+| `Shift+Tab` | Toggle auto-approve all actions |
+| `Esc` | Exit or cancel current operation |
+
+### Input Controls
+
+| Shortcut | Action |
+|----------|--------|
+| `Enter` | Submit your message |
+| `↑` / `↓` | Navigate message history |
+| `Home` / `End` | Move cursor to start/end of line |
+| `Ctrl+A` | Move cursor to beginning |
+| `Ctrl+E` | Move cursor to end |
+| `Ctrl+W` | Delete word before cursor |
+| `Ctrl+U` | Delete entire line |
+
+### Session Controls
+
+| Shortcut | Action |
+|----------|--------|
+| `Ctrl+C` | Exit with session summary |
+
+## File Mentions with @
+
+Reference files from your workspace by typing `@` followed by the filename:
+
+```text
+@src/utils.ts can you add error handling to this file?
+```
+
+As you type after `@`, Cline shows a fuzzy search dropdown of matching files. Use arrow keys to navigate and `Enter` to select.
+
+<Tip>
+File search uses ripgrep for fast, fuzzy matching. You can type partial paths like `@utils` to find `src/utils/helpers.ts`.
+</Tip>
+
+### Multiple File Mentions
+
+Include multiple files in a single message:
+
+```text
+Compare @src/old-api.ts with @src/new-api.ts and list the breaking changes
+```
+
+## Slash Commands
+
+Type `/` to see available commands. Slash commands provide quick access to settings, history, and workflows.
+
+### Built-in Commands
+
+| Command | Description |
+|---------|-------------|
+| `/settings` | Open the settings panel |
+| `/models` | Quick model switching |
+| `/history` | Browse and resume previous tasks |
+| `/clear` | Start a fresh task (clears current conversation) |
+| `/help` | Show help and available commands |
+| `/exit` | Exit the CLI |
+
+### Workflow Commands
+
+If you have [workflows](/customization/workflows) configured, they appear as additional slash commands. For example, if you have a workflow named `code-review`, you can invoke it with:
+
+```text
+/code-review
+```
+
+## Settings Panel
+
+Access the settings panel with `/settings`. Navigate between tabs using arrow keys.
+
+| Tab | Description | Settings |
+|-----|-------------|----------|
+| **API** | Configure your AI provider and model | Provider selection, model choice, extended thinking toggle, thinking budget |
+| **Auto-approve** | Control which actions Cline can perform without prompting | Read files, write files, execute commands, browser actions, MCP tools |
+| **Features** | Toggle Cline capabilities | Hooks, skills, auto-compact, sound notifications |
+| **Account** | Manage your Cline account | View account status, sign in/out, manage subscription |
+| **Other** | Additional preferences | Theme preferences, debug options |
+
+## Plan and Act Modes
+
+Cline operates in two modes, toggled with `Tab`. These modes work the same way in the CLI as they do in the VS Code extension. For a deeper explanation of how Plan and Act modes work, see the [Plan and Act documentation](/core-workflows/plan-and-act).
+
+### Plan Mode
+
+In Plan mode, Cline analyzes your request and creates a strategy before making changes. Use this when:
+- Exploring a new codebase
+- Working on complex refactoring
+- You want to review the approach first
+
+### Act Mode
+
+In Act mode, Cline executes tasks directly. Use this when:
+- You're confident in the task
+- Making straightforward changes
+- Running quick operations
+
+<Tip>
+Press `Tab` anytime to switch modes. Starting in Plan mode and switching to Act after reviewing is a common workflow.
+</Tip>
+
+## Auto-approve Toggle
+
+Press `Shift+Tab` to toggle auto-approve for all actions. This removes the approval prompts that appear before each action, letting Cline work continuously without interruption.
+
+### When to Enable Auto-approve
+
+Auto-approve is useful when:
+- **You trust the task** - Well-defined tasks where you're confident in the outcome
+- **Speed matters** - Long-running tasks where constant approvals slow you down
+- **You're watching anyway** - You can see Cline's work in real-time and can interrupt if needed
+- **Iterating quickly** - Rapid prototyping where you want to see results fast
+
+### What Gets Auto-approved
+
+When enabled, these actions happen without prompting:
+- File reads
+- File writes  
+- Command execution
+- Browser actions
+- MCP tool calls
+
+You can also configure granular auto-approve settings (e.g., auto-approve reads but not writes) via `/settings` → Auto-approve tab, or see the [Auto-approve documentation](/features/auto-approve) for more details.
+
+<Warning>
+Auto-approve gives Cline full autonomy. Use on a clean git branch so you can easily revert changes if needed. You can always press `Ctrl+C` to stop Cline immediately.
+</Warning>
+
+## Session Summary
+
+When you exit with `Ctrl+C`, Cline displays a session summary showing:
+- Tasks completed
+- Files modified
+- Commands executed
+- Token usage
+
+This helps you track what was accomplished during your session.
+
+## Running Multiple Instances
+
+By default, all CLI instances share the same settings and state. However, you may want to run isolated instances with separate configurations for scenarios like:
+
+- **Different models for different tasks** - Use a fast, cheap model for quick questions in one terminal and a more capable model for complex refactoring in another
+- **Separate work and personal projects** - Keep API keys, rules, and task history isolated between contexts
+- **Testing configuration changes** - Experiment with new settings without affecting your main setup
+- **Team vs. individual settings** - Use shared team configuration for work projects and personal preferences for side projects
+
+To run isolated instances, use the `--config` flag with different directories:
+
+```bash
+# Work instance with team configuration
+cline --config ~/.cline-work
+
+# Personal instance with different model/provider
+cline --config ~/.cline-personal
+
+# Experimental instance for testing new settings
+cline --config ~/.cline-test
+```
+
+Each config directory maintains its own provider settings, API keys, task history, and preferences.
+
+<Tip>
+Use terminal multiplexers like tmux or split terminals to run multiple Cline instances in parallel, each working on different parts of your project with different models or settings.
+</Tip>
+
+## Tips for Effective Usage
+
+### Start with Context
+
+Give Cline context about what you're working on:
+
+```text
+I'm building a REST API with Express. The routes are in @src/routes/ and models in @src/models/. Help me add user authentication.
+```
+
+### Use Plan Mode for Exploration
+
+When you're unsure about the best approach:
+
+```text
+[Tab to Plan mode]
+How should I structure the database schema for a multi-tenant SaaS app?
+```
+
+### Iterate with Follow-ups
+
+The interactive CLI maintains conversation context. Build on previous messages:
+
+```text
+> Add a login endpoint
+[Cline creates the endpoint]
+
+> Now add rate limiting to it
+[Cline modifies the same endpoint]
+
+> Add tests for both features
+[Cline creates test files]
+```
+
+## Next Steps
+
+<Columns cols={2}>
+  <Card title="Headless Mode" icon="robot" href="/cline-cli/three-core-flows">
+    Run Cline autonomously in scripts, CI/CD pipelines, and automated workflows.
+  </Card>
+  
+  <Card title="Configuration" icon="gear" href="/cline-cli/configuration">
+    Explore `cline config` and advanced configuration options.
+  </Card>
+</Columns>

docs/cline-cli/overview.mdx

@@ -0,0 +1,246 @@
+---
+title: "Overview"
+description: "Run Cline AI coding agents directly in your terminal with an interactive CLI or automated workflows"
+---
+
+## What is Cline CLI?
+
+Cline CLI brings the full power of Cline to your terminal. Whether you prefer an interactive experience or automated workflows for CI/CD pipelines, the CLI adapts to your needs.
+
+The CLI supports macOS, Linux, and Windows, and works with all the same AI providers as the VS Code extension.
+
+<Tip>
+Ready to get started? Check out the [installation guide](/cline-cli/installation) to install Cline CLI and run your first task.
+</Tip>
+
+## Two Ways to Use Cline CLI
+
+<Columns cols={2}>
+  <Card title="Interactive Mode" icon="terminal" href="/cline-cli/interactive-mode">
+    **For hands-on development.** Launch `cline` in your terminal and collaborate with Cline in real-time — chat, review plans, approve actions, and iterate on tasks with a rich visual interface.
+  </Card>
+  <Card title="Headless Mode" icon="robot" href="/cline-cli/three-core-flows">
+    **For automation & CI/CD.** Run `cline -y "task"` to let Cline work autonomously — no interaction needed. Pipe input/output, get JSON results, and chain commands in scripts and pipelines.
+  </Card>
+</Columns>
+
+The CLI operates in two distinct modes, automatically selecting the appropriate one based on how you invoke it:
+
+### Interactive Mode
+
+Interactive mode is designed for **hands-on development sessions** where you want to collaborate with Cline in real-time. It provides a rich terminal interface that feels like chatting with an AI assistant.
+
+**When it activates:** Running `cline` without arguments, or when stdin is a TTY (terminal).
+
+```bash
+cline
+```
+
+Key features:
+
+- **Real-time conversation** - Type messages, see Cline's responses, and iterate on tasks
+- **Visual feedback** - Animated welcome screen, syntax-highlighted code, and progress indicators
+- **File mentions** with `@` - Reference workspace files with fuzzy search autocomplete
+- **Slash commands** with `/` - Quick access to `/settings`, `/history`, `/models`, and workflows
+- **Keyboard shortcuts** - `Tab` to toggle Plan/Act, `Shift+Tab` for auto-approve all
+- **Session summaries** - See tasks completed, files modified, and token usage on exit
+- **Settings panel** - Configure providers, models, and features without leaving the CLI
+
+Interactive mode keeps you in control. You review Cline's plan, approve or modify actions, and guide the conversation.
+
+[Learn more about interactive mode →](/cline-cli/interactive-mode)
+
+### Headless Mode (Non-Interactive)
+
+Headless mode is designed for **automation, scripting, and CI/CD pipelines** where human interaction isn't possible or desired.
+
+**When it activates:** Using the `-y`/`--yolo` flag, `--json` flag, piping input/output, or when stdin is not a TTY.
+
+```bash
+# Headless with auto-approval (YOLO mode)
+cline -y "Run tests and fix any failures"
+
+# Headless with JSON output for parsing
+cline --json "List all TODO comments" | jq '.text'
+
+# Headless via piped input
+cat README.md | cline "Summarize this document"
+
+# Chain multiple headless commands
+git diff | cline -y "explain these changes" | cline -y "write a commit message"
+```
+
+Key features:
+
+- **No visual interface** - Clean text or JSON output suitable for scripting
+- **Automatic execution** - With `-y`, Cline approves all actions and runs autonomously
+- **Process control** - Exits automatically when the task completes
+- **Piped workflows** - Read from stdin, write to stdout, chain with other commands
+- **Machine-readable output** - Use `--json` to get structured output for parsing
+
+<Warning>
+Headless mode with `-y` gives Cline full autonomy. Run on a clean git branch so you can easily revert changes if needed.
+</Warning>
+
+### Mode Detection Summary
+
+Cline automatically detects which mode to use based on your invocation. This table shows how different command patterns trigger each mode, helping you predict behavior in scripts and interactive sessions.
+
+| Invocation | Mode | Reason |
+|------------|------|--------|
+| `cline` | Interactive | No arguments, TTY connected |
+| `cline "task"` | Interactive | TTY connected |
+| `cline -y "task"` | Headless | YOLO flag forces headless |
+| `cline --json "task"` | Headless | JSON flag forces headless |
+| `cat file \| cline "task"` | Headless | stdin is piped |
+| `cline "task" > output.txt` | Headless | stdout is redirected |
+
+[Learn more about headless mode →](/cline-cli/three-core-flows)
+
+## Supported Model Providers
+
+Cline CLI supports all providers available in the VS Code extension:
+
+- **Anthropic** (Claude)
+- **OpenAI** (GPT-4o, GPT-4)
+- **OpenAI Codex** (ChatGPT subscription)
+- **OpenRouter**
+- **AWS Bedrock**
+- **Google Gemini**
+- **X AI (Grok)**
+- **Cerebras**
+- **DeepSeek**
+- **Ollama** (local models)
+- **LM Studio** (local models)
+- **OpenAI Compatible** (any compatible API)
+
+During setup, authenticate with `cline auth` to configure your preferred provider. [See setup guide →](/cline-cli/installation#authenticate)
+
+## What You Can Build
+
+### Automated Code Maintenance
+
+Keep your codebase healthy with automated fixes. Cline scans for issues and applies corrections across multiple files.
+
+```bash
+cline -y "Fix all ESLint errors in src/"
+```
+Finds and fixes linting violations throughout your source directory.
+
+```bash
+cline -y "Update all deprecated React lifecycle methods"
+```
+Migrates legacy code patterns to modern equivalents (e.g., `componentWillMount` → `useEffect`).
+
+```bash
+cline -y "Update dependencies with known vulnerabilities"
+```
+Identifies outdated packages with security issues and updates them to safe versions.
+
+### CI/CD Integration
+
+Integrate Cline into your continuous integration pipelines for automated code review and documentation.
+
+```bash
+git diff origin/main | cline -y "Review these changes for issues"
+```
+Pipes your PR diff to Cline for automated code review, catching bugs and style issues before merge.
+
+```bash
+git log --oneline v1.0..v1.1 | cline -y "Write release notes"
+```
+Generates human-readable release notes from your commit history between two tags.
+
+```bash
+cline -y "Run tests and fix failures" --timeout 600
+```
+Executes your test suite, analyzes failures, and attempts fixes with a 10-minute timeout.
+
+### Development Workflows
+
+From quick edits to complex refactors, Cline adapts to your workflow.
+
+```bash
+cline
+```
+Launches interactive mode for exploratory development and back-and-forth collaboration.
+
+```bash
+cline "Refactor this function to use async/await"
+```
+Executes a focused task directly from the command line with approval prompts at key steps.
+
+```bash
+cline "Based on @src/api.ts, add error handling to all endpoints"
+```
+Uses file mentions (`@`) to give Cline context about specific files in your workspace.
+
+### Custom Shell Pipelines
+
+Chain Cline with other CLI tools to build powerful automation workflows.
+
+```bash
+gh pr diff 123 | cline -y "Review this PR"
+```
+Fetches a GitHub PR diff and pipes it directly to Cline for review.
+
+```bash
+cline --json "List all TODO comments" | jq '.text'
+```
+Outputs structured JSON that you can process with tools like `jq` for scripting.
+
+```bash
+git diff | cline -y "explain" | cline -y "write a haiku about these changes"
+```
+Chains multiple Cline invocations together for creative multi-step workflows.
+
+## Features at a Glance
+
+| Feature | Interactive Mode | Non-Interactive Mode |
+|---------|------------------|----------------------|
+| Interactive chat | ✓ | - |
+| File mentions (@) | ✓ | ✓ (inline) |
+| Slash commands (/) | ✓ | - |
+| Settings panel | ✓ | `cline config` |
+| Plan/Act toggle | ✓ (Tab) | `-p` / `-a` flags |
+| Auto-approve | ✓ (Shift+Tab) | `-y` flag |
+| Session summary | ✓ | - |
+| JSON output | - | `--json` |
+| Piped input | - | ✓ |
+| [MCP servers](/cline-cli/configuration#mcp-server-configuration) | ✓ | ✓ |
+
+## MCP Server Support
+
+Cline CLI supports [MCP (Model Context Protocol)](/mcp/mcp-overview) servers, the same extensibility system available in the VS Code extension. MCP servers give Cline access to external tools and data sources, from databases and APIs to browser automation and project management.
+
+To use MCP servers with the CLI, add your server configuration to `~/.cline/data/settings/cline_mcp_settings.json`. The format is identical to the VS Code extension.
+
+[Configure MCP servers for the CLI →](/cline-cli/configuration#mcp-server-configuration)
+
+## Learn More
+
+<Columns cols={2}>
+  <Card title="Installation & Setup" icon="download" href="/cline-cli/installation">
+    Install Cline CLI and authenticate with your preferred provider.
+  </Card>
+  
+  <Card title="Interactive Mode" icon="terminal" href="/cline-cli/interactive-mode">
+    Master the interactive CLI with keyboard shortcuts and slash commands.
+  </Card>
+  
+  <Card title="Headless Mode" icon="robot" href="/cline-cli/three-core-flows">
+    Run Cline autonomously in scripts, CI/CD pipelines, and automated workflows.
+  </Card>
+  
+  <Card title="Configuration" icon="gear" href="/cline-cli/configuration">
+    Configure settings, rules, workflows, and environment variables.
+  </Card>
+  
+  <Card title="Use in Other Editors" icon="code" href="/cline-cli/acp-editor-integrations">
+    Run Cline as an ACP agent in JetBrains, Neovim, Zed, and more.
+  </Card>
+  
+  <Card title="CLI Samples" icon="flask" href="/cline-cli/samples/overview">
+    Real-world examples of headless workflows and automation patterns.
+  </Card>
+</Columns>

docs/cline-cli/samples/github-integration.mdx

@@ -7,7 +7,7 @@ Automate GitHub issue analysis with AI. Mention `@cline` in any issue comment to
 
 
 <Note>
-**New to Cline CLI?** This sample assumes you understand Cline CLI basics and have completed the [Installation Guide](https://docs.cline.bot/getting-started/installing-cline). If you're new to Cline CLI, we recommend starting with the [GitHub RCA sample](./github-issue-rca) first, as it's simpler and will help you understand the fundamentals before setting up GitHub Actions.
+**New to Cline CLI?** This sample assumes you understand Cline CLI basics and have completed the [Installation Guide](https://docs.cline.bot/cline-cli/installation). If you're new to Cline CLI, we recommend starting with the [GitHub RCA sample](./github-issue-rca) first, as it's simpler and will help you understand the fundamentals before setting up GitHub Actions.
 </Note>
 
 ## The Workflow
@@ -32,7 +32,7 @@ Let's configure your repository.
 
 Before you begin, you'll need:
 
-- **Cline CLI knowledge** - Completed the [Installation Guide](https://docs.cline.bot/getting-started/installing-cline) and understand basic usage
+- **Cline CLI knowledge** - Completed the [Installation Guide](https://docs.cline.bot/cline-cli/installation) and understand basic usage
 - **GitHub repository** - With admin access to configure Actions and secrets
 - **GitHub Actions familiarity** - Basic understanding of workflows and CI/CD
 - **API provider account** - OpenRouter, Anthropic, or similar with API key
@@ -95,7 +95,7 @@ jobs:
 
       - name: Install Cline CLI
         if: steps.detect.outputs.hit == 'true'
-        run: npm install -g @cline/cli
+        run: npm install -g cline
 
       - name: Configure Cline Authentication
         if: steps.detect.outputs.hit == 'true'
@@ -120,6 +120,7 @@ jobs:
         env:
           ISSUE_URL: ${{ steps.detect.outputs.issue_url }}
           COMMENT: ${{ steps.detect.outputs.comment_body }}
+          CLINE_ADDRESS: ${{ env.CLINE_ADDRESS }}
         run: |
           set -euo pipefail
           
@@ -230,9 +231,10 @@ nano git-scripts/analyze-issue.sh  # or use vim, code, etc.
 # Analyze a GitHub issue using Cline CLI
 
 if [ -z "$1" ]; then
-    echo "Usage: $0 <github-issue-url> [prompt]"
+    echo "Usage: $0 <github-issue-url> [prompt] [address]"
     echo "Example: $0 https://github.com/owner/repo/issues/123"
     echo "Example: $0 https://github.com/owner/repo/issues/123 'What is the root cause of this issue?'"
+    echo "Example: $0 https://github.com/owner/repo/issues/123 'What is the root cause of this issue?'"
     exit 1
 fi
 
@@ -241,8 +243,9 @@ ISSUE_URL="$1"
 PROMPT="${2:-What is the root cause of this issue?}"
 
 # Ask Cline for its analysis, showing only the summary
-cline --auto-approve true --json "$PROMPT: $ISSUE_URL" | \
-    jq -r 'select(.type == "agent_event" and .event.type == "done") | .event.text' | \
+cline -y "$PROMPT: $ISSUE_URL" --mode act -F json | \
+    sed -n '/^{/,$p' | \
+    jq -r 'select(.say == "completion_result") | .text' | \
     sed 's/\\n/\n/g'
 ```
 
@@ -280,7 +283,7 @@ GitHub Actions will:
 1. Detect the `@cline` mention
 2. Start a Cline CLI instance
 3. Download the analysis script
-4. Analyze the issue using Act mode with auto-approval enabled
+4. Analyze the issue using act mode with yolo (fully autonomous)
 5. Post Cline's analysis as a new comment
 
 **Note**: The workflow only triggers on issue comments, not pull request
@@ -293,7 +296,7 @@ The workflow (`cline-responder.yml`):
 1. **Triggers** on issue comments (created or edited)
 2. **Detects** `@cline` mentions (case-insensitive)
 3. **Installs** Cline CLI globally using npm
-4. **Configures** authentication using `cline auth --provider openrouter --apikey ...`
+4. **Configures** authentication using `cline config set open-router-api-key=...`
 6. **Downloads** the reusable `analyze-issue.sh` script from the
    `github-issue-rca` sample
 7. **Runs** analysis in Cline CLI

docs/cline-cli/samples/github-issue-rca.mdx

@@ -6,7 +6,7 @@ description: "Automated GitHub issue analysis using Cline CLI to identify root c
 Automated GitHub issue analysis using Cline CLI. This script uses Cline's autonomous AI capabilities to fetch, analyze, and identify root causes of GitHub issues, outputting clean, parseable results that can be easily integrated into your development workflows.
 
 <Note>
-**New to Cline CLI?** This sample assumes you have already completed the [Installation Guide](https://docs.cline.bot/getting-started/installing-cline) and authenticated with `cline auth`. If you haven't set up Cline CLI yet, please start there first.
+**New to Cline CLI?** This sample assumes you have already completed the [Installation Guide](https://docs.cline.bot/cline-cli/installation) and authenticated with `cline auth`. If you haven't set up Cline CLI yet, please start there first.
 </Note>
 
 <Frame>
@@ -17,7 +17,7 @@ Automated GitHub issue analysis using Cline CLI. This script uses Cline's autono
 
 This sample assumes you have already:
 
-- **Cline CLI** installed and authenticated ([Installation Guide](https://docs.cline.bot/getting-started/installing-cline))
+- **Cline CLI** installed and authenticated ([Installation Guide](https://docs.cline.bot/cline-cli/installation))
 - **At least one AI model provider** configured (e.g., OpenRouter, Anthropic, OpenAI)
 - **Basic familiarity** with Cline CLI commands
 
@@ -80,18 +80,24 @@ curl -O https://raw.githubusercontent.com/cline/cline/main/src/samples/cli/githu
 # Analyze a GitHub issue using Cline CLI
 
 if [ -z "$1" ]; then
-    echo "Usage: $0 <github-issue-url> [prompt]"
+    echo "Usage: $0 <github-issue-url> [prompt] [address]"
     echo "Example: $0 https://github.com/owner/repo/issues/123"
     echo "Example: $0 https://github.com/owner/repo/issues/123 'What is the root cause of this issue?'"
+    echo "Example: $0 https://github.com/owner/repo/issues/123 'What is the root cause of this issue?' 127.0.0.1:46529"
     exit 1
 fi
 
 # Gather the args
 ISSUE_URL="$1"
 PROMPT="${2:-What is the root cause of this issue?}"
+if [ -n "$3" ]; then
+    ADDRESS="--address $3"
+fi
+
 # Ask Cline for its analysis, showing only the summary
-cline --auto-approve true --json "$PROMPT: $ISSUE_URL" | \
-    jq -r 'select(.type == "agent_event" and .event.type == "done") | .event.text' | \
+cline -y "$PROMPT: $ISSUE_URL" --mode act $ADDRESS -F json | \
+    sed -n '/^{/,$p' | \
+    jq -r 'select(.say == "completion_result") | .text' | \
     sed 's/\\n/\n/g'
 ```
 
@@ -127,6 +133,23 @@ Ask specific questions about the issue:
 ./analyze-issue.sh https://github.com/owner/repo/issues/456 "What is the security impact?"
 ```
 
+### Using Specific Cline Instance
+
+Target a particular Cline instance by address:
+
+```bash
+./analyze-issue.sh https://github.com/owner/repo/issues/123 \
+    "What is the root cause of this issue?" \
+    127.0.0.1:46529
+```
+
+<Warning>
+This is useful when:
+- Running multiple Cline instances
+- Using a remote Cline server
+- Testing with specific configurations
+</Warning>
+
 <Note>
 The script will automatically handle everything: fetching the issue, analyzing it with Cline, and displaying the results. The analysis typically takes 30-60 seconds depending on the issue complexity.
 </Note>
@@ -141,9 +164,10 @@ The script validates input and provides usage instructions:
 
 ```bash
 if [ -z "$1" ]; then
-    echo "Usage: $0 <github-issue-url> [prompt]"
+    echo "Usage: $0 <github-issue-url> [prompt] [address]"
     echo "Example: $0 https://github.com/owner/repo/issues/123"
     echo "Example: $0 https://github.com/owner/repo/issues/123 'What is the root cause?'"
+    echo "Example: $0 https://github.com/owner/repo/issues/123 'Analyze security impact' 127.0.0.1:46529"
     exit 1
 fi
 ```
@@ -152,6 +176,7 @@ fi
 - Validates required GitHub issue URL
 - Shows clear usage examples
 - Supports optional custom prompt
+- Supports optional Cline instance address
 
 ### Argument Parsing
 
@@ -161,12 +186,15 @@ The script extracts and sets up the arguments:
 # Gather the args
 ISSUE_URL="$1"
 PROMPT="${2:-What is the root cause of this issue?}"
+if [ -n "$3" ]; then
+    ADDRESS="--address $3"
+fi
 ```
 
 **Explanation:**
 - `ISSUE_URL="$1"` - First argument is always the issue URL
 - `PROMPT="${2:-...}"` - Second argument is optional, defaults to root cause analysis
-- The SDK CLI runs the task directly, so no address flag is required.
+- `ADDRESS` - Third argument is optional, only set if provided
 
 ### The Core Analysis Pipeline
 
@@ -174,26 +202,39 @@ This is where the magic happens:
 
 ```bash
 # Ask Cline for its analysis, showing only the summary
-cline --auto-approve true --json "$PROMPT: $ISSUE_URL" | \
-    jq -r 'select(.type == "agent_event" and .event.type == "done") | .event.text' | \
+cline -y "$PROMPT: $ISSUE_URL" --mode act $ADDRESS -F json | \
+    sed -n '/^{/,$p' | \
+    jq -r 'select(.say == "completion_result") | .text' | \
     sed 's/\\n/\n/g'
 ```
 
 <Accordion title="Pipeline Breakdown: Understanding Each Component">
 
-**1. `cline --auto-approve true --json "$PROMPT: $ISSUE_URL"`**
-   - `cline` is the Cline CLI binary
-   - Act mode is the default for prompt runs
-   - `--auto-approve true` allows tool use without interactive prompts
-   - `--json` emits newline-delimited JSON for parsing
+**1. `cline -y "$PROMPT: $ISSUE_URL"`**
+   - `-y` enables yolo mode (no user interaction)
    - Constructs prompt with issue URL
 
-**2. `jq -r 'select(.type == "agent_event" and .event.type == "done") | .event.text'`**
-   - Filters for the final agent `done` event
-   - Extracts the final text field
+**2. `--mode act`**
+   - Enables act mode for active investigation
+   - Allows Cline to use tools (read files, run commands, etc.)
+
+**3. `$ADDRESS`**
+   - Optional address flag for specific instance
+   - Expands to `--address <ip:port>` if set
+
+**4. `-F json`**
+   - Outputs in JSON format for parsing
+
+**5. `sed -n '/^{/,$p'`**
+   - Extracts JSON from output
+   - Skips any non-JSON prefix lines
+
+**6. `jq -r 'select(.say == "completion_result") | .text'`**
+   - Filters for completion result messages
+   - Extracts the text field
    - `-r` outputs raw strings (no JSON quotes)
 
-**3. `sed 's/\\n/\n/g'`**
+**7. `sed 's/\\n/\n/g'`**
    - Converts escaped newlines to actual newlines
    - Makes output readable
 
@@ -335,6 +376,6 @@ This pattern can be adapted for many other automation scenarios, from pull reque
 
 ## Related Resources
 
-- [CLI Installation Guide](https://docs.cline.bot/getting-started/installing-cline)
-- [CLI Reference Documentation](https://docs.cline.bot/cli/cli-reference)
-- [Headless Mode](https://docs.cline.bot/usage/cli-overview#headless-mode)
+- [CLI Installation Guide](https://docs.cline.bot/cline-cli/installation)
+- [CLI Reference Documentation](https://docs.cline.bot/cline-cli/cli-reference)
+- [Headless Mode](https://docs.cline.bot/cline-cli/three-core-flows)

docs/cline-cli/samples/github-pr-review.mdx

@@ -69,7 +69,7 @@ jobs:
           cache: "npm"
 
       - name: Install Cline CLI
-        run: npm install -g @cline/cli
+        run: npm install -g cline
 
       - name: Configure Cline Authentication
         # Replace 'anthropic' with your provider of choice (openai, openrouter, etc.)
@@ -110,7 +110,7 @@ jobs:
               ]
             }
         run: |
-          cline --auto-approve true 'You are a GitHub PR reviewer for this repository. Your goal is to give the PR author helpful feedback and give maintainers the context they need to review efficiently.
+          cline --yolo 'You are a GitHub PR reviewer for this repository. Your goal is to give the PR author helpful feedback and give maintainers the context they need to review efficiently.
 
           PR: #'"${PR_NUMBER}"'
 
@@ -175,11 +175,11 @@ cline auth --provider anthropic --apikey "..."
 ```
 The `auth` command configures Cline in the CI environment without interactive prompts. You can switch providers (e.g., `openai`, `openrouter`) by changing the flags.
 
-### Autonomous Mode (`--auto-approve true`)
+### Autonomous Mode (`--yolo`)
 ```bash
-cline --auto-approve true '...'
+cline --yolo '...'
 ```
-The `--auto-approve true` flag tells Cline to run autonomously, executing approved tools without waiting for interactive confirmation. Prompt runs start in Act mode by default, so CI/CD workflows can perform the requested work immediately.
+The `--yolo` flag tells Cline to run autonomously, executing commands without waiting for user approval. This is essential for CI/CD workflows.
 
 ### Command Permissions
 We explicitly restrict what commands Cline can run using `CLINE_COMMAND_PERMISSIONS`. This ensures Cline can only use `gh` and `git` commands relevant to reviewing, preventing any accidental or malicious system modifications.

docs/cline-cli/samples/model-orchestration.mdx

@@ -43,20 +43,20 @@ Use different models for different phases of work. Route simple tasks to cheap m
 ISSUE_CONTENT=$(gh issue view $(gh issue list -L 1 | awk '{print $1}'))
 
 # Phase 1: Quick summary with cheap model
-SUMMARY=$(echo "$ISSUE_CONTENT" | cline --auto-approve true --config ~/.cline-haiku \
+SUMMARY=$(echo "$ISSUE_CONTENT" | cline -y --config ~/.cline-haiku \
   "summarize this issue in 2-3 sentences")
 
 # Phase 2: Detailed plan with expensive model + thinking
-PLAN=$(echo "$SUMMARY" | cline --auto-approve true --thinking high --config ~/.cline-opus \
+PLAN=$(echo "$SUMMARY" | cline -y --thinking --config ~/.cline-opus \
   "create detailed implementation plan with edge cases")
 
 # Phase 3: Execute with mid-tier model
-echo "$PLAN" | cline --auto-approve true --config ~/.cline-sonnet \
+echo "$PLAN" | cline -y --config ~/.cline-sonnet \
   "implement the plan from above"
 ```
 
 <Note>
-Each `cline` invocation needs to complete before passing output to the next phase. Use shell variables to store intermediate results rather than piping `cline` commands directly.
+Each cline invocation needs to complete before passing output to the next phase. Use shell variables to store intermediate results rather than piping cline commands directly.
 </Note>
 
 **Cost impact:**
@@ -102,19 +102,19 @@ Get multiple AI perspectives on the same change, then synthesize their feedback.
 DIFF=$(git show)
 
 # Review 1: Gemini's perspective
-echo "$DIFF" | cline --auto-approve true --config ~/.cline-gemini \
+echo "$DIFF" | cline -y --config ~/.cline-gemini \
     "review this diff and write your analysis to gemini-review.md"
 
 # Review 2: Codex's perspective
-echo "$DIFF" | cline --auto-approve true --config ~/.cline-codex \
+echo "$DIFF" | cline -y --config ~/.cline-codex \
     "review this diff and write your analysis to codex-review.md"
 
 # Review 3: Opus's perspective
-echo "$DIFF" | cline --auto-approve true --config ~/.cline-opus \
+echo "$DIFF" | cline -y --config ~/.cline-opus \
     "review this diff and write your analysis to opus-review.md"
 
 # Synthesize all reviews into a consensus
-cat gemini-review.md codex-review.md opus-review.md | cline --auto-approve true \
+cat gemini-review.md codex-review.md opus-review.md | cline -y \
     "summarize these 3 reviews and identify: 1) issues all models agree on, 2) issues only one model caught, 3) your final recommendation"
 ```
 
@@ -130,19 +130,19 @@ Run reviews in parallel for faster feedback:
 
 ```bash
 # Run all reviews simultaneously
-git show | cline --auto-approve true --config ~/.cline-gemini "review and save to gemini-review.md" &
-git show | cline --auto-approve true --config ~/.cline-codex "review and save to codex-review.md" &
-git show | cline --auto-approve true --config ~/.cline-opus "review and save to opus-review.md" &
+git show | cline -y --config ~/.cline-gemini "review and save to gemini-review.md" &
+git show | cline -y --config ~/.cline-codex "review and save to codex-review.md" &
+git show | cline -y --config ~/.cline-opus "review and save to opus-review.md" &
 
 # Wait for all to complete
 wait
 
 # Synthesize
-cat *-review.md | cline --auto-approve true "create consensus review"
+cat *-review.md | cline -y "create consensus review"
 ```
 
 <Note>
-Parallel execution requires managing multiple Cline instances. See [Multi-instance workflows](/usage/cli-overview#automation-patterns) for details.
+Parallel execution requires managing multiple Cline instances. See [Multi-instance workflows](/cline-cli/three-core-flows#3-multi-instance-run-parallel-agents) for details.
 </Note>
 
 ## Extended Thinking for Complex Tasks
@@ -151,14 +151,14 @@ Use the `--thinking` flag when Cline needs to analyze multiple approaches:
 
 ```bash
 # Without thinking: Fast but may miss nuances
-cline --auto-approve true "refactor this codebase"
+cline -y "refactor this codebase"
 
 # With thinking: Slower but more thorough
-cline --auto-approve true --thinking high \
+cline -y --thinking \
     "refactor this codebase - consider: performance, maintainability, backward compatibility"
 ```
 
-The `--thinking <level>` flag sets reasoning effort. Use `--thinking high` or `--thinking xhigh` when you want the model to spend more effort on complex tradeoffs. Best for:
+The `--thinking` flag allocates 1024 tokens for internal reasoning before Cline responds. Best for:
 - Architectural decisions
 - Security analysis
 - Complex refactoring
@@ -178,12 +178,12 @@ The `--thinking <level>` flag sets reasoning effort. Use `--thinking high` or `-
 
 ```bash
 # Haiku: Quick summary and issue identification
-gh pr view $PR | cline --auto-approve true --config ~/.cline-haiku \
+gh pr view $PR | cline -y --config ~/.cline-haiku \
     "list all issues to fix, output as JSON"
 
 # Opus with thinking: Deep analysis only if issues found
 if [ -s issues.json ]; then
-    cline --auto-approve true --thinking high --config ~/.cline-opus \
+    cline -y --thinking --config ~/.cline-opus \
         "analyze these issues and recommend fixes"
 fi
 ```
@@ -192,31 +192,31 @@ fi
 
 ```bash
 # Different models have different security perspectives
-git diff main | cline --auto-approve true --config ~/.cline-gemini "security review" > gemini-sec.md &
-git diff main | cline --auto-approve true --config ~/.cline-opus "security review" > opus-sec.md &
-git diff main | cline --auto-approve true --config ~/.cline-codex "security review" > codex-sec.md &
+git diff main | cline -y --config ~/.cline-gemini "security review" > gemini-sec.md &
+git diff main | cline -y --config ~/.cline-opus "security review" > opus-sec.md &
+git diff main | cline -y --config ~/.cline-codex "security review" > codex-sec.md &
 wait
 
 # High-priority: Issues all 3 models found
-cat *-sec.md | cline --auto-approve true "find security issues all 3 reviews mentioned"
+cat *-sec.md | cline -y "find security issues all 3 reviews mentioned"
 ```
 
 ## Related Documentation
 
 <Columns cols={2}>
-  <Card title="CLI Reference" icon="terminal" href="/cli/cli-reference">
+  <Card title="CLI Reference" icon="terminal" href="/cline-cli/cli-reference">
     Complete documentation for --config and --thinking flags
   </Card>
   
-  <Card title="Headless Mode" icon="robot" href="/usage/cli-overview#headless-mode">
+  <Card title="Headless Mode" icon="robot" href="/cline-cli/three-core-flows">
     Run Cline autonomously in scripts, CI/CD pipelines, and automated workflows.
   </Card>
   
-  <Card title="Cline provider" icon="brain" href="/getting-started/cline-provider">
-    Fastest built-in model access setup and account workflow
+  <Card title="Model Selection Guide" icon="brain" href="/core-features/model-selection-guide">
+    Compare models and choose the right one for your needs
   </Card>
   
-  <Card title="CI/CD Integration" icon="github" href="/cli/samples/github-integration">
+  <Card title="CI/CD Integration" icon="github" href="/cline-cli/samples/github-integration">
     Automate GitHub workflows with Cline CLI
   </Card>
 </Columns>

docs/cline-cli/samples/overview.mdx

@@ -0,0 +1,56 @@
+---
+title: "Samples Overview"
+description: Example implementations demonstrating Cline CLI capabilities
+---
+
+This section provides sample implementations that demonstrate various Cline CLI features and capabilities. Each sample includes complete code, detailed explanations, and real-world usage examples.
+
+## Available Samples
+
+<CardGroup cols={1}>
+  <Card 
+    title="Model Orchestration" 
+    icon="layer-group" 
+    href="/cline-cli/samples/model-orchestration"
+  >
+    Use multiple AI models strategically with --config and --thinking flags. Optimize costs by routing simple tasks to cheap models and complex reasoning to premium models. Includes patterns for CI/CD code review, task phase optimization, and multi-model consensus.
+  </Card>
+
+  <Card 
+    title="Worktree Workflows" 
+    icon="code-branch" 
+    href="/cline-cli/samples/worktree-workflows"
+  >
+    Use Git worktrees with the --cwd flag to run parallel tasks, test different approaches, and pipe context between isolated environments. Includes patterns for parallel execution, cross-worktree piping, and combining with model orchestration.
+  </Card>
+
+  <Card 
+    title="GitHub Root Cause Analysis" 
+    icon="magnifying-glass-chart" 
+    href="/cline-cli/samples/github-issue-rca"
+  >
+    A command-line script that uses Cline's autonomous AI capabilities to fetch, analyze, and identify root causes of GitHub issues. Features JSON output parsing and non-interactive execution.
+  </Card>
+
+  <Card 
+    title="GitHub Integration (Actions)" 
+    icon="github" 
+    href="/cline-cli/samples/github-integration"
+  >
+    Automatically respond to GitHub issues by mentioning @cline in comments. Uses Cline CLI in GitHub Actions to create an AI-powered issue assistant that analyzes and responds autonomously.
+  </Card>
+
+  <Card 
+    title="GitHub PR Review (Actions)" 
+    icon="code-pull-request" 
+    href="/cline-cli/samples/github-pr-review"
+  >
+    Automatically review Pull Requests with AI. Configures Cline in GitHub Actions to analyze diffs, check for security issues, and post detailed reviews with inline code suggestions.
+  </Card>
+</CardGroup>
+
+## Additional Resources
+
+- [CLI Installation Guide](/cline-cli/installation)
+- [CLI Reference Documentation](/cline-cli/cli-reference)
+- [Headless Mode](/cline-cli/three-core-flows)

docs/cline-cli/samples/worktree-workflows.mdx

@@ -0,0 +1,273 @@
+---
+title: "Worktree Workflows"
+description: "Use Git worktrees with Cline CLI to run parallel tasks, test different approaches, and pipe context between isolated environments"
+---
+
+Git worktrees let you have multiple branches checked out simultaneously in different folders. Combined with Cline CLI's `--cwd` flag, this enables powerful parallel development workflows and isolated experimentation.
+
+<Tip>
+New to Git worktrees? See our comprehensive [Worktrees guide](/features/worktrees) for the full concept explanation, VS Code integration, and best practices.
+</Tip>
+
+## Quick Worktree Setup
+
+If you haven't used Git worktrees before, here's the essentials:
+
+```bash
+# Create a new worktree in ~/worktree-a on branch feature-a
+git worktree add ~/worktree-a -b feature-a
+
+# Create another worktree for a different feature
+git worktree add ~/worktree-b -b feature-b
+
+# List all worktrees
+git worktree list
+
+# Remove a worktree when done
+git worktree remove ~/worktree-a
+```
+
+Each worktree is a separate folder with its own branch checked out. They all share the same Git history and `.git` directory, but have independent working directories.
+
+## The `--cwd` Flag
+
+The `-c, --cwd <path>` flag tells Cline to run in a specific directory without changing your current location:
+
+```bash
+# Run Cline in a different directory
+cline --cwd ~/worktree-a -y "refactor the authentication code"
+
+# Short form
+cline -c ~/worktree-b -y "add unit tests"
+```
+
+This is the key to worktree workflows—you can run multiple Cline instances in different worktrees simultaneously from a single terminal.
+
+## Pattern 1: Parallel Task Execution
+
+Run different tasks in parallel across multiple worktrees. Each task works on a separate branch in complete isolation.
+
+### Example: Parallel Feature Development
+
+```bash
+# Terminal 1: Update docs in worktree-a
+cline --cwd ~/worktree-a -y "read the last 10 changes using git show and update our README with them" &
+
+# Terminal 2: TypeScript migration in worktree-b
+cline --cwd ~/worktree-b -y "update the index.js to use typescript" &
+
+# Terminal 3: Refactoring in worktree-c
+cline --cwd ~/worktree-c -y "refactor the cli/ folder to be more modular" &
+
+# Wait for all to complete
+wait
+```
+
+The `&` runs each command in the background, allowing all three to execute simultaneously.
+
+### When to Use Parallel Execution
+
+**Perfect for:**
+- Multiple independent features
+- Bulk refactoring across different modules
+- Running tests in one worktree while developing in another
+- Trying multiple approaches to the same problem
+
+**Not ideal for:**
+- Tasks that modify the same files (merge conflicts likely)
+- Tasks that depend on each other's results
+- When you need to monitor progress closely
+
+## Pattern 2: Cross-Worktree Context Piping
+
+Pipe output from one worktree as input to another. Use when a task in one worktree needs context from attempts in another worktree.
+
+### Example: Learning from Failures
+
+```bash
+# Try approach A in worktree-a, capture only the failure summary
+cline --cwd ~/worktree-a -y \
+  "edit the index.ts to be better and then npm run. if it fails, output ONLY the failure summary. nothing else but the failure summary" \
+  | cline --cwd ~/worktree-b -y \
+  "i've tried to edit the index.ts in a different worktree but it failed. use a different approach for this work tree"
+```
+
+**How it works:**
+1. First Cline instance runs in `worktree-a`, attempts a change, tests it
+2. If it fails, outputs just the failure summary
+3. That summary is piped to a second Cline instance in `worktree-b`
+4. Second instance sees the failure and tries a different approach
+
+### When to Use Context Piping
+
+**Perfect for:**
+- A/B testing different solutions
+- Learning from failed attempts
+- Iterative refinement (try → analyze → try differently)
+- Comparing outputs across approaches
+
+**Not ideal for:**
+- Simple tasks that don't need cross-context
+- When both worktrees would succeed independently
+- Real-time collaboration (use parallel execution instead)
+
+## Combining with Other CLI Features
+
+### Different Models Per Worktree
+
+Use `--config` to run different models in different worktrees:
+
+```bash
+# Cheap model for simple docs update
+cline --cwd ~/worktree-docs --config ~/.cline-haiku -y \
+  "update README with latest changes"
+
+# Expensive model for complex refactoring
+cline --cwd ~/worktree-refactor --config ~/.cline-opus --thinking -y \
+  "refactor authentication system for better security"
+```
+
+This optimizes costs while maintaining quality where it matters.
+
+### Task Isolation
+
+Keep long-running worktree sessions isolated by running each task against a different worktree path:
+
+```bash
+# Run tasks in dedicated worktrees
+cline --cwd ~/worktree-a -y "long-running task"
+cline --cwd ~/worktree-b -y "another task"
+```
+
+Each worktree has its own Git branch and working directory, so task history and changes stay separated without needing instance management.
+
+### With YOLO Mode
+
+The `-y` (YOLO) flag is essential for worktree workflows:
+
+```bash
+# Without -y: Opens interactive chat (blocks other tasks)
+cline --cwd ~/worktree-a "refactor code"
+
+# With -y: Runs autonomously (doesn't block)
+cline --cwd ~/worktree-a -y "refactor code" &
+```
+
+For parallel execution, always use `-y` to avoid blocking on user approval.
+
+## Real-World Workflow Example
+
+Here's a complete workflow showing how these patterns work together:
+
+```bash
+# Setup: Create three worktrees
+git worktree add ~/cline-worktrees/feature-auth -b feature/authentication
+git worktree add ~/cline-worktrees/feature-api -b feature/api-endpoints
+git worktree add ~/cline-worktrees/fix-tests -b fix/failing-tests
+
+# Pattern 1: Run parallel independent tasks
+cline -c ~/cline-worktrees/feature-auth -y --config ~/.cline-sonnet \
+  "implement JWT authentication" &
+
+cline -c ~/cline-worktrees/feature-api -y --config ~/.cline-sonnet \
+  "create REST API endpoints for user management" &
+
+cline -c ~/cline-worktrees/fix-tests -y --config ~/.cline-haiku \
+  "fix all failing unit tests" &
+
+wait
+echo "All parallel tasks complete!"
+
+# Pattern 2: Use piping for iterative refinement
+cline -c ~/cline-worktrees/feature-auth -y \
+  "test the authentication with curl. output only errors if any" \
+  | cline -c ~/cline-worktrees/feature-auth -y \
+  "fix the authentication issues described in the input"
+
+# Merge successful changes back
+cd ~/cline-worktrees/feature-auth
+git checkout main
+git merge feature/authentication
+
+# Cleanup
+git worktree remove ~/cline-worktrees/feature-auth
+```
+
+## Best Practices
+
+<AccordionGroup>
+  <Accordion title="Worktree Organization">
+    - **Use a dedicated folder**: Create `~/cline-worktrees/` for all worktrees
+    - **Meaningful branch names**: Use `feature/`, `fix/`, `refactor/` prefixes
+    - **Clean up regularly**: Remove worktrees after merging branches
+  </Accordion>
+
+  <Accordion title="Task Isolation">
+    - **Independent features only**: Don't parallelize tasks that touch the same files
+    - **Test in isolation**: Each worktree should have its own test run
+    - **Separate configs**: Use `.worktreeinclude` to copy `node_modules` and build artifacts
+  </Accordion>
+
+  <Accordion title="Resource Management">
+    - **Monitor disk space**: Each worktree is a full checkout
+    - **Limit parallel tasks**: Running too many simultaneously can slow your system
+    - **Use background jobs wisely**: Track with `jobs` command, kill with `kill %1`, etc.
+  </Accordion>
+
+  <Accordion title="Error Handling">
+    - **Check exit codes**: Use `|| echo "Task failed"` to catch errors
+    - **Log outputs**: Redirect to files for debugging: `> worktree-a.log 2>&1`
+    - **Graceful cleanup**: Always remove worktrees after tasks complete
+  </Accordion>
+</AccordionGroup>
+
+## Troubleshooting
+
+<AccordionGroup>
+  <Accordion title="&quot;Branch already checked out&quot; error">
+    Git doesn't allow the same branch in multiple worktrees. Solutions:
+    - Use different branch names for each worktree
+    - Remove the existing worktree first: `git worktree remove <path>`
+  </Accordion>
+
+  <Accordion title="Tasks not running in parallel">
+    Make sure you're using:
+    - `&` at the end of each command to background it
+    - `-y` flag so Cline doesn't wait for approval
+    - Different worktrees (not the same path)
+  </Accordion>
+
+  <Accordion title="Pipe not working as expected">
+    Verify:
+    - First command outputs to stdout (not stderr)
+    - Second command reads from stdin (use `--` separator if needed)
+    - Both commands use correct `--cwd` paths
+  </Accordion>
+
+  <Accordion title="Changes not appearing in worktree">
+    Check:
+    - You're in the right worktree: `git worktree list`
+    - Files aren't gitignored
+    - You committed/staged changes if needed
+  </Accordion>
+</AccordionGroup>
+
+## Related Documentation
+
+<Columns cols={2}>
+  <Card title="Worktrees Overview" icon="code-branch" href="/features/worktrees">
+    Complete guide to Git worktrees, VS Code integration, and .worktreeinclude
+  </Card>
+  
+  <Card title="Model Orchestration" icon="layer-group" href="/cline-cli/samples/model-orchestration">
+    Use different models strategically with --config and --thinking flags
+  </Card>
+  
+  <Card title="CLI Reference" icon="terminal" href="/cline-cli/cli-reference">
+    Complete documentation for --cwd and all other CLI flags
+  </Card>
+  
+  <Card title="Headless Mode" icon="robot" href="/cline-cli/three-core-flows">
+    Run Cline autonomously in scripts, CI/CD pipelines, and automated workflows.
+  </Card>
+</Columns>

docs/cline-cli/three-core-flows.mdx

@@ -0,0 +1,244 @@
+---
+title: "Headless Mode"
+description: "Run Cline autonomously in scripts, CI/CD pipelines, and automated workflows"
+---
+
+Headless mode runs Cline without an interactive interface — perfect for automation, scripting, and CI/CD pipelines where human interaction isn't possible or desired. Cline executes tasks, produces clean text or JSON output, and exits when complete.
+
+For collaborative, conversational development, see [Interactive Mode](/cline-cli/interactive-mode) instead.
+
+<Note>
+**Migrating from an older CLI version?** Instance commands (`cline instance new/list/kill`) have been removed in Cline CLI 2.0. The new architecture is simpler — just use `cline -y "task"` for headless execution.
+</Note>
+
+## When Headless Mode Activates
+
+Cline automatically enters headless mode when any of these conditions are met:
+
+| Invocation | Reason |
+|------------|--------|
+| `cline -y "task"` | `-y`/`--yolo` flag forces headless |
+| `cline --json "task"` | `--json` flag forces headless |
+| `cat file \| cline "task"` | stdin is piped |
+| `cline "task" > output.txt` | stdout is redirected |
+
+If none of these apply (e.g., running `cline` or `cline "task"` in a terminal), Cline launches in [interactive mode](/cline-cli/interactive-mode).
+
+## YOLO Mode (Fully Autonomous)
+
+The `-y` or `--yolo` flag enables fully autonomous operation — Cline approves all actions and runs without prompts:
+
+```bash
+cline -y "Run the test suite and fix any failures"
+```
+
+In YOLO mode:
+- All actions are auto-approved
+- Output is plain text (non-interactive)
+- Process exits automatically when complete
+- Perfect for CI/CD and scripts
+
+<Warning>
+YOLO mode gives Cline full autonomy. Run on a clean git branch so you can easily revert changes if needed.
+</Warning>
+
+### Mode Selection
+
+Control whether Cline plans first or acts immediately:
+
+```bash
+# Start in Plan mode (analyze before acting)
+cline -y -p "Design a REST API for user management"
+
+# Start in Act mode (default)
+cline -y -a "Fix the typo in README.md"
+```
+
+## Piping Context
+
+Pipe file contents or command output into Cline to provide context:
+
+```bash
+# Explain a file
+cat README.md | cline "Summarize this document"
+
+# Review git changes
+git diff | cline "Review these changes and suggest improvements"
+
+# Analyze command output
+npm test 2>&1 | cline "Analyze these test failures and fix them"
+
+# Pipe a GitHub PR diff
+gh pr diff 123 | cline -y "Review this PR"
+```
+
+When stdin is piped, Cline automatically enters headless mode — the piped content becomes part of the task context.
+
+## Chaining Commands
+
+Pipe Cline's output into another Cline instance for multi-step workflows:
+
+```bash
+# Explain changes, then write a commit message
+git diff | cline -y "explain these changes" | cline -y "write a commit message for this"
+
+# Generate code, then write tests
+cline -y "create a fibonacci function" | cline -y "write unit tests for this code"
+
+# Fun: Generate a poem about your code
+git diff | cline -y "explain" | cline -y "write a haiku about this"
+```
+
+## JSON Output
+
+Use `--json` for machine-readable output that's easy to parse in scripts:
+
+```bash
+cline --json "List all TODO comments in the codebase" | jq '.text'
+```
+
+JSON output follows the same format as task files in `~/.cline/data/tasks/<id>/ui_messages.json`.
+
+**JSON Message Schema:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `type` | `"ask"` or `"say"` | Message category |
+| `text` | `string` | Message content |
+| `ts` | `number` | Unix timestamp (ms) |
+| `reasoning` | `string` | (Optional) Model reasoning |
+| `partial` | `boolean` | (Optional) Streaming flag |
+
+## Including Images
+
+Attach images to your headless task:
+
+```bash
+cline -y -i screenshot.png "Fix the layout issue shown in this screenshot"
+
+# Or reference inline
+cline -y "Fix the UI shown in @./design-mockup.png"
+```
+
+## Timeout Control
+
+Set a maximum execution time to prevent runaway tasks:
+
+```bash
+cline -y --timeout 600 "Run full test suite"
+```
+
+## Environment Variables
+
+Control Cline behavior via environment variables — useful for CI/CD where you can't use interactive configuration.
+
+**CLINE_DIR** — Custom configuration directory:
+```bash
+export CLINE_DIR=/path/to/config
+cline -y "your task"
+```
+
+**CLINE_COMMAND_PERMISSIONS** — Restrict allowed commands:
+```bash
+export CLINE_COMMAND_PERMISSIONS='{"allow": ["npm *", "git *"], "deny": ["rm -rf *"]}'
+cline -y "your task"
+```
+
+See [Configuration](/cline-cli/configuration#environment-variables) for full documentation.
+
+## CI/CD Integration
+
+### GitHub Actions Example
+
+Automate PR reviews with Cline:
+
+```yaml
+name: AI Code Review
+
+on:
+  pull_request:
+    types: [opened, synchronize]
+
+jobs:
+  review:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+      
+      - name: Install Cline
+        run: npm install -g cline
+      
+      - name: Configure Cline
+        run: cline auth -p anthropic -k ${{ secrets.ANTHROPIC_API_KEY }}
+      
+      - name: Review PR
+        run: |
+          git diff origin/main...HEAD | cline -y "Review this PR for:
+          - Potential bugs
+          - Security issues  
+          - Performance concerns
+          - Code style violations
+          
+          Provide a summary of findings."
+```
+
+### Shell Script Example
+
+Create a reusable code review script:
+
+```bash
+#!/bin/bash
+# review.sh - AI-powered code review
+
+set -e
+
+# Get the diff
+DIFF=$(git diff HEAD~1)
+
+if [ -z "$DIFF" ]; then
+  echo "No changes to review"
+  exit 0
+fi
+
+# Run Cline review
+echo "$DIFF" | cline -y --json "Review this code diff for issues" | jq -r '.text'
+```
+
+## Common Use Cases
+
+| Use Case | Example |
+|----------|---------|
+| Code review | `git diff \| cline -y "Review these changes"` |
+| Fix test failures | `cline -y "Run tests and fix any failures"` |
+| Generate release notes | `git log --oneline v1.0..v1.1 \| cline -y "Write release notes"` |
+| Fix lint errors | `cline -y "Fix all ESLint errors in src/"` |
+| Update dependencies | `cline -y "Update dependencies with known vulnerabilities"` |
+| Migrate code patterns | `cline -y "Update all deprecated React lifecycle methods"` |
+| PR automation | `gh pr diff 123 \| cline -y "Review this PR"` |
+| Batch processing | `cline -y --json "List all TODO comments" \| jq '.text'` |
+
+## Next Steps
+
+<Columns cols={2}>
+  <Card title="Interactive Mode" icon="terminal" href="/cline-cli/interactive-mode">
+    For hands-on development with keyboard shortcuts, slash commands, and file mentions.
+  </Card>
+  
+  <Card title="CLI Reference" icon="book" href="/cline-cli/cli-reference">
+    Complete command documentation with all flags and options.
+  </Card>
+  
+  <Card title="Configuration" icon="gear" href="/cline-cli/configuration">
+    Environment variables, rules, and advanced settings.
+  </Card>
+  
+  <Card title="CLI Samples" icon="flask" href="/cline-cli/samples/overview">
+    Real-world examples of headless workflows and automation patterns.
+  </Card>
+</Columns>

docs/cline-overview.mdx

@@ -1,68 +0,0 @@
----
-title: "Cline Overview"
-sidebarTitle: "Cline Overview"
-description: "Your AI-powered coding agent for complex work. Read files, write code, run commands, all with your approval."
----
-
-Welcome to the Cline documentation. Whether you're just getting started or looking to unlock advanced capabilities, you'll find everything you need here.
-
-## What is Cline?
-
-Cline is an AI coding agent that lives in your editor and your terminal. It can read and write files, run terminal commands, use a browser, and help you build features through natural conversation. Every action requires your explicit approval. You're always in control.
-### Agent Core (SDK)
-
-The SDK is Cline's agent core—use it to build your own applications, automations, and integrations. See SDK section for detailed functionality and architectural design of the Cline Agent.
-
-<CardGroup cols={1}>
-  <Card title="SDK" icon="cube" href="https://docs.cline.bot/sdk/overview">
-    Build AI agents and integrations powered by the same core engine behind the CLI, Kanban, VS Code extension, and JetBrains plugin.
-
-    `npm install @cline/sdk`
-  </Card>
-</CardGroup>
-
-### Applications
-
-These are end-user applications built on top of Cline's agent core:
-
-<CardGroup cols={2}>
-  <Card title="CLI" icon="terminal" href="/usage/cli-overview">
-    Run Cline in your terminal with interactive chat or fully headless automation for CI/CD and scripting.
-
-    `npm i -g cline`
-  </Card>
-  <Card title="Kanban" icon="table-columns" href="https://github.com/cline/kanban">
-    Run many agents in parallel from a web-based task board with per-card worktrees, auto-commit, and dependency chains.
-
-    `npx kanban`
-  </Card>
-  <Card title="VS Code Extension" icon="code" href="https://marketplace.visualstudio.com/items?itemName=saoudrizwan.claude-dev">
-    AI coding assistant in your editor. Create files, run commands, browse the web, and use tools with human-in-the-loop approval.
-  </Card>
-  <Card title="JetBrains Plugin" icon="brain" href="https://plugins.jetbrains.com/plugin/27189-cline">
-    The same Cline experience in IntelliJ IDEA, PyCharm, WebStorm, GoLand, and the rest of the JetBrains family.
-  </Card>
-</CardGroup>
-
-
-## Other IDE Supports
-
-Cline works across all major editors: **VS Code**, **Cursor**, **Windsurf**, **JetBrains** (IntelliJ, PyCharm, WebStorm), **Antigravity**, and **Zed**, **Neovim** via ACP mode.
-
-
-## Enterprise Solutions
-
-<CardGroup cols={2}>
-  <Card title="Security & Governance" icon="shield-halved" href="/enterprise-solutions/overview">
-    SSO, role-based access control, model and tool controls per team, and remote configuration.
-  </Card>
-  <Card title="Observability" icon="chart-line" href="/enterprise-solutions/monitoring/overview">
-    OpenTelemetry, Datadog, Grafana, Splunk integrations with real-time analytics.
-  </Card>
-  <Card title="Team Management" icon="users-gear" href="/enterprise-solutions/team-management/managing-members">
-    Manage members, roles, and permissions across your organization.
-  </Card>
-  <Card title="API Reference" icon="code" href="/enterprise-solutions/api-reference">
-    Programmatic access to Cline's enterprise features.
-  </Card>
-</CardGroup>

docs/cline-sdk/overview.md

@@ -0,0 +1,769 @@
+---
+title: "Cline SDK"
+sidebarTitle: "SDK (Programmatic Use)"
+description: "Embed Cline as a programmable coding agent in your Node.js applications using an ACP-compatible TypeScript API."
+---
+
+# Cline SDK
+
+The Cline SDK lets you embed Cline as a programmable coding agent in your Node.js applications. It exposes the same capabilities as the Cline CLI and VS Code extension — file editing, command execution, browser use, MCP servers — through a TypeScript API that conforms to the [Agent Client Protocol (ACP)](https://agentclientprotocol.com/protocol/schema).
+
+## Installation
+
+```bash
+npm install cline
+```
+
+If you want direct ACP type imports as well:
+
+```bash
+npm install @agentclientprotocol/sdk
+```
+
+Requires Node.js 20+.
+
+## Quick Start
+
+```typescript
+import { ClineAgent } from "cline";
+
+const CLINE_DIR = "/Users/username/.cline";
+const agent = new ClineAgent({ clineDir: CLINE_DIR });
+
+// 1. Initialize — negotiates capabilities
+const initializeResponse = await agent.initialize({
+    protocolVersion: 1,
+    // these are the capabilities that the client (you) supports
+    // The cline agent may or may not use them, but it needs to know about them to make informed decisions about what tools to use.
+    clientCapabilities: {
+        fs: { readTextFile: true, writeTextFile: true },
+        terminal: true,
+    },
+});
+
+const { agentInfo, authMethods } = initializeResponse;
+console.log("Agent info:", agentInfo); // contains things like agent name and version
+console.log("Auth methods:", authMethods); // contains a list of supported authentication methods. More auth methods coming soon
+
+// 2. Authenticate if needed
+// If you skip this step, ClineAgent will look in CLINE_DIR for any existing credentials and authenticate with those
+await agent.authenticate({ methodId: "cline-oauth" });
+
+// 3. Create a session.
+// A session represents a conversation or task with the agent. You can have multiple sessions for different tasks or conversations.
+const { sessionId } = await agent.newSession({
+    cwd: process.cwd(),
+    mcpServers: [], // mcpServers field not supported yet, but exposed here to maintain conformance with acp protocol
+});
+
+// 4. Agent updates are sent via events. You can subscribe to these events to get real-time updates on the agent's progress, tool calls, and more.
+const emitter = agent.emitterForSession(sessionId);
+
+emitter.on("agent_message_chunk", (payload) => {
+    process.stdout.write(
+        payload.content.type === "text"
+            ? payload.content.text
+            : `[${payload.content.type}]`,
+    );
+});
+emitter.on("agent_thought_chunk", (payload) => {
+    process.stdout.write(
+        payload.content.type === "text"
+            ? payload.content.text
+            : `[${payload.content.type}]`,
+    );
+});
+emitter.on("tool_call", (payload) => {
+    console.log(`[tool] ${payload.title}`);
+});
+emitter.on("error", (err) => {
+    console.error("[session error]", err);
+});
+
+// 5. Send a prompt and wait for completion
+const { stopReason } = await agent.prompt({
+    sessionId,
+    prompt: [{ type: "text", text: "Create a hello world Express server" }],
+});
+
+console.log("Done:", stopReason);
+
+// 6. Clean up
+await agent.shutdown();
+
+```
+
+## Core Concepts
+
+### Agent Lifecycle
+
+The SDK follows the ACP lifecycle:
+
+```
+initialize() → authenticate() → newSession() → prompt() ⇄ events → shutdown()
+```
+
+| Step | Method | Purpose |
+|------|--------|---------|
+| Init | `initialize()` | Exchange protocol version and capabilities |
+| Auth | `authenticate()` | OAuth flow for Cline or OpenAI Codex accounts. Optional step if cline config directory already has credentials |
+| Session | `newSession()` | Create an isolated conversation context |
+| Prompt | `prompt()` | Send user messages; blocks until the turn ends |
+| Cancel | `cancel()` | Abort an in-progress prompt turn |
+| Mode | `setSessionMode()` | Switch between `"plan"` and `"act"` modes |
+| Model | `unstable_setSessionModel()` | Change the backing LLM (experimental) |
+| Shutdown | `shutdown()` | Abort all tasks, flush state, release resources |
+
+### Sessions
+
+A session is an independent conversation with its own task history and working directory. You can run multiple sessions concurrently.
+
+```typescript
+const { sessionId, modes, models } = await agent.newSession({
+  cwd: "/path/to/project",
+  mcpServers: [], // mcpServers field not supported yet, but exposed here to maintain conformance with acp protocol
+})
+```
+
+The response includes:
+- `sessionId` — use this in all subsequent calls
+- `modes` — available modes (`plan`, `act`) and the current mode
+- `models` — available models and the current model ID
+
+Access session metadata via the read-only `sessions` map:
+
+```typescript
+const session = agent.sessions.get(sessionId)
+// { sessionId, cwd, mode, mcpServers, createdAt, lastActivityAt, ... }
+```
+
+### Prompting
+
+`prompt()` sends a user message and blocks until the agent finishes its turn. While the prompt is processing, the agent streams output via session events.
+
+```typescript
+const response = await agent.prompt({
+  sessionId,
+  prompt: [
+    { type: "text", text: "Refactor the auth module to use JWT" },
+  ],
+})
+```
+
+The prompt array accepts multiple content blocks:
+
+```typescript
+// Text + image + file context
+await agent.prompt({
+  sessionId,
+  prompt: [
+    { type: "text", text: "What's in this screenshot?" },
+    { type: "image", data: base64ImageData, mimeType: "image/png" },
+    {
+      type: "resource",
+      resource: {
+        uri: "file:///path/to/relevant-file.ts",
+        mimeType: "text/plain",
+        text: fileContents,
+      },
+    },
+  ],
+})
+```
+
+#### Content Block Types
+
+| Type | Fields | Description |
+|------|--------|-------------|
+| `TextContent` | `{ type: "text", text: string }` | Plain text message |
+| `ImageContent` | `{ type: "image", mimeType: string, data: string }` | Base64-encoded image |
+| `EmbeddedResource` | `{ type: "resource", resource: { uri: string, mimeType?: string, text?: string, blob?: string } }` | File or resource context |
+
+#### Stop Reasons
+
+`prompt()` resolves with a `stopReason`. The ACP `StopReason` type defines the full set of possible values:
+
+| Value | Meaning |
+|-------|---------|
+| `"end_turn"` | Agent finished normally (completed task or waiting for user input) |
+| `"error"` | An error occurred |
+
+> **Note:** Cline currently returns `"end_turn"` or `"error"`. Other `StopReason` values like `"max_tokens"` or `"cancelled"` are part of the ACP type but may not be produced by the current implementation.
+
+### Streaming Events
+
+Subscribe to real-time output via `ClineSessionEmitter`. Each session has its own emitter.
+
+```typescript
+const emitter = agent.emitterForSession(sessionId)
+```
+
+#### Event Types
+
+All events correspond to [ACP `SessionUpdate` types](https://agentclientprotocol.com/protocol/schema#SessionUpdate):
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `agent_message_chunk` | `{ content: ContentBlock }` | Streamed text from the agent |
+| `agent_thought_chunk` | `{ content: ContentBlock }` | Internal reasoning / chain-of-thought |
+| `tool_call` | `ToolCall` | New tool invocation (file edit, command, etc.) |
+| `tool_call_update` | `ToolCallUpdate` | Progress/result update for an existing tool call |
+| `plan` | `{ entries: PlanEntry[] }` | Agent's execution plan |
+| `available_commands_update` | `{ availableCommands: AvailableCommand[] }` | Slash commands the agent supports |
+| `current_mode_update` | `{ currentModeId: string }` | Mode changed (plan/act) |
+| `user_message_chunk` | `{ content: ContentBlock }` | User message chunks (for multi-turn) |
+| `config_option_update` | `{ configOptions: SessionConfigOption[] }` | Configuration changed |
+| `session_info_update` | Session metadata | Session metadata changed |
+| `error` | `Error` | Session-level error (not an ACP update) |
+
+```typescript
+emitter.on("agent_message_chunk", (payload) => {
+  // payload.content is a ContentBlock — usually { type: "text", text: "..." }
+  process.stdout.write(payload.content.text)
+})
+
+emitter.on("agent_thought_chunk", (payload) => {
+  console.log("[thinking]", payload.content.text)
+})
+
+emitter.on("tool_call", (payload) => {
+  console.log(`[${payload.kind}] ${payload.title} (${payload.status})`)
+})
+
+emitter.on("tool_call_update", (payload) => {
+  console.log(`  → ${payload.toolCallId}: ${payload.status}`)
+})
+
+emitter.on("error", (err) => {
+  console.error("Session error:", err)
+})
+```
+
+The emitter supports `on`, `once`, `off`, and `removeAllListeners`.
+
+### Permission Handling
+
+When the agent wants to execute a tool (edit a file, run a command, etc.), it requests permission. You **must** set a permission handler or all tool calls will be auto-rejected.
+
+```typescript
+agent.setPermissionHandler(async (request) => {
+  // request.toolCall — details about what the agent wants to do
+  // request.options — available choices (allow_once, reject_once, etc.)
+
+  console.log(`Permission requested: ${request.toolCall.title}`)
+  console.log("Options:", request.options.map(o => `${o.optionId} (${o.kind})`))
+
+  // Auto-approve everything:
+  const allowOption = request.options.find(o => o.kind.includes("allow"))
+  if (allowOption) {
+    return { outcome: { outcome: "selected", optionId: allowOption.optionId } }
+  } else {
+    return { outcome: { outcome: "rejected" } }
+  }
+})
+```
+
+#### Permission Options
+
+Each permission request includes an array of `PermissionOption` objects:
+
+| `kind` | Meaning |
+|--------|---------|
+| `allow_once` | Approve this single operation |
+| `allow_always` | Approve and remember for future operations (sent for commands, tools, MCP servers) |
+| `reject_once` | Deny this single operation |
+
+**Important:** If no permission handler is set, all tool calls are rejected for safety.
+
+### Modes
+
+Cline supports two modes:
+
+- **`plan`** — The agent gathers information and creates a plan without executing actions
+- **`act`** — The agent executes actions (file edits, commands, etc.)
+
+```typescript
+// Switch to plan mode
+await agent.setSessionMode({ sessionId, modeId: "plan" })
+
+// Switch back to act mode
+await agent.setSessionMode({ sessionId, modeId: "act" })
+```
+
+The current mode is returned in `newSession()`
+
+### Model Selection
+
+Change the backing model with `unstable_setSessionModel()`. The model ID format is `"provider/modelId"`.
+
+```typescript
+await agent.unstable_setSessionModel({
+  sessionId,
+  modelId: "anthropic/claude-sonnet-4-20250514",
+})
+```
+
+This sets the model for both plan and act modes. Available providers include `anthropic`, `openai-native`, `gemini`, `bedrock`, `deepseek`, `mistral`, `groq`, `xai`, and others. Model Ids can be found in the NewSessionResponse object after calling `agent.newSession(..)`
+
+> **Note:** This API is experimental and may change. 
+
+### Authentication
+
+The SDK supports two OAuth flows:
+
+```typescript
+// Cline account (uses browser OAuth)
+await agent.authenticate({ methodId: "cline-oauth" })
+
+// OpenAI Codex / ChatGPT subscription
+await agent.authenticate({ methodId: "openai-codex-oauth" })
+```
+
+Both methods open a browser window for the OAuth flow and block until authentication completes (5-minute timeout for Cline OAuth).
+
+For BYO (bring-your-own) API key providers, you can pre-configure credentials using the Cline CLI before using the SDK:
+
+```bash
+# Configure an Anthropic API key (default directory: ~/.cline/data/)
+cline auth -p anthropic -k "sk-ant-..." -m anthropic/claude-sonnet-4-20250514
+
+# Configure an OpenRouter API key
+cline auth -p openrouter -k "sk-or-..." -m openrouter/anthropic/claude-sonnet-4
+```
+
+This writes credentials to `~/.cline/data/`. Once configured, the SDK will use these credentials automatically — no `authenticate()` call needed.
+
+**Using a custom directory:** If you specify a custom `clineDir` when creating `ClineAgent`, you must use the same path with `--config` when running `cline auth`:
+
+```typescript
+// SDK code using custom directory
+const agent = new ClineAgent({ clineDir: "/custom/path" })
+```
+
+```bash
+# CLI auth command must use the same path
+cline auth -p anthropic -k "sk-ant-..." -m anthropic/claude-sonnet-4-20250514 --config /custom/path
+```
+
+### Cancellation
+
+Cancel an in-progress prompt turn:
+
+```typescript
+await agent.cancel({ sessionId })
+```
+
+## API Reference
+
+### Constructor
+
+```typescript
+new ClineAgent(options: ClineAgentOptions)
+```
+
+```typescript
+interface ClineAgentOptions {
+  /** Enable debug logging (default: false) */
+  debug?: boolean
+  /** Custom Cline config directory (default: ~/.cline) */
+  clineDir?: string
+  /** Additional runtime hooks directory */
+  hooksDir?: string
+}
+```
+
+The `clineDir` option lets you isolate configuration and task history per-application:
+
+```typescript
+const agent = new ClineAgent({
+  clineDir: "/tmp/my-app-cline",
+})
+```
+
+### Methods
+
+#### `initialize(params): Promise<InitializeResponse>`
+
+Initialize the agent and negotiate protocol capabilities.
+
+```typescript
+const response = await agent.initialize({
+  clientCapabilities: {},
+  protocolVersion: 1,
+})
+
+// Response includes:
+{
+  protocolVersion: 1,
+  agentCapabilities: {
+    loadSession: true,
+    promptCapabilities: { image: true, audio: false, embeddedContext: true },
+    mcpCapabilities: { http: true, sse: false }
+  },
+  agentInfo: { name: "cline", version: "<installed_version>" },
+  authMethods: [
+    { id: "cline-oauth", name: "Sign in with Cline", description: "..." },
+    { id: "openai-codex-oauth", name: "Sign in with ChatGPT", description: "..." }
+  ]
+}
+```
+
+#### Client Capabilities
+
+The `clientCapabilities` object in `initialize()` declares what your environment supports. It is part of the ACP protocol handshake.
+
+| Capability | Type | Description |
+|------------|------|-------------|
+| `fs.readTextFile` | `boolean` | Client supports file read requests |
+| `fs.writeTextFile` | `boolean` | Client supports file write requests |
+| `terminal` | `boolean` | Client supports terminal command execution |
+
+**When using `ClineAgent` directly (SDK use)**, the agent always uses standalone providers for file operations and terminal commands — it reads/writes files and runs shell commands on the local machine regardless of what you pass here. Simply pass `{}`:
+
+```typescript
+await agent.initialize({ protocolVersion: 1, clientCapabilities: {} })
+```
+
+These capabilities only affect behavior when `ClineAgent` is used through the `AcpAgent` stdio wrapper (e.g., IDE integrations), where an ACP connection delegates operations back to the client.
+
+#### `newSession(params): Promise<NewSessionResponse>`
+
+Create a new conversation session.
+
+```typescript
+const session = await agent.newSession({
+  cwd: "/path/to/project",
+  mcpServers: [
+    {
+      type: "stdio",
+      name: "filesystem",
+      command: "npx",
+      args: ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"],
+      env: {},
+    },
+  ],
+})
+
+// Response includes:
+{
+  sessionId: "uuid-string",
+  modes: {
+    availableModes: [
+      { id: "plan", name: "Plan", description: "Gather information and create a detailed plan" },
+      { id: "act", name: "Act", description: "Execute actions to accomplish the task" }
+    ],
+    currentModeId: "act"
+  },
+  models: {
+    currentModelId: "anthropic/claude-sonnet-4-20250514",
+    availableModels: [{ modelId: "anthropic/claude-sonnet-4-20250514", name: "claude-sonnet-4-20250514" } /* ... */]
+  }
+}
+```
+
+> **Note:** `newSession()` may throw an auth-required error if credentials are not configured yet.
+
+#### `prompt(params): Promise<PromptResponse>`
+
+Send a user prompt to the agent. This is the main method for interacting with Cline. Blocks until the agent finishes its turn.
+
+```typescript
+const response = await agent.prompt({
+  sessionId: session.sessionId,
+  prompt: [
+    { type: "text", text: "Create a function that adds two numbers" },
+  ],
+})
+
+// Response: { stopReason: "end_turn" | "max_tokens" | "cancelled" | "error" }
+```
+
+#### `cancel(params): Promise<void>`
+
+Cancel an ongoing prompt operation.
+
+```typescript
+await agent.cancel({ sessionId: session.sessionId })
+```
+
+#### `setSessionMode(params): Promise<SetSessionModeResponse>`
+
+Switch between plan and act modes.
+
+```typescript
+await agent.setSessionMode({ sessionId, modeId: "plan" })
+```
+
+#### `unstable_setSessionModel(params): Promise<SetSessionModelResponse>`
+
+Change the model for the session. Model ID format depends on the inference provider. See NewSessionResponse object to get modelIds.
+
+```typescript
+await agent.unstable_setSessionModel({
+  sessionId,
+  modelId: "anthropic/claude-sonnet-4-20250514",
+})
+```
+
+#### `authenticate(params): Promise<AuthenticateResponse>`
+
+Authenticate with a provider. Opens a browser window for OAuth flow.
+
+```typescript
+await agent.authenticate({ methodId: "cline-oauth" })
+```
+
+Current methodIds we support:
+
+| methodId             | Description                   |
+| -------------------- | ----------------------------- |
+| `cline-oauth`        | use cline inference provider  |
+| `openai-codex-oauth` | use your chatgpt subscription |
+| more coming soon!... |                               |
+
+#### `shutdown(): Promise<void>`
+
+Clean up all resources. Call this when done.
+
+```typescript
+await agent.shutdown()
+```
+
+#### `setPermissionHandler(handler)`
+
+Set a callback to handle tool permission requests. The handler receives a `RequestPermissionRequest` and must return a `Promise<RequestPermissionResponse>`.
+
+```typescript
+agent.setPermissionHandler(async (request) => {
+  // request.toolCall — details about what the agent wants to do
+  // request.options — available choices (allow_once, reject_once, etc.)
+  const allow = request.options.find(o => o.kind === "allow_once")
+  return {
+    outcome: allow
+      ? { outcome: "selected", optionId: allow.optionId }
+      : { outcome: "cancelled" }
+  }
+})
+```
+
+#### `emitterForSession(sessionId): ClineSessionEmitter`
+
+Get the typed event emitter for a session.
+
+```typescript
+const emitter = agent.emitterForSession(session.sessionId)
+```
+
+#### `sessions` (read-only Map)
+
+Access active sessions:
+
+```typescript
+for (const [sessionId, session] of agent.sessions) {
+  console.log(sessionId, session.cwd, session.mode)
+}
+```
+
+## Error Handling
+
+SDK methods throw standard JavaScript errors. Key error scenarios:
+
+| Method | Error | Cause |
+|--------|-------|-------|
+| `newSession()` | `RequestError` (auth required) | No credentials configured — call `authenticate()` or pre-configure via CLI |
+| `prompt()` | `Error("Session not found")` | Invalid `sessionId` |
+| `prompt()` | `Error("already processing")` | Called `prompt()` while a previous prompt is still running on the same session |
+| `unstable_setSessionModel()` | `Error("Invalid modelId format")` | Model ID must be `"provider/modelId"` format (e.g., `"anthropic/claude-sonnet-4-20250514"`) |
+| `authenticate()` | `Error("Unknown authentication method")` | Invalid `methodId` — use `"cline-oauth"` or `"openai-codex-oauth"` |
+| `authenticate()` | `Error("Authentication timed out")` | OAuth flow not completed within 5 minutes |
+
+```typescript
+try {
+  const { sessionId } = await agent.newSession({ cwd: process.cwd(), mcpServers: [] })
+} catch (error) {
+  if (error.message?.includes("auth")) {
+    // Need to authenticate first
+    await agent.authenticate({ methodId: "cline-oauth" })
+  }
+}
+```
+
+Session-level errors during `prompt()` execution are emitted on the session emitter rather than thrown:
+
+```typescript
+emitter.on("error", (err) => {
+  console.error("Session error:", err.message)
+})
+```
+
+## Full Example: Auto-Approve Agent
+
+```typescript
+import { ClineAgent } from "cline";
+
+async function runTask(taskPrompt: string, cwd: string) {
+    const agent = new ClineAgent({ clineDir: "/path/to/.cline" });
+
+    await agent.initialize({
+        protocolVersion: 1,
+        clientCapabilities: {},
+    });
+
+    const { sessionId } = await agent.newSession({ cwd, mcpServers: [] });
+
+    // Auto-approve all tool calls
+    agent.setPermissionHandler(async (request) => {
+        const allow = request.options.find((o) => o.kind === "allow_once");
+        return {
+            outcome: allow
+                ? { outcome: "selected", optionId: allow.optionId }
+                : { outcome: "cancelled" },
+        };
+    });
+
+    // Collect output
+    const output: string[] = [];
+    const emitter = agent.emitterForSession(sessionId);
+
+    emitter.on("agent_message_chunk", (p) => {
+        if (p.content.type === "text") output.push(p.content.text);
+    });
+
+    emitter.on("tool_call", (p) => {
+        console.log(`[tool] ${p.title}`);
+    });
+
+    const { stopReason } = await agent.prompt({
+        sessionId,
+        prompt: [{ type: "text", text: taskPrompt }],
+    });
+
+    console.log("\n--- Agent Output ---");
+    console.log(output.join(""));
+    console.log(`\nStop reason: ${stopReason}`);
+
+    await agent.shutdown();
+}
+
+runTask("Create a README.md for this project", process.cwd());
+```
+
+## Full Example: Interactive Permission Flow
+
+```typescript
+import { ClineAgent, type PermissionHandler } from "cline";
+import * as readline from "readline";
+
+const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+});
+const ask = (q: string) => new Promise<string>((res) => rl.question(q, res));
+
+const interactivePermissions: PermissionHandler = async (request) => {
+    console.log(`\n⚠️  Permission: ${request.toolCall.title}`);
+
+    for (const [i, opt] of request.options.entries()) {
+        console.log(`  ${i + 1}. [${opt.kind}] ${opt.name}`);
+    }
+
+    const choice = await ask("Choose (number): ");
+    const idx = parseInt(choice, 10) - 1;
+    const selected = request.options[idx];
+
+    if (selected) {
+        return {
+            outcome: { outcome: "selected", optionId: selected.optionId },
+        };
+    } else {
+        return { outcome: { outcome: "cancelled" } };
+    }
+};
+
+async function main() {
+    const agent = new ClineAgent({});
+    await agent.initialize({ protocolVersion: 1, clientCapabilities: {} });
+
+    const { sessionId } = await agent.newSession({
+        cwd: process.cwd(),
+        mcpServers: [],
+    });
+
+    agent.setPermissionHandler(interactivePermissions);
+
+    const emitter = agent.emitterForSession(sessionId);
+    emitter.on("agent_message_chunk", (p) => {
+        if (p.content.type === "text") process.stdout.write(p.content.text);
+    });
+
+    // Multi-turn conversation
+    while (true) {
+        const userInput = await ask("\n> ");
+        if (userInput === "exit") break;
+
+        const { stopReason } = await agent.prompt({
+            sessionId,
+            prompt: [{ type: "text", text: userInput }],
+        });
+
+        console.log(`\n[${stopReason}]`);
+    }
+
+    await agent.shutdown();
+    rl.close();
+}
+
+main();
+
+```
+
+## Exported Types
+
+All types are re-exported from the `cline` package. Key types:
+
+| Type | Description |
+|------|-------------|
+| `ClineAgent` | Main agent class |
+| `ClineSessionEmitter` | Typed event emitter for session events |
+| `ClineAgentOptions` | Constructor options (`debug`, `clineDir`, `hooksDir`) |
+| `ClineAcpSession` | Session metadata (read-only) |
+| `ClineSessionEvents` | Event name → handler signature map |
+| `AcpSessionStatus` | Session lifecycle enum: `Idle`, `Processing`, `Cancelled` |
+| `AcpSessionState` | Session state tracking (status, pending tool calls) |
+| `PermissionHandler` | `(request: RequestPermissionRequest) => Promise<RequestPermissionResponse>` |
+| `RequestPermissionRequest` | Permission request details (sessionId, toolCall, options) |
+| `RequestPermissionResponse` | Permission response with outcome |
+| `PermissionOption` | Permission choice (`kind`, `optionId`, `name`) |
+| `SessionUpdate` | Union of all session update types |
+| `SessionUpdateType` | Discriminator values (`"agent_message_chunk"`, `"tool_call"`, etc.) |
+| `SessionUpdatePayload` | Typed payload for a given `SessionUpdateType` |
+| `SessionModelState` | Current model and available models |
+| `ToolCall` | Tool call details (id, title, kind, status, content) |
+| `ToolCallUpdate` | Partial update to an existing tool call |
+| `ToolCallStatus` | `"pending" \| "in_progress" \| "completed" \| "failed"` |
+| `ToolKind` | `"read" \| "edit" \| "delete" \| "execute" \| "search" \| ...` |
+| `StopReason` | `"end_turn" \| "cancelled" \| "error" \| "max_tokens" \| ...` |
+| `ContentBlock` | `TextContent \| ImageContent \| AudioContent \| ...` |
+| `TextContent` / `ImageContent` / `AudioContent` | Individual content block types |
+| `McpServer` | MCP server configuration (stdio, http) |
+| `ModelInfo` | Model metadata (`modelId`, `name`) |
+| `PromptRequest` / `PromptResponse` | Prompt call types |
+| `NewSessionRequest` / `NewSessionResponse` | Session creation types |
+| `InitializeRequest` / `InitializeResponse` | Initialization types |
+| `SetSessionModeRequest` / `SetSessionModeResponse` | Mode switching types |
+| `SetSessionModelRequest` / `SetSessionModelResponse` | Model switching types |
+| `TranslatedMessage` | Result of translating a Cline message to ACP updates |
+
+See the [ACP Schema](https://agentclientprotocol.com/protocol/schema) for the full type definitions.
+
+## Relationship to ACP
+
+The Cline SDK implements the [Agent Client Protocol](https://agentclientprotocol.com) `Agent` interface. The key difference from a standard ACP stdio agent is that the SDK uses an **event emitter pattern** instead of a transport connection:
+
+| ACP Stdio (via `AcpAgent`) | SDK (via `ClineAgent`) |
+|-----------------------------|------------------------|
+| Session updates sent over JSON-RPC stdio | Session updates emitted via `ClineSessionEmitter` |
+| Permissions requested via `connection.requestPermission()` | Permissions requested via `setPermissionHandler()` callback |
+| Single process, single connection | Embeddable, multiple concurrent sessions |
+
+If you need stdio-based ACP communication (e.g., for IDE integration), use the `cline` CLI binary directly. The SDK is for embedding Cline in your own Node.js processes.

docs/contributing/doc-templates.mdx

@@ -0,0 +1,316 @@
+---
+title: "Documentation Templates"
+sidebarTitle: "Templates"
+description: "Templates for different types of Cline documentation"
+---
+
+Use these templates as starting points for new documentation. Each template is designed for a specific purpose. Choose the one that best fits what you're documenting.
+
+## Choosing a Template
+
+| If you're documenting... | Use this template |
+|--------------------------|-------------------|
+| What a feature does and how to use it | Feature Doc |
+| How to accomplish a specific task | How-To Guide |
+| Technical specifications or API details | Reference Doc |
+| A complete project walkthrough | Tutorial |
+
+## Feature Doc
+
+Use this template when explaining a Cline feature. Focus on what it does, how to use it, and real examples.
+
+````text
+---
+title: "Feature Name"
+sidebarTitle: "Feature Name"
+---
+
+[One sentence explaining what this feature does.]
+
+<Frame>
+  <img src="..." alt="Feature in action" />
+</Frame>
+
+[1-2 paragraphs explaining the feature in plain terms. What problem does it 
+solve? Why would someone use it?]
+
+## How It Works
+
+[Explain the mechanics without jargon. What happens when you use this feature?]
+
+## Using [Feature Name]
+
+[Show how to access and use it. Include the exact UI path.]
+
+### [Option or Variation 1]
+
+[Details with examples]
+
+### [Option or Variation 2]
+
+[Details with examples]
+
+## Inspiration
+
+[Share how you personally use this feature. Use "I" voice. Give 2-3 real 
+examples that spark imagination about what's possible.]
+
+<Note>
+  [Important caveat, limitation, or requirement]
+</Note>
+````
+
+### Example: Checkpoints Feature
+
+Here's how the [Checkpoints](/core-workflows/checkpoints) doc follows this pattern:
+
+- Opens with one clear sentence about what checkpoints do
+- Shows a screenshot of the feature in action
+- Explains how checkpoints work under the hood
+- Shows exact steps to create and restore checkpoints
+- Includes real examples of when checkpoints save the day
+
+## How-To Guide
+
+Use this template when showing how to accomplish a specific task. Focus on clear steps and troubleshooting.
+
+````text
+---
+title: "How to [Accomplish Task]"
+sidebarTitle: "[Short Title]"
+description: "[One sentence describing what the reader will learn]"
+---
+
+[Brief intro explaining what problem this guide solves and what you'll end up 
+with after following it.]
+
+## Prerequisites
+
+[What the reader needs before starting. Keep it short. Link to other docs 
+rather than explaining setup here.]
+
+- Cline installed and configured
+- [Other requirement]
+
+## Steps
+
+<Steps>
+  <Step title="[First Action]">
+    [Clear instructions. Show exactly what to click or type.]
+    
+    ```bash
+    example command if needed
+    ```
+  </Step>
+  <Step title="[Second Action]">
+    [Next step. Include screenshots for complex UI interactions.]
+    
+    <Frame>
+      <img src="..." alt="What you should see" />
+    </Frame>
+  </Step>
+  <Step title="[Final Action]">
+    [Complete the task. Show the expected result.]
+  </Step>
+</Steps>
+
+## Troubleshooting
+
+Common issues and how to fix them:
+
+- **Problem description**: Solution in one or two sentences.
+- **Another problem**: Another solution.
+
+## Next Steps
+
+<Card title="Related Feature" icon="arrow-right" href="/path/to/related">
+  Continue learning with this related guide.
+</Card>
+````
+
+### Example: Your First Project
+
+The [Your First Project](/getting-started/your-first-project) guide follows this pattern:
+
+- Clear goal stated upfront
+- Prerequisites listed briefly
+- Step-by-step instructions with the Steps component
+- Troubleshooting section for common issues
+
+## Reference Doc
+
+Use this template for technical specifications, API documentation, or detailed configuration options.
+
+````text
+---
+title: "[Component/API] Reference"
+sidebarTitle: "[Short Title]"
+description: "[What this reference covers]"
+---
+
+[Brief description of what this reference documents and when you'd need it.]
+
+## Overview
+
+[High-level explanation. What is this component? What role does it play?]
+
+## [Category 1]
+
+### [Item Name]
+
+[What it does in one sentence.]
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `propertyName` | `string` | `"default"` | What this property controls |
+| `anotherProp` | `boolean` | `false` | What this does |
+
+**Example:**
+
+```typescript
+// Show practical usage
+const example = {
+  propertyName: "custom value",
+  anotherProp: true
+}
+```
+
+### [Another Item]
+
+[Continue for each item in this category.]
+
+## [Category 2]
+
+[Continue with other categories as needed.]
+
+## Examples
+
+[Show 2-3 complete, practical examples that combine multiple concepts.]
+
+### [Example 1 Title]
+
+```typescript
+// Complete working example
+```
+
+### [Example 2 Title]
+
+```typescript
+// Another complete example
+```
+
+## Related
+
+- [Related Doc 1](/path/to/doc) - Brief description
+- [Related Doc 2](/path/to/doc) - Brief description
+````
+
+### Example: Cline Tools Guide
+
+The [Cline Tools Guide](/tools-reference/all-cline-tools) follows this pattern:
+
+- Overview of the tool system
+- Each tool documented with parameters and examples
+- Practical examples showing tools in context
+
+## Tutorial
+
+Use this template for comprehensive project walkthroughs where users build something from start to finish.
+
+````text
+---
+title: "[Build/Create X] Tutorial"
+sidebarTitle: "[Short Title]"
+description: "[What the reader will build]"
+---
+
+In this tutorial, you'll build [specific outcome]. By the end, you'll have 
+[tangible result you can see/use].
+
+<Frame>
+  <img src="..." alt="Preview of what you'll build" />
+</Frame>
+
+## What You'll Learn
+
+- [Skill or concept 1]
+- [Skill or concept 2]
+- [Skill or concept 3]
+
+## Prerequisites
+
+[Required setup. Link to installation guides rather than repeating them.]
+
+- [Prerequisite 1]
+- [Prerequisite 2]
+
+## Part 1: [First Major Section]
+
+[Introduction to this section. What are we doing and why?]
+
+### [Subsection]
+
+[Detailed walkthrough with code blocks and explanations.]
+
+```typescript
+// Code that the reader should write or understand
+```
+
+[Explain what the code does and why.]
+
+## Part 2: [Second Major Section]
+
+[Continue building on Part 1.]
+
+### [Subsection]
+
+[More detailed walkthrough.]
+
+## Part 3: [Final Section]
+
+[Complete the project.]
+
+## Summary
+
+You built [what they built]. Along the way, you learned:
+
+- [Key takeaway 1]
+- [Key takeaway 2]
+- [Key takeaway 3]
+
+## Next Steps
+
+<CardGroup cols={2}>
+  <Card title="Go Deeper" icon="book" href="/path/to/advanced">
+    Learn more advanced techniques.
+  </Card>
+  <Card title="Related Tutorial" icon="code" href="/path/to/related">
+    Build something else with similar concepts.
+  </Card>
+</CardGroup>
+````
+
+### Example Structure
+
+A good tutorial:
+- Shows the end result upfront so readers know what they're building
+- Breaks the work into logical parts
+- Explains the "why" alongside the "how"
+- Ends with clear next steps
+
+## Quick Tips
+
+When using these templates:
+
+1. **Delete sections you don't need.** Templates are starting points, not rigid structures.
+
+2. **Add sections that make sense.** If your doc needs something not in the template, add it.
+
+3. **Keep the reader moving forward.** Every section should lead naturally to the next.
+
+4. **Test your own instructions.** Follow your guide from scratch to catch missing steps.
+
+<Tip>
+  Use the `/write-docs` workflow to generate documentation from these templates automatically. 
+  Cline helps you fill in each section based on your project.
+</Tip>

docs/contributing/documentation-guide.mdx

@@ -0,0 +1,200 @@
+---
+title: "Documentation Guide"
+sidebarTitle: "Documentation Guide"
+description: "How to write and contribute to Cline documentation"
+---
+
+Cline's documentation lives in the `docs/` directory and uses [Mintlify](https://mintlify.com) for rendering. This guide covers how to write docs that match Cline's established style.
+
+## Using the Documentation Workflow
+
+The fastest way to create documentation is using the `/write-docs` workflow. Type `/write-docs` in Cline and describe what you want to document. Cline guides you through a 4-step process:
+
+1. **Research**: Examine existing docs structure and patterns
+2. **Scope**: Clarify audience, doc type, and key use cases
+3. **Outline**: Select a template and create structure
+4. **Write**: Generate documentation following style guidelines
+
+The workflow file lives at `.clinerules/workflows/write-docs.md` and contains templates, style rules, and examples.
+
+## Documentation Principles
+
+### Write for Developers
+
+Your audience is developers who value their time. Get to the point. Every sentence should either help them understand something or help them do something.
+
+```markdown
+# Good
+Switch to bash in Cline Settings → Terminal → Default Terminal Profile.
+
+# Bad
+Users who are experiencing issues may find it helpful to navigate to the 
+Cline settings menu where they can locate the terminal configuration 
+options and subsequently modify the default terminal profile setting.
+```
+
+### Show Real Examples
+
+Abstract descriptions don't help anyone. Show actual code, real file paths, and concrete implementations.
+
+```markdown
+# Good
+I use `/deep-planning` whenever I'm building features that touch multiple 
+parts of the codebase. For example, when adding authentication, Cline 
+mapped every endpoint and created a migration plan that avoided breaking changes.
+
+# Bad
+The deep planning feature can be utilized for various complex tasks 
+that may require careful consideration and planning.
+```
+
+### Use Active Voice
+
+Cline does things. Files don't get created by Cline, Cline creates files.
+
+```markdown
+# Good
+Cline reads your project files and builds context automatically.
+
+# Bad
+Project files are read and context is built automatically.
+```
+
+### Use Neutral Pronouns for Cline
+
+Refer to Cline as "it" not "he". Cline is software, not a person.
+
+```markdown
+# Good
+When Cline encounters an error, it suggests fixes.
+
+# Bad
+When Cline encounters an error, he suggests fixes.
+```
+
+## File Format
+
+All documentation uses MDX format with YAML frontmatter:
+
+```yaml
+---
+title: "Full Page Title"
+sidebarTitle: "Shorter Nav Title"  # optional
+description: "One sentence for SEO"  # optional but recommended
+---
+```
+
+### Adding New Pages
+
+After creating a new `.mdx` file, add it to `docs/docs.json` in the appropriate navigation group:
+
+```json
+{
+  "group": "Features",
+  "pages": [
+    "features/existing-page",
+    "features/your-new-page"
+  ]
+}
+```
+
+## Mintlify Components
+
+Use these components appropriately throughout your docs.
+
+### Frame
+
+Wrap all images and videos:
+
+```jsx
+<Frame>
+  <img 
+    src="https://storage.googleapis.com/cline_public_images/docs/assets/filename.png" 
+    alt="Descriptive alt text" 
+  />
+</Frame>
+```
+
+### Callouts
+
+Use sparingly and purposefully:
+
+```jsx
+<Tip>Helpful suggestions that improve the experience.</Tip>
+<Note>Important information the reader needs to know.</Note>
+<Warning>Something that could cause problems if ignored.</Warning>
+```
+
+### Steps
+
+For sequential procedures:
+
+```jsx
+<Steps>
+  <Step title="Install the Extension">
+    Search for "Cline" in the VS Code marketplace.
+  </Step>
+  <Step title="Configure Your Model">
+    Open settings and add your API key.
+  </Step>
+</Steps>
+```
+
+### Cards
+
+For navigation and feature overviews:
+
+```jsx
+<CardGroup cols={2}>
+  <Card title="Getting Started" icon="rocket" href="/getting-started/installing-cline">
+    Install Cline and set up your first project.
+  </Card>
+  <Card title="Features" icon="wand-magic-sparkles" href="/core-workflows/plan-and-act">
+    Explore what Cline can do.
+  </Card>
+</CardGroup>
+```
+
+## Style Rules
+
+Quick reference for consistent documentation:
+
+| Do | Don't |
+|---|---|
+| Use "use" | Use "utilize" |
+| Keep sentences under 25 words | Write run-on sentences |
+| Use bullet points for lists | Write walls of text |
+| Show where things are in the UI | Assume users can find features |
+| Cross-link related docs | Leave readers stranded |
+| Use code blocks with language tags | Use inline code for long snippets |
+
+### Avoid These Patterns
+
+- Em dashes and emojis
+- Starting with "This document explains..."
+- The **Bold Text**: description pattern
+- Explaining obvious things
+- Passive voice
+
+## Previewing Changes
+
+Run the docs locally to preview your changes:
+
+```bash
+cd docs
+npm install  # first time only
+npm run dev
+```
+
+Open `http://localhost:3000` to see your changes in real time.
+
+## Related Resources
+
+<CardGroup cols={2}>
+  <Card title="Documentation Templates" icon="file-lines" href="/contributing/doc-templates">
+    Templates for different documentation types.
+  </Card>
+  <Card title="Workflows" icon="diagram-project" href="/customization/workflows">
+    Learn about Cline's workflow system.
+  </Card>
+</CardGroup>

docs/core-features/model-selection-guide.mdx

@@ -0,0 +1,220 @@
+---
+title: "Model Selection Guide"
+description: "Choose the right AI model for your workflow based on reliability, speed, cost, and context window size."
+---
+
+New models drop constantly, so this guide focuses on what's working well with Cline right now. We'll keep it updated as the landscape shifts.
+
+<Callout type="tip">
+**New to model selection?** Start with [Module 2 of Cline's Learning Path](https://cline.bot/learn) for a comprehensive guide to choosing and configuring models.
+</Callout>
+
+## What is an AI Model?
+
+Think of an AI model as the "brain" that powers Cline. When you ask Cline to write code, fix bugs, or refactor your project, it's the model that actually understands your request and generates the response.
+
+**Key points:**
+- **Models are trained AI systems** that understand natural language and code
+- **Different models have different strengths** some excel at complex reasoning, others prioritize speed or cost
+- **You choose which model Cline uses** like picking between different experts for different tasks
+- **Models are accessed via API providers** - companies like Anthropic, OpenAI, and OpenRouter host these models
+
+**Why it matters:** The model you choose directly impacts Cline's capabilities, response quality, speed, and cost. A premium model might handle complex refactoring beautifully but cost more, while a budget model works great for routine tasks at a fraction of the price.
+
+## How to Select a Model in Cline
+
+Follow these 5 simple steps to get Cline up and running with your preferred AI model:
+
+### Step 1: Open Cline Settings
+
+First, you need to access Cline's configuration panel.
+
+**Two ways to open settings:**
+- **Quick method**: Click the **gear icon (⚙️)** in the top-right corner of Cline's chat interface
+- **Command palette**: Press **Cmd/Ctrl + Shift + P** → type "Cline: Open Settings"
+
+<Frame>
+  <img src="https://storage.googleapis.com/cline_public_images/step1-config.png" alt="Cline Settings Panel" />
+</Frame>
+
+The settings panel will open, showing configuration options with "API Provider" at the top.
+
+<Note>
+The settings panel remembers your last configuration, so you'll only need to set this up once.
+</Note>
+
+### Step 2: Select an API Provider
+
+Choose your preferred AI provider from the dropdown menu.
+
+
+<Frame>
+  <img src="https://storage.googleapis.com/cline_public_images/step2-provider.png" alt="Cline Settings Panel" />
+</Frame>
+
+**Popular providers at a glance:**
+
+| Provider | Best For | Notes |
+|----------|----------|-------|
+| **Cline** | Easiest setup | No API keys needed, access to multiple models including stealth models |
+| **OpenRouter** | Value seekers | Multiple models, competitive pricing |
+| **Anthropic** | Reliability | Claude models, most dependable tool usage |
+| **OpenAI** | Latest tech | GPT-5, o3, o4-mini models |
+| **OpenAI Codex** | ChatGPT subscribers | Use your ChatGPT subscription — no API key needed |
+| **Google Gemini** | Large context | Gemini 3/2.5 with up to 2M context |
+| **DeepSeek** | Budget reasoning | V3.2, R1 models at low cost |
+| **Alibaba Qwen** | Open source coding | Qwen3 Coder with 1M context |
+| **Moonshot** | Agentic coding | Kimi K2.5 with 262K context |
+| **Cerebras** | Speed | Up to 2,600 tokens/sec |
+| **AWS Bedrock** | Enterprise | Advanced features |
+| **Ollama** | Privacy | Run models locally |
+
+See the [full provider list](/getting-started/authorizing-with-cline) for all 30+ supported providers including xAI Grok, Mistral, Groq, Fireworks, Together, Baseten, SambaNova, Nebius, Hugging Face, and more.
+
+<Info>
+**Recommended for beginners:** Start with **Cline** as your provider - no API key management needed, instant access to multiple models, and occasional free inferencing through partner providers.
+</Info>
+
+### Step 3: Add Your API Key (or Sign In)
+
+The next step depends on which provider you selected.
+
+#### If you selected **Cline** as your provider:
+
+- **No API key needed!** Simply sign in with your Cline account
+- Click the **Sign In** button when prompted
+- You'll be redirected to [app.cline.bot](https://app.cline.bot) to authenticate
+- After signing in, return to your IDE
+
+<Note>
+  For detailed information about the Cline authentication flow, OAuth tokens, and troubleshooting, see [Authorizing with Cline](/getting-started/authorizing-with-cline).
+</Note>
+
+#### If you selected **OpenAI Codex** as your provider:
+
+- **No API key needed!** If you have a ChatGPT subscription (Plus, Pro, or Team), you can use it directly in Cline
+- Click **"Sign in with OpenAI"** to authenticate via your browser
+- Once authorized, all models available on your OpenAI plan will appear automatically
+- Usage is governed by your ChatGPT subscription — no separate API billing
+
+See the full [OpenAI Codex setup guide](/provider-config/openai-codex) for details.
+
+#### If you selected any other provider:
+
+You'll need to get an API key from your chosen provider:
+
+1. **Visit your provider's website to get an API key:**
+   - **Anthropic**: [console.anthropic.com](https://console.anthropic.com/)
+   - **OpenRouter**: [openrouter.ai/keys](https://openrouter.ai/keys)
+   - **OpenAI**: [platform.openai.com/api-keys](https://platform.openai.com/api-keys)
+   - **Google**: [aistudio.google.com/apikey](https://aistudio.google.com/apikey)
+   - **Others**: See [Provider Setup Guide](/getting-started/authorizing-with-cline)
+
+2. **Generate a new API key** on the provider's website
+
+3. **Copy the API key** to your clipboard
+
+4. **Paste your key** in the **"API Key"** field in Cline settings
+
+5. **Save automatically** - Your key is stored securely in your editor's secrets storage
+
+<Frame>
+  <img src="https://storage.googleapis.com/cline_public_images/step3-API.png" alt="Cline API Selection" />
+</Frame>
+
+<Warning>
+**Payment required for most providers**: Most providers need payment information before generating keys. You only pay for what you use (typically $0.01-$0.10 per coding task).
+</Warning>
+
+### Step 4: Choose Your Model
+
+Once your API key is added (or you've signed in), the **"Model"** dropdown becomes available.
+
+<Frame>
+  <img src="https://storage.googleapis.com/cline_public_images/step4-model.png" alt="Cline Model Selection" />
+</Frame>
+
+**Quick model selection guide:**
+
+| Your Priority | Choose This Model | Why |
+|---------------|-------------------|-----|
+| **Maximum reliability** | Claude Sonnet 4.5 | Most reliable tool usage, excellent at complex tasks |
+| **Best value** | DeepSeek V3 or Qwen3 Coder | Great performance at budget prices |
+| **Fastest speed** | Qwen3 Coder on Cerebras | Lightning-fast responses |
+| **Run locally** | Any Ollama model | Complete privacy, no internet needed |
+| **Latest features** | GPT-5 | OpenAI's newest capabilities |
+
+Not sure which to pick? Start with **Claude Sonnet 4.5** for reliability or **DeepSeek V3** for value.
+
+<Tip>
+You can switch models at any time without losing your conversation. Try different models to find what works best for your specific tasks.
+</Tip>
+
+See the [model comparison tables](#current-top-models) below for detailed specifications and pricing.
+
+### Step 5: Start Using Cline
+
+**Congratulations! You're all set up.** Here's how to start coding with Cline:
+
+1. **Type your request** in the Cline chat box
+   - Example: "Create a React component for a login form"
+   - Example: "Debug this TypeScript error"
+   - Example: "Refactor this function to be more efficient"
+
+2. **Press Enter** or click the send icon to submit
+
+## Choosing the Right Model
+
+Selecting the right model involves balancing several factors. Use this framework to find your ideal match:
+
+<Note>
+**Pro tips**: Configure separate models for Plan Mode and Act Mode. Make the most out the each model's strengths. For example, use a budget model for planning discussions and a premium model for implementation.
+</Note>
+
+### Key Selection Factors
+
+| Factor | What to Consider | Recommendation |
+|--------|------------------|----------------|
+| **Task Complexity** | Simple fixes vs complex refactoring | Budget models for routine tasks; Premium models for complex work |
+| **Budget** | Monthly spending capacity | \$10-\$30: Budget,  \$30-\$100: Mid-tier, \$100+: Premium |
+| **Context Window** | Project size and file count | Small: 32K-128K, Medium: 128K-200K, Large: 400K+ |
+| **Speed** | Response time requirements | Interactive: Fast models, Background: Reasoning models OK |
+| **Tool Reliability** | Complex operations | Claude excels at tool usage; Test others with your workflow |
+| **Provider** | Access and pricing needs | OpenRouter: Many options, Direct: Faster/reliable, Local: Privacy |
+
+
+
+## Model Comparison Resources
+
+For detailed model comparisons and performance metrics, see:
+- [**Context Window Guide**](/model-config/context-windows) - Understanding and optimizing context usage
+
+## Open Source vs Closed Source
+
+### Open Source Advantages
+- **Multiple providers** compete to host them
+- **Cheaper pricing** due to competition  
+- **Provider choice** - switch if one goes down
+- **Faster innovation** cycles
+
+### Open Source Models Available
+- **Qwen3 Coder** (Apache 2.0)
+- **Z AI GLM 4.5** (MIT)
+- **Kimi K2** (Open source)
+- **DeepSeek series** (Various licenses)
+
+## Quick Decision Matrix
+
+| If you want... | Use this |
+|----------------|----------|
+| Something that just works | Claude Sonnet 4.5 |
+| To save money | DeepSeek V3 or Qwen3 variants |
+| Huge context windows | Gemini 2.5 Pro or Claude Sonnet 4.5 |
+| Open source | Qwen3 Coder, Z AI GLM 4.5, or Kimi K2 |
+| Latest tech | GPT-5 |
+| To use your ChatGPT subscription | [OpenAI Codex](/provider-config/openai-codex) — sign in with your OpenAI account, no API key needed |
+| Speed | Qwen3 Coder on Cerebras (fastest available) |
+
+## What Others Are Using
+
+Check [Vercel's leaderboard](https://vercel.com/ai-gateway/leaderboards) to see real usage patterns from the community.

docs/core-workflows/plan-and-act.mdx

@@ -89,7 +89,7 @@ For complex tasks that need thorough analysis, use the `/deep-planning` slash co
 3. Creates a detailed implementation plan
 4. Asks clarifying questions before proceeding
 
-The deep planning prompt is optimized for each model family, so it adapts to the strengths of whatever model you're using. See [/deep-planning](/core-workflows/using-commands#deep-planning) for more details.
+The deep planning prompt is optimized for each model family, so it adapts to the strengths of whatever model you're using. See the [Deep Planning docs](/features/deep-planning) for more details.
 
 ## Choosing the Right Approach by Task Size
 

docs/core-workflows/using-commands.mdx

@@ -1,7 +1,7 @@
 ---
 title: "Using Commands"
 sidebarTitle: "Using Commands"
-description: "Built-in slash commands to manage context, plan implementations, and trigger reusable skills."
+description: "Built-in slash commands to manage context, plan implementations, and create reusable workflows."
 ---
 
 Cline provides slash commands in chat that help you manage your conversation and plan complex implementations.
@@ -37,7 +37,7 @@ Use `/smol` when you're deep into a debugging session or brainstorming and need
 
 ### /newrule
 
-`/newrule` creates a rule file that teaches Cline your preferences. Cline will guide you through setting up guidelines for communication style, coding standards, project context, and reusable practices. The rule is saved to your `.clinerules` directory and automatically loaded for future conversations.
+`/newrule` creates a rule file that teaches Cline your preferences. Cline will guide you through setting up guidelines for communication style, coding standards, project context, and workflows. The rule is saved to your `.clinerules` directory and automatically loaded for future conversations.
 
 Use `/newrule` when you find yourself repeating the same instructions across tasks. For more about rules, see [Cline Rules](/customization/cline-rules).
 
@@ -50,7 +50,7 @@ Transform Cline into a meticulous architect who investigates your codebase, asks
 3. **Plan Creation** - Generates `implementation_plan.md` with detailed specifications
 4. **Task Creation** - Creates a new task with trackable implementation steps
 
-Use `/deep-planning` for features touching multiple parts of your codebase, architectural changes, or complex integrations.
+Use `/deep-planning` for features touching multiple parts of your codebase, architectural changes, or complex integrations. For detailed documentation, see [Deep Planning](/features/deep-planning).
 
 ### /explain-changes
 
@@ -60,7 +60,7 @@ This command is only available in VS Code.
 
 `/explain-changes` generates AI-powered explanations for any git diff. You can explain the last commit, uncommitted work, staged changes, specific commits, branches, PRs, or any range of changes.
 
-Use `/explain-changes` when reviewing code, onboarding to a new codebase, or understanding what changed. For the full list of use cases and examples, see [Explain Changes Command](#explain-changes).
+Use `/explain-changes` when reviewing code, onboarding to a new codebase, or understanding what changed. For the full list of use cases and examples, see [Explain Changes](/features/explain-changes).
 
 ### /reportbug
 
@@ -68,14 +68,8 @@ Use `/explain-changes` when reviewing code, onboarding to a new codebase, or und
 
 Use `/reportbug` when you encounter unexpected behavior, crashes, or bugs you want to report.
 
-## Skills via Slash Commands
+## Custom Workflows
 
-In addition to built-in commands, you can trigger enabled skills directly from chat using slash commands.
+Beyond the built-in slash commands, you can create your own workflow files that work the same way. Store Markdown files in `.clinerules/workflows/` and invoke them with `/your-workflow.md`.
 
-- Type `/` to open command suggestions.
-- Select a skill command (for example, `/aws-deploy`).
-- Cline loads that skill and applies its `SKILL.md` instructions for the task.
-
-Any enabled skill can be triggered this way, which gives you a fast path to skill-specific guidance without rewriting the same instructions each time.
-
-For setup and management details, see [Skills](/customization/skills#triggering-skills-with-slash-commands).
+For a complete guide on creating and managing custom workflows, see [Workflows](/customization/workflows).

docs/core-workflows/working-with-files.mdx

@@ -1,14 +1,18 @@
 ---
 title: "Adding Context"
 sidebarTitle: "Adding Context"
-description: "Use @ mentions and drag & drop to bring files into your conversations."
+description: "Use @ mentions and drag & drop to bring files, terminal output, errors, git changes, and web content into your conversations."
 ---
 
-Cline works best when it has the right context, not just more context. `@` mentions let you pull in the files and folders that matter for your task — no copying, no pasting, no context switching.
+Cline works best when it has the right context, not just more context. @ mentions let you pull in exactly the files, errors, terminal output, or documentation that matter for your task. No copying, no pasting, no context switching.
 
 You can add context two ways:
-- Type `@` in the chat input and select a file or folder
-- Click the **+** button in the bottom left to browse files or images
+- Type `@` in the chat input and select what you want
+- Click the **+** button in the bottom left to browse files, images, or mentions
+
+<Tip>
+**Want to learn more about managing context?** Watch [Adding Context with @ Mentions](https://youtu.be/7j6R75Dvj1Y) to see it in action.
+</Tip>
 
 ## Quick Reference
 
@@ -16,8 +20,11 @@ You can add context two ways:
 |---------------|--------|---------|
 | File content | `@/path/to/file` | `@/src/index.ts` |
 | Folder contents | `@/path/to/folder/` | `@/src/components/` |
-
-For other context — git history, web pages, terminal errors — just describe it. Cline will run `git log`, fetch the URL, or read the output itself.
+| Workspace errors | `@problems` | `@problems` |
+| Terminal output | `@terminal` | `@terminal` |
+| Uncommitted changes | `@git-changes` | `@git-changes` |
+| Specific commit | `@<commit-hash>` | `@a1b2c3d` |
+| Web page | `@<url>` | `@https://react.dev/learn` |
 
 ## File Mentions
 
@@ -39,6 +46,59 @@ Explain how the components in @/src/components/auth/ work together.
 In multi-root workspaces, prefix paths with the workspace name: `@workspace-name:/path/to/file`
 </Note>
 
+## Problem Mentions
+
+Use `@problems` to share all errors and warnings from your workspace's Problems panel.
+
+```text
+@problems Can you fix these TypeScript errors?
+```
+
+## Terminal Mentions
+
+Use `@terminal` to share recent terminal output. Perfect for debugging build errors or test failures.
+
+```text
+@terminal The build is failing. What's wrong?
+```
+
+## Git Mentions
+
+Reference uncommitted changes with `@git-changes`:
+
+```text
+@git-changes Review my changes before I commit.
+```
+
+Reference specific commits with `@<commit-hash>` (7-40 character hex):
+
+```text
+What did @a1b2c3d change?
+```
+
+## URL Mentions
+
+Reference web content with `@https://example.com`. Cline fetches the page content.
+
+```text
+Implement the pattern described in @https://react.dev/learn/scaling-up-with-reducer-and-context
+```
+
+## Combining Mentions
+
+Combine multiple @ mentions for comprehensive context:
+
+```text
+I'm getting these errors: @problems
+
+Here's my component: @/src/components/Form.jsx
+And the API endpoint: @/src/api/users.js
+
+The error happens when I submit: @terminal
+
+I think this commit might have caused it: @a1b2c3d
+```
+
 ## Drag & Drop
 
 Drag files directly into the chat input to add them to your conversation.

docs/customization/cline-rules.mdx

@@ -51,7 +51,7 @@ your-project/
 
 Cline processes all `.md` and `.txt` files inside `.clinerules/`, combining them into a unified set of rules. Numeric prefixes (like `01-coding.md`) help organize files but are optional.
 
-When both workspace and global rules exist, Cline combines them. Workspace rules take precedence when they conflict with global rules. See [Storage Locations](/getting-started/config#storage-locations) for more guidance.
+When both workspace and global rules exist, Cline combines them. Workspace rules take precedence when they conflict with global rules. See [Storage Locations](/customization/overview#storage-locations) for more guidance.
 
 ### Global Rules Directory
 

docs/customization/clineignore.mdx

@@ -107,3 +107,4 @@ You can still reference ignored files explicitly using [@ mentions](/core-workfl
 - [Cline Rules](/customization/cline-rules) - Define persistent instructions for Cline
 - [Task Management](/core-workflows/task-management#context-window) - Understand how context windows work
 - [Auto-Compact](/features/auto-compact) - Automatic context compression during long tasks
+- [Memory Bank](/features/memory-bank) - Structured documentation for cross-session context

docs/customization/hooks.mdx

@@ -1,7 +1,509 @@
 ---
 title: "Hooks"
 sidebarTitle: "Hooks"
-description: "See details under SDK Hooks page."
+description: "Inject custom logic into Cline's workflow to validate operations and shape Cline's decisions."
 ---
 
-See details under [SDK Plugins](/sdk/plugins).
+Hooks are scripts that run at key moments in Cline's workflow. Because they execute at known points with consistent inputs and outputs, hooks bring determinism to the non-deterministic nature of AI models by enforcing guardrails, validations, and context injection. You can validate operations before they execute, monitor tool usage, and shape how Cline makes decisions.
+
+## What You Can Build
+
+- Stop operations before they cause problems (like creating `.js` files in a TypeScript project)
+- Run linters or custom validators before files get saved
+- Prevent operations that violate security policies
+- Track everything for analytics or compliance
+- Trigger external tools or services at the right moments
+- Add context to the conversation based on what Cline is doing
+
+## Hook Types
+
+Cline supports 8 hook types that run at different points in the task lifecycle:
+
+| Hook Type | When It Runs | 
+|-----------|--------------|
+| TaskStart | When you start a new task |
+| TaskResume | When you resume an interrupted task |
+| TaskCancel | When you cancel a running task |
+| TaskComplete | When a task finishes successfully |
+| PreToolUse | Before Cline executes a tool (read_file, write_to_file, etc.) |
+| PostToolUse | After a tool execution completes |
+| UserPromptSubmit | When you submit a message to Cline |
+| PreCompact | Before Cline truncates conversation history to free up context |
+
+## Hook Lifecycle
+
+```mermaid
+flowchart TD
+    %% Styling
+    classDef hook fill:#FFB74D,stroke:#E65100,stroke-width:2px,color:black,rx:5,ry:5;
+    classDef state fill:#E1F5FE,stroke:#0277BD,stroke-width:2px,color:black;
+    classDef action fill:#FFFFFF,stroke:#333,stroke-width:1px,color:black,stroke-dasharray: 5 5;
+
+    %% Entry Points
+    Start((Start)) --> CheckType{New or<br/>Resume?}
+    
+    %% Initialization Hooks
+    CheckType -- New Task --> H_Start[TaskStart]:::hook
+    CheckType -- Resume --> H_Resume[TaskResume]:::hook
+    
+    %% Main Loop
+    H_Start --> Loop(Task Active Loop):::state
+    H_Resume --> Loop
+
+    subgraph Conversation Cycle
+        direction TB
+        Loop -- User sends message --> H_Submit[UserPromptSubmit]:::hook
+        H_Submit --> Thinking[Cline Processes Context]:::state
+        
+        %% Context Compaction Path
+        Thinking -. Context Limit Reached .-> H_Compact[PreCompact]:::hook
+        H_Compact -.-> Thinking
+        
+        %% Tool Execution Path
+        Thinking -- Decides to use tool --> H_PreTool[PreToolUse]:::hook
+        H_PreTool -- Allowed --> ToolExec[Tool Executes]:::action
+        H_PreTool -- Cancelled --> Thinking
+        ToolExec --> H_PostTool[PostToolUse]:::hook
+        H_PostTool --> Thinking
+    end
+
+    %% Termination Paths
+    Thinking -- Task Successfully Finished --> H_Complete[TaskComplete]:::hook
+    Loop -- User Cancels Task --> H_Cancel[TaskCancel]:::hook
+    
+    %% End
+    H_Complete --> End((End))
+    H_Cancel --> End
+```
+
+The diagram shows the complete hook lifecycle:
+
+1. **Entry**: When you start a task, either **TaskStart** (new task) or **TaskResume** (interrupted task) runs first
+2. **Conversation Cycle**: Each time you send a message, **UserPromptSubmit** runs, then Cline processes your request
+3. **Tool Execution**: When Cline decides to use a tool, **PreToolUse** runs first-if allowed, the tool executes, then **PostToolUse** runs
+4. **Context Management**: If the conversation approaches context limits, **PreCompact** runs before truncation
+5. **Exit**: The task ends with either **TaskComplete** (success) or **TaskCancel** (user cancellation)
+
+Orange nodes represent hooks where you can inject custom logic. The cycle repeats as you continue the conversation.
+
+## Hook Locations
+
+Hooks can be stored globally or in a project workspace. See [Storage Locations](/customization/overview#storage-locations) for guidance on when to use each.
+
+- **Global hooks**: `~/Documents/Cline/Hooks/`
+- **Project hooks**: `.clinerules/hooks/` in your repo (can be committed to version control)
+
+When both global and workspace hooks exist for the same hook type, both run. Global hooks execute first, then workspace hooks. If either returns `cancel: true`, the operation stops.
+
+## Creating a Hook
+
+<Steps>
+  <Step title="Open the Hooks tab">
+    Click the scale icon at the bottom of the Cline panel, to the left of the model selector. Switch to the Hooks tab.
+  </Step>
+  <Step title="Create a new hook">
+    Click **"New hook..."** dropdown and select a hook type (e.g., PreToolUse, TaskStart).
+  </Step>
+  <Step title="Review the hook's code">
+    Click the pencil icon to open and edit the hook script. Cline generates a template with examples.
+  </Step>
+  <Step title="Enable the hook">
+    Toggle the switch to activate the hook once you understand what it does.
+  </Step>
+</Steps>
+
+<Warning>
+Always review a hook's code before enabling it. Hooks execute automatically during your workflow and can block operations or run shell commands.
+</Warning>
+
+## Quick Start: Your First Hook
+
+Let's create a simple hook that logs every file Cline reads or writes. You'll see results in seconds.
+
+### The Hook
+
+Create a file called `file-logger` in your hooks directory with this content:
+
+```bash
+#!/bin/bash
+# Logs all file operations to ~/cline-activity.log
+
+INPUT=$(cat)
+TOOL=$(echo "$INPUT" | jq -r '.preToolUse.tool')
+FILE_PATH=$(echo "$INPUT" | jq -r '.preToolUse.parameters.path // "N/A"')
+
+# Log to file
+echo "$(date '+%H:%M:%S') - $TOOL: $FILE_PATH" >> ~/cline-activity.log
+
+# Always allow the operation
+echo '{"cancel":false}'
+```
+
+### Setup
+
+<Steps>
+  <Step title="Create the hook file">
+    Save the script above as `~/Documents/Cline/Hooks/file-logger` or create it through the Hooks UI.
+  </Step>
+  <Step title="Make it executable">
+    On macOS/Linux, run `chmod +x ~/Documents/Cline/Hooks/file-logger`.
+  </Step>
+  <Step title="Enable it (macOS/Linux only)">
+    In Cline's Hooks tab, find "file-logger" under PreToolUse hooks and toggle it on.
+  </Step>
+</Steps>
+
+<Note>
+On Windows, hooks are executed with PowerShell and run whenever the hook file exists. In this
+foundation PR, hook enable/disable toggling is not yet supported on Windows.
+</Note>
+
+<Note>
+Coming next: JSON-backed hook enabled/disabled state across platforms, so toggle behavior is
+consistent on Windows, macOS, and Linux.
+</Note>
+
+<Note>
+Hook filenames are platform-specific:
+
+- **Windows**: only `HookName.ps1` is supported (PowerShell script files)
+- **macOS/Linux**: only extensionless `HookName` is supported (executable files like bash scripts or binaries)
+
+Wrong-platform naming is ignored by hook discovery.
+</Note>
+
+### Test It
+
+Ask Cline to read any file in your project: "What's in package.json?"
+
+Then check the log:
+
+```bash
+cat ~/cline-activity.log
+```
+
+You'll see entries like:
+```text
+14:23:45 - read_file: /path/to/package.json
+14:23:47 - search_files: /path/to/src
+```
+
+### Customize It
+
+Try modifying the hook to:
+- Filter specific file types (only log `.ts` files)
+- Add the task ID to each log entry
+- Send notifications for write operations
+- Block operations on certain paths
+
+The sections below explain how hooks receive input and return output, plus more examples.
+
+## How Hooks Work
+
+Hooks are executable scripts that receive JSON input via stdin and return JSON output via stdout.
+
+### Input Structure
+
+Every hook receives a JSON object with common fields plus hook-specific data:
+
+```json
+{
+  "taskId": "abc123",
+  "hookName": "PreToolUse",
+  "clineVersion": "3.17.0",
+  "timestamp": "1736654400000",
+  "workspaceRoots": ["/path/to/project"],
+  "userId": "user_123",
+  "model": {
+    "provider": "openrouter",
+    "slug": "anthropic/claude-sonnet-4.5"
+  },
+  
+  // Hook-specific field (name matches hook type in camelCase)
+  "taskStart": {
+    "task": "Add authentication to the API"
+  }
+}
+```
+
+`model.provider` and `model.slug` are machine-stable identifiers for the active provider/model at hook execution time. If unavailable, Cline sends deterministic fallback values: `"unknown"`.
+
+<Note>
+Migration note for existing hook scripts:
+
+- `timestamp` is a string (milliseconds since epoch), not a number
+- `workspaceRoots` is an array of workspace root paths and replaces the old singular `workspacePath`
+
+If your scripts previously read `.workspacePath`, switch to `.workspaceRoots[0]` (or iterate all roots).
+</Note>
+
+The hook-specific field name matches the hook type:
+- `taskStart`, `taskResume`, `taskCancel`, `taskComplete` contain `{ task: string }`
+- `preToolUse` contains `{ tool: string, parameters: object }`
+- `postToolUse` contains `{ tool: string, parameters: object, result: string, success: boolean, durationMs: number }`
+- `userPromptSubmit` contains `{ prompt: string }`
+- `preCompact` contains `{ conversationLength: number, estimatedTokens: number }`
+
+### Output Structure
+
+Hooks return a JSON object to stdout:
+
+```json
+{
+  "cancel": false,
+  "contextModification": "Optional text to add to the conversation",
+  "errorMessage": ""
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `cancel` | boolean | If `true`, stops the operation (blocks the tool, cancels the task start, etc.) |
+| `contextModification` | string | Optional text that gets injected into the conversation as context for Cline |
+| `errorMessage` | string | Shown to the user if `cancel` is `true` |
+
+### Context Modification
+
+The `contextModification` field lets hooks inject information into the conversation. This is useful for:
+
+- Adding project-specific context when a task starts
+- Providing validation results that Cline should consider
+- Injecting environment information before tool execution
+
+For example, a PreToolUse hook could add: `"Note: This file is auto-generated. Edits may be overwritten."`
+
+## Hook Reference
+
+### Task Lifecycle Hooks
+
+#### TaskStart
+
+Runs when you start a new task. Use it to:
+- Log task start time for analytics
+- Add project context to the conversation
+- Check prerequisites before work begins
+- Notify external systems (Slack, issue trackers)
+
+```bash
+#!/bin/bash
+INPUT=$(cat)
+TASK=$(echo "$INPUT" | jq -r '.taskStart.task')
+echo "[TaskStart] Starting: $TASK" >&2
+echo '{"cancel":false,"contextModification":"","errorMessage":""}'
+```
+
+#### TaskResume
+
+Runs when you resume an interrupted task (instead of TaskStart). Use it to:
+- Check for changes since the task was paused
+- Refresh context with latest project state
+- Notify that work is resuming
+
+#### TaskCancel
+
+Runs when you cancel a running task. Use it to:
+- Clean up temporary files or resources
+- Notify external systems about cancellation
+- Log cancellation for analytics
+
+#### TaskComplete
+
+Runs when a task completes successfully. Use it to:
+- Run tests or validation after changes
+- Generate reports or summaries
+- Notify stakeholders
+- Trigger CI/CD pipelines
+
+### Tool Hooks
+
+#### PreToolUse
+
+Runs before any tool executes. This is the most powerful hook for validation and safety. Use it to:
+- Block dangerous operations
+- Validate parameters before execution
+- Add context about the file or resource being accessed
+- Log tool usage
+
+The input includes the tool name and its parameters:
+
+```json
+{
+  "preToolUse": {
+    "tool": "write_to_file",
+    "parameters": {
+      "path": "src/config.ts",
+      "content": "..."
+    }
+  }
+}
+```
+
+Example that blocks `.js` files in a TypeScript project:
+
+```bash
+#!/bin/bash
+INPUT=$(cat)
+TOOL=$(echo "$INPUT" | jq -r '.preToolUse.tool')
+FILE_PATH=$(echo "$INPUT" | jq -r '.preToolUse.parameters.path // empty')
+
+if [[ "$TOOL" == "write_to_file" && "$FILE_PATH" == *.js ]]; then
+  echo '{"cancel":true,"errorMessage":"Use .ts files instead of .js in this TypeScript project"}'
+  exit 0
+fi
+
+echo '{"cancel":false}'
+```
+
+#### PostToolUse
+
+Runs after a tool completes (success or failure). Use it to:
+- Audit tool usage
+- Validate results
+- Trigger follow-up actions
+- Monitor performance
+
+The input includes execution results:
+
+```json
+{
+  "postToolUse": {
+    "tool": "execute_command",
+    "parameters": { "command": "npm test" },
+    "result": "All tests passed",
+    "success": true,
+    "durationMs": 3450
+  }
+}
+```
+
+<Note>
+PostToolUse hooks can return `cancel: true` to stop the task, but they cannot undo the tool execution that already happened.
+</Note>
+
+### Other Hooks
+
+#### UserPromptSubmit
+
+Runs when you send a message to Cline. Use it to:
+- Log prompts for analytics
+- Add context based on prompt content
+- Validate or sanitize prompts
+
+#### PreCompact
+
+Runs before Cline truncates conversation history to stay within context limits. Use it to:
+- Archive important conversation parts before they're removed
+- Log compaction events
+- Add a summary of what's being removed
+
+The input includes context metrics:
+
+```json
+{
+  "preCompact": {
+    "conversationLength": 45,
+    "estimatedTokens": 125000
+  }
+}
+```
+
+## Examples
+
+### TypeScript Enforcement
+
+Block creation of `.js` files in a TypeScript project:
+
+```bash
+#!/bin/bash
+# PreToolUse hook
+
+INPUT=$(cat)
+TOOL=$(echo "$INPUT" | jq -r '.preToolUse.tool')
+FILE_PATH=$(echo "$INPUT" | jq -r '.preToolUse.parameters.path // empty')
+
+if [[ "$TOOL" == "write_to_file" && "$FILE_PATH" == *.js ]]; then
+  echo '{"cancel":true,"errorMessage":"Use .ts files instead of .js in this TypeScript project"}'
+  exit 0
+fi
+
+echo '{"cancel":false}'
+```
+
+### Tool Usage Logging
+
+Log all tool executions to a file:
+
+```bash
+#!/bin/bash
+# PostToolUse hook
+
+INPUT=$(cat)
+TOOL=$(echo "$INPUT" | jq -r '.postToolUse.tool')
+SUCCESS=$(echo "$INPUT" | jq -r '.postToolUse.success')
+DURATION=$(echo "$INPUT" | jq -r '.postToolUse.durationMs')
+
+echo "$(date -Iseconds) | $TOOL | success=$SUCCESS | ${DURATION}ms" >> ~/.cline-tool-log.txt
+
+echo '{"cancel":false}'
+```
+
+### Add Project Context on Task Start
+
+Inject project-specific information when a task begins:
+
+```bash
+#!/bin/bash
+# TaskStart hook
+
+INPUT=$(cat)
+WORKSPACE=$(echo "$INPUT" | jq -r '.workspaceRoots[0] // empty')
+
+# Read project info if available
+if [[ -f "$WORKSPACE/.project-context" ]]; then
+  CONTEXT=$(cat "$WORKSPACE/.project-context")
+  echo "{\"cancel\":false,\"contextModification\":\"Project context: $CONTEXT\"}"
+else
+  echo '{"cancel":false}'
+fi
+```
+
+## CLI Support
+
+Hooks are available in the [Cline CLI](/cline-cli/getting-started):
+
+```bash
+# Enable hooks for a task
+cline "What does this repo do?" -s hooks_enabled=true
+
+# Configure hooks globally
+cline config set hooks-enabled=true
+```
+
+<Note>
+Windows hooks require PowerShell (`powershell.exe`) available on your PATH.
+</Note>
+
+## Troubleshooting
+
+**Hook not running?**
+- On macOS/Linux, check that the file is executable (`chmod +x hookname`)
+- On Windows, ensure PowerShell is available (`powershell -NoProfile -Command "$PSVersionTable.PSVersion"`)
+- On Windows, ensure the hook file is named `<HookName>.ps1` (for example `PreToolUse.ps1`)
+- On macOS/Linux, ensure the hook file uses extensionless `<HookName>` naming (for example `PreToolUse`)
+- On macOS/Linux, verify the hook is enabled (toggle is on in the Hooks tab)
+- Check that Hooks are enabled globally in Settings
+
+**Hook output not parsed?**
+- Ensure output is valid JSON on a single line to stdout
+- Use stderr (`>&2`) for debug logging, not stdout
+- Check for trailing characters or newlines before the JSON
+
+**Hook blocking unexpectedly?**
+- Review the hook's logic and test with sample input
+- Check both global and workspace hooks (both run if they exist)
+
+## Related Features
+
+- [Rules](/customization/cline-rules) define high-level guidance that hooks can enforce programmatically
+- [Checkpoints](/core-workflows/checkpoints) let you roll back if a hook didn't catch an issue
+- [Auto-Approve](/features/auto-approve) works well with hooks as safety nets

docs/customization/overview.mdx

@@ -0,0 +1,86 @@
+---
+title: "Overview"
+sidebarTitle: "Overview"
+description: "Understand how Rules, Skills, Workflows, Hooks, and .clineignore work together to customize Cline."
+---
+
+Out of the box, Cline is a general-purpose AI assistant. Customizations transform it into an expert on your codebase, your team's conventions, and your workflows. Instead of repeating the same instructions every task, you define them once and Cline follows them automatically.
+
+Cline offers five systems for this: Rules, Skills, Workflows, Hooks, and .clineignore. Each serves a different purpose and activates at different times.
+
+## Quick Comparison
+
+| Feature | Purpose | When Active | Best For |
+|---------|---------|-------------|----------|
+| **[Rules](/customization/cline-rules)** | Define how Cline behaves | Always (or contextually) | Coding standards, project constraints, team conventions |
+| **[Skills](/customization/skills)** | Domain expertise loaded on-demand | Triggered by matching requests | Specialized knowledge, complex procedures, institutional expertise |
+| **[Workflows](/customization/workflows)** | Step-by-step task automation | Invoked with `/workflow.md` | Repetitive processes, release procedures, setup scripts |
+| **[Hooks](/customization/hooks)** | Inject custom logic at key moments | Automatically on specific events | Validation, enforcement, monitoring, automation triggers |
+| **[.clineignore](/customization/clineignore)** | Control file access | Always | Excluding dependencies, build artifacts, large data files |
+
+## Understanding Each Tool
+
+**[Rules](/customization/cline-rules)** are always-on guidance. Use them when you want Cline to consistently follow certain patterns: coding standards, naming conventions, architectural constraints, or project-specific context. Rules shape *how* Cline works across all tasks. For example, a rule might say "always use TypeScript" or "follow the repository pattern for data access."
+
+**[Skills](/customization/skills)** are domain expertise that loads only when relevant. Use them when you have extensive knowledge that would waste context if always active. Cline sees skill descriptions at startup and activates the full instructions only when your request matches. A data analysis skill might include pandas patterns, visualization preferences, and output formats that Cline only loads when you're working with data files.
+
+**[Workflows](/customization/workflows)** are explicit task scripts you invoke on demand. Use them when you have a repeatable multi-step process that should run the same way every time. Type `/release.md` and Cline executes your release sequence: bump version, run tests, update changelog, commit, tag, push. Workflows define *what* to do, step by step.
+
+**[Hooks](/customization/hooks)** are programmatic guardrails that run automatically at key moments. Use them when you need to validate, enforce, or extend Cline's behavior with custom code. A hook might block `.js` file creation in a TypeScript project, run linters before saves, or notify external services after deployments.
+
+**[.clineignore](/customization/clineignore)** controls which files and directories Cline can access. Use it to exclude dependencies, build artifacts, generated files, and large data files from Cline's context. This reduces token usage, lowers costs, and keeps Cline focused on the code that matters. It works like `.gitignore`: add patterns to a `.clineignore` file in your project root and matching files are automatically excluded.
+
+### Example: A Release Process
+
+Consider how all five work together for releasing a new version:
+
+1. **Rules** ensure Cline follows your team's commit message format and versioning policy
+2. **Skills** offer deep knowledge about your CI/CD system that Cline loads when deployment questions arise
+3. **Workflows** provide the explicit `/release.md` sequence: bump version, update changelog, tag, push
+4. **Hooks** validate that tests pass before allowing any commit or that the changelog was actually updated
+5. **.clineignore** keeps build artifacts, `node_modules/`, and generated files out of Cline's context so it stays focused
+
+## Storage Locations
+
+All five systems support both global and project-specific configurations:
+
+| System | Global Location | Project Location |
+|--------|-----------------|------------------|
+| Rules | `~/Documents/Cline/Rules/` | `.clinerules/` |
+| Skills | `~/.cline/skills/` | `.cline/skills/` |
+| Workflows | `~/Documents/Cline/Workflows/` | `.clinerules/workflows/` |
+| Hooks | `~/Documents/Cline/Hooks/` | `.clinerules/hooks/` |
+| .clineignore | N/A | `.clineignore` |
+
+### When to Use Each
+
+**Start with project storage.** Most customizations belong in your project's directory because they're tied to that specific codebase. Team coding standards, deployment workflows, and architectural constraints all live with the code they describe. This also means your customizations travel with the repository, so collaborators get them automatically and changes can be reviewed in pull requests.
+
+**Use global storage for personal preferences.** If you find yourself adding the same customization to every project, move it to global storage. Your preferred communication style, personal productivity workflows, and tools you use everywhere belong here. Global customizations apply to all projects but stay out of version control, so they won't affect your teammates.
+
+When names conflict, project-specific configurations take precedence (except for Skills, where global takes precedence). This lets you override global defaults for specific projects when needed.
+
+## Security Considerations
+
+<Warning>
+Always review customizations before adding them to your projects. Only use customizations from sources you trust.
+</Warning>
+
+Customizations are powerful. They shape how Cline writes code, execute commands automatically, and influence every interaction. Treat customization files with the same scrutiny you'd give any code running in your environment.
+
+### Best Practices
+
+Review any customization file before adding it to your project or global configuration. Understand what it does and why.
+
+When downloading customizations from GitHub repositories, community shares, or other external sources, verify the source:
+- Is the author reputable?
+- Has the community reviewed it?
+- Does the code do what it claims?
+
+Look for dangerous commands:
+- Shell commands that delete files (`rm`, `del`)
+- Commands that transmit data (`curl`, `wget` with POST)
+- File operations outside your project directory
+- Commands that modify system configuration
+
+Keep your customizations in version control so you can track changes, review diffs, and roll back if something goes wrong. When creating hooks, use the most restrictive event triggers necessary. Don't run hooks on every file save if you only need them before commits.

docs/customization/plugins.mdx

@@ -1,138 +0,0 @@
----
-title: "Plugins"
-sidebarTitle: "Plugins"
-description: "Install and manage plugins that extend Cline with custom tools, hooks, and capabilities."
----
-<Warning>
-  This feature currently only applies to Cline SDK, CLI, and Kanban. This feature is not applicable on VSCode and JetBrains Extension for now.
-</Warning>
-
-Plugins extend Cline with custom tools, lifecycle hooks, slash commands, and more. They can be installed globally (available in all sessions) or per-project.
-
-## Installing Plugins via CLI
-
-The `cline plugin install` command installs plugins from three source types:
-
-<Tabs>
-  <Tab title="Git Repository">
-    ```bash
-    cline plugin install https://github.com/owner/repo.git
-    cline plugin install git@github.com:owner/repo.git
-    ```
-
-    The installer clones the repository, installs production dependencies, and registers the plugin entry files.
-
-    To install a specific branch or tag, append `@ref`:
-
-    ```bash
-    cline plugin install https://github.com/owner/repo.git@v1.2.0
-    cline plugin install https://github.com/owner/repo.git@main
-    ```
-  </Tab>
-  <Tab title="npm Package">
-    ```bash
-    cline plugin install npm:@scope/my-plugin
-    cline plugin install --npm my-plugin
-    ```
-  </Tab>
-  <Tab title="Local Path">
-    ```bash
-    cline plugin install ./my-plugin
-    cline plugin install ~/plugins/my-tool
-    cline plugin install /absolute/path/to/plugin.ts
-    ```
-
-    Local installs copy the file or directory into the plugin store. Both single `.ts`/`.js` files and directories with a `package.json` are supported.
-  </Tab>
-</Tabs>
-
-Additional flags:
-
-| Flag | Description |
-|------|-------------|
-| `--force` | Replace an existing install for the same source |
-| `--json` | Output the result as JSON (useful for scripting) |
-| `--cwd <path>` | Install to `<path>/.cline/plugins` instead of the global directory |
-
-After installation, confirm the plugin is loaded by running `cline config` and checking the plugin tab.
-
-### Example: TypeScript Navigation Plugin
-
-The [typescript-lsp-plugin](https://github.com/cline/typescript-lsp-plugin) is a good reference for how plugins work. It adds a `goto_definition` tool that uses the TypeScript Language Service API to resolve symbol definitions through imports, re-exports, and type aliases.
-
-Install it with:
-
-```bash
-cline plugin install https://github.com/cline/typescript-lsp-plugin.git
-```
-
-Once installed, Cline can call `goto_definition` with a file path and line number to find where symbols are defined, which is much more precise than text search.
-
-## Plugin Manifest Format
-
-For a repository or npm package to be installable as a Cline plugin, its `package.json` should include a `cline` field that declares plugin entry points:
-
-```json
-{
-  "name": "my-cline-plugin",
-  "version": "1.0.0",
-  "cline": {
-    "plugins": [
-      {
-        "paths": ["./index.ts"],
-        "capabilities": ["tools", "hooks"]
-      }
-    ]
-  }
-}
-```
-
-The `cline.plugins` array accepts:
-
-| Format | Example |
-|--------|---------|
-| Object with `paths` array | `{ "paths": ["./src/plugin.ts"], "capabilities": ["tools"] }` |
-| Plain string | `"./index.ts"` |
-
-Each path should point to a `.ts` or `.js` file that exports an `AgentPlugin` (either as the default export or a named export).
-
-If no `cline.plugins` field is present, the installer falls back to auto-discovery: it looks for standard entry points, then recursively scans for `.ts` and `.js` files (skipping `node_modules` and `.git`).
-
-### Host-Provided Dependencies
-
-Dependencies under the `@cline/` scope (like `@cline/core`, `@cline/shared`) are provided by the host runtime. The installer automatically strips these from the plugin's dependency list before running `npm install`, so you should declare them as `peerDependencies`:
-
-```json
-{
-  "peerDependencies": {
-    "@cline/core": "*"
-  },
-  "peerDependenciesMeta": {
-    "@cline/core": {
-      "optional": true
-    }
-  }
-}
-```
-
-## Plugin Directory Structure
-
-Plugins are stored in the `plugins` directory at two levels:
-
-```
-~/.cline/
-  plugins/                     # Global plugins
-    _installed/                # Managed by `cline plugin install`
-      npm/                     # npm-sourced plugins
-      git/                     # git-sourced plugins
-      local/                   # local-sourced plugins
-
-.cline/                        # Project root
-  plugins/                     # Project-scoped plugins
-```
-
-Global plugins (`~/.cline/plugins/`) are available across all sessions. Project plugins (`.cline/plugins/` in your repo) are available only when working in that project.
-
-## Writing Plugins
-
-For a guide on building plugins with the SDK, see [Writing Plugins](/sdk/guides/writing-plugins). For the plugin API reference, see [SDK Plugins](/sdk/plugins).

docs/customization/skills.mdx

@@ -4,7 +4,7 @@ sidebarTitle: "Skills"
 description: "Modular instruction sets that extend Cline's capabilities for specific tasks."
 ---
 
-Skills are modular instruction sets that extend Cline's capabilities for specific tasks. Each skill packages detailed guidance, processes, and optional resources that Cline loads only when relevant to your request.
+Skills are modular instruction sets that extend Cline's capabilities for specific tasks. Each skill packages detailed guidance, workflows, and optional resources that Cline loads only when relevant to your request.
 
 Install multiple skills and Cline only loads what it needs. A deployment skill stays dormant until you ask about deploying. Unlike [rules](/customization/cline-rules) (which are always active), skills load on-demand so they don't consume context when you're working on something unrelated.
 
@@ -24,16 +24,6 @@ Skills use progressive loading to maximize efficiency:
 
 When you send a message, Cline sees a list of available skills with their descriptions. If your request matches a skill's description, Cline activates it using the `use_skill` tool, which loads the full instructions from SKILL.md.
 
-## Triggering Skills with Slash Commands
-
-You can also invoke enabled skills explicitly from the chat input using slash commands.
-
-1. Type `/` in chat to open command suggestions.
-2. Select the skill command you want to run (for example, `/aws-deploy`).
-3. Cline triggers that skill and loads its `SKILL.md` instructions.
-
-This is useful when you want to force a specific skill immediately instead of waiting for auto-matching based on description.
-
 ## Skill Structure
 
 Every skill is a directory containing a `SKILL.md` file with YAML frontmatter.
@@ -148,7 +138,7 @@ Include real examples. Show what commands to run, what output to expect, and wha
 
 ## Where Skills Live
 
-Skills can be stored globally or in a project workspace. See [Storage Locations](/getting-started/config#storage-locations) for guidance on when to use each.
+Skills can be stored globally or in a project workspace. See [Storage Locations](/customization/overview#storage-locations) for guidance on when to use each.
 
 Project skills:
 - `.cline/skills/` (recommended)
@@ -225,7 +215,7 @@ Cline reads documentation files using `read_file` when the instructions referenc
 | Use Scripts For | Use Instructions For |
 |-----------------|---------------------|
 | Deterministic operations (validation, formatting) | Flexible guidance that adapts to context |
-| Complex computations | Decision-making processes |
+| Complex computations | Decision-making workflows |
 | Operations that need reliability | Steps that might vary by situation |
 | Anything you'd rather not consume tokens explaining | Best practices and patterns |
 
@@ -241,7 +231,7 @@ description: Analyze data files and generate insights. Use when working with CSV
 
 # Data Analysis
 
-When analyzing data files, follow this process:
+When analyzing data files, follow this workflow:
 
 ## 1. Understand the Data
 - Read a sample of the file to understand its structure

docs/customization/workflows.mdx

@@ -0,0 +1,221 @@
+---
+title: "Workflows"
+sidebarTitle: "Workflows"
+description: "Automate repetitive tasks with Markdown-based workflow files."
+---
+
+Workflows are Markdown files that define a series of steps to guide Cline through repetitive or complex tasks. Type `/` followed by the workflow's filename to invoke it (e.g., `/deploy.md`).
+
+Deploying, setting up a new project, running through a release checklist: these tasks often require remembering a dozen steps, running commands in the right order, and updating files manually. Mess up one step and you're debugging for an hour. Workflows turn those multi-step processes into one command. Type `/release.md` and Cline handles the version bump, runs tests, updates the changelog, commits, tags, and pushes. You just review and approve.
+
+## Workflow Structure
+
+A workflow is a markdown file with a title and steps. The filename becomes the command: `demo-workflow.md` is invoked with `/demo-workflow.md`.
+
+````markdown title="demo-workflow.md"
+# Demo Workflow
+
+Brief description of what this workflow accomplishes.
+
+## Step 1: Check prerequisites
+Verify the environment is ready. Look for required tools and dependencies.
+
+## Step 2: Run the build
+Execute the build command:
+```bash
+npm run build
+```
+
+## Step 3: Verify results
+Check that the build completed successfully and report any issues.
+````
+
+Steps can be written at different levels of detail:
+
+- **High-level**: "Run the test suite and fix any failures" lets Cline decide how to accomplish the goal
+- **Specific**: Use XML tool syntax or exact commands when you need precise control
+
+## Creating Workflows
+
+<Steps>
+  <Step title="Open the Workflows menu">
+    Click the scale icon at the bottom of the Cline panel, to the left of the model selector. Switch to the Workflows tab.
+  </Step>
+  <Step title="Create a new workflow file">
+    Click "New workflow file..." and enter a filename (e.g., `deploy`). The file will be created with a `.md` extension.
+  </Step>
+  <Step title="Write your workflow">
+    Add a title and numbered steps in markdown format. Describe what each step should accomplish.
+  </Step>
+</Steps>
+
+<Tip>
+**Create workflows from completed tasks.** After finishing something you'll need to repeat, tell Cline: "Create a workflow for the process I just completed." Cline analyzes the conversation, identifies the steps, and generates the workflow file. Your accumulated context becomes reusable automation.
+</Tip>
+
+### Invoking Workflows
+
+Type `/` in the chat input to see available workflows. Cline shows autocomplete suggestions as you type, so `/rel` would match `release-prep.md`. Select a workflow and press Enter to start it.
+
+Cline executes each step in sequence, pausing for your approval when needed. You can stop a workflow at any point by rejecting a step.
+
+### Toggling Workflows
+
+Every workflow has a toggle to enable or disable it. This lets you control which workflows appear in the `/` menu without deleting the file.
+
+## Where Workflows Live
+
+Workflows can be stored in two locations: your project workspace or globally on your system.
+
+**Workspace workflows** go in `.clinerules/workflows/` at your project root. Use these for project-specific automation like deployment scripts, release processes, or setup procedures that your team shares.
+
+**Global workflows** go in your system's Cline Workflows directory. Use these for personal productivity workflows you use across all projects.
+
+### Global Workflows Directory
+
+| Operating System | Default Location |
+|------------------|------------------|
+| Windows | `Documents\Cline\Workflows` |
+| macOS | `~/Documents/Cline/Workflows` |
+| Linux/WSL | `~/Documents/Cline/Workflows` |
+
+Workspace workflows take precedence when names match global workflows. See [Storage Locations](/customization/overview#storage-locations) for more guidance.
+
+## What Workflows Can Use
+
+Workflows can combine natural language instructions with specific tool calls. This flexibility lets you write workflows that are as simple or as precise as your task requires.
+
+### Natural Language
+
+Write steps as plain instructions. Cline interprets them and figures out which tools to use:
+
+```markdown
+## Step 1: Check for uncommitted changes
+Look at the git status. If there are uncommitted changes, ask whether to continue or abort.
+
+## Step 2: Run the test suite
+Execute all tests. If any fail, show the failures and stop.
+```
+
+This approach works well when you want Cline to adapt to the situation rather than follow rigid steps.
+
+### Cline Tools
+
+For precise control, use Cline's built-in tools with XML syntax. This guarantees specific actions:
+
+```xml
+<execute_command>
+  <command>npm run test</command>
+  <requires_approval>false</requires_approval>
+</execute_command>
+```
+
+```xml
+<read_file>
+  <path>src/config.json</path>
+</read_file>
+```
+
+```xml
+<ask_followup_question>
+  <question>Deploy to production or staging?</question>
+  <options>["Production", "Staging", "Cancel"]</options>
+</ask_followup_question>
+```
+
+See the full list in the [Cline Tools Reference](/tools-reference/all-cline-tools).
+
+### CLI Tools
+
+Reference any command-line tool installed on your machine. Git, npm, docker, gh, make, curl: whatever you have available.
+
+```bash
+git log --author="$(git config user.name)" --since="yesterday" --oneline
+```
+
+### MCP Tools
+
+If you have [MCP servers](/mcp/mcp-overview) connected, use them in your workflows with the `use_mcp_tool` syntax. This lets you integrate with external services like GitHub, Slack, databases, or custom internal tools.
+
+```xml
+<use_mcp_tool>
+<server_name>github-server</server_name>
+<tool_name>create_release</tool_name>
+<arguments>{"tag": "v1.2.0", "name": "Release v1.2.0", "body": "Changelog content here"}</arguments>
+</use_mcp_tool>
+```
+
+Or describe the intent in natural language and let Cline figure out the tool call:
+
+```markdown
+## Step 3: Create GitHub release
+Use the GitHub MCP server to create a release tagged with the version from package.json.
+Include the changelog as the release body.
+```
+
+## Writing Effective Workflows
+
+**Start simple.** Write natural language steps first. Only add XML tool calls when you need guaranteed behavior.
+
+**Be specific about decisions.** If a step requires user input, make that explicit: "Ask whether to deploy to production or staging."
+
+**Include failure handling.** Tell Cline what to do when something goes wrong: "If tests fail, show the failures and stop the workflow."
+
+**Keep workflows focused.** A `deploy.md` should deploy. A `setup-db.md` should set up the database. Split complex processes into multiple workflows that can be run independently.
+
+**Version control your workflows.** Store workflows in `.clinerules/workflows/` and commit them. Your team can share, review, and improve them together.
+
+<Warning>
+Workflows execute with your permissions. Review workflows before running them, especially those from external sources.
+</Warning>
+
+## Example: Release Preparation
+
+This workflow automates the tedious pre-release checklist. It verifies your working directory is clean, runs tests and builds, prompts you for the version bump, and generates a changelog from recent commits.
+
+The workflow demonstrates both approaches: XML tool syntax (`<execute_command>`, `<ask_followup_question>`) for steps that need precise control, and natural language for steps where Cline should adapt to the situation.
+
+````markdown title="release-prep.md"
+# Release Preparation
+
+Prepare a new release by running tests, building, and updating version info.
+
+## Step 1: Check for clean working directory
+<execute_command>
+<command>git status --porcelain</command>
+</execute_command>
+
+If there are uncommitted changes, ask whether to continue or stash them first.
+
+## Step 2: Run the test suite
+<execute_command>
+<command>npm run test</command>
+</execute_command>
+
+If any tests fail, stop the workflow and report the failures.
+
+## Step 3: Build the project
+<execute_command>
+<command>npm run build</command>
+</execute_command>
+
+Verify the build completes without errors.
+
+## Step 4: Ask for new version
+<ask_followup_question>
+<question>What should the new version be?</question>
+<options>["Patch (x.x.X)", "Minor (x.X.0)", "Major (X.0.0)", "Custom"]</options>
+</ask_followup_question>
+
+## Step 5: Update version
+Update the version in `package.json` to the new version specified by the user.
+
+## Step 6: Generate changelog entry
+<execute_command>
+<command>git log --oneline $(git describe --tags --abbrev=0)..HEAD</command>
+</execute_command>
+
+Use these commits to write a changelog entry for the new version.
+````
+
+Invoke it with `/release-prep.md` and Cline walks through each step.

docs/enterprise-solutions/api-reference.mdx

@@ -4,7 +4,7 @@ sidebarTitle: "API Reference"
 description: "REST API endpoints for managing users, organizations, billing, plans, and API keys."
 ---
 
-The Enterprise API provides REST endpoints for account management, organization administration, billing, and API key management. These are separate from the [Chat Completions API](/api/overview), which handles model inference.
+The Enterprise API provides REST endpoints for account management, organization administration, billing, and API key management. These are separate from the [Chat Completions API](/api/reference), which handles model inference.
 
 ## Base URL
 
@@ -20,7 +20,7 @@ All endpoints require a Bearer token in the `Authorization` header:
 Authorization: Bearer YOUR_AUTH_TOKEN
 ```
 
-Use the same API key or account auth token described in the [public API reference](/api/overview#authentication).
+Use the same API key or account auth token described in the [public API reference](/api/reference#authentication).
 
 ## Quick Example
 
@@ -180,7 +180,7 @@ Track token consumption and costs across your organization.
 
 ## API Keys
 
-Create and manage API keys for programmatic access. Keys created here work with both the [Chat Completions API](/api/overview) and the endpoints on this page.
+Create and manage API keys for programmatic access. Keys created here work with both the [Chat Completions API](/api/reference) and the endpoints on this page.
 
 | Method | Endpoint | Description |
 |--------|----------|-------------|
@@ -193,7 +193,7 @@ Create and manage API keys for programmatic access. Keys created here work with
 ## Related
 
 <CardGroup cols={2}>
-  <Card title="Chat Completions API" icon="code" href="/api/overview">
+  <Card title="Chat Completions API" icon="code" href="/api/reference">
     The public inference API for sending prompts and receiving completions.
   </Card>
   <Card title="SSO Setup" icon="key" href="/enterprise-solutions/sso-setup">

docs/enterprise-solutions/configuration/remote-configuration/anthropic/admin-configuration.mdx

@@ -1,98 +0,0 @@
----
-title: "Configure Anthropic Provider (Admin)"
-sidebarTitle: "Configure Anthropic (Admin)"
-description: "This guide explains how administrators configure Anthropic as the organization-wide LLM provider for Cline."
----
-
-
-As an administrator, you can add Anthropic as the organization-wide LLM provider for all Cline users through the hosted admin console. This centralized approach provides direct access to Anthropic's Claude models, with an optional custom base URL for organizations that route traffic through a proxy.
-
-## Before You Begin
-
-To get started with setting up Anthropic as your organization's LLM provider, you'll need a few items in place.
-
-**Administrator access to the Cline Admin console**  
-You need admin privileges to enforce provider settings across your organization. If you can navigate to **Settings → Cline Settings** in the admin console at [app.cline.bot](https://app.cline.bot), you have the right access level.
-
-**Anthropic API access**  
-Your organization needs an Anthropic account with API access to Claude models. Members will need individual API keys to authenticate.
-
-<Note>
-If your organization requires routing API traffic through a proxy or custom endpoint, have the proxy URL ready before configuring.
-</Note>
-
-## Configuration Steps
-
-<Steps>
-<Step title="Access Cline Settings">
-Navigate to [app.cline.bot](https://app.cline.bot) and sign in with your administrator account. Go to **Settings → Cline Settings**.
-
-<Info>
-You should see the provider configuration options if you have the correct admin access level.
-</Info>
-</Step>
-
-<Step title="Enable Remote Provider Configuration">
-Toggle on **Enable settings** to reveal the remote provider configuration options. This allows you to enforce provider settings across your organization.
-</Step>
-
-<Step title="Select Anthropic as the API Provider">
-Open the **API Provider** dropdown menu and select **Anthropic**. This will open the Anthropic configuration panel where you'll configure all your organization-wide settings.
-</Step>
-
-<Step title="Configure Anthropic Settings">
-The configuration panel includes settings that control how Anthropic works for your organization:
-
-<AccordionGroup>
-<Accordion title="Base URL (optional)">
-By default, Cline connects directly to the Anthropic API (`https://api.anthropic.com`). If your organization routes API traffic through a proxy or custom endpoint, enter the base URL here.
-
-Use cases for a custom base URL:
-- Corporate proxy that logs or filters API traffic
-- Self-hosted API gateway for rate limiting or access control
-- Regional routing requirements
-
-Leave this empty to use the default Anthropic API endpoint.
-
-<Tip>
-If using a proxy, ensure it correctly forwards requests to the Anthropic API and preserves all required headers.
-</Tip>
-</Accordion>
-</AccordionGroup>
-</Step>
-
-<Step title="Save Configuration">
-After configuring your settings, close the provider configuration panel and click **Save** on the settings page to persist your changes.
-
-Once saved, all organization members signed into the Cline extension will automatically use Anthropic with your configured settings. They won't be able to select other providers or switch to their personal Cline accounts.
-
-<Warning>
-Members can't switch to personal Cline accounts or join other organizations once remote configuration is enabled. This ensures consistent provider usage across your team.
-</Warning>
-</Step>
-</Steps>
-
-## Verification
-
-To verify the configuration:
-
-1. Check that the provider shows as "Anthropic" in the Enabled provider field
-2. Confirm the settings persist after refreshing the page
-3. Test with a member account to ensure they see only Anthropic as a provider
-4. Verify that Claude models are available in the model dropdown
-
-## Troubleshooting
-
-**Members don't see the configured provider**  
-Ensure you clicked Save after closing the configuration panel. Verify the member account belongs to the correct organization.
-
-**Connection errors when using a custom base URL**  
-Verify the proxy URL is correct and accessible from your team's development environments. Ensure the proxy correctly forwards requests to the Anthropic API.
-
-**Configuration changes don't persist**  
-Make sure to click the Save button on the main settings page, not just close the configuration panel.
-
-**Need to change settings later**  
-You can update the base URL or other settings at any time. Changes take effect immediately for all organization members.
-
-For further details, consult the [Anthropic API documentation](https://docs.anthropic.com/) and coordinate with your infrastructure team.

docs/enterprise-solutions/configuration/remote-configuration/anthropic/member-configuration.mdx

@@ -1,95 +0,0 @@
----
-title: "Configure Anthropic in VS Code (Members)"
-sidebarTitle: "Configure Anthropic (Member)"
-description: "Guide for engineers connecting to their organization's Anthropic provider through VS Code after admin setup"
----
-
-As a team member, you can connect your local development environment to your organization's Anthropic provider setup. This guide walks you through configuring your API key in VS Code so you can start using Claude models through your organization's configuration. Your administrator has already configured the provider settings — you just need to add your API key to get started.
-
-## Before You Begin
-
-To successfully connect to your organization's Anthropic provider, you'll need a few things ready.
-
-**Cline extension installed and configured**  
-The Cline extension must be installed in VS Code and you need to be signed into your organization account. If you haven't installed Cline yet, follow our [installation guide](/getting-started/installing-cline).
-
-<Info>
-**Quick Check**: Open the Cline panel in VS Code. If you see your organization name in the bottom left, you're signed in correctly.
-</Info>
-
-**Anthropic API key**  
-You need an API key from Anthropic to authenticate requests. Your organization may provide keys centrally or require you to create one through the [Anthropic Console](https://console.anthropic.com/).
-
-<Note>
-If you're unsure how to obtain an API key, check with your administrator about your organization's key provisioning process.
-</Note>
-
-## Configuration Steps
-
-<Steps>
-<Step title="Open Cline Settings">
-Open VS Code and access the Cline settings panel using either of these methods:
-
-- Click the settings icon (⚙️) in the Cline panel
-- Click on the API Provider dropdown located directly below the chat area
-
-</Step>
-
-<Step title="Enter Your API Key">
-
-1. Select or confirm the **Anthropic** provider is selected
-2. Enter your Anthropic API key in the **API Key** field
-3. If your administrator configured a custom base URL, it will already be set and locked
-4. Click **Save** to store your credentials
-
-<Tip>
-API keys are stored locally and are only used by the Cline extension.
-</Tip>
-
-<Note>
-The base URL setting is controlled by your administrator. If a custom proxy URL is configured, your API requests will be routed through it automatically.
-</Note>
-</Step>
-
-<Step title="Verify Configuration">
-After entering your API key, administrator-controlled settings (such as base URL) will be locked (shown with a lock icon 🔒) as they're managed by your organization.
-</Step>
-
-<Step title="Test the Connection">
-Send a test message in Cline to verify your API key works correctly with the configured Anthropic endpoint.
-
-<Tip>
-**Testing Recommendation**
-
-Try a simple test like "Hello" first to verify basic connectivity before starting development tasks.
-</Tip>
-</Step>
-</Steps>
-
-## Troubleshooting
-
-**Anthropic not available as provider option**  
-Confirm you're signed into the correct Cline organization. Verify your administrator has saved the Anthropic configuration and that you have the latest version of the Cline extension.
-
-**Authentication errors ("Invalid API Key" or "Unauthorized")**  
-Verify your API key is correct and active. Check the [Anthropic Console](https://console.anthropic.com/) to confirm your key status and that it has sufficient permissions.
-
-**Connection errors or timeouts**  
-If your administrator configured a custom base URL (proxy), check with your IT team about network requirements. If using the default Anthropic endpoint, ensure you have internet access to `api.anthropic.com`.
-
-**Models not available**  
-The available models depend on your Anthropic API plan and your organization's configuration. Contact your administrator if expected models are not available.
-
-**Rate limit errors**  
-Your API key may have rate limits configured by Anthropic. If you encounter rate limit errors during normal use, contact your administrator about adjusting limits or managing key usage across the team.
-
-## Security Best Practices
-
-When working with your Anthropic API key:
-
-- Keep your API key secure and do not share it
-- Never store your API key in code or version control
-- Report any suspected key compromise to your administrator immediately
-- Regularly check the [Anthropic Console](https://console.anthropic.com/) for unusual usage patterns
-
-For further details, consult the [Anthropic API documentation](https://docs.anthropic.com/) and coordinate with your organization's administrator.

docs/enterprise-solutions/configuration/remote-configuration/openai-compatible/admin-configuration.mdx

@@ -1,138 +0,0 @@
----
-title: "Configure OpenAI Compatible Provider (Admin)"
-sidebarTitle: "Configure OpenAI Compatible (Admin)"
-description: "This guide explains how administrators configure an OpenAI-compatible endpoint as the organization-wide LLM provider for Cline."
----
-
-
-As an administrator, you can add an OpenAI-compatible endpoint as the organization-wide LLM provider for all Cline users through the hosted admin console. This covers any provider that exposes an OpenAI-compatible API, including Azure Foundry (Azure OpenAI), self-hosted inference engines (vLLM, TGI), and other compatible services.
-
-## Before You Begin
-
-To get started with setting up an OpenAI-compatible provider for your organization, you'll need a few items in place.
-
-**Administrator access to the Cline Admin console**  
-You need admin privileges to enforce provider settings across your organization. If you can navigate to **Settings → Cline Settings** in the admin console at [app.cline.bot](https://app.cline.bot), you have the right access level.
-
-**An OpenAI-compatible API endpoint**  
-You need a running endpoint that implements the OpenAI chat completions API. This could be:
-- Azure Foundry (Azure OpenAI Service)
-- A self-hosted inference engine (vLLM, text-generation-inference, etc.)
-- Any third-party service with an OpenAI-compatible API
-
-<Note>
-If you're using Azure Foundry, you'll need your Azure OpenAI endpoint URL and optionally the API version. Work with your Azure administrator to ensure the endpoint is provisioned and accessible.
-</Note>
-
-**Endpoint URL and authentication details**  
-You'll need the base URL of your endpoint and any required authentication headers.
-
-## Configuration Steps
-
-<Steps>
-<Step title="Access Cline Settings">
-Navigate to [app.cline.bot](https://app.cline.bot) and sign in with your administrator account. Go to **Settings → Cline Settings**.
-
-<Info>
-You should see the provider configuration options if you have the correct admin access level.
-</Info>
-</Step>
-
-<Step title="Enable Remote Provider Configuration">
-Toggle on **Enable settings** to reveal the remote provider configuration options. This allows you to enforce provider settings across your organization.
-</Step>
-
-<Step title="Select OpenAI Compatible as the API Provider">
-Open the **API Provider** dropdown menu and select **OpenAI Compatible**. This will open the configuration panel where you'll configure all your organization-wide settings.
-</Step>
-
-<Step title="Configure OpenAI Compatible Settings">
-The configuration panel includes settings that control how the provider works for your organization:
-
-<AccordionGroup>
-<Accordion title="Base URL (required)">
-Enter the base URL of your OpenAI-compatible endpoint. Examples:
-
-- **Azure Foundry**: `https://your-resource.openai.azure.com`
-- **Self-hosted vLLM**: `https://inference.yourcompany.com/v1`
-- **Other compatible services**: The provider's API base URL
-
-<Tip>
-Use HTTPS endpoints in production for security. Ensure the URL is accessible from your team's development environments.
-</Tip>
-</Accordion>
-
-<Accordion title="Custom Headers (optional)">
-Add custom HTTP headers that will be included with every API request. This is useful for:
-
-- Custom authentication schemes beyond API keys
-- Routing headers for internal load balancers
-- Organization or tenant identifiers required by your endpoint
-
-Headers are configured as key-value pairs.
-</Accordion>
-
-<Accordion title="Azure API Version (optional — Azure Foundry only)">
-If you're using Azure Foundry (Azure OpenAI), specify the API version string. For example: `2024-02-15-preview` or `2024-06-01`.
-
-This field is only needed for Azure OpenAI deployments. Leave it empty for non-Azure endpoints.
-
-<Note>
-Check the [Azure OpenAI API version documentation](https://learn.microsoft.com/en-us/azure/ai-services/openai/reference) for available versions.
-</Note>
-</Accordion>
-
-<Accordion title="Azure Identity Authentication (optional — Azure Foundry only)">
-Enable this to use Azure Active Directory (Entra ID) token-based authentication instead of API keys. When enabled, members authenticate using their Azure AD credentials rather than a static API key.
-
-This field is only relevant for Azure Foundry deployments.
-</Accordion>
-</AccordionGroup>
-</Step>
-
-<Step title="Save Configuration">
-After configuring your settings, close the provider configuration panel and click **Save** on the settings page to persist your changes.
-
-Once saved, all organization members signed into the Cline extension will automatically use the OpenAI Compatible provider with your configured settings. They won't be able to select other providers or switch to their personal Cline accounts.
-
-<Warning>
-Members can't switch to personal Cline accounts or join other organizations once remote configuration is enabled. This ensures consistent provider usage across your team.
-</Warning>
-</Step>
-</Steps>
-
-## Azure Foundry Configuration
-
-For organizations using Azure Foundry (Azure OpenAI Service), use the following configuration:
-
-1. **Base URL**: Your Azure OpenAI endpoint (e.g., `https://your-resource.openai.azure.com`)
-2. **Azure API Version**: The API version to use (e.g., `2024-06-01`)
-3. **Azure Identity Authentication**: Enable if your organization uses Azure AD for authentication instead of API keys
-
-## Verification
-
-To verify the configuration:
-
-1. Check that the provider shows as "OpenAI Compatible" in the Enabled provider field
-2. Confirm the settings persist after refreshing the page
-3. Test with a member account to ensure they see only the OpenAI Compatible provider
-4. Verify that configured models are available in the model dropdown
-
-## Troubleshooting
-
-**Members don't see the configured provider**  
-Ensure you clicked Save after closing the configuration panel. Verify the member account belongs to the correct organization.
-
-**Connection errors to the endpoint**  
-Verify the Base URL is correct and accessible from your team's development environments. Check that any firewalls or security groups allow access from developer IP addresses.
-
-**Azure authentication failures**  
-If using Azure Identity Authentication, verify that members' Azure AD accounts have the appropriate role assignments on the Azure OpenAI resource. If using API keys, verify the key is correctly entered by the member.
-
-**Configuration changes don't persist**  
-Make sure to click the Save button on the main settings page, not just close the configuration panel.
-
-**Need to change endpoint or settings later**  
-You can update these settings at any time. Changes take effect immediately for all organization members.
-
-For Azure Foundry, consult the [Azure OpenAI Service documentation](https://learn.microsoft.com/en-us/azure/ai-services/openai/). For other OpenAI-compatible endpoints, refer to your provider's documentation.

docs/enterprise-solutions/configuration/remote-configuration/openai-compatible/member-configuration.mdx

@@ -1,117 +0,0 @@
----
-title: "Configure OpenAI Compatible in VS Code (Members)"
-sidebarTitle: "Configure OpenAI Compatible (Member)"
-description: "Guide for engineers connecting to their organization's OpenAI-compatible endpoint through VS Code after admin setup"
----
-
-As a team member, you can connect your local development environment to your organization's OpenAI-compatible endpoint. This guide walks you through configuring your credentials in VS Code so you can start using models through your organization's configured endpoint. Your administrator has already configured the provider settings — you just need to add your API key to get started.
-
-## Before You Begin
-
-To successfully connect to your organization's OpenAI-compatible endpoint, you'll need a few things ready.
-
-**Cline extension installed and configured**  
-The Cline extension must be installed in VS Code and you need to be signed into your organization account. If you haven't installed Cline yet, follow our [installation guide](/getting-started/installing-cline).
-
-<Info>
-**Quick Check**: Open the Cline panel in VS Code. If you see your organization name in the bottom left, you're signed in correctly.
-</Info>
-
-**API key or credentials for your endpoint**  
-You need an API key or credentials to authenticate with your organization's configured endpoint. For Azure Foundry deployments using Azure Identity Authentication, your Azure AD credentials may be used instead.
-
-<Note>
-If you're unsure what credentials to use, check with your administrator or IT team about how your organization has configured access.
-</Note>
-
-## Configuration Steps
-
-<Steps>
-<Step title="Open Cline Settings">
-Open VS Code and access the Cline settings panel using either of these methods:
-
-- Click the settings icon (⚙️) in the Cline panel
-- Click on the API Provider dropdown located directly below the chat area
-
-</Step>
-
-<Step title="Configure Your Credentials">
-The authentication method depends on how your administrator configured the endpoint:
-
-<AccordionGroup>
-<Accordion title="API Key Authentication">
-For most OpenAI-compatible endpoints:
-
-1. Select or confirm the **OpenAI Compatible** provider is selected
-2. Enter your API key in the **API Key** field
-3. The base URL, custom headers, and other settings are preconfigured by your administrator
-4. Click **Save** to store your credentials
-
-<Tip>
-API keys are stored locally and are only used by the Cline extension.
-</Tip>
-</Accordion>
-
-<Accordion title="Azure Identity Authentication (Azure Foundry)">
-If your organization uses Azure AD authentication:
-
-1. Select or confirm the **OpenAI Compatible** provider is selected
-2. Ensure you are signed into Azure in your development environment
-3. The extension will use your Azure AD credentials automatically
-4. No API key is needed when Azure Identity Authentication is enabled
-
-<Note>
-You may need the Azure Account extension or Azure CLI installed for credential resolution.
-</Note>
-</Accordion>
-</AccordionGroup>
-
-<Note>
-The Base URL, custom headers, Azure API version, and Azure Identity settings are preconfigured by your administrator and do not need to be set in the extension.
-</Note>
-</Step>
-
-<Step title="Verify Configuration">
-After configuring your credentials, administrator-controlled settings will be locked (shown with a lock icon 🔒) as they're managed by your organization.
-</Step>
-
-<Step title="Test the Connection">
-Send a test message in Cline to verify your credentials work correctly with the configured endpoint.
-
-<Tip>
-**Testing Recommendation**
-
-Try a simple test like "Hello" first to verify basic connectivity before starting development tasks.
-</Tip>
-</Step>
-</Steps>
-
-## Troubleshooting
-
-**OpenAI Compatible not available as provider option**  
-Confirm you're signed into the correct Cline organization. Verify your administrator has saved the configuration and that you have the latest version of the Cline extension.
-
-**Authentication errors ("Access Denied" or "Invalid API Key")**  
-Verify your API key is correct and active. For Azure Foundry with Azure Identity Authentication, ensure you are signed into Azure in your development environment and that your account has the appropriate role assignments on the Azure OpenAI resource.
-
-**Connection errors or timeouts**  
-The endpoint URL is configured by your administrator. If you experience connection issues, check with your IT team about network requirements (VPN, firewall rules, etc.).
-
-**Models not available**  
-The available models depend on your organization's endpoint configuration. Contact your administrator if expected models are not available in the model dropdown.
-
-**Configuration changes don't persist**  
-Make sure to save your credentials. The base URL and other admin-controlled settings cannot be changed locally.
-
-## Security Best Practices
-
-When working with your API credentials:
-
-- Keep your API key secure and do not share it
-- Never store credentials in code or version control
-- Report any suspected key compromise to your administrator immediately
-- Follow your organization's usage guidelines for the configured endpoint
-
-Your organization administrator controls which endpoint, models, and settings are available. The extension will automatically apply the configured settings based on your organization's remote configuration.
-
-For Azure Foundry, refer to the [Azure OpenAI Service documentation](https://learn.microsoft.com/en-us/azure/ai-services/openai/). For other endpoints, consult your organization's internal documentation or contact your administrator.

docs/enterprise-solutions/configuration/remote-configuration/overview.mdx

@@ -1,11 +1,11 @@
 ---
-title: "Enterprise Provider Configuration"
+title: "SaaS Provider Configuration"
 sidebarTitle: "Overview"
 description: "Configure inference providers through the Cline hosted admin console for centralized organization management"
 ---
 
 
-Remote Provider Configuration allows administrators to centrally configure inference providers for their entire organization through the Cline hosted admin console. This approach ensures consistent provider access, security policies, and cost management across all team members without requiring individual developer setup or infrastructure deployment.
+SaaS Provider Configuration allows administrators to centrally configure inference providers for their entire organization through the Cline hosted admin console. This approach ensures consistent provider access, security policies, and cost management across all team members without requiring individual developer setup or infrastructure deployment.
 
 ## How Remote Configuration Works
 
@@ -35,17 +35,11 @@ Cline supports remote configuration for the following inference providers:
 
 | Provider | Use Case | Configuration | Member Setup |
 |----------|----------|---------------|--------------|
-| **Cline** | Organizations using Cline's native provider with centralized API key management | API provider selection, model access | No individual API keys needed — fully managed by organization |
-| **Amazon Bedrock** | Organizations using AWS infrastructure | Region selection, VPC endpoints, cross-region inference, global inference, prompt caching | AWS credential configuration (API key, CLI profile, or credential chain) |
-| **Google Vertex AI** | Organizations using Google Cloud Platform | Project ID, region selection, model access | Google Cloud credential configuration (service account, SDK, or ADC) |
-| **Azure Foundry** | Organizations using Azure OpenAI or Azure AI services | Base URL, Azure API version, Azure identity authentication, custom headers | API key configuration in the extension |
-| **Anthropic** | Organizations using the Anthropic API directly | Optional custom base URL for proxy deployments, model access | API key configuration in the extension |
-| **OpenAI Compatible** | Organizations using any OpenAI-compatible endpoint (self-hosted, vLLM, custom proxies) | Base URL, custom headers, model access | API key configuration in the extension |
-| **LiteLLM** | Organizations requiring multi-model access through a unified proxy | Proxy endpoint, authentication, model routing | API key or endpoint configuration (or centralized with Master Key) |
+| **Cline** | Organizations using Cline's native provider with centralized API key management | API provider selection, model access | No individual API keys needed - fully managed by organization |
+| **Amazon Bedrock** | Organizations using AWS infrastructure | Region selection, VPC endpoints, cross-region inference, prompt caching | AWS credential configuration in VS Code |
+| **LiteLLM** | Organizations requiring multi-model access through a unified proxy | Proxy endpoint, authentication, model routing | API key or endpoint configuration in VS Code (or centralized with Master Key) |
+| **Google Vertex AI** | Organizations using Google Cloud Platform | Project ID, region selection, model access | Service account or credential configuration in VS Code |
 
-<Note>
-**Azure Foundry** uses the OpenAI Compatible provider configuration with Azure-specific settings (API version, Azure identity authentication). See the [OpenAI Compatible admin configuration](/enterprise-solutions/configuration/remote-configuration/openai-compatible/admin-configuration) for setup instructions.
-</Note>
 
 ## Configuration Process
 
@@ -61,7 +55,7 @@ Provider configuration is automatically distributed to all organization members
 </Step>
 
 <Step title="Member Credential Setup">
-Team members add their individual credentials (API keys, AWS profiles, etc.) to connect to the configured provider. For some providers like Cline and LiteLLM (with Master Key), no individual credentials are needed.
+Team members add their individual credentials (API keys, AWS profiles, etc.) to connect to the configured provider.
 </Step>
 
 <Step title="Immediate Access">
@@ -98,19 +92,11 @@ Select your provider below to begin the configuration process:
     AWS-based AI models with enterprise security and compliance features.
   </Card>
   
-  <Card title="Google Vertex AI" icon="google" href="/enterprise-solutions/configuration/remote-configuration/google-vertex/admin-configuration">
-    Google Cloud's AI platform with Gemini models and regional control.
-  </Card>
-
-  <Card title="OpenAI Compatible" icon="plug" href="/enterprise-solutions/configuration/remote-configuration/openai-compatible/admin-configuration">
-    Any OpenAI-compatible endpoint, including Azure Foundry.
-  </Card>
-
-  <Card title="Anthropic" icon="robot" href="/enterprise-solutions/configuration/remote-configuration/anthropic/admin-configuration">
-    Direct Anthropic API access with optional custom base URL configuration.
-  </Card>
-
   <Card title="LiteLLM" icon="layer-group" href="/enterprise-solutions/configuration/remote-configuration/litellm/admin-configuration">
     Unified proxy for accessing 100+ AI models through a single interface.
   </Card>
+  
+  <Card title="Google Vertex AI" icon="google" href="/enterprise-solutions/configuration/remote-configuration/google-vertex/admin-configuration">
+    Google Cloud's AI platform with advanced ML capabilities and global infrastructure.
+  </Card>
 </CardGroup>

docs/enterprise-solutions/monitoring/opentelemetry-events.mdx

@@ -1,630 +0,0 @@
----
-title: "OpenTelemetry Events Reference"
-sidebarTitle: "OTel Events"
-description: "Complete reference of OpenTelemetry log events emitted by Cline"
----
-
-This page documents all OpenTelemetry log events currently instrumented in Cline. These events are emitted when OpenTelemetry integration is enabled and provide detailed insights into user behavior, task execution, and system operations.
-
-<Info>
-Events are only emitted when OpenTelemetry is enabled. See [OpenTelemetry](/enterprise-solutions/monitoring/opentelemetry) for configuration instructions.
-</Info>
-
-## Event Categories
-
-Cline emits events across several categories, each prefixed with a namespace:
-
-<CardGroup cols={3}>
-  <Card title="user.*" icon="user">
-    Authentication, telemetry controls, extension lifecycle
-  </Card>
-  
-  <Card title="task.*" icon="list-check">
-    Task execution, conversation turns, tool usage, tokens
-  </Card>
-  
-  <Card title="workspace.*" icon="folder-tree">
-    Workspace initialization, VCS detection, path resolution
-  </Card>
-  
-  <Card title="ui.*" icon="window">
-    User interface interactions and model selection
-  </Card>
-  
-  <Card title="hooks.*" icon="webhook">
-    Hook discovery, execution, and context modification
-  </Card>
-  
-  <Card title="worktree.*" icon="code-branch">
-    Git worktree operations and merge handling
-  </Card>
-  
-  <Card title="host.*" icon="computer">
-    Host environment detection
-  </Card>
-  
-  <Card title="test.*" icon="flask">
-    Diagnostic and connection testing
-  </Card>
-</CardGroup>
-
-## User Events
-
-Events related to user authentication, telemetry preferences, and extension lifecycle.
-
-| Event | Description | Key Attributes |
-|-------|-------------|----------------|
-| `user.opt_out` | User explicitly opts out of telemetry | user_id, timestamp |
-| `user.opt_in` | User explicitly opts into telemetry | user_id, timestamp |
-| `user.telemetry_enabled` | Telemetry service enabled/initialization signal | enabled, timestamp |
-| `user.extension_activated` | Extension activation event | extension_version, host_type |
-| `user.extension_storage_error` | Error while reading/writing extension storage state | error_type, error_message |
-| `user.auth_started` | Authentication flow started | provider, timestamp |
-| `user.auth_succeeded` | Authentication flow succeeded | provider, user_id |
-| `user.auth_failed` | Authentication flow failed | provider, error_reason |
-| `user.auth_logged_out` | User logged out | reason, provider |
-| `user.onboarding_progress` | Onboarding step/action progress | step, action, completed |
-
-### Example: user.auth_succeeded
-
-```json
-{
-  "event": "user.auth_succeeded",
-  "timestamp": "2026-03-05T10:30:00Z",
-  "attributes": {
-    "provider": "github",
-    "user_id": "user_abc123",
-    "session_id": "sess_xyz789"
-  }
-}
-```
-
-## Workspace Events
-
-Events related to workspace initialization, version control detection, and multi-root operations.
-
-| Event | Description | Key Attributes |
-|-------|-------------|----------------|
-| `workspace.initialized` | Workspace initialization completed | roots_count, vcs_type, duration_ms |
-| `workspace.init_error` | Workspace initialization failed | error_type, fallback_used |
-| `workspace.vcs_detected` | Version control system detection event | vcs_type, root_path_hash |
-| `workspace.multi_root_checkpoint` | Multi-root checkpoint operation telemetry | operation, roots_count, duration_ms |
-| `workspace.path_resolved` | Workspace path resolution | hint, fallback_used, cross_workspace |
-
-### Example: workspace.initialized
-
-```json
-{
-  "event": "workspace.initialized",
-  "timestamp": "2026-03-05T10:32:15Z",
-  "attributes": {
-    "roots_count": 2,
-    "vcs_type": "git",
-    "duration_ms": 145,
-    "multi_root_enabled": true
-  }
-}
-```
-
-## Task Events
-
-Core events tracking task lifecycle, conversation turns, tool usage, and execution details.
-
-### Task Lifecycle
-
-| Event | Description | Key Attributes |
-|-------|-------------|----------------|
-| `task.created` | New task/conversation started | task_id, mode, model, provider |
-| `task.restarted` | Existing task restarted/reopened | task_id, time_since_last_message |
-| `task.completed` | Task completed | task_id, duration_ms, model, provider, tokens_total |
-| `task.feedback` | User feedback on task | task_id, feedback_type (thumbs_up/thumbs_down) |
-| `task.historical_loaded` | Historical task loaded from storage | task_id, age_days |
-| `task.retry_clicked` | User clicked retry on a failed action/request | task_id, action_type |
-
-### Conversation & Tokens
-
-| Event | Description | Key Attributes |
-|-------|-------------|----------------|
-| `task.conversation_turn` | Conversation turn event | role (user/assistant), provider, model, tokens_in, tokens_out |
-| `task.tokens` | Token usage event | tokens_in, tokens_out, cached_tokens, cost |
-| `task.mode` | Plan/Act mode switch event | previous_mode, new_mode, task_id |
-
-### Tool Usage
-
-| Event | Description | Key Attributes |
-|-------|-------------|----------------|
-| `task.tool_used` | Tool invocation and outcome telemetry | tool_name, success, duration_ms, auto_approved |
-| `task.mcp_tool_called` | MCP tool call lifecycle event | status (started/success/error), tool_name, server_name |
-| `task.browser_tool_start` | Browser tool/session started | url, action |
-| `task.browser_tool_end` | Browser tool/session ended with stats | duration_ms, actions_count, success |
-| `task.browser_error` | Browser tool error event | error_type, url |
-| `task.terminal_execution` | Terminal execution capture success/failure event | success, command_hash, duration_ms |
-| `task.terminal_output_failure` | Terminal output capture failed | reason |
-| `task.terminal_user_intervention` | User intervention during terminal execution | intervention_type |
-| `task.terminal_hang` | Terminal hang/stuck detection event | duration_ms, command_hash |
-
-### Features & Options
-
-| Event | Description | Key Attributes |
-|-------|-------------|----------------|
-| `task.checkpoint_used` | Checkpoint action used | action (create/restore/compare), task_id |
-| `task.option_selected` | User selected one of AI-provided options | option_index, total_options |
-| `task.options_ignored` | User ignored AI options and entered custom input | options_count |
-| `task.slash_command_used` | Slash command or MCP prompt command used | command_name |
-| `task.mention_used` | Mention resolution succeeded | mention_type (file/url/folder/terminal/problems/git) |
-| `task.mention_failed` | Mention resolution failed | mention_type, error_reason |
-| `task.mention_search_results` | Mention search query result telemetry | query, results_count |
-| `task.workspace_search_pattern` | Workspace search strategy/pattern telemetry | pattern_type, files_scanned |
-
-### Advanced Features
-
-| Event | Description | Key Attributes |
-|-------|-------------|----------------|
-| `task.focus_chain_enabled` | Focus chain feature enabled | task_id |
-| `task.focus_chain_disabled` | Focus chain feature disabled | task_id |
-| `task.focus_chain_progress_first` | First focus-chain checklist/progress emitted | items_count |
-| `task.focus_chain_progress_update` | Subsequent focus-chain checklist/progress updates | items_total, items_completed |
-| `task.focus_chain_incomplete_on_completion` | Task completed while focus-chain checklist still incomplete | items_remaining |
-| `task.focus_chain_list_opened` | Focus-chain markdown/list opened by user | task_id |
-| `task.focus_chain_list_written` | Focus-chain markdown/list written/saved | task_id |
-| `task.subagent_enabled` | Subagents feature enabled | task_id |
-| `task.subagent_disabled` | Subagents feature disabled | task_id |
-| `task.subagent_started` | Subagent execution started | subagent_id, prompt_length |
-| `task.subagent_completed` | Subagent execution completed | subagent_id, duration_ms, success |
-| `task.skill_used` | Skill invocation event | skill_name, task_id |
-
-### Auto-Compact & Context
-
-| Event | Description | Key Attributes |
-|-------|-------------|----------------|
-| `task.summarize_task` | Auto-compaction/summarize triggered for context pressure | conversation_length, estimated_tokens |
-| `task.auto_condense_toggled` | Auto-condense setting toggled | enabled |
-
-### Settings & Features
-
-| Event | Description | Key Attributes |
-|-------|-------------|----------------|
-| `task.feature_toggled` | Generic feature toggle changed | feature_name, enabled |
-| `task.rule_toggled` | Cline rule toggled on/off | rule_name, enabled, is_global |
-| `task.yolo_mode_toggled` | YOLO mode toggled | enabled |
-| `task.cline_web_tools_toggled` | Cline web tools setting toggled | enabled |
-
-### API & Performance
-
-| Event | Description | Key Attributes |
-|-------|-------------|----------------|
-| `task.gemini_api_performance` | Gemini-specific API performance telemetry | duration_ms, tokens, cache_hit |
-| `task.provider_api_error` | API provider error event | provider, model, error_code, error_message |
-| `task.diff_edit_failed` | Diff/replace edit failed | file_path_hash, error_type |
-| `task.initialization` | Task initialization timing/metadata event | duration_ms, mode |
-
-### AI Output Feedback
-
-| Event | Description | Key Attributes |
-|-------|-------------|----------------|
-| `task.ai_output.accepted` | AI-generated file edit accepted | lines_added, lines_removed, file_count |
-| `task.ai_output.rejected` | AI-generated file edit rejected | lines_added, lines_removed, file_count |
-
-### Example: task.tool_used
-
-```json
-{
-  "event": "task.tool_used",
-  "timestamp": "2026-03-05T10:35:22Z",
-  "attributes": {
-    "task_id": "task_1234567890",
-    "tool_name": "write_to_file",
-    "success": true,
-    "duration_ms": 125,
-    "auto_approved": false,
-    "model": "claude-sonnet-4",
-    "provider": "anthropic"
-  }
-}
-```
-
-## UI Events
-
-Events tracking user interface interactions.
-
-| Event | Description | Key Attributes |
-|-------|-------------|----------------|
-| `ui.model_selected` | Model selected in UI | model, provider, previous_model |
-| `ui.model_favorite_toggled` | Model favorite toggled | model_id, is_favorited |
-| `ui.button_clicked` | UI button click event | button_id, context |
-| `ui.rules_menu_opened` | Rules/skills menu/modal opened | menu_type |
-
-### Example: ui.model_selected
-
-```json
-{
-  "event": "ui.model_selected",
-  "timestamp": "2026-03-05T11:20:00Z",
-  "attributes": {
-    "model": "claude-sonnet-4",
-    "provider": "anthropic",
-    "previous_model": "gpt-4o",
-    "mode": "act"
-  }
-}
-```
-
-## Hooks Events
-
-Events related to hook discovery, execution lifecycle, and context modifications.
-
-| Event | Description | Key Attributes |
-|-------|-------------|----------------|
-| `hooks.enabled` | Hooks feature enabled | user_id |
-| `hooks.disabled` | Hooks feature disabled | user_id |
-| `hooks.cancel_requested` | Hook requested cancellation | hook_name, task_id |
-| `hooks.context_modified` | Hook modified context | hook_name, modification_type |
-| `hooks.discovery_completed` | Hook discovery completed | hooks_count, global_count, workspace_count |
-| `hooks.execution` | Unified hook execution lifecycle | hook_name, status (started/completed/failed/cancelled), duration_ms |
-
-### Hook Execution Lifecycle
-
-The `hooks.execution` event tracks the complete lifecycle with a `status` attribute:
-
-- **started**: Hook execution began
-- **completed**: Hook finished successfully
-- **failed**: Hook encountered an error
-- **cancelled**: Hook was cancelled by user or system
-
-### Example: hooks.execution
-
-```json
-{
-  "event": "hooks.execution",
-  "timestamp": "2026-03-05T10:40:15Z",
-  "attributes": {
-    "hook_name": "preToolUse",
-    "status": "completed",
-    "duration_ms": 234,
-    "task_id": "task_1234567890",
-    "context_modified": false
-  }
-}
-```
-
-## Worktree Events
-
-Events related to Git worktree operations.
-
-| Event | Description | Key Attributes |
-|-------|-------------|----------------|
-| `worktree.view_opened` | Worktree view opened | user_id |
-| `worktree.created` | Worktree create event | success, branch_name, duration_ms |
-| `worktree.merge_attempted` | Worktree merge attempt event | has_conflicts, delete_option_chosen |
-
-### Example: worktree.created
-
-```json
-{
-  "event": "worktree.created",
-  "timestamp": "2026-03-05T14:22:00Z",
-  "attributes": {
-    "success": true,
-    "branch_name_hash": "abc123",
-    "duration_ms": 1250,
-    "parent_branch": "main"
-  }
-}
-```
-
-## Host Events
-
-Events related to host environment detection.
-
-| Event | Description | Key Attributes |
-|-------|-------------|----------------|
-| `host.detected` | Host environment detection event | host_type (vscode/jetbrains/cli), version |
-
-### Example: host.detected
-
-```json
-{
-  "event": "host.detected",
-  "timestamp": "2026-03-05T09:00:00Z",
-  "attributes": {
-    "host_type": "vscode",
-    "version": "1.95.0",
-    "platform": "darwin"
-  }
-}
-```
-
-## Test Events
-
-Diagnostic and connection testing events.
-
-| Event | Description | Key Attributes |
-|-------|-------------|----------------|
-| `cline.test.connection` | OTEL connection test event from "Test OTEL Connection" flow | success, exporter_type, endpoint |
-
-### Example: cline.test.connection
-
-```json
-{
-  "event": "cline.test.connection",
-  "timestamp": "2026-03-05T15:30:00Z",
-  "attributes": {
-    "success": true,
-    "exporter_type": "otlp",
-    "endpoint": "https://api.datadoghq.com:4317",
-    "protocol": "grpc"
-  }
-}
-```
-
-## Event Attribute Guidelines
-
-### Common Attributes
-
-Most events include these standard attributes:
-
-| Attribute | Type | Description |
-|-----------|------|-------------|
-| `timestamp` | ISO 8601 | Event occurrence time |
-| `user_id` | string | Anonymized user identifier (when authenticated) |
-| `session_id` | string | Current session identifier |
-| `extension_version` | string | Cline extension version |
-| `host_type` | string | vscode, jetbrains, or cli |
-
-### Privacy & Hashing
-
-Sensitive information is hashed or anonymized:
-
-- **File paths**: Hashed to preserve privacy
-- **Command content**: Hashed, not logged verbatim
-- **User identifiers**: Anonymized tokens
-- **Branch names**: Hashed in worktree events
-
-<Warning>
-File paths, command arguments, and code content are **never** included in raw form. Only hashes or anonymized identifiers are used.
-</Warning>
-
-## Task Event Deep Dive
-
-Task events are the most detailed category. Here's a typical task execution flow:
-
-```mermaid
-sequenceDiagram
-    participant User
-    participant Cline
-    participant OTel
-
-    User->>Cline: Start Task
-    Cline->>OTel: task.created
-    
-    User->>Cline: Submit Message
-    Cline->>OTel: task.conversation_turn (user)
-    
-    Cline->>Cline: Process with AI
-    Cline->>OTel: task.tokens
-    Cline->>OTel: task.conversation_turn (assistant)
-    
-    Cline->>Cline: Use Tool
-    Cline->>OTel: task.tool_used
-    
-    User->>Cline: Provide Feedback
-    Cline->>OTel: task.option_selected
-    
-    User->>Cline: Complete Task
-    Cline->>OTel: task.completed
-```
-
-### Task Token Tracking
-
-Token events provide detailed cost and usage information:
-
-```json
-{
-  "event": "task.tokens",
-  "timestamp": "2026-03-05T10:35:30Z",
-  "attributes": {
-    "task_id": "task_1234567890",
-    "tokens_in": 2500,
-    "tokens_out": 850,
-    "cached_tokens": 1200,
-    "cost": 0.0043,
-    "model": "claude-sonnet-4",
-    "provider": "anthropic"
-  }
-}
-```
-
-## Using Events for Analytics
-
-<Warning>
-**SQL syntax is illustrative only.** Attribute access varies by observability platform — for example, `JSON_EXTRACT(attributes, '$.model')` in BigQuery, `attributes['model']` in ClickHouse, or `@attributes.model` in Datadog. Adapt all queries below to your platform's query language before use.
-</Warning>
-
-### Query Patterns
-
-**Most used tools:**
-```sql
-SELECT attributes.tool_name, COUNT(*) as count
-FROM otel_logs
-WHERE event = 'task.tool_used'
-  AND attributes.success = true
-GROUP BY attributes.tool_name
-ORDER BY count DESC
-LIMIT 10
-```
-
-**Average task duration by model:**
-```sql
-SELECT 
-  attributes.model,
-  AVG(attributes.duration_ms) as avg_duration_ms,
-  COUNT(*) as task_count
-FROM otel_logs
-WHERE event = 'task.completed'
-GROUP BY attributes.model
-```
-
-**Token usage by provider:**
-```sql
-SELECT 
-  attributes.provider,
-  SUM(attributes.tokens_in) as total_tokens_in,
-  SUM(attributes.tokens_out) as total_tokens_out,
-  SUM(attributes.cost) as total_cost
-FROM otel_logs
-WHERE event = 'task.tokens'
-  AND timestamp >= NOW() - INTERVAL '30 days'
-GROUP BY attributes.provider
-```
-
-**Tool approval rates:**
-```sql
-SELECT 
-  attributes.tool_name,
-  SUM(CASE WHEN attributes.auto_approved THEN 1 ELSE 0 END)::float / COUNT(*) as auto_approval_rate,
-  COUNT(*) as total_uses
-FROM otel_logs
-WHERE event = 'task.tool_used'
-GROUP BY attributes.tool_name
-ORDER BY total_uses DESC
-```
-
-## Integration Examples
-
-<Note>
-Query syntax below is illustrative. Attribute access varies by platform — for example, `JSON_EXTRACT(attributes, '$.model')` in BigQuery, `attributes['model']` in ClickHouse, or dot notation in Datadog. Adapt to your platform's query language.
-</Note>
-
-### Datadog Dashboard
-
-Create custom Datadog dashboards using these events:
-
-```json
-{
-  "widgets": [
-    {
-      "definition": {
-        "type": "timeseries",
-        "requests": [
-          {
-            "q": "sum:cline.task.completed{*}.as_count()",
-            "display_type": "bars"
-          }
-        ],
-        "title": "Tasks Completed Over Time"
-      }
-    },
-    {
-      "definition": {
-        "type": "query_value",
-        "requests": [
-          {
-            "q": "sum:cline.task.tokens{*}",
-            "aggregator": "sum"
-          }
-        ],
-        "title": "Total Tokens Used"
-      }
-    }
-  ]
-}
-```
-
-### Grafana Queries
-
-Example Loki query for tool usage:
-
-```logql
-{event="task.tool_used"} 
-| json
-| line_format "{{.attributes_tool_name}}: {{.attributes_success}}"
-```
-
-### New Relic NRQL
-
-Query task completion rates:
-
-```sql
-SELECT count(*) 
-FROM Log 
-WHERE event = 'task.completed' 
-FACET attributes.model 
-SINCE 1 day ago
-```
-
-## Event Schema Reference
-
-All events follow this structure:
-
-```typescript
-interface OtelLogEvent {
-  event: string              // Event name (e.g., "task.created")
-  timestamp: string           // ISO 8601 timestamp
-  attributes: {
-    // Event-specific attributes
-    [key: string]: string | number | boolean
-  }
-  resource: {
-    service_name: "cline"
-    service_version: string   // Extension version
-    host_type: string         // vscode | jetbrains | cli
-  }
-}
-```
-
-## Best Practices
-
-<CardGroup cols={2}>
-  <Card title="Filter Noise" icon="filter">
-    Focus on events relevant to your use case. Not all events need dashboards.
-  </Card>
-  
-  <Card title="Set Alerts" icon="bell">
-    Alert on error events and usage anomalies for proactive monitoring.
-  </Card>
-  
-  <Card title="Aggregate Metrics" icon="chart-bar">
-    Roll up events into metrics for long-term trend analysis.
-  </Card>
-  
-  <Card title="Respect Privacy" icon="shield">
-    Remember events are already anonymized. Don't attempt to de-anonymize.
-  </Card>
-</CardGroup>
-
-## Troubleshooting
-
-### Events Not Appearing
-
-If events aren't showing up in your observability platform:
-
-1. **Verify OTel is enabled** in remote configuration or environment variables
-2. **Check endpoint configuration** - ensure URL and protocol are correct
-3. **Validate credentials** - test with the "Test OTEL Connection" button
-4. **Check exporter settings** - ensure logs exporter includes `otlp`
-5. **Review platform-specific requirements** - some platforms need specific headers
-
-### Event Volume Concerns
-
-If you're seeing excessive event volume:
-
-1. **Sample events** - Configure sampling in your OTel collector
-2. **Filter events** - Use your platform's filtering to drop noisy events
-3. **Aggregate on collection** - Pre-aggregate metrics before export
-4. **Adjust export intervals** - Increase `openTelemetryMetricExportInterval` and batch settings
-
-## See Also
-
-<CardGroup cols={3}>
-  <Card title="OpenTelemetry Setup" icon="chart-line" href="/enterprise-solutions/monitoring/opentelemetry">
-    Configure OTel integration
-  </Card>
-  
-  <Card title="Prompt Storage" icon="database" href="/enterprise-solutions/monitoring/prompt-storage">
-    Backup conversation history
-  </Card>
-  
-  <Card title="Telemetry" icon="chart-simple" href="/enterprise-solutions/monitoring/telemetry">
-    Basic telemetry overview
-  </Card>
-</CardGroup>

docs/enterprise-solutions/monitoring/opentelemetry.mdx

@@ -194,11 +194,7 @@ Current OpenTelemetry support in Cline:
 
 ## Next Steps
 
-<CardGroup cols={3}>
-  <Card title="Event Reference" icon="list" href="/enterprise-solutions/monitoring/opentelemetry-events">
-    Complete catalog of all emitted OTel events
-  </Card>
-  
+<CardGroup cols={2}>
   <Card title="Cline Telemetry" icon="chart-simple" href="/enterprise-solutions/monitoring/telemetry">
     Configure simple built-in telemetry
   </Card>

docs/enterprise-solutions/monitoring/opentelemetry_override.mdx

@@ -1,155 +0,0 @@
----
-title: "OpenTelemetry Environment Variables"
-sidebarTitle: "OpenTelemetry Override"
-description: "Configure OpenTelemetry using environment variables for advanced scenarios"
----
-
-<Note>
-This is an **advanced configuration method**. Most users should use [Remote Configuration](/enterprise-solutions/monitoring/opentelemetry) via the dashboard instead.
-</Note>
-
-Environment variables provide an alternative way to configure OpenTelemetry, useful for self-hosted deployments, local development, CI/CD pipelines, or when you need to override organization settings.
-
-## When to Use
-
-- **Self-hosted deployments** without dashboard access
-- **Local development and testing** with your own collectors
-- **CI/CD pipelines** that need observability
-- **Override organization settings** with user-specific configuration
-
-<Warning>
-Environment variable configuration bypasses user telemetry settings and will export data regardless of individual preferences.
-</Warning>
-
-## Environment Variables
-
-### Core Configuration
-
-| Variable | Description | Values |
-|----------|-------------|--------|
-| `CLINE_OTEL_TELEMETRY_ENABLED` | Enable OpenTelemetry export | `"true"` or `"false"` |
-| `CLINE_OTEL_METRICS_EXPORTER` | Metrics exporters (comma-separated) | `"console"`, `"otlp"` |
-| `CLINE_OTEL_LOGS_EXPORTER` | Logs exporters (comma-separated) | `"console"`, `"otlp"` |
-
-### OTLP Configuration
-
-| Variable | Description | Values |
-|----------|-------------|--------|
-| `CLINE_OTEL_EXPORTER_OTLP_PROTOCOL` | OTLP protocol | `"grpc"`, `"http/json"`, or `"http/protobuf"` |
-| `CLINE_OTEL_EXPORTER_OTLP_ENDPOINT` | OTLP collector endpoint (applies to both metrics and logs) | URL with optional port |
-| `CLINE_OTEL_EXPORTER_OTLP_HEADERS` | Authentication headers (comma-separated `key=value` pairs) | `"key=value,key2=value2"` |
-| `CLINE_OTEL_EXPORTER_OTLP_INSECURE` | Disable TLS for gRPC (local development only) | `"true"` |
-
-### Advanced OTLP Configuration
-
-For separate metrics and logs endpoints:
-
-| Variable | Description |
-|----------|-------------|
-| `CLINE_OTEL_EXPORTER_OTLP_METRICS_PROTOCOL` | Metrics-specific protocol override |
-| `CLINE_OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` | Metrics-specific endpoint |
-| `CLINE_OTEL_EXPORTER_OTLP_LOGS_PROTOCOL` | Logs-specific protocol override |
-| `CLINE_OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` | Logs-specific endpoint |
-
-### Export Tuning
-
-| Variable | Description | Default |
-|----------|-------------|---------|
-| `CLINE_OTEL_METRIC_EXPORT_INTERVAL` | Milliseconds between metric exports | 60000 |
-| `CLINE_OTEL_LOG_BATCH_SIZE` | Maximum batch size for log records | 512 |
-| `CLINE_OTEL_LOG_BATCH_TIMEOUT` | Maximum time before exporting logs (ms) | 5000 |
-| `CLINE_OTEL_LOG_MAX_QUEUE_SIZE` | Maximum queue size for log records | 2048 |
-
-## Quick Start Examples
-
-### Datadog with gRPC
-
-```bash
-export CLINE_OTEL_TELEMETRY_ENABLED=true
-export CLINE_OTEL_METRICS_EXPORTER=otlp
-export CLINE_OTEL_LOGS_EXPORTER=otlp
-export CLINE_OTEL_EXPORTER_OTLP_PROTOCOL=grpc
-export CLINE_OTEL_EXPORTER_OTLP_ENDPOINT=https://api.datadoghq.com:4317
-export CLINE_OTEL_EXPORTER_OTLP_HEADERS="dd-api-key=YOUR_API_KEY"
-
-code .
-```
-
-<Note>
-The endpoint shown above is for Datadog's **US1 region**. If you're in a different region (EU, US3, US5, AP1, etc.), replace `api.datadoghq.com` with your region-specific hostname (e.g., `api.datadoghq.eu` for EU). See [Datadog's OTLP documentation](https://docs.datadoghq.com/opentelemetry/) for your region's endpoint.
-</Note>
-
-### New Relic with HTTP
-
-```bash
-export CLINE_OTEL_TELEMETRY_ENABLED=true
-export CLINE_OTEL_METRICS_EXPORTER=otlp
-export CLINE_OTEL_LOGS_EXPORTER=otlp
-export CLINE_OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
-export CLINE_OTEL_EXPORTER_OTLP_ENDPOINT=https://otlp.nr-data.net:4318
-export CLINE_OTEL_EXPORTER_OTLP_HEADERS="api-key=YOUR_LICENSE_KEY"
-
-code .
-```
-
-### Local Development (Insecure)
-
-```bash
-export CLINE_OTEL_TELEMETRY_ENABLED=true
-export CLINE_OTEL_METRICS_EXPORTER=otlp
-export CLINE_OTEL_LOGS_EXPORTER=otlp
-export CLINE_OTEL_EXPORTER_OTLP_PROTOCOL=grpc
-export CLINE_OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
-export CLINE_OTEL_EXPORTER_OTLP_INSECURE=true
-
-code .
-```
-
-### Console Output (Testing)
-
-```bash
-export CLINE_OTEL_TELEMETRY_ENABLED=true
-export CLINE_OTEL_METRICS_EXPORTER=console
-export CLINE_OTEL_LOGS_EXPORTER=console
-
-code .
-```
-
-## Debugging
-
-Enable detailed OpenTelemetry diagnostic logging:
-
-```bash
-export TEL_DEBUG_DIAGNOSTICS=true
-code .
-```
-
-This outputs:
-- Configuration being used
-- Exporters being created
-- Connection attempts
-- Export successes/failures
-
-Check the VS Code Developer Tools Console (Help > Toggle Developer Tools) for diagnostic output.
-
-## Configuration Priority
-
-When multiple configuration methods are present, Cline uses this priority order:
-
-1. **Environment variables** (highest priority) - This method
-2. **Remote Configuration** - Dashboard settings
-3. **Default settings** - Built-in defaults
-
-Environment variable configuration will override dashboard settings.
-
-## See Also
-
-<CardGroup cols={2}>
-  <Card title="Dashboard Configuration" icon="globe" href="/enterprise-solutions/monitoring/opentelemetry">
-    Configure OpenTelemetry via the web dashboard
-  </Card>
-  
-  <Card title="Remote Configuration" icon="server" href="/enterprise-solutions/configuration/remote-configuration/overview">
-    Learn about Remote Configuration system
-  </Card>
-</CardGroup>

docs/enterprise-solutions/monitoring/overview.mdx

@@ -9,14 +9,6 @@ Cline includes optional monitoring capabilities for organizations that want to t
 ## Monitoring Options
 
 <CardGroup cols={2}> 
-  <Card title="Cline Telemetry" icon="chart-simple" href="/enterprise-solutions/monitoring/telemetry">
-    Built-in anonymous usage tracking that helps improve Cline (opt-in)
-  </Card>
-
-  <Card title="Prompt Storage" icon="database" href="/enterprise-solutions/monitoring/prompt-storage">
-    Backup conversation history to S3/R2 for compliance and analysis
-  </Card>
-
   <Card title="OpenTelemetry" icon="chart-line" href="/enterprise-solutions/monitoring/opentelemetry">
     Export metrics and logs to your own observability backends
   </Card>
@@ -26,6 +18,12 @@ Cline includes optional monitoring capabilities for organizations that want to t
   </Card>
 </CardGroup>
 
+<CardGroup cols={1}>
+  <Card title="Cline Telemetry" icon="chart-simple" href="/enterprise-solutions/monitoring/telemetry">
+    Built-in anonymous usage tracking that helps improve Cline (opt-in)
+  </Card>  
+</CardGroup>
+
 ## Cline Telemetry
 
 Cline includes opt-in telemetry for anonymous usage tracking:

docs/enterprise-solutions/monitoring/prompt-storage.mdx

@@ -1,666 +0,0 @@
----
-title: "Prompt Storage"
-description: "Backup conversation history to S3 or Cloudflare R2 for compliance, audit, and analysis"
----
-
-Prompt Storage allows enterprises to automatically back up Cline conversation history to cloud storage (AWS S3 or Cloudflare R2). This provides a centralized repository for compliance, audit trails, and usage analysis while maintaining local storage as the primary source of truth.
-
-## Overview
-
-Every Cline task conversation is stored locally in `~/.cline/data/tasks/<taskId>/api_conversation_history.json`. When prompt storage is enabled, a background sync worker automatically uploads these conversation files to your configured S3 or R2 bucket.
-
-<CardGroup cols={2}>
-  <Card title="Compliance Ready" icon="shield-check">
-    Maintain conversation records for regulatory requirements and internal policies.
-  </Card>
-  
-  <Card title="Audit Trail" icon="scroll">
-    Track AI interactions across your organization with timestamped conversation logs.
-  </Card>
-  
-  <Card title="Usage Analysis" icon="chart-line">
-    Analyze conversation patterns, token usage, and model performance at scale.
-  </Card>
-  
-  <Card title="Disaster Recovery" icon="cloud-arrow-up">
-    Backup conversation history independent of local storage for business continuity.
-  </Card>
-</CardGroup>
-
-## How It Works
-
-```mermaid
-graph LR
-    A[User] --> B[Cline Extension]
-    B --> C[Local Storage<br/>~/.cline/data/tasks/]
-    C --> D[Background Sync Worker]
-    D --> E[S3/R2 Bucket]
-    E --> F[Compliance/Analytics]
-```
-
-1. **Local Storage First**: All conversations are written to local disk immediately
-2. **Background Sync**: A worker process queues conversation files for upload
-3. **Reliable Upload**: Automatic retry logic with configurable batch sizes
-4. **Cloud Backup**: Files are stored in your S3/R2 bucket with the same path structure
-
-## Storage Architecture
-
-### What Gets Stored
-
-Prompt storage uploads the following files from each task:
-
-| File | Content | Purpose |
-|------|---------|---------|
-| `api_conversation_history.json` | Full conversation in Anthropic MessageParam format | Core conversation data for analysis |
-| Task metadata | Task ID, timestamps, model info | Correlation and indexing |
-
-### What's NOT Stored
-
-Prompt storage **does not** include:
-
-- ❌ Workspace files not accessed by Cline
-- ❌ API keys or secrets  
-- ❌ User credentials or authentication tokens
-
-<Warning>
-Conversation history includes **all tool inputs and outputs**. This means code written via `write_to_file`, file contents read via `read_file`, and command outputs are included in the uploaded data. Review your compliance and data classification requirements before enabling.
-</Warning>
-
-### Storage Path Pattern
-
-Files are uploaded to your bucket following this structure:
-
-```
-s3://your-bucket/tasks/{taskId}/api_conversation_history.json
-```
-
-This mirrors the local storage structure, making it easy to correlate local and cloud data.
-
-## Configuration
-
-Prompt storage is configured through Remote Configuration in the `enterpriseTelemetry.promptUploading` section.
-
-### Schema
-
-```json
-{
-  "enterpriseTelemetry": {
-    "promptUploading": {
-      "enabled": true,
-      "type": "s3_access_keys",
-      "s3AccessSettings": {
-        "bucket": "your-cline-prompts",
-        "accessKeyId": "AKIAIOSFODNN7EXAMPLE",
-        "secretAccessKey": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
-        "region": "us-east-1",
-        "intervalMs": 30000,
-        "maxRetries": 5,
-        "batchSize": 10,
-        "maxQueueSize": 1000,
-        "maxFailedAgeMs": 604800000,
-        "backfillEnabled": false
-      }
-    }
-  }
-}
-```
-
-### Configuration Fields
-
-#### Core Settings
-
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| `enabled` | boolean | Yes | Enable/disable prompt storage |
-| `type` | string | Yes | Storage type: `"s3_access_keys"` or `"r2_access_keys"` |
-
-#### Access Settings (S3/R2)
-
-| Field | Type | Required | Description | Default |
-|-------|------|----------|-------------|---------|
-| `bucket` | string | Yes | S3/R2 bucket name | - |
-| `accessKeyId` | string | Yes | AWS/Cloudflare access key ID | - |
-| `secretAccessKey` | string | Yes | AWS/Cloudflare secret access key | - |
-| `region` | string | S3 only | AWS region (e.g., `us-east-1`) | - |
-| `endpoint` | string | R2 only | Cloudflare R2 endpoint URL | - |
-| `accountId` | string | R2 only | Cloudflare account ID | - |
-
-#### Sync Worker Settings
-
-| Field | Type | Description | Default |
-|-------|------|-------------|---------|
-| `intervalMs` | number | Milliseconds between sync attempts | 30000 (30s) |
-| `maxRetries` | number | Maximum retries before giving up | 5 |
-| `batchSize` | number | Items to process per interval | 10 |
-| `maxQueueSize` | number | Maximum queue size before eviction | 1000 |
-| `maxFailedAgeMs` | number | Time before discarding failed items | 604800000 (7 days) |
-| `backfillEnabled` | boolean | Sync existing tasks on startup | false |
-
-## Setup Guides
-
-<Tabs>
-  <Tab title="AWS S3">
-    ### AWS S3 Configuration
-
-    <Steps>
-      <Step title="Create S3 Bucket">
-        Create a dedicated S3 bucket for Cline conversation storage:
-        
-        ```bash
-        aws s3 mb s3://your-cline-prompts --region us-east-1
-        ```
-        
-        Enable versioning and encryption:
-        
-        ```bash
-        aws s3api put-bucket-versioning \
-          --bucket your-cline-prompts \
-          --versioning-configuration Status=Enabled
-        
-        aws s3api put-bucket-encryption \
-          --bucket your-cline-prompts \
-          --server-side-encryption-configuration '{
-            "Rules": [{
-              "ApplyServerSideEncryptionByDefault": {
-                "SSEAlgorithm": "AES256"
-              }
-            }]
-          }'
-        ```
-      </Step>
-
-      <Step title="Create IAM Policy">
-        Create an IAM policy with minimal required permissions:
-        
-        ```json
-        {
-          "Version": "2012-10-17",
-          "Statement": [
-            {
-              "Effect": "Allow",
-              "Action": [
-                "s3:PutObject",
-                "s3:PutObjectAcl",
-                "s3:GetObject",
-                "s3:DeleteObject"
-              ],
-              "Resource": "arn:aws:s3:::your-cline-prompts/*"
-            },
-            {
-              "Effect": "Allow",
-              "Action": [
-                "s3:ListBucket"
-              ],
-              "Resource": "arn:aws:s3:::your-cline-prompts"
-            }
-          ]
-        }
-        ```
-        
-        Save this as `cline-prompt-storage-policy.json` and create the policy:
-        
-        ```bash
-        aws iam create-policy \
-          --policy-name ClinePromptStorage \
-          --policy-document file://cline-prompt-storage-policy.json
-        ```
-      </Step>
-
-      <Step title="Create IAM User">
-        Create a dedicated IAM user and attach the policy:
-        
-        ```bash
-        aws iam create-user --user-name cline-prompt-uploader
-        
-        aws iam attach-user-policy \
-          --user-name cline-prompt-uploader \
-          --policy-arn arn:aws:iam::YOUR_ACCOUNT_ID:policy/ClinePromptStorage
-        
-        aws iam create-access-key --user-name cline-prompt-uploader
-        ```
-        
-        Save the `AccessKeyId` and `SecretAccessKey` from the output.
-      </Step>
-
-      <Step title="Configure in Cline Dashboard">
-        In the Cline admin console at [app.cline.bot](https://app.cline.bot):
-        
-        1. Navigate to **Settings** → **Enterprise Telemetry**
-        2. Enable **Prompt Uploading**
-        3. Select **S3** as the storage type
-        4. Enter your bucket name, access key ID, secret key, and region
-        5. Configure sync worker settings (or use defaults)
-        6. Save configuration
-      </Step>
-
-      <Step title="Test Connection">
-        Use the "Test Connection" button in the admin console to verify:
-        - Bucket access
-        - Write permissions
-        - Credential validity
-        
-        A test file will be uploaded and deleted from your bucket.
-      </Step>
-    </Steps>
-
-    ### Optional: Lifecycle Policies
-
-    Configure retention policies for cost management:
-
-    ```json
-    {
-      "Rules": [
-        {
-          "Id": "ArchiveOldPrompts",
-          "Status": "Enabled",
-          "Transitions": [
-            {
-              "Days": 90,
-              "StorageClass": "GLACIER"
-            }
-          ]
-        },
-        {
-          "Id": "DeleteOldPrompts",
-          "Status": "Enabled",
-          "Expiration": {
-            "Days": 2555
-          }
-        }
-      ]
-    }
-    ```
-  </Tab>
-
-  <Tab title="Cloudflare R2">
-    ### Cloudflare R2 Configuration
-
-    <Steps>
-      <Step title="Create R2 Bucket">
-        1. Log in to the [Cloudflare Dashboard](https://dash.cloudflare.com)
-        2. Navigate to **R2** in the sidebar
-        3. Click **Create bucket**
-        4. Name your bucket (e.g., `cline-prompts`)
-        5. Select a location close to your users
-        6. Click **Create bucket**
-      </Step>
-
-      <Step title="Generate API Token">
-        1. In the R2 dashboard, click **Manage R2 API Tokens**
-        2. Click **Create API token**
-        3. Configure permissions:
-           - **Token name**: Cline Prompt Storage
-           - **Permissions**: Object Read & Write
-           - **Bucket**: Select your bucket or use All buckets
-        4. Click **Create API Token**
-        5. Save the **Access Key ID** and **Secret Access Key**
-        6. Note your **Account ID** (shown in the R2 overview)
-      </Step>
-
-      <Step title="Get R2 Endpoint">
-        Your R2 endpoint follows this format:
-        
-        ```
-        https://<ACCOUNT_ID>.r2.cloudflarestorage.com
-        ```
-        
-        Find your account ID in the Cloudflare dashboard under R2 overview.
-      </Step>
-
-      <Step title="Configure in Cline Dashboard">
-        In the Cline admin console at [app.cline.bot](https://app.cline.bot):
-        
-        1. Navigate to **Settings** → **Enterprise Telemetry**
-        2. Enable **Prompt Uploading**
-        3. Select **R2** as the storage type
-        4. Enter:
-           - Bucket name
-           - Access key ID
-           - Secret access key
-           - Account ID
-           - Endpoint URL
-        5. Configure sync worker settings (or use defaults)
-        6. Save configuration
-      </Step>
-
-      <Step title="Test Connection">
-        Use the "Test Connection" button to verify:
-        - Bucket access with provided credentials
-        - Write permissions
-        - Endpoint connectivity
-      </Step>
-    </Steps>
-
-    ### Cost Advantages
-
-    R2 offers significant cost advantages over S3:
-    - **No egress fees**: Download data at no cost
-    - **Lower storage costs**: ~$0.015/GB vs S3's ~$0.023/GB
-    - **Global edge access**: Fast access from anywhere
-  </Tab>
-</Tabs>
-
-## Sync Worker Behavior
-
-The background sync worker manages the upload queue with these characteristics:
-
-### Queue Management
-
-- **FIFO ordering**: Files are uploaded in the order they were created
-- **Automatic batching**: Processes up to `batchSize` items per interval
-- **Queue size limits**: Evicts oldest items when `maxQueueSize` is exceeded
-- **Retry logic**: Failed uploads are retried up to `maxRetries` times
-
-### Failure Handling
-
-When an upload fails:
-
-1. **Immediate retry**: Item stays in queue for next sync interval
-2. **Exponential backoff**: Retry attempts are spaced out
-3. **Maximum retries**: After `maxRetries` attempts, item is marked as permanently failed
-4. **Age-based cleanup**: Failed items older than `maxFailedAgeMs` are discarded
-5. **No data loss**: Local files remain intact regardless of sync status
-
-### Backfill Mode
-
-When `backfillEnabled` is set to `true`:
-
-- On first startup, scans all existing tasks in `~/.cline/data/tasks/`
-- Queues conversation files that haven't been uploaded
-- Useful for enabling prompt storage on an existing Cline deployment
-- Can generate significant upload volume — monitor queue size
-
-<Warning>
-Enable backfill carefully on large deployments. Consider starting with `backfillEnabled: false` and monitoring the steady-state queue before enabling backfill.
-</Warning>
-
-## Monitoring & Observability
-
-### Integration with OpenTelemetry
-
-While prompt storage operates independently, it integrates with Cline's observability system:
-
-- **Task lifecycle events**: `task.created`, `task.completed` track when conversations are generated
-- **Conversation events**: `task.conversation_turn`, `task.tokens` provide usage metrics
-- **Local monitoring**: Sync worker status is logged but not yet exported as OTel events
-
-See [OpenTelemetry](/enterprise-solutions/monitoring/opentelemetry) for configuring metrics export.
-
-### CloudWatch Monitoring (S3)
-
-Monitor S3 upload activity with CloudWatch:
-
-```bash
-# View PutObject requests (uploads)
-aws cloudwatch get-metric-statistics \
-  --namespace AWS/S3 \
-  --metric-name NumberOfObjects \
-  --dimensions Name=BucketName,Value=your-cline-prompts \
-  --start-time 2026-03-01T00:00:00Z \
-  --end-time 2026-03-08T00:00:00Z \
-  --period 3600 \
-  --statistics Sum
-```
-
-### R2 Analytics
-
-Cloudflare R2 provides built-in analytics in the dashboard:
-
-- Request counts and rates
-- Storage usage over time
-- Bandwidth utilization
-- Error rates
-
-## Security & Compliance
-
-### Encryption
-
-**At Rest:**
-- S3: Enable server-side encryption (SSE-S3 or SSE-KMS)
-- R2: Encryption enabled by default
-
-**In Transit:**
-- All uploads use HTTPS/TLS
-- Credentials are never logged or exposed
-
-### Access Control
-
-**Recommended IAM policies:**
-
-- Use dedicated IAM users/roles
-- Limit permissions to write-only if read access isn't needed
-- Enable MFA for credential generation
-- Rotate access keys regularly
-
-**Bucket policies:**
-
-```json
-{
-  "Version": "2012-10-17",
-  "Statement": [
-    {
-      "Effect": "Deny",
-      "Principal": "*",
-      "Action": "s3:*",
-      "Resource": [
-        "arn:aws:s3:::your-cline-prompts/*",
-        "arn:aws:s3:::your-cline-prompts"
-      ],
-      "Condition": {
-        "Bool": {
-          "aws:SecureTransport": "false"
-        }
-      }
-    }
-  ]
-}
-```
-
-### Audit Logging
-
-**S3 Server Access Logging:**
-
-```bash
-aws s3api put-bucket-logging \
-  --bucket your-cline-prompts \
-  --bucket-logging-status '{
-    "LoggingEnabled": {
-      "TargetBucket": "your-log-bucket",
-      "TargetPrefix": "cline-prompts-access/"
-    }
-  }'
-```
-
-**CloudTrail for API Calls:**
-
-Enable CloudTrail to track all S3 API operations on your bucket.
-
-### Data Retention
-
-Implement retention policies based on your compliance requirements:
-
-- **GDPR**: Consider right to erasure
-- **SOC 2**: Maintain audit trails for required period
-- **HIPAA**: Ensure appropriate retention and disposal
-
-## Troubleshooting
-
-### Common Issues
-
-<AccordionGroup>
-  <Accordion title="Queue size growing continuously">
-    **Symptoms**: `maxQueueSize` limit reached, oldest items being evicted
-    
-    **Causes**:
-    - Upload rate slower than conversation creation rate
-    - Network connectivity issues
-    - Insufficient batch size or interval
-    
-    **Solutions**:
-    1. Increase `batchSize` to process more items per interval
-    2. Decrease `intervalMs` to sync more frequently
-    3. Check network connectivity and credentials
-    4. Temporarily increase `maxQueueSize` while investigating
-  </Accordion>
-
-  <Accordion title="Uploads failing with 403 Forbidden">
-    **Symptoms**: Repeated upload failures, items reaching `maxRetries`
-    
-    **Causes**:
-    - Invalid or expired credentials
-    - Insufficient IAM permissions
-    - Bucket policy denying access
-    
-    **Solutions**:
-    1. Verify credentials are correct in remote config
-    2. Check IAM policy includes `s3:PutObject` permission
-    3. Review bucket policies for deny rules
-    4. Test with AWS CLI: `aws s3 cp test.txt s3://your-bucket/`
-  </Accordion>
-
-  <Accordion title="R2 endpoint connection timeout">
-    **Symptoms**: Connection timeouts, failed uploads
-    
-    **Causes**:
-    - Incorrect endpoint URL
-    - Firewall blocking Cloudflare IPs
-    - Invalid account ID
-    
-    **Solutions**:
-    1. Verify endpoint format: `https://<ACCOUNT_ID>.r2.cloudflarestorage.com`
-    2. Check firewall rules allow HTTPS to Cloudflare IPs
-    3. Confirm account ID in Cloudflare dashboard
-    4. Test with curl: `curl -I https://<ACCOUNT_ID>.r2.cloudflarestorage.com`
-  </Accordion>
-
-  <Accordion title="Backfill overwhelming upload queue">
-    **Symptoms**: Queue at max size immediately after enabling backfill
-    
-    **Causes**:
-    - Large number of existing tasks
-    - Backfill queuing faster than upload processing
-    
-    **Solutions**:
-    1. Disable backfill temporarily: `"backfillEnabled": false`
-    2. Let steady-state queue drain first
-    3. Increase `batchSize` and decrease `intervalMs`
-    4. Consider `maxQueueSize` increase during backfill period
-    5. Re-enable backfill once queue is stable
-  </Accordion>
-</AccordionGroup>
-
-### Debug Logging
-
-Enable debug logging to diagnose sync issues:
-
-1. Check extension developer console (Help → Toggle Developer Tools)
-2. Look for `[ClineBlobStorage]` and `[SyncWorker]` log entries
-3. Failed uploads log error messages with details
-
-### Testing Configuration
-
-Use the built-in test connection feature:
-
-```typescript
-// Programmatic test (for custom integrations)
-import { testPromptUploading } from '@/core/controller/state/testPromptUploading'
-
-await testPromptUploading(controller)
-// Returns: { success: boolean, message: string }
-```
-
-## Data Format Reference
-
-### Conversation File Schema
-
-Uploaded `api_conversation_history.json` files contain an array of messages:
-
-```json
-[
-  {
-    "role": "user",
-    "content": [
-      {
-        "type": "text",
-        "text": "Create a React component for a todo list"
-      }
-    ]
-  },
-  {
-    "role": "assistant",
-    "content": [
-      {
-        "type": "text",
-        "text": "I'll create a todo list component..."
-      },
-      {
-        "type": "tool_use",
-        "id": "toolu_123",
-        "name": "write_to_file",
-        "input": {
-          "path": "TodoList.tsx",
-          "content": "..."
-        }
-      }
-    ]
-  }
-]
-```
-
-This follows the [Anthropic Messages API format](https://docs.anthropic.com/claude/reference/messages_post).
-
-### Metadata Schema
-
-Task metadata includes:
-
-```json
-{
-  "taskId": "1234567890",
-  "createdAt": "2026-03-05T10:30:00Z",
-  "lastModified": "2026-03-05T11:45:00Z",
-  "modelInfo": {
-    "id": "claude-sonnet-4",
-    "provider": "anthropic"
-  },
-  "tokensUsed": {
-    "input": 1250,
-    "output": 3400
-  }
-}
-```
-
-## Best Practices
-
-<CardGroup cols={2}>
-  <Card title="Start Small" icon="seedling">
-    Test with a single team or project before rolling out organization-wide.
-  </Card>
-  
-  <Card title="Monitor Costs" icon="dollar-sign">
-    Set up billing alerts and review storage usage monthly.
-  </Card>
-  
-  <Card title="Secure Credentials" icon="lock">
-    Use dedicated IAM users with minimal permissions and rotate keys regularly.
-  </Card>
-  
-  <Card title="Plan Retention" icon="calendar">
-    Define and implement data retention policies based on compliance needs.
-  </Card>
-</CardGroup>
-
-## See Also
-
-<CardGroup cols={3}>
-  <Card title="OpenTelemetry" icon="chart-line" href="/enterprise-solutions/monitoring/opentelemetry">
-    Configure metrics and logs export for comprehensive observability
-  </Card>
-  
-  <Card title="Telemetry" icon="chart-simple" href="/enterprise-solutions/monitoring/telemetry">
-    Learn about Cline's built-in anonymous usage tracking
-  </Card>
-  
-  <Card title="Remote Configuration" icon="gear" href="/enterprise-solutions/configuration/remote-configuration/overview">
-    Understand the remote configuration system
-  </Card>
-</CardGroup>

docs/enterprise-solutions/monitoring/telemetry.mdx

@@ -10,7 +10,7 @@ Cline includes telemetry to help understand usage patterns and improve the produ
 
 Telemetry captures anonymous usage events such as:
 
-- Features used (which tools and commands)
+- Features used (which tools, commands, workflows)
 - Task completion rates
 - Error occurrences
 - Performance metrics
@@ -39,7 +39,7 @@ When telemetry is enabled, Cline captures:
   <Accordion title="Feature Usage" icon="cursor-click">
     - Tools executed (e.g., read_file, execute_command)
     - Slash commands used
-    - Skills triggered
+    - Workflows triggered
     - Settings changed
   </Accordion>
   
@@ -83,22 +83,11 @@ Administrators can set default telemetry state through remote configuration:
 Even with enterprise configuration, individual users can still disable Cline Telemetry in their local settings.
 </Note>
 
-## Enterprise Monitoring Features
+## Advanced Monitoring
 
-For organizations with additional compliance or monitoring requirements, Cline provides:
+For organizations needing detailed monitoring, Cline supports optional OpenTelemetry integration to export telemetry data to your own observability systems.
 
-### Prompt Storage
-Automatically backup conversation history to AWS S3 or Cloudflare R2 for:
-- Compliance and audit trails
-- Usage analysis and reporting
-- Disaster recovery
-
-See [Prompt Storage](/enterprise-solutions/monitoring/prompt-storage) for configuration details.
-
-### OpenTelemetry Integration
-Export detailed metrics and logs to your own observability platforms like Datadog, New Relic, or Grafana Cloud.
-
-See [OpenTelemetry](/enterprise-solutions/monitoring/opentelemetry) for setup instructions.
+See [Enterprise Monitoring](/enterprise-solutions/monitoring/overview) for details on available monitoring options.
 
 ## Privacy
 
@@ -138,7 +127,7 @@ Anonymous usage data helps:
     Enterprise monitoring and observability
   </Card>
   
-  <Card title="Event Details" icon="shield" href="/enterprise-solutions/monitoring/opentelemetry-events">
-    See what data is collected
+  <Card title="Privacy" icon="shield" href="/more-info/telemetry">
+    Full telemetry documentation
   </Card>
 </CardGroup>

docs/enterprise-solutions/onboarding.mdx

@@ -10,7 +10,7 @@ Cline Enterprise integrates with your existing identity provider (IdP) via WorkO
 
 ## Prerequisites
 
-- [Cline Enterprise License](https://cline.bot/contact-sales)
+- [Cline Enterprise License](https://cline.bot/enterprise)
 - Access to your identity provider (IdP) configuration (e.g., Okta, Azure AD, Google Workspace)
 - Knowledge of your organization's SSO requirements
 

docs/enterprise-solutions/team-management/managing-members.mdx

@@ -199,7 +199,8 @@ Understanding how seats work helps you manage your license effectively:
   
   <Accordion title="Upgrading Your License" icon="arrow-up">
     Need more seats?
-    - **Enterprise Plan:** Includes unlimited seats with no per-user restrictions. Contact your account manager or visit app.cline.bot/settings/billing to upgrade.
+    - **Teams Plan:** Contact your account manager or visit app.cline.bot/settings/billing to upgrade your license.
+    - **Enterprise Plan:** Includes unlimited seats with no per-user restrictions.
   </Accordion>
 </AccordionGroup>
 
@@ -297,7 +298,7 @@ Now that you understand member management, proceed with configuring your organiz
   <Card 
     title="Configure Providers" 
     icon="plug" 
-    href="/enterprise-solutions/configuration/remote-configuration/overview"
+    href="/enterprise-solutions/configuration/choosing-your-deployment"
   >
     Set up API providers for your team to use
   </Card>

docs/features/auto-compact.mdx

@@ -35,7 +35,7 @@ Now with summarization:
 - You can work on much larger projects without interruption
 
 <Tip>
-Auto Compact works especially well for long-running tasks. Structured task lists can help maintain progress across summarizations so Cline can stay on track across multiple context windows.
+Auto Compact works beautifully with [Focus Chain](/features/focus-chain). When Focus Chain is enabled, todo lists persist across summarizations. Cline can work on long-horizon tasks spanning multiple context windows while staying on track.
 </Tip>
 
 ## Cost Considerations
@@ -44,6 +44,15 @@ Summarization leverages your existing prompt cache from the conversation, so it
 
 Since most input tokens are already cached, you're primarily paying for summary generation (output tokens), making it cost-effective.
 
+## Supported Models
+
+Auto Compact uses advanced LLM-based summarization for these models:
+
+- Claude 4 series
+- Gemini 2.5 series
+- GPT-5
+- Grok 4
+
 <Note>
 With other models, Cline falls back to standard rule-based context truncation, even if Auto Compact is enabled.
 </Note>

docs/features/background-edit.mdx

@@ -0,0 +1,51 @@
+---
+title: "Background Edit"
+sidebarTitle: "Background Edit"
+---
+
+Background Edit lets Cline make file changes without opening the diff editor, so you can keep writing code while Cline works on other files in the background.
+
+<Note>
+  This feature is marked as experimental.
+</Note>
+
+## How It Works
+
+By default, Cline opens a side-by-side diff editor tab for each file it modifies. With Background Edit enabled:
+
+- Edits write directly to your files without opening new tabs
+- Changes appear as collapsible diff blocks in the chat panel
+- Your editor focus stays on whatever file you had open
+
+## Enabling Background Edit
+
+1. Click the settings icon (gear) in the top-right corner of the Cline panel
+2. Go to "**Feature Settings**"
+3. Toggle "**Enable Background Edit**" on
+
+## Viewing Changes
+
+File changes display directly in the chat panel with:
+
+- **File action icons** showing whether the file was added, updated, or deleted
+- **Stats** showing additions (+) and deletions (-) at a glance
+- **Collapsible diffs** you can expand or collapse by clicking the file header
+- **Real-time streaming** as changes appear line-by-line
+
+Green highlights additions, red highlights deletions.
+
+## When to Use It
+
+This feature works well when you:
+
+- Use [auto-approve mode](/features/auto-approve) and prefer reviewing changes after the fact
+- Work on tasks with many small file changes
+- Want to stay focused on your current file
+
+Stick with the default diff editor if you prefer reviewing each change before it saves, or need to make inline edits to Cline's proposed changes.
+
+## Relationship with Other Features
+
+- **Checkpoints**: Still created after each file operation
+- **Auto-approve**: Pairs well for uninterrupted workflows
+- **Message editing**: Restoring from a previous message works as expected

docs/features/deep-planning.mdx

@@ -0,0 +1,129 @@
+---
+title: "Deep Planning"
+sidebarTitle: "Deep Planning"
+description: "Transform Cline into a meticulous architect who investigates your codebase and creates comprehensive implementation plans."
+---
+
+Deep Planning (`/deep-planning`) turns Cline into an architect before it becomes a builder. Instead of jumping straight into code, Cline systematically explores your codebase, asks targeted questions, and produces a detailed implementation plan — all before writing a single line.
+
+<Tip>
+**When should you use this?** Use `/deep-planning` for features that touch multiple files, architectural changes, complex integrations, or any task where "just start coding" would lead to rework.
+</Tip>
+
+## How It Works
+
+Deep Planning follows a four-step process:
+
+<Steps>
+  <Step title="Silent Investigation">
+    Cline explores your codebase without asking you anything. It reads relevant files, traces dependencies, examines patterns, and builds a mental model of how your project is structured. You'll see Cline reading files and running searches during this phase.
+
+    This step is intentionally silent — Cline gathers context first so it can ask better questions next.
+  </Step>
+
+  <Step title="Discussion">
+    Based on what it learned, Cline asks you targeted, specific questions about your requirements and preferences. These aren't generic questions — they're informed by what Cline found in your code.
+
+    For example, instead of asking "how should authentication work?", Cline might ask "I see you're using JWT tokens in `auth/middleware.ts` with refresh token rotation. Should the new endpoint follow the same pattern, or do you want session-based auth for this feature?"
+
+    Answer these questions to shape the plan. The more specific you are, the better the implementation plan will be.
+  </Step>
+
+  <Step title="Plan Creation">
+    Cline generates a comprehensive `implementation_plan.md` file in your project. This plan typically includes:
+
+    - **Overview** of the feature and its scope
+    - **File-by-file changes** with specific descriptions of what to add, modify, or remove
+    - **Dependencies** between changes (what needs to happen first)
+    - **Edge cases** and error handling considerations
+    - **Testing strategy** for the implementation
+
+    The plan is saved as a markdown file you can review, edit, and share with your team before any code is written.
+  </Step>
+
+  <Step title="Task Creation">
+    After you approve the plan, Cline creates a new task with the implementation steps loaded as trackable items. This gives you a clean context window focused entirely on execution, with the plan serving as the roadmap.
+  </Step>
+</Steps>
+
+## Using Deep Planning
+
+### Invoking It
+
+Type `/deep-planning` in the Cline chat input, followed by a description of what you want to build:
+
+```
+/deep-planning Add a notification system that sends email and in-app 
+notifications when users receive comments on their posts
+```
+
+The more context you provide upfront, the more focused the investigation phase will be. Include:
+
+- What you want to build
+- Any constraints or preferences
+- Which parts of the codebase are relevant (if you know)
+
+### Reviewing the Plan
+
+Once Cline generates `implementation_plan.md`, review it carefully:
+
+1. **Check the scope** — Does it cover everything you need? Is anything missing?
+2. **Verify the approach** — Does the technical approach match your preferences?
+3. **Review the order** — Are dependencies handled correctly?
+4. **Edit if needed** — It's a markdown file. Change anything that doesn't look right.
+
+Tell Cline about any adjustments before proceeding to implementation.
+
+## Model-Specific Optimization
+
+The deep planning prompt is optimized for each model family. Cline adapts its investigation and planning approach based on the strengths of whatever model you're using — whether that's Claude, GPT, Gemini, DeepSeek, or others.
+
+This means you get effective deep planning regardless of your model choice, though stronger reasoning models will generally produce more thorough plans.
+
+<Tip>
+Consider using a stronger reasoning model for the planning phase and a faster model for implementation. You can configure separate models for Plan and Act modes in Cline Settings. See [Plan & Act Mode](/core-workflows/plan-and-act#using-different-models-for-each-mode) for details.
+</Tip>
+
+## Pairing with Other Features
+
+Deep Planning works well with several other Cline features:
+
+| Feature | How It Helps |
+|---------|-------------|
+| [Focus Chain](/features/focus-chain) | Tracks implementation progress against the plan with a visible todo list |
+| [Memory Bank](/features/memory-bank) | Preserves project context across sessions so deep planning has richer input |
+| [Plan & Act Mode](/core-workflows/plan-and-act) | Use Plan mode for quick exploration, deep planning for thorough architecture |
+| [Checkpoints](/core-workflows/checkpoints) | Roll back implementation steps if something goes wrong during execution |
+
+<Tip>
+A powerful workflow: run `/deep-planning` to create the plan, enable [Focus Chain](/features/focus-chain) to track progress, then let Cline implement step by step. You get architecture-level thinking with granular progress visibility.
+</Tip>
+
+## Deep Planning vs Plan Mode
+
+Both involve thinking before doing, but they serve different purposes:
+
+| | Plan Mode | Deep Planning |
+|---|-----------|---------------|
+| **Scope** | Quick exploration and discussion | Thorough codebase investigation |
+| **Output** | Conversation context | `implementation_plan.md` file |
+| **Best for** | Medium tasks, understanding code | Large tasks, multi-file features |
+| **Duration** | Minutes | Longer — depends on codebase size |
+| **Persistence** | Lives in conversation history | Saved as a file you can reference later |
+
+For most development work, starting in Plan mode is sufficient. Reserve `/deep-planning` for tasks where you'd normally spend significant time planning on a whiteboard before coding.
+
+## Tips
+
+- **Be specific in your initial prompt.** "Add authentication" gives a vague plan. "Add OAuth2 authentication with Google and GitHub providers, using our existing user model in `models/user.ts`" gives a focused one.
+- **Point Cline at relevant files.** Use `@` mentions to highlight key files in your prompt so the investigation phase starts in the right place.
+- **Edit the plan before implementing.** The generated plan is a starting point. Adjust priorities, remove unnecessary steps, or add details before Cline starts coding.
+- **Save plans for reference.** The `implementation_plan.md` file is useful documentation even after the feature is built. Consider committing it or moving it to a docs folder.
+- **Use for onboarding.** Run `/deep-planning` on a feature you're unfamiliar with to get Cline to map out the codebase and explain how things connect.
+
+## Related
+
+- [Plan & Act Mode](/core-workflows/plan-and-act) — Cline's dual-mode system for structured development
+- [Focus Chain](/features/focus-chain) — Automatic todo list tracking for long-running tasks
+- [Memory Bank](/features/memory-bank) — Structured documentation for cross-session context
+- [Using Commands](/core-workflows/using-commands) — All available slash commands

docs/features/explain-changes.mdx

@@ -0,0 +1,91 @@
+---
+title: "Explain Changes"
+sidebarTitle: "Explain Changes"
+description: "Generate AI-powered inline explanations for any git diff, right inside a multi-file diff view."
+---
+
+`/explain-changes` lets you point Cline at any set of git changes — a commit, a branch comparison, a PR, uncommitted work — and get AI-generated inline comments explaining what changed and why. The comments appear directly in a side-by-side diff view inside VS Code.
+
+<Note>
+This feature is only available in VS Code. It is not supported in the CLI or JetBrains environments.
+</Note>
+
+## How to Use It
+
+Type `/explain-changes` in the Cline chat input, optionally followed by a description of what you want explained:
+
+```
+/explain-changes Explain the last commit
+```
+
+```
+/explain-changes What changed between main and feature/auth?
+```
+
+```
+/explain-changes Walk me through PR #42
+```
+
+If you don't provide any details, Cline defaults to analyzing uncommitted changes in your working directory.
+
+### What Happens Next
+
+1. **Cline gathers context** — It runs git or gh CLI commands to retrieve the diff, reads relevant files, and builds an understanding of the changes.
+2. **Cline calls `generate_explanation`** — This opens a multi-file diff view and streams AI-generated inline comments explaining each change.
+
+You'll see Cline working through these steps in the chat before the diff view opens.
+
+## Git Reference Formats
+
+Cline understands all standard git references. Here are common examples:
+
+| What You Want | How to Ask |
+|---|---|
+| Last commit | `Explain the last commit` |
+| Specific commit | `Explain commit abc1234` |
+| Commit range | `Explain changes from abc1234 to def5678` |
+| Branch comparison | `What changed between main and feature/auth?` |
+| Pull request | `Explain PR #42` |
+| Uncommitted changes | `Explain my current changes` |
+| Staged changes | `Explain what I've staged` |
+| Tag comparison | `What changed between v1.0 and v2.0?` |
+
+Under the hood, this translates to git refs like commit hashes, branch names, tags, and relative references (`HEAD~1`, `HEAD^`, `origin/main`, etc.).
+
+## Understanding the Output
+
+### Multi-File Diff View
+
+Cline opens a side-by-side diff view in VS Code showing the before and after state of each changed file. Inline comments are attached to the specific lines they explain.
+
+### Streaming Comments
+
+Comments appear in real-time as the AI generates them. For smaller diffs (1–2 files), the diff view opens immediately and comments stream in. For larger diffs (3+ files), Cline cycles through each file individually to show comments as they arrive, then opens the combined multi-file diff view at the end.
+
+### Interactive Replies
+
+Each comment thread is interactive — you can reply to ask follow-up questions about a specific change. Cline will respond with additional context about that code section. If you need Cline to actually modify code based on the discussion, each comment thread has an **"Add to Cline Chat"** button that sends the conversation to the main Cline agent.
+
+## Checkpoint-Based Explanations
+
+Beyond the slash command, you can also trigger Explain Changes from **checkpoint messages** within a task. When Cline creates checkpoints during a task, each checkpoint message has an option to explain the changes made since the previous checkpoint. This uses the same diff view and inline comments but compares checkpoint hashes rather than git refs.
+
+## Use Cases
+
+- **Code review** — Understand what a PR or commit does before approving it
+- **Onboarding** — Explore unfamiliar codebases by explaining recent changes
+- **Learning** — See explanations of how specific patterns or features were implemented
+- **Debugging** — Understand what changed between a working and broken state
+- **Documentation** — Generate explanations you can reference later when maintaining code
+
+## Tips
+
+- **Provide context in your prompt.** The more specific you are ("Explain the auth changes in PR #42"), the more focused Cline's investigation will be.
+- **Use `@` mentions.** Point Cline at specific files to give it additional context before generating explanations.
+- **Reply to comments.** The interactive threads let you dig deeper into any change you don't fully understand.
+
+## Related
+
+- [Using Commands](/core-workflows/using-commands) — All available slash commands
+- [Checkpoints](/core-workflows/checkpoints) — Git-based snapshots of your project during tasks
+- [Plan & Act Mode](/core-workflows/plan-and-act) — Cline's dual-mode system for structured development

docs/features/focus-chain.mdx

@@ -0,0 +1,65 @@
+---
+title: "Focus Chain"
+sidebarTitle: "Focus Chain"
+description: "Automatic todo list management with real-time progress tracking for long-running tasks."
+---
+
+Focus Chain is automatic todo list management with real-time progress tracking. It helps Cline work on longer tasks by maintaining a visible checklist that persists across context window resets.
+
+<Frame>
+	<img
+		src="https://storage.googleapis.com/cline_public_images/docs/assets/2dos.gif"
+		alt="Focus Chain todo list management with real-time progress tracking"
+	/>
+</Frame>
+
+## When to Use It
+
+Focus Chain works best for:
+- Multi-step implementations (building a feature end-to-end)
+- Tasks that might span multiple context windows
+- Work where you want visibility into Cline's plan
+
+For quick, single-step requests, Focus Chain adds overhead without much benefit.
+
+<Tip>
+Focus Chain pairs well with [Deep Planning](/features/deep-planning). Use `/deep-planning` to create a detailed implementation plan, then let Focus Chain track progress as you execute it.
+</Tip>
+
+## Enabling Focus Chain
+
+1. Click the gear icon in the Cline sidebar
+2. Navigate to "Features"
+3. Check "Enable Focus Chain"
+4. Optionally adjust "Remind Cline Interval" (default: 6 messages)
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| Enable Focus Chain | Disabled | Enables enhanced task progress tracking |
+| Remind Cline Interval | 6 | How often Cline updates the todo list (1-100 messages) |
+
+## How It Works
+
+When you start a task with Focus Chain enabled, Cline:
+
+1. Analyzes your request and creates a comprehensive todo list
+2. Stores it as an editable markdown file
+3. Updates progress in real-time as work progresses
+4. Shows a progress indicator in the task header (e.g., "3/8")
+
+The todo list uses standard markdown checklist syntax:
+
+```markdown
+- [x] Set up project structure
+- [x] Install authentication dependencies
+- [ ] Create user registration component
+- [ ] Implement login functionality  ← Currently working
+- [ ] Add password validation
+- [ ] Write authentication tests
+```
+
+## Editing Todo Lists
+
+Need to adjust the plan? Click the edit button in the expanded todo view. A markdown file opens in your editor where you can add, remove, or reorder items. Save the file and Cline automatically detects your updates.
+
+For complex projects, start with [Plan Mode](/core-workflows/plan-and-act) to discuss the approach before committing to a todo list.

docs/features/jupyter-notebooks.mdx

@@ -112,4 +112,4 @@ You can bind any of these commands to keyboard shortcuts for faster access:
 ## Related
 
 - [All Cline Tools](/tools-reference/all-cline-tools) - Overview of all Cline tools
-- [Cline provider](/getting-started/cline-provider) - Fastest way to get started with built-in provider setup
+- [Model Selection Guide](/core-features/model-selection-guide) - Choosing the right model for your workflow

docs/features/memory-bank.mdx

@@ -0,0 +1,222 @@
+---
+title: "Memory Bank"
+sidebarTitle: "Memory Bank"
+description: "A structured documentation system that helps Cline maintain context across sessions."
+---
+
+Memory Bank is a documentation methodology that transforms Cline from a stateless assistant into a persistent development partner. Through structured markdown files, Cline can "remember" your project details across sessions.
+
+## Quick Setup
+
+1. Copy the [custom instructions below](#memory-bank-custom-instructions)
+2. Add to custom instructions or a [`.clinerules` file](/customization/cline-rules)
+3. Ask Cline to "initialize memory bank"
+
+## How It Works
+
+Memory Bank files are regular markdown files in your project that both you and Cline can access. They're organized hierarchically to build a complete picture of your project:
+
+```text
+memory-bank/
+├── projectbrief.md      # Foundation document
+├── productContext.md    # Why this project exists
+├── activeContext.md     # Current work focus
+├── systemPatterns.md    # Architecture & patterns
+├── techContext.md       # Tech stack & setup
+└── progress.md          # Status & milestones
+```
+
+<Frame>
+	<img src="https://storage.googleapis.com/cline_public_images/docs/assets/image%20(16).png" alt="Memory Bank file hierarchy showing projectbrief.md at the top flowing into productContext, systemPatterns, and techContext, which feed into activeContext and progress" />
+</Frame>
+
+## Core Files
+
+| File | Purpose |
+|------|---------|
+| `projectbrief.md` | Foundation document with core requirements and goals |
+| `productContext.md` | Why the project exists, problems it solves, UX goals |
+| `activeContext.md` | Current focus, recent changes, next steps (updates most frequently) |
+| `systemPatterns.md` | Architecture, design patterns, component relationships |
+| `techContext.md` | Tech stack, setup, constraints, dependencies |
+| `progress.md` | What works, what's left, known issues |
+
+## Key Commands
+
+- **"follow your custom instructions"** - Tells Cline to read Memory Bank and continue where you left off
+- **"initialize memory bank"** - Creates the initial structure for a new project
+- **"update memory bank"** - Triggers a full documentation review and update
+
+These work alongside Cline's built-in [slash commands](/core-workflows/using-commands). In particular, [`/newtask`](/core-workflows/using-commands#newtask) and [`/smol`](/core-workflows/using-commands#smol) help you manage context windows without losing progress.
+
+## Working with Plan & Act Modes
+
+Memory Bank pairs naturally with [Plan & Act mode](/core-workflows/plan-and-act):
+
+- **Plan mode**: Start here when resuming a project. Ask Cline to read the Memory Bank, review the current state, and discuss strategy before making changes.
+- **Act mode**: Switch to Act mode once you have a plan. Cline retains everything from the planning session and can implement changes.
+
+For complex features, use [`/deep-planning`](/core-workflows/using-commands#deep-planning) to have Cline investigate your codebase and create a detailed implementation plan. The Memory Bank gives Cline the project context it needs to plan effectively.
+
+## Managing Context Windows
+
+Every AI model has a [context window](/core-workflows/task-management#context-window) that limits how much information it can process at once. As you work, this window fills with conversation history, file contents, and tool results. Memory Bank helps you preserve important knowledge when you need to free up space.
+
+### Manual approach
+
+When your context window fills up:
+
+1. Ask Cline to "update memory bank" to document the current state
+2. Start a new conversation
+3. Ask Cline to "follow your custom instructions"
+
+This preserves important context in your Memory Bank files before the window clears, letting you continue seamlessly in a fresh conversation.
+
+### Using slash commands
+
+Cline's built-in commands offer more targeted options:
+
+- **[`/smol`](/core-workflows/using-commands#smol)** compresses your conversation history while keeping you in the same task. Use this when you want to free up space without starting over.
+- **[`/newtask`](/core-workflows/using-commands#newtask)** distills key decisions, file changes, and progress into a fresh task with a clean context window. This is like a developer handoff that preserves what matters.
+
+### Automatic context management
+
+Enable [Auto-Compact](/features/auto-compact) to let Cline automatically compress context as you work. This reduces how often you need to manually manage the context window, though you should still update the Memory Bank after significant milestones.
+
+<Frame>
+	<img src="https://storage.googleapis.com/cline_public_images/docs/assets/image%20(18).png" alt="Context window progress bar showing usage approaching the limit" />
+</Frame>
+
+## Memory Bank and Checkpoints
+
+Memory Bank and [Checkpoints](/core-workflows/checkpoints) solve different sides of the same problem:
+
+- **Memory Bank** preserves *knowledge*: project context, decisions, patterns, and progress across sessions.
+- **Checkpoints** preserve *code state*: file snapshots you can restore if something goes wrong.
+
+Together, they let you experiment freely. Checkpoints protect your code, and Memory Bank protects your understanding of the project. If you need to roll back code changes, your Memory Bank still has the context of what you were trying to do and why.
+
+## Reducing Your Context Footprint
+
+Memory Bank works best when your starting context is lean. If Cline loads your entire project into context, including dependencies, build artifacts, and generated files, you burn through tokens before the real work starts.
+
+**Add a [`.clineignore`](/customization/clineignore) file.** This is the single biggest improvement most users can make. It tells Cline which files to skip when scanning your project. Adding one can drop your starting context from 200k+ tokens to under 50k, which means faster responses, lower costs, and the ability to use smaller models effectively.
+
+**Keep Memory Bank files concise.** Each file adds to your context when Cline reads it at the start of a session. Keep `projectbrief.md` to one page, `activeContext.md` to current state only (not a running log), and `progress.md` to a summary rather than a detailed changelog. If a file grows beyond a page or two, split the detail into a separate doc and link to it. Cline can read linked files on demand.
+
+**Use [Cline Rules](/customization/cline-rules) strategically.** Rules load into every request. Use [conditional rules](/customization/cline-rules#conditional-rules) to activate rules only when working with matching files, so frontend rules don't load when you're editing backend code.
+
+## Best Practices
+
+- Start with a basic project brief and let structure evolve
+- Let Cline help create the initial structure
+- `activeContext.md` changes most frequently; update it after each session
+- `progress.md` tracks milestones; review it when resuming work
+- Update after significant milestones or direction changes
+- Use [Cline Rules](/customization/cline-rules) to store the Memory Bank instructions per-project
+- Add a [`.clineignore`](/customization/clineignore) early to keep your starting context small
+
+---
+
+## Memory Bank Custom Instructions
+
+Copy this into custom instructions or a `.clinerules` file:
+
+```markdown
+# Cline's Memory Bank
+
+I am Cline, an expert software engineer with a unique characteristic: my memory resets completely between sessions. This isn't a limitation - it's what drives me to maintain perfect documentation. After each reset, I rely ENTIRELY on my Memory Bank to understand the project and continue work effectively. I MUST read ALL memory bank files at the start of EVERY task - this is not optional.
+
+## Memory Bank Structure
+
+The Memory Bank consists of core files and optional context files, all in Markdown format. Files build upon each other in a clear hierarchy:
+
+### Core Files (Required)
+1. `projectbrief.md`
+   - Foundation document that shapes all other files
+   - Created at project start if it doesn't exist
+   - Defines core requirements and goals
+   - Source of truth for project scope
+
+2. `productContext.md`
+   - Why this project exists
+   - Problems it solves
+   - How it should work
+   - User experience goals
+
+3. `activeContext.md`
+   - Current work focus
+   - Recent changes
+   - Next steps
+   - Active decisions and considerations
+   - Important patterns and preferences
+   - Learnings and project insights
+
+4. `systemPatterns.md`
+   - System architecture
+   - Key technical decisions
+   - Design patterns in use
+   - Component relationships
+   - Critical implementation paths
+
+5. `techContext.md`
+   - Technologies used
+   - Development setup
+   - Technical constraints
+   - Dependencies
+   - Tool usage patterns
+
+6. `progress.md`
+   - What works
+   - What's left to build
+   - Current status
+   - Known issues
+   - Evolution of project decisions
+
+### Additional Context
+Create additional files/folders within memory-bank/ when they help organize:
+- Complex feature documentation
+- Integration specifications
+- API documentation
+- Testing strategies
+- Deployment procedures
+
+## Documentation Updates
+
+Memory Bank updates occur when:
+1. Discovering new project patterns
+2. After implementing significant changes
+3. When user requests with **update memory bank** (MUST review ALL files)
+4. When context needs clarification
+
+REMEMBER: After every memory reset, I begin completely fresh. The Memory Bank is my only link to previous work. It must be maintained with precision and clarity, as my effectiveness depends entirely on its accuracy.
+```
+
+## FAQ
+
+**Custom instructions or .clinerules?**
+Either works. Custom instructions apply globally across all projects. A [`.clinerules` file](/customization/cline-rules) is project-specific and stored in your repo, which makes it easy to share with collaborators. You can also use [conditional rules](/customization/cline-rules#conditional-rules) to activate Memory Bank instructions only when working with `memory-bank/` files.
+
+**How often should I update?**
+After significant milestones or direction changes. For active development, every few sessions. You can also let [Auto-Compact](/features/auto-compact) handle routine context management and reserve manual "update memory bank" for important checkpoints.
+
+**How does Memory Bank relate to checkpoints?**
+[Checkpoints](/core-workflows/checkpoints) save your code state (file snapshots). Memory Bank saves your project knowledge (context, decisions, progress). They complement each other: checkpoints let you roll back code, Memory Bank lets you pick up where you left off intellectually.
+
+**How does Memory Bank relate to context window limitations?**
+Memory Bank stores important information in structured files that Cline can load efficiently at the start of each session. This prevents context bloat while keeping critical information available. For more on how context windows work, see [Task Management](/core-workflows/task-management#context-window).
+
+**Does this work with other AI tools?**
+Yes. Memory Bank is a documentation methodology that works with any AI that can read docs. Commands may differ but the approach works across tools.
+
+**Different from README files?**
+Memory Bank provides structured, comprehensive documentation designed for AI context management, going beyond what a single README covers. It includes files for active context and progress tracking that change frequently, unlike a typical README.
+
+For more information, see the [Memory Bank blog post](https://cline.bot/blog/memory-bank-how-to-make-cline-an-ai-agent-that-never-forgets).
+
+## Related
+
+- [Plan & Act Mode](/core-workflows/plan-and-act) - Separate thinking from doing with structured planning sessions
+- [Checkpoints](/core-workflows/checkpoints) - Roll back code changes while keeping your conversation context
+- [Cline Rules](/customization/cline-rules) - Define persistent instructions including Memory Bank setup
+- [Task Management](/core-workflows/task-management) - Understand tasks, context windows, and when to start fresh

docs/features/multiroot-workspace.mdx

@@ -111,7 +111,7 @@ For each workspace folder, Cline detects:
 This means Cline understands that your frontend and backend might be at different commits, on different branches, or even use different version control systems.
 
 <Note>
-While Cline detects VCS information for all workspace folders, certain features only use the **primary workspace** (the first folder): [Cline rules](/customization/cline-rules), [skills](/customization/skills#triggering-skills-with-slash-commands), and [Git-related features](/core-workflows/working-with-files) like `@git` mentions.
+While Cline detects VCS information for all workspace folders, certain features only use the **primary workspace** (the first folder): [Cline rules](/customization/cline-rules), [workflows](/customization/workflows), and [Git-related features](/core-workflows/working-with-files) like `@git` mentions.
 </Note>
 
 ## Referencing Files Across Workspaces

docs/features/subagents.mdx

@@ -24,13 +24,17 @@ Subagent costs (tokens and API spend) are tracked separately per subagent and ro
 
 ## Enabling Subagents
 
-Subagents are enabled by default. Cline decides when parallel research is worth the overhead — you don't need to opt in or call them out in your prompt. To turn subagents off, disable the `use_subagents` tool in Settings → Features → Agent.
+Subagents are disabled by default. To turn them on:
+
+1. Open Cline Settings (click the gear icon in the Cline panel)
+2. Go to **Features**
+3. Under the **Agent** section, toggle **Subagents** on
 
 This setting applies across all editors (VS Code, JetBrains, CLI).
 
 ## Using Subagents
 
-When subagents are enabled, Cline picks them up on its own when a task benefits from parallel exploration. You can also nudge it explicitly by asking for parallel research in your prompt.
+Cline does not automatically decide to use subagents. You need to ask for them in your prompt. When the feature is enabled and you mention subagents (or describe a task that benefits from parallel exploration), Cline will use the `use_subagents` tool.
 
 Example prompts:
 
@@ -45,6 +49,8 @@ You can also run only one subagent when the task is small enough that parallel d
 
 Subagents follow the **Read project files** auto-approve permission. If you have "Read project files" enabled in [Auto Approve](/features/auto-approve), subagent launches will be auto-approved.
 
+In [YOLO mode](/features/auto-approve#yolo-mode), subagents are always auto-approved.
+
 If auto-approve is off, Cline will ask for your approval before launching subagents, showing you the prompts it plans to send.
 
 ## What Subagents Can Do

docs/features/web-tools.mdx

@@ -0,0 +1,55 @@
+---
+title: "Web Tools"
+sidebarTitle: "Web Tools"
+description: "Search the web and fetch content from URLs directly within Cline"
+---
+
+Web Tools give Cline the ability to search the internet and fetch content from specific URLs during your tasks. This is useful when you need up-to-date information, documentation lookups, or research that goes beyond your local codebase and the LLM's internal knowledge.
+
+<Warning>
+	Web Tools require the **Cline provider**. They are not available when using other providers like OpenRouter, Anthropic, AWS Bedrock, etc.
+</Warning>
+
+## How Web Tools Work
+
+Cline has two web tools:
+
+- **web_search**: Searches the web and returns a list of relevant webpages based on your query
+- **web_fetch**: Fetches and analyzes content from a specific URL
+
+When Cline determines that web information would help complete your task, it will use these tools automatically. The tools call Cline's backend API, which handles the search or fetch operation and returns the results.
+
+## Enabling Web Tools
+
+Web Tools are available when using the Cline provider. To use them:
+
+1. Make sure you're signed in to Cline
+2. Ensure you're using the Cline provider
+3. Enable the Web Tools toggle in the Feature Settings menu
+
+<Note>
+	Web tools can be auto-approved using the "Use the browser" setting in [Auto Approve](/features/auto-approve).
+</Note>
+
+## Use Cases
+
+### Looking Up Documentation
+
+When working with unfamiliar libraries or APIs:
+- Search for official documentation
+- Fetch specific API reference pages
+- Get examples and usage patterns
+
+### Research Before Implementation
+
+Before implementing a feature:
+- Search for best practices and common patterns
+- Find recent discussions about approaches
+- Look up known issues or limitations
+
+### Checking Latest Information
+
+For time-sensitive information:
+- Latest release notes and changelogs
+- Recent bug fixes or security updates
+- Current recommended versions

docs/features/worktrees.mdx

@@ -0,0 +1,274 @@
+---
+title: "Worktrees"
+sidebarTitle: "Worktrees"
+---
+
+Worktrees let you work on multiple branches simultaneously, each in its own folder. This enables Cline to work on tasks in parallel across separate VS Code windows, or lets Cline work independently while you continue coding in your main workspace.
+
+## What Are Git Worktrees?
+
+A Git worktree is a linked copy of your repository in a separate folder, checked out to a specific branch. All worktrees share the same Git history and `.git` directory, but each has its own working directory with different code checked out.
+
+Key concepts:
+- **Main worktree**: Your original repository folder where the `.git` directory lives
+- **Linked worktrees**: Additional folders you create, each checked out to a different branch
+- **Shared history**: All worktrees share commits, branches, and Git configuration
+
+<Tip>
+  Unlike regular branch switching, worktrees let you have multiple branches checked out at the same time in different folders. This means you can have VS Code windows open for different features simultaneously.
+</Tip>
+
+## Why Use Worktrees with Cline?
+
+Worktrees solve a common problem: **Cline takes over your VS Code window while working on a task**. With worktrees, you can:
+
+1. **Run Cline in parallel** - Have Cline work on multiple tasks simultaneously, each in its own worktree and VS Code window
+2. **Keep working while Cline works** - Let Cline handle a task in a separate worktree while you continue coding in your main workspace
+3. **Isolate experimental changes** - Test risky changes in a worktree without affecting your main branch
+4. **Quick context switching** - Jump between features without stashing or committing incomplete work
+
+## Getting Started
+
+### Quick Launch (Recommended)
+
+The fastest way to start using worktrees is the **New Worktree Window** button on Cline's home screen:
+
+1. Click **New Worktree Window** on the home screen
+2. Enter a branch name and folder path (defaults are auto-filled)
+3. Click **Create & Open**
+
+A new VS Code window opens with your worktree, and Cline automatically opens ready to work.
+
+<Tip>
+  The home screen also shows your current branch and worktree path. Click it to open the full Worktrees view.
+</Tip>
+
+### Full Worktrees View
+
+For more control, open the full Worktrees view by clicking the **Worktrees** button in the Cline sidebar header, or by clicking your current branch info on the home screen:
+
+<Steps>
+  <Step title="Create a New Worktree">
+    Click **New Worktree** at the bottom of the view. Enter a branch name and path (defaults are auto-filled).
+  </Step>
+  <Step title="Open in New Window">
+    Once created, click the **Open in new window** button to open the worktree in a separate VS Code window. Cline will automatically open in the new window.
+  </Step>
+</Steps>
+
+## Typical Workflow
+
+Here's how a typical worktree session looks:
+
+<Steps>
+  <Step title="Create a new worktree">
+    Click **New Worktree Window** on the home screen or use the Worktrees view. A new VS Code window opens with Cline ready to go.
+  </Step>
+  <Step title="Do your work">
+    Work on your feature or let Cline handle a task. Make commits as you go.
+  </Step>
+  <Step title="Close the worktree window">
+    When you're done, close the worktree's VS Code window.
+  </Step>
+  <Step title="Merge from your primary worktree">
+    Back in your main VS Code window, open the Worktrees view and click the **merge button** on the worktree you just worked in. This merges the branch and optionally deletes the worktree.
+  </Step>
+</Steps>
+
+## Managing Worktrees
+
+### Viewing Worktrees
+
+The Worktrees view shows all worktrees for your repository:
+
+- **Current**: The worktree you're currently in (highlighted)
+- **Main**: The primary worktree where your `.git` directory lives (cannot be deleted)
+- **Locked**: Worktrees that are locked to prevent accidental deletion
+
+### Opening Worktrees
+
+Each worktree has two open options:
+- **Open in current window**: Replace your current workspace with the worktree
+- **Open in new window**: Open the worktree in a separate VS Code window (recommended for parallel Cline sessions)
+
+Either way, Cline automatically opens in the new workspace, ready to start a task.
+
+### Deleting Worktrees
+
+Click the trash icon on any linked worktree to delete it. A confirmation dialog will show you exactly what will be deleted:
+- The branch itself
+- All project files in the worktree folder
+
+<Warning>
+  Deleting a worktree permanently removes the branch and all files in that folder. Make sure any important changes are committed and pushed first.
+</Warning>
+
+<Note>
+  You cannot delete the main worktree. It's the primary repository where your `.git` directory lives.
+</Note>
+
+### Merging Worktrees
+
+When you're done working in a worktree and ready to merge your changes back to the main branch:
+
+1. Click the **merge icon** (git merge symbol) on any linked worktree
+2. Review the merge details in the confirmation modal
+3. Choose whether to delete the worktree after merging
+4. Click **Merge**
+
+#### Handling Merge Conflicts
+
+If your branch has conflicts with the main branch, Cline will detect them and show you the conflicting files. You have two options:
+
+1. **Ask Cline to Resolve & Merge** - Creates a new Cline task with a prompt asking Cline to resolve the conflicts, complete the merge, and clean up the worktree
+2. **Resolve Manually** - Close the modal and resolve conflicts yourself using your preferred Git tools
+
+<Tip>
+  The "Ask Cline to Resolve" option is particularly useful for complex conflicts. Cline will analyze the conflicting files and attempt to merge them intelligently based on the intent of both branches.
+</Tip>
+
+## .worktreeinclude: Automatic File Copying
+
+When you create a new worktree, it starts with a fresh checkout—no `node_modules`, no build artifacts, no IDE settings. This means you'd normally need to run `npm install` or similar setup commands.
+
+The `.worktreeinclude` file solves this by automatically copying specified files to new worktrees.
+
+### How It Works
+
+1. Create a `.worktreeinclude` file in your repository root
+2. Add glob patterns for files you want copied (using `.gitignore` syntax)
+3. When Cline creates a new worktree, files matching **both** `.worktreeinclude` **and** `.gitignore` are copied automatically
+
+<Note>
+  Only files that are both matched by `.worktreeinclude` AND listed in `.gitignore` are copied. This prevents accidentally duplicating tracked files.
+</Note>
+
+### Example `.worktreeinclude`
+
+```gitignore
+# Copy node_modules to avoid npm install
+node_modules/
+
+# Copy IDE settings
+.vscode/
+
+# Copy build cache
+.next/
+dist/
+
+# Copy environment files (if gitignored)
+.env.local
+```
+
+### Creating a `.worktreeinclude` File
+
+The Worktrees view will show a tip if you don't have a `.worktreeinclude` file. If you have a `.gitignore`, you can click **Create from .gitignore** to create one pre-filled with your gitignore contents. Then edit it to keep only the patterns you want copied.
+
+<Tip>
+  For most JavaScript/TypeScript projects, just including `node_modules/` in your `.worktreeinclude` saves significant setup time for each new worktree.
+</Tip>
+
+### Pro Tip: Symlink to .gitignore
+
+Since `.gitignore` usually contains most of the files you'd want copied to new worktrees (dependencies, environment files, build caches, etc.), you can create a symlink so they stay in sync automatically:
+
+```bash
+# In your repository root
+ln -s .gitignore .worktreeinclude
+```
+
+Now whenever you update your `.gitignore`, your `.worktreeinclude` will have the same patterns. This is especially useful for projects where gitignored files are exactly what you want copied—no need to maintain two separate files.
+
+<Note>
+  If you need different patterns than your `.gitignore`, create a regular `.worktreeinclude` file instead of a symlink.
+</Note>
+
+## Best Practices
+
+<AccordionGroup>
+  <Accordion title="For Parallel Cline Sessions">
+    1. **Create purpose-specific worktrees** - Name branches clearly (e.g., `cline/refactor-auth`, `cline/add-tests`)
+    2. **Open in new windows** - Always use "Open in new window" for true parallelism
+    3. **Use .worktreeinclude** - Set up automatic file copying to reduce setup time
+  </Accordion>
+  <Accordion title="For Solo Development">
+    1. **Keep your main branch clean** - Use worktrees for experimental or risky changes
+    2. **Quick feature switches** - Instead of stashing, create a worktree for interruptions
+    3. **Review in isolation** - Create worktrees to review PRs without disrupting your work
+  </Accordion>
+  <Accordion title="Worktree Hygiene">
+    1. **Delete unused worktrees** - Remove worktrees when their branches are merged
+    2. **Use meaningful names** - Branch names should indicate the worktree's purpose
+    3. **Check for stale worktrees** - Periodically review and clean up old worktrees
+  </Accordion>
+</AccordionGroup>
+
+## Limitations
+
+Worktrees are not available in certain workspace configurations:
+
+- **Multi-root workspaces**: If you have multiple folders open in VS Code, worktrees are disabled. Open a single repository folder instead.
+- **Subfolder of a repository**: If you've opened a subfolder within a Git repository (not the root), worktrees are disabled. Open the repository root folder instead.
+
+The Worktrees view will display a message explaining the limitation if either of these applies to your workspace.
+
+## Using Worktrees with Cline CLI
+
+Cline CLI's `--cwd` flag unlocks powerful command-line worktree workflows:
+
+- **Parallel execution**: Run multiple Cline instances simultaneously in different worktrees
+- **Context piping**: Pipe output from one worktree as input to another for iterative refinement
+- **Combined with other features**: Use with `--config` for different models per worktree, or `--thinking` for deep analysis
+
+Example:
+```bash
+# Run parallel tasks in different worktrees
+cline --cwd ~/worktree-a -y "refactor authentication" &
+cline --cwd ~/worktree-b -y "add unit tests" &
+wait
+```
+
+For complete CLI worktree patterns and examples, see [Worktree Workflows](/cline-cli/samples/worktree-workflows).
+
+## Troubleshooting
+
+<AccordionGroup>
+  <Accordion title="Branch already exists error">
+    Git doesn't allow the same branch to be checked out in multiple worktrees. Either:
+    - Use a different branch name
+    - Delete the existing worktree using that branch
+  </Accordion>
+  <Accordion title="Worktree folder already exists">
+    The path you specified already contains files. Choose a different path or delete the existing folder first.
+  </Accordion>
+  <Accordion title="Can't delete worktree">
+    If a worktree is locked, you'll need to unlock it first using `git worktree unlock <path>` in the terminal. If the worktree has uncommitted changes, you may need to use force delete.
+  </Accordion>
+  <Accordion title=".worktreeinclude files not copying">
+    Make sure the files you want copied are:
+    1. Listed in your `.worktreeinclude` file
+    2. Also listed in your `.gitignore` (only gitignored files are copied)
+    3. Actually exist in your current worktree
+  </Accordion>
+</AccordionGroup>
+
+## Technical Details
+
+<AccordionGroup>
+  <Accordion title="How Worktrees Work Internally">
+    - Worktrees are a native Git feature (`git worktree` command)
+    - All worktrees share the same `.git` directory and object database
+    - Each worktree has its own index, working directory, and HEAD
+    - Worktree list is stored in `.git/worktrees/`
+  </Accordion>
+  <Accordion title="Storage Considerations">
+    - Each worktree contains a full checkout of the repository
+    - `.worktreeinclude` can significantly increase worktree size (e.g., copying `node_modules`)
+    - Consider your disk space when creating many worktrees
+  </Accordion>
+  <Accordion title="Relationship with Checkpoints">
+    Worktrees are separate from Cline's [checkpoint system](/core-workflows/checkpoints). Each worktree has its own checkpoint history. Checkpoints track changes within a single worktree, while worktrees let you work across multiple branches simultaneously.
+  </Accordion>
+</AccordionGroup>
+
+Worktrees unlock true parallel development with Cline. Create a worktree, open it in a new window, and let Cline work independently while you continue coding!

docs/getting-started/authorizing-with-cline.mdx

@@ -1,51 +1,100 @@
 ---
-title: "Authorization"
+title: "Authorization & Model Selection"
 description: "Authenticate with Cline and choose your first AI model"
 ---
 
 Cline connects to AI models through a **provider**. You have two paths:
 
-- **Cline Provider** (recommended): sign in with Google/GitHub/email, no API key setup.
-- **Bring Your Own Key (BYOK)**: use your own provider credentials (cloud or local runtimes).
+<CardGroup cols={2}>
+  <Card title="Cline Provider" icon="bolt">
+    Sign in with Google, GitHub, or email. No API keys to manage — access multiple models with built-in billing, free options, and early access to new releases.
 
-## Menu
+    **Best for:** Most users, fastest setup
+  </Card>
+  <Card title="Bring Your Own Key (BYOK)" icon="key">
+    Use 3rd party provider or API keys from Anthropic, OpenAI, OpenRouter, or any supported provider. Run models locally with Ollama or LM Studio for complete privacy.
 
-- [IDE Setup](#ide-setup)
-- [CLI Setup](#cli-setup)
+    **Best for:** Enterprise, custom billing, local models
+  </Card>
+</CardGroup>
 
-## IDE Setup
+<Tip>
+  **Watch:** [Selecting Your Model](https://youtu.be/GuPmu5TVtfA) walks through choosing and configuring your first model.
+</Tip>
+
+## Setup Steps
 
 <Steps>
-  <Step title="Open Cline Settings">
-    Click the settings icon (⚙️) in the Cline panel.
+  <Step title="Open Settings">
+    Click the settings icon in the top-right of the Cline panel.
   </Step>
 
-  <Step title="Select Provider">
-    Choose your desired provider from the **API Provider** dropdown.
+  <Step title="Select a Provider">
+    Choose from the **API Provider** dropdown:
+    - **Cline** — simplest setup, no API key needed
+    - **OpenRouter** — many models, one API key
+    - **Anthropic** — direct Claude access
+    - **Ollama / LM Studio** — run models locally
   </Step>
 
   <Step title="Authenticate">
-    - **Cline Provider:** Click **Sign In** and complete OAuth.
-    - **BYOK cloud provider:** Paste your API key into the **API Key** field.
-    - **Local runtime (Ollama/LM Studio):** no key needed; ensure runtime is running.
+    **Cline Provider:** Click **Sign In** and authenticate via Google, GitHub, or email. See [OAuth details](#how-oauth-works) below.
+
+    **BYOK:** Paste your API key from your provider's dashboard.
+
+    **Local:** No key needed — just ensure your local server is running.
+
+    <Note>
+    API keys are stored in your system's credential manager and sent only to your selected provider. They are never logged or transmitted to Cline's servers.
+    </Note>
   </Step>
 
-  <Step title="Select Model">
-    Choose your desired Claude model from the **Model** dropdown.
+  <Step title="Choose a Model">
+    Select a model from the **Model** dropdown. Consider:
+    - **Context window** — how much code the model can process at once
+    - **Speed** — smaller models respond faster
+    - **Cost** — varies by model; local models are free
+  </Step>
+
+  <Step title="Verify">
+    Send any message. If Cline responds, you're ready.
   </Step>
 </Steps>
 
-## Provider Options
+## Cline Provider
 
-### Cline Provider
+The Cline Provider gives you one account, one billing relationship, and access to models from Anthropic, OpenAI, Google, and more.
 
-- One sign-in, no key management
-- Built-in billing and free model options
-- Access to multiple providers from one account
+- **No API key juggling** — one sign-in, multiple models
+- **Built-in billing** — add credits once, use across all models
+- **Free models** — search "free" in the model selector to find no-cost options tagged **FREE**
+- **Stealth models** — early access to new releases before they're widely available
+- **Always current** — new models added as they launch
 
-Add credits in Cline settings or at [app.cline.bot/dashboard](https://app.cline.bot/dashboard).
+### Adding Credits
 
-### BYOK (cloud + local)
+Click **Add Credits** in Cline settings or visit your [account dashboard](https://app.cline.bot/dashboard). Credits work across all available models.
+
+### How OAuth Works
+
+<Steps>
+  <Step title="Sign In">
+    Click **Sign In** in Cline settings. Your browser opens to `app.cline.bot`.
+  </Step>
+  <Step title="Authenticate">
+    Choose Google, GitHub, or email.
+  </Step>
+  <Step title="Return to IDE">
+    After authentication, you're redirected back with an authorization code.
+  </Step>
+  <Step title="Secure Storage">
+    Tokens are stored in your IDE's native secret storage (VS Code Secrets, JetBrains Credential Store, etc.).
+  </Step>
+</Steps>
+
+## Bring Your Own Key (BYOK)
+
+Use your own API keys when you need specific billing arrangements, higher rate limits, access to beta models, or local privacy.
 
 ### Cloud Providers
 
@@ -53,9 +102,9 @@ Add credits in Cline settings or at [app.cline.bot/dashboard](https://app.cline.
 |----------|----------|-------------|
 | **OpenRouter** | Multiple models, competitive pricing | [Setup](/provider-config/openrouter) |
 | **Anthropic** | Direct Claude access | [Setup](/provider-config/anthropic) |
-| **Claude Code** | Claude Max/Pro subscription | [Setup](/provider-config/anthropic) |
+| **Claude Code** | Claude Max/Pro subscription | [Setup](/provider-config/claude-code) |
 | **OpenAI** | GPT models | [Setup](/provider-config/openai) |
-| **Google Gemini** | Gemini models | [Setup](/provider-config/google-gemini) |
+| **Google Gemini** | Large context windows | [Setup](/provider-config/gcp-vertex-ai) |
 | **AWS Bedrock** | Enterprise | [Setup](/provider-config/aws-bedrock/api-key) |
 | **DeepSeek** | Great value | [Setup](/provider-config/deepseek) |
 
@@ -65,12 +114,26 @@ Run models on your own hardware for complete privacy and zero per-request costs.
 
 | Provider | Best For | Setup Guide |
 |----------|----------|-------------|
-| **Ollama** | CLI-based local runtime | [Setup](/running-models-locally/overview#runtime-options) |
-| **LM Studio** | GUI-based local runtime | [Setup](/running-models-locally/overview#runtime-options) |
+| **Ollama** | Easy setup, wide model selection | [Setup](/running-models-locally/ollama) |
+| **LM Studio** | GUI-based model management | [Setup](/running-models-locally/lm-studio) |
 
 Local models require sufficient hardware (especially GPU memory). See [Running Models Locally](/running-models-locally/overview) for requirements.
 
-## CLI Setup
+## Which Model Should I Choose?
+
+| Priority | Recommended Model |
+|----------|-------------------|
+| **Reliability** | Claude Sonnet 4 |
+| **Value** | Qwen3 Coder |
+| **Speed** | Cerebras GLm 4.6 |
+| **Privacy** | Any Ollama/LM Studio model |
+| **Existing subscription** | Claude Code with Max/Pro |
+
+<Note>
+Learn more about LLMs and models in [Chapter 2 of AI Coding University](https://cline.bot/learn).
+</Note>
+
+## CLI Authentication
 
 ```bash
 # Authenticate from the terminal
@@ -80,7 +143,12 @@ cline auth
 cline a
 ```
 
-Runs the same auth flow as IDE setup.
+Opens a browser for OAuth, same as the IDE extension. Your session persists until you sign out.
+
+## Account Management
+
+- **Balance & usage:** Open Cline settings — your credit balance is at the top. Click **View Usage** for transaction history.
+- **Switch organization:** Go to Cline settings → **Switch Organization** to change which billing account is charged.
 
 ## Troubleshooting
 
@@ -90,3 +158,9 @@ Runs the same auth flow as IDE setup.
 | Browser doesn't open | Check default browser settings. Copy the URL from the Cline output panel manually. |
 | Frequent re-authentication | Check org security policies. Ensure you're not clearing IDE secrets. Try a full sign-out/sign-in. |
 | Can't access organization | Verify membership at [app.cline.bot](https://app.cline.bot). Ask your admin about permissions. Sign out and back in. |
+
+## Next Steps
+
+- [Your First Project](/getting-started/your-first-project) — build something with Cline
+- [Core Workflows](/core-workflows/task-management) — patterns you'll use daily
+- [Customization](/customization/overview) — tailor Cline to your workflow

docs/getting-started/cline-provider.mdx

@@ -1,51 +0,0 @@
----
-title: "Cline provider"
-description: "Use the Cline provider for the fastest setup with built-in authentication and unified billing."
----
-
-The **Cline provider** is the simplest way to get started with Cline.
-
-Instead of managing separate API keys across multiple vendors, you sign in once and select from available models directly in Cline.
-
-## Why use Cline provider
-
-- **Fastest setup**: no manual API key copy/paste
-- **One account**: sign in once with Google, GitHub, or email
-- **Unified billing**: one balance across supported models
-- **Free options**: look for models tagged **FREE** in the selector
-
-## Setup
-
-<Steps>
-  <Step title="Open Cline Settings">
-    Click the settings icon in the Cline panel.
-  </Step>
-
-  <Step title="Choose Provider">
-    Set **API Provider** to **Cline**.
-  </Step>
-
-  <Step title="Sign In">
-    Click **Sign In** and complete authentication in your browser.
-  </Step>
-
-  <Step title="Select a Model">
-    Choose a model from the **Model** dropdown.
-  </Step>
-
-  <Step title="Verify">
-    Send a test message. If Cline responds, setup is complete.
-  </Step>
-</Steps>
-
-## Credits and usage
-
-- Add credits from your [Cline dashboard](https://app.cline.bot/dashboard)
-- View usage in Cline Settings → **View Usage**
-- Switch organizations in Cline Settings → **Switch Organization**
-
-## Related
-
-- [Authorization](/getting-started/authorizing-with-cline)
-- [Local models](/running-models-locally/overview)
-- [Provider setup guides](/provider-config/openrouter)

docs/getting-started/config.mdx

@@ -1,165 +0,0 @@
----
-title: "Config"
-sidebarTitle: "Config"
-description: "Understand where Cline stores configuration and how global and project config work together."
----
-
-Cline configuration lives in two scopes:
-
-- **Global configuration** in `~/.cline/` (applies globally across all Cline applications, including IDE, CLI, and SDK)
-- **Project configuration** in `.cline/` (applies only to the current workspace)
-
-## Configuration Directory Layout
-
-Cline stores shared configuration across a few well-known locations. The primary root is `~/.cline/`, with structured app state under `~/.cline/data/`:
-
-```text
-~/.cline/
-  data/
-    settings/
-      providers.json           # API keys and provider configuration
-      global-settings.json     # Global settings
-      cline_mcp_settings.json  # MCP settings
-    teams/                     # Team state
-    sessions/                  # Session data
-    db/                        # SQLite databases (for example cron.db)
-    workflows/                 # Global workflows
-  rules/                       # Global rules
-  hooks/                       # Global hooks
-  skills/                      # Global skills
-  agents/                      # Global agent definitions
-  plugins/                     # Global plugins (.js, .ts)
-  cron/                        # Global cron specs
-```
-
-Additional global search paths supported by the code:
-
-```text
-~/Documents/Cline/
-  Rules/                       # Additional global rules
-  Hooks/                       # Additional global hooks
-  Plugins/                     # Additional global plugins
-  Workflows/                   # Additional global workflows
-```
-
-Project-level configuration lives in `.cline/` at your repository root:
-
-```text
-.cline/
-  rules/                       # Project rules
-  skills/                      # Project skills
-  hooks/                       # Lifecycle hooks
-  agents/                      # Project agent definitions
-  plugins/                     # Project plugins
-  cron/                        # Workspace cron specs
-```
-
-Notes:
-
-- Global provider settings, global settings, and MCP settings are stored under `~/.cline/data/settings/`.
-- Global workflows resolve from `~/.cline/data/workflows/`.
-- Global rules, hooks, skills, agents, plugins, and cron specs resolve directly under `~/.cline/`.
-- Rules, hooks, plugins, and workflows may also be discovered from `~/Documents/Cline/` for compatibility.
-
-## What Goes Where?
-
-- Use **global (`~/.cline/`)** for defaults shared across all Cline applications (IDE, CLI, SDK) on your machine.
-- Use **project (`.cline/`)** for team-shared behavior that should travel with the repo.
-
-Commit `.cline/` files you want to share with your team. Keep secrets out of the repo.
-
-## Configure Through the CLI
-
-Use the interactive config UI:
-
-```bash
-cline config
-```
-
-From there, you can view/edit:
-
-- Settings (global + workspace)
-- Rules
-- Skills
-- Hooks
-
-## Useful Configuration Commands
-
-Use a custom configuration directory:
-
-```bash
-cline --config /path/to/custom/config "your task"
-```
-
-Or via environment variable:
-
-```bash
-export CLINE_DATA_DIR=/custom/path/to/cline
-cline "your task"
-```
-
-View CLI logs when troubleshooting:
-
-```bash
-cline dev log
-```
-
-## Environment Variables
-
-| Variable | Description |
-|----------|-------------|
-| `CLINE_DATA_DIR` | Custom data directory (replaces `~/.cline/data/`) |
-| `CLINE_HUB_ADDRESS` | Override hub address (default: `127.0.0.1:25463`) |
-| `CLINE_SESSION_BACKEND_MODE` | Force backend mode (`local`, `hub`, `remote`, `auto`) |
-| `CLINE_SANDBOX` | Enable sandbox mode |
-| `CLINE_SANDBOX_DATA_DIR` | Sandbox session storage directory |
-| `CLINE_HOOKS_DIR` | Additional hooks directory |
-| `CLINE_COMMAND_PERMISSIONS` | JSON policy restricting shell commands |
-
-### CLINE_DATA_DIR
-
-```bash
-export CLINE_DATA_DIR=/custom/path/to/cline
-cline "your task"
-```
-
-### CLINE_COMMAND_PERMISSIONS
-
-Restrict which shell commands Cline can execute:
-
-```bash
-export CLINE_COMMAND_PERMISSIONS='{"allow": ["npm *", "git *"], "deny": ["rm -rf *"]}'
-```
-
-Format:
-
-```json
-{
-  "allow": ["pattern1", "pattern2"],
-  "deny": ["pattern3"],
-  "allowRedirects": true
-}
-```
-
-Rules:
-
-- `deny` overrides `allow`
-- If `allow` is set, commands not matching `allow` are denied
-- `allowRedirects` controls shell redirects (`>`, `>>`, `<`), default `false`
-
-## Related Docs
-
-- [CLI Configuration](/cli/configuration)
-- [Rules](/customization/cline-rules)
-- [Skills](/customization/skills)
-- [Hooks](/customization/hooks)
-- [Plugins](/customization/plugins)
-- [.clineignore](/customization/clineignore)
-
-## Security Notes
-
-<Warning>
-Only use rules, hooks, skills, and plugins from sources you trust.
-</Warning>
-
-Hooks and plugins can execute code. Review them like any other executable artifact before adding them globally or to a project.

docs/getting-started/installing-cline.mdx

@@ -1,139 +1,296 @@
 ---
 title: "Installing Cline"
-description: "Choose your installation path: IDE Extension, CLI, SDK, or Kanban"
+description: "Get Cline up and running in your favorite IDE or terminal with these simple installation steps"
 ---
 
-## Choose Your Install Path
+## Before You Begin
 
-- [IDE Extension](#ide-extension) — VS Code, Cursor, JetBrains, Windsurf, VSCodium, Antigravity
-- [CLI](#cli) — terminal workflows
-- [Kanban](#kanban) (preview) — easily manage through multiple agents through a kanban board
-- [SDK](#sdk) — build with `@cline/sdk`
+1. **Create your account** at [app.cline.bot](https://app.cline.bot/login) for access to multiple AI models, seamless setup without managing API keys, and occasional free inferencing.
 
-## IDE Extension
+2. **Choose your platform**: VS Code, Cursor, Antigravity, JetBrains IDEs, CLI (macOS/Linux preview), Zed, Neovim, VSCodium, or Windsurf.
 
-Use this if you want Cline inside your editor UI.
+## Installation Instructions
 
 <Tabs>
-  <Tab title="VS Code / Cursor / Windsurf / VSCodium / Antigravity">
+  <Tab title="VS Code/Cursor/Antigravity">
     <Steps>
+      <Step title="Open VS Code, Cursor, or Antigravity">
+        Launch the editor on your computer.
+      </Step>
+      <Step title="Open Extensions">
+        Press `Ctrl/Cmd + Shift + X` or click the Extensions icon in the Activity Bar.
+      </Step>
+      <Step title="Search for Cline">
+        Type "Cline" in the search bar.
+      </Step>
+      <Step title="Install">
+        Click the **Install** button on the Cline extension.
+      </Step>
+      <Step title="Access Cline">
+        Click the Cline icon in the Activity Bar, or open Command Palette (`Ctrl/Cmd + Shift + P`) and type "Cline: Open In New Tab".
+      </Step>
+    </Steps>
+
+    <Tip>
+    If VS Code shows "Running extensions might..." dialog, click **Allow**. If you don't see the Cline icon, restart VS Code.
+    </Tip>
+  </Tab>
+  <Tab title="JetBrains IDEs">
+    <Note>
+    Cline for JetBrains works almost identically to VS Code, with all core features: diff editing, tools, multiple API providers, MCP servers, Cline rules/workflows, and more.
+    </Note>
+
+    <Steps>
+      <Step title="Open your JetBrains IDE">
+        Launch IntelliJ IDEA, PyCharm, WebStorm, or any JetBrains IDE.
+      </Step>
+      <Step title="Open Settings">
+        Press `Ctrl+Alt+S` (Windows/Linux) or `Cmd+,` (macOS).
+      </Step>
+      <Step title="Navigate to Plugins">
+        Go to **Plugins** → **Marketplace** tab.
+      </Step>
+      <Step title="Install Cline">
+        Search for "Cline" and click **Install**.
+      </Step>
+      <Step title="Restart IDE">
+        Restart your IDE to complete the installation.
+      </Step>
+    </Steps>
+
+    Find Cline in **View** → **Tool Windows** → **Cline** (usually on the right side).
+
+    <AccordionGroup>
+      <Accordion title="Alternative Installation Methods">
+        **Browser Install:**
+        1. Go to the [JetBrains Marketplace](https://plugins.jetbrains.com/plugin/28247-cline)
+        2. Click **Install to IDE**
+        3. Confirm in your IDE and restart
+
+        **Manual Install:**
+        1. Download from the [marketplace page](https://plugins.jetbrains.com/plugin/28247-cline)
+        2. Go to **Settings** → **Plugins** → gear icon → **Install Plugin from Disk**
+        3. Select the downloaded `.zip` file and restart
+      </Accordion>
+
+      <Accordion title="Terminal Integration Difference">
+        JetBrains shows terminal output differently than VS Code. In VS Code, output streams directly to chat. In JetBrains, output appears in collapsible "Command Output" sections.
+        
+        Commands execute successfully in both. Expand the section to see results in JetBrains.
+      </Accordion>
+    </AccordionGroup>
+  </Tab>
+  <Tab title="CLI">
+    <Warning>
+    **Preview Release**: Cline CLI is currently in preview and only available for macOS and Linux. Windows support is coming soon.
+    </Warning>
+
+    Cline CLI runs AI coding agents directly in your terminal. Use it for automated code reviews in CI/CD, multi-instance development, or shell workflow integration.
+
+    <Steps>
+      <Step title="Install Node.js 20+">
+        Check your version with `node --version`. If needed, visit [nodejs.org](https://nodejs.org) or use nvm.
+      </Step>
+      <Step title="Install Cline CLI">
+        Run `npm install -g cline` in your terminal.
+      </Step>
+      <Step title="Authenticate">
+        Run `cline auth` to sign in and configure your AI model provider.
+      </Step>
+      <Step title="Run Cline">
+        Run `cline` to start an interactive session, or `cline "Your task here"` for headless execution.
+      </Step>
+    </Steps>
+
+    <Tip>
+    Want to learn more? See the [Cline CLI documentation](/cline-cli/getting-started) for advanced usage patterns like multi-instance development and CI/CD integration.
+    </Tip>
+  </Tab>
+  <Tab title="Zed/Neovim (ACP via CLI)">
+    <Note>
+    **ACP (Agent Client Protocol)** lets you run Cline in any ACP-compatible editor via the CLI. This gives you full access to Cline's capabilities—including Skills, Hooks, and MCP integrations—in your preferred editor.
+    </Note>
+
+    <Steps>
+      <Step title="Install Node.js 20+">
+        Check your version with `node --version`. If needed, visit [nodejs.org](https://nodejs.org) or use nvm.
+      </Step>
+      <Step title="Install Cline CLI">
+        ```bash
+        npm install -g cline
+        ```
+      </Step>
+      <Step title="Authenticate">
+        ```bash
+        cline auth
+        ```
+      </Step>
+      <Step title="Configure your editor">
+        <Tabs>
+          <Tab title="Zed">
+            Open Zed settings (`Cmd/Ctrl + ,`) and add Cline to your `settings.json`:
+            ```json
+            {
+              "agent_servers": {
+                "Cline": {
+                  "type": "custom",
+                  "command": "cline",
+                  "args": ["--acp"],
+                  "env": {}
+                }
+              }
+            }
+            ```
+            Then open the AI assistant panel, select **Cline** from the agent dropdown, and start coding.
+          </Tab>
+          <Tab title="Neovim (agentic.nvim)">
+            Install [agentic.nvim](https://github.com/carlos-algms/agentic.nvim) using lazy.nvim:
+            ```lua
+            {
+              "carlos-algms/agentic.nvim",
+              opts = {
+                provider = "cline-acp",
+                acp_providers = {
+                  ["cline-acp"] = {
+                    command = "cline",
+                    args = {"--acp"},
+                  },
+                },
+              },
+              keys = {
+                {"<C-\\>", function() require("agentic").toggle() end, mode={"n","v","i"}, desc="Toggle Cline Chat"},
+              },
+            }
+            ```
+            Press `<C-\>` to toggle the Cline chat panel.
+          </Tab>
+          <Tab title="Neovim (avante.nvim)">
+            Follow the [avante.nvim documentation](https://github.com/yetone/avante.nvim) for configuring external ACP agents and point it to `cline --acp`.
+          </Tab>
+        </Tabs>
+      </Step>
+    </Steps>
+
+    <Tip>
+    For full details on ACP editor integrations—including JetBrains ACP setup and troubleshooting—see the [ACP Editor Integrations](/cline-cli/acp-editor-integrations) guide.
+    </Tip>
+  </Tab>
+  <Tab title="VSCodium/Windsurf">
+    <Note>
+    These editors use the **Open VSX Registry** instead of the VS Code Marketplace, but the installation process is nearly identical.
+    </Note>
+
+    <Steps>
+      <Step title="Open your editor">
+        Launch VSCodium, Windsurf, or another Open VSX-compatible editor.
+      </Step>
       <Step title="Open Extensions">
         Press `Ctrl/Cmd + Shift + X`.
       </Step>
       <Step title="Search for Cline">
-        Type `Cline`.
+        Type "Cline" in the search bar.
       </Step>
       <Step title="Install">
-        Click **Install** on the Cline extension.
+        Select "Cline" by saoudrizwan and click **Install**.
       </Step>
-      <Step title="Open Cline">
-        Use the Cline activity bar icon, or run `Cline: Open In New Tab` from Command Palette.
-      </Step>
-      <Step title="Authorize with Cline">
-        After installing the extension, complete provider setup in Cline settings.
-
-        [Authorize with Cline](/getting-started/authorizing-with-cline)
+      <Step title="Reload">
+        Reload your editor if prompted.
       </Step>
     </Steps>
 
-    <Note>
-    Windsurf and VSCodium use Open VSX. The install flow is the same.
-    </Note>
-  </Tab>
-
-  <Tab title="JetBrains">
-    <Steps>
-      <Step title="Open Plugins Marketplace">
-        **Settings** → **Plugins** → **Marketplace**.
-      </Step>
-      <Step title="Install Cline">
-        Search `Cline`, click **Install**, then restart the IDE.
-      </Step>
-      <Step title="Open Cline">
-        **View** → **Tool Windows** → **Cline**.
-      </Step>
-      <Step title="Authorize with Cline">
-        After installing the extension, complete provider setup in Cline settings.
-
-        [Authorize with Cline](/getting-started/authorizing-with-cline)
-      </Step>
-    </Steps>
-
-    Alternative: install from the [JetBrains Marketplace](https://plugins.jetbrains.com/plugin/28247-cline).
+    Look for the Cline icon in your Activity Bar or use the Command Palette.
   </Tab>
 </Tabs>
 
-## CLI
+## Sign In & Start Building
 
-Use this if you want Cline in terminal workflows (interactive + automation).
+<Note>
+**CLI users:** If you installed via CLI, you already authenticated during setup with `cline auth`. You're ready to go!
+</Note>
 
-<Steps>
-  <Step title="Install Node.js">
-    Install Node.js 20+ (22 recommended).
-  </Step>
-  <Step title="Install CLI">
-    ```bash
-    npm install -g cline
-    ```
-  </Step>
-  <Step title="Authenticate">
-    ```bash
-    cline auth
-    ```
-  </Step>
-  <Step title="Run Cline">
-    ```bash
-    cline
-    # or
-    cline "your task"
-    ```
-  </Step>
-</Steps>
+1. **Open Cline** in your editor:
+   - **VS Code/Cursor/Antigravity/VSCodium/Windsurf:** Click the Cline icon in the Activity Bar
+   - **JetBrains:** Go to **View** → **Tool Windows** → **Cline**
 
-More details: [CLI Installation & Setup](/usage/cli-overview)
+2. **Sign in** by clicking the **Sign Up** button in the Cline interface. You'll be redirected to [app.cline.bot](https://app.cline.bot) to authenticate.
 
-## Kanban
+   <Tip>
+     Learn more about [authorizing with Cline](/getting-started/authorizing-with-cline), including how OAuth authentication works, using API keys with other providers, and troubleshooting auth issues.
+   </Tip>
 
-Use this if you want task-board workflows with agent execution.
+3. **Start building!** After signing in, you'll automatically return to your editor-Cline is ready to help.
 
-<Steps>
-  <Step title="Install Node.js">
-    Install Node.js 18+.
-  </Step>
-  <Step title="Launch Kanban">
-    ```bash
-    npx kanban
-    ```
-  </Step>
-</Steps>
+## Setting Up Cline in the Right Sidebar
 
-More details: [Kanban](/usage/kanban)
+For the best coding experience, we recommend moving Cline to the right sidebar. This keeps your project files visible on the left while you chat with Cline on the right, giving you full visibility of your codebase as Cline works.
 
-## SDK
+<Tabs>
+  <Tab title="VS Code">
+    <Steps>
+      <Step title="Align Extension View">
+        Make sure your extension view is aligned vertically to the left.
+      </Step>
+      <Step title="Open Right Side View">
+        Click the button that opens the right side panel (typically used for GitHub Copilot chat), or use `Option + Cmd/Ctrl + B`.
+      </Step>
+      <Step title="Drag Cline Icon">
+        Drag the Cline icon over to the nav panel at the top of that right view.
+      </Step>
+    </Steps>
 
-Use this if you are building your own app/agent on top of Cline.
+    <Frame>
+      <img
+        src="https://storage.googleapis.com/cline_public_images/vscode_right_view.gif"
+        alt="VS Code Right Sidebar Setup"
+      />
+    </Frame>
+  </Tab>
+  <Tab title="Cursor">
+    <Steps>
+      <Step title="Set Vertical Activity Bar">
+        Cursor uses a horizontal activity bar by default. To switch to vertical:
+        1. Open Command Palette (`Cmd/Ctrl + Shift + P`)
+        2. Search for "Preferences: Open Settings (UI)"
+        3. Search for `workbench.activityBar.orientation`
+        4. Set the value to `vertical`
+        5. Restart Cursor
+      </Step>
+      <Step title="Open the AI Pane">
+        Click the Cursor cube icon (AI Pane) to open the right side view panel.
+      </Step>
+      <Step title="Drag Cline to the AI Pane">
+        Drag the Cline icon directly into the AI Pane sidebar.
+      </Step>
+    </Steps>
 
-<Steps>
-  <Step title="Create project">
-    ```bash
-    mkdir my-agent && cd my-agent
-    npm init -y
-    ```
-  </Step>
-  <Step title="Install SDK">
-    ```bash
-    npm install @cline/sdk
-    ```
-  </Step>
-  <Step title="Build and run">
-    Browse SDK examples to run your first agent.
-  </Step>
-</Steps>
+    <Frame>
+      <img
+        src="https://storage.googleapis.com/cline_public_images/Cursor-sidebar.gif"
+        alt="Cursor Right Sidebar Setup"
+      />
+    </Frame>
+  </Tab>
+</Tabs>
 
-Start here: [SDK Examples](/sdk/examples)
+## Troubleshooting
 
+### Can't Find Cline in the Marketplace
+
+Sometimes Cline doesn't show up in search results if you're looking in the wrong tab or using an incompatible IDE version. Make sure you're searching in the **Marketplace** tab (not Installed), try searching for "Cline AI" instead, and verify your IDE is up to date. If installation fails, restart your IDE and check your internet connection.
+
+### Cline Icon Not Appearing After Install
+
+The most common fix is a full restart-close your IDE completely (File → Exit) and reopen it. In VS Code/Cursor/VSCodium, you can also open the Command Palette (`Ctrl/Cmd + Shift + P`) and type "Cline: Open In New Tab". In JetBrains, check **View** → **Tool Windows** → **Cline**. If it's still missing, verify the plugin is enabled in your Extensions/Plugins settings.
+
+### CLI: Node.js or Permission Errors
+
+Cline CLI requires Node.js 20 or higher. Run `node --version` to check-if you need to upgrade, use nvm (`nvm install 22 && nvm use 22`) or download from [nodejs.org](https://nodejs.org). For permission errors on `npm install -g`, either prefix with `sudo` on macOS/Linux or configure npm to use a user-owned directory for global packages.
+
+### Plugin Installed But Not Working
+
+If Cline appears installed but doesn't respond, try disabling and re-enabling the extension in your IDE's settings. Check the Developer Console (VS Code: Help → Toggle Developer Tools) or Event Log (JetBrains) for error messages. Also ensure you're using a supported IDE version and close any resource-intensive extensions that might interfere.
 
 ## Need Help?
 
-- [Troubleshooting](/troubleshooting/networking-and-proxies)
-- [Discord community](https://discord.gg/cline)
+- Join our [Discord community](https://discord.gg/cline) for support, tips, and discussions.
+- [Read the docs](/getting-started/authorizing-with-cline) to explore model selection guides and advanced features.

docs/getting-started/quick-start.mdx

@@ -0,0 +1,101 @@
+---
+title: "Quick Start"
+sidebarTitle: "Quick Start"
+description: "Get Cline running in under 2 minutes."
+---
+
+Cline is an AI-powered coding assistant that works directly inside your editor. You describe what you want in plain text, and Cline writes code, creates files, runs terminal commands, and even tests web apps in a browser, all while asking for your permission before making any changes.
+
+Think of it as pair programming with an AI that can actually touch your files and run your tools, but only when you say so.
+
+This guide gets you from zero to working code in under 2 minutes.
+
+<Info>
+  **What You'll Need:**
+  - One of: **VS Code**, **Cursor**, **Windsurf**, **Antigravity**, a **JetBrains IDE**, or **Node.js 20+** (for CLI)
+  - An internet connection (Cline connects to AI models in the cloud)
+  - ~2 minutes
+</Info>
+
+## 1. Install
+
+<Tabs>
+  <Tab title="VS Code / Cursor / Windsurf / Antigravity">
+    Open Extensions (`Cmd+Shift+X` on Mac, `Ctrl+Shift+X` on Windows/Linux), search **Cline**, click **Install**.
+  </Tab>
+  <Tab title="JetBrains">
+    Go to **Settings > Plugins > Marketplace**, search **Cline**, click **Install**, then restart your IDE.
+  </Tab>
+  <Tab title="CLI">
+    ```bash
+    npm install -g cline
+    ```
+  </Tab>
+</Tabs>
+
+<Tip>
+For detailed installation instructions including troubleshooting, see the [full installation guide](/getting-started/installing-cline).
+</Tip>
+
+## 2. Authenticate
+
+Click the Cline icon in your editor's sidebar, then click **Sign Up**. You'll authenticate at [app.cline.bot](https://app.cline.bot) and return to your editor ready to go.
+
+Authenticating gives you access to multiple AI models without managing separate API keys. Your account includes both free and paid models. Free models are labeled **FREE** in the model selector. For paid models, you can add credits in your [account dashboard](https://app.cline.bot/dashboard). You're always in control of which model you use.
+
+Send any message to confirm you're connected, then move on to building something.
+
+<Note>
+**CLI users:** Run `cline auth` to authenticate from your terminal.
+</Note>
+
+## 3. Build Something
+
+Now let's have Cline write some code. Open any folder in your editor, then paste this:
+
+```text
+Create a Python function that checks if a string is a palindrome. Include tests.
+```
+
+Cline will analyze your request, create a new file, and ask for your approval before writing anything to disk. Click **Approve** to create the file.
+
+That's it. You have working code with tests.
+
+<Note>
+**Not seeing file changes?** You might be in **Plan Mode**, where Cline discusses the approach without modifying files. Look for the **Plan/Act toggle** at the bottom of the Cline panel and switch to **Act** to let Cline start writing code. [Learn more about Plan & Act →](/core-workflows/plan-and-act)
+</Note>
+
+## 4. You're All Set
+
+Let's recap what you just did:
+
+1. **Installed Cline** in your editor
+2. **Authenticated** to connect to AI models
+3. **Built working code**: Cline wrote it, you approved it
+
+Every step of the way, Cline showed you exactly what it planned to do and waited for your approval. This is Cline's **human-in-the-loop** model: every file edit, terminal command, and browser action is shown to you first and only happens after you click Approve. You can review exactly what's changing, reject anything you don't want, and stay fully in control of your codebase. Nothing happens behind your back.
+
+## What Else Can Cline Do?
+
+The palindrome example is just the beginning. Here are some prompts to explore Cline's full capabilities:
+
+- `Read my project and explain the architecture`: Cline navigates and analyzes your codebase
+- `Find and fix the bug in src/utils.ts`: Cline reads files, proposes edits, and can run tests
+- `Run my test suite and fix any failures`: Cline executes terminal commands and iterates on problems
+- `Open a browser and test my app at localhost:3000`: Cline launches a browser and interacts with pages
+- `Set up an MCP server for my database`: Cline can connect to external tools and APIs
+
+Cline works best when you give it clear, specific instructions. The more context you provide about what you want, the better the results.
+
+<AccordionGroup>
+  <Accordion title="How does Cline work under the hood?">
+    Cline runs entirely in your editor (or terminal). When you send a message, it goes to the AI model you've selected (like Claude, GPT-4, or Gemini). The model's response is parsed into actions (file edits, terminal commands, browser interactions) which Cline presents to you for approval. Your code never passes through Cline's servers. It goes directly from your machine to your chosen AI provider.
+  </Accordion>
+</AccordionGroup>
+
+## Next Steps
+
+- [What is Cline?](/getting-started/what-is-cline): Understand Cline's full capabilities and how it works
+- [Build Your First Project](/getting-started/your-first-project): Hands-on tutorial building a complete todo app
+- [Select Your Model](/getting-started/authorizing-with-cline): Connect Claude, GPT-4, Gemini, DeepSeek, or local models
+- [Core Workflows](/core-workflows/task-management): Learn the patterns you'll use daily with Cline